Reference

Standard Library

The functions, filters, and tests available inside a Netsukefile: paths, file contents, collections, time, command execution, executable discovery, and network access — each labelled pure or host-observing.

Standard Library Reference

fetch() Network

Downloads content from a URL. HTTPS is the only allowed scheme by default; the --fetch-* CLI options widen or narrow the policy. Since v0.1.0-beta4 every redirect is rechecked against it (at most five hops), and a project .netsuke.toml can only narrow it. Pass cache=true to cache the result in .netsuke/fetch. Marks the template as impure.

fetch("https://example.com/data", cache=true)

command_available() Discovery

Returns true when an executable can be found on PATH, false otherwise. Accepts the same keyword arguments as which, including cwd_mode; since v0.1.0-beta4 it searches only PATH unless told otherwise. Ideal in when conditions.

when: command_available('pandoc')

with_suffix Path

Replaces the file extension of a path. Accepts an optional count to replace multiple trailing extensions, and an optional separator (default .).

env() Data

Reads one required environment variable. There is no default-value argument; a missing or non-Unicode value is an error. Since v0.1.0-beta4 the operator's env_allow_var and env_block_var lists govern which names it may read; a refused name fails with “Access to an environment variable is blocked.” See environment access.

env("CC")

basename / dirname Path

Pure path filters: basename returns the final path component; dirname returns the parent (or . when there is none).

glob File

Finds workspace paths matching a pattern, sorted, including parent-relative patterns such as glob('../shared/*.h'). Expansion holds only the authority of the pattern's literal directory prefix; a match reached through a symbolic link that escapes the prefix is skipped. Matched paths must be portable unquoted shell words (letters, digits, /, :, comma, full stop, underscore, hyphen); anything else is rejected so a checkout filename cannot become shell syntax. Host-observing: results depend on workspace contents and platform. Use sparingly to maintain explicit dependencies.

glob('src/*.c')

Extended Standard Library

Beyond the core functions, Netsuke provides a rich set of filters and helpers covering time, file inspection, paths, collections, shell execution, and executable discovery.

Time helpers

now() Time

Returns the current time as a timezone-aware object (defaults to UTC). Exposes .iso8601, .unix_timestamp, and .offset. Accepts an optional UTC offset string such as '+02:00' or 'Z'.

timedelta() Time

Creates a duration object for age comparisons and arithmetic. Accepts weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds. Exposes .iso8601, .seconds, .nanoseconds.

timedelta(days=7)

File content filters

One read policy for `contents`, `linecount`, `hash`, and `digest`

Breaking in v0.1.0-beta4

Each read stops at 8 MiB by default. max_bytes=N lowers the budget for one call; a larger value is clamped to the ceiling.
A symbolic link as the final path component is refused (on Windows, any reparse point). follow_symlinks=true accepts a relative-target link; an absolute-target link is still refused.
The opened object must be a regular file, so FIFOs and device nodes are refused.

Details and the trust model are on the security page.

contents File

Reads a file's content as a string. Accepts an optional encoding argument; 'utf-8' (alias 'utf8') is currently the only supported encoding, and other byte sequences are an error.

size File

Returns the file size in bytes. Useful for gating large downloads or asserting build artefact bounds.

linecount File

Counts the number of lines in a UTF-8 text file, reading within the shared byte budget.

hash File

Returns the full hex digest of a file. Supports sha256 (default) and sha512; MD5 and SHA-1 need the legacy-digests build feature.

digest File

Returns a truncated hex digest of a file. Accepts a length (default: 8) and an algorithm (default: sha256). Useful for short cache-busting hashes in output filenames.

Path filters

relative_to Path

Makes an absolute path relative to a given base. '/a/b/c' | relative_to('/a/b') → 'c'.

realpath Path

Canonicalises a path, resolving all symlinks and relative components to an absolute path.

expanduser Path

Expands a leading ~ to the current user's home directory.

Collection filters

uniq Collection

Removes duplicate items from a list, preserving the original order of first occurrences.

glob('**/*.h') | uniq

flatten Collection

Flattens a nested list into a single flat list. [[1], [2, 3]] | flatten → [1, 2, 3].

source_groups | flatten

group_by Collection

Groups a list of dicts or objects by the value of a named attribute, returning a dict of lists keyed by the grouped value.

files | group_by('extension')

Command filters Impure

These filters execute external processes at template evaluation time, making the template impure — its output depends on the environment, not just the manifest. Use judiciously.

shell() Command

Pipes the input value as stdin to a shell command string. Capture mode (the default) returns the command's stdout. Pass {'mode': 'tempfile'} (also spelled stream or streaming) to write bounded output to a persisted temporary file; those modes return the file's path, not its contents.

grep() Command

Runs the host grep executable over the input value. The flags argument is a sequence such as ['-i']; availability and flag spelling are platform-dependent. Options share the same modes as shell.

Executable discovery

which Discovery

Resolves executables using the current PATH without marking the template impure. Available as both a filter ({{ 'clang++' | which }}) and a function ({{ which('clang++') }}). On Windows, an extensionless name is matched against the effective PATHEXT, so which('cargo') finds cargo.exe.

Workspace search is opt-in

Breaking in v0.1.0-beta4

The default lookup searches only PATH. Beta3 fell back to a recursive workspace search when PATH was empty or unset; that fallback is gone, and such a lookup now reports the command missing. A trusted manifest that needs the old search asks for it with cwd_mode='workspace-recursive' — and only for a checkout it trusts, because the search can resolve an executable the checkout supplies. NETSUKE_WHICH_WORKSPACE=0 (or false, off) switches that explicit mode off.

Keyword arguments

all Return every match, ordered by PATH (default: false)

canonical Resolve symlinks and deduplicate by canonical path (default: false)

fresh Bypass the resolver cache for this lookup (default: false)

cwd_mode Choose the search domain. auto (default): PATH only. always: prepend the workspace root or current directory. never: exclude it. workspace-recursive: scan the workspace tree after PATH.

Diagnostic codes

netsuke::jinja::which::not_found — executable not found; includes a preview of the scanned PATH and, unless that mode was already chosen, a hint pointing at cwd_mode="workspace-recursive"

netsuke::jinja::which::args — unknown or invalid keyword argument

Filesystem tests

Use Jinja's is keyword with these tests to gate targets conditionally. Tests are host-observing; a missing path or non-string value yields false, and the symlink test does not follow links.

Type tests

is file — regular file

is dir — directory

is symlink — symbolic link

Special-file tests (always false off Unix)

is pipe — named pipe

is block_device / is char_device

is device — either device kind

targets:
  - when: 'src/main.c' is file and command_available('clang')
    name: "build/main.o"
    rule: "compile"

Pure vs host-observing

“Pure” means the result depends only on the supplied value and arguments. Host-observing helpers read the clock, environment, filesystem, network, or subprocess state; fetch with a cache may also write beneath .netsuke/. Pure helpers make generated build graphs reproducible; host-observing helpers are useful for discovery and conditional planning, but their results can vary between machines or invocations.

Prefer explicit manifest inputs when a value is part of the build's reproducibility contract, and keep network or command execution out of untrusted Netsukefile content — Netsuke bounds helper output, but it does not sandbox template evaluation.

The `help targets` query allowlist

netsuke help targets renders the manifest through a restricted, side-effect-free surface. Only the lexical path filters basename, dirname, with_suffix, and relative_to, the collection filters uniq, flatten, and group_by, and the clock-independent timedelta function are available. Recipe bodies are skipped entirely, so build-only helpers there are never evaluated.

env(), glob(), file tests, filesystem metadata filters, hash, digest, contents, realpath, expanduser, which, command_available, fetch, shell, grep, and now() are rejected in queries. A when expression that needs one of them keeps its entry in the catalogue marked conditional rather than failing. Normal build rendering retains the full library.

Templating

CLI Commands