2. Paths

Paths select values from the source, scope, library, or transform itself. The deployed dialect combines a result prefix with a selector:

• ^ returns the first selected value, or null.
• & returns the complete list of selected values.
• $ starts at the root source.
• @ starts at the caller’s scope.
• ^ as a selector starts at the current builtin scope.
• * starts at the transform library.
• ~ starts at the root transform.
• % starts at a value supplied as the first argument.

The first ^ in "^$.name" is the result prefix; $ is the selector.

Map members and list indexes

Given:

{
  "person": {"name": "Ada"},
  "items": ["zero", "one"]
}

"^$.person.name" returns "Ada", and "^$.items.1" returns "one". Missing head selections return null.

Wildcards

* selects immediate children:

"&$.people.*.name"

Given two people, this returns both names. ** descends recursively:

"&$.document.**.url"

Use & when a wildcard may select several values. A ^ wildcard deliberately takes only the first and should not be used where map ordering matters.

Raw paths

% selects from a value constructed inside the transform:

["^%", {"person": {"name": "Fred"}}, "person", "name"]

Result:

"Fred"

The list form can represent selectors that would be awkward in a dotted string.

Paths are forgiving

An inapplicable path component discards that branch. It does not throw. The full-list form therefore returns [] for no matches, while the head form returns null.

Historical note

The old v0.3 README used # and ##. Deployed Studio examples and all later language material use ^ and &; this guide uses the deployed notation.

Try the curated basic path and wildcard examples.

Next: Builtins.