nix-ast

A Nix library that parses, inspects, transforms, and evaluates Nix Abstract Syntax Trees (AST) using Haskell’s hnix parser.

nix-ast exposes a full Nix AST API directly in Nix itself (via IFD, Import From Derivation) and uses hnix’s Haskell parser and evaluator internally. You can parse any Nix expression into a structured AST, traverse and transform it with pure Nix functions, render it back to source code, and even evaluate it. All from within your Nix expressions.

Features

Feature	Description
Parse	Parse any Nix expression (file, string, or stdin) into a structured, typed AST
Render	Convert an AST back to formatted, importable Nix code
Eval	Evaluate ASTs using hnix’s evaluator and get the results as JSON values
toAST	Convert native Nix values (ints, strings, lists, attrsets) to AST nodes (pure, no IFD)
fromAST	Convert an AST back to a native Nix value, the inverse of `toAST` (pure, no IFD)
Pattern Matching	Type-safe tag-based dispatch with `match ast { Tag = handler; _ = fallback; }`
Traversal	Recursive `transform`, `rewrite`, `universe`, `children`/`rebuild`, and `contexts`
Type-checked Constructors	All `mk*` builders validate argument types at runtime with descriptive error messages
CLI Tool	`nix-ast eval` / `nix-ast parse` / `nix-ast render` for shell/pipe workflows

Quick Start

Using the Nix Library (Flake)

Add nix-ast to your flake inputs:

inputs.nix-ast.url = "github:z1-0/nix-ast";

The library exposes three main API groups via inputs.nix-ast.lib:

API	Description
`lib.parse` `lib.render` `lib.eval`	IFD-based: bridge to hnix’s parser/evaluator
`lib.toAST` `lib.fromAST`	Pure Nix: convert between Nix values and ASTs
`lib.match` `lib.syntax` `lib.traversal`	Work with AST nodes after construction

# Parse -> Transform -> Render
asts = lib.parse pkgs [./config.nix];
transformed = lib.traversal.transform (node: ...) (builtins.head asts);
outPaths = lib.render pkgs [transformed];
config = import (builtins.head outPaths);

# Parse -> Evaluate (skip rendering)
result = lib.eval pkgs asts;

CLI

# Parse from expression string
nix-ast parse --expr '{ x = 1; }' > ast.json

# Parse files from stdin (one path per line)
echo ./config.nix | nix-ast parse > ast.json

# Render AST back to Nix
nix-ast render --json '{"tag":"Set","recursive":false,"bindings":[...]}'

# Render batch to output directory
nix-ast render < asts.json --out-dir ./out

# Evaluate AST using hnix
nix-ast eval --json '{"tag":"Constant","contents":{"tag":"Int","contents":42}}'

# Pipe workflow: parse -> eval
nix-ast parse --expr '{ x = 1 + 2; }' | nix-ast eval

Architecture

┌─────────────────────────────────────────────────────────┐
│                     Nix (your flake)                     │
│                                                         │
│  lib.parse   lib.render   lib.eval                      │
│       │           │           │                         │
│       ▼           ▼           ▼                         │
│  ┌──────────────────────────────┐                       │
│  │  IFD: nix-ast CLI (Haskell)  │  <- hnix parser/eval  │
│  └──────────────────────────────┘                       │
│                                                         │
│  lib.toAST  lib.fromAST  (pure Nix, no IFD)             │
│  lib.match  lib.syntax  lib.traversal                   │
└─────────────────────────────────────────────────────────┘

parse/render/eval go through Haskell via IFD. toAST/fromAST/match/syntax/traversal run in pure Nix on the AST values.

Installation

# Run directly without installing
nix run github:z1-0/nix-ast -- parse --expr '{ x = 1; }'

# Or add to your flake inputs
inputs.nix-ast.url = "github:z1-0/nix-ast";

Binary Cache

Use the Cachix cache to skip building from source.

nix.settings = {
  substituters = [ "https://z1-0.cachix.org" ];
  trusted-public-keys = [ "z1-0.cachix.org-1:FS7lPgL0StRBOPrlu0RgdCL7LafUI23+U6Iivdw5QK8=" ];
};

Learn more

API Reference: parse, render, eval, construct, match, and traverse AST nodes
- Core Functions: parse, render, eval, toAST, fromAST
- Pattern Matching: tag-based dispatch on node types
- Syntax: runtime-validated constructors and predicates
- Traversal: children, rebuild, transform, universe
AST Reference: every node type with fields, JSON representation, and examples
- Expr: 19 expression constructors
- Atom: primitive constants (Bool, Int, Float, Null, Uri)
- Binding: Inherit, NamedVar
- KeyName: StaticKey, DynamicKey
- Params: Param, ParamSet
- String: DoubleQuoted, Indented
- Antiquoted: Plain, Antiquoted, EscapedNewline
CLI Reference: nix-ast eval / nix-ast parse / nix-ast render

License

BSD-3-Clause: see LICENSE for details.

API Reference

Functions for parsing, constructing, matching, and transforming Nix AST nodes.

Overview

The API is organized into three layers:

Layer	Functions	Description
IFD bridge	`parse`, `render`, `eval`	Bridge to the Haskell parser/evaluator via Import From Derivation
Value conversion	`toAST`, `fromAST`	Pure Nix conversion between Nix values and AST nodes
AST tools	`match`, `syntax`, `traversal`	Pattern matching, constructors, and tree operations

Pages

Page	Description
Core Functions	`parse`, `render`, `eval`, `toAST`, `fromAST`
syntax: Constructors & Predicates	`mk` builders and `is` tag checks for all node types
match: Pattern Matching	Type-safe tag dispatch with `match ast { ... }`
traversal: Tree Operations	`children`, `rebuild`, `transform`, `universe`, `contexts`

How IFD Works

parse, render, and eval use pkgs.runCommand to create a derivation that:

Serializes the input (paths, ASTs) to a JSON file via pkgs.writeText
Runs the nix-ast CLI binary inside the derivation, piping the JSON file to stdin
Captures stdout as the derivation output
Reads back the output with builtins.readFile + builtins.fromJSON

These functions have IFD (Import From Derivation) semantics: they work in nix build and nix eval but are unavailable in restricted evaluation modes like nix-instantiate --eval.

Quick Example

# Parse, transform, and render
asts = lib.parse pkgs [./file.nix];
transformed = lib.traversal.transform (node:
  if lib.syntax.isConstant node && lib.syntax.isInt node.contents then
    lib.syntax.mkConstant (lib.syntax.mkInt (node.contents.contents * 2))
  else node
) (builtins.head asts);
outPaths = lib.render pkgs [transformed];
builtins.head outPaths

See also CLI Reference for the nix-ast eval / nix-ast parse / nix-ast render command-line tool.

AST Reference

Complete reference for every node type in the Nix AST, organized by type hierarchy as defined in Types.hs.

Quick Overview

The AST is a sum type with 19 expression constructors and supporting types for atoms, bindings, keys, parameters, strings, and antiquoted parts. Every node has a tag field (a string identifying the constructor) plus constructor-specific fields.

Node Types

Type	Description
Expr	The main expression tree, with 19 constructors
Atom	Primitive constant values (Bool, Float, Int, Null, Uri)
VarName	Identifier name (simple string)
AttrPath	Non-empty list of `KeyName` for attribute paths
Binding	Left-hand side of attribute bindings (Inherit, NamedVar)
KeyName	Attribute path components (StaticKey, DynamicKey)
Operators	Binary and unary operators
Params	Function parameter definitions (Param, ParamSet)
String	String literal contents (DoubleQuoted, Indented)
Antiquoted	String parts with interpolation

JSON Representation

Every node is serializable to/from JSON. The tag field identifies the constructor:

{ "tag": "Constant", "contents": { "tag": "Int", "contents": 42 } }

This is the format used by the CLI for nix-ast parse output and nix-ast render input.

Quick Start

# Parse Nix code into AST
asts = lib.parse pkgs [./example.nix];
ast = builtins.head asts;

# Inspect the expression type using match
lib.match ast {
  Set = { recursive, bindings }: "attribute set";
  List = { contents }: "list of ${toString (builtins.length contents)} items";
  _ = _: "other expression";
};

# Transform all integer constants: double their value
transformed = lib.traversal.transform (node:
  if node.tag == "Constant" && node.contents.tag == "Int"
  then lib.syntax.mkConstant (lib.syntax.mkInt (node.contents.contents * 2))
  else node
) ast;

# Render back to Nix code
outPaths = lib.render pkgs [transformed];
builtins.head outPaths

CLI

nix-ast - Nix AST tool

Usage: nix-ast COMMAND [-v|--version]

  nix-ast: Parse and generate Nix expressions

Available options:
  -h,--help                Show this help text
  -v,--version             Show version

Available commands:
  eval                     Evaluate AST JSON and output result
  parse                    Parse Nix expression to AST JSON
  render                   Render AST JSON to Nix source

The CLI has three subcommands: eval, parse, render. Each operates in two modes:

Direct mode: supply input via --expr or --json flag for single-item operation
Batch mode: pipe a JSON array through stdin for bulk processing (one item per array element)

When stdin is a TTY and no direct flag is given, the CLI shows the subcommand’s help text instead of hanging.

Eval

Evaluate AST values and output the results as JSON. This is the CLI equivalent of nix eval but operates on AST JSON rather than source code.

Usage: nix-ast eval [--json JSON]

  Evaluate AST JSON and output result

Available options:
  --json JSON              AST in JSON format
  -h,--help                Show this help text

Modes:

Mode	Flag	Input source	Output
Direct	`--json JSON`	Single AST as JSON string	Single JSON value to stdout
Batch (stdin)	(none)	`[AST]` JSON array on stdin	`[a]` JSON array to stdout

How it works: Each AST is deserialized, evaluated using the built-in evaluator with basic filesystem effects, and the result is serialized to JSON.

Error handling: Parse errors, conversion errors, evaluation errors, and IO exceptions are all caught and reported with appropriate prefixes (“Decode error”, “Conversion error”, “Eval error”).

Examples

# Evaluate a single AST from a JSON string
nix-ast eval --json '{"tag":"Set","recursive":false,"bindings":[{"tag":"NamedVar","attrPath":[{"tag":"StaticKey","contents":"x"}],"value":{"tag":"Constant","contents":{"tag":"Int","contents":1}}}]}'

# Pipe ASTs from a file (JSON array, one element per line in the array)
cat asts.json | nix-ast eval

# Pipe from parse: parse then evaluate
nix-ast parse --expr '{ x = 1 + 2; }' | nix-ast eval

Parse

Parse Nix source code into AST JSON.

Usage: nix-ast parse [--expr EXPR]

  Parse Nix expression to AST JSON

Available options:
  --expr EXPR              Nix expression string
  -h,--help                Show this help text

Modes:

Mode	Flag	Input source	Output
Direct	`--expr EXPR`	Single Nix expression string	Single AST JSON to stdout
Batch (stdin)	(none)	`[FilePath]` JSON array on stdin	`[AST]` JSON array to stdout

How it works:

Direct mode: The expression string is parsed into an AST, converted to our Expr type, and serialized to JSON.
Batch mode: Stdin is read as a JSON array of file paths. Each file is read concurrently using mapConcurrently with a semaphore limiting concurrency to 50. Each file is parsed separately; if any file fails, the entire command exits with an error.

Examples

# Parse a single expression from string
nix-ast parse --expr '{ x = 1; }' > ast.json

# Parse multiple files from stdin (one path per JSON array element)
echo '["/path/to/a.nix", "/path/to/b.nix"]' | nix-ast parse > asts.json

# Pipe from jq for dynamic path selection
nix build 2>&1 | grep "error:" | jq -R -s -c 'split("\n") | map(select(length > 0))' | nix-ast parse

Output Format

The AST is a JSON object with a tag field identifying the node type, plus type-specific fields:

{
  "tag": "Set",
  "recursive": false,
  "bindings": [
    {
      "tag": "NamedVar",
      "attrPath": [{ "tag": "StaticKey", "contents": "x" }],
      "value": {
        "tag": "Constant",
        "contents": { "tag": "Int", "contents": 1 }
      }
    }
  ]
}

For a complete reference of all node types with their JSON shapes, see the AST Reference.

Render

Convert AST JSON back to formatted Nix source code.

Usage: nix-ast render [--json JSON] [--out-dir DIR]

  Render AST JSON to Nix source

Available options:
  --json JSON              AST in JSON format
  --out-dir DIR            Output directory for rendered files (default: stdout)
  -h,--help                Show this help text

Modes:

Mode	Flag	Input source	Output
Direct	`--json JSON`	Single AST as JSON string	Formatted Nix source to stdout
Batch (stdin)	(none), no `--out-dir`	`[AST]` JSON array on stdin	`[Text]` JSON array to stdout
Batch to disk	(none), `--out-dir DIR`	`[AST]` JSON array on stdin	Files `0.nix`, `1.nix`, … in `DIR`

How it works: Each AST is deserialized and pretty-printed back to formatted Nix source code.

Direct mode (--json only, no --out-dir): Single AST → single line of Nix source to stdout.
Batch to stdout (stdin only, no --out-dir): Array of ASTs → JSON array of Nix source strings to stdout.
Batch to disk (stdin + --out-dir): Array of ASTs → individual files named <index>.nix in the specified directory. Files are numbered sequentially starting from 0.
Forbidden combination: --json + --out-dir is not supported and raises an error.

Examples

# Render a single AST from string to stdout
nix-ast render --json '{"tag":"Set","recursive":false,"bindings":[...]}'

# Pipe from parse: parse then render back to source
nix-ast parse --expr '{ x = 1; }' | nix-ast render

# Render batch to individual files
cat asts.json | nix-ast render --out-dir ./rendered
# Creates: ./rendered/0.nix, ./rendered/1.nix, ...

# Render batch to stdout (as JSON array of strings)
cat asts.json | nix-ast render

Output Format

{
  x = 1;
}

For list/multiline outputs, each AST is pretty-printed independently.

Shell Workflow Examples

# Parse, transform via jq, and render back
nix-ast parse --expr '{ x = 1; }' \
  | jq '.bindings[0].value.contents.contents *= 2' \
  | nix-ast render

# Evaluate and query results
nix-ast parse --expr '{ inherit (builtins) map filter; }' | nix-ast eval | jq 'keys'

# Batch process multiple files
echo '["file1.nix", "file2.nix", "file3.nix"]' \
  | nix-ast parse \
  | nix-ast render --out-dir ./out

Core Functions

The four main functions (parse, render, eval, toAST, fromAST) bridge between Nix source code, AST values, and evaluated Nix values.

All IFD-based functions (parse, render, eval) require a pkgs argument (a Nixpkgs instance). They serialize inputs to JSON, invoke the nix-ast CLI inside a derivation, and parse the output back.

`parse`

Read .nix files from disk and return their AST representations. Uses nix-ast parse under the hood.

parse :: pkgs -> [Path] -> [AST]

How it works: Serializes file paths to JSON, runs nix-ast parse < paths.json in a derivation, then parses the JSON output back into Nix values.

Parameters:

Parameter	Type	Description
`pkgs`	`pkgs`	Nixpkgs instance (provides `runCommand` and `stdenv` for IFD)
`paths`	`[Path]`	List of paths to `.nix` files to parse

Returns: [AST]. A list of AST nodes, one per input file, in the same order.

Example:

# Parse a single file
asts = lib.parse pkgs [./config.nix];

# Parse multiple files
asts = lib.parse pkgs [./config.nix ./default.nix ./modules/*.nix];

# Access the first AST
ast = builtins.head asts;

Error behavior: If a file doesn’t exist or contains invalid Nix syntax, the derivation fails at build time with an error message indicating which file and the parser error.

`render`

Convert AST values to .nix files on disk. The inverse of parse.

render :: pkgs -> [AST] -> [Path]

How it works: Serializes ASTs to JSON, pipes them through nix-ast render --out-dir $out, which writes each AST to a file named by its index (0.nix, 1.nix, etc.) inside the derivation output directory.

Parameters:

Parameter	Type	Description
`pkgs`	`pkgs`	Nixpkgs instance (for IFD)
`asts`	`[AST]`	List of AST nodes to render

Returns: [Path]. List of store paths to generated .nix files. The i-th path corresponds to the i-th input AST.

Example:

# Render a single AST to file
outPaths = lib.render pkgs [ast];
configFile = builtins.head outPaths;
config = import configFile;

# Render multiple ASTs
outPaths = lib.render pkgs [ast1, ast2, ast3];
imported = map import outPaths;

Error behavior: If an AST is structurally invalid (e.g., missing required fields), the conversion to internal representation fails with a descriptive error.

`eval`

Evaluate AST values and return the results as JSON values.

eval :: pkgs -> [AST] -> [a]

How it works: Serializes ASTs to JSON, pipes them through nix-ast eval in a derivation. The CLI deserializes each AST, evaluates it, and outputs the results as JSON.

Parameters:

Parameter	Type	Description
`pkgs`	`pkgs`	Nixpkgs instance (for IFD)
`asts`	`[AST]`	List of AST nodes to evaluate

Returns: [a]. List of evaluated Nix values, serialized to JSON-compatible Nix values (atoms, lists, attrsets).

Constraints: Only JSON-serializable values are supported. Functions and derivations in the evaluation result cause errors.

Example:

# Evaluate a simple expression
asts = lib.parse pkgs [./expr.nix];
result = lib.eval pkgs asts;  # evaluated values

# Evaluate inline-generated AST
ast = lib.toAST { x = 1 + 2; };
result = lib.eval pkgs [ast];  # => [ { x = 3; } ]

`toAST`

Convert any native Nix value to its AST representation. A pure function with no IFD required.

toAST :: a -> AST

How it works: Recursively inspects the Nix value’s type using builtins.isBool, builtins.isInt, etc., and constructs the corresponding AST nodes using syntax constructors (mkInt, mkSet, mkStr, etc.). Attrsets are converted to Set nodes with NamedVar bindings. Strings become Str → DoubleQuoted → Plain.

Supported types:

Nix type	AST representation
`Bool`	`Constant (Bool b)`
`Int`	`Constant (Int i)`
`Float`	`Constant (Float f)`
`null`	`Constant Null`
`String`	`Str (DoubleQuoted [Plain s])`
`Path`	`LiteralPath`
`List`	`List [items...]`
`AttrSet`	`Set { recursive = false, bindings = [...] }`

Unsupported types: Functions and derivations raise an error.

Example:

lib.toAST 42;
# => { tag = "Constant"; contents = { tag = "Int"; contents = 42; }; }

lib.toAST { x = 1; y = [1 2 3]; };
# => { tag = "Set"; recursive = false;
#      bindings = [
#        { tag = "NamedVar"; attrPath = [{tag="StaticKey"; contents="x"}];
#          value = { tag = "Constant"; contents = { tag = "Int"; contents = 1; }; }; }
#        ...
#      ]; }

Error behavior:

toAST on a function: "toAST: cannot convert function to AST"
toAST on a derivation: "toAST: cannot convert derivation to AST"
Unrecognized type: "toAST: unsupported Nix type"

`fromAST`

Convert an AST back to a native Nix value. A pure function that runs entirely in Nix with no IFD.

fromAST :: AST -> a

How it works: Dispatches on the AST node tag via match and recursively converts nodes to native Nix values. Atoms become their Nix equivalents, strings are concatenated from their parts, lists are mapped element-wise, and non-recursive attrsets are reconstructed from bindings.

Supported node conversions:

AST node	Nix type	Notes
`Constant`	atom value	Int, Float, Bool, Null, Uri
`Str`	`String`	Concatenates parts; only `Str` and text in interpolation
`EnvPath`	`String`	Returns the path string directly
`LiteralPath`	`String`	Returns the path string directly
`List`	`List`	Recursively converts elements
`Set`	`AttrSet`	Only non-recursive sets

Limitations:

Recursive sets (rec { ... }) throw: "fromAST: cannot convert recursive set to Nix value"
Plain inherit (without a scope) throws: "fromAST: plain inherit (without scope) is not supported"
String interpolation only supports Str nodes or plain text inside Antiquoted parts
Paths are returned as strings, not actual Nix paths

Example:

ast = lib.toAST { greeting = "hello"; count = 42; };
lib.fromAST ast;
# => { greeting = "hello"; count = 42; }

# Round-trip: toAST → fromAST preserves the value
assert lib.fromAST (lib.toAST [1 2 3]) == [1 2 3];

Workflow Example

Parse a Nix file, transform it, render the result, and verify via eval.

let
  inherit (lib) parse render eval traversal syntax toAST fromAST;

  # Step 1: Parse source files into ASTs
  asts = parse pkgs [./config.nix];
  original = builtins.head asts;

  # Step 2: Transform the AST (double all integer constants)
  transformed = traversal.transform (node:
    if syntax.isConstant node && syntax.isInt node.contents then
      syntax.mkConstant (syntax.mkInt (node.contents.contents * 2))
    else
      node
  ) original;

  # Step 3: Render back to .nix file
  outPaths = render pkgs [transformed];
  configFile = builtins.head outPaths;

  # Step 4: Import the result
  config = import configFile;

  # Step 5: Or evaluate the transformed AST directly
  evaluated = eval pkgs [transformed];

in { inherit config configFile evaluated; }

match: Pattern Matching

Type-safe pseudo pattern matching on AST node tags.

Syntax

match ast {
  Tag1 = handler1;
  Tag2 = handler2;
  _ = defaultHandler;
}

Each handler is a function that receives the matched node.

Examples

Simple Match

match ast {
  Sym = n: n.contents;
  _ = n: "unknown";
}

Destructure

match ast {
  App = { func, arg }: "application";
  If = { cond, thenExpr, elseExpr }: "conditional";
  Let = { bindings, body }: "let expression";
  _ = n: n.tag;
}

Nested Match

match ast {
  Set = { recursive, bindings }:
    if recursive then "recursive set" else "set";
  _ = n: "other";
}

Handler Signatures

Each handler receives the node as its argument. You can destructure the fields:

# Full node
match ast {
  Sym = n: n;  # n is the entire node
  _ = n: n;
}

# Destructured
match ast {
  Sym = { contents }: contents;  # destructure fields
  App = { func, arg }: func;
  _ = n: n.tag;
}

Wildcard

The _ handler catches any unmatched tag:

match ast {
  Sym = n: "symbol";
  _ = n: "other: ${n.tag}";
}

Use Cases

Type Checking

isInteger = match ast {
  Constant = { contents }: syntax.isInt contents;
  _ = _: false;
};

Pretty Printing

pretty = match ast {
  Sym = { contents }: contents;
  Int = { contents }: toString contents;
  Str = { contents }: "\"${contents}\"";
  _ = n: builtins.toJSON n;
};

syntax: Constructors & Predicates

Type-checked node builders and tag predicates. All constructors validate their arguments at runtime.

Constructors

Atoms

syntax.mkInt 42
syntax.mkFloat 3.14
syntax.mkBool true
syntax.mkNull
syntax.mkUri "https://example.com"

Strings

syntax.mkStr (syntax.mkDoubleQuoted [ syntax.mkPlain "hello" ])
syntax.mkStr (syntax.mkIndented 2 [ syntax.mkPlain "world" ])

Expressions

syntax.mkSym "x"
syntax.mkApp (syntax.mkSym "f") (syntax.mkInt 1)
syntax.mkAbs (syntax.mkParam "x") (syntax.mkSym "x")
syntax.mkIf (syntax.mkBool true) (syntax.mkInt 1) (syntax.mkInt 2)
syntax.mkLet [ syntax.mkNamedVar [ syntax.mkStaticKey "x" ] (syntax.mkInt 1) ] (syntax.mkSym "x")
syntax.mkSet false [ syntax.mkNamedVar [ syntax.mkStaticKey "x" ] (syntax.mkInt 1) ]
syntax.mkList [ syntax.mkInt 1 syntax.mkInt 2 syntax.mkInt 3 ]
syntax.mkBinary "+" (syntax.mkSym "x") (syntax.mkSym "y")
syntax.mkUnary "!" (syntax.mkSym "x")
syntax.mkWith (syntax.mkSym "pkgs") (syntax.mkSym "x")
syntax.mkAssert (syntax.mkBool true) (syntax.mkSym "x")
syntax.mkSelect (syntax.mkSym "default") (syntax.mkSym "set") [ syntax.mkStaticKey "attr" ]
syntax.mkHasAttr (syntax.mkSym "set") [ syntax.mkStaticKey "attr" ]
syntax.mkLiteralPath "./foo.nix"
syntax.mkEnvPath "<nixpkgs>"

Bindings

syntax.mkInherit null [ "x" "y" ]
syntax.mkInherit (syntax.mkSym "pkgs") [ "vim" "git" ]
syntax.mkNamedVar [ syntax.mkStaticKey "x" ] (syntax.mkInt 1)

Keys

syntax.mkStaticKey "foo"
syntax.mkDynamicKey (syntax.mkAntiquoted (syntax.mkSym "name"))

Parameters

syntax.mkParam "x"
syntax.mkParamSet null false [ [ "x" null ] [ "y" (syntax.mkInt 1) ] ]

Antiquoted Text

syntax.mkPlain "hello"
syntax.mkAntiquoted (syntax.mkSym "x")
syntax.mkEscapedNewline

Predicates

One predicate per node type:

# Expression predicates
syntax.isAbs node
syntax.isApp node
syntax.isAssert node
syntax.isBinary node
syntax.isConstant node
syntax.isEnvPath node
syntax.isHasAttr node
syntax.isIf node
syntax.isLet node
syntax.isList node
syntax.isLiteralPath node
syntax.isSelect node
syntax.isSet node
syntax.isStr node
syntax.isSym node
syntax.isSynHole node
syntax.isUnary node
syntax.isWith node

# Atom predicates
syntax.isInt node
syntax.isFloat node
syntax.isBool node
syntax.isNull node
syntax.isUri node

# Binding predicates
syntax.isInherit node
syntax.isNamedVar node

# Key predicates
syntax.isDynamicKey node
syntax.isStaticKey node

# String predicates
syntax.isDoubleQuoted node
syntax.isIndented node

# Antiquoted text predicates
syntax.isPlain node
syntax.isAntiquoted node
syntax.isEscapedNewline node

Helpers

# Get node tag
syntax.getExprKind node  # => "Sym", "App", etc.

# Check tag
syntax.hasTag "Sym" node  # => true/false

traversal: Tree Operations

All operations respect the children/rebuild contract: rebuild node (children node) == node.

Core Operations

`children`

Get immediate child nodes in deterministic order.

traversal.children :: Expr -> [Expr]

Example:

# For: { tag = "App"; func = f; arg = x; }
traversal.children node  # => [f, x]

`rebuild`

Reconstruct node from new children (inverse of children).

traversal.rebuild :: Expr -> [Expr] -> Expr

Example:

newNode = traversal.rebuild node [newFunc newArg]

`descend`

Apply function to all immediate children, then rebuild.

traversal.descend :: (Expr -> Expr) -> Expr -> Expr

Example:

# Transform all direct children
traversal.descend (n: n + 1) node

Transformations

`transform`

Bottom-up transformation: f (descend (transform f) node).

traversal.transform :: (Expr -> Expr) -> Expr -> Expr

Example:

# Replace all integers with their double
doubleInts = traversal.transform (node:
  if syntax.isConstant node && syntax.isInt node.contents then
    syntax.mkConstant (syntax.mkInt (node.contents.contents * 2))
  else
    node
);

`rewrite`

Apply rule bottom-up; null means no change.

traversal.rewrite :: (Expr -> Expr | null) -> Expr -> Expr

Example:

# Simplify constant folding
simplify = traversal.rewrite (node:
  if isBinaryAdd node && bothConstants node then
    syntax.mkInt (evalNode node)
  else
    null  # no change
);

`para`

Paramorphism: access node and recursive results from children.

traversal.para :: (Expr -> [a] -> a) -> Expr -> a

Example:

# Count all nodes
countNodes = traversal.para (node: childCounts:
  1 + builtins.foldl' (a: b: a + b) 0 childCounts
);

Exploration

`universe`

All descendant nodes including self.

traversal.universe :: Expr -> [Expr]

Example:

allSymbols = builtins.filter syntax.isSym (traversal.universe ast);

`holes`

Each child paired with a replacement function.

traversal.holes :: Expr -> [(Expr, Expr -> Expr)]

Example:

# Get all positions where a child can be replaced
holes = traversal.holes ast;
# => [(child1, \replacement -> rebuild node [replacement ...]),
#     (child2, \replacement -> rebuild node [... replacement ...])]

`contexts`

Every subnode paired with a function to replace it in context.

traversal.contexts :: Expr -> [(Expr, Expr -> Expr)]

Example:

# Get all subexpressions with their context
contexts = traversal.contexts ast;

Children/Rebuild Contract

All traversal operations maintain this invariant:

traversal.rebuild node (traversal.children node) == node

This ensures that operations can freely decompose and reconstruct nodes without losing information.

Use Cases

Deep Transformation

# Replace all variable references
replaceVars = traversal.transform (node:
  if syntax.isSym node then
    syntax.mkSym (replaceName node.contents)
  else
    node
);

Collection

# Collect all function applications
collectApps = traversal.universe >> builtins.filter syntax.isApp;

Analysis

# Check if expression contains a specific pattern
containsAssert = node:
  builtins.any syntax.isAssert (traversal.universe node);

Antiquoted

Constructors

Constructor	Fields	Description
`Plain`	`contents: v`	Literal value: `Text` in string parts, `String` in `DynamicKey`
`Antiquoted`	`contents: Expr`	Embedded expression `${...}`
`EscapedNewline`	(none)	Escaped newline `\` in indented strings

Description

Antiquoted is polymorphic in the Plain constructor. It is used at two type arguments:

Antiquoted Text: in string parts (DoubleQuoted / Indented), Plain wraps literal text.
Antiquoted String: in DynamicKey, Plain wraps a String AST node (DoubleQuoted / Indented).

A string like "hello ${x} world" becomes a list: [Plain "hello ", Antiquoted (Sym "x"), Plain " world"]

Constructor	Field	Type	Description
`Bool`	`contents`	`Bool`	Boolean value (`true`/`false`)
`Float`	`contents`	`Float`	Floating-point (not in Nix surface syntax)
`Int`	`contents`	`Integer`	64-bit integer
`Null`	(none)	-	Null value
`Uri`	`contents`	`Text`	URI literal

Constructor	Fields	Description
`Inherit`	`scope: Maybe Expr`, `names: [VarName]`	Inherit variables from scope
`NamedVar`	`attrPath: AttrPath`, `value: Expr`	Named variable binding

Field	Type	Description
`scope`	`Maybe Expr`	Optional scope expression (`Nothing` = current scope, `Just e` = inherit from `e`)
`names`	`[VarName]`	List of variable names to inherit

Field	Type	Description
`attrPath`	`AttrPath`	Attribute path (non-empty list of `KeyName`)
`value`	`Expr`	The bound expression

Keyboard shortcuts

nix-ast