key

Reads one value out of a map by key or out of a slice by index.

Pass a string to look up a map key, and use dot notation in that string to walk into nested maps (for example 'database.host'). Pass a number to index into a slice.

A lookup that finds nothing is a miss rather than a failure. A missing key, a path that runs out partway, an out-of-range index, and a nil value all report one. That is catchable, so | default:'x' supplies a fallback, an if reads it as false, and a for iterates nothing. Uncaught, it fails the render rather than quietly rendering empty, since a misspelled key that renders nothing is indistinguishable from data that was genuinely absent.

Being handed something that cannot be looked up at all is a different thing and stays terminal. No key parameter, a non-string key, or a value that is neither map nor slice means the template is wrong, and no default rescues it.

InputArgumentsReturnsany[]anyany

Source

Behaviors

Catchable miss: When the data it looks for is not there, it reports a miss rather than failing the render, so default can supply a fallback and an if or for reads the absence as false.

BasicSource

Reads one value out of a map by key, walking nested maps with dot notation.

Given

{"config": {"database": {"host": "db.local", "port": 5432}}}

Template

{{ config | key:'database.host' }}

Result

db.local

ConditionSource

Shows an absent key read as false. An if already asks whether something is there, so it needs no default to say what absence means.

Given

{"user": {"name": "Alice"}}

Template

{{ if user | key:'phone' }}call them{{ else }}write instead{{ endif }}

Result

write instead

DefaultSource

Pairs an absent key with default, which supplies a value in its place.

Given

{"user": {"name": "Alice"}}

Template

{{ user | key:'phone' | default:'no phone on file' }}

Result

no phone on file

Default further downSource

Shows that the default answering a miss need not follow it immediately. An absent key sends nothing down the pipe, and first declines to take an element from nothing, leaving the miss for default to answer.

Given

{"user": {"name": "Alice"}}

Template

{{ user | key:'phones' | first | default:'no phone on file' }}

Result

no phone on file

IndexSource

Reads one element out of a list by passing its position as a number instead of a name.

Given

{"items": ["espresso", "latte", "macchiato"]}

Template

{{ items | key:0 }}

Result

espresso

Nested numberSource

Walks a dot path into nested maps and returns the value it lands on, keeping its number type.

Given

{"config": {"database": {"host": "db.local", "port": 5432}}}

Template

{{ config | key:'database.port' }}

Result

Missing keySource

Shows an absent key with nothing to answer it. Rendering empty here would read the same as a host that was genuinely blank, and a misspelled key would go unnoticed, so the render fails instead.

Given

{"config": {"database": {"host": "db.local"}}}

Template

{{ config | key:'database.hsot' }}

Result

error: failed to render template: failed to render variable token 'config': modifier "key": function failed to apply: key "hsot" not found

Not a mapSource

Shows a value that cannot be looked up at all. That is the template being wrong rather than data being absent, so no default rescues it.

Given

{"name": "Alice"}

Template

{{ name | key:'first' | default:'unknown' }}

Result

error: failed to render template: failed to render variable token 'name': modifier "key": function failed to apply: key expected a map or slice, got string: invalid value type

Read the source of key on GitHub