search_ui 0.0.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 710fcef9a16190a9c6f59491c8ba25f44e82cd5a9718489658ed2f1b2a893487
-  data.tar.gz: cbec273ce822d45c805d92325ffa7e4970d079a1bd2680a4732a413002cfeaf8
+  metadata.gz: e7d5feb21158fa490f48360724a1e4bd0110a1dd64d89c6bbb79be5bf8de3019
+  data.tar.gz: e162cee1ef6035b7ea1305360c88d260b5ebb0b5ecf91fe573a2d0be5c50eaca
 SHA512:
-  metadata.gz: 3f398a7c9be2b14ac3aaee4cf38a22b1b4871dedc4c5250a251cd1376beb88fe8b00ae495a1baaf184d8bf05c742f7dd399a1c4888eec225e17d9affdb33ba30
-  data.tar.gz: 1de4d6e0313b493136e1f42cf1aeebdbf023e09c5840dbd8dfaf28a881f2e317fb9814b0813d69ec033bc4f4c7b33f96bfb4daba8e2bf44d7ab3fe9cdb5ba3d8
+  metadata.gz: 66b6d79977ab604dc5cb1fec8bb6c5e9467ac80af1a7ad4e95dab2466aa6c5d48f98e5b4e3fd820a1522f16dfcd88e02690759a09ef8d906f21a3d8e6d32a079
+  data.tar.gz: eebad124b4790a0059b7ce0fd7b337cbb55d439035a04e869ca6d040130a333b3d63531ed21d40b0745200493831cc653513ff3c4b7d2324a94172ac67d8fa38

data/.rspec

@@ -0,0 +1 @@
+-r spec_helper

data/Rakefile

@@ -9,9 +9,13 @@ GemHadar do
   email       'flori@ping.de'
   homepage    "https://github.com/flori/#{name}"
   summary     'Library to provide a user interface for searching in a console'
-  description 'This library allows a user to search an array of objects
-  interactively in the console by matching the pattern a user inputs to an
-  array of objects and pick one of the remaining objects.'
+  description <<~EOT
+    This library allows a user to search an array of objects
+    interactively in the console by matching the pattern a user inputs to an
+    array of objects and pick one of the remaining objects.
+  EOT
+
+  test_dir    'spec'
 
   ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', 'coverage', '.AppleDouble',
     'tags', '.DS_Store', '.yardoc', 'doc'
@@ -22,10 +26,11 @@ GemHadar do
   executables << 'search_it'
 
   required_ruby_version '>= 2.0'
-  dependency             'tins', '~>1.0'
+  dependency             'tins',           '~>1.0'
   dependency             'term-ansicolor', '~>1.0'
-  dependency             'amatch', '~>0.0'
-  development_dependency 'simplecov', '~>0.0'
+  dependency             'amatch',         '~>0.0'
+  development_dependency 'rspec',          '~>3.0'
+  development_dependency 'simplecov',      '~>0.0'
   development_dependency 'debug'
   licenses << 'MIT'
 end

data/VERSION

@@ -1 +1 @@
-0.0.9
+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.0.9'
+  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/lib/search_ui/wrapper.rb

@@ -0,0 +1,67 @@
+# Wrapper around an arbitrary value that:
+#
+# * Exposes the wrapped object via `value`.
+# * Allows you to supply a custom string representation (`display`).
+# * Delegates all other method calls straight through to the wrapped value.
+#
+# This is handy when you want to keep your objects printable in a
+# particular colour or format (e.g. with Term::ANSIColor) while still
+# behaving like the original object for comparisons, length checks,
+# etc.
+#
+# @example Basic usage
+#   wrapper = SearchUI::Wrapper.new('foo', display: '🟢 foo')
+#   puts wrapper          # => "🟢 foo"
+#   wrapper.length        # => 3 (delegated to the string)
+class SearchUI::Wrapper < BasicObject
+  # Initializes a new wrapper.
+  #
+  # @param value [Object] The object you want to wrap.
+  # @option options [String, Proc] :display Custom display string or block that returns it.
+  #   Defaults to `value.to_s`.
+  def initialize(value, display: value.to_s)
+    @value   = value
+    @display = display
+  end
+
+  # Returns the wrapped object.
+  #
+  # @return [Object]
+  attr_reader :value
+
+  # Equality comparison.
+  #
+  # Two wrappers are equal if their underlying values compare equal to the other argument.
+  #
+  # @param other [Object] The value or another wrapper to compare against.
+  # @return [Boolean]
+  def ==(other)
+    @value == other
+  end
+
+  alias eql? ==
+
+  # String representation of the wrapped object.
+  #
+  # If a custom `display` was supplied, that string is returned; otherwise,
+  # it falls back to `value.to_s`.
+  #
+  # @return [String]
+  def to_s
+    @display.to_s
+  end
+
+  alias to_str to_s
+
+  # Delegates any unknown method call to the wrapped value.
+  #
+  # This makes the wrapper behave like a transparent proxy for most
+  # operations (e.g. `length`, `upcase`, etc.).
+  #
+  # @param a [Array] Method name and arguments.
+  # @param o [Hash] Keyword arguments.
+  # @yield b Optional block passed to the underlying method.
+  def method_missing(*a, **o, &b)
+    @value.__send__(*a, **o, &b)
+  end
+end

data/lib/search_ui.rb

@@ -1,4 +1,3 @@
-
 # SearchUI is a library that provides interactive console-based searching
 # capabilities
 #
@@ -14,4 +13,5 @@ module SearchUI
 end
 
 require 'search_ui/version'
+require 'search_ui/wrapper'
 require 'search_ui/search'

data/search_ui.gemspec

@@ -1,29 +1,31 @@
 # -*- encoding: utf-8 -*-
-# stub: search_ui 0.0.9 ruby lib
+# stub: search_ui 0.2.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "search_ui".freeze
-  s.version = "0.0.9".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]
   s.authors = ["Florian Frank".freeze]
   s.date = "1980-01-02"
-  s.description = "This library allows a user to search an array of objects\n  interactively in the console by matching the pattern a user inputs to an\n  array of objects and pick one of the remaining objects.".freeze
+  s.description = "This library allows a user to search an array of objects\ninteractively in the console by matching the pattern a user inputs to an\narray of objects and pick one of the remaining objects.\n".freeze
   s.email = "flori@ping.de".freeze
   s.executables = ["search_it".freeze]
-  s.extra_rdoc_files = ["README.md".freeze, "lib/search_ui.rb".freeze, "lib/search_ui/search.rb".freeze, "lib/search_ui/version.rb".freeze]
-  s.files = ["Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "bin/search_it".freeze, "lib/search_ui.rb".freeze, "lib/search_ui/search.rb".freeze, "lib/search_ui/version.rb".freeze, "search_ui.gemspec".freeze]
+  s.extra_rdoc_files = ["README.md".freeze, "lib/search_ui.rb".freeze, "lib/search_ui/search.rb".freeze, "lib/search_ui/version.rb".freeze, "lib/search_ui/wrapper.rb".freeze]
+  s.files = [".rspec".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "bin/search_it".freeze, "lib/search_ui.rb".freeze, "lib/search_ui/search.rb".freeze, "lib/search_ui/version.rb".freeze, "lib/search_ui/wrapper.rb".freeze, "search_ui.gemspec".freeze, "spec/search_ui/wrapper_spec.rb".freeze, "spec/spec_helper.rb".freeze]
   s.homepage = "https://github.com/flori/search_ui".freeze
   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.2".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.12".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])
   s.add_runtime_dependency(%q<tins>.freeze, ["~> 1.0".freeze])

data/spec/search_ui/wrapper_spec.rb

@@ -0,0 +1,56 @@
+describe SearchUI::Wrapper do
+  let(:value) { 'foo' }
+
+  c = Term::ANSIColor
+
+  let(:sw1) { described_class.new(value, display: c.red { value }) }
+
+  let(:sw2) { described_class.new(value, display: c.blue { value }) }
+
+  it 'stores the wrapped value' do
+    expect(sw1.value).to eq value
+  end
+
+  it 'returns the custom string when to_s is called' do
+    expect(sw1.to_s).to eq c.red { 'foo' }
+  end
+
+  it 'falls back to the wrapped object’s to_s if no display given' do
+    wrapper = described_class.new(value)
+    expect(wrapper.to_s).to eq 'foo'
+  end
+
+  it 'delegates methods to the wrapped value (e.g., length)' do
+    expect(sw1.length).to eq 3
+  end
+
+  it 'compares equal when underlying values are equal' do
+    expect(sw1 == sw2).to be true
+  end
+
+  it 'is not equal to a different wrapped value' do
+    diff_obj = "bar"
+    expect(sw1 == described_class.new(diff_obj)).to be false
+  end
+
+  context 'equality with other wrappers' do
+    it 'is eq' do
+      expect(sw1).to eq sw2
+    end
+
+    it 'is ==' do
+      expect(sw1 == sw2).to eq true
+      expect(sw2 == sw1).to eq true
+    end
+
+    it 'is eql' do
+      expect(sw1).to be_eql sw2
+      expect(sw2).to be_eql sw1
+    end
+  end
+
+  it 'is equal to its original value' do
+    expect(sw1).to eq value
+    expect(value).to eq sw1
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+begin
+  require 'gem_hadar/simplecov'
+  GemHadar::SimpleCov.start
+rescue LoadError
+end
+require 'rspec'
+require 'search_ui'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: search_ui
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.2.0
 platform: ruby
 authors:
 - Florian Frank
@@ -11,18 +11,32 @@ date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gem_hadar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.17.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.17.1
+- !ruby/object:Gem::Dependency
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.12'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.12'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -93,10 +107,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.0'
-description: |-
+description: |
   This library allows a user to search an array of objects
-    interactively in the console by matching the pattern a user inputs to an
-    array of objects and pick one of the remaining objects.
+  interactively in the console by matching the pattern a user inputs to an
+  array of objects and pick one of the remaining objects.
 email: flori@ping.de
 executables:
 - search_it
@@ -106,7 +120,9 @@ extra_rdoc_files:
 - lib/search_ui.rb
 - lib/search_ui/search.rb
 - lib/search_ui/version.rb
+- lib/search_ui/wrapper.rb
 files:
+- ".rspec"
 - Gemfile
 - LICENSE
 - README.md
@@ -116,7 +132,10 @@ files:
 - lib/search_ui.rb
 - lib/search_ui/search.rb
 - lib/search_ui/version.rb
+- lib/search_ui/wrapper.rb
 - search_ui.gemspec
+- spec/search_ui/wrapper_spec.rb
+- spec/spec_helper.rb
 homepage: https://github.com/flori/search_ui
 licenses:
 - MIT
@@ -139,7 +158,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Library to provide a user interface for searching in a console
-test_files: []
+test_files:
+- spec/search_ui/wrapper_spec.rb
+- spec/spec_helper.rb