From 781c42cc9ce2e6a3f1024ea1f4e3f071cc8f2dd4 Mon Sep 17 00:00:00 2001
From: Akshay <nerdy@peppe.rs>
Date: Sun, 24 Oct 2021 17:55:57 +0530
Subject: flake build with json feature, add better usage docs

---
 readme.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 63 insertions(+), 23 deletions(-)

(limited to 'readme.md')

diff --git a/readme.md b/readme.md
index 68265cc..293b72e 100644
--- a/readme.md
+++ b/readme.md
@@ -2,50 +2,82 @@
 
 > Lints and suggestions for the Nix programming language.
 
-`statix` highlights antipatterns in Nix code. `statix fix`
+`statix` highlights antipatterns in Nix code. `statix --fix`
 can fix several such occurrences.
 
 For the time-being, `statix` works only with ASTs
 produced by the `rnix-parser` crate and does not evaluate
 any nix code (imports, attr sets etc.). 
 
+## Examples
+
+```shell
+$ statix tests/c.nix
+[W04] Warning: Assignment instead of inherit from
+   ╭─[tests/c.nix:2:3]
+   │
+ 2 │   mtl = pkgs.haskellPackages.mtl;
+   ·   ───────────────┬───────────────
+   ·                  ╰───────────────── This assignment is better written with inherit
+───╯
+
+$ statix --fix --dry-run tests/c.nix
+--- tests/c.nix
++++ tests/c.nix [fixed]
+@@ -1,6 +1,6 @@
+ let
+-  mtl = pkgs.haskellPackages.mtl;
++  inherit (pkgs.haskellPackages) mtl;
+ in
+ null
+```
+
 ## Installation
 
 `statix` is available via a nix flake:
 
-```
-nix run git+https://git.peppe.rs/languages/statix
-
-# or
-
+```shell
+# build from source
 nix build git+https://git.peppe.rs/languages/statix
 ./result/bin/statix --help
+
+# statix also provides a flake app
+nix run git+https://git.peppe.rs/languages/statix -- --help
+
+# save time on builds using cachix
+cachix use statix
 ```
 
 ## Usage
 
-```
-statix 0.1.0
+Basic usage is as simple as:
 
-Akshay <nerdy@peppe.rs>
+```shell
+# recursively finds nix files and raises lints
+statix /path/to/dir
 
-Lints and suggestions for the Nix programming language
+# ignore generated files, such as Cargo.nix
+statix /path/to/dir -i '*Cargo.nix'
 
-USAGE:
-    statix [FLAGS] [OPTIONS] [--] [TARGET]
+# see `statix -h` for a full list of options
+```
 
-ARGS:
-    <TARGET>    File or directory to run statix on [default: .]
+Certain lints have suggestions. Apply suggestions back to
+the source with:
 
-FLAGS:
-    -d, --dry-run    Do not fix files in place, display a diff instead
-    -f, --fix        Find and fix issues raised by statix
-    -h, --help       Print help information
-    -V, --version    Print version information
+```shell
+statix --fix /path/to/file
 
-OPTIONS:
-    -i, --ignore <IGNORE>...    Globs of file patterns to skip
-    -o, --format <FORMAT>       Output format. Supported values: errfmt, json (on feature flag only)
+# show diff, do not write to file
+statix --fix --dry-run /path/to/file
+```
+
+`statix` supports a variety of output formats; standard,
+json and errfmt:
+
+```shell
+statix /path/to/dir -o json
+statix /path/to/dir -o errfmt # singleline, easy to integrate with vim
 ```
 
 ## Architecture
@@ -55,6 +87,7 @@ OPTIONS:
 - `bin`: the CLI/entrypoint
 - `lib`: library of lints and utilities to define these
   lints
+- `vfs`: virtual filesystem
 - `macros`: procedural macros to help define a lint
 
 ### `bin`
@@ -70,6 +103,11 @@ A library of AST-based lints and utilities to help write
 those lints. It should be easy for newcomers to write lints
 without being familiar with the rest of the codebase.
 
+### `vfs`
+
+VFS is an in-memory filesystem. It provides cheap-to-copy
+handles (`FileId`s) to access paths and file contents.
+
 ### `macros`
 
 This crate intends to be a helper layer to declare lints and
@@ -79,4 +117,6 @@ their metadata.
 
 - Offline documentation for each lint
 - Test suite for lints and suggestions
-- Output singleline/errfmt + vim plugin
+- Vim plugin (qf list population, apply suggestions)
+- Resolve imports and scopes for better lints
+- Add silent flag that exits with status
-- 
cgit v1.2.3