puppet 4.7.1 → 4.8.0

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of puppet might be problematic. Click here for more details.

Files changed (276) hide show
  1. data/Gemfile +0 -3
  2. data/MAINTAINERS +76 -0
  3. data/README.md +0 -6
  4. data/Rakefile +2 -2
  5. data/lib/puppet/agent.rb +3 -3
  6. data/lib/puppet/application/apply.rb +1 -1
  7. data/lib/puppet/configurer.rb +2 -2
  8. data/lib/puppet/data_providers.rb +1 -0
  9. data/lib/puppet/data_providers/data_adapter.rb +1 -0
  10. data/lib/puppet/data_providers/data_function_support.rb +1 -0
  11. data/lib/puppet/data_providers/function_env_data_provider.rb +1 -0
  12. data/lib/puppet/data_providers/function_module_data_provider.rb +1 -0
  13. data/lib/puppet/data_providers/hiera_config.rb +1 -0
  14. data/lib/puppet/data_providers/hiera_env_data_provider.rb +1 -0
  15. data/lib/puppet/data_providers/hiera_interpolate.rb +1 -0
  16. data/lib/puppet/data_providers/hiera_module_data_provider.rb +1 -0
  17. data/lib/puppet/data_providers/hiera_support.rb +1 -2
  18. data/lib/puppet/data_providers/json_data_provider_factory.rb +2 -0
  19. data/lib/puppet/data_providers/yaml_data_provider_factory.rb +2 -0
  20. data/lib/puppet/defaults.rb +20 -1
  21. data/lib/puppet/environments.rb +5 -2
  22. data/lib/puppet/face/catalog.rb +1 -1
  23. data/lib/puppet/face/epp.rb +57 -11
  24. data/lib/puppet/face/module/install.rb +6 -6
  25. data/lib/puppet/functions.rb +23 -24
  26. data/lib/puppet/functions/alert.rb +14 -0
  27. data/lib/puppet/functions/binary_file.rb +25 -0
  28. data/lib/puppet/functions/break.rb +22 -0
  29. data/lib/puppet/functions/contain.rb +33 -0
  30. data/lib/puppet/functions/crit.rb +14 -0
  31. data/lib/puppet/functions/debug.rb +14 -0
  32. data/lib/puppet/functions/emerg.rb +14 -0
  33. data/lib/puppet/functions/epp.rb +1 -1
  34. data/lib/puppet/functions/err.rb +14 -0
  35. data/lib/puppet/functions/find_file.rb +31 -0
  36. data/lib/puppet/functions/include.rb +21 -0
  37. data/lib/puppet/functions/info.rb +14 -0
  38. data/lib/puppet/functions/new.rb +1 -1
  39. data/lib/puppet/functions/next.rb +23 -0
  40. data/lib/puppet/functions/notice.rb +14 -0
  41. data/lib/puppet/functions/regsubst.rb +12 -16
  42. data/lib/puppet/functions/require.rb +37 -0
  43. data/lib/puppet/functions/return.rb +22 -0
  44. data/lib/puppet/functions/strftime.rb +35 -0
  45. data/lib/puppet/functions/warning.rb +14 -0
  46. data/lib/puppet/generate/models/type/type.rb +4 -0
  47. data/lib/puppet/generate/templates/type/pcore.erb +2 -1
  48. data/lib/puppet/indirector/face.rb +6 -1
  49. data/lib/puppet/network/http/error.rb +2 -2
  50. data/lib/puppet/network/http/handler.rb +2 -2
  51. data/lib/puppet/node/environment.rb +11 -0
  52. data/lib/puppet/parser/ast.rb +5 -0
  53. data/lib/puppet/parser/ast/pops_bridge.rb +17 -4
  54. data/lib/puppet/parser/compiler.rb +29 -1
  55. data/lib/puppet/parser/functions.rb +6 -0
  56. data/lib/puppet/parser/functions/assert_type.rb +1 -1
  57. data/lib/puppet/parser/functions/binary_file.rb +24 -0
  58. data/lib/puppet/parser/functions/break.rb +39 -0
  59. data/lib/puppet/parser/functions/contain.rb +7 -15
  60. data/lib/puppet/parser/functions/defined.rb +2 -2
  61. data/lib/puppet/parser/functions/dig.rb +1 -1
  62. data/lib/puppet/parser/functions/each.rb +1 -1
  63. data/lib/puppet/parser/functions/epp.rb +2 -2
  64. data/lib/puppet/parser/functions/filter.rb +1 -1
  65. data/lib/puppet/parser/functions/find_file.rb +28 -0
  66. data/lib/puppet/parser/functions/hiera.rb +4 -4
  67. data/lib/puppet/parser/functions/hiera_array.rb +1 -1
  68. data/lib/puppet/parser/functions/hiera_hash.rb +1 -1
  69. data/lib/puppet/parser/functions/hiera_include.rb +1 -1
  70. data/lib/puppet/parser/functions/include.rb +4 -8
  71. data/lib/puppet/parser/functions/inline_epp.rb +1 -1
  72. data/lib/puppet/parser/functions/lest.rb +1 -1
  73. data/lib/puppet/parser/functions/lookup.rb +4 -2
  74. data/lib/puppet/parser/functions/map.rb +1 -1
  75. data/lib/puppet/parser/functions/match.rb +1 -1
  76. data/lib/puppet/parser/functions/new.rb +414 -18
  77. data/lib/puppet/parser/functions/next.rb +38 -0
  78. data/lib/puppet/parser/functions/reduce.rb +1 -1
  79. data/lib/puppet/parser/functions/regsubst.rb +4 -2
  80. data/lib/puppet/parser/functions/require.rb +4 -27
  81. data/lib/puppet/parser/functions/return.rb +71 -0
  82. data/lib/puppet/parser/functions/reverse_each.rb +1 -1
  83. data/lib/puppet/parser/functions/scanf.rb +13 -8
  84. data/lib/puppet/parser/functions/slice.rb +1 -1
  85. data/lib/puppet/parser/functions/split.rb +1 -1
  86. data/lib/puppet/parser/functions/step.rb +1 -1
  87. data/lib/puppet/parser/functions/strftime.rb +185 -0
  88. data/lib/puppet/parser/functions/then.rb +1 -1
  89. data/lib/puppet/parser/functions/type.rb +1 -1
  90. data/lib/puppet/parser/functions/with.rb +3 -3
  91. data/lib/puppet/parser/resource.rb +8 -5
  92. data/lib/puppet/parser/scope.rb +1 -1
  93. data/lib/puppet/plugins/configuration.rb +8 -0
  94. data/lib/puppet/plugins/data_providers.rb +1 -0
  95. data/lib/puppet/plugins/data_providers/data_provider.rb +7 -28
  96. data/lib/puppet/plugins/data_providers/registry.rb +1 -0
  97. data/lib/puppet/pops.rb +4 -0
  98. data/lib/puppet/pops/evaluator/access_operator.rb +36 -5
  99. data/lib/puppet/pops/evaluator/closure.rb +81 -12
  100. data/lib/puppet/pops/evaluator/compare_operator.rb +24 -1
  101. data/lib/puppet/pops/evaluator/evaluator_impl.rb +29 -5
  102. data/lib/puppet/pops/evaluator/json_strict_literal_evaluator.rb +1 -1
  103. data/lib/puppet/pops/evaluator/runtime3_converter.rb +53 -62
  104. data/lib/puppet/pops/evaluator/runtime3_support.rb +15 -6
  105. data/lib/puppet/pops/functions/dispatch.rb +9 -2
  106. data/lib/puppet/pops/functions/dispatcher.rb +3 -1
  107. data/lib/puppet/pops/functions/function.rb +19 -2
  108. data/lib/puppet/pops/issues.rb +9 -0
  109. data/lib/puppet/pops/label_provider.rb +2 -2
  110. data/lib/puppet/pops/loader/loader.rb +17 -0
  111. data/lib/puppet/pops/loader/static_loader.rb +0 -41
  112. data/lib/puppet/pops/lookup.rb +12 -0
  113. data/lib/puppet/pops/lookup/context.rb +86 -0
  114. data/lib/puppet/pops/lookup/explainer.rb +46 -6
  115. data/lib/puppet/pops/lookup/invocation.rb +19 -0
  116. data/lib/puppet/pops/lookup/sub_lookup.rb +1 -1
  117. data/lib/puppet/pops/model/factory.rb +20 -8
  118. data/lib/puppet/pops/model/model_label_provider.rb +3 -0
  119. data/lib/puppet/pops/model/model_meta.rb +2 -0
  120. data/lib/puppet/pops/model/model_tree_dumper.rb +14 -0
  121. data/lib/puppet/pops/parser/egrammar.ra +11 -6
  122. data/lib/puppet/pops/parser/eparser.rb +1112 -1086
  123. data/lib/puppet/pops/parser/heredoc_support.rb +1 -2
  124. data/lib/puppet/pops/pcore.rb +1 -0
  125. data/lib/puppet/pops/puppet_stack.rb +3 -3
  126. data/lib/puppet/pops/resource/param.rb +5 -1
  127. data/lib/puppet/pops/resource/resource_type_impl.rb +8 -4
  128. data/lib/puppet/pops/resource/resource_type_set.pcore +1 -0
  129. data/lib/puppet/pops/serialization/abstract_reader.rb +19 -2
  130. data/lib/puppet/pops/serialization/abstract_writer.rb +16 -3
  131. data/lib/puppet/pops/serialization/deserializer.rb +5 -1
  132. data/lib/puppet/pops/serialization/extension.rb +2 -0
  133. data/lib/puppet/pops/serialization/json.rb +76 -26
  134. data/lib/puppet/pops/serialization/serializer.rb +5 -1
  135. data/lib/puppet/pops/serialization/time_factory.rb +2 -1
  136. data/lib/puppet/pops/time/timespan.rb +718 -0
  137. data/lib/puppet/pops/time/timestamp.rb +148 -0
  138. data/lib/puppet/pops/types/p_binary_type.rb +220 -0
  139. data/lib/puppet/pops/types/p_object_type.rb +12 -6
  140. data/lib/puppet/pops/types/p_sensitive_type.rb +5 -1
  141. data/lib/puppet/pops/types/p_timespan_type.rb +141 -0
  142. data/lib/puppet/pops/types/p_timestamp_type.rb +69 -0
  143. data/lib/puppet/pops/types/string_converter.rb +62 -0
  144. data/lib/puppet/pops/types/type_asserter.rb +1 -1
  145. data/lib/puppet/pops/types/type_calculator.rb +17 -3
  146. data/lib/puppet/pops/types/type_factory.rb +35 -1
  147. data/lib/puppet/pops/types/type_formatter.rb +64 -11
  148. data/lib/puppet/pops/types/type_mismatch_describer.rb +110 -61
  149. data/lib/puppet/pops/types/type_parser.rb +18 -4
  150. data/lib/puppet/pops/types/types.rb +98 -63
  151. data/lib/puppet/pops/validation.rb +9 -1
  152. data/lib/puppet/pops/validation/checker4_0.rb +7 -0
  153. data/lib/puppet/property.rb +1 -1
  154. data/lib/puppet/provider.rb +3 -6
  155. data/lib/puppet/provider/mcx/mcxcontent.rb +1 -1
  156. data/lib/puppet/provider/mount/parsed.rb +18 -4
  157. data/lib/puppet/provider/nameservice/directoryservice.rb +15 -7
  158. data/lib/puppet/provider/package/gem.rb +6 -1
  159. data/lib/puppet/provider/package/pip.rb +0 -1
  160. data/lib/puppet/provider/package/pkg.rb +5 -1
  161. data/lib/puppet/provider/package/pkgng.rb +1 -1
  162. data/lib/puppet/provider/package/yum.rb +10 -0
  163. data/lib/puppet/provider/service/launchd.rb +1 -0
  164. data/lib/puppet/provider/user/directoryservice.rb +6 -6
  165. data/lib/puppet/provider/yumrepo/inifile.rb +1 -1
  166. data/lib/puppet/provider/zpool/zpool.rb +1 -1
  167. data/lib/puppet/resource.rb +54 -12
  168. data/lib/puppet/resource/capability_finder.rb +15 -9
  169. data/lib/puppet/resource/catalog.rb +25 -6
  170. data/lib/puppet/resource/type.rb +3 -1
  171. data/lib/puppet/settings.rb +1 -1
  172. data/lib/puppet/settings/environment_conf.rb +12 -4
  173. data/lib/puppet/syntax_checkers/base64.rb +41 -0
  174. data/lib/puppet/syntax_checkers/json.rb +0 -2
  175. data/lib/puppet/transaction.rb +6 -0
  176. data/lib/puppet/transaction/additional_resource_generator.rb +5 -0
  177. data/lib/puppet/transaction/report.rb +7 -2
  178. data/lib/puppet/type.rb +2 -1
  179. data/lib/puppet/type/file/checksum.rb +1 -0
  180. data/lib/puppet/type/file/content.rb +4 -4
  181. data/lib/puppet/type/mount.rb +44 -0
  182. data/lib/puppet/type/ssh_authorized_key.rb +1 -1
  183. data/lib/puppet/type/tidy.rb +3 -0
  184. data/lib/puppet/type/user.rb +12 -6
  185. data/lib/puppet/util/log.rb +25 -0
  186. data/lib/puppet/util/plist.rb +8 -3
  187. data/lib/puppet/version.rb +1 -1
  188. data/lib/puppet_x.rb +7 -1
  189. data/spec/integration/application/apply_spec.rb +118 -0
  190. data/spec/integration/parser/compiler_spec.rb +28 -0
  191. data/spec/integration/parser/pcore_resource_spec.rb +40 -3
  192. data/spec/integration/provider/mount_spec.rb +2 -1
  193. data/spec/integration/util/windows/principal_spec.rb +2 -2
  194. data/spec/integration/util/windows/registry_spec.rb +4 -4
  195. data/spec/lib/puppet_spec/compiler.rb +5 -1
  196. data/spec/lib/puppet_spec/unindent.rb +5 -0
  197. data/spec/shared_contexts/types_setup.rb +6 -0
  198. data/spec/shared_examples/rhel_package_provider.rb +16 -0
  199. data/spec/spec_helper.rb +1 -0
  200. data/spec/unit/agent_spec.rb +11 -0
  201. data/spec/unit/application/lookup_spec.rb +94 -3
  202. data/spec/unit/capability_spec.rb +22 -0
  203. data/spec/unit/configurer_spec.rb +8 -0
  204. data/spec/unit/face/epp_face_spec.rb +22 -3
  205. data/spec/unit/functions/assert_type_spec.rb +3 -3
  206. data/spec/unit/functions/binary_file_spec.rb +46 -0
  207. data/spec/unit/functions/break_spec.rb +89 -0
  208. data/spec/unit/{parser/functions → functions}/contain_spec.rb +68 -3
  209. data/spec/unit/functions/find_file_spec.rb +69 -0
  210. data/spec/unit/functions/include_spec.rb +175 -0
  211. data/spec/unit/functions/logging_spec.rb +54 -0
  212. data/spec/unit/functions/lookup_spec.rb +3 -3
  213. data/spec/unit/functions/new_spec.rb +105 -5
  214. data/spec/unit/functions/next_spec.rb +93 -0
  215. data/spec/unit/functions/require_spec.rb +83 -0
  216. data/spec/unit/functions/return_spec.rb +105 -0
  217. data/spec/unit/{parser/functions → functions}/shared.rb +14 -11
  218. data/spec/unit/functions/strftime_spec.rb +152 -0
  219. data/spec/unit/functions4_spec.rb +22 -0
  220. data/spec/unit/indirector/face_spec.rb +10 -2
  221. data/spec/unit/network/http/error_spec.rb +1 -2
  222. data/spec/unit/network/http/handler_spec.rb +6 -5
  223. data/spec/unit/parser/functions/hiera_array_spec.rb +1 -1
  224. data/spec/unit/parser/functions/hiera_hash_spec.rb +1 -1
  225. data/spec/unit/parser/functions/hiera_include_spec.rb +1 -1
  226. data/spec/unit/parser/functions/hiera_spec.rb +1 -1
  227. data/spec/unit/parser/functions/lookup_spec.rb +1 -1
  228. data/spec/unit/parser/functions/regsubst_spec.rb +1 -1
  229. data/spec/unit/parser/functions/split_spec.rb +1 -1
  230. data/spec/unit/pops/evaluator/access_ops_spec.rb +81 -1
  231. data/spec/unit/pops/evaluator/arithmetic_ops_spec.rb +170 -0
  232. data/spec/unit/pops/evaluator/evaluating_parser_spec.rb +29 -4
  233. data/spec/unit/pops/evaluator/runtime3_converter_spec.rb +112 -4
  234. data/spec/unit/pops/loaders/dependency_loader_spec.rb +12 -0
  235. data/spec/unit/pops/loaders/static_loader_spec.rb +0 -26
  236. data/spec/unit/pops/lookup/context_spec.rb +149 -0
  237. data/spec/unit/pops/parser/parse_functions_spec.rb +19 -0
  238. data/spec/unit/pops/parser/parse_lambda_spec.rb +19 -0
  239. data/spec/unit/pops/puppet_stack_spec.rb +1 -1
  240. data/spec/unit/pops/resource/resource_type_impl_spec.rb +74 -0
  241. data/spec/unit/pops/serialization/packer_spec.rb +34 -14
  242. data/spec/unit/pops/serialization/serialization_spec.rb +67 -5
  243. data/spec/unit/pops/time/timespan_spec.rb +121 -0
  244. data/spec/unit/pops/types/p_binary_type_spec.rb +243 -0
  245. data/spec/unit/pops/types/p_object_type_spec.rb +7 -7
  246. data/spec/unit/pops/types/p_sensitive_type_spec.rb +1 -1
  247. data/spec/unit/pops/types/p_timespan_type_spec.rb +273 -0
  248. data/spec/unit/pops/types/p_timestamp_type_spec.rb +311 -0
  249. data/spec/unit/pops/types/p_type_set_type_spec.rb +13 -13
  250. data/spec/unit/pops/types/ruby_generator_spec.rb +12 -12
  251. data/spec/unit/pops/types/string_converter_spec.rb +89 -0
  252. data/spec/unit/pops/types/type_asserter_spec.rb +3 -3
  253. data/spec/unit/pops/types/type_calculator_spec.rb +113 -5
  254. data/spec/unit/pops/types/type_formatter_spec.rb +40 -0
  255. data/spec/unit/pops/types/type_mismatch_describer_spec.rb +49 -38
  256. data/spec/unit/pops/types/type_parser_spec.rb +87 -4
  257. data/spec/unit/pops/types/types_spec.rb +1 -1
  258. data/spec/unit/pops/validator/validator_spec.rb +23 -0
  259. data/spec/unit/provider/mount/parsed_spec.rb +47 -29
  260. data/spec/unit/provider/package/pkg_spec.rb +109 -99
  261. data/spec/unit/provider/ssh_authorized_key/parsed_spec.rb +1 -0
  262. data/spec/unit/provider/user/aix_spec.rb +1 -1
  263. data/spec/unit/provider/user/directoryservice_spec.rb +101 -30
  264. data/spec/unit/resource/capability_finder_spec.rb +29 -7
  265. data/spec/unit/resource/catalog_spec.rb +127 -0
  266. data/spec/unit/ssl/certificate_request_spec.rb +1 -1
  267. data/spec/unit/transaction/additional_resource_generator_spec.rb +30 -0
  268. data/spec/unit/transaction/persistence_spec.rb +1 -6
  269. data/spec/unit/transaction/report_spec.rb +23 -0
  270. data/spec/unit/transaction_spec.rb +38 -0
  271. data/spec/unit/type/mount_spec.rb +5 -0
  272. data/spec/unit/util/plist_spec.rb +14 -2
  273. metadata +71 -12
  274. data/spec/integration/parser/functions/require_spec.rb +0 -43
  275. data/spec/unit/parser/functions/include_spec.rb +0 -55
  276. data/spec/unit/parser/functions/require_spec.rb +0 -68
@@ -17,22 +17,14 @@ relative names are not allowed. In addition to names in string form,
17
17
  you may also directly use Class and Resource Type values that are produced by
18
18
  evaluating resource and relationship expressions.
19
19
 
20
+ The function returns an array of references to the classes that were contained thus
21
+ allowing the function call to `contain` to directly continue.
22
+
20
23
  - Since 4.0.0 support for Class and Resource Type values, absolute names
24
+ - Since 4.7.0 an Array[Type[Class[n]]] is returned with all the contained classes
21
25
  "
22
26
  ) do |classes|
23
- scope = self
24
-
25
- # Make call patterns uniform and protected against nested arrays, also make
26
- # names absolute if so desired.
27
- classes = transform_and_assert_classnames(classes.is_a?(Array) ? classes.flatten : [classes])
28
-
29
- containing_resource = scope.resource
30
-
31
- # This is the same as calling the include function but faster and does not rely on the include
32
- # function (which is a statement) to return something (it should not).
33
- (compiler.evaluate_classes(classes, self, false) || []).each do |resource|
34
- if ! scope.catalog.edge?(containing_resource, resource)
35
- scope.catalog.add_edge(containing_resource, resource)
36
- end
37
- end
27
+ # Call the 4.x version of this function in case 3.x ruby code uses this function
28
+ Puppet.warn_once(:deprecation, '3xfunction#contain', "Calling function_contain via the Scope class is deprecated. Use Scope#call_function instead")
29
+ call_function('contain', classes)
38
30
  end
@@ -12,7 +12,7 @@ This function takes at least one string argument, which can be a class name, typ
12
12
  resource reference, or variable reference of the form `'$name'`.
13
13
 
14
14
  The `defined` function checks both native and defined types, including types
15
- provided by modules. Types and classes are matched by their names. The function matches
15
+ provided by modules. Types and classes are matched by their names. The function matches
16
16
  resource declarations by using resource references.
17
17
 
18
18
  **Examples**: Different types of `defined` function matches
@@ -103,5 +103,5 @@ defined('$tmp_file2')
103
103
  - Since 4.0.0 includes all future parser features
104
104
  DOC
105
105
  ) do |vals|
106
- function_fail(["defined() is a 4.x function - an illegal call was made to this function using old API"])
106
+ Error.is4x('defined')
107
107
  end
@@ -25,5 +25,5 @@ Would notice the value 100.
25
25
  * Since 4.5.0
26
26
  DOC
27
27
  ) do |args|
28
- function_fail(["dig() is only available when parser/evaluator future is in effect"])
28
+ Error.is4x('dig')
29
29
  end
@@ -100,5 +100,5 @@ documentation.
100
100
  - Since 4.0.0
101
101
  DOC
102
102
  ) do |args|
103
- function_fail(["each() is only available when parser/evaluator future is in effect"])
103
+ Error.is4x('each')
104
104
  end
@@ -19,7 +19,7 @@ For example, to call the apache module's `templates/vhost/_docroot.epp`
19
19
  template and pass the `docroot` and `virtual_docroot` parameters, call the `epp`
20
20
  function like this:
21
21
 
22
- `epp('apache/templates/vhost/_docroot.epp', { 'docroot' => '/var/www/html',
22
+ `epp('apache/vhost/_docroot.epp', { 'docroot' => '/var/www/html',
23
23
  'virtual_docroot' => '/var/www/example' })`
24
24
 
25
25
  Puppet produces a syntax error if you pass more parameters than are declared in
@@ -32,5 +32,5 @@ function fails to pass any required parameter.
32
32
 
33
33
  - Since 4.0.0") do |args|
34
34
 
35
- function_fail(["epp() is only available when parser/evaluator future is in effect"])
35
+ Error.is4x('epp')
36
36
  end
@@ -74,5 +74,5 @@ $filtered_data = $data.filter |$keys, $values| { $keys =~ /berry$/ and $values <
74
74
  - Since 4.0.0
75
75
  DOC
76
76
  ) do |args|
77
- function_fail(["filter() is only available when parser/evaluator future is in effect"])
77
+ Error.is4x('filter')
78
78
  end
@@ -0,0 +1,28 @@
1
+ Puppet::Parser::Functions::newfunction(
2
+ :find_file,
3
+ :type => :rvalue,
4
+ :arity => -2,
5
+ :doc => <<-DOC
6
+ Finds an existing file from a module and returns its path.
7
+
8
+ The argument to this function should be a String as a `<MODULE NAME>/<FILE>`
9
+ reference, which will search for `<FILE>` relative to a module's `files`
10
+ directory. (For example, the reference `mysql/mysqltuner.pl` will search for the
11
+ file `<MODULES DIRECTORY>/mysql/files/mysqltuner.pl`.)
12
+
13
+ This function can also accept:
14
+
15
+ * An absolute String path, which will check for the existence of a file from anywhere on disk.
16
+ * Multiple String arguments, which will return the path of the **first** file
17
+ found, skipping non existing files.
18
+ * An array of string paths, which will return the path of the **first** file
19
+ found from the given paths in the array, skipping non existing files.
20
+
21
+ The function returns `undef` if none of the given paths were found
22
+
23
+ - since 4.8.0
24
+ DOC
25
+ ) do |args|
26
+ Error.is4x('find_file')
27
+ end
28
+
@@ -34,7 +34,7 @@ throughout a hierarchy, use the `hiera_array` or `hiera_hash` functions.
34
34
  # - common
35
35
 
36
36
  # Assuming web01.example.com.yaml:
37
- # users:
37
+ # users:
38
38
  # - "Amy Barry"
39
39
  # - "Carrie Douglas"
40
40
 
@@ -58,7 +58,7 @@ $users = hiera('users', undef)
58
58
  ~~~
59
59
 
60
60
  You can optionally generate the default value with a
61
- [lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html) that
61
+ [lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html) that
62
62
  takes one parameter.
63
63
 
64
64
  **Example**: Using `hiera` with a lambda
@@ -74,7 +74,7 @@ $users = hiera('users') | $key | { "Key \'${key}\' not found" }
74
74
  # "Key 'users' not found".
75
75
  ~~~
76
76
 
77
- The returned value's data type depends on the types of the results. In the example
77
+ The returned value's data type depends on the types of the results. In the example
78
78
  above, Hiera matches the 'users' key and returns it as a hash.
79
79
 
80
80
  See
@@ -84,6 +84,6 @@ for more information about Hiera lookup functions.
84
84
  - Since 4.0.0
85
85
  DOC
86
86
  ) do |*args|
87
- function_fail(["hiera() has been converted to 4x API"])
87
+ Error.is4x('hiera')
88
88
  end
89
89
  end
@@ -72,7 +72,7 @@ for more information about Hiera lookup functions.
72
72
  - Since 4.0.0
73
73
  DOC
74
74
  ) do |*args|
75
- function_fail(["hiera_array() has been converted to 4x API"])
75
+ Error.is4x('hiera_array')
76
76
  end
77
77
  end
78
78
 
@@ -82,7 +82,7 @@ for more information about Hiera lookup functions.
82
82
  - Since 4.0.0
83
83
  DOC
84
84
  ) do |*args|
85
- function_fail(["hiera_hash() has been converted to 4x API"])
85
+ Error.is4x('hiera_hash')
86
86
  end
87
87
  end
88
88
 
@@ -82,7 +82,7 @@ nodes.
82
82
  - Since 4.0.0
83
83
  DOC
84
84
  ) do |*args|
85
- function_fail(["hiera_include() has been converted to 4x API"])
85
+ Error.is4x('hiera_include')
86
86
  end
87
87
  end
88
88
 
@@ -26,12 +26,8 @@ the future parser's resource and relationship expressions.
26
26
 
27
27
  - Since < 3.0.0
28
28
  - Since 4.0.0 support for class and resource type values, absolute names
29
- ") do |vals|
30
-
31
- # Unify call patterns (if called with nested arrays), make names absolute if
32
- # wanted and evaluate the classes
33
- compiler.evaluate_classes(
34
- transform_and_assert_classnames(
35
- vals.is_a?(Array) ? vals.flatten : [vals]),
36
- self, false)
29
+ - Since 4.7.0 returns an Array[Type[Class]] of all included classes
30
+ ") do |classes|
31
+ Puppet.warn_once(:deprecation, '3xfunction#include', "Calling function_include via the Scope class is deprecated. Use Scope#call_function instead")
32
+ call_function('include', classes)
37
33
  end
@@ -47,5 +47,5 @@ END
47
47
  - Since 3.5
48
48
  - Requires [future parser](/puppet/3.8/reference/experiments_future.html) in Puppet 3.5 to 3.8") do |arguments|
49
49
 
50
- function_fail(["inline_epp() is only available when parser/evaluator future is in effect"])
50
+ Error.is4x('inline_epp')
51
51
  end
@@ -45,5 +45,5 @@ Would notice the value `20`
45
45
  * Since 4.5.0
46
46
  DOC
47
47
  ) do |args|
48
- function_fail(["lest() is only available when parser/evaluator future is in effect"])
48
+ Error.is4x('lest')
49
49
  end
@@ -1,4 +1,5 @@
1
- Puppet::Parser::Functions.newfunction(:lookup, :type => :rvalue, :arity => -2, :doc => <<-'ENDHEREDOC') do |args|
1
+ module Puppet::Parser::Functions
2
+ newfunction(:lookup, :type => :rvalue, :arity => -2, :doc => <<-'ENDHEREDOC') do |args|
2
3
  Uses the Puppet lookup system to retrieve a value for a given key. By default,
3
4
  this returns the first value found (and fails compilation if no values are
4
5
  available), but you can configure it to merge multiple values into one, fail
@@ -126,5 +127,6 @@ remove values by prefixing them with `--`:
126
127
  })
127
128
 
128
129
  ENDHEREDOC
129
- function_fail(["lookup() has been converted to 4x API"])
130
+ Error.is4x('lookup')
131
+ end
130
132
  end
@@ -72,5 +72,5 @@ $transformed_data = $data.map |$key,$value| { $value }
72
72
  - Since 4.0.0
73
73
  DOC
74
74
  ) do |args|
75
- function_fail(["map() is only available when parser/evaluator future is in effect"])
75
+ Error.is4x('map')
76
76
  end
@@ -39,5 +39,5 @@ $matches = ["abc123","def456"].match(/([a-z]+)([1-9]+)/)
39
39
  - Since 4.0.0
40
40
  DOC
41
41
  ) do |args|
42
- function_fail(["match() is only available when parser/evaluator future is in effect"])
42
+ Error.is4x('match')
43
43
  end
@@ -75,11 +75,13 @@ type Radix = Variant[Default, Integer[2,2], Integer[8,8], Integer[10,10], Intege
75
75
 
76
76
  function Integer.new(
77
77
  String $value,
78
- Radix $radix = 10
78
+ Radix $radix = 10,
79
+ Boolean $abs = false
79
80
  )
80
81
 
81
82
  function Integer.new(
82
- Variant[Numeric, Boolean] $value
83
+ Variant[Numeric, Boolean] $value,
84
+ Boolean $abs = false
83
85
  )
84
86
  ```
85
87
 
@@ -99,14 +101,16 @@ function Integer.new(
99
101
  * Conversion from `Boolean` results in 0 for `false` and 1 for `true`.
100
102
  * Conversion from `Integer`, `Float`, and `Boolean` ignores the radix.
101
103
  * `Float` value fractions are truncated (no rounding).
104
+ * When `abs` is set to `true`, the result will be an absolute integer.
102
105
 
103
106
  Examples - Converting to Integer:
104
107
 
105
108
  ```puppet
106
- $a_number = Integer("0xFF", 16) # results in 255
107
- $a_number = Numeric("010") # results in 8
108
- $a_number = Numeric("010", 10) # results in 10
109
- $a_number = Integer(true) # results in 1
109
+ $a_number = Integer("0xFF", 16) # results in 255
110
+ $a_number = Integer("010") # results in 8
111
+ $a_number = Integer("010", 10) # results in 10
112
+ $a_number = Integer(true) # results in 1
113
+ $a_number = Integer(-38, 10, true) # results in 38
110
114
  ```
111
115
 
112
116
  Conversion to Float
@@ -117,7 +121,8 @@ For conversion from `String` both float and integer formats are supported.
117
121
 
118
122
  ```puppet
119
123
  function Float.new(
120
- Variant[Numeric, Boolean, String] $value
124
+ Variant[Numeric, Boolean, String] $value,
125
+ Boolean $abs = true
121
126
  )
122
127
  ```
123
128
 
@@ -125,7 +130,8 @@ function Float.new(
125
130
  * For an integer, the floating point fraction of `.0` is added to the value.
126
131
  * A `Boolean` `true` is converted to 1.0, and a `false` to 0.0
127
132
  * In `String` format, integer prefixes for hex and binary are understood (but not octal since
128
- floating point in string format may start with a '0').
133
+ floating point in string format may start with a '0').
134
+ * When `abs` is set to `true`, the result will be an absolute floating point value.
129
135
 
130
136
  Conversion to Numeric
131
137
  ---------------------
@@ -135,7 +141,8 @@ A new `Integer` or `Float` can be created from `Integer`, `Float`, `Boolean` and
135
141
 
136
142
  ```puppet
137
143
  function Numeric.new(
138
- Variant[Numeric, Boolean, String] $value
144
+ Variant[Numeric, Boolean, String] $value,
145
+ Boolean $abs = true
139
146
  )
140
147
  ```
141
148
 
@@ -143,14 +150,329 @@ function Numeric.new(
143
150
  (e/E), the result is a `Float`, otherwise the value is an `Integer`. The
144
151
  conversion from `String` always uses a radix based on the prefix of the string.
145
152
  * Conversion from `Boolean` results in 0 for `false` and 1 for `true`.
153
+ * When `abs` is set to `true`, the result will be an absolute `Float`or `Integer` value.
146
154
 
147
155
  Examples - Converting to Numeric
148
156
 
149
157
  ```puppet
150
- $a_number = Numeric(true) # results in 1
151
- $a_number = Numeric("0xFF") # results in 255
152
- $a_number = Numeric("010") # results in 8
153
- $a_number = Numeric("3.14") # results in 3.14 (a float)
158
+ $a_number = Numeric(true) # results in 1
159
+ $a_number = Numeric("0xFF") # results in 255
160
+ $a_number = Numeric("010") # results in 8
161
+ $a_number = Numeric("3.14") # results in 3.14 (a float)
162
+ $a_number = Numeric(-42.3, true) # results in 42.3
163
+ $a_number = Numeric(-42, true) # results in 42
164
+ ```
165
+
166
+ Conversion to Timespan
167
+ -------------------
168
+
169
+ A new `Timespan` can be created from `Integer`, `Float`, `String`, and `Hash` values. Several variants of the constructor are provided.
170
+
171
+ #### Timespan from seconds
172
+
173
+ When a Float is used, the decimal part represents fractions of a second.
174
+
175
+ ```puppet
176
+ function Timespan.new(
177
+ Variant[Float, Integer] $value
178
+ )
179
+ ```
180
+
181
+ #### Timespan from days, hours, mintues, seconds, and fractions of a second
182
+
183
+ The arguments can be passed separately in which case the first four, days, hours, minutes, and seconds are mandatory and the rest are optional.
184
+ All values may overflow and/or be negative. The internal 128-bit nano-second integer is calculated as:
185
+
186
+ ```
187
+ (((((days * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000 + milliseconds) * 1000 + microseconds) * 1000 + nanoseconds
188
+ ```
189
+
190
+ ```puppet
191
+ function Timespan.new(
192
+ Integer $days, Integer $hours, Integer $minutes, Integer $seconds,
193
+ Integer $milliseconds = 0, Integer $microseconds = 0, Integer $nanoseconds = 0
194
+ )
195
+ ```
196
+
197
+ or, all arguments can be passed as a `Hash`, in which case all entries are optional:
198
+
199
+ ```puppet
200
+ function Timespan.new(
201
+ Struct[{
202
+ Optional[negative] => Boolean,
203
+ Optional[days] => Integer,
204
+ Optional[hours] => Integer,
205
+ Optional[minutes] => Integer,
206
+ Optional[seconds] => Integer,
207
+ Optional[milliseconds] => Integer,
208
+ Optional[microseconds] => Integer,
209
+ Optional[nanoseconds] => Integer
210
+ }] $hash
211
+ )
212
+ ```
213
+
214
+ #### Timespan from String and format directive patterns
215
+
216
+ The first argument is parsed using the format optionally passed as a string or array of strings. When an array is used, an attempt
217
+ will be made to parse the string using the first entry and then with each entry in succession until parsing succeeds. If the second
218
+ argument is omitted, an array of default formats will be used.
219
+
220
+ An exception is raised when no format was able to parse the given string.
221
+
222
+ ```puppet
223
+ function Timespan.new(
224
+ String $string, Variant[String[2],Array[String[2]], 1] $format = <default format>)
225
+ )
226
+ ```
227
+
228
+ the arguments may also be passed as a `Hash`:
229
+
230
+ ```puppet
231
+ function Timespan.new(
232
+ Struct[{
233
+ string => String[1],
234
+ Optional[format] => Variant[String[2],Array[String[2]], 1]
235
+ }] $hash
236
+ )
237
+ ```
238
+
239
+ The directive consists of a percent (%) character, zero or more flags, optional minimum field width and
240
+ a conversion specifier as follows:
241
+ ```
242
+ %[Flags][Width]Conversion
243
+ ```
244
+
245
+ ##### Flags:
246
+
247
+ | Flag | Meaning
248
+ | ---- | ---------------
249
+ | - | Don't pad numerical output
250
+ | _ | Use spaces for padding
251
+ | 0 | Use zeros for padding
252
+
253
+ ##### Format directives:
254
+
255
+ | Format | Meaning |
256
+ | ------ | ------- |
257
+ | D | Number of Days |
258
+ | H | Hour of the day, 24-hour clock |
259
+ | M | Minute of the hour (00..59) |
260
+ | S | Second of the minute (00..59) |
261
+ | L | Millisecond of the second (000..999) |
262
+ | N | Fractional seconds digits |
263
+
264
+ The format directive that represents the highest magnitude in the format will be allowed to
265
+ overflow. I.e. if no "%D" is used but a "%H" is present, then the hours may be more than 23.
266
+
267
+ The default array contains the following patterns:
268
+
269
+ ```
270
+ ['%D-%H:%M:%S', '%D-%H:%M', '%H:%M:%S', '%H:%M']
271
+ ```
272
+
273
+ Examples - Converting to Timespan
274
+
275
+ ```puppet
276
+ $duration = Timespan(13.5) # 13 seconds and 500 milliseconds
277
+ $duration = Timespan({days=>4}) # 4 days
278
+ $duration = Timespan(4, 0, 0, 2) # 4 days and 2 seconds
279
+ $duration = Timespan('13:20') # 13 hours and 20 minutes (using default pattern)
280
+ $duration = Timespan('10:03.5', '%M:%S.%L') # 10 minutes, 3 seconds, and 5 milli-seconds
281
+ $duration = Timespan('10:03.5', '%M:%S.%N') # 10 minutes, 3 seconds, and 5 nano-seconds
282
+ ```
283
+
284
+ Conversion to Timestamp
285
+ -------------------
286
+
287
+ A new `Timestamp` can be created from `Integer`, `Float`, `String`, and `Hash` values. Several variants of the constructor are provided.
288
+
289
+ #### Timestamp from seconds since epoch (1970-01-01 00:00:00 UTC)
290
+
291
+ When a Float is used, the decimal part represents fractions of a second.
292
+
293
+ ```puppet
294
+ function Timestamp.new(
295
+ Variant[Float, Integer] $value
296
+ )
297
+ ```
298
+
299
+ #### Timestamp from String and patterns consisting of format directives
300
+
301
+ The first argument is parsed using the format optionally passed as a string or array of strings. When an array is used, an attempt
302
+ will be made to parse the string using the first entry and then with each entry in succession until parsing succeeds. If the second
303
+ argument is omitted, an array of default formats will be used.
304
+
305
+ A third optional timezone argument can be provided. The first argument will then be parsed as if it represents a local time in that
306
+ timezone. The timezone can be any timezone that is recognized when using the '%z' or '%Z' formats, or the word 'current', in which
307
+ case the current timezone of the evaluating process will be used. The timezone argument is case insensitive.
308
+
309
+ The default timezone, when no argument is provided, or when using the keyword `default`, is 'UTC'.
310
+
311
+ It is illegal to provide a timezone argument other than `default` in combination with a format that contains '%z' or '%Z' since that
312
+ would introduce an ambiguity as to which timezone to use. The one extracted from the string, or the one provided as an argument.
313
+
314
+ An exception is raised when no format was able to parse the given string.
315
+
316
+ ```puppet
317
+ function Timestamp.new(
318
+ String $string,
319
+ Variant[String[2],Array[String[2]], 1] $format = <default format>,
320
+ String $timezone = default)
321
+ )
322
+ ```
323
+
324
+ the arguments may also be passed as a `Hash`:
325
+
326
+ ```puppet
327
+ function Timestamp.new(
328
+ Struct[{
329
+ string => String[1],
330
+ Optional[format] => Variant[String[2],Array[String[2]], 1],
331
+ Optional[timezone] => String[1]
332
+ }] $hash
333
+ )
334
+ ```
335
+
336
+ The directive consists of a percent (%) character, zero or more flags, optional minimum field width and
337
+ a conversion specifier as follows:
338
+ ```
339
+ %[Flags][Width]Conversion
340
+ ```
341
+
342
+ ##### Flags:
343
+
344
+ | Flag | Meaning
345
+ | ---- | ---------------
346
+ | - | Don't pad numerical output
347
+ | _ | Use spaces for padding
348
+ | 0 | Use zeros for padding
349
+ | # | Change names to upper-case or change case of am/pm
350
+ | ^ | Use uppercase
351
+ | : | Use colons for %z
352
+
353
+ ##### Format directives (names and padding can be altered using flags):
354
+
355
+ **Date (Year, Month, Day):**
356
+
357
+ | Format | Meaning |
358
+ | ------ | ------- |
359
+ | Y | Year with century, zero-padded to at least 4 digits |
360
+ | C | year / 100 (rounded down such as 20 in 2009) |
361
+ | y | year % 100 (00..99) |
362
+ | m | Month of the year, zero-padded (01..12) |
363
+ | B | The full month name ("January") |
364
+ | b | The abbreviated month name ("Jan") |
365
+ | h | Equivalent to %b |
366
+ | d | Day of the month, zero-padded (01..31) |
367
+ | e | Day of the month, blank-padded ( 1..31) |
368
+ | j | Day of the year (001..366) |
369
+
370
+ **Time (Hour, Minute, Second, Subsecond):**
371
+
372
+ | Format | Meaning |
373
+ | ------ | ------- |
374
+ | H | Hour of the day, 24-hour clock, zero-padded (00..23) |
375
+ | k | Hour of the day, 24-hour clock, blank-padded ( 0..23) |
376
+ | I | Hour of the day, 12-hour clock, zero-padded (01..12) |
377
+ | l | Hour of the day, 12-hour clock, blank-padded ( 1..12) |
378
+ | P | Meridian indicator, lowercase ("am" or "pm") |
379
+ | p | Meridian indicator, uppercase ("AM" or "PM") |
380
+ | M | Minute of the hour (00..59) |
381
+ | S | Second of the minute (00..60) |
382
+ | L | Millisecond of the second (000..999). Digits under millisecond are truncated to not produce 1000 |
383
+ | N | Fractional seconds digits, default is 9 digits (nanosecond). Digits under a specified width are truncated to avoid carry up |
384
+
385
+ **Time (Hour, Minute, Second, Subsecond):**
386
+
387
+ | Format | Meaning |
388
+ | ------ | ------- |
389
+ | z | Time zone as hour and minute offset from UTC (e.g. +0900) |
390
+ | :z | hour and minute offset from UTC with a colon (e.g. +09:00) |
391
+ | ::z | hour, minute and second offset from UTC (e.g. +09:00:00) |
392
+ | Z | Abbreviated time zone name or similar information. (OS dependent) |
393
+
394
+ **Weekday:**
395
+
396
+ | Format | Meaning |
397
+ | ------ | ------- |
398
+ | A | The full weekday name ("Sunday") |
399
+ | a | The abbreviated name ("Sun") |
400
+ | u | Day of the week (Monday is 1, 1..7) |
401
+ | w | Day of the week (Sunday is 0, 0..6) |
402
+
403
+ **ISO 8601 week-based year and week number:**
404
+
405
+ The first week of YYYY starts with a Monday and includes YYYY-01-04.
406
+ The days in the year before the first week are in the last week of
407
+ the previous year.
408
+
409
+ | Format | Meaning |
410
+ | ------ | ------- |
411
+ | G | The week-based year |
412
+ | g | The last 2 digits of the week-based year (00..99) |
413
+ | V | Week number of the week-based year (01..53) |
414
+
415
+ **Week number:**
416
+
417
+ The first week of YYYY that starts with a Sunday or Monday (according to %U
418
+ or %W). The days in the year before the first week are in week 0.
419
+
420
+ | Format | Meaning |
421
+ | ------ | ------- |
422
+ | U | Week number of the year. The week starts with Sunday. (00..53) |
423
+ | W | Week number of the year. The week starts with Monday. (00..53) |
424
+
425
+ **Seconds since the Epoch:**
426
+
427
+ | Format | Meaning |
428
+ | s | Number of seconds since 1970-01-01 00:00:00 UTC. |
429
+
430
+ **Literal string:**
431
+
432
+ | Format | Meaning |
433
+ | ------ | ------- |
434
+ | n | Newline character (\n) |
435
+ | t | Tab character (\t) |
436
+ | % | Literal "%" character |
437
+
438
+ **Combination:**
439
+
440
+ | Format | Meaning |
441
+ | ------ | ------- |
442
+ | c | date and time (%a %b %e %T %Y) |
443
+ | D | Date (%m/%d/%y) |
444
+ | F | The ISO 8601 date format (%Y-%m-%d) |
445
+ | v | VMS date (%e-%^b-%4Y) |
446
+ | x | Same as %D |
447
+ | X | Same as %T |
448
+ | r | 12-hour time (%I:%M:%S %p) |
449
+ | R | 24-hour time (%H:%M) |
450
+ | T | 24-hour time (%H:%M:%S) |
451
+
452
+ The default array contains the following patterns:
453
+
454
+ When a timezone argument (other than `default`) is explicitly provided:
455
+
456
+ ```
457
+ ['%FT%T.L', '%FT%T', '%F']
458
+ ```
459
+
460
+ otherwise:
461
+
462
+ ```
463
+ ['%FT%T.%L %Z', '%FT%T %Z', '%F %Z', '%FT%T.L', '%FT%T', '%F']
464
+ ```
465
+
466
+ Examples - Converting to Timestamp
467
+
468
+ ```puppet
469
+ $ts = Timestamp(1473150899) # 2016-09-06 08:34:59 UTC
470
+ $ts = Timestamp({string=>'2015', format=>'%Y'}) # 2015-01-01 00:00:00.000 UTC
471
+ $ts = Timestamp('Wed Aug 24 12:13:14 2016', '%c') # 2016-08-24 12:13:14 UTC
472
+ $ts = Timestamp('Wed Aug 24 12:13:14 2016 PDT', '%c %Z') # 2016-08-24 19:13:14.000 UTC
473
+ $ts = Timestamp('2016-08-24 12:13:14', '%F %T', 'PST') # 2016-08-24 20:13:14.000 UTC
474
+ $ts = Timestamp('2016-08-24T12:13:14', default, 'PST') # 2016-08-24 20:13:14.000 UTC
475
+
154
476
  ```
155
477
 
156
478
  Conversion to String
@@ -243,7 +565,7 @@ $str = String([10], "%(a") # produces '("10")'
243
565
  **Example:** Specifying type for values contained in an array
244
566
 
245
567
  ```puppet
246
- $formats = {
568
+ $formats = {
247
569
  Array => {
248
570
  format => '%(a',
249
571
  string_formats => { Integer => '%#x' }
@@ -301,7 +623,7 @@ Defaults to `s` at top level and `p` inside array or hash.
301
623
  ### Boolean to String
302
624
 
303
625
  | Format | Boolean Formats
304
- | ---- | -------------------
626
+ | ---- | -------------------
305
627
  | t T | String 'true'/'false' or 'True'/'False', first char if alternate form is used (i.e. 't'/'f' or 'T'/'F').
306
628
  | y Y | String 'yes'/'no', 'Yes'/'No', 'y'/'n' or 'Y'/'N' if alternative flag `#` is used.
307
629
  | dxXobB | Numeric value 0/1 in accordance with the given format which must be valid integer format.
@@ -337,6 +659,23 @@ Defaults to `s` at top level and `p` inside array or hash.
337
659
  | s | Same as d.
338
660
  | p | Same as d.
339
661
 
662
+ ### Binary value to String
663
+
664
+ | Format | Default formats
665
+ | ------ | ---------------
666
+ | s | binary as unquoted UTF-8 characters (errors if byte sequence is invalid UTF-8). Alternate form escapes non ascii bytes.
667
+ | p | 'Binary("<base64strict>")'
668
+ | b | '<base64>' - base64 string with newlines inserted
669
+ | B | '<base64strict>' - base64 strict string (without newlines inserted)
670
+ | u | '<base64urlsafe>' - base64 urlsafe string
671
+ | t | 'Binary' - outputs the name of the type only
672
+ | T | 'BINARY' - output the name of the type in all caps only
673
+
674
+ * The alternate form flag `#` will quote the binary or base64 text output.
675
+ * The format `%#s` allows invalid UTF-8 characters and outputs all non ascii bytes
676
+ as hex escaped characters on the form `\\xHH` where `H` is a hex digit.
677
+ * The width and precision values are applied to the text part only in `%p` format.
678
+
340
679
  ### Array & Tuple to String
341
680
 
342
681
  | Format | Array/Tuple Formats
@@ -375,7 +714,7 @@ The alternate form flag `#` will format each hash key/value entry indented on a
375
714
 
376
715
  ### Flags
377
716
 
378
- | Flag | Effect
717
+ | Flag | Effect
379
718
  | ------ | ------
380
719
  | (space) | A space instead of `+` for numeric output (`-` is shown), for containers skips delimiters.
381
720
  | # | Alternate format; prefix 0x/0x, 0 (octal) and 0b/0B for binary, Floats force decimal '.'. For g/G keep trailing 0.
@@ -405,6 +744,8 @@ When given a single value as argument:
405
744
  * An empty `Hash` becomes an empty array.
406
745
  * An `Array` is simply returned.
407
746
  * An `Iterable[T]` is turned into an array of `T` instances.
747
+ * A `Binary` is converted to an `Array[Integer[0,255]]` of byte values
748
+
408
749
 
409
750
  When given a second Boolean argument:
410
751
 
@@ -476,7 +817,7 @@ function SemVer.new(SemVerHash $hash_args)
476
817
  # SemVerRange objects.
477
818
  #
478
819
  $t = SemVer[
479
- SemVerRange('>=1.0.0 <2.0.0'),
820
+ SemVerRange('>=1.0.0 <2.0.0'),
480
821
  SemVerRange('>=3.0.0 <4.0.0')
481
822
  ]
482
823
  notice(SemVer('1.2.3') =~ $t) # true
@@ -521,10 +862,65 @@ function SemVerRange.new(
521
862
 
522
863
  For examples of `SemVerRange` use see "Creating a SemVer"
523
864
 
865
+ Creating a Binary
866
+ ---
867
+
868
+ A `Binary` object represents a sequence of bytes and it can be created from a String in Base64 format,
869
+ an Array containing byte values. A Binary can also be created from a Hash containing the value to convert to
870
+ a `Binary`.
871
+
872
+ The signatures are:
873
+
874
+ ```puppet
875
+ type ByteInteger = Integer[0,255]
876
+ type Base64Format = Enum["%b", "%u", "%B", "%s"]
877
+ type StringHash = Struct[{value => String, "format" => Optional[Base64Format]}]
878
+ type ArrayHash = Struct[{value => Array[ByteInteger]}]
879
+ type BinaryArgsHash = Variant[StringHash, ArrayHash]
880
+
881
+ function Binary.new(
882
+ String $base64_str,
883
+ Optional[Base64Format] $format
884
+ )
885
+
886
+
887
+ function Binary.new(
888
+ Array[ByteInteger] $byte_array
889
+ }
890
+
891
+ # Same as for String, or for Array, but where arguments are given in a Hash.
892
+ function Binary.new(BinaryArgsHash $hash_args)
893
+ ```
894
+
895
+ The formats have the following meaning:
896
+
897
+ | format | explanation |
898
+ | ---- | ---- |
899
+ | B | The data is in base64 strict encoding
900
+ | u | The data is in URL safe base64 encoding
901
+ | b | The data is in base64 encoding, padding as required by base64 strict, is added by default
902
+ | s | The data is a puppet string. The string must be valid UTF-8, or convertible to UTF-8 or an error is raised.
903
+ | r | (Ruby Raw) the byte sequence in the given string is used verbatim irrespective of possible encoding errors
904
+
905
+ * The default format is `%B`.
906
+ * Note that the format `%r` should be used sparingly, or not at all. It exists for backwards compatibility reasons when someone receiving
907
+ a string from some function and that string should be treated as Binary. Such code should be changed to return a Binary instead of a String.
908
+
909
+ **Examples:** Creating a Binary
910
+
911
+ ```puppet
912
+ # create the binary content "abc"
913
+ $a = Binary('YWJj')
914
+
915
+ # create the binary content from content in a module's file
916
+ $b = binary_file('mymodule/mypicture.jpg')
917
+ ```
918
+
524
919
  * Since 4.5.0
920
+ * Binary type since 4.8.0
525
921
 
526
922
  DOC
527
923
  ) do |args|
528
- function_fail(["new() is only available when parser/evaluator future is in effect"])
924
+ Error.is4x('new')
529
925
  end
530
926