gli 2.10.0 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bc8b2ac1abb69495f8096899fbb4da56b2e85d32
-  data.tar.gz: ce4f47438626b06fbd4fcf4b714a5257b63a2ec5
+  metadata.gz: 362815ed2ee02ae4318a321eca52acb7175f802f
+  data.tar.gz: 27dadfccc2e537d4ae9824cf1a75075020391d6c
 SHA512:
-  metadata.gz: 1d9e77187528594f30d47c0dca4cdef47a1dc01fbc35657e0bfec3441a20b1d37d87dccecc4015957bf78c1055ff4ce9a0cb0b728b1e97305b6c8936ba82f2c2
-  data.tar.gz: 81eb28d1e7b564fed156a69fa0159bd4236bffec82d51bf1c5874c6d6a521eb8f24ce1ee3f156ff9445a504311b9deb83deb059ab27120c079b04e8578b286cf
+  metadata.gz: 261bf4ac97f86f4b2b1d68aba7cb7396da8c6e2651504dfd8ce1a736215cca382b723db02820165b69c71e74721b4ac4588c45cfcf7014596c80e1225845a504
+  data.tar.gz: 4a12460017ee29eb4dd7f97111ee5cbb8b5112cd44db7dd933c7edc069b3f8053e0245417e4fa3ffaaeb108b4f85384ab2a86bf0483b7811ad52dbdafb9d6110

data/features/todo.feature

@@ -17,6 +17,7 @@ Feature: The todo app has a nice user interface
 
   Scenario Outline: Getting Help for todo in general
     When I successfully run `todo <help>`
+    Then the exit status should be 0
     Then the output should contain:
     """
     NAME
@@ -195,8 +196,9 @@ Feature: The todo app has a nice user interface
         stored in your todo databases. 
 
     COMMAND OPTIONS
-        -l, --[no-]long     - Show long form
-        --required_flag=arg - (required, default: none)
+        -l, --[no-]long      - Show long form
+        --required_flag=arg  - (required, default: none)
+        --required_flag2=arg - (required, default: none)
 
     COMMANDS
         contexts - List contexts
@@ -238,8 +240,9 @@ Feature: The todo app has a nice user interface
         List a whole lot of things that you might be keeping track of    in your overall todo list.   This is your go-to place or finding all of the things that you   might have    stored in    your todo databases. 
 
     COMMAND OPTIONS
-        -l, --[no-]long     - Show long form
-        --required_flag=arg - (required, default: none)
+        -l, --[no-]long      - Show long form
+        --required_flag=arg  - (required, default: none)
+        --required_flag2=arg - (required, default: none)
 
     COMMANDS
         contexts - List contexts
@@ -270,8 +273,9 @@ Feature: The todo app has a nice user interface
      
 
     COMMAND OPTIONS
-        -l, --[no-]long     - Show long form
-        --required_flag=arg - (required, default: none)
+        -l, --[no-]long      - Show long form
+        --required_flag=arg  - (required, default: none)
+        --required_flag2=arg - (required, default: none)
 
     COMMANDS
         contexts - List contexts
@@ -294,8 +298,9 @@ Feature: The todo app has a nice user interface
         List a whole lot of things that you might be keeping track of    in your overall todo list.   This is your go-to place or finding all of the things that you   might have    stored in    your todo databases. 
 
     COMMAND OPTIONS
-        -l, --[no-]long     - Show long form
-        --required_flag=arg - (required, default: none)
+        -l, --[no-]long      - Show long form
+        --required_flag=arg  - (required, default: none)
+        --required_flag2=arg - (required, default: none)
 
     COMMANDS
         contexts - List contexts
@@ -336,21 +341,27 @@ Feature: The todo app has a nice user interface
     SYNOPSIS
         todo [global options] create 
         todo [global options] create contexts [context_name]
+        todo [global options] create relation_1-1 first second [name]
+        todo [global options] create relation_1-n first second[, second]* [name]
+        todo [global options] create relation_n-1 first[, first]* second [name]
         todo [global options] create tasks task_name[, task_name]*
 
     COMMANDS
-        <default> - Makes a new task
-        contexts  - Make a new context
-        tasks     - Make a new task
+        <default>    - Makes a new task
+        contexts     - Make a new context
+        relation_1-1 - 
+        relation_1-n - 
+        relation_n-1 - 
+        tasks        - Make a new task
     """
     And the output should not contain "COMMAND OPTIONS"
 
   Scenario: Running list w/out subcommand performs list tasks by default
-    When I successfully run `todo list --required_flag=blah boo yay`
+    When I successfully run `todo list --required_flag=blah --required_flag2=bleh boo yay`
     Then the output should contain "list tasks: boo,yay"
 
   Scenario: Running list w/out subcommand or any arguments performs list tasks by default
-    When I successfully run `todo list --required_flag=blah`
+    When I successfully run `todo list --required_flag=blah --required_flag2=bleh`
     Then the output should contain "list tasks:"
 
   Scenario: Running chained commands works
@@ -479,3 +490,57 @@ Feature: The todo app has a nice user interface
         todo [global options] ls [command options] contexts [subcommand options]
         todo [global options] ls [command options] tasks [subcommand options]
     """
+
+  Scenario: We get a clear error message when a required argument is missing
+    Given a clean home directory
+    When I run `todo list`
+    Then the exit status should not be 0
+    And the stderr should contain "error: required_flag is required, required_flag2 is required"
+    And the output should contain:
+    """
+    NAME
+        list - List things, such as tasks or contexts
+
+    SYNOPSIS
+        todo [global options] list [command options] [tasks] [subcommand options]
+        todo [global options] list [command options] contexts [subcommand options]
+
+    DESCRIPTION
+        List a whole lot of things that you might be keeping track of in your
+        overall todo list.
+
+        This is your go-to place or finding all of the things that you might have
+        stored in your todo databases. 
+
+    COMMAND OPTIONS
+        -l, --[no-]long      - Show long form
+        --required_flag=arg  - (required, default: none)
+        --required_flag2=arg - (required, default: none)
+
+    COMMANDS
+        contexts - List contexts
+        tasks    - List tasks (default)
+    """
+
+  Scenario: Getting help on a root command with an arg_name outputs the argument description
+    When I run `todo help first`
+    And the stdout should contain:
+    """
+    NAME
+        first - 
+
+    SYNOPSIS
+        todo [global options] first [argument]
+    """
+
+  Scenario: Getting help on a root command with an arg outputs the argument description
+    When I run `todo help second`
+    And the stdout should contain:
+    """
+    NAME
+        second - 
+
+    SYNOPSIS
+        todo [global options] second [argument]
+    """
+

data/lib/gli.rb

@@ -13,6 +13,7 @@ require 'gli/exceptions.rb'
 require 'gli/flag.rb'
 require 'gli/options.rb'
 require 'gli/switch.rb'
+require 'gli/argument.rb'
 require 'gli/dsl.rb'
 require 'gli/version.rb'
 require 'gli/commands/help'

data/lib/gli/app_support.rb

@@ -210,7 +210,7 @@ module GLI
     def handle_exception(ex,command)
       if regular_error_handling?(ex)
         output_error_message(ex)
-        if ex.kind_of?(OptionParser::ParseError) || ex.kind_of?(BadCommandLine)
+        if ex.kind_of?(OptionParser::ParseError) || ex.kind_of?(BadCommandLine) || ex.kind_of?(RequestHelp)
           if commands[:help]
             command_for_help = command.nil? ? [] : command.name_for_help
             commands[:help].execute({},{},command_for_help)
@@ -220,7 +220,7 @@ module GLI
         stderr.puts "Custom error handler exited false, skipping normal error handling"
       end
 
-      raise ex if ENV['GLI_DEBUG'] == 'true'
+      raise ex if ENV['GLI_DEBUG'] == 'true' && !ex.kind_of?(RequestHelp)
 
       ex.extend(GLI::StandardException)
       ex.exit_code

data/lib/gli/argument.rb

@@ -0,0 +1,20 @@
+module GLI
+  class Argument #:nodoc:
+
+    attr_reader :name
+    attr_reader :options
+
+    def initialize(name,options = [])
+      @name = name
+      @options = options
+    end
+
+    def optional?
+      @options.include? :optional
+    end
+
+    def multiple?
+      @options.include? :multiple
+    end
+  end
+end

data/lib/gli/command.rb

@@ -49,6 +49,7 @@ module GLI
       super(options[:names],options[:description],options[:long_desc])
       @arguments_description = options[:arguments_name] || ''
       @arguments_options = Array(options[:arguments_options]).flatten
+      @arguments = options[:arguments] || []
       @skips_pre = options[:skips_pre]
       @skips_post = options[:skips_post]
       @skips_around = options[:skips_around]

data/lib/gli/command_support.rb

@@ -25,6 +25,10 @@ module GLI
       @arguments_options
     end
 
+    def arguments
+      @arguments
+    end
+
     # If true, this command doesn't want the pre block run before it executes
     def skips_pre 
       @skips_pre

data/lib/gli/commands/help_modules/arg_name_formatter.rb

@@ -3,7 +3,34 @@ module GLI
     module HelpModules
       # Handles wrapping text
       class ArgNameFormatter
-        def format(arguments_description,arguments_options)
+        def format(arguments_description,arguments_options,arguments)
+          # Select which format to use: argname or arguments
+          # Priority to old way: argname
+          desc = format_argname(arguments_description, arguments_options)
+          desc = format_arguments(arguments) if desc.strip == ''
+          desc
+        end
+
+        def format_arguments(arguments)
+          return '' if arguments.empty?
+          desc = ""
+
+          # Go through the arguments, building the description string
+          arguments.each do |arg|
+            arg_desc = "#{arg.name}"
+            if arg.optional?
+              arg_desc = "[#{arg_desc}]"
+            end
+            if arg.multiple?
+              arg_desc = "#{arg_desc}[, #{arg_desc}]*"
+            end
+            desc = desc + " " + arg_desc
+          end
+
+          desc
+        end
+
+        def format_argname(arguments_description,arguments_options)
           return '' if String(arguments_description).strip == ''
           desc = arguments_description
           if arguments_options.include? :optional

data/lib/gli/commands/help_modules/full_synopsis_formatter.rb

@@ -11,7 +11,7 @@ module GLI
         def synopses_for_command(command)
           synopses = []
           one_line_usage = basic_usage(command)
-          one_line_usage << command.arguments_description
+          one_line_usage << ArgNameFormatter.new.format(command.arguments_description,command.arguments_options,command.arguments).strip
           if command.commands.empty?
             synopses << one_line_usage
           else
@@ -73,7 +73,7 @@ module GLI
             usage << ' '
             usage << sub_options_doc
           end
-          arg_name_doc = ArgNameFormatter.new.format(sub.arguments_description,sub.arguments_options).strip
+          arg_name_doc = ArgNameFormatter.new.format(sub.arguments_description,sub.arguments_options,sub.arguments).strip
           if arg_name_doc.length > 0
             usage << ' '
             usage << arg_name_doc

data/lib/gli/dsl.rb

@@ -36,6 +36,26 @@ module GLI
       @next_arg_options = options
     end
 
+    # Describes one of the arguments of the next command
+    #
+    # +name+:: A String that *briefly* describes the argument given to the following command.
+    # +options+:: Symbol or array of symbols to annotate this argument.  This doesn't affect parsing, just
+    #             the help output.  Values recognized are:
+    #             +:optional+:: indicates this argument is optional; will format it with square brackets
+    #             +:multiple+:: indicates multiple values are accepted; will format appropriately
+    #
+    # Example:
+    #     arg :output
+    #     arg :input, :multiple
+    #     command :pack do ...
+    #
+    # Produces the synopsis:
+    #     app.rb [global options] pack output input[, input]*
+    def arg(name, options=[])
+      @next_arguments ||= []
+      @next_arguments << Argument.new(name, Array(options).flatten)
+    end
+
     # set the default value of the next flag or switch
     #
     # +val+:: The default value to be used for the following flag if the user doesn't specify one
@@ -152,6 +172,7 @@ module GLI
         :description => @next_desc,
         :arguments_name => @next_arg_name,
         :arguments_options => @next_arg_options,
+        :arguments => @next_arguments,
         :long_desc => @next_long_desc,
         :skips_pre => @skips_pre,
         :skips_post => @skips_post,
@@ -178,6 +199,7 @@ module GLI
         yield command
       end
       clear_nexts
+      @next_arguments = []
     end
     alias :c :command
 

data/lib/gli/exceptions.rb

@@ -5,6 +5,21 @@ module GLI
   module StandardException
     def exit_code; 1; end
   end
+
+  # Hack to request help from within a command
+  # Will *not* be rethrown when GLI_DEBUG is ON
+  class RequestHelp < StandardError
+    include StandardException
+    def exit_code; 0; end
+
+    # The command for which the argument was unknown
+    attr_reader :command_in_context
+
+    def initialize(command_in_context)
+      @command_in_context = command_in_context
+    end
+  end
+
   # Indicates that the command line invocation was bad
   class BadCommandLine < StandardError
     include StandardException
@@ -44,6 +59,17 @@ module GLI
     end
   end
 
+  class MissingRequiredArgumentsException < BadCommandLine
+    # The command for which the argument was unknown
+    attr_reader :command_in_context
+    # +message+:: the error message to show the user
+    # +command+:: the command we were using to parse command-specific options
+    def initialize(message,command)
+      super(message)
+      @command_in_context = command
+    end
+  end
+
   # Indicates the bad command line was an unknown command argument
   class UnknownCommandArgument < CommandException
   end

data/lib/gli/gli_option_parser.rb

@@ -37,23 +37,24 @@ module GLI
                        end
         parsing_result.command        = @command_finder.find_command(command_name)
         unless command_name == 'help'
-          verify_required_options!(@flags,parsing_result.global_options)
+          verify_required_options!(@flags, parsing_result.command, parsing_result.global_options)
         end
         parsing_result
       end
 
     protected
 
-      def verify_required_options!(flags,options)
+      def verify_required_options!(flags, command, options)
         missing_required_options = flags.values.
           select(&:required?).
           reject { |option|
             options[option.name] != nil
         }
         unless missing_required_options.empty?
-          raise BadCommandLine, missing_required_options.map { |option|
+          missing_required_options.sort!
+          raise MissingRequiredArgumentsException.new(missing_required_options.map { |option|
             "#{option.name} is required"
-          }.join(' ')
+          }.join(', '), command)
         end
       end
     end
@@ -86,7 +87,7 @@ module GLI
           command_finder                  = CommandFinder.new(command.commands,command.get_default_command)
           next_command_name               = arguments.shift
 
-          verify_required_options!(command.flags,parsed_command_options[command])
+          verify_required_options!(command.flags, command, parsed_command_options[command])
 
           begin
             command = command_finder.find_command(next_command_name)
@@ -138,7 +139,7 @@ module GLI
         subcommand,args                = find_subcommand(command,parsing_result.arguments)
         parsing_result.command         = subcommand
         parsing_result.arguments       = args
-        verify_required_options!(command.flags,parsing_result.command_options)
+        verify_required_options!(command.flags, parsing_result.command, parsing_result.command_options)
       end
 
     private

data/lib/gli/option_parser_factory.rb

@@ -71,7 +71,7 @@ module GLI
       unless help_args.empty?
         help_args << "Get help for #{command.name}"
         option_parser.on(*help_args) do
-          raise CommandException.new(nil,command,0)
+          raise RequestHelp.new(command)
         end
       end
     end

data/lib/gli/version.rb

@@ -1,5 +1,5 @@
 module GLI
   unless const_defined? :VERSION
-    VERSION = '2.10.0'
+    VERSION = '2.11.0'
   end
 end

data/test/apps/todo/bin/todo

@@ -35,7 +35,10 @@ version Todo::VERSION
 commands_from 'todo/commands'
 commands_from File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'todo_plugins', 'commands'))
 
+arg_name :argument, :optional
 command :first  do |c| c.action { |g,o,a| puts "first: #{a.join(',')}" } end
+
+arg :argument, :optional
 command :second do |c| c.action { |g,o,a| puts "second: #{a.join(',')}" } end
 
 command :chained         => [ :first, :second ]

data/test/apps/todo/lib/todo/commands/create.rb

@@ -2,6 +2,7 @@ desc "Create a new task or context"
 command [:create,:new] do |c|
   c.desc "Make a new task"
   c.arg_name 'task_name', :multiple
+  c.arg :should_ignore_this
   c.command :tasks do |tasks|
     tasks.action do |global,options,args|
       puts "#{args}"
@@ -9,6 +10,7 @@ command [:create,:new] do |c|
   end
 
   c.desc "Make a new context"
+  c.arg :should_ignore_this
   c.arg_name 'context_name', :optional
   c.command :contexts do |contexts|
     contexts.action do |global,options,args|
@@ -20,5 +22,32 @@ command [:create,:new] do |c|
   c.action do
     puts "default action"
   end
+
+  c.arg "first"
+  c.arg "second"
+  c.arg "name", :optional
+  c.command :"relation_1-1" do |remote|
+    remote.action do |global,options,args|
+      puts "relation: #{args}"
+    end
+  end
+
+  c.arg "first", :multiple
+  c.arg "second"
+  c.arg "name", :optional
+  c.command :"relation_n-1" do |remote|
+    remote.action do |global,options,args|
+      puts "relation: #{args}"
+    end
+  end
+
+  c.arg "first"
+  c.arg "second", :multiple
+  c.arg "name", :optional
+  c.command :"relation_1-n" do |remote|
+    remote.action do |global,options,args|
+      puts "relation: #{args}"
+    end
+  end
 end
 

data/test/apps/todo/lib/todo/commands/list.rb

@@ -15,6 +15,7 @@ command [:list] do |c|
   c.switch [:l,:long]
 
   c.flag :required_flag, :required => true
+  c.flag :required_flag2, :required => true
 
   c.desc "List tasks"
   c.long_desc %(

data/test/tc_gli.rb

@@ -84,6 +84,7 @@ class TC_testGLI < Clean::Test::TestCase
     assert_equal 64, @app.run(['foo']), "Expected exit status to be 64"
     assert  @fake_stderr.contained?(/flag is required/), @fake_stderr.strings.inspect
     assert  @fake_stderr.contained?(/other_flag is required/), @fake_stderr.strings.inspect
+    assert  @fake_stderr.contained?(/flag is required, other_flag is required/), @fake_stderr.strings.inspect
     assert !@called
 
     assert_equal 0, @app.run(['foo','--flag=bar','--other_flag=blah']), "Expected exit status to be 0 #{@fake_stderr.strings.join(',')}"
@@ -104,6 +105,7 @@ class TC_testGLI < Clean::Test::TestCase
     assert_equal 64, @app.run(['foo']), "Expected exit status to be 64"
     assert  @fake_stderr.contained?(/flag is required/), @fake_stderr.strings.inspect
     assert  @fake_stderr.contained?(/other_flag is required/), @fake_stderr.strings.inspect
+    assert  @fake_stderr.contained?(/flag is required, other_flag is required/), @fake_stderr.strings.inspect
     assert !@called
 
     assert_equal 0, @app.run(['--flag=bar','--other_flag=blah','foo']), "Expected exit status to be 0 #{@fake_stderr.strings.join(',')}"
@@ -663,6 +665,19 @@ class TC_testGLI < Clean::Test::TestCase
     assert_raises(GLI::CustomExit) { @app.run(['foo']) }
   end
 
+  def test_gli_help_does_not_raise_on_debug
+    ENV['GLI_DEBUG'] = 'true'
+
+    @app.reset
+    @app.command(:multiply) do |c|
+      c.action do |g,o,a|
+        # Nothing
+      end
+    end
+
+    assert_nothing_raised(GLI::CustomExit) { @app.run(['multiply', '--help']) }
+  end
+
   class ConvertMe
     attr_reader :value
     def initialize(value)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gli
 version: !ruby/object:Gem::Version
-  version: 2.10.0
+  version: 2.11.0
 platform: ruby
 authors:
 - David Copeland
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-22 00:00:00.000000000 Z
+date: 2014-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -174,6 +174,7 @@ files:
 - lib/gli.rb
 - lib/gli/app.rb
 - lib/gli/app_support.rb
+- lib/gli/argument.rb
 - lib/gli/command.rb
 - lib/gli/command_finder.rb
 - lib/gli/command_line_option.rb