{"path":"/sutl/guide/paths","content":{"title":"2. Paths","summary":"Select source values with paths, indexes, wildcards and explicit starting values.","body":"[sUTL](/sutl) · [Guide](/sutl/guide) · [Reference](/sutl/reference) · [Examples](/sutl/examples)\n\nPaths select values from the source, scope, library, or transform itself. The\ndeployed dialect combines a result prefix with a selector:\n\n- `^` returns the first selected value, or null.\n- `&` returns the complete list of selected values.\n- `$` starts at the root source.\n- `@` starts at the caller's scope.\n- `^` as a selector starts at the current builtin scope.\n- `*` starts at the transform library.\n- `~` starts at the root transform.\n- `%` starts at a value supplied as the first argument.\n\nThe first `^` in `\"^$.name\"` is the result prefix; `$` is the selector.\n\n## Map members and list indexes\n\nGiven:\n\n```json\n{\n  \"person\": {\"name\": \"Ada\"},\n  \"items\": [\"zero\", \"one\"]\n}\n```\n\n`\"^$.person.name\"` returns `\"Ada\"`, and `\"^$.items.1\"` returns `\"one\"`.\nMissing head selections return null.\n\n## Wildcards\n\n`*` selects immediate children:\n\n```json\n\"&$.people.*.name\"\n```\n\nGiven two people, this returns both names. `**` descends recursively:\n\n```json\n\"&$.document.**.url\"\n```\n\nUse `&` when a wildcard may select several values. A `^` wildcard deliberately\ntakes only the first and should not be used where map ordering matters.\n\n## Raw paths\n\n`%` selects from a value constructed inside the transform:\n\n```json\n[\"^%\", {\"person\": {\"name\": \"Fred\"}}, \"person\", \"name\"]\n```\n\nResult:\n\n```json\n\"Fred\"\n```\n\nThe list form can represent selectors that would be awkward in a dotted\nstring.\n\n## Paths are forgiving\n\nAn inapplicable path component discards that branch. It does not throw. The\nfull-list form therefore returns `[]` for no matches, while the head form\nreturns null.\n\n## Historical note\n\nThe old v0.3 README used `#` and `##`. Deployed Studio examples and all later\nlanguage material use `^` and `&`; this guide uses the deployed notation.\n\nTry the curated [basic path](/sutl/examples/path-basic)\nand [wildcard](/sutl/examples/path-wildcards)\nexamples.\n\nNext: [Builtins](/sutl/guide/builtins).\n\n## Continue learning\n\n[Previous: 1. MLSNBN and transforms](/sutl/guide/mlsnbn-and-transforms) · [Guide contents](/sutl/guide) · [Language reference](/sutl/reference)\n\n## Source\n\nAdapted from [the sUTL source material](https://github.com/emlynoregan/sutllang-site/blob/e59ecafd364848cd71a1d18ce74cdf67f2f69328/content/guide/02-paths.md).\n\n[Back to sUTL](/sutl) · [Software & Agents](/topics/software-and-agents) · [All topics](/guide)","author":"Emlyn O'Regan"}}