acclaim 0.5.0 → 0.5.1

data/acclaim.version

@@ -1 +1 @@
-0.5.0
+0.5.1

data/lib/acclaim/command.rb

@@ -1,13 +1,6 @@
 %w(
 
 acclaim/command/dsl
-acclaim/command/parser
-acclaim/option
-acclaim/option/parser
-acclaim/option/parser/regexp
-
-ribbon
-ribbon/core_extensions/object
 
 ).each { |file| require file }
 

data/lib/acclaim/command/dsl.rb

@@ -1,4 +1,15 @@
-require 'acclaim/command/dsl/root'
+%w(
+
+acclaim/command/dsl/root
+acclaim/command/parser
+acclaim/option
+acclaim/option/parser
+acclaim/option/parser/regexp
+
+ribbon
+ribbon/core_extensions/object
+
+).each { |file| require file }
 
 module Acclaim
   class Command
@@ -29,14 +40,14 @@ module Acclaim
 
       # Commands which may be given to this command.
       #
-      # @return [Array] this command's subcommands
+      # @return [Array<Acclaim::Command::DSL>] this command's subcommands
       def subcommands
         @subcommands ||= []
       end
 
       # The options this command can take.
       #
-      # @return [Array] the options this command takes
+      # @return [Array<Acclaim::Option>] the options this command takes
       def options
         @options ||= []
       end
@@ -54,8 +65,8 @@ module Acclaim
       #
       # @yieldparam [Ribbon] options a Ribbon instance which associates options
       #   with their corresponding values
-      # @yieldparam [Array] arguments the arguments that remained in the command
-      #   line
+      # @yieldparam [Array<String>] arguments the arguments that remained in the
+      #   command line
       # @return [Proc, nil] the given block
       def action(&block)
         @action = block if block.respond_to? :call
@@ -64,74 +75,106 @@ module Acclaim
 
       alias when_called action
 
-      # Parses the argument array using this command's set of options.
+      # Parses the given arguments using this command's set of options.
+      #
+      # @param [Array<String>] arguments the argument array
+      # @return [Ribbon::Wrapper] ribbon containing the values
       def parse_options_in!(arguments)
         Option::Parser.new(arguments, options).parse!
       end
 
-      # Looks for this command's subcommands in the argument array.
+      # Searches the given arguments for one of this command's subcommands.
+      #
+      # @param [Array<String>] arguments the argument array
+      # @return [Acclaim::Command::DSL, nil] a subcommand of this command or nil
+      #   if there was no match
       def parse_subcommands_in!(arguments)
         Command::Parser.new(arguments, subcommands).parse!
       end
 
-      # Invokes this command with a fresh set of option values.
+      # Invokes this command with the given arguments. Outputs
+      # {Option::Parser::Error parser error} messages to the standard error
+      # stream.
+      #
+      # @param [Array<String>] arguments the argument array
+      # @see #invoke
       def run(*arguments)
         invoke arguments
       rescue Option::Parser::Error => error
         $stderr.puts error.message
       end
 
-      # Parses the argument array. The argument array will be searched for
-      # subcommands; if one is found, it will be invoked, if not, this command
-      # will be executed. A subcommand may be anywhere in the array as long as
-      # it is before an argument separator, which is tipically a double dash
-      # (<tt>--</tt>) and may be omitted.
+      # Searches the given arguments for subcommands and {#invoke invokes} it.
+      # If none were found, {#execute executes} this command instead.
       #
-      # All argument separators will be deleted from the argument array before a
-      # command is executed.
-      def invoke(arguments = [], options = [])
-        options = options + self.options
+      # The arguments will be parsed using all options from {#command_ancestors
+      # this command and its parents}.
+      #
+      # @note Argument separators will be deleted prior to command execution.
+      #
+      # @param [Array<String>] arguments the argument array
+      def invoke(arguments = [])
         subcommand = parse_subcommands_in! arguments
         if subcommand.nil?
-          parsed_options = Option::Parser.new(arguments, options).parse!
+          all_options = command_ancestors.collect(&:options).flatten
+          parsed_options = Option::Parser.new(arguments, all_options).parse!
           delete_argument_separators_in! arguments
           execute parsed_options, arguments
         else
-          subcommand.invoke arguments, options
+          subcommand.invoke arguments
         end
       end
 
-      # Calls this command's action block with the given option values and
-      # arguments.
-      def execute(options, arguments)
-        @action.call options, arguments if @action.respond_to? :call
+      # Calls this command's {#action action block} with the given option values
+      # and arguments.
+      #
+      # @param [Ribbon::Wrapper] options ribbon containing options and values
+      # @param [Array<String>] arguments additional arguments to the program
+      def execute(options, arguments = [])
+        action.instance_eval do
+          call options, arguments if respond_to? :call
+        end
       end
 
       alias call execute
 
-      # True if this is a top-level command.
-      def root?
-        superclass == Acclaim::Command
-      end
-
       # Returns all command ancestors of this command.
+      #
+      # @return [Array<Acclaim::Command::DSL] this command's parent commands
       def command_ancestors
         ancestors - Acclaim::Command.ancestors
       end
 
       # Returns the root of the command hierarchy.
+      #
+      # @return [Acclaim::Command::DSL] the top-level command
       def root
         command_ancestors.last
       end
 
+      # Whether this is a top-level command.
+      #
+      # @return [true, false] whether this command is at the root of the
+      #   hierarchy
+      def root?
+        self == root
+      end
+
       # Returns the sequence of commands from #root that leads to this command.
+      #
+      # @return [Array<Acclaim::Command::DSL>] the path to this command
       def command_path
         command_ancestors.reverse
       end
 
-      # Computes the full command line of this command, which takes parent
-      # commands into account.
+      # Computes the full command line of this command, taking parent commands
+      # into account.
+      #
+      # @param [Hash, Ribbon, Ribbon::Wrapper] options method options
+      # @option options [true, false] :include_root (false) whether to include
+      #   the {#root root} command in the full command line
       #
+      # @example
       #   class Command < Acclaim::Command
       #     class Do < Command
       #       class Something < Do
@@ -140,12 +183,12 @@ module Acclaim
       #   end
       #
       #   Command::Do::Something.full_line
-      #    => "do something"
+      #   # => "do something"
       #
       #   Command::Do::Something.full_line include_root: true
-      #    => "command do something"
-      def full_line(*arguments)
-        options = arguments.extract_ribbon!
+      #   # => "command do something"
+      def full_line(options = {})
+        options = Ribbon.wrap options
         command_path.tap do |path|
           path.shift unless options.include_root?
         end.map(&:line).join ' '

data/lib/acclaim/option/arity.rb

@@ -5,6 +5,9 @@ module Acclaim
 
     # Represents the the number of arguments an option can take, both mandatory
     # and optional.
+    #
+    # @author Matheus Afonso Martins Moreira
+    # @since 0.0.2
     class Arity
 
       # The minimum number of arguments.
@@ -13,58 +16,78 @@ module Acclaim
       # The number of optional arguments.
       attr_accessor :optional
 
-      # Same as +minimum+.
       alias required minimum
 
-      # Initializes this arity with a number of required parameters and a number
-      # of optional parameters. If the latter is less than zero, then it means
-      # the option may take infinite parameters, as long as it takes at least
-      # +minimum+ parameters.
+      # Initializes an arity with the given number of required and optional
+      # parameters. If the latter is less than zero, then it means the option
+      # may take infinite parameters, as long as it takes the minimum number of
+      # parameters.
+      #
+      # @param [Integer] minimum the number of mandatory parameters
+      # @param [Integer] optional the number of optional parameters
       def initialize(minimum = 0, optional = 0)
         @minimum, @optional = minimum, optional
       end
 
-      # Returns +true+ if the option takes +n+ and only +n+ parameters.
+      # Whether the option takes +n+ and only +n+ parameters.
+      #
+      # @param [Integer] n the number of parameters
+      # @return [true, false] whether the option takes only +n+ parameters
       def only?(n)
         optional.zero? and minimum == n
       end
 
-      # Returns +true+ if the option takes no parameters.
-      def none?
+      # Whether the option takes no parameters.
+      #
+      # @return [true, false] whether the option takes zero parameters
+      # @since 0.5.1
+      def zero?
         only? 0
       end
 
-      # Returns +true+ if the option can take an infinite number of arguments.
+      alias none? zero?
+
+      # Whether the option can take an unlimited number of arguments.
+      #
+      # @return [true, false] whether the option can take infinite parameters
       def unlimited?
         optional < 0
       end
 
-      # Returns +true+ if the option must take a finite number of arguments.
+      # Whether the option must take a finite number of arguments.
+      #
+      # @return [true, false] whether the maximum number of arguments is limited
+      # @see #total
       def bound?
         not unlimited?
       end
 
-      # Returns the total number of parameters that the option may take, which
-      # is the number of mandatory parameters plus the number of optional
-      # parameters. Returns +nil+ if the option may take an infinite number of
-      # parameters.
+      # The total number of parameters that the option may take, or +nil+ if the
+      # option can take an infinite number of arguments.
+      #
+      # @return [Integer, nil] the total number of parameters or nil if infinite
       def total
-        bound? ? minimum + optional : nil
+        if bound? then minimum + optional else nil end
       end
 
-      # Converts this arity to an array in the form of
-      # <tt>[ required, optional ]</tt>.
+      # Converts this arity to an array in the form of:
+      #
+      #   [ required, optional ]
+      #
+      # @return [Array<Integer>] number of required and optional parameters in
+      #   order
       def to_a
         [ minimum, optional ]
       end
 
-      # Same as +to_a+.
       alias to_ary   to_a
-
-      # Same as +to_a+.
       alias to_array to_a
 
-      # Equivalent to <tt>to_a.hash</tt>.
+      # Equivalent to:
+      #
+      #   to_a.hash
+      #
+      # @return [Integer] hash value for this arity
       def hash
         to_a.hash
       end
@@ -78,12 +101,16 @@ module Acclaim
         to_a == arity.to_a
       end
 
-      # Same as <tt>==</tt>
-      alias eql? ==
-
-      # Same as <tt>==</tt>
       alias ===  ==
 
+      # Same as {#== ==} but does not compare directly with arrays.
+      #
+      # @param [Arity] arity the arity to compare this instance to
+      # @return [true, false] whether this instance is equal to the given arity
+      def eql?(arity)
+        minimum == arity.minimum and optional == arity.optional
+      end
+
       # Returns a string in the following format:
       #
       #   minimum +optional

data/lib/acclaim/option/type.rb

@@ -2,6 +2,9 @@ module Acclaim
   class Option
 
     # Associates a class with a handler block.
+    #
+    # @author Matheus Afonso Martins Moreira
+    # @since 0.0.4
     module Type
     end
 
@@ -10,6 +13,9 @@ module Acclaim
 
       # Yields class, proc pairs if a block was given. Returns an enumerator
       # otherwise.
+      #
+      # @yieldparam [Class, Module] type the class or module
+      # @yieldparam [Proc] handler the type handler
       def each(&block)
         table.each &block
       end
@@ -18,37 +24,43 @@ module Acclaim
       include Enumerable
 
       # Returns all registered classes.
+      #
+      # @return [Array<Class, Module>] registered types
       def all
         table.keys
       end
 
+      alias registered all
+
       # Registers a handler for a class.
-      def register(*klasses, &block)
-        klasses.each { |klass| table[klass] = block }
+      #
+      # @param [Class, Module] types the types to associate with the handler
+      # @param [Proc] block the type handler
+      # @yieldparam [String] string the command line argument
+      # @yieldreturn [Class, Module] new object of the handled type
+      def register(*types, &block)
+        types.each { |type| table[type] = block }
       end
 
+      alias add_handler_for register
+      alias accept register
+
       # Returns the handler for the given class.
-      def handler_for(klass)
-        table.fetch klass do
-          raise "#{klass} does not have an associated handler"
+      #
+      # @param [Class, Module] type the handler associated with the given type
+      def handler_for(type)
+        table.fetch type do
+          raise "#{type} does not have an associated handler"
         end
       end
 
-      # Same as <tt>all</tt>.
-      alias registered all
-
-      # Same as <tt>register</tt>.
-      alias add_handler_for register
-
-      # Same as <tt>register</tt>.
-      alias accept register
-
-      # Same as <tt>handler_for</tt>.
       alias [] handler_for
 
       private
 
       # The hash used to associate classes with their handlers.
+      #
+      # @return [Hash] the type handler table
       def table
         @table ||= {}
       end

data/lib/acclaim/option/type/big_decimal.rb

@@ -6,6 +6,9 @@ module Acclaim
     module Type
 
       # Handles big decimals given as arguments in the command line.
+      #
+      # @author Matheus Afonso Martins Moreira
+      # @since 0.3.0
       module BigDecimal
 
         # Returns +BigDecimal.new(str)+.

data/lib/acclaim/option/type/complex.rb

@@ -5,6 +5,9 @@ module Acclaim
     module Type
 
       # Handles complex numbers given as arguments in the command line.
+      #
+      # @author Matheus Afonso Martins Moreira
+      # @since 0.3.0
       module Complex
 
         # Simply returns +str.to_c+.

data/lib/acclaim/option/type/date.rb

@@ -6,6 +6,8 @@ module Acclaim
     module Type
 
       # Handles dates given as arguments in the command line.
+      #
+      # @author Matheus Afonso Martins Moreira
       module Date
 
         # Parses a +Date+ from the string.

data/lib/acclaim/option/type/date_time.rb

@@ -6,6 +6,8 @@ module Acclaim
     module Type
 
       # Handles dates and times given as arguments in the command line.
+      #
+      # @author Matheus Afonso Martins Moreira
       module DateTime
 
         # Parses a +DateTime+ from the string.

data/lib/acclaim/option/type/float.rb

@@ -5,6 +5,9 @@ module Acclaim
     module Type
 
       # Handles floating point numbers given as arguments in the command line.
+      #
+      # @author Matheus Afonso Martins Moreira
+      # @since 0.3.0
       module Float
 
         # Simply returns +str.to_f+.

data/lib/acclaim/option/type/integer.rb

@@ -5,6 +5,9 @@ module Acclaim
     module Type
 
       # Handles integers given as arguments in the command line.
+      #
+      # @author Matheus Afonso Martins Moreira
+      # @since 0.3.0
       module Integer
 
         # Simply returns +str.to_i+.

data/lib/acclaim/option/type/pathname.rb

@@ -6,6 +6,9 @@ module Acclaim
     module Type
 
       # Handles URIs given as arguments in the command line.
+      #
+      # @author Matheus Afonso Martins Moreira
+      # @since 0.3.1
       module Pathname
 
         # Parses an +URI+ from the string.

data/lib/acclaim/option/type/rational.rb

@@ -5,6 +5,9 @@ module Acclaim
     module Type
 
       # Handles rational numbers given as arguments in the command line.
+      #
+      # @author Matheus Afonso Martins Moreira
+      # @since 0.3.0
       module Rational
 
         # Simply returns +str.to_r+.

data/lib/acclaim/option/type/string.rb

@@ -5,6 +5,8 @@ module Acclaim
     module Type
 
       # Handles strings given as arguments in the command line.
+      #
+      # @author Matheus Afonso Martins Moreira
       module String
 
         # Simply returns +str.to_s+.

data/lib/acclaim/option/type/symbol.rb

@@ -5,6 +5,9 @@ module Acclaim
     module Type
 
       # Handles symbols given as arguments in the command line.
+      #
+      # @author Matheus Afonso Martins Moreira
+      # @since 0.0.6
       module Symbol
 
         # Simply returns +str.to_sym+.

data/lib/acclaim/option/type/time.rb

@@ -6,6 +6,8 @@ module Acclaim
     module Type
 
       # Handles times given as arguments in the command line.
+      #
+      # @author Matheus Afonso Martins Moreira
       module Time
 
         # Parses a +Time+ from the string.

data/lib/acclaim/option/type/uri.rb

@@ -6,6 +6,8 @@ module Acclaim
     module Type
 
       # Handles URIs given as arguments in the command line.
+      #
+      # @author Matheus Afonso Martins Moreira
       module URI
 
         # Parses an +URI+ from the string.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acclaim
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-25 00:00:00.000000000 Z
+date: 2012-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jewel
@@ -172,7 +172,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1568560335460056762
+      hash: 4151957857271700799
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -181,7 +181,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1568560335460056762
+      hash: 4151957857271700799
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24