gli 2.0.0 → 2.1.0

data/README.rdoc

@@ -1,8 +1,6 @@
 = Git-Like Interface Command Line Parser
 
-<b>GLI2 is currently in Release Candidate, so this might change before the official release</b>
-
-The best way to make a "command-suite" command-line application (for the best way to make a
+GLI is the best way to make a "command-suite" command-line application, e.g. one like <tt>git</tt> (for the best way to make a
 simpler command-line application, check out methadone[http://www.github.com/davetron5000/methadone]).
 
 GLI allows you to make a very polished, easy-to-maintain command-line application without a lot

data/features/todo.feature

@@ -44,6 +44,47 @@ Feature: The todo app has a nice user interface
       | help      |
       | --version |
 
+  Scenario: Help completion mode
+    When I successfully run `todo help -c`
+    Then the output should contain:
+    """
+    ch2
+    chained
+    chained2
+    create
+    first
+    help
+    initconfig
+    list
+    ls
+    new
+    second
+    """
+
+  Scenario: Help completion mode for partial match
+    When I successfully run `todo help -c ch`
+    Then the output should contain:
+    """
+    ch2
+    chained
+    chained2
+    """
+
+  Scenario: Help completion mode for subcommands
+    When I successfully run `todo help -c list`
+    Then the output should contain:
+    """
+    contexts
+    tasks
+    """
+
+  Scenario: Help completion mode partial match for subcommands
+    When I successfully run `todo help -c list con`
+    Then the output should contain:
+    """
+    contexts
+    """
+
   Scenario: Getting Help for a top level command of todo
     When I successfully run `todo help list`
     Then the output should contain:
@@ -98,8 +139,8 @@ Feature: The todo app has a nice user interface
 
     SYNOPSIS
         todo [global options] create [command options] 
-        todo [global options] create [command options]  contexts
-        todo [global options] create [command options]  tasks
+        todo [global options] create [command options]  contexts [context_name]
+        todo [global options] create [command options]  tasks task_name[, task_name]*
 
     COMMANDS
         <default> - Makes a new task

data/lib/gli/app.rb

@@ -141,6 +141,14 @@ module GLI
       switch :version, :negatable => false
     end
 
+    # By default, GLI mutates the argument passed to it.  This is
+    # consistent with +OptionParser+, but be less than ideal.  Since
+    # that value, for scaffolded apps, is +ARGV+, you might want to
+    # refer to the entire command-line via +ARGV+ and thus not want it mutated.
+    def preserve_argv(preserve=true)
+      @preserve_argv = preserve
+    end
+
     # Call this with +true+ will cause the +global_options+ and
     # +options+ passed to your code to be wrapped in
     # Options, which is a subclass of +OpenStruct+ that adds

data/lib/gli/app_support.rb

@@ -37,12 +37,13 @@ module GLI
       @default_command
     end
 
-    # Runs whatever command is needed based on the arguments. 
+    # Runs whatever command is needed based on the arguments.
     #
     # +args+:: the command line ARGV array
     #
     # Returns a number that would be a reasonable exit code
     def run(args) #:nodoc:
+      args = args.dup if @preserve_argv
       command = nil
       begin
         override_defaults_based_on_config(parse_config)
@@ -169,7 +170,7 @@ module GLI
         stderr.puts error_message(ex) 
         if ex.kind_of?(OptionParser::ParseError) || ex.kind_of?(BadCommandLine)
           stderr.puts 
-          commands[:help] and commands[:help].execute([],[],command.nil? ? [] : [command.name.to_s])
+          commands[:help] and commands[:help].execute({},{},command.nil? ? [] : [command.name.to_s])
         end
       end
 

data/lib/gli/command.rb

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

data/lib/gli/command_support.rb

@@ -20,6 +20,10 @@ module GLI
       @arguments_description
     end
 
+    def arguments_options
+      @arguments_options
+    end
+
     # If true, this command doesn't want the pre block run before it executes
     def skips_pre 
       @skips_pre
@@ -76,11 +80,11 @@ module GLI
       end
     end
 
-    def arg_name(d)
+    def arg_name(d,options=[])
       if parent.kind_of? Command
-        parent.arg_name(d)
+        parent.arg_name(d,options)
       else
-        super(d)
+        super(d,options)
       end
     end
 

data/lib/gli/commands/help.rb

@@ -6,6 +6,8 @@ require 'gli/commands/help_modules/text_wrapper'
 require 'gli/commands/help_modules/options_formatter'
 require 'gli/commands/help_modules/global_help_format'
 require 'gli/commands/help_modules/command_help_format'
+require 'gli/commands/help_modules/help_completion_format'
+require 'gli/commands/help_modules/command_finder'
 
 module GLI
   module Commands
@@ -20,6 +22,9 @@ module GLI
               :skips_post => true,
               :skips_around => true)
         @app = app
+        desc 'List commands one per line, to assist with shell completion'
+        switch :c
+
         action do |global_options,options,arguments|
           show_help(global_options,options,arguments,output,error)
         end
@@ -28,37 +33,21 @@ module GLI
     private
 
       def show_help(global_options,options,arguments,out,error)
-        if arguments.empty?
+        command_finder = HelpModules::CommandFinder.new(@app,arguments,error)
+        if options[:c]
+          help_output = HelpModules::HelpCompletionFormat.new(@app,command_finder,arguments).format
+          out.puts help_output unless help_output.nil?
+        elsif arguments.empty? || options[:c]
           out.puts HelpModules::GlobalHelpFormat.new(@app).format
         else
           name = arguments.shift
-          command = find_command(name,@app)
-          return if unknown_command(command,name,error)
-          while !arguments.empty?
-            name = arguments.shift
-            command = find_command(name,command)
-            return if unknown_command(command,name,error)
+          command = command_finder.find_command(name)
+          unless command.nil?
+            out.puts HelpModules::CommandHelpFormat.new(command,@app,File.basename($0).to_s).format
           end
-          out.puts HelpModules::CommandHelpFormat.new(command,@app,File.basename($0).to_s).format
         end
       end
 
-      def unknown_command(command,name,error)
-        if command.nil?
-          error.puts "error: Unknown command '#{name}'.  Use 'gli help' for a list of commands."
-          true
-        else
-          false
-        end
-      end
-
-      def find_command(command_name,base)
-        base.commands.values.select { |command|
-          if [command.name,Array(command.aliases)].flatten.map(&:to_s).any? { |_| _ == command_name }
-            command
-          end
-        }.first
-      end
     end
   end
 end

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

@@ -0,0 +1,60 @@
+module GLI
+  module Commands
+    module HelpModules
+      # Finds commands from the application/command data structures
+      class CommandFinder
+
+        attr_reader :last_unknown_command
+        attr_reader :last_found_command
+        attr_writer :squelch_stderr
+
+        def initialize(app,arguments,error)
+          @app = app
+          @arguments = arguments
+          @error = error
+          @squelch_stderr = false
+          @last_unknown_command = nil
+        end
+
+        def find_command(name)
+          command = find_command_from_base(name,@app)
+          return if unknown_command?(command,name,@error)
+          @last_found_command = command
+          while !@arguments.empty?
+            name = @arguments.shift
+            command = find_command_from_base(name,command)
+            return if unknown_command?(command,name,@error)
+            @last_found_command = command
+          end
+          command
+        end
+
+      private
+
+        # Given the name of a command to find, and a base, either the app or another command, returns
+        # the command object or nil.
+        def find_command_from_base(command_name,base)
+          base.commands.values.select { |command|
+            if [command.name,Array(command.aliases)].flatten.map(&:to_s).any? { |_| _ == command_name }
+              command
+            end
+          }.first
+        end
+
+        # Checks if the return from find_command was unknown and, if so, prints an error
+        # for the user on the error device, returning true or false if the command was unknown.
+        def unknown_command?(command,name,error)
+          if command.nil?
+            @last_unknown_command = name
+            unless @squelch_stderr
+              error.puts "error: Unknown command '#{name}'.  Use 'gli help' for a list of commands."
+            end
+            true
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -72,8 +72,21 @@ COMMANDS
           else
             usage << sub.name.to_s
           end
+          usage << format_arg_name(sub)
           usage
         end
+
+        def format_arg_name(command)
+          return '' if String(command.arguments_description).strip == ''
+          desc = command.arguments_description
+          if command.arguments_options.include? :optional
+            desc = "[#{desc}]"
+          end
+          if command.arguments_options.include? :multiple
+            desc = "#{desc}[, #{desc}]*"
+          end
+          " " + desc
+        end
  
         def basic_usage(flags_and_switches)
           usage = @basic_invocation.dup

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

@@ -0,0 +1,31 @@
+module GLI
+  module Commands
+    module HelpModules
+      class HelpCompletionFormat
+        def initialize(app,command_finder,args)
+          @app = app
+          @command_finder = command_finder
+          @command_finder.squelch_stderr = true
+          @args = args
+        end
+
+        def format
+          name = @args.shift
+
+          base = @command_finder.find_command(name)
+          base = @command_finder.last_found_command if base.nil?
+          base = @app if base.nil?
+
+          prefix_to_match = @command_finder.last_unknown_command
+
+          base.commands.values.map { |command|
+            [command.name,command.aliases]
+          }.flatten.compact.map(&:to_s).sort.select { |command_name|
+            prefix_to_match.nil? || command_name =~ /^#{prefix_to_match}/
+          }.join("\n")
+        end
+
+      end
+    end
+  end
+end

data/lib/gli/dsl.rb

@@ -19,6 +19,10 @@ module GLI
     # this VERY short and, ideally, without any spaces (see Example).
     #
     # +name+:: A String that *briefly* describes the argument given to the following command or flag.
+    # +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:
     #     desc 'Set the filename'
@@ -27,7 +31,10 @@ module GLI
     #
     # Produces:
     #     -f, --filename=file_name      Set the filename
-    def arg_name(name); @next_arg_name = name; end
+    def arg_name(name,options=[])
+      @next_arg_name = name
+      @next_arg_options = options
+    end
 
     # set the default value of the next flag
     #
@@ -94,6 +101,7 @@ module GLI
     def clear_nexts # :nodoc:
       @next_desc = nil
       @next_arg_name = nil
+      @next_arg_options = nil
       @next_default_value = nil
       @next_long_desc = nil
     end
@@ -137,6 +145,7 @@ module GLI
       command_options = {
         :description => @next_desc,
         :arguments_name => @next_arg_name,
+        :arguments_options => @next_arg_options,
         :long_desc => @next_long_desc,
         :skips_pre => @skips_pre,
         :skips_post => @skips_post,

data/lib/gli/gli_option_parser.rb

@@ -23,7 +23,7 @@ module GLI
       remaining_args = nil
 
       global_options,command_name,args = parse_global_options(OptionParserFactory.new(@flags,@switches,@accepts), args)
-      @flags.each do |name,flag| 
+      @flags.each do |name,flag|
         global_options[name] = flag.default_value unless global_options[name]
       end
 
@@ -39,11 +39,11 @@ module GLI
                                                    command,
                                                    args)
 
-      command.flags.each do |name,flag| 
+      command.flags.each do |name,flag|
         command_options[name] = flag.default_value unless command_options[name]
       end
-      command.switches.each do |name,switch| 
-        command_options[name] = switch.default_value unless command_options[name] 
+      command.switches.each do |name,switch|
+        command_options[name] = switch.default_value unless command_options[name]
       end
 
       [global_options,command,command_options,args]

data/lib/gli/version.rb

@@ -1,5 +1,5 @@
 module GLI
   unless const_defined? :VERSION
-    VERSION = '2.0.0' #:nodoc:
+    VERSION = '2.1.0' #:nodoc:
   end
 end

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

@@ -1,6 +1,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.command :tasks do |tasks|
     tasks.action do |global,options,args|
       puts "#{args}"
@@ -8,6 +9,7 @@ command [:create,:new] do |c|
   end
 
   c.desc "Make a new context"
+  c.arg_name 'context_name', :optional
   c.command :contexts do |contexts|
     contexts.action do |global,options,args|
       puts "#{args}"
@@ -15,7 +17,7 @@ command [:create,:new] do |c|
   end
 
   c.default_desc "Makes a new task"
-  c.action do 
+  c.action do
     puts "default action"
   end
 end

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

@@ -21,11 +21,12 @@ command [:list] do |c|
   )
   c.command :tasks do |tasks|
     tasks.desc "blah blah crud x whatever"
-    tasks.flag [:x]
+    tasks.flag [:x], :must_match => Array
 
     tasks.flag :flag
 
     tasks.action do |global,options,args|
+      puts options[:x].inspect
       puts "list tasks: #{args.join(',')}"
     end
   end

data/test/tc_doc.rb

@@ -306,6 +306,9 @@ command: help
   desc: Shows a list of commands or help for one command
   long_desc: Gets help for the application or its commands. Can also list the commands in a way helpful to creating a bash-style completion function
   arg_name: command
+  switch: c
+    desc: List commands one per line, to assist with shell completion
+    negatable: true
   default_command: 
 end help
 default_command: 

data/test/tc_gli.rb

@@ -558,6 +558,37 @@ class TC_testGLI < Clean::Test::TestCase
     assert_equal 'crud',@baz.value
   end
 
+  def test_that_we_mutate_ARGV_by_default
+    @app.reset
+    @app.flag :f
+    @app.command :foo do |c|
+      c.action do |*args|
+      end
+    end
+
+    argv = %w(-f some_flag foo bar blah)
+
+    @app.run(argv)
+
+    assert_equal %w(bar blah),argv
+  end
+
+  def test_that_we_can_avoid_mutating_ARGV
+    @app.reset
+    @app.flag :f
+    @app.command :foo do |c|
+      c.action do |*args|
+      end
+    end
+    @app.preserve_argv
+
+    argv = %w(-f some_flag foo bar blah)
+
+    @app.run(argv)
+
+    assert_equal %w(-f some_flag foo bar blah),argv
+  end
+
   private
 
   def do_test_flag_create(object)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gli
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-14 00:00:00.000000000 Z
+date: 2012-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -213,12 +213,18 @@ files:
   bGliL2dsaS9jb21tYW5kcy9kb2MucmI=
 - !binary |-
   bGliL2dsaS9jb21tYW5kcy9oZWxwLnJi
+- !binary |-
+  bGliL2dsaS9jb21tYW5kcy9oZWxwX21vZHVsZXMvY29tbWFuZF9maW5kZXIu
+  cmI=
 - !binary |-
   bGliL2dsaS9jb21tYW5kcy9oZWxwX21vZHVsZXMvY29tbWFuZF9oZWxwX2Zv
   cm1hdC5yYg==
 - !binary |-
   bGliL2dsaS9jb21tYW5kcy9oZWxwX21vZHVsZXMvZ2xvYmFsX2hlbHBfZm9y
   bWF0LnJi
+- !binary |-
+  bGliL2dsaS9jb21tYW5kcy9oZWxwX21vZHVsZXMvaGVscF9jb21wbGV0aW9u
+  X2Zvcm1hdC5yYg==
 - !binary |-
   bGliL2dsaS9jb21tYW5kcy9oZWxwX21vZHVsZXMvbGlzdF9mb3JtYXR0ZXIu
   cmI=
@@ -329,7 +335,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1554108449042083355
+      hash: 2667779553904162412
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -338,7 +344,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1554108449042083355
+      hash: 2667779553904162412
 requirements: []
 rubyforge_project: gli
 rubygems_version: 1.8.24