bombshell 0.1.4 → 0.1.5

data/bombshell.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andy Rossmeissl"]
-  s.date = %q{2011-03-31}
+  s.date = "2011-04-20"
   s.description = %q{Give your application or gem an interactive shell, complete with custom prompts, tab completion, and various callbacks. Commands are defined as Ruby methods and can be grouped into logical subshells.}
   s.email = %q{andy@rossmeissl.net}
   s.extra_rdoc_files = [

data/features/support/env.rb

@@ -5,6 +5,6 @@ require 'rspec/expectations'
 require 'bombshell'
 
 Before do
-  @aruba_io_wait_seconds = 2
+  @aruba_io_wait_seconds = 3
   @dirs = [File.join(ENV['HOME'], 'bombshell_features')]
 end

data/lib/bombshell.rb

@@ -5,7 +5,15 @@ require 'bombshell/completor'
 require 'bombshell/environment'
 require 'bombshell/irb'
 
+# Bombshell enables the lickety-split creation of interactive consoles
+# (really just boring old custom IRB sessions).
+# As a Ruby library developer, you may want to build a little shell into
+# your library so that other developers can play around with it before
+# adding it to their applications. In the past this has been a real PITA.
+# With Bombshell it's a little easier.
 module Bombshell
+  # Launch a shell. This is typically called from a "gem binary" executable Ruby script as described in the README.
+  # @param [Class] shell The shell class to launch. Must include <tt>Bombshell::Shell</tt>.
   def launch(shell)
     begin
       failure = shell.launch(ARGV.dup)

data/lib/bombshell/completor.rb

@@ -1,15 +1,20 @@
 module Bombshell
+  # A class used by <tt>IRB.start_session</tt> to handle tab completion.
   class Completor
+    # Always initialize Completor with the shell it's completing for.
     def initialize(shell)
       @shell = shell
     end
     
     attr_reader :shell
     
+    # Provide completion for a given fragment.
+    # @param [String] fragment the fragment to complete for
     def complete(fragment)
       self.class.filter(shell.instance_methods).grep Regexp.new(Regexp.quote(fragment))
     end
     
+    # Filter out irrelevant methods that shouldn't appear in a completion list.
     def self.filter(m)
       (m - Bombshell::Environment.instance_methods - Bombshell::Shell::Commands::HIDE).reject do |m|
         m =~ /^_/

data/lib/bombshell/environment.rb

@@ -1,4 +1,7 @@
 module Bombshell
+  # A (mostly) blank class like Ruby's own CleanSlate. We leave a few important methods in here; your shell shouldn't redefine them.
+  # It's best practice to set your shell classes to inherit from <tt>Bombshell::Environment</tt>. See the README for more details.
+  # @see file:README.markdown
   class Environment
     instance_methods.each do |m|
       undef_method m if m.to_s !~ /(?:^__|^nil\?$|^send$|^instance_eval$|^define_method$|^class$|^object_id|^instance_methods$)/

data/lib/bombshell/irb.rb

@@ -1,6 +1,9 @@
 # encoding: utf-8
 
+# We have to monkey patch a method into IRB here. I've tried extending it, and it doesn't work.
 module IRB
+  # Launch a custom IRB session with the given binding, set up the prompt, and define tab completion.
+  # @param [Binding] binding Your shell's binding
   def self.start_session(binding)
     unless @__initialized
       args = ARGV

data/lib/bombshell/shell.rb

@@ -1,18 +1,28 @@
 require 'bombshell/shell/commands'
 
 module Bombshell
+  # Classes include this module to become Bombshell shells.
   module Shell
+    # Add class methods and a callback hash to your shell.
     def self.included(base)
       base.extend ClassMethods
       base.instance_variable_set :@bombshell_callbacks, :before_launch => [], :having_launched => []
     end
     
+    # IRB has pretty limited hooks for defining prompts, so we have to piggyback on your
+    # shell's <tt>#to_s</tt>. Hope you don't need it for something else.
     def to_s
       _prompt
     end
     
     include Commands
     
+    # Render and return your shell's prompt.
+    #
+    # You can define the prompt with <tt>MyShell.prompt_with</tt> and access it without rendering with <tt>MyShell.bombshell_prompt</tt>.
+    # @see ClassMethods#prompt_with
+    # @see ClassMethods#bombshell_prompt
+    # @return String
     def _prompt
       if self.class.bombshell_prompt.is_a? String
         self.class.bombshell_prompt
@@ -25,11 +35,22 @@ module Bombshell
       end
     end
     
+    # Returns your shell's binding, which IRB needs (desperately).
+    # @return Binding
     def get_binding
       binding
     end
     
+    # Class methods for your shell
     module ClassMethods
+      # Launch the shell.
+      #
+      # You should generally call <tt>Bombshell.launch(MyShell)</tt> instead
+      # of <tt>MyShell.launch</tt> directly, as the former approach will handle
+      # exits correctly and pass command-line parameters as arguments.
+      # @param [Array] arguments An array of arguments that, eventually, callbacks
+      #   might use. If you're using the <tt>Bombshell.launch</tt> wrapper, these
+      #   will be command-line parameters.
       def launch(*arguments)
         @bombshell_callbacks[:before_launch].each do |callback|
           callback.call(*arguments.first(callback.arity > -1 ? callback.arity : 0))
@@ -41,18 +62,63 @@ module Bombshell
         ::IRB.start_session(shell.get_binding)
       end
     
+      # Define a callback that will get called before your shell is instantiated (and
+      # therefore before it is handed over to IRB).
+      # 
+      # This is a great place to
+      # dynamically define additional instance methods on your class. If your callback
+      # proc asks for blockvars, Bombshell will give it as many command-line parameters
+      # as it needs to. Within the callback, <tt>self</tt> is your shell <i>class</i>.
+      # @see #having_launched
+      # @example
+      #   class MyShell < Bombshell::Environment
+      #     include Bombshell::Shell
+      #     before_launch do
+      #       define_method :foo
+      #         puts 'bar'
+      #       end
+      #     end
+      #   end
+      # @example
+      #   class MyShell < Bombshell::Environment
+      #     include Bombshell::Shell
+      #     before_launch do |first_command_line_parameter, second_command_line_parameter|
+      #       define_method :display_first_command_line_parameter
+      #         puts first_command_line_parameter
+      #       end
+      #     end
+      #   end
       def before_launch(&callback)
         @bombshell_callbacks[:before_launch] << callback
       end
 
+      # Define a callback that will get called <i>after</i> your shell is instantiated,
+      # but <i>before</i> its binding is handed over to IRB.  Within the callback, <tt>self</tt> is your shell <i>instance</i>.
+      # @see #before_launch
       def having_launched(&callback)
         @bombshell_callbacks[:having_launched] << callback
       end
       
+      # Define your shell's prompt.
+      #
+      # You can either set your prompt to a static string, or use a Proc for a dynamic prompt.
+      # @param [String] p a string to be used as your shell's prompt.
+      # @param [Proc] prompt a Proc to be rendered whenever your shell's prompt needs to be
+      #   displayed.  Within the callback, <tt>self</tt> is your shell <i>class</i>. If your
+      #   proc asks for a blockvar, it will be given your shell <i>instance</i>.
+      # @see Bombshell::Shell#_prompt
+      # @see #bombshell_prompt
       def prompt_with(p = nil, &prompt)
         @bombshell_prompt = p || prompt
       end
       
+      # Read your shell's prompt
+      #
+      # Note that this method returns an <i>unrendered</i> prompt. That is, if it's defined as
+      # a Proc, you'll get a Proc back. If you want to get the rendered prompt, use <tt>#_prompt</tt>
+      # on your shell instance.
+      # @see #prompt_with
+      # @see Bombshell::Shell#_prompt
       def bombshell_prompt
         @bombshell_prompt
       end

data/lib/bombshell/shell/commands.rb

@@ -1,11 +1,16 @@
 module Bombshell
   module Shell
+    # Standard commands that show up in all Bombshell shells.
     module Commands
+      # An explicit list of commands to hide from tab completion.
       HIDE = [:method_missing, :get_binding, :_prompt, :to_s]
       
+      # Exit safely, accounting for the fact that we might be inside a subshell.
       def quit
         throw :IRB_EXIT
       end
+      
+      # Provide an error message for unknown commands rather than raise an exception.
       def method_missing(*args)
         return if [:extend, :respond_to?].include? args.first
         puts "Unknown command #{args.first}"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: bombshell
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 17
   prerelease: 
   segments: 
   - 0
   - 1
-  - 4
-  version: 0.1.4
+  - 5
+  version: 0.1.5
 platform: ruby
 authors: 
 - Andy Rossmeissl
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-31 00:00:00 -04:00
+date: 2011-04-20 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency