jmespath-ruby 0.1.2 → 0.1.3

data/docs/guides/compilation.md

@@ -13,6 +13,316 @@ The expression owns a frozen copy of the query text.
 Changing the caller's original string does not change the compiled expression.
 Mutable literal results are copied for each evaluation.
 
+## Failure results
+
+`Expression#try_search` reuses compiled syntax and saved evaluation options, with per-call overrides handled independently.
+Calls return separate frozen results and isolate capture state across nested calls, threads, and fibers.
+The returned value or error retains its identity and independent mutability.
+See [search results](search.md#search-results) for the result fields.
+
+A custom function can handle an inner query failure explicitly:
+
+```ruby
+inner = JMESPath.compile("length(@)")
+functions = JMESPath::Functions.default.with("checked", signature: [[:any]]) do |value|
+  result = inner.try_search(value)
+  result.success? ? result.value : "invalid"
+end
+outer = JMESPath.compile("checked(@)", functions: functions)
+outer.try_search(4).value #=> "invalid"
+outer.try_search([1, 2]).value #=> 2
+```
+
+An exception escaping the custom function propagates from the outer call, even when it came from an inner query.
+
+## Required results
+
+Call `Expression#fetch` when a Ruby caller requires a non-null final result.
+It accepts the same inputs, positional options, and keyword options as `search`, including saved defaults and per-call overrides.
+Each call evaluates once and returns any non-nil result unchanged, preserving selected object identity and mutability.
+False, zero, empty strings, empty arrays, and empty hashes succeed.
+
+Use these calls in Ruby code:
+
+```ruby
+query = JMESPath.compile("user.name")
+query.fetch({user: {name: "Ada"}}) #=> "Ada"
+query.fetch({user: {name: false}}) #=> false
+query.fetch({}) # raises JMESPath::Errors::NullResultError
+query.fetch({user: {name: nil}}) # raises JMESPath::Errors::NullResultError
+```
+
+Missing fields, explicit null, and out-of-range indexes produce the same error.
+Only the final result must be non-null; intermediate null values can be replaced by the query.
+With `disable_visit_errors: true`, suppressed type or arity failures producing nil also raise `NullResultError`.
+Other failures propagate unchanged.
+The error exposes frozen query text through `expression` and uses the message `Expression returned null`.
+It contains no input document or explanation of the null result.
+Nullable `search` and `call` behavior is unchanged.
+
+## Query inspection
+
+Call `Expression#explain` to inspect query structure without providing input data.
+Inspection neither resolves function names nor executes callbacks.
+Unknown and custom function names remain valid structure; inspection cannot establish availability, argument types, or callback behavior.
+
+```ruby
+query = JMESPath.compile("user.name")
+query.explain[:root][:operation] #=> "subexpression"
+query.explain[:root][:children].map { |child| child[:node][:details][:name] } #=> ["user", "name"]
+query.explain[:root][:source_range] #=> [0, 9]
+```
+
+The returned hash has two keys: `:source`, containing the complete UTF-8 query text, and `:root`, containing a logical operation.
+Every operation has these keys:
+
+| Key | Value |
+| --- | --- |
+| `:id` | Integer identifying the operation within this explanation |
+| `:operation` | String from the operation table below |
+| `:source_range` | Two byte offsets, `[start_byte, end_byte]`, or nil |
+| `:details` | Hash containing operation-specific values |
+| `:children` | Ordered array of `{role: String, node: operation_hash}` entries |
+
+All hashes, arrays, and strings are frozen, including literal object keys and nested literal values.
+Repeated inspection produces equal data; object identity is unspecified.
+Saved evaluation options and cache settings do not affect the explanation.
+Compiled expressions support concurrent inspection with separate traversal state.
+Inspection exposes neither private syntax nodes nor optimizer operations.
+Ordinary compilation and evaluation do not construct explanations.
+
+### Operations and child roles
+
+Keys use symbols; operation names and child roles use strings.
+Decoded names and literal values retain their Ruby representations.
+Literal contents remain values, without additional operation nodes.
+Empty details are represented by `{}`.
+
+| Operation | Details | Child roles in traversal order |
+| --- | --- | --- |
+| `field` | `name: String` | None |
+| `current` | Empty | None |
+| `literal` | `value: decoded Ruby value` | None |
+| `group` | Empty | `expression` |
+| `subexpression` | Empty | Repeated `step` |
+| `pipe` | Empty | Repeated `step` |
+| `index` | `index: Integer` | `input` |
+| `slice` | `start`, `stop`, `step`, each Integer or nil | `input` |
+| `flatten` | Empty | `input` |
+| `projection` | Empty | `input`, `expression` |
+| `value_projection` | Empty | `input`, `expression` |
+| `filter_projection` | Empty | `input`, `condition`, `expression` |
+| `expression_reference` | Empty | `expression` |
+| `function` | `name: String` | Repeated `argument` |
+| `and`, `or` | Empty | Repeated `operand` |
+| `not` | Empty | `operand` |
+| `comparison` | `operator: String`, one of `==`, `!=`, `<`, `<=`, `>`, `>=` | `left`, `right` |
+| `multi_select_list` | Empty | Repeated `element` |
+| `multi_select_hash` | Empty | Repeated `entry` |
+| `entry` | `name: String` | `expression` |
+
+Repeated roles preserve source order, including duplicate hash entries.
+Omitted slice components remain nil, including an omitted step.
+Flattening and slicing can appear as inputs to projections.
+Explicit parentheses produce `group` nodes; implicit identities produce `current` nodes.
+Adjacent unparenthesized subexpressions, pipes, and identical boolean operators form ordered nodes with multiple children.
+
+### Operation IDs and evaluation rules
+
+IDs start at zero and increase consecutively in preorder: each operation, then its children in the table's order.
+Filter conditions precede projected expressions in this traversal.
+IDs include structural groups and hash entries.
+Identical query text produces identical IDs under this contract, independently of evaluation options or cache use.
+IDs are local to an explanation and do not identify operations across query edits.
+
+Traversal order describes structure, with these logical evaluation rules:
+
+| Operation family | Evaluation rule |
+| --- | --- |
+| Subexpressions and pipes | Evaluate steps left to right, passing each result to the next step. |
+| Function calls | Evaluate arguments left to right against the same input, then invoke the function. |
+| Expression references | Defer the referenced expression until a function requests evaluation against its chosen value. |
+| Projections | Evaluate input, then project each element; omit nil results and retain false. |
+| Value projections | Project object values without promising sorted object keys. |
+| Filters | Evaluate input, evaluate conditions for all elements, then project selected elements; omit nil projected results. |
+| Boolean operators | Evaluate operands left to right against the same input, stopping according to JMESPath truth rules. |
+| Comparisons | Evaluate both operands against the same input before comparing, left before right. |
+| Multiselects | Evaluate entries left to right against the same input; nil input returns nil without evaluating entries. |
+| Groups and entries | Evaluate their contained expression. |
+| Indexes, slices, flattening | Evaluate input before applying the operation; flattening removes one array level. |
+| Fields, current, literals, negation | Apply standard JMESPath semantics; negation evaluates its operand first. |
+
+The explanation contains no input values, evaluation events, or optimizer details.
+
+### Source coordinates and serialization
+
+Ranges include the start byte and exclude the end byte in the returned UTF-8 `:source`.
+They use the same coordinate units as lexer offsets and function-error byte ranges.
+Use `source.byteslice(start_byte...end_byte)` to extract the text.
+Inspection retains all source whitespace, including trailing newlines.
+Convertible non-UTF-8 query text is encoded as UTF-8 in the explanation; `Expression#source` retains its original encoding.
+
+Explicit operation ranges cover their entire syntactic expression, including delimiters and contained expressions.
+They exclude surrounding whitespace and retain internal whitespace.
+Quoted fields include quotes, groups include parentheses, and references include `&`.
+Projections include their projected expression; filters also include the input, brackets, and condition.
+Index, slice, and flatten ranges include their input when present.
+Hash-entry ranges include the key and value expression, excluding separators.
+Parent and child ranges can overlap.
+
+Implicit `current` operations have nil ranges; an explicit `@` has its token range.
+Every non-nil range stays within the source and ends on UTF-8 character boundaries.
+Line and column fields are omitted; derive them using the [syntax diagnostic conventions](errors.md).
+
+For finite numeric values, `JSON.generate(explanation)` serializes directly, with string keys and JSON values.
+Numeric overflow literals preserve their decoded non-finite Ruby floats, including values inside literal arrays and objects.
+Strict JSON cannot represent these values; generation raises `JSON::GeneratorError`, even with `max_nesting: false`.
+Inspection preserves those values and compilation behavior without substituting strings or nulls.
+Deep explanation trees can exceed JSON's default nesting limit before reaching the query's supported depth limit.
+Use `JSON.generate(explanation, max_nesting: false)` for these trees.
+Use the corresponding option when parsing the serialized explanation.
+For example, this Ruby code reads the root operation after serialization:
+
+```ruby
+explanation = JMESPath.compile("user.name").explain
+JSON.parse(JSON.generate(explanation))["root"]["operation"] #=> "subexpression"
+```
+
+This Ruby example serializes an explanation with nested groups:
+
+```ruby
+explanation = JMESPath.compile("(" * 128 + "@" + ")" * 128).explain
+serialized = JSON.generate(explanation, max_nesting: false)
+JSON.parse(serialized, max_nesting: false)["root"]["operation"] #=> "group"
+```
+
+This Ruby example inspects an overflow literal without serializing it:
+
+```ruby
+query = JMESPath.compile("`1e400`")
+query.explain[:root][:details][:value].infinite? #=> 1
+query.search(nil).infinite? #=> 1
+```
+
+## Evaluation tracing
+
+Call `Expression#trace` to evaluate once and explain null fields, filter exclusions, and omitted projection results.
+It accepts the same input forms and evaluation options as `search`, including saved defaults and per-call overrides.
+The keyword `limit:` sets a positive Integer event limit, defaulting to 1,000.
+Invalid limits raise `ArgumentError` before consuming input; positional `:limit` is not an evaluation option.
+
+This Ruby example traces a projection while retaining false values:
+
+```ruby
+query = JMESPath.compile("items[*].name")
+report = query.trace({items: [{name: "Ada"}, {}, {name: false}]})
+report[:value] #=> ["Ada", false]
+report[:events].map { |event| event[:type] } #=> ["field_null", "projection_omission"]
+report[:events].first[:context] #=> [{operation_id: 0, index: 1}]
+report[:truncated] #=> false
+```
+
+### Report and event format
+
+The frozen report has exactly three keys:
+
+| Key | Value |
+| --- | --- |
+| `:value` | The ordinary query result, including nil or false |
+| `:events` | A deeply frozen array of diagnostic events |
+| `:truncated` | True when a diagnostic event was discarded because the limit was reached |
+
+The result retains ordinary mutability and selected input object identity.
+Freezing the report does not freeze its `:value`.
+Diagnostics contain no input objects, intermediate query values, or document snapshots.
+
+Every event has exactly four keys:
+
+| Key | Value |
+| --- | --- |
+| `:type` | A string from the event table below |
+| `:operation_id` | The responsible operation's ID in `query.explain` |
+| `:context` | An ordered array of enclosing iteration frames |
+| `:details` | A hash of event-specific details |
+
+Event and detail keys are symbols; type and reason values are strings.
+
+| Type | Responsible operation | Details |
+| --- | --- | --- |
+| `field_null` | The field access returning nil | `name: String` and `reason: String` |
+| `filter_exclusion` | The filter rejecting an item | Empty hash |
+| `projection_omission` | The projection omitting a nil result | Empty hash |
+
+Field reasons are `missing`, `null`, `non_object`, and `unknown`.
+`missing` means lookup established absence under string-key and symbol-key fallback rules.
+`null` means lookup established an explicitly present nil under those rules.
+`non_object` means ordinary conversion produced no object.
+`unknown` means classification would require additional observable operations.
+Custom lookup methods and identity-based hashes receive conservative `unknown` classifications.
+Tracing adds no conversions, application callbacks, or application-observable field lookups to refine a reason.
+
+This Ruby example finds the source of an omission through its operation ID:
+
+```ruby
+query = JMESPath.compile("items[*].name")
+report = query.trace({items: [{}]})
+event = report[:events].last
+query.explain[:root][:id] == event[:operation_id] #=> true
+query.explain[:root][:source_range] #=> [0, 13]
+```
+
+Successful fields, retained values, out-of-range indexes, and unvisited branches produce no diagnostics.
+Tracing explains the three event types above; it does not explain every possible nil result.
+Field events precede any exclusion or omission they cause.
+Filters evaluate all conditions before projecting selected items.
+
+### Local item context
+
+Each context frame has exactly `:operation_id` and `:index`.
+Frames run from the outermost iteration to the innermost.
+Indexes are zero-based positions in the immediate array or object-values sequence.
+Filter projections retain original input indexes, including gaps left by rejected items.
+An exclusion or omission includes the frame of its affected item.
+Events outside iteration have an empty context.
+
+Object projections use ordinal values positions without extra key enumeration.
+Pipes, slicing, flattening, and functions can establish local sequences.
+Context does not provide object keys or paths back through transformations to the original document.
+
+Expression-reference frames identify the reference operation and its zero-based invocation count within that trace call.
+The count describes callback invocation order, not positions in a function's input.
+Synchronous reference calls retain enclosing iteration frames.
+Concurrent reference calls keep separate thread contexts; application scheduling determines event order.
+References saved by callbacks remain callable after tracing finishes, with collection closed.
+
+### Limits, errors, and isolation
+
+Tracing retains the first `limit` diagnostic events in observed evaluation order.
+Exactly `limit` events leave `:truncated` false; the next diagnostic sets it to true.
+Truncation adds no sentinel event.
+Evaluation continues normally after the limit, preserving callback counts, order, and the complete result.
+
+This Ruby example limits diagnostics without changing the result:
+
+```ruby
+query = JMESPath.compile("items[*].name")
+limited = query.trace({items: [{}, {name: false}]}, limit: 1)
+limited[:value] #=> [false]
+limited[:events].length #=> 1
+limited[:truncated] #=> true
+```
+
+The limit bounds retained diagnostics, not evaluation memory.
+The operation map uses memory proportional to query size; retained events contain copies of their enclosing frames.
+Filters retain selected original indexes until projection finishes.
+Collection avoids further event snapshots after truncation.
+
+Trace state is separate for each call, including concurrent calls and nested calls from callbacks.
+Ordinary search builds no trace collector or operation map.
+Tracing propagates original evaluation and input exceptions without attaching a report or retrying evaluation.
+Suppression retains its ordinary behavior; a suppressed nil result can produce a downstream omission.
+There is no dedicated validation-failure event, automatic logging, module-level trace method, or CLI trace flag.
+
 ## Saved options
 
 Pass `functions:` and `disable_visit_errors:` to `compile` to save defaults for repeated searches.

data/docs/guides/completion.md

@@ -0,0 +1,69 @@
+# Shell completion
+
+The gem includes Bash and Zsh completion definitions for `jmespath` and `jmespath.rb`.
+They suggest option names and filesystem paths after `--file` and `--query-file`.
+Both `--file PATH` and `--file=PATH` forms support completion, including spaces in filenames.
+
+## Bash setup
+
+Run these commands in the Bash session and Ruby environment where you use the gem:
+
+```bash
+jmespath_gem_root="$(ruby -rrubygems -e 'print Gem::Specification.find_by_name("jmespath-ruby").full_gem_path')"
+source "$jmespath_gem_root/completions/jmespath.bash"
+```
+
+The definition uses Bash built-ins and supports Bash 3.2 or later.
+It requires no completion framework.
+Unquoted `~/`, `$HOME/`, and `${HOME}/` prefixes use your home directory.
+Quoted or escaped tildes remain literal, with `./` added when necessary to preserve the selected path.
+Bash completion leaves named-user prefixes such as `~other/` unchanged.
+Completion inside a word follows Readline's insertion rules, which can repeat existing trailing text.
+Move the cursor to the word's end to avoid that behavior.
+
+## Zsh setup
+
+Add the gem's completion directory to `fpath` before initializing completion:
+
+```zsh
+jmespath_gem_root="$(ruby -rrubygems -e 'print Gem::Specification.find_by_name("jmespath-ruby").full_gem_path')"
+fpath=("$jmespath_gem_root/completions" $fpath)
+autoload -Uz compinit
+compinit
+```
+
+If completion is initialized in the session, run these commands again to register the added definition.
+The definition uses Zsh's standard completion system.
+
+## Persistent setup
+
+To enable completion in later sessions, add the relevant setup commands to your shell startup file yourself.
+For Zsh, place the `fpath` assignment before your startup file's `compinit` call.
+Installation does not edit shell configuration.
+
+When the gem is available only through Bundler, replace `ruby` in the lookup command with `bundle exec ruby`.
+Use the Ruby environment and gem version that supply your executable.
+After changing Ruby environments or gem versions, load the matching completion definition again.
+
+## Usage and boundaries
+
+Press Tab while entering an option or path.
+These examples show the key as `<Tab>`:
+
+```text
+jmespath --que<Tab>
+jmespath --query-file queries/rep<Tab>
+jmespath.rb --file=my<Tab>
+```
+
+Directories remain available for further path completion, without filtering by file extension.
+Paths containing spaces receive shell quoting, so the completed path remains one argument.
+Hyphen-leading filenames follow the CLI's literal-path rules, such as `--file=--document.json` or `--file ./--document.json`.
+
+Options remain available before or after an expression until a standalone `--` delimiter.
+Repeated or conflicting options remain visible; the CLI validates combinations when you run the command.
+Completion does not suggest JMESPath expressions or complete arguments after the delimiter.
+It lists filesystem names without running the CLI, evaluating queries, or reading document or query contents.
+Ruby runs only during the installation-path lookup shown above.
+
+Fish support and automatic installation are outside this feature.

data/docs/guides/errors.md

@@ -10,6 +10,35 @@ SyntaxError derives from that base; evaluation errors derive from RuntimeError.
 | `InvalidArityError` | Incorrect number of function arguments |
 | `InvalidValueError` | Invalid slice step or cyclic value during structural processing |
 | `UnknownFunctionError` | Function absent from the supplied registry |
+| `NullResultError` | `Expression#fetch` received a null final result |
+
+## Failure results
+
+`Expression#try_search` returns library-owned evaluation, JSON parsing, and native input I/O failures in a `JMESPath::SearchResult`.
+Its `error` reader contains the original exception; `value` is nil and `success?` is false.
+Successful null results have `success?` true and `error` nil.
+Compilation happens before this method and can still raise syntax errors.
+A valid per-call nesting limit that rejects the compiled expression produces a failure result.
+
+```ruby
+query = JMESPath.compile("length(@)")
+query.try_search(4).error.function_name #=> "length"
+query.try_search(4, disable_visit_errors: true).success? #=> true
+query.try_search(4, disable_visit_errors: true).value #=> nil
+JMESPath.compile("@").try_search(StringIO.new("invalid")).error.is_a?(JSON::ParserError) #=> true
+```
+
+Invalid options raise `ArgumentError` before reading input.
+Suppressed type and arity failures remain successful null results; unknown-function failures remain failures.
+Caller-owned streams remain open, and library-opened files close after input processing.
+Failures from native reads are captured; exceptions from application overrides of input methods propagate.
+
+Exceptions escaping custom functions, registry overrides, and application conversions propagate unchanged, including JSON and library error classes.
+This includes failures from ordinary queries called inside application code.
+Use an inner `try_search` to handle those failures explicitly, as shown in [compiled result handling](compilation.md#failure-results).
+Ordinary `search`, `call`, `fetch`, and CLI error handling retain their contracts.
+
+## Syntax diagnostics
 
 SyntaxError exposes the expression, a zero-based byte position, and one-based line and character column.
 Character columns count Unicode code points, independently of byte offsets and terminal display widths.
@@ -68,6 +97,47 @@ Only library argument-type and arity failures are suppressed by `disable_visit_e
 Syntax, unknown-function, invalid-value, adapter, and callback failures remain visible.
 Missing fields and out-of-range indices normally return nil.
 
+`Expression#fetch` raises `NullResultError` for a nil final result, including explicit null and suppressed validation failures.
+The error derives from `RuntimeError`, exposes frozen query text through `expression`, and has the message `Expression returned null`.
+It retains no input document and does not distinguish missing fields from explicit null.
+Non-nil values, including false and empty collections, succeed.
+Other evaluation and application exceptions propagate unchanged.
+See [required results](compilation.md#required-results) for executable Ruby examples.
+
+## Syntax validation
+
+Use `JMESPath.validate` in Ruby to check syntax without an input document:
+
+```ruby
+JMESPath.validate("items[*].name") #=> []
+diagnostics = JMESPath.validate("items[?active")
+failure = diagnostics.fetch(0)
+failure.reason #=> "Expected rbracket, received eof"
+failure.expression #=> "items[?active"
+failure.position #=> 13
+failure.line #=> 1
+failure.column #=> 14
+failure.location_known? #=> true
+JMESPath::Diagnostic.format(failure) #=> "Expected rbracket, received eof at line 1, column 14\nitems[?active\n             ^"
+```
+
+The result is a frozen array containing zero or one immutable `JMESPath::SyntaxDiagnostic` record.
+Parsing stops at the first syntax failure.
+Records contain frozen copies of the reason and expression, without an exception or backtrace.
+Source text and coordinates match compilation errors, including the lexer's conversion to UTF-8.
+Positions are zero-based byte offsets; lines and Unicode character columns are one-based.
+For unknown locations, `position`, `line`, and `column` are nil, and `location_known?` is false.
+Invalid encodings produce an unlocated diagnostic with an empty stored expression.
+The formatter accepts both records and syntax errors and applies the same excerpt and caret rules.
+
+Validation neither evaluates data nor invokes callbacks, checks function availability, builds execution plans, or uses the compilation cache.
+Unknown functions, incorrect argument counts, and unsupported runtime argument types remain valid syntax.
+Validation cannot establish whether a query will succeed for a function registry or input document.
+Parser failures other than `SyntaxError` propagate, including `InvalidValueError` for a zero slice step, matching compilation.
+
+The only option is `max_depth:`, an Integer from 1 through 128, defaulting to 128.
+Invalid expression types, depth values, and unsupported keywords raise `ArgumentError` before parsing.
+
 ## Function validation data
 
 Library-owned `InvalidTypeError` and `InvalidArityError` failures expose immutable metadata.
@@ -172,11 +242,138 @@ Invalid options raise ArgumentError.
 
 ## CLI diagnostics
 
-Both `jmespath` and `jmespath.rb` print expected input and query failures to stderr and exit with status 1.
+Both `jmespath` and `jmespath.rb` print expected input and query failures to stderr.
+Noninteractive queries exit with status 1 on these failures; interactive sessions recover from query failures as described below.
 Failures before output starts leave stdout empty.
-Successful queries print one JSON result to stdout.
+Successful document queries print one JSON result to stdout.
+With `--raw-output`, string results print without JSON quotes or escape encoding; other types retain compact JSON encoding.
+Raw output appends one newline while preserving every embedded and trailing newline in the string.
+An empty string produces one newline; a string ending with one newline produces two.
+Raw output preserves diagnostics, source coordinates, failure statuses, and empty stdout on failures before output starts.
+Repeated `--raw-output` options and combinations with `--pretty` produce usage failures before accessing input.
+Output is compact by default; `--pretty` selects two-space indentation with one final newline.
+Both formats emit valid JSON, including scalar results and Unicode text.
+Pretty formatting preserves all diagnostics, source coordinates, exit statuses, and empty stdout on failures before output starts.
+Repeated `--pretty` options produce usage failures.
 Usage failures print usage to stderr and exit with status 2 without reading stdin.
 Help and version requests exit with status 0 without reading stdin.
+With `--file PATH`, usage failures and informational requests do not open the document.
+Missing or unreadable document files produce escaped operating-system messages on stderr with status 1.
+File failures leave stdin unused; single-document files close after parsing, including when parsing fails.
+Query diagnostics retain their source locations when JSON comes from a file.
+
+### JSON Lines failures
+
+Use `--json-lines` to read independent records from stdin or `--file PATH`:
+
+```sh
+jmespath --json-lines 'length(@)' < records.jsonl
+jmespath --json-lines --file records.jsonl --query-file query.jmespath
+```
+
+The query compiles once before document input is accessed, including for empty input.
+A valid query with empty input returns status 0 without output; an invalid query returns status 1.
+Each physical line must contain one complete JSON value.
+Blank and whitespace-only lines fail with `Invalid JSON input`.
+LF, CRLF, and a final unterminated record are accepted.
+Results use compact JSON with one final newline per record, including null and false values.
+
+If the input contains `[]` on line 1 and `4` on line 2, the first command prints `0` before failing.
+Its stderr identifies both the input record and the query location:
+
+```text
+Input line 2:
+Invalid argument 1 for length: expected string, array, or object; received number at line 1, column 1
+length(@)
+^
+```
+
+Processing stops at the failing record with status 1, preserving earlier results and omitting the failed result.
+Check the exit status before treating stdout as complete.
+Parsing failures retain the generic message without document fragments.
+Results that cannot be encoded as JSON report `Invalid JSON result` without result fragments.
+Query excerpts and function context remain available after the input-line prefix.
+Compilation and file-open failures have no record number.
+
+The CLI reads the next line after writing the preceding result, using normal output buffering.
+Memory is proportional to the current record, its evaluation, and its serialized result, plus the compiled query.
+Owned files close after processing succeeds or fails; caller-owned streams remain open.
+Injected input needs `gets` for JSON Lines and `read` for document mode; injected output needs only `puts`.
+Repeated flags or combinations with `--pretty`, `--raw-output`, or validation fail with status 2 before input access.
+The exact two-argument invocation `--validate --json-lines` validates literal query text.
+
+### Interactive sessions
+
+Use `jmespath --interactive --file document.json` to load a document once and enter successive UTF-8 queries through stdin.
+The file closes before the session reads commands.
+Prompts appear only for terminal stdin, including when stderr is redirected.
+Help, prompts, and diagnostics use stderr; successful results use compact JSON on stdout with one final newline.
+Results and diagnostics are flushed when supported; terminal prompts always flush before input reads.
+
+Syntax failures retain query excerpts and carets; type, arity, and unknown-function failures retain their diagnostic context.
+Each failure omits its result and permits the next query.
+An invalid UTF-8 line or unknown colon command also produces a recoverable diagnostic.
+Empty lines and lines containing only spaces or tabs are ignored; LF, CRLF, and a final unterminated query are accepted.
+`:help` prints instructions, while `:quit` and EOF return status 0, including after recovered failures.
+Earlier output remains available if a later stream failure terminates the session with status 1.
+
+Missing, unreadable, or malformed documents terminate startup with status 1 before commands or prompts.
+Malformed JSON reports `Invalid JSON input` without exposing document contents.
+Input and output stream failures terminate with status 1; failed diagnostic writes are not retried.
+Missing `--file`, repeated flags, queries in arguments, and combinations with `--query-file` or other modes return usage status 2.
+Information flags must remain standalone.
+The exact two-argument form `--validate --interactive` still validates the literal query `--interactive`.
+
+Injected readers require `gets`; readers without `tty?` receive no prompts.
+Output and diagnostic streams require `puts` and may support `flush`.
+Terminal prompts additionally require `print` and `flush` on the diagnostic stream.
+Caller-owned streams remain open after success or failure.
+
+### Saved queries
+
+Select a saved UTF-8 query with `--query-file PATH` and supply the document through stdin or `--file PATH`.
+Query files retain their source text, including Unicode, line breaks, and trailing newlines.
+Syntax and function diagnostics use that text for their excerpts, coordinates, and carets.
+An empty file produces an empty-expression syntax diagnostic with status 1.
+Missing or unreadable query files produce escaped operating-system messages with status 1, leaving document input untouched.
+Query files close after reading, including read failures, before document input is accessed.
+In single-document mode, malformed JSON takes precedence over query syntax errors after the query file is read.
+Absent or conflicting query sources, repeated options, and missing values produce usage failures before opening files.
+
+To execute a saved query, run this command in a shell:
+
+```sh
+jmespath --query-file query.jmespath --file document.json
+jmespath --pretty --query-file query.jmespath --file document.json
+```
+
+To query a UTF-8 document file, run this command in a shell:
+
+```sh
+jmespath --file document.json 'length(@)'
+```
+
+Both executables also support validation without reading stdin.
+Run this command in a shell:
+
+```sh
+jmespath --validate 'items[*].name'
+jmespath --validate --query-file query.jmespath
+```
+
+Valid syntax leaves both output streams empty and exits with status 0.
+Unknown functions remain valid syntax; function availability and runtime types require evaluation.
+For invalid syntax, the command prints a formatted diagnostic to stderr and exits with status 1.
+Parser value failures, including a zero slice step, also exit with status 1.
+Missing or excess validation arguments print usage to stderr and exit with status 2.
+Every validation outcome leaves stdout empty and does not read stdin.
+In the exact two-argument form `--validate EXPRESSION`, the second argument is query text, even when it resembles a flag.
+Thus `--validate --query-file` validates the literal expression `--query-file`.
+File validation also accepts `--query-file PATH --validate` and rejects `--file`.
+Combining `--pretty` with validation produces a usage failure before opening input files or reading stdin.
+Combining `--raw-output` with validation follows the same rule.
+The exact two-argument call `--validate --pretty` validates the literal expression `--pretty`.
+Likewise, `--validate --raw-output` validates the literal expression `--raw-output`.
 
 To inspect a function type failure, run this command in a shell:
 
@@ -205,7 +402,7 @@ Missing or unusable source ranges omit coordinates, the query line, and the care
 Incomplete validation metadata retains the escaped exception message and any usable source location.
 Unknown-function diagnostics retain suggestions; invalid-value failures use message-only diagnostics.
 
-Malformed stdin JSON prints `Invalid JSON input` without parser messages or document fragments.
+Malformed JSON from stdin or a file prints `Invalid JSON input` without parser messages or document fragments.
 For example, run this command in a shell:
 
 ```sh

data/docs/guides/functions.md

@@ -45,6 +45,39 @@ JMESPath.search("sort_by(@, &age)[*].name", [{name: "Lin", age: 20}, {name: "Ada
 JMESPath.search("avg(@)", [1, 2, 3]) #=> 2.0
 ```
 
+## Command-line reference
+
+Run either executable from the shell to list built-in signatures and descriptions without reading stdin:
+
+```sh
+jmespath --functions
+jmespath.rb --functions
+```
+
+Each built-in appears once in alphabetical order, using public function metadata.
+For example, the listing includes these entries:
+
+```text
+join(string, array<string>) Join strings with a separator.
+length(string|array|object) Character or element count.
+map(expref, array) Map an expression over an array, including null results.
+merge(object...) Merge objects, with later values winning.
+sort(array<number>|array<string>) Stable sorted array of numbers or strings.
+```
+
+`A|B` accepts either type; `any` accepts any value.
+`array<T>` requires every element to have type `T`, while `array` accepts elements of any type.
+Thus `array<number>|array<string>` accepts a homogeneous array, including an empty array.
+`expref` denotes an expression reference written as `&expression`.
+The final `...` marks a required argument that repeats, so `merge(object...)` needs at least one object.
+The listing includes a notation legend and describes declared types; runtime checks can impose narrower constraints.
+Return types are not inferred.
+
+Use `--functions` alone, without queries, paths, other modes, repeated flags, or values.
+The exact two-argument form `--validate --functions` validates the literal query text under the validation rules.
+Listing returns status 0 with empty stderr; output failures return status 1.
+Usage failures return status 2 with empty stdout and usage guidance on stderr, before accessing input.
+
 ## Custom signatures
 
 Start with `Functions.default` to retain the built-ins, or `Functions.new` for an empty registry.