(#7012) Split plumbing into Puppet::Interface

This splits out the plumbing into the Puppet::Interface namespace, and uses
Puppet::Faces for all the public-facing code.

The fault line is "what you care about if you are using or writing a face",
which is public, against "what you care about to enable either of those two",
which is the plumbing.

9 files changed, 141 insertions, 129 deletions

diff --git a/lib/puppet/faces.rb b/lib/puppet/faces.rb
index 07a745480..947eecf24 100644
--- a/lib/puppet/faces.rb
+++ b/lib/puppet/faces.rb
@@ -1,106 +1,12 @@
-require 'puppet'
-require 'puppet/util/autoload'
-
-class Puppet::Faces
-  require 'puppet/faces/face_collection'
-
-  require 'puppet/faces/action_manager'
-  include Puppet::Faces::ActionManager
-  extend Puppet::Faces::ActionManager
-
-  require 'puppet/faces/option_manager'
-  include Puppet::Faces::OptionManager
-  extend Puppet::Faces::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/faces")
-    end
-
-    def faces
-      Puppet::Faces::FaceCollection.faces
-    end
-
-    def face?(name, version)
-      Puppet::Faces::FaceCollection.face?(name, version)
-    end
-
-    def register(instance)
-      Puppet::Faces::FaceCollection.register(instance)
-    end
-
-    def define(name, version, &block)
-      if face?(name, version)
-        face = Puppet::Faces::FaceCollection[name, version]
-      else
-        face = self.new(name, version)
-        Puppet::Faces::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
-
-    alias :[] :define
-  end
-
-  attr_accessor :default_format
-
-  def set_default_format(format)
-    self.default_format = format.to_sym
-  end
-
-  attr_accessor :type, :verb, :version, :arguments
-  attr_reader :name
-
-  def initialize(name, version, &block)
-    unless Puppet::Faces::FaceCollection.validate_version(version)
-      raise ArgumentError, "Cannot create face #{name.inspect} with invalid version number '#{version}'!"
-    end
-
-    @name = Puppet::Faces::FaceCollection.underscorize(name)
-    @version = version
-    @default_format = :pson
-
-    instance_eval(&block) if block_given?
-  end
-
-  # Try to find actions defined in other files.
-  def load_actions
-    path = "puppet/faces/#{name}"
-
-    loaded = []
-    [path, "#{name}@#{version}/#{path}"].each do |path|
-      Puppet::Faces.autoloader.search_directories.each do |dir|
-        fdir = ::File.join(dir, path)
-        next unless FileTest.directory?(fdir)
-
-        Dir.chdir(fdir) do
-          Dir.glob("*.rb").each do |file|
-            aname = file.sub(/\.rb/, '')
-            if loaded.include?(aname)
-              Puppet.debug "Not loading duplicate action '#{aname}' for '#{name}' from '#{fdir}/#{file}'"
-              next
-            end
-            loaded << aname
-            Puppet.debug "Loading action '#{aname}' for '#{name}' from '#{fdir}/#{file}'"
-            require "#{Dir.pwd}/#{aname}"
-          end
-        end
-      end
-    end
-  end
-
-  def to_s
-    "Puppet::Faces[#{name.inspect}, #{version.inspect}]"
-  end
-end
+# The public name of this feature is 'faces', but we have hidden all the
+# plumbing over in the 'interfaces' namespace to make clear the distinction
+# between the two.
+#
+# This file exists to ensure that the public name is usable without revealing
+# the details of the implementation; you really only need go look at anything
+# under Interfaces if you are looking to extend the implementation.
+#
+# It isn't hidden to gratuitously hide things, just to make it easier to
+# separate out the interests people will have.  --daniel 2011-04-07
+require 'puppet/interface'
+Puppet::Faces = Puppet::Interface
diff --git a/lib/puppet/interface.rb b/lib/puppet/interface.rb
new file mode 100644
index 000000000..70484adfc
--- /dev/null
+++ b/lib/puppet/interface.rb
@@ -0,0 +1,106 @@
+require 'puppet'
+require 'puppet/util/autoload'
+
+class Puppet::Interface
+  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/faces")
+    end
+
+    def faces
+      Puppet::Interface::FaceCollection.faces
+    end
+
+    def face?(name, version)
+      Puppet::Interface::FaceCollection.face?(name, version)
+    end
+
+    def register(instance)
+      Puppet::Interface::FaceCollection.register(instance)
+    end
+
+    def define(name, version, &block)
+      if face?(name, version)
+        face = Puppet::Interface::FaceCollection[name, version]
+      else
+        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
+
+    alias :[] :define
+  end
+
+  attr_accessor :default_format
+
+  def set_default_format(format)
+    self.default_format = format.to_sym
+  end
+
+  attr_accessor :type, :verb, :version, :arguments
+  attr_reader :name
+
+  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
+    @default_format = :pson
+
+    instance_eval(&block) if block_given?
+  end
+
+  # Try to find actions defined in other files.
+  def load_actions
+    path = "puppet/faces/#{name}"
+
+    loaded = []
+    [path, "#{name}@#{version}/#{path}"].each do |path|
+      Puppet::Interface.autoloader.search_directories.each do |dir|
+        fdir = ::File.join(dir, path)
+        next unless FileTest.directory?(fdir)
+
+        Dir.chdir(fdir) do
+          Dir.glob("*.rb").each do |file|
+            aname = file.sub(/\.rb/, '')
+            if loaded.include?(aname)
+              Puppet.debug "Not loading duplicate action '#{aname}' for '#{name}' from '#{fdir}/#{file}'"
+              next
+            end
+            loaded << aname
+            Puppet.debug "Loading action '#{aname}' for '#{name}' from '#{fdir}/#{file}'"
+            require "#{Dir.pwd}/#{aname}"
+          end
+        end
+      end
+    end
+  end
+
+  def to_s
+    "Puppet::Faces[#{name.inspect}, #{version.inspect}]"
+  end
+end
diff --git a/lib/puppet/faces/action.rb b/lib/puppet/interface/action.rb
index 58d2c6003..e4a37a1f7 100644
--- a/lib/puppet/faces/action.rb
+++ b/lib/puppet/interface/action.rb
@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
-require 'puppet/faces'
-require 'puppet/faces/option'
+require 'puppet/interface'
+require 'puppet/interface/option'
 
-class Puppet::Faces::Action
+class Puppet::Interface::Action
   def initialize(face, name, attrs = {})
     raise "#{name.inspect} is an invalid action name" unless name.to_s =~ /^[a-z]\w*$/
     @face    = face
diff --git a/lib/puppet/faces/action_builder.rb b/lib/puppet/interface/action_builder.rb
index a67068926..b08c3d023 100644
--- a/lib/puppet/faces/action_builder.rb
+++ b/lib/puppet/interface/action_builder.rb
@@ -1,7 +1,7 @@
-require 'puppet/faces'
-require 'puppet/faces/action'
+require 'puppet/interface'
+require 'puppet/interface/action'
 
-class Puppet::Faces::ActionBuilder
+class Puppet::Interface::ActionBuilder
   attr_reader :action
 
   def self.build(face, name, &block)
@@ -12,7 +12,7 @@ class Puppet::Faces::ActionBuilder
   private
   def initialize(face, name, &block)
     @face   = face
-    @action = Puppet::Faces::Action.new(face, name)
+    @action = Puppet::Interface::Action.new(face, name)
     instance_eval(&block)
   end
 
@@ -25,7 +25,7 @@ class Puppet::Faces::ActionBuilder
   end
 
   def option(*declaration, &block)
-    option = Puppet::Faces::OptionBuilder.build(@action, *declaration, &block)
+    option = Puppet::Interface::OptionBuilder.build(@action, *declaration, &block)
     @action.add_option(option)
   end
 end
diff --git a/lib/puppet/faces/action_manager.rb b/lib/puppet/interface/action_manager.rb
index 6c0036bd8..bb0e5bf57 100644
--- a/lib/puppet/faces/action_manager.rb
+++ b/lib/puppet/interface/action_manager.rb
@@ -1,12 +1,12 @@
-require 'puppet/faces/action_builder'
+require 'puppet/interface/action_builder'
 
-module Puppet::Faces::ActionManager
+module Puppet::Interface::ActionManager
   # Declare that this app can take a specific action, and provide
   # the code to do so.
   def action(name, &block)
     @actions ||= {}
     raise "Action #{name} already defined for #{self}" if action?(name)
-    action = Puppet::Faces::ActionBuilder.build(self, name, &block)
+    action = Puppet::Interface::ActionBuilder.build(self, name, &block)
     @actions[action.name] = action
   end
 
@@ -15,7 +15,7 @@ module Puppet::Faces::ActionManager
   def script(name, &block)
     @actions ||= {}
     raise "Action #{name} already defined for #{self}" if action?(name)
-    @actions[name] = Puppet::Faces::Action.new(self, name, :when_invoked => block)
+    @actions[name] = Puppet::Interface::Action.new(self, name, :when_invoked => block)
   end
 
   def actions
diff --git a/lib/puppet/faces/face_collection.rb b/lib/puppet/interface/face_collection.rb
index e6ee709d6..9f7a499c2 100644
--- a/lib/puppet/faces/face_collection.rb
+++ b/lib/puppet/interface/face_collection.rb
@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
-require 'puppet/faces'
+require 'puppet/interface'
 
-module Puppet::Faces::FaceCollection
+module Puppet::Interface::FaceCollection
   SEMVER_VERSION = /^(\d+)\.(\d+)\.(\d+)([A-Za-z][0-9A-Za-z-]*|)$/
 
   @faces = Hash.new { |hash, key| hash[key] = {} }
diff --git a/lib/puppet/faces/option.rb b/lib/puppet/interface/option.rb
index 7d3ed37ca..ccc2fbba7 100644
--- a/lib/puppet/faces/option.rb
+++ b/lib/puppet/interface/option.rb
@@ -1,6 +1,6 @@
-require 'puppet/faces'
+require 'puppet/interface'
 
-class Puppet::Faces::Option
+class Puppet::Interface::Option
   attr_reader   :parent
   attr_reader   :name
   attr_reader   :aliases
diff --git a/lib/puppet/faces/option_builder.rb b/lib/puppet/interface/option_builder.rb
index 0b6667546..83a1906b0 100644
--- a/lib/puppet/faces/option_builder.rb
+++ b/lib/puppet/interface/option_builder.rb
@@ -1,6 +1,6 @@
-require 'puppet/faces/option'
+require 'puppet/interface/option'
 
-class Puppet::Faces::OptionBuilder
+class Puppet::Interface::OptionBuilder
   attr_reader :option
 
   def self.build(face, *declaration, &block)
@@ -10,13 +10,13 @@ class Puppet::Faces::OptionBuilder
   private
   def initialize(face, *declaration, &block)
     @face   = face
-    @option = Puppet::Faces::Option.new(face, *declaration)
+    @option = Puppet::Interface::Option.new(face, *declaration)
     block and instance_eval(&block)
     @option
   end
 
   # Metaprogram the simple DSL from the option class.
-  Puppet::Faces::Option.instance_methods.grep(/=$/).each do |setter|
+  Puppet::Interface::Option.instance_methods.grep(/=$/).each do |setter|
     next if setter =~ /^=/      # special case, darn it...
 
     dsl = setter.sub(/=$/, '')
diff --git a/lib/puppet/faces/option_manager.rb b/lib/puppet/interface/option_manager.rb
index 02a73afc3..56df9760f 100644
--- a/lib/puppet/faces/option_manager.rb
+++ b/lib/puppet/interface/option_manager.rb
@@ -1,10 +1,10 @@
-require 'puppet/faces/option_builder'
+require 'puppet/interface/option_builder'
 
-module Puppet::Faces::OptionManager
+module Puppet::Interface::OptionManager
   # Declare that this app can take a specific option, and provide
   # the code to do so.
   def option(*declaration, &block)
-    add_option Puppet::Faces::OptionBuilder.build(self, *declaration, &block)
+    add_option Puppet::Interface::OptionBuilder.build(self, *declaration, &block)
   end
 
   def add_option(option)