gli 2.1.0 → 2.2.0

data/lib/gli/commands/help.rb

@@ -3,14 +3,27 @@ require 'gli/command'
 require 'gli/terminal'
 require 'gli/commands/help_modules/list_formatter'
 require 'gli/commands/help_modules/text_wrapper'
+require 'gli/commands/help_modules/no_wrapping_wrapper'
+require 'gli/commands/help_modules/tty_only_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'
+require 'gli/commands/help_modules/arg_name_formatter'
 
 module GLI
   module Commands
+    SORTERS = {
+      :manually => lambda { |list| list },
+      :alpha    => lambda { |list| list.sort },
+    }
+
+    WRAPPERS = {
+      :to_terminal => HelpModules::TextWrapper,
+      :never       => HelpModules::NoWrappingWrapper,
+      :tty_only    => HelpModules::TTYOnlyWrapper,
+    }
     # The help command used for the two-level interactive help system
     class Help < Command
       def initialize(app,output=$stdout,error=$stderr)
@@ -22,6 +35,9 @@ module GLI
               :skips_post => true,
               :skips_around => true)
         @app = app
+        @sorter = SORTERS[@app.help_sort_type]
+        @text_wrapping_class = WRAPPERS[@app.help_text_wrap_type]
+
         desc 'List commands one per line, to assist with shell completion'
         switch :c
 
@@ -38,12 +54,12 @@ module GLI
           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
+          out.puts HelpModules::GlobalHelpFormat.new(@app,@sorter,@text_wrapping_class).format
         else
           name = arguments.shift
           command = command_finder.find_command(name)
           unless command.nil?
-            out.puts HelpModules::CommandHelpFormat.new(command,@app,File.basename($0).to_s).format
+            out.puts HelpModules::CommandHelpFormat.new(command,@app,File.basename($0).to_s,@sorter,@text_wrapping_class).format
           end
         end
       end

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

@@ -0,0 +1,20 @@
+module GLI
+  module Commands
+    module HelpModules
+      # Handles wrapping text
+      class ArgNameFormatter
+        def format(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}]*"
+          end
+          " " + desc
+        end
+      end
+    end
+  end
+end

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

@@ -4,17 +4,19 @@ module GLI
   module Commands
     module HelpModules
       class CommandHelpFormat
-        def initialize(command,app,basic_invocation)
+        def initialize(command,app,basic_invocation,sorter,wrapper_class=TextWrapper)
           @basic_invocation = basic_invocation
           @app = app
           @command = command
+          @sorter = sorter
+          @wrapper_class = wrapper_class
         end
 
         def format
-          command_wrapper = TextWrapper.new(Terminal.instance.size[0],4 + @command.name.to_s.size + 3)
-          wrapper = TextWrapper.new(Terminal.instance.size[0],4)
+          command_wrapper = @wrapper_class.new(Terminal.instance.size[0],4 + @command.name.to_s.size + 3)
+          wrapper = @wrapper_class.new(Terminal.instance.size[0],4)
           flags_and_switches = Hash[@command.topmost_ancestor.flags.merge(@command.topmost_ancestor.switches).select { |_,option| option.associated_command == @command }]
-          options_description = OptionsFormatter.new(flags_and_switches).format
+          options_description = OptionsFormatter.new(flags_and_switches,@wrapper_class).format
           commands_description = format_subcommands(@command)
 
           synopses = []
@@ -72,21 +74,10 @@ COMMANDS
           else
             usage << sub.name.to_s
           end
-          usage << format_arg_name(sub)
+          usage << ArgNameFormatter.new.format(sub.arguments_description,sub.arguments_options)
           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
@@ -110,7 +101,7 @@ COMMANDS
         end
  
         def format_subcommands(command)
-          commands_array = command.commands.values.sort.map { |cmd| 
+          commands_array = @sorter.call(command.commands_declaration_order).map { |cmd| 
             if command.get_default_command == cmd.name
               [cmd.names,cmd.description + " (default)"] 
             else
@@ -120,7 +111,7 @@ COMMANDS
           if command.has_action?
             commands_array.unshift(["<default>",command.default_description])
           end
-          formatter = ListFormatter.new(commands_array)
+          formatter = ListFormatter.new(commands_array,@wrapper_class)
           StringIO.new.tap { |io| formatter.output(io) }.string
         end
 

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

@@ -4,21 +4,30 @@ module GLI
   module Commands
     module HelpModules
       class GlobalHelpFormat
-        def initialize(app)
+        def initialize(app,sorter,wrapper_class)
           @app = app
+          @sorter = sorter
+          @wrapper_class = wrapper_class
         end
 
         def format
           program_desc = @app.program_desc
+          program_long_desc = @app.program_long_desc
+          if program_long_desc
+            wrapper = @wrapper_class.new(Terminal.instance.size[0],4)
+            program_long_desc = "\n    #{wrapper.wrap(program_long_desc)}\n\n" if program_long_desc
+          else
+            program_long_desc = "\n"
+          end
 
-          command_formatter = ListFormatter.new(@app.commands.values.sort.reject(&:nodoc).map { |command|
+          command_formatter = ListFormatter.new(@sorter.call(@app.commands_declaration_order.reject(&:nodoc)).map { |command|
             [[command.name,Array(command.aliases)].flatten.join(', '),command.description]
-          })
+          }, @wrapper_class)
           stringio = StringIO.new
           command_formatter.output(stringio)
           commands = stringio.string
 
-          global_option_descriptions = OptionsFormatter.new(global_flags_and_switches).format
+          global_option_descriptions = OptionsFormatter.new(global_flags_and_switches,@wrapper_class).format
 
           GLOBAL_HELP.result(binding)
         end
@@ -27,7 +36,7 @@ module GLI
 
         GLOBAL_HELP = ERB.new(%q(NAME
     <%= File.basename($0) %> - <%= program_desc %>
-
+<%= program_long_desc %>
 SYNOPSIS
     <%= usage_string %>
 

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

@@ -3,15 +3,16 @@ module GLI
     module HelpModules
       # Given a list of two-element lists, formats on the terminal 
       class ListFormatter
-        def initialize(list)
+        def initialize(list,wrapper_class=TextWrapper)
           @list = list
+          @wrapper_class = wrapper_class
         end
 
         # Output the list to the output_device
         def output(output_device)
           return if @list.empty?
           max_width = @list.map { |_| _[0].length }.max
-          wrapper = TextWrapper.new(Terminal.instance.size[0],4 + max_width + 3)
+          wrapper = @wrapper_class.new(Terminal.instance.size[0],4 + max_width + 3)
           @list.each do |(name,description)|
             output_device.printf("    %-#{max_width}s - %s\n",name,wrapper.wrap(String(description).strip))
           end

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

@@ -0,0 +1,18 @@
+module GLI
+  module Commands
+    module HelpModules
+      # Formats text in one line, stripping newlines and NOT wrapping
+      class NoWrappingWrapper
+        # Args are ignored entirely; this keeps it consistent with the TextWrapper interface
+        def initialize(width,indent)
+        end
+
+        # Return a wrapped version of text, assuming that the first line has already been
+        # indented by @indent characters.  Resulting text does NOT have a newline in it.
+        def wrap(text)
+          return String(text).gsub(/\n+/,' ').strip
+        end
+      end
+    end
+  end
+end

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

@@ -2,8 +2,9 @@ module GLI
   module Commands
     module HelpModules
       class OptionsFormatter
-        def initialize(flags_and_switches)
+        def initialize(flags_and_switches,wrapper_class)
           @flags_and_switches = flags_and_switches
+          @wrapper_class = wrapper_class
         end
 
         def format
@@ -15,7 +16,7 @@ module GLI
             else
               [option_names_for_help_string(option),description_with_default(option)]
             end
-          })
+          },@wrapper_class)
           stringio = StringIO.new
           list_formatter.output(stringio)
           stringio.string
@@ -25,7 +26,7 @@ module GLI
 
         def description_with_default(option)
           if option.kind_of? Flag
-            String(option.description) + " (default: #{option.default_value || 'none'})"
+            String(option.description) + " (default: #{option.safe_default_value || 'none'})"
           else
             String(option.description)
           end

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

@@ -0,0 +1,23 @@
+module GLI
+  module Commands
+    module HelpModules
+      # Formats text in one line, stripping newlines and NOT wrapping
+      class TTYOnlyWrapper
+        # Args are ignored entirely; this keeps it consistent with the TextWrapper interface
+        def initialize(width,indent)
+          @proxy = if STDOUT.tty?
+                     TextWrapper.new(width,indent)
+                   else
+                     NoWrappingWrapper.new(width,indent)
+                   end
+        end
+
+        # Return a wrapped version of text, assuming that the first line has already been
+        # indented by @indent characters.  Resulting text does NOT have a newline in it.
+        def wrap(text)
+          @proxy.wrap(text)
+        end
+      end
+    end
+  end
+end

data/lib/gli/commands/rdoc_document_listener.rb

@@ -1,4 +1,5 @@
 require 'stringio'
+require 'gli/commands/help_modules/arg_name_formatter'
 module GLI
   module Commands
     class RdocDocumentListener
@@ -6,6 +7,7 @@ module GLI
       def initialize(global_options,options,arguments)
         @io = File.new(File.basename($0) + ".rdoc",'w')
         @nest = ''
+        @arg_name_formatter = GLI::Commands::HelpModules::ArgNameFormatter.new
       end
 
       def beginning
@@ -22,6 +24,11 @@ module GLI
         @io.puts
       end
 
+      def program_long_desc(desc)
+        @io.puts desc
+        @io.puts
+      end
+
       # Gives you the program version
       def version(version)
         @io.puts "v#{version}"
@@ -38,12 +45,12 @@ module GLI
 
       # Gives you a flag in the current context
       def flag(name,aliases,desc,long_desc,default_value,arg_name,must_match,type)
-        usage = "#{add_dashes(name)} #{arg_name || 'arg'}"
+        invocations = ([name] + Array(aliases)).map { |_| add_dashes(_) }.join('|')
+        usage = "#{invocations} #{arg_name || 'arg'}"
         @io.puts "#{@nest}=== #{usage}"
         @io.puts
         @io.puts String(desc).strip
         @io.puts
-        @io.puts "[Aliases] #{aliases.map { |_| add_dashes(_) }.join(',')}" unless aliases.empty?
         @io.puts "[Default Value] #{default_value || 'None'}"
         @io.puts "[Must Match] #{must_match.to_s}" unless must_match.nil?
         @io.puts String(long_desc).strip
@@ -56,11 +63,10 @@ module GLI
           name = "[no-]#{name}" if name.length > 1
           aliases = aliases.map { |_|  _.length > 1 ? "[no-]#{_}" : _ } 
         end
-        @io.puts "#{@nest}=== #{add_dashes(name)}"
+        invocations = ([name] + aliases).map { |_| add_dashes(_) }.join('|')
+        @io.puts "#{@nest}=== #{invocations}"
         @io.puts String(desc).strip
         @io.puts
-        @io.puts "[Aliases] #{aliases.map { |_| add_dashes(_) }.join(',')}\n" unless aliases.empty?
-        @io.puts
         @io.puts String(long_desc).strip
         @io.puts
       end
@@ -74,12 +80,10 @@ module GLI
       end
 
       # 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)
-        @io.puts "#{@nest}=== #{name} #{arg_name}"
+      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 String(desc).strip
         @io.puts 
-        @io.puts "[Aliases] #{aliases.join(',')}\n" unless aliases.empty?
-        @io.puts 
         @io.puts String(long_desc).strip
         @nest = "#{@nest}="
       end

data/lib/gli/dsl.rb

@@ -163,6 +163,8 @@ module GLI
         commands[command.name] = command
         yield command
       end
+      @commands_declaration_order ||= []
+      @commands_declaration_order << command
       clear_nexts
     end
     alias :c :command

data/lib/gli/flag.rb

@@ -15,20 +15,32 @@ module GLI
 
     # Creates a new option
     #
-    # names - Array of symbols or strings representing the names of this switch
-    # options - hash of options:
-    #           :desc - the short description
-    #           :long_desc - the long description
-    #           :default_value - the default value of this option
-    #           :arg_name - the name of the flag's argument, default is "arg"
-    #           :must_match - a regexp that the flag's value must match
-    #           :type - a class to convert the value to
+    # names:: Array of symbols or strings representing the names of this switch
+    # options:: hash of options:
+    #           :desc:: the short description
+    #           :long_desc:: the long description
+    #           :default_value:: the default value of this option
+    #           :arg_name:: the name of the flag's argument, default is "arg"
+    #           :must_match:: a regexp that the flag's value must match
+    #           :type:: a class to convert the value to
+    #           :mask:: if true, the default value of this flag will not be output in the help.
+    #                   This is useful for password flags where you might not want to show it
+    #                   on the command-line.
     def initialize(names,options)
       super(names,options)
       @argument_name = options[:arg_name] || "arg"
       @default_value = options[:default_value]
       @must_match = options[:must_match]
       @type = options[:type]
+      @mask = options[:mask]
+    end
+
+    def safe_default_value
+      if @mask
+        "********"
+      else
+        default_value
+      end
     end
 
     def arguments_for_option_parser

data/lib/gli/gli_option_parser.rb

@@ -53,6 +53,25 @@ module GLI
 
     def parse_command_options(option_parser_factory,command,args)
       option_parser,command_options = option_parser_factory.option_parser
+      help_args = %w(-h --help).reject { |_| command.has_option?(_) }
+
+      unless help_args.empty?
+        option_parser.on(*help_args) do
+          # We need to raise the help exception later in the process, after
+          # the command-line has been parsed, so we know what command
+          # to show help for.  Unfortunately, we can't just call #action
+          # on the command to override what to do, so...metaprogramming.
+          class << command
+            def execute(*help_args)
+              exception = BadCommandLine.new(nil)
+              class << exception
+                def exit_code; 0; end
+              end
+              raise exception
+            end
+          end
+        end
+      end
       option_parser.parse!(args)
       [command_options,args]
     rescue OptionParser::InvalidOption => ex

data/lib/gli/option_parser_factory.rb

@@ -23,9 +23,9 @@ module GLI
   private
 
     def self.setup_accepts(opts,accepts)
-      accepts.each do |object,block| 
-        opts.accept(object) do |arg_as_string| 
-          block.call(arg_as_string) 
+      accepts.each do |object,block|
+        opts.accept(object) do |arg_as_string|
+          block.call(arg_as_string)
         end
       end
     end

data/lib/gli/terminal.rb

@@ -74,7 +74,7 @@ module GLI
     #
     # Returns an Array of size two Ints representing the terminal width and height
     def size
-      SIZE_DETERMINERS.select { |predicate,ignore| predicate.call }.first[1].call
+      SIZE_DETERMINERS.select { |(predicate,ignore)| predicate.call }.first[1].call
     rescue Exception => ex
       raise ex if @unsafe
       Terminal.default_size