ripl

== Description

ripl is a light shell that encourages common middleware for shells i.e. rack for ruby shells. It is also a modular alternative to irb. Like irb, it loads ~/.irbrc, has autocompletion and keeps history in ~/.irb_history. Unlike irb, it is highly customizable via plugins and supports commands i.e. {ripl-play}[https://github.com/cldwalker/ripl-play#readme]. This customizability makes it easy to build custom shells (i.e. for a gem or application) and complex shells (i.e. for the {web}[https://github.com/cldwalker/nirvana#readme]). Works on ruby 1.8.7 and greater.

== Install

If you have {readline}[http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html], install ripl with:

gem install ripl

If you don't have readline, first install ripl with {a pure ruby readline}[https://github.com/luislavena/rb-readline#readme]:

gem install ripl rb-readline -- --without-readline

Then, add the following to ~/.riplrc:

Ripl.config[:readline] = 'rb-readline'
Ripl.config[:completion] = {:readline => :ruby }

== Setup

To make your first ripl experience smoother, install these plugins:

# Adds multi-line evaluation
gem install ripl-multi_line

# Ignore errors caused by irb-specific configuration in ~/.irbrc
gem install ripl-irb

# Add to ~/.riplrc
require 'ripl/multi_line'
require 'ripl/irb'

== Usage

$ ripl
>> ...

To view ripl's man page:

# If installed with rubygems
$ gem install gem-man
$ gem man ripl

# If installed with rip, man page is automatically installed
$ man ripl

== Coming from irb

When first trying ripl, you may experience errors in your ~/.irbrc due to an irb-specific configuration. In order to have ripl and irb coexist peacefully, you should silence these errors. To silence them without touching your ~/.irbrc, install the {ripl-irb}[https://github.com/cldwalker/ripl-irb#readme] gem. This ripl plugin fakes irb's existence and points to ripl equivalents for your irb configurations. Otherwise, if you don't mind modifying ~/.irbrc, wrap your irb-specific configuration in a block as follow:

if defined? IRB
  IRB.conf[:BLAH] = 'blah'
  # ...
end

== Comparison to Irb

• Similar to irb
  • Reads ~/.irbrc on startup
  • Appends to ~/.irb_history on exit
  • Autocompletion (from bond)
  • _ for last result
  • Type exit, quit or press Ctrl-D to exit
  • 6 common commandline options: -f, -r, -I, -d, -h, -v
  • IRB.conf -> Ripl.config
  • Handles Ctrl-C quietly
• Enhancements over irb
  • ~290 lines (doc included) vs irb's 5000+ lines
  • Easily extendable with plugins
  • Tests and documentation!
  • Customizable completion and completion of method arguments (from bond)
  • Easy to create custom shells for gems and apps i.e. Ripl.start
  • Easy to create and invoke ripl commands
  • Create console commands in a simple, modular way
  • Custom commandline options can be added via a plugin
  • ~/.irbrc errors caught
  • Well-integrated internationalization (see {ripl-i18n}[https://github.com/cldwalker/ripl-i18n#readme])
• Different from irb
  • No multi-line evaluation by default (but there is a plugin, {ripl-multi_line}[https://github.com/janlelis/ripl-multi_line#readme]).
  • No irb subsessions or workspaces (though ripl has jumps via {ripl-commands}[https://github.com/cldwalker/ripl-commands#readme])
  • Some IRB.conf features aren't supported yet (see {ripl-irb}[https://github.com/cldwalker/ripl-irb#readme] for details)

Note: Irb features not in ripl can be implemented as plugins.

== Plugins

A ripl plugin is a module that is included into Ripl::Shell or extended into Ripl::Runner. Being simply modules, they can be packaged as gems and reused across shells as needed. ripl highly encourages plugins by loading them as early as possible and allowing them to extend most of ripl's functionality.

As an example plugin, let's color error messages red:

require 'ripl'

# To try place in ~/.riplrc
module Ripl
  module RedError
    def format_error(error)
      "\e[31m#{super}\e[m"
    end
  end
end
Ripl::Shell.include Ripl::RedError

Note this plugin extends format_error() by invoking the original format_error() with super. This is possible for any method that is available for extension by plugins. To see what methods are available for extension, see Ripl::Shell::API and Ripl::Runner::API.

If we want to add a config for this plugin, we can simply add a key to Ripl.config that matches the underscored version of the plugin name i.e. Ripl.config[:red_error].

For available plugins, see Ripl Plugins below.

== Configuration

Since ripl is highly customizable, it loads ~/.riplrc before it does anything. This ruby file should require and/or define plugins. Any ripl configurations via Ripl.config should also be done here. For an example ~/.riplrc, see {mine}[https://github.com/cldwalker/dotfiles/tree/master/.riplrc].

== Create Custom Shells

Creating and starting a custom shell is as simple as:

require 'ripl'
# Define plugins, load files, etc...
Ripl.start

Ripl.start takes options to customize your shell. For example if you wanted to start on a specific binding:

Ripl.start :binding => MyClass.instance_eval{ binding }

== Create Commands

If you want to invoke your custom shell with ripl, make it a ripl command. To create one, create an executable in the format ripl- and make sure it's in your shell's $PATH. For example, the file ripl-my_gem would be invoked with ripl my_gem. Note that with your command you can take arguments and parse your options as you please. For an example command, see {ripl-rails}[https://github.com/cldwalker/ripl-rails#readme].

== Credits

• janlelis and godfat for bug fix and tweaks
• JoshCheek for bug fixes
• postmodern for windows fixes and no history support

== Bugs/Issues

Please report them {on github}[https://github.com/cldwalker/ripl/issues].

== Contributing

{See here}[http://tagaholic.me/contributing.html]

== Ripl Plugins

• {ripl-multi_line}[https://github.com/janlelis/ripl-multi_line#readme]: evaluate multiple lines
• {ripl-ripper}[https://github.com/cldwalker/ripl-ripper#readme]: evaluate multiple lines with ripper
• {ripl-rails}[https://github.com/cldwalker/ripl-rails#readme]: console for rails
• {ripl-rack}[https://github.com/cldwalker/ripl-rack#readme]: console for rack
• {ripl-play}[https://github.com/cldwalker/ripl-play#readme]: play back and record input into ripl
• {ripl-debug}[https://github.com/cldwalker/ripl-debug#readme]: automatically debugs a failed eval
• {ripl-after_rc}[https://github.com/cldwalker/ripl-after_rc#readme]: provide blocks to run after ~/.irbrc is loaded
• {ripl-irb}[https://github.com/cldwalker/ripl-irb#readme]: smooths transition from irb
• {ripl-i18n}[https://github.com/cldwalker/ripl-i18n#readme]: translates ripl to your language
• {ripl-commands}[https://github.com/cldwalker/ripl-commands#readme]: adds ripl commands similar to irb's commands
• {ripl-shell_commands}[https://github.com/postmodern/ripl-shell_commands#readme]: adds support for !ls shell commands.
• {ripl-color_error}[https://github.com/cldwalker/ripl-color_error#readme]: colorize errors
• {ripl-color_streams}[https://github.com/janlelis/ripl-color_streams#readme]: colorizes stderr + stdout
• {ripl-color_result}[https://github.com/janlelis/ripl-color_result#readme]: colorizes results
• {ripl-auto_indent}[https://github.com/janlelis/ripl-auto_indent#readme]: auto indents multi-line input
• {ripl-hirb}[https://github.com/cldwalker/hirb#readme]: comes with hirb to make it a proper riplzen
• {ripl-hijack}[https://github.com/cldwalker/ripl-hijack#readme]: ripl console to a ruby process
• {ripl-misc}[https://github.com/cldwalker/ripl-misc#readme]: a playground for ripl plugins
• {ripl-profiles}[https://github.com/janlelis/ripl-profiles#readme]: load ripl profiles with a --profile option
• {ripl-short_errors}[https://github.com/janlelis/ripl-misc/blob/master/lib/ripl/short_errors.rb]: display short backtrace
• {ripl-rocket}[https://github.com/janlelis/ripl-rocket#readme]: outputs ripl result as a hash rocket
• {ripl-padrino}[https://github.com/achiu/ripl-padrino#readme]: console for padrino
• {ripltools}[https://github.com/janlelis/ripltools#readme]: a collection of ripl plugins
• {ripl-rc}[https://github.com/godfat/ripl-rc#readme]: ripl plugins for debugging, class-based coloring and more
• {ripl-em}[https://github.com/cldwalker/ripl-em#readme]: interact with EM libraries asynchronously
• {ripl-readline-em}[https://github.com/pmahoney/ripl-readline-em#readme]: another async EM interface

== Ripl Shells

Shells built on top of ripl:

• {nirvana}[https://github.com/cldwalker/nirvana#readme]: A ruby web shell complete with autocomplete
• {fresh}[https://github.com/janlelis/fresh#readme]: An interesting ruby/system hybrid shell
• {ripl-johnson}[https://github.com/cldwalker/ripl-johnson#readme]: A js shell based on johnson (firefox tracemonkey)
• {ronin}[http://ronin-ruby.github.io]: An exploit development platform using ripl for its console
• {tux}[https://github.com/cldwalker/tux#readme]: A sinatra shell
• {rack-webconsole}[https://github.com/codegram/rack-webconsole#readme]: A rack middleware that adds a web shell to any rack app

== More Ripl Links

• {ripl screencast}[http://www.rubypulse.com/ep0.51_ripl.html]
• {overview of ripl features}[http://rbjl.net/44-ripl-why-should-you-use-an-irb-alternative]
• {slides at euroko about ruby consoles}[http://rbjl.net/irbtools+ripl.pdf]

== Irb Alternatives

Some other irb alternatives to check out:

• {ir}[https://github.com/raggi/ir#readme]: nice and light
• {irb2}[https://github.com/wycats/irb2#readme]: yehuda katz's partial attempt at rewriting irb
• {dietrb}[https://github.com/alloy/dietrb#readme]: mac and ruby 1.9 specific
• {pry}[https://github.com/banister/pry#readme]: featureful but heavy