puppet 4.0.0 → 4.9.1

data/lib/puppet/functions/type.rb

@@ -0,0 +1,31 @@
+# (Documentation in 3.x stub)
+# @since 4.4.0
+#
+Puppet::Functions.create_function(:type) do
+  dispatch :type_detailed do
+    param 'Any', :value
+    optional_param 'Enum[detailed]', :inference_method
+  end
+
+  dispatch :type_parameterized do
+    param 'Any', :value
+    param 'Enum[reduced]', :inference_method
+  end
+
+  dispatch :type_generalized do
+    param 'Any', :value
+    param 'Enum[generalized]', :inference_method
+  end
+
+  def type_detailed(value, _ = nil)
+    Puppet::Pops::Types::TypeCalculator.infer_set(value)
+  end
+
+  def type_parameterized(value, _)
+    Puppet::Pops::Types::TypeCalculator.infer(value)
+  end
+
+  def type_generalized(value, _)
+    Puppet::Pops::Types::TypeCalculator.infer(value).generalize
+  end
+end

data/lib/puppet/functions/unwrap.rb

@@ -0,0 +1,40 @@
+# Unwraps a Sensitive value and returns the wrapped object.
+#
+# ~~~puppet
+# $plaintext = 'hunter2'
+# $pw = Sensitive.new($plaintext)
+# notice("Wrapped object is $pw") #=> Prints "Wrapped object is Sensitive [value redacted]"
+# $unwrapped = $pw.unwrap
+# notice("Unwrapped object is $unwrapped") #=> Prints "Unwrapped object is hunter2"
+# ~~~
+#
+# You can optionally pass a block to unwrap in order to limit the scope where the
+# unwrapped value is visible.
+#
+# ~~~puppet
+# $pw = Sensitive.new('hunter2')
+# notice("Wrapped object is $pw") #=> Prints "Wrapped object is Sensitive [value redacted]"
+# $pw.unwrap |$unwrapped| {
+#   $conf = inline_template("password: ${unwrapped}\n")
+#   Sensitive.new($conf)
+# } #=> Returns a new Sensitive object containing an interpolated config file
+# # $unwrapped is now out of scope
+# ~~~
+#
+# @since 4.0.0
+#
+Puppet::Functions.create_function(:unwrap) do
+  dispatch :unwrap do
+    param 'Sensitive', :arg
+    optional_block_param
+  end
+
+  def unwrap(arg)
+    unwrapped = arg.unwrap
+    if block_given?
+      yield(unwrapped)
+    else
+      unwrapped
+    end
+  end
+end

data/lib/puppet/functions/versioncmp.rb

@@ -0,0 +1,36 @@
+require 'puppet/util/package'
+
+# Compares two version numbers.
+#
+# Prototype:
+#
+#     \$result = versioncmp(a, b)
+#
+# Where a and b are arbitrary version strings.
+#
+# This function returns:
+#
+# * `1` if version a is greater than version b
+# * `0` if the versions are equal
+# * `-1` if version a is less than version b
+#
+# @example
+#
+#     if versioncmp('2.6-1', '2.4.5') > 0 {
+#         notice('2.6-1 is > than 2.4.5')
+#     }
+#
+# This function uses the same version comparison algorithm used by Puppet's
+# `package` type.
+#
+Puppet::Functions.create_function(:versioncmp) do
+
+  dispatch :versioncmp do
+    param 'String', :a
+    param 'String', :b
+  end
+
+  def versioncmp(a, b)
+    Puppet::Util::Package.versioncmp(a, b)
+  end
+end

data/lib/puppet/functions/warning.rb

@@ -0,0 +1,14 @@
+# Log a message on the server at level notice.
+Puppet::Functions.create_function(:warning, Puppet::Functions::InternalFunction) do
+  # @param values The values to log.
+  # @return [Undef]
+  dispatch :warning do
+    scope_param
+    repeated_param 'Any', :values
+    return_type 'Undef'
+  end
+
+  def warning(scope, *values)
+    Puppet::Util::Log.log_func(scope, :warning, values)
+  end
+end

data/lib/puppet/functions/with.rb

@@ -1,12 +1,20 @@
-# Call a lambda with the given arguments. Since the parameters of the lambda
-# are local to the lambda's scope, this can be used to create private sections
-# of logic in a class so that the variables are not visible outside of the
-# class.
+# Call a [lambda](https://docs.puppet.com/puppet/latest/reference/lang_lambdas.html)
+# with the given arguments and return the result. Since a lambda's scope is
+# [local](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html#lambda-scope)
+# to the lambda, you can use the `with` function to create private blocks of code within a
+# class using variables whose values cannot be accessed outside of the lambda.
 #
-# @example Using with
+# @example Using `with`
 #
-#     # notices the array [1, 2, 'foo']
-#     with(1, 2, 'foo') |$x, $y, $z| { notice [$x, $y, $z] }
+# ~~~ puppet
+# # Concatenate three strings into a single string formatted as a list.
+# $fruit = with("apples", "oranges", "bananas") |$x, $y, $z| { 
+#   "${x}, ${y}, and ${z}" 
+# }
+# $check_var = $x
+# # $fruit contains "apples, oranges, and bananas"
+# # $check_var is undefined, as the value of $x is local to the lambda.
+# ~~~
 #
 # @since 4.0.0
 #

data/lib/puppet/functions/yaml_data.rb

@@ -0,0 +1,21 @@
+# @since 4.8.0
+#
+require 'yaml'
+
+Puppet::Functions.create_function(:yaml_data) do
+  dispatch :yaml_data do
+    param 'Struct[{path=>String[1]}]', :options
+    param 'Puppet::LookupContext', :context
+  end
+
+  def yaml_data(options, context)
+    begin
+      data = YAML.load_file(options['path'])
+      Puppet::Pops::Lookup::HieraConfig.symkeys_to_string(data.nil? ? {} : data)
+    rescue YAML::SyntaxError => ex
+      # Psych errors includes the absolute path to the file, so no need to add that
+      # to the message
+      raise Puppet::DataBinding::LookupError, "Unable to parse #{ex.message}"
+    end
+  end
+end

data/lib/puppet/functions.rb

@@ -44,7 +44,7 @@
 # When the function is called, puppet searches the signatures for one that
 # matches the supplied arguments. Each signature is part of a dispatch, which
 # specifies the method that should be called for that signature. When a
-# matching signature is found, the corrosponding method is called.
+# matching signature is found, the corresponding method is called.
 #
 # Documentation for the function should be placed as comments to the
 # implementation method(s).
@@ -153,6 +153,28 @@ module Puppet::Functions
   #
   # @api public
   def self.create_function(func_name, function_base = Function, &block)
+    # Ruby < 2.1.0 does not have method on Binding, can only do eval
+    # and it will fail unless protected with an if defined? if the local
+    # variable does not exist in the block's binder.
+    #
+    loader = block.binding.eval('loader_injected_arg if defined?(loader_injected_arg)')
+    create_loaded_function(func_name, loader, function_base, &block)
+  end
+
+  # Creates a function in, or in a local loader under the given loader.
+  # This method should only be used when manually creating functions
+  # for the sake of testing. Functions that are autoloaded should
+  # always use the `create_function` method and the autoloader will supply
+  # the correct loader.
+  #
+  # @param func_name [String, Symbol] a simple or qualified function name
+  # @param loader [Puppet::Pops::Loaders::Loader] the loader loading the function
+  # @param block [Proc] the block that defines the methods and dispatch of the
+  #   Function to create
+  # @return [Class<Function>] the newly created Function class
+  #
+  # @api public
+  def self.create_loaded_function(func_name, loader, function_base = Function, &block)
     if function_base.ancestors.none? { |s| s == Puppet::Pops::Functions::Function }
       raise ArgumentError, "Functions must be based on Puppet::Pops::Functions::Function. Got #{function_base}"
     end
@@ -162,7 +184,12 @@ module Puppet::Functions
     # The idea being that it is garbage collected when there are no more
     # references to it.
     #
-    the_class = Class.new(function_base, &block)
+    # (Do not give the class the block here, as instance variables should be set first)
+    the_class = Class.new(function_base)
+
+    unless loader.nil?
+      the_class.instance_variable_set(:'@loader', loader.private_loader)
+    end
 
     # Make the anonymous class appear to have the class-name <func_name>
     # Even if this class is not bound to such a symbol in a global ruby scope and
@@ -175,11 +202,20 @@ module Puppet::Functions
     #
     the_class.instance_eval do
       @func_name = func_name
+
       def name
         @func_name
       end
+
+      def loader
+        @loader
+      end
     end
 
+    # The given block can now be evaluated and have access to name and loader
+    #
+    the_class.class_eval(&block)
+
     # Automatically create an object dispatcher based on introspection if the
     # loaded user code did not define any dispatchers. Fail if function name
     # does not match a given method name in user code.
@@ -222,8 +258,8 @@ module Puppet::Functions
   def self.any_signature(from, to, names)
     # Construct the type for the signature
     # Tuple[Object, from, to]
-    factory = Puppet::Pops::Types::TypeFactory
-    [factory.callable(factory.any, from, to), names]
+    param_types = Puppet::Pops::Types::PTupleType.new([Puppet::Pops::Types::PAnyType::DEFAULT], Puppet::Pops::Types::PIntegerType.new(from, to))
+    [Puppet::Pops::Types::PCallableType.new(param_types), names]
   end
 
   # Function
@@ -236,9 +272,7 @@ module Puppet::Functions
 
     # @api private
     def self.builder
-      @type_parser ||= Puppet::Pops::Types::TypeParser.new
-      @all_callables ||= Puppet::Pops::Types::TypeFactory.all_callables
-      DispatcherBuilder.new(dispatcher, @type_parser, @all_callables)
+      DispatcherBuilder.new(dispatcher, Puppet::Pops::Types::TypeParser.singleton, Puppet::Pops::Types::PCallableType::DEFAULT, loader)
     end
 
     # Dispatch any calls that match the signature to the provided method name.
@@ -254,6 +288,53 @@ module Puppet::Functions
         dispatch(meth_name, &block)
       end
     end
+
+    # Allows types local to the function to be defined to ease the use of complex types
+    # in a 4.x function. Within the given block, calls to `type` can be made with a string
+    # 'AliasType = ExistingType` can be made to define aliases. The defined aliases are
+    # available for further aliases, and in all dispatchers.
+    #
+    # @since 4.5.0
+    # @api public
+    #
+    def self.local_types(&block)
+      if loader.nil?
+        raise ArgumentError, "No loader present. Call create_loaded_function(:myname, loader,...), instead of 'create_function' if running tests"
+      end
+      aliases = LocalTypeAliasesBuilder.new(loader, name)
+      aliases.instance_eval(&block)
+      # Add the loaded types to the builder
+      aliases.local_types.each do |type_alias_expr|
+        # Bind the type alias to the local_loader using the alias
+        t = Puppet::Pops::Loader::TypeDefinitionInstantiator.create_from_model(type_alias_expr, aliases.loader)
+
+        # Also define a method for convenient access to the defined type alias.
+        # Since initial capital letter in Ruby means a Constant these names use a prefix of
+        # `type`. As an example, the type 'MyType' is accessed by calling `type_MyType`.
+        define_method("type_#{t.name}") { t }
+      end
+      # Store the loader in the class
+      @loader = aliases.loader
+    end
+
+    # Creates a new function instance in the given closure scope (visibility to variables), and a loader
+    # (visibility to other definitions). The created function will either use the `given_loader` or
+    # (if it has local type aliases) a loader that was constructed from the loader used when loading
+    # the function's class.
+    #
+    # TODO: It would be of value to get rid of the second parameter here, but that would break API.
+    #
+    def self.new(closure_scope, given_loader)
+      super(closure_scope, @loader || given_loader)
+    end
+  end
+
+  # Base class for all functions implemented in the puppet language
+  class PuppetFunction < Function
+    def self.init_dispatch(a_closure)
+      # A closure is compatible with a dispatcher - they are both callable signatures
+      dispatcher.add(a_closure)
+    end
   end
 
   # Public api methods of the DispatcherBuilder are available within dispatch()
@@ -261,11 +342,14 @@ module Puppet::Functions
   #
   # @api public
   class DispatcherBuilder
+    attr_reader :loader
+
     # @api private
-    def initialize(dispatcher, type_parser, all_callables)
+    def initialize(dispatcher, type_parser, all_callables, loader)
       @type_parser = type_parser
       @all_callables = all_callables
       @dispatcher = dispatcher
+      @loader = loader
     end
 
     # Defines a required positional parameter with _type_ and _name_.
@@ -311,7 +395,25 @@ module Puppet::Functions
     #
     # @api public
     def repeated_param(type, name)
-      internal_param(type, name)
+      internal_param(type, name, true)
+      @max = :default
+    end
+    alias optional_repeated_param repeated_param
+
+    # Defines a repeated positional parameter with _type_ and _name_ that may occur 1 to "infinite" number of times.
+    # It may only appear last or just before a block parameter.
+    #
+    # @param type [String] The type specification for the parameter.
+    # @param name [Symbol] The name of the parameter. This is primarily used
+    #   for error message output and does not have to match an implementation
+    #   method parameter.
+    # @return [Void]
+    #
+    # @api public
+    def required_repeated_param(type, name)
+      internal_param(type, name, true)
+      raise ArgumentError, 'A required repeated parameter cannot be added after an optional parameter' if @min != @max
+      @min += 1
       @max = :default
     end
 
@@ -323,16 +425,14 @@ module Puppet::Functions
     def block_param(*type_and_name)
       case type_and_name.size
       when 0
-        # the type must be an independent instance since it will be contained in another type
-        type = @all_callables.copy
+        type = @all_callables
         name = :block
       when 1
-        # the type must be an independent instance since it will be contained in another type
-        type = @all_callables.copy
+        type = @all_callables
         name = type_and_name[0]
       when 2
         type_string, name = type_and_name
-        type = @type_parser.parse(type_string)
+        type = @type_parser.parse(type_string, loader)
       else
         raise ArgumentError, "block_param accepts max 2 arguments (type, name), got #{type_and_name.size}."
       end
@@ -365,10 +465,19 @@ module Puppet::Functions
       @block_type = Puppet::Pops::Types::TypeFactory.optional(@block_type)
     end
 
+    # Defines the return type. Defaults to 'Any'
+    # @param [String] type a reference to a Puppet Data Type
+    #
+    # @api public
+    def return_type(type)
+      raise ArgumentError, "Argument to 'return_type' must be a String reference to a Puppet Data Type. Got #{type.class}" unless type.is_a?(String)
+      @return_type = type
+    end
+
     private
 
     # @api private
-    def internal_param(type, name)
+    def internal_param(type, name, repeat = false)
       raise ArgumentError, 'Parameters cannot be added after a block parameter' unless @block_type.nil?
       raise ArgumentError, 'Parameters cannot be added after a repeated parameter' if @max == :default
 
@@ -380,7 +489,11 @@ module Puppet::Functions
         @types << type
         @names << name
         # mark what should be picked for this position when dispatching
-        @weaving << @names.size()-1
+        if repeat
+          @weaving << -@names.size()
+        else
+          @weaving << @names.size()-1
+        end
       else
         raise ArgumentError, "Parameter 'type' must be a String reference to a Puppet Data Type. Got #{type.class}"
       end
@@ -400,8 +513,9 @@ module Puppet::Functions
       @max = 0
       @block_type = nil
       @block_name = nil
+      @return_type = nil
       self.instance_eval &block
-      callable_t = create_callable(@types, @block_type, @min, @max)
+      callable_t = create_callable(@types, @block_type, @return_type, @min, @max)
       @dispatcher.add_dispatch(callable_t, meth_name, @names, @block_name, @injections, @weaving, @max == :default)
     end
 
@@ -411,22 +525,43 @@ module Puppet::Functions
     # Optional[Callable], Callable, or nil.
     #
     # @api private
-    def create_callable(types, block_type, from, to)
+    def create_callable(types, block_type, return_type, from, to)
       mapped_types = types.map do |t|
-        @type_parser.parse(t)
+        @type_parser.parse(t, loader)
       end
+      param_types = Puppet::Pops::Types::PTupleType.new(mapped_types, from > 0 && from == to ? nil : Puppet::Pops::Types::PIntegerType.new(from, to))
+      return_type = @type_parser.parse(return_type, loader) unless return_type.nil?
+      Puppet::Pops::Types::PCallableType.new(param_types, block_type, return_type)
+    end
+  end
 
-      if from != to
-        # :optional and/or :repeated parameters are present.
-        mapped_types << from
-        mapped_types << to
-      end
+  # The LocalTypeAliasBuilder is used by the 'local_types' method to collect the individual
+  # type aliases given by the function's author.
+  #
+  class LocalTypeAliasesBuilder
+    attr_reader :local_types, :parser, :loader
+
+    def initialize(loader, name)
+      @loader = Puppet::Pops::Loader::PredefinedLoader.new(loader, :"local_function_#{name}")
+      @local_types = []
+      # get the shared parser used by puppet's compiler
+      @parser = Puppet::Pops::Parser::EvaluatingParser.singleton()
+    end
 
-      if block_type
-        mapped_types << block_type
+    # Defines a local type alias, the given string should be a Puppet Language type alias expression
+    # in string form without the leading 'type' keyword.
+    # Calls to local_type must be made before the first parameter definition or an error will
+    # be raised.
+    #
+    # @param assignment_string [String] a string on the form 'AliasType = ExistingType'
+    # @api public
+    #
+    def type(assignment_string)
+      result = parser.parse_string("type #{assignment_string}", nil) # no file source :-(
+      unless result.body.kind_of?(Puppet::Pops::Model::TypeAlias)
+        raise ArgumentError, "Expected a type alias assignment on the form 'AliasType = T', got '#{assignment_string}'"
       end
-
-      Puppet::Pops::Types::TypeFactory.callable(*mapped_types)
+      @local_types << result.body
     end
   end
 
@@ -466,9 +601,7 @@ module Puppet::Functions
   class InternalFunction < Function
     # @api private
     def self.builder
-      @type_parser ||= Puppet::Pops::Types::TypeParser.new
-      @all_callables ||= Puppet::Pops::Types::TypeFactory.all_callables
-      InternalDispatchBuilder.new(dispatcher, @type_parser, @all_callables)
+      InternalDispatchBuilder.new(dispatcher, Puppet::Pops::Types::TypeParser.singleton, Puppet::Pops::Types::PCallableType::DEFAULT, loader)
     end
 
     # Defines class level injected attribute with reader method

data/lib/puppet/generate/models/type/property.rb

@@ -0,0 +1,70 @@
+module Puppet
+  module Generate
+    module Models
+      module Type
+        # A model for resource type properties and parameters.
+        class Property
+          # Gets the name of the property as a Puppet string literal.
+          attr_reader :name
+
+          # Gets the Puppet type of the property.
+          attr_reader :type
+
+          # Gets the doc string of the property.
+          attr_reader :doc
+
+          # Initializes a property model.
+          # @param property [Puppet::Property] The Puppet property to model.
+          # @return [void]
+          def initialize(property)
+            @name = Puppet::Pops::Types::StringConverter.convert(property.name.to_s, '%p')
+            @type = self.class.get_puppet_type(property)
+            @doc = property.doc.strip
+            @is_namevar = property.isnamevar?
+          end
+
+          # Determines if this property is a namevar.
+          # @return [Boolean] Returns true if the property is a namevar or false if not.
+          def is_namevar?
+            @is_namevar
+          end
+
+          # Gets the Puppet type for a property.
+          # @param property [Puppet::Property] The Puppet property to get the Puppet type for.
+          # @return [String] Returns the string representing the Puppet type.
+          def self.get_puppet_type(property)
+            # HACK: the value collection does not expose the underlying value information at all
+            #       thus this horribleness to get the underlying values hash
+            regexes = []
+            strings = []
+            values = property.value_collection.instance_variable_get('@values') || {}
+            values.each do |_, value|
+              if value.regex?
+                regexes << "/#{value.name.source.gsub(/\//, '\/')}/"
+                next
+              end
+
+              strings << Puppet::Pops::Types::StringConverter.convert(value.name.to_s, '%p')
+              value.aliases.each do |a|
+                strings << Puppet::Pops::Types::StringConverter.convert(a.to_s, '%p')
+              end
+            end
+
+            # If no string or regexes, default to Any type
+            return 'Any' if strings.empty? && regexes.empty?
+
+            # Calculate a variant of supported values
+            # Note that boolean strings are mapped to Variant[Boolean, Enum['true', 'false']]
+            # because of tech debt...
+            enum    = strings.empty? ? nil : "Enum[#{strings.join(', ')}]"
+            pattern = regexes.empty? ? nil : "Pattern[#{regexes.join(', ')}]"
+            boolean = strings.include?('\'true\'') || strings.include?('\'false\'') ? 'Boolean' : nil
+            variant = [boolean, enum, pattern].reject { |t| t.nil? }
+            return variant[0] if variant.size == 1
+            "Variant[#{variant.join(', ')}]"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/puppet/generate/models/type/type.rb

@@ -0,0 +1,61 @@
+require 'puppet/generate/models/type/property'
+
+module Puppet
+  module Generate
+    module Models
+      module Type
+        # A model for Puppet resource types.
+        class Type
+          # Gets the name of the type as a Puppet string literal.
+          attr_reader :name
+
+          # Gets the doc string of the type.
+          attr_reader :doc
+
+          # Gets the properties of the type.
+          attr_reader :properties
+
+          # Gets the parameters of the type.
+          attr_reader :parameters
+
+          # Gets the title patterns of the type
+          attr_reader :title_patterns
+
+          # Gets the isomorphic member attribute of the type
+          attr_reader :isomorphic
+
+          # Gets the capability member attribute of the type
+          attr_reader :capability
+
+          # Initializes a type model.
+          # @param type [Puppet::Type] The Puppet type to model.
+          # @return [void]
+          def initialize(type)
+            @name = Puppet::Pops::Types::StringConverter.convert(type.name.to_s, '%p')
+            @doc = type.doc.strip
+            @properties = type.properties.map { |p| Property.new(p) }
+            @parameters = type.parameters.map do |name|
+              Property.new(type.paramclass(name))
+            end
+            @title_patterns = Hash[type.title_patterns.map do |mapping|
+              [
+                "/#{mapping[0].source.gsub(/\//, '\/')}/",
+                mapping[1].map { |names|
+                  next if names.empty?
+                  raise Puppet::Error, 'title patterns that use procs are not supported.' if names.size != 1
+                  Puppet::Pops::Types::StringConverter.convert(names[0].to_s, '%p')
+                }
+              ]
+            end]
+            @isomorphic = type.isomorphic?
+            @capability = type.is_capability?
+          end
+
+          def render(template)
+            template.result(binding)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/puppet/generate/templates/type/pcore.erb

@@ -0,0 +1,42 @@
+# This file was automatically generated on <%= Time.now %>.
+# Use the 'puppet generate types' command to regenerate this file.
+
+<%- unless doc.empty? -%>
+  <%- doc.each_line do |line| -%>
+# <%= line -%>
+  <%- end %>
+<%- end -%>
+Puppet::Resource::ResourceType3.new(
+  <%= name %>,
+  [
+<%- properties.each_with_index do |property, index| -%>
+  <%- unless property.doc.empty? -%>
+    <%- property.doc.each_line do |line| -%>
+    # <%= line -%>
+    <%- end %>
+  <%- end -%>
+    Puppet::Resource::Param(<%= property.type %>, <%= property.name %><% if property.is_namevar? %>, true<% end %>)<% if index + 1 < properties.size %>,
+
+    <%- end -%>
+<%- end %>
+  ],
+  [
+<%- parameters.each_with_index do |parameter, index| -%>
+  <%- unless parameter.doc.empty? -%>
+    <%- parameter.doc.each_line do |line| -%>
+    # <%= line -%>
+    <%- end %>
+  <%- end -%>
+    Puppet::Resource::Param(<%= parameter.type %>, <%= parameter.name %><% if parameter.is_namevar? %>, true<% end %>)<% if index + 1 < parameters.size %>,
+
+    <%- end -%>
+<%- end %>
+  ],
+  {
+<%- title_patterns.each_with_index do |mapping, index| -%>
+    <%= mapping[0] %> => [<%= mapping[1].join(', ')%>]<%= "," if index + 1 < title_patterns.size %>
+<%- end -%>
+  },
+  <%= isomorphic -%>,
+  <%= capability -%>
+)