acclaim 0.0.7 → 0.1.0

data/README.markdown

@@ -12,7 +12,7 @@ application in a structured manner. Commands are classes that inherit from
 
     module App
       class Command < Acclaim::Command
-        option :verbose, '-v', '--verbose'
+        option :verbose, '-V', '--verbose'
 
         when_called do |options, args|
           puts 'Hello World!'
@@ -21,17 +21,19 @@ application in a structured manner. Commands are classes that inherit from
       end
     end
 
+    App::Command.run *ARGV
+
     $ app --verbose a b c
     Hello World!
     a, b, c
 
-Every command has a set of options and block that is executed when it is called.
-The options are parsed into an object and passed to the command's block along
-with the remaining command line arguments. The first argument of the `option`
-method is the key used to store the value of the option, the other strings are
-either switches or a description:
+Every command has a set of options and block. When the application runs, the
+options are parsed into an object and passed to the command's block along with
+the remaining command line arguments. The first argument of the `option` method
+is the key used to store the value of the option, the other strings are either
+switches or a description:
 
-    option :verbose, '-v', '--verbose', '--run-verbosely', 'Run verbosely.'
+    option :verbose, '-V', '--verbose', '--run-verbosely', 'Run verbosely.'
 
 Acclaim provides especial `help` and `version` commands that may be added to
 your program. The help command will automatically generate and print a help page
@@ -56,10 +58,9 @@ version and exit. To use them:
     $ app version
     1.2.3
 
-Both methods can take a hash as the last parameter, which accepts the same
-configurations. If you don't want the options, or if you want to specify a
-different set of switches or a different description, you can write something
-like:
+Both methods can take a hash as the last parameter. If you don't want the
+options, or if you want to specify a different set of switches or a different
+description, you can write:
 
     help options: false
     version '1.2.3', switches: %w(--version),
@@ -82,21 +83,19 @@ from an existing command:
       end
     end
 
-    $ app do x y, z
-    Doing something with x y, z
+    $ app do x y z
+    Doing something with x, y, z
 
-    $ app do --what x y, z
+    $ app do --what x y z
     Doing x with y, z
 
-Options may also take an Hash as the last parameter. Among the things that can
+Options may also take an hash as the last parameter. Among the things that can
 be configured is the default value for the option and its arity. The default
 value is `nil` by default and is used if the option is not given. The arity of
 the option represents the minimum number of arguments it __must__ take and the
-number of optional arguments it __may__ take. It is specified as an array in the
-form `[minimum, optional]`. Options that take zero arguments, which is the
-default, are flags.
-
-So, options can take from zero to an unlimited number of arguments, right?
+number of optional arguments it __may__ take. It can be specified as an array in
+the form `[minimum, optional]`. Options that take zero arguments, which is the
+default, are called switches.
 
     class App::Command::Do < App::Command
 
@@ -107,6 +106,7 @@ So, options can take from zero to an unlimited number of arguments, right?
         what = (options.what.join ', ' rescue options.what)
         subjects = args.join ', '
         puts "Doing #{what} with #{subjects}"
+      end
     end
 
     $ app do --what x y z
@@ -132,9 +132,8 @@ will not work:
     $ app do --what w x --verbose y z
     Doing w, x, y, z with
 
-This happens because `--verbose` is an option of the main command. Since it will
-be parsed and deleted from the argument array, when `do` gets its turn it will
-be parsing the `%w(--what w x y z)` array.
+This happens because `--verbose` is an option of the main command. When `do`
+gets its turn it will be parsing the `%w(--what w x y z)` array.
 
 ### Option Type Handlers
 
@@ -142,8 +141,7 @@ Arguments given to options are by default strings. To make life easier, you may
 specify the type of the arguments by passing a class among the arguments:
 
     class App::Command::Do
-      opt :when, '--when', 'When to do it.', Date,
-                 default: Date.today, arity: [1,0]
+      opt :when, '--when', 'When to do it.', Date, default: Date.today, arity: [1,0]
 
       action do |options, args|
         what = (options.what.join ', ' rescue options.what)
@@ -159,23 +157,33 @@ specify the type of the arguments by passing a class among the arguments:
     Merry Christmas!
     Doing w, x with y, z on 12/25/2011
 
-There are type handlers included for `Date`s, `Time`s, `DateTime`s, `URI`s and
-`String`s, but if you need more you can always write your own:
+There are type handlers included for `Date`s, `Time`s, `DateTime`s, `URI`s,
+`Symbol`s and `String`s, but if you need more you can always write your own:
+
+    class Person
+      attr_accessor :first_name, :middle_names, :last_name
+
+      def initialize(first, *others)
+        @first_name, @last_name, @middle_names = first, others.pop, others
+      end
+    end
+
+    Acclaim::Option::Type.add_handler_for Person do |argument|
+      Person.new *argument.split
+    end
 
-    Acclaim::Option::Type.add_handler_for(Symbol) { |str| str.to_sym }
+    class App::Command::Show < App::Command
 
-    class App::Command::Handle < App::Command
-      opt :syms, '--symbol', '--symbols', Symbol, arity: [1,-1], required: true
+      # If no switches are specified, one will be derived from the key
+      opt :person, Person, arity: [1,0], required: true
 
       when_called do |options, args|
-        options.syms.each { |sym| puts "#{sym.class} => #{sym.inspect}" }
+        puts "#{options.person.last_name}, #{options.person.first_name}"
       end
     end
 
-    $ app handle --symbols a s d
-    Symbol => :a
-    Symbol => :s
-    Symbol => :d
+    $ app show --person 'Matheus Afonso Martins Moreira'
+    Moreira, Matheus
 
 `add_handler_for` takes a class and a block, which will be called for every
 argument of that class that must be parsed.

data/lib/acclaim/command.rb

@@ -69,6 +69,7 @@ module Acclaim
         options << Option.new(*args, &block)
       end
 
+      # Same as #option.
       alias :opt :option
 
       # The block which is executed when this command is called. It is given 2
@@ -78,6 +79,7 @@ module Acclaim
         @action = block
       end
 
+      # Same as #action.
       alias :when_called :action
 
       # Adds help subcommand and options to this command.
@@ -132,6 +134,7 @@ module Acclaim
         @action.call opts, args if @action
       end
 
+      # Same as #execute.
       alias :call :execute
 
       # True if this is a top-level command.
@@ -154,6 +157,7 @@ module Acclaim
         const_get(:Version).execute opts, args if opts.acclaim_version?
       end
 
+      # Deletes all argument separators in the given argument array.
       def delete_argument_separators_in!(args)
         args.delete_if do |arg|
           arg =~ Option::Parser::Regexp::ARGUMENT_SEPARATOR

data/lib/acclaim/command/parser.rb

@@ -7,7 +7,11 @@ module Acclaim
     # the elements of the array.
     class Parser
 
-      attr_accessor :argv, :commands
+      # The argument array to be searched.
+      attr_accessor :argv
+
+      # The commands to search for.
+      attr_accessor :commands
 
       # Initializes a new command parser, with the given argument array and set
       # of commands to search for.
@@ -36,7 +40,7 @@ module Acclaim
 
       # Searches for one of the given commands in the argument array, and
       # returns it. Removes the string that matched the command name from
-      # +argv+. Returns +nil if no command was found.
+      # +argv+. Returns +nil+ if no command was found.
       def find_command
         commands.find do |command|
           arguments_up_to_separator.include? command.line

data/lib/acclaim/option.rb

@@ -1,13 +1,36 @@
 require 'acclaim/option/arity'
 require 'acclaim/option/parser/regexp'
 require 'acclaim/option/type'
+require 'ribbon'
+require 'ribbon/core_ext/array'
 
 module Acclaim
 
   # Represents a command-line option.
   class Option
 
-    attr_accessor :key, :names, :description, :type, :default, :handler, :on_multiple
+    # The key used to store the value of the option.
+    attr_accessor :key
+
+    # The strings that refer to this option in the command line.
+    attr_accessor :names
+
+    # The description of this option.
+    attr_accessor :description
+
+    # The type the option's value will be converted to. See Option::Type.
+    attr_accessor :type
+
+    # The default value for the option. Default is +nil+.
+    attr_accessor :default
+
+    # This option's custom handler.
+    attr_accessor :handler
+
+    # How the parser should react when multiple instances of this option are
+    # found in the command line. It will, by default, replace the old value with
+    # the new one, but it can also collect all values or raise an error.
+    attr_accessor :on_multiple
 
     # Initializes a command line option. The +key+ is the object used to
     # associate this option with a value. The other arguments may be:
@@ -23,13 +46,20 @@ module Acclaim
     # [class]           The <tt>Class</tt> which will be used in parameter
     #                   conversion. The default is <tt>String</tt>.
     #
+    # If no switches were specified, the +key+ will be used to derive one. See
+    # Option::name_from for details.
+    #
     # The last argument can be a hash of options, which may specify:
     #
-    # [:arity]     The number of required and optional arguments. See Arity for
-    #              defails.
-    # [:default]   The default value for this option.
-    # [:required]  Whether or not the option must be present on the command
-    #              line.
+    # [:arity]        The number of required and optional arguments. See Arity
+    #                 for defails. Defaults to no arguments.
+    # [:default]      The default value for this option. Defaults to +nil+.
+    # [:required]     Whether or not the option must be present on the command
+    #                 line. Default is +false+.
+    # [:on_multiple]  What to do if the option is encountered multiple times.
+    #                 Supported modes are <tt>:replace</tt>, <tt>:append</tt>
+    #                 and <tt>:raise</tt>. New values will replace old ones by
+    #                 default.
     #
     # Additionally, if a block is given, it will be called when the option is
     # parsed with a ribbon instance and the parameters given to the option. The
@@ -37,18 +67,20 @@ module Acclaim
     # this is not desirable consider not specifying a class to the option or
     # registering a custom type handler.
     def initialize(key, *args, &block)
-      options = args.last.is_a?(Hash) ? args.pop : {}
-      matches = args.select { |arg| arg.is_a? String }.group_by do |arg|
+      options = args.extract_ribbon!
+      matches = args.select do |arg|
+        arg.is_a? String
+      end.group_by do |arg|
         arg =~ Parser::Regexp::SWITCH ? true : false
       end
       klass = args.find { |arg| arg.is_a? Module }
       self.key         = key
-      self.names       = matches.fetch true, []
+      self.names       = matches.fetch(true) { [ Option.name_from(key) ] }
       self.description = matches.fetch(false, []).first
-      self.on_multiple = options.fetch :on_multiple, :replace
-      self.arity       = options[:arity]
-      self.default     = options[:default]
-      self.required    = options[:required]
+      self.on_multiple = options.on_multiple? :replace
+      self.arity       = options.arity?
+      self.default     = options.default?
+      self.required    = options.required?
       self.type        = klass || String
       self.handler     = block
     end
@@ -94,14 +126,38 @@ module Acclaim
       self.required = true
     end
 
-    # Returns true if this option takes no arguments.
+    # Returns +true+ if this option takes no arguments.
     def flag?
       not arity or arity == [0, 0]
     end
 
-    alias :bool?    :flag?
+    # Same as <tt>flag?</tt>
+    alias :bool? :flag?
+
+    # Same as <tt>flag?</tt>
     alias :boolean? :flag?
-    alias :switch?  :flag?
+
+    # Same as <tt>flag?</tt>
+    alias :switch? :flag?
+
+    # The class methods.
+    class << self
+
+      # Derives a name from the given key's string representation. All
+      # underscores will be replaced with dashes.
+      #
+      # If the string is empty, an +ArgumentError+ will be raised. If the
+      # resulting name is not a valid switch, a +NameError+ will be raised.
+      def name_from(key)
+        name = key.to_s
+        raise ArgumentError, "Can't derive name from empty string representation." if name.empty?
+        name = (name.length == 1 ? '-' : '--') + name
+        name.gsub! '_', '-'
+        raise NameError, "Derived name is invalid: #{name}" unless name =~ Parser::Regexp::SWITCH
+        name
+      end
+
+    end
 
   end
 end

data/lib/acclaim/option/arity.rb

@@ -5,7 +5,13 @@ module Acclaim
     # and optional.
     class Arity
 
-      attr_accessor :minimum, :optional
+      # The minimum number of arguments.
+      attr_accessor :minimum
+
+      # 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
@@ -45,7 +51,10 @@ module Acclaim
         [ 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>.
@@ -62,7 +71,10 @@ module Acclaim
         to_a == arity.to_a
       end
 
+      # Same as <tt>==</tt>
       alias :eql? :==
+
+      # Same as <tt>==</tt>
       alias :===  :==
 
       # Returns a string in the following format:

data/lib/acclaim/option/parser.rb

@@ -37,7 +37,11 @@ module Acclaim
 
       end
 
-      attr_accessor :argv, :options
+      # The argument array to parse.
+      attr_accessor :argv
+
+      # The options to be parsed.
+      attr_accessor :options
 
       # Initializes a new parser, with the given argument array and set of
       # options. If no option array is given, the argument array will be

data/lib/acclaim/option/type.rb

@@ -4,40 +4,55 @@ module Acclaim
     # Associates a class with a handler block.
     module Type
 
-      # Yields class, proc pairs if a block was given. Returns an enumerator
-      # otherwise.
-      def self.each(&block)
-        table.each &block
-      end
+      # The class methods.
+      class << self
 
-      # Returns all registered classes.
-      def self.all
-        table.keys
-      end
+        # Yields class, proc pairs if a block was given. Returns an enumerator
+        # otherwise.
+        def each(&block)
+          table.each &block
+        end
 
-      # Registers a handler for a class.
-      def self.register(klass, &block)
-        table[klass] = block
-      end
+        # Take advantage of each method.
+        include Enumerable
 
-      # Returns the handler for the given class.
-      def self.handler_for(klass)
-        table[klass]
-      end
+        # Returns all registered classes.
+        def all
+          table.keys
+        end
 
-      class << self
+        # Registers a handler for a class.
+        def register(klass, &block)
+          table[klass] = block
+        end
+
+        # Returns the handler for the given class.
+        def handler_for(klass)
+          table.fetch klass do
+            raise "#{klass} 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
-      end
 
-      # The hash used to associate classes with their handlers.
-      def self.table
-        @table ||= {}
-      end
+        private
+
+        # The hash used to associate classes with their handlers.
+        def table
+          @table ||= {}
+        end
 
-      private_class_method :table
+      end
 
     end
 

data/lib/acclaim/version.rb

@@ -11,12 +11,12 @@ module Acclaim
     # Minor version.
     #
     # Increments denote backward-compatible changes and additions.
-    MINOR = 0
+    MINOR = 1
 
     # Patch version.
     #
     # Increments denote changes in implementation.
-    PATCH = 7
+    PATCH = 0
 
     # Build version.
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acclaim
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-12 00:00:00.000000000 Z
+date: 2012-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ribbon
-  requirement: &17514000 !ruby/object:Gem::Requirement
+  requirement: &22189080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *17514000
+  version_requirements: *22189080
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &17513440 !ruby/object:Gem::Requirement
+  requirement: &22188500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *17513440
+  version_requirements: *22188500
 - !ruby/object:Gem::Dependency
   name: rookie
-  requirement: &17513000 !ruby/object:Gem::Requirement
+  requirement: &22188080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *17513000
+  version_requirements: *22188080
 description: Command-line option parser and command interface.
 email: matheus.a.m.moreira@gmail.com
 executables: []
@@ -94,7 +94,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1879446143954765838
+      hash: -901301498998529047
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -103,7 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1879446143954765838
+      hash: -901301498998529047
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.10