gli 2.9.0 → 2.20.0

data/lib/gli/app_support.rb

@@ -26,8 +26,10 @@ module GLI
       @pre_block = false
       @post_block = false
       @default_command = :help
+      @autocomplete = false
       @around_block = nil
       @subcommand_option_handling_strategy = :legacy
+      @argument_handling_strategy = :loose
       clear_nexts
     end
 
@@ -67,8 +69,10 @@ module GLI
                                                 flags,
                                                 switches,
                                                 accepts,
-                                                @default_command,
-                                                self.subcommand_option_handling_strategy)
+                                                :default_command => @default_command,
+                                                :autocomplete => autocomplete,
+                                                :subcommand_option_handling_strategy => subcommand_option_handling_strategy,
+                                                :argument_handling_strategy => argument_handling_strategy)
 
         parsing_result = gli_option_parser.parse_options(args)
         parsing_result.convert_to_openstruct! if @use_openstruct
@@ -197,20 +201,28 @@ module GLI
 
     def override_default(tokens,config)
       tokens.each do |name,token|
-        token.default_value=config[name] if config[name]
+        token.default_value=config[name] unless config[name].nil?
       end
     end
 
+    def argument_handling_strategy
+      @argument_handling_strategy || :loose
+    end
+
     def subcommand_option_handling_strategy
       @subcommand_option_handling_strategy || :legacy
     end
 
+    def autocomplete
+      @autocomplete.nil? ? true : @autocomplete
+    end
+
   private
 
     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 +232,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

@@ -30,8 +30,16 @@ module GLI
     include DSL
     include CommandSupport
 
-    # Key in an options hash to find the parent's parsed options
-    PARENT = Object.new 
+    class ParentKey
+      def to_sym
+        "__parent__".to_sym
+      end
+    end
+
+    # Key in an options hash to find the parent's parsed options.  Note that if you are
+    # using openstruct, e.g. via `use_openstruct true` in your app setup, you will need
+    # to use the method `__parent__` to access parent parsed options.
+    PARENT = ParentKey.new
 
     # Create a new command.
     #
@@ -44,19 +52,36 @@ module GLI
     #           +skips_pre+:: if true, this command advertises that it doesn't want the pre block called first
     #           +skips_post+:: if true, this command advertises that it doesn't want the post block called after it
     #           +skips_around+:: if true, this command advertises that it doesn't want the around block called
+    #           +hide_commands_without_desc+:: if true and there isn't a description the command is not going to be shown in the help
+    #           +examples+:: An array of Hashes, where each hash must have the key +:example+ mapping to a string, and may optionally have the key +:desc+
+    #                        that documents that example.
     def initialize(options)
       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]
+      @hide_commands_without_desc = options[:hide_commands_without_desc]
       @commands_declaration_order = []
       @flags_declaration_order = []
       @switches_declaration_order = []
+      @examples = options[:examples] || []
       clear_nexts
     end
 
+    # Specify an example invocation.
+    #
+    # example_invocation:: test of a complete command-line invocation you want to show
+    # options:: refine the example:
+    #           +:desc+:: A description of the example to be shown with it (optional)
+    def example(example_invocation,options = {})
+      @examples << {
+        example: example_invocation
+      }.merge(options)
+    end
+
     # Set the default command if this command has subcommands and the user doesn't 
     # provide a subcommand when invoking THIS command.  When nil, this will show an error and the help
     # for this command; when set, the command with this name will be executed.

data/lib/gli/command_finder.rb

@@ -1,40 +1,57 @@
 module GLI
   class CommandFinder
-    # Initialize a finder on the given list of commands, using default_command as the default if none found
-    def initialize(commands,default_command)
-      @default_command = default_command
-      @names_to_commands = {}
-      commands.each do |command_name,command|
-        @names_to_commands[command_name.to_s] = command
-        Array(command.aliases).each do |command_alias|
-          @names_to_commands[command_alias.to_s] = command
-        end
-      end
+    attr_accessor :options
+
+    DEFAULT_OPTIONS = {
+      :default_command => nil,
+      :autocomplete    => true
+    }
+
+    def initialize(commands, options = {})
+      self.options = DEFAULT_OPTIONS.merge(options)
+      self.commands_with_aliases = expand_with_aliases(commands)
     end
 
-    # Finds the command with the given name, allowing for partial matches.  Returns the command named by
-    # the default command if no command with +name+ matched
     def find_command(name)
-      name ||= @default_command
-
-      raise UnknownCommand.new("No command name given nor default available") if String(name).strip == ''
+      name = String(name || options[:default_command]).strip
+      raise UnknownCommand.new("No command name given nor default available") if name == ''
 
-      command_found = @names_to_commands.fetch(name.to_s) do |command_to_match|
-        find_command_by_partial_name(@names_to_commands, command_to_match)
-      end
-      if Array(command_found).empty?
-        raise UnknownCommand.new("Unknown command '#{name}'")
-      elsif command_found.kind_of? Array
-        raise AmbiguousCommand.new("Ambiguous command '#{name}'. It matches #{command_found.sort.join(',')}")
+      command_found = commands_with_aliases.fetch(name) do |command_to_match|
+        if options[:autocomplete]
+          found_match = find_command_by_partial_name(commands_with_aliases, command_to_match)
+          if found_match.kind_of? GLI::Command
+            if ENV["GLI_DEBUG"] == 'true'
+              $stderr.puts "Using '#{name}' as it's is short for #{found_match.name}."
+              $stderr.puts "Set autocomplete false for any command you don't want matched like this"
+            end
+          elsif found_match.kind_of?(Array) && !found_match.empty?
+            raise AmbiguousCommand.new("Ambiguous command '#{name}'. It matches #{found_match.sort.join(',')}")
+          end
+          found_match
+        end
       end
+
+      raise UnknownCommand.new("Unknown command '#{name}'") if Array(command_found).empty?
       command_found
     end
 
   private
+    attr_accessor :commands_with_aliases
+
+    def expand_with_aliases(commands)
+      expanded = {}
+      commands.each do |command_name, command|
+        expanded[command_name.to_s] = command
+        Array(command.aliases).each do |command_alias|
+          expanded[command_alias.to_s] = command
+        end
+      end
+      expanded
+    end
 
-    def find_command_by_partial_name(names_to_commands, command_to_match)
-      partial_matches = names_to_commands.keys.select { |command_name| command_name =~ /^#{command_to_match}/ }
-      return names_to_commands[partial_matches[0]] if partial_matches.size == 1
+    def find_command_by_partial_name(commands_with_aliases, command_to_match)
+      partial_matches = commands_with_aliases.keys.select { |command_name| command_name =~ /^#{command_to_match}/ }
+      return commands_with_aliases[partial_matches[0]] if partial_matches.size == 1
       partial_matches
     end
   end

data/lib/gli/command_support.rb

@@ -11,8 +11,9 @@ module GLI
     end
 
     # Return true to avoid including this command in your help strings
+    # Will honor the hide_commands_without_desc flag
     def nodoc
-      false
+      @hide_commands_without_desc and description.nil?
     end
 
     # Return the arguments description
@@ -24,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
@@ -44,6 +49,11 @@ module GLI
       all_forms
     end
 
+    # Returns the array of examples
+    def examples
+      @examples
+    end
+
     # Get an array of commands, ordered by when they were declared
     def commands_declaration_order # :nodoc:
       @commands_declaration_order
@@ -156,12 +166,8 @@ module GLI
 
     def generate_error_action(arguments)
       lambda { |global_options,options,arguments|
-        if am_subcommand?
-          if arguments.size > 0
-            raise UnknownCommand,"Unknown command '#{arguments[0]}'"
-          else
-            raise BadCommandLine,"Command '#{name}' requires a subcommand"
-          end
+        if am_subcommand? && arguments.size > 0
+          raise UnknownCommand,"Unknown command '#{arguments[0]}'"
         elsif have_subcommands?
           raise BadCommandLine,"Command '#{name}' requires a subcommand #{self.commands.keys.join(',')}"
         else

data/lib/gli/commands/doc.rb

@@ -4,7 +4,7 @@ module GLI
     # about your app, so as to create documentation in whatever format you want
     class Doc < Command
       FORMATS = {
-        'rdoc' => GLI::Commands::RdocDocumentListener,
+        'rdoc' => GLI::Commands::RdocDocumentListener
       }
       # Create the Doc generator based on the GLI app passed in
       def initialize(app)
@@ -139,7 +139,7 @@ module GLI
     private
 
       def format_class(format_name)
-        FORMATS.fetch(format_name) { 
+        FORMATS.fetch(format_name) {
           begin
             return format_name.split(/::/).reduce(Kernel) { |context,part| context.const_get(part) }
           rescue => ex
@@ -168,8 +168,14 @@ module GLI
                         command.description,
                         command.long_description,
                         command.arguments_description]
-        if document_listener.method(:command).arity == 6
+        if document_listener.method(:command).arity >= 6
           command_args << command.arguments_options
+          if document_listener.method(:command).arity >= 7
+            command_args << command.arguments
+          end
+          if document_listener.method(:command).arity >= 8
+            command_args << command.examples
+          end
         end
         document_listener.command(*command_args)
       end

data/lib/gli/commands/help.rb

@@ -59,7 +59,8 @@ module GLI
         super(:names => :help,
               :description => 'Shows a list of commands or help for one command',
               :arguments_name => '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')
+              :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',
+              :arguments => [Argument.new(:command_name, [:multiple, :optional])])
         @app = app
         @parent = app
         @sorter = SORTERS[@app.help_sort_type]

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

@@ -3,14 +3,41 @@ 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}..."
+            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
             desc = "[#{desc}]"
           end
           if arguments_options.include? :multiple
-            desc = "#{desc}[, #{desc}]*"
+            desc = "#{desc}..."
           end
           " " + desc
         end

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

@@ -18,6 +18,7 @@ module GLI
           
           options_description  = OptionsFormatter.new(flags_and_switches(@command,@app),@sorter,@wrapper_class).format
           commands_description = format_subcommands(@command)
+          command_examples = format_examples(@command)
 
           synopses = @synopsis_formatter.synopses_for_command(@command)
           COMMAND_HELP.result(binding)
@@ -45,7 +46,14 @@ COMMAND OPTIONS
 
 COMMANDS
 <%= commands_description %>
-<% end %>),nil,'<>')
+<% end %>
+<% unless @command.examples.empty? %>
+
+<%= @command.examples.size == 1 ? 'EXAMPLE' : 'EXAMPLES' %>
+
+
+<%= command_examples %>
+<% end %>))
 
 
         def flags_and_switches(command,app)
@@ -76,6 +84,16 @@ COMMANDS
           formatter = ListFormatter.new(commands_array,@wrapper_class)
           StringIO.new.tap { |io| formatter.output(io) }.string
         end
+
+        def format_examples(command)
+          command.examples.map {|example|
+            string = ""
+            if example[:desc]
+              string << "    # #{example[:desc]}\n"
+            end
+            string << "    #{example.fetch(:example)}\n"
+          }.join("\n")
+        end
       end
     end
   end

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
@@ -27,10 +27,11 @@ module GLI
 
         def sub_options_doc(sub_options)
           sub_options_doc = sub_options.map { |_,option| 
-            option.names_and_aliases.map { |name| 
+            doc = option.names_and_aliases.map { |name|
               CommandLineOption.name_as_string(name,false) + (option.kind_of?(Flag) ? " #{option.argument_name }" : '')
             }.join('|')
-          }.map { |invocations| "[#{invocations}]" }.sort.join(' ').strip
+            option.required?? doc : "[#{doc}]"
+          }.sort.join(' ').strip
         end
 
       private
@@ -73,7 +74,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/commands/help_modules/global_help_format.rb

@@ -51,7 +51,7 @@ GLOBAL OPTIONS
 
 <% end %>
 COMMANDS
-<%= commands %>),nil,'<>')
+<%= commands %>))
 
         def global_flags_and_switches
           @app.flags_declaration_order + @app.switches_declaration_order

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

@@ -24,12 +24,10 @@ module GLI
 
         def description_with_default(option)
           if option.kind_of? Flag
-            required = if option.required?
-                         'required, '
-                       else
-                         ''
-                       end
-            String(option.description) + " (#{required}default: #{option.safe_default_value || 'none'})"
+            required = option.required? ? 'required, ' : ''
+            multiple = option.multiple? ? 'may be used more than once, ' : ''
+
+            String(option.description) + " (#{required}#{multiple}default: #{option.safe_default_value || 'none'})"
           else
             String(option.description) +  (option.default_value ?  " (default: enabled)" : "")
           end

data/lib/gli/commands/initconfig.rb

@@ -35,12 +35,9 @@ module GLI
   private
 
     def create_config(global_options,options,arguments)
-      config = Hash[global_options.map { |option_name,option_value|
-        if option_value.kind_of?(String) && option_value.respond_to?(:force_encoding)
-          [option_name,option_value.force_encoding("utf-8")]
-        else
-          [option_name,option_value]
-        end
+      config = Hash[(@app_switches.keys + @app_flags.keys).map { |option_name|
+        option_value = global_options[option_name]
+        [option_name,option_value]
       }]
       config[COMMANDS_KEY] = {}
       @app_commands.each do |name,command|

data/lib/gli/commands/rdoc_document_listener.rb

@@ -5,6 +5,7 @@ module GLI
     class RdocDocumentListener
 
       def initialize(global_options,options,arguments,app)
+        @app = app
         @io = File.new("#{app.exe_name}.rdoc",'w')
         @nest = ''
         @arg_name_formatter = GLI::Commands::HelpModules::ArgNameFormatter.new
@@ -81,7 +82,7 @@ module GLI
 
       # Gives you a command in the current context and creates a new context of this command
       def command(name,aliases,desc,long_desc,arg_name,arg_options)
-        @io.puts "#{@nest}=== Command: <tt>#{([name] + aliases).join('|')} #{@arg_name_formatter.format(arg_name,arg_options)}</tt>"
+        @io.puts "#{@nest}=== Command: <tt>#{([name] + aliases).join('|')} #{@arg_name_formatter.format(arg_name,arg_options,[])}</tt>"
         @io.puts String(desc).strip
         @io.puts 
         @io.puts String(long_desc).strip