Module: Utils::IRB::Shell

Includes:
FileUtils, SearchUI, Tins::Find
Included in:
Object
Defined in:
lib/utils/irb.rb

Overview

A module that extends Regexp functionality with additional pattern matching and display capabilities.

Provides enhanced regexp operations including match highlighting and shell command integration.

Defined Under Namespace

Classes: ConstantWrapper, MethodWrapper, WrapperBase

Constant Summary collapse

Infinity =

I like to define the infinite.

1.0 / 0

Instance Method Summary collapse

Instance Method Details

#ai(query, command: false, respond: false, parse: false, dir: ?.) ⇒ String?

The ai method interacts with an Ollama chat service to process queries and optionally return responses.

This method constructs command-line arguments for the ollama_chat_send utility based on the provided options, executes the command with the query as input, and returns the response if requested.

Parameters:

  • the input query to send to the Ollama chat service

  • (defaults to: false)

    whether to treat the query as a command

  • (defaults to: false)

    whether to capture and return the response from the service

  • (defaults to: false)

    whether to parse the response

  • (defaults to: ?.)

    the directory to use for the operation

Returns:

  • the response from the Ollama chat service if respond is true, otherwise nil



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/utils/irb.rb', line 108

def ai(query, command: false, respond: false, parse: false, dir: ?.)
  dir = File.expand_path(dir)
  args = {
    ?r => respond,
    ?t => command,
    ?p => parse,
    ?d => dir,
  }
  args = args.map { |k, v|
    v == false and next
    v == true ? "-#{k}" : [ "-#{k}", v.to_s ]
  }.flatten.compact
  args.unshift 'ollama_chat_send'
  response = nil
  IO.popen(Shellwords.join(args), 'r+') do |io|
    io.write query
    io.close_write
    if respond
      response = io.read
    end
  end
  response
end

#capture_output(with_stderr = false) {|void| ... } ⇒ String

The capture_output method captures stdout and optionally stderr output during code execution.

This method temporarily redirects standard output (and optionally standard error) to a temporary file, executes the provided block, and then returns the captured output as a string.

Parameters:

  • (defaults to: false)

    whether to also capture standard error output

Yields:

  • (void) —

    the block of code to execute while capturing output

Returns:

  • the captured output as a string



511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
 
# File 'lib/utils/irb.rb', line 511

def capture_output(with_stderr = false)
  require 'tempfile'
  begin
    old_stdout, $stdout = $stdout, Tempfile.new('irb')
    if with_stderr
      old_stderr, $stderr = $stderr, $stdout
    end
    yield
  ensure
    $stdout, temp = old_stdout, $stdout
    with_stderr and $stderr = old_stderr
  end
  temp.rewind
  temp.read
end

#ed(*files) ⇒ Object

The ed method opens files for editing using the system editor.

This method provides a convenient way to edit files by invoking the configured editor. When called without arguments, it edits the current object’s representation. When called with file arguments, it edits those specific files.

Parameters:

  • an array of file paths to be edited



785
786
787
788
789
790
791
 
# File 'lib/utils/irb.rb', line 785

def ed(*files)
  if files.empty?
    $editor.full?(:edit, self)
  else
    $editor.full?(:edit, *files)
  end
end

#irb_all_class_instance_methods(obj = self) ⇒ Array

This method obtains the complete list of instance methods available for the specified object’s class, then processes them through the irb_wrap_methods helper to prepare them for interactive use in IRB.

Parameters:

  • (defaults to: self)

    the object whose class instance methods are to be retrieved

Returns:

  • an array of wrapped method objects suitable for IRB interaction



167
168
169
170
 
# File 'lib/utils/irb.rb', line 167

def irb_all_class_instance_methods(obj = self)
  methods = obj.class.instance_methods
  irb_wrap_methods obj, methods
end

#irb_all_instance_methods(modul = self) ⇒ Array

The irb_all_instance_methods method retrieves all instance methods defined on a module.

This method collects the instance methods from the specified module and wraps them for enhanced interactive exploration in IRB. It is designed to provide a more user-friendly interface for examining module methods within the interactive Ruby environment.

Parameters:

  • (defaults to: self)

    the module from which to retrieve instance methods

Returns:

  • an array of wrapped method objects suitable for IRB interaction



196
197
198
199
 
# File 'lib/utils/irb.rb', line 196

def irb_all_instance_methods(modul = self)
  methods = modul.instance_methods
  irb_wrap_methods modul, methods, true
end

#irb_all_methods(obj = self) ⇒ Array

The irb_all_methods method retrieves all methods available on an object.

This method collects all methods associated with the given object (including its singleton methods) and wraps them for enhanced interactive exploration in IRB. It provides a comprehensive list of methods that can be used to understand the object’s capabilities and interface.

Parameters:

  • (defaults to: self)

    the object whose methods are to be retrieved

Returns:

  • an array of wrapped method objects for interactive use



229
230
231
232
 
# File 'lib/utils/irb.rb', line 229

def irb_all_methods(obj = self)
  methods = obj.methods
  irb_wrap_methods obj, methods
end

#irb_class_instance_methods(obj = self) ⇒ Array

The irb_class_instance_methods method retrieves instance methods defined directly in the class of the given object, excluding inherited methods, and wraps them for enhanced interactive exploration in IRB environment.

Parameters:

  • (defaults to: self)

    the object whose class instance methods are to be retrieved

Returns:

  • an array of wrapped method objects suitable for IRB interaction



180
181
182
183
 
# File 'lib/utils/irb.rb', line 180

def irb_class_instance_methods(obj = self)
  methods = obj.class.instance_methods(false)
  irb_wrap_methods obj, methods
end

#irb_client ⇒ Utils::IRB::IRBServer

The irb_client method provides access to an IRB server client instance.

This method creates and returns a new IRB server client by first loading the configuration from standard paths and then using the configured server URL to initialize the client.

Returns:

  • a new IRB server client instance configured with the URL from the application’s configuration



772
773
774
775
 
# File 'lib/utils/irb.rb', line 772

def irb_client
  config = Utils::ConfigFile.new.tap(&:configure_from_paths)
  Utils::IRB::IRBServer.new(url: config.irb_server_url)
end

#irb_constants(modul = self) ⇒ Array<ConstantWrapper>

The irb_constants method retrieves and wraps all constants from a given module.

This method collects all constants defined in the specified module, creates ConstantWrapper instances for each constant, and returns them sorted in ascending order.

Parameters:

  • (defaults to: self)

    the module from which to retrieve constants

Returns:

  • an array of ConstantWrapper objects representing the constants in the module, sorted alphabetically



476
477
478
 
# File 'lib/utils/irb.rb', line 476

def irb_constants(modul = self)
  modul.constants.map { |c| ConstantWrapper.new(modul.const_get(c), c) }.sort
end

#irb_instance_methods(modul = self) ⇒ Array

Return instance methods defined in module modul without the inherited/mixed in methods. The irb_instance_methods method retrieves instance methods defined directly in a module.

This method fetches all instance methods that are explicitly defined within the specified module, excluding inherited methods. It then wraps these methods for enhanced interactive exploration within the IRB environment.

Parameters:

  • (defaults to: self)

    the module from which to retrieve instance methods

Returns:

  • an array of wrapped method objects suitable for IRB interaction



212
213
214
215
 
# File 'lib/utils/irb.rb', line 212

def irb_instance_methods(modul = self)
  methods = modul.instance_methods(false)
  irb_wrap_methods modul, methods, true
end

#irb_load!(glob = ENV.fetch('UTILS_IRB_LOAD_GLOB', 'lib/**/*.rb')) ⇒ Boolean

Note:

This method uses fuzzy matching to help find files when typing partial names. It respects the terminal height to limit the number of displayed results.

The irb_load! method loads Ruby files by their names into the current environment through an interactive selection interface.

This method takes a glob pattern and finds matching Ruby files, then presents an interactive search interface for selecting which file to load. It ensures that each file is loaded only once by tracking loaded files using their paths. The method outputs messages to standard error indicating which file has been successfully loaded.

Examples:

# Load a file interactively with default glob pattern
irb_load!

# Load files matching a custom pattern
irb_load!('app/models/**/*.rb')

# Set environment variable for default pattern
ENV['UTILS_IRB_LOAD_GLOB'] = 'lib/**/*.rb'
irb_load!

Parameters:

  • (defaults to: ENV.fetch('UTILS_IRB_LOAD_GLOB', 'lib/**/*.rb'))

    the glob pattern to search for Ruby files (defaults to ENV or ‘lib/*/.rb’)

Returns:

  • true if a file was successfully loaded, false if no file was selected or loaded

See Also:

  • for the interactive search interface implementation
  • for the fuzzy matching algorithm


710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
 
# File 'lib/utils/irb.rb', line 710

def irb_load!(glob = ENV.fetch('UTILS_IRB_LOAD_GLOB', 'lib/**/*.rb'))
  files = Dir.glob(glob)
  found = Search.new(
    match: -> answer {
      matcher = Amatch::PairDistance.new(answer.downcase)
      matches = files.map { |n| [ n, -matcher.similar(n.downcase) ] }.
        sort.select { _2 < 0 }.sort_by(&:last).map(&:first)
      matches.empty? and matches = files
      matches.first(Tins::Terminal.lines - 1)
    },
    query: -> _answer, matches, selector {
      matches.each_with_index.
      map { |m, i| i == selector ? "→ " + Search.on_blue(m) : "  " + m } * ?\n
    },
    found: -> _answer, matches, selector {
      matches[selector]
    },
    output: STDOUT
  ).start
  found or return false
  load found
end

#irb_methods(obj = self) ⇒ Array

The irb_methods method retrieves instance methods defined in the class hierarchy excluding those inherited from ancestor classes.

This method computes a list of instance methods that are directly defined in the class of the given object, excluding any methods that are inherited from its superclass or modules. It then wraps these methods for enhanced display in IRB.

Parameters:

  • (defaults to: self)

    the object whose class methods are to be examined

Returns:

  • an array of wrapped method objects for display in IRB



245
246
247
248
249
250
 
# File 'lib/utils/irb.rb', line 245

def irb_methods(obj = self)
  methods = obj.class.ancestors[1..-1].inject(obj.methods) do |all, a|
    all -= a.instance_methods
  end
  irb_wrap_methods obj, methods
end

#irb_open(url = nil, &block) ⇒ Object

The irb_open method opens a URL or executes a block to capture output and open it.

This method provides a way to open URLs or capture the output of a block and open it in the default application. If a URL is provided, it directly opens the URL. If a block is given, it captures the output of the block, writes it to a temporary file, and opens that file. If neither is provided, it raises an error.

Parameters:

  • (defaults to: nil)

    the URL to open

  • the block to capture output from



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/utils/irb.rb', line 143

def irb_open(url = nil, &block)
  case
  when url
    system 'open', url
  when block
    Tempfile.open('wb') do |t|
      t.write capture_output(&block)
      t.rewind
      system 'open', t.path
    end
  when url = receiver_unless_main(method(__method__))
    irb_open url
  else
    raise ArgumentError, 'need an url or block'
  end
end

#irb_read(filename, chunk_size = 8_192) {|chunk| ... } ⇒ String?

The irb_read method reads the contents of a file either entirely or in chunks. When a block is provided, it reads the file in chunks of the specified size and yields each chunk to the block. If no block is given, it reads the entire file content at once and returns it as a string.

block is provided

otherwise nil

Parameters:

  • the path to the file to be read

  • (defaults to: 8_192)

    the size of each chunk to read when a

Yields:

  • (chunk) —

    yields each chunk of the file to the block

Yield Parameters:

  • chunk (String) —

    a portion of the file content

Returns:

  • the entire file content if no block is given,



665
666
667
668
669
670
671
672
673
674
675
676
 
# File 'lib/utils/irb.rb', line 665

def irb_read(filename, chunk_size = 8_192)
  if block_given?
    File.open(filename) do |file|
      until file.eof?
        yield file.read(chunk_size)
      end
    end
    nil
  else
    File.read filename
  end
end

#irb_server ⇒ Utils::IRB::IRBServer

The irb_server method provides access to an IRB server instance for interactive Ruby sessions.

This method ensures that a single IRB server instance is created and started for the current process, loading the configuration from standard paths and using the configured server URL.

Returns:

  • the IRB server instance, initialized and started if not already running



742
743
744
745
746
747
748
 
# File 'lib/utils/irb.rb', line 742

def irb_server
  unless @irb_server
    config = Utils::ConfigFile.new.tap(&:configure_from_paths)
    @irb_server = Utils::IRB::IRBServer.new(url: config.irb_server_url).start
  end
  @irb_server
end

#irb_server_stop ⇒ nil

The irb_server_stop method sends a stop command to the IRB server client.

This method accesses the IRB client instance and invokes the stop_server method on it, which gracefully shuts down the IRB server process.

Returns:

  • always returns nil after sending the stop command to the server



759
760
761
 
# File 'lib/utils/irb.rb', line 759

def irb_server_stop
  irb_client.stop_server
end

#irb_singleton_methods(obj = self) ⇒ Array

The irb_singleton_methods method retrieves singleton methods associated with an object.

This method collects all singleton methods defined on the specified object, excluding inherited methods, and prepares them for display in an interactive Ruby environment.

Parameters:

  • (defaults to: self)

    the object whose singleton methods are to be retrieved

Returns:

  • an array of singleton method names associated with the object



262
263
264
 
# File 'lib/utils/irb.rb', line 262

def irb_singleton_methods(obj = self)
  irb_wrap_methods obj, obj.methods(false)
end

#irb_subclasses(klass = self) ⇒ Array<ConstantWrapper>

The irb_subclasses method retrieves and wraps subclass information for a given class.

This method fetches the subclasses of the specified class and creates ConstantWrapper instances for each subclass, allowing them to be sorted and displayed in a structured format.

representing the subclasses

Parameters:

  • (defaults to: self)

    the class object to retrieve subclasses from

Returns:

  • an array of ConstantWrapper objects



491
492
493
 
# File 'lib/utils/irb.rb', line 491

def irb_subclasses(klass = self)
  klass.subclasses.map { |c| ConstantWrapper.new(eval(c), c) }.sort
end

#irb_time(n = 1) {|block| ... } ⇒ Object

The irb_time method measures the execution time of a block and outputs the duration to standard error.

to 1

Parameters:

  • (defaults to: 1)

    the number of times to execute the block, defaults

Yields:

  • (block) —

    the block to be executed and timed



552
553
554
555
556
557
558
559
560
561
562
563
 
# File 'lib/utils/irb.rb', line 552

def irb_time(n = 1, &block)
  s = Time.now
  n.times(&block)
  d = Time.now - s
ensure
  d ||= Time.now - s
  if n == 1
    warn "Took %.3fs seconds." % d
  else
    warn "Took %.3fs seconds, %.3fs per call (avg)." % [ d, d / n ]
  end
end

#irb_time_result(n = 1) {|i| ... } ⇒ Object

The irb_time_result method executes a block n times while measuring execution time and returns the result of the last execution.

Parameters:

  • (defaults to: 1)

    the number of times to execute the block

Yields:

  • (i)

Returns:

  • the result of the last block execution



573
574
575
576
577
 
# File 'lib/utils/irb.rb', line 573

def irb_time_result(n = 1)
  r = nil
  irb_time(n) { |i| r = yield(i) }
  r
end

#irb_time_watch(duration = 1) {|i| ... } ⇒ Object

The irb_time_watch method monitors and reports performance metrics over time.

This method continuously measures the output of a provided block, calculating differences and rates of change between successive measurements. It tracks these metrics and displays them with timing information, useful for observing how values evolve during execution.

measurements

Parameters:

  • (defaults to: 1)

    the time interval in seconds between

Yields:

  • (i) —

    the block to be measured, receiving the iteration count as an argument



591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
 
# File 'lib/utils/irb.rb', line 591

def irb_time_watch(duration = 1)
  start = Time.now
  pre = nil
  avg = Hash.new
  i = 0
  fetch_next = -> cur do
    pre = cur.map(&:to_f)
    i += 1
    sleep duration
  end
  loop do
    cur = [ yield(i) ].flatten
    unless pre
      fetch_next.(cur)
      redo
    end
    expired = Time.now - start
    diffs = cur.zip(pre).map { |c, p| c - p }
    rates = diffs.map { |d| d / duration }
    durs = cur.zip(rates).each_with_index.map { |(c, r), i|
      if r < 0
        x = c.to_f / -r
        a = avg[i].to_f
        a -= a / 2
        a += x / 2
        d = Tins::Duration.new(a)
        ds = d.to_s
        ds.singleton_class { define_method(:to_f) { d.to_f } }
        avg[i] = ds
      end
      avg[i]
    }
    warn "#{expired} #{cur.zip(diffs, rates, durs) * ' '} 𝝙 / per sec."
    fetch_next.(cur)
    sleep duration
  end
end

#irb_toggle_logging ⇒ TrueClass, FalseClass

The irb_toggle_logging method toggles the logging configuration for ActiveRecord.

This method manages the logger setting for ActiveRecord by switching between a custom logger and the previously configured logger. It returns true when switching to the custom logger, and false when reverting to the original logger.

the custom logger, false if it was reverted to the original logger

Returns:

  • true if the logger was switched to



805
806
807
808
809
810
811
812
813
814
815
 
# File 'lib/utils/irb.rb', line 805

def irb_toggle_logging
  require 'logger'
  if ActiveRecord::Base.logger != $logger
    $old_logger = ActiveRecord::Base.logger
    ActiveRecord::Base.logger = $logger
    true
  else
    ActiveRecord::Base.logger = $old_logger
    false
  end
end

#irb_wrap_methods(obj = self, methods = methods(), modul = false) ⇒ Array

The irb_wrap_methods method creates wrapped method objects for introspection.

This method takes a set of method names and wraps them in a way that allows for easier inspection and display within an IRB session. It handles potential errors during the wrapping process by rescuing exceptions and filtering out invalid entries.

Parameters:

  • (defaults to: self)

    the object whose methods are being wrapped

  • (defaults to: methods())

    the array of method names to wrap

  • (defaults to: false)

    flag indicating if the methods are module methods

Returns:

  • an array of wrapped method objects sorted in ascending order



278
279
280
281
282
 
# File 'lib/utils/irb.rb', line 278

def irb_wrap_methods(obj = self, methods = methods(), modul = false)
  methods.map do |name|
    MethodWrapper.new(obj, name, modul) rescue nil
  end.compact.sort!
end

#irb_write(filename, text = nil) {|| ... } ⇒ Object

The irb_write method writes text to a file or executes a block to generate content for writing.

This method provides a convenient way to write content to a file, either by passing the text directly or by executing a block that generates the content. It uses secure file writing to ensure safety.

written nil if using a block

Parameters:

  • the path to the file where content will be

  • (defaults to: nil)

    the text content to write to the file, or

Yields:

  • () —

    a block that generates content to be written to the file



642
643
644
645
646
647
648
 
# File 'lib/utils/irb.rb', line 642

def irb_write(filename, text = nil, &block)
  if text.nil? && block
    File.secure_write filename, nil, 'wb', &block
  else
    File.secure_write filename, text, 'wb'
  end
end

#less(with_stderr = false) {|void| ... } ⇒ Object

Use pager on the output of the commands given in the block. The less method executes a block and outputs its result through the pager.

This method runs the provided block in a controlled environment, captures its output, and streams that output through the system’s configured pager for display.

Parameters:

  • (defaults to: false)

    whether to include standard error in the capture

Yields:

  • (void) 


537
538
539
540
541
542
543
 
# File 'lib/utils/irb.rb', line 537

def less(with_stderr = false, &block)
  IO.popen($pager, 'w') do |f|
    f.write capture_output(with_stderr, &block)
    f.close_write
  end
  nil
end

#ri(*patterns, doc: 'ri') ⇒ Object

The ri method invokes the ri documentation tool to display help information for the specified patterns. It automatically determines the pattern to search for when none are provided. The method handles different types of patterns including modules, objects that respond to to_str, and other objects. Documentation is displayed through the system’s ri command with output piped to the pager.

Parameters:

  • the patterns to search for in the documentation

  • (defaults to: 'ri')

    the documentation command to execute (defaults to ‘ri’)



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/utils/irb.rb', line 64

def ri(*patterns, doc: 'ri')
  patterns.empty? and
    receiver_unless_main(method(__method__)) do |pattern|
      return ri(pattern, doc: doc)
    end
  patterns.map! { |p|
    case
    when Module === p
      p.name
    when p.respond_to?(:to_str)
      p.to_str
    else
      p.class.name
    end
  }
  system "#{doc} #{patterns.map { |p| "'#{p}'" } * ' ' } | #$pager"
end

#yri(*patterns) ⇒ Object

The yri method invokes the ri documentation tool with yri as the documenter to display help information for the specified patterns.

Parameters:

  • the patterns to look up documentation for



86
87
88
 
# File 'lib/utils/irb.rb', line 86

def yri(*patterns)
  ri(*patterns, doc: 'yri')
end