Hi! Recently I’ve become more interested in Nix but realized that I still have gaps in understanding its syntax.
For the past couple of months I was working on a visual tool that explains what each language feature does. You can click anywhere in the code and Explainix will show a brief description with a link to the official documentation page.
https://zaynetro.com/explainix
PS Let me know if there are any errors or if I’ve missed some syntax.
This is great!
Some things I noticed:
_, - or '” and only show the regex for completeness.let expressioninherit (attrset) attribute; syntax is missingwith expression explanation is correct but can probably only be understood if you already know how it works or are a programming language nerd"two words" attribute? syntaxThis is quite impressive! Consider adding it to awesome-nix.
I recognise a few phrases from nix.dev and the Nix manual in the descriptions. It would be a lot more sustainable to link to the Nix manual for authoritative definitions. Currently they are not always great, but any improvement to the manual would automatically improve the experience with your tool.
Super cool ! How about adding this to nix.dev?
Do EBNF diagrams exist for the Nix language?
No, this is a “future work” / “contributions welcome” task for documentation. But there exist independent parsers such as rnix-parser which could contain something that can be reused.
Awesome work, thanks @zaynetro
Small usability nitpick: It would be great if the explanation overlay can be closed with ESC key.
For the update operator, I would add this example too:
nix-repl> :p { a = { foo = "bar"; };} // { a = { bar = "foo";};}
{ a = { bar = "foo"; }; }
Just to show that the update operation does not merge recursively.
Thanks a lot for so many great comments!
- There should be a way to show all things you could hover over
I am not sure what you mean by this. You can hover over any element.
- The URL data type is deprecated and should not be used: https://github.com/NixOS/rfcs/blob/c65c8321782b40844167beb48818471f70900d9d/rfcs/0045-deprecate-url-syntax.md
Oh wow. Thanks! Added a note. Nix reference manual has no mention of it.
- Null is basically unexplained. It’s obvious what null is to us but I doubt that’s true for every Nix/NixOS newcomer.
I just copied Nix reference manual here. Let me know if you have any suggestions.
- The regexes are quite readable but if I didn’t know how regexes worked, my eyes would likely just glaze over in the identifier explanation. I’d prefer a prose explanation like “a string of characters that start with a letter followed by any number of letters, digits,
_,-or'” and only show the regex for completeness.
Modified identifier’s description to include human readable text. Will check other places later.
- Perhaps highlight the attrset when hovering over its constituents like with the
letexpression
This is actually a technical limitation. I don’t know how to implement it yet 
The main issue is that I decided to keep the opening brace on the same line as the previous element. Works for inline attribute sets though.
- Operator boxes cannot be clicked on unless you hover over the operator
- Attribute set example description is missing the
"two words"attribute
Fixed.
inherit (attrset) attribute;syntax is missingwithexpression explanation is correct but can probably only be understood if you already know how it works or are a programming language nerd- String interpolation is explained but an example would be great, especially if it’s non-trivial (i.e. a conditional with function calls)
- String interpolation escape syntax is missing
- Imports are missing
- Attrset lambda arguments are missing from the example. Would be good to have w.r.t. highlighting wtf is going on with that goofy
?syntax
Thanks! Added to my TODO list.
I recognise a few phrases from nix.dev and the Nix manual in the descriptions. It would be a lot more sustainable to link to the Nix manual for authoritative definitions. Currently they are not always great, but any improvement to the manual would automatically improve the experience with your tool.
My idea originally was to keep short easy-to-follow descriptions and link to the manual for full details but then I got a bit lazy…
It would be great if the explanation overlay can be closed with
ESCkey.
Fixed.
PS Explainix is open-source so if you have any docs suggestions feel free to contribute. File with docs.
I meant to have e.g. a button that highlights all the interactable code points at once.
I think this is quite useful, and I’ve shared it with the rest of my small team so we can handle our Nix investment better.
I did have a couple of small points to suggest changing:
The docs on function application do sort of mention this, but that’s a weird place to find it, and it’s only by way of talking about partial application. (You did a good job of explaining that, though!)
A possible addition just after the first sentence describing patterns in the function def doc:
(A function only has a single pattern for a single argument, but it’s easy to nest functions to take multiple arguments, one by one, and these are all in scope in the innermost function body.)
You might also add a more explicit example for nested function closures, although I think the one on the left is fairly clear once you know what to look for.
"functions" = let concat = x: y: x+y; in concat x y; and you click on the highlight for concat x y, it will show you only the first line or two of help in the sidebar.Something along the lines of this, maybe:
Null is the absence of a useful value. It is not equal to anything except itself and can’t be part of most simple expressions. However, equality (
null == "test"returnsfalse), inequality (1 != nullreturnstrue), attrset selection with the optionalorclause (null.example or "fallback"returns"fallback"), and has_attr (null ? examplereturnsfalse) operators can be used to work with it.
This is really cool I had one idea:
When hovering over a bound variable, you could show both its definition and its usage sites (maybe in different colours). That way, one can visualize namespaces and name shadowing.
