Merge branch 'feature/next/6962-self-documenting-strings-actions-and-options' into next

13 files changed, 208 insertions, 35 deletions

diff --git a/lib/puppet/application.rb b/lib/puppet/application.rb
index 4c5a5a967..f3a749786 100644
--- a/lib/puppet/application.rb
+++ b/lib/puppet/application.rb
@@ -359,14 +359,10 @@ class Application
       end
     end
 
-    # scan command line.
-    begin
-      option_parser.parse!(self.command_line.args)
-    rescue OptionParser::ParseError => detail
-      $stderr.puts detail
-      $stderr.puts "Try 'puppet #{command_line.subcommand_name} --help'"
-      exit(1)
-    end
+    # Scan command line.  We just hand any exceptions to our upper levels,
+    # rather than printing help and exiting, so that we can meaningfully
+    # respond with context-sensitive help if we want to. --daniel 2011-04-12
+    option_parser.parse!(self.command_line.args)
   end
 
   def handlearg(opt, arg)
diff --git a/lib/puppet/application/cert.rb b/lib/puppet/application/cert.rb
index cbd6fd610..c08775380 100644
--- a/lib/puppet/application/cert.rb
+++ b/lib/puppet/application/cert.rb
@@ -48,7 +48,7 @@ class Puppet::Application::Cert < Puppet::Application
   end
 
   def help
-    puts <<-HELP
+    <<-HELP
 
 puppet-cert(8) -- Manage certificates and requests
 ========
@@ -166,7 +166,6 @@ COPYRIGHT
 Copyright (c) 2011 Puppet Labs, LLC Licensed under the Apache 2.0 License
 
     HELP
-    exit
   end
 
   def main
diff --git a/lib/puppet/application/faces_base.rb b/lib/puppet/application/faces_base.rb
index 288b50048..f1b77f285 100644
--- a/lib/puppet/application/faces_base.rb
+++ b/lib/puppet/application/faces_base.rb
@@ -1,5 +1,6 @@
 require 'puppet/application'
 require 'puppet/faces'
+require 'optparse'
 
 class Puppet::Application::FacesBase < Puppet::Application
   should_parse_config
@@ -50,11 +51,13 @@ class Puppet::Application::FacesBase < Puppet::Application
       $stderr.puts "Cancelling Face"
       exit(0)
     end
+  end
 
+  def parse_options
     # We need to parse enough of the command line out early, to identify what
     # the action is, so that we can obtain the full set of options to parse.
 
-    # TODO: These should be configurable versions, through a global
+    # REVISIT: These should be configurable versions, through a global
     # '--version' option, but we don't implement that yet... --daniel 2011-03-29
     @type   = self.class.name.to_s.sub(/.+:/, '').downcase.to_sym
     @face   = Puppet::Faces[@type, :current]
@@ -88,25 +91,30 @@ class Puppet::Application::FacesBase < Puppet::Application
             index += 1          # ...so skip the argument.
           end
         else
-          raise ArgumentError, "Unknown option #{item.sub(/=.*$/, '').inspect}"
+          raise OptionParser::InvalidOption.new(item.sub(/=.*$/, ''))
         end
       else
         action = @face.get_action(item.to_sym)
         if action.nil? then
-          raise ArgumentError, "#{@face} does not have an #{item.inspect} action!"
+          raise OptionParser::InvalidArgument.new("#{@face} does not have an #{item} action")
         end
         @action = action
       end
     end
 
-    @action or raise ArgumentError, "No action given on the command line!"
+    unless @action
+      raise OptionParser::MissingArgument.new("No action given on the command line")
+    end
 
-    # Finally, we can interact with the default option code to build behaviour
+    # Now we can interact with the default option code to build behaviour
     # around the full set of options we now know we support.
     @action.options.each do |option|
       option = @action.get_option(option) # make it the object.
       self.class.option(*option.optparse) # ...and make the CLI parse it.
     end
+
+    # ...and invoke our parent to parse all the command line options.
+    super
   end
 
   def find_global_settings_argument(item)
diff --git a/lib/puppet/application/help.rb b/lib/puppet/application/help.rb
new file mode 100644
index 000000000..fd8818db0
--- /dev/null
+++ b/lib/puppet/application/help.rb
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+require 'puppet/application/faces_base'
+
+class Puppet::Application::Help < Puppet::Application::FacesBase
+  # Meh.  Disable the default behaviour, which is to inspect the
+  # string and return that – not so helpful. --daniel 2011-04-11
+  def render(result) result end
+end
diff --git a/lib/puppet/faces/help.rb b/lib/puppet/faces/help.rb
new file mode 100644
index 000000000..1d8abe20e
--- /dev/null
+++ b/lib/puppet/faces/help.rb
@@ -0,0 +1,104 @@
+require 'puppet/faces'
+require 'puppet/util/command_line'
+require 'pathname'
+require 'erb'
+
+Puppet::Faces.define(:help, '0.0.1') do
+  summary "Displays help about puppet subcommands"
+
+  action(:help) do
+    summary "Display help about faces and their actions."
+
+    option "--version VERSION" do
+      desc "Which version of the interface to show help for"
+    end
+
+    when_invoked do |*args|
+      # Check our invocation, because we want varargs and can't do defaults
+      # yet.  REVISIT: when we do option defaults, and positional options, we
+      # should rewrite this to use those. --daniel 2011-04-04
+      options = args.pop
+      if options.nil? or args.length > 2 then
+        raise ArgumentError, "help only takes two (optional) arguments, a face name, and an action"
+      end
+
+      version = :current
+      if options.has_key? :version then
+        if options[:version].to_s !~ /^current$/i then
+          version = options[:version]
+        else
+          if args.length == 0 then
+            raise ArgumentError, "version only makes sense when a face is given"
+          end
+        end
+      end
+
+      # Name those parameters...
+      facename, actionname = args
+
+      if facename then
+        if legacy_applications.include? facename then
+          actionname and raise ArgumentError, "Legacy subcommands don't take actions"
+          return Puppet::Application[facename].help
+        else
+          face = Puppet::Faces[facename.to_sym, version]
+          actionname and action = face.get_action(actionname.to_sym)
+        end
+      end
+
+      case args.length
+      when 0 then
+        template = erb 'global.erb'
+      when 1 then
+        face or fail ArgumentError, "Unable to load face #{facename}"
+        template = erb 'face.erb'
+      when 2 then
+        face or fail ArgumentError, "Unable to load face #{facename}"
+        action or fail ArgumentError, "Unable to load action #{actionname} from #{face}"
+        template = erb 'action.erb'
+      else
+        fail ArgumentError, "Too many arguments to help action"
+      end
+
+      # Run the ERB template in our current binding, including all the local
+      # variables we established just above. --daniel 2011-04-11
+      return template.result(binding)
+    end
+  end
+
+  def erb(name)
+    template = (Pathname(__FILE__).dirname + "help" + name)
+    erb = ERB.new(template.read, nil, '%')
+    erb.filename = template.to_s
+    return erb
+  end
+
+  def legacy_applications
+    # The list of applications, less those that are duplicated as a face.
+    Puppet::Util::CommandLine.available_subcommands.reject do |appname|
+      Puppet::Faces.face? appname.to_sym, :current or
+        # ...this is a nasty way to exclude non-applications. :(
+        %w{faces_base indirection_base}.include? appname
+    end.sort
+  end
+
+  def horribly_extract_summary_from(appname)
+    begin
+      require "puppet/application/#{appname}"
+      help = Puppet::Application[appname].help.split("\n")
+      # Now we find the line with our summary, extract it, and return it.  This
+      # depends on the implementation coincidence of how our pages are
+      # formatted.  If we can't match the pattern we expect we return the empty
+      # string to ensure we don't blow up in the summary. --daniel 2011-04-11
+      while line = help.shift do
+        if md = /^puppet-#{appname}\([^\)]+\) -- (.*)$/.match(line) then
+          return md[1]
+        end
+      end
+    rescue Exception
+      # Damn, but I hate this: we just ignore errors here, no matter what
+      # class they are.  Meh.
+    end
+    return ''
+  end
+end
diff --git a/lib/puppet/faces/help/action.erb b/lib/puppet/faces/help/action.erb
new file mode 100644
index 000000000..eaf131464
--- /dev/null
+++ b/lib/puppet/faces/help/action.erb
@@ -0,0 +1,3 @@
+Use: puppet <%= face.name %> [options] <%= action.name %> [options]
+
+Summary: <%= action.summary %>
diff --git a/lib/puppet/faces/help/face.erb b/lib/puppet/faces/help/face.erb
new file mode 100644
index 000000000..efe5fd809
--- /dev/null
+++ b/lib/puppet/faces/help/face.erb
@@ -0,0 +1,7 @@
+Use: puppet <%= face.name %> [options] <action> [options]
+
+Available actions:
+% face.actions.each do |actionname|
+%   action = face.get_action(actionname)
+  <%= action.name.to_s.ljust(16) %>  <%= action.summary %>
+% end
diff --git a/lib/puppet/faces/help/global.erb b/lib/puppet/faces/help/global.erb
new file mode 100644
index 000000000..e123367a2
--- /dev/null
+++ b/lib/puppet/faces/help/global.erb
@@ -0,0 +1,20 @@
+puppet <subcommand> [options] <action> [options]
+
+Available subcommands, from Puppet Faces:
+% Puppet::Faces.faces.sort.each do |name|
+%   face = Puppet::Faces[name, :current]
+  <%= face.name.to_s.ljust(16) %>  <%= face.summary %>
+% end
+
+% unless legacy_applications.empty? then # great victory when this is true!
+Available applications, soon to be ported to Faces:
+%   legacy_applications.each do |appname|
+%     summary = horribly_extract_summary_from appname
+  <%= appname.to_s.ljust(16) %>  <%= summary %>
+%   end
+% end
+
+See 'puppet help <subcommand> <action>' for help on a specific subcommand action.
+See 'puppet help <subcommand>' for help on a specific subcommand.
+See 'puppet man  <subcommand>' for the full man page.
+Puppet v<%= Puppet::PUPPETVERSION %>
diff --git a/lib/puppet/interface.rb b/lib/puppet/interface.rb
index 07e27efa8..27b3584b9 100644
--- a/lib/puppet/interface.rb
+++ b/lib/puppet/interface.rb
@@ -68,8 +68,13 @@ class Puppet::Interface
     self.default_format = format.to_sym
   end
 
-  attr_accessor :type, :verb, :version, :arguments
-  attr_reader :name
+  attr_accessor :summary
+  def summary(value = nil)
+    @summary = value unless value.nil?
+    @summary
+  end
+
+  attr_reader :name, :version
 
   def initialize(name, version, &block)
     unless Puppet::Interface::FaceCollection.validate_version(version)
diff --git a/lib/puppet/interface/action.rb b/lib/puppet/interface/action.rb
index e4a37a1f7..302e61901 100644
--- a/lib/puppet/interface/action.rb
+++ b/lib/puppet/interface/action.rb
@@ -14,6 +14,7 @@ class Puppet::Interface::Action
   attr_reader :name
   def to_s() "#{@face}##{@name}" end
 
+  attr_accessor :summary
 
   # Initially, this was defined to allow the @action.invoke pattern, which is
   # a very natural way to invoke behaviour given our introspection
diff --git a/lib/puppet/interface/action_builder.rb b/lib/puppet/interface/action_builder.rb
index b08c3d023..34bb3fa44 100644
--- a/lib/puppet/interface/action_builder.rb
+++ b/lib/puppet/interface/action_builder.rb
@@ -28,4 +28,8 @@ class Puppet::Interface::ActionBuilder
     option = Puppet::Interface::OptionBuilder.build(@action, *declaration, &block)
     @action.add_option(option)
   end
+
+  def summary(text)
+    @action.summary = text
+  end
 end
diff --git a/lib/puppet/interface/face_collection.rb b/lib/puppet/interface/face_collection.rb
index 84296582c..e4eb22fa3 100644
--- a/lib/puppet/interface/face_collection.rb
+++ b/lib/puppet/interface/face_collection.rb
@@ -53,7 +53,11 @@ module Puppet::Interface::FaceCollection
 
   def self.face?(name, version)
     name = underscorize(name)
-    return true if @faces[name].has_key?(version)
+
+    # Note: be careful not to accidentally create the top level key, either,
+    # because it will result in confusion when people try to enumerate the
+    # list of valid faces later. --daniel 2011-04-11
+    return true if @faces.has_key?(name) and @faces[name].has_key?(version)
 
     # We always load the current version file; the common case is that we have
     # the expected version and any compatibility versions in the same file,
@@ -106,7 +110,11 @@ module Puppet::Interface::FaceCollection
     # but we don't need that right now.
     #
     # So, this comment is a place-holder for that.  --daniel 2011-04-06
-    return !! @faces[name].has_key?(version)
+    #
+    # Note: be careful not to accidentally create the top level key, either,
+    # because it will result in confusion when people try to enumerate the
+    # list of valid faces later. --daniel 2011-04-11
+    return !! (@faces.has_key?(name) and @faces[name].has_key?(version))
   end
 
   def self.register(face)
diff --git a/lib/puppet/util/command_line.rb b/lib/puppet/util/command_line.rb
index 52b5f81ef..fa462ee2d 100644
--- a/lib/puppet/util/command_line.rb
+++ b/lib/puppet/util/command_line.rb
@@ -17,12 +17,12 @@ module Puppet
         'master'     => 'puppetmasterd'
       )
 
-      def initialize( zero = $0, argv = ARGV, stdin = STDIN )
+      def initialize(zero = $0, argv = ARGV, stdin = STDIN)
         @zero  = zero
         @argv  = argv.dup
         @stdin = stdin
 
-        @subcommand_name, @args = subcommand_and_args( @zero, @argv, @stdin )
+        @subcommand_name, @args = subcommand_and_args(@zero, @argv, @stdin)
         Puppet::Plugins.on_commandline_initialization(:command_line_object => self)
       end
 
@@ -33,19 +33,20 @@ module Puppet
         File.join('puppet', 'application')
       end
 
-      def available_subcommands
-        absolute_appdirs = $LOAD_PATH.collect do |x| 
+      def self.available_subcommands
+        absolute_appdirs = $LOAD_PATH.collect do |x|
           File.join(x,'puppet','application')
         end.select{ |x| File.directory?(x) }
         absolute_appdirs.inject([]) do |commands, dir|
           commands + Dir[File.join(dir, '*.rb')].map{|fn| File.basename(fn, '.rb')}
         end.uniq
       end
-
-      def usage_message
-        usage = "Usage: puppet command <space separated arguments>"
-        available = "Available commands are: #{available_subcommands.sort.join(', ')}"
-        [usage, available].join("\n")
+      # available_subcommands was previously an instance method, not a class
+      # method, and we have an unknown number of user-implemented applications
+      # that depend on that behaviour.  Forwarding allows us to preserve a
+      # backward compatible API. --daniel 2011-04-11
+      def available_subcommands
+        self.class.available_subcommands
       end
 
       def require_application(application)
@@ -53,15 +54,24 @@ module Puppet
       end
 
       def execute
-        if subcommand_name.nil?
-          puts usage_message
-        elsif available_subcommands.include?(subcommand_name) #subcommand
+        if subcommand_name and available_subcommands.include?(subcommand_name) then
           require_application subcommand_name
           app = Puppet::Application.find(subcommand_name).new(self)
           Puppet::Plugins.on_application_initialization(:appliation_object => self)
           app.run
+        elsif execute_external_subcommand then
+          # Logically, we shouldn't get here, but we do, so whatever.  We just
+          # return to the caller.  How strange we are. --daniel 2011-04-11
         else
-          abort "Error: Unknown command #{subcommand_name}.\n#{usage_message}" unless execute_external_subcommand
+          unless subcommand_name.nil? then
+            puts "Error: Unknown Puppet subcommand #{subcommand_name}.\n"
+          end
+
+          # Doing this at the top of the file is natural, but causes puppet.rb
+          # to load too early, which causes things to break.  This is a nasty
+          # thing, found in #7065. --daniel 2011-04-11
+          require 'puppet/faces/help'
+          puts Puppet::Faces[:help, :current].help
         end
       end
 
@@ -69,10 +79,10 @@ module Puppet
         external_command = "puppet-#{subcommand_name}"
 
         require 'puppet/util'
-        path_to_subcommand = Puppet::Util.which( external_command )
+        path_to_subcommand = Puppet::Util.which(external_command)
         return false unless path_to_subcommand
 
-        system( path_to_subcommand, *args )
+        system(path_to_subcommand, *args)
         true
       end
 
@@ -82,7 +92,7 @@ module Puppet
 
       private
 
-      def subcommand_and_args( zero, argv, stdin )
+      def subcommand_and_args(zero, argv, stdin)
         zero = File.basename(zero, '.rb')
 
         if zero == 'puppet'