docs: improve project description and styling in README

This commit is contained in:
raf 2025-06-02 16:08:52 +03:00
commit cbfa512d75
Signed by: NotAShelf
GPG key ID: 29D95B64378DB4BF

View file

@ -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