puppet 4.3.1 → 4.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bbb3d1b7ae680827054a63fb3fe802e44769a0b2
-  data.tar.gz: c63a7977ba8f1c7440fee55996b907b87b9b01a7
+  metadata.gz: 60bac673f74c2536d8b6cabef95b12f681870b0b
+  data.tar.gz: c2ec8ac4a44a646e7107c77c8c2a3369bb539069
 SHA512:
-  metadata.gz: bb2e66fdd215d9fa2494211c9332e20fb1447be490a92c1093b280688f5e37c5b674751ee506089583c7446376af9ce20665df1e6010b67686c3b4c845746b8c
-  data.tar.gz: 14e69b0c2ccfa644196413e815c77ccf9c09c15628c821b9a73eb8ee2a9d315814acedd606ebf1ed94d2fa4276d5404514e0dad191f8b1384cf25886080c3b9e
+  metadata.gz: 56de86472279f036aa8909f2ff792bb5f9dff0ad77067d096a497d3fe48949386a60cebd02bf8b5d71757083ca1263203f590610f6e296742f7779e7fbeadd7f
+  data.tar.gz: 456955eeee0d45ee397618a4e5934f7c77bf37f278d4346b2a6bfcf9d8a3e4a941c3402bc605f252faf0212e3008953d55686dd091c33b0dbb61994ca0447a44

data/ext/build_defaults.yaml

@@ -14,7 +14,7 @@ build_dmg: FALSE
 sign_tar: FALSE
 yum_host: 'yum.puppetlabs.com'
 yum_repo_path: '/opt/repository/yum/'
-apt_host: 'apt.puppetlabs.com'
+apt_signing_server: 'apt.puppetlabs.com'
 apt_repo_url: 'http://apt.puppetlabs.com'
 apt_repo_path: '/opt/repository/incoming'
 tar_host: 'downloads.puppetlabs.com'

data/lib/hiera/scope.rb

@@ -33,7 +33,7 @@ class Hiera
       if [CALLING_CLASS, CALLING_CLASS_PATH, CALLING_MODULE].include? key
         true
       else
-        @real.lookupvar(key) != ""
+        @real.exist?(key)
       end
     end
 

data/lib/puppet/application/lookup.rb

@@ -12,11 +12,7 @@ class Puppet::Application::Lookup < Puppet::Application
 
   # Options for lookup
   option('--merge TYPE') do |arg|
-    if %w{unique hash deep}.include?(arg)
-      options[:merge] = arg
-    else
-      raise "The --merge option only accepts 'unique', 'hash', or 'deep'.\n#{RUN_HELP}"
-    end
+    options[:merge] = arg
   end
 
   option('--debug', '-d')
@@ -31,6 +27,8 @@ class Puppet::Application::Lookup < Puppet::Application
     options[:type] = arg
   end
 
+  option('--compile', '-c')
+
   option('--knock-out-prefix PREFIX_STRING') do |arg|
     options[:prefix] = arg
   end
@@ -45,6 +43,8 @@ class Puppet::Application::Lookup < Puppet::Application
 
   option('--explain')
 
+  option('--explain-options')
+
   option('--default VALUE') do |arg|
     options[:default_value] = arg
   end
@@ -96,31 +96,6 @@ class Puppet::Application::Lookup < Puppet::Application
     Puppet::FileBucket::File.indirection.terminus_class = :file
   end
 
-  def setup_ssl
-    # Configure all of the SSL stuff.
-    if Puppet::SSL::CertificateAuthority.ca?
-      Puppet::SSL::Host.ca_location = :local
-      Puppet.settings.use :ca
-      Puppet::SSL::CertificateAuthority.instance
-    else
-      Puppet::SSL::Host.ca_location = :none
-    end
-    # These lines are not on stable (seems like a copy was made from master)
-    #
-    # Puppet::SSL::Oids.register_puppet_oids
-    # Puppet::SSL::Oids.load_custom_oid_file(Puppet[:trusted_oid_mapping_file])
-  end
-
-  # Sets up a special node cache "write only yaml" that collects and stores node data in yaml
-  # but never finds or reads anything (this since a real cache causes stale data to be served
-  # in circumstances when the cache can not be cleared).
-  # @see puppet issue 16753
-  # @see Puppet::Node::WriteOnlyYaml
-  # @return [void]
-  def setup_node_cache
-    Puppet::Node.indirection.cache_class = Puppet[:node_cache_terminus]
-  end
-
   def setup
     setup_logs
 
@@ -129,11 +104,6 @@ class Puppet::Application::Lookup < Puppet::Application
     Puppet.settings.use :main, :master, :ssl, :metrics
 
     setup_terminuses
-
-    # TODO: Do we need this in lookup? It sets up a write only cache
-    setup_node_cache
-
-    setup_ssl
   end
 
   def help
@@ -156,6 +126,7 @@ puppet lookup [--help] [--type <TYPESTRING>] [--merge unique|hash|deep]
   [--knock-out-prefix <PREFIX-STRING>] [--sort-merged-arrays]
   [--unpack-arrays <STRING-VALUE>] [--merge-hash-arrays] [--explain]
   [--default <VALUE>] [--node <NODE-NAME>] [--facts <FILE>]
+  [--compile]
   [--render-as s|json|yaml|binary|msgpack] <keys>
 
 DESCRIPTION
@@ -214,6 +185,10 @@ the puppet lookup function linked to above.
   than the value returned for the key. The explaination will describe how
   the result was obtained or why lookup failed to obtain the result.
 
+* --explain-options
+  Explain if a lookup_options hash will be used and how it was assembled
+  when performing a lookup.
+
 * --default <VALUE>
   A value produced if no value was found in the lookup.
 
@@ -227,6 +202,11 @@ the puppet lookup function linked to above.
   override the facts for the current node. Any facts not specified by the
   user will maintain their original value.
 
+* --compile
+  Perform a full catalog compilation prior to the lookup. This is meaningful when
+  the catalog changes global variables that are referenced in interpolated values.
+  No catalog compilation takes place unless this flag is given.
+
 * --render-as s|json|yaml|binary|msgpack
   Determines how the results will be rendered to the standard output where
   s means plain text. The default when lookup is producing a value is yaml
@@ -266,7 +246,6 @@ Copyright (c) 2015 Puppet Labs, LLC Licensed under the Apache 2.0 License
 
   def main
     keys = command_line.args
-    raise 'No keys were given to lookup.' if keys.empty?
 
     #unless options[:node]
     #  raise "No node was given via the '--node' flag for the scope of the lookup.\n#{RUN_HELP}"
@@ -279,8 +258,15 @@ Copyright (c) 2015 Puppet Labs, LLC Licensed under the Apache 2.0 License
     use_default_value = !options[:default_value].nil?
     merge_options = nil
 
-    if options[:merge]
-      if options[:merge] == 'deep'
+    merge = options[:merge]
+    unless merge.nil?
+      strategies = Puppet::Pops::MergeStrategy.strategy_keys
+      unless strategies.include?(merge.to_sym)
+        strategies = strategies.map {|k| "'#{k}'"}
+        raise "The --merge option only accepts #{strategies[0...-1].join(', ')}, or #{strategies.last}\n#{RUN_HELP}"
+      end
+
+      if merge == 'deep'
         merge_options = {'strategy' => 'deep',
           'sort_merge_arrays' => !options[:sort_merge_arrays].nil?,
           'merge_hash_arrays' => !options[:merge_hash_arrays].nil?}
@@ -294,11 +280,22 @@ Copyright (c) 2015 Puppet Labs, LLC Licensed under the Apache 2.0 License
         end
 
       else
-        merge_options = {'strategy' => options[:merge]}
+        merge_options = {'strategy' => merge}
       end
     end
 
-    explain = !!options[:explain]
+    explain_data = !!options[:explain]
+    explain_options = !!options[:explain_options]
+    only_explain_options = explain_options && !explain_data
+    if keys.empty?
+      if only_explain_options
+        # Explain lookup_options for lookup of an unqualified value.
+        keys = Puppet::Pops::Lookup::GLOBAL
+      else
+        raise 'No keys were given to lookup.'
+      end
+    end
+    explain = explain_data || explain_options
 
     # Format defaults to text (:s) when producing an explanation and :yaml when producing the value
     format = options[:render_as] || (explain ? :s : :yaml)
@@ -308,7 +305,7 @@ Copyright (c) 2015 Puppet Labs, LLC Licensed under the Apache 2.0 License
     type = options.include?(:type) ? Puppet::Pops::Types::TypeParser.new.parse(options[:type]) : nil
 
     generate_scope do |scope|
-      lookup_invocation = Puppet::Pops::Lookup::Invocation.new(scope, {}, {}, explain)
+      lookup_invocation = Puppet::Pops::Lookup::Invocation.new(scope, {}, {}, explain ? Puppet::Pops::Lookup::Explainer.new(explain_options, only_explain_options) : nil)
       begin
         result = Puppet::Pops::Lookup.lookup(keys, type, options[:default_value], use_default_value, merge_options, lookup_invocation)
         puts renderer.render(result) unless explain
@@ -336,7 +333,7 @@ Copyright (c) 2015 Puppet Labs, LLC Licensed under the Apache 2.0 License
     fact_file = options[:fact_file]
 
     if fact_file
-      original_facts = node.facts.values
+      original_facts = node.parameters
       if fact_file.end_with?("json")
         given_facts = JSON.parse(File.read(fact_file))
       else
@@ -347,9 +344,10 @@ Copyright (c) 2015 Puppet Labs, LLC Licensed under the Apache 2.0 License
         raise "Incorrect formatted data in #{fact_file} given via the --facts flag"
       end
 
-      node.facts.values = original_facts.merge(given_facts)
+      node.parameters = original_facts.merge(given_facts)
     end
 
+    Puppet[:code] = 'undef' unless options[:compile]
     compiler = Puppet::Parser::Compiler.new(node)
     compiler.compile { |catalog| yield(compiler.topscope); catalog }
   end

data/lib/puppet/data_providers/lookup_adapter.rb

@@ -3,7 +3,9 @@
 #
 class Puppet::DataProviders::LookupAdapter < Puppet::DataProviders::DataAdapter
 
-  LOOKUP_OPTIONS = 'lookup_options'.freeze
+  LOOKUP_OPTIONS = Puppet::Pops::Lookup::LOOKUP_OPTIONS
+  LOOKUP_OPTIONS_PREFIX = LOOKUP_OPTIONS + '.'
+  LOOKUP_OPTIONS_PREFIX.freeze
   HASH = 'hash'.freeze
   MERGE = 'merge'.freeze
 
@@ -29,12 +31,43 @@ class Puppet::DataProviders::LookupAdapter < Puppet::DataProviders::DataAdapter
   # @throws :no_such_key if the given key is not found
   #
   def lookup(key, lookup_invocation, merge)
-    merge = lookup_merge_options(key, lookup_invocation) if merge.nil?
-    merge_strategy = Puppet::Pops::MergeStrategy.strategy(merge)
-    lookup_invocation.with(:merge, merge_strategy) do
-      result = merge_strategy.merge_lookup([:lookup_global, :lookup_in_environment, :lookup_in_module]) { |m| send(m, key, lookup_invocation, merge_strategy) }
-      lookup_invocation.report_result(result)
-      result
+    # The 'lookup_options' key is reserved and not found as normal data
+    if key == LOOKUP_OPTIONS || key.start_with?(LOOKUP_OPTIONS_PREFIX)
+      lookup_invocation.with(:invalid_key, LOOKUP_OPTIONS) do
+        throw :no_such_key
+      end
+    end
+
+    lookup_invocation.top_key ||= key
+    merge_explained = false
+    if lookup_invocation.explain_options?
+      catch(:no_such_key) do
+        module_name = extract_module_name(key) unless key == Puppet::Pops::Lookup::GLOBAL
+        lookup_invocation.module_name = module_name
+        if lookup_invocation.only_explain_options?
+          do_lookup(LOOKUP_OPTIONS, lookup_invocation, HASH)
+          return nil
+        end
+
+        # Bypass cache and do a "normal" lookup of the lookup_options
+        lookup_invocation.with(:meta, LOOKUP_OPTIONS) do
+          key_options = do_lookup(LOOKUP_OPTIONS, lookup_invocation, HASH)[key]
+          merge = key_options[MERGE] unless key_options.nil?
+          merge_explained = true
+        end
+      end
+    elsif merge.nil?
+      # Used cached lookup_options
+      merge = lookup_merge_options(key, lookup_invocation)
+      lookup_invocation.report_merge_source('lookup_options') unless merge.nil?
+    end
+
+    if merge_explained
+      # Merge lookup is explained in detail so we need to explain the data in a section
+      # on the same level to avoid confusion
+      lookup_invocation.with(:data, key) { do_lookup(key, lookup_invocation, merge) }
+    else
+      do_lookup(key, lookup_invocation, merge)
     end
   end
 
@@ -44,13 +77,15 @@ class Puppet::DataProviders::LookupAdapter < Puppet::DataProviders::DataAdapter
     lookup_invocation.with(:global, terminus) do
       catch(:no_such_key) do
         return lookup_invocation.report_found(name, Puppet::DataBinding.indirection.find(name,
-            { :environment => @env.to_s, :variables => lookup_invocation.scope, :merge => merge_strategy }))
+            { :environment => @env, :variables => lookup_invocation.scope, :merge => merge_strategy }))
       end
       lookup_invocation.report_not_found(name)
       throw :no_such_key
     end
-  rescue Puppet::DataBinding::LookupError => e
-    raise Puppet::Error.new("Error from DataBinding '#{terminus}' while looking up '#{name}': #{e.message}", e)
+  rescue Puppet::DataBinding::LookupError => detail
+    error = Puppet::Error.new("Lookup of key '#{lookup_invocation.top_key}' failed: #{detail.message}")
+    error.set_backtrace(detail.backtrace)
+    raise error
   end
 
   # @api private
@@ -60,7 +95,7 @@ class Puppet::DataProviders::LookupAdapter < Puppet::DataProviders::DataAdapter
 
   # @api private
   def lookup_in_module(name, lookup_invocation, merge_strategy)
-    module_name = extract_module_name(name)
+    module_name = lookup_invocation.module_name || extract_module_name(name)
 
     # Do not attempt to do a lookup in a module unless the name is qualified.
     throw :no_such_key if module_name.nil?
@@ -95,41 +130,52 @@ class Puppet::DataProviders::LookupAdapter < Puppet::DataProviders::DataAdapter
     module_name = extract_module_name(name)
 
     # Retrieve the options for the module. We use nil as a key in case we have none
-    options = @lookup_options[module_name]
-    if options.nil? && !@lookup_options.include?(module_name)
+    if !@lookup_options.include?(module_name)
       options = retrieve_lookup_options(module_name, lookup_invocation, Puppet::Pops::MergeStrategy.strategy(HASH))
       raise Puppet::DataBinding::LookupError.new("value of #{LOOKUP_OPTIONS} must be a hash") unless options.nil? || options.is_a?(Hash)
       @lookup_options[module_name] = options
+    else
+      options = @lookup_options[module_name]
     end
     options.nil? ? nil : options[name]
   end
 
   private
 
+  def do_lookup(key, lookup_invocation, merge)
+    merge_strategy = Puppet::Pops::MergeStrategy.strategy(merge)
+    lookup_invocation.with(:merge, merge_strategy) do
+      result = merge_strategy.merge_lookup([:lookup_global, :lookup_in_environment, :lookup_in_module]) { |m| send(m, key, lookup_invocation, merge_strategy) }
+      lookup_invocation.report_result(result)
+      result
+    end
+  end
+
   # Retrieve lookup options that applies when using a specific module (i.e. a merge of the pre-cached
   # `env_lookup_options` and the module specific data)
   def retrieve_lookup_options(module_name, lookup_invocation, merge_strategy)
-    lookup_invocation.with(:meta, module_name) do
-      env_opts = env_lookup_options(lookup_invocation, merge_strategy)
-      options = nil
-      unless module_name.nil?
-        catch(:no_such_key) do
-          options = module_provider(module_name).lookup(LOOKUP_OPTIONS, lookup_invocation, merge_strategy)
-          options = merge_strategy.merge(env_opts, options) unless env_opts.nil?
-        end
+    meta_invocation = Puppet::Pops::Lookup::Invocation.new(lookup_invocation.scope)
+    meta_invocation.top_key = lookup_invocation.top_key
+    env_opts = env_lookup_options(meta_invocation, merge_strategy)
+    unless module_name.nil? || @env.module(module_name).nil?
+      catch(:no_such_key) do
+        meta_invocation.module_name = module_name
+        options = module_provider(module_name).lookup(LOOKUP_OPTIONS, meta_invocation, merge_strategy)
+        options = merge_strategy.merge(env_opts, options) unless env_opts.nil?
+        return options
       end
-      options.nil? ? env_opts : options
     end
+    env_opts
   end
 
   # Retrieve and cache lookup options specific to the environment that this adapter is attached to (i.e. a merge
   # of global and environment lookup options).
-  def env_lookup_options(lookup_invocation, merge_strategy)
-    unless instance_variable_defined?(:@env_lookup_options)
+  def env_lookup_options(meta_invocation, merge_strategy)
+    if !instance_variable_defined?(:@env_lookup_options)
       @env_lookup_options = nil
       catch(:no_such_key) do
         @env_lookup_options = merge_strategy.merge_lookup([:lookup_global, :lookup_in_environment]) do |m|
-          send(m, LOOKUP_OPTIONS, lookup_invocation, merge_strategy)
+          send(m, LOOKUP_OPTIONS, meta_invocation, merge_strategy)
         end
       end
     end
@@ -170,7 +216,8 @@ class Puppet::DataProviders::LookupAdapter < Puppet::DataProviders::DataAdapter
     unless provider
       raise Puppet::Error.new("Environment '#{@env.name}', cannot find module_data_provider '#{provider_name}'")
     end
-    provider
+    # Provider is configured per module but cached using environment life cycle so it must be cloned
+    provider.clone
   end
 
   def initialize_env_provider

data/lib/puppet/functions/lookup.rb

@@ -1,153 +1,129 @@
-# Looks up data defined using Data Binding, and Data Providers using different strategies. The lookup searches in
-# Data Bindings first (if configured; typically Hiera), then in the environments data provider (if any), and last in
-# the module's data provider (if any) of the module the call to lookup originates from. Thus, the global Data Binding
-# has higher priority than data provided in the environment, which has higher priority than data provided in a module,
-#
-# The lookup function can be called in one of these ways:
-#
-#     lookup(name)
-#     lookup(name, value_type)
-#     lookup(name, value_type, merge)
-#     lookup(name, value_type, merge, default_value)
-#     lookup(options_hash)
-#     lookup(name, options_hash)
-#
-# The function may optionally be called with a code block / lambda with the following signature:
-#
-#     lookup(...) |$name| { ... }
-#
-# The block, if present, is mutually exclusive to the `default_value` and will be called with the `name` used in the
-# lookup when no value is found. The value produced by the block then becomes the value produced by the lookup.
-#
-# The meaning of the parameters or content of the options hash is:
-#
-# * `name` - The name or array of names to lookup (first found is returned)
-# * `value_type` - The type to assert. Defaults to 'Data' See 'Type Specification' below.
-# * `default_value` - The default value if there was no value found (must comply with the data type)
-# * `override` - a hash with map from names to values that are used instead of the underlying bindings. If the name
-#   is found here it wins. Defaults to an empty hash.
-# * `default_values_hash` - a hash with map from names to values that are used as a last resort to obtain a value.
-#   Defaults to an empty hash.
-# * `merge` - A string of type Enum[unique, hash, merge] or a hash with the key 'strategy' set to that string. See
-#   'Merge Strategies' below.
-#
-# It is not permitted to pass the `name` as both a parameter and in the options hash.
-#
-# The search will proceed as follows:
-# 1. For each name given in the `name` array (or once, if it's just one name):
-#   - If a matching key is found in the `override` hash, it's value is immediately type checked and returned
-#   - Search and optionally merge Data Binding, environment data providers, and module data providers
-#   - Type check and return the value if a matching key is found
-# 2. For each name given in the `name` array (or once, if it's just one name):
-#   - Type check and return the value if a matching key is found in the `default_values_hash`
-# 3. Type check and return either the given `default_value` or the result of calling the code block if either exist
-# 4. Raise an error indicating that no matching value was found
-#
-# *Merge Strategies*
-#
-# The default behavior of the lookup is to return the first value that is found for the given `name`. The optional
-# `merge` parameter will change this so that a lookup makes an attempt to find values in all three sources (the Data
-# Binder, the environment, and the module scope) and then merge these values according to the given strategy. This
-# does not apply to values found in the 'override' hash. Such values are returned immediately without merging.
-# Note that `merge` is passed on to allow the underlying provider to return a merged result
-#
-# The valid strategies are:
-#  - 'hash' Performs a simple hash-merge by overwriting keys of lower lookup priority. Merged values must be of Hash type
-#  - 'unique' Appends everything to an array containing no nested arrays and where all duplicates have been removed. Can
-#    append values of Scalar or Array[Scalar] type
-#  - 'deep' Performs a deep merge on values of Array and Hash type. See documentation for the DeepMerge gem's deep_merge
-#    operation for details and options.
-#
-# The 'deep' strategy can use additional options to control its behavior. Options can be passed as top level
-# keys in the `merge` parameter when it is a given as a hash. Recognized options are:
-#  - 'knockout_prefix' Set to string value to signify prefix which deletes elements from existing element. Defaults is _undef_
-#  - 'sort_merged_arrays' Set to _true_ to sort all arrays that are merged together. Default is _false_
-#  - 'unpack_arrays' Set to string value used as a deliminator to join all array values and then split them again. Default is _undef_
-#  - 'merge_hash_arrays' Set to _true_ to merge hashes within arrays. Default is _false_
-#
-# *Type Specification*
-#
-# The type specification is a type in the Puppet Type System, e.g.:
-#   * `Integer`, an integral value with optional range e.g.:
-#     * `Integer[0, default]` - 0 or positive
-#     * `Integer[default, -1]` - negative,
-#     * `Integer[1,100]` - value between 1 and 100 inclusive
-#   * `String`- any string
-#   * `Float` - floating point number (same signature as for Integer for `Integer` ranges)
-#   * `Boolean` - true of false (strict)
-#   * `Array` - an array (of Data by default), or parameterized as `Array[<element_type>]`, where
-#     `<element_type>` is the expected type of elements
-#   * `Hash`,  - a hash (of default `Literal` keys and `Data` values), or parameterized as
-#     `Hash[<value_type>]`, `Hash[<key_type>, <value_type>]`, where `<key_type>`, and
-#     `<value_type>` are the types of the keys and values respectively
-#     (key is `Literal` by default).
-#   * `Data` - abstract type representing any `Literal` (including _undef_), `Array[Data]`, or `Hash[Literal, Data]`
-#   * `Pattern[<p1>, <p2>, ..., <pn>]` - an enumeration of valid patterns (one or more) where
-#      a pattern is a regular expression string or regular expression,
-#      e.g. `Pattern['.com$', '.net$']`, `Pattern[/[a-z]+[0-9]+/]`
-#   * `Enum[<s1>, <s2>, ..., <sn>]`, - an enumeration of exact string values (one or more)
-#      e.g. `Enum[blue, red, green]`.
-#   * `Variant[<t1>, <t2>,...<tn>]` - matches one of the listed types (at least one must be given)
-#     e.g. `Variant[Integer[8000,8999], Integer[20000, 99999]]` to accept a value in either range
-#   * `Regexp`- a regular expression (i.e. the result is a regular expression, not a string
-#      matching a regular expression).
-#
-# For more options and details about types, see the Puppet Language Reference
-#
-# *Handling of undef*
-#
-# When no match is found for the given `name` when searching all sources, (including the `override`and
-# `default_values_hash`), then the value used is either the `default_value` or the value produced by the given block.
-# If neither is provided, then the lookup will always raise an error. Note that this only applies when there's no
-# match for the given `name`. It does not happen when a value is found and that value happens to be _undef_.
-#
-# *Validation of returned value*
-#
-# The produced value is subject to type validation using the `value_type` (if given) and an error is raised unless
-# the resulting value is of correct type.
-#
-# *Examples*
-#
-# When called with one argument; **the name**, it
-# returns the bound value with the given name after having  asserted it has the default datatype `Data`:
-#
-#     lookup('the_name')
-#
-# When called with two arguments; **the name**, and **the expected type**, it
-# returns the bound value with the given name after having asserted it has the given data
-# type ('String' in the example):
-#
-#     lookup('the_name', String)
-#
-# When called with four arguments, **the name**, the **expected type**, the **merge** strategy, and a
-# **default value**, it returns the bound value with the given name, or the default after having asserted the value
-# has the given data type:
-#
-#     lookup('the_name', String, undef, 'Fred')
-#     lookup('the_name', Array[String], 'unique', [Fred])
-#
-# Using a lambda to provide a default value by calling a function:
-#
-#     lookup('the_size', Integer[1,100]) |$name| {
-#       obtain_size_default()
-#     }
-#
-# There are two ways to make lookup return undef when no matching key was found instead of raising an error.
-# Either call it with four arguments (the `merge` argument must be present even when using the default strategy
-# to ensure that the four argument variant is used):
-#
-#      $are_you_there = lookup('peekaboo', Optional[String], undef, undef)
-#
-# or call it using an options hash:
-#
-#      $are_you_there = lookup('peekaboo', { 'default_value' => undef })
-#      $are_you_there = lookup({ 'name' => 'peekaboo', 'default_value' => undef })
-#
-# or with a block that produces an undef value:
-#
-#      $are_you_there = lookup('peekaboo', Optional[String]) |$name| { undef }
-#
-# - Since 4.0.0
+# Uses the Puppet lookup system to retrieve a value for a given key. By default,
+# this returns the first value found (and fails compilation if no values are
+# available), but you can configure it to merge multiple values into one, fail
+# gracefully, and more.
+#
+# When looking up a key, Puppet will search up to three tiers of data, in the
+# following order:
+#
+# 1. Hiera.
+# 2. The current environment's data provider.
+# 3. The indicated module's data provider, if the key is of the form
+#    `<MODULE NAME>::<SOMETHING>`.
+#
+# #### Arguments
+#
+# You must provide the name of a key to look up, and can optionally provide other
+# arguments. You can combine these arguments in the following ways:
+#
+# * `lookup( <NAME>, [<VALUE TYPE>], [<MERGE BEHAVIOR>], [<DEFAULT VALUE>] )`
+# * `lookup( [<NAME>], <OPTIONS HASH> )`
+# * `lookup( as above ) |$key| { # lambda returns a default value }`
+#
+# Arguments in `[square brackets]` are optional.
+#
+# The arguments accepted by `lookup` are as follows:
+#
+# 1. `<NAME>` (string or array) --- The name of the key to look up.
+#     * This can also be an array of keys. If Puppet doesn't find anything for the
+#     first key, it will try again with the subsequent ones, only resorting to a
+#     default value if none of them succeed.
+# 2. `<VALUE TYPE>` (data type) --- A
+# [data type](https://docs.puppetlabs.com/puppet/latest/reference/lang_data_type.html)
+# that must match the retrieved value; if not, the lookup (and catalog
+# compilation) will fail. Defaults to `Data` (accepts any normal value).
+# 3. `<MERGE BEHAVIOR>` (string or hash; see **"Merge Behaviors"** below) ---
+# Whether (and how) to combine multiple values. If present, this overrides any
+# merge behavior specified in the data sources. Defaults to no value; Puppet will
+# use merge behavior from the data sources if present, and will otherwise do a
+# first-found lookup.
+# 4. `<DEFAULT VALUE>` (any normal value) --- If present, `lookup` returns this
+# when it can't find a normal value. Default values are never merged with found
+# values. Like a normal value, the default must match the value type. Defaults to
+# no value; if Puppet can't find a normal value, the lookup (and compilation) will
+# fail.
+# 5. `<OPTIONS HASH>` (hash) --- Alternate way to set the arguments above, plus
+# some less-common extra options. If you pass an options hash, you can't combine
+# it with any regular arguments (except `<NAME>`). An options hash can have the
+# following keys:
+#     * `'name'` --- Same as `<NAME>` (argument 1). You can pass this as an
+#     argument or in the hash, but not both.
+#     * `'value_type'` --- Same as `<VALUE TYPE>` (argument 2).
+#     * `'merge'` --- Same as `<MERGE BEHAVIOR>` (argument 3).
+#     * `'default_value'` --- Same as `<DEFAULT VALUE>` (argument 4).
+#     * `'default_values_hash'` (hash) --- A hash of lookup keys and default
+#     values. If Puppet can't find a normal value, it will check this hash for the
+#     requested key before giving up. You can combine this with `default_value` or
+#     a lambda, which will be used if the key isn't present in this hash. Defaults
+#     to an empty hash.
+#     * `'override'` (hash) --- A hash of lookup keys and override values. Puppet
+#     will check for the requested key in the overrides hash _first;_ if found, it
+#     returns that value as the _final_ value, ignoring merge behavior. Defaults
+#     to an empty hash.
+#
+# Finally, `lookup` can take a lambda, which must accept a single parameter.
+# This is yet another way to set a default value for the lookup; if no results are
+# found, Puppet will pass the requested key to the lambda and use its result as
+# the default value.
+#
+# #### Merge Behaviors
+#
+# Puppet lookup uses a hierarchy of data sources, and a given key might have
+# values in multiple sources. By default, Puppet returns the first value it finds,
+# but it can also continue searching and merge all the values together.
+#
+# > **Note:** Data sources can use the special `lookup_options` metadata key to
+# request a specific merge behavior for a key. The `lookup` function will use that
+# requested behavior unless you explicitly specify one.
+#
+# The valid merge behaviors are:
+#
+# * `'first'` --- Returns the first value found, with no merging. Puppet lookup's
+# default behavior.
+# * `'unique'` (called "array merge" in classic Hiera) --- Combines any number of
+# arrays and scalar values to return a merged, flattened array with all duplicate
+# values removed. The lookup will fail if any hash values are found.
+# * `'hash'` --- Combines the keys and values of any number of hashes to return a
+# merged hash. If the same key exists in multiple source hashes, Puppet will use
+# the value from the highest-priority data source; it won't recursively merge the
+# values.
+# * `'deep'` --- Combines the keys and values of any number of hashes to return a
+# merged hash. If the same key exists in multiple source hashes, Puppet will
+# recursively merge hash or array values (with duplicate values removed from
+# arrays). For conflicting scalar values, the highest-priority value will win.
+# * `{'strategy' => 'first|unique|hash'}` --- Same as the string versions of these
+# merge behaviors.
+# * `{'strategy' => 'deep', <DEEP OPTION> => <VALUE>, ...}` --- Same as `'deep'`,
+# but can adjust the merge with additional options. The available options are:
+#     * `'knockout_prefix'` (string or undef) --- A string prefix to indicate a
+#     value should be _removed_ from the final result. Defaults to `undef`, which
+#     disables this feature.
+#     * `'sort_merged_arrays'` (boolean) --- Whether to sort all arrays that are
+#     merged together. Defaults to `false`.
+#     * `'unpack_arrays'` (string or undef) --- A delimiter string; Puppet will
+#     join merged arrays with this delimiter, then split them again. Defaults to
+#     `undef`, which disables this feature.
+#     * `'merge_hash_arrays'` (boolean) --- Whether to merge hashes within arrays.
+#     Defaults to `false`.
+#
+# @example Look up a key and return the first value found
+#
+#     lookup('ntp::service_name')
+#
+# @example Do a unique merge lookup of class names, then add all of those classes to the catalog (like `hiera_include`)
+#
+#     lookup('classes', Array[String], 'unique').include
+#
+# @example Do a deep hash merge lookup of user data, but let higher priority sources remove values by prefixing them with `--`
+#
+#     lookup( { 'name'  => 'users',
+#               'merge' => {
+#                 'strategy'        => 'deep',
+#                 'knockout_prefix' => '--',
+#               },
+#     })
+#
+# @since 4.0.0
 Puppet::Functions.create_function(:lookup, Puppet::Functions::InternalFunction) do
   name_t = 'Variant[String,Array[String]]'
   value_type_t = 'Type'