rnix 0.11.0

A Nix parser written in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

# rnix-parser [![Crates.io](https://img.shields.io/crates/v/rnix.svg)](http://crates.io/crates/rnix) [![Chat on Matrix](https://matrix.to/img/matrix-badge.svg)](https://matrix.to/#/#rnix-lsp:matrix.org)

rnix is a parser for the [Nix language](https://nixos.org/nix/) written in Rust.

This can be used to manipulate the Nix AST and can for example be used for:

- Interactively render Nix on a GUI
- Formatting Nix code
- Rename identifiers

and a lot more!

rnix nowadays uses [@matklad](https://github.com/matklad)'s
[rowan](https://crates.io/crates/rowan) crate to ensure:

- all span information is preserved, meaning you can use the AST to for
  example apply highlighting
- printing out the AST prints out 100% the original code. This is not an
  over-exaggeration, even completely invalid nix code such as this README can
  be intact after a parsing session (though the AST will mark errnous nodes)
- easy ways to walk the tree without resorting to recursion

## Demo

Examples can be found in the `examples/` directory. 

You may also want to see
[nix-explorer](https://gitlab.com/jD91mZM2/nix-explorer): An example
that highlights AST nodes in Nix code. This demonstrates how
whitespaces and commands are preserved.

## Hacking

Tests can be run with `cargo test`.

In order to update all `.expect`-files to the currently expected results,
you may run `UPDATE_TESTS=1 cargo test`.

You can parse Nix expressions from standard input using the `from-stdin` example.
To try that, run the following in your shell:

```sh
echo "[hello nix]" | cargo run --quiet --example from-stdin
```

## Release Checklist

* Ensure that all PRs that were scheduled for the release are merged (or optionally move
  them to another milestone).
* Close the milestone for the release (if any).
* Run `cargo test` on `master` (or the branch to release from) with all changes being pulled in.
* Apply the following patch to [nixpkgs-fmt](https://github.com/nix-community/nixpkgs-fmt):
  ```diff
  diff --git a/Cargo.toml b/Cargo.toml
  index 0891350..edad471 100644
  --- a/Cargo.toml
  +++ b/Cargo.toml
  @@ -13,6 +13,9 @@ repository = "https://github.com/nix-community/nixpkgs-fmt"
   [workspace]
   members = [ "./wasm" ]
   
  +[patch.crates-io]
  +rnix = { path = "/home/ma27/Projects/rnix-parser" }
  +
   [dependencies]
   rnix = "0.9.0"
   smol_str = "0.1.17"
  ```

  and run `cargo test`.

  While it's planned to add [fuzzing to `rnix-parser` as well](https://github.com/nix-community/rnix-parser/issues/32),
  `nixpkgs-fmt` has a decent test-suite that would've helped to catch regressions in the past.

  __Note:__ API changes are OK (and fixes should be contributed to `nixpkgs-fmt`), behavioral changes
  are not unless explicitly discussed before.
* Update the [CHANGELOG.md](https://github.com/nix-community/rnix-parser/blob/master/CHANGELOG.md).
* Bump the version number in [Cargo.toml](https://github.com/nix-community/rnix-parser/blob/master/Cargo.toml) & re-run `cargo build` to refresh the lockfile.
* Commit & run `nix build`.
* Tag the release and push everything.
* As soon as the CI has completed, run `cargo publish`.

# RIP jd91mzm2

Sadly, the original author of this project, [@jD91mZM2 has passed
away](https://www.redox-os.org/news/open-source-mental-health/). His online
presence was anonymous and what we have left is his code. This is but one of
his many repos that he contributed to.