cri 1.0.1 → 2.0a1

data/lib/cri/command_dsl.rb

@@ -0,0 +1,98 @@
+# encoding: utf-8
+
+module Cri
+
+  # @todo Document
+  class CommandDSL
+
+    def initialize(command=nil)
+      @command = command || Cri::Command.new
+    end
+
+    # @todo Document
+    def command
+      @command
+    end
+
+    # @todo Document
+    def subcommand(cmd=nil, &block)
+      if cmd.nil?
+        cmd = Cri::Command.define(&block)
+      end
+
+      @command.add_command(cmd)
+    end
+
+    # @todo Document
+    def name(arg)
+      @command.name = arg
+    end
+
+    # @todo Document
+    def aliases(*args)
+      @command.aliases = args.flatten
+    end
+
+    # @todo Document
+    def summary(arg)
+      @command.short_desc = arg
+    end
+
+    # @todo Document
+    def description(arg)
+      @command.long_desc = arg
+    end
+
+    # @todo Document
+    def usage(arg)
+      @command.usage = arg
+    end
+
+    # @todo Document
+    def option(short, long, desc, params={}, &block)
+      requiredness = params[:argument] || :forbidden
+      self.add_option(short, long, desc, requiredness, block)
+    end
+    alias_method :opt, :option
+
+    # @todo Document
+    def required(short, long, desc, &block)
+      self.add_option(short, long, desc, :required, block)
+    end
+
+    # @todo Document
+    def flag(short, long, desc, &block)
+      self.add_option(short, long, desc, :forbidden, block)
+    end
+    alias_method :forbidden, :flag
+
+    # @todo Document
+    def optional(short, long, desc, &block)
+      self.add_option(short, long, desc, :optional, block)
+    end
+
+    # @todo Document
+    def run(&block)
+      if block.arity != 2
+        raise ArgumentError,
+          "The block given to Cri::Command#run expects exactly two args"
+      end
+
+      @command.block = block
+    end
+
+  protected
+
+    # @todo Document
+    def add_option(short, long, desc, argument, block)
+      @command.option_definitions << {
+        :short    => short.to_s,
+        :long     => long.to_s,
+        :desc     => desc,
+        :argument => argument,
+        :block    => block }
+    end
+
+  end
+
+end

data/lib/cri/commands/basic_help.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+
+name        'help'
+usage       'help [command_name]'
+summary     'show help'
+description <<-EOS
+Show help for the given command, or show general help. When no command is
+given, a list of available commands is displayed, as well as a list of global
+commandline options. When a command is given, a command description as well as
+command-specific commandline options are shown.
+EOS
+
+run do |opts, args|
+  if args.empty?
+    puts self.supercommand.help
+  elsif args.size == 1
+    puts self.supercommand.command_named(args[0]).help
+  else
+    $stderr.puts self.usage
+    exit 1
+  end
+end

data/lib/cri/commands/basic_root.rb

@@ -0,0 +1,8 @@
+# encoding: utf-8
+
+option :h, :help, 'show help for this command' do |value|
+  puts self.help
+  exit 0
+end
+
+subcommand Cri::Command.new_basic_help

data/lib/cri/core_ext.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Cri::CoreExtensions
 end
 

data/lib/cri/core_ext/string.rb

@@ -1,7 +1,25 @@
+# encoding: utf-8
+
 module Cri::CoreExtensions
 
   module String
 
+    # @todo Document
+    def to_paragraphs
+      lines = self.scan(/([^\n]+\n|[^\n]*$)/).map { |s| s[0].strip }
+
+      paragraphs = [ [] ]
+      lines.each do |line|
+        if line.empty?
+          paragraphs << []
+        else
+          paragraphs.last << line
+        end
+      end
+
+      paragraphs.reject { |p| p.empty? }.map { |p| p.join(' ') }
+    end
+
     # Word-wraps and indents the string.
     #
     # +width+:: The maximal width of each line. This also includes indentation,
@@ -10,7 +28,7 @@ module Cri::CoreExtensions
     # +indentation+:: The number of spaces to indent each wrapped line.
     def wrap_and_indent(width, indentation)
       # Split into paragraphs
-      paragraphs = self.split("\n").map { |p| p.strip }.reject { |p| p == '' }
+      paragraphs = self.to_paragraphs
 
       # Wrap and indent each paragraph
       paragraphs.map do |paragraph|

data/lib/cri/option_parser.rb

@@ -1,17 +1,93 @@
+# encoding: utf-8
+
 module Cri
 
   # Cri::OptionParser is used for parsing commandline options.
   class OptionParser
 
+    # Superclass for generic option parser errors.
+    class GenericError < StandardError
+    end
+
     # Error that will be raised when an unknown option is encountered.
-    class IllegalOptionError < RuntimeError ; end
+    class IllegalOptionError < Cri::OptionParser::GenericError
+    end
 
     # Error that will be raised when an option without argument is
     # encountered.
-    class OptionRequiresAnArgumentError < RuntimeError ; end
+    class OptionRequiresAnArgumentError < Cri::OptionParser::GenericError
+    end
+
+    # The delegate to which events will be sent. The following methods will
+    # be send to the delegate:
+    #
+    # * `option_added(key, value, cmd)`
+    # * `argument_added(argument, cmd)`
+    #
+    # @return [#option_added, #argument_added] The delegate
+    attr_accessor :delegate
+
+    # The options 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 [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
+
+    # The options and arguments that have not yet been processed. If the
+    # parser wasn’t stopped (using {#stop}), this list will be empty.
+    #
+    # @return [Array] The not yet parsed options and arguments.
+    attr_reader :unprocessed_arguments_and_options
+
+    # Parses the commandline arguments. See the instance `parse` method for
+    # details.
+    def self.parse(arguments_and_options, definitions)
+      self.new(arguments_and_options, definitions).run
+    end
 
-    # Parses the commandline arguments in +arguments_and_options+, using the
-    # commandline option definitions in +definitions+.
+    # Creates a new parser with the given options/arguments and definitions.
+    #
+    # @param [Array<String>] arguments_and_options An array containing the
+    #   commandline arguments
+    #
+    # @param [Array<Hash>] definitions An array of option definitions
+    def initialize(arguments_and_options, definitions)
+      @unprocessed_arguments_and_options = arguments_and_options.dup
+      @definitions = definitions
+
+      @options   = {}
+      @arguments = []
+
+      @running = false
+      @no_more_options = false
+    end
+
+    # @return [Boolean] true if the parser is running, false otherwise.
+    def running?
+      @running
+    end
+
+    # Stops the parser. The parser will finish its current parse cycle but
+    # will not start parsing new options and/or arguments.
+    #
+    # @return [void]
+    def stop
+      @running = false
+    end
+
+    # Parses the commandline arguments into options and arguments
     #
     # +arguments_and_options+ is an array of commandline arguments and
     # options. This will usually be +ARGV+.
@@ -85,27 +161,19 @@ module Cri
     #         :name   => 'luke'
     #       }
     #     }
-    def self.parse(arguments_and_options, definitions)
-      # Don't touch original argument
-      unprocessed_arguments_and_options = arguments_and_options.dup
-
-      # Initialize
-      arguments = []
-      options   = {}
+    def run
+      @running = true
 
-      # Determines whether we've passed the '--' marker or not
-      no_more_options = false
-
-      loop do
+      while running?
         # Get next item
-        e = unprocessed_arguments_and_options.shift
+        e = @unprocessed_arguments_and_options.shift
         break if e.nil?
 
         # Handle end-of-options marker
         if e == '--'
-          no_more_options = true
+          @no_more_options = true
         # Handle incomplete options
-        elsif e =~ /^--./ and !no_more_options
+        elsif e =~ /^--./ and !@no_more_options
           # Get option key, and option value if included
           if e =~ /^--([^=]+)=(.+)$/
             option_key   = $1
@@ -116,38 +184,38 @@ module Cri
           end
 
           # Find definition
-          definition = definitions.find { |d| d[:long] == option_key }
+          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
+              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)
+                  @unprocessed_arguments_and_options.unshift(option_value)
                   option_value = true
                 end
               end
             end
 
             # Store option
-            options[definition[:long].to_sym] = option_value
+            add_option(definition[:long].to_sym, option_value)
           else
             # Store option
-            options[definition[:long].to_sym] = true
+            add_option(definition[:long].to_sym, true)
           end
         # Handle -xyz options
-        elsif e =~ /^-./ and !no_more_options
+        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 }
+            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
@@ -155,30 +223,44 @@ module Cri
               raise OptionRequiresAnArgumentError.new(option_key)
             elsif [ :required, :optional ].include?(definition[:argument])
               # Get option value
-              option_value = unprocessed_arguments_and_options.shift
+              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)
+                  @unprocessed_arguments_and_options.unshift(option_value)
                   option_value = true
                 end
               end
 
               # Store option
-              options[definition[:long].to_sym] = option_value
+              add_option(definition[:long].to_sym, option_value)
             else
               # Store option
-              options[definition[:long].to_sym] = true
+              add_option(definition[:long].to_sym, true)
             end
           end
         # Handle normal arguments
         else
-          arguments << e
+          add_argument(e)
         end
       end
 
       { :options => options, :arguments => arguments }
+    ensure
+      @running = false
+    end
+
+  private
+
+    def add_option(key, value)
+      options[key] = value
+      delegate.option_added(key, value, self) unless delegate.nil?
+    end
+
+    def add_argument(value)
+      arguments << value
+      delegate.argument_added(value, self) unless delegate.nil?
     end
 
   end

data/test/helper.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+require 'stringio'
+
+class Cri::TestCase < MiniTest::Unit::TestCase
+
+  def capture_io_while(&block)
+    $orig_stdout = $stdout
+    $orig_stderr = $stderr
+
+    $stdout = StringIO.new
+    $stderr = StringIO.new
+
+    block.call
+
+    [ $stdout.string, $stderr.string ]
+  ensure
+    $stdout = $orig_stdout
+    $stderr = $orig_stderr
+  end
+
+  def lines(string)
+    string.scan(/^.*\n/).map { |s| s.chomp }
+  end
+
+end

data/test/test_base.rb

@@ -0,0 +1,8 @@
+# encoding: utf-8
+
+class Cri::BaseTestCase < Cri::TestCase
+
+  def test_stub
+  end
+
+end

data/test/test_command.rb

@@ -0,0 +1,232 @@
+# encoding: utf-8
+
+class Cri::CommandTestCase < Cri::TestCase
+
+  def simple_cmd
+    Cri::Command.define do
+      name        'moo'
+      usage       'dunno whatever'
+      summary     'does stuff'
+      description 'This command does a lot of stuff.'
+
+      option    :a, :aaa, 'opt a', :argument => :optional do |value|
+        $stdout.puts "#{name}:#{value}"
+      end
+      required  :b, :bbb, 'opt b'
+      optional  :c, :ccc, 'opt c'
+      flag      :d, :ddd, 'opt d'
+      forbidden :e, :eee, 'opt e'
+
+      run do |opts, args|
+        $stdout.puts "Awesome #{name}!"
+
+        $stdout.puts args.join(',')
+
+        opts_strings = []
+        opts.each_pair { |k,v| opts_strings << "#{k}=#{v}" }
+        $stdout.puts opts_strings.join(',')
+      end
+    end
+  end
+
+  def nested_cmd
+    super_cmd = Cri::Command.define do
+      name        'super'
+      usage       'does something super'
+      summary     'does super stuff'
+      description 'This command does super stuff.'
+
+      option    :a, :aaa, 'opt a', :argument => :optional do |value|
+        $stdout.puts "#{name}:#{value}"
+      end
+      required  :b, :bbb, 'opt b'
+      optional  :c, :ccc, 'opt c'
+      flag      :d, :ddd, 'opt d'
+      forbidden :e, :eee, 'opt e'
+    end
+
+    super_cmd.define_command do
+      name        'sub'
+      aliases     'sup'
+      usage       'does something subby'
+      summary     'does subby stuff'
+      description 'This command does subby stuff.'
+
+      option    :m, :mmm, 'opt m', :argument => :optional
+      required  :n, :nnn, 'opt n'
+      optional  :o, :ooo, 'opt o'
+      flag      :p, :ppp, 'opt p'
+      forbidden :q, :qqq, 'opt q'
+
+      run do |opts, args|
+        $stdout.puts "Sub-awesome!"
+
+        $stdout.puts args.join(',')
+
+        opts_strings = []
+        opts.each_pair { |k,v| opts_strings << "#{k}=#{v}" }
+        $stdout.puts opts_strings.join(',')
+      end
+    end
+
+    super_cmd.define_command do
+      name        'sink'
+      usage       'sink thing_to_sink'
+      summary     'sinks stuff'
+      description 'Sinks stuff (like ships and the like).'
+
+      run do |opts, args|
+        $stdout.puts "Sinking!"
+      end
+    end
+
+    super_cmd
+  end
+
+  def test_invoke_simple_without_opts_or_args
+    out, err = capture_io_while do
+      simple_cmd.run(%w())
+    end
+
+    assert_equal [ 'Awesome moo!', '', '' ], lines(out)
+    assert_equal [], lines(err)
+  end
+
+  def test_invoke_simple_with_args
+    out, err = capture_io_while do
+      simple_cmd.run(%w(abc xyz))
+    end
+
+    assert_equal [ 'Awesome moo!', 'abc,xyz', '' ], lines(out)
+    assert_equal [], lines(err)
+  end
+
+  def test_invoke_simple_with_opts
+    out, err = capture_io_while do
+      simple_cmd.run(%w(-c -b x))
+    end
+
+    assert_equal [ 'Awesome moo!', '', 'ccc=true,bbb=x' ], lines(out)
+    assert_equal [], lines(err)
+  end
+
+  def test_invoke_simple_with_missing_opt_arg
+    out, err = capture_io_while do
+      assert_raises SystemExit do
+        simple_cmd.run(%w( -b ))
+      end
+    end
+
+    assert_equal [], lines(out)
+    assert_equal [ "moo: option requires an argument -- b" ], lines(err)
+  end
+
+  def test_invoke_simple_with_illegal_opt
+    out, err = capture_io_while do
+      assert_raises SystemExit do
+        simple_cmd.run(%w( -z ))
+      end
+    end
+
+    assert_equal [], lines(out)
+    assert_equal [ "moo: illegal option -- z" ], lines(err)
+  end
+
+  def test_invoke_simple_with_opt_with_block
+    out, err = capture_io_while do
+      simple_cmd.run(%w( -a 123 ))
+    end
+
+    assert_equal [ 'moo:123', 'Awesome moo!', '', 'aaa=123' ], lines(out)
+    assert_equal [], lines(err)
+  end
+
+  def test_invoke_nested_without_opts_or_args
+    out, err = capture_io_while do
+      assert_raises SystemExit do
+        nested_cmd.run(%w())
+      end
+    end
+
+    assert_equal [ ], lines(out)
+    assert_equal [ 'super: no command given' ], lines(err)
+  end
+
+  def test_invoke_nested_with_correct_command_name
+    out, err = capture_io_while do
+      nested_cmd.run(%w( sub ))
+    end
+
+    assert_equal [ 'Sub-awesome!', '', '' ], lines(out)
+    assert_equal [ ], lines(err)
+  end
+
+  def test_invoke_nested_with_incorrect_command_name
+    out, err = capture_io_while do
+      assert_raises SystemExit do
+        nested_cmd.run(%w( oogabooga ))
+      end
+    end
+
+    assert_equal [ ], lines(out)
+    assert_equal [ "super: unknown command 'oogabooga'" ], lines(err)
+  end
+
+  def test_invoke_nested_with_ambiguous_command_name
+    out, err = capture_io_while do
+      assert_raises SystemExit do
+        nested_cmd.run(%w( s ))
+      end
+    end
+
+    assert_equal [ ], lines(out)
+    assert_equal [ "super: 's' is ambiguous:", "  sub sink" ], lines(err)
+  end
+
+  def test_invoke_nested_with_alias
+    out, err = capture_io_while do
+      nested_cmd.run(%w( sup ))
+    end
+
+    assert_equal [ 'Sub-awesome!', '', '' ], lines(out)
+    assert_equal [ ], lines(err)
+  end
+
+  def test_invoke_nested_with_options_before_command
+    out, err = capture_io_while do
+      nested_cmd.run(%w( -a 666 sub ))
+    end
+
+    assert_equal [ 'super:666', 'Sub-awesome!', '', 'aaa=666' ], lines(out)
+    assert_equal [ ], lines(err)
+  end
+
+  def test_modify
+    cmd = Cri::Command.define do
+      name 'build'
+    end
+    assert_equal 'build', cmd.name
+
+    cmd.modify do
+      name 'compile'
+    end
+
+    assert_equal 'compile', cmd.name
+  end
+
+  def test_new_basic_root
+    cmd = Cri::Command.new_basic_root.modify do
+      name 'mytool'
+    end
+
+    # Check option definitions
+    assert_equal 1, cmd.option_definitions.size
+    opt_def = cmd.option_definitions.to_a[0]
+    assert_equal 'help', opt_def[:long]
+
+    # Check subcommand
+    assert_equal 1,      cmd.subcommands.size
+    assert_equal 'help', cmd.subcommands.to_a[0].name
+  end
+
+end