jmespath-ruby 0.1.3 → 1.0.0

data/lib/jmespath/cli/interactive_completion.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module JMESPath
+  module CLI
+    # @api private
+    class InteractiveCompletion
+      def initialize(functions: Functions.default)
+        @names = functions.names.sort
+      end
+
+      def complete(line, point:)
+        # @type var unchanged: completion_result
+        unchanged = { line: line, point: point, candidates: [] }
+        token = token(line, point)
+        return unchanged unless token
+
+        prefix, start, finish = token
+        names = @names.select { |name| name.start_with?(prefix) }
+        unchanged[:candidates] = names
+        return unchanged if names.empty?
+
+        common = common_prefix(names)
+        return unchanged if names.length > 1 && common == prefix
+
+        { line: replace(line, start, finish, common),
+          point: start + common.bytesize, candidates: names }
+      end
+
+      private
+
+      def replace(line, start, finish, common)
+        line.byteslice(0, start).to_s + common + line.byteslice(finish..).to_s
+      end
+
+      def token(line, point)
+        return unless valid_cursor?(line, point)
+
+        before = line.byteslice(0, point).to_s
+        return if quoted?(before)
+
+        prefix = identifier_prefix(before)
+        return unless prefix&.match?(/\A[A-Za-z_]/)
+
+        suffix = line.byteslice(point..).to_s[/\A[A-Za-z0-9_]*/].to_s
+        [prefix, point - prefix.bytesize, point + suffix.bytesize]
+      end
+
+      def identifier_prefix(before)
+        before.reverse[/\A[A-Za-z0-9_]+/]&.reverse
+      end
+
+      def valid_cursor?(line, point)
+        source = line.dup.force_encoding(Encoding::UTF_8)
+        return false unless source.valid_encoding? && point.between?(0, source.bytesize)
+        return false unless source.byteslice(0, point).to_s.valid_encoding?
+        return false if source.include?("\n")
+
+        query?(source, point)
+      end
+
+      def query?(line, point)
+        return true unless line.match?(/\A[ \t]*:/)
+
+        command = /\A[ \t]*:(?:explain|trace)[ \t]+/.match(line)
+        return false unless command
+
+        point >= command[0].bytesize
+      end
+
+      def quoted?(before)
+        index = 0
+        quote = nil
+        while index < before.bytesize
+          byte = before.getbyte(index)
+          if quote
+            index += 1 if byte == 92
+            quote = nil if byte == quote
+          elsif [34, 39, 96].include?(byte)
+            quote = byte
+          end
+          index += 1
+        end
+        !quote.nil?
+      end
+
+      def common_prefix(names)
+        common = names.fetch(0)
+        common = common[0...-1] until names.fetch(-1).start_with?(common)
+        common
+      end
+    end
+  end
+end

data/lib/jmespath/cli/interactive_editor.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "interactive_editor_state"
+require_relative "interactive_completion"
+
+module JMESPath
+  module CLI
+    # @api private
+    class InteractiveEditor
+      HISTORY_LIMIT = 500
+
+      def self.supported?(input:, errors:)
+        return false unless terminal_environment?
+
+        return false unless [input, errors].all? { |stream| stream.is_a?(IO) && !stream.closed? && stream.tty? }
+
+        require "io/console"
+        backend_supported?
+      end
+
+      def self.backend_supported?
+        require "reline"
+        backend = Reline::IOGate
+        !backend.dumb? && backend.respond_to?(:input=) && backend.respond_to?(:output=)
+      end
+
+      def self.terminal_environment?
+        ![nil, "", "dumb"].include?(ENV.fetch("TERM", nil)) && !ENV.key?("RELINE_STDERR_TTY")
+      end
+
+      def initialize(input:, errors:)
+        require "reline"
+        require_relative "interactive_key_stroke"
+        require_relative "interactive_line_editor"
+        @input = input
+        @errors = errors
+        @history = []
+        @pending = []
+        @completion = InteractiveCompletion.new
+        @writing_errors = false
+      end
+
+      def open
+        state = InteractiveEditorState.new
+        begin
+          state.configure(@input, @errors)
+          Reline.completion_proc = method(:complete)
+          yield
+        ensure
+          state.restore
+        end
+      end
+
+      def gets
+        return @pending.shift unless @pending.empty?
+
+        read_line
+      rescue Interrupt
+        @errors.puts("^C")
+        retry
+      end
+
+      def remember(query)
+        @history << query
+        @history.shift if @history.length > HISTORY_LIMIT
+        Reline::HISTORY.replace(@history)
+      end
+
+      def writing_errors?
+        @writing_errors
+      end
+
+      private
+
+      def read_line
+        @writing_errors = true
+        line = Reline.readline("jmespath> ", false)
+        @writing_errors = false
+        return unless line
+
+        lines = Reline.core.line_editor.whole_lines
+        return line if lines.length == 1
+
+        @pending = lines
+        @pending.shift
+      rescue InteractiveKeyStroke::InvalidInput => e
+        reject_invalid(e)
+      end
+
+      def reject_invalid(error)
+        terminator = error.ended? ? error.byte : discard_line
+        @errors.puts("")
+        @writing_errors = false
+        return if terminator.nil? || terminator == 4
+
+        "\xFF".b
+      end
+
+      def discard_line
+        # @type var input: Object & _RawInput
+        input = @input
+        input.raw(intr: true) do
+          loop do
+            byte = Reline::IOGate.getc(Float::INFINITY)
+            break byte if byte.nil? || [4, 10, 13].include?(byte)
+          end
+        end
+      end
+
+      def complete(_target)
+        line = Reline.line_buffer
+        result = @completion.complete(line, point: Reline.point)
+        if result[:line] != line
+          Reline.delete_text
+          Reline.insert_text(result[:line])
+          Reline.point = result[:point]
+        elsif result[:candidates].length > 1
+          list_candidates(result[:candidates])
+        end
+        nil
+      end
+
+      def list_candidates(candidates)
+        Reline.core.line_editor.render_finished
+        @errors.puts(candidates.join("  "))
+      end
+    end
+  end
+end

data/lib/jmespath/cli/interactive_editor_state.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module JMESPath
+  module CLI
+    # @api private
+    class InteractiveEditorState
+      PROPERTIES = %i[completion_proc output_modifier_proc prompt_proc auto_indent_proc pre_input_hook
+                      dig_perfect_match_proc last_incremental_search].freeze
+
+      def initialize
+        @core = Reline.core
+        # Reline 0.7 exposes only input=; retain the previous reader for restoration.
+        @input = Reline::IOGate.instance_variable_get(:@input)
+        @output = @core.output
+        @configuration = [@core.config, @core.key_stroke, @core.line_editor]
+        @callbacks = PROPERTIES.to_h { |key| [key, Reline.public_send(key)] }
+        @history = Reline::HISTORY.to_a
+        @history_size = @core.config.history_size
+      end
+
+      def configure(input, errors)
+        Reline.input = input
+        Reline.output = errors
+        @core.config.history_size = InteractiveEditor::HISTORY_LIMIT
+        configure_core
+        PROPERTIES.each { |key| Reline.public_send(:"#{key}=", nil) }
+        Reline::HISTORY.clear
+      end
+
+      def configure_core
+        config = Reline::Config.new
+        config.read
+        config.autocompletion = false
+        config.disable_completion = false
+        config.history_size = InteractiveEditor::HISTORY_LIMIT
+        Reline::IOGate.set_default_key_bindings(config)
+        @core.config = config
+        @core.key_stroke = InteractiveKeyStroke.new(config, Reline::IOGate.encoding)
+        @core.line_editor = InteractiveLineEditor.new(config)
+      end
+
+      def restore
+        Reline.input = @input
+        Reline.output = @output
+        @core.config, @core.key_stroke, @core.line_editor = @configuration
+        @core.config.history_size = @history_size
+        @callbacks.each { |key, value| Reline.public_send(:"#{key}=", value) }
+        Reline::HISTORY.replace(@history)
+      end
+    end
+  end
+end

data/lib/jmespath/cli/interactive_help.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module JMESPath
+  module CLI
+    # @api private
+    module InteractiveHelp
+      TEXT = <<~TEXT
+        Interactive: jmespath --interactive --file PATH
+                     jmespath --interactive --file document.json
+        Enter one UTF-8 query per line; empty lines and lines containing only spaces or tabs are ignored.
+        Queries accept LF, CRLF, and a final line without a newline.
+        :help shows session help; :quit or EOF exits with status 0, even after query failures.
+        :functions lists built-in names, signatures, and descriptions on stderr.
+        :explain QUERY shows the query's operation tree and source locations on stderr without evaluating data.
+        :trace QUERY evaluates once, writes events to stderr, and writes one compact JSON result to stdout.
+        Traces retain at most 1000 events and report truncation after evaluation completes.
+        Query errors, unknown commands, and invalid UTF-8 lines report diagnostics; the session continues.
+        Failed queries print no result. Successful queries print compact JSON and a newline to stdout.
+        Prompts, help, and diagnostics use stderr. Prompts appear only when stdin is a terminal.
+        Results flush after each query when supported; piped query input produces no prompts.
+        The document loads once and its file closes before the first prompt or query read.
+        Interactive mode requires --file and rejects query sources, other modes, information flags, and repeats.
+        Startup or stream failures exit with status 1; usage failures return 2 before reading input.
+        CLI.run input needs gets; tty? is optional and absent detection means no prompts.
+        Writers need puts; output flush is optional. Terminal prompts require stderr print and flush.
+        Supported terminals provide editing and recall of the last 500 queries for this session only.
+        Ctrl-C cancels the current edit. History includes failed queries, excludes commands, and creates no files.
+        Editing requires terminal IO on stdin and stderr and a usable TERM; other streams use a plain reader.
+        Tab completes built-in function names outside quoted identifiers and literals, preserving surrounding text.
+        Unique matches insert only a name. Ambiguous matches extend a common prefix or list sorted alternatives.
+        Empty or unknown prefixes remain unchanged. Caller-owned streams remain open.
+        Multiline editing and document reloads are unavailable.
+      TEXT
+    end
+  end
+end

data/lib/jmespath/cli/interactive_key_stroke.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module JMESPath
+  module CLI
+    # @api private
+    class InteractiveKeyStroke < Reline::KeyStroke
+      # @api private
+      class InvalidInput < StandardError
+        attr_reader :byte
+
+        def initialize(byte)
+          @byte = byte
+          super("Invalid UTF-8 query")
+        end
+
+        def ended?
+          [4, 10, 13].include?(@byte)
+        end
+      end
+
+      def match_status(input)
+        validate_prefix(input)
+        super
+      end
+
+      def expand(input)
+        keys, rest = super
+        keys = keys.map do |key|
+          case key.method_symbol
+          when :bracketed_paste_start
+            Reline::Key.new(read_paste, :insert_multiline_text)
+          when :quoted_insert, :ed_quoted_insert
+            Reline::Key.new(read_quoted, :insert_raw_char)
+          else
+            key
+          end
+        end
+        [keys, rest]
+      end
+
+      private
+
+      def validate_prefix(input)
+        decoder = Encoding::Converter.new("UTF-8", "UTF-16LE")
+        source = input.pack("C*")
+        status = decoder.primitive_convert(source, +"", nil, nil, Encoding::Converter::PARTIAL_INPUT)
+        raise InvalidInput, input.fetch(-1) unless status == :source_buffer_empty
+      end
+
+      def read_paste
+        marker = "\e[201~".b
+        buffer = +"".b
+        until buffer.end_with?(marker)
+          byte = Reline::IOGate.getc(Float::INFINITY)
+          break unless byte
+
+          buffer << byte
+        end
+        text = buffer.delete_suffix(marker).force_encoding(Encoding::UTF_8)
+        raise InvalidInput, 255 unless text.valid_encoding?
+
+        text
+      end
+
+      def read_quoted
+        # @type var bytes: Array[Integer]
+        bytes = []
+        loop do
+          byte = Reline::IOGate.getc(Float::INFINITY)
+          return "" unless byte
+
+          bytes << byte
+          validate_prefix(bytes)
+          text = bytes.pack("C*").force_encoding(Encoding::UTF_8)
+          return text if text.valid_encoding?
+        end
+      end
+    end
+  end
+end

data/lib/jmespath/cli/interactive_line_editor.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module JMESPath
+  module CLI
+    # @api private
+    class InteractiveLineEditor < Reline::LineEditor
+      # Dialogs registered by another Reline consumer do not belong to this session.
+      def add_dialog_proc(_name, _callback, _context = nil); end
+    end
+  end
+end

data/lib/jmespath/cli/interactive_session.rb

@@ -4,7 +4,13 @@ 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."
+      HELP = "Enter one query per line; blank lines are ignored.\n:help shows help; :quit ends the session.\n" \
+             ":functions lists built-ins; :explain QUERY shows structure without evaluating the document.\n" \
+             ":trace QUERY evaluates once; at most 1000 events use stderr and one JSON result uses stdout.\n" \
+             "Supported terminals provide editing and recall of the last 500 queries for this session only.\n" \
+             "Ctrl-C cancels the current edit. Other streams use the plain line reader.\n" \
+             "Tab completes function names outside quotes; ambiguous prefixes list sorted names.\n" \
+             "Prompts and diagnostics use stderr; successful JSON results use stdout."
 
       def initialize(data, input:, output:, errors:)
         @data = data
@@ -15,13 +21,13 @@ module JMESPath
       end
 
       def run
-        loop do
-          prompt
-          line = @input.gets
-          break unless line
-          break if process?(line)
+        if InteractiveEditor.supported?(input: @input, errors: @errors)
+          editor = InteractiveEditor.new(input: @input, errors: @errors)
+          @editor = editor
+          editor.open { read_queries }
+        else
+          read_queries
         end
-        0
       rescue IOError, SystemCallError => e
         report_stream_failure(e)
         1
@@ -29,6 +35,17 @@ module JMESPath
 
       private
 
+      def read_queries
+        loop do
+          prompt unless @editor
+          editor = @editor
+          line = editor ? editor.gets : @input.gets
+          break unless line
+          break if process?(line)
+        end
+        0
+      end
+
       def process?(line)
         expression = line.dup.force_encoding(Encoding::UTF_8)
         unless expression.valid_encoding?
@@ -47,14 +64,21 @@ module JMESPath
         if command == ":help"
           diagnostic(HELP)
         elsif command.start_with?(":")
-          diagnostic(FailureDiagnostic.format(Errors::Error.new("Unknown command: #{command}"), nil))
+          execute_command(expression)
         else
+          @editor&.remember(expression)
           result = evaluate(expression)
           write_result(result) if result
         end
         false
       end
 
+      def execute_command(expression)
+        report, result = InteractiveCommands.call(expression, data: @data)
+        diagnostic(report)
+        write_result(result) if result
+      end
+
       def evaluate(expression)
         JSON.generate(JMESPath.search(expression, @data))
       rescue JSON::NestingError
@@ -97,7 +121,9 @@ module JMESPath
       end
 
       def report_stream_failure(error)
-        diagnostic(FailureDiagnostic.format(error, nil)) unless @writing_errors
+        return if @writing_errors || @editor&.writing_errors?
+
+        diagnostic(FailureDiagnostic.format(error, nil))
       rescue IOError, SystemCallError
         nil
       end

data/lib/jmespath/cli.rb

@@ -4,6 +4,8 @@ require_relative "../jmespath"
 require_relative "cli/failure_diagnostic"
 require_relative "cli/arguments"
 require_relative "cli/function_listing"
+require_relative "cli/interactive_commands"
+require_relative "cli/interactive_editor"
 require_relative "cli/interactive_session"
 require_relative "cli/help"
 
@@ -17,11 +19,12 @@ module JMESPath
     # @return [Integer] zero on success, one on input failure, two on usage failure
     def self.run(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr)
       return validation(argv, stderr) if literal_validation?(argv)
-      return information(argv, stdout) if [%w[--help], %w[-h], %w[--version], %w[--functions]].include?(argv)
+      return help(argv, stdout) if %w[--help -h].include?(argv.first)
+      return information(argv, stdout) if [%w[--version], %w[--functions]].include?(argv)
 
       query(argv, stdin, stdout, stderr)
     rescue OptionParser::ParseError
-      stderr.puts(USAGE)
+      stderr.puts("#{USAGE}\nUse jmespath --help for options and topic help.")
       2
     rescue JSON::ParserError, Errors::Error, IOError, SystemCallError => e
       failure(e, nil, stderr)
@@ -29,18 +32,18 @@ module JMESPath
 
     # @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
+      expression, path, query_path, mode = parse_arguments(argv)
+      return interactive_session(path, stdin, stdout, stderr) if mode == "interactive"
 
       expression = read_query(expression, query_path)
-      return validation(["--validate", expression], stderr) if validate
-      if json_lines
+      return validation(["--validate", expression], stderr) if mode == "validate"
+      if mode == "json-lines"
         # @type var stdin: _LineReader
         return execute_lines(expression, path, stdin, stdout, stderr)
       end
 
       # @type var stdin: _Reader
-      execute(expression, read_document(path, stdin), stdout, pretty, raw_output)
+      execute(expression, read_document(path, stdin), stdout, mode)
     rescue JSON::ParserError, Errors::Error => e
       failure(e, expression, stderr)
     end
@@ -75,12 +78,12 @@ module JMESPath
     end
 
     # @api private
-    def self.execute(expression, data, stdout, pretty, raw_output)
+    def self.execute(expression, data, stdout, mode)
       result = JMESPath.search(expression, data)
-      output = if raw_output && result.is_a?(String)
+      output = if mode == "raw-output" && result.is_a?(String)
                  "#{result}\n"
                else
-                 pretty ? JSON.pretty_generate(result) : JSON.generate(result)
+                 mode == "pretty" ? JSON.pretty_generate(result) : JSON.generate(result)
                end
       stdout.puts(output)
       0
@@ -123,6 +126,14 @@ module JMESPath
       1
     end
 
+    # @api private
+    def self.help(argv, output)
+      raise OptionParser::InvalidArgument, "expected at most one help topic" if argv.length > 2
+
+      output.puts(Help.render(argv[1]))
+      0
+    end
+
     # @api private
     def self.information(argv, output)
       if argv == ["--functions"]
@@ -130,7 +141,7 @@ module JMESPath
         return 0
       end
 
-      output.puts(argv == ["--version"] ? "jmespath-ruby #{VERSION}" : HELP)
+      output.puts("jmespath-ruby #{VERSION}")
       0
     end
   end

data/lib/jmespath/version.rb

@@ -3,5 +3,5 @@
 # Queries JSON-compatible Ruby values using JMESPath expressions.
 module JMESPath
   # The semantic version of this implementation.
-  VERSION = "0.1.3"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jmespath-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -29,6 +29,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '4'
+- !ruby/object:Gem::Dependency
+  name: reline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
 - !ruby/object:Gem::Dependency
   name: stringio
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +80,7 @@ files:
 - VERSIONING.md
 - completions/_jmespath
 - completions/jmespath.bash
+- docs/guides/command-line.md
 - docs/guides/comparison.md
 - docs/guides/compatibility.md
 - docs/guides/compilation.md
@@ -85,6 +100,14 @@ files:
 - lib/jmespath/cli/failure_diagnostic.rb
 - lib/jmespath/cli/function_listing.rb
 - lib/jmespath/cli/help.rb
+- lib/jmespath/cli/inspection_report.rb
+- lib/jmespath/cli/interactive_commands.rb
+- lib/jmespath/cli/interactive_completion.rb
+- lib/jmespath/cli/interactive_editor.rb
+- lib/jmespath/cli/interactive_editor_state.rb
+- lib/jmespath/cli/interactive_help.rb
+- lib/jmespath/cli/interactive_key_stroke.rb
+- lib/jmespath/cli/interactive_line_editor.rb
 - lib/jmespath/cli/interactive_session.rb
 - lib/jmespath/data_access.rb
 - lib/jmespath/diagnostic.rb