boson 0.0.1 → 0.1.0

data/lib/boson/libraries/module_library.rb

@@ -1,5 +1,5 @@
 module Boson
-  # A library which takes a module as a library's name. Reload for this library
+  # This library takes a module as a library's name. Reload for this library
   # subclass is disabled.
   class ModuleLibrary < Library
     #:stopdoc:

data/lib/boson/library.rb

@@ -24,9 +24,31 @@ module Boson
     attr_reader :except, :no_alias_creation, :new_module, :new_commands
     # Optional namespace name for a library. When enabled defaults to a library's name.
     attr_writer :namespace
+
     # Creates a library object with a hash of attributes which must include a :name attribute.
     # Each hash pair maps directly to an instance variable and value. Defaults for attributes
-    # are read from config[:libraries][@library_name]. See Boson::Repo.config for more details.
+    # are read from config[:libraries][@library_name][@attribute].
+    #
+    # Attributes that can be configured:
+    # * *:dependencies*: An array of libraries that this library depends on. A library won't load
+    #   unless its dependencies are loaded first.
+    # * *:commands*: A hash or array of commands that belong to this library. A hash configures command attributes
+    #   for the given commands with command names pointing to their configs. See Command.new for a
+    #   command's configurable attributes. If an array, the commands are set for the given library,
+    #   overidding default command detection.
+    #     Example:
+    #       :commands=>{'commands'=>{:description=>'Lists commands', :alias=>'com'}}
+    # * *:class_commands*: A hash of commands to create. Hash should map command names to any string of ruby code
+    #   that ends with a method call.
+    #     Example:
+    #       :class_commands=>{'spy'=>'Bond.spy', 'create'=>'Alias.manager.create'}
+    # * *:force*: Boolean which forces a library to ignore when a library's methods are overriding existing ones.
+    #   Use with caution. Default is false.
+    # * *:object_methods*: Boolean which detects any Object/Kernel methods created when loading a library and automatically
+    #   adds them to a library's commands. Default is true.
+    # * *:namespace*: Boolean or string which namespaces a library. When true, the library is automatically namespaced
+    #   to the library's name. When a string, the library is namespaced to the string. Default is nil. To control the
+    #   namespacing of all libraries see Boson::Repo.config.
     def initialize(hash)
       @name = set_name hash.delete(:name)
       @loaded = false
@@ -35,7 +57,6 @@ module Boson
       @commands_hash = {}
       @commands = []
       set_config (repo.config[:libraries][@name] || {}).merge(hash)
-      @commands_hash = repo.config[:commands].merge @commands_hash
       set_command_aliases(repo.config[:command_aliases])
       @namespace = true if Boson.repo.config[:auto_namespace] && @namespace.nil? &&
         !Boson::Runner.default_libraries.include?(@module)

data/lib/boson/loader.rb

@@ -4,7 +4,7 @@ module Boson
 
   # This module is mixed into Library to give it load() and reload() functionality.
   # When creating your own Library subclass, you should override load_source_and_set_module and
-  # reload_source_and_set_module. You can override other methods in this module as needed.
+  # reload_source_and_set_module . You can override other methods in this module as needed.
   module Loader
     # Loads a library and its dependencies and returns true if library loads correctly.
     def load
@@ -64,7 +64,7 @@ module Boson
       options[:object_methods] = @object_methods if !@object_methods.nil?
       detected = Util.detect(options, &block)
       @gems += detected[:gems] if detected[:gems]
-      @commands += detected[:methods]
+      @commands += detected[:methods].map {|e| e.to_s }
       detected
     end
 

data/lib/boson/manager.rb

@@ -4,6 +4,7 @@ module Boson
   # Raised when a library's append_features returns false.
   class AppendFeaturesFalseError < StandardError; end
 
+  # Handles loading and reloading of libraries and commands.
   class Manager
     class <<self
       # Loads a library or an array of libraries with options. Manager loads the first library subclass
@@ -62,7 +63,7 @@ module Boson
       rescue Exception=>e
         FileLibrary.reset_file_cache(library.to_s)
         print_error_message "Unable to #{load_method} library #{library}. Reason: #{$!}" + "\n" +
-          e.backtrace.slice(0,3).join("\n")
+          e.backtrace.slice(0,3).map {|e| "  " + e }.join("\n")
       ensure
         Inspector.disable if Inspector.enabled
       end
@@ -103,7 +104,7 @@ module Boson
 
       def loader_create(source)
         lib_class = Library.handle_blocks.find {|k,v| v.call(source) } or raise(LoaderError, "Library #{source} not found.")
-        lib_class[0].new(:name=>source, :index=>@options[:index])
+        lib_class[0].new(@options.merge(:name=>source))
       end
 
       def after_load

data/lib/boson/namespace.rb

@@ -1,25 +1,29 @@
 module Boson
+  # Used in all things namespace.
   class Namespace
-    def self.create_object_namespace(name, library)
-      obj = library.namespace_object
-      obj.instance_eval("class<<self;self;end").send(:define_method, :boson_commands) {
-        self.class.instance_methods(false) }
-      obj.instance_eval("class<<self;self;end").send(:define_method, :object_delegate?) { true }
-      namespaces[name.to_s] = obj
-    end
-
+    # Hash of created namespace names to namespace objects
     def self.namespaces
       @namespaces ||= {}
     end
 
+    # Creates a namespace given its name and the library it belongs to.
     def self.create(name, library)
-      if library.object_namespace && library.module.instance_methods.include?(name)
+      if library.object_namespace && library.module.instance_methods.map {|e| e.to_s}.include?(name)
         library.include_in_universe
         create_object_namespace(name, library)
       else
         create_basic_namespace(name, library)
       end
     end
+    #:stopdoc:
+
+    def self.create_object_namespace(name, library)
+      obj = library.namespace_object
+      obj.instance_eval("class<<self;self;end").send(:define_method, :boson_commands) {
+        self.class.instance_methods(false) }
+      obj.instance_eval("class<<self;self;end").send(:define_method, :object_delegate?) { true }
+      namespaces[name.to_s] = obj
+    end
 
     def self.create_basic_namespace(name, library)
       namespaces[name.to_s] = new(name, library)
@@ -32,14 +36,15 @@ module Boson
       class <<self; self end.send :include, @library.module
     end
 
-    def boson_commands
-      @library.module.instance_methods
-    end
-
     def object_delegate?; false; end
 
     def method_missing(method, *args, &block)
       Boson.can_invoke?(method) ? Boson.invoke(method, *args, &block) : super
     end
+    #:startdoc:
+    # List of subcommands for the namespace.
+    def boson_commands
+      @library.module.instance_methods.map {|e| e.to_s }
+    end
   end
 end

data/lib/boson/option_parser.rb

@@ -1,9 +1,9 @@
 module Boson
-  # Simple Hash with indifferent access
-  class IndifferentAccessHash < ::Hash
+  # Simple Hash with indifferent access. Used by OptionParser.
+  class IndifferentAccessHash < ::Hash #:nodoc:
     def initialize(hash)
       super()
-      update hash.each {|k,v| hash[convert_key(k)] = hash.delete(k) }
+      hash.each {|k,v| self[k] = v }
     end
 
     def [](key)
@@ -24,9 +24,21 @@ module Boson
       end
   end
 
+  # This class provides option parsing for boolean, string, numeric and array
+  # values given a simple hash of options. Setting option values should be straightforward for
+  # *nix people. By option type:
+  # * *:boolean*: These don't have values i.e. '--debug'. To toogle a boolean, prepend with --no- i.e. '--no-debug'.
+  #   Multiple booleans can be joined together i.e. '-d -f -t' == '-dft'.
+  # * *:string*: Separate name from value with space or '=' i.e. '--color red' or '--color=red'.
+  # * *:numeric*: Receives values as :string does or by appending number right after name i.e.
+  #   '-N3' == '-N=3'. 
+  # * *:array*: Receives values as :string does. Multiple values are split by ',' i.e.
+  #   '--fields 1,2,3' -> ['1','2','3']. The split character can be configured as explained at
+  #   OptionParser.new .
   # This is a modified version of Yehuda Katz's Thor::Options class which is a modified version
-  # of Daniel Berger's Getopt::Long class, licensed under Ruby's license.
+  # of Daniel Berger's Getopt::Long class (licensed under Ruby's license).
   class OptionParser
+    # Raised for all OptionParser errors
     class Error < StandardError; end
 
     NUMERIC     = /(\d*\.\d+|\d+)/
@@ -37,28 +49,54 @@ module Boson
     SHORT_NUM   = /^(-[a-zA-Z])#{NUMERIC}$/i
     
     attr_reader :leading_non_opts, :trailing_non_opts, :opt_aliases
-    
+
+    # Array of arguments left after defined options have been parsed out by parse.
     def non_opts
       leading_non_opts + trailing_non_opts
     end
 
-    # Takes an array of options. Each array consists of up to three
-    # elements that indicate the name and type of option. Returns a hash
-    # containing each option name, minus the '-', as a key. The value
-    # for each key depends on the type of option and/or the value provided
-    # by the user.
+    # Takes a hash of options. Each option, a key-value pair, must provide the option's
+    # name and type. Names longer than one character are accessed with '--' while
+    # one character names are accessed with '-'. Names can be symbols, strings
+    # or even dasherized strings:
+    #
+    #    Boson::OptionParser.new :debug=>:boolean, 'level'=>:numeric,
+    #      '--fields'=>:array
+    #
+    # Options can have default values and implicit types simply by changing the
+    # option type for the default value:
+    #
+    #    Boson::OptionParser.new :debug=>true, 'level'=>3.1, :fields=>%w{f1 f2}
+    #
+    # By default every option name longer than one character is given an alias,
+    # the first character from its name. For example, the --fields option
+    # has -f as its alias. You can override the default alias by providing your own
+    # option aliases as an array in the option's key.
+    #
+    #    Boson::OptionParser.new [:debug, :damnit, :D]=>true
+    #
+    # Note that aliases are accessed the same way as option names. For the above,
+    # --debug, --damnit and -D all refer to the same option.
     #
-    # The long option _must_ be provided. The short option defaults to the
-    # first letter of the option. The default type is :boolean.
+    # Options can have additional attributes by passing a hash to the option value instead of
+    # a type or default:
+    # 
+    #    Boson::OptionParser.new :fields=>{:type=>:array, :values=>%w{f1 f2 f3},
+    #     :enum=>false}
     #
-    # Example:
+    # Here are the available option attributes:
     #
-    #   opts = Boson::OptionParser.new(
-    #      "--debug" => true,
-    #      ["--verbose", "-v"] => true,
-    #      ["--level", "-l"] => :numeric
-    #   ).parse(args)
+    # * *:type*: This or :default is required. Available types are :string, :boolean, :array, :numeric.
+    # * *:default*: This or :type is required. This is the default value an option has when not passed.
+    # * *:values*: An array of values an option can have. Available for :array and :string options.  Values here
+    #   can be aliased by typing a unique string it starts with. For example:
+    #      
+    #     For values foo, odd, optional: f refers to foo, o to odd and op to optional.
     #
+    # * *:enum*: Boolean indicating if an option enforces values in :values. Default is true. Available for
+    #   :array and :string options.
+    # * *:split*: Only for :array options. A string or regular expression on which an array value splits
+    #   to produce an array of values. Default is ','.
     def initialize(opts)
       @defaults = {}
       @opt_aliases = {}
@@ -114,6 +152,11 @@ module Boson
       }
     end
 
+    # Parses an array of arguments for defined options to return a hash. Once the parser
+    # recognizes a valid option, it continues to parse until an non option argument is detected.
+    # Flags that can be passed to the parser:
+    # * :opts_before_args: When true options must come before arguments. Default is false.
+    # * :delete_invalid_opts: When true deletes any invalid options left after parsing. Default is false.
     def parse(args, flags={})
       @args = args
       # start with defaults
@@ -151,6 +194,7 @@ module Boson
       hash
     end
 
+    # One-line option usage
     def formatted_usage
       return "" if @opt_types.empty?
       @opt_types.map do |opt, type|
@@ -173,6 +217,7 @@ module Boson
 
     alias :to_s :formatted_usage
 
+    # More verbose option help in the form of a table.
     def print_usage_table(render_options={})
       aliases = @opt_aliases.invert
       additional = [:desc, :values].select {|e| (@option_attributes || {}).values.any? {|f| f.key?(e) } }

data/lib/boson/repo.rb

@@ -1,35 +1,54 @@
 %w{yaml fileutils}.each {|e| require e }
 module Boson
+  # A class for repositories. A repository has a root directory with required subdirectories config/ and
+  # commands/ and optional subdirectory lib/. Each repository has a primary config file at config/boson.yml.
   class Repo
-    def self.commands_dir(dir)
+    def self.commands_dir(dir) #:nodoc:
       File.join(dir, 'commands')
     end
 
     attr_accessor :dir, :config
+    # Creates a repository given a root directory.
     def initialize(dir)
       @dir = dir
     end
 
+    # Points to the config/ subdirectory and is automatically created when called. Used for config files.
     def config_dir
-      @config_dir ||= FileUtils.mkdir_p File.join(dir, 'config')
+      @config_dir ||= FileUtils.mkdir_p("#{dir}/config") && "#{dir}/config"
     end
 
+    # Points to the commands/ subdirectory and is automatically created when called. Used for command libraries.
     def commands_dir
-      @commands_dir ||= FileUtils.mkdir_p self.class.commands_dir(@dir)
+      @commands_dir ||= (cdir = self.class.commands_dir(@dir)) && FileUtils.mkdir_p(cdir) && cdir
     end
 
+    # A hash read from the YAML config file at config/boson.yml.
+    # {See here}[http://github.com/cldwalker/irbfiles/blob/master/boson/config/boson.yml] for an example config file.
     # ==== Valid config keys:
-    # [:libraries] Hash of libraries mapping their name to attribute hashes.
-    # [:commands] Hash of commands mapping their name to attribute hashes.
-    # [:defaults] Array of libraries to load at start up.
-    # [:add_load_path] Boolean specifying whether to add a load path pointing to the lib under boson's directory. Defaults to false if
-    #                  the lib directory isn't defined in the boson directory. Default is false.
-    # [:error_method_conflicts] Boolean specifying library loading behavior when one of its methods conflicts with existing methods in
+    # [:libraries] Hash of libraries mapping their name to attribute hashes. See Library.new for configurable attributes.
+    #               Example:
+    #               :libraries=>{'completion'=>{:namespace=>true}}
+    # [:command_aliases] Hash of commands names and their aliases. Since this is global it will be read by _all_ libraries.
+    #                    This is useful for quickly creating aliases without having to worry about placing them under
+    #                    the correct library config. For non-global aliasing, aliases should be placed under the :command_aliases
+    #                    key of a library entry in :libraries.
+    #                     Example:
+    #                      :command_aliases=>{'libraries'=>'lib', 'commands'=>'com'}
+    # [:console_defaults] Array of libraries to load at start up when used in irb. Default is to load all library files and libraries defined
+    #             in the config.
+    # [:bin_defaults] Array of libraries to load at start up when used from the commandline. Default is no libraries.
+    # [:add_load_path] Boolean specifying whether to add a load path pointing to the lib subdirectory/. This is useful in sharing
+    #                  classes between libraries without resorting to packaging them as gems. Defaults to false if the lib
+    #                  subdirectory doesn't exist in the boson directory.
+    # [:error_method_conflicts] Boolean specifying library loading behavior when its methods conflicts with existing methods in
     #                           the global namespace. When set to false, Boson automatically puts the library in its own namespace.
     #                           When set to true, the library fails to load explicitly. Default is false.
+    # [:console] Console to load when using --console from commandline. Default is irb.
+    # [:auto_namespace] Boolean which automatically namespaces all user-defined libraries. Default is false.
     def config(reload=false)
       if reload || @config.nil?
-        default = {:commands=>{}, :libraries=>{}, :command_aliases=>{}, :defaults=>[]}
+        default = {:libraries=>{}, :command_aliases=>{}, :console_defaults=>[]}
         @config = default.merge(YAML::load_file(config_dir + '/boson.yml')) rescue default
       end
       @config

data/lib/boson/runner.rb

@@ -1,37 +1,43 @@
 module Boson
+  # Base class for runners.
   class Runner
     class<<self
+      # Enables view, adds local load path and loads default_libraries
       def init
         View.enable
         add_load_path
         Manager.load default_libraries, load_options
       end
 
-      def add_load_path
-        Boson.repos.each {|repo|
-          if repo.config[:add_load_path] || File.exists?(File.join(repo.dir, 'lib'))
-            $: <<  File.join(repo.dir, 'lib') unless $:.include? File.expand_path(File.join(repo.dir, 'lib'))
-          end
-        }
-      end
-
-      def load_options
-        {:verbose=>@options[:verbose]}
-      end
-
+      # Libraries that come with Boson
       def default_libraries
         [Boson::Commands::Core, Boson::Commands::WebCore]
       end
 
+      # Libraries detected in repositories
       def detected_libraries
         Boson.repos.map {|repo| Dir[File.join(repo.commands_dir, '**/*.rb')].
           map {|e| e.gsub(/.*commands\//,'').gsub('.rb','') } }.flatten
       end
 
+      # Libraries specified in config files and detected_libraries
       def all_libraries
         (detected_libraries + Boson.repos.map {|e| e.config[:libraries].keys}.flatten).uniq
       end
 
+      #:stopdoc:
+      def add_load_path
+        Boson.repos.each {|repo|
+          if repo.config[:add_load_path] || File.exists?(File.join(repo.dir, 'lib'))
+            $: <<  File.join(repo.dir, 'lib') unless $:.include? File.expand_path(File.join(repo.dir, 'lib'))
+          end
+        }
+      end
+
+      def load_options
+        {:verbose=>@options[:verbose]}
+      end
+
       def define_autoloader
         class << ::Boson.main_object
           def method_missing(method, *args, &block)
@@ -45,7 +51,7 @@ module Boson
           end
         end
       end
-
+      #:startdoc:
     end
   end
 end

data/lib/boson/runners/bin_runner.rb

@@ -1,36 +1,53 @@
 module Boson
+  # Runs Boson from the commandline. Usage for the boson shell command looks like this:
+  #   boson [GLOBAL OPTIONS] [COMMAND] [ARGS] [COMMAND OPTIONS]
+  #
+  # The boson executable comes with these global options:
+  # [:help]  Gives a basic help of global options. When a command is given the help shifts to a command's help.
+  # [:verbose] Using this along with :help option shows more help. Also gives verbosity to other actions i.e. loading.
+  # [:index] Updates index. This should be called in the unusual case that Boson doesn't detect new commands
+  #          and libraries.
+  # [:execute] Like ruby -e, this executes a string of ruby code. However, this has the advantage that all
+  #            commands are available as normal methods, automatically loading as needed. This is a good
+  #            way to call commands that take non-string arguments.
+  # [:console] This drops Boson into irb after having loaded default commands and any explict libraries with
+  #                :load option. This is a good way to start irb with only certain libraries loaded.
+  # [:load] Explicitly loads a list of libraries separated by commas. Most useful when used with :console option.
+  #         Can also be used to explicitly load libraries that aren't being detected automatically.
+  # [:render] Pretty formats the results of commands without options. Handy for commands that return arrays.
   class BinRunner < Runner
     GLOBAL_OPTIONS =  {
       :verbose=>{:type=>:boolean, :desc=>"Verbose description of loading libraries or help"},
-      :index=>{:type=>:boolean, :desc=>"Updates index"},
+      :index=>{:type=>:boolean, :desc=>"Updates index for libraries and commands"},
       :execute=>{:type=>:string, :desc=>"Executes given arguments as a one line script"},
-      :repl=>{:type=>:boolean, :desc=>"Drops into irb or another given repl/shell with default and explicit libraries loaded"},
+      :console=>{:type=>:boolean, :desc=>"Drops into irb with default and explicit libraries loaded"},
       :help=>{:type=>:boolean, :desc=>"Displays this help message or a command's help if given a command"},
-      :load=>{:type=>:array, :values=>all_libraries, :enum=>false, :desc=>"A comma delimited array of libraries to load"}
-    }
+      :load=>{:type=>:array, :values=>all_libraries, :enum=>false, :desc=>"A comma delimited array of libraries to load"},
+      :render=>{:type=>:boolean, :desc=>"Renders a Hirb view from result of command without options"}
+    } #:nodoc:
 
     class <<self
       attr_accessor :command
+      # Starts, processes and ends a commandline request.
       def start(args=ARGV)
         @command, @options, @args = parse_args(args)
-        return print_usage if args.empty? || (@command.nil? && !@options[:repl] && !@options[:execute])
-        return ReplRunner.bin_start(@options[:repl], @options[:load]) if @options[:repl]
+        return print_usage if args.empty? || (@command.nil? && !@options[:console] && !@options[:execute])
+        return ConsoleRunner.bin_start(@options[:console], @options[:load]) if @options[:console]
         init
 
         if @options[:help]
-          print_command_help
+          Boson.invoke(:usage, @command, :verbose=>@options[:verbose])
         elsif @options[:execute]
           Boson.main_object.instance_eval @options[:execute]
         else
           execute_command
         end
       rescue Exception
-        message = (@command && !Boson.can_invoke?(@command)) ?
+        print_error_message (@command && !Boson.can_invoke?(@command[/\w+/])) ?
           "Error: Command '#{@command}' not found" : "Error: #{$!.message}"
-        message += "\nActual error: #{$!}\n" + $!.backtrace.inspect if @options && @options[:verbose]
-        $stderr.puts message
       end
 
+      # Loads the given command.
       def init
         super
         Index.update(:verbose=>true) if @options[:index]
@@ -43,6 +60,12 @@ module Boson
         end
       end
 
+      #:stopdoc:
+      def print_error_message(message)
+        message += "\nActual error: #{$!}\n" + $!.backtrace.inspect if @options && @options[:verbose]
+        $stderr.puts message
+      end
+
       def load_command_by_index
         Index.update(:verbose=>@options[:verbose]) if !@options[:index] && Boson.can_invoke?(@command) && !@options[:help]
         if !Boson.can_invoke?(@command) && ((lib = Index.find_library(@command)) ||
@@ -58,15 +81,12 @@ module Boson
       def execute_command
         command, subcommand = @command.include?('.') ? @command.split('.', 2) : [@command, nil]
         dispatcher = subcommand ? Boson.invoke(command) : Boson.main_object
-        @args = @args.join(" ") if ((com = Boson::Command.find(@command)) && com.option_command?)
         render_output dispatcher.send(subcommand || command, *@args)
       rescue ArgumentError
-        puts "Wrong number of arguments for #{@command}\n\n"
-        print_command_help
-      end
-
-      def print_command_help
-        Boson.invoke(:usage, @command, :verbose=>@options[:verbose])
+        # for the rare case it's raise outside of boson
+        raise unless $!.backtrace.first.include?('boson/')
+        print_error_message "'#{@command}' was called incorrectly."
+        Boson.invoke(:usage, @command)
       end
 
       def parse_args(args)
@@ -77,10 +97,10 @@ module Boson
       end
 
       def render_output(output)
-        if Scientist.global_options
-          puts output.inspect unless Scientist.rendered
-        else
-          View.render(output)
+        if Scientist.global_options && !Scientist.rendered && !View.silent_object?(output)
+          puts output.inspect
+        elsif !Scientist.global_options && @options[:render]
+          View.render(output, :silence_booleans=>true)
         end
       end
 
@@ -95,6 +115,7 @@ module Boson
           Boson.invoke :commands, "", :fields=>["name", "usage", "description"], :description=>false
         end
       end
+      #:startdoc:
     end
   end
 end