Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

API Reference

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

Overview

The API is organized into three layers:

LayerFunctionsDescription
IFD bridgeparse, render, evalBridge to the Haskell parser/evaluator via Import From Derivation
Value conversiontoAST, fromASTPure Nix conversion between Nix values and AST nodes
AST toolsmatch, syntax, traversalPattern matching, constructors, and tree operations

Pages

PageDescription
Core Functionsparse, render, eval, toAST, fromAST
syntax: Constructors & Predicatesmk* builders and is* tag checks for all node types
match: Pattern MatchingType-safe tag dispatch with match ast { ... }
traversal: Tree Operationschildren, rebuild, transform, universe, contexts

How IFD Works

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

  1. Serializes the input (paths, ASTs) to a JSON file via pkgs.writeText
  2. Runs the nix-ast CLI binary inside the derivation, piping the JSON file to stdin
  3. Captures stdout as the derivation output
  4. 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.