Skip to content

Extends IRB by providing additional productivity enhancements.

License

Notifications You must be signed in to change notification settings

bkuhlmann/irb-kit

Repository files navigation

IRB Kit

This gem is a collection of IRB Extensions for enhancing IRB with additional commands, helpers, prompts, and more. Add this gem to your IRB configuration (i.e. irbrc) to get all these enhancements immediately while keeping your IRB configuration slim and readable.

Features

  • Provides custom helpers.

  • Provides dynamic prompt based on environment.

Requirements

  1. Ruby.

  2. IRB.

  3. A solid understanding of Interactive Ruby.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install irb-kit --trust-policy HighSecurity

To install without security, run:

gem install irb-kit

You can also add the gem directly to your project:

bundle add irb-kit

Once the gem is installed, you only need to require it:

require "irb/kit"

Usage

To use, add the following to your ~/.config/irb/irbrc configuration (or ~/.irbrc if not using XDG).

begin
  require "irb/kit"
rescue LoadError => error
  puts "ERROR: #{error.message.capitalize}."
end

This ensures this gem is fully loaded in order to enhance IRB further. Otherwise, an error is displayed if you are in a Ruby project that doesn’t have this gem as a dependency. To customize, read on.

Quick Start

If you’d like all the bells and whistles fully enabled, add the following to your IRB configuration (as discussed above):

begin
  require "irb/kit"

  IRB::Kit.register_helpers :all

  IRB.conf[:PROMPT] ||= {}

  IRB.conf[:PROMPT][:DEMO] = {
    PROMPT_I: "[#{IRB::Kit.prompt}]> ",
    PROMPT_N: "[#{IRB::Kit.prompt}]| ",
    PROMPT_C: "[#{IRB::Kit.prompt}]| ",
    PROMPT_S: "[#{IRB::Kit.prompt}]%l ",
    RETURN: "=> %s\n"
  }

  IRB.conf[:PROMPT_MODE] = :DEMO
rescue LoadError => error
  puts "ERROR: #{error.message.capitalize}."
end

The above enables all helpers and configures your prompt for Ruby, Hanami, and Rails environments.

💡 Use of :DEMO, while functional, is meant to be replaced with the name of your organization or personal identity. So please ensure you replace both occurrences of :DEMO with your own unique identifier.

Commands

At the moment, this gem does not provide any custom commands but might in the future. See IRB Extensions documentation for further details.

Helpers

Several custom helpers are provided for you by this gem. Each is listed below as found when using help within an IRB console:

Helper methods
  clip           Copy input to macOS clipboard.
  csource        Find a constant's source location.
  msource        Find an object method's source location.
  paste          Paste last entry from macOS clipboard.
  search         Search an object's methods by pattern.

To enable all of these helpers, use IRB::Kit.register_helpers :all. This is the same as using:

IRB::Kit.register_helpers(*%i[clip csource msource paste search])

Knowing this, you can disable all helpers entirely, use only the ones you care about, or enable all of them at once. The following explains each helper in greater detail.

clip

Use this helper to copy output into the macOS clipboard. Example:

clip (1..3).to_a
# 1
# 2
# 3

clip 1, 2, 3
# 1
# 2
# 3

clip Object.new
# #<Object:0x000000012a46eaf8>

This helper accepts any number of arguments. Each is delimited by a new line for pasting into another application.

csource

Use this helper, short for constant source, to find the source location of a constant. Example:

csource :RUBY_DESCRIPTION   # "$HOME/.cache/frum/versions/3.3.2/bin/ruby:0"
csource "RUBY_DESCRIPTION"  # "$HOME/.cache/frum/versions/3.3.2/bin/ruby:0"

You can use a symbol or a string when looking up the source location of a constant. The output is formatted so you can use CONTROL + <click> to immediately view the source at the exact line number in consoles like iTerm2.

msource

Use this helper, short for method source, to find the source location of a method. Example:

msource IRB, :start   # "$HOME/.cache/frum/versions/3.3.2/lib/ruby/3.3.0/irb.rb:893"
msource IRB, "start"  # "$HOME/.cache/frum/versions/3.3.2/lib/ruby/3.3.0/irb.rb:893"

The first argument is the object you want to message while the second argument is the object’s method you want to find the source code location for. You can also use a symbol or string for the method.

The output is formatted so you can use CONTROL + <click> to immediately view the source at the exact line number in consoles like iTerm2.

paste

Use this helper to paste the last entry from your macOS clipboard into your console. For example, assuming the text This is a demonstration is in your clipboard, you’d see the following:

paste
# "This is a demonstration"

This helper takes no arguments.

Use this helper to search for methods on an object. Example:

search Module, "protected"
# [
#    protected_instance_methods(*args) #<Class:Module> (Class)
#     protected_method_defined?(*arg1) #<Class:Module> (Module)
#             protected_methods(*args) #<Class:Module> (Object)
# ]

search Module, /_defined/
# [
#       class_variable_defined?(arg1)  #<Class:Module> (Module)
#                const_defined?(*arg1) #<Class:Module> (Module)
#    instance_variable_defined?(arg1)  #<Class:Module> (Kernel)
#               method_defined?(*arg1) #<Class:Module> (Module)
#       private_method_defined?(*arg1) #<Class:Module> (Module)
#     protected_method_defined?(*arg1) #<Class:Module> (Module)
#        public_method_defined?(*arg1) #<Class:Module> (Module)
# ]

This helper takes two arguments. The first is the object you want to search on and the second argument is the string or regular expression of the methods to search for.

Prompt

A dynamic prompt, based on environment, is provided for you. The code — as shown above — for configuring IRB to make use of this custom prompt is:

IRB.conf[:PROMPT][:DEMO] = {
  PROMPT_I: "[#{IRB::Kit.prompt}]> ",
  PROMPT_N: "[#{IRB::Kit.prompt}]| ",
  PROMPT_C: "[#{IRB::Kit.prompt}]| ",
  PROMPT_S: "[#{IRB::Kit.prompt}]%l ",
  RETURN: "=> %s\n"
}

IRB.conf[:PROMPT_MODE] = :DEMO

You only need to swap out the :DEMO key with a key that identifies you as you see fit.

At the moment, the prompt dynamically detects the following environments:

Additionally, when working with the Hanami and/or Rails frameworks, environment information will be color coded as follows:

  • Non-Production: Displays as green for any environment other than production.

  • Production: Displays as red but only for a production environment.

The following screenshots demonstrate what the prompt looks like in different environments:

Ruby (with Git)

Screenshot

Ruby (without Git)

Screenshot

Hanami (development)

Screenshot

Hanami (production)

Screenshot

Rails

Screenshot

Development

To contribute, run:

git clone https://github.com/bkuhlmann/irb-kit
cd irb-kit
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

Credits

About

Extends IRB by providing additional productivity enhancements.

Topics

Resources

License

Stars

Watchers

Forks

Sponsor this project

 

Packages

No packages published

Languages