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

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

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.

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 text file. Does not load the entire file into memory.

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++') }}).

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 auto | always | never — control whether empty PATH segments honour the working directory

Diagnostic codes

netsuke::jinja::which::not_found — executable not on PATH; includes a preview of the scanned PATH

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.

Templating

CLI Commands