docs: improve project description and styling in README
This commit is contained in:
parent
13245c08fe
commit
cbfa512d75
1 changed files with 41 additions and 21 deletions
62
README.md
62
README.md
|
@ -1,27 +1,33 @@
|
|||
# nff
|
||||
|
||||
This is a high performance configuration parser and written in Rust. The goal is
|
||||
to receive possibly jumbled up nftables rule files, and output ✨ pretty ✨
|
||||
human readable output in return. The main emphasis is on the syntax-aware
|
||||
formatting with comprehensive grammar support. It is a future goal to allow
|
||||
editors to hook into nff in order to format your rulesets directly from your
|
||||
editor, or as a diagnostics source.
|
||||
This is a high performance, low overhead configuration parser for nftables,
|
||||
written in Rust. Syntax-aware parsing allows nff to provide a complete formatter
|
||||
_and_ a linter for nftables. With the formatter the goal is to receive possibly
|
||||
jumbled up nftables rule files, and output ✨ pretty ✨ human readable output in
|
||||
return. The linter on another hand, will demonstrate possible syntax,
|
||||
performance or stylistic errors.
|
||||
|
||||
The main emphasis, however, is on the syntax-aware formatting with comprehensive
|
||||
grammar support.
|
||||
|
||||
## Features
|
||||
|
||||
nff is in its early stages of development. While _most_ of the syntax is
|
||||
supported, I cannot guarantee that _everything_ is supported just yet.
|
||||
> [!NOTE]
|
||||
> nff is in its early stages of development. While _most_ of the syntax is
|
||||
> supported, I cannot guarantee that _everything_ is supported just yet.
|
||||
|
||||
### Core Functionality
|
||||
|
||||
Basic functionality of nff that most users will be interested in
|
||||
|
||||
- **Syntax-aware formatting** - Deep understanding of nftables grammar with
|
||||
semantic preservation
|
||||
- **Multi-family support** - Handles `inet`, `ip`, `ip6`, `arp`, `bridge`, and
|
||||
`netdev` table families
|
||||
- **Multi-family support** - Handles `inet`, `ip`, `ip6`, `arp`, `bridge`, and
|
||||
`netdev` table families
|
||||
- **CIDR notation** - Proper handling of network addresses (`192.168.1.0/24`)
|
||||
- **Chain properties** - Hooks, priorities (including negative), policies,
|
||||
device bindings
|
||||
- **Flexible indentation** - Configurable tabs/spaces with custom depth
|
||||
- **CIDR notation** - Proper handling of network addresses (`192.168.1.0/24`)
|
||||
- **Chain properties** - Hooks, priorities (including negative), policies,
|
||||
device bindings
|
||||
|
||||
### Advanced Features
|
||||
|
||||
|
@ -145,16 +151,26 @@ graph TD
|
|||
|
||||
## Installation
|
||||
|
||||
Recommended way of installing nff is to use Nix.
|
||||
Recommended way of installing nff is to use Nix. Add `nff` to your flake inputs,
|
||||
and add the package to your `environment.systemPackages`. Alternatively, on
|
||||
non-NixOS systems, it is possible to use `nix profile install` to install nff.
|
||||
|
||||
### Editor Integration
|
||||
|
||||
> [!TIP]
|
||||
> Your editor not here? Open an issue. I can only add support for editors I use
|
||||
> but pull requests documenting alternative editor setups are appreciated!
|
||||
|
||||
#### Neovim Setup
|
||||
|
||||
nff can be integrated into Neovim as a diagnostics source for nftables files.
|
||||
Here are several setup approaches:
|
||||
|
||||
##### Option 2: Using none-ls
|
||||
##### Option 1: Using none-ls
|
||||
|
||||
none-ls is the most common method of adding diagnostics sources in Neovim. While
|
||||
I recommend using nvim-lint for its simplicity, below instructions document how
|
||||
to set up null-ls.
|
||||
|
||||
```lua
|
||||
local null_ls = require("null-ls")
|
||||
|
@ -182,6 +198,9 @@ null_ls.setup({
|
|||
|
||||
##### Option 2: Using nvim-lint (recommended)
|
||||
|
||||
Recommended way of adding nff as a diagnostics source in Neovim. Simple, low
|
||||
overhead and not as error-prone as null-ls.
|
||||
|
||||
```lua
|
||||
-- ~/.config/nvim/lua/config/lint.lua
|
||||
require('lint').linters.nff = {
|
||||
|
@ -224,7 +243,8 @@ vim.api.nvim_create_autocmd({ "BufEnter", "BufWritePost" }, {
|
|||
|
||||
##### Option 3: Custom Lua Function
|
||||
|
||||
For a simple custom solution:
|
||||
Alternatively, if you don't want to use plugins, consider a setup such as this
|
||||
one to do it without any reliance on plugins:
|
||||
|
||||
```lua
|
||||
-- ~/.config/nvim/lua/nff.lua
|
||||
|
@ -564,6 +584,11 @@ style.nft:1:16: warning: Missing space after '{' [NFT503]
|
|||
|
||||
## Contributing
|
||||
|
||||
### Building
|
||||
|
||||
Build with `cargo build` as usual. If you are using Nix, you will also want to
|
||||
ensure that the Nix package builds as expected.
|
||||
|
||||
### Code Style
|
||||
|
||||
- Follow `cargo fmt` formatting
|
||||
|
@ -578,11 +603,6 @@ style.nft:1:16: warning: Missing space after '{' [NFT503]
|
|||
- **Regression tests**: Known issue prevention
|
||||
- **Performance tests**: Benchmark critical paths
|
||||
|
||||
### Building
|
||||
|
||||
Build with `cargo build` as usual. If you are using Nix, you will also want to
|
||||
ensure that the Nix package builds as expected.
|
||||
|
||||
## Technical Notes
|
||||
|
||||
### CST Implementation
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue