diff --git a/lib/puppet/interface/option.rb b/lib/puppet/interface/option.rb index 493b5c3bd..b68bdeb12 100644 --- a/lib/puppet/interface/option.rb +++ b/lib/puppet/interface/option.rb @@ -1,110 +1,110 @@ require 'puppet/interface' class Puppet::Interface::Option - include Puppet::Interface::FullDocs + include Puppet::Interface::TinyDocs # For compatibility, deprecated, and should go fairly soon... ['', '='].each { |x| alias :"desc#{x}" :"description#{x}" } def initialize(parent, *declaration, &block) @parent = parent @optparse = [] # Collect and sort the arguments in the declaration. dups = {} declaration.each do |item| if item.is_a? String and item.to_s =~ /^-/ then unless item =~ /^-[a-z]\b/ or item =~ /^--[^-]/ then raise ArgumentError, "#{item.inspect}: long options need two dashes (--)" end @optparse << item # Duplicate checking... name = optparse_to_name(item) if dup = dups[name] then raise ArgumentError, "#{item.inspect}: duplicates existing alias #{dup.inspect} in #{@parent}" else dups[name] = item end else raise ArgumentError, "#{item.inspect} is not valid for an option argument" end end if @optparse.empty? then raise ArgumentError, "No option declarations found while building" end # Now, infer the name from the options; we prefer the first long option as # the name, rather than just the first option. @name = optparse_to_name(@optparse.find do |a| a =~ /^--/ end || @optparse.first) @aliases = @optparse.map { |o| optparse_to_name(o) } # Do we take an argument? If so, are we consistent about it, because # incoherence here makes our life super-difficult, and we can more easily # relax this rule later if we find a valid use case for it. --daniel 2011-03-30 @argument = @optparse.any? { |o| o =~ /[ =]/ } if @argument and not @optparse.all? { |o| o =~ /[ =]/ } then raise ArgumentError, "Option #{@name} is inconsistent about taking an argument" end # Is our argument optional? The rules about consistency apply here, also, # just like they do to taking arguments at all. --daniel 2011-03-30 @optional_argument = @optparse.any? { |o| o=~/[ =]\[/ } @optional_argument and raise ArgumentError, "Options with optional arguments are not supported" if @optional_argument and not @optparse.all? { |o| o=~/[ =]\[/ } then raise ArgumentError, "Option #{@name} is inconsistent about the argument being optional" end end # to_s and optparse_to_name are roughly mirrored, because they are used to # transform options to name symbols, and vice-versa. This isn't a full # bidirectional transformation though. --daniel 2011-04-07 def to_s @name.to_s.tr('_', '-') end def optparse_to_name(declaration) unless found = declaration.match(/^-+(?:\[no-\])?([^ =]+)/) then raise ArgumentError, "Can't find a name in the declaration #{declaration.inspect}" end name = found.captures.first.tr('-', '_') raise "#{name.inspect} is an invalid option name" unless name.to_s =~ /^[a-z]\w*$/ name.to_sym end def takes_argument? !!@argument end def optional_argument? !!@optional_argument end def required? !!@required end attr_reader :parent, :name, :aliases, :optparse attr_accessor :required attr_accessor :before_action def before_action=(proc) proc.is_a? Proc or raise ArgumentError, "before action hook for #{self} is a #{proc.class.name.inspect}, not a proc" @before_action = @parent.__send__(:__add_method, __decoration_name(:before), proc) end attr_accessor :after_action def after_action=(proc) proc.is_a? Proc or raise ArgumentError, "after action hook for #{self} is a #{proc.class.name.inspect}, not a proc" @after_action = @parent.__send__(:__add_method, __decoration_name(:after), proc) end def __decoration_name(type) if @parent.is_a? Puppet::Interface::Action then :"option #{name} from #{parent.name} #{type} decoration" else :"option #{name} #{type} decoration" end end end diff --git a/spec/integration/faces/documentation_spec.rb b/spec/integration/faces/documentation_spec.rb new file mode 100755 index 000000000..9ddf2f1b3 --- /dev/null +++ b/spec/integration/faces/documentation_spec.rb @@ -0,0 +1,55 @@ +#!/usr/bin/env rspec +require 'spec_helper' +require 'puppet/face' + +describe "documentation of faces" do + it "should generate global help" do + help = nil + expect { help = Puppet::Face[:help, :current].help }.not_to raise_error + help.should be_an_instance_of String + help.length.should be > 200 + end + + ######################################################################## + # Can we actually generate documentation for the face, and the actions it + # has? This avoids situations where the ERB template turns out to have a + # bug in it, triggered in something the user might do. + Puppet::Face.faces.sort.each do |face_name| + # REVISIT: We should walk all versions of the face here... + let :help do Puppet::Face[:help, :current] end + + context "generating help" do + it "for #{face_name}" do + expect { + text = help.help(face_name) + text.should be_an_instance_of String + text.length.should be > 100 + }.not_to raise_error + end + + Puppet::Face[face_name, :current].actions.sort.each do |action_name| + it "for #{face_name}.#{action_name}" do + expect { + text = help.help(face_name, action_name) + text.should be_an_instance_of String + text.length.should be > 100 + }.not_to raise_error + end + end + end + + ######################################################################## + # Ensure that we have authorship and copyright information in *our* faces; + # if you apply this to third party faces you might well be disappointed. + context "licensing of Puppet Labs face '#{face_name}'" do + subject { Puppet::Face[face_name, :current] } + its :license do should =~ /Apache\s*2/ end + its :copyright do should =~ /Puppet Labs/ end + + # REVISIT: This is less that ideal, I think, but right now I am more + # comfortable watching us ship with some copyright than without any; we + # can redress that when it becomes appropriate. --daniel 2011-04-27 + its :copyright do should =~ /2011/ end + end + end +end diff --git a/spec/lib/puppet/face/basetest.rb b/spec/lib/puppet/face/basetest.rb index a98bc382f..41a4ef3f9 100755 --- a/spec/lib/puppet/face/basetest.rb +++ b/spec/lib/puppet/face/basetest.rb @@ -1,33 +1,35 @@ require 'puppet/face' Puppet::Face.define(:basetest, '0.0.1') do + copyright "Puppet Labs", 2011 + license "Apache 2 license; see COPYING" summary "This is just so tests don't fail" option "--[no-]boolean" option "--mandatory ARGUMENT" action :foo do option("--action") when_invoked do |*args| args.length end end action :return_true do summary "just returns true" when_invoked do |options| true end end action :return_false do summary "just returns false" when_invoked do |options| false end end action :return_nil do summary "just returns nil" when_invoked do |options| nil end end action :raise do summary "just raises an exception" when_invoked do |options| raise ArgumentError, "your failure" end end end diff --git a/spec/lib/puppet/face/huzzah.rb b/spec/lib/puppet/face/huzzah.rb index 3428c6816..2c2b7aa8d 100755 --- a/spec/lib/puppet/face/huzzah.rb +++ b/spec/lib/puppet/face/huzzah.rb @@ -1,5 +1,7 @@ require 'puppet/face' Puppet::Face.define(:huzzah, '2.0.1') do + copyright "Puppet Labs", 2011 + license "Apache 2 license; see COPYING" summary "life is a thing for celebration" action :bar do "is where beer comes from" end end diff --git a/spec/lib/puppet/face/version_matching.rb b/spec/lib/puppet/face/version_matching.rb index bfd0013f7..52bc71dbd 100644 --- a/spec/lib/puppet/face/version_matching.rb +++ b/spec/lib/puppet/face/version_matching.rb @@ -1,10 +1,12 @@ require 'puppet/face' # The set of versions here are used explicitly in the interface_spec; if you # change this you need to ensure that is still correct. --daniel 2011-04-21 ['1.0.0', '1.0.1', '1.1.0', '1.1.1', '2.0.0'].each do |version| Puppet::Face.define(:version_matching, version) do + copyright "Puppet Labs", 2011 + license "Apache 2 license; see COPYING" summary "version matching face #{version}" script :version do version end end end