ripl 0.2.1 → 0.2.2

data/.gemspec

@@ -8,16 +8,17 @@ Gem::Specification.new do |s|
   s.authors     = ["Gabriel Horner"]
   s.email       = "gabriel.horner@gmail.com"
   s.homepage    = "http://github.com/cldwlaker/ripl"
-  s.summary = "A light, modular alternative to irb"
-  s.description =  "Ruby Interactive Print Loop - A light, modular alternative to irb"
+  s.summary =  "Ruby Interactive Print Loop - A light, modular alternative to irb"
+  s.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.  This customizability makes it easy to build custom shells (i.e. for a gem or application) and complex shells (i.e. for the web)."
   s.required_rubygems_version = ">= 1.3.6"
   s.rubyforge_project = 'tagaholic'
   s.executables        = %w(ripl)
-  s.add_dependency 'bond', '~> 0.3.1'
+  s.add_dependency 'bond', '~> 0.3.3'
   s.add_development_dependency 'bacon', '>= 1.1.0'
   s.add_development_dependency 'rr', '= 0.10.10'
   s.add_development_dependency 'bacon-bits'
   s.files = Dir.glob(%w[{lib,test}/**/*.rb bin/* [A-Z]*.{txt,rdoc} ext/**/*.{rb,c} **/deps.rip]) + %w{Rakefile .gemspec}
+  s.files += Dir.glob('man/*')
   s.extra_rdoc_files = ["README.rdoc", "LICENSE.txt"]
   s.license = 'MIT'
 end

data/CHANGELOG.rdoc

@@ -1,3 +1,6 @@
+== 0.2.2
+* Add man page
+
 == 0.2.1
 * Add tests
 * Add more flexible -I and -r

data/README.rdoc

@@ -1,6 +1,9 @@
 == Description
 
-Ruby Interactive Print Loop - A light, modular alternative to irb
+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.  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]).
 
 == Install
 
@@ -8,7 +11,46 @@ Install the gem with:
 
     sudo gem install ripl
 
-== Features
+To make your first ripl experience smoother, also install these plugins:
+
+    # Adds multi-line evaluation
+    sudo gem install ripl-multi_line
+
+    # Ignore errors caused by irb-specific configuration in ~/.irbrc
+    sudo 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 gem. This ripl plugin fakes
+irb's existence, effectively ignoring irb-specific configuration. 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
@@ -21,9 +63,10 @@ Install the gem with:
 * Enhancements over irb
   * ~200 lines 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 subcommands
+  * Easy to create and invoke ripl commands
   * ~/.irbrc errors caught
 * Different from irb
   * No multi-line evaluation by default (there is a plugin. See Available Plugins below).
@@ -32,17 +75,6 @@ Install the gem with:
 
 Note: Irb features not in ripl can be implemented as plugins.
 
-== Philosophy
-
-ripl is a light, flexible repl(shell) meant to lay the foundation for customizable ruby shells. It
-provides an environment for plugins to share and reuse best practices for shells. ripl can be
-easily customized for gems, applications and is even usable on the web (examples forthcoming).
-
-== Usage
-
-    $ ripl
-    >> ...
-
 == Plugins
 
 A ripl plugin is a module that is included into Ripl::Shell or Ripl::Runner. Being simply modules,
@@ -62,7 +94,7 @@ As an example plugin, let's color error messages red:
     Ripl::Shell.send :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 methods are available for
+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
@@ -70,6 +102,12 @@ underscored version of the plugin name i.e. Ripl.config[:red_error].
 
 For available plugins, see Available 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].
+
 == Create Custom Shells
 
 Creating and starting a custom shell is as simple as:
@@ -91,18 +129,15 @@ $PATH. For example, the file 'ripl-my_gem' would be invoked with `ripl my_gem`.
 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].
 
-== Customize ripl
-
-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].
-
 == Available Plugins
 
 * {ripl-rails}[http://github.com/cldwalker/ripl-rails] : script/console for ripl
 * {ripl-color_error}[http://github.com/cldwalker/ripl-color_error] : colorize errors
 * {ripl-after_rc}[http://github.com/cldwalker/ripl-after_rc] : provide blocks to run after ~/.irbrc is loaded
 * {ripl-multi_line}[http://github.com/janlelis/ripl-multi_line] : evaluate multiple lines
+* {ripl-irb}[http://github.com/cldwalker/ripl-irb] : smooths transition from irb
+* {ripl-color_result}[http://github.com/janlelis/ripl-color_result] : colorizes results
+* {nirvana}[http://github.com/cldwalker/nirvana]: Not a plugin but rather a web shell built on top of ripl
 
 == Credits
 * janlelis for bug fix and tweaks

data/lib/ripl/completion.rb

@@ -2,8 +2,8 @@ require 'bond'
 
 module Ripl::Completion
   def before_loop
-    Bond.start(config[:completion] || {})
     super
+    Bond.restart(config[:completion] || {})
   end
 end
 Ripl::Shell.send :include, Ripl::Completion

data/lib/ripl/version.rb

@@ -1,3 +1,3 @@
 module Ripl
-  VERSION = '0.2.1'
+  VERSION = '0.2.2'
 end

data/man/ripl.1

@@ -0,0 +1,236 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "RIPL" "1" "November 2010" "CLDWALKER" "Ripl Manual"
+.
+.SH "NAME"
+\fBripl\fR \- Ruby Interactive Print Loop \- A light, modular alternative to irb
+.
+.SH "SYNOPSIS"
+.
+.nf
+
+ripl [\-r|\-\-require] [\-I] [\-f] [\-d] [\-h|\-\-help] [\-v|\-\-version] COMMAND [ARGS]
+.
+.fi
+.
+.SH "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\. This customizability makes it easy to build custom shells (i\.e\. for a gem or application) and complex shells (i\.e\. for the web)\.
+.
+.SH "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, effectively ignoring irb\-specific configuration\. Otherwise, if you don\'t mind modifying ~/\.irbrc, wrap your irb\-specific configuration in a block as follow:
+.
+.IP "" 4
+.
+.nf
+
+if defined? IRB
+  IRB\.conf[:BLAH] = \'blah\'
+  # \.\.\.
+end
+.
+.fi
+.
+.IP "" 0
+.
+.SH "CONFIGURATION"
+All ripl shells load the ruby file ~/\.riplrc if it exists\. In this file, plugins are required and configuration options are set\. To configure ripl and its plugins, use Ripl\.config\. By default, Ripl\.config is a hash with the following keys:
+.
+.TP
+\fB:binding\fR
+Binding to use for eval()\. Default is TOPLEVEL_BINDING\.
+.
+.TP
+\fB:completion\fR
+A hash that configures completion via Bond\.start\. See bond for more details\.
+.
+.TP
+\fB:history\fR
+A file used to store input history\. Default is \'~/\.irb_history\'\.
+.
+.TP
+\fB:irbrc\fR
+A ruby file to load at startup or false to not load anything\. Default is \'~/\.irbrc\'\.
+.
+.TP
+\fB:name\fR
+Name of the shell\. Default is \'ripl\'\.
+.
+.TP
+\fB:prompt\fR
+A string or lambda to generate string that prompts user for input\. Default is \'>> \'\.
+.
+.TP
+\fB:readline\fR
+A boolean to enable Readline\. Default is true\.
+.
+.TP
+\fB:result_prompt\fR
+A string that prefixes the result of an eval\. Default is \'=> \'\.
+.
+.P
+Plugins can optionally provide their own config key(s) for use here\. It is strongly recommended that a plugin start with an underscored version of its name i\.e\. Ripl::ColorError \-> Ripl\.config[:color_error]\.
+.
+.P
+An example ~/\.riplrc:
+.
+.IP "" 4
+.
+.nf
+
+  require \'ripl/multi_line\'
+  require \'ripl/color_error\'
+  Ripl\.config[:color_error] = :blue
+.
+.fi
+.
+.IP "" 0
+.
+.SH "PLUGINS"
+A ripl plugin is a module that is included into Ripl::Shell or 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 mentioned in the \fBCONFIGURATION\fR section, a plugin can be configured via Ripl\.config\.
+.
+.P
+To always use a plugin, require it in ~/\.riplrc\. To sometimes use it, require it from the commandline:
+.
+.IP "" 4
+.
+.nf
+
+$ ripl \-rripl/multi_line
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Plugins can also be required in the console but it is not recommended since plugins can depend on initialization that occurs before the console is started\. For this same reason, plugins should not be required in ~/\.irbrc\.
+.
+.SH "CREATE PLUGINS"
+For an example shell plugin, let\'s color error messages red:
+.
+.IP "" 4
+.
+.nf
+
+# Place in ~/\.riplrc
+module Ripl
+  module RedError
+    def format_error(error)
+      "\ee[31m#{super}\ee[m"
+    end
+  end
+end
+Ripl::Shell\.send :include, Ripl::RedError
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Note this plugin extends format_error() by invoking the original format_error() with super\. To see what methods are available for extension, see Ripl::Shell::API and Ripl::Runner::API\.
+.
+.P
+Points to consider when creating plugins:
+.
+.IP "\(bu" 4
+When adding functionality to a method, make sure to call \fBsuper\fR to preserve existing functionality\.
+.
+.IP "\(bu" 4
+When replacing functionality for a method, make sure the method\'s expectations are met i\.e\. setting a specific instance variable\. Failure to do so, will \fBbreak\fR ripl for you and anyone else who uses your plugin!
+.
+.IP "\(bu" 4
+Plugins can setup and teardown anything around a shell by extending Shell#before_loop and Shell#after_loop:
+.
+.IP
+module Ripl::MyPlugin
+.
+.IP "" 4
+.
+.nf
+
+def before_loop
+  super
+  Ripl\.config[:my_plugin] ||= :web_scale
+end
+
+def after_loop
+  super
+  # Write to files
+  # close a connection
+  # \.\.\.
+end
+.
+.fi
+.
+.IP "" 0
+.
+.IP
+end
+.
+.IP "\(bu" 4
+To add configuration for a plugin, add a key to Ripl\.config that matches the underscored version of the plugin name i\.e\. Ripl::RedError \-> Ripl\.config[:red_error]\. To set a default config value, see the previous example\.
+.
+.IP "\(bu" 4
+For more examples of plugins, see gems I\'ve made that start with \'ripl\-\'\.
+.
+.IP "" 0
+.
+.SH "CREATE CUSTOM SHELLS"
+Creating and starting a custom shell is as simple as:
+.
+.IP "" 4
+.
+.nf
+
+require \'ripl\'
+# Define plugins, load files, etc\.\.\.
+Ripl\.start
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Ripl\.start takes the same config keys mentioned in the \fBCONFIGURATION\fR section\. For example if you wanted to start on a specific binding:
+.
+.IP "" 4
+.
+.nf
+
+Ripl\.start :binding => MyClass\.send(:binding)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Also, since all shells load ~/\.riplrc, Ripl\.start can be used to override undesirable global configuration for a custom shell\.
+.
+.SH "COMMANDS"
+A ripl command is a command passed to ripl that loads a custom shell\. It\'s a convenient way to package and invoke custom shells\. A ripl command can take standard ripl options as long as they are before the command:
+.
+.IP "" 4
+.
+.nf
+
+# Load rails console without ~/\.irbrc
+$ ripl \-f rails
+
+# Load rails console with debugger
+$ ripl \-rrdebug rails
+.
+.fi
+.
+.IP "" 0
+.
+.P
+To create a ripl command, 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\'\. Any arguments to a ripl command can be parsed as the ripl command pleases i\.e\. into options and arguments\. For an example command, see ripl\-rails \fIhttp://github\.com/cldwalker/ripl\-rails\fR\.
+.
+.SH "BUGS"
+Please report bugs at \fIhttp://github\.com/cldwalker/ripl/issues\fR\.
+.
+.SH "COPYRIGHT"
+\fBripl\fR is Copyright (C) 2010 Gabriel Horner
+.
+.SH "SEE ALSO"
+\fIhttp://github\.com/cldwalker/ripl\fR, \fIhttp://github\.com/cldwalker/bond\fR, \fIhttp://github\.com/cldwalker/nirvana\fR, \fIhttp://github\.com/cldwalker/ripl\-irb\fR, \fIhttp://github\.com/cldwalker/ripl\-rails\fR, \fIhttp://github\.com/janlelis/multi_line\fR

data/man/ripl.1.ronn

@@ -0,0 +1,174 @@
+ripl(1) -- Ruby Interactive Print Loop - A light, modular alternative to irb
+====================================
+
+## SYNOPSIS
+
+    ripl [-r|--require] [-I] [-f] [-d] [-h|--help] [-v|--version] COMMAND [ARGS]
+
+## 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.  This customizability makes it easy to build custom shells (i.e. for a gem or application)
+and complex shells (i.e. for the web).
+
+## 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, effectively ignoring irb-specific configuration. 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
+
+## CONFIGURATION
+
+All ripl shells load the ruby file ~/.riplrc if it exists. In this file, plugins are required and
+configuration options are set. To configure ripl and its plugins, use Ripl.config. By default,
+Ripl.config is a hash with the following keys:
+
+* `:binding`:
+  Binding to use for eval(). Default is TOPLEVEL_BINDING.
+
+* `:completion`:
+  A hash that configures completion via Bond.start. See bond for more details.
+
+* `:history`:
+  A file used to store input history. Default is '~/.irb_history'.
+
+* `:irbrc`:
+  A ruby file to load at startup or false to not load anything. Default is '~/.irbrc'.
+
+* `:name`:
+  Name of the shell. Default is 'ripl'.
+
+* `:prompt`:
+  A string or lambda to generate string that prompts user for input. Default is '>> '.
+
+* `:readline`:
+  A boolean to enable Readline. Default is true.
+
+* `:result_prompt`:
+  A string that prefixes the result of an eval. Default is '=> '.
+
+Plugins can optionally provide their own config key(s) for use here. It is strongly recommended that
+a plugin start with an underscored version of its name i.e. Ripl::ColorError -> Ripl.config[:color_error].
+
+An example ~/.riplrc:
+
+      require 'ripl/multi_line'
+      require 'ripl/color_error'
+      Ripl.config[:color_error] = :blue
+
+## PLUGINS
+
+A ripl plugin is a module that is included into Ripl::Shell or 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
+mentioned in the `CONFIGURATION` section, a plugin can be configured via Ripl.config.
+
+To always use a plugin, require it in ~/.riplrc. To sometimes use it, require it from
+the commandline:
+
+    $ ripl -rripl/multi_line
+
+Plugins can also be required in the console but it is not recommended since plugins can depend on
+initialization that occurs before the console is started. For this same reason, plugins should not
+be required in ~/.irbrc.
+
+## CREATE PLUGINS
+
+For an example shell plugin, let's color error messages red:
+
+    # Place in ~/.riplrc
+    module Ripl
+      module RedError
+        def format_error(error)
+          "\e[31m#{super}\e[m"
+        end
+      end
+    end
+    Ripl::Shell.send :include, Ripl::RedError
+
+Note this plugin extends format_error() by invoking the original format_error() with super. To see
+what methods are available for extension, see Ripl::Shell::API and Ripl::Runner::API.
+
+Points to consider when creating plugins:
+
+* When adding functionality to a method, make sure to call `super` to preserve existing functionality.
+
+* When replacing functionality for a method, make sure the method's expectations are met i.e.
+setting a specific instance variable. Failure to do so, will `break` ripl for you and anyone else
+who uses your plugin!
+
+* Plugins can setup and teardown anything around a shell by extending Shell#before_loop and Shell#after_loop:
+
+    module Ripl::MyPlugin
+      def before_loop
+        super
+        Ripl.config[:my_plugin] ||= :web_scale
+      end
+
+      def after_loop
+        super
+        # Write to files
+        # close a connection
+        # ...
+      end
+    end
+
+* To add configuration for a plugin, add a key to Ripl.config that matches the underscored version
+of the plugin name i.e. Ripl::RedError -> Ripl.config[:red_error]. To set a default config value, see
+the previous example.
+
+* For more examples of plugins, see gems I've made that start with 'ripl-'.
+
+## 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 the same config keys mentioned in the `CONFIGURATION` section. For example if you wanted to
+start on a specific binding:
+
+    Ripl.start :binding => MyClass.send(:binding)
+
+Also, since all shells load ~/.riplrc, Ripl.start can be used to override undesirable global
+configuration for a custom shell.
+
+## COMMANDS
+
+A ripl command is a command passed to ripl that loads a custom shell. It's a convenient way to
+package and invoke custom shells. A ripl command can take standard ripl options as long as they are
+before the command:
+
+    # Load rails console without ~/.irbrc
+    $ ripl -f rails
+
+    # Load rails console with debugger
+    $ ripl -rrdebug rails
+
+To create a ripl command, 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'. Any
+arguments to a ripl command can be parsed as the ripl command pleases i.e. into options and
+arguments. For an example command, see [ripl-rails](http://github.com/cldwalker/ripl-rails).
+
+## BUGS
+
+Please report bugs at _http://github.com/cldwalker/ripl/issues_.
+
+## COPYRIGHT
+
+`ripl` is Copyright (C) 2010 Gabriel Horner
+
+## SEE ALSO
+
+<http://github.com/cldwalker/ripl>, <http://github.com/cldwalker/bond>, <http://github.com/cldwalker/nirvana>,
+<http://github.com/cldwalker/ripl-irb>, <http://github.com/cldwalker/ripl-rails>, <http://github.com/janlelis/multi_line>

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: ripl
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: false
   segments: 
   - 0
   - 2
-  - 1
-  version: 0.2.1
+  - 2
+  version: 0.2.2
 platform: ruby
 authors: 
 - Gabriel Horner
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-11 00:00:00 -05:00
+date: 2010-11-14 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -26,12 +26,12 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 17
+        hash: 21
         segments: 
         - 0
         - 3
-        - 1
-        version: 0.3.1
+        - 3
+        version: 0.3.3
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -80,7 +80,7 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id004
-description: Ruby Interactive Print Loop - A light, modular alternative to irb
+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.  This customizability makes it easy to build custom shells (i.e. for a gem or application) and complex shells (i.e. for the web).
 email: gabriel.horner@gmail.com
 executables: 
 - ripl
@@ -108,6 +108,8 @@ files:
 - test/deps.rip
 - Rakefile
 - .gemspec
+- man/ripl.1
+- man/ripl.1.ronn
 has_rdoc: true
 homepage: http://github.com/cldwlaker/ripl
 licenses: 
@@ -143,6 +145,6 @@ rubyforge_project: tagaholic
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: A light, modular alternative to irb
+summary: Ruby Interactive Print Loop - A light, modular alternative to irb
 test_files: []