o list#

Read every node a path names, optionally filtered by a match.

The path is a kpath -- .field, [i], {i}, (key), the wildcards . [] {*}, and .. for any depth, which belong here rather than in get: list answers with every node the path names.

o list ..image deploy.tony      # every image, wherever it is
o list 'spec..name' deploy.tony # every name under spec, at any depth

A leading $ is accepted and dropped, from when paths were written that way, and the $...x spelling of any-depth is read as ..x.

-depth bounds the path's descents to that many segments between them -- how far off what the path spells the answer may lie, counted from the node the path names -- so 'a..' at -depth 1 is a and its children, of every kind, at whatever level a is, and '..name' at -depth 2 reaches a name at most two levels down. It bounds a .., and a path with none refuses it.

o list -paths -depth 1 'spec..' deploy.tony   # spec and what is directly under it

The path says where to look and -if says which of what is there to keep, which together are how a list is filtered by a match:

x | o list -if '{state: open}' '$[*]'            # the matching elements
o list -if '{state: open}' '$.items[*]' doc.tony # at any depth the path reaches

-trim writes only the parts its own match document names, so which nodes and how much of each are asked separately:

x | o list -if '{status: running}' -trim '{runner: null, started: null}' '[*]'

-paths writes where each node is rather than what it is, as a path this same tool reads, so a query can be turned into the places it found:

o list -paths ..image deploy.tony
- spec.containers[0].image
- spec.containers[1].image

o list -paths ..image deploy.tony | o list '[*]' | ...   # feed them onward

It answers about the same nodes -if selects, and ignores -trim, which is about how much of a node to write and not about where it is.

A comment describes a value and is not the value itself, so -if sees through one. !comment is how it asks about the comments instead, and it needs -c -- without it the comments are never read and there is nothing to ask about:

o list -c -if '!comment {head: ["# generated"]}' 'items[*]' doc.tony

A head comment belongs to the value written under it and a line comment to the value it follows, so the question is asked at that node and not at the one above:

o list -c -if '{name: !comment {line: [" # keep"]}}' 'items[*]' doc.tony

A file is optional: with none, stdin is read, as grep and cat do -- from a pipe, or typed at a terminal and ended with Ctrl-D. An input is a stream of documents, --- separated, and the path is asked of every one of them; the answer is a single list over all of them, whichever input each node came from.

Without -if the path is the whole question and every node it names is written. The answer is a list, and the empty list is written as one; the exit code says whether it was empty: 0 when something was kept, 1 when nothing was, 2 for a fault.

The match documents -if and -trim take are the ones o match takes; the operators they may use are at https://signadot.github.io/tony-format/matchpatch/

Also known as l.

Usage#

o list [opts] <kpath> [file...]

Options#

inherited from o#

o list options#

Inherited options may be given either before or after the command they are inherited by.

Boolean options take no argument and may be negated with a no- prefix, as in -no-debug.

See also#

• o
• o view
• o eval
• o diff
• o get
• o match
• o patch
• o build
• o dump
• o load
• o schema
• o system
• o docs
• o help
• o completion
• o version