Project	binding.repl
homepage	https://github.com/robgleeson/binding.repl
build

DESCRIPTION

binding.repl can start a number of different ruby repls at runtime. IRB, ripl, rib, and pry can be started at runtime in any scope that an instance of Binding closes over. the interface to start pry at runtime(binding.pry) has become known in a lot of circles and I thought it'd be cool to offer the same feature to other REPLs.

credit is due to John Mair(banisterfiend), the original author of pry, for seeing the potential in a repl that can be started at runtime and bound to a Binding with ease.

FEATURES

• start the repls IRB, Pry, Ripl, or Rib at runtime
• easily extended to support new repls.
• option to auto discover and start the first available repl
• default auto order is configurable via shell environment variable and at runtime.
• it can be enabled or disabled at runtime(like pry)
• light and small
• lazy require of repls (e.g: binding.repl.irb requires "irb").
  Kernel#require is never called more than once for a given repl.
• zero (gemspec) runtime dependencies.
• ships with a helpful doc/ directory

EXAMPLES

Any repl

class BlogsController < ApplicationController
  def show
    @blog = Blog.find(params[:id])
    binding.repl.{pry,irb,ripl,rib}
  end
end

Auto discovery

the first available repl can be loaded with binding.repl.auto or if you're in a hurry binding.repl!. the default order is defined as ["pry", "ripl", "rib", "irb"] but it can be changed at runtime and with shell environment variables.

class Foo
  # auto discover and start the first available repl.
  binding.repl.auto

  # same as 'binding.repl.auto' but in a hurry
  binding.repl!

  # change default load order of auto (irb first, etc..)
  BindingRepl.auto_order = ["irb", "ripl"]
end

DOCS

• SHELL ENVIRONMENT VARIABLES
  configure the default order used by binding.repl.auto with shell envionment variables.

see doc/shellvariables.md

• RUNTIME OPTIONS
  ripl, rib, and pry can be configured at runtime by passing a set of key-value pairs but IRB isn't as straight forward to configure and I haven't implemented any customization options for it yet.

see doc/runtimeoptions.md

• EXIT VALUES
  binding.repl and repl exit values.

see doc/exit_values.md

• ENABLE/DISABLE AT RUNTIME
  binding.repl can be enabled or disabled at runtime.

see doc/disableatruntime.md

DEPENDENCIES

binding.repl has 0 (gemspec) runtime dependencies.
irb, pry, rib, and ripl can be installed manually and binding.repl will delay their require until you try to start a repl at runtime(e.g: binding.repl.irb).

binding.repl has no load dependencies on external gems or the standard library.
it should be light to load and prevent eager-loading of dependencies you don't use at runtime.

MONKEY PATCHES

monkey patches on core classes aren't always cool and if not used carefully monkey patches can be bad news. binding.repl implements a few monkey patches on top of the Binding class to provide a familiar API to the one pry adopted and because to me i can't imagine something that would be better.

all of the monkey patches are documented incase you're curious:

• Binding.repl (class method , returns BindingRepl class)
• Binding#repl (instance method , returns instance of BindingRepl)
• Binding#repl! (instance method , calls BindingRepl#auto)

RUBIES

all of them (jruby, MRI, rubinius). 1.9+ and up only, though. check .travis.yml for a complete list.

CONTRIBUTE!

fork it, clone it, change!
open a pull request :)

some tips for working on the project:

cd $CLONED_DIR
bundle install
rake test # run tests

the isolation tests

tests inside test/isolation/ are meant to be run as standalone tests and are excluded from a regular test run through 'rake test'. the tests inside test/isolation/ make sure a require of "binding.repl" does not attempt to require any repls. the CI service TravisCI takes care of running each isolation test in its own process on every push.

INSTALL

gem install binding.repl

LEGAL

see LEGAL.txt