Explainix: Learn Nix syntax visually

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.

34 Likes

This is great!

Some things I noticed:

  • There should be a way to show all things you could hover over
  • The URL data type is deprecated and should not be used: https://github.com/NixOS/rfcs/blob/c65c8321782b40844167beb48818471f70900d9d/rfcs/0045-deprecate-url-syntax.md
  • Null is basically unexplained. It’s obvious what null is to us but I doubt that’s true for every Nix/NixOS newcomer.
  • 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.
  • Perhaps highlight the attrset when hovering over its constituents like with the let expression
  • inherit (attrset) attribute; syntax is missing
  • with expression explanation is correct but can probably only be understood if you already know how it works or are a programming language nerd
  • The comparison operator in the conditionals example isn’t highlighted
  • 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
  • Operator boxes cannot be clicked on unless you hover over the operator
  • Attribute set example description is missing the "two words" attribute
  • 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
  • Function application is missing (i.e. builtins)
6 Likes

This 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.

5 Likes

Super cool ! How about adding this to nix.dev?

5 Likes

Would be amazing, especially if used on the language basics page.

7 Likes

Do EBNF diagrams exist for the Nix language?

1 Like

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.

1 Like

Awesome work, thanks @zaynetro

Small usability nitpick: It would be great if the explanation overlay can be closed with ESC key.

3 Likes

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.

2 Likes

Thanks a lot for so many great comments!

@Atemu

  • 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.

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 let expression

This is actually a technical limitation. I don’t know how to implement it yet :slight_smile: 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 missing
  • with expression 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.

@fricklerhandwerk

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…

@don.dfh

It would be great if the explanation overlay can be closed with ESC key.

Fixed.

PS Explainix is open-source so if you have any docs suggestions feel free to contribute. File with docs.

2 Likes

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 explanation for function patterns should be clear that every function technically only takes one argument (although going off on a tangent on closures would perhaps be a bit much). I’m a professional Clojurist with some exposure to Haskell, F#, and a few other FP languages, so I know that there are languages with unary-only functions, but even so, this took me aback for a minute when the sidebar help seemed so mismatched with the example.
    • 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.

  • The right-side help section could adjust its position to ensure everything is in view. For example, if you’ve scrolled down only just far enough to see "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" returns false), inequality (1 != null returns true), attrset selection with the optional or clause (null.example or "fallback" returns "fallback"), and has_attr (null ? example returns false) operators can be used to work with it.

1 Like

This is really cool :slight_smile: 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.

2 Likes