README.rdoc in ripl-0.7.0 vs README.rdoc in ripl-0.7.1

- old
+ new

@@ -1,22 +1,26 @@ == Description -ripl is a light, 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}[http://github.com/cldwalker/ripl-play]. This customizability makes it -easy to build custom shells (i.e. for a gem or application) and complex shells (i.e. for the -{web}[http://github.com/cldwalker/nirvana]). In other words, ripl is also a shell framework. Works -on ruby 1.8.7 and greater. +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: +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]: +readline}[https://github.com/luislavena/rb-readline#readme]: gem install ripl rb-readline -- --without-readline Then, add the following to ~/.riplrc: @@ -51,15 +55,17 @@ # 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 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: +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 @@ -69,11 +75,11 @@ * 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 + * 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 @@ -83,26 +89,27 @@ * 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}[http://github.com/cldwalker/ripl-i18n]) + * 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}[http://github.com/janlelis/ripl-multi_line]). + {ripl-multi_line}[https://github.com/janlelis/ripl-multi_line#readme]). * No irb subsessions or workspaces (though ripl has jumps via - {ripl-commands}[http://github.com/cldwalker/ripl-commands]) - * Some IRB.conf features aren't supported yet (see {ripl-irb}[http://github.com/cldwalker/ripl-irb] + {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. +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' @@ -114,24 +121,27 @@ 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. +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]. +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}[http://github.com/cldwalker/dotfiles/tree/master/.riplrc]. +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: @@ -145,74 +155,111 @@ 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-<command> 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}[http://github.com/cldwalker/ripl-rails]. +To create one, create an executable in the format ripl-<command> 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}[http://github.com/cldwalker/ripl/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}[http://github.com/janlelis/ripl-multi_line] : evaluate multiple lines -* {ripl-ripper}[http://github.com/cldwalker/ripl-ripper] : evaluate multiple lines with ripper -* {ripl-rails}[http://github.com/cldwalker/ripl-rails] : console for rails -* {ripl-rack}[http://github.com/cldwalker/ripl-rack] : console for rack -* {ripl-play}[http://github.com/cldwalker/ripl-play] : play back and record input into ripl -* {ripl-debug}[http://github.com/cldwalker/ripl-debug] : automatically debugs a failed eval -* {ripl-after_rc}[http://github.com/cldwalker/ripl-after_rc] : provide blocks to run after ~/.irbrc is loaded -* {ripl-irb}[http://github.com/cldwalker/ripl-irb] : smooths transition from irb -* {ripl-i18n}[http://github.com/cldwalker/ripl-i18n] : translates ripl to your language -* {ripl-commands}[http://github.com/cldwalker/ripl-commands] : adds ripl commands similar to irb's commands -* {ripl-color_error}[http://github.com/cldwalker/ripl-color_error] : colorize errors -* {ripl-color_streams}[http://github.com/janlelis/ripl-color_streams] : colorizes stderr + stdout -* {ripl-color_result}[http://github.com/janlelis/ripl-color_result] : colorizes results -* {ripl-auto_indent}[http://github.com/janlelis/ripl-auto_indent] : auto indents multi-line input -* {ripl-hirb}[http://github.com/cldwalker/hirb] : comes with hirb to make it a proper riplzen -* {ripl-hijack}[http://github.com/cldwalker/ripl-hijack] : ripl console to a ruby process -* {ripl-misc}[http://github.com/cldwalker/ripl-misc] : a playground for ripl plugins -* {ripl-profiles}[https://github.com/janlelis/ripl-profiles]: load ripl profiles with a --profile option +* {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]: outputs ripl result as a hash rocket -* {ripl-padrino}[https://github.com/achiu/ripl-padrino]: console for padrino -* {ripltools}[https://github.com/janlelis/ripltools]: a collection of ripl plugins -* {ripl-rc}[https://github.com/godfat/ripl-rc]: ripl plugins for debugging, class-based coloring and more -* {ripl-em}[https://github.com/cldwalker/ripl-em]: interact with EM libraries asynchronously -* {ripl-readline-em}[https://github.com/pmahoney/ripl-readline-em]: another async EM interface +* {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}[http://github.com/cldwalker/nirvana]: A ruby web shell complete with autocomplete -* {fresh}[http://github.com/janlelis/fresh]: An interesting ruby/system hybrid shell -* {ripl-johnson}[http://github.com/cldwalker/ripl-johnson]: A js shell based on johnson (firefox tracemonkey) -* {ronin}[https://github.com/ronin-ruby/ronin]: An exploit development platform using ripl for its console -* {tux}[http://github.com/cldwalker/tux]: A sinatra shell -* {rack-webconsole}[https://github.com/codegram/rack-webconsole]: A rack middleware that adds a - web shell to any rack app +* {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}[http://github.com/raggi/ir]: nice and light -* {irb2}[http://github.com/wycats/irb2]: yehuda katz's partial attempt at rewriting irb -* {dietrb}[http://github.com/alloy/dietrb]: mac and ruby 1.9 specific -* {pry}[http://github.com/banister/pry]: featureful but heavy +* {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