History

sterni 0c178a0ef6 chore(3p/sources): Bump channels & overlays Upstream nixpkgs removed a lot of aliases this time, so we needed to do the following transformations. It's a real shame that aliases only really become discoverable easily when they are removed. * runCommandNoCC -> runCommand * gmailieer -> lieer We also need to work around the fact that home-manager hasn't catched on to this rename. * mysql -> mariadb * pkgconfig -> pkg-config This also affects our Nix fork which needs to be bumped. * prometheus_client -> prometheus-client * rxvt_unicode -> rxvt-unicode-unwrapped * nix-review -> nixpkgs-review * oauth2_proxy -> oauth2-proxy Additionally, some Go-related builders decided to drop support for passing the sha256 hash in directly, so we need to use the generic hash arguments. Change-Id: I84aaa225ef18962937f8616a9ff064822f0d5dc3 Reviewed-on: https://cl.tvl.fyi/c/depot/+/6792 Autosubmit: sterni <sternenseemann@systemli.org> Tested-by: BuildkiteCI Reviewed-by: grfn <grfn@gws.fyi> Reviewed-by: flokli <flokli@flokli.de> Reviewed-by: tazjin <tazjin@tvl.su> Reviewed-by: wpcarro <wpcarro@gmail.com>		2022-09-28 08:02:31 +00:00
..
tests	chore(3p/sources): Bump channels & overlays	2022-09-28 08:02:31 +00:00
default.nix	style: format entire depot with nixpkgs-fmt	2022-01-31 16:11:53 +00:00
README.md	feat(users/sterni/nix): cursed nix html DSL	2021-08-26 15:34:58 +00:00

README.md

html.nix — the most cursed Nix HTML DSL

A quick example to show you what it looks like:

# Note: this example is for standalone usage out of depot
{ pkgs ? import <nixpkgs> {} }:

let
  # zero dependency, one file implementation
  htmlNix = import ./path/to/html.nix { };

  # make the magic work
  inherit (htmlNix) __findFile esc withDoctype;
in

pkgs.writeText "example.html" (withDoctype (<html> {} [
  (<head> {} [
    (<meta> { charset = "utf-8"; } null)
    (<title> {} (esc "hello world"))
  ])
  (<body> {} [
    (<h1> {} (esc "hello world"))
    (<p> { class = "intro"; } (esc ''
      welcome to the land of sillyness!
    ''))
    (<ul> {} [
      (<li> {} [
        (esc "check out ")
        (<a> { href = "https://code.tvl.fyi"; } "depot")
      ])
      (<li> {} [
        (esc "find ")
        (<a> { href = "https://cl.tvl.fyi/q/hashtag:cursed"; } "cursed things")
      ])
    ])
  ])
]))

Convince yourself it works:

$ $BROWSER $(nix-build example.nix)

Alternatively, in depot:

$ $BROWSER $(nix-build -A users.sterni.nix.html.tests)

Creating tags

An empty tag is passed null as its content argument:

<link> {
  rel = "stylesheet";
  href = "/main.css";
  type = "text/css";
} null

# => "<link href=\"/main.css\" rel=\"stylesheet\" type=\"text/css\"/>"

Content is expected to be HTML:

<div> { class = "foo"; } "<strong>hi</strong>"

# => "<div class=\"foo\"><strong>hi</strong></div>"

If it's not, be sure to escape it:

<p> {} (esc "A => B")

# => "<p>A =&gt; B</p>"

Nesting tags works of course:

<div> {} (<strong> {} (<em> {} "hi"))

# => "<div><strong><em>hi</em></strong></div>"

If the content of a tag is a list, it's concatenated:

<h1> {} [
  (esc "The ")
  (<strong> {} "Nix")
  (esc " ")
  (<em> {} "Expression")
  (esc " Language")
]

# => "<h1>The <strong>Nix</strong> <em>Expression</em> Language</h1>"

More detailed documentation can be found in nixdoc-compatible comments in the source file (default.nix in this directory).

How does this work?

Theoretically expressions like <nixpkgs> are just ordinary paths — their actual value is determined from NIX_PATH. html.nix works because of how this is actually implemented: At parse time Nix transparently translates an expression like <foo> into __findFile __nixPath "foo":

nix-repl> <nixpkgs>
/nix/var/nix/profiles/per-user/root/channels/vuizvui/nixpkgs

nix-repl> __findFile __nixPath "nixpkgs"
/nix/var/nix/profiles/per-user/root/channels/vuizvui/nixpkgs

This translation doesn't take any scoping issues into account -- so we can just shadow __findFile and make it return anything, even a function:

nix-repl> __findFile = nixPath: str:
            /**/ if str == "double" then x: x * 2
            else if str == "triple" then x: x * 3
            else throw "what?"

nix-repl> <double> 2
4

nix-repl> <triple> 3
9

nix-repl> <quadruple> 4
error: what?

Exactly this is what we are doing in html.nix: Using let inherit (htmlNix) __findFile; in we shadow the builtin __findFile with a function which returns a function rendering a particular HTML tag.