boson 0.1.0 → 0.2.0

data/lib/boson/libraries/gem_library.rb

@@ -1,6 +1,12 @@
 module Boson
   # This library loads a gem by the given name. Unlike FileLibrary or ModuleLibrary, this library
   # doesn't need a module to provide its functionality.
+  #
+  # Example:
+  #   >> load_library 'httparty', :class_commands=>{'put'=>'HTTParty.put',
+  #      'delete'=>'HTTParty.delete' }
+  #   => true
+  #   >> put 'http://someurl.com'
   class GemLibrary < Library
     #:stopdoc:
     def self.is_a_gem?(name)

data/lib/boson/libraries/module_library.rb

@@ -1,6 +1,22 @@
 module Boson
-  # This library takes a module as a library's name. Reload for this library
-  # subclass is disabled.
+  # This library takes a module or class as a library's name and loads its class methods
+  # as commands. If no commands are given it defaults to loading all of its class methods
+  # as commands. The only method callback (see Loader) this library calls on the
+  # original module/class is config().
+  #
+  # Example:
+  #  >> load_library Math, :commands=>%w{sin cos tan}
+  #  => true
+  #
+  #  # Let's brush up on ol trig
+  #  >> sin (Math::PI/2)
+  #  => 1.0
+  #  >> tan (Math::PI/4)
+  #  => 1.0
+  #  # Close enough :)
+  #  >> cos (Math::PI/2)
+  #  => 6.12323399573677e-17
+
   class ModuleLibrary < Library
     #:stopdoc:
     handles {|source| source.is_a?(Module) }
@@ -11,7 +27,11 @@ module Boson
       super Util.underscore(underscore_lib)
     end
 
-    def reload; false; end
+    def initialize_library_module
+      @class_commands = {@module.to_s=>Array(@commands).empty? ? @module.methods(false) : @commands }
+      @module = nil
+      super
+    end
     #:startdoc:
   end
-end
+end

data/lib/boson/libraries/require_library.rb

@@ -1,5 +1,13 @@
 # This library requires the given name. This is useful for loading standard libraries,
 # non-gem libraries (i.e. rip packages) and anything else in $LOAD_PATH.
+#
+# Example:
+#   >> load_library 'fileutils', :class_commands=>{'cd'=>'FileUtils.cd', 'cp'=>'FileUtils.cp'}
+#   => true
+#   >> cd '/home'
+#   => 0
+#   >> Dir.pwd
+#   >> '/home'
 class Boson::RequireLibrary < Boson::GemLibrary
   handles {|source|
     begin

data/lib/boson/library.rb

@@ -2,7 +2,33 @@ module Boson
   # A library is a group of commands (Command objects) usually grouped together by a module.
   # Libraries are loaded from different sources depending on the library subclass. Default library
   # subclasses are FileLibrary, GemLibrary, RequireLibrary and ModuleLibrary.
+  # See Loader for callbacks a library's module can have.
   #
+  # == Naming a Library Module
+  # Although you can name a library module almost anything, here's the fine print:
+  # * A module can have any name if it's the only module in a library.
+  # * If there are multiple modules in a file library, the module's name must be a camelized version
+  #   of the file's basename i.e. ~/.boson/commands/ruby_core.rb -> RubyCore.
+  # * Although modules are evaluated under the Boson::Commands namespace, Boson will warn you about creating
+  #   modules whose name is the same as a top level class/module. The warning is to encourage users to stay
+  #   away from error-prone libraries. Once you introduce such a module, _all_ libraries assume the nested module
+  #   over the top level module and the top level module has to be prefixed with '::' _everywhere_.
+  #
+  # == Configuration
+  # To configure a library, pass a hash of {library attributes}[link:classes/Boson/Library.html#M000077] under
+  # {the :libraries key}[link:classes/Boson/Repo.html#M000070] of a config file. When not using FileLibrary,
+  # you can give most commands the functionality FileLibrary naturally gives its commands by configuring
+  # the :commands key. Here's a config example of a GemLibrary that does that:
+  #   :libraries:
+  #     httparty:
+  #       :class_commands:
+  #         delete: HTTParty.delete
+  #       :commands:
+  #         delete:
+  #           :alias: d
+  #           :description: Http delete a given url
+  #
+  # === Creating Your Own Library
   # To create your own subclass you need to define what sources the subclass can handle with handles().
   # If handles() returns true then the subclass is chosen to load. See Loader to see what instance methods
   # to override for a subclass.
@@ -18,49 +44,49 @@ module Boson
     end
 
     # Public attributes for use outside of Boson.
-    ATTRIBUTES = [:gems, :dependencies, :commands, :loaded, :module, :name, :namespace]
+    ATTRIBUTES = [:gems, :dependencies, :commands, :loaded, :module, :name, :namespace, :indexed_namespace]
     attr_reader *(ATTRIBUTES + [:commands_hash, :library_file, :object_namespace])
     # Private attribute for use within Boson.
-    attr_reader :except, :no_alias_creation, :new_module, :new_commands
+    attr_reader :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][@attribute].
+    # are read from config[:libraries][@library_name][@attribute]. When loading libraries, attributes
+    # can also be set via a library module's config() method (see Loader).
     #
     # 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.
+    # [*: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. A hash key-pair can map command names to any string of ruby code
+    #                     that ends with a method call. Or a key-pair can map a class to an array of its class methods
+    #                     to create commands of the same name. Example:
+    #                      :class_commands=>{'spy'=>'Bond.spy', 'create'=>'Alias.manager.create',
+    #                       'Boson::Util'=>['detect', 'any_const_get']}
+    # [*: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.
+    # [*:no_alias_creation*] Boolean which doesn't create aliases for a library. Useful for libraries that configure command
+    #                        aliases outside of Boson's control. Default is false.
     def initialize(hash)
-      @name = set_name hash.delete(:name)
-      @loaded = false
       repo = set_repo
       @repo_dir = repo.dir
+      @name = set_name hash.delete(:name)
+      @loaded = false
       @commands_hash = {}
       @commands = []
-      set_config (repo.config[:libraries][@name] || {}).merge(hash)
+      set_config (repo.config[:libraries][@name] || {}).merge(hash), true
       set_command_aliases(repo.config[:command_aliases])
-      @namespace = true if Boson.repo.config[:auto_namespace] && @namespace.nil? &&
-        !Boson::Runner.default_libraries.include?(@module)
-      @namespace = clean_name if @namespace
     end
 
     # A concise symbol version of a library type i.e. FileLibrary -> :file.
@@ -69,9 +95,19 @@ module Boson
       str.downcase.to_sym
     end
 
+    def namespace(orig=@namespace)
+      @namespace = [String,FalseClass].include?(orig.class) ? orig : begin
+        if (@namespace == true || (Boson.repo.config[:auto_namespace] && !@index))
+          @namespace = clean_name
+        else
+          @namespace = false
+        end
+      end
+    end
+
     # The object a library uses for executing its commands.
     def namespace_object
-      @namespace_object ||= @namespace ? Boson.invoke(@namespace) : Boson.main_object
+      @namespace_object ||= namespace ? Boson.invoke(namespace) : Boson.main_object
     end
 
     #:stopdoc:
@@ -84,7 +120,7 @@ module Boson
       name.to_s or raise ArgumentError, "New library missing required key :name"
     end
 
-    def set_config(config)
+    def set_config(config, force=false)
       if (commands = config.delete(:commands))
         if commands.is_a?(Array)
           @commands += commands
@@ -95,7 +131,7 @@ module Boson
         end
       end
       set_command_aliases config.delete(:command_aliases) if config[:command_aliases]
-      set_attributes config, true
+      set_attributes config, force
     end
 
     def set_command_aliases(command_aliases)
@@ -113,16 +149,20 @@ module Boson
       hash.each {|k,v| instance_variable_set("@#{k}", v) if instance_variable_get("@#{k}").nil? || force }
     end
 
-    def command_objects(names)
-      Boson.commands.select {|e| names.include?(e.name) && e.lib == self.name }
+    def command_objects(names=self.commands, command_array=Boson.commands)
+      command_array.select {|e| names.include?(e.name) && e.lib == self.name }
+    end
+
+    def command_object(name)
+      command_objects([name])[0]
     end
 
     def marshal_dump
-      [@name, @commands, @gems, @module.to_s, @repo_dir]
+      [@name, @commands, @gems, @module.to_s, @repo_dir, @indexed_namespace]
     end
 
     def marshal_load(ary)
-      @name, @commands, @gems, @module, @repo_dir = ary
+      @name, @commands, @gems, @module, @repo_dir, @indexed_namespace = ary
     end
     #:startdoc:
   end

data/lib/boson/loader.rb

@@ -5,6 +5,27 @@ 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.
+  #
+  # === Module Callbacks
+  # For libraries that have a module i.e. FileLibrary and GemLibrary, the following class methods
+  # are invoked in the order below when loading a library:
+  #
+  # [*:config*] This method returns a library's hash of attributes as explained by Library.new. This is useful
+  #             for distributing libraries with a default configuration. The library attributes specified here
+  #             are overridden by ones a user has in their config file except for the :commands attribute, which
+  #             is recursively merged together.
+  # [*:append_features*] In addition to its normal behavior, this method's return value determines if a
+  #                      library is loaded in the current environment. This is useful for libraries that you
+  #                      want loaded by default but not in some environments i.e. different ruby versions or
+  #                      in irb but not in script/console. Remember to use super when returning true.
+  # [*:included*] In addition to its normal behavior, this method should be used to require external libraries.
+  #               Although requiring dependencies could be done anywhere in a module, putting dependencies here
+  #               are encouraged. By not having dependencies hardcoded in a module, it's possible to analyze
+  #               and view a library's commands without having to install and load its dependencies.
+  #               If creating commands here, note that conflicts with existing commands won't be detected.
+  # [*:after_included*] This method is called after included() to initialize functionality. This is useful for
+  #                     libraries that are primarily executing ruby code i.e. defining ruby extensions or
+  #                     setting irb features. This method isn't called when indexing a library.
   module Loader
     # Loads a library and its dependencies and returns true if library loads correctly.
     def load
@@ -12,9 +33,9 @@ module Boson
       load_source_and_set_module
       module_callbacks if @module
       yield if block_given?
-      (@module || @class_commands) ? detect_additions { load_module_commands } : @namespace = nil
-      @init_methods.each {|m| namespace_object.send(m) if namespace_object.respond_to?(m) } if @init_methods && !@index
+      (@module || @class_commands) ? detect_additions { load_module_commands } : @namespace = false
       set_library_commands
+      @indexed_namespace = (@namespace == false) ? nil : @namespace if @index
       loaded_correctly? && (@loaded = true)
     end
 
@@ -26,7 +47,8 @@ module Boson
       !!@module
     end
 
-    # Reloads a library from its source and adds new commands.
+    # Reloads a library from its source and adds new commands. Only implemented
+    # for FileLibrary for now.
     def reload
       original_commands = @commands
       reload_source_and_set_module
@@ -49,12 +71,13 @@ module Boson
     end
 
     def load_module_commands
-        initialize_library_module
+      initialize_library_module
     rescue MethodConflictError=>e
-      if Boson.repo.config[:error_method_conflicts] || @namespace
+      if Boson.repo.config[:error_method_conflicts] || namespace
         raise MethodConflictError, e.message
       else
         @namespace = clean_name
+        @method_conflict = true
         $stderr.puts "#{e.message}. Attempting load into the namespace #{@namespace}..."
         initialize_library_module
       end
@@ -71,20 +94,27 @@ module Boson
     def initialize_library_module
       @module = @module ? Util.constantize(@module) : Util.create_module(Boson::Commands, clean_name)
       raise(LoaderError, "No module for library #{@name}") unless @module
-      Manager.create_class_aliases(@module, @class_commands) unless @class_commands.to_s.empty?
+      if (conflict = Util.top_level_class_conflict(Boson::Commands, @module.to_s))
+        warn "Library module '#{@module}' may conflict with top level class/module '#{conflict}' references in"+
+          " your libraries. Rename your module to avoid this warning."
+      end
+
+      Manager.create_class_aliases(@module, @class_commands) unless @class_commands.to_s.empty? || @method_conflict
       check_for_method_conflicts unless @force
       @namespace = clean_name if @object_namespace
-      @namespace ? Namespace.create(@namespace, self) : include_in_universe
+      namespace ? Namespace.create(namespace, self) : include_in_universe
     end
 
     def include_in_universe(lib_module=@module)
       Boson::Universe.send :include, lib_module
+      @module.after_included if lib_module.respond_to?(:after_included) && !@index
       Boson::Universe.send :extend_object, Boson.main_object
     end
 
     def check_for_method_conflicts
-      conflicts = @namespace ? (Boson.can_invoke?(@namespace) ? [@namespace] : []) :
-        Util.common_instance_methods(@module, Boson::Universe)
+      conflicts = namespace ? (Boson.can_invoke?(namespace) ? [namespace] : []) :
+        (@module.instance_methods + @module.private_instance_methods) & (Boson.main_object.methods +
+          Boson.main_object.private_methods)
       unless conflicts.empty?
         raise MethodConflictError,"The following commands conflict with existing commands: #{conflicts.join(', ')}"
       end
@@ -93,9 +123,8 @@ module Boson
     def set_library_commands
       aliases = @commands_hash.select {|k,v| @commands.include?(k) }.map {|k,v| v[:alias]}.compact
       @commands -= aliases
-      @commands.delete(@namespace) if @namespace
-      @commands += Boson.invoke(@namespace).boson_commands if @namespace && !@pre_defined_commands
-      @commands -= @except if @except
+      @commands.delete(namespace) if namespace
+      @commands += Boson.invoke(namespace).boson_commands if namespace && !@pre_defined_commands
       @commands.uniq!
     end
     #:startdoc:

data/lib/boson/manager.rb

@@ -7,17 +7,18 @@ module Boson
   # Handles loading and reloading of libraries and commands.
   class Manager
     class <<self
+      attr_accessor :failed_libraries
+
       # Loads a library or an array of libraries with options. Manager loads the first library subclass
       # to meet a library subclass' criteria in this order: ModuleLibrary, FileLibrary, GemLibrary, RequireLibrary.
       # ==== Examples:
       #   Manager.load 'my_commands'  -> Loads a FileLibrary object from ~/.boson/commands/my_commands.rb
       #   Manager.load 'method_lister' -> Loads a GemLibrary object which requires the method_lister gem
+      # Any options that aren't listed here are passed as library attributes to the libraries (see Library.new)
       # ==== Options:
       # [:verbose] Boolean to print each library's loaded status along with more verbose errors. Default is false.
-      # [:index]   Boolean to load in index mode. Default is false.
       def load(libraries, options={})
-        libraries = [libraries] unless libraries.is_a?(Array)
-        libraries.map {|e|
+        Array(libraries).map {|e|
           (@library = load_once(e, options)) ? after_load : false
         }.all?
       end
@@ -45,6 +46,10 @@ module Boson
       end
 
       #:stopdoc:
+      def failed_libraries
+        @failed_libraries ||= []
+      end
+
       def add_library(lib)
         Boson.libraries.delete(Boson.library(lib.name))
         Boson.libraries << lib
@@ -59,19 +64,18 @@ module Boson
       rescue AppendFeaturesFalseError
       rescue LoaderError=>e
         FileLibrary.reset_file_cache(library.to_s)
-        print_error_message "Unable to #{load_method} library #{library}. Reason: #{e.message}"
+        failed_libraries << library
+        $stderr.puts "Unable to #{load_method} library #{library}. Reason: #{e.message}"
       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).map {|e| "  " + e }.join("\n")
+        failed_libraries << library
+        message = "Unable to #{load_method} library #{library}. Reason: #{$!}"
+        message += "\n" + e.backtrace.slice(0,3).map {|e| "  " + e }.join("\n") if @options[:verbose]
+        $stderr.puts message
       ensure
         Inspector.disable if Inspector.enabled
       end
 
-      def print_error_message(message)
-        $stderr.puts message if !@options[:index] || (@options[:index] && @options[:verbose])
-      end
-
       def load_once(source, options={})
         @options = options
         rescue_load_action(source, :load) do
@@ -129,10 +133,6 @@ module Boson
       end
 
       def create_commands(lib, commands=lib.commands)
-        if lib.except
-          commands -= lib.except
-          lib.except.each {|e| lib.namespace_object.instance_eval("class<<self;self;end").send :undef_method, e }
-        end
         before_create_commands(lib)
         commands.each {|e| Boson.commands << Command.create(e, lib)}
         create_command_aliases(lib, commands) if commands.size > 0 && !lib.no_alias_creation
@@ -170,6 +170,11 @@ module Boson
       end
 
       def create_class_aliases(mod, class_commands)
+        class_commands.each {|k,v|
+          if v.is_a?(Array)
+            class_commands.delete(k).each {|e| class_commands[e] = "#{k}.#{e}"}
+          end
+        }
         Alias.manager.create_aliases(:any_to_instance_method, mod.to_s=>class_commands.invert)
       end
 

data/lib/boson/option_parser.rb

@@ -1,6 +1,8 @@
 module Boson
-  # Simple Hash with indifferent access. Used by OptionParser.
-  class IndifferentAccessHash < ::Hash #:nodoc:
+  # Simple Hash with indifferent fetching and storing using symbol or string keys. Other actions such as
+  # merging should assume symbolic keys. Used by OptionParser.
+  class IndifferentAccessHash < ::Hash
+    #:stopdoc:
     def initialize(hash)
       super()
       hash.each {|k,v| self[k] = v }
@@ -19,22 +21,49 @@ module Boson
     end
 
     protected
-      def convert_key(key)
-        key.kind_of?(String) ? key.to_sym : key
-      end
+    def convert_key(key)
+      key.kind_of?(String) ? key.to_sym : key
+    end
+    #:startdoc:
   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 class concisely defines commandline options that when parsed produce a Hash of option keys and values.
+  # Additional points:
+  # * Setting option values should follow conventions in *nix environments. See examples below.
+  # * By default, there are 5 option types, each which produce different objects for option values.
+  # * The default option types can produce objects for one or more of the following Ruby classes:
+  #   String, Integer, Float, Array, Hash, FalseClass, TrueClass.
+  # * Users can define their own option types which create objects for _any_ Ruby class. See Options.
+  # * Each option type can have attributes to enable more features (see OptionParser.new).
+  # * When options are parsed by OptionParser.parse, an IndifferentAccessHash hash is returned.
+  # * Options are also called switches, parameters, flags etc.
+  #
+  # Default option types:
+  # [*:boolean*] This option has no passed value. To toogle a boolean, prepend with '--no-'.
+  #              Multiple booleans can be joined together.
+  #                '--debug'    -> {:debug=>true}
+  #                '--no-debug' -> {:debug=>false}
+  #                '--no-d'     -> {:debug=>false}
+  #                '-d -f -t' same as '-dft'
+  # [*:string*] Sets values by separating name from value with space or '='.
+  #               '--color red' -> {:color=>'red'}
+  #               '--color=red' -> {:color=>'red'}
+  #               '--color "gotta love spaces"' -> {:color=>'gotta love spaces'}
+  # [*:numeric*] Sets values as :string does or by appending number right after aliased name. Shortened form
+  #              can be appended to joined booleans.
+  #                '-n3'  -> {:num=>3}
+  #                '-dn3' -> {:debug=>true, :num=>3}
+  # [*:array*] Sets values as :string does. Multiple values are split by a configurable character
+  #            Default is ',' (see OptionParser.new). Passing '*' refers to all known :values.
+  #             '--fields 1,2,3' -> {:fields=>['1','2','3']}
+  #             '--fields *'     -> {:fields=>['1','2','3']}
+  # [*:hash*] Sets values as :string does. Key-value pairs are split by ':' and pairs are split by
+  #           a configurable character (default ','). Multiple keys can be joined to one value. Passing '*'
+  #           as a key refers to all known :keys.
+  #             '--fields a:b,c:d' -> {:fields=>{'a'=>'b', 'c'=>'d'} }
+  #             '--fields a,b:d'   -> {:fields=>{'a'=>'d', 'b'=>'d'} }
+  #             '--fields *:d'     -> {:fields=>{'a'=>'d', 'b'=>'d', 'c'=>'d'} }
+  #
   # 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).
   class OptionParser
@@ -84,19 +113,29 @@ module Boson
     #    Boson::OptionParser.new :fields=>{:type=>:array, :values=>%w{f1 f2 f3},
     #     :enum=>false}
     #
-    # Here are the available option attributes:
-    #
-    # * *: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.
+    # These attributes are available when an option is parsed via current_attributes().
+    # Here are the available option attributes for the default option types:
     #
-    # * *: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 ','.
+    # [*:type*] This or :default is required. Available types are :string, :boolean, :array, :numeric, :hash.
+    # [*:default*] This or :type is required. This is the default value an option has when not passed.
+    # [*:bool_default*] This is the value an option has when passed as a boolean. However, by enabling this
+    #                   an option can only have explicit values with '=' i.e. '--index=alias' and no '--index alias'.
+    #                   If this value is a string, it is parsed as any option value would be. Otherwise, the value is
+    #                   passed directly without parsing.
+    # [*:required*] Boolean indicating if option is required. Option parses raises error if value not given.
+    #               Default is false.
+    # [*:alias*] Alternative way to define option aliases with an option name or an array of them. Useful in yaml files.
+    #            Setting to false will prevent creating an automatic alias.
+    # [*: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 or :keys. Default is true. For
+    #           :array, :hash and :string options.
+    # [*:split*] For :array and :hash options. A string or regular expression on which an array value splits
+    #            to produce an array of values. Default is ','.
+    # [*:keys*] :hash option only. An array of values a hash option's keys can have. Keys can be aliased just like :values.
+    # [:default_keys] :hash option only. Default keys to assume when only a value is given. Multiple keys can be joined
+    #                 by the :split character. Defaults to first key of :keys if :keys given.
     def initialize(opts)
       @defaults = {}
       @opt_aliases = {}
@@ -120,19 +159,22 @@ module Boson
         if type.is_a?(Hash)
           @option_attributes ||= {}
           @option_attributes[nice_name] = type
+          @opt_aliases[nice_name] = Array(type[:alias]) if type.key?(:alias)
           @defaults[nice_name] = type[:default] if type[:default]
-          @option_attributes[nice_name][:enum] = true if type.key?(:values) && !type.key?(:enum)
-          type = determine_option_type(type[:default]) || type[:type] || :boolean
+          @option_attributes[nice_name][:enum] = true if (type.key?(:values) || type.key?(:keys)) &&
+            !type.key?(:enum)
+          @option_attributes[nice_name][:default_keys] ||= type[:keys][0] if type.key?(:keys)
+          type = type[:type] || (!type[:default].nil? ? determine_option_type(type[:default]) : :boolean)
         end
 
         # set defaults
         case type
-          when TrueClass               then  @defaults[nice_name] = true
-          when FalseClass              then  @defaults[nice_name] = false
-          when String, Numeric, Array  then  @defaults[nice_name] = type
+        when TrueClass                     then  @defaults[nice_name] = true
+        when FalseClass                    then  @defaults[nice_name] = false
+        else
+          @defaults[nice_name] = type unless type.is_a?(Symbol)
         end
-        
-        mem[name] = determine_option_type(type) || type
+        mem[name] = !type.nil? ? determine_option_type(type) : type
         mem
       end
 
@@ -146,13 +188,13 @@ module Boson
           opt_alias = h.key?("-"+opt_alias) ? "-"+opt_alias.capitalize : "-"+opt_alias
           h[opt_alias] ||= name unless @opt_types.key?(opt_alias)
         else
-          aliases.each { |e| h[e] = name unless @opt_types.key?(e) }
+          aliases.each {|e| h[e] = name if !@opt_types.key?(e) && e != false }
         end
         h
       }
     end
 
-    # Parses an array of arguments for defined options to return a hash. Once the parser
+    # Parses an array of arguments for defined options to return an IndifferentAccessHash. 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.
@@ -168,7 +210,7 @@ module Boson
       end
 
       while current_is_option?
-        case shift
+        case @original_current_option = shift
         when SHORT_SQ_RE
           unshift $1.split('').map { |f| "-#{f}" }
           next
@@ -178,12 +220,12 @@ module Boson
         when LONG_RE, SHORT_RE
           option = $1
         end
-        
+
         dashed_option = normalize_option(option)
         @current_option = undasherize(dashed_option)
         type = option_type(dashed_option)
         validate_option_value(type)
-        value = get_option_value(type, dashed_option)
+        value = create_option_value(type)
         # set on different line since current_option may change
         hash[@current_option.to_sym] = value
       end
@@ -194,24 +236,18 @@ module Boson
       hash
     end
 
-    # One-line option usage
+    # Helper method to generate usage. Takes a dashed option and a string value indicating
+    # an option value's format.
+    def default_usage(opt, val)
+      opt + "=" + (@defaults[undasherize(opt)] || val).to_s
+    end
+
+    # Generates one-line usage of all options.
     def formatted_usage
       return "" if @opt_types.empty?
       @opt_types.map do |opt, type|
-        case type
-        when :boolean
-          "[#{opt}]"
-        when :required
-          opt + "=" + opt.gsub(/\-/, "").upcase
-        else
-          sample = @defaults[undasherize(opt)]
-          sample ||= case type
-            when :string  then undasherize(opt).gsub(/\-/, "_").upcase
-            when :numeric then "N"
-            when :array   then "A,B,C"
-            end
-          "[" + opt + "=" + sample.to_s + "]"
-        end
+        val = respond_to?("usage_for_#{type}", true) ? send("usage_for_#{type}", opt) : "#{opt}=:#{type}"
+        "[" + val + "]"
       end.join(" ")
     end
 
@@ -221,51 +257,61 @@ module Boson
     def print_usage_table(render_options={})
       aliases = @opt_aliases.invert
       additional = [:desc, :values].select {|e| (@option_attributes || {}).values.any? {|f| f.key?(e) } }
+      additional_opts = {:desc=>[:desc], :values=>[:values, :keys]}
       opts = @opt_types.keys.sort.inject([]) {|t,e|
         h = {:name=>e, :aliases=>aliases[e], :type=>@opt_types[e]}
-        additional.each {|f| h[f] = (@option_attributes[undasherize(e)] || {})[f]  }
+        additional.each {|f|
+          h[f] = additional_opts[f].map {|g| (@option_attributes[undasherize(e)] || {})[g]}.flatten.compact
+        }
         t << h
       }
-      render_options = {:headers=>{:name=>"Option", :aliases=>"Alias", :desc=>'Description', :values=>'Values'},
+      render_options = {:headers=>{:name=>"Option", :aliases=>"Alias", :desc=>'Description', :values=>'Values/Keys', :type=>'Type'},
         :fields=>[:name, :aliases, :type] + additional, :description=>false, :filters=>{:values=>lambda {|e| (e || []).join(',')} }
       }.merge(render_options)
       View.render opts, render_options
     end
 
+    # Hash of option attributes for the currently parsed option. _Any_ hash keys
+    # passed to an option are available here. This means that an option type can have any
+    # user-defined attributes available during option parsing and object creation.
+    def current_attributes
+      @option_attributes && @option_attributes[@current_option] || {}
+    end
+
+    # Removes dashes from a dashed option i.e. '--date' -> 'date' and '-d' -> 'd'.
+    def undasherize(str)
+      str.sub(/^-{1,2}/, '')
+    end
+
+    # Adds dashes to an option name i.e. 'date' -> '--date' and 'd' -> '-d'.
+    def dasherize(str)
+      (str.length > 1 ? "--" : "-") + str
+    end
+
     private
     def determine_option_type(value)
+      return value if value.is_a?(Symbol)
       case value
-        when TrueClass, FalseClass then :boolean
-        when String                then :string
-        when Numeric               then :numeric
-        when Array                 then :array
-        else nil
+      when TrueClass, FalseClass   then :boolean
+      when Numeric                 then :numeric
+      else
+        Util.underscore(value.class.to_s).to_sym
       end
     end
 
-    def get_option_value(type, opt)
-      case type
-        when :required
-          shift
-        when :string
-          value = shift
-          if (values = @option_attributes[@current_option][:values].sort_by {|e| e.to_s} rescue nil)
-            (val = auto_alias_value(values, value)) && value = val
-          end
-          value
-        when :boolean
-          (!@opt_types.key?(opt) && @current_option =~ /^no-(\w+)$/) ? (@current_option.replace($1) && false) : true
-        when :numeric
-          peek.index('.') ? shift.to_f : shift.to_i
-        when :array
-          splitter = (@option_attributes[@current_option][:split] rescue nil) || ','
-          array = shift.split(splitter)
-          if values = @option_attributes[@current_option][:values].sort_by {|e| e.to_s } rescue nil
-            array.each_with_index {|e,i|
-              (value = auto_alias_value(values, e)) && array[i] = value
-            }
-          end
-          array
+    def value_shift
+      return shift if !current_attributes.key?(:bool_default)
+      return shift if @original_current_option =~ EQ_RE
+      current_attributes[:bool_default]
+    end
+
+    def create_option_value(type)
+      if current_attributes.key?(:bool_default) && (@original_current_option !~ EQ_RE) &&
+        !(bool_default = current_attributes[:bool_default]).is_a?(String)
+          bool_default
+      else
+        respond_to?("create_#{type}", true) ? send("create_#{type}", type != :boolean ? value_shift : nil) :
+          raise(Error, "Option '#{@current_option}' is invalid option type #{type.inspect}.")
       end
     end
 
@@ -275,18 +321,11 @@ module Boson
     end
 
     def validate_option_value(type)
+      return if current_attributes.key?(:bool_default)
       if type != :boolean && peek.nil?
         raise Error, "no value provided for option '#{@current_option}'"
       end
-
-      case type
-      when :required, :string
-        raise Error, "cannot pass '#{peek}' as an argument to option '#{@current_option}'" if valid?(peek)
-      when :numeric
-        unless peek =~ NUMERIC and $& == peek
-          raise Error, "expected numeric value for option '#{@current_option}'; got #{peek.inspect}"
-        end
-      end
+      send("validate_#{type}", peek) if respond_to?("validate_#{type}", true)
     end
 
     def delete_invalid_opts
@@ -299,14 +338,6 @@ module Boson
       end
     end
 
-    def undasherize(str)
-      str.sub(/^-{1,2}/, '')
-    end
-    
-    def dasherize(str)
-      (str.length > 1 ? "--" : "-") + str
-    end
-    
     def peek
       @args.first
     end
@@ -325,7 +356,8 @@ module Boson
     
     def valid?(arg)
       if arg.to_s =~ /^--no-(\w+)$/
-        @opt_types.key?(arg) or (@opt_types["--#{$1}"] == :boolean)
+        @opt_types.key?(arg) or (@opt_types["--#{$1}"] == :boolean) or
+          (@opt_types[original_no_opt($1)] == :boolean)
       else
         @opt_types.key?(arg) or @opt_aliases.key?(arg)
       end
@@ -346,16 +378,21 @@ module Boson
     
     def option_type(opt)
       if opt =~ /^--no-(\w+)$/
-        @opt_types[opt] || @opt_types["--#{$1}"]
+        @opt_types[opt] || @opt_types["--#{$1}"] || @opt_types[original_no_opt($1)]
       else
         @opt_types[opt]
       end
     end
-    
+
+    def original_no_opt(opt)
+      @opt_aliases[dasherize(opt)]
+    end
+
     def check_required!(hash)
       for name, type in @opt_types
-        if type == :required and !hash[undasherize(name)]
-          raise Error, "no value provided for required option '#{undasherize(name)}'"
+        @current_option = undasherize(name)
+        if current_attributes[:required] && !hash.key?(@current_option.to_sym)
+          raise Error, "no value provided for required option '#{@current_option}'"
         end
       end
     end