rink 1.0.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,22 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+.idea

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Colin MacKenzie IV
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,135 @@
+= rink
+
+Makes interactive consoles awesome. More specifically, it does this by automating as much as conceivably possible so
+that you can get right down to what you really care about: your application.
+
+After the second copy-and-paste of an interactive console that I'd written for a few of my various gems, I decided to
+extract that code into a plug-and-play-friendly console gem. This library is the result.
+
+== Examples
+
+To create a new interactive console:
+
+  require 'rink'
+  Rink::Console.new
+
+The above example creates a console, but it doesn't add much in the way of usefulness. To really get started on your
+application-specific interactive console, extend the Rink::Console class:
+
+  class MyConsole < Rink::Console
+    # ...
+  end
+
+  #...
+  MyConsole.new
+  
+By default, Rink will execute code within the context of its #namespace (see the Rink::Console class documentation for
+details). You can, however, add specific commands to Rink like so:
+
+  class MyConsole < Rink::Console
+    command :help do |args|
+      if args.length == 0
+        puts "What do you need help with?"
+      else
+        puts "Sorry, I don't know anything about #{args.inspect}."
+      end
+    end
+  end
+  
+  MyConsole.new
+  
+  # produces...
+  
+  >> Interactive Console <<
+  
+  MyConsole > help
+  What do you need help with?
+  
+  MyConsole > help feed the poor
+  Sorry, I don't know anything about ["feed", "the", "poor"]
+  
+  MyConsole >
+   
+In addition to commands, you can also easily add or override default options in your console:
+
+  class MyConsole < Rink::Console
+    option :allow_ruby => false, :welcome => "Hello there!"
+    command :greet_me do |args|
+      puts options[:welcome]
+    end
+  end
+  
+  MyConsole.new
+  
+  # produces...
+  
+  >> Interactive Console <<
+  
+  MyConsole > inspect
+  I don't know the word "inspect."
+    
+  MyConsole > greet_me
+  Hello there!
+  
+== Running From The Command Line
+
+You've seen numerous examples of how to start Rink from within Ruby. The same thing works from within IRB or a Rake
+task. Additionally, Rink ships with a script so that you can run it directly from the command line:
+
+  $ rink
+  
+If you've extended Rink, you can give it the name of the class you extended it with. Rink will look in both the current
+directory, and the "lib" directory (if present) beneath the current location:
+
+  $ rink My::Console
+
+  Loaded constant My::Console from /Users/colin/projects/gems/rink/my/console.rb
+
+  >> Interactive Console <<
+  My::Console > 
+  
+If you need to load the console from a nonstandard directory, specify the path to that directory as a second argument.
+Rink will check both that directory and any 'lib' directory beneath it for your console.
+
+== Testing
+
+Testing your console turns out to be really easy, since the Rink::Console initializer takes some optional arguments to
+override the input and output streams. To can the set of input, for instance, just use:
+
+  input_string = "help"
+  MyConsole.new(:input => input_string)
+
+You'll see the output of the above dumped to STDOUT. If you want to capture that output, the answer is pretty obvious:
+
+  output_string = ""
+  MyConsole.new(:input => input_string, :output => output_string)
+  #=> output_string now contains the contents of the result of running the commands found inside of input_string.
+
+You can also pass IO objects in directly:
+
+  File.open("commands.txt", "r") do |cmd_file|
+    File.open("output.log", "w") do |log_file|
+      MyConsole.new(:input => cmd_file, :output => log_file)
+    end
+  end
+  
+Normally, if an error occurs, Rink will print a nicely-formatted message to its output stream. This is helpful if you're
+using the console but not if you're trying to write tests for one. So, you can disable error catching within Rink by
+passing :rescue_errors => false to the initializer:
+
+  MyConsole.new(:input => "raise", :rescue_errors => false)
+  #=> RuntimeError!
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Colin MacKenzie IV. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,47 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "rink"
+    gem.summary = %Q{Makes interactive consoles awesome.}
+    gem.description = %Q{Makes interactive consoles awesome.}
+    gem.email = "sinisterchipmunk@gmail.com"
+    gem.homepage = "http://github.com/sinisterchipmunk/rink"
+    gem.authors = ["Colin MacKenzie IV"]
+    
+    gem.add_development_dependency "rspec", ">= 1.3.0"
+
+    gem.test_files = FileList['spec/**/*']
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "rink #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/bin/rink

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+require File.expand_path(File.join(File.dirname(__FILE__), "../lib/rink"))
+
+def find_class(name, path)
+  if const = eval(name)
+    return const
+  end rescue nil
+  
+  paths = [path, File.join(path, "lib")]
+  filename = name.gsub(/::/, '/').gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+    gsub(/([a-z\d])([A-Z])/,'\1_\2').tr("-", "_").downcase
+  
+  filename += ".rb" unless filename[/\.rb$/]
+
+  paths.each do |dir|
+    file = File.expand_path(File.join(dir, filename))
+    if File.exist?(file)
+      load file
+      if const = eval(name)
+        puts "Loaded constant #{const} from #{file}"
+        puts
+        return const
+      end rescue nil
+    end
+  end
+  
+  raise "Console could not be found: #{name}\n  (searching for '#{filename}' in #{paths.inspect})"
+end
+
+def banner
+  puts "Usage:"
+  puts "  rink [My::Console] [path/to/file]"
+  puts
+  puts "By default, Rink::Console will be used. If path is omitted, the"
+  puts "current directory will be used."
+  puts
+  puts "Rink will check ./[file] and ./lib/[file] for the console to"
+  puts "load, where [file] is the underscored class name. For example,"
+  puts "App::Console would be found in either ./app/console.rb or "
+  puts "./lib/app/console.rb"
+  puts
+  exit
+end
+
+ARGV.each do |cmd|
+  if cmd == 'help' || cmd == '-h' || cmd == '/h' || cmd == '--help'
+    banner
+  end
+end
+
+puts
+begin
+  if ARGV.length == 0
+    klass = Rink::Console
+  elsif ARGV.length == 1
+    klass = find_class(ARGV.first, ".")
+  elsif ARGV.length == 2
+    klass = find_class(ARGV.first, ARGV.last)
+  else
+    banner
+  end
+  klass.new
+rescue
+  puts $!.message
+  puts
+end

data/lib/core_ext/object.rb

@@ -0,0 +1,15 @@
+class Object
+  unless defined?(instance_exec)
+    def instance_exec(*args, &block)
+      mname = "__instance_exec_#{Thread.current.object_id.abs}"
+      eigen = class << self; self; end
+      eigen.class_eval { define_method(mname, &block) }
+      begin
+        ret = send(mname, *args)
+      ensure
+        eigen.class_eval { undef_method(mname) } rescue nil
+      end
+      ret
+    end
+  end
+end

data/lib/rink/console.rb

@@ -0,0 +1,335 @@
+module Rink
+  class Console
+    extend Rink::Delegation
+    attr_reader :line_processor
+    attr_writer :namespace, :silenced
+    attr_reader :input, :output
+    delegate :silenced?, :print, :write, :puts, :to => :output, :allow_nil => true
+    delegate :banner, :commands, :to => 'self.class'
+    
+    # One caveat: if you override #initialize, make sure to do as much setup as possible before calling super -- or,
+    # call super with :defer => true -- because otherwise Rink will start the console before your init code executes.
+    def initialize(options = {})
+      options = default_options.merge(options)
+      apply_options(options)
+      run(options) unless options[:defer]
+    end
+    
+    # The Ruby object within whose context the console will be run.
+    # For example:
+    #  class CustomNamespace
+    #    def save_the_world
+    #      'maybe later'
+    #    end
+    #  end
+    #  
+    #  Rink::Console.new(:namespace => CustomNamespace.new)
+    #  # ...
+    #  Rink::Console > save_the_world
+    #  => "maybe later"
+    #
+    # This is most useful if you have an object with a lot of methods that you wish to treat
+    # as console commands. Also, it segregates the user from the Rink::Console instance, preventing
+    # them from making any changes to it.
+    #
+    # Note that you can set a console's namespace to itself if you _want_ the user to have access to it:
+    #
+    #  Rink::Console.new(:namespace => :self)
+    #
+    def namespace
+      @namespace ||= begin
+        # We want namespace to be any object, and in order to do that, Rink will call namespace#binding.
+        # But by default, the namespace should be TOPLEVEL_BINDING. If we set @namespace to this,
+        # Rink will call TOPLEVEL_BINDING#binding, which is an error. So instead we'll create a singleton
+        # object and override #binding on that object to return TOPLEVEL_BINDING. Effectively, that
+        # singleton object becomes (more-or-less) a proxy into the toplevel object. (Is there a better way?)
+        klass = Class.new(Object)
+        klass.send(:define_method, :binding) { TOPLEVEL_BINDING }
+        klass.new
+      end
+    end
+
+    # Runs a series of commands in the context of this Console. Input can be either a string
+    # or an input stream. Other options include:
+    #
+    #   :input     => a string or an input stream
+    #   :output    => a string or an output stream.
+    #   :banner    => boolean: whether to print a welcome banner.
+    #   :silent    => boolean: whether to print any output at all.
+    #   :namespace => any object (other than nil). Will be used as the default namespace.
+    #
+    # Note also that any value can be a proc. In this case, the proc will be called while
+    # applying the options and the  return value of that proc will be used. This is useful
+    # for lazy loading a value or for setting options based on some condition.
+    #
+    def run(input = {}, options = {})
+      if input.kind_of?(Hash)
+        options = options.merge(input)
+      else
+        options.merge! :input => input
+      end
+      
+      temporary_options(options) do
+        puts banner if options.key?(:banner) ? options[:banner] : default_options[:banner]
+        enter_input_loop
+      end
+    end
+
+    # runs a block of code with the specified options set, and then sets them back to their previous state.
+    # Options that are nil or not specified will be inherited from the previous state; and options in the
+    # previous state that are nil or not specified will not be reverted.
+    def temporary_options(options)
+      old_options = gather_options
+      apply_options(options)
+      yield
+    ensure
+      apply_options(old_options)
+    end
+
+    # Applies a new set of options. Options that are currently unset or nil will not be modified.
+    def apply_options(options)
+      return unless options
+      
+      options.each do |key, value|
+        options[key] = value.call if value.kind_of?(Proc)
+      end
+      @_options ||= {}
+      @_options.merge! options
+      @input  = setup_input_method(options[:input] || @input)
+      @output = setup_output_method(options[:output] || @output)
+      @output.silenced = options.key?(:silent) ? options[:silent] : !@output || @output.silenced?
+      @line_processor = options[:processor] || options[:line_processor] || @line_processor
+      @allow_ruby = options.key?(:allow_ruby) ? options[:allow_ruby] : @allow_ruby
+
+      if options[:namespace]
+        ns = options[:namespace] == :self ? self : options[:namespace]
+        if ns != @namespace
+          @namespace = ns
+          @namespace_binding = nil
+        end
+      end
+      
+      if @input
+        @input.output = @output
+        @input.prompt = prompt
+        if @input.respond_to?(:completion_proc)
+          @input.completion_proc = proc { |line| autocomplete(line) }
+        end
+      end
+    end
+    
+    # Returns the current set of options.
+    def gather_options
+      @_options
+    end
+    alias options gather_options
+
+    class << self
+      # Sets or returns the banner displayed when the console is started.
+      def banner(msg = nil)
+        if msg.nil?
+          @banner ||= ">> Interactive Console <<"
+        else
+          @banner = msg
+        end
+      end
+      
+      # Sets or overrides a default option.
+      #
+      # Example:
+      #
+      #   class MyConsole < Rink::Console
+      #     option :allow_ruby => false, :greeting => "Hi there!"
+      #   end
+      #
+      def option(options)
+        default_options.merge! options
+      end
+      
+      # Sets or returns the prompt for this console.
+      def prompt(msg = nil)
+        if msg.nil?
+          @prompt ||= "#{name} > "
+        else
+          @prompt = msg
+        end
+      end
+      
+      # Adds a custom command to the console. When the command is typed, a custom block of code
+      # will fire. The command may contain spaces. Any words following the command will be sent
+      # to the block as an array of arguments.
+      def command(name, case_sensitive = false, &block)
+        commands[name.to_s] = { :case_sensitive => case_sensitive, :block => block }
+      end
+      
+      # Returns a hash containing all registered commands.
+      def commands
+        @commands ||= {}
+      end
+      
+      # Default options are:
+      #  :processor => Rink::LineProcessor::PureRuby.new(self),
+      #  :output => STDOUT,
+      #  :input  => STDIN,
+      #  :banner => true,             # if false, Rink won't show a banner.
+      #  :silent => false,            # if true, Rink won't produce output.
+      #  :rescue_errors => true       # if false, Rink won't catch errors.
+      #  :defer => false              # if true, Rink won't automatically wait for input.
+      #  :allow_ruby => true          # if false, Rink won't execute unmatched commands as Ruby code.
+      def default_options
+        @default_options ||= {
+          :output => STDOUT,
+          :input  => STDIN,
+          :banner => true,
+          :silent => false,
+          :processor => Rink::LineProcessor::PureRuby.new(self),
+          :rescue_errors => true,
+          :defer => false,
+          :allow_ruby => true,
+        }
+      end
+    end
+
+    command(:exit) { |args| instance_variable_set("@exiting", true) }
+
+  protected
+    # The default set of options which will be used wherever an option from #apply_options is unset or nil.
+    def default_options
+      @default_options ||= self.class.default_options
+    end
+
+    # The prompt that is displayed next to the cursor.
+    def prompt
+      self.class.prompt
+    end
+    
+    # Executes the given command, which is a String, and returns a String to be
+    # printed to @output. If a command cannot be found, it is treated as Ruby code
+    # and is executed within the context of @namespace.
+    #
+    # You can override this method to produce custom results, or you can use the
+    # +:allow_ruby => false+ option in #run to prevent Ruby code from being executed.
+    def process_line(line)
+      args = line.split
+      cmd = args.shift
+      
+      catch(:command_not_found) { return process_command(cmd, args) }
+
+      # no matching commands, try to process it as ruby code
+      if @allow_ruby
+        result = process_ruby_code(line)
+        puts "  => #{result.inspect}"
+        return result
+      end
+      
+      puts "I don't know the word \"#{cmd}.\""
+    end
+    
+    def process_ruby_code(code)
+      prepare_scanner_for(code)
+      evaluate_scanner_statement
+    end
+    
+    # Returns the instance of Rink::Lexer used to process Ruby code.
+    def scanner
+      return @scanner if @scanner
+      @scanner = Rink::Lexer.new
+      @scanner.exception_on_syntax_error = false
+      @scanner
+    end
+    
+    # Searches for a command matching cmd and returns the result of running its block.
+    # If the command is not found, process_command throws :command_not_found.
+    def process_command(cmd, args)
+      commands.each do |command, options|
+        if (options[:case_sensitive]  && cmd == command) ||
+           (!options[:case_sensitive] && cmd.downcase == command.downcase)
+          #return options[:block].call(args)
+          return instance_exec(args, &options[:block])
+        end
+      end
+      throw :command_not_found
+    end
+
+  private    
+    include Rink::IOMethods
+    
+    def evaluate_scanner_statement
+      _caller = eval("caller", namespace_binding)
+      scanner.each_top_level_statement do |code, line_no|
+        begin
+          return eval(code, namespace_binding, self.class.name, line_no)
+        rescue
+          # clean out the backtrace so that it starts with the console line instead of program invocation.
+          _caller.reverse.each { |line| $!.backtrace.pop if $!.backtrace.last == line }
+          raise
+        end
+      end
+    end
+    
+    def namespace_binding
+      @namespace_binding ||= namespace.send(:binding)
+    end
+    
+    def prepare_scanner_for(code)
+      # the scanner prompt should be empty at first because we've already received the first line. Nothing to prompt for.
+      scanner.set_prompt nil
+      
+      # redirect scanner output to @output so that prompts go where they belong
+      scanner.output = @output
+      
+      # the meat: scanner will yield to set_input whenever it needs another line of code (including the first line).
+      # the first yield must give the code we've already received; subsequent yields should get more data from @input.
+      first = true
+      scanner.set_input(@input) do
+        line = if !first
+          # For subsequent gets, we need a prompt.
+          scanner.set_prompt prompt
+          line = @input.gets
+          scanner.set_prompt nil
+          line
+        else
+          first = false
+          code + "\n"
+        end
+
+        line
+      end
+    end
+
+    def enter_input_loop
+      @exiting = false
+      while !@exiting && (cmd = @input.gets)
+        cmd.strip!
+        unless cmd.length == 0
+          begin
+            @last_value = process_line(cmd)
+          rescue SystemExit, SignalException
+            raise
+          rescue Exception
+            raise unless gather_options[:rescue_errors]
+            print $!.class.name, ": ", $!.message, "\n"
+            print "\t", $!.backtrace.join("\n\t"), "\n"
+          end
+        end
+      end
+      @last_value
+    end
+    
+    # Runs the autocomplete method from the line processor, then reformats its result to be an array.
+    def autocomplete(line)
+      return [] unless @line_processor
+      result = @line_processor.autocomplete(line, namespace)
+      case result
+        when String
+          [result]
+        when nil
+          []
+        when Array
+          result
+        else
+          result.to_a
+      end
+    end
+  end
+end