acclaim 0.3.2 → 0.4.0

data/.gitignore

@@ -1,2 +1,3 @@
 *.lock
 doc/
+.yardoc/

data/acclaim.gemspec

@@ -1,24 +1,27 @@
 #!/usr/bin/env gem build
 # encoding: utf-8
-$:.unshift File.expand_path('../lib', __FILE__)
 
-require 'acclaim/version'
+Gem::Specification.new 'acclaim' do |gem|
 
-Gem::Specification.new('acclaim') do |gem|
+  current_directory = File.dirname __FILE__
+  version_file = File.expand_path "#{gem.name}.version", current_directory
 
-  gem.version     = Acclaim::Version::STRING
-  gem.summary     = 'Command-line option parser and command interface.'
-  gem.description = gem.summary
-  gem.homepage    = 'https://github.com/matheusmoreira/acclaim'
+  gem.version = File.read(version_file).chomp
+
+  gem.summary = 'Command-line option parser and command interface.'
+  gem.homepage = 'https://github.com/matheusmoreira/acclaim'
 
   gem.author = 'Matheus Afonso Martins Moreira'
-  gem.email  = 'matheus.a.m.moreira@gmail.com'
+  gem.email = 'matheus.a.m.moreira@gmail.com'
 
   gem.files = `git ls-files`.split "\n"
 
+  gem.add_runtime_dependency 'jewel'
   gem.add_runtime_dependency 'ribbon'
 
-  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'redcarpet'
   gem.add_development_dependency 'rookie'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'yard'
 
 end

data/acclaim.version

@@ -0,0 +1 @@
+0.4.0

data/lib/acclaim.rb

@@ -1,7 +1,14 @@
-# Acclaim is a command line option parsing and command interface for Ruby.
+# Command line option parsing and command interface for Ruby.
+#
+# @author Matheus Afonso Martins Moreira
+# @since 0.0.1
 module Acclaim
 end
 
-%w(command option version).each do |file|
-  require file.prepend 'acclaim/'
-end
+%w(
+
+acclaim/command
+acclaim/gem
+acclaim/option
+
+).each { |file| require file }

data/lib/acclaim/command.rb

@@ -1,8 +1,15 @@
-%w(option option/parser option/parser/regexp).each do |file|
-  require file.prepend 'acclaim/'
-end
+%w(
+
+acclaim/command/dsl
+acclaim/command/parser
+acclaim/option
+acclaim/option/parser
+acclaim/option/parser/regexp
 
-%w(ribbon ribbon/core_extensions/object).each { |file| require file }
+ribbon
+ribbon/core_extensions/object
+
+).each { |file| require file }
 
 module Acclaim
 
@@ -42,177 +49,19 @@ module Acclaim
   #   Verbose? yes
   #   Doing testing with acclaim and safeguard!
   class Command
+  end
 
-    # Module containing the class methods every command class should inherit.
-    module ClassMethods
-
-      # String which calls this command.
-      def line(*args)
-        @line = args.first unless args.empty?
-        @line ||= (name.gsub(/^.*::/, '').downcase rescue nil)
-      end
-
-      # Commands which may be given to this command.
-      def subcommands
-        @subcommands ||= []
-      end
-
-      # The options this command can take.
-      def options
-        @options ||= []
-      end
-
-      # Adds an option to this command.
-      def option(*args, &block)
-        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
-      # parameters; the first is an Ribbon instance which can be queried for
-      # settings information; the second is the remaining command line.
-      def action(&block)
-        @action = block
-      end
-
-      # Same as #action.
-      alias when_called action
-
-      # Adds help subcommand and options to this command.
-      def help(*args)
-        Help.create(self, *args)
-      end
-
-      # Adds help subcommand and options to this command.
-      def version(*args)
-        Version.create(self, *args)
-      end
-
-      # Parses the argument array using this command's set of options.
-      def parse_options!(args)
-        Option::Parser.new(args, options).parse!
-      end
-
-      # Looks for this command's subcommands in the argument array.
-      def parse_subcommands!(args)
-        Command::Parser.new(args, subcommands).parse!
-      end
-
-      # Invokes this command with a fresh set of option values.
-      def run(*args)
-        invoke args
-      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.
-      #
-      # All argument separators will be deleted from the argument array before a
-      # command is executed.
-      def invoke(args = [], opts = {})
-        opts = Ribbon.wrap opts
-        opts.merge! parse_options!(args)
-        handle_special_options! opts, args
-        if subcommand = parse_subcommands!(args)
-          subcommand.invoke args, opts
-        else
-          delete_argument_separators_in! args
-          execute opts, args
-        end
-      end
-
-      # Calls this command's action block with the given option values and
-      # arguments.
-      def execute(opts, args)
-        @action.call opts, args if @action
-      end
-
-      # Same as #execute.
-      alias call execute
-
-      # True if this is a top-level command.
-      def root?
-        superclass == Acclaim::Command
-      end
-
-      # Returns all command ancestors of this command.
-      def command_ancestors
-        ancestors - Acclaim::Command.ancestors
-      end
-
-      # Returns the root of the command hierarchy.
-      def root
-        command_ancestors.last
-      end
-
-      # Returns the sequence of commands from #root that leads to this command.
-      def command_path
-        command_ancestors.reverse
-      end
-
-      # Computes the full command line of this command, which takes parent
-      # commands into account.
-      #
-      #   class Command < Acclaim::Command
-      #     class Do < Command
-      #       class Something < Do
-      #       end
-      #     end
-      #   end
-      #
-      #   Command::Do::Something.full_line
-      #    => "do something"
-      #
-      #   Command::Do::Something.full_line include_root: true
-      #    => "command do something"
-      def full_line(*args)
-        options = args.extract_ribbon!
-        command_path.tap do |path|
-          path.shift unless options.include_root?
-        end.map(&:line).join ' '
-      end
-
-      private
-
-      # Handles special options such as <tt>--help</tt> or <tt>--version</tt>.
-      def handle_special_options!(opts, args)
-        const_get(:Help).execute opts, args if opts.acclaim_help?
-        const_get(:Version).execute opts, args if opts.acclaim_version?
-      # TODO:
-      #   possibly rescue a NameError and warn user
-      #   fix bug:
-      #     calling this method causes a subcommand to be executed even if it
-      #     wasn't given on the command line. This may result up to **three**
-      #     commands (help, version and the actual command) running in one
-      #     invocation.
-      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
-        end
-      end
-
-    end
+  class << Command
 
     # Add the class methods to the subclass and add it to this command's list of
     # subcommands.
-    def self.inherited(sub)
-      sub.extend ClassMethods
-      subcommands << sub if respond_to? :subcommands
+    #
+    # @param [Class] command the class that inherited from this command
+    def inherited(command)
+      command.extend Command::DSL
+      subcommands << command if respond_to? :subcommands
     end
 
   end
 
 end
-
-%w(help parser version).each do |command|
-  require command.prepend 'acclaim/command/'
-end

data/lib/acclaim/command/dsl.rb

@@ -0,0 +1,181 @@
+require 'acclaim/command/dsl/root'
+
+module Acclaim
+  class Command
+
+    # Module containing the methods that make up the domain-specific language
+    # used to create commands.
+    #
+    # @author Matheus Afonso Martins Moreira
+    # @since 0.4.0
+    module DSL
+
+      # The string used to invoke this command from the command line.
+      #
+      # @overload line
+      #   If not set, will try to figure out the name from the command's class.
+      #
+      #   @return [String] the name used to invoke this command
+      #
+      # @overload line(string)
+      #   Uses the given string to invoke this command.
+      #
+      #   @param [String, nil] string the new command name
+      #   @return [String] the name used to invoke this command
+      def line(*arguments)
+        @line = arguments.first unless arguments.empty?
+        @line ||= (name.gsub(/^.*::/, '').downcase if respond_to? :name)
+      end
+
+      # Commands which may be given to this command.
+      #
+      # @return [Array] this command's subcommands
+      def subcommands
+        @subcommands ||= []
+      end
+
+      # The options this command can take.
+      #
+      # @return [Array] the options this command takes
+      def options
+        @options ||= []
+      end
+
+      # Adds an option to this command.
+      #
+      # @see Acclaim::Option#initialize
+      def option(*arguments, &block)
+        options << Option.new(*arguments, &block)
+      end
+
+      alias opt option
+
+      # The block which is executed when this command is called.
+      #
+      # @yieldparam [Ribbon] options a Ribbon instance which associates options
+      #   with their corresponding values
+      # @yieldparam [Array] 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
+        @action
+      end
+
+      alias when_called action
+
+      # Parses the argument array using this command's set of options.
+      def parse_options_in!(arguments)
+        Option::Parser.new(arguments, options).parse!
+      end
+
+      # Looks for this command's subcommands in the argument array.
+      def parse_subcommands_in!(arguments)
+        Command::Parser.new(arguments, subcommands).parse!
+      end
+
+      # Invokes this command with a fresh set of option values.
+      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.
+      #
+      # All argument separators will be deleted from the argument array before a
+      # command is executed.
+      def invoke(arguments = [], options = [])
+        options = options + self.options
+        subcommand = parse_subcommands_in! arguments
+        if subcommand.nil?
+          parsed_options = Option::Parser.new(arguments, options).parse!
+          delete_argument_separators_in! arguments
+          execute parsed_options, arguments
+        else
+          subcommand.invoke arguments, options
+        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
+      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.
+      def command_ancestors
+        ancestors - Acclaim::Command.ancestors
+      end
+
+      # Returns the root of the command hierarchy.
+      def root
+        command_ancestors.last
+      end
+
+      # Returns the sequence of commands from #root that leads to this command.
+      def command_path
+        command_ancestors.reverse
+      end
+
+      # Computes the full command line of this command, which takes parent
+      # commands into account.
+      #
+      #   class Command < Acclaim::Command
+      #     class Do < Command
+      #       class Something < Do
+      #       end
+      #     end
+      #   end
+      #
+      #   Command::Do::Something.full_line
+      #    => "do something"
+      #
+      #   Command::Do::Something.full_line include_root: true
+      #    => "command do something"
+      def full_line(*arguments)
+        options = arguments.extract_ribbon!
+        command_path.tap do |path|
+          path.shift unless options.include_root?
+        end.map(&:line).join ' '
+      end
+
+      private
+
+      # Handles special options such as <tt>--help</tt> or <tt>--version</tt>.
+      def handle_special_options!(options, arguments)
+        const_get(:Help).execute options, arguments if options.acclaim_help?
+        const_get(:Version).execute options, arguments if options.acclaim_version?
+      # TODO:
+      #   possibly rescue a NameError and warn user
+      #   fix bug:
+      #     calling this method causes a subcommand to be executed even if it
+      #     wasn't given on the command line. This may result up to **three**
+      #     commands (help, version and the actual command) running in one
+      #     invocation.
+      end
+
+      # Deletes all argument separators in the given argument array.
+      def delete_argument_separators_in!(arguments)
+        arguments.delete_if do |arg|
+          arg =~ Option::Parser::Regexp::ARGUMENT_SEPARATOR
+        end
+      end
+
+      include Root
+
+    end
+
+  end
+end

data/lib/acclaim/command/dsl/root.rb

@@ -0,0 +1,36 @@
+%w(
+
+acclaim/command/help
+acclaim/command/version
+
+).each { |file| require file }
+
+module Acclaim
+  class Command
+    module DSL
+
+      # Methods that only work with root commands.
+      #
+      # @author Matheus Afonso Martins Moreira
+      # @since 0.4.0
+      module Root
+
+        # Adds help subcommand and options to this command.
+        #
+        # @see Acclaim::Command::Help.create
+        def help(*arguments, &block)
+          Help.create root, *arguments, &block
+        end
+
+        # Adds version subcommand and options to this command.
+        #
+        # @see Acclaim::Command::Help.create
+        def version(*arguments, &block)
+          Version.create root, *arguments, &block
+        end
+
+      end
+
+    end
+  end
+end

data/lib/acclaim/gem.rb

@@ -0,0 +1,17 @@
+require 'jewel'
+
+module Acclaim
+
+  # Acclaim gem information and metadata.
+  #
+  # @author Matheus Afonso Martins Moreira
+  # @since 0.4.0
+  class Gem < Jewel::Gem
+
+    root '../..'
+
+    specification ::Gem::Specification.load root.join('acclaim.gemspec').to_s
+
+  end
+
+end

data/lib/acclaim/option.rb

@@ -139,7 +139,7 @@ module Acclaim
 
     # Returns +true+ if this option takes no arguments.
     def flag?
-      arity and arity.none?
+      arity.none?
     end
 
     # Same as <tt>flag?</tt>
@@ -151,6 +151,22 @@ module Acclaim
     # Same as <tt>flag?</tt>
     alias switch? flag?
 
+    # Generate human-readable string containing this option's data.
+    #
+    # @return [String] string describing this option
+    def inspect
+      '#<%s %s (%s) %s = %s %s %s %s>' % [
+        self.class.name,
+        key,
+        names.join('|'),
+        type.inspect,
+        default.inspect,
+        arity.inspect,
+        on_multiple,
+        if required? then :required else :optional end
+      ]
+    end
+
   end
 
   class << Option

data/lib/acclaim/option/parser.rb

@@ -1,11 +1,19 @@
-%w(error regexp).each { |file| require file.prepend 'acclaim/option/parser/' }
+%w(
 
-require 'ribbon'
+acclaim/option/parser/error
+acclaim/option/parser/regexp
+
+ribbon
+
+).each { |file| require file }
 
 module Acclaim
   class Option
 
     # Parses arrays of strings and returns an Options instance containing data.
+    #
+    # @author Matheus Afonso Martins Moreira
+    # @since 0.0.1
     class Parser
 
       include Parser::Regexp
@@ -24,11 +32,15 @@ module Acclaim
         self.options = options || []
       end
 
-      # Parses the meaning of the options given to this parser. If none were
-      # given, the argument array will be preprocessed only. Any parsed options
-      # and arguments will be removed from the argument array, so pass in a
-      # duplicate if you need the original.
+      # Parses the given argument array, looking for the given {Option options}
+      # and their arguments if any.
+      #
+      # If no options were given, the argument array will be preprocessed only.
+      #
+      # @note Parsed options and their parameters will be removed from the
+      #   argument array.
       #
+      # @example
       #   include Acclaim
       #
       #   args = %w(-F log.txt --verbose arg1 arg2)
@@ -37,22 +49,49 @@ module Acclaim
       #   options << Option.new(:verbose)
       #
       #   Option::Parser.new(args, options).parse!
-      #    => {file: "log.txt", verbose: true}
+      #   # => {file: "log.txt", verbose: true}
       #
       #   args
-      #    => ["arg1", "arg2"]
+      #   # => ["arg1", "arg2"]
       def parse!
         preprocess_argv!
-        parse_values!
+        parse_values!.tap do
+          delete_options_from_argv!
+        end
       end
 
       private
 
+      # List of arguments that are to be removed from argv, identified by their
+      # index.
+      #
+      # @return [Array] the indexes of options marked for deletion
+      # @see #delete_options_from_argv!
+      # @since 0.4.0
+      def deleted_options
+        @deleted_options ||= []
+      end
+
+      # Deletes all marked options from argv.
+      #
+      # @note The list of removed indexes will be discarded.
+      #
+      # @see #deleted_options
+      # @since 0.4.0
+      def delete_options_from_argv!
+        argv.delete_if.with_index do |argument, index|
+          deleted_options.include? index
+        end
+      ensure
+        deleted_options.clear
+      end
+
       # Preprocesses the argument array.
       def preprocess_argv!
         split_multiple_short_options!
         normalize_parameters!
         argv.compact!
+        check_for_errors!
       end
 
       # Splits multiple short options.
@@ -73,6 +112,8 @@ module Acclaim
       #   %w(--switch=PARAM1,PARAM2) => %w(--switch PARAM1 PARAM2)
       #   %w(--switch=PARAM1,)       => %w(--switch PARAM1)
       #   %w(--switch=,PARAM2)       =>   [ '--switch', '', 'PARAM2' ]
+      #
+      # @since 0.0.3
       def normalize_parameters!
         argv.find_all { |arg| arg =~ SWITCH_PARAM_EQUALS }.each do |switch|
           switch_index = argv.index switch
@@ -83,48 +124,79 @@ module Acclaim
         end
       end
 
+      # Checks to see if the arguments have any errors
+      #
+      # @since 0.4.0
+      def check_for_errors!
+        ensure_required_options_are_present!
+        raise_on_multiple_options!
+      end
+
+      # Ensures all options are present in the argument array; raises a parser
+      # error otherwise.
+      #
+      # @since 0.4.0
+      def ensure_required_options_are_present!
+        options.find_all(&:required?).each do |option|
+          Error.raise_missing_required option if argv.find_all do |argument|
+            option =~ argument
+          end.empty?
+        end
+      end
+
+      # Raises a parser error if multiple switches were found for an option that
+      # explicitly disallowed it.
+      #
+      # @since 0.4.0
+      def raise_on_multiple_options!
+        options.find_all do |option|
+          option.on_multiple == :raise
+        end.each do |option|
+          Error.raise_multiple option if argv.find_all do |argument|
+            option =~ argument
+          end.count > 1
+        end
+      end
+
       # Parses the options and their arguments, associating that information
       # with a Ribbon instance.
+      #
+      # @since 0.0.3
       def parse_values!
         values = Ribbon.wrap
-        options.each do |option|
-          key = option.key
-          values[key] = option.default unless values.has_key? key
-          switches = argv.find_all { |switch| option =~ switch }
-          Error.raise_missing_required option if option.required? and switches.empty?
-          Error.raise_multiple option if option.on_multiple == :raise and switches.count > 1
-          switches.each do |switch|
+        argv.each_with_index do |argument, index|
+          options.find_all do |option|
+            option =~ argument
+          end.each do |option|
+            key = option.key
+            values[key] = option.default unless values.has_key? key
             if option.flag?
               found_boolean option, values.ribbon
-              argv.delete_at argv.index(switch)
+              deleted_options << index
             else
-              params = extract_parameters_of! option, switch
-              found_params_for option, params, values.ribbon
+              parameters = extract_parameters_of! option, index
+              found_params_for option, parameters, values.ribbon
             end
           end
         end
         values
       end
 
-      # Finds the +switch+ in #argv and scans the next +option.arity.total+
-      # elements if +option.arity.bound?+ is +true+, or all parameters
-      # otherwise. In either case, the algorithm will stop if it finds +nil+,
-      # another switch or an argument separator among the parameters.
+      # Starting from the given index, extracts parameters from the following
+      # arguments. Stops if it finds nil, another switch, an argument separator,
+      # or if enough values have been found according to the option's arity.
+      #
+      # @note All arguments scanned, in addition to the option at the given
+      #   index, will be marked for deletion.
       #
-      # Deletes the switch and every value that was extracted from #argv. Raises
-      # an Error if the number of parameters found is less than
-      # +option.arity.required+.
-      def extract_parameters_of!(option, switch)
+      # @return [Array] the parameters for the given option found in argv
+      # @raise [Parser::Error] if not enough arguments are found
+      # @since 0.0.4
+      def extract_parameters_of!(option, index)
         arity = option.arity
-        switch_index = argv.index switch
-        len = if arity.bound?
-          switch_index + arity.total
-        else
-          argv.length - 1
-        end
-        params = argv[switch_index + 1, len]
+        length = if arity.bound? then index + arity.total else argv.length - 1 end
         values = []
-        params.each do |param|
+        argv[index + 1, length].each do |param|
           case param
             when nil, SWITCH, ARGUMENT_SEPARATOR then break
             else
@@ -134,7 +206,9 @@ module Acclaim
         end
         count = values.count
         Error.raise_wrong_arg_number count, *arity if count < arity.required
-        argv.slice! switch_index..(switch_index + count)
+        limit = index + count
+        range = index..limit
+        deleted_options.push *range
         values
       end
 
@@ -148,6 +222,8 @@ module Acclaim
       # so. In this case, the value of the option will always be an array.
       #
       # The parameters will be converted according to the option's type.
+      #
+      # @since 0.0.6
       def found_params_for(option, params = [], ribbon = Ribbon.new)
         params = option.convert_parameters *params
         if handler = option.handler then handler.call ribbon, params
@@ -162,6 +238,8 @@ module Acclaim
       # If the option has an custom handler associated, it will be called with
       # only the option values as the first argument. Otherwise, the value will
       # be set to <tt>true</tt>.
+      #
+      # @since 0.0.6
       def found_boolean(option, ribbon = Ribbon.new)
         if handler = option.handler then handler.call ribbon
         else ribbon[option.key] = true end

data/spec/acclaim/option/parser_spec.rb

@@ -201,6 +201,31 @@ describe Acclaim::Option::Parser do
         end
       end
 
+      context 'which contains one option with unbound aritiy and one boolean option' do
+        let(:options) { [ Acclaim::Option.new(:boolean), Acclaim::Option.new(:parameters, arity: [1, -1]) ] }
+
+        context 'and the arguments are such that the boolean option is between the parameters' do
+          let!(:args) { %w(--parameters a b c d --boolean e f g) }
+
+          it 'should parse from left to right, stopping at the boolean option' do
+            subject.parse!
+            args.should == %w(e f g)
+          end
+
+          context 'the parsed ribbon' do
+            let(:ribbon) { subject.parse! }
+
+            it 'should cointain the correct value for boolean' do
+              ribbon.parameters.should == %w(a b c d)
+            end
+
+            it 'should cointain the correct value for parameters' do
+              ribbon.boolean.should be_true
+            end
+          end
+        end
+      end
+
       context 'containing an option which' do
         let!(:options) { [ Acclaim::Option.new(:files, '-f', arity: [1,0], on_multiple: on_multiple, &block) ] }
         let!(:args) { %w(-f f1 -f f2 -f f3) }

data/spec/acclaim/option_spec.rb

@@ -15,17 +15,45 @@ describe Acclaim::Option do
       subject.key.should == key
     end
 
-    context 'when given multiple strings' do
+    context 'when given multiple switches' do
       let(:switches) { %w(-s --switch) }
+
+      context 'directly' do
+        let(:args) { [*switches] }
+
+        it 'should find the switches' do
+          subject.names.should == switches
+        end
+      end
+
+      context 'as an array' do
+        let(:args) { [switches] }
+
+        it 'should find the switches' do
+          subject.names.should == switches
+        end
+      end
+    end
+
+    context 'when given a description string' do
       let(:description) { 'Description' }
-      let(:args) { [*switches, description] }
 
-      it 'should find the switches' do
-        subject.names.should == switches
+      context 'by itself' do
+        let(:args) { [description] }
+
+        it 'should find the description' do
+          subject.description.should == description
+        end
       end
 
-      it 'should find the description' do
-        subject.description.should == description
+      context 'with another description specified in the options hash' do
+        let(:description_from_options_hash) { 'Description from options hash' }
+        let(:options_hash) { { description: description_from_options_hash } }
+        let(:args) { [description, options_hash] }
+
+        it 'should use the description from the options hash' do
+          subject.description.should == description_from_options_hash
+        end
       end
     end
 
@@ -114,6 +142,27 @@ describe Acclaim::Option do
           end
         end
       end
+
+      context 'that specifies a description' do
+        let(:hash) { { description: description } }
+
+        context 'as a regular string' do
+          let(:description) { 'Description' }
+
+          it 'should use the string as the description' do
+            subject.description.should == description
+          end
+        end
+
+        context 'as a block' do
+          let(:description) { -> { 'Description' } }
+
+          it 'should call the block and use return value as the description' do
+            value = description.call
+            subject.description.should == value
+          end
+        end
+      end
     end
 
     context 'when not given a block' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acclaim
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-10 00:00:00.000000000 Z
+date: 2012-06-22 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: jewel
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: ribbon
   requirement: !ruby/object:Gem::Requirement
@@ -28,7 +44,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: redcarpet
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -59,7 +75,39 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Command-line option parser and command interface.
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
 email: matheus.a.m.moreira@gmail.com
 executables: []
 extensions: []
@@ -72,13 +120,17 @@ files:
 - README.markdown
 - Rakefile
 - acclaim.gemspec
+- acclaim.version
 - lib/acclaim.rb
 - lib/acclaim/command.rb
+- lib/acclaim/command/dsl.rb
+- lib/acclaim/command/dsl/root.rb
 - lib/acclaim/command/help.rb
 - lib/acclaim/command/help/template.rb
 - lib/acclaim/command/help/template/command.erb
 - lib/acclaim/command/parser.rb
 - lib/acclaim/command/version.rb
+- lib/acclaim/gem.rb
 - lib/acclaim/option.rb
 - lib/acclaim/option/arity.rb
 - lib/acclaim/option/parser.rb
@@ -97,7 +149,6 @@ files:
 - lib/acclaim/option/type/symbol.rb
 - lib/acclaim/option/type/time.rb
 - lib/acclaim/option/type/uri.rb
-- lib/acclaim/version.rb
 - spec/acclaim/command_spec.rb
 - spec/acclaim/option/arity_spec.rb
 - spec/acclaim/option/parser/regexp_spec.rb
@@ -117,7 +168,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 4033184433190617249
+      hash: 3293933185562874440
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -126,7 +177,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 4033184433190617249
+      hash: 3293933185562874440
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24

data/lib/acclaim/version.rb

@@ -1,31 +0,0 @@
-module Acclaim
-
-  # Acclaim's version.
-  module Version
-
-    # Major version.
-    #
-    # Increments denote backward-incompatible changes and additions.
-    MAJOR = 0
-
-    # Minor version.
-    #
-    # Increments denote backward-compatible changes and additions.
-    MINOR = 3
-
-    # Patch version.
-    #
-    # Increments denote changes in implementation.
-    PATCH = 2
-
-    # Build version.
-    #
-    # Used for pre-release versions.
-    BUILD = nil
-
-    # Complete version string, which is every individual version number joined
-    # by a dot (<tt>'.'</tt>), in descending order of prescedence.
-    STRING = [ MAJOR, MINOR, PATCH, BUILD ].compact.join '.'
-
-  end
-end