search_ui 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc66d5f87d1370805a30dad557a8831bc5a6e92d58f7a66cfbd1d595894a8643
-  data.tar.gz: 49a905c0c598310528f07e4bf7edf5cee63da6f522329c6417ca3b5b19834d5c
+  metadata.gz: e7d5feb21158fa490f48360724a1e4bd0110a1dd64d89c6bbb79be5bf8de3019
+  data.tar.gz: e162cee1ef6035b7ea1305360c88d260b5ebb0b5ecf91fe573a2d0be5c50eaca
 SHA512:
-  metadata.gz: 36333f847712de6afc618fd6f8671b8ad693c9d929056863a959920bbed0d23cc888d4043ddddfe122a6f284128bfee8983cf0a2d45bf13cdcf0ff80c15c795c
-  data.tar.gz: 39b38086ac623ab6b918e56a3828396439dd383dec601c71c99ecb6124f327f00a47ce0b045935ef7fab84c7d0f349ea111650c3cfd1b1f5f1bc1757b63913a5
+  metadata.gz: 66b6d79977ab604dc5cb1fec8bb6c5e9467ac80af1a7ad4e95dab2466aa6c5d48f98e5b4e3fd820a1522f16dfcd88e02690759a09ef8d906f21a3d8e6d32a079
+  data.tar.gz: eebad124b4790a0059b7ce0fd7b337cbb55d439035a04e869ca6d040130a333b3d63531ed21d40b0745200493831cc653513ff3c4b7d2324a94172ac67d8fa38

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/search_ui/search.rb

@@ -18,35 +18,54 @@ class SearchUI::Search
   include Term::ANSIColor
   extend Term::ANSIColor
 
-  # Initializes a new SearchUI::Search instance with the specified parameters.
+  # Represents the current state of the search interface.
   #
-  # @param match [ Proc ] a procedure that takes a string and returns an array
-  #   of matching objects
-  # @param query [ Proc ] a procedure that takes the current answer, matches,
-  #   and selector index to generate a query result
-  # @param found [ Proc ] a procedure that takes the current answer, matches,
-  #   jand selector index to determine if a selection has been made
-  # @param output [ IO ] the output stream to display the search interface
-  #   (defaults to STDOUT)
-  # @param prompt [ String ] the prompt template to display during searching
-  #   (defaults to 'Search? %s')
+  # @attr answer [ String ] the current input string entered by the user
+  # @attr selector [ Integer ] the index of the currently selected match
+  State = Struct.new(:answer, :selector)
+
+  # Initializes a new SearchUI::Search instance to manage an interactive
+  # console search interface. This method sets up the filtering logic, display
+  # formatting, and selection criteria required to drive the search loop, as
+  # well as the output stream and prompt.
+  #
+  # @param match [ Proc ] a procedure that accepts a search pattern string and returns
+  #   an array of matching objects.
+  # @param query [ Proc ] a procedure that accepts the current answer, the list of
+  #   matches, and the current selector index to generate the string representation
+  #   of the results list.
+  # @param found [ Proc ] a procedure that accepts the current answer, the list of
+  #   matches, and the current selector index to determine the final selected object.
+  # @param output [ IO ] the output stream where the interface will be rendered.
+  #   Defaults to STDOUT.
+  # @param prompt [ String ] a format string used as the user prompt.
+  #   Defaults to 'Search? %s'.
+  # @param state [ SearchUI::Search::State, nil ] an initial state object containing
+  #   the starting answer and selector position. Defaults to a new State with an
+  #   empty answer and selector set to 0.
   def initialize(
     match:,
     query:,
     found:,
     output: STDOUT,
-    prompt: 'Search? %s'
+    prompt: 'Search? %s',
+    state:  nil
   )
     @match        = match
     @query        = query
     @found        = found
     @output       = output
     @prompt       = prompt
-    @selector     = 0
-    @max_selector = nil
-    @answer       = ''
+    @state        = state || State.new('', 0)
   end
 
+  # Reads the current internal state of the search interface, containing the
+  # current input answer and the active selection index.
+  #
+  # @return [ SearchUI::Search::State ] the current state object tracking
+  #   the user's search progress and cursor position
+  attr_reader :state
+
   # Starts the interactive search interface and handles user input until a
   # selection is made or the process is cancelled.
   #
@@ -54,16 +73,16 @@ class SearchUI::Search
   #   is made, or nil if the process is cancelled
   def start
     @output.print reset
-    @matches = @match.(@answer)
-    @selector = @selector.clamp(0, [ @matches.size - 1, 0 ].max)
-    result = @query.(@answer, @matches, @selector)
+    @matches = @match.(@state.answer)
+    @state.selector = @state.selector.clamp(0, [ @matches.size - 1, 0 ].max)
+    result = @query.(@state.answer, @matches, @state.selector)
     loop do
       @output.print clear_screen
-      @output.print move_home { @prompt % @answer + ?\n + result }
+      @output.print move_home { @prompt % @state.answer + ?\n + result }
       case getc
       when true
         @output.print clear_screen, move_home, reset
-        if result = @found.(@answer, @matches, @selector)
+        if result = @found.(@state.answer, @matches, @state.selector)
           return result
         else
           return nil
@@ -71,26 +90,33 @@ class SearchUI::Search
       when false
         return nil
       end
-      @matches = @match.(@answer)
-      @selector = @selector.clamp(0, [ @matches.size - 1, 0 ].max)
-      result = @query.(@answer, @matches, @selector)
+      @matches = @match.(@state.answer)
+      @state.selector = @state.selector.clamp(0, [ @matches.size - 1, 0 ].max)
+      result = @query.(@state.answer, @matches, @state.selector)
     end
   end
 
   private
 
-  # Reads and processes a single character input from stdin, handling special
+  # Reads and processes a single character input from STDIN, handling special
   # key sequences and updating the search state accordingly.
   #
   # This method manages raw terminal input to capture user keystrokes,
-  # interpreting control characters and escape sequences for navigation,
-  # selection, and editing operations. It temporarily disables terminal echo
-  # and sets raw mode to ensure proper input handling.
+  # interpreting control characters and ANSI escape sequences:
+  # - Up/Down arrows: Navigate the result selector.
+  # - Enter (`\r`): Confirms the current selection.
+  # - Ctrl-C (`\x03`): Cancels the search operation.
+  # - Ctrl-K (`\v`): Clears the current search answer.
+  # - Backspace (`\x7f`): Deletes the last character of the answer.
+  # - Note: Any modification to the search answer resets the selector to 0.
+  #
+  # It temporarily disables terminal echo and sets raw mode to ensure proper
+  # input handling.
   #
-  # @return [ Boolean, nil ] returns true when the Enter key is pressed to
-  #   confirm selection, false when Ctrl+C is pressed to cancel the operation, or
-  #   nil for all other inputs
-  #   which update the search state and require further processing
+  # @return [ Boolean, nil ]
+  #   - `true`: The Enter key was pressed to confirm selection.
+  #   - `false`: Ctrl-C was pressed to cancel the operation.
+  #   - `nil`: Input updated the search state or was ignored.
   def getc
     print hide_cursor
     system 'stty raw -echo'
@@ -103,27 +129,27 @@ class SearchUI::Search
       STDIN.getc == ?[ or return nil
       STDIN.getc =~ /\A([AB])\z/ or return nil
       if $1 == ?A
-        @selector -= 1
+        @state.selector -= 1
       else
-        @selector += 1
+        @state.selector += 1
       end
-      @selector = [ @selector, 0 ].max
+      @state.selector = [ @state.selector, 0 ].max
       nil
     when ?\r
       true
     when "\x7f"
-      @selector = 0
-      @answer.chop!
+      @state.selector = 0
+      @state.answer.chop!
       nil
-    when "\v"
-      @selector = 0
-      @answer.clear
+    when ?\v
+      @state.selector = 0
+      @state.answer.clear
       nil
     when /\A[\x00-\x1f]\z/
       nil
     else
-      @selector = 0
-      @answer << c
+      @state.selector = 0
+      @state.answer << c
       nil
     end
   ensure

data/lib/search_ui/version.rb

@@ -1,6 +1,6 @@
 module SearchUI
   # SearchUI version
-  VERSION         = '0.1.0'
+  VERSION         = '0.2.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/search_ui.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: search_ui 0.1.0 ruby lib
+# stub: search_ui 0.2.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "search_ui".freeze
-  s.version = "0.1.0".freeze
+  s.version = "0.2.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -18,13 +18,13 @@ Gem::Specification.new do |s|
   s.licenses = ["MIT".freeze]
   s.rdoc_options = ["--title".freeze, "SearchUI -- Search User Interface".freeze, "--main".freeze, "README.md".freeze]
   s.required_ruby_version = Gem::Requirement.new(">= 2.0".freeze)
-  s.rubygems_version = "4.0.3".freeze
+  s.rubygems_version = "4.0.10".freeze
   s.summary = "Library to provide a user interface for searching in a console".freeze
   s.test_files = ["spec/search_ui/wrapper_spec.rb".freeze, "spec/spec_helper.rb".freeze]
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, [">= 2.17.0".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, [">= 2.17.1".freeze])
   s.add_development_dependency(%q<rspec>.freeze, ["~> 3.0".freeze])
   s.add_development_dependency(%q<simplecov>.freeze, ["~> 0.0".freeze])
   s.add_development_dependency(%q<debug>.freeze, [">= 0".freeze])

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: search_ui
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Florian Frank
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.17.0
+        version: 2.17.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.17.0
+        version: 2.17.1
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -158,7 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Library to provide a user interface for searching in a console
 test_files: