puppet 4.5.3-universal-darwin → 4.6.1-universal-darwin

data/lib/puppet/functions/reverse_each.rb

@@ -1,62 +1,5 @@
-# Reverses the order of the elements of something that is iterable and optionally runs a
-# [lambda](http://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html) for each
-# element.
-#
-# This function takes one to two arguments.
-#
-# 1. An `Iterable` that the function will iterate over.
-# 2. An optional lambda, which the function calls for each element in the first argument. It must
-# request one parameter.
-#
-# @example Using the `reverse_each` function
-#
-# `$data.reverse_each |$parameter| { <PUPPET CODE BLOCK> }`
-#
-# or
-#
-# `$reverse_data = $data.reverse_each`
-#
-# or
-#
-# `reverse_each($data) |$parameter| { <PUPPET CODE BLOCK> }`
-#
-# or
-#
-# `$reverse_data = reverse_each($data)`
-#
-# When no second argument is present, Puppet returns an `Iterable` that represents the reverse
-# order of its first argument. This allows methods on `Iterable` to be chained.
-#
-# When a lamdba is given as the second argument, Puppet iterates the first argument in reverse
-# order and passes each value in turn to the lambda, then returns `undef`.
-#
-# @example Using the `reverse_each` function with an array and a one-parameter lambda
-#
-# ~~~ puppet
-# # Puppet will log a notice for each of the three items in $data in reverse order.
-# $data = [1,2,3]
-# $data.reverse_each |$item| { notice($item) }
-#
-# ~~~
-#
-# When no second argument is present, Puppet returns a new `Iterable` which allows it to
-# be directly chained into another function that takes an `Iterable` as an argument.
-#
-# @example Using the `reverse_each` function chained with a `map` function.
-#
-# # For the array $data, return an array containing each value multiplied by 10 in reverse order
-# $data = [1,2,3]
-# $transformed_data = $data.reverse_each.map |$item| { $item * 10 }
-# # $transformed_data is set to [30,20,10]
-# ~~~
-#
-# @example The same example using `reverse_each` function chained with a `map` in alternative syntax
-#
-# # For the array $data, return an array containing each value multiplied by 10 in reverse order
-# $data = [1,2,3]
-# $transformed_data = map(reverse_each($data)) |$item| { $item * 10 }
-# # $transformed_data is set to [30,20,10]
-# ~~~
+# Reverses the order of the elements of something that is iterable.
+# (Documentation in 3.x stub)
 #
 # @since 4.4.0
 #

data/lib/puppet/functions/scanf.rb

@@ -1,11 +1,11 @@
 # Scans a string and returns an array of one or more converted values based on the given format string.
-# See the documenation of Ruby's String#scanf method for details about the supported formats (which
+# See the documentation of Ruby's String#scanf method for details about the supported formats (which
 # are similar but not identical to the formats used in Puppet's `sprintf` function.)
 #
 # This function takes two mandatory arguments: the first is the string to convert, and the second is
-# the format string. The result of the scan is an array, with each sucessfully scanned and transformed value.
-# The scanning stops if a scan is unsuccesful, and the scanned result up to that point is returned. If there
-# was no succesful scan, the result is an empty array.
+# the format string. The result of the scan is an array, with each successfully scanned and transformed value.
+# The scanning stops if a scan is unsuccessful, and the scanned result up to that point is returned. If there
+# was no successful scan, the result is an empty array.
 #
 #    "42".scanf("%i")
 #

data/lib/puppet/functions/step.rb

@@ -1,66 +1,4 @@
-# Provides stepping with given interval over elements in an iterable and optionally runs a
-# [lambda](http://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html) for each
-# element.
-#
-# This function takes two to three arguments.
-#
-# 1. An 'Iterable' that the function will iterate over.
-# 2. An `Integer` step factor. This must be a positive integer.
-# 3. An optional lambda, which the function calls for each element in the interval. It must
-# request one parameter.
-#
-# @example Using the `step` function
-#
-# `$data.step(<n>) |$parameter| { <PUPPET CODE BLOCK> }`
-#
-# or
-#
-# `$stepped_data = $data.step(<n>)`
-#
-# or
-#
-# `step($data, <n>) |$parameter| { <PUPPET CODE BLOCK> }`
-#
-# or
-#
-# `$stepped_data = step($data, <n>)`
-#
-# When no block is given, Puppet returns an `Iterable` that yields the first element and every nth successor
-# element, from its first argument. This allows functions on iterables to be chained.
-#
-# When a block is given, Puppet iterates and calls the block with the first element and then with
-# every nth successor element. It then returns `undef`.
-#
-# @example Using the `step` function with an array, a step factor, and a one-parameter block
-#
-# ~~~ puppet
-# # For the array $data, call a block with the first element and then with each 3rd successor element
-# $data = [1,2,3,4,5,6,7,8]
-# $data.step(3) |$item| {
-#  notice($item)
-# }
-# # Puppet notices the values '1', '4', '7'.
-# ~~~
-#
-# When no block is given, Puppet returns a new `Iterable` which allows it to be directly chained into
-# another function that takes an `Iterable` as an argument.
-#
-# @example Using the `step` function chained with a `map` function.
-#
-# # For the array $data, return an array, set to the first element and each 5th successor element, in reverse
-# # order multiplied by 10
-# $data = Integer[0,20]
-# $transformed_data = $data.step(5).map |$item| { $item * 10 }
-# # $transformed_data contains [0,50,100,150,200]
-# ~~~
-#
-# @example The same example using `step` function chained with a `map` in alternative syntax
-#
-# # For the array $data, return an array, set to the first and each 5th successor, in reverse order, multiplied by 10
-# $data = Integer[0,20]
-# $transformed_data = map(step($data, 5)) |$item| { $item * 10 }
-# # $transformed_data contains [0,50,100,150,200]
-# ~~~
+# (Documentation in 3.x stub)
 #
 # @since 4.4.0
 #

data/lib/puppet/functions/then.rb

@@ -1,64 +1,4 @@
-# Call a [lambda](https://docs.puppet.com/puppet/latest/reference/lang_lambdas.html)
-# with the given argument unless the argument is undef. Return undef if argument is
-# undef, and otherwise the result of giving the argument to the lambda.
-#
-# This is useful to process a sequence of operations where an intermediate
-# result may be undef (which makes the entire sequence undef).
-# The `then` function is especially useful with the function `dig` which
-# performs in a similar way "digging out" a value in a complex structure.
-#
-# @example Using `then`
-#
-# ~~~ puppet
-# $data = {a => { b => [{x => 10, y => 20}, {x => 100, y => 200}]}}
-# notice $data.dig(a, b, 1, x).then |$x| { $x * 2 }
-# ~~~
-#
-# Would notice the value 200
-#
-# Contrast this with:
-#
-# ~~~ puppet
-# $data = {a => { b => [{x => 10, y => 20}, {ex => 100, why => 200}]}}
-# notice $data.dig(a, b, 1, x).then |$x| { $x * 2 }
-# ~~~
-#
-# Which would notice undef since the last lookup of 'x' results in `undef` which
-# is returned (without calling the block).
-#
-# As a result there was no need for conditional logic or a temporary (non local) 
-# variable as the result is now either the wanted value (x) multiplied
-# by 2 or `undef`.
-#
-# Calls to `then` can be chained. In the next example, a structure is using an offset that
-# is using 1 as the index to the first element (instead of 0 which is used in the language).
-# We are not sure if user input actually contains an index at all, or if it is
-# outside the range of available names.
-#
-# ~~~ puppet
-# # Names to choose from
-# $names = ['Ringo', 'Paul', 'George', 'John']
-#
-# # structure where 'beatle 2' is wanted (but where the number refers
-# # to 'Paul' because input comes from a source using 1 for the first
-# # element).
-#
-# $data = [202, { beatle => 2 }]
-# $picked = assert_type(String,
-#   # the data we are interested in is the second in the array,
-#   # a hash, where we want the value of the key 'beatle'
-#   $data.dig(1, 'beatle')
-#     # and we want the index in $names before the given index
-#     .then |$x| { $names[$x-1] }
-#     # so we can construct a string with that beatle's name
-#     .then |$x| { "Picked Beatle '${x}'" }
-# )
-#
-# ~~~ puppet
-#
-# Would notice "Picked Beatle 'Paul'", and would raise an error if the result
-# was not a String.
-#
+# (Documented in 3.x stub)
 # @since 4.5.0
 #
 Puppet::Functions.create_function(:then) do

data/lib/puppet/functions/type.rb

@@ -1,43 +1,4 @@
-# Returns the data type of a given value with a given degree of generality.
-#
-# @example Using `type()`
-#
-# ~~~ puppet
-# notice type(42) =~ Type[Integer]
-# ~~~
-#
-# Would notice true
-#
-# By default, the best possible inference is made where all details are retained.
-# This is good when the type is used for further type calculations but is overwhelmingly
-# rich in information if it is used in a error message.
-#
-# The optional argument `inference_method` may be given as (from lowest to highest fidelity):
-#
-# * `generalized` - reduces to common type and drops size constraints
-# * `reduced` - reduces to common type in collections
-# * `detailed` - (default) all details about inferred types is retained
-#
-# @example Using `type()` with different qualities:
-#
-# ~~~ puppet
-# notice type([3.14, 42], generalized)
-# notice type([3.14, 42], reduced)
-# notice type([3.14, 42], detailed)
-# notice type([3.14, 42])
-# ~~~
-#
-# Would notice the four values:
-#
-# 1. 'Array[Numeric]'
-# 2. 'Array[Numeric, 2, 2]'
-# 3. 'Tuple[Float[3.14], Integer[42,42]]]'
-# 4. 'Tuple[Float[3.14], Integer[42,42]]]'
-#
-# @param value [Any] - the value for which data type is returned
-# @param inference_type[Enum[generalized, reduced, detailed]] inference_type
-# @returns [Type] - the inferred type
-#
+# (Documentation in 3.x stub)
 # @since 4.4.0
 #
 Puppet::Functions.create_function(:type) do

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/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,57 @@
+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
+
+          # 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?
+          end
+
+          def render(template)
+            template.result(binding)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# 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 -%>
+)