cri 2.4.1 → 2.5.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NmEyNjRhYjcyOTg2MzdiNWM1MDA5OWJiYTM0ZWNiMGIzYWM1ZjAxNw==
+    YTY4ZDU4NjdmNGI4NDNhM2UxMTA1YTA1MDBjZmEzYWZiNDgwOTY0ZA==
   data.tar.gz: !binary |-
-    MGUyZjJjNjdkMGY2ZjAxYWZjYzdjMzgzMTAzOWZiMzgwZWYzYTkzOA==
+    MjkxMmY1ZDA1M2ExNDUxYmUxOTYyNjVjZTE3OWExM2Y1NmVhODg2Mg==
 SHA512:
   metadata.gz: !binary |-
-    MjhlMjE2ODU5OTNiODMxZTY4ZGFlMzA3YjM0OGY3MDRiYmI2MzUwMjNhMTY1
-    YmY2YTZkODk2NGEyNjYwMmZiOTM0ZjQ2ZDQ3YWE5NDIxMWNkZGZhY2UzNjVk
-    MmJmNDI0ZjYwMDQ5ODYyNzE4N2QwNjQ3NzVlMTJmZmZlZTFlODg=
+    MTNjMmU4ZTViYjg2YzFiYjI5MjZiZTcyNzViNGYyYTEzZjdiMzY5MTc4Mzlk
+    MWIwYWNlNzI4Njk3Y2JlYTFkNDI4NDkyNGQ0YmVhMWE5Mzk1YjFhM2VjZDBm
+    ZjMxZmYzMDVkMzM2MGQ1OTVhYmI4NDUxMTFiNWEyZDU5MGQ5ZWE=
   data.tar.gz: !binary |-
-    OGZjNzRmYzk5ZmYzMmVhZDlhOTcyM2IzOGY2OTZhOWQ5YmFmMzdjODZmYzk2
-    MjhmMDkzOTQ3Yjc2Mzc4MjExMTg4ZjU4ZTM5N2YzNTgwZWViMTgxZTdjZjJl
-    NTYxYWJjOGE5ZDM2MWY3NzQ2M2FjYWU0NjEyNGY3YmZmOGQ5MmI=
+    MmEwYjAzNDVhYzg0MWExM2MyODhmMzJlMDE1ZDkwY2U4Y2U2ZGFkNjYxZjk5
+    YjYxNGMxNTJlYjk5N2U0MDRkYzYyNDg3Mjc0NjlhODg5MDkyNGFmNWZlYTU2
+    YjRlY2EyNGU0NjlhYWM2NTMzZmE1MGU1MjRkMDRkNjZiODFiYjc=

data/Gemfile.lock

@@ -1,16 +1,16 @@
 PATH
   remote: .
   specs:
-    cri (2.4.1)
+    cri (2.5.0)
       colored (>= 1.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
     colored (1.2)
-    minitest (5.0.6)
-    rake (10.1.0)
-    yard (0.8.7)
+    minitest (5.3.0)
+    rake (10.1.1)
+    yard (0.8.7.3)
 
 PLATFORMS
   ruby

data/NEWS.md

@@ -1,6 +1,12 @@
 Cri News
 ========
 
+2.5.0
+-----
+
+* Made the default help command handle subcommands
+* Added `#raw` method to argument arrays, returning all arguments including `--`
+
 2.4.1
 -----
 

data/README.adoc

@@ -0,0 +1,158 @@
+= Cri =
+
+Cri is a library for building easy-to-use commandline tools with support for
+nested commands.
+
+== Usage ==
+
+The central concept in Cri is the _command_, which has option definitions as
+well as code for actually executing itself. In Cri, the commandline tool
+itself is a command as well.
+
+Here’s a sample command definition:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+command = Cri::Command.define do
+  name        'dostuff'
+  usage       'dostuff [options]'
+  aliases     :ds, :stuff
+  summary     'does stuff'
+  description 'This command does a lot of stuff. I really mean a lot.'
+
+  flag   :h,  :help,  'show help for this command' do |value, cmd|
+    puts cmd.help
+    exit 0
+  end
+  flag   nil, :more,  'do even more stuff'
+  option :s,  :stuff, 'specify stuff to do', :argument => :required
+
+  run do |opts, args, cmd|
+    stuff = opts.fetch(:stuff, 'generic stuff')
+    puts "Doing #{stuff}!"
+
+    if opts[:more]
+      puts 'Doing it even more!'
+    end
+  end
+end
+--------------------------------------------------------------------------------
+
+To run this command, invoke the `#run` method with the raw arguments. For
+example, for a root command (the commandline tool itself), the command could
+be called like this:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+command.run(ARGV)
+--------------------------------------------------------------------------------
+
+Each command has automatically generated help. This help can be printed using
+`Cri::Command#help`; something like this will be shown:
+
+--------------------------------------------------------------------------------
+usage: dostuff [options]
+
+does stuff
+
+    This command does a lot of stuff. I really mean a lot.
+
+options:
+
+    -h --help      show help for this command
+       --more      do even more stuff
+    -s --stuff     specify stuff to do
+--------------------------------------------------------------------------------
+
+Let’s disect the command definition and start with the first five lines:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+name        'dostuff'
+usage       'dostuff [options]'
+aliases     :ds, :stuff
+summary     'does stuff'
+description 'This command does a lot of stuff. I really mean a lot.'
+--------------------------------------------------------------------------------
+
+These lines of the command definition specify the name of the command (or the
+commandline tool, if the command is the root command), the usage, a list of
+aliases that can be used to call this command, a one-line summary and a (long)
+description. The usage should not include a “usage:” prefix nor the name of
+the supercommand, because the latter will be automatically prepended.
+
+Aliases don’t make sense for root commands, but for subcommands they do.
+
+The next few lines contain the command’s option definitions:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+flag   :h,  :help,  'show help for this command' do |value, cmd|
+  puts cmd.help
+  exit 0
+end
+flag   nil, :more,  'do even more stuff'
+option :s,  :stuff, 'specify stuff to do', :argument => :required
+--------------------------------------------------------------------------------
+
+Options can be defined using the following methods:
+
+* `Cri::CommandDSL#option` or `Cri::CommandDSL#opt`
+* `Cri::CommandDSL#flag` (implies no arguments passed to option)
+* `Cri::CommandDSL#required` (implies required argument)
+* `Cri::CommandDSL#optional` (implies optional argument)
+
+All these methods take the short option form as their first argument, and a
+long option form as their second argument. Either the short or the long form
+can be nil, but not both (because that would not make any sense). In the
+example above, the `--more` option has no short form.
+
+Each of the above methods also take a block, which will be executed when the
+option is found. The argument to the block are the option value (`true` in
+case the option does not have an argument) and the command.
+
+The last part of the command defines the execution itself:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+run do |opts, args, cmd|
+  stuff = opts.fetch(:stuff, 'generic stuff')
+  puts "Doing #{stuff}!"
+
+  if opts[:more]
+    puts 'Doing it even more!'
+  end
+end
+--------------------------------------------------------------------------------
+
+The +Cri::CommandDSL#run+ method takes a block with the actual code to
+execute. This block takes three arguments: the options, any arguments passed
+to the command, and the command itself.
+
+Instead of defining a run block, it is possible to declare a class, the
+_command runner_ class (`Cri::CommandRunner`) that will perform the actual
+execution of the command. This makes it easier to break up large run blocks
+into manageable pieces.
+
+Commands can have subcommands. For example, the `git` commandline tool would be
+represented by a command that has subcommands named `commit`, `add`, and so on.
+Commands with subcommands do not use a run block; execution will always be
+dispatched to a subcommand (or none, if no subcommand is found).
+
+To add a command as a subcommand to another command, use the
+`Cri::Command#add_command` method, like this:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+root_cmd.add_command(cmd_add)
+root_cmd.add_command(cmd_commit)
+root.cmd.add_command(cmd_init)
+--------------------------------------------------------------------------------
+
+== Contributors ==
+
+* Toon Willems
+* Ken Coar
+
+Thanks for Lee “injekt” Jarvis for link:https://github.com/injekt/slop[Slop],
+which has inspired the design of Cri 2.0.

data/cri.gemspec

@@ -19,12 +19,12 @@ Gem::Specification.new do |s|
                          [ 'cri.gemspec' ]
   s.require_paths      = [ 'lib' ]
 
-  s.add_dependency('colored', '>= 1.2')
+  s.add_dependency('colored', '~> 1.2')
 
-  s.add_development_dependency('rake')
-  s.add_development_dependency('minitest')
-  s.add_development_dependency('yard')
+  s.add_development_dependency('rake',     '~> 10.1')
+  s.add_development_dependency('minitest', '~> 5.3')
+  s.add_development_dependency('yard',     '~> 0.8')
 
-  s.rdoc_options     = [ '--main', 'README.md' ]
-  s.extra_rdoc_files = [ 'LICENSE', 'README.md', 'NEWS.md' ]
+  s.rdoc_options     = [ '--main', 'README.adoc' ]
+  s.extra_rdoc_files = [ 'LICENSE', 'README.adoc', 'NEWS.md' ]
 end

data/lib/cri.rb

@@ -20,6 +20,7 @@ module Cri
   autoload 'Command',           'cri/command'
   autoload 'CommandDSL',        'cri/command_dsl'
   autoload 'CommandRunner',     'cri/command_runner'
+  autoload 'HelpRenderer',      'cri/help_renderer'
   autoload 'OptionParser',      'cri/option_parser'
 
 end
@@ -27,3 +28,4 @@ end
 require 'set'
 
 require 'cri/core_ext'
+require 'cri/argument_array'

data/lib/cri/argument_array.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+
+module Cri
+
+  # Represents an array of arguments. It is an array that strips separator
+  # arguments (`--`) but provides a `#raw` method to get the raw arguments
+  # array, i.e. an array that includes the separator `--` arguments.
+  class ArgumentArray < Array
+
+    # Initializes the array using the given raw arguments.
+    #
+    # @param [Array<String>] raw_arguments A list of raw arguments, i.e.
+    #   including any separator arguments (`--`).
+    def initialize(raw_arguments)
+      super(raw_arguments.reject { |a| '--' == a })
+      @raw_arguments = raw_arguments
+    end
+
+    # @return [Array<String>] The arguments, including any separator arguments
+    #   (`--`)
+    def raw
+      @raw_arguments
+    end
+
+  end
+
+end

data/lib/cri/command.rb

@@ -300,92 +300,7 @@ module Cri
 
     # @return [String] The help text for this command
     def help(params={})
-      is_verbose = params.fetch(:verbose, false)
-
-      text = ''
-
-      # Append name and summary
-      if summary
-        text << "name".formatted_as_title << "\n"
-        text << "    #{name.formatted_as_command} - #{summary}" << "\n"
-        unless aliases.empty?
-          text << "    aliases: " << aliases.map { |a| a.formatted_as_command }.join(' ') << "\n"
-        end
-      end
-
-      # Append usage
-      if usage
-        path = [ self.supercommand ]
-        path.unshift(path[0].supercommand) until path[0].nil?
-        formatted_usage = usage.gsub(/^([^\s]+)/) { |m| m.formatted_as_command }
-        full_usage = path[1..-1].map { |c| c.name.formatted_as_command + ' ' }.join + formatted_usage
-
-        text << "\n"
-        text << "usage".formatted_as_title << "\n"
-        text << full_usage.wrap_and_indent(78, 4) << "\n"
-      end
-
-      # Append long description
-      if description
-        text << "\n"
-        text << "description".formatted_as_title << "\n"
-        text << description.wrap_and_indent(78, 4) + "\n"
-      end
-
-      # Append subcommands
-      unless self.subcommands.empty?
-        text << "\n"
-        text << (self.supercommand ? 'subcommands' : 'commands').formatted_as_title
-        text << "\n"
-
-        shown_subcommands = self.subcommands.select { |c| !c.hidden? || is_verbose }
-        length = shown_subcommands.map { |c| c.name.formatted_as_command.size }.max
-
-        # Command
-        shown_subcommands.sort_by { |cmd| cmd.name }.each do |cmd|
-          text << sprintf("    %-#{length+4}s %s\n",
-            cmd.name.formatted_as_command,
-            cmd.summary)
-        end
-
-        # Hidden notice
-        if !is_verbose
-          diff = self.subcommands.size - shown_subcommands.size
-          case diff
-          when 0
-          when 1
-            text << "    (1 hidden command omitted; show it with --verbose)\n"
-          else
-            text << "    (#{diff} hidden commands omitted; show them with --verbose)\n"
-          end
-        end
-      end
-
-      # Append options
-      groups = { 'options' => self.option_definitions }
-      if self.supercommand
-        groups["options for #{self.supercommand.name}"] = self.supercommand.global_option_definitions
-      end
-      length = groups.values.inject(&:+).map { |o| o[:long].to_s.size }.max
-      groups.keys.sort.each do |name|
-        defs = groups[name]
-        unless defs.empty?
-          text << "\n"
-          text << "#{name}".formatted_as_title
-          text << "\n"
-          ordered_defs = defs.sort_by { |x| x[:short] || x[:long] }
-          ordered_defs.each do |opt_def|
-            text << sprintf(
-              "    %-2s %-#{length+6}s",
-              opt_def[:short] ? ('-' + opt_def[:short]) : '',
-              opt_def[:long] ? ('--' + opt_def[:long]) : '').formatted_as_option
-
-            text << opt_def[:desc] << "\n"
-          end
-        end
-      end
-
-      text
+      HelpRenderer.new(self, params).render
     end
 
     # Compares this command's name to the other given command's name.

data/lib/cri/commands/basic_help.rb

@@ -20,12 +20,8 @@ run do |opts, args, cmd|
 
   is_verbose = opts.fetch(:verbose, false)
 
-  if args.empty?
-    puts cmd.supercommand.help(:verbose => is_verbose)
-  elsif args.size == 1
-    puts cmd.supercommand.command_named(args[0]).help(:verbose => is_verbose)
-  else
-    $stderr.puts cmd.usage
-    exit 1
+  resolved_cmd = args.inject(cmd.supercommand) do |acc, name|
+    acc.command_named(name)
   end
+  puts resolved_cmd.help(:verbose => is_verbose)
 end

data/lib/cri/help_renderer.rb

@@ -0,0 +1,123 @@
+# encoding: utf-8
+
+module Cri
+
+  class HelpRenderer
+
+    def initialize(cmd, params={})
+      @cmd        = cmd
+      @is_verbose = params.fetch(:verbose, false)
+    end
+
+    def render
+      text = ''
+
+      append_summary(text)
+      append_usage(text)
+      append_description(text)
+      append_subcommands(text)
+      append_options(text)
+
+      text
+    end
+
+    private
+
+    def append_summary(text)
+      return if @cmd.summary.nil?
+
+      text << "name".formatted_as_title << "\n"
+      text << "    #{@cmd.name.formatted_as_command} - #{@cmd.summary}" << "\n"
+      unless @cmd.aliases.empty?
+        text << "    aliases: " << @cmd.aliases.map { |a| a.formatted_as_command }.join(' ') << "\n"
+      end
+    end
+
+    def append_usage(text)
+      return if @cmd.usage.nil?
+
+      path = [ @cmd.supercommand ]
+      path.unshift(path[0].supercommand) until path[0].nil?
+      formatted_usage = @cmd.usage.gsub(/^([^\s]+)/) { |m| m.formatted_as_command }
+      full_usage = path[1..-1].map { |c| c.name.formatted_as_command + ' ' }.join + formatted_usage
+
+      text << "\n"
+      text << "usage".formatted_as_title << "\n"
+      text << full_usage.wrap_and_indent(78, 4) << "\n"
+    end
+
+    def append_description(text)
+      return if @cmd.description.nil?
+
+      text << "\n"
+      text << "description".formatted_as_title << "\n"
+      text << @cmd.description.wrap_and_indent(78, 4) + "\n"
+    end
+
+    def append_subcommands(text)
+      return if @cmd.subcommands.empty?
+
+      text << "\n"
+      text << (@cmd.supercommand ? 'subcommands' : 'commands').formatted_as_title
+      text << "\n"
+
+      shown_subcommands = @cmd.subcommands.select { |c| !c.hidden? || @is_verbose }
+      length = shown_subcommands.map { |c| c.name.formatted_as_command.size }.max
+
+      # Command
+      shown_subcommands.sort_by { |cmd| cmd.name }.each do |cmd|
+        text << sprintf("    %-#{length+4}s %s\n",
+          cmd.name.formatted_as_command,
+          cmd.summary)
+      end
+
+      # Hidden notice
+      if !@is_verbose
+        diff = @cmd.subcommands.size - shown_subcommands.size
+        case diff
+        when 0
+        when 1
+          text << "    (1 hidden command omitted; show it with --verbose)\n"
+        else
+          text << "    (#{diff} hidden commands omitted; show them with --verbose)\n"
+        end
+      end
+    end
+
+    def append_options(text)
+      groups = { 'options' => @cmd.option_definitions }
+      if @cmd.supercommand
+        groups["options for #{@cmd.supercommand.name}"] = @cmd.supercommand.global_option_definitions
+      end
+      length = groups.values.inject(&:+).map { |o| o[:long].to_s.size }.max
+      groups.keys.sort.each do |name|
+        defs = groups[name]
+        append_option_group(text, name, defs, length)
+      end
+    end
+
+    def append_option_group(text, name, defs, length)
+      return if defs.empty?
+
+      text << "\n"
+      text << "#{name}".formatted_as_title
+      text << "\n"
+
+      ordered_defs = defs.sort_by { |x| x[:short] || x[:long] }
+      ordered_defs.each do |opt_def|
+        text << format_opt_def(opt_def, length)
+        text << opt_def[:desc] << "\n"
+      end
+    end
+
+    def format_opt_def(opt_def, length)
+      opt_text = sprintf(
+          "    %-2s %-#{length+6}s",
+          opt_def[:short] ? ('-' + opt_def[:short]) : '',
+          opt_def[:long]  ? ('--' + opt_def[:long]) : '')
+      opt_text.formatted_as_option
+    end
+
+  end
+
+end

data/lib/cri/option_parser.rb

@@ -84,14 +84,9 @@ module Cri
     # @return [Hash] The already parsed options.
     attr_reader :options
 
-    # The arguments that have already been parsed.
-    #
-    # If the parser was stopped before it finished, this will not contain all
-    # options and `unprocessed_arguments_and_options` will contain what is
-    # left to be processed.
-    #
-    # @return [Array] The already parsed arguments.
-    attr_reader :arguments
+    # @return [Array] The arguments that have already been parsed, including
+    #   the -- separator.
+    attr_reader :raw_arguments
 
     # The options and arguments that have not yet been processed. If the
     # parser wasn’t stopped (using {#stop}), this list will be empty.
@@ -122,13 +117,24 @@ module Cri
       @unprocessed_arguments_and_options = arguments_and_options.dup
       @definitions = definitions
 
-      @options   = {}
-      @arguments = []
+      @options       = {}
+      @raw_arguments = []
 
       @running = false
       @no_more_options = false
     end
 
+    # Returns the arguments that have already been parsed.
+    #
+    # If the parser was stopped before it finished, this will not contain all
+    # options and `unprocessed_arguments_and_options` will contain what is
+    # left to be processed.
+    #
+    # @return [Array] The already parsed arguments.
+    def arguments
+      ArgumentArray.new(@raw_arguments).freeze
+    end
+
     # @return [Boolean] true if the parser is running, false otherwise.
     def running?
       @running
@@ -161,78 +167,12 @@ module Cri
         e = @unprocessed_arguments_and_options.shift
         break if e.nil?
 
-        # Handle end-of-options marker
         if e == '--'
-          @no_more_options = true
-        # Handle incomplete options
+          handle_dashdash(e)
         elsif e =~ /^--./ and !@no_more_options
-          # Get option key, and option value if included
-          if e =~ /^--([^=]+)=(.+)$/
-            option_key   = $1
-            option_value = $2
-          else
-            option_key    = e[2..-1]
-            option_value  = nil
-          end
-
-          # Find definition
-          definition = @definitions.find { |d| d[:long] == option_key }
-          raise IllegalOptionError.new(option_key) if definition.nil?
-
-          if [ :required, :optional ].include?(definition[:argument])
-            # Get option value if necessary
-            if option_value.nil?
-              option_value = @unprocessed_arguments_and_options.shift
-              if option_value.nil? || option_value =~ /^-/
-                if definition[:argument] == :required
-                  raise OptionRequiresAnArgumentError.new(option_key)
-                else
-                  @unprocessed_arguments_and_options.unshift(option_value)
-                  option_value = true
-                end
-              end
-            end
-
-            # Store option
-            add_option(definition, option_value)
-          else
-            # Store option
-            add_option(definition, true)
-          end
-        # Handle -xyz options
+          handle_dashdash_option(e)
         elsif e =~ /^-./ and !@no_more_options
-          # Get option keys
-          option_keys = e[1..-1].scan(/./)
-
-          # For each key
-          option_keys.each do |option_key|
-            # Find definition
-            definition = @definitions.find { |d| d[:short] == option_key }
-            raise IllegalOptionError.new(option_key) if definition.nil?
-
-            if option_keys.length > 1 and definition[:argument] == :required
-              # This is a combined option and it requires an argument, so complain
-              raise OptionRequiresAnArgumentError.new(option_key)
-            elsif [ :required, :optional ].include?(definition[:argument])
-              # Get option value
-              option_value = @unprocessed_arguments_and_options.shift
-              if option_value.nil? || option_value =~ /^-/
-                if definition[:argument] == :required
-                  raise OptionRequiresAnArgumentError.new(option_key)
-                else
-                  @unprocessed_arguments_and_options.unshift(option_value)
-                  option_value = true
-                end
-              end
-
-              # Store option
-              add_option(definition, option_value)
-            else
-              # Store option
-              add_option(definition, true)
-            end
-          end
-        # Handle normal arguments
+          handle_dash_option(e)
         else
           add_argument(e)
         end
@@ -244,6 +184,78 @@ module Cri
 
   private
 
+    def handle_dashdash(e)
+      add_argument(e)
+      @no_more_options = true
+    end
+
+    def handle_dashdash_option(e)
+      # Get option key, and option value if included
+      if e =~ /^--([^=]+)=(.+)$/
+        option_key   = $1
+        option_value = $2
+      else
+        option_key    = e[2..-1]
+        option_value  = nil
+      end
+
+      # Find definition
+      definition = @definitions.find { |d| d[:long] == option_key }
+      raise IllegalOptionError.new(option_key) if definition.nil?
+
+      if [ :required, :optional ].include?(definition[:argument])
+        # Get option value if necessary
+        if option_value.nil?
+          option_value = find_option_value(definition, option_key)
+        end
+
+        # Store option
+        add_option(definition, option_value)
+      else
+        # Store option
+        add_option(definition, true)
+      end
+    end
+
+    def handle_dash_option(e)
+      # Get option keys
+      option_keys = e[1..-1].scan(/./)
+
+      # For each key
+      option_keys.each do |option_key|
+        # Find definition
+        definition = @definitions.find { |d| d[:short] == option_key }
+        raise IllegalOptionError.new(option_key) if definition.nil?
+
+        if option_keys.length > 1 and definition[:argument] == :required
+          # This is a combined option and it requires an argument, so complain
+          raise OptionRequiresAnArgumentError.new(option_key)
+        elsif [ :required, :optional ].include?(definition[:argument])
+          # Get option value
+          option_value = find_option_value(definition, option_key)
+
+          # Store option
+          add_option(definition, option_value)
+        else
+          # Store option
+          add_option(definition, true)
+        end
+      end
+    end
+
+    def find_option_value(definition, option_key)
+      option_value = @unprocessed_arguments_and_options.shift
+      if option_value.nil? || option_value =~ /^-/
+        if definition[:argument] == :required
+          raise OptionRequiresAnArgumentError.new(option_key)
+        else
+          @unprocessed_arguments_and_options.unshift(option_value)
+          option_value = true
+        end
+      end
+      option_value
+    end
+
     def add_option(definition, value)
       key = (definition[:long] || definition[:short]).to_sym
       options[key] = value
@@ -251,8 +263,11 @@ module Cri
     end
 
     def add_argument(value)
-      arguments << value
-      delegate.argument_added(value, self) unless delegate.nil?
+      @raw_arguments << value
+
+      unless '--' == value
+        delegate.argument_added(value, self) unless delegate.nil?
+      end
     end
 
   end

data/lib/cri/version.rb

@@ -1,6 +1,6 @@
 module Cri
 
   # The current Cri version.
-  VERSION = '2.4.1'
+  VERSION = '2.5.0'
 
 end

data/test/test_argument_array.rb

@@ -0,0 +1,11 @@
+# encoding: utf-8
+
+class Cri::ArgumentArrayTestCase < Cri::TestCase
+
+  def test_initialize
+    arr = Cri::ArgumentArray.new([ 'foo', 'bar', '--', 'baz' ])
+    assert_equal [ 'foo', 'bar', 'baz' ], arr
+    assert_equal [ 'foo', 'bar', '--', 'baz' ], arr.raw
+  end
+
+end

data/test/test_basic_help.rb

@@ -21,4 +21,47 @@ class Cri::BasicHelpTestCase < Cri::TestCase
     help_cmd.run([])
   end
 
+  def test_run_with_chain_of_commands
+    cmd = Cri::Command.define do
+      name 'root'
+      summary 'I am root!'
+
+      subcommand do
+        name 'foo'
+        summary 'I am foo!'
+
+        subcommand do
+          name 'subsubby'
+          summary 'I am subsubby!'
+        end
+      end
+    end
+
+    help_cmd = Cri::Command.new_basic_help
+    cmd.add_command(help_cmd)
+
+    # Simple call
+    stdout, stderr = capture_io_while do
+      help_cmd.run([ 'foo' ])
+    end
+    assert_match(/I am foo!/m, stdout)
+    assert_equal('', stderr)
+
+    # Subcommand
+    stdout, stderr = capture_io_while do
+      help_cmd.run([ 'foo', 'subsubby' ])
+    end
+    assert_match(/I am subsubby!/m, stdout)
+    assert_equal('', stderr)
+
+    # Non-existing subcommand
+    stdout, stderr = capture_io_while do
+      assert_raises SystemExit do
+        help_cmd.run([ 'foo', 'mysterycmd' ])
+      end
+    end
+    assert_equal '', stdout
+    assert_match(/foo: unknown command 'mysterycmd'/, stderr)
+  end
+
 end

data/test/test_command.rb

@@ -424,4 +424,34 @@ class Cri::CommandTestCase < Cri::TestCase
     assert_match(pattern, cmd.help(:verbose => true))
   end
 
+  def test_run_with_raw_args
+    cmd = Cri::Command.define do
+      name 'moo'
+      run do |opts, args|
+        puts "args=#{args.join(',')} args.raw=#{args.raw.join(',')}"
+      end
+    end
+
+    out, err = capture_io_while do
+      cmd.run(%w( foo -- bar ))
+    end
+    assert_equal "args=foo,bar args.raw=foo,--,bar\n", out
+  end
+
+  def test_runner_with_raw_args
+    cmd = Cri::Command.define do
+      name 'moo'
+      runner(Class.new(Cri::CommandRunner) do
+        def run
+          puts "args=#{arguments.join(',')} args.raw=#{arguments.raw.join(',')}"
+        end
+      end)
+    end
+
+    out, err = capture_io_while do
+      cmd.run(%w( foo -- bar ))
+    end
+    assert_equal "args=foo,bar args.raw=foo,--,bar\n", out
+  end
+
 end

data/test/test_option_parser.rb

@@ -263,8 +263,9 @@ class Cri::OptionParserTestCase < Cri::TestCase
 
     parser = Cri::OptionParser.parse(input, definitions)
 
-    assert_equal({},                                      parser.options)
-    assert_equal([ 'foo', 'bar', '-x', '--yyy', '-abc' ], parser.arguments)
+    assert_equal({},                                            parser.options)
+    assert_equal([ 'foo', 'bar', '-x', '--yyy', '-abc' ],       parser.arguments)
+    assert_equal([ 'foo', 'bar', '--', '-x', '--yyy', '-abc' ], parser.arguments.raw)
   end
 
   def test_parse_with_end_marker_between_option_key_and_value

metadata

@@ -1,71 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: cri
 version: !ruby/object:Gem::Version
-  version: 2.4.1
+  version: 2.5.0
 platform: ruby
 authors:
 - Denis Defreyne
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-29 00:00:00.000000000 Z
+date: 2014-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colored
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.1'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '5.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '5.3'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.8'
 description: Cri allows building easy-to-use commandline interfaces with support for
   subcommands.
 email: denis.defreyne@stoneship.org
@@ -73,26 +73,30 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - LICENSE
-- README.md
+- README.adoc
 - NEWS.md
 files:
 - Gemfile
 - Gemfile.lock
 - LICENSE
 - NEWS.md
+- README.adoc
 - Rakefile
-- README.md
+- cri.gemspec
+- lib/cri.rb
+- lib/cri/argument_array.rb
 - lib/cri/command.rb
 - lib/cri/command_dsl.rb
 - lib/cri/command_runner.rb
 - lib/cri/commands/basic_help.rb
 - lib/cri/commands/basic_root.rb
-- lib/cri/core_ext/string.rb
 - lib/cri/core_ext.rb
+- lib/cri/core_ext/string.rb
+- lib/cri/help_renderer.rb
 - lib/cri/option_parser.rb
 - lib/cri/version.rb
-- lib/cri.rb
 - test/helper.rb
+- test/test_argument_array.rb
 - test/test_base.rb
 - test/test_basic_help.rb
 - test/test_basic_root.rb
@@ -100,7 +104,6 @@ files:
 - test/test_command_dsl.rb
 - test/test_core_ext.rb
 - test/test_option_parser.rb
-- cri.gemspec
 homepage: http://stoneship.org/software/cri/
 licenses:
 - MIT
@@ -108,7 +111,7 @@ metadata: {}
 post_install_message: 
 rdoc_options:
 - --main
-- README.md
+- README.adoc
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
@@ -123,7 +126,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.11
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: a library for building easy-to-use commandline tools

data/README.md

@@ -1,138 +0,0 @@
-Cri
-===
-
-Cri is a library for building easy-to-use commandline tools with support for
-nested commands.
-
-Usage
------
-
-The central concept in Cri is the _command_, which has option definitions as
-well as code for actually executing itself. In Cri, the commandline tool
-itself is a command as well.
-
-Here’s a sample command definition:
-
-	command = Cri::Command.define do
-	  name        'dostuff'
-	  usage       'dostuff [options]'
-	  aliases     :ds, :stuff
-	  summary     'does stuff'
-	  description 'This command does a lot of stuff. I really mean a lot.'
-
-	  flag   :h,  :help,  'show help for this command' do |value, cmd|
-	    puts cmd.help
-	    exit 0
-	  end
-	  flag   nil, :more,  'do even more stuff'
-	  option :s,  :stuff, 'specify stuff to do', :argument => :required
-
-	  run do |opts, args, cmd|
-	    stuff = opts[:stuff] || 'generic stuff'
-	    puts "Doing #{stuff}!"
-
-	    if opts[:more]
-	      puts 'Doing it even more!'
-	    end
-	  end
-	end
-
-To run this command, invoke the `#run` method with the raw arguments. For
-example, for a root command (the commandline tool itself), the command could
-be called like this:
-
-	command.run(ARGS)
-
-Each command has automatically generated help. This help can be printed using
-{Cri::Command#help}; something like this will be shown:
-
-	usage: dostuff [options]
-
-	does stuff
-
-	    This command does a lot of stuff. I really mean a lot.
-
-	options:
-
-	    -h --help      show help for this command
-	       --more      do even more stuff
-	    -s --stuff     specify stuff to do
-
-Let’s disect the command definition and start with the first five lines:
-
-	name        'dostuff'
-	usage       'dostuff [options]'
-	aliases     :ds, :stuff
-	summary     'does stuff'
-	description 'This command does a lot of stuff. I really mean a lot.'
-
-These lines of the command definition specify the name of the command (or the
-commandline tool, if the command is the root command), the usage, a list of
-aliases that can be used to call this command, a one-line summary and a (long)
-description. The usage should not include a “usage:” prefix nor the name of
-the supercommand, because the latter will be automatically prepended.
-
-Aliases don’t make sense for root commands, but for subcommands they do.
-
-The next few lines contain the command’s option definitions:
-
-	flag   :h,  :help,  'show help for this command' do |value, cmd|
-	  puts cmd.help
-	  exit 0
-	end
-	flag   nil, :more,  'do even more stuff'
-	option :s,  :stuff, 'specify stuff to do', :argument => :required
-
-Options can be defined using the following methods:
-
-* {Cri::CommandDSL#option} or {Cri::CommandDSL#opt}
-* {Cri::CommandDSL#flag} (implies forbidden argument)
-* {Cri::CommandDSL#required} (implies required argument)
-* {Cri::CommandDSL#optional} (implies optional argument)
-
-All these methods take the short option form as their first argument, and a
-long option form as their second argument. Either the short or the long form
-can be nil, but not both (because that would not make any sense). In the
-example above, the `--more` option has no short form.
-
-Each of the above methods also take a block, which will be executed when the
-option is found. The argument to the block are the option value (`true` in
-case the option does not have an argument) and the command.
-
-The last part of the command defines the execution itself:
-
-	run do |opts, args, cmd|
-	  stuff = opts[:stuff] || 'generic stuff'
-	  puts "Doing #{stuff}!"
-
-	  if opts[:more]
-	    puts 'Doing it even more!'
-	  end
-	end
-
-The {Cri::CommandDSL#run} method takes a block with the actual code to
-execute. This block takes three arguments: the options, any arguments passed
-to the command, and the command itself.
-
-Instead of defining a run block, it is possible to declare a class, the
-_command runner_ class ({Cri::CommandRunner}) that will perform the actual
-execution of the command. This makes it easier to break up large run blocks
-into manageable pieces.
-
-Commands can have subcommands. For example, the `git` commandline tool would be represented by a command that has subcommands named `commit`, `add`, and so on. Commands with subcommands do not use a run block; execution will always be dispatched to a subcommand (or none, if no subcommand is found).
-
-To add a command as a subcommand to another command, use the {Cri::Command#add_command} method, like this:
-
-	root_cmd.add_command cmd_add
-	root_cmd.add_command cmd_commit
-	root.cmd.add_command cmd_init
-
-Contributors
-------------
-
-* Toon Willems
-* Ken Coar
-
-Thanks for Lee “injekt” Jarvis for [Slop][1], which has inspired the design of Cri 2.0.
-
-[1]: https://github.com/injekt/slop