gli 2.8.1 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2fac00c937ac549343211b11935089bcb1277768
-  data.tar.gz: 0242a96c13a3e5e35ccfd51a65dd6764eb7c375a
+  metadata.gz: d1fffe3ab7b8b3aa4881cfb38de3b7cc1e31508b
+  data.tar.gz: 057ab9061b13527ed56f448cc20ee3ea54a7472d
 SHA512:
-  metadata.gz: 7d4d6b60d31a79295c9a8102c78b8148b71db8b0e2e1f57c1ab1ea36c1c89afd7f0d9f158480699d6e3bc17f90e6b4ce2edf2dfed702711a611ad56191d8cb44
-  data.tar.gz: 579f2c2504172996d80276540dd0b402ea4f634a2335b246aeb184cf3f3b36b53d0673ff26d34a2200ce20b39c4f6246081fb247aa9862601028e5a576927ac9
+  metadata.gz: c61409e0f16a9d07d9e4f704e05890e48868dc359be530dd2c094d3856a841b224968c1f2902b761355ad3ff2574ab8e9a33af626ceb77e897e3a2dfa17a3580
+  data.tar.gz: 3f26ab6c6026483c986241c506fdf1742a43408eac52605aa7ba2c5a36076f1d48acba70fbba5031b649fc042043d2cdf112ebc175cf9afeb35b49821fd15979

data/.travis.yml

@@ -3,14 +3,10 @@ notifications:
     on_success: always
 script: 'bundle exec rake test features'
 rvm:
-  - 1.9.2
   - 1.9.3
   - 1.8.7
-  - ree
   - 2.0.0
+  - 2.1.0
 branches:
   only:
-    - 'master'
     - 'gli-2'
-    - 'quick-bugifxes'
-    - 'fully-nested-subcommands'

data/features/step_definitions/todo_steps.rb

@@ -86,3 +86,11 @@ end
 Given /^the todo app is coded to use verbatim formatting$/ do
   ENV['TODO_WRAP_HELP_TEXT'] = 'verbatim'
 end
+
+Given(/^my terminal is (\d+) characters wide$/) do |terminal_width|
+  ENV['COLUMNS'] = terminal_width.to_s
+end
+
+Given(/^my app is configured for "(.*?)" synopses$/) do |synopsis|
+  ENV['SYNOPSES'] = synopsis
+end

data/features/support/env.rb

@@ -15,6 +15,7 @@ GLI_GEMSET = 'gli-testing'
 TMP_PATH = 'tmp/aruba'
 
 Before do
+  unset_bundler_env_vars
   # Not sure how else to get this dynamically
   @dirs = [TMP_PATH]
   @aruba_timeout_seconds = 5

data/features/todo.feature

@@ -152,8 +152,8 @@ Feature: The todo app has a nice user interface
         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
+        todo [global options] list [command options] [tasks] [--flag arg] [-x arg]
+        todo [global options] list [command options] contexts [--otherflag arg] [-b] [-f|--foobar]
 
     DESCRIPTION
         List a whole lot of things that you might be keeping track of in your
@@ -163,7 +163,8 @@ Feature: The todo app has a nice user interface
         stored in your todo databases. 
 
     COMMAND OPTIONS
-        -l, --[no-]long - Show long form
+        -l, --[no-]long     - Show long form
+        --required_flag=arg - (required, default: none)
 
     COMMANDS
         contexts - List contexts
@@ -198,14 +199,15 @@ Feature: The todo app has a nice user interface
         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
+        todo [global options] list [command options] [tasks] [--flag arg] [-x arg]
+        todo [global options] list [command options] contexts [--otherflag arg] [-b] [-f|--foobar]
 
     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
+        -l, --[no-]long     - Show long form
+        --required_flag=arg - (required, default: none)
 
     COMMANDS
         contexts - List contexts
@@ -221,8 +223,8 @@ Feature: The todo app has a nice user interface
         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
+        todo [global options] list [command options] [tasks] [--flag arg] [-x arg]
+        todo [global options] list [command options] contexts [--otherflag arg] [-b] [-f|--foobar]
 
     DESCRIPTION
         
@@ -236,7 +238,8 @@ Feature: The todo app has a nice user interface
      
 
     COMMAND OPTIONS
-        -l, --[no-]long - Show long form
+        -l, --[no-]long     - Show long form
+        --required_flag=arg - (required, default: none)
 
     COMMANDS
         contexts - List contexts
@@ -252,14 +255,15 @@ Feature: The todo app has a nice user interface
         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
+        todo [global options] list [command options] [tasks] [--flag arg] [-x arg]
+        todo [global options] list [command options] contexts [--otherflag arg] [-b] [-f|--foobar]
 
     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
+        -l, --[no-]long     - Show long form
+        --required_flag=arg - (required, default: none)
 
     COMMANDS
         contexts - List contexts
@@ -275,7 +279,7 @@ Feature: The todo app has a nice user interface
 
     SYNOPSIS
         todo [global options] list tasks [command options] 
-        todo [global options] list tasks [command options]  open
+        todo [global options] list tasks [command options] open
 
     DESCRIPTION
         Lists all of your tasks that you have, in varying orders, and all that
@@ -299,8 +303,8 @@ 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  tasks task_name[, task_name]*
+        todo [global options] create contexts [context_name]
+        todo [global options] create tasks task_name[, task_name]*
 
     COMMANDS
         <default> - Makes a new task
@@ -310,11 +314,11 @@ Feature: The todo app has a nice user interface
     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 boo yay`
+    When I successfully run `todo list --required_flag=blah 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`
+    When I successfully run `todo list --required_flag=blah`
     Then the output should contain "list tasks:"
 
   Scenario: Running chained commands works
@@ -351,8 +355,8 @@ Feature: The todo app has a nice user interface
         ls - LS things, such as tasks or contexts
 
     SYNOPSIS
-        todo [global options] ls [command options] [-b] [-f|--foobar] contexts
-        todo [global options] ls [command options] [-x arg] tasks
+        todo [global options] ls [command options] contexts [-b] [-f|--foobar]
+        todo [global options] ls [command options] tasks [-x arg]
 
     DESCRIPTION
         List a whole lot of things that you might be keeping track of in your
@@ -411,3 +415,35 @@ Feature: The todo app has a nice user interface
     And a config file that specifies defaults for some commands with subcommands
     When I successfully run `todo help list contexts`
     Then I should see the defaults for 'list contexts' from the config file in the help
+
+  Scenario: A complex SYNOPSIS section gets summarized in terminal mode
+    Given my terminal is 50 characters wide
+    And my app is configured for "terminal" synopses
+    When I run `todo ls`
+    Then the exit status should not be 0
+    And the stderr should contain "error: Command 'ls' requires a subcommand"
+    And the stdout should contain:
+    """
+    NAME
+        ls - LS things, such as tasks or contexts
+
+    SYNOPSIS
+        todo [global options] ls [command options] contexts [subcommand options]
+        todo [global options] ls [command options] tasks [subcommand options]
+    """
+
+  Scenario: We can always use a compact SYNOPSIS
+    Given my terminal is 500 characters wide
+    And my app is configured for "compact" synopses
+    When I run `todo ls`
+    Then the exit status should not be 0
+    And the stderr should contain "error: Command 'ls' requires a subcommand"
+    And the stdout should contain:
+    """
+    NAME
+        ls - LS things, such as tasks or contexts
+
+    SYNOPSIS
+        todo [global options] ls [command options] contexts [subcommand options]
+        todo [global options] ls [command options] tasks [subcommand options]
+    """

data/features/todo_legacy.feature

@@ -31,8 +31,8 @@ Feature: The todo app is backwards compatible with legacy subcommand parsing
         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
+        todo [global options] list [command options] [tasks] [--flag arg] [-x arg]
+        todo [global options] list [command options] contexts [--otherflag arg] [-b] [-f|--foobar]
 
     DESCRIPTION
         List a whole lot of things that you might be keeping track of in your
@@ -65,7 +65,7 @@ Feature: The todo app is backwards compatible with legacy subcommand parsing
 
     SYNOPSIS
         todo [global options] list tasks [command options] 
-        todo [global options] list tasks [command options]  open
+        todo [global options] list tasks [command options] open
 
     DESCRIPTION
         Lists all of your tasks that you have, in varying orders, and all that
@@ -89,8 +89,8 @@ Feature: The todo app is backwards compatible with legacy subcommand parsing
 
     SYNOPSIS
         todo [global options] create 
-        todo [global options] create  contexts [context_name]
-        todo [global options] create  tasks task_name[, task_name]*
+        todo [global options] create contexts [context_name]
+        todo [global options] create tasks task_name[, task_name]*
 
     COMMANDS
         <default> - Makes a new task
@@ -109,8 +109,8 @@ Feature: The todo app is backwards compatible with legacy subcommand parsing
         ls - LS things, such as tasks or contexts
 
     SYNOPSIS
-        todo [global options] ls [command options] [-b] [-f|--foobar] contexts
-        todo [global options] ls [command options] [-x arg] tasks
+        todo [global options] ls [command options] contexts [-b] [-f|--foobar]
+        todo [global options] ls [command options] tasks [-x arg]
 
     DESCRIPTION
         List a whole lot of things that you might be keeping track of in your

data/lib/gli/app.rb

@@ -245,6 +245,16 @@ module GLI
       @help_text_wrap_type = wrap_type
     end
 
+    # Control how the SYNOPSIS is formatted.
+    #
+    # format:: one of:
+    #          +:full+:: the default, show subcommand options and flags inline
+    #          +:terminal+:: if :full would be wider than the terminal, use :compact
+    #          +:compact+:: use a simpler and shorter SYNOPSIS.  Useful if your app has a lot of options and showing them in the SYNOPSIS makes things more confusing
+    def synopsis_format(format)
+      @synopsis_format_type = format
+    end
+
     def program_name(override=nil) #:nodoc:
       warn "#program_name has been deprecated"
     end

data/lib/gli/app_support.rb

@@ -166,6 +166,10 @@ module GLI
       @help_text_wrap_type || :to_terminal
     end
 
+    def synopsis_format_type
+      @synopsis_format_type || :full
+    end
+
     # Sets the default values for flags based on the configuration
     def override_defaults_based_on_config(config)
       override_default(flags,config)

data/lib/gli/commands/help.rb

@@ -12,6 +12,9 @@ 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'
+require 'gli/commands/help_modules/full_synopsis_formatter'
+require 'gli/commands/help_modules/compact_synopsis_formatter'
+require 'gli/commands/help_modules/terminal_synopsis_formatter'
 
 module GLI
   module Commands
@@ -28,6 +31,12 @@ module GLI
       :none        => HelpModules::VerbatimWrapper,
       :verbatim    => HelpModules::VerbatimWrapper,
     }
+
+    SYNOPSIS_FORMATTERS = {
+      :full     => HelpModules::FullSynopsisFormatter,
+      :compact  => HelpModules::CompactSynopsisFormatter,
+      :terminal => HelpModules::TerminalSynopsisFormatter,
+    }
     # The help command used for the two-level interactive help system
     class Help < Command
       @@skips_pre    = true
@@ -55,6 +64,7 @@ module GLI
         @parent = app
         @sorter = SORTERS[@app.help_sort_type]
         @text_wrapping_class = WRAPPERS[@app.help_text_wrap_type]
+        @synopsis_formatter_class = SYNOPSIS_FORMATTERS[@app.synopsis_format_type]
 
         desc 'List commands one per line, to assist with shell completion'
         switch :c
@@ -85,7 +95,12 @@ module GLI
           name = arguments.shift
           command = command_finder.find_command(name)
           unless command.nil?
-            out.puts HelpModules::CommandHelpFormat.new(command,@app,@app.exe_name.to_s,@sorter,@text_wrapping_class).format
+            out.puts HelpModules::CommandHelpFormat.new(
+              command,
+              @app,
+              @sorter,
+              @synopsis_formatter_class,
+              @text_wrapping_class).format
           end
         end
       end

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

@@ -4,12 +4,12 @@ module GLI
   module Commands
     module HelpModules
       class CommandHelpFormat
-        def initialize(command,app,basic_invocation,sorter,wrapper_class=TextWrapper)
-          @basic_invocation = basic_invocation
+        def initialize(command,app,sorter,synopsis_formatter_class,wrapper_class=TextWrapper)
           @app = app
           @command = command
           @sorter = sorter
           @wrapper_class = wrapper_class
+          @synopsis_formatter = synopsis_formatter_class.new(@app,flags_and_switches(@command,@app))
         end
 
         def format
@@ -19,19 +19,7 @@ module GLI
           options_description  = OptionsFormatter.new(flags_and_switches(@command,@app),@sorter,@wrapper_class).format
           commands_description = format_subcommands(@command)
 
-          synopses = []
-          one_line_usage = basic_usage
-          one_line_usage << @command.arguments_description
-          if @command.commands.empty?
-            synopses << one_line_usage
-          else
-            synopses = sorted_synopses
-            if @command.has_action?
-              synopses.unshift(one_line_usage)
-            end
-
-          end
-
+          synopses = @synopsis_formatter.synopses_for_command(@command)
           COMMAND_HELP.result(binding)
         end
 
@@ -59,27 +47,6 @@ COMMANDS
 <%= commands_description %>
 <% end %>),nil,'<>')
 
-        def command_with_subcommand_usage(sub,is_default_command)
-          usage = basic_usage
-          sub_options = if @app.subcommand_option_handling_strategy == :legacy 
-                          @command.flags.merge(@command.switches).select { |_,o| o.associated_command == sub }
-                        else
-                          sub.flags.merge(sub.switches)
-                        end
-          usage << sub_options.map { |option_name,option| 
-            option.names_and_aliases.map { |_| 
-              CommandLineOption.name_as_string(_,false) + (option.kind_of?(Flag) ? " #{option.argument_name }" : '')
-            }.join('|')
-          }.map { |_| "[#{_}]" }.sort.join(' ')
-          usage << ' '
-          if is_default_command
-            usage << "[#{sub.name}]"
-          else
-            usage << sub.name.to_s
-          end
-          usage << ArgNameFormatter.new.format(sub.arguments_description,sub.arguments_options)
-          usage
-        end
 
         def flags_and_switches(command,app)
           if app.subcommand_option_handling_strategy == :legacy
@@ -95,29 +62,6 @@ COMMANDS
           end
         end
  
-        def basic_usage
-          usage = @basic_invocation.dup
-          usage << " [global options]" unless global_flags_and_switches.empty?
-          usage << " #{path_to_command}"
-          usage << " [command options]" unless flags_and_switches(@command,@app).empty?
-          usage << " "
-          usage
-        end
- 
-        def path_to_command
-          path = []
-          c = @command
-          while c.kind_of? Command
-            path.unshift(c.name)
-            c = c.parent
-          end
-          path.join(' ')
-        end
- 
-        def global_flags_and_switches
-          @app.flags.merge(@app.switches)
-        end
- 
         def format_subcommands(command)
           commands_array = @sorter.call(command.commands_declaration_order).map { |cmd| 
             if command.get_default_command == cmd.name
@@ -132,24 +76,6 @@ COMMANDS
           formatter = ListFormatter.new(commands_array,@wrapper_class)
           StringIO.new.tap { |io| formatter.output(io) }.string
         end
-
-        def sorted_synopses
-          synopses_command = {}
-          @command.commands.each do |name,sub|
-            default = @command.get_default_command == name
-            synopsis = command_with_subcommand_usage(sub,default)
-            synopses_command[synopsis] = sub
-          end
-          synopses = synopses_command.keys.sort { |one,two|
-            if synopses_command[one].name == @command.get_default_command
-              -1
-            elsif synopses_command[two].name == @command.get_default_command
-              1
-            else
-              synopses_command[one] <=> synopses_command[two]
-            end
-          }
-        end
       end
     end
   end

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

@@ -0,0 +1,20 @@
+module GLI
+  module Commands
+    module HelpModules
+      class CompactSynopsisFormatter < FullSynopsisFormatter
+
+      protected
+
+        def sub_options_doc(sub_options)
+          if sub_options.empty?
+            ''
+          else
+            '[subcommand options]'
+          end
+        end
+
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+module GLI
+  module Commands
+    module HelpModules
+      class FullSynopsisFormatter
+        def initialize(app,flags_and_switches)
+          @app = app
+          @basic_invocation = @app.exe_name.to_s
+          @flags_and_switches = flags_and_switches
+        end
+
+        def synopses_for_command(command)
+          synopses = []
+          one_line_usage = basic_usage(command)
+          one_line_usage << command.arguments_description
+          if command.commands.empty?
+            synopses << one_line_usage
+          else
+            synopses = sorted_synopses(command)
+            if command.has_action?
+              synopses.unshift(one_line_usage)
+            end
+          end
+          synopses
+        end
+
+      protected
+
+        def sub_options_doc(sub_options)
+          sub_options_doc = sub_options.map { |_,option| 
+            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
+        end
+
+      private
+
+        def path_to_command(command)
+          path = []
+          c = command
+          while c.kind_of? Command
+            path.unshift(c.name)
+            c = c.parent
+          end
+          path.join(' ')
+        end
+ 
+
+        def basic_usage(command)
+          usage = @basic_invocation.dup
+          usage << " [global options]" unless global_flags_and_switches.empty?
+          usage << " #{path_to_command(command)}"
+          usage << " [command options]" unless @flags_and_switches.empty?
+          usage << " "
+          usage
+        end
+
+ 
+        def command_with_subcommand_usage(command,sub,is_default_command)
+          usage = basic_usage(command)
+          sub_options = if @app.subcommand_option_handling_strategy == :legacy 
+                          command.flags.merge(command.switches).select { |_,o| o.associated_command == sub }
+                        else
+                          sub.flags.merge(sub.switches)
+                        end
+          if is_default_command
+            usage << "[#{sub.name}]"
+          else
+            usage << sub.name.to_s
+          end
+          sub_options_doc = sub_options_doc(sub_options)
+          if sub_options_doc.length > 0
+            usage << ' '
+            usage << sub_options_doc
+          end
+          arg_name_doc = ArgNameFormatter.new.format(sub.arguments_description,sub.arguments_options).strip
+          if arg_name_doc.length > 0
+            usage << ' '
+            usage << arg_name_doc
+          end
+          usage
+        end
+
+        def sorted_synopses(command)
+          synopses_command = {}
+          command.commands.each do |name,sub|
+            default = command.get_default_command == name
+            synopsis = command_with_subcommand_usage(command,sub,default)
+            synopses_command[synopsis] = sub
+          end
+          synopses = synopses_command.keys.sort { |one,two|
+            if synopses_command[one].name == command.get_default_command
+              -1
+            elsif synopses_command[two].name == command.get_default_command
+              1
+            else
+              synopses_command[one] <=> synopses_command[two]
+            end
+          }
+        end
+
+        def global_flags_and_switches
+          @app.flags.merge(@app.switches)
+        end
+ 
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,22 @@
+module GLI
+  module Commands
+    module HelpModules
+      class TerminalSynopsisFormatter
+        def initialize(app,flags_and_switches)
+          @app = app
+          @basic_invocation = @app.exe_name.to_s
+          @flags_and_switches = flags_and_switches
+        end
+        def synopses_for_command(command)
+          synopses = FullSynopsisFormatter.new(@app,@flags_and_switches).synopses_for_command(command)
+          if synopses.any? { |synopsis| synopsis.length > Terminal.instance.size[0] }
+            CompactSynopsisFormatter.new(@app,@flags_and_switches).synopses_for_command(command)
+
+          else
+            synopses
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gli/commands/scaffold.rb

@@ -63,12 +63,7 @@ spec = Gem::Specification.new do |s|
   s.homepage = 'http://your.website.com'
   s.platform = Gem::Platform::RUBY
   s.summary = 'A description of your project'
-# Add your other files here if you make them
-  s.files = %w(
-bin/#{project_name}
-lib/#{project_name}/version.rb
-lib/#{project_name}.rb
-  )
+  s.files = `git ls-files`.split("\n")
   s.require_paths << 'lib'
   s.has_rdoc = true
   s.extra_rdoc_files = ['README.rdoc','#{project_name}.rdoc']

data/lib/gli/flag.rb

@@ -23,6 +23,7 @@ module GLI
     #           :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
+    #           :required:: if true, this flag must be specified on the command line
     #           :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.
@@ -33,8 +34,15 @@ module GLI
       @must_match = options[:must_match]
       @type = options[:type]
       @mask = options[:mask]
+      @required = options[:required]
     end
 
+    # True if this flag is required on the command line
+    def required?
+      @required
+    end
+
+
     def safe_default_value
       if @mask
         "********"

data/lib/gli/gli_option_parser.rb

@@ -3,7 +3,7 @@ module GLI
   class GLIOptionParser
     def initialize(commands,flags,switches,accepts,default_command = nil,subcommand_option_handling_strategy=:legacy)
        command_finder       = CommandFinder.new(commands,default_command || "help")
-      @global_option_parser = GlobalOptionParser.new(OptionParserFactory.new(flags,switches,accepts),command_finder)
+      @global_option_parser = GlobalOptionParser.new(OptionParserFactory.new(flags,switches,accepts),command_finder,flags)
       @accepts              = accepts
       @subcommand_option_handling_strategy = subcommand_option_handling_strategy
     end
@@ -21,9 +21,10 @@ module GLI
   private
 
     class GlobalOptionParser
-      def initialize(option_parser_factory,command_finder)
+      def initialize(option_parser_factory,command_finder,flags)
         @option_parser_factory = option_parser_factory
         @command_finder        = command_finder
+        @flags                 = flags
       end
 
       def parse!(parsing_result)
@@ -35,11 +36,29 @@ module GLI
                          parsing_result.arguments.shift
                        end
         parsing_result.command        = @command_finder.find_command(command_name)
+        unless command_name == 'help'
+          verify_required_options!(@flags,parsing_result.global_options)
+        end
         parsing_result
       end
+
+    protected
+
+      def verify_required_options!(flags,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|
+            "#{option.name} is required"
+          }.join(' ')
+        end
+      end
     end
 
-    class NormalCommandOptionParser
+    class NormalCommandOptionParser < GlobalOptionParser
       def initialize(accepts)
         @accepts = accepts
       end
@@ -67,6 +86,8 @@ 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])
+
           begin
             command = command_finder.find_command(next_command_name)
           rescue AmbiguousCommand
@@ -101,6 +122,7 @@ module GLI
         parsing_result.arguments = Array(arguments.compact)
         parsing_result
       end
+
     end
 
     class LegacyCommandOptionParser < NormalCommandOptionParser
@@ -116,6 +138,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)
       end
 
     private

data/lib/gli/version.rb

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

data/test/apps/todo/Rakefile

@@ -1,7 +1,7 @@
 require 'rake/clean'
 require 'rubygems'
 require 'rake/gempackagetask'
-require 'rake/rdoctask'
+require 'rdoc/task'
 
 Rake::RDocTask.new do |rd|
   rd.main = "README.rdoc"

data/test/apps/todo/bin/todo

@@ -16,6 +16,7 @@ end
 
 sort_help (ENV['TODO_SORT_HELP'] || 'alpha').to_sym
 wrap_help_text (ENV['TODO_WRAP_HELP_TEXT'] || 'to_terminal').to_sym
+synopsis_format (ENV['SYNOPSES'] || 'full').to_sym
 
 subcommand_option_handling :normal
 

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

@@ -14,6 +14,8 @@ command [:list] do |c|
   c.desc "Show long form"
   c.switch [:l,:long]
 
+  c.flag :required_flag, :required => true
+
   c.desc "List tasks"
   c.long_desc %(
     Lists all of your tasks that you have, in varying orders, and

data/test/apps/todo_legacy/Rakefile

@@ -1,7 +1,7 @@
 require 'rake/clean'
 require 'rubygems'
 require 'rake/gempackagetask'
-require 'rake/rdoctask'
+require 'rdoc/task'
 
 Rake::RDocTask.new do |rd|
   rd.main = "README.rdoc"

data/test/tc_gli.rb

@@ -71,6 +71,61 @@ class TC_testGLI < Clean::Test::TestCase
     assert @called, "Expected default command to be executed"
   end
 
+  def test_command_options_can_be_required
+    @app.reset
+    @called = false
+    @app.command :foo do |c|
+      c.flag :flag, :required => true
+      c.flag :other_flag, :required => true
+      c.action do |global, options, arguments|
+        @called = true
+      end
+    end
+    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 !@called
+
+    assert_equal 0, @app.run(['foo','--flag=bar','--other_flag=blah']), "Expected exit status to be 0 #{@fake_stderr.strings.join(',')}"
+    assert @called
+
+  end
+
+  def test_global_options_can_be_required
+    @app.reset
+    @called = false
+    @app.flag :flag, :required => true
+    @app.flag :other_flag, :required => true
+    @app.command :foo do |c|
+      c.action do |global, options, arguments|
+        @called = true
+      end
+    end
+    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 !@called
+
+    assert_equal 0, @app.run(['--flag=bar','--other_flag=blah','foo']), "Expected exit status to be 0 #{@fake_stderr.strings.join(',')}"
+    assert @called
+
+  end
+
+  def test_global_required_options_are_ignored_on_help
+    @app.reset
+    @called = false
+    @app.flag :flag, :required => true
+    @app.flag :other_flag, :required => true
+    @app.command :foo do |c|
+      c.action do |global, options, arguments|
+        @called = true
+      end
+    end
+    assert_equal 0, @app.run(['help']), "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
+  end
+
   def test_flag_with_space_barfs
     @app.reset
     assert_raises(ArgumentError) { @app.flag ['some flag'] }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gli
 version: !ruby/object:Gem::Version
-  version: 2.8.1
+  version: 2.9.0
 platform: ruby
 authors:
 - David Copeland
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-08 00:00:00.000000000 Z
+date: 2014-01-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -185,11 +185,14 @@ files:
 - lib/gli/commands/help_modules/arg_name_formatter.rb
 - lib/gli/commands/help_modules/command_finder.rb
 - lib/gli/commands/help_modules/command_help_format.rb
+- lib/gli/commands/help_modules/compact_synopsis_formatter.rb
+- lib/gli/commands/help_modules/full_synopsis_formatter.rb
 - lib/gli/commands/help_modules/global_help_format.rb
 - lib/gli/commands/help_modules/help_completion_format.rb
 - lib/gli/commands/help_modules/list_formatter.rb
 - lib/gli/commands/help_modules/one_line_wrapper.rb
 - lib/gli/commands/help_modules/options_formatter.rb
+- lib/gli/commands/help_modules/terminal_synopsis_formatter.rb
 - lib/gli/commands/help_modules/text_wrapper.rb
 - lib/gli/commands/help_modules/tty_only_wrapper.rb
 - lib/gli/commands/help_modules/verbatim_wrapper.rb
@@ -272,7 +275,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: gli
-rubygems_version: 2.0.3
+rubygems_version: 2.0.14
 signing_key: 
 specification_version: 4
 summary: Build command-suite CLI apps that are awesome.