puppet 3.0.2 → 3.1.0.rc1

data/lib/puppet/parameter/package_options.rb

@@ -1,5 +1,9 @@
 require 'puppet/parameter'
 
+# This specialized {Puppet::Parameter} handles munging of package options.
+# Package options are passed as an array of key value pairs. Special munging is
+# required as the keys and values needs to be quoted in a safe way.
+# 
 class Puppet::Parameter::PackageOptions < Puppet::Parameter
   def unsafe_munge(values)
     values = [values] unless values.is_a? Array
@@ -20,6 +24,7 @@ class Puppet::Parameter::PackageOptions < Puppet::Parameter
     end
   end
 
+  # @api private
   def quote(value)
     value.include?(' ') ? %Q["#{value.gsub(/"/, '\"')}"] : value
   end

data/lib/puppet/parameter/path.rb

@@ -1,6 +1,13 @@
 require 'puppet/parameter'
 
+# This specialized {Puppet::Parameter} handles validation and munging of paths.
+# By default, a single path is accepted, and by calling {accept_arrays} it is possible to
+# allow an array of paths.
+#
 class Puppet::Parameter::Path < Puppet::Parameter
+  # Specifies whether multiple paths are accepted or not.
+  # @dsl type
+  #
   def self.accept_arrays(bool = true)
     @accept_arrays = !!bool
   end
@@ -8,6 +15,13 @@ class Puppet::Parameter::Path < Puppet::Parameter
     @accept_arrays
   end
 
+  # Performs validation of the given paths.
+  # If the concrete parameter defines a validation method, it may call this method to perform
+  # path validation.
+  # @raise [Puppet::Error] if this property is configured for single paths and an array is given
+  # @raise [Puppet::Error] if a path is not an absolute path
+  # @return [Array<String>] the given paths
+  # 
   def validate_path(paths)
     if paths.is_a?(Array) and ! self.class.arrays? then
       fail "#{name} only accepts a single path, not an array of paths"
@@ -18,13 +32,22 @@ class Puppet::Parameter::Path < Puppet::Parameter
     paths
   end
 
-  # This will be overridden if someone uses the validate option, which is why
-  # it just delegates to the other, useful, method.
+  # This is the default implementation of the `validate` method.
+  # It will be overridden if the validate option is used when defining the parameter.
+  # @return [void]
+  #
   def unsafe_validate(paths)
     validate_path(paths)
   end
 
-  # Likewise, this might be overridden, but by default...
+  # This is the default implementation  of `munge`.
+  # If the concrete parameter defines a `munge` method, this default implementation will be overridden.
+  # This default implementation does not perform any munging, it just checks the one/many paths
+  # constraints. A derived implementation can perform this check as:
+  # `paths.is_a?(Array) and ! self.class.arrays?` and raise a {Puppet::Error}.
+  # @param [String, Array<String>] one of multiple paths
+  # @return [String, Array<String>] the given paths
+  # @raise [Puppet::Error] if the given paths does not comply with the on/many paths rule.
   def unsafe_munge(paths)
     if paths.is_a?(Array) and ! self.class.arrays? then
       fail "#{name} only accepts a single path, not an array of paths"

data/lib/puppet/parameter/value.rb

@@ -1,25 +1,42 @@
 require 'puppet/parameter/value_collection'
 
-# An individual Value class.
+# Describes an acceptable value for a parameter or property.
+# An acceptable value is either specified as a literal value or a regular expression.
+# @note this class should be used via the api methods in {Puppet::Parameter} and {Puppet::Property}
+# @api private
+#
 class Puppet::Parameter::Value
   attr_reader :name, :options, :event
   attr_accessor :block, :call, :method, :required_features
 
-  # Add an alias for this value.
+  # Adds an alias for this value.
+  # Makes the given _name_ be an alias for this acceptable value.
+  # @param name [Symbol] the additonal alias this value should be known as
+  # @api private
+  #
   def alias(name)
     @aliases << convert(name)
   end
 
-  # Return all aliases.
+  # @return [Array<Symbol>] Returns all aliases (or an empty array).
+  # @api private
+  #
   def aliases
     @aliases.dup
   end
 
-  # Store the event that our value generates, if it does so.
+  # Stores the event that our value generates, if it does so.
+  # @api private
+  #
   def event=(value)
     @event = convert(value)
   end
 
+  # Initializes the instance with a literal accepted value, or a regular expression.
+  # If anything else is passed, it is turned into a String, and then made into a Symbol.
+  # @param [Symbol, Regexp, Object] the value to accept, Symbol, a regular expression, or object to convert.
+  # @api private
+  #
   def initialize(name)
     if name.is_a?(Regexp)
       @name = name
@@ -34,7 +51,10 @@ class Puppet::Parameter::Value
     @call = :instead
   end
 
-  # Does a provided value match our value?
+  # Checks if the given value matches the acceptance rules (literal value, regular expression, or one
+  # of the aliases.
+  # @api private
+  #
   def match?(value)
     if regex?
       return true if name =~ value.to_s
@@ -43,7 +63,9 @@ class Puppet::Parameter::Value
     end
   end
 
-  # Is our value a regex?
+  # @return [Boolean] whether the accepted value is a regular expression or not.
+  # @api private
+  #
   def regex?
     @name.is_a?(Regexp)
   end
@@ -52,6 +74,8 @@ class Puppet::Parameter::Value
 
   # A standard way of converting all of our values, so we're always
   # comparing apples to apples.
+  # @api private
+  #
   def convert(value)
     case value
     when Symbol, ''             # can't intern an empty string

data/lib/puppet/parameter/value_collection.rb

@@ -1,9 +1,21 @@
 require 'puppet/parameter/value'
 
-# A collection of values and regexes, used for specifying
-# what values are allowed in a given parameter.
+# A collection of values and regular expressions, used for specifying allowed values
+# in a given parameter.
+# @note This class is considered part of the internal implementation of {Puppet::Parameter}, and 
+#   {Puppet::Property} and the functionality provided by this class should be used via their interfaces.
+# @comment This class probably have several problems when trying to use it with a combination of
+#   regular expressions and aliases as it finds an acceptable value holder vi "name" which may be
+#   a regular expression...
+#
+# @api private
+#
 class Puppet::Parameter::ValueCollection
 
+  # Aliases the given existing _other_ value with the additional given _name_.
+  # @return [void]
+  # @api private
+  #
   def aliasvalue(name, other)
     other = other.to_sym
     unless value = match?(other)
@@ -13,7 +25,10 @@ class Puppet::Parameter::ValueCollection
     value.alias(name)
   end
 
-  # Return a doc string for all of the values in this parameter/property.
+  # Returns a doc string (enumerating the acceptable values) for all of the values in this parameter/property.
+  # @return [String] a documentation string.
+  # @api private
+  #
   def doc
     unless defined?(@doc)
       @doc = ""
@@ -34,11 +49,15 @@ class Puppet::Parameter::ValueCollection
     @doc
   end
 
-  # Does this collection contain any value definitions?
+  # @return [Boolean] Returns whether the set of allowed values is empty or not.
+  # @api private
+  #
   def empty?
     @values.empty?
   end
 
+  # @api private
+  #
   def initialize
     # We often look values up by name, so a hash makes more sense.
     @values = {}
@@ -49,7 +68,15 @@ class Puppet::Parameter::ValueCollection
     @strings = []
   end
 
-  # Can we match a given value?
+  # Checks if the given value is acceptable (matches one of the literal values or patterns) and returns
+  # the "matcher" that matched.
+  # Literal string matchers are tested first, if both a literal and a regexp match would match, the literal
+  # match wins.
+  #
+  # @param test_value [Object] the value to test if it complies with the configured rules
+  # @return [Puppet::Parameter::Value, nil] The instance of Puppet::Parameter::Value that matched the given value, or nil if there was no match.
+  # @api private
+  #
   def match?(test_value)
     # First look for normal values
     if value = @strings.find { |v| v.match?(test_value) }
@@ -60,7 +87,14 @@ class Puppet::Parameter::ValueCollection
     @regexes.find { |v| v.match?(test_value) }
   end
 
-  # If the specified value is allowed, then munge appropriately.
+  # Munges the value if it is valid, else produces the same value.
+  # @param value [Object] the value to munge 
+  # @return [Object] the munged value, or the given value
+  # @todo This method does not seem to do any munging. It just returns the value if it matches the
+  #   regexp, or the (most likely Symbolic) allowed value if it matches (which is more of a replacement
+  #   of one instance with an equal one. Is the intent that this method should be specialized?
+  # @api private
+  #
   def munge(value)
     return value if empty?
 
@@ -75,17 +109,25 @@ class Puppet::Parameter::ValueCollection
     end
   end
 
-  # Define a new valid value for a property.  You must provide the value itself,
-  # usually as a symbol, or a regex to match the value.
+  # Defines a new valid value for a {Puppet::Property}.
+  # A valid value is specified as a literal (typically a Symbol), but can also be
+  # specified with a regexp.
+  #
+  # @param name [Symbol, Regexp] a valid literal value, or a regexp that matches a value
+  # @param options [Hash] a hash with options
+  # @option options [Symbol] :event The event that should be emitted when this value is set.
+  # @todo Option :event original comment says "event should be returned...", is "returned" the correct word
+  #   to use?
+  # @option options [Symbol] :call When to call any associated block. The default value is `:instead` which
+  #   means that the block should be called instead of the provider. In earlier versions (before 20081031) it
+  #   was possible to specify a value of `:before` or `:after` for the purpose of calling
+  #   both the block and the provider. Use of these deprecated options will now raise an exception later
+  #   in the process when the _is_ value is set (see Puppet::Property#set).
+  # @option options [Object] _any_ Any other option is treated as a call to a setter having the given
+  #   option name (e.g. `:required_features` calls `required_features=` with the option's value as an
+  #   argument).
+  # @api private
   #
-  # The first argument to the method is either the value itself or a regex.
-  # The second argument is an option hash; valid options are:
-  # * <tt>:event</tt>: The event that should be returned when this value is set.
-  # * <tt>:call</tt>: When to call any associated block.  The default value
-  #   is ``instead``, which means to call the value instead of calling the
-  #   provider.  You can also specify ``before`` or ``after``, which will
-  #   call both the block and the provider, according to the order you specify
-  #   (the ``first`` refers to when the block is called, not the provider).
   def newvalue(name, options = {}, &block)
     value = Puppet::Parameter::Value.new(name)
     @values[value.name] = value
@@ -107,16 +149,27 @@ class Puppet::Parameter::ValueCollection
     value
   end
 
-  # Define one or more new values for our parameter.
+  # Defines one or more valid values (literal or regexp) for a parameter or property.
+  # @return [void]
+  # @dsl type
+  # @api private
+  #
   def newvalues(*names)
     names.each { |name| newvalue(name) }
   end
 
+  # @return [Array<String>] An array of the regular expressions in string form, configured as matching valid values.
+  # @api private
+  #
   def regexes
     @regexes.collect { |r| r.name.inspect }
   end
 
-  # Verify that the passed value is valid.
+  # Validates the given value against the set of valid literal values and regular expressions.
+  # @raise [ArgumentError] if the value is not accepted
+  # @return [void]
+  # @api private
+  #
   def validate(value)
     return if empty?
 
@@ -131,12 +184,21 @@ class Puppet::Parameter::ValueCollection
     end
   end
 
-  # Return a single value instance.
+  # Returns a valid value matcher (a literal or regular expression)
+  # @todo This looks odd, asking for an instance that matches a symbol, or a instance that has
+  #   a regexp. What is the intention here? Marking as api private...
+  # 
+  # @return [Puppet::Parameter::Value] a valid valud matcher
+  # @api private
+  #
   def value(name)
     @values[name]
   end
 
-  # Return the list of valid values.
+  # @return [Array<Symbol>] Returns a list of valid literal values.
+  # @see regexes
+  # @api private
+  #
   def values
     @strings.collect { |s| s.name }
   end

data/lib/puppet/parser.rb

@@ -1,3 +1,6 @@
+# @api public
+module Puppet::Parser; end
+
 require 'puppet/parser/parser'
 require 'puppet/parser/compiler'
 require 'puppet/resource/type_collection'

data/lib/puppet/parser/ast/definition.rb

@@ -3,15 +3,12 @@ require 'puppet/parser/ast/top_level_construct'
 class Puppet::Parser::AST::Definition < Puppet::Parser::AST::TopLevelConstruct
   attr_accessor :context
 
-  def initialize(name, context = {}, &ruby_code)
+  def initialize(name, context = {})
     @name = name
     @context = context
-    @ruby_code = ruby_code
   end
 
   def instantiate(modname)
-    new_definition = Puppet::Resource::Type.new(:definition, @name, @context.merge(:module_name => modname))
-    new_definition.ruby_code = @ruby_code if @ruby_code
-    [new_definition]
+    [Puppet::Resource::Type.new(:definition, @name, @context.merge(:module_name => modname))]
   end
 end

data/lib/puppet/parser/ast/hostclass.rb

@@ -3,15 +3,13 @@ require 'puppet/parser/ast/top_level_construct'
 class Puppet::Parser::AST::Hostclass < Puppet::Parser::AST::TopLevelConstruct
   attr_accessor :name, :context
 
-  def initialize(name, context = {}, &ruby_code)
+  def initialize(name, context = {})
     @context = context
     @name = name
-    @ruby_code = ruby_code
   end
 
   def instantiate(modname)
     new_class = Puppet::Resource::Type.new(:hostclass, @name, @context.merge(:module_name => modname))
-    new_class.ruby_code = @ruby_code if @ruby_code
     all_types = [new_class]
     if code
       code.each do |nested_ast_node|
@@ -20,6 +18,7 @@ class Puppet::Parser::AST::Hostclass < Puppet::Parser::AST::TopLevelConstruct
         end
       end
     end
+
     return all_types
   end
 

data/lib/puppet/parser/ast/node.rb

@@ -3,18 +3,15 @@ require 'puppet/parser/ast/top_level_construct'
 class Puppet::Parser::AST::Node < Puppet::Parser::AST::TopLevelConstruct
   attr_accessor :names, :context
 
-  def initialize(names, context = {}, &ruby_code)
+  def initialize(names, context = {})
     raise ArgumentError, "names should be an array" unless names.is_a? Array
     @names = names
     @context = context
-    @ruby_code = ruby_code
   end
 
   def instantiate(modname)
     @names.collect do |name|
-      new_node = Puppet::Resource::Type.new(:node, name, @context.merge(:module_name => modname))
-      new_node.ruby_code = @ruby_code if @ruby_code
-      new_node
+      Puppet::Resource::Type.new(:node, name, @context.merge(:module_name => modname))
     end
   end
 end

data/lib/puppet/parser/ast/resourceparam.rb

@@ -11,7 +11,7 @@ class Puppet::Parser::AST
 
     # Return the parameter and the value.
     def evaluate(scope)
-      return Puppet::Parser::Resource::Param.new(
+      Puppet::Parser::Resource::Param.new(
         :name   => @param,
         :value  => @value.safeevaluate(scope),
         :source => scope.source, :line => self.line, :file => self.file,

data/lib/puppet/parser/compiler.rb

@@ -3,8 +3,10 @@ require 'forwardable'
 require 'puppet/node'
 require 'puppet/resource/catalog'
 require 'puppet/util/errors'
+require 'puppet/util/manifest_filetype_helper'
 
 require 'puppet/resource/type_collection_helper'
+require 'puppet/dsl/parser'
 
 # Maintain a graph of scopes, along with a bunch of data
 # about the individual catalog we're compiling.
@@ -90,6 +92,7 @@ class Puppet::Parser::Compiler
   # This is the main entry into our catalog.
   def compile
     # Set the client's parameters into the top scope.
+
     set_node_parameters
     create_settings_scope
 
@@ -110,6 +113,10 @@ class Puppet::Parser::Compiler
 
   def_delegator :@collections, :delete, :delete_collection
 
+  def assign_ruby_code(file)
+    Puppet::DSL::Parser.prepare_for_evaluation @main, File.read(file), file
+  end
+
   # Return the node's environment.
   def environment
     unless defined?(@environment)
@@ -279,6 +286,9 @@ class Puppet::Parser::Compiler
 
     add_resource(@topscope, @main_resource)
 
+    file = Puppet.settings.value :manifest, environment
+    assign_ruby_code file if Puppet::Util::ManifestFiletypeHelper.is_ruby_filename? file
+
     @main_resource.evaluate
   end
 

data/lib/puppet/parser/functions.rb

@@ -5,6 +5,8 @@ require 'monitor'
 # A module for managing parser functions.  Each specified function
 # is added to a central module that then gets included into the Scope
 # class.
+#
+# @api public
 module Puppet::Parser::Functions
   Environment = Puppet::Node::Environment
 
@@ -12,7 +14,9 @@ module Puppet::Parser::Functions
     include Puppet::Util
   end
 
-  # This is used by tests
+  # Reset the list of loaded functions.
+  #
+  # @api private
   def self.reset
     @functions = Hash.new { |h,k| h[k] = {} }.extend(MonitorMixin)
     @modules = Hash.new.extend(MonitorMixin)
@@ -25,12 +29,19 @@ module Puppet::Parser::Functions
     end
   end
 
+  # Accessor for singleton autoloader
+  #
+  # @api private
   def self.autoloader
     @autoloader ||= Puppet::Util::Autoload.new(
       self, "puppet/parser/functions", :wrap => false
     )
   end
 
+  # Get the module that functions are mixed into corresponding to an
+  # environment
+  #
+  # @api private
   def self.environment_module(env = nil)
     if env and ! env.is_a?(Puppet::Node::Environment)
       env = Puppet::Node::Environment.new(env)
@@ -40,12 +51,79 @@ module Puppet::Parser::Functions
     }
   end
 
-  # Create a new function type.
+  # Create a new Puppet DSL function.
+  #
+  # **The {newfunction} method provides a public API.**
+  #
+  # This method is used both internally inside of Puppet to define parser
+  # functions.  For example, template() is defined in
+  # {file:lib/puppet/parser/functions/template.rb template.rb} using the
+  # {newfunction} method.  Third party Puppet modules such as
+  # [stdlib](https://forge.puppetlabs.com/puppetlabs/stdlib) use this method to
+  # extend the behavior and functionality of Puppet.
+  #
+  # See also [Docs: Custom
+  # Functions](http://docs.puppetlabs.com/guides/custom_functions.html)
+  #
+  # @example Define a new Puppet DSL Function
+  #     >> Puppet::Parser::Functions.newfunction(:double, :arity => 1,
+  #          :doc => "Doubles an object, typically a number or string.",
+  #          :type => :rvalue) {|i| i[0]*2 }
+  #     => {:arity=>1, :type=>:rvalue,
+  #         :name=>"function_double",
+  #         :doc=>"Doubles an object, typically a number or string."}
+  #
+  # @example Invoke the double function from irb as is done in RSpec examples:
+  #     >> scope = Puppet::Parser::Scope.new_for_test_harness('example')
+  #     => Scope()
+  #     >> scope.function_double([2])
+  #     => 4
+  #     >> scope.function_double([4])
+  #     => 8
+  #     >> scope.function_double([])
+  #     ArgumentError: double(): Wrong number of arguments given (0 for 1)
+  #     >> scope.function_double([4,8])
+  #     ArgumentError: double(): Wrong number of arguments given (2 for 1)
+  #     >> scope.function_double(["hello"])
+  #     => "hellohello"
+  #
+  # @param [Symbol] name the name of the function represented as a ruby Symbol.
+  #   The {newfunction} method will define a Ruby method based on this name on
+  #   the parser scope instance.
+  #
+  # @param [Proc] block the block provided to the {newfunction} method will be
+  #   executed when the Puppet DSL function is evaluated during catalog
+  #   compilation.  The arguments to the function will be passed as an array to
+  #   the first argument of the block.  The return value of the block will be
+  #   the return value of the Puppet DSL function for `:rvalue` functions.
+  #
+  # @option options [:rvalue, :statement] :type (:statement) the type of function.
+  #   Either `:rvalue` for functions that return a value, or `:statement` for
+  #   functions that do not return a value.
+  #
+  # @option options [String] :doc ('') the documentation for the function.
+  #   This string will be extracted by documentation generation tools.
+  #
+  # @option options [Integer] :arity (-1) the
+  #   [arity](http://en.wikipedia.org/wiki/Arity) of the function.  When
+  #   specified as a positive integer the function is expected to receive
+  #   _exactly_ the specified number of arguments.  When specified as a
+  #   negative number, the function is expected to receive _at least_ the
+  #   absolute value of the specified number of arguments incremented by one.
+  #   For example, a function with an arity of `-4` is expected to receive at
+  #   minimum 3 arguments.  A function with the default arity of `-1` accepts
+  #   zero or more arguments.  A function with an arity of 2 must be provided
+  #   with exactly two arguments, no more and no less.  Added in Puppet 3.1.0.
+  #
+  # @return [Hash] describing the function.
+  #
+  # @api public
   def self.newfunction(name, options = {}, &block)
     name = name.intern
 
     Puppet.warning "Overwriting previous definition for function #{name}" if get_function(name)
 
+    arity = options[:arity] || -1
     ftype = options[:type] || :statement
 
     unless ftype == :statement or ftype == :rvalue
@@ -60,22 +138,32 @@ module Puppet::Parser::Functions
     fname = "function_#{name}"
     environment_module.send(:define_method, fname) do |*args|
       if args[0].is_a? Array
+        if arity >= 0 and args[0].size != arity
+          raise ArgumentError, "#{name}(): Wrong number of arguments given (#{args[0].size} for #{arity})"
+        elsif arity < 0 and args[0].size < (arity+1).abs
+          raise ArgumentError, "#{name}(): Wrong number of arguments given (#{args[0].size} for minimum #{(arity+1).abs})"
+        end
         self.send(real_fname, args[0])
       else
         raise ArgumentError, "custom functions must be called with a single array that contains the arguments. For example, function_example([1]) instead of function_example(1)"
       end
     end
 
-    # Someday we'll support specifying an arity, but for now, nope
-    #functions[name] = {:arity => arity, :type => ftype}
-    func = {:type => ftype, :name => fname}
+    func = {:arity => arity, :type => ftype, :name => fname}
     func[:doc] = options[:doc] if options[:doc]
 
     add_function(name, func)
     func
   end
 
-  # Determine if a given name is a function
+  # Determine if a function is defined
+  #
+  # @param [Symbol] name the function
+  #
+  # @return [Symbol, false] The name of the function if it's defined,
+  #   otherwise false.
+  #
+  # @api public
   def self.function(name)
     name = name.intern
 
@@ -113,12 +201,28 @@ module Puppet::Parser::Functions
     ret
   end
 
-  # Determine if a given function returns a value or not.
+  # Determine whether a given function returns a value.
+  #
+  # @param [Symbol] name the function
+  #
+  # @api public
   def self.rvalue?(name)
     func = get_function(name)
     func ? func[:type] == :rvalue : false
   end
 
+  # Return the number of arguments a function expects.
+  #
+  # @param [Symbol] name the function
+  # @return [Integer] The arity of the function. See {newfunction} for
+  #   the meaning of negative values.
+  #
+  # @api public
+  def self.arity(name)
+    func = get_function(name)
+    func ? func[:arity] : -1
+  end
+
   class << self
     private