gli 2.1.0 → 2.2.0

data/features/gli_executable.feature

@@ -88,5 +88,3 @@ Feature: The GLI executable works as intended
     Given the file "gli.rdoc" doesn't exist
     When I run `gli _doc`
     Then a file named "gli.rdoc" should exist
-    
-     

data/features/step_definitions/todo_steps.rb

@@ -2,6 +2,17 @@ Given /^todo's bin directory is in my path/ do
   add_to_path(File.expand_path(File.join(File.dirname(__FILE__),'..','..','test','apps','todo','bin')))
 end
 
+Given /^the todo app is coded to avoid sorted help commands$/ do
+  ENV['TODO_SORT_HELP'] = 'manually'
+end
+
+Given /^the todo app is coded to avoid wrapping text$/ do
+  ENV['TODO_WRAP_HELP_TEXT'] = 'never'
+end
+
+Given /^the todo app is coded to wrap text only for tty$/ do
+  ENV['TODO_WRAP_HELP_TEXT'] = 'tty_only'
+end
 
 Given /^a clean home directory$/ do
   FileUtils.rm_rf File.join(ENV['HOME'],'gli_test_todo.rc')

data/features/support/env.rb

@@ -24,6 +24,7 @@ Before do
   FileUtils.rm_rf new_home
   FileUtils.mkdir new_home
   ENV['HOME'] = new_home
+  FileUtils.cp 'gli.rdoc','gli.rdoc.orig'
 end
 
 After do |scenario|
@@ -34,6 +35,9 @@ After do |scenario|
   end
   ENV['PATH'] = @original_path.join(File::PATH_SEPARATOR)
   ENV['HOME'] = @original_home
+  ENV['TODO_SORT_HELP'] = nil
+  ENV['TODO_WRAP_HELP_TEXT'] = nil
+  FileUtils.mv 'gli.rdoc.orig','gli.rdoc'
 end
 
 def add_to_path(dir)

data/features/todo.feature

@@ -15,6 +15,9 @@ Feature: The todo app has a nice user interface
     NAME
         todo - Manages tasks
 
+        A test program that has a sophisticated UI that can be used to exercise a
+        lot of GLI's power
+
     SYNOPSIS
         todo [global options] command [command options] [arguments...]
 
@@ -85,8 +88,44 @@ Feature: The todo app has a nice user interface
     contexts
     """
 
-  Scenario: Getting Help for a top level command of todo
-    When I successfully run `todo help list`
+  Scenario: Getting Help with self-ordered commands
+    Given the todo app is coded to avoid sorted help commands
+    When I successfully run `todo help`
+    Then the output should contain:
+    """
+    NAME
+        todo - Manages tasks
+
+        A test program that has a sophisticated UI that can be used to exercise a
+        lot of GLI's power
+
+    SYNOPSIS
+        todo [global options] command [command options] [arguments...]
+
+    VERSION
+        0.0.1
+
+    GLOBAL OPTIONS
+        --flag=arg         - (default: none)
+        --help             - Show this message
+        --[no-]otherswitch - 
+        --[no-]switch      - 
+        --version          - 
+
+    COMMANDS
+        help          - Shows a list of commands or help for one command
+        initconfig    - Initialize the config file using current global options
+        create, new   - Create a new task or context
+        list          - List things, such as tasks or contexts
+        ls            - LS things, such as tasks or contexts
+        first         - 
+        second        - 
+        chained       - 
+        chained2, ch2 - 
+    """
+
+  Scenario Outline: Getting Help for a top level command of todo
+    When I successfully run `todo <help_invocation>`
     Then the output should contain:
     """
     NAME
@@ -111,6 +150,59 @@ Feature: The todo app has a nice user interface
         tasks    - List tasks (default)
     """
 
+    Examples:
+      | help_invocation |
+      | help list       |
+      | list -h         |
+      | list --help     |
+
+
+  Scenario: Getting Help without wrapping
+    Given the todo app is coded to avoid wrapping text
+    When I successfully run `todo help list`
+    Then the output should contain:
+    """
+    NAME
+        list - List things, such as tasks or contexts
+
+    SYNOPSIS
+        todo [global options] list [command options] [--flag arg] [-x arg] [tasks]
+        todo [global options] list [command options] [--otherflag arg] [-b] [-f|--foobar] contexts
+
+    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
+
+    COMMANDS
+        contexts - List contexts
+        tasks    - List tasks (default)
+    """
+
+  Scenario: Getting Help without wrapping
+    Given the todo app is coded to wrap text only for tty
+    When I successfully run `todo help list`
+    Then the output should contain:
+    """
+    NAME
+        list - List things, such as tasks or contexts
+
+    SYNOPSIS
+        todo [global options] list [command options] [--flag arg] [-x arg] [tasks]
+        todo [global options] list [command options] [--otherflag arg] [-b] [-f|--foobar] contexts
+
+    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
+
+    COMMANDS
+        contexts - List contexts
+        tasks    - List tasks (default)
+    """
+
   Scenario: Getting Help for a sub command of todo list
     When I successfully run `todo help list tasks`
     Then the output should contain:

data/gli.gemspec

@@ -29,5 +29,6 @@ spec = Gem::Specification.new do |s|
   s.add_development_dependency('clean_test')
   s.add_development_dependency('aruba')
   s.add_development_dependency('sdoc')
+  s.add_development_dependency('faker','1.0.0')
 end
 

data/gli.rdoc

@@ -1,13 +1,12 @@
 == gli - create scaffolding for a GLI-powered application
 
-v2.0.0.rc8
+v2.1.0
 
 === Global Options
-=== -r arg
+=== -r|--root arg
 
 Root dir of project
 
-[Aliases] --root
 [Default Value] .
 This is the directory where the project''s directory will be made, so if you 
 specify a project name ''foo'' and the root dir of ''.'', the directory 
@@ -18,46 +17,43 @@ Show this message
 
 
 
-
 === -n
 Dry run; dont change the disk
 
 
 
-
 === -v
 Be verbose
 
 
 
-
 === --version
 
 
 
 
-
 === Commands
-==== help command
+==== Command: <tt>help  command</tt>
 Shows a list of commands or help for one command
 
-
 Gets help for the application or its commands. Can also list the commands in a way helpful to creating a bash-style completion function
-==== init project_name [command[ command]*]
-Create a new GLI-based project
+===== Options
+===== -c
+List commands one per line, to assist with shell completion
 
-[Aliases] scaffold
+
+
+==== Command: <tt>init|scaffold  project_name [command[ command]*]</tt>
+Create a new GLI-based project
 
 This will create a scaffold command line project that uses GLI
 for command line processing.  Specifically, this will create
 an executable ready to go, as well as a lib and test directory, all
 inside the directory named for your project
 ===== Options
-===== -e
+===== -e|--[no-]ext
 Create an ext dir
 
-[Aliases] --[no-]ext
-
 
 
 ===== --[no-]force
@@ -65,16 +61,13 @@ Overwrite/ignore existing files and directories
 
 
 
-
 ===== --notest
 Do not create a test or features dir
 
 
 
-
 ===== --[no-]rvmrc
 Create an .rvmrc based on your current RVM setup
 
 
 
-

data/lib/gli/app.rb

@@ -23,7 +23,7 @@ module GLI
       $LOAD_PATH.each do |load_path|
         commands_path = File.join(load_path,path)
         if File.exists? commands_path
-          Dir.entries(commands_path).each do |entry|
+          Dir.entries(commands_path).sort.each do |entry|
             file = File.join(commands_path,entry)
             if file =~ /\.rb$/
               require file
@@ -44,6 +44,17 @@ module GLI
       @program_desc
     end
 
+    # Provide a longer description of the program.  This can be as long as needed, and use double-newlines
+    # for paragraphs.  This will show up in the help output.
+    #
+    # description:: A String for the description
+    def program_long_desc(description=nil)
+      if description
+        @program_long_desc = description
+      end
+      @program_long_desc
+    end
+
     # Use this if the following command should not have the pre block executed.
     # By default, the pre block is executed before each command and can result in
     # aborting the call.  Using this will avoid that behavior for the following command
@@ -77,6 +88,7 @@ module GLI
         @config_file = File.join(File.expand_path(ENV['HOME']),filename)
       end
       commands[:initconfig] = InitConfig.new(@config_file,commands,flags,switches)
+      @commands_declaration_order << commands[:initconfig]
       @config_file
     end
 
@@ -195,8 +207,8 @@ module GLI
 
     # Exit now, showing the user help for the command they executed.  Use #exit_now! to just show the error message
     #
-    # message:: message to indicate how the user has messed up the CLI invocation
-    def help_now!(message)
+    # message:: message to indicate how the user has messed up the CLI invocation or nil to just simply show help
+    def help_now!(message=nil)
       exception = OptionParser::ParseError.new(message)
       class << exception
         def exit_code; 64; end
@@ -204,6 +216,25 @@ module GLI
       raise exception
     end
 
+    # Control how help commands are sorted.  By default, the commands are sorted alphabetically.
+    #
+    # sort_type:: How you want help commands sorted:
+    #             +:manually+:: help commands are ordered in the order declared.
+    #             +:alpha+:: sort alphabetically (default)
+    def sort_help(sort_type)
+      @help_sort_type = sort_type
+    end
+
+    # Set how help text is wrapped.
+    #
+    # wrap_type:: Symbol indicating how you'd like text wrapped:
+    #             +:to_terminal+:: Wrap text based on the width of the terminal (default)
+    #             +:never+:: Do not wrap text at all.  This will bring all help content onto one line, removing any newlines
+    #             +:tty_only+:: Wrap like +:to_terminal+ if this output is going to a TTY, otherwise don't wrap (like +:never+)
+    def wrap_help_text(wrap_type)
+      @help_text_wrap_type = wrap_type
+    end
+
     def program_name(override=nil) #:nodoc:
       warn "#program_name has been deprecated"
     end

data/lib/gli/app_support.rb

@@ -15,6 +15,7 @@ module GLI
       switches.clear
       flags.clear
       @commands = nil
+      @commands_declaration_order = []
       @version = nil
       @config_file = nil
       @use_openstruct = false
@@ -27,8 +28,13 @@ module GLI
       clear_nexts
     end
 
+    # Get an array of commands, ordered by when they were declared
+    def commands_declaration_order # :nodoc:
+      @commands_declaration_order
+    end
+
     # Get the version string
-    def version_string #:nodoc
+    def version_string #:nodoc:
       @version
     end
 
@@ -119,7 +125,13 @@ module GLI
     end
 
     def commands # :nodoc:
-      @commands ||= { :help => GLI::Commands::Help.new(self), :_doc => GLI::Commands::Doc.new(self) }
+      if !@commands
+        @commands = { :help => GLI::Commands::Help.new(self), :_doc => GLI::Commands::Doc.new(self) }
+        @commands_declaration_order ||= []
+        @commands_declaration_order << @commands[:help]
+        @commands_declaration_order << @commands[:_doc]
+      end
+      @commands
     end
 
     def pre_block
@@ -137,6 +149,14 @@ module GLI
       @around_blocks || []
     end
 
+    def help_sort_type
+      @help_sort_type || :alpha
+    end
+
+    def help_text_wrap_type
+      @help_text_wrap_type || :to_terminal
+    end
+
     # Sets the default values for flags based on the configuration
     def override_defaults_based_on_config(config)
       override_default(flags,config)
@@ -167,9 +187,8 @@ module GLI
 
     def handle_exception(ex,command)
       if regular_error_handling?(ex)
-        stderr.puts error_message(ex) 
+        output_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])
         end
       end
@@ -180,6 +199,17 @@ module GLI
       ex.exit_code
     end
 
+    def output_error_message(ex)
+      stderr.puts error_message(ex) unless no_message_given?(ex)
+      if ex.kind_of?(OptionParser::ParseError) || ex.kind_of?(BadCommandLine)
+        stderr.puts unless no_message_given?(ex)
+      end
+    end
+
+    def no_message_given?(ex)
+      ex.message == ex.class.name
+    end
+
     # Possibly returns a copy of the passed-in Hash as an instance of GLI::Option.
     # By default, it will *not*. However by putting <tt>use_openstruct true</tt>
     # in your CLI definition, it will

data/lib/gli/command.rb

@@ -50,6 +50,7 @@ module GLI
       @skips_pre = options[:skips_pre]
       @skips_post = options[:skips_post]
       @skips_around = options[:skips_around]
+      @commands_declaration_order = []
       clear_nexts
     end
 
@@ -132,6 +133,13 @@ module GLI
       @default_desc = desc
     end
 
+    # Returns true if this command has the given option defined
+    def has_option?(option) #:nodoc:
+      option = option.gsub(/^\-+/,'')
+      ((flags.values.map { |_| [_.name,_.aliases] }) + 
+       (switches.values.map { |_| [_.name,_.aliases] })).flatten.map(&:to_s).include?(option)
+    end
+
     def self.name_as_string(name,negatable=false) #:nodoc:
       name.to_s
     end

data/lib/gli/command_support.rb

@@ -44,6 +44,11 @@ module GLI
       all_forms
     end
 
+    # Get an array of commands, ordered by when they were declared
+    def commands_declaration_order # :nodoc:
+      @commands_declaration_order
+    end
+
     def flag(*names)
       new_flag = if parent.kind_of? Command
                    parent.flag(*names)

data/lib/gli/commands/doc.rb

@@ -32,7 +32,8 @@ module GLI
       # Generates documentation using the listener
       def document(document_listener)
         document_listener.beginning
-        document_listener.program_desc(@app.program_desc)
+        document_listener.program_desc(@app.program_desc) unless @app.program_desc.nil?
+        document_listener.program_long_desc(@app.program_long_desc) unless @app.program_long_desc.nil?
         document_listener.version(@app.version_string)
         if any_options?(@app)
           document_listener.options 
@@ -66,6 +67,11 @@ module GLI
           abstract!
         end
 
+        # Gives you the program long description
+        def program_long_desc(desc)
+          abstract!
+        end
+
         # Gives you the program version
         def version(version)
           abstract!
@@ -107,7 +113,7 @@ 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)
+        def command(name,aliases,desc,long_desc,arg_name,arg_options)
           abstract!
         end
 
@@ -136,11 +142,7 @@ module GLI
 
       def document_commands(document_listener,context)
         context.commands.values.reject {|_| _.nodoc }.sort(&by_name).each do |command|
-          document_listener.command(command.name,
-                                    Array(command.aliases),
-                                    command.description,
-                                    command.long_description,
-                                    command.arguments_description)
+          call_command_method_being_backwards_compatible(document_listener,command)
           document_listener.options if any_options?(command)
           document_flags_and_switches(document_listener,command_flags(command),command_switches(command))
           document_listener.end_options if any_options?(command)
@@ -152,6 +154,18 @@ module GLI
         document_listener.default_command(context.get_default_command)
       end
 
+      def call_command_method_being_backwards_compatible(document_listener,command)
+        command_args = [command.name,
+                        Array(command.aliases),
+                        command.description,
+                        command.long_description,
+                        command.arguments_description]
+        if document_listener.method(:command).arity == 6
+          command_args << command.arguments_options
+        end
+        document_listener.command(*command_args)
+      end
+
       def by_name
         lambda { |a,b| a.name.to_s <=> b.name.to_s }
       end
@@ -170,7 +184,7 @@ module GLI
                                  Array(flag.aliases),
                                  flag.description,
                                  flag.long_description,
-                                 flag.default_value,
+                                 flag.safe_default_value,
                                  flag.argument_name,
                                  flag.must_match,
                                  flag.type)