Module: Utils::IRB::Shell

Includes:
FileUtils, 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

#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:

  • with_stderr (TrueClass, FalseClass) (defaults to: false) —

    whether to also capture standard error output

Yields:

  • (void) —

    the block of code to execute while capturing output

Returns:

  • (String) —

    the captured output as a string



465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
 
# File 'lib/utils/irb.rb', line 465

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:

  • files (Array) —

    an array of file paths to be edited



672
673
674
675
676
677
678
 
# File 'lib/utils/irb.rb', line 672

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:

  • obj (Object) (defaults to: self) —

    the object whose class instance methods are to be retrieved

Returns:

  • (Array) —

    an array of wrapped method objects suitable for IRB interaction



121
122
123
124
 
# File 'lib/utils/irb.rb', line 121

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:

  • modul (Object) (defaults to: self) —

    the module from which to retrieve instance methods

Returns:

  • (Array) —

    an array of wrapped method objects suitable for IRB interaction



150
151
152
153
 
# File 'lib/utils/irb.rb', line 150

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:

  • obj (Object) (defaults to: self) —

    the object whose methods are to be retrieved

Returns:

  • (Array) —

    an array of wrapped method objects for interactive use



183
184
185
186
 
# File 'lib/utils/irb.rb', line 183

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:

  • obj (Object) (defaults to: self) —

    the object whose class instance methods are to be retrieved

Returns:

  • (Array) —

    an array of wrapped method objects suitable for IRB interaction



134
135
136
137
 
# File 'lib/utils/irb.rb', line 134

def irb_class_instance_methods(obj = self)
  methods = obj.class.instance_methods(false)
  irb_wrap_methods obj, methods
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:

  • modul (Object) (defaults to: self) —

    the module from which to retrieve constants

Returns:

  • (Array<ConstantWrapper>) —

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



430
431
432
 
# File 'lib/utils/irb.rb', line 430

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:

  • modul (Object) (defaults to: self) —

    the module from which to retrieve instance methods

Returns:

  • (Array) —

    an array of wrapped method objects suitable for IRB interaction



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

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

#irb_load!(*files) ⇒ nil

The irb_load! method loads Ruby files by their names into the current environment.

This method takes one or more file names and attempts to locate and load the corresponding Ruby files from the current directory and its subdirectories. It ensures that each file is loaded only once by tracking loaded files using their MD5 checksums. The method outputs messages to standard error indicating which files have been successfully loaded.

Parameters:

  • files (Array<String>) —

    the names of the Ruby files to be loaded

Returns:

  • (nil) —

    always returns nil after processing all specified files



645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
 
# File 'lib/utils/irb.rb', line 645

def irb_load!(*files)
  files = files.map { |f| f.gsub(/(\.rb)?\Z/, '.rb') }
  loaded = {}
  for file in files
    catch :found do
      Find.find('.') do |f|
        File.directory?(f) and next
        md5_f = Utils::MD5.md5(f)
        if f.end_with?(file) and !loaded[md5_f]
          Kernel.load f
          loaded[md5_f] = true
          STDERR.puts "Loaded '#{f}'."
        end
      end
    end
  end
  nil
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:

  • obj (Object) (defaults to: self) —

    the object whose class methods are to be examined

Returns:

  • (Array) —

    an array of wrapped method objects for display in IRB



199
200
201
202
203
204
 
# File 'lib/utils/irb.rb', line 199

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:

  • url (String, nil) (defaults to: nil) —

    the URL to open

  • block (Proc, nil) —

    the block to capture output from



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/utils/irb.rb', line 97

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:

  • filename (String) —

    the path to the file to be read

  • chunk_size (Integer) (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:

  • (String, nil) —

    the entire file content if no block is given,



619
620
621
622
623
624
625
626
627
628
629
630
 
# File 'lib/utils/irb.rb', line 619

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_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:

  • obj (Object) (defaults to: self) —

    the object whose singleton methods are to be retrieved

Returns:

  • (Array) —

    an array of singleton method names associated with the object



216
217
218
 
# File 'lib/utils/irb.rb', line 216

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:

  • klass (Object) (defaults to: self) —

    the class object to retrieve subclasses from

Returns:



445
446
447
 
# File 'lib/utils/irb.rb', line 445

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:

  • n (Integer) (defaults to: 1) —

    the number of times to execute the block, defaults

Yields:

  • (block) —

    the block to be executed and timed



506
507
508
509
510
511
512
513
514
515
516
517
 
# File 'lib/utils/irb.rb', line 506

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:

  • n (Integer) (defaults to: 1) —

    the number of times to execute the block

Yields:

  • (i)

Returns:

  • (Object) —

    the result of the last block execution



527
528
529
530
531
 
# File 'lib/utils/irb.rb', line 527

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:

  • duration (Integer) (defaults to: 1) —

    the time interval in seconds between

Yields:

  • (i) —

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



545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
 
# File 'lib/utils/irb.rb', line 545

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:

  • (TrueClass, FalseClass) —

    true if the logger was switched to



692
693
694
695
696
697
698
699
700
701
702
 
# File 'lib/utils/irb.rb', line 692

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:

  • obj (Object) (defaults to: self) —

    the object whose methods are being wrapped

  • methods (Array) (defaults to: methods()) —

    the array of method names to wrap

  • modul (TrueClass, FalseClass) (defaults to: false) —

    flag indicating if the methods are module methods

Returns:

  • (Array) —

    an array of wrapped method objects sorted in ascending order



232
233
234
235
236
 
# File 'lib/utils/irb.rb', line 232

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:

  • filename (String) —

    the path to the file where content will be

  • text (String, nil) (defaults to: nil) —

    the text content to write to the file, or

Yields:

  • () —

    a block that generates content to be written to the file



596
597
598
599
600
601
602
 
# File 'lib/utils/irb.rb', line 596

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:

  • with_stderr (TrueClass, FalseClass) (defaults to: false) —

    whether to include standard error in the capture

Yields:

  • (void) 


491
492
493
494
495
496
497
 
# File 'lib/utils/irb.rb', line 491

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:

  • patterns (Array) —

    the patterns to search for in the documentation

  • doc (String) (defaults to: 'ri') —

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



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/utils/irb.rb', line 60

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:

  • patterns (Array<String>) —

    the patterns to look up documentation for



82
83
84
 
# File 'lib/utils/irb.rb', line 82

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