ripl 0.1.2 → 0.2.0

data/CHANGELOG.rdoc

@@ -1,3 +1,9 @@
+== 0.2.0
+* Full support for plugins
+* Add history support for all shells
+* Add ~/.riplrc
+* Add usage and more commandline options
+
 == 0.1.2
 * Add support for commands
 * Add -I, -r and -v options

data/README.rdoc

@@ -10,24 +10,27 @@ Install the gem with:
 
 == Features
 
-* Same as irb
+* Similar to irb
   * Reads ~/.irbrc on startup
   * Appends to ~/.irb_history on exit
   * Autocompletion (from bond)
   * _ for last result
   * Type 'exit' or Ctrl-D to exit
-  * Commandline options: -r, -I, -v
+  * 6 common commandline options: -f, -r, -I, -d, -h, -v
+  * IRB.conf -> Ripl.config
 * Enhancements over irb
+  * ~200 lines vs irb's 5000+ lines
+  * Easily extendable with plugins
+  * 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
   * ~/.irbrc errors caught
-  * Provides hooks for plugins
-  * Method argument and customizable autocompletion (from bond)
-  * Less than 150 loc vs irb's 5000+ loc
-  * Simple configuration i.e. one hash
 * Different from irb
   * No multi-line evaluation
   * No irb subsessions or workspaces
-  * No IRB.conf features i.e. dynamic prompts and auto indent
-  * Most commandline options not supported
+  * No IRB.conf features i.e. preconfigured prompts and auto indent
+
+Note: Irb features not in ripl can be implemented as plugins.
 
 == Philosophy
 
@@ -40,14 +43,37 @@ easily customized for gems, applications and is even usable on the web (examples
     $ ripl
     >> ...
 
-== Create Custom Shells
+== 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 an example 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
 
-Creating a custom shell is as simple as:
+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
+extension, see Ripl::Shell::API and Ripl::Runner::API.
 
-    #!/usr/bin/env ruby
+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].
+
+== Create Custom Shells
+
+Creating and starting a custom shell is as simple as:
 
     require 'ripl'
-    # Do whatever setup you want ...
+    # Define plugins, load files, etc...
     Ripl.start
 
 Ripl.start takes options to customize your shell. For example if you wanted to
@@ -63,11 +89,17 @@ $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].
+
 == Credits
 * janlelis for bug fix and tweaks
 
 == irb alternatives
-Some other irb alternatives which I encourage you to check out:
+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

data/bin/ripl

@@ -1,4 +1,4 @@
 #!/usr/bin/env ruby
 
 require 'ripl'
-Ripl.run
+Ripl::Runner.run

data/lib/ripl.rb

@@ -1,44 +1,16 @@
-require 'ripl/shell'
-require 'ripl/version'
-
 module Ripl
-  extend self
-
-  def run
-    parse_options(ARGV)
-    ARGV[0] ? run_command(ARGV) : start
-  end
-
-  def parse_options(argv)
-    while argv[0] =~ /^-/
-      case argv.shift
-      when /-I=?(.*)/
-        $LOAD_PATH.unshift(*$1.split(":"))
-      when /-r=?(.*)/
-        require $1
-      when '-v', '--version'
-        puts Ripl::VERSION; exit
-      end
-    end
+  def self.config
+    @config ||= {:readline=>true, :riplrc=>'~/.riplrc'}
   end
 
-  def run_command(argv)
-    exec "ripl-#{argv.shift}", *argv
-  rescue Errno::ENOENT
-    raise unless $!.message =~ /No such file or directory.*ripl-(\w+)/
-    abort "`#{$1}' is not a ripl command."
-  end
-
-  def start(options={})
-    shell(options).loop
-  end
+  def self.start(*args); Runner.start(*args); end
 
-  def shell(options={})
-    @shell ||= begin
-      require 'ripl/readline_shell'
-      ReadlineShell.new(options)
-    rescue LoadError
-      Shell.new(options)
-    end
+  def self.shell(options={})
+    @shell ||= Shell.create(config.merge(options))
   end
 end
+
+require 'ripl/shell'
+require 'ripl/runner'
+require 'ripl/history'
+require 'ripl/version'

data/lib/ripl/completion.rb

@@ -1,11 +1,9 @@
-module Ripl
-  module Completion
-    def start_completion
-      require 'bond'
-      Bond.start
-      true
-    rescue LoadError
-      false
-    end
+require 'bond'
+
+module Ripl::Completion
+  def before_loop
+    super
+    Bond.start(config[:completion] || {}) unless Bond.started?
   end
 end
+Ripl::Shell.send :include, Ripl::Completion

data/lib/ripl/history.rb

@@ -0,0 +1,24 @@
+module Ripl::History
+  def history_file
+    @history_file ||= File.expand_path(config[:history])
+  end
+
+  def history; @history; end
+
+  def get_input
+    (@history << super)[-1]
+  end
+
+  def before_loop
+    config[:history], @history = '~/.irb_history', []
+    super
+    at_exit { write_history }
+    File.exists?(history_file) &&
+      IO.readlines(history_file).each {|e| history << e.chomp }
+  end
+
+  def write_history
+    File.open(history_file, 'w') {|f| f.write Array(history).join("\n") }
+  end
+end
+Ripl::Shell.send :include, Ripl::History

data/lib/ripl/readline.rb

@@ -0,0 +1,9 @@
+require 'readline'
+module Ripl::Readline
+  def get_input
+    Readline.readline prompt, true
+  end
+
+  def history; Readline::HISTORY; end
+end
+Ripl::Shell.send :include, Ripl::Readline

data/lib/ripl/runner.rb

@@ -0,0 +1,67 @@
+module Ripl::Runner
+  def self.included(mod)
+    mod.extend(self)
+  end
+
+  module API
+    def run
+      load_rc(Ripl.config[:riplrc])
+      @riplrc = true
+      parse_options(ARGV)
+      ARGV[0] ? run_command(ARGV) : start
+    end
+
+    def parse_options(argv)
+      while argv[0] =~ /^-/
+        case argv.shift
+        when /-I=?(.*)/
+          $LOAD_PATH.unshift(*$1.split(":"))
+        when /-r=?(.*)/
+          require $1
+        when '-d'
+          $DEBUG = true
+        when '-v', '--version'
+          puts Ripl::VERSION; exit
+        when '-f'
+          ENV['RIPL_IRBRC'] = 'false'
+        when '-h', '--help'
+          puts IO.readlines(__FILE__).grep(/^#/).map {|e| e.sub(/^#\s/,'') }; exit
+        end
+      end
+    end
+
+    def run_command(argv)
+      exec "ripl-#{argv.shift}", *argv
+    rescue Errno::ENOENT
+      raise unless $!.message =~ /No such file or directory.*ripl-(\w+)/
+      abort "`#{$1}' is not a ripl command."
+    end
+
+    def start(options={})
+      load_rc(Ripl.config[:riplrc]) unless @riplrc
+      Ripl.config[:irbrc] = ENV['RIPL_IRBRC'] != 'false' if ENV['RIPL_IRBRC']
+      Ripl.shell(options).loop
+    end
+
+    def load_rc(file)
+      load file if File.exists?(File.expand_path(file))
+    rescue StandardError, SyntaxError
+      warn "Error while loading #{file}:\n"+ format_error($!)
+    end
+
+    def format_error(err)
+      "#{err.class}: #{err.message}\n    #{err.backtrace.join("\n    ")}"
+    end
+  end
+  extend API
+end
+__END__
+# Usage: ripl [OPTIONS] [COMMAND] [ARGS]
+#
+# Options:
+#   -f                  Supress loading ~/.irbrc
+#   -d, --debug         Set $DEBUG to true (same as `ruby -d')
+#   -I=PATH             Add to front of $LOAD_PATH. Delimit multiple paths with ':'
+#   -r, --require=FILE  Require file (same as `ruby -r')
+#   -v, --version       Print ripl version
+#   -h, --help          Print help

data/lib/ripl/shell.rb

@@ -1,66 +1,79 @@
-module Ripl
-  class Shell
-    OPTIONS = {:name=>'ripl', :line=>1, :result_prompt=>'=> ', :prompt=>'>> ',
-      :binding=>TOPLEVEL_BINDING, :irbrc=>'~/.irbrc', :history=>'~/.irb_history'}
+class Ripl::Shell
+  OPTIONS = {:name=>'ripl', :line=>1, :result_prompt=>'=> ', :prompt=>'>> ',
+    :binding=>TOPLEVEL_BINDING, :irbrc=>'~/.irbrc'}
 
-    attr_accessor :line, :binding, :result_prompt
-    def initialize(options={})
-      @options = OPTIONS.merge options
-      @name, @binding, @line = @options.values_at(:name, :binding, :line)
-      @irbrc = @options[:irbrc]
+  def self.create(options={})
+    require 'ripl/readline' if options[:readline]
+    require 'ripl/completion'
+    new(options)
+  rescue LoadError
+    new(options)
+  end
+
+  attr_accessor :line, :binding, :result_prompt, :last_result
+  def initialize(options={})
+    @options = OPTIONS.merge options
+    @name, @binding, @line = @options.values_at(:name, :binding, :line)
+    @irbrc = @options[:irbrc]
+  end
+
+  def loop
+    before_loop
+    during_loop
+    after_loop
+  end
+
+  def config; Ripl.config; end
+
+  module API
+    def before_loop
+      Ripl::Runner.load_rc(@irbrc) if @irbrc
     end
 
-    def loop
-      before_loop
+    def during_loop
       while true do
+        @error_raised = nil
         input = get_input
         break if !input || input == 'exit'
-        puts loop_once(input)
+        loop_once(input)
+        puts(format_result(@last_result)) unless @error_raised
       end
-      after_loop
     end
 
     def get_input
-      print @options[:prompt]
+      print prompt
       $stdin.gets.chomp
     end
 
-    def loop_once(input)
-      begin
-        result = loop_eval(input)
-      rescue Exception => e
-        print_eval_error(e)
-      end
+    def prompt
+      @options[:prompt].respond_to?(:call) ? @options[:prompt].call : @options[:prompt]
+    end
 
+    def loop_once(input)
+      @last_result = loop_eval(input)
+      eval("_ = Ripl.shell.last_result", @binding)
+    rescue Exception => e
+      @error_raised = true
+      print_eval_error(e)
+    ensure
       @line += 1
-      format_result result
     end
 
-    def print_eval_error(e)
-      warn format_error(e)
+    def loop_eval(str)
+      eval(str, @binding, "(#{@name})", @line)
     end
 
-    def format_error(e)
-      "#{e.class}: #{e.message}\n\t#{e.backtrace.join("\n\t")}"
+    def print_eval_error(err)
+      warn format_error(err)
     end
 
+    def format_error(err); Ripl::Runner.format_error(err); end
+
     def format_result(result)
       @options[:result_prompt] + result.inspect
     end
-  end
-
-  module Hooks
-    def before_loop
-      load @irbrc if @irbrc && File.exists?(File.expand_path(@irbrc))
-    rescue StandardError, SyntaxError
-      warn "Error while loading #{@irbrc}:\n"+ format_error($!)
-    end
-
-    def loop_eval(str)
-      eval('_ = '+str, @binding, "(#{@name})", @line)
-    end
 
     def after_loop; end
   end
-  Shell.send :include, Hooks
+  include API
 end

data/lib/ripl/version.rb

@@ -1,3 +1,3 @@
 module Ripl
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: ripl
 version: !ruby/object:Gem::Version 
-  hash: 31
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
   - 2
-  version: 0.1.2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Gabriel Horner
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-01 00:00:00 -04:00
+date: 2010-11-08 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -45,7 +45,9 @@ extra_rdoc_files:
 - LICENSE.txt
 files: 
 - lib/ripl/completion.rb
-- lib/ripl/readline_shell.rb
+- lib/ripl/history.rb
+- lib/ripl/readline.rb
+- lib/ripl/runner.rb
 - lib/ripl/shell.rb
 - lib/ripl/version.rb
 - lib/ripl.rb

data/lib/ripl/readline_shell.rb

@@ -1,25 +0,0 @@
-require 'readline'
-require 'ripl/completion'
-
-class Ripl::ReadlineShell < Ripl::Shell
-  include Ripl::Completion
-
-  def get_input
-    Readline.readline @options[:prompt], true
-  end
-
-  def history_file
-    @history_file ||= File.expand_path(@options[:history])
-  end
-
-  def before_loop
-    start_completion
-    super
-    File.exists?(history_file) &&
-      IO.readlines(history_file).each {|e| Readline::HISTORY << e.chomp }
-  end
-
-  def after_loop
-    File.open(history_file, 'w') {|f| f.write Readline::HISTORY.to_a.join("\n") }
-  end
-end