diff --git a/lib/puppet/face/help.rb b/lib/puppet/face/help.rb index ba64d2b54..07c3ed9b1 100644 --- a/lib/puppet/face/help.rb +++ b/lib/puppet/face/help.rb @@ -1,133 +1,133 @@ require 'puppet/face' require 'puppet/util/command_line' require 'pathname' require 'erb' Puppet::Face.define(:help, '0.0.1') do copyright "Puppet Labs", 2011 license "Apache 2 license; see COPYING" 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" + summary "which version of the interface to show help for" end default 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 if args.select { |x| x == 'help' }.length > 2 then c = "\n !\"'),-./7:;<%= action.default? ? '' : " #{action.name}" %>(1) -- <%= action.summary || face.summary %> <%= '=' * (_erbout.length - 1) %> % if action.synopsis SYNOPSIS -------- <%= action.synopsis %> % end % if action.description DESCRIPTION ----------- <%= action.description %> %end % unless action.options.empty? OPTIONS ------- % action.options.sort.each do |name| % option = action.get_option name <%= " " + option.optparse.join(" |" ) %> -<%= option.desc and option.desc.gsub(/^/, ' ') %> +<%= option.summary %> +<%= option.description %> % end % end % if action.examples EXAMPLES -------- <%= action.examples %> % end % if action.notes NOTES ----- <%= action.notes %> % end % unless action.authors.empty? AUTHOR ------ <%= action.authors.map {|x| " * " + x } .join("\n") %> %end COPYRIGHT AND LICENSE --------------------- <%= action.copyright %> <%= action.license %> diff --git a/lib/puppet/face/help/face.erb b/lib/puppet/face/help/face.erb index 944f7a96b..b249981de 100644 --- a/lib/puppet/face/help/face.erb +++ b/lib/puppet/face/help/face.erb @@ -1,47 +1,48 @@ NAME <%= face.name %> -- <%= face.summary || "unknown face..." %> % if face.synopsis SYNOPSIS <%= face.synopsis.gsub(/^/, ' ') %> % end % if face.description DESCRIPTION <%= face.description.chomp.gsub(/^/, ' ') %> %end % unless face.options.empty? OPTIONS % face.options.sort.each do |name| % option = face.get_option name <%= " " + option.optparse.join(" |" ) %> -<%= option.desc and option.desc.gsub(/^/, ' ') %> +<%= option.summary %> +<%= option.description %> % end % end ACTIONS % padding = face.actions.map{|x| x.to_s.length}.max + 2 % face.actions.each do |actionname| % action = face.get_action(actionname) <%= action.name.to_s.ljust(padding) %> <%= action.summary %> % end % if face.examples EXAMPLES <%= face.examples %> % end % if face.notes NOTES <%= face.notes %> % end % unless face.authors.empty? AUTHOR <%= face.authors.join("\n").gsub(/^/, ' * ') %> %end COPYRIGHT AND LICENSE <%= face.copyright.gsub(/^/, ' ') %> <%= face.license.gsub(/^/, ' ') %> diff --git a/lib/puppet/face/indirector.rb b/lib/puppet/face/indirector.rb index 6c7708b51..a7ff7e1f0 100644 --- a/lib/puppet/face/indirector.rb +++ b/lib/puppet/face/indirector.rb @@ -1,95 +1,97 @@ require 'puppet' require 'puppet/face' class Puppet::Face::Indirector < Puppet::Face option "--terminus TERMINUS" do - desc "REVISIT: You can select a terminus, which has some bigger effect -that we should describe in this file somehow." + description %q{ +REVISIT: You can select a terminus, which has some bigger effect +that we should describe in this file somehow. +}.strip before_action do |action, args, options| set_terminus(options[:terminus]) end after_action do |action, args, options| indirection.reset_terminus_class end end def self.indirections Puppet::Indirector::Indirection.instances.collect { |t| t.to_s }.sort end def self.terminus_classes(indirection) Puppet::Indirector::Terminus.terminus_classes(indirection.to_sym).collect { |t| t.to_s }.sort end def call_indirection_method(method, *args) options = args.last begin result = indirection.__send__(method, *args) rescue => detail puts detail.backtrace if Puppet[:trace] raise "Could not call '#{method}' on '#{indirection_name}': #{detail}" end return result end action :destroy do when_invoked { |*args| call_indirection_method(:destroy, *args) } end action :find do when_invoked { |*args| call_indirection_method(:find, *args) } end action :save do when_invoked { |*args| call_indirection_method(:save, *args) } end action :search do when_invoked { |*args| call_indirection_method(:search, *args) } end # Print the configuration for the current terminus class action :info do when_invoked do |*args| if t = indirection.terminus_class puts "Run mode '#{Puppet.run_mode.name}': #{t}" else $stderr.puts "No default terminus class for run mode '#{Puppet.run_mode.name}'" end end end attr_accessor :from def indirection_name @indirection_name || name.to_sym end # Here's your opportunity to override the indirection name. By default it # will be the same name as the face. def set_indirection_name(name) @indirection_name = name end # Return an indirection associated with a face, if one exists; # One usually does. def indirection unless @indirection @indirection = Puppet::Indirector::Indirection.instance(indirection_name) @indirection or raise "Could not find terminus for #{indirection_name}" end @indirection end def set_terminus(from) begin indirection.terminus_class = from rescue => detail raise "Could not set '#{indirection.name}' terminus to '#{from}' (#{detail}); valid terminus types are #{self.class.terminus_classes(indirection.name).join(", ") }" end end end diff --git a/lib/puppet/interface.rb b/lib/puppet/interface.rb index 23d760b30..4a735069f 100644 --- a/lib/puppet/interface.rb +++ b/lib/puppet/interface.rb @@ -1,175 +1,175 @@ require 'puppet' require 'puppet/util/autoload' require 'puppet/interface/documentation' require 'prettyprint' class Puppet::Interface - include DocSupport + include FullDocs require 'puppet/interface/face_collection' require 'puppet/interface/action_manager' include Puppet::Interface::ActionManager extend Puppet::Interface::ActionManager require 'puppet/interface/option_manager' include Puppet::Interface::OptionManager extend Puppet::Interface::OptionManager include Puppet::Util class << self # This is just so we can search for actions. We only use its # list of directories to search. # Can't we utilize an external autoloader, or simply use the $LOAD_PATH? -pvb def autoloader @autoloader ||= Puppet::Util::Autoload.new(:application, "puppet/face") end def faces Puppet::Interface::FaceCollection.faces end def register(instance) Puppet::Interface::FaceCollection.register(instance) end def define(name, version, &block) face = Puppet::Interface::FaceCollection[name, version] if face.nil? then face = self.new(name, version) Puppet::Interface::FaceCollection.register(face) # REVISIT: Shouldn't this be delayed until *after* we evaluate the # current block, not done before? --daniel 2011-04-07 face.load_actions end face.instance_eval(&block) if block_given? return face end def face?(name, version) Puppet::Interface::FaceCollection[name, version] end def [](name, version) unless face = Puppet::Interface::FaceCollection[name, version] if current = Puppet::Interface::FaceCollection[name, :current] raise Puppet::Error, "Could not find version #{version} of #{name}" else raise Puppet::Error, "Could not find Puppet Face #{name.inspect}" end end face end end def set_default_format(format) Puppet.warning("set_default_format is deprecated (and ineffective); use render_as on your actions instead.") end ######################################################################## # Documentation. We currently have to rewrite both getters because we share # the same instance between build-time and the runtime instance. When that # splits out this should merge into a module that both the action and face # include. --daniel 2011-04-17 def synopsis output = PrettyPrint.format do |s| s.text("puppet #{name} ") s.breakable options.each do |option| option = get_option(option) wrap = option.required? ? %w{ < > } : %w{ [ ] } s.group(0, *wrap) do option.optparse.each do |item| unless s.current_group.first? s.breakable s.text '|' s.breakable end s.text item end end end end end ######################################################################## attr_reader :name, :version def initialize(name, version, &block) unless Puppet::Interface::FaceCollection.validate_version(version) raise ArgumentError, "Cannot create face #{name.inspect} with invalid version number '#{version}'!" end @name = Puppet::Interface::FaceCollection.underscorize(name) @version = version # The few bits of documentation we actually demand. The default license # is a favour to our end users; if you happen to get that in a core face # report it as a bug, please. --daniel 2011-04-26 @authors = [] @license = 'All Rights Reserved' instance_eval(&block) if block_given? end # Try to find actions defined in other files. def load_actions Puppet::Interface.autoloader.search_directories.each do |dir| Dir.glob(File.join(dir, "puppet/face/#{name}", "*.rb")).each do |file| action = file.sub(dir, '').sub(/^[\\\/]/, '').sub(/\.rb/, '') Puppet.debug "Loading action '#{action}' for '#{name}' from '#{dir}/#{action}.rb'" require(action) end end end def to_s "Puppet::Face[#{name.inspect}, #{version.inspect}]" end ######################################################################## # Action decoration, whee! You are not expected to care about this code, # which exists to support face building and construction. I marked these # private because the implementation is crude and ugly, and I don't yet know # enough to work out how to make it clean. # # Once we have established that these methods will likely change radically, # to be unrecognizable in the final outcome. At which point we will throw # all this away, replace it with something nice, and work out if we should # be making this visible to the outside world... --daniel 2011-04-14 private def __invoke_decorations(type, action, passed_args = [], passed_options = {}) [:before, :after].member?(type) or fail "unknown decoration type #{type}" # Collect the decoration methods matching our pass. methods = action.options.select do |name| passed_options.has_key? name end.map do |name| action.get_option(name).__decoration_name(type) end methods.each do |hook| begin respond_to? hook and self.__send__(hook, action, passed_args, passed_options) rescue => e Puppet.warning("invoking #{action} #{type} hook: #{e}") end end end def __add_method(name, proc) meta_def(name, &proc) method(name).unbind end def self.__add_method(name, proc) define_method(name, proc) instance_method(name) end end diff --git a/lib/puppet/interface/action.rb b/lib/puppet/interface/action.rb index 18c7ab057..177df81f2 100644 --- a/lib/puppet/interface/action.rb +++ b/lib/puppet/interface/action.rb @@ -1,272 +1,272 @@ require 'puppet/interface' require 'puppet/interface/documentation' require 'prettyprint' class Puppet::Interface::Action - include Puppet::Interface::DocSupport + include Puppet::Interface::FullDocs def initialize(face, name, attrs = {}) raise "#{name.inspect} is an invalid action name" unless name.to_s =~ /^[a-z]\w*$/ @face = face @name = name.to_sym # The few bits of documentation we actually demand. The default license # is a favour to our end users; if you happen to get that in a core face # report it as a bug, please. --daniel 2011-04-26 @authors = [] @license = 'All Rights Reserved' attrs.each do |k, v| send("#{k}=", v) end @options = {} @when_rendering = {} end # This is not nice, but it is the easiest way to make us behave like the # Ruby Method object rather than UnboundMethod. Duplication is vaguely # annoying, but at least we are a shallow clone. --daniel 2011-04-12 def __dup_and_rebind_to(to) bound_version = self.dup bound_version.instance_variable_set(:@face, to) return bound_version end def to_s() "#{@face}##{@name}" end attr_reader :name attr_accessor :default def default? !!@default end ######################################################################## # Documentation... def synopsis output = PrettyPrint.format do |s| s.text("puppet #{@face.name}") s.text(" #{name}") unless default? s.breakable options.each do |option| option = get_option(option) wrap = option.required? ? %w{ < > } : %w{ [ ] } s.group(0, *wrap) do option.optparse.each do |item| unless s.current_group.first? s.breakable s.text '|' s.breakable end s.text item end end end end end ######################################################################## # Support for rendering formats and all. def when_rendering(type) unless type.is_a? Symbol raise ArgumentError, "The rendering format must be a symbol, not #{type.class.name}" end return unless @when_rendering.has_key? type return @when_rendering[type].bind(@face) end def set_rendering_method_for(type, proc) unless proc.is_a? Proc msg = "The second argument to set_rendering_method_for must be a Proc" msg += ", not #{proc.class.name}" unless proc.nil? raise ArgumentError, msg end if proc.arity != 1 then msg = "when_rendering methods take one argument, the result, not " if proc.arity < 0 then msg += "a variable number" else msg += proc.arity.to_s end raise ArgumentError, msg end unless type.is_a? Symbol raise ArgumentError, "The rendering format must be a symbol, not #{type.class.name}" end if @when_rendering.has_key? type then raise ArgumentError, "You can't define a rendering method for #{type} twice" end # Now, the ugly bit. We add the method to our interface object, and # retrieve it, to rotate through the dance of getting a suitable method # object out of the whole process. --daniel 2011-04-18 @when_rendering[type] = @face.__send__( :__add_method, __render_method_name_for(type), proc) end def __render_method_name_for(type) :"#{name}_when_rendering_#{type}" end private :__render_method_name_for attr_accessor :render_as def render_as=(value) @render_as = value.to_sym end ######################################################################## # Initially, this was defined to allow the @action.invoke pattern, which is # a very natural way to invoke behaviour given our introspection # capabilities. Heck, our initial plan was to have the faces delegate to # the action object for invocation and all. # # It turns out that we have a binding problem to solve: @face was bound to # the parent class, not the subclass instance, and we don't pass the # appropriate context or change the binding enough to make this work. # # We could hack around it, by either mandating that you pass the context in # to invoke, or try to get the binding right, but that has probably got # subtleties that we don't instantly think of – especially around threads. # # So, we are pulling this method for now, and will return it to life when we # have the time to resolve the problem. For now, you should replace... # # @action = @face.get_action(name) # @action.invoke(arg1, arg2, arg3) # # ...with... # # @action = @face.get_action(name) # @face.send(@action.name, arg1, arg2, arg3) # # I understand that is somewhat cumbersome, but it functions as desired. # --daniel 2011-03-31 # # PS: This code is left present, but commented, to support this chunk of # documentation, for the benefit of the reader. # # def invoke(*args, &block) # @face.send(name, *args, &block) # end # We need to build an instance method as a wrapper, using normal code, to be # able to expose argument defaulting between the caller and definer in the # Ruby API. An extra method is, sadly, required for Ruby 1.8 to work since # it doesn't expose bind on a block. # # Hopefully we can improve this when we finally shuffle off the last of Ruby # 1.8 support, but that looks to be a few "enterprise" release eras away, so # we are pretty stuck with this for now. # # Patches to make this work more nicely with Ruby 1.9 using runtime version # checking and all are welcome, provided that they don't change anything # outside this little ol' bit of code and all. # # Incidentally, we though about vendoring evil-ruby and actually adjusting # the internal C structure implementation details under the hood to make # this stuff work, because it would have been cleaner. Which gives you an # idea how motivated we were to make this cleaner. Sorry. # --daniel 2011-03-31 def when_invoked=(block) internal_name = "#{@name} implementation, required on Ruby 1.8".to_sym arity = block.arity if arity == 0 then # This will never fire on 1.8.7, which treats no arguments as "*args", # but will on 1.9.2, which treats it as "no arguments". Which bites, # because this just begs for us to wind up in the horrible situation # where a 1.8 vs 1.9 error bites our end users. --daniel 2011-04-19 raise ArgumentError, "action when_invoked requires at least one argument (options)" elsif arity > 0 then range = Range.new(1, arity - 1) decl = range.map { |x| "arg#{x}" } << "options = {}" optn = "" args = "[" + (range.map { |x| "arg#{x}" } << "options").join(", ") + "]" else range = Range.new(1, arity.abs - 1) decl = range.map { |x| "arg#{x}" } << "*rest" optn = "rest << {} unless rest.last.is_a?(Hash)" if arity == -1 then args = "rest" else args = "[" + range.map { |x| "arg#{x}" }.join(", ") + "] + rest" end end file = __FILE__ + "+eval[wrapper]" line = __LINE__ + 2 # <== points to the same line as 'def' in the wrapper. wrapper = <