Allow multiple usages to be passed to commands

Sometimes, for mutually exclusive arguments, it is better to specify
each of the command line versions on its own line.

This is explained in
http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html,
bullet point 8, and it's a technique used by many CLI utils.

For example, the following is the beginning of the man's man page:

```
NAME
       man - an interface to the on-line reference manuals

SYNOPSIS
       man  [-C  file] [-d] [-D] [--warnings[=warnings]] [-R encoding] [-L locale] [-m system[,...]] [-M path] [-S list] [-e extension] [-i|-I] [--regex|--wildcard]
       [--names-only] [-a] [-u] [--no-subpages] [-P pager] [-r prompt] [-7] [-E encoding] [--no-hyphenation]  [--no-justification]  [-p  string]  [-t]  [-T[device]]
       [-H[browser]] [-X[dpi]] [-Z] [[section] page[.section] ...] ...
       man -k [apropos options] regexp ...
       man -K [-w|-W] [-S list] [-i|-I] [--regex] [section] term ...
       man -f [whatis options] page ...
       man  -l  [-C  file]  [-d]  [-D]  [--warnings[=warnings]]  [-R  encoding]  [-L locale] [-P pager] [-r prompt] [-7] [-E encoding] [-p string] [-t] [-T[device]]
       [-H[browser]] [-X[dpi]] [-Z] file ...
       man -w|-W [-C file] [-d] [-D] page ...
       man -c [-C file] [-d] [-D] page ...
       man [-?V]
```

This commit implements support for that, by passing an array of "usages"
instead of a single one.

Author: deivid-rodriguez

lib/thor.rb

@@ -170,7 +170,7 @@ def command_help(shell, command_name)
       handle_no_command_error(meth) unless command
 
       shell.say "Usage:"
-      shell.say "  #{banner(command)}"
+      shell.say "  #{banner(command).split("\n").join("\n  ")}"
       shell.say
       class_options_help(shell, nil => command.options.values)
       if command.long_description
@@ -393,7 +393,9 @@ def dispatch(meth, given_args, given_opts, config) #:nodoc: # rubocop:disable Me
     # the namespace should be displayed as arguments.
     #
     def banner(command, namespace = nil, subcommand = false)
-      "#{basename} #{command.formatted_usage(self, $thor_runner, subcommand)}"
+      command.formatted_usage(self, $thor_runner, subcommand).split("\n").map do |formatted_usage|
+        "#{basename} #{formatted_usage}"
+      end.join("\n")
     end
 
     def baseclass #:nodoc:

lib/thor/base.rb

@@ -502,7 +502,7 @@ def handle_argument_error(command, error, args, arity) #:nodoc:
         msg = "ERROR: \"#{basename} #{name}\" was called with ".dup
         msg << "no arguments"               if     args.empty?
         msg << "arguments " << args.inspect unless args.empty?
-        msg << "\nUsage: #{banner(command).inspect}"
+        msg << "\nUsage: \"#{banner(command).split("\n").join("\"\n       \"")}\""
         raise InvocationError, msg
       end
 

lib/thor/command.rb

@@ -49,13 +49,17 @@ def formatted_usage(klass, namespace = true, subcommand = false)
 
       formatted ||= "".dup
 
-      formatted << required_arguments_for(klass, specific_usage)
+      Array(usage).map do |specific_usage|
+        formatted_specific_usage = formatted
 
-      # Add required options
-      formatted << " #{required_options}"
+        formatted_specific_usage += required_arguments_for(klass, specific_usage)
 
-      # Strip and go!
-      formatted.strip
+        # Add required options
+        formatted_specific_usage += " #{required_options}"
+
+        # Strip and go!
+        formatted_specific_usage.strip
+      end.join("\n")
     end
 
   protected

spec/command_spec.rb

@@ -1,12 +1,12 @@
 require "helper"
 
 describe Thor::Command do
-  def command(options = {})
+  def command(options = {}, usage = "can_has")
     options.each do |key, value|
       options[key] = Thor::Option.parse(key, value)
     end
 
-    @command ||= Thor::Command.new(:can_has, "I can has cheezburger", "I can has cheezburger\nLots and lots of it", "can_has", options)
+    @command ||= Thor::Command.new(:can_has, "I can has cheezburger", "I can has cheezburger\nLots and lots of it", usage, options)
   end
 
   describe "#formatted_usage" do
@@ -30,6 +30,11 @@ def command(options = {})
       object = Struct.new(:namespace, :arguments).new("foo", [Thor::Argument.new(:bar, options)])
       expect(command(:foo => :required).formatted_usage(object)).to eq("foo:can_has BAR --foo=FOO")
     end
+
+    it "allows multiple usages" do
+      object = Struct.new(:namespace, :arguments).new("foo", [])
+      expect(command({ :bar => :required }, ["can_has FOO", "can_has BAR"]).formatted_usage(object, false)).to eq("can_has FOO --bar=BAR\ncan_has BAR --bar=BAR")
+    end
   end
 
   describe "#dynamic" do

spec/fixtures/script.thor

@@ -51,6 +51,12 @@ END
     [bar, options]
   end
 
+  method_option :all, :desc => "Do bazing for all the things"
+  desc ["baz THING", "baz --all"], "super cool"
+  def baz(thing = nil)
+    raise if thing.nil? && !options.include?(:all)
+  end
+
   desc "example_default_command", "example!"
   method_options :with => :string
   def example_default_command
@@ -215,6 +221,10 @@ module Scripts
     desc "optional_arg [ARG]", "takes an optional arg"
     def optional_arg(arg='default')
     end
+
+    desc ["multiple_usages ARG --foo", "multiple_usages ARG --bar"], "takes mutually exclusive combinations of args and flags"
+    def multiple_usages(arg)
+    end
   end
 end
 

spec/thor_spec.rb

@@ -440,6 +440,9 @@ def boring(*args)
 Usage: "thor scripts:arities:two_args ARG1 ARG2"'
       arity_asserter.call %w(optional_arg one two), 'ERROR: "thor optional_arg" was called with arguments ["one", "two"]
 Usage: "thor scripts:arities:optional_arg [ARG]"'
+      arity_asserter.call %w(multiple_usages), 'ERROR: "thor multiple_usages" was called with no arguments
+Usage: "thor scripts:arities:multiple_usages ARG --foo"
+       "thor scripts:arities:multiple_usages ARG --bar"'
     end
 
     it "raises an error if the invoked command does not exist" do
@@ -552,6 +555,19 @@ def shell
 END
       end
 
+      it "provides full help info when talking about a specific command with multiple usages" do
+        expect(capture(:stdout) { MyScript.command_help(shell, "baz") }).to eq(<<-END)
+Usage:
+  thor my_script:baz THING
+  thor my_script:baz --all
+
+Options:
+  [--all=ALL]  # Do bazing for all the things
+
+super cool
+END
+      end
+
       it "raises an error if the command can't be found" do
         expect do
           MyScript.command_help(shell, "unknown")