Modifying providers so that docs generate better

git-svn-id: https://reductivelabs.com/svn/puppet/trunk@1502 980ebf18-57e1-0310-9a29-db15c13687c0

11 files changed, 72 insertions, 59 deletions

diff --git a/lib/puppet/provider.rb b/lib/puppet/provider.rb
index 44851c16b..1aff6b9fc 100644
--- a/lib/puppet/provider.rb
+++ b/lib/puppet/provider.rb
@@ -7,7 +7,8 @@ class Puppet::Provider
     class << self
         # Include the util module so we have access to things like 'binary'
         include Puppet::Util
-        attr_accessor :name, :model, :doc
+        attr_accessor :name, :model
+        attr_writer :doc
     end
 
     attr_accessor :model
@@ -16,20 +17,29 @@ class Puppet::Provider
         name = symbolize(name)
 
         if command = @commands[name]
-            return command
+            # nothing
         elsif superclass.respond_to? :command and command = superclass.command(name)
-            return command
+            # nothing
         else
             raise Puppet::DevError, "No command %s defined for provider %s" %
                 [name, self.name]
         end
+
+        unless command =~ /^\//
+            raise Puppet::Error, "Command #{command} could not be found"
+        end
     end
 
     # Define one or more binaries we'll be using
     def self.commands(hash)
         hash.each do |name, path|
             name = symbolize(name)
-            path = binary(path) unless path =~ /^\//
+            # Keep the short name if we couldn't find it.
+            unless path =~ /^\//
+                if tmp = binary(path)
+                    path = tmp
+                end
+            end
             @commands[name] = path
             confine :exists => path
         end
@@ -72,6 +82,17 @@ class Puppet::Provider
         @doc = str
     end
 
+    def self.doc
+        if defined? @commands and @commands.length > 0
+            extra = "  Required binaries: " + @commands.collect do |n, c|
+                "``#{c}``"
+            end.join(", ")
+            @doc + extra
+        else
+            @doc
+        end
+    end
+
     def self.initvars
         @defaults = {}
         @commands = {}
diff --git a/lib/puppet/provider/group/netinfo.rb b/lib/puppet/provider/group/netinfo.rb
index 4be1e4f35..eb98c0066 100644
--- a/lib/puppet/provider/group/netinfo.rb
+++ b/lib/puppet/provider/group/netinfo.rb
@@ -4,10 +4,7 @@ require 'puppet/provider/nameservice/netinfo'
 
 Puppet::Type.type(:group).provide :netinfo, :parent => Puppet::Provider::NameService::NetInfo do
     desc "Group management using NetInfo."
-    NIREPORT = binary("nireport")
-    NIUTIL = binary("niutil")
-    confine :exists => NIREPORT
-    confine :exists => NIUTIL
+    commands :nireport => "nireport", :niutil => "niutil"
 
     defaultfor :operatingsystem => :darwin
 end
diff --git a/lib/puppet/provider/nameservice/netinfo.rb b/lib/puppet/provider/nameservice/netinfo.rb
index d3a51bcf0..be73f7cae 100644
--- a/lib/puppet/provider/nameservice/netinfo.rb
+++ b/lib/puppet/provider/nameservice/netinfo.rb
@@ -41,7 +41,7 @@ class NetInfo < Puppet::Provider::NameService
     end
 
     def creatorcmd(arg)
-        cmd = ["niutil"]
+        cmd = [command(:niutil)]
         cmd << arg
 
         cmd << "/" << "/%s/%s" %
@@ -110,7 +110,7 @@ class NetInfo < Puppet::Provider::NameService
     end
 
     def modifycmd(param, value)
-        cmd = ["niutil"]
+        cmd = [command(:niutil)]
 
         cmd << "-createprop" << "/" << "/%s/%s" %
             [self.class.netinfodir, @model[:name]]
@@ -136,7 +136,7 @@ class NetInfo < Puppet::Provider::NameService
     # rather than retrieving it one at a time.
     def report(*params)
         dir = self.class.netinfodir()
-        cmd = ["nireport", "/", "/%s" % dir]
+        cmd = [command(:nireport), "/", "/%s" % dir]
 
         # We require the name in order to know if we match.  There's no
         # way to just report on our individual object, we have to get the
@@ -196,7 +196,7 @@ class NetInfo < Puppet::Provider::NameService
     end
 
     def setuserlist(group, list)
-        cmd = "niutil -createprop / /groups/%s users %s" %
+        cmd = "#{command(:niutil)} -createprop / /groups/%s users %s" %
             [group, list.join(",")]
         begin
             output = execute(cmd)
diff --git a/lib/puppet/provider/package/apple.rb b/lib/puppet/provider/package/apple.rb
index a9a86652d..e16609bfa 100755
--- a/lib/puppet/provider/package/apple.rb
+++ b/lib/puppet/provider/package/apple.rb
@@ -5,7 +5,7 @@ Puppet::Type.type(:package).provide :apple do
         it only supports installation; no deletion or upgrades."
 
     confine :exists => "/Library/Receipts"
-    confine :exists => "/usr/sbin/installer"
+    commands :installer => "/usr/sbin/installer"
 
     defaultfor :operatingsystem => :darwin
 
@@ -45,7 +45,7 @@ Puppet::Type.type(:package).provide :apple do
         end
 
         begin
-            output = execute("/usr/sbin/installer -pkg #{source} -target / 2>&1")
+            output = execute("#{command(:installer)} -pkg #{source} -target / 2>&1")
         rescue Puppet::ExecutionFailure
             raise Puppet::PackageError.new(output)
         end
diff --git a/lib/puppet/provider/package/apt.rb b/lib/puppet/provider/package/apt.rb
index 7f2cef375..52b4fa8ce 100755
--- a/lib/puppet/provider/package/apt.rb
+++ b/lib/puppet/provider/package/apt.rb
@@ -1,9 +1,8 @@
 Puppet::Type.type(:package).provide :apt, :parent => :dpkg do
     desc "Package management via ``apt-get``."
 
-    APT = "/usr/bin/apt-get"
-
-    confine :exists => APT
+    commands :aptget => "/usr/bin/apt-get"
+    commands :aptcache => "/usr/bin/apt-cache"
 
     defaultfor :operatingsystem => :debian
 
@@ -49,7 +48,7 @@ Puppet::Type.type(:package).provide :apt, :parent => :dpkg do
             # Add the package version
             str += "=%s" % should
         end
-        cmd = "/usr/bin/apt-get -q -y install %s" % str
+        cmd = "#{command(:aptget)} -q -y install %s" % str
 
         begin
             output = execute(cmd)
@@ -60,7 +59,7 @@ Puppet::Type.type(:package).provide :apt, :parent => :dpkg do
 
     # What's the latest package version available?
     def latest
-        cmd = "/usr/bin/apt-cache showpkg %s" % @model[:name] 
+        cmd = "#{command(:aptcache)}he showpkg %s" % @model[:name] 
         begin
             output = execute(cmd)
         rescue Puppet::ExecutionFailure
@@ -96,7 +95,7 @@ Puppet::Type.type(:package).provide :apt, :parent => :dpkg do
     end
 
     def uninstall
-        cmd = "/usr/bin/apt-get -y -q remove %s" % @model[:name]
+        cmd = "#{command(:aptget)} -y -q remove %s" % @model[:name]
         begin
             output = execute(cmd)
         rescue Puppet::ExecutionFailure
diff --git a/lib/puppet/provider/package/blastwave.rb b/lib/puppet/provider/package/blastwave.rb
index b6c449415..feea6721e 100755
--- a/lib/puppet/provider/package/blastwave.rb
+++ b/lib/puppet/provider/package/blastwave.rb
@@ -1,21 +1,18 @@
 # Packaging using Blastwave's pkg-get program.
 Puppet::Type.type(:package).provide :blastwave, :parent => :sun do
     desc "Package management using Blastwave.org's ``pkg-get`` command on Solaris."
+    pkgget = "pkg-get"
     if FileTest.executable?("/opt/csw/bin/pkg-get")
-        PKGGET = "/opt/csw/bin/pkg-get"
-    elsif pkgget = binary("pkg-get")
-        PKGGET = pkgget
-    else
-        PKGGET = nil
+        pkgget = "/opt/csw/bin/pkg-get"
     end
 
-    confine :exists => PKGGET
+    commands :pkgget => pkgget
 
     # This is so stupid, but then, so is blastwave.
     ENV["PAGER"] = "/usr/bin/cat"
 
     def self.extended(mod)
-        unless PKGGET
+        unless command(:pkgget) != "pkg-get"
             raise Puppet::Error,
                 "The pkg-get command is missing; blastwave packaging unavailable"
         end
@@ -35,7 +32,7 @@ Puppet::Type.type(:package).provide :blastwave, :parent => :sun do
 
     # Turn our blastwave listing into a bunch of hashes.
     def self.blastlist(hash)
-        command = "#{PKGGET} -c"
+        command = "#{command(:pkgget)} -c"
 
         if hash[:justme]
             command += " " + hash[:justme]
@@ -93,7 +90,7 @@ Puppet::Type.type(:package).provide :blastwave, :parent => :sun do
 
     def install
         begin
-            execute("#{PKGGET} -f install #{@model[:name]}")
+            execute("#{command(:pkgget)} -f install #{@model[:name]}")
         rescue Puppet::ExecutionFailure => detail
             raise Puppet::Error,
                 "Could not install %s: %s" %
@@ -116,7 +113,7 @@ Puppet::Type.type(:package).provide :blastwave, :parent => :sun do
     # Remove the old package, and install the new one
     def update
         begin
-            execute("#{PKGGET} -f upgrade #{@model[:name]}")
+            execute("#{command(:pkgget)} -f upgrade #{@model[:name]}")
         rescue Puppet::ExecutionFailure => detail
             raise Puppet::Error,
                 "Could not upgrade %s: %s" %
@@ -126,7 +123,7 @@ Puppet::Type.type(:package).provide :blastwave, :parent => :sun do
 
     def uninstall
         begin
-            execute("#{PKGGET} -f remove #{@model[:name]}")
+            execute("#{command(:pkgget)} -f remove #{@model[:name]}")
         rescue Puppet::ExecutionFailure => detail
             raise Puppet::Error,
                 "Could not remove %s: %s" %
diff --git a/lib/puppet/provider/package/dpkg.rb b/lib/puppet/provider/package/dpkg.rb
index a747a884c..690f1ca85 100755
--- a/lib/puppet/provider/package/dpkg.rb
+++ b/lib/puppet/provider/package/dpkg.rb
@@ -3,9 +3,7 @@ Puppet::Type.type(:package).provide :dpkg do
         and not ``apt``, you must specify the source of any packages you want
         to manage."
 
-    DPKG = "/usr/bin/dpkg"
-
-    confine :exists => DPKG
+    commands :dpkg => "/usr/bin/dpkg"
 
     def self.list
         packages = []
@@ -17,7 +15,7 @@ Puppet::Type.type(:package).provide :dpkg do
         ENV["COLUMNS"] = "500"
 
         # list out all of the packages
-        open("| #{DPKG} -l") { |process|
+        open("| #{command(:dpkg)} -l") { |process|
             # our regex for matching dpkg output
             regex = %r{^(\S+)\s+(\S+)\s+(\S+)\s+(.+)$}
             fields = [:status, :name, :version, :description]
@@ -60,7 +58,7 @@ Puppet::Type.type(:package).provide :dpkg do
 
         hash = {}
         # list out our specific package
-        open("| #{DPKG} -l %s 2>/dev/null" % @model[:name]) { |process|
+        open("| #{command(:dpkg)} -l %s 2>/dev/null" % @model[:name]) { |process|
             # our regex for matching dpkg output
             regex = %r{^(.)(.)(.)\s(\S+)\s+(\S+)\s+(.+)$}
 
@@ -103,7 +101,7 @@ Puppet::Type.type(:package).provide :dpkg do
     end
 
     def uninstall
-        cmd = "#{DPKG} -r %s" % @model[:name]
+        cmd = "#{command(:dpkg)} -r %s" % @model[:name]
         begin
             output = execute(cmd)
         rescue Puppet::ExecutionFailure
diff --git a/lib/puppet/provider/package/gem.rb b/lib/puppet/provider/package/gem.rb
index fba8b4702..227541ea0 100755
--- a/lib/puppet/provider/package/gem.rb
+++ b/lib/puppet/provider/package/gem.rb
@@ -2,12 +2,11 @@
 Puppet::Type.type(:package).provide :gem do
     desc "Ruby Gem support.  By default uses remote gems, but you can specify
         the path to a local gem via ``source``."
-    GEM = binary("gem")
 
-    confine :exists => GEM
+    commands :gem => "gem"
 
     def self.gemlist(hash)
-        command = "#{GEM} list "
+        command = "#{command(:gem)} list "
 
         if hash[:local]
             command += "--local "
@@ -62,7 +61,7 @@ Puppet::Type.type(:package).provide :gem do
     end
 
     def install(useversion = true)
-        command = "#{GEM} install "
+        command = "#{command(:gem)} install "
         if @model[:version] and useversion
             command += "-v %s " % @model[:version]
         end
@@ -93,7 +92,7 @@ Puppet::Type.type(:package).provide :gem do
     def uninstall
         begin
             # Remove everything, including the binaries.
-            execute("#{GEM} uninstall -x -a #{@model[:name]}")
+            execute("#{command(:gem)} uninstall -x -a #{@model[:name]}")
         rescue Puppet::ExecutionFailure => detail
             raise Puppet::Error, "Could not uninstall %s: %s" %
                 [@model[:name], detail]
diff --git a/lib/puppet/provider/service/base.rb b/lib/puppet/provider/service/base.rb
index eedcac4ae..c2980863d 100755
--- a/lib/puppet/provider/service/base.rb
+++ b/lib/puppet/provider/service/base.rb
@@ -2,10 +2,9 @@ Puppet::Type.type(:service).provide :base do
     desc "The simplest form of service support.  You have to specify
         enough about your service for this to work; the minimum you can specify
         is a binary for starting the process, and this same binary will be searched
-        for in the process table to stop the service.
-
-        It is preferable to specify start, stop, and status commands, akin
-        to how you would do so using ``init``."
+        for in the process table to stop the service.  It is preferable to
+        specify start, stop, and status commands, akin to how you would do
+        so using ``init``."
 
     # Execute a command.  Basically just makes sure it exits with a 0
     # code.
diff --git a/lib/puppet/provider/user/netinfo.rb b/lib/puppet/provider/user/netinfo.rb
index e453c4582..79469fa24 100644
--- a/lib/puppet/provider/user/netinfo.rb
+++ b/lib/puppet/provider/user/netinfo.rb
@@ -4,11 +4,7 @@ require 'puppet/provider/nameservice/netinfo'
 
 Puppet::Type.type(:user).provide :netinfo, :parent => Puppet::Provider::NameService::NetInfo do
     desc "User management in NetInfo."
-
-    NIREPORT = binary("nireport")
-    NIUTIL = binary("niutil")
-    confine :exists => NIREPORT
-    confine :exists => NIUTIL
+    commands :nireport => "nireport", :niutil => "niutil"
 
     options :comment, :key => "realname"
 
@@ -21,7 +17,7 @@ Puppet::Type.type(:user).provide :netinfo, :parent => Puppet::Provider::NameServ
 
         user = @model[:name]
         # Retrieve them all from netinfo
-        open("| nireport / /groups name users") do |file|
+        open("| #{command(:nireport)} / /groups name users") do |file|
             file.each do |line|
                 name, members = line.split(/\s+/)
                 next unless members
@@ -45,7 +41,7 @@ Puppet::Type.type(:user).provide :netinfo, :parent => Puppet::Provider::NameServ
         diff = groups - (@is || [])
 
         data = {}
-        open("| nireport / /groups name users") do |file|
+        open("| #{command(:nireport)} / /groups name users") do |file|
             file.each do |line|
                 name, members = line.split(/\s+/)
 
@@ -77,7 +73,7 @@ Puppet::Type.type(:user).provide :netinfo, :parent => Puppet::Provider::NameServ
     end
 
     def setuserlist(group, list)
-        cmd = "niutil -createprop / /groups/%s users %s" %
+        cmd = "#{command(:niutil)} -createprop / /groups/%s users %s" %
             [group, list.join(",")]
         begin
             output = execute(cmd)
diff --git a/lib/puppet/type.rb b/lib/puppet/type.rb
index e09a0c981..a5a8cf966 100644
--- a/lib/puppet/type.rb
+++ b/lib/puppet/type.rb
@@ -520,18 +520,25 @@ class Type < Puppet::Element
     # are providers.
     def self.providify
         return if @paramhash.has_key? :provider
+        model = self
         newparam(:provider) do
             desc "The specific backend for #{self.name.to_s} to use. You will
                 seldom need to specify this -- Puppet will usually discover the
                 appropriate provider for your platform."
 
+            # This is so we can refer back to the type to get a list of
+            # providers for documentation.
+            class << self
+                attr_accessor :parenttype
+            end
+
             # We need to add documentation for each provider.
             def self.doc
-                @doc + "Available providers are:\n" + @model.providers.sort { |a,b|
+                @doc + "  Available providers are:\n\n" + parenttype().providers.sort { |a,b|
                     a.to_s <=> b.to_s
-                }.each { |i|
-                    "* **%s**: %s" % [i, self.provider(i).doc]
-                }
+                }.collect { |i|
+                    "* **%s**: %s" % [i, parenttype().provider(i).doc]
+                }.join("\n")
             end
 
             defaultto { @parent.class.defaultprovider.name }
@@ -558,7 +565,7 @@ class Type < Puppet::Element
                 @parent.provider = provider
                 provider
             end
-        end
+        end.parenttype = self
     end
 
     def self.unprovide(name)