jmespath-ruby 0.1.2 → 0.1.3

data/docs/guides/search.md

@@ -54,3 +54,26 @@ JMESPath.search("{name: user.name, missing: absent}", {user: {name: "Ada"}}) #=>
 An omitted negative-slice stop differs from an explicit `-1`.
 A zero slice step raises InvalidValueError.
 Multiselects construct new arrays or hashes and retain explicit nil values.
+
+## Search results
+
+Use `Expression#try_search` when an integration needs to display library-owned failures without rescuing exceptions.
+The frozen `JMESPath::SearchResult` exposes `success?`, `value`, and `error`.
+Successful null and false remain successful values:
+
+```ruby
+query = JMESPath.compile("name")
+query.try_search({}).success? #=> true
+query.try_search({}).value #=> nil
+query.try_search({name: false}).value #=> false
+query.try_search({name: false}).error #=> nil
+failure = JMESPath.compile("length(name)").try_search({name: nil})
+failure.success? #=> false
+failure.value #=> nil
+failure.error.is_a?(JMESPath::Errors::InvalidTypeError) #=> true
+```
+
+The container retains selected value identity without copying or freezing the value.
+Failures retain the original exception, metadata, and backtrace without freezing the exception.
+Each call evaluates once, with the same inputs and evaluation options as `search`.
+See [failure ownership](errors.md#failure-results) and [compiled result handling](compilation.md#failure-results).

data/lib/jmespath/ast.rb

@@ -7,12 +7,13 @@ module JMESPath
     class Node
       attr_reader :kind, :value, :children, :start, :finish, :depth
 
-      def initialize(kind:, value: nil, children: [], start: 0, finish: 0)
+      def initialize(kind:, value: nil, children: [], start: 0, finish: 0, synthetic: false) # rubocop:disable Metrics/ParameterLists
         @kind = kind
         @value = self.class.immutable(value)
         @children = children.freeze
         @start = start
         @finish = finish
+        @synthetic = synthetic
         @depth = if kind == :literal
                    self.class.literal_depth(value)
                  else
@@ -21,6 +22,10 @@ module JMESPath
         freeze
       end
 
+      def synthetic?
+        @synthetic
+      end
+
       def self.literal_depth(value)
         values = case value
                  when Array then value

data/lib/jmespath/cli/argument_parser.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module JMESPath
+  module CLI
+    # Avoid require_exact, which breaks equals values and delimiters on Ruby 3.3.
+    # @api private
+    class ArgumentParser < OptionParser
+      def permute(argv)
+        index = 0
+        while (argument = argv[index])
+          break if argument == "--"
+          raise InvalidOption, argument if argument.match?(/\A--(?:raw_output|json_lines)(?:=|\z)/)
+
+          index += %w[--file --query-file --query_file].include?(argument) ? 2 : 1
+        end
+        super
+      end
+
+      private
+
+      def complete(kind, name, *)
+        switch = search(kind, name)
+        raise InvalidOption, name unless switch
+
+        [switch, name]
+      end
+    end
+  end
+end

data/lib/jmespath/cli/arguments.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "argument_parser"
+
+module JMESPath
+  # Executes queries, validates syntax, or lists built-in functions.
+  module CLI
+    # @api private
+    def self.literal_validation?(argv)
+      argv.first == "--validate" && argv.length == 2
+    end
+
+    # @api private
+    def self.parse_arguments(argv)
+      if argv.one? && !argv.fetch(0).start_with?("-")
+        return [argv.fetch(0), nil, nil, false, false, false, false, false]
+      end
+
+      paths = {} # : Hash[String, String]
+      arguments = argument_parser(paths).permute(argv)
+      check_sources(arguments, paths)
+
+      [arguments.first, paths["file"], paths["query-file"], paths.key?("validate"), paths.key?("pretty"),
+       paths.key?("raw-output"), paths.key?("json-lines"), paths.key?("interactive")]
+    end
+
+    # @api private
+    def self.check_sources(arguments, paths)
+      if paths.key?("interactive")
+        check_interactive(arguments, paths)
+        return check_modes(paths)
+      end
+
+      sources = arguments.length + (paths.key?("query-file") ? 1 : 0)
+      raise OptionParser::InvalidArgument, "expected one query source" unless sources == 1
+
+      check_modes(paths)
+    end
+
+    # @api private
+    def self.check_modes(paths)
+      modes = paths.keys & %w[validate pretty raw-output json-lines interactive]
+      raise OptionParser::InvalidArgument, "conflicting modes" if modes.length > 1
+      return unless paths.key?("validate")
+      return if paths.key?("query-file") && !paths.key?("file")
+
+      raise OptionParser::InvalidArgument, "validation requires a query file"
+    end
+
+    # @api private
+    def self.check_interactive(arguments, paths)
+      return if arguments.empty? && paths.key?("file") && !paths.key?("query-file")
+
+      raise OptionParser::InvalidArgument, "interactive mode requires only a document file"
+    end
+
+    # @api private
+    def self.argument_parser(paths)
+      ArgumentParser.new do |options|
+        options.on("-h", "--help", "--version", "--functions", "--*-completion-bash", "--*-completion-zsh") do
+          raise OptionParser::InvalidOption, "unsupported option combination"
+        end
+        %w[file query-file].each do |name|
+          options.on("--#{name} PATH") do |value|
+            raise OptionParser::InvalidOption, "--#{name} repeated" if paths.key?(name)
+
+            paths[name] = value
+          end
+        end
+        %w[validate pretty raw-output json-lines interactive].each do |name|
+          options.on("--#{name}") do
+            raise OptionParser::InvalidOption, "--#{name} repeated" if paths.key?(name)
+
+            paths[name] = ""
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jmespath/cli/failure_diagnostic.rb

@@ -21,6 +21,7 @@ module JMESPath
 
         def message(error)
           return "Invalid JSON input" if error.is_a?(JSON::ParserError)
+          return "Invalid JSON result" if error.is_a?(JSON::GeneratorError)
 
           details = case error
                     when Errors::InvalidTypeError then type_message(error)

data/lib/jmespath/cli/function_listing.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module JMESPath
+  module CLI
+    # @api private
+    module FunctionListing
+      LEGEND = "Types: any accepts any value; A|B accepts either type.\n" \
+               "array<T> requires every element to have type T; array is unrestricted.\n" \
+               "expref is an expression reference, written &expression.\n" \
+               "T... requires one or more arguments of type T.\n" \
+               "Signatures describe declared argument types; runtime checks can be narrower.\n"
+
+      def self.render(registry)
+        entries = registry.names.map do |name|
+          metadata = registry.metadata(name) or raise "Missing function metadata: #{name}"
+          "#{name}(#{signature(metadata)}) #{metadata.description}\n"
+        end
+        "#{entries.join}\n#{LEGEND}"
+      end
+
+      class << self
+        private
+
+        def signature(metadata)
+          metadata.signature.each_with_index.map do |types, index|
+            argument(types, metadata.variadic? && index == metadata.signature.length - 1)
+          end.join(", ")
+        end
+
+        def argument(types, repeated)
+          text = types.map { |type| type_name(type) }.join("|")
+          return text unless repeated
+
+          text = "(#{text})" if types.length > 1
+          "#{text}..."
+        end
+
+        def type_name(type)
+          case type
+          when :array_number then "array<number>"
+          when :array_string then "array<string>"
+          else type.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jmespath/cli/help.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module JMESPath
+  module CLI
+    USAGE = "Usage: jmespath [--pretty | --raw-output | --json-lines] [--file PATH] " \
+            "(EXPRESSION | --query-file PATH)\n       " \
+            "jmespath --validate (EXPRESSION | --query-file PATH)\n       jmespath --functions\n       " \
+            "jmespath --interactive --file PATH"
+    HELP = "#{USAGE}\n" \
+           "Read one UTF-8 JSON document from --file PATH, or stdin when omitted.\n" \
+           "Supply one query as EXPRESSION or --query-file PATH, read as UTF-8 without trimming.\n" \
+           "Options may precede or follow EXPRESSION; -- ends option parsing.\n" \
+           "Quote spaces: --file 'my document.json'. Use --file=--document.json for option-like names.\n" \
+           "Paths are literal: --file - reads the file named -.\n" \
+           "Query paths follow the same rules: --query-file - reads the query file named -.\n" \
+           "Output is compact JSON by default; --pretty uses two-space indentation and a final newline.\n" \
+           "Use --raw-output for literal string results; other results remain compact JSON.\n" \
+           "Raw strings retain all their newlines and receive one additional output newline.\n" \
+           "Output flags cannot be repeated or combined with each other or --validate.\n" \
+           "Use --json-lines for one JSON record per physical input line and one compact result per record.\n" \
+           "JSON Lines compiles once before input; empty input succeeds with a valid query.\n" \
+           "Blank records are invalid; failures report the input line, retain earlier output, and exit 1.\n" \
+           "Memory follows the current record and result; output uses normal buffering.\n" \
+           "The --json-lines flag cannot be repeated or combined with --pretty, --raw-output, or --validate.\n" \
+           "Function arguments and expression-reference results are validated; failures exit with status 1.\n" \
+           "Unknown functions suggest similar registered names.\n" \
+           "Query failures include source locations when available.\n" \
+           "Use --interactive --file PATH for successive queries against one loaded document.\n" \
+           "Enter one query per line; blank lines are ignored. :help shows help; :quit or EOF exits successfully.\n" \
+           "Query errors are reported and the session continues; startup or stream failures exit 1.\n" \
+           "Results are compact JSON on stdout; prompts and diagnostics use stderr.\n" \
+           "Prompts appear only when stdin is a terminal; results are flushed after each query.\n" \
+           "Interactive mode requires --file and rejects query sources, other modes, and information flags.\n" \
+           "Use --validate to check syntax only, without reading stdin; unknown functions remain valid.\n" \
+           "Validate saved queries with --validate --query-file PATH; --file is unavailable during validation.\n" \
+           "The two-argument form --validate EXPRESSION always treats EXPRESSION as query text.\n" \
+           "Validation exits with status 0 for valid syntax, 1 for query failures, and 2 for usage failures.\n" \
+           "Use standalone --functions to list built-in signatures and descriptions without reading stdin.\n" \
+           "The --functions flag cannot be repeated or combined with queries, paths, modes, or information flags.\n" \
+           "Listing exits with status 0 on success, 1 for output failures, and 2 for usage failures.\n" \
+           "Manual Bash and Zsh completion: docs/guides/completion.md.\n#{FunctionListing::LEGEND}".freeze
+  end
+end

data/lib/jmespath/cli/interactive_session.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module JMESPath
+  module CLI
+    # @api private
+    class InteractiveSession
+      HELP = "Enter one query per line; blank lines are ignored.\n:help shows help; :quit ends the session."
+
+      def initialize(data, input:, output:, errors:)
+        @data = data
+        @input = input
+        @output = output
+        @errors = errors
+        @writing_errors = false
+      end
+
+      def run
+        loop do
+          prompt
+          line = @input.gets
+          break unless line
+          break if process?(line)
+        end
+        0
+      rescue IOError, SystemCallError => e
+        report_stream_failure(e)
+        1
+      end
+
+      private
+
+      def process?(line)
+        expression = line.dup.force_encoding(Encoding::UTF_8)
+        unless expression.valid_encoding?
+          diagnostic("Invalid UTF-8 query")
+          return false
+        end
+        expression = expression.sub(/\r?\n\z/, "")
+        command = expression.gsub(/\A[ \t]+|[ \t]+\z/, "")
+        command?(command, expression)
+      end
+
+      def command?(command, expression)
+        return true if command == ":quit"
+        return false if command.empty?
+
+        if command == ":help"
+          diagnostic(HELP)
+        elsif command.start_with?(":")
+          diagnostic(FailureDiagnostic.format(Errors::Error.new("Unknown command: #{command}"), nil))
+        else
+          result = evaluate(expression)
+          write_result(result) if result
+        end
+        false
+      end
+
+      def evaluate(expression)
+        JSON.generate(JMESPath.search(expression, @data))
+      rescue JSON::NestingError
+        diagnostic("Invalid JSON result")
+        nil
+      rescue Errors::Error, JSON::GeneratorError => e
+        diagnostic(FailureDiagnostic.format(e, expression))
+        nil
+      end
+
+      def write_result(result)
+        @output.puts(result)
+        flush(@output)
+      end
+
+      def diagnostic(text)
+        @writing_errors = true
+        @errors.puts(text)
+        flush(@errors)
+        @writing_errors = false
+      end
+
+      def prompt
+        # @type var input: Object & _TerminalReader
+        input = @input
+        return unless input.respond_to?(:tty?) && input.tty?
+
+        @writing_errors = true
+        # @type var errors: _PromptWriter
+        errors = @errors
+        errors.print("jmespath> ")
+        errors.flush
+        @writing_errors = false
+      end
+
+      def flush(stream)
+        # @type var output: Object & _Flushable
+        output = stream
+        output.flush if output.respond_to?(:flush)
+      end
+
+      def report_stream_failure(error)
+        diagnostic(FailureDiagnostic.format(error, nil)) unless @writing_errors
+      rescue IOError, SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/jmespath/cli.rb

@@ -2,38 +2,134 @@
 
 require_relative "../jmespath"
 require_relative "cli/failure_diagnostic"
+require_relative "cli/arguments"
+require_relative "cli/function_listing"
+require_relative "cli/interactive_session"
+require_relative "cli/help"
 
 module JMESPath
-  # Runs one JMESPath query against a JSON document from standard input.
+  # Executes queries, validates syntax, or lists built-in functions.
   module CLI
-    USAGE = "Usage: jmespath EXPRESSION < document.json"
-    HELP = "#{USAGE}\n" \
-           "Function arguments and expression-reference results are validated; failures exit with status 1.\n" \
-           "Unknown functions suggest similar registered names.\n" \
-           "Query failures include source locations when available.".freeze
-
     # @param argv [Array<String>] command-line arguments
-    # @param stdin [IO, StringIO] source JSON stream
+    # @param stdin [IO, StringIO] read for documents, gets for JSON Lines or interactive queries; optional tty?
     # @param stdout [IO, StringIO] result stream
     # @param stderr [IO, StringIO] diagnostic stream
     # @return [Integer] zero on success, one on input failure, two on usage failure
     def self.run(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr)
-      return information(argv, stdout) if [%w[--help], %w[-h], %w[--version]].include?(argv)
+      return validation(argv, stderr) if literal_validation?(argv)
+      return information(argv, stdout) if [%w[--help], %w[-h], %w[--version], %w[--functions]].include?(argv)
+
+      query(argv, stdin, stdout, stderr)
+    rescue OptionParser::ParseError
+      stderr.puts(USAGE)
+      2
+    rescue JSON::ParserError, Errors::Error, IOError, SystemCallError => e
+      failure(e, nil, stderr)
+    end
+
+    # @api private
+    def self.query(argv, stdin, stdout, stderr)
+      expression, path, query_path, validate, pretty, raw_output, json_lines, interactive = parse_arguments(argv)
+      return interactive_session(path, stdin, stdout, stderr) if interactive
 
-      unless argv.length == 1
-        stderr.puts(USAGE)
-        return 2
+      expression = read_query(expression, query_path)
+      return validation(["--validate", expression], stderr) if validate
+      if json_lines
+        # @type var stdin: _LineReader
+        return execute_lines(expression, path, stdin, stdout, stderr)
       end
-      data = JSON.parse(stdin.read.to_s)
-      stdout.puts(JSON.generate(JMESPath.search(argv.fetch(0), data)))
+
+      # @type var stdin: _Reader
+      execute(expression, read_document(path, stdin), stdout, pretty, raw_output)
+    rescue JSON::ParserError, Errors::Error => e
+      failure(e, expression, stderr)
+    end
+
+    # @api private
+    def self.failure(error, expression, errors)
+      errors.puts(FailureDiagnostic.format(error, expression))
+      1
+    rescue IOError, SystemCallError
+      1
+    end
+
+    # @api private
+    def self.interactive_session(path, input, output, errors)
+      # @type var input: _Reader & _LineReader
+      data = read_document(path, input)
+      InteractiveSession.new(data, input: input, output: output, errors: errors).run
+    end
+
+    # @api private
+    def self.read_query(expression, path)
+      return expression || "" unless path
+
+      File.open(path, "rb:UTF-8:-", &:read)
+    end
+
+    # @api private
+    def self.read_document(path, stdin)
+      return JSON.parse(stdin.read.to_s) unless path
+
+      File.open(path, "r:UTF-8") { |file| JSON.parse(file.read) }
+    end
+
+    # @api private
+    def self.execute(expression, data, stdout, pretty, raw_output)
+      result = JMESPath.search(expression, data)
+      output = if raw_output && result.is_a?(String)
+                 "#{result}\n"
+               else
+                 pretty ? JSON.pretty_generate(result) : JSON.generate(result)
+               end
+      stdout.puts(output)
       0
-    rescue JSON::ParserError, Errors::Error, IOError, SystemCallError => e
-      stderr.puts(FailureDiagnostic.format(e, argv.first))
+    end
+
+    # @api private
+    def self.execute_lines(expression, path, stdin, stdout, stderr)
+      compiled = JMESPath.compile(expression)
+      return process_lines(compiled, expression, stdin, stdout, stderr) unless path
+
+      File.open(path, "r:UTF-8") { |file| process_lines(compiled, expression, file, stdout, stderr) }
+    end
+
+    # @api private
+    def self.process_lines(compiled, expression, input, output, errors)
+      line_number = 0
+      loop do
+        line_number += 1
+        line = input.gets
+        break unless line
+
+        line = line.dup.force_encoding(Encoding::UTF_8)
+        raise JSON::ParserError, "Invalid UTF-8 input" unless line.valid_encoding?
+
+        output.puts(JSON.generate(compiled.search(JSON.parse(line))))
+      end
+      0
+    rescue JSON::ParserError, JSON::GeneratorError, Errors::Error, IOError, SystemCallError => e
+      errors.puts("Input line #{line_number}:")
+      errors.puts(FailureDiagnostic.format(e, expression))
+      1
+    end
+
+    # @api private
+    def self.validation(argv, errors)
+      diagnostic = JMESPath.validate(argv.fetch(1)).first
+      return 0 unless diagnostic
+
+      errors.puts(Diagnostic.format(diagnostic))
       1
     end
 
     # @api private
     def self.information(argv, output)
+      if argv == ["--functions"]
+        output.puts(FunctionListing.render(Functions.default))
+        return 0
+      end
+
       output.puts(argv == ["--version"] ? "jmespath-ruby #{VERSION}" : HELP)
       0
     end

data/lib/jmespath/data_access.rb

@@ -9,13 +9,15 @@ module JMESPath
         mapping = value.is_a?(Hash) ? value : DataAccess.object(value)
         return nil unless mapping
 
-        result = mapping[name]
-        return result unless result.nil?
-
-        mapping.each_key do |key|
-          return mapping[key] if key.is_a?(Symbol) && key.name == name
+        FailureCapture.application do
+          result = mapping[name]
+          return result unless result.nil?
+
+          mapping.each_key do |key|
+            return mapping[key] if key.is_a?(Symbol) && key.name == name
+          end
+          nil
         end
-        nil
       end
     end
 
@@ -41,7 +43,7 @@ module JMESPath
       end
 
       def object(value)
-        return value.to_h if value.is_a?(Struct)
+        return FailureCapture.application { value.to_h } if value.is_a?(Struct)
 
         convert(value, Hash, :to_hash)
       end
@@ -54,9 +56,10 @@ module JMESPath
 
       def convert(value, type, method)
         return value if value.is_a?(type)
-        return nil unless value.respond_to?(method)
 
-        result = value.public_send(method)
+        result = FailureCapture.application do
+          value.public_send(method) if value.respond_to?(method)
+        end
         return result if result.nil? || result.is_a?(type)
 
         raise TypeError, "#{method} must return #{type}"

data/lib/jmespath/diagnostic.rb

@@ -5,7 +5,7 @@ module JMESPath
   module Diagnostic
     class << self
       # Format a syntax failure without reading data or printing output.
-      # @param error [Errors::SyntaxError] the syntax failure
+      # @param error [Errors::SyntaxError, SyntaxDiagnostic] the syntax failure
       # @return [String] UTF-8 diagnostic without a trailing newline
       # @example Format a located failure
       #   error = JMESPath::Errors::SyntaxError.new("Bad query", expression: "$", position: 0)
@@ -30,9 +30,10 @@ module JMESPath
 
       def source_parts(error)
         source = error.expression
-        return unless error.location_known? && error.position.between?(0, source.bytesize)
+        position = error.position
+        return unless position&.between?(0, source.bytesize) && error.location_known?
 
-        prefix = source.byteslice(0, error.position).to_s
+        prefix = source.byteslice(0, position).to_s
         return unless source.valid_encoding? && prefix.valid_encoding?
 
         [source.encode(Encoding::UTF_8), prefix.encode(Encoding::UTF_8)]

data/lib/jmespath/errors.rb

@@ -8,6 +8,20 @@ module JMESPath
     # A runtime evaluation failure.
     class RuntimeError < Error; end
 
+    # A required query result is null.
+    class NullResultError < RuntimeError
+      # @return [String] the frozen query text
+      attr_reader :expression
+
+      # @param expression [String] the query that returned null
+      # @example Inspect a failed requirement
+      #   JMESPath::Errors::NullResultError.new(expression: "user.name").expression #=> "user.name"
+      def initialize(expression:)
+        @expression = expression.dup.freeze
+        super("Expression returned null")
+      end
+    end
+
     # A malformed expression with a byte position and readable coordinates.
     class SyntaxError < Error
       # @return [String] the reason parsing failed, without coordinates