boson 0.0.1 → 0.1.0

data/lib/boson/runners/console_runner.rb

@@ -0,0 +1,54 @@
+module Boson
+  # Runner used when starting irb. To use in irb, drop this in your ~/.irbrc:
+  #   require 'boson'
+  #   Boson.start
+  class ConsoleRunner < Runner
+    class <<self
+      # Starts Boson by loading configured libraries. If no default libraries are specified in the config,
+      # it will load up all detected libraries.
+      # ==== Options
+      # [:libraries] Array of libraries to load.
+      # [:verbose] Boolean to be verbose about libraries loading. Default is true.
+      # [:no_defaults] Boolean which turns off loading any default libraries. Default is false.
+      # [:autoload_libraries] Boolean which makes any command execution easier. It redefines
+      #                       method_missing on Boson.main_object so that commands with unloaded
+      #                       libraries are automatically loaded. Default is false.
+      def start(options={})
+        @options = {:verbose=>true}.merge options
+        init unless @initialized
+        Manager.load(@options[:libraries], load_options) if @options[:libraries]
+      end
+
+      # Loads libraries and then starts irb (or the configured console) from the commandline.
+      def bin_start(repl, libraries)
+        start :no_defaults=>true, :libraries=>libraries
+        repl = Boson.repo.config[:console] if Boson.repo.config[:console]
+        repl = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb' unless repl.is_a?(String)
+        unless repl.index('/') == 0 || (repl = Util.which(repl))
+          $stderr.puts "Console not found. Please specify full path in config[:console]."
+          return
+        end
+        ARGV.replace ['-f']
+        Kernel.load $0 = repl
+      end
+
+      def init #:nodoc:
+        super
+        define_autoloader if @options[:autoload_libraries]
+        @initialized = true
+      end
+
+      def default_libraries #:nodoc:
+        defaults = super
+        unless @options[:no_defaults]
+          new_defaults = Boson.repos.map {|e| e.config[:console_defaults] }.flatten
+          new_defaults = detected_libraries if new_defaults.empty?
+          defaults += new_defaults
+          defaults.uniq!
+        end
+        defaults
+      end
+    end
+  end
+end
+  

data/lib/boson/scientist.rb

@@ -1,27 +1,96 @@
 require 'shellwords'
 module Boson
+  # Scientist redefines the methods of commands that have options and/or take global options. This redefinition
+  # allows a command to receive its arguments normally or as a commandline app does. For a command's
+  # method to be redefined correctly, its last argument _must_ expect a hash.
+  #
+  # Take for example this basic method/command with an options definition:
+  #   options :level=>:numeric, :verbose=>:boolean
+  #   def foo(arg='', options={})
+  #     [arg, options]
+  #   end
+  #
+  # When Scientist wraps around foo(), argument defaults are respected:
+  #    foo '', :verbose=>true   # normal call
+  #    foo '-v'                 # commandline call
+  #
+  #    Both calls return: ['', {:verbose=>true}]
+  #
+  # Non-string arguments can be passed in:
+  #    foo Object, :level=>1
+  #    foo Object, 'l1'
+  #
+  #    Both calls return: [Object, {:level=>1}]
+  #
+  # === Global Options
+  # Any command with options comes with default global options. For example '-hv' on such a command
+  # prints a help summarizing a command's options as well as the global options.
+  # When using global options along with command options, global options _must_ precede command options.
+  # Take for example using the global --pretend option with the method above:
+  #   irb>> foo '-p -l=1'
+  #   Arguments: ["", {:level=>1}]
+  #   Global options: {:pretend=>true}
+  #
+  # If a global option conflicts with a command's option, the command's option takes precedence. You can get around
+  # this by passing a --global option which takes a string of options without their dashes. For example:
+  #   foo '-p --fields=f1,f2 -l=1'
+  #   # is the same as
+  #   foo ' -g "p fields=f1,f2" -l=1 '
+  #
+  # === Rendering Views With Global Options
+  # Perhaps the most important global option is --render. This option toggles the rendering of your command's output
+  # with Hirb[http://github.com/cldwalker/hirb]. Since Hirb can be customized to generate any view, this option allows
+  # you toggle a predefined view for a command without embedding view code in your command!
+  #
+  # Here's a simple example, toggling Hirb's table view:
+  #   # Defined in a library file:
+  #   #@options {}
+  #   def list(options={})
+  #     [1,2,3]
+  #   end
+  #
+  #   Using it in irb:
+  #   >> list
+  #   => [1,2,3]
+  #   >> list '-r'
+  #   +-------+
+  #   | value |
+  #   +-------+
+  #   | 1     |
+  #   | 2     |
+  #   | 3     |
+  #   +-------+
+  #   3 rows in set
+  #   => true
+  #
+  # To default to rendering a view for a command, add a render_options {method attribute}[link:classes/Boson/MethodInspector.html]
+  # above list() along with any options you want to pass to your Hirb helper class. In this case, using '-r' gives you the
+  # command's returned object instead of a formatted view!
   module Scientist
     extend self
+    # Handles all Scientist errors.
     class Error < StandardError; end
     class EscapeGlobalOption < StandardError; end
+
     attr_reader :global_options, :rendered
     @no_option_commands ||= []
     GLOBAL_OPTIONS = {
       :help=>{:type=>:boolean, :desc=>"Display a command's help"},
-      :render=>{:type=>:boolean, :desc=>"Toggle a command's default render behavior"},
+      :render=>{:type=>:boolean, :desc=>"Toggle a command's default rendering behavior"},
       :verbose=>{:type=>:boolean, :desc=>"Increase verbosity for help, errors, etc."},
-      :global=>{:type=>:string, :desc=>"Pass a string of global options without the dashes i.e. '-p -f=f1,f2' -> 'p f=f1,f2'"},
+      :global=>{:type=>:string, :desc=>"Pass a string of global options without the dashes"},
       :pretend=>{:type=>:boolean, :desc=>"Display what a command would execute without executing it"}
-    }
+    } #:nodoc:
     RENDER_OPTIONS = {
       :fields=>{:type=>:array, :desc=>"Displays fields in the order given"},
       :sort=>{:type=>:string, :desc=>"Sort by given field"},
-      :as=>{:type=>:string, :desc=>"Hirb helper class which renders"},
+      :class=>{:type=>:string, :desc=>"Hirb helper class which renders"},
       :reverse_sort=>{:type=>:boolean, :desc=>"Reverse a given sort"},
       :max_width=>{:type=>:numeric, :desc=>"Max width of a table"},
       :vertical=>{:type=>:boolean, :desc=>"Display a vertical table"}
-    }
+    } #:nodoc:
 
+    # Redefines a command's method for the given object.
     def create_option_command(obj, command)
       cmd_block = create_option_command_block(obj, command)
       @no_option_commands << command if command.options.nil?
@@ -30,12 +99,14 @@ module Boson
       }
     end
 
+    # The actual method which replaces a command's original method
     def create_option_command_block(obj, command)
       lambda {|*args|
         Boson::Scientist.translate_and_render(obj, command, args) {|args| super(*args) }
       }
     end
 
+    #:stopdoc:
     def translate_and_render(obj, command, args)
       @global_options = {}
       args = translate_args(obj, command, args)
@@ -58,13 +129,9 @@ module Boson
         return @args if @no_option_commands.include?(@command)
         @args << parsed_options
         if @args.size != command.arg_size && !command.has_splat_args?
-          command_size = @args.size > command.arg_size ? command.arg_size : command.arg_size - 1
-          if @args.size - 1 == command_size
-            raise Error, "Arguments are misaligned. Possible causes are incorrect argument "+
-              "size or no argument for this method's options."
-          else
-            raise ArgumentError, "wrong number of arguments (#{@args.size - 1} for #{command_size})"
-          end
+          command_size, args_size = @args.size > command.arg_size ? [command.arg_size, @args.size] :
+            [command.arg_size - 1, @args.size - 1]
+          raise ArgumentError, "wrong number of arguments (#{args_size} for #{command_size})"
         end
       end
       @args
@@ -110,7 +177,7 @@ module Boson
             @command.render_options[k] = {:default=>v}
           end
         }
-        opts = Util.recursive_hash_merge(@command.render_options, RENDER_OPTIONS)
+        opts = Util.recursive_hash_merge(@command.render_options, Util.deep_copy(RENDER_OPTIONS))
         opts[:sort][:values] ||= opts[:fields][:values] if opts[:fields][:values]
         opts
       end
@@ -129,11 +196,17 @@ module Boson
         parsed_options, @args = parse_options Shellwords.shellwords(@args[0])
       # last string argument interpreted as args + options
       elsif @args.size > 1 && @args[-1].is_a?(String)
-        parsed_options, new_args = parse_options @args.pop.split(/\s+/)
+        args = caller.grep(/bin_runner.rb:/).empty? ? Shellwords.shellwords(@args.pop) : @args
+        parsed_options, new_args = parse_options args
         @args += new_args
-      # default options
-      elsif (@args.size <= @command.arg_size - 1) || (@command.has_splat_args? && !@args[-1].is_a?(Hash))
+      # add default options
+      elsif (!@command.has_splat_args? && @args.size <= @command.arg_size - 1) ||
+        (@command.has_splat_args? && !@args[-1].is_a?(Hash))
+          parsed_options = parse_options([])[0]
+      # merge default options with given hash of options
+      elsif (@command.has_splat_args? || (@args.size == @command.arg_size)) && @args[-1].is_a?(Hash)
         parsed_options = parse_options([])[0]
+        parsed_options.merge!(@args.pop)
       end
       parsed_options
     end
@@ -143,7 +216,8 @@ module Boson
       @global_options = option_parser.parse @command.option_parser.leading_non_opts
       new_args = option_parser.non_opts.dup + @command.option_parser.trailing_non_opts
       if @global_options[:global]
-        global_opts = Shellwords.shellwords(@global_options[:global]).map {|str| (str.length > 1 ? "--" : "-") + str }
+        global_opts = Shellwords.shellwords(@global_options[:global]).map {|str|
+          ((str[/^(.*?)=/,1] || str).length > 1 ? "--" : "-") + str }
         @global_options.merge! option_parser.parse(global_opts)
       end
       raise EscapeGlobalOption if @global_options[:help]
@@ -164,5 +238,6 @@ module Boson
         }
       end
     end
+    #:startdoc:
   end
 end

data/lib/boson/util.rb

@@ -1,7 +1,9 @@
 module Boson
+  # Collection of utility methods used throughout Boson.
   module Util
     extend self
-    #From Rails ActiveSupport
+    # From Rails ActiveSupport, converts a camelcased string to an underscored string:
+    # 'Boson::MethodInspector' -> 'boson/method_inspector'
     def underscore(camel_cased_word)
       camel_cased_word.to_s.gsub(/::/, '/').
        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
@@ -10,11 +12,14 @@ module Boson
        downcase
     end
 
-    # from Rails ActiveSupport
+    # From Rails ActiveSupport, does the reverse of underscore:
+    # 'boson/method_inspector' -> 'Boson::MethodInspector'
     def camelize(string)
       string.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
     end
-    
+
+    # Converts a module/class string to the actual constant.
+    # Returns nil if not found.
     def constantize(string)
       any_const_get(camelize(string))
     end
@@ -40,6 +45,9 @@ module Boson
       end
     end
 
+    # Detects new object/kernel methods, gems and modules created within a block.
+    # Returns a hash of what's detected.
+    # Valid options and possible returned keys are :methods, :object_methods, :modules, :gems.
     def detect(options={}, &block)
       options = {:methods=>true, :object_methods=>true}.merge!(options)
       original_gems = Gem.loaded_specs.keys if Object.const_defined? :Gem
@@ -56,6 +64,7 @@ module Boson
       detected
     end
 
+    # Safely calls require, returning false if LoadError occurs.
     def safe_require(lib)
       begin
         require lib
@@ -64,16 +73,20 @@ module Boson
       end
     end
 
+    # Returns all modules that currently exist.
     def modules
       all_modules = []
       ObjectSpace.each_object(Module) {|e| all_modules << e}
       all_modules
     end
 
+    # Returns array of _all_ common instance methods between two modules/classes.
     def common_instance_methods(module1, module2)
       (module1.instance_methods + module1.private_instance_methods) & (module2.instance_methods + module2.private_instance_methods)
     end
 
+    # Creates a module under a given base module and possible name. If the module already exists, it attempts
+    # to create one with a number appended to the name.
     def create_module(base_module, name)
       desired_class = camelize(name)
       if (suffix = ([""] + (1..10).to_a).find {|e| !base_module.const_defined?(desired_class+e)})
@@ -81,10 +94,16 @@ module Boson
       end
     end
 
+    # Behaves just like the unix which command, returning the full path to an executable based on ENV['PATH'].
     def which(command)
       ENV['PATH'].split(File::PATH_SEPARATOR).map {|e| File.join(e, command) }.find {|e| File.exists?(e) }
     end
 
+    # Deep copies any object if it can be marshaled. Useful for deep hashes.
+    def deep_copy(obj)
+      Marshal::load(Marshal::dump(obj))
+    end
+
     # Recursively merge hash1 with hash2.
     def recursive_hash_merge(hash1, hash2)
       hash1.merge(hash2) {|k,o,n| (o.is_a?(Hash)) ? recursive_hash_merge(o,n) : n}

data/lib/boson/view.rb

@@ -1,18 +1,30 @@
 module Boson
+  # Handles {Hirb}[http://tagaholic.me/hirb/]-based views.
   module View
     extend self
 
+    # Enables hirb and reads a config file from the main repo's config/hirb.yml.
     def enable
       Hirb::View.enable(:config_file=>File.join(Boson.repo.config_dir, 'hirb.yml')) unless @enabled
       @enabled = true
     end
 
+    # Renders any object via Hirb. Options are passed directly to
+    # {Hirb::Console.render_output}[http://tagaholic.me/hirb/doc/classes/Hirb/Console.html#M000011].
     def render(object, options={})
-      [nil,false,true].include?(object) ? puts(object.inspect) : render_object(object, options)
+      if silent_object?(object)
+        puts(object.inspect) unless options[:silence_booleans]
+      else
+        render_object(object, options)
+      end
+    end
+
+    def silent_object?(obj)
+      [nil,false,true].include?(obj)
     end
 
-    def render_object(object, options={})
-      options[:class] = options.delete(:as) || :auto_table
+    def render_object(object, options={}) #:nodoc:
+      options[:class] ||= :auto_table
       if object.is_a?(Array) && object.size > 0 && (sort = options.delete(:sort))
         begin
           sort_lambda = object[0].is_a?(Hash) ? (object[0][sort].respond_to?(:<=>) ?

data/test/bin_runner_test.rb

@@ -36,17 +36,17 @@ module Boson
         start('-l', 'blah', 'libraries')
       end
 
-      test "repl option starts repl" do
-        ReplRunner.expects(:start)
+      test "console option starts irb" do
+        ConsoleRunner.expects(:start)
         Util.expects(:which).returns("/usr/bin/irb")
         Kernel.expects(:load).with("/usr/bin/irb")
-        start("--repl")
+        start("--console")
       end
 
-      test "repl option but no repl found prints error" do
-        ReplRunner.expects(:start)
+      test "console option but no irb found prints error" do
+        ConsoleRunner.expects(:start)
         Util.expects(:which).returns(nil)
-        capture_stderr { start("--repl") } =~ /Repl not found/
+        capture_stderr { start("--console") }.should =~ /Console not found/
       end
 
       test "execute option executes string" do
@@ -54,17 +54,27 @@ module Boson
         capture_stdout { start("-e", "p 1 + 1") }.should == "2\n"
       end
 
+      test "global option takes value with whitespace" do
+        View.expects(:render).with(anything, {:sort => :lib, :fields => [:name, :lib]})
+        start('commands', '-g', 'f=name,lib s=lib')
+      end
+
       test "execute option errors are caught" do
         capture_stderr { start("-e", "raise 'blah'") }.should =~ /^Error:/
       end
 
       test "command and too many arguments prints error" do
-        capture_stdout { start('commands','1','2','3') }.should =~ /Wrong number/
+        capture_stdout { capture_stderr { start('commands','1','2','3') }.should =~ /'commands'.*incorrect/ }
+      end
+
+      test "failed subcommand prints error and not command not found" do
+        BinRunner.expects(:execute_command).raises("bling")
+        capture_stderr { start("commands.blah") }.should =~ /Error: bling/
       end
 
       test "undiscovered command prints error" do
          BinRunner.expects(:load_command_by_index).returns(false)
-        capture_stderr { start('blah') }.should =~ /Error.*blah/
+        capture_stderr { start('blah') }.should =~ /Error.*not found/
       end
 
       test "basic command executes" do

data/test/loader_test.rb

@@ -30,7 +30,7 @@ module Boson
       end
 
       test "loads and strips aliases from a library's commands" do
-        with_config(:commands=>{"blah"=>{:alias=>'b'}}) do
+        with_config(:command_aliases=>{"blah"=>'b'}) do
           load :blah, :file_string=>"module Blah; def blah; end; alias_method(:b, :blah); end"
           library_loaded?('blah')
           library('blah').commands.should == ['blah']

data/test/manager_test.rb

@@ -37,7 +37,7 @@ module Boson
         after(:each) { Object.send(:remove_const, "Aquateen") }
 
         test "created with command specific config" do
-          with_config(:commands=>{'frylock'=>{:alias=>'fr'}}) do
+          with_config(:command_aliases=>{'frylock'=>'fr'}) do
             Manager.expects(:create_instance_aliases).with({"Aquateen"=>{"frylock"=>"fr"}})
             load_library :name=>'aquateen', :commands=>['frylock'], :module=>Aquateen
             library_loaded? 'aquateen'
@@ -53,7 +53,7 @@ module Boson
         end
 
         test "not created and warns for commands with no module" do
-          with_config(:commands=>{'frylock'=>{:alias=>'fr'}}) do
+          with_config(:command_aliases=>{'frylock'=>'fr'}) do
             capture_stderr {
               load_library(:name=>'aquateen', :commands=>['frylock'])
             }.should =~ /No aliases/

data/test/repo_test.rb

@@ -16,7 +16,7 @@ class Boson::RepoTest < Test::Unit::TestCase
     end
 
     test "ignores nonexistent file and sets config defaults" do
-      assert @repo.config[:commands].is_a?(Hash) && @repo.config[:libraries].is_a?(Hash)
+      assert @repo.config[:command_aliases].is_a?(Hash) && @repo.config[:libraries].is_a?(Hash)
     end
   end
 end

data/test/runner_test.rb

@@ -3,17 +3,17 @@ require File.join(File.dirname(__FILE__), 'test_helper')
 module Boson
   class RunnerTest < Test::Unit::TestCase
     context "repl_runner" do
-      def start(*args)
+      def start(hash={})
         Hirb.stubs(:enable)
-        Boson.start(*args)
+        Boson.start(hash.merge(:verbose=>false))
       end
 
       before(:all) { reset }
-      before(:each) { Boson::ReplRunner.instance_eval("@initialized = false") }
+      before(:each) { Boson::ConsoleRunner.instance_eval("@initialized = false") }
 
-      test "loads default libraries and libraries in :defaults config" do
+      test "loads default libraries and libraries in :console_defaults config" do
         defaults = Boson::Runner.default_libraries + ['yo']
-        with_config(:defaults=>['yo']) do
+        with_config(:console_defaults=>['yo']) do
           Manager.expects(:load).with {|*args| args[0] == defaults }
           start
         end
@@ -21,12 +21,12 @@ module Boson
 
       test "doesn't call init twice" do
         start
-        ReplRunner.expects(:init).never
+        ConsoleRunner.expects(:init).never
         start
       end
 
       test "loads multiple libraries with :libraries option" do
-        ReplRunner.expects(:init)
+        ConsoleRunner.expects(:init)
         Manager.expects(:load).with([:lib1,:lib2], anything)
         start(:libraries=>[:lib1, :lib2])
       end