Utilities API
Helper Tools for Data & Paths
Loom exposes two utility modules: collection (for data manipulation) and path (for tree introspection). These are often used when building complex measure logic.
Module: loom.collection
Functional utilities for manipulating standard Typst dictionaries and arrays. These helpers are "safe" by default—they tend to return none or default values rather than panicking.
get
Safely retrieves a value from a nested structure of dictionaries and arrays.
collection.get(root, ..path, req-type: none, default: none) -> any
| Parameter | Type | Default | Description |
|---|---|---|---|
root | dictionary | array | required |
..path | str | int | required |
req-type | type | none | If provided, returns default if the found value does not match this type. |
default | any | none | The value to return if the path is invalid or result is none. |
map
Applies a function to a value only if the value is not none.
collection.map(value, fn, req-type: none) -> any
| Parameter | Type | Default | Description |
|---|---|---|---|
value | any | required | The value to transform. |
fn | function | required | The transformation function v => new_v. |
req-type | type | none | If provided, returns none if value does not match this type. |
merge-deep
Recursively merges two dictionaries. Unlike standard Typst +, this preserves nested keys in the base dictionary instead of overwriting the entire sub-dictionary.
collection.merge-deep(base, override) -> dictionary
| Parameter | Type | Default | Description |
|---|---|---|---|
base | dictionary | required | The original dictionary (e.g., default config). |
override | dictionary | required | The dictionary with updates (e.g., user config). |
omit
Creates a new dictionary with specific keys removed.
collection.omit(dict, ..keys) -> dictionary
| Parameter | Type | Default | Description |
|---|---|---|---|
dict | dictionary | required | The source dictionary. |
..keys | str | required | The keys to exclude. |
pick
Creates a new dictionary containing only the specified keys. Keys not present in the source are ignored.
collection.pick(dict, ..keys) -> dictionary
| Parameter | Type | Default | Description |
|---|---|---|---|
dict | dictionary | required | The source dictionary. |
..keys | str | required | The keys to keep. |
compact
Removes all none values from an array or dictionary.
collection.compact(collection) -> array | dictionary
Module: loom.path
Utilities for inspecting the component hierarchy. These functions read the System Path stored in the Context (ctx).
get
Retrieves the raw path array.
path.get(ctx) -> array<(str, int)>
- Returns: An array of tuples, e.g.,
( ("root", 0), ("section", 2) ).
to-string
Serializes the path into a unique string identifier.
path.to-string(ctx, separator: ">") -> str
- Returns: A string like
"root(0)>section(2)>div(1)".
contains
Checks if the current path contains specific component kinds.
path.contains(ctx, ..kinds, include-current: true) -> bool
| Parameter | Type | Default | Description |
|---|---|---|---|
ctx | dictionary | required | The current context. |
..kinds | str | required | One or more kinds to check for (e.g., "project"). |
include-current | bool | true | If false, checks only ancestors (parents), ignoring the component itself. |
parent
Retrieves the full tuple (kind, id) of the immediate parent.
path.parent(ctx) -> (str, int) | none
parent-kind
Retrieves just the "kind" string of the immediate parent.
path.parent-kind(ctx) -> str | none
parent-is
Checks if the immediate parent matches one of the provided kinds.
path.parent-is(ctx, ..kinds) -> bool
current
Retrieves the full tuple (kind, id) of the current component (the tip of the path).
path.current(ctx) -> (str, int) | none
current-kind
Retrieves just the "kind" string of the current component.
path.current-kind(ctx) -> str | none
depth
Returns the current nesting depth (length of the path).
path.depth(ctx) -> int