Netsuke Standard Library (Stdlib)

Netsuke provides a rich set of built-in Jinja functions, filters, and tests to simplify common build tasks. These are automatically available in your manifest templates.

• env(name, default=None): Reads an environment variable. Fails if name is unset and no default is provided. Example: {{ env('CC', 'gcc') }}

• glob(pattern): Expands a filesystem glob pattern into a sorted list of files (directories are excluded). Handles *, **, ?, []. Case-sensitive. Example: {{ glob('src/**/*.c') }}

• fetch(url, cache=False): Downloads content from a URL. If cache=True, caches the result in .netsuke/fetch within the workspace based on URL hash. Enforces a configurable maximum response size (default 8 MiB); requests abort with an error quoting the configured threshold when the limit is exceeded. Cached downloads stream directly to disk and remove partial files on error. Configure the limit with StdlibConfig::with_fetch_max_response_bytes. Marks template as impure.

• now(offset=None): Returns the current time as a timezone-aware object (defaults to UTC). offset can be '+HH:MM' or 'Z'. Exposes .iso8601, .unix_timestamp, .offset.

• timedelta(...): Creates a duration object (e.g., for age comparisons). Accepts weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds. Exposes .iso8601, .seconds, .nanoseconds.

Apply filters using the pipe | operator: {{ value | filter_name(args...) }}

• basename: {{ 'path/to/file.txt' | basename }} -> "file.txt"

• dirname: {{ 'path/to/file.txt' | dirname }} -> "path/to"

• with_suffix(new_suffix, count=1, sep='.'): Replaces the last count dot-separated extensions. {{ 'archive.tar.gz' | with_suffix('.zip', 2) }} -> "archive.zip"

• relative_to(base_path): Makes a path relative. {{ '/a/b/c' | relative_to('/a/b') }} -> "c"

• realpath: Canonicalizes path, resolving symlinks.

• expanduser: Expands ~ to the home directory.

• contents(encoding='utf-8'): Reads file content as a string.

• size: File size in bytes.

• linecount: Number of lines in a text file.

• hash(alg='sha256'): Full hex digest of file content (supports sha256, sha512; md5, sha1 if legacy-digests feature enabled).

• digest(len=8, alg='sha256'): Truncated hex digest.

• shell_escape: Crucial for security. Safely quotes a string for use as a single shell argument. Use this whenever interpolating paths or variables into commands unless you are certain they are safe.

• uniq: Removes duplicate items from a list, preserving order.

• flatten: Flattens a nested list. {{ [[1], [2, 3]] | flatten }} -> [1, 2, 3]

• group_by(attribute): Groups items in a list of dicts/objects by an attribute's value.

• map(attribute='...') / map('filter', ...): Applies attribute access or another filter to each item in a list.

• filter(attribute='...') / filter('test', ...): Selects items based on attribute value or a test function.

• join(sep): Joins list items into a string.

• sort: Sorts list items.

• shell(command_string): Pipes the input value (string or bytes) as stdin to command_string executed via the system shell (sh -c or cmd /C). Returns stdout. Marks the template as impure. Example: {{ user_list | shell('grep admin') }}. The captured stdout is limited to 1 MiB by default; configure a different budget with StdlibConfig::with_command_max_output_bytes. Exceeding the limit raises an InvalidOperation error that quotes the configured threshold. Templates can pass an options mapping such as {'mode': 'tempfile'} to stream stdout into a temporary file instead. The file path is returned to the template and remains bounded by StdlibConfig::with_command_max_stream_bytes (default 64 MiB).

• grep(pattern, flags=None): Filters input lines matching pattern. flags can be a string (e.g., '-i') or list of strings. Implemented via shell. Marks template as impure. The same output and streaming limits apply when grep emits large result sets.

• which filter/function: Resolves executables using the current PATH without marking the template as impure. Example: {{ 'clang++' | which }} returns the first matching binary; the function alias {{ which('clang++') }} is available if piping would be awkward.
• Keyword arguments:
• all (default false): Return every match, ordered by PATH.
• canonical (default false): Resolve symlinks and deduplicate entries by their canonical path.
• fresh (default false): Bypass the resolver cache for this lookup while keeping previous entries available for future renders.
• cwd_mode (auto | always | never, default auto): Control whether empty PATH segments (and, on Windows, the implicit current-directory search) are honoured. Use "always" to force the working directory into the search order when PATH is empty.
• Errors include actionable diagnostic codes such as netsuke::jinja::which::not_found along with a preview of the scanned PATH. Supplying unknown keyword arguments or invalid values raises netsuke::jinja::which::args.

Impurity: Filters like shell and functions like fetch interact with the outside world. Netsuke tracks this "impurity". Impure templates might affect caching or reproducibility analysis in future versions. Use impure helpers judiciously.

Use tests with the is keyword: {% if path is file %}

• file, dir, symlink: Checks filesystem object type (without following links).

• readable, writable, executable: Checks permissions for the current user.

• absolute, relative: Checks path type.