jmespath-ruby 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9f2db0a8d51af9e3258964210daf3aa1391f97370fca0d0e5610045aad9e012
-  data.tar.gz: ec560bc1d5607e14175267d6b1bb82329a3d126686d99393c2cd6a8e7bc62585
+  metadata.gz: 5a6f19fa8b3debba295dd502232919a608226c50d486d849ff7148f07e5eeaea
+  data.tar.gz: 3a030e207e2645fa16c1511bc70f07b779d6cb53ca05ba320f51e83de5057dcc
 SHA512:
-  metadata.gz: b8b8a4b5d663ae5b6ac54d093867c94ea420d836d44f1de5de1b781c21a984277a8211f7a6343392b335d0e451b7f3f749802e0ad910fc0af45d573fb305d2b9
-  data.tar.gz: 985c5eddf2e47265eaa74f37afd4ea73094ae84f6a87ec90ec0c0501be1af03b3c46a4d95207be57d42ec47f4b94dc2b632a1e87b5eabfa712e3ba4232753794
+  metadata.gz: 8233ac05750fb3e6e91c637d7c4416d5ff47183b6c900f2a350340bf968058d2d7ee437aff69d10cc028929bf26b843e82e1fc94399ae5c2a1844f5335f81840
+  data.tar.gz: 54fc62c2faf79343c1ccfdcc2eaaadc29634c70ab4d29ebd5d6a2a7cdd5819a49a2c4a8a75af4b0b1954431bc0ed2a159a6991c08b55c2d289cb33efea976315

data/CHANGELOG.md

@@ -5,6 +5,23 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) for t
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-11-02
+
+### Added
+
+- Add `JMESPath.validate` with immutable syntax diagnostics and configurable nesting limits.
+- Add `--validate EXPRESSION` to both executables for syntax validation without reading standard input.
+- Add `Expression#explain` with an immutable query tree, operation IDs, and source ranges.
+- Add `Expression#trace` with bounded events for null fields and omitted projection items.
+- Add `Expression#fetch` to require a non-null result and raise `NullResultError` when the result is null.
+- Add `Expression#try_search` and `SearchResult` to return library-owned failures while preserving exceptions from application callbacks and conversions.
+- Add `--file PATH` for JSON documents and `--query-file PATH` for UTF-8 query text.
+- Add `--pretty` for indented JSON and `--raw-output` for unquoted string results.
+- Add `--json-lines` to compile once and process independent JSON records incrementally.
+- Add `--functions` to list built-in function signatures and descriptions without reading input.
+- Add `--interactive --file PATH` to load one document and evaluate successive queries with recovery from query failures.
+- Package manually installed Bash and Zsh completion for options and paths through both executable names.
+
 ## [0.1.2] - 2026-11-02
 
 ### Added
@@ -45,7 +62,8 @@ Initial implementation for Ruby 3.3 and later.
 The compatibility guide documents intentional corrections and limits.
 Applications that depend on the gem name `jmespath` must change that dependency explicitly.
 
-[unreleased]: https://github.com/svyatov/jmespath-ruby/compare/v0.1.2...HEAD
+[unreleased]: https://github.com/svyatov/jmespath-ruby/compare/v0.1.3...HEAD
+[0.1.3]: https://github.com/svyatov/jmespath-ruby/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/svyatov/jmespath-ruby/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/svyatov/jmespath-ruby/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/svyatov/jmespath-ruby/releases/tag/v0.1.0

data/README.md

@@ -12,7 +12,7 @@ Search JSON and Ruby data with reusable queries and typed custom functions.
 In your Ruby project, add the gem with Bundler. Run `bundle init` first if the project has no Gemfile.
 
 ```sh
-bundle add jmespath-ruby --version "~> 0.1.2"
+bundle add jmespath-ruby --version "~> 0.1.3"
 ```
 
 Save this Ruby example as `example.rb`:
@@ -76,7 +76,7 @@ Replace that Gemfile entry:
 
 ```diff
 -gem "jmespath"
-+gem "jmespath-ruby", "~> 0.1.2"
++gem "jmespath-ruby", "~> 0.1.3"
 ```
 
 Run `bundle install`. Your Ruby code keeps the same entry points:
@@ -94,6 +94,16 @@ See [compatibility and deliberate corrections](docs/guides/compatibility.md) bef
 
 ## Search
 
+Use `Expression#fetch` when a Ruby caller requires a non-null result:
+
+```ruby
+JMESPath.compile("user.name").fetch({user: {name: "Ada"}}) #=> "Ada"
+```
+
+Null results raise `JMESPath::Errors::NullResultError`, whose `expression` attribute contains the query text.
+False, zero, and empty values succeed.
+See [required query results](docs/guides/compilation.md#required-results) for options and suppression behavior.
+
 Use `JMESPath.search` in Ruby code to evaluate a query:
 
 ```ruby
@@ -123,6 +133,25 @@ Compiled expressions are immutable and safe to share between threads.
 Each search uses separate evaluation state.
 Custom callbacks and input objects remain the caller's responsibility.
 
+In Ruby code, inspect the query without evaluating input or resolving function names:
+
+```ruby
+JMESPath.compile("user.name").explain[:root][:operation] #=> "subexpression"
+```
+
+See [query inspection](docs/guides/compilation.md#query-inspection) for the immutable tree format, operation IDs, and source ranges.
+
+In Ruby code, trace omissions during one evaluation with a bounded event limit:
+
+```ruby
+query = JMESPath.compile("items[*].name")
+report = query.trace({items: [{name: "Ada"}, {}, {name: false}]}, limit: 100)
+report[:value] #=> ["Ada", false]
+report[:events].map { |event| event[:type] } #=> ["field_null", "projection_omission"]
+```
+
+See [evaluation tracing](docs/guides/compilation.md#evaluation-tracing) for event types, local item indexes, and truncation.
+
 In Ruby code, save evaluation options when compiling a query, then use `search` or its `call` alias:
 
 ```ruby
@@ -158,6 +187,22 @@ See [registry inspection](docs/guides/functions.md#registry-inspection) for all
 
 ## Errors and diagnostics
 
+Use `Expression#try_search` in Ruby code to distinguish a successful null result from a library-owned failure:
+
+```ruby
+query = JMESPath.compile("length(@)")
+query.try_search("Ada").value #=> 3
+query.try_search(4).success? #=> false
+query.try_search(4).error.function_name #=> "length"
+JMESPath.compile("missing").try_search({}).success? #=> true
+```
+
+The frozen `JMESPath::SearchResult` exposes `success?`, `value`, and the original `error`.
+Library-owned evaluation, JSON parsing, and native input I/O failures become failure results.
+Invalid options and exceptions from application callbacks or conversions still raise.
+Compilation can raise syntax errors before `try_search` runs.
+See [failure results](docs/guides/errors.md#failure-results) for ownership and suppression rules.
+
 Format syntax failures in Ruby with `JMESPath::Diagnostic.format(error)` to get source coordinates, a query excerpt, and a caret.
 Function type and arity errors expose immutable validation data, including the function name, signature, argument counts or types, and available source ranges.
 Unknown-function errors expose the missing name and up to three suggestions from the active registry.
@@ -165,18 +210,146 @@ See [errors and diagnostics](docs/guides/errors.md) for examples, nullable field
 
 ## Command line
 
-Both `jmespath` and `jmespath.rb` accept an expression and a JSON document on standard input.
+Both `jmespath` and `jmespath.rb` accept an expression and a JSON document from stdin or `--file PATH`.
+Use `--query-file PATH` to read the expression from a UTF-8 file.
+See [shell completion](docs/guides/completion.md) for manual Bash and Zsh setup for both executable names.
 
 ```sh
 printf '%s\n' '{"user":{"name":"Ada"}}' | jmespath 'user.name'
+jmespath --file document.json 'user.name'
+jmespath 'user.name' --file document.json
+jmespath --file 'my document.json' 'user.name'
+jmespath --file=--document.json 'user.name'
+jmespath --file ./--document.json 'user.name'
+jmespath --file - 'user.name'
+jmespath --file document.json -- 'user.name'
+jmespath --query-file query.jmespath < document.json
+jmespath --query-file query.jmespath --file document.json
+jmespath --pretty 'items' < document.json
+jmespath --raw-output 'user.name' < document.json
+```
+
+Document files are read as UTF-8 and closed after parsing, before query evaluation in single-document mode.
+File input leaves stdin unused; omitting `--file` selects stdin.
+Paths are literal: `--file -` reads a file named `-`.
+Quote filenames with spaces; use the equals form or `./` prefix for option-like filenames.
+Options can precede or follow the expression; `--` ends option parsing.
+Supply exactly one query source: a positional expression or `--query-file PATH`.
+Repeated file options, unknown options, missing values, and conflicting or absent query sources are usage failures.
+Help and version flags must appear alone.
+
+List built-in functions from the shell without reading stdin:
+
+```sh
+jmespath --functions
 ```
 
-The result goes to standard output as JSON.
+Each line shows a name, accepted argument types, and the description from public function metadata.
+The listing is alphabetical and ends with a notation legend.
+Unions use `|`, homogeneous arrays use `array<T>`, and expression references use `expref`.
+A final `...` means the last argument repeats and remains required.
+Runtime checks can be narrower than the declared types.
+See [the function listing](docs/guides/functions.md#command-line-reference) for examples.
+
+Use `--functions` alone; queries, paths, other modes, repeated flags, and values are usage failures.
+The two-argument form `--validate --functions` retains literal query validation.
+Listing exits with status 0 on success, 1 for output failures, or 2 for usage failures.
+Usage failures leave stdout empty and print usage guidance on stderr.
+
+Query files retain all source text, including trailing newlines and Unicode diagnostic coordinates.
+An empty query file produces a syntax failure.
+Query files close after reading, before document input is accessed.
+Missing or unreadable query files leave document input untouched.
+In single-document mode, execution parses JSON before compiling the expression.
+Query paths follow the document path rules: `--query-file -` reads a literal file named `-`.
+
+The result goes to standard output as compact JSON followed by a newline.
+Use `--pretty` for JSON with two-space indentation and one final newline.
+Both formats support objects, arrays, strings, numbers, booleans, and null, with Unicode preserved.
+Pretty output works with positional or file queries and either document source.
+Repeated `--pretty` options are usage failures.
+Pretty formatting preserves stderr diagnostics, source coordinates, and exit statuses; failures before output starts leave stdout empty.
+Use `--raw-output` to print string results without JSON quotes or escape encoding.
+Other result types retain compact JSON encoding.
+Raw output appends one newline and preserves every embedded and trailing newline in the result.
+An empty string produces one newline; a string ending with one newline produces two.
+Repeated `--raw-output` options and combinations with `--pretty` are usage failures.
+Raw output preserves stderr diagnostics, source coordinates, and exit statuses; failures before output starts leave stdout empty.
 Syntax, function type, and arity failures include source coordinates, a query excerpt, and a caret when available.
 Unknown functions suggest similar registered names.
 Malformed JSON input reports `Invalid JSON input` without including document fragments.
 These failures go to standard error and exit with status 1.
 Usage failures exit with status 2; `--help` and `--version` exit with status 0 without reading input.
+
+Process independent JSON records with these shell commands:
+
+```sh
+jmespath --json-lines 'user.name' < events.jsonl
+jmespath --json-lines --file events.jsonl --query-file query.jmespath
+```
+
+JSON Lines mode compiles the query once before opening document input or reading stdin.
+Each physical line must contain one complete JSON value; blank and whitespace-only lines fail.
+LF, CRLF, and a final record without a newline are accepted.
+Each result is compact JSON followed by a newline, including `null` and `false`.
+Empty input succeeds without output when the query is valid; an invalid query still fails.
+
+Processing stops at the first failure with status 1 and an `Input line N:` diagnostic prefix.
+Earlier results remain on stdout; check the exit status before treating output as complete.
+Query compilation and file-open errors have no input line prefix.
+Memory is proportional to the current record, its evaluation, and its serialized result, plus the compiled query.
+Output uses normal buffering.
+Owned files close after processing; caller-owned streams remain open.
+Injected `CLI.run` input needs `gets` for JSON Lines or `read` for document mode; output needs only `puts`.
+Repeated `--json-lines` flags and combinations with `--pretty`, `--raw-output`, or validation are usage failures.
+
+Start a session against one loaded document:
+
+```sh
+jmespath --interactive --file document.json
+```
+
+Enter one UTF-8 query per line; empty lines and lines containing only spaces or tabs are ignored.
+Use `:help` for session instructions and `:quit` to finish, or end input with EOF.
+Queries accept LF, CRLF, and a final line without a newline.
+Each successful query prints compact JSON and a final newline to stdout, then flushes when the stream supports it.
+Prompts appear only when stdin is a terminal; prompts, help, and diagnostics use stderr.
+The document loads once and its file closes before the first prompt or command read.
+
+Queries can also come from a pipe without prompts:
+
+```sh
+printf 'user.name\nlength(user.name)\n' | jmespath --interactive --file document.json
+```
+
+Query errors, unknown commands, and invalid UTF-8 query lines produce diagnostics and allow the session to continue.
+Failed queries produce no JSON result; successful results remain available.
+EOF and `:quit` return status 0 even after query failures.
+Document and stream failures terminate with status 1; usage failures return status 2.
+Interactive mode requires `--file PATH` and rejects positional queries, `--query-file`, other modes, information flags, and repeated flags.
+Readers supplied to `CLI.run` need `gets`; `tty?` is optional and absent detection means no prompts.
+Writers need `puts`; `flush` is optional except for terminal prompts, whose diagnostic stream needs both `print` and `flush`.
+Caller-owned streams remain open; history, completion, multiline editing, and document reloads are unavailable.
+
+Validate syntax without providing a JSON document by running this shell command:
+
+```sh
+jmespath --validate 'items[*].name'
+jmespath --validate --query-file query.jmespath
+jmespath --query-file query.jmespath --validate
+```
+
+Both executables support `--validate EXPRESSION` without reading standard input.
+File validation also leaves stdin untouched and rejects document options such as `--file`.
+Combining `--pretty` with validation is a usage failure, rejected before opening input files or reading stdin.
+Combining `--raw-output` with validation follows the same rule.
+The exact two-argument form `--validate EXPRESSION` always treats the second argument as query text, including flag-like text.
+Thus `jmespath --validate --pretty` validates the literal expression `--pretty`.
+Likewise, `jmespath --validate --raw-output` validates the literal expression `--raw-output`.
+Valid syntax produces no output and exits with status 0.
+Query failures print a diagnostic to standard error and exit with status 1; incorrect usage exits with status 2.
+Validation does not check function availability or runtime argument types.
+The Ruby interface is `JMESPath.validate(expression, max_depth: 128)`.
 See [CLI diagnostics](docs/guides/errors.md#cli-diagnostics) for examples and fallback behavior.
 
 ## Guides

data/completions/_jmespath

@@ -0,0 +1,50 @@
+#compdef jmespath jmespath.rb
+local index expecting_path=0 literal_path=0 value raw option candidate suffix
+local -a paths
+for ((index = 2; index < CURRENT; index++)); do
+  if ((expecting_path)); then expecting_path=0; continue; fi
+  case ${(Q)words[index]} in
+    --file|--query-file) expecting_path=1 ;;
+    --) return ;;
+  esac
+done
+option=${(Q)${PREFIX%%=*}}
+if ((expecting_path)); then
+  if [[ $compstate[quoting] == dollars ]]; then
+    raw=$words[CURRENT]
+    value=${(Q)raw}
+    [[ $value == "$raw" ]] && value=${(Q)${:-"$raw'"}}
+    literal_path=1
+  else
+    _files
+  fi
+elif [[ $option == --file || $option == --query-file ]]; then
+  compset -P "${PREFIX%%=*}="
+  raw=${words[CURRENT]#*=}
+  if [[ $raw == \$\'* ]]; then
+    value=${(Q)raw}
+    [[ $value == "$raw" ]] && value=${(Q)${:-"$raw'"}}
+    literal_path=1
+  elif [[ $PREFIX == *\$\'* || $raw == \'* || $raw == '"~'* || $raw == '\~'* ]]; then
+    value=${(Q)PREFIX}
+    literal_path=1
+  elif [[ $compstate[quoting] == single || $compstate[quoting] == double ]]; then
+    _files -S ''
+  else
+    _files
+  fi
+elif [[ $PREFIX == -* ]]; then
+  compadd -- -h --help --version --functions --file --query-file \
+    --validate --pretty --raw-output --json-lines --interactive
+fi
+
+if ((literal_path)); then
+  paths=( "$value"*(NM) )
+  for candidate in "${paths[@]}"; do
+    suffix=
+    if [[ $compstate[quoting] == dollars && -z $QISUFFIX && ! -d $candidate ]]; then
+      suffix="'"
+    fi
+    compadd -U -i "$IPREFIX" -S "$suffix" -f -- "$candidate"
+  done
+fi

data/completions/jmespath.bash

@@ -0,0 +1,178 @@
+# Bash 3.2 completion for both executable names. Source this file to register it.
+# Rejoin Readline word-break fragments only when they are adjacent in the input.
+_jmespath_completion_words() {
+  local remaining=${COMP_LINE:0:COMP_POINT} piece joined= index
+  for ((index = COMP_CWORD; index >= 0; index--)); do
+    piece=${COMP_WORDS[index]}
+    if ((index == COMP_CWORD)); then
+      while [[ $remaining != *"$piece" ]]; do piece=${piece%?}; done
+    fi
+    joined=$piece$joined
+    remaining=${remaining%"$piece"}
+    if ((index == 0)) || [[ $remaining == *[[:space:]] ]]; then
+      words=("$joined" "${words[@]}")
+      joined=
+      while [[ $remaining == *[[:space:]] ]]; do
+        remaining=${remaining%?}
+      done
+    fi
+  done
+}
+
+# Decode quoting and HOME references without evaluating filename text.
+_jmespath_completion_unquote() {
+  local text=$1 character next quote= escape decoded digits skip_ansi=0
+  REPLY=
+  while [[ -n $text ]]; do
+    character=${text:0:1}
+    text=${text:1}
+    if [[ $quote == ansi ]]; then
+      if [[ $character == "'" ]]; then
+        quote=
+      elif [[ $character == \\ ]]; then
+        next=${text:0:1}
+        text=${text:1}
+        ((skip_ansi)) && continue
+        escape=\\$next
+        case $next in
+          [0-7])
+            digits=$next
+            while ((${#digits} < 3)) && [[ $text == [0-7]* ]]; do
+              digits+=${text:0:1}; text=${text:1}
+            done
+            escape=\\0$digits ;;
+          x)
+            digits=
+            while ((${#digits} < 2)) && [[ $text == [[:xdigit:]]* ]]; do
+              digits+=${text:0:1}; text=${text:1}
+            done
+            if [[ -z $digits ]]; then REPLY+='\x'; continue; fi
+            escape=\\x$digits ;;
+          c)
+            next=${text:0:1}; text=${text:1}
+            printf -v digits '%d' "'$next"
+            printf -v escape '\\%03o' "$((digits & 31))" ;;
+          "'"|'"'|'?') escape=$next ;;
+        esac
+        printf -v decoded '%b' "$escape"
+        REPLY+=$decoded
+        [[ -z $decoded ]] && skip_ansi=1
+      elif ((!skip_ansi)); then
+        REPLY+=$character
+      fi
+    elif [[ $quote == "'" ]]; then
+      if [[ $character == "'" ]]; then quote=; else REPLY+=$character; fi
+    elif [[ $character == \\ ]]; then
+      next=${text:0:1}
+      if [[ $quote == '"' && $next != [\$\`\"\\] && $next != $'\n' ]]; then
+        REPLY+=$character
+      else
+        text=${text:1}
+        [[ $next != $'\n' ]] && REPLY+=$next
+      fi
+    elif [[ $character == '$' && -z $quote && $text == "'"* ]]; then
+      quote=ansi
+      skip_ansi=0
+      text=${text:1}
+    elif [[ $character == '$' && ( $text == HOME || $text == HOME[/\"]* ) ]]; then
+      REPLY+=$HOME
+      text=${text#HOME}
+    elif [[ $character == '$' && $text == '{HOME}'* ]]; then
+      REPLY+=$HOME
+      text=${text#'{HOME}'}
+    elif [[ $character == "'" || $character == '"' ]]; then
+      if [[ $quote == "$character" ]]; then
+        quote=
+      elif [[ -z $quote ]]; then
+        quote=$character
+      else
+        REPLY+=$character
+      fi
+    else
+      REPLY+=$character
+    fi
+  done
+  unclosed_quote=$quote
+}
+
+_jmespath_completion() {
+  local -a words=()
+  local current word candidate prefix REPLY unclosed_quote raw_path option=
+  local index expecting_path=0 expand_home=0
+  _jmespath_completion_words
+  current=${words[${#words[@]}-1]}
+  COMPREPLY=()
+
+  for ((index = 1; index < ${#words[@]} - 1; index++)); do
+    _jmespath_completion_unquote "${words[index]}"
+    word=$REPLY
+    if ((expecting_path)); then
+      expecting_path=0
+      continue
+    fi
+    case $word in
+      --file|--query-file) expecting_path=1 ;;
+      --) return ;;
+    esac
+  done
+
+  raw_path=$current
+  if ((!expecting_path)); then
+    if [[ $current == *=* ]]; then
+      _jmespath_completion_unquote "${current%%=*}"
+      case $REPLY in
+        --file|--query-file)
+          expecting_path=1
+          option=$REPLY=
+          raw_path=${current#*=}
+          [[ -n $unclosed_quote ]] && raw_path= ;;
+      esac
+    fi
+  fi
+
+  if ((expecting_path)); then
+    case $raw_path in
+      '~'|'~/'*) expand_home=1 ;;
+      '~'*) return ;;
+    esac
+    # Readline replaces only the suffix after its last unquoted word break.
+    _jmespath_completion_unquote "${current%"${2-}"}"
+    prefix=$REPLY
+    _jmespath_completion_unquote "$current"
+    current=$REPLY
+    if [[ -n $option ]]; then
+      current=${current#"$option"}
+      if [[ $prefix == "$option"* ]]; then
+        prefix=${prefix#"$option"}
+        option=
+      fi
+    fi
+    if ((expand_home)); then
+      current=$HOME${current#\~}
+      [[ $prefix == '~'* ]] && prefix=$HOME${prefix#\~}
+    elif [[ $current == '~'* ]]; then
+      # A quoted or escaped tilde must stay literal when Readline rewrites it.
+      current=./$current
+      [[ -n $prefix ]] && prefix=./$prefix
+    fi
+    while IFS= read -r -d '' candidate; do
+      COMPREPLY[${#COMPREPLY[@]}]=$option${candidate#"$prefix"}
+    done < <(
+      shopt -s nullglob
+      shopt -u failglob
+      for candidate in "$current"*; do printf '%s\0' "$candidate"; done
+    )
+    # Enable Readline filename quoting only for paths, including on Bash 3.2.
+    if type compopt >/dev/null 2>&1; then
+      compopt -o filenames
+    else
+      compgen -f -- "$current" >/dev/null || :
+    fi
+  elif [[ $current == -* ]]; then
+    while IFS= read -r candidate; do
+      COMPREPLY[${#COMPREPLY[@]}]=$candidate
+    done < <(compgen -W '-h --help --version --functions --file --query-file --validate --pretty --raw-output --json-lines --interactive' -- "$current")
+  fi
+}
+
+complete -F _jmespath_completion jmespath jmespath.rb