puppet 8.2.0-x86-mingw32 → 8.4.0-x86-mingw32

Sign up to get free protection for your applications and to get access to all the features.
Files changed (1063) hide show
  1. checksums.yaml +4 -4
  2. data/Gemfile +1 -1
  3. data/Gemfile.lock +45 -43
  4. data/README.md +4 -4
  5. data/Rakefile +0 -27
  6. data/examples/enc/regexp_nodes/regexp_nodes.rb +1 -1
  7. data/ext/project_data.yaml +2 -2
  8. data/ext/windows/service/daemon.rb +4 -5
  9. data/lib/hiera/puppet_function.rb +3 -2
  10. data/lib/hiera/scope.rb +2 -2
  11. data/lib/hiera_puppet.rb +1 -3
  12. data/lib/puppet/agent/disabler.rb +2 -1
  13. data/lib/puppet/agent/locker.rb +1 -2
  14. data/lib/puppet/agent.rb +2 -1
  15. data/lib/puppet/application/agent.rb +292 -291
  16. data/lib/puppet/application/apply.rb +143 -139
  17. data/lib/puppet/application/catalog.rb +1 -0
  18. data/lib/puppet/application/config.rb +1 -0
  19. data/lib/puppet/application/describe.rb +53 -55
  20. data/lib/puppet/application/device.rb +150 -150
  21. data/lib/puppet/application/doc.rb +61 -60
  22. data/lib/puppet/application/epp.rb +1 -0
  23. data/lib/puppet/application/face_base.rb +8 -7
  24. data/lib/puppet/application/facts.rb +1 -0
  25. data/lib/puppet/application/filebucket.rb +186 -184
  26. data/lib/puppet/application/generate.rb +1 -0
  27. data/lib/puppet/application/help.rb +1 -0
  28. data/lib/puppet/application/indirection_base.rb +1 -0
  29. data/lib/puppet/application/lookup.rb +168 -171
  30. data/lib/puppet/application/module.rb +1 -0
  31. data/lib/puppet/application/node.rb +1 -0
  32. data/lib/puppet/application/parser.rb +1 -0
  33. data/lib/puppet/application/plugin.rb +1 -0
  34. data/lib/puppet/application/report.rb +1 -0
  35. data/lib/puppet/application/resource.rb +111 -108
  36. data/lib/puppet/application/script.rb +92 -93
  37. data/lib/puppet/application/ssl.rb +119 -83
  38. data/lib/puppet/application.rb +13 -8
  39. data/lib/puppet/application_support.rb +1 -1
  40. data/lib/puppet/coercion.rb +3 -2
  41. data/lib/puppet/compilable_resource_type.rb +1 -0
  42. data/lib/puppet/concurrent/lock.rb +1 -2
  43. data/lib/puppet/concurrent/synchronized.rb +1 -2
  44. data/lib/puppet/concurrent/thread_local_singleton.rb +1 -0
  45. data/lib/puppet/concurrent.rb +1 -0
  46. data/lib/puppet/configurer/downloader.rb +1 -1
  47. data/lib/puppet/configurer/fact_handler.rb +2 -1
  48. data/lib/puppet/configurer/plugin_handler.rb +1 -0
  49. data/lib/puppet/configurer.rb +17 -13
  50. data/lib/puppet/confine/any.rb +1 -0
  51. data/lib/puppet/confine/boolean.rb +1 -0
  52. data/lib/puppet/confine/exists.rb +1 -0
  53. data/lib/puppet/confine/false.rb +1 -0
  54. data/lib/puppet/confine/feature.rb +1 -0
  55. data/lib/puppet/confine/true.rb +1 -0
  56. data/lib/puppet/confine/variable.rb +1 -0
  57. data/lib/puppet/confine.rb +2 -0
  58. data/lib/puppet/confine_collection.rb +3 -1
  59. data/lib/puppet/confiner.rb +1 -0
  60. data/lib/puppet/context/trusted_information.rb +1 -0
  61. data/lib/puppet/context.rb +1 -0
  62. data/lib/puppet/daemon.rb +4 -1
  63. data/lib/puppet/data_binding.rb +2 -1
  64. data/lib/puppet/datatypes/error.rb +2 -1
  65. data/lib/puppet/datatypes/impl/error.rb +1 -0
  66. data/lib/puppet/datatypes.rb +5 -1
  67. data/lib/puppet/defaults.rb +24 -23
  68. data/lib/puppet/environments.rb +3 -2
  69. data/lib/puppet/error.rb +9 -7
  70. data/lib/puppet/etc.rb +6 -3
  71. data/lib/puppet/external/dot.rb +12 -31
  72. data/lib/puppet/face/catalog/select.rb +2 -1
  73. data/lib/puppet/face/catalog.rb +3 -2
  74. data/lib/puppet/face/config.rb +19 -21
  75. data/lib/puppet/face/epp.rb +8 -8
  76. data/lib/puppet/face/facts.rb +4 -3
  77. data/lib/puppet/face/generate.rb +2 -0
  78. data/lib/puppet/face/help.rb +8 -7
  79. data/lib/puppet/face/module/changes.rb +2 -0
  80. data/lib/puppet/face/module/install.rb +2 -1
  81. data/lib/puppet/face/module/list.rb +9 -10
  82. data/lib/puppet/face/module/uninstall.rb +1 -0
  83. data/lib/puppet/face/module.rb +1 -0
  84. data/lib/puppet/face/node/clean.rb +2 -1
  85. data/lib/puppet/face/node.rb +2 -1
  86. data/lib/puppet/face/parser.rb +3 -3
  87. data/lib/puppet/face/plugin.rb +2 -1
  88. data/lib/puppet/face/report.rb +2 -1
  89. data/lib/puppet/face/resource.rb +1 -0
  90. data/lib/puppet/face.rb +1 -0
  91. data/lib/puppet/feature/base.rb +2 -1
  92. data/lib/puppet/feature/bolt.rb +1 -0
  93. data/lib/puppet/feature/cfpropertylist.rb +1 -0
  94. data/lib/puppet/feature/eventlog.rb +1 -0
  95. data/lib/puppet/feature/hiera_eyaml.rb +1 -0
  96. data/lib/puppet/feature/hocon.rb +1 -0
  97. data/lib/puppet/feature/libuser.rb +4 -3
  98. data/lib/puppet/feature/msgpack.rb +1 -0
  99. data/lib/puppet/feature/pe_license.rb +2 -1
  100. data/lib/puppet/feature/pson.rb +1 -0
  101. data/lib/puppet/feature/selinux.rb +1 -0
  102. data/lib/puppet/feature/ssh.rb +1 -0
  103. data/lib/puppet/feature/telnet.rb +1 -0
  104. data/lib/puppet/feature/zlib.rb +1 -0
  105. data/lib/puppet/ffi/posix/constants.rb +1 -0
  106. data/lib/puppet/ffi/posix/functions.rb +1 -1
  107. data/lib/puppet/ffi/posix.rb +1 -0
  108. data/lib/puppet/ffi/windows/api_types.rb +1 -0
  109. data/lib/puppet/ffi/windows/constants.rb +78 -77
  110. data/lib/puppet/ffi/windows/functions.rb +73 -73
  111. data/lib/puppet/ffi/windows/structs.rb +3 -3
  112. data/lib/puppet/ffi/windows.rb +1 -0
  113. data/lib/puppet/file_bucket/dipper.rb +7 -1
  114. data/lib/puppet/file_bucket/file.rb +1 -0
  115. data/lib/puppet/file_bucket.rb +1 -0
  116. data/lib/puppet/file_serving/base.rb +13 -6
  117. data/lib/puppet/file_serving/configuration/parser.rb +3 -1
  118. data/lib/puppet/file_serving/configuration.rb +5 -3
  119. data/lib/puppet/file_serving/content.rb +1 -0
  120. data/lib/puppet/file_serving/fileset.rb +9 -6
  121. data/lib/puppet/file_serving/http_metadata.rb +1 -3
  122. data/lib/puppet/file_serving/metadata.rb +9 -10
  123. data/lib/puppet/file_serving/mount/file.rb +6 -3
  124. data/lib/puppet/file_serving/mount/locales.rb +2 -1
  125. data/lib/puppet/file_serving/mount/modules.rb +2 -0
  126. data/lib/puppet/file_serving/mount/pluginfacts.rb +2 -1
  127. data/lib/puppet/file_serving/mount/plugins.rb +2 -1
  128. data/lib/puppet/file_serving/mount/scripts.rb +2 -0
  129. data/lib/puppet/file_serving/mount/tasks.rb +2 -0
  130. data/lib/puppet/file_serving/mount.rb +2 -0
  131. data/lib/puppet/file_serving/terminus_helper.rb +1 -0
  132. data/lib/puppet/file_serving/terminus_selector.rb +1 -0
  133. data/lib/puppet/file_serving.rb +1 -0
  134. data/lib/puppet/file_system/file_impl.rb +2 -2
  135. data/lib/puppet/file_system/jruby.rb +1 -0
  136. data/lib/puppet/file_system/memory_file.rb +2 -0
  137. data/lib/puppet/file_system/memory_impl.rb +3 -0
  138. data/lib/puppet/file_system/path_pattern.rb +1 -0
  139. data/lib/puppet/file_system/posix.rb +5 -1
  140. data/lib/puppet/file_system/uniquefile.rb +11 -11
  141. data/lib/puppet/file_system/windows.rb +4 -2
  142. data/lib/puppet/file_system.rb +3 -2
  143. data/lib/puppet/forge/cache.rb +1 -1
  144. data/lib/puppet/forge/errors.rb +1 -3
  145. data/lib/puppet/forge/repository.rb +2 -0
  146. data/lib/puppet/forge.rb +3 -0
  147. data/lib/puppet/functions/abs.rb +2 -1
  148. data/lib/puppet/functions/alert.rb +1 -0
  149. data/lib/puppet/functions/all.rb +1 -0
  150. data/lib/puppet/functions/annotate.rb +1 -0
  151. data/lib/puppet/functions/any.rb +1 -0
  152. data/lib/puppet/functions/assert_type.rb +1 -0
  153. data/lib/puppet/functions/binary_file.rb +3 -1
  154. data/lib/puppet/functions/break.rb +2 -1
  155. data/lib/puppet/functions/call.rb +1 -1
  156. data/lib/puppet/functions/camelcase.rb +1 -1
  157. data/lib/puppet/functions/capitalize.rb +1 -1
  158. data/lib/puppet/functions/ceiling.rb +2 -2
  159. data/lib/puppet/functions/chomp.rb +1 -1
  160. data/lib/puppet/functions/chop.rb +1 -1
  161. data/lib/puppet/functions/compare.rb +1 -0
  162. data/lib/puppet/functions/contain.rb +1 -0
  163. data/lib/puppet/functions/convert_to.rb +1 -0
  164. data/lib/puppet/functions/crit.rb +1 -0
  165. data/lib/puppet/functions/debug.rb +1 -0
  166. data/lib/puppet/functions/defined.rb +7 -4
  167. data/lib/puppet/functions/dig.rb +10 -8
  168. data/lib/puppet/functions/downcase.rb +1 -0
  169. data/lib/puppet/functions/each.rb +1 -0
  170. data/lib/puppet/functions/emerg.rb +1 -0
  171. data/lib/puppet/functions/empty.rb +1 -0
  172. data/lib/puppet/functions/epp.rb +1 -1
  173. data/lib/puppet/functions/err.rb +1 -0
  174. data/lib/puppet/functions/eyaml_lookup_key.rb +6 -4
  175. data/lib/puppet/functions/filter.rb +1 -0
  176. data/lib/puppet/functions/find_file.rb +1 -0
  177. data/lib/puppet/functions/find_template.rb +1 -0
  178. data/lib/puppet/functions/flatten.rb +1 -0
  179. data/lib/puppet/functions/floor.rb +2 -2
  180. data/lib/puppet/functions/get.rb +2 -1
  181. data/lib/puppet/functions/getvar.rb +2 -1
  182. data/lib/puppet/functions/hiera.rb +1 -0
  183. data/lib/puppet/functions/hiera_array.rb +1 -0
  184. data/lib/puppet/functions/hiera_hash.rb +1 -0
  185. data/lib/puppet/functions/hiera_include.rb +2 -0
  186. data/lib/puppet/functions/hocon_data.rb +1 -0
  187. data/lib/puppet/functions/import.rb +1 -0
  188. data/lib/puppet/functions/include.rb +1 -0
  189. data/lib/puppet/functions/index.rb +2 -2
  190. data/lib/puppet/functions/info.rb +1 -0
  191. data/lib/puppet/functions/inline_epp.rb +1 -1
  192. data/lib/puppet/functions/join.rb +2 -1
  193. data/lib/puppet/functions/json_data.rb +1 -0
  194. data/lib/puppet/functions/keys.rb +1 -0
  195. data/lib/puppet/functions/length.rb +1 -1
  196. data/lib/puppet/functions/lest.rb +1 -0
  197. data/lib/puppet/functions/lookup.rb +8 -9
  198. data/lib/puppet/functions/lstrip.rb +1 -1
  199. data/lib/puppet/functions/map.rb +1 -0
  200. data/lib/puppet/functions/match.rb +3 -1
  201. data/lib/puppet/functions/max.rb +4 -4
  202. data/lib/puppet/functions/min.rb +4 -4
  203. data/lib/puppet/functions/module_directory.rb +1 -0
  204. data/lib/puppet/functions/new.rb +2 -1
  205. data/lib/puppet/functions/next.rb +1 -0
  206. data/lib/puppet/functions/notice.rb +1 -0
  207. data/lib/puppet/functions/reduce.rb +1 -1
  208. data/lib/puppet/functions/regsubst.rb +1 -0
  209. data/lib/puppet/functions/require.rb +2 -0
  210. data/lib/puppet/functions/return.rb +1 -0
  211. data/lib/puppet/functions/reverse_each.rb +1 -0
  212. data/lib/puppet/functions/round.rb +1 -0
  213. data/lib/puppet/functions/rstrip.rb +1 -1
  214. data/lib/puppet/functions/scanf.rb +1 -0
  215. data/lib/puppet/functions/size.rb +1 -2
  216. data/lib/puppet/functions/slice.rb +2 -0
  217. data/lib/puppet/functions/sort.rb +1 -0
  218. data/lib/puppet/functions/split.rb +29 -1
  219. data/lib/puppet/functions/step.rb +1 -0
  220. data/lib/puppet/functions/strftime.rb +3 -2
  221. data/lib/puppet/functions/strip.rb +1 -1
  222. data/lib/puppet/functions/then.rb +2 -0
  223. data/lib/puppet/functions/tree_each.rb +1 -1
  224. data/lib/puppet/functions/type.rb +1 -0
  225. data/lib/puppet/functions/unique.rb +2 -1
  226. data/lib/puppet/functions/unwrap.rb +1 -0
  227. data/lib/puppet/functions/upcase.rb +1 -0
  228. data/lib/puppet/functions/values.rb +1 -0
  229. data/lib/puppet/functions/versioncmp.rb +2 -2
  230. data/lib/puppet/functions/warning.rb +1 -0
  231. data/lib/puppet/functions/with.rb +1 -0
  232. data/lib/puppet/functions/yaml_data.rb +1 -0
  233. data/lib/puppet/functions.rb +9 -9
  234. data/lib/puppet/generate/models/type/property.rb +2 -0
  235. data/lib/puppet/generate/models/type/type.rb +2 -0
  236. data/lib/puppet/generate/type.rb +6 -1
  237. data/lib/puppet/gettext/config.rb +6 -0
  238. data/lib/puppet/gettext/module_translations.rb +1 -1
  239. data/lib/puppet/gettext/stubs.rb +1 -0
  240. data/lib/puppet/graph/key.rb +1 -0
  241. data/lib/puppet/graph/prioritizer.rb +1 -0
  242. data/lib/puppet/graph/rb_tree_map.rb +12 -2
  243. data/lib/puppet/graph/relationship_graph.rb +3 -2
  244. data/lib/puppet/graph/sequential_prioritizer.rb +1 -0
  245. data/lib/puppet/graph/simple_graph.rb +38 -31
  246. data/lib/puppet/graph.rb +1 -0
  247. data/lib/puppet/http/client.rb +4 -1
  248. data/lib/puppet/http/dns.rb +5 -5
  249. data/lib/puppet/http/errors.rb +1 -0
  250. data/lib/puppet/http/external_client.rb +2 -2
  251. data/lib/puppet/http/factory.rb +1 -0
  252. data/lib/puppet/http/pool.rb +2 -1
  253. data/lib/puppet/http/pool_entry.rb +1 -0
  254. data/lib/puppet/http/proxy.rb +3 -2
  255. data/lib/puppet/http/redirector.rb +1 -0
  256. data/lib/puppet/http/resolver/server_list.rb +1 -1
  257. data/lib/puppet/http/resolver/settings.rb +1 -1
  258. data/lib/puppet/http/resolver/srv.rb +1 -1
  259. data/lib/puppet/http/resolver.rb +1 -0
  260. data/lib/puppet/http/response.rb +1 -0
  261. data/lib/puppet/http/response_converter.rb +1 -0
  262. data/lib/puppet/http/response_net_http.rb +1 -1
  263. data/lib/puppet/http/retry_after_handler.rb +1 -1
  264. data/lib/puppet/http/service/ca.rb +1 -0
  265. data/lib/puppet/http/service/compiler.rb +9 -3
  266. data/lib/puppet/http/service/file_server.rb +2 -1
  267. data/lib/puppet/http/service/puppetserver.rb +1 -1
  268. data/lib/puppet/http/service/report.rb +1 -1
  269. data/lib/puppet/http/service.rb +1 -0
  270. data/lib/puppet/http/session.rb +2 -1
  271. data/lib/puppet/http/site.rb +1 -0
  272. data/lib/puppet/http.rb +1 -0
  273. data/lib/puppet/indirector/catalog/compiler.rb +50 -40
  274. data/lib/puppet/indirector/catalog/json.rb +1 -0
  275. data/lib/puppet/indirector/catalog/msgpack.rb +1 -0
  276. data/lib/puppet/indirector/catalog/rest.rb +9 -0
  277. data/lib/puppet/indirector/catalog/store_configs.rb +1 -2
  278. data/lib/puppet/indirector/catalog/yaml.rb +1 -0
  279. data/lib/puppet/indirector/code.rb +1 -0
  280. data/lib/puppet/indirector/data_binding/hiera.rb +1 -0
  281. data/lib/puppet/indirector/data_binding/none.rb +1 -0
  282. data/lib/puppet/indirector/direct_file_server.rb +3 -1
  283. data/lib/puppet/indirector/envelope.rb +1 -0
  284. data/lib/puppet/indirector/errors.rb +1 -0
  285. data/lib/puppet/indirector/exec.rb +1 -0
  286. data/lib/puppet/indirector/face.rb +7 -6
  287. data/lib/puppet/indirector/fact_search.rb +1 -0
  288. data/lib/puppet/indirector/facts/facter.rb +3 -1
  289. data/lib/puppet/indirector/facts/json.rb +1 -0
  290. data/lib/puppet/indirector/facts/memory.rb +1 -0
  291. data/lib/puppet/indirector/facts/network_device.rb +1 -0
  292. data/lib/puppet/indirector/facts/rest.rb +1 -0
  293. data/lib/puppet/indirector/facts/store_configs.rb +1 -1
  294. data/lib/puppet/indirector/facts/yaml.rb +1 -0
  295. data/lib/puppet/indirector/file_bucket_file/file.rb +11 -6
  296. data/lib/puppet/indirector/file_bucket_file/rest.rb +2 -0
  297. data/lib/puppet/indirector/file_bucket_file/selector.rb +1 -0
  298. data/lib/puppet/indirector/file_content/file.rb +1 -0
  299. data/lib/puppet/indirector/file_content/file_server.rb +1 -0
  300. data/lib/puppet/indirector/file_content/rest.rb +1 -0
  301. data/lib/puppet/indirector/file_content/selector.rb +1 -0
  302. data/lib/puppet/indirector/file_content.rb +1 -0
  303. data/lib/puppet/indirector/file_metadata/file.rb +1 -0
  304. data/lib/puppet/indirector/file_metadata/file_server.rb +1 -0
  305. data/lib/puppet/indirector/file_metadata/http.rb +1 -0
  306. data/lib/puppet/indirector/file_metadata/rest.rb +1 -0
  307. data/lib/puppet/indirector/file_metadata/selector.rb +1 -0
  308. data/lib/puppet/indirector/file_metadata.rb +1 -0
  309. data/lib/puppet/indirector/file_server.rb +2 -0
  310. data/lib/puppet/indirector/generic_http.rb +1 -0
  311. data/lib/puppet/indirector/hiera.rb +5 -4
  312. data/lib/puppet/indirector/indirection.rb +12 -2
  313. data/lib/puppet/indirector/json.rb +3 -1
  314. data/lib/puppet/indirector/memory.rb +2 -0
  315. data/lib/puppet/indirector/msgpack.rb +5 -2
  316. data/lib/puppet/indirector/node/exec.rb +3 -2
  317. data/lib/puppet/indirector/node/json.rb +1 -1
  318. data/lib/puppet/indirector/node/memory.rb +1 -0
  319. data/lib/puppet/indirector/node/msgpack.rb +1 -0
  320. data/lib/puppet/indirector/node/plain.rb +1 -0
  321. data/lib/puppet/indirector/node/rest.rb +1 -0
  322. data/lib/puppet/indirector/node/store_configs.rb +1 -2
  323. data/lib/puppet/indirector/node/yaml.rb +1 -0
  324. data/lib/puppet/indirector/none.rb +1 -0
  325. data/lib/puppet/indirector/plain.rb +1 -0
  326. data/lib/puppet/indirector/report/json.rb +1 -0
  327. data/lib/puppet/indirector/report/msgpack.rb +1 -0
  328. data/lib/puppet/indirector/report/processor.rb +2 -0
  329. data/lib/puppet/indirector/report/rest.rb +1 -0
  330. data/lib/puppet/indirector/report/yaml.rb +1 -0
  331. data/lib/puppet/indirector/request.rb +7 -5
  332. data/lib/puppet/indirector/resource/ral.rb +1 -0
  333. data/lib/puppet/indirector/resource/store_configs.rb +1 -0
  334. data/lib/puppet/indirector/resource/validator.rb +1 -0
  335. data/lib/puppet/indirector/rest.rb +1 -0
  336. data/lib/puppet/indirector/store_configs.rb +1 -0
  337. data/lib/puppet/indirector/terminus.rb +4 -1
  338. data/lib/puppet/indirector/yaml.rb +1 -0
  339. data/lib/puppet/indirector.rb +2 -0
  340. data/lib/puppet/info_service/class_information_service.rb +5 -3
  341. data/lib/puppet/info_service/plan_information_service.rb +1 -0
  342. data/lib/puppet/info_service/task_information_service.rb +2 -1
  343. data/lib/puppet/interface/action.rb +32 -27
  344. data/lib/puppet/interface/action_builder.rb +14 -14
  345. data/lib/puppet/interface/action_manager.rb +2 -0
  346. data/lib/puppet/interface/documentation.rb +21 -15
  347. data/lib/puppet/interface/face_collection.rb +5 -2
  348. data/lib/puppet/interface/option.rb +15 -4
  349. data/lib/puppet/interface/option_builder.rb +13 -9
  350. data/lib/puppet/interface/option_manager.rb +3 -2
  351. data/lib/puppet/interface.rb +3 -3
  352. data/lib/puppet/loaders.rb +1 -1
  353. data/lib/puppet/metatype/manager.rb +9 -8
  354. data/lib/puppet/module/plan.rb +10 -4
  355. data/lib/puppet/module/task.rb +8 -2
  356. data/lib/puppet/module.rb +13 -3
  357. data/lib/puppet/module_tool/applications/application.rb +6 -4
  358. data/lib/puppet/module_tool/applications/checksummer.rb +1 -2
  359. data/lib/puppet/module_tool/applications/installer.rb +32 -45
  360. data/lib/puppet/module_tool/applications/uninstaller.rb +22 -21
  361. data/lib/puppet/module_tool/applications/unpacker.rb +3 -0
  362. data/lib/puppet/module_tool/applications/upgrader.rb +28 -26
  363. data/lib/puppet/module_tool/applications.rb +1 -0
  364. data/lib/puppet/module_tool/checksums.rb +1 -1
  365. data/lib/puppet/module_tool/contents_description.rb +1 -2
  366. data/lib/puppet/module_tool/dependency.rb +1 -1
  367. data/lib/puppet/module_tool/errors/base.rb +1 -0
  368. data/lib/puppet/module_tool/errors/installer.rb +4 -4
  369. data/lib/puppet/module_tool/errors/shared.rb +12 -12
  370. data/lib/puppet/module_tool/errors/uninstaller.rb +2 -2
  371. data/lib/puppet/module_tool/errors/upgrader.rb +3 -3
  372. data/lib/puppet/module_tool/errors.rb +1 -0
  373. data/lib/puppet/module_tool/install_directory.rb +6 -4
  374. data/lib/puppet/module_tool/installed_modules.rb +2 -0
  375. data/lib/puppet/module_tool/local_tarball.rb +3 -0
  376. data/lib/puppet/module_tool/metadata.rb +21 -20
  377. data/lib/puppet/module_tool/shared_behaviors.rb +23 -21
  378. data/lib/puppet/module_tool/tar/gnu.rb +1 -0
  379. data/lib/puppet/module_tool/tar/mini.rb +1 -0
  380. data/lib/puppet/module_tool/tar.rb +2 -1
  381. data/lib/puppet/module_tool.rb +2 -2
  382. data/lib/puppet/network/authconfig.rb +1 -0
  383. data/lib/puppet/network/authorization.rb +1 -0
  384. data/lib/puppet/network/client_request.rb +1 -0
  385. data/lib/puppet/network/format.rb +5 -0
  386. data/lib/puppet/network/format_handler.rb +2 -1
  387. data/lib/puppet/network/format_support.rb +6 -5
  388. data/lib/puppet/network/formats.rb +18 -14
  389. data/lib/puppet/network/http/api/indirected_routes.rb +8 -8
  390. data/lib/puppet/network/http/api/indirection_type.rb +1 -1
  391. data/lib/puppet/network/http/api/master/v3/environments.rb +1 -0
  392. data/lib/puppet/network/http/api/master/v3.rb +1 -0
  393. data/lib/puppet/network/http/api/master.rb +1 -0
  394. data/lib/puppet/network/http/api/server/v3/environments.rb +20 -14
  395. data/lib/puppet/network/http/api/server/v3.rb +13 -13
  396. data/lib/puppet/network/http/api/server.rb +1 -0
  397. data/lib/puppet/network/http/api.rb +11 -10
  398. data/lib/puppet/network/http/connection.rb +1 -0
  399. data/lib/puppet/network/http/error.rb +2 -1
  400. data/lib/puppet/network/http/handler.rb +3 -2
  401. data/lib/puppet/network/http/issues.rb +1 -0
  402. data/lib/puppet/network/http/memory_response.rb +2 -1
  403. data/lib/puppet/network/http/request.rb +13 -6
  404. data/lib/puppet/network/http/response.rb +1 -0
  405. data/lib/puppet/network/http/route.rb +4 -2
  406. data/lib/puppet/network/http.rb +1 -0
  407. data/lib/puppet/network/http_pool.rb +2 -1
  408. data/lib/puppet/network/uri.rb +1 -0
  409. data/lib/puppet/network.rb +1 -0
  410. data/lib/puppet/node/environment.rb +12 -9
  411. data/lib/puppet/node/facts.rb +2 -1
  412. data/lib/puppet/node.rb +3 -2
  413. data/lib/puppet/pal/catalog_compiler.rb +1 -3
  414. data/lib/puppet/pal/compiler.rb +6 -2
  415. data/lib/puppet/pal/function_signature.rb +2 -1
  416. data/lib/puppet/pal/json_catalog_encoder.rb +5 -1
  417. data/lib/puppet/pal/pal_api.rb +1 -0
  418. data/lib/puppet/pal/pal_impl.rb +20 -19
  419. data/lib/puppet/pal/plan_signature.rb +2 -1
  420. data/lib/puppet/pal/script_compiler.rb +3 -2
  421. data/lib/puppet/pal/task_signature.rb +14 -9
  422. data/lib/puppet/parameter/boolean.rb +1 -0
  423. data/lib/puppet/parameter/package_options.rb +1 -0
  424. data/lib/puppet/parameter/path.rb +3 -0
  425. data/lib/puppet/parameter/value.rb +1 -0
  426. data/lib/puppet/parameter/value_collection.rb +6 -6
  427. data/lib/puppet/parameter.rb +4 -3
  428. data/lib/puppet/parser/abstract_compiler.rb +0 -2
  429. data/lib/puppet/parser/ast/block_expression.rb +1 -0
  430. data/lib/puppet/parser/ast/branch.rb +1 -0
  431. data/lib/puppet/parser/ast/hostclass.rb +1 -0
  432. data/lib/puppet/parser/ast/leaf.rb +2 -0
  433. data/lib/puppet/parser/ast/node.rb +1 -0
  434. data/lib/puppet/parser/ast/pops_bridge.rb +6 -6
  435. data/lib/puppet/parser/ast/resource.rb +2 -3
  436. data/lib/puppet/parser/ast/resource_instance.rb +2 -0
  437. data/lib/puppet/parser/ast/resourceparam.rb +6 -5
  438. data/lib/puppet/parser/ast/top_level_construct.rb +1 -0
  439. data/lib/puppet/parser/ast.rb +4 -3
  440. data/lib/puppet/parser/catalog_compiler.rb +1 -2
  441. data/lib/puppet/parser/compiler/catalog_validator/relationship_validator.rb +3 -0
  442. data/lib/puppet/parser/compiler/catalog_validator.rb +1 -0
  443. data/lib/puppet/parser/compiler.rb +10 -8
  444. data/lib/puppet/parser/e4_parser_adapter.rb +15 -15
  445. data/lib/puppet/parser/files.rb +5 -4
  446. data/lib/puppet/parser/functions/assert_type.rb +55 -54
  447. data/lib/puppet/parser/functions/binary_file.rb +19 -18
  448. data/lib/puppet/parser/functions/break.rb +35 -34
  449. data/lib/puppet/parser/functions/contain.rb +1 -0
  450. data/lib/puppet/parser/functions/create_resources.rb +8 -6
  451. data/lib/puppet/parser/functions/defined.rb +102 -101
  452. data/lib/puppet/parser/functions/dig.rb +33 -32
  453. data/lib/puppet/parser/functions/digest.rb +1 -0
  454. data/lib/puppet/parser/functions/each.rb +99 -98
  455. data/lib/puppet/parser/functions/epp.rb +2 -2
  456. data/lib/puppet/parser/functions/fail.rb +9 -8
  457. data/lib/puppet/parser/functions/file.rb +14 -13
  458. data/lib/puppet/parser/functions/filter.rb +74 -73
  459. data/lib/puppet/parser/functions/find_file.rb +22 -21
  460. data/lib/puppet/parser/functions/fqdn_rand.rb +23 -22
  461. data/lib/puppet/parser/functions/generate.rb +20 -20
  462. data/lib/puppet/parser/functions/hiera.rb +94 -93
  463. data/lib/puppet/parser/functions/hiera_array.rb +82 -81
  464. data/lib/puppet/parser/functions/hiera_hash.rb +92 -91
  465. data/lib/puppet/parser/functions/hiera_include.rb +92 -91
  466. data/lib/puppet/parser/functions/include.rb +2 -1
  467. data/lib/puppet/parser/functions/inline_epp.rb +2 -2
  468. data/lib/puppet/parser/functions/inline_template.rb +11 -11
  469. data/lib/puppet/parser/functions/lest.rb +44 -43
  470. data/lib/puppet/parser/functions/lookup.rb +131 -130
  471. data/lib/puppet/parser/functions/map.rb +71 -70
  472. data/lib/puppet/parser/functions/match.rb +39 -38
  473. data/lib/puppet/parser/functions/md5.rb +2 -1
  474. data/lib/puppet/parser/functions/new.rb +985 -984
  475. data/lib/puppet/parser/functions/next.rb +34 -33
  476. data/lib/puppet/parser/functions/realize.rb +9 -9
  477. data/lib/puppet/parser/functions/reduce.rb +132 -131
  478. data/lib/puppet/parser/functions/regsubst.rb +6 -5
  479. data/lib/puppet/parser/functions/require.rb +5 -4
  480. data/lib/puppet/parser/functions/return.rb +88 -87
  481. data/lib/puppet/parser/functions/reverse_each.rb +78 -77
  482. data/lib/puppet/parser/functions/scanf.rb +28 -27
  483. data/lib/puppet/parser/functions/sha1.rb +2 -1
  484. data/lib/puppet/parser/functions/sha256.rb +1 -0
  485. data/lib/puppet/parser/functions/shellquote.rb +1 -0
  486. data/lib/puppet/parser/functions/slice.rb +34 -33
  487. data/lib/puppet/parser/functions/split.rb +5 -6
  488. data/lib/puppet/parser/functions/sprintf.rb +3 -3
  489. data/lib/puppet/parser/functions/step.rb +79 -78
  490. data/lib/puppet/parser/functions/strftime.rb +180 -179
  491. data/lib/puppet/parser/functions/tag.rb +7 -6
  492. data/lib/puppet/parser/functions/tagged.rb +13 -12
  493. data/lib/puppet/parser/functions/template.rb +24 -23
  494. data/lib/puppet/parser/functions/then.rb +68 -67
  495. data/lib/puppet/parser/functions/type.rb +48 -47
  496. data/lib/puppet/parser/functions/versioncmp.rb +1 -1
  497. data/lib/puppet/parser/functions/with.rb +23 -22
  498. data/lib/puppet/parser/functions.rb +3 -1
  499. data/lib/puppet/parser/parser_factory.rb +1 -0
  500. data/lib/puppet/parser/relationship.rb +3 -0
  501. data/lib/puppet/parser/resource/param.rb +1 -0
  502. data/lib/puppet/parser/resource.rb +10 -4
  503. data/lib/puppet/parser/scope.rb +40 -32
  504. data/lib/puppet/parser/script_compiler.rb +5 -6
  505. data/lib/puppet/parser/templatewrapper.rb +1 -0
  506. data/lib/puppet/parser/type_loader.rb +19 -17
  507. data/lib/puppet/parser.rb +1 -0
  508. data/lib/puppet/plugins/configuration.rb +1 -0
  509. data/lib/puppet/plugins/syntax_checkers.rb +1 -1
  510. data/lib/puppet/plugins.rb +1 -0
  511. data/lib/puppet/pops/adaptable.rb +3 -1
  512. data/lib/puppet/pops/adapters.rb +3 -1
  513. data/lib/puppet/pops/evaluator/access_operator.rb +79 -65
  514. data/lib/puppet/pops/evaluator/callable_signature.rb +1 -1
  515. data/lib/puppet/pops/evaluator/closure.rb +273 -277
  516. data/lib/puppet/pops/evaluator/collector_transformer.rb +11 -9
  517. data/lib/puppet/pops/evaluator/collectors/abstract_collector.rb +1 -0
  518. data/lib/puppet/pops/evaluator/collectors/catalog_collector.rb +2 -2
  519. data/lib/puppet/pops/evaluator/collectors/exported_collector.rb +4 -4
  520. data/lib/puppet/pops/evaluator/collectors/fixed_set_collector.rb +1 -1
  521. data/lib/puppet/pops/evaluator/compare_operator.rb +15 -3
  522. data/lib/puppet/pops/evaluator/deferred_resolver.rb +2 -2
  523. data/lib/puppet/pops/evaluator/epp_evaluator.rb +10 -10
  524. data/lib/puppet/pops/evaluator/evaluator_impl.rb +140 -138
  525. data/lib/puppet/pops/evaluator/external_syntax_support.rb +1 -1
  526. data/lib/puppet/pops/evaluator/json_strict_literal_evaluator.rb +2 -1
  527. data/lib/puppet/pops/evaluator/literal_evaluator.rb +1 -1
  528. data/lib/puppet/pops/evaluator/puppet_proc.rb +2 -0
  529. data/lib/puppet/pops/evaluator/relationship_operator.rb +5 -3
  530. data/lib/puppet/pops/evaluator/runtime3_converter.rb +21 -19
  531. data/lib/puppet/pops/evaluator/runtime3_resource_support.rb +31 -33
  532. data/lib/puppet/pops/evaluator/runtime3_support.rb +16 -19
  533. data/lib/puppet/pops/functions/dispatch.rb +1 -0
  534. data/lib/puppet/pops/functions/dispatcher.rb +1 -1
  535. data/lib/puppet/pops/functions/function.rb +1 -2
  536. data/lib/puppet/pops/issue_reporter.rb +19 -17
  537. data/lib/puppet/pops/issues.rb +8 -4
  538. data/lib/puppet/pops/label_provider.rb +1 -0
  539. data/lib/puppet/pops/loader/base_loader.rb +2 -2
  540. data/lib/puppet/pops/loader/dependency_loader.rb +3 -0
  541. data/lib/puppet/pops/loader/gem_support.rb +3 -1
  542. data/lib/puppet/pops/loader/generic_plan_instantiator.rb +1 -0
  543. data/lib/puppet/pops/loader/loader.rb +1 -2
  544. data/lib/puppet/pops/loader/loader_paths.rb +24 -23
  545. data/lib/puppet/pops/loader/module_loaders.rb +28 -28
  546. data/lib/puppet/pops/loader/predefined_loader.rb +1 -2
  547. data/lib/puppet/pops/loader/puppet_function_instantiator.rb +4 -2
  548. data/lib/puppet/pops/loader/puppet_plan_instantiator.rb +4 -2
  549. data/lib/puppet/pops/loader/puppet_resource_type_impl_instantiator.rb +1 -1
  550. data/lib/puppet/pops/loader/ruby_data_type_instantiator.rb +4 -1
  551. data/lib/puppet/pops/loader/ruby_function_instantiator.rb +4 -1
  552. data/lib/puppet/pops/loader/ruby_legacy_function_instantiator.rb +6 -2
  553. data/lib/puppet/pops/loader/runtime3_type_loader.rb +2 -2
  554. data/lib/puppet/pops/loader/simple_environment_loader.rb +1 -2
  555. data/lib/puppet/pops/loader/static_loader.rb +22 -21
  556. data/lib/puppet/pops/loader/task_instantiator.rb +1 -0
  557. data/lib/puppet/pops/loader/type_definition_instantiator.rb +6 -4
  558. data/lib/puppet/pops/loader/typed_name.rb +1 -0
  559. data/lib/puppet/pops/loader/uri_helper.rb +1 -0
  560. data/lib/puppet/pops/loaders.rb +21 -18
  561. data/lib/puppet/pops/lookup/configured_data_provider.rb +1 -0
  562. data/lib/puppet/pops/lookup/context.rb +24 -23
  563. data/lib/puppet/pops/lookup/data_adapter.rb +1 -0
  564. data/lib/puppet/pops/lookup/data_dig_function_provider.rb +2 -2
  565. data/lib/puppet/pops/lookup/data_hash_function_provider.rb +1 -0
  566. data/lib/puppet/pops/lookup/data_provider.rb +1 -0
  567. data/lib/puppet/pops/lookup/environment_data_provider.rb +1 -0
  568. data/lib/puppet/pops/lookup/explainer.rb +35 -34
  569. data/lib/puppet/pops/lookup/function_provider.rb +7 -6
  570. data/lib/puppet/pops/lookup/global_data_provider.rb +1 -1
  571. data/lib/puppet/pops/lookup/hiera_config.rb +137 -101
  572. data/lib/puppet/pops/lookup/interpolation.rb +5 -1
  573. data/lib/puppet/pops/lookup/invocation.rb +3 -0
  574. data/lib/puppet/pops/lookup/key_recorder.rb +3 -1
  575. data/lib/puppet/pops/lookup/location_resolver.rb +2 -1
  576. data/lib/puppet/pops/lookup/lookup_adapter.rb +22 -20
  577. data/lib/puppet/pops/lookup/lookup_key.rb +1 -0
  578. data/lib/puppet/pops/lookup/lookup_key_function_provider.rb +1 -0
  579. data/lib/puppet/pops/lookup/module_data_provider.rb +3 -1
  580. data/lib/puppet/pops/lookup/sub_lookup.rb +5 -2
  581. data/lib/puppet/pops/lookup.rb +13 -8
  582. data/lib/puppet/pops/merge_strategy.rb +5 -2
  583. data/lib/puppet/pops/migration/migration_checker.rb +3 -1
  584. data/lib/puppet/pops/model/ast.rb +786 -685
  585. data/lib/puppet/pops/model/ast_transformer.rb +4 -3
  586. data/lib/puppet/pops/model/factory.rb +18 -14
  587. data/lib/puppet/pops/model/model_label_provider.rb +1 -1
  588. data/lib/puppet/pops/model/model_tree_dumper.rb +10 -9
  589. data/lib/puppet/pops/model/pn_transformer.rb +4 -6
  590. data/lib/puppet/pops/model/tree_dumper.rb +3 -1
  591. data/lib/puppet/pops/parser/code_merger.rb +0 -1
  592. data/lib/puppet/pops/parser/epp_parser.rb +1 -1
  593. data/lib/puppet/pops/parser/epp_support.rb +3 -3
  594. data/lib/puppet/pops/parser/evaluating_parser.rb +6 -3
  595. data/lib/puppet/pops/parser/heredoc_support.rb +6 -7
  596. data/lib/puppet/pops/parser/interpolation_support.rb +2 -3
  597. data/lib/puppet/pops/parser/lexer2.rb +32 -29
  598. data/lib/puppet/pops/parser/lexer_support.rb +38 -41
  599. data/lib/puppet/pops/parser/locatable.rb +1 -2
  600. data/lib/puppet/pops/parser/locator.rb +31 -28
  601. data/lib/puppet/pops/parser/parser_support.rb +2 -0
  602. data/lib/puppet/pops/parser/pn_parser.rb +2 -2
  603. data/lib/puppet/pops/parser/slurp_support.rb +33 -32
  604. data/lib/puppet/pops/patterns.rb +2 -3
  605. data/lib/puppet/pops/pcore.rb +2 -2
  606. data/lib/puppet/pops/pn.rb +4 -1
  607. data/lib/puppet/pops/puppet_stack.rb +1 -0
  608. data/lib/puppet/pops/resource/param.rb +11 -10
  609. data/lib/puppet/pops/resource/resource_type_impl.rb +37 -36
  610. data/lib/puppet/pops/semantic_error.rb +1 -0
  611. data/lib/puppet/pops/serialization/abstract_reader.rb +3 -2
  612. data/lib/puppet/pops/serialization/abstract_writer.rb +5 -4
  613. data/lib/puppet/pops/serialization/deserializer.rb +2 -0
  614. data/lib/puppet/pops/serialization/extension.rb +7 -0
  615. data/lib/puppet/pops/serialization/from_data_converter.rb +3 -0
  616. data/lib/puppet/pops/serialization/instance_reader.rb +1 -0
  617. data/lib/puppet/pops/serialization/instance_writer.rb +1 -0
  618. data/lib/puppet/pops/serialization/json.rb +6 -3
  619. data/lib/puppet/pops/serialization/json_path.rb +2 -1
  620. data/lib/puppet/pops/serialization/object.rb +4 -1
  621. data/lib/puppet/pops/serialization/serializer.rb +6 -2
  622. data/lib/puppet/pops/serialization/time_factory.rb +1 -1
  623. data/lib/puppet/pops/serialization/to_data_converter.rb +4 -2
  624. data/lib/puppet/pops/serialization/to_stringified_converter.rb +2 -2
  625. data/lib/puppet/pops/serialization.rb +1 -0
  626. data/lib/puppet/pops/time/timespan.rb +16 -6
  627. data/lib/puppet/pops/time/timestamp.rb +4 -0
  628. data/lib/puppet/pops/types/annotatable.rb +1 -1
  629. data/lib/puppet/pops/types/annotation.rb +1 -0
  630. data/lib/puppet/pops/types/class_loader.rb +8 -6
  631. data/lib/puppet/pops/types/implementation_registry.rb +1 -0
  632. data/lib/puppet/pops/types/iterable.rb +18 -9
  633. data/lib/puppet/pops/types/p_binary_type.rb +2 -3
  634. data/lib/puppet/pops/types/p_init_type.rb +12 -9
  635. data/lib/puppet/pops/types/p_meta_type.rb +1 -1
  636. data/lib/puppet/pops/types/p_object_type.rb +65 -42
  637. data/lib/puppet/pops/types/p_object_type_extension.rb +10 -7
  638. data/lib/puppet/pops/types/p_runtime_type.rb +11 -9
  639. data/lib/puppet/pops/types/p_sem_ver_range_type.rb +1 -1
  640. data/lib/puppet/pops/types/p_sem_ver_type.rb +5 -5
  641. data/lib/puppet/pops/types/p_sensitive_type.rb +1 -4
  642. data/lib/puppet/pops/types/p_timespan_type.rb +4 -2
  643. data/lib/puppet/pops/types/p_timestamp_type.rb +3 -2
  644. data/lib/puppet/pops/types/p_type_set_type.rb +36 -28
  645. data/lib/puppet/pops/types/p_uri_type.rb +25 -18
  646. data/lib/puppet/pops/types/puppet_object.rb +1 -1
  647. data/lib/puppet/pops/types/recursion_guard.rb +7 -2
  648. data/lib/puppet/pops/types/ruby_generator.rb +9 -6
  649. data/lib/puppet/pops/types/ruby_method.rb +6 -5
  650. data/lib/puppet/pops/types/string_converter.rb +71 -63
  651. data/lib/puppet/pops/types/tree_iterators.rb +6 -7
  652. data/lib/puppet/pops/types/type_acceptor.rb +1 -0
  653. data/lib/puppet/pops/types/type_asserter.rb +1 -0
  654. data/lib/puppet/pops/types/type_assertion_error.rb +0 -1
  655. data/lib/puppet/pops/types/type_calculator.rb +10 -4
  656. data/lib/puppet/pops/types/type_conversion_error.rb +1 -10
  657. data/lib/puppet/pops/types/type_factory.rb +7 -4
  658. data/lib/puppet/pops/types/type_formatter.rb +14 -13
  659. data/lib/puppet/pops/types/type_mismatch_describer.rb +13 -8
  660. data/lib/puppet/pops/types/type_parser.rb +111 -107
  661. data/lib/puppet/pops/types/type_set_reference.rb +2 -0
  662. data/lib/puppet/pops/types/type_with_members.rb +1 -1
  663. data/lib/puppet/pops/types/types.rb +178 -153
  664. data/lib/puppet/pops/utils.rb +1 -0
  665. data/lib/puppet/pops/validation/checker4_0.rb +17 -11
  666. data/lib/puppet/pops/validation/tasks_checker.rb +2 -1
  667. data/lib/puppet/pops/validation/validator_factory_4_0.rb +1 -2
  668. data/lib/puppet/pops/validation.rb +8 -6
  669. data/lib/puppet/pops/visitable.rb +1 -0
  670. data/lib/puppet/pops/visitor.rb +14 -1
  671. data/lib/puppet/pops.rb +2 -0
  672. data/lib/puppet/property/boolean.rb +1 -0
  673. data/lib/puppet/property/ensure.rb +4 -1
  674. data/lib/puppet/property/keyvalue.rb +5 -4
  675. data/lib/puppet/property/list.rb +5 -5
  676. data/lib/puppet/property/ordered_list.rb +4 -4
  677. data/lib/puppet/property.rb +13 -11
  678. data/lib/puppet/provider/aix_object.rb +5 -0
  679. data/lib/puppet/provider/command.rb +1 -0
  680. data/lib/puppet/provider/confine.rb +1 -0
  681. data/lib/puppet/provider/exec/posix.rb +2 -0
  682. data/lib/puppet/provider/exec/shell.rb +1 -0
  683. data/lib/puppet/provider/exec/windows.rb +2 -1
  684. data/lib/puppet/provider/exec.rb +1 -0
  685. data/lib/puppet/provider/file/posix.rb +1 -0
  686. data/lib/puppet/provider/file/windows.rb +10 -6
  687. data/lib/puppet/provider/group/aix.rb +1 -0
  688. data/lib/puppet/provider/group/directoryservice.rb +1 -1
  689. data/lib/puppet/provider/group/groupadd.rb +9 -4
  690. data/lib/puppet/provider/group/ldap.rb +2 -0
  691. data/lib/puppet/provider/group/pw.rb +1 -0
  692. data/lib/puppet/provider/group/windows_adsi.rb +2 -0
  693. data/lib/puppet/provider/ldap.rb +2 -0
  694. data/lib/puppet/provider/nameservice/directoryservice.rb +30 -21
  695. data/lib/puppet/provider/nameservice/objectadd.rb +1 -0
  696. data/lib/puppet/provider/nameservice/pw.rb +6 -5
  697. data/lib/puppet/provider/nameservice.rb +8 -4
  698. data/lib/puppet/provider/network_device.rb +1 -2
  699. data/lib/puppet/provider/package/aix.rb +5 -4
  700. data/lib/puppet/provider/package/appdmg.rb +20 -19
  701. data/lib/puppet/provider/package/apple.rb +3 -2
  702. data/lib/puppet/provider/package/apt.rb +5 -5
  703. data/lib/puppet/provider/package/aptitude.rb +1 -0
  704. data/lib/puppet/provider/package/aptrpm.rb +2 -1
  705. data/lib/puppet/provider/package/blastwave.rb +6 -6
  706. data/lib/puppet/provider/package/dnf.rb +3 -1
  707. data/lib/puppet/provider/package/dnfmodule.rb +8 -7
  708. data/lib/puppet/provider/package/dpkg.rb +4 -4
  709. data/lib/puppet/provider/package/fink.rb +2 -1
  710. data/lib/puppet/provider/package/freebsd.rb +3 -2
  711. data/lib/puppet/provider/package/gem.rb +9 -5
  712. data/lib/puppet/provider/package/hpux.rb +4 -3
  713. data/lib/puppet/provider/package/macports.rb +2 -1
  714. data/lib/puppet/provider/package/nim.rb +13 -15
  715. data/lib/puppet/provider/package/openbsd.rb +6 -4
  716. data/lib/puppet/provider/package/opkg.rb +2 -0
  717. data/lib/puppet/provider/package/pacman.rb +12 -12
  718. data/lib/puppet/provider/package/pip.rb +3 -1
  719. data/lib/puppet/provider/package/pip2.rb +2 -2
  720. data/lib/puppet/provider/package/pip3.rb +2 -2
  721. data/lib/puppet/provider/package/pkg.rb +17 -13
  722. data/lib/puppet/provider/package/pkgdmg.rb +7 -2
  723. data/lib/puppet/provider/package/pkgin.rb +5 -5
  724. data/lib/puppet/provider/package/pkgng.rb +11 -7
  725. data/lib/puppet/provider/package/pkgutil.rb +7 -6
  726. data/lib/puppet/provider/package/portage.rb +11 -6
  727. data/lib/puppet/provider/package/ports.rb +6 -5
  728. data/lib/puppet/provider/package/portupgrade.rb +6 -12
  729. data/lib/puppet/provider/package/puppet_gem.rb +1 -0
  730. data/lib/puppet/provider/package/puppetserver_gem.rb +1 -0
  731. data/lib/puppet/provider/package/rpm.rb +10 -6
  732. data/lib/puppet/provider/package/rug.rb +2 -1
  733. data/lib/puppet/provider/package/sun.rb +20 -17
  734. data/lib/puppet/provider/package/sunfreeware.rb +1 -0
  735. data/lib/puppet/provider/package/tdnf.rb +1 -0
  736. data/lib/puppet/provider/package/up2date.rb +2 -1
  737. data/lib/puppet/provider/package/urpmi.rb +1 -0
  738. data/lib/puppet/provider/package/windows/exe_package.rb +1 -0
  739. data/lib/puppet/provider/package/windows/msi_package.rb +1 -0
  740. data/lib/puppet/provider/package/windows/package.rb +5 -3
  741. data/lib/puppet/provider/package/windows.rb +4 -2
  742. data/lib/puppet/provider/package/yum.rb +17 -14
  743. data/lib/puppet/provider/package/zypper.rb +15 -14
  744. data/lib/puppet/provider/package.rb +7 -6
  745. data/lib/puppet/provider/package_targetable.rb +1 -0
  746. data/lib/puppet/provider/parsedfile.rb +7 -2
  747. data/lib/puppet/provider/service/base.rb +2 -1
  748. data/lib/puppet/provider/service/bsd.rb +1 -0
  749. data/lib/puppet/provider/service/daemontools.rb +9 -7
  750. data/lib/puppet/provider/service/debian.rb +4 -3
  751. data/lib/puppet/provider/service/freebsd.rb +5 -6
  752. data/lib/puppet/provider/service/gentoo.rb +5 -4
  753. data/lib/puppet/provider/service/init.rb +10 -11
  754. data/lib/puppet/provider/service/launchd.rb +10 -4
  755. data/lib/puppet/provider/service/openbsd.rb +4 -4
  756. data/lib/puppet/provider/service/openrc.rb +1 -1
  757. data/lib/puppet/provider/service/openwrt.rb +1 -1
  758. data/lib/puppet/provider/service/rcng.rb +1 -0
  759. data/lib/puppet/provider/service/redhat.rb +3 -2
  760. data/lib/puppet/provider/service/runit.rb +8 -7
  761. data/lib/puppet/provider/service/service.rb +1 -0
  762. data/lib/puppet/provider/service/smf.rb +5 -2
  763. data/lib/puppet/provider/service/src.rb +16 -16
  764. data/lib/puppet/provider/service/systemd.rb +8 -4
  765. data/lib/puppet/provider/service/upstart.rb +8 -7
  766. data/lib/puppet/provider/service/windows.rb +22 -26
  767. data/lib/puppet/provider/user/aix.rb +3 -2
  768. data/lib/puppet/provider/user/directoryservice.rb +53 -45
  769. data/lib/puppet/provider/user/hpux.rb +15 -14
  770. data/lib/puppet/provider/user/ldap.rb +8 -6
  771. data/lib/puppet/provider/user/openbsd.rb +21 -20
  772. data/lib/puppet/provider/user/pw.rb +3 -2
  773. data/lib/puppet/provider/user/user_role_add.rb +19 -14
  774. data/lib/puppet/provider/user/useradd.rb +51 -41
  775. data/lib/puppet/provider/user/windows_adsi.rb +4 -1
  776. data/lib/puppet/provider.rb +9 -9
  777. data/lib/puppet/reference/configuration.rb +44 -43
  778. data/lib/puppet/reference/function.rb +1 -0
  779. data/lib/puppet/reference/indirection.rb +43 -42
  780. data/lib/puppet/reference/metaparameter.rb +1 -0
  781. data/lib/puppet/reference/providers.rb +2 -0
  782. data/lib/puppet/reference/report.rb +1 -0
  783. data/lib/puppet/reference/type.rb +4 -3
  784. data/lib/puppet/relationship.rb +3 -2
  785. data/lib/puppet/reports/http.rb +1 -1
  786. data/lib/puppet/reports/log.rb +1 -0
  787. data/lib/puppet/reports/store.rb +3 -1
  788. data/lib/puppet/reports.rb +5 -4
  789. data/lib/puppet/resource/catalog.rb +14 -10
  790. data/lib/puppet/resource/status.rb +1 -1
  791. data/lib/puppet/resource/type.rb +28 -18
  792. data/lib/puppet/resource/type_collection.rb +4 -0
  793. data/lib/puppet/resource.rb +24 -16
  794. data/lib/puppet/runtime.rb +1 -0
  795. data/lib/puppet/scheduler/job.rb +1 -0
  796. data/lib/puppet/scheduler/scheduler.rb +1 -0
  797. data/lib/puppet/scheduler/splay_job.rb +1 -0
  798. data/lib/puppet/scheduler/timer.rb +1 -0
  799. data/lib/puppet/scheduler.rb +1 -0
  800. data/lib/puppet/settings/alias_setting.rb +1 -0
  801. data/lib/puppet/settings/array_setting.rb +1 -1
  802. data/lib/puppet/settings/autosign_setting.rb +1 -1
  803. data/lib/puppet/settings/base_setting.rb +9 -5
  804. data/lib/puppet/settings/boolean_setting.rb +1 -0
  805. data/lib/puppet/settings/certificate_revocation_setting.rb +1 -1
  806. data/lib/puppet/settings/config_file.rb +3 -3
  807. data/lib/puppet/settings/directory_setting.rb +1 -0
  808. data/lib/puppet/settings/duration_setting.rb +1 -0
  809. data/lib/puppet/settings/enum_setting.rb +2 -1
  810. data/lib/puppet/settings/environment_conf.rb +9 -8
  811. data/lib/puppet/settings/errors.rb +2 -0
  812. data/lib/puppet/settings/file_or_directory_setting.rb +1 -5
  813. data/lib/puppet/settings/file_setting.rb +3 -13
  814. data/lib/puppet/settings/http_extra_headers_setting.rb +1 -1
  815. data/lib/puppet/settings/ini_file.rb +1 -0
  816. data/lib/puppet/settings/integer_setting.rb +1 -0
  817. data/lib/puppet/settings/path_setting.rb +1 -0
  818. data/lib/puppet/settings/port_setting.rb +2 -1
  819. data/lib/puppet/settings/priority_setting.rb +9 -8
  820. data/lib/puppet/settings/server_list_setting.rb +2 -2
  821. data/lib/puppet/settings/string_setting.rb +1 -0
  822. data/lib/puppet/settings/symbolic_enum_setting.rb +2 -1
  823. data/lib/puppet/settings/terminus_setting.rb +1 -0
  824. data/lib/puppet/settings/ttl_setting.rb +2 -0
  825. data/lib/puppet/settings/value_translator.rb +8 -7
  826. data/lib/puppet/settings.rb +89 -66
  827. data/lib/puppet/ssl/base.rb +4 -0
  828. data/lib/puppet/ssl/certificate.rb +3 -2
  829. data/lib/puppet/ssl/certificate_request.rb +9 -7
  830. data/lib/puppet/ssl/certificate_request_attributes.rb +3 -1
  831. data/lib/puppet/ssl/certificate_signer.rb +2 -3
  832. data/lib/puppet/ssl/digest.rb +1 -0
  833. data/lib/puppet/ssl/error.rb +2 -0
  834. data/lib/puppet/ssl/oids.rb +3 -3
  835. data/lib/puppet/ssl/openssl_loader.rb +1 -0
  836. data/lib/puppet/ssl/ssl_context.rb +11 -15
  837. data/lib/puppet/ssl/ssl_provider.rb +2 -1
  838. data/lib/puppet/ssl/state_machine.rb +1 -0
  839. data/lib/puppet/ssl/verifier.rb +2 -2
  840. data/lib/puppet/ssl.rb +1 -0
  841. data/lib/puppet/syntax_checkers/base64.rb +2 -1
  842. data/lib/puppet/syntax_checkers/epp.rb +1 -1
  843. data/lib/puppet/syntax_checkers/json.rb +1 -2
  844. data/lib/puppet/syntax_checkers/pp.rb +1 -1
  845. data/lib/puppet/syntax_checkers.rb +1 -0
  846. data/lib/puppet/test/test_helper.rb +16 -14
  847. data/lib/puppet/thread_local.rb +1 -0
  848. data/lib/puppet/transaction/additional_resource_generator.rb +5 -1
  849. data/lib/puppet/transaction/event.rb +5 -3
  850. data/lib/puppet/transaction/event_manager.rb +4 -3
  851. data/lib/puppet/transaction/persistence.rb +2 -1
  852. data/lib/puppet/transaction/report.rb +24 -16
  853. data/lib/puppet/transaction/resource_harness.rb +6 -3
  854. data/lib/puppet/transaction.rb +11 -6
  855. data/lib/puppet/trusted_external.rb +8 -4
  856. data/lib/puppet/type/component.rb +11 -5
  857. data/lib/puppet/type/exec.rb +26 -10
  858. data/lib/puppet/type/file/checksum.rb +1 -0
  859. data/lib/puppet/type/file/checksum_value.rb +3 -2
  860. data/lib/puppet/type/file/content.rb +16 -13
  861. data/lib/puppet/type/file/ctime.rb +2 -1
  862. data/lib/puppet/type/file/data_sync.rb +4 -2
  863. data/lib/puppet/type/file/ensure.rb +5 -5
  864. data/lib/puppet/type/file/group.rb +2 -1
  865. data/lib/puppet/type/file/mode.rb +4 -2
  866. data/lib/puppet/type/file/mtime.rb +2 -1
  867. data/lib/puppet/type/file/owner.rb +2 -1
  868. data/lib/puppet/type/file/selcontext.rb +2 -2
  869. data/lib/puppet/type/file/source.rb +12 -10
  870. data/lib/puppet/type/file/target.rb +2 -2
  871. data/lib/puppet/type/file/type.rb +2 -1
  872. data/lib/puppet/type/file.rb +22 -13
  873. data/lib/puppet/type/filebucket.rb +2 -1
  874. data/lib/puppet/type/group.rb +8 -8
  875. data/lib/puppet/type/notify.rb +1 -1
  876. data/lib/puppet/type/package.rb +21 -21
  877. data/lib/puppet/type/resources.rb +30 -25
  878. data/lib/puppet/type/schedule.rb +9 -10
  879. data/lib/puppet/type/service.rb +9 -7
  880. data/lib/puppet/type/stage.rb +1 -0
  881. data/lib/puppet/type/tidy.rb +9 -4
  882. data/lib/puppet/type/user.rb +28 -24
  883. data/lib/puppet/type/whit.rb +1 -1
  884. data/lib/puppet/type.rb +71 -61
  885. data/lib/puppet/util/at_fork/noop.rb +1 -0
  886. data/lib/puppet/util/at_fork/solaris.rb +2 -1
  887. data/lib/puppet/util/at_fork.rb +2 -1
  888. data/lib/puppet/util/autoload.rb +5 -0
  889. data/lib/puppet/util/backups.rb +3 -2
  890. data/lib/puppet/util/character_encoding.rb +1 -0
  891. data/lib/puppet/util/checksums.rb +11 -9
  892. data/lib/puppet/util/classgen.rb +8 -13
  893. data/lib/puppet/util/colors.rb +32 -31
  894. data/lib/puppet/util/command_line/puppet_option_parser.rb +12 -12
  895. data/lib/puppet/util/command_line/trollop.rb +693 -690
  896. data/lib/puppet/util/command_line.rb +1 -0
  897. data/lib/puppet/util/constant_inflector.rb +3 -3
  898. data/lib/puppet/util/diff.rb +14 -14
  899. data/lib/puppet/util/docs.rb +3 -0
  900. data/lib/puppet/util/errors.rb +1 -0
  901. data/lib/puppet/util/execution.rb +24 -21
  902. data/lib/puppet/util/execution_stub.rb +1 -0
  903. data/lib/puppet/util/feature.rb +1 -0
  904. data/lib/puppet/util/file_watcher.rb +2 -0
  905. data/lib/puppet/util/fileparsing.rb +2 -0
  906. data/lib/puppet/util/filetype.rb +3 -0
  907. data/lib/puppet/util/http_proxy.rb +1 -0
  908. data/lib/puppet/util/inifile.rb +5 -5
  909. data/lib/puppet/util/instance_loader.rb +2 -0
  910. data/lib/puppet/util/json.rb +1 -0
  911. data/lib/puppet/util/json_lockfile.rb +3 -1
  912. data/lib/puppet/util/ldap/connection.rb +19 -18
  913. data/lib/puppet/util/ldap/generator.rb +1 -0
  914. data/lib/puppet/util/ldap/manager.rb +3 -2
  915. data/lib/puppet/util/ldap.rb +1 -0
  916. data/lib/puppet/util/libuser.rb +1 -1
  917. data/lib/puppet/util/limits.rb +1 -0
  918. data/lib/puppet/util/lockfile.rb +1 -0
  919. data/lib/puppet/util/log/destination.rb +1 -0
  920. data/lib/puppet/util/log/destinations.rb +14 -13
  921. data/lib/puppet/util/log.rb +21 -17
  922. data/lib/puppet/util/logging.rb +18 -14
  923. data/lib/puppet/util/metaid.rb +1 -0
  924. data/lib/puppet/util/metric.rb +2 -0
  925. data/lib/puppet/util/monkey_patches.rb +19 -0
  926. data/lib/puppet/util/multi_match.rb +4 -1
  927. data/lib/puppet/util/network_device/base.rb +1 -1
  928. data/lib/puppet/util/network_device/config.rb +3 -4
  929. data/lib/puppet/util/network_device/transport/base.rb +0 -1
  930. data/lib/puppet/util/network_device/transport.rb +1 -0
  931. data/lib/puppet/util/network_device.rb +1 -0
  932. data/lib/puppet/util/package/version/debian.rb +5 -3
  933. data/lib/puppet/util/package/version/gem.rb +2 -0
  934. data/lib/puppet/util/package/version/pip.rb +7 -2
  935. data/lib/puppet/util/package/version/range/eq.rb +2 -0
  936. data/lib/puppet/util/package/version/range/gt.rb +2 -0
  937. data/lib/puppet/util/package/version/range/gt_eq.rb +2 -0
  938. data/lib/puppet/util/package/version/range/lt.rb +2 -0
  939. data/lib/puppet/util/package/version/range/lt_eq.rb +2 -0
  940. data/lib/puppet/util/package/version/range/min_max.rb +4 -0
  941. data/lib/puppet/util/package/version/range/simple.rb +1 -0
  942. data/lib/puppet/util/package/version/range.rb +3 -0
  943. data/lib/puppet/util/package/version/rpm.rb +7 -5
  944. data/lib/puppet/util/package.rb +3 -0
  945. data/lib/puppet/util/pidlock.rb +7 -7
  946. data/lib/puppet/util/platform.rb +1 -0
  947. data/lib/puppet/util/plist.rb +1 -1
  948. data/lib/puppet/util/posix.rb +8 -5
  949. data/lib/puppet/util/profiler/aggregate.rb +2 -5
  950. data/lib/puppet/util/profiler/around_profiler.rb +1 -1
  951. data/lib/puppet/util/profiler/logging.rb +1 -0
  952. data/lib/puppet/util/profiler/object_counts.rb +1 -0
  953. data/lib/puppet/util/profiler/wall_clock.rb +1 -0
  954. data/lib/puppet/util/profiler.rb +1 -0
  955. data/lib/puppet/util/provider_features.rb +5 -1
  956. data/lib/puppet/util/psych_support.rb +1 -0
  957. data/lib/puppet/util/rdoc/code_objects.rb +3 -7
  958. data/lib/puppet/util/rdoc/generators/puppet_generator.rb +37 -50
  959. data/lib/puppet/util/rdoc/generators/template/puppet/puppet.rb +50 -68
  960. data/lib/puppet/util/rdoc/parser/puppet_parser_core.rb +5 -5
  961. data/lib/puppet/util/rdoc/parser/puppet_parser_rdoc2.rb +1 -0
  962. data/lib/puppet/util/rdoc/parser.rb +1 -0
  963. data/lib/puppet/util/rdoc.rb +1 -1
  964. data/lib/puppet/util/reference.rb +1 -1
  965. data/lib/puppet/util/resource_template.rb +2 -0
  966. data/lib/puppet/util/retry_action.rb +3 -3
  967. data/lib/puppet/util/rpm_compare.rb +6 -3
  968. data/lib/puppet/util/rubygems.rb +1 -1
  969. data/lib/puppet/util/run_mode.rb +2 -1
  970. data/lib/puppet/util/selinux.rb +23 -12
  971. data/lib/puppet/util/skip_tags.rb +1 -0
  972. data/lib/puppet/util/splayer.rb +1 -0
  973. data/lib/puppet/util/storage.rb +2 -1
  974. data/lib/puppet/util/suidmanager.rb +8 -5
  975. data/lib/puppet/util/symbolic_file_mode.rb +3 -1
  976. data/lib/puppet/util/tag_set.rb +1 -0
  977. data/lib/puppet/util/tagging.rb +2 -1
  978. data/lib/puppet/util/terminal.rb +1 -0
  979. data/lib/puppet/util/user_attr.rb +1 -0
  980. data/lib/puppet/util/warnings.rb +3 -0
  981. data/lib/puppet/util/watched_file.rb +1 -0
  982. data/lib/puppet/util/watcher/change_watcher.rb +1 -0
  983. data/lib/puppet/util/watcher/periodic_watcher.rb +1 -0
  984. data/lib/puppet/util/watcher/timer.rb +1 -0
  985. data/lib/puppet/util/watcher.rb +1 -0
  986. data/lib/puppet/util/windows/access_control_entry.rb +2 -1
  987. data/lib/puppet/util/windows/access_control_list.rb +4 -3
  988. data/lib/puppet/util/windows/adsi.rb +41 -27
  989. data/lib/puppet/util/windows/com.rb +5 -3
  990. data/lib/puppet/util/windows/daemon.rb +33 -33
  991. data/lib/puppet/util/windows/error.rb +4 -3
  992. data/lib/puppet/util/windows/eventlog.rb +8 -5
  993. data/lib/puppet/util/windows/file.rb +32 -26
  994. data/lib/puppet/util/windows/monkey_patches/process.rb +0 -1
  995. data/lib/puppet/util/windows/principal.rb +27 -27
  996. data/lib/puppet/util/windows/process.rb +8 -7
  997. data/lib/puppet/util/windows/registry.rb +43 -41
  998. data/lib/puppet/util/windows/root_certs.rb +1 -0
  999. data/lib/puppet/util/windows/security.rb +43 -44
  1000. data/lib/puppet/util/windows/security_descriptor.rb +1 -0
  1001. data/lib/puppet/util/windows/service.rb +12 -1
  1002. data/lib/puppet/util/windows/sid.rb +10 -8
  1003. data/lib/puppet/util/windows/string.rb +1 -0
  1004. data/lib/puppet/util/windows/user.rb +33 -33
  1005. data/lib/puppet/util/windows.rb +6 -0
  1006. data/lib/puppet/util/yaml.rb +1 -0
  1007. data/lib/puppet/util.rb +20 -23
  1008. data/lib/puppet/vendor.rb +2 -1
  1009. data/lib/puppet/version.rb +3 -1
  1010. data/lib/puppet/x509/cert_provider.rb +13 -3
  1011. data/lib/puppet/x509/pem_store.rb +1 -0
  1012. data/lib/puppet/x509.rb +1 -0
  1013. data/lib/puppet.rb +1 -0
  1014. data/lib/puppet_pal.rb +1 -0
  1015. data/lib/puppet_x.rb +1 -0
  1016. data/locales/puppet.pot +214 -210
  1017. data/man/man5/puppet.conf.5 +3 -3
  1018. data/man/man8/puppet-agent.8 +1 -1
  1019. data/man/man8/puppet-apply.8 +1 -1
  1020. data/man/man8/puppet-catalog.8 +1 -1
  1021. data/man/man8/puppet-config.8 +1 -1
  1022. data/man/man8/puppet-describe.8 +1 -1
  1023. data/man/man8/puppet-device.8 +1 -1
  1024. data/man/man8/puppet-doc.8 +1 -1
  1025. data/man/man8/puppet-epp.8 +1 -1
  1026. data/man/man8/puppet-facts.8 +1 -1
  1027. data/man/man8/puppet-filebucket.8 +1 -1
  1028. data/man/man8/puppet-generate.8 +1 -1
  1029. data/man/man8/puppet-help.8 +1 -1
  1030. data/man/man8/puppet-lookup.8 +1 -1
  1031. data/man/man8/puppet-module.8 +1 -1
  1032. data/man/man8/puppet-node.8 +1 -1
  1033. data/man/man8/puppet-parser.8 +1 -1
  1034. data/man/man8/puppet-plugin.8 +1 -1
  1035. data/man/man8/puppet-report.8 +1 -1
  1036. data/man/man8/puppet-resource.8 +1 -1
  1037. data/man/man8/puppet-script.8 +1 -1
  1038. data/man/man8/puppet-ssl.8 +5 -1
  1039. data/man/man8/puppet.8 +2 -2
  1040. data/spec/integration/application/agent_spec.rb +13 -0
  1041. data/spec/integration/type/exec_spec.rb +13 -0
  1042. data/spec/lib/puppet_spec/puppetserver.rb +1 -0
  1043. data/spec/lib/puppet_spec/verbose.rb +15 -4
  1044. data/spec/unit/agent_spec.rb +2 -14
  1045. data/spec/unit/application/ssl_spec.rb +49 -0
  1046. data/spec/unit/daemon_spec.rb +3 -20
  1047. data/spec/unit/functions/split_spec.rb +6 -0
  1048. data/spec/unit/indirector/catalog/compiler_spec.rb +17 -0
  1049. data/spec/unit/indirector/catalog/rest_spec.rb +17 -0
  1050. data/spec/unit/info_service_spec.rb +1 -1
  1051. data/spec/unit/provider/package/appdmg_spec.rb +1 -1
  1052. data/spec/unit/provider/package/dnf_spec.rb +7 -0
  1053. data/spec/unit/provider/package/dnfmodule_spec.rb +22 -2
  1054. data/spec/unit/provider/service/systemd_spec.rb +8 -6
  1055. data/spec/unit/ssl/certificate_signer_spec.rb +17 -0
  1056. data/spec/unit/ssl/ssl_provider_spec.rb +1 -1
  1057. data/spec/unit/type/exec_spec.rb +14 -9
  1058. data/spec/unit/util/execution_spec.rb +1 -0
  1059. data/spec/unit/util/monkey_patches_spec.rb +42 -0
  1060. data/spec/unit/util/rpm_compare_spec.rb +8 -8
  1061. data/spec/unit/util/windows/adsi_spec.rb +25 -0
  1062. metadata +9 -14
  1063. data/CONTRIBUTING.md +0 -161
@@ -1,992 +1,993 @@
1
1
  # frozen_string_literal: true
2
+
2
3
  Puppet::Parser::Functions::newfunction(
3
4
  :new,
4
5
  :type => :rvalue,
5
6
  :arity => -1,
6
- :doc => <<-DOC
7
- Creates a new instance/object of a given data type.
8
-
9
- This function makes it possible to create new instances of
10
- concrete data types. If a block is given it is called with the
11
- just created instance as an argument.
12
-
13
- Calling this function is equivalent to directly
14
- calling the data type:
15
-
16
- **Example:** `new` and calling type directly are equivalent
17
-
18
- ```puppet
19
- $a = Integer.new("42")
20
- $b = Integer("42")
21
- ```
22
-
23
- These would both convert the string `"42"` to the decimal value `42`.
24
-
25
- **Example:** arguments by position or by name
26
-
27
- ```puppet
28
- $a = Integer.new("42", 8)
29
- $b = Integer({from => "42", radix => 8})
30
- ```
31
-
32
- This would convert the octal (radix 8) number `"42"` in string form
33
- to the decimal value `34`.
34
-
35
- The new function supports two ways of giving the arguments:
36
-
37
- * by name (using a hash with property to value mapping)
38
- * by position (as regular arguments)
39
-
40
- Note that it is not possible to create new instances of
41
- some abstract data types (for example `Variant`). The data type `Optional[T]` is an
42
- exception as it will create an instance of `T` or `undef` if the
43
- value to convert is `undef`.
44
-
45
- The arguments that can be given is determined by the data type.
46
-
47
- > An assertion is always made that the produced value complies with the given type constraints.
48
-
49
- **Example:** data type constraints are checked
50
-
51
- ```puppet
52
- Integer[0].new("-100")
53
- ```
54
-
55
- Would fail with an assertion error (since value is less than 0).
56
-
57
- The following sections show the arguments and conversion rules
58
- per data type built into the Puppet Type System.
59
-
60
- ### Conversion to Optional[T] and NotUndef[T]
61
-
62
- Conversion to these data types is the same as a conversion to the type argument `T`.
63
- In the case of `Optional[T]` it is accepted that the argument to convert may be `undef`.
64
- It is however not acceptable to give other arguments (than `undef`) that cannot be
65
- converted to `T`.
66
-
67
- ### Conversion to Integer
68
-
69
- A new `Integer` can be created from `Integer`, `Float`, `Boolean`, and `String` values.
70
- For conversion from `String` it is possible to specify the radix (base).
71
-
72
- ```puppet
73
- type Radix = Variant[Default, Integer[2,2], Integer[8,8], Integer[10,10], Integer[16,16]]
74
-
75
- function Integer.new(
76
- String $value,
77
- Radix $radix = 10,
78
- Boolean $abs = false
79
- )
80
-
81
- function Integer.new(
82
- Variant[Numeric, Boolean] $value,
83
- Boolean $abs = false
84
- )
85
- ```
86
-
87
- * When converting from `String` the default radix is 10.
88
- * If radix is not specified an attempt is made to detect the radix from the start of the string:
89
- * `0b` or `0B` is taken as radix 2.
90
- * `0x` or `0X` is taken as radix 16.
91
- * `0` as radix 8.
92
- * All others are decimal.
93
- * Conversion from `String` accepts an optional sign in the string.
94
- * For hexadecimal (radix 16) conversion an optional leading "0x", or "0X" is accepted.
95
- * For octal (radix 8) an optional leading "0" is accepted.
96
- * For binary (radix 2) an optional leading "0b" or "0B" is accepted.
97
- * When `radix` is set to `default`, the conversion is based on the leading.
98
- characters in the string. A leading "0" for radix 8, a leading "0x", or "0X" for
99
- radix 16, and leading "0b" or "0B" for binary.
100
- * Conversion from `Boolean` results in 0 for `false` and 1 for `true`.
101
- * Conversion from `Integer`, `Float`, and `Boolean` ignores the radix.
102
- * `Float` value fractions are truncated (no rounding).
103
- * When `abs` is set to `true`, the result will be an absolute integer.
104
-
105
- Examples - Converting to Integer:
106
-
107
- ```puppet
108
- $a_number = Integer("0xFF", 16) # results in 255
109
- $a_number = Integer("010") # results in 8
110
- $a_number = Integer("010", 10) # results in 10
111
- $a_number = Integer(true) # results in 1
112
- $a_number = Integer(-38, 10, true) # results in 38
113
- ```
114
-
115
- ### Conversion to Float
116
-
117
- A new `Float` can be created from `Integer`, `Float`, `Boolean`, and `String` values.
118
- For conversion from `String` both float and integer formats are supported.
119
-
120
- ```puppet
121
- function Float.new(
122
- Variant[Numeric, Boolean, String] $value,
123
- Boolean $abs = true
124
- )
125
- ```
126
-
127
- * For an integer, the floating point fraction of `.0` is added to the value.
128
- * A `Boolean` `true` is converted to 1.0, and a `false` to 0.0
129
- * In `String` format, integer prefixes for hex and binary are understood (but not octal since
130
- floating point in string format may start with a '0').
131
- * When `abs` is set to `true`, the result will be an absolute floating point value.
132
-
133
- ### Conversion to Numeric
134
-
135
- A new `Integer` or `Float` can be created from `Integer`, `Float`, `Boolean` and
136
- `String` values.
137
-
138
- ```puppet
139
- function Numeric.new(
140
- Variant[Numeric, Boolean, String] $value,
141
- Boolean $abs = true
142
- )
143
- ```
144
-
145
- * If the value has a decimal period, or if given in scientific notation
146
- (e/E), the result is a `Float`, otherwise the value is an `Integer`. The
147
- conversion from `String` always uses a radix based on the prefix of the string.
148
- * Conversion from `Boolean` results in 0 for `false` and 1 for `true`.
149
- * When `abs` is set to `true`, the result will be an absolute `Float`or `Integer` value.
150
-
151
- Examples - Converting to Numeric
152
-
153
- ```puppet
154
- $a_number = Numeric(true) # results in 1
155
- $a_number = Numeric("0xFF") # results in 255
156
- $a_number = Numeric("010") # results in 8
157
- $a_number = Numeric("3.14") # results in 3.14 (a float)
158
- $a_number = Numeric(-42.3, true) # results in 42.3
159
- $a_number = Numeric(-42, true) # results in 42
160
- ```
161
-
162
- ### Conversion to Timespan
163
-
164
- A new `Timespan` can be created from `Integer`, `Float`, `String`, and `Hash` values. Several variants of the constructor are provided.
165
-
166
- #### Timespan from seconds
167
-
168
- When a Float is used, the decimal part represents fractions of a second.
169
-
170
- ```puppet
171
- function Timespan.new(
172
- Variant[Float, Integer] $value
173
- )
174
- ```
175
-
176
- #### Timespan from days, hours, minutes, seconds, and fractions of a second
177
-
178
- The arguments can be passed separately in which case the first four, days, hours, minutes, and seconds are mandatory and the rest are optional.
179
- All values may overflow and/or be negative. The internal 128-bit nano-second integer is calculated as:
180
-
181
- ```
182
- (((((days * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000 + milliseconds) * 1000 + microseconds) * 1000 + nanoseconds
183
- ```
184
-
185
- ```puppet
186
- function Timespan.new(
187
- Integer $days, Integer $hours, Integer $minutes, Integer $seconds,
188
- Integer $milliseconds = 0, Integer $microseconds = 0, Integer $nanoseconds = 0
189
- )
190
- ```
191
-
192
- or, all arguments can be passed as a `Hash`, in which case all entries are optional:
193
-
194
- ```puppet
195
- function Timespan.new(
196
- Struct[{
197
- Optional[negative] => Boolean,
198
- Optional[days] => Integer,
199
- Optional[hours] => Integer,
200
- Optional[minutes] => Integer,
201
- Optional[seconds] => Integer,
202
- Optional[milliseconds] => Integer,
203
- Optional[microseconds] => Integer,
204
- Optional[nanoseconds] => Integer
205
- }] $hash
206
- )
207
- ```
208
-
209
- #### Timespan from String and format directive patterns
210
-
211
- The first argument is parsed using the format optionally passed as a string or array of strings. When an array is used, an attempt
212
- will be made to parse the string using the first entry and then with each entry in succession until parsing succeeds. If the second
213
- argument is omitted, an array of default formats will be used.
214
-
215
- An exception is raised when no format was able to parse the given string.
216
-
217
- ```puppet
218
- function Timespan.new(
219
- String $string, Variant[String[2],Array[String[2], 1]] $format = <default format>)
220
- )
221
- ```
222
-
223
- the arguments may also be passed as a `Hash`:
224
-
225
- ```puppet
226
- function Timespan.new(
227
- Struct[{
228
- string => String[1],
229
- Optional[format] => Variant[String[2],Array[String[2], 1]]
230
- }] $hash
231
- )
232
- ```
233
-
234
- The directive consists of a percent (%) character, zero or more flags, optional minimum field width and
235
- a conversion specifier as follows:
236
- ```
237
- %[Flags][Width]Conversion
238
- ```
239
-
240
- ##### Flags:
241
-
242
- | Flag | Meaning
243
- | ---- | ---------------
244
- | - | Don't pad numerical output
245
- | _ | Use spaces for padding
246
- | 0 | Use zeros for padding
247
-
248
- ##### Format directives:
249
-
250
- | Format | Meaning |
251
- | ------ | ------- |
252
- | D | Number of Days |
253
- | H | Hour of the day, 24-hour clock |
254
- | M | Minute of the hour (00..59) |
255
- | S | Second of the minute (00..59) |
256
- | L | Millisecond of the second (000..999) |
257
- | N | Fractional seconds digits |
258
-
259
- The format directive that represents the highest magnitude in the format will be allowed to
260
- overflow. I.e. if no "%D" is used but a "%H" is present, then the hours may be more than 23.
261
-
262
- The default array contains the following patterns:
263
-
264
- ```
265
- ['%D-%H:%M:%S', '%D-%H:%M', '%H:%M:%S', '%H:%M']
266
- ```
267
-
268
- Examples - Converting to Timespan
269
-
270
- ```puppet
271
- $duration = Timespan(13.5) # 13 seconds and 500 milliseconds
272
- $duration = Timespan({days=>4}) # 4 days
273
- $duration = Timespan(4, 0, 0, 2) # 4 days and 2 seconds
274
- $duration = Timespan('13:20') # 13 hours and 20 minutes (using default pattern)
275
- $duration = Timespan('10:03.5', '%M:%S.%L') # 10 minutes, 3 seconds, and 5 milli-seconds
276
- $duration = Timespan('10:03.5', '%M:%S.%N') # 10 minutes, 3 seconds, and 5 nano-seconds
277
- ```
278
-
279
- ### Conversion to Timestamp
280
-
281
- A new `Timestamp` can be created from `Integer`, `Float`, `String`, and `Hash` values. Several variants of the constructor are provided.
282
-
283
- #### Timestamp from seconds since epoch (1970-01-01 00:00:00 UTC)
284
-
285
- When a Float is used, the decimal part represents fractions of a second.
286
-
287
- ```puppet
288
- function Timestamp.new(
289
- Variant[Float, Integer] $value
290
- )
291
- ```
292
-
293
- #### Timestamp from String and patterns consisting of format directives
294
-
295
- The first argument is parsed using the format optionally passed as a string or array of strings. When an array is used, an attempt
296
- will be made to parse the string using the first entry and then with each entry in succession until parsing succeeds. If the second
297
- argument is omitted, an array of default formats will be used.
298
-
299
- A third optional timezone argument can be provided. The first argument will then be parsed as if it represents a local time in that
300
- timezone. The timezone can be any timezone that is recognized when using the '%z' or '%Z' formats, or the word 'current', in which
301
- case the current timezone of the evaluating process will be used. The timezone argument is case insensitive.
302
-
303
- The default timezone, when no argument is provided, or when using the keyword `default`, is 'UTC'.
304
-
305
- It is illegal to provide a timezone argument other than `default` in combination with a format that contains '%z' or '%Z' since that
306
- would introduce an ambiguity as to which timezone to use. The one extracted from the string, or the one provided as an argument.
307
-
308
- An exception is raised when no format was able to parse the given string.
309
-
310
- ```puppet
311
- function Timestamp.new(
312
- String $string,
313
- Variant[String[2],Array[String[2], 1]] $format = <default format>,
314
- String $timezone = default)
315
- )
316
- ```
317
-
318
- the arguments may also be passed as a `Hash`:
319
-
320
- ```puppet
321
- function Timestamp.new(
322
- Struct[{
323
- string => String[1],
324
- Optional[format] => Variant[String[2],Array[String[2], 1]],
325
- Optional[timezone] => String[1]
326
- }] $hash
327
- )
328
- ```
329
-
330
- The directive consists of a percent (%) character, zero or more flags, optional minimum field width and
331
- a conversion specifier as follows:
332
- ```
333
- %[Flags][Width]Conversion
334
- ```
335
-
336
- ##### Flags:
337
-
338
- | Flag | Meaning
339
- | ---- | ---------------
340
- | - | Don't pad numerical output
341
- | _ | Use spaces for padding
342
- | 0 | Use zeros for padding
343
- | # | Change names to upper-case or change case of am/pm
344
- | ^ | Use uppercase
345
- | : | Use colons for %z
346
-
347
- ##### Format directives (names and padding can be altered using flags):
348
-
349
- **Date (Year, Month, Day):**
350
-
351
- | Format | Meaning |
352
- | ------ | ------- |
353
- | Y | Year with century, zero-padded to at least 4 digits |
354
- | C | year / 100 (rounded down such as 20 in 2009) |
355
- | y | year % 100 (00..99) |
356
- | m | Month of the year, zero-padded (01..12) |
357
- | B | The full month name ("January") |
358
- | b | The abbreviated month name ("Jan") |
359
- | h | Equivalent to %b |
360
- | d | Day of the month, zero-padded (01..31) |
361
- | e | Day of the month, blank-padded ( 1..31) |
362
- | j | Day of the year (001..366) |
363
-
364
- **Time (Hour, Minute, Second, Subsecond):**
365
-
366
- | Format | Meaning |
367
- | ------ | ------- |
368
- | H | Hour of the day, 24-hour clock, zero-padded (00..23) |
369
- | k | Hour of the day, 24-hour clock, blank-padded ( 0..23) |
370
- | I | Hour of the day, 12-hour clock, zero-padded (01..12) |
371
- | l | Hour of the day, 12-hour clock, blank-padded ( 1..12) |
372
- | P | Meridian indicator, lowercase ("am" or "pm") |
373
- | p | Meridian indicator, uppercase ("AM" or "PM") |
374
- | M | Minute of the hour (00..59) |
375
- | S | Second of the minute (00..60) |
376
- | L | Millisecond of the second (000..999). Digits under millisecond are truncated to not produce 1000 |
377
- | N | Fractional seconds digits, default is 9 digits (nanosecond). Digits under a specified width are truncated to avoid carry up |
378
-
379
- **Time (Hour, Minute, Second, Subsecond):**
380
-
381
- | Format | Meaning |
382
- | ------ | ------- |
383
- | z | Time zone as hour and minute offset from UTC (e.g. +0900) |
384
- | :z | hour and minute offset from UTC with a colon (e.g. +09:00) |
385
- | ::z | hour, minute and second offset from UTC (e.g. +09:00:00) |
386
- | Z | Abbreviated time zone name or similar information. (OS dependent) |
387
-
388
- **Weekday:**
389
-
390
- | Format | Meaning |
391
- | ------ | ------- |
392
- | A | The full weekday name ("Sunday") |
393
- | a | The abbreviated name ("Sun") |
394
- | u | Day of the week (Monday is 1, 1..7) |
395
- | w | Day of the week (Sunday is 0, 0..6) |
396
-
397
- **ISO 8601 week-based year and week number:**
398
-
399
- The first week of YYYY starts with a Monday and includes YYYY-01-04.
400
- The days in the year before the first week are in the last week of
401
- the previous year.
402
-
403
- | Format | Meaning |
404
- | ------ | ------- |
405
- | G | The week-based year |
406
- | g | The last 2 digits of the week-based year (00..99) |
407
- | V | Week number of the week-based year (01..53) |
408
-
409
- **Week number:**
410
-
411
- The first week of YYYY that starts with a Sunday or Monday (according to %U
412
- or %W). The days in the year before the first week are in week 0.
413
-
414
- | Format | Meaning |
415
- | ------ | ------- |
416
- | U | Week number of the year. The week starts with Sunday. (00..53) |
417
- | W | Week number of the year. The week starts with Monday. (00..53) |
418
-
419
- **Seconds since the Epoch:**
420
-
421
- | Format | Meaning |
422
- | s | Number of seconds since 1970-01-01 00:00:00 UTC. |
423
-
424
- **Literal string:**
425
-
426
- | Format | Meaning |
427
- | ------ | ------- |
428
- | n | Newline character (\n) |
429
- | t | Tab character (\t) |
430
- | % | Literal "%" character |
431
-
432
- **Combination:**
433
-
434
- | Format | Meaning |
435
- | ------ | ------- |
436
- | c | date and time (%a %b %e %T %Y) |
437
- | D | Date (%m/%d/%y) |
438
- | F | The ISO 8601 date format (%Y-%m-%d) |
439
- | v | VMS date (%e-%^b-%4Y) |
440
- | x | Same as %D |
441
- | X | Same as %T |
442
- | r | 12-hour time (%I:%M:%S %p) |
443
- | R | 24-hour time (%H:%M) |
444
- | T | 24-hour time (%H:%M:%S) |
445
-
446
- The default array contains the following patterns:
447
-
448
- When a timezone argument (other than `default`) is explicitly provided:
449
-
450
- ```
451
- ['%FT%T.L', '%FT%T', '%F']
452
- ```
453
-
454
- otherwise:
455
-
456
- ```
457
- ['%FT%T.%L %Z', '%FT%T %Z', '%F %Z', '%FT%T.L', '%FT%T', '%F']
458
- ```
459
-
460
- Examples - Converting to Timestamp
461
-
462
- ```puppet
463
- $ts = Timestamp(1473150899) # 2016-09-06 08:34:59 UTC
464
- $ts = Timestamp({string=>'2015', format=>'%Y'}) # 2015-01-01 00:00:00.000 UTC
465
- $ts = Timestamp('Wed Aug 24 12:13:14 2016', '%c') # 2016-08-24 12:13:14 UTC
466
- $ts = Timestamp('Wed Aug 24 12:13:14 2016 PDT', '%c %Z') # 2016-08-24 19:13:14.000 UTC
467
- $ts = Timestamp('2016-08-24 12:13:14', '%F %T', 'PST') # 2016-08-24 20:13:14.000 UTC
468
- $ts = Timestamp('2016-08-24T12:13:14', default, 'PST') # 2016-08-24 20:13:14.000 UTC
469
-
470
- ```
471
-
472
- ### Conversion to Type
473
-
474
- A new `Type` can be create from its `String` representation.
475
-
476
- **Example:** Creating a type from a string
477
-
478
- ```puppet
479
- $t = Type.new('Integer[10]')
480
- ```
481
-
482
- ### Conversion to String
483
-
484
- Conversion to `String` is the most comprehensive conversion as there are many
485
- use cases where a string representation is wanted. The defaults for the many options
486
- have been chosen with care to be the most basic "value in textual form" representation.
487
- The more advanced forms of formatting are intended to enable writing special purposes formatting
488
- functions in the Puppet language.
489
-
490
- A new string can be created from all other data types. The process is performed in
491
- several steps - first the data type of the given value is inferred, then the resulting data type
492
- is used to find the most significant format specified for that data type. And finally,
493
- the found format is used to convert the given value.
494
-
495
- The mapping from data type to format is referred to as the *format map*. This map
496
- allows different formatting depending on type.
497
-
498
- **Example:** Positive Integers in Hexadecimal prefixed with '0x', negative in Decimal
499
-
500
- ```puppet
501
- $format_map = {
502
- Integer[default, 0] => "%d",
503
- Integer[1, default] => "%#x"
504
- }
505
- String("-1", $format_map) # produces '-1'
506
- String("10", $format_map) # produces '0xa'
507
- ```
508
-
509
- A format is specified on the form:
510
-
511
- ```
512
- %[Flags][Width][.Precision]Format
513
- ```
514
-
515
- `Width` is the number of characters into which the value should be fitted. This allocated space is
516
- padded if value is shorter. By default it is space padded, and the flag `0` will cause padding with `0`
517
- for numerical formats.
518
-
519
- `Precision` is the number of fractional digits to show for floating point, and the maximum characters
520
- included in a string format.
521
-
522
- Note that all data type supports the formats `s` and `p` with the meaning "default string representation" and
523
- "default programmatic string representation" (which for example means that a String is quoted in 'p' format).
524
-
525
- #### Signatures of String conversion
526
-
527
- ```puppet
528
- type Format = Pattern[/^%([\s\+\-#0\[\{<\(\|]*)([1-9][0-9]*)?(?:\.([0-9]+))?([a-zA-Z])/]
529
- type ContainerFormat = Struct[{
530
- format => Optional[String],
531
- separator => Optional[String],
532
- separator2 => Optional[String],
533
- string_formats => Hash[Type, Format]
534
- }]
535
- type TypeMap = Hash[Type, Variant[Format, ContainerFormat]]
536
- type Formats = Variant[Default, String[1], TypeMap]
537
-
538
- function String.new(
539
- Any $value,
540
- Formats $string_formats
541
- )
542
- ```
543
-
544
- Where:
545
-
546
- * `separator` is the string used to separate entries in an array, or hash (extra space should not be included at
547
- the end), defaults to `","`
548
- * `separator2` is the separator between key and value in a hash entry (space padding should be included as
549
- wanted), defaults to `" => "`.
550
- * `string_formats` is a data type to format map for values contained in arrays and hashes - defaults to `{Any => "%p"}`. Note that
551
- these nested formats are not applicable to data types that are containers; they are always formatted as per the top level
552
- format specification.
553
-
554
- **Example:** Simple Conversion to String (using defaults)
555
-
556
- ```puppet
557
- $str = String(10) # produces '10'
558
- $str = String([10]) # produces '["10"]'
559
- ```
560
-
561
- **Example:** Simple Conversion to String specifying the format for the given value directly
562
-
563
- ```puppet
564
- $str = String(10, "%#x") # produces '0x10'
565
- $str = String([10], "%(a") # produces '("10")'
566
- ```
567
-
568
- **Example:** Specifying type for values contained in an array
569
-
570
- ```puppet
571
- $formats = {
572
- Array => {
573
- format => '%(a',
574
- string_formats => { Integer => '%#x' }
575
- }
576
- }
577
- $str = String([1,2,3], $formats) # produces '(0x1, 0x2, 0x3)'
578
- ```
579
-
580
- The given formats are merged with the default formats, and matching of values to convert against format is based on
581
- the specificity of the mapped type; for example, different formats can be used for short and long arrays.
582
-
583
- #### Integer to String
584
-
585
- | Format | Integer Formats
586
- | ------ | ---------------
587
- | d | Decimal, negative values produces leading '-'.
588
- | x X | Hexadecimal in lower or upper case. Uses ..f/..F for negative values unless + is also used. A `#` adds prefix 0x/0X.
589
- | o | Octal. Uses ..0 for negative values unless `+` is also used. A `#` adds prefix 0.
590
- | b B | Binary with prefix 'b' or 'B'. Uses ..1/..1 for negative values unless `+` is also used.
591
- | c | Numeric value representing a Unicode value, result is a one unicode character string, quoted if alternative flag # is used
592
- | s | Same as d, or d in quotes if alternative flag # is used.
593
- | p | Same as d.
594
- | eEfgGaA | Converts integer to float and formats using the floating point rules.
595
-
596
- Defaults to `d`.
597
-
598
- #### Float to String
599
-
600
- | Format | Float formats
601
- | ------ | -------------
602
- | f | Floating point in non exponential notation.
603
- | e E | Exponential notation with 'e' or 'E'.
604
- | g G | Conditional exponential with 'e' or 'E' if exponent < -4 or >= the precision.
605
- | a A | Hexadecimal exponential form, using 'x'/'X' as prefix and 'p'/'P' before exponent.
606
- | s | Converted to string using format p, then applying string formatting rule, alternate form # quotes result.
607
- | p | Same as f format with minimum significant number of fractional digits, prec has no effect.
608
- | dxXobBc | Converts float to integer and formats using the integer rules.
609
-
610
- Defaults to `p`.
611
-
612
- #### String to String
613
-
614
- | Format | String
615
- | ------ | ------
616
- | s | Unquoted string, verbatim output of control chars.
617
- | p | Programmatic representation - strings are quoted, interior quotes and control chars are escaped.
618
- | C | Each `::` name segment capitalized, quoted if alternative flag `#` is used.
619
- | c | Capitalized string, quoted if alternative flag `#` is used.
620
- | d | Downcased string, quoted if alternative flag `#` is used.
621
- | u | Upcased string, quoted if alternative flag `#` is used.
622
- | t | Trims leading and trailing whitespace from the string, quoted if alternative flag `#` is used.
623
-
624
- Defaults to `s` at top level and `p` inside array or hash.
625
-
626
- #### Boolean to String
627
-
628
- | Format | Boolean Formats
629
- | ---- | -------------------
630
- | t T | String 'true'/'false' or 'True'/'False', first char if alternate form is used (i.e. 't'/'f' or 'T'/'F').
631
- | y Y | String 'yes'/'no', 'Yes'/'No', 'y'/'n' or 'Y'/'N' if alternative flag `#` is used.
632
- | dxXobB | Numeric value 0/1 in accordance with the given format which must be valid integer format.
633
- | eEfgGaA | Numeric value 0.0/1.0 in accordance with the given float format and flags.
634
- | s | String 'true' / 'false'.
635
- | p | String 'true' / 'false'.
636
-
637
- #### Regexp to String
638
-
639
- | Format | Regexp Formats
640
- | ---- | --------------
641
- | s | No delimiters, quoted if alternative flag `#` is used.
642
- | p | Delimiters `/ /`.
643
-
644
- #### Undef to String
645
-
646
- | Format | Undef formats
647
- | ------ | -------------
648
- | s | Empty string, or quoted empty string if alternative flag `#` is used.
649
- | p | String 'undef', or quoted '"undef"' if alternative flag `#` is used.
650
- | n | String 'nil', or 'null' if alternative flag `#` is used.
651
- | dxXobB | String 'NaN'.
652
- | eEfgGaA | String 'NaN'.
653
- | v | String 'n/a'.
654
- | V | String 'N/A'.
655
- | u | String 'undef', or 'undefined' if alternative `#` flag is used.
656
-
657
- #### Default value to String
658
-
659
- | Format | Default formats
660
- | ------ | ---------------
661
- | d D | String 'default' or 'Default', alternative form `#` causes value to be quoted.
662
- | s | Same as d.
663
- | p | Same as d.
664
-
665
- #### Binary value to String
666
-
667
- | Format | Default formats
668
- | ------ | ---------------
669
- | s | binary as unquoted UTF-8 characters (errors if byte sequence is invalid UTF-8). Alternate form escapes non ascii bytes.
670
- | p | 'Binary("<base64strict>")'
671
- | b | '<base64>' - base64 string with newlines inserted
672
- | B | '<base64strict>' - base64 strict string (without newlines inserted)
673
- | u | '<base64urlsafe>' - base64 urlsafe string
674
- | t | 'Binary' - outputs the name of the type only
675
- | T | 'BINARY' - output the name of the type in all caps only
676
-
677
- * The alternate form flag `#` will quote the binary or base64 text output.
678
- * The format `%#s` allows invalid UTF-8 characters and outputs all non ascii bytes
679
- as hex escaped characters on the form `\\xHH` where `H` is a hex digit.
680
- * The width and precision values are applied to the text part only in `%p` format.
681
-
682
- #### Array & Tuple to String
683
-
684
- | Format | Array/Tuple Formats
685
- | ------ | -------------
686
- | a | Formats with `[ ]` delimiters and `,`, alternate form `#` indents nested arrays/hashes.
687
- | s | Same as a.
688
- | p | Same as a.
689
-
690
- See "Flags" `<[({\|` for formatting of delimiters, and "Additional parameters for containers; Array and Hash" for
691
- more information about options.
692
-
693
- The alternate form flag `#` will cause indentation of nested array or hash containers. If width is also set
694
- it is taken as the maximum allowed length of a sequence of elements (not including delimiters). If this max length
695
- is exceeded, each element will be indented.
696
-
697
- #### Hash & Struct to String
698
-
699
- | Format | Hash/Struct Formats
700
- | ------ | -------------
701
- | h | Formats with `{ }` delimiters, `,` element separator and ` => ` inner element separator unless overridden by flags.
702
- | s | Same as h.
703
- | p | Same as h.
704
- | a | Converts the hash to an array of [k,v] tuples and formats it using array rule(s).
705
-
706
- See "Flags" `<[({\|` for formatting of delimiters, and "Additional parameters for containers; Array and Hash" for
707
- more information about options.
708
-
709
- The alternate form flag `#` will format each hash key/value entry indented on a separate line.
710
-
711
- #### Type to String
712
-
713
- | Format | Array/Tuple Formats
714
- | ------ | -------------
715
- | s | The same as `p`, quoted if alternative flag `#` is used.
716
- | p | Outputs the type in string form as specified by the Puppet Language.
717
-
718
- #### Flags
719
-
720
- | Flag | Effect
721
- | ------ | ------
722
- | (space) | A space instead of `+` for numeric output (`-` is shown), for containers skips delimiters.
723
- | # | Alternate format; prefix 0x/0x, 0 (octal) and 0b/0B for binary, Floats force decimal '.'. For g/G keep trailing 0.
724
- | + | Show sign +/- depending on value's sign, changes x, X, o, b, B format to not use 2's complement form.
725
- | - | Left justify the value in the given width.
726
- | 0 | Pad with 0 instead of space for widths larger than value.
727
- | <[({\| | Defines an enclosing pair <> [] () {} or \| \| when used with a container type.
728
-
729
- ### Conversion to Boolean
730
-
731
- Accepts a single value as argument:
732
-
733
- * Float 0.0 is `false`, all other float values are `true`
734
- * Integer 0 is `false`, all other integer values are `true`
735
- * Strings
736
- * `true` if 'true', 'yes', 'y' (case independent compare)
737
- * `false` if 'false', 'no', 'n' (case independent compare)
738
- * Boolean is already boolean and is simply returned
739
-
740
- ### Conversion to Array and Tuple
741
-
742
- When given a single value as argument:
743
-
744
- * A non empty `Hash` is converted to an array matching `Array[Tuple[Any,Any], 1]`.
745
- * An empty `Hash` becomes an empty array.
746
- * An `Array` is simply returned.
747
- * An `Iterable[T]` is turned into an array of `T` instances.
748
- * A `Binary` is converted to an `Array[Integer[0,255]]` of byte values
749
-
750
-
751
- When given a second Boolean argument:
752
-
753
- * if `true`, a value that is not already an array is returned as a one element array.
754
- * if `false`, (the default), converts the first argument as shown above.
755
-
756
- **Example:** Ensuring value is an array
757
-
758
- ```puppet
759
- $arr = Array($value, true)
760
- ```
761
-
762
- Conversion to a `Tuple` works exactly as conversion to an `Array`, only that the constructed array is
763
- asserted against the given tuple type.
764
-
765
- ### Conversion to Hash and Struct
766
-
767
- Accepts a single value as argument:
768
-
769
- * An empty `Array` becomes an empty `Hash`
770
- * An `Array` matching `Array[Tuple[Any,Any], 1]` is converted to a hash where each tuple describes a key/value entry
771
- * An `Array` with an even number of entries is interpreted as `[key1, val1, key2, val2, ...]`
772
- * An `Iterable` is turned into an `Array` and then converted to hash as per the array rules
773
- * A `Hash` is simply returned
774
-
775
- Alternatively, a tree can be constructed by giving two values; an array of tuples on the form `[path, value]`
776
- (where the `path` is the path from the root of a tree, and `value` the value at that position in the tree), and
777
- either the option `'tree'` (do not convert arrays to hashes except the top level), or
778
- `'hash_tree'` (convert all arrays to hashes).
779
-
780
- The tree/hash_tree forms of Hash creation are suited for transforming the result of an iteration
781
- using `tree_each` and subsequent filtering or mapping.
782
-
783
- **Example:** Mapping a hash tree
784
-
785
- Mapping an arbitrary structure in a way that keeps the structure, but where some values are replaced
786
- can be done by using the `tree_each` function, mapping, and then constructing a new Hash from the result:
787
-
788
- ```puppet
789
- # A hash tree with 'water' at different locations
790
- $h = { a => { b => { x => 'water'}}, b => { y => 'water'} }
791
- # a helper function that turns water into wine
792
- function make_wine($x) { if $x == 'water' { 'wine' } else { $x } }
793
- # create a flattened tree with water turned into wine
794
- $flat_tree = $h.tree_each.map |$entry| { [$entry[0], make_wine($entry[1])] }
795
- # create a new Hash and log it
796
- notice Hash($flat_tree, 'hash_tree')
797
- ```
798
-
799
- Would notice the hash `{a => {b => {x => wine}}, b => {y => wine}}`
800
-
801
- Conversion to a `Struct` works exactly as conversion to a `Hash`, only that the constructed hash is
802
- asserted against the given struct type.
803
-
804
- ### Conversion to a Regexp
805
-
806
- A `String` can be converted into a `Regexp`
807
-
808
- **Example**: Converting a String into a Regexp
809
- ```puppet
810
- $s = '[a-z]+\.com'
811
- $r = Regexp($s)
812
- if('foo.com' =~ $r) {
813
- ...
814
- }
815
- ```
816
-
817
- ### Creating a SemVer
818
-
819
- A SemVer object represents a single [Semantic Version](http://semver.org/).
820
- It can be created from a String, individual values for its parts, or a hash specifying the value per part.
821
- See the specification at [semver.org](http://semver.org/) for the meaning of the SemVer's parts.
822
-
823
- The signatures are:
824
-
825
- ```puppet
826
- type PositiveInteger = Integer[0,default]
827
- type SemVerQualifier = Pattern[/\A(?<part>[0-9A-Za-z-]+)(?:\.\g<part>)*\Z/]
828
- type SemVerString = String[1]
829
- type SemVerHash =Struct[{
830
- major => PositiveInteger,
831
- minor => PositiveInteger,
832
- patch => PositiveInteger,
833
- Optional[prerelease] => SemVerQualifier,
834
- Optional[build] => SemVerQualifier
835
- }]
836
-
837
- function SemVer.new(SemVerString $str)
838
-
839
- function SemVer.new(
840
- PositiveInteger $major
841
- PositiveInteger $minor
842
- PositiveInteger $patch
843
- Optional[SemVerQualifier] $prerelease = undef
844
- Optional[SemVerQualifier] $build = undef
845
- )
846
-
847
- function SemVer.new(SemVerHash $hash_args)
848
- ```
849
-
850
- **Examples:** SemVer and SemVerRange usage
851
-
852
- ```puppet
853
- # As a type, SemVer can describe disjunct ranges which versions can be
854
- # matched against - here the type is constructed with two
855
- # SemVerRange objects.
856
- #
857
- $t = SemVer[
858
- SemVerRange('>=1.0.0 <2.0.0'),
859
- SemVerRange('>=3.0.0 <4.0.0')
860
- ]
861
- notice(SemVer('1.2.3') =~ $t) # true
862
- notice(SemVer('2.3.4') =~ $t) # false
863
- notice(SemVer('3.4.5') =~ $t) # true
864
- ```
865
-
866
- ### Creating a SemVerRange
867
-
868
- A `SemVerRange` object represents a range of `SemVer`. It can be created from
869
- a `String`, or from two `SemVer` instances, where either end can be given as
870
- a literal `default` to indicate infinity. The string format of a `SemVerRange` is specified by
871
- the [Semantic Version Range Grammar](https://github.com/npm/node-semver#ranges).
872
-
873
- > Use of the comparator sets described in the grammar (joining with `||`) is not supported.
874
-
875
- The signatures are:
876
-
877
- ```puppet
878
- type SemVerRangeString = String[1]
879
- type SemVerRangeHash = Struct[{
880
- min => Variant[Default, SemVer],
881
- Optional[max] => Variant[Default, SemVer],
882
- Optional[exclude_max] => Boolean
883
- }]
884
-
885
- function SemVerRange.new(
886
- SemVerRangeString $semver_range_string
887
- )
888
-
889
- function SemVerRange.new(
890
- Variant[Default,SemVer] $min
891
- Variant[Default,SemVer] $max
892
- Optional[Boolean] $exclude_max = undef
893
- )
894
-
895
- function SemVerRange.new(
896
- SemVerRangeHash $semver_range_hash
897
- )
898
- ```
899
-
900
- For examples of `SemVerRange` use, see "Creating a SemVer".
901
-
902
- ### Creating a Binary
903
-
904
- A `Binary` object represents a sequence of bytes and it can be created from a String in Base64 format,
905
- an Array containing byte values. A Binary can also be created from a Hash containing the value to convert to
906
- a `Binary`.
907
-
908
- The signatures are:
909
-
910
- ```puppet
911
- type ByteInteger = Integer[0,255]
912
- type Base64Format = Enum["%b", "%u", "%B", "%s"]
913
- type StringHash = Struct[{value => String, "format" => Optional[Base64Format]}]
914
- type ArrayHash = Struct[{value => Array[ByteInteger]}]
915
- type BinaryArgsHash = Variant[StringHash, ArrayHash]
916
-
917
- function Binary.new(
918
- String $base64_str,
919
- Optional[Base64Format] $format
920
- )
921
-
922
- function Binary.new(
923
- Array[ByteInteger] $byte_array
924
- }
925
-
926
- # Same as for String, or for Array, but where arguments are given in a Hash.
927
- function Binary.new(BinaryArgsHash $hash_args)
928
- ```
929
-
930
- The formats have the following meaning:
931
-
932
- | format | explanation |
933
- | ---- | ---- |
934
- | B | The data is in base64 strict encoding
935
- | u | The data is in URL safe base64 encoding
936
- | b | The data is in base64 encoding, padding as required by base64 strict, is added by default
937
- | s | The data is a puppet string. The string must be valid UTF-8, or convertible to UTF-8 or an error is raised.
938
- | r | (Ruby Raw) the byte sequence in the given string is used verbatim irrespective of possible encoding errors
939
-
940
- * The default format is `%B`.
941
- * Note that the format `%r` should be used sparingly, or not at all. It exists for backwards compatibility reasons when someone receiving
942
- 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.
943
-
944
- **Examples:** Creating a Binary
945
-
946
- ```puppet
947
- # create the binary content "abc"
948
- $a = Binary('YWJj')
949
-
950
- # create the binary content from content in a module's file
951
- $b = binary_file('mymodule/mypicture.jpg')
952
- ```
953
-
954
- * Since 4.5.0
955
- * Binary type since 4.8.0
956
-
957
- Creating an instance of a `Type` using the `Init` type.
958
- -------
959
-
960
- The type `Init[T]` describes a value that can be used when instantiating a type. When used as the first argument in a call to `new`, it
961
- will dispatch the call to its contained type and optionally augment the parameter list with additional arguments.
962
-
963
- **Example:** Creating an instance of Integer using Init[Integer]
964
-
965
- ```puppet
966
- # The following declaration
967
- $x = Init[Integer].new('128')
968
- # is exactly the same as
969
- $x = Integer.new('128')
970
- ```
971
-
972
- or, with base 16 and using implicit new
973
-
974
- ```puppet
975
- # The following declaration
976
- $x = Init[Integer,16]('80')
977
- # is exactly the same as
978
- $x = Integer('80', 16)
979
- ```
980
-
981
- **Example:** Creating an instance of String using a predefined format
982
-
983
- ```puppet
984
- $fmt = Init[String,'%#x']
985
- notice($fmt(256)) # will notice '0x100'
986
- ```
987
-
988
- DOC
989
- ) do |args|
7
+ :doc => <<~DOC
8
+ Creates a new instance/object of a given data type.
9
+
10
+ This function makes it possible to create new instances of
11
+ concrete data types. If a block is given it is called with the
12
+ just created instance as an argument.
13
+
14
+ Calling this function is equivalent to directly
15
+ calling the data type:
16
+
17
+ **Example:** `new` and calling type directly are equivalent
18
+
19
+ ```puppet
20
+ $a = Integer.new("42")
21
+ $b = Integer("42")
22
+ ```
23
+
24
+ These would both convert the string `"42"` to the decimal value `42`.
25
+
26
+ **Example:** arguments by position or by name
27
+
28
+ ```puppet
29
+ $a = Integer.new("42", 8)
30
+ $b = Integer({from => "42", radix => 8})
31
+ ```
32
+
33
+ This would convert the octal (radix 8) number `"42"` in string form
34
+ to the decimal value `34`.
35
+
36
+ The new function supports two ways of giving the arguments:
37
+
38
+ * by name (using a hash with property to value mapping)
39
+ * by position (as regular arguments)
40
+
41
+ Note that it is not possible to create new instances of
42
+ some abstract data types (for example `Variant`). The data type `Optional[T]` is an
43
+ exception as it will create an instance of `T` or `undef` if the
44
+ value to convert is `undef`.
45
+
46
+ The arguments that can be given is determined by the data type.
47
+
48
+ > An assertion is always made that the produced value complies with the given type constraints.
49
+
50
+ **Example:** data type constraints are checked
51
+
52
+ ```puppet
53
+ Integer[0].new("-100")
54
+ ```
55
+
56
+ Would fail with an assertion error (since value is less than 0).
57
+
58
+ The following sections show the arguments and conversion rules
59
+ per data type built into the Puppet Type System.
60
+
61
+ ### Conversion to Optional[T] and NotUndef[T]
62
+
63
+ Conversion to these data types is the same as a conversion to the type argument `T`.
64
+ In the case of `Optional[T]` it is accepted that the argument to convert may be `undef`.
65
+ It is however not acceptable to give other arguments (than `undef`) that cannot be
66
+ converted to `T`.
67
+
68
+ ### Conversion to Integer
69
+
70
+ A new `Integer` can be created from `Integer`, `Float`, `Boolean`, and `String` values.
71
+ For conversion from `String` it is possible to specify the radix (base).
72
+
73
+ ```puppet
74
+ type Radix = Variant[Default, Integer[2,2], Integer[8,8], Integer[10,10], Integer[16,16]]
75
+
76
+ function Integer.new(
77
+ String $value,
78
+ Radix $radix = 10,
79
+ Boolean $abs = false
80
+ )
81
+
82
+ function Integer.new(
83
+ Variant[Numeric, Boolean] $value,
84
+ Boolean $abs = false
85
+ )
86
+ ```
87
+
88
+ * When converting from `String` the default radix is 10.
89
+ * If radix is not specified an attempt is made to detect the radix from the start of the string:
90
+ * `0b` or `0B` is taken as radix 2.
91
+ * `0x` or `0X` is taken as radix 16.
92
+ * `0` as radix 8.
93
+ * All others are decimal.
94
+ * Conversion from `String` accepts an optional sign in the string.
95
+ * For hexadecimal (radix 16) conversion an optional leading "0x", or "0X" is accepted.
96
+ * For octal (radix 8) an optional leading "0" is accepted.
97
+ * For binary (radix 2) an optional leading "0b" or "0B" is accepted.
98
+ * When `radix` is set to `default`, the conversion is based on the leading.
99
+ characters in the string. A leading "0" for radix 8, a leading "0x", or "0X" for
100
+ radix 16, and leading "0b" or "0B" for binary.
101
+ * Conversion from `Boolean` results in 0 for `false` and 1 for `true`.
102
+ * Conversion from `Integer`, `Float`, and `Boolean` ignores the radix.
103
+ * `Float` value fractions are truncated (no rounding).
104
+ * When `abs` is set to `true`, the result will be an absolute integer.
105
+
106
+ Examples - Converting to Integer:
107
+
108
+ ```puppet
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
114
+ ```
115
+
116
+ ### Conversion to Float
117
+
118
+ A new `Float` can be created from `Integer`, `Float`, `Boolean`, and `String` values.
119
+ For conversion from `String` both float and integer formats are supported.
120
+
121
+ ```puppet
122
+ function Float.new(
123
+ Variant[Numeric, Boolean, String] $value,
124
+ Boolean $abs = true
125
+ )
126
+ ```
127
+
128
+ * For an integer, the floating point fraction of `.0` is added to the value.
129
+ * A `Boolean` `true` is converted to 1.0, and a `false` to 0.0
130
+ * In `String` format, integer prefixes for hex and binary are understood (but not octal since
131
+ floating point in string format may start with a '0').
132
+ * When `abs` is set to `true`, the result will be an absolute floating point value.
133
+
134
+ ### Conversion to Numeric
135
+
136
+ A new `Integer` or `Float` can be created from `Integer`, `Float`, `Boolean` and
137
+ `String` values.
138
+
139
+ ```puppet
140
+ function Numeric.new(
141
+ Variant[Numeric, Boolean, String] $value,
142
+ Boolean $abs = true
143
+ )
144
+ ```
145
+
146
+ * If the value has a decimal period, or if given in scientific notation
147
+ (e/E), the result is a `Float`, otherwise the value is an `Integer`. The
148
+ conversion from `String` always uses a radix based on the prefix of the string.
149
+ * Conversion from `Boolean` results in 0 for `false` and 1 for `true`.
150
+ * When `abs` is set to `true`, the result will be an absolute `Float`or `Integer` value.
151
+
152
+ Examples - Converting to Numeric
153
+
154
+ ```puppet
155
+ $a_number = Numeric(true) # results in 1
156
+ $a_number = Numeric("0xFF") # results in 255
157
+ $a_number = Numeric("010") # results in 8
158
+ $a_number = Numeric("3.14") # results in 3.14 (a float)
159
+ $a_number = Numeric(-42.3, true) # results in 42.3
160
+ $a_number = Numeric(-42, true) # results in 42
161
+ ```
162
+
163
+ ### Conversion to Timespan
164
+
165
+ A new `Timespan` can be created from `Integer`, `Float`, `String`, and `Hash` values. Several variants of the constructor are provided.
166
+
167
+ #### Timespan from seconds
168
+
169
+ When a Float is used, the decimal part represents fractions of a second.
170
+
171
+ ```puppet
172
+ function Timespan.new(
173
+ Variant[Float, Integer] $value
174
+ )
175
+ ```
176
+
177
+ #### Timespan from days, hours, minutes, seconds, and fractions of a second
178
+
179
+ The arguments can be passed separately in which case the first four, days, hours, minutes, and seconds are mandatory and the rest are optional.
180
+ All values may overflow and/or be negative. The internal 128-bit nano-second integer is calculated as:
181
+
182
+ ```
183
+ (((((days * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000 + milliseconds) * 1000 + microseconds) * 1000 + nanoseconds
184
+ ```
185
+
186
+ ```puppet
187
+ function Timespan.new(
188
+ Integer $days, Integer $hours, Integer $minutes, Integer $seconds,
189
+ Integer $milliseconds = 0, Integer $microseconds = 0, Integer $nanoseconds = 0
190
+ )
191
+ ```
192
+
193
+ or, all arguments can be passed as a `Hash`, in which case all entries are optional:
194
+
195
+ ```puppet
196
+ function Timespan.new(
197
+ Struct[{
198
+ Optional[negative] => Boolean,
199
+ Optional[days] => Integer,
200
+ Optional[hours] => Integer,
201
+ Optional[minutes] => Integer,
202
+ Optional[seconds] => Integer,
203
+ Optional[milliseconds] => Integer,
204
+ Optional[microseconds] => Integer,
205
+ Optional[nanoseconds] => Integer
206
+ }] $hash
207
+ )
208
+ ```
209
+
210
+ #### Timespan from String and format directive patterns
211
+
212
+ The first argument is parsed using the format optionally passed as a string or array of strings. When an array is used, an attempt
213
+ will be made to parse the string using the first entry and then with each entry in succession until parsing succeeds. If the second
214
+ argument is omitted, an array of default formats will be used.
215
+
216
+ An exception is raised when no format was able to parse the given string.
217
+
218
+ ```puppet
219
+ function Timespan.new(
220
+ String $string, Variant[String[2],Array[String[2], 1]] $format = <default format>)
221
+ )
222
+ ```
223
+
224
+ the arguments may also be passed as a `Hash`:
225
+
226
+ ```puppet
227
+ function Timespan.new(
228
+ Struct[{
229
+ string => String[1],
230
+ Optional[format] => Variant[String[2],Array[String[2], 1]]
231
+ }] $hash
232
+ )
233
+ ```
234
+
235
+ The directive consists of a percent (%) character, zero or more flags, optional minimum field width and
236
+ a conversion specifier as follows:
237
+ ```
238
+ %[Flags][Width]Conversion
239
+ ```
240
+
241
+ ##### Flags:
242
+
243
+ | Flag | Meaning
244
+ | ---- | ---------------
245
+ | - | Don't pad numerical output
246
+ | _ | Use spaces for padding
247
+ | 0 | Use zeros for padding
248
+
249
+ ##### Format directives:
250
+
251
+ | Format | Meaning |
252
+ | ------ | ------- |
253
+ | D | Number of Days |
254
+ | H | Hour of the day, 24-hour clock |
255
+ | M | Minute of the hour (00..59) |
256
+ | S | Second of the minute (00..59) |
257
+ | L | Millisecond of the second (000..999) |
258
+ | N | Fractional seconds digits |
259
+
260
+ The format directive that represents the highest magnitude in the format will be allowed to
261
+ overflow. I.e. if no "%D" is used but a "%H" is present, then the hours may be more than 23.
262
+
263
+ The default array contains the following patterns:
264
+
265
+ ```
266
+ ['%D-%H:%M:%S', '%D-%H:%M', '%H:%M:%S', '%H:%M']
267
+ ```
268
+
269
+ Examples - Converting to Timespan
270
+
271
+ ```puppet
272
+ $duration = Timespan(13.5) # 13 seconds and 500 milliseconds
273
+ $duration = Timespan({days=>4}) # 4 days
274
+ $duration = Timespan(4, 0, 0, 2) # 4 days and 2 seconds
275
+ $duration = Timespan('13:20') # 13 hours and 20 minutes (using default pattern)
276
+ $duration = Timespan('10:03.5', '%M:%S.%L') # 10 minutes, 3 seconds, and 5 milli-seconds
277
+ $duration = Timespan('10:03.5', '%M:%S.%N') # 10 minutes, 3 seconds, and 5 nano-seconds
278
+ ```
279
+
280
+ ### Conversion to Timestamp
281
+
282
+ A new `Timestamp` can be created from `Integer`, `Float`, `String`, and `Hash` values. Several variants of the constructor are provided.
283
+
284
+ #### Timestamp from seconds since epoch (1970-01-01 00:00:00 UTC)
285
+
286
+ When a Float is used, the decimal part represents fractions of a second.
287
+
288
+ ```puppet
289
+ function Timestamp.new(
290
+ Variant[Float, Integer] $value
291
+ )
292
+ ```
293
+
294
+ #### Timestamp from String and patterns consisting of format directives
295
+
296
+ The first argument is parsed using the format optionally passed as a string or array of strings. When an array is used, an attempt
297
+ will be made to parse the string using the first entry and then with each entry in succession until parsing succeeds. If the second
298
+ argument is omitted, an array of default formats will be used.
299
+
300
+ A third optional timezone argument can be provided. The first argument will then be parsed as if it represents a local time in that
301
+ timezone. The timezone can be any timezone that is recognized when using the '%z' or '%Z' formats, or the word 'current', in which
302
+ case the current timezone of the evaluating process will be used. The timezone argument is case insensitive.
303
+
304
+ The default timezone, when no argument is provided, or when using the keyword `default`, is 'UTC'.
305
+
306
+ It is illegal to provide a timezone argument other than `default` in combination with a format that contains '%z' or '%Z' since that
307
+ would introduce an ambiguity as to which timezone to use. The one extracted from the string, or the one provided as an argument.
308
+
309
+ An exception is raised when no format was able to parse the given string.
310
+
311
+ ```puppet
312
+ function Timestamp.new(
313
+ String $string,
314
+ Variant[String[2],Array[String[2], 1]] $format = <default format>,
315
+ String $timezone = default)
316
+ )
317
+ ```
318
+
319
+ the arguments may also be passed as a `Hash`:
320
+
321
+ ```puppet
322
+ function Timestamp.new(
323
+ Struct[{
324
+ string => String[1],
325
+ Optional[format] => Variant[String[2],Array[String[2], 1]],
326
+ Optional[timezone] => String[1]
327
+ }] $hash
328
+ )
329
+ ```
330
+
331
+ The directive consists of a percent (%) character, zero or more flags, optional minimum field width and
332
+ a conversion specifier as follows:
333
+ ```
334
+ %[Flags][Width]Conversion
335
+ ```
336
+
337
+ ##### Flags:
338
+
339
+ | Flag | Meaning
340
+ | ---- | ---------------
341
+ | - | Don't pad numerical output
342
+ | _ | Use spaces for padding
343
+ | 0 | Use zeros for padding
344
+ | # | Change names to upper-case or change case of am/pm
345
+ | ^ | Use uppercase
346
+ | : | Use colons for %z
347
+
348
+ ##### Format directives (names and padding can be altered using flags):
349
+
350
+ **Date (Year, Month, Day):**
351
+
352
+ | Format | Meaning |
353
+ | ------ | ------- |
354
+ | Y | Year with century, zero-padded to at least 4 digits |
355
+ | C | year / 100 (rounded down such as 20 in 2009) |
356
+ | y | year % 100 (00..99) |
357
+ | m | Month of the year, zero-padded (01..12) |
358
+ | B | The full month name ("January") |
359
+ | b | The abbreviated month name ("Jan") |
360
+ | h | Equivalent to %b |
361
+ | d | Day of the month, zero-padded (01..31) |
362
+ | e | Day of the month, blank-padded ( 1..31) |
363
+ | j | Day of the year (001..366) |
364
+
365
+ **Time (Hour, Minute, Second, Subsecond):**
366
+
367
+ | Format | Meaning |
368
+ | ------ | ------- |
369
+ | H | Hour of the day, 24-hour clock, zero-padded (00..23) |
370
+ | k | Hour of the day, 24-hour clock, blank-padded ( 0..23) |
371
+ | I | Hour of the day, 12-hour clock, zero-padded (01..12) |
372
+ | l | Hour of the day, 12-hour clock, blank-padded ( 1..12) |
373
+ | P | Meridian indicator, lowercase ("am" or "pm") |
374
+ | p | Meridian indicator, uppercase ("AM" or "PM") |
375
+ | M | Minute of the hour (00..59) |
376
+ | S | Second of the minute (00..60) |
377
+ | L | Millisecond of the second (000..999). Digits under millisecond are truncated to not produce 1000 |
378
+ | N | Fractional seconds digits, default is 9 digits (nanosecond). Digits under a specified width are truncated to avoid carry up |
379
+
380
+ **Time (Hour, Minute, Second, Subsecond):**
381
+
382
+ | Format | Meaning |
383
+ | ------ | ------- |
384
+ | z | Time zone as hour and minute offset from UTC (e.g. +0900) |
385
+ | :z | hour and minute offset from UTC with a colon (e.g. +09:00) |
386
+ | ::z | hour, minute and second offset from UTC (e.g. +09:00:00) |
387
+ | Z | Abbreviated time zone name or similar information. (OS dependent) |
388
+
389
+ **Weekday:**
390
+
391
+ | Format | Meaning |
392
+ | ------ | ------- |
393
+ | A | The full weekday name ("Sunday") |
394
+ | a | The abbreviated name ("Sun") |
395
+ | u | Day of the week (Monday is 1, 1..7) |
396
+ | w | Day of the week (Sunday is 0, 0..6) |
397
+
398
+ **ISO 8601 week-based year and week number:**
399
+
400
+ The first week of YYYY starts with a Monday and includes YYYY-01-04.
401
+ The days in the year before the first week are in the last week of
402
+ the previous year.
403
+
404
+ | Format | Meaning |
405
+ | ------ | ------- |
406
+ | G | The week-based year |
407
+ | g | The last 2 digits of the week-based year (00..99) |
408
+ | V | Week number of the week-based year (01..53) |
409
+
410
+ **Week number:**
411
+
412
+ The first week of YYYY that starts with a Sunday or Monday (according to %U
413
+ or %W). The days in the year before the first week are in week 0.
414
+
415
+ | Format | Meaning |
416
+ | ------ | ------- |
417
+ | U | Week number of the year. The week starts with Sunday. (00..53) |
418
+ | W | Week number of the year. The week starts with Monday. (00..53) |
419
+
420
+ **Seconds since the Epoch:**
421
+
422
+ | Format | Meaning |
423
+ | s | Number of seconds since 1970-01-01 00:00:00 UTC. |
424
+
425
+ **Literal string:**
426
+
427
+ | Format | Meaning |
428
+ | ------ | ------- |
429
+ | n | Newline character (\n) |
430
+ | t | Tab character (\t) |
431
+ | % | Literal "%" character |
432
+
433
+ **Combination:**
434
+
435
+ | Format | Meaning |
436
+ | ------ | ------- |
437
+ | c | date and time (%a %b %e %T %Y) |
438
+ | D | Date (%m/%d/%y) |
439
+ | F | The ISO 8601 date format (%Y-%m-%d) |
440
+ | v | VMS date (%e-%^b-%4Y) |
441
+ | x | Same as %D |
442
+ | X | Same as %T |
443
+ | r | 12-hour time (%I:%M:%S %p) |
444
+ | R | 24-hour time (%H:%M) |
445
+ | T | 24-hour time (%H:%M:%S) |
446
+
447
+ The default array contains the following patterns:
448
+
449
+ When a timezone argument (other than `default`) is explicitly provided:
450
+
451
+ ```
452
+ ['%FT%T.L', '%FT%T', '%F']
453
+ ```
454
+
455
+ otherwise:
456
+
457
+ ```
458
+ ['%FT%T.%L %Z', '%FT%T %Z', '%F %Z', '%FT%T.L', '%FT%T', '%F']
459
+ ```
460
+
461
+ Examples - Converting to Timestamp
462
+
463
+ ```puppet
464
+ $ts = Timestamp(1473150899) # 2016-09-06 08:34:59 UTC
465
+ $ts = Timestamp({string=>'2015', format=>'%Y'}) # 2015-01-01 00:00:00.000 UTC
466
+ $ts = Timestamp('Wed Aug 24 12:13:14 2016', '%c') # 2016-08-24 12:13:14 UTC
467
+ $ts = Timestamp('Wed Aug 24 12:13:14 2016 PDT', '%c %Z') # 2016-08-24 19:13:14.000 UTC
468
+ $ts = Timestamp('2016-08-24 12:13:14', '%F %T', 'PST') # 2016-08-24 20:13:14.000 UTC
469
+ $ts = Timestamp('2016-08-24T12:13:14', default, 'PST') # 2016-08-24 20:13:14.000 UTC
470
+
471
+ ```
472
+
473
+ ### Conversion to Type
474
+
475
+ A new `Type` can be create from its `String` representation.
476
+
477
+ **Example:** Creating a type from a string
478
+
479
+ ```puppet
480
+ $t = Type.new('Integer[10]')
481
+ ```
482
+
483
+ ### Conversion to String
484
+
485
+ Conversion to `String` is the most comprehensive conversion as there are many
486
+ use cases where a string representation is wanted. The defaults for the many options
487
+ have been chosen with care to be the most basic "value in textual form" representation.
488
+ The more advanced forms of formatting are intended to enable writing special purposes formatting
489
+ functions in the Puppet language.
490
+
491
+ A new string can be created from all other data types. The process is performed in
492
+ several steps - first the data type of the given value is inferred, then the resulting data type
493
+ is used to find the most significant format specified for that data type. And finally,
494
+ the found format is used to convert the given value.
495
+
496
+ The mapping from data type to format is referred to as the *format map*. This map
497
+ allows different formatting depending on type.
498
+
499
+ **Example:** Positive Integers in Hexadecimal prefixed with '0x', negative in Decimal
500
+
501
+ ```puppet
502
+ $format_map = {
503
+ Integer[default, 0] => "%d",
504
+ Integer[1, default] => "%#x"
505
+ }
506
+ String("-1", $format_map) # produces '-1'
507
+ String("10", $format_map) # produces '0xa'
508
+ ```
509
+
510
+ A format is specified on the form:
511
+
512
+ ```
513
+ %[Flags][Width][.Precision]Format
514
+ ```
515
+
516
+ `Width` is the number of characters into which the value should be fitted. This allocated space is
517
+ padded if value is shorter. By default it is space padded, and the flag `0` will cause padding with `0`
518
+ for numerical formats.
519
+
520
+ `Precision` is the number of fractional digits to show for floating point, and the maximum characters
521
+ included in a string format.
522
+
523
+ Note that all data type supports the formats `s` and `p` with the meaning "default string representation" and
524
+ "default programmatic string representation" (which for example means that a String is quoted in 'p' format).
525
+
526
+ #### Signatures of String conversion
527
+
528
+ ```puppet
529
+ type Format = Pattern[/^%([\s\+\-#0\[\{<\(\|]*)([1-9][0-9]*)?(?:\.([0-9]+))?([a-zA-Z])/]
530
+ type ContainerFormat = Struct[{
531
+ format => Optional[String],
532
+ separator => Optional[String],
533
+ separator2 => Optional[String],
534
+ string_formats => Hash[Type, Format]
535
+ }]
536
+ type TypeMap = Hash[Type, Variant[Format, ContainerFormat]]
537
+ type Formats = Variant[Default, String[1], TypeMap]
538
+
539
+ function String.new(
540
+ Any $value,
541
+ Formats $string_formats
542
+ )
543
+ ```
544
+
545
+ Where:
546
+
547
+ * `separator` is the string used to separate entries in an array, or hash (extra space should not be included at
548
+ the end), defaults to `","`
549
+ * `separator2` is the separator between key and value in a hash entry (space padding should be included as
550
+ wanted), defaults to `" => "`.
551
+ * `string_formats` is a data type to format map for values contained in arrays and hashes - defaults to `{Any => "%p"}`. Note that
552
+ these nested formats are not applicable to data types that are containers; they are always formatted as per the top level
553
+ format specification.
554
+
555
+ **Example:** Simple Conversion to String (using defaults)
556
+
557
+ ```puppet
558
+ $str = String(10) # produces '10'
559
+ $str = String([10]) # produces '["10"]'
560
+ ```
561
+
562
+ **Example:** Simple Conversion to String specifying the format for the given value directly
563
+
564
+ ```puppet
565
+ $str = String(10, "%#x") # produces '0x10'
566
+ $str = String([10], "%(a") # produces '("10")'
567
+ ```
568
+
569
+ **Example:** Specifying type for values contained in an array
570
+
571
+ ```puppet
572
+ $formats = {
573
+ Array => {
574
+ format => '%(a',
575
+ string_formats => { Integer => '%#x' }
576
+ }
577
+ }
578
+ $str = String([1,2,3], $formats) # produces '(0x1, 0x2, 0x3)'
579
+ ```
580
+
581
+ The given formats are merged with the default formats, and matching of values to convert against format is based on
582
+ the specificity of the mapped type; for example, different formats can be used for short and long arrays.
583
+
584
+ #### Integer to String
585
+
586
+ | Format | Integer Formats
587
+ | ------ | ---------------
588
+ | d | Decimal, negative values produces leading '-'.
589
+ | x X | Hexadecimal in lower or upper case. Uses ..f/..F for negative values unless + is also used. A `#` adds prefix 0x/0X.
590
+ | o | Octal. Uses ..0 for negative values unless `+` is also used. A `#` adds prefix 0.
591
+ | b B | Binary with prefix 'b' or 'B'. Uses ..1/..1 for negative values unless `+` is also used.
592
+ | c | Numeric value representing a Unicode value, result is a one unicode character string, quoted if alternative flag # is used
593
+ | s | Same as d, or d in quotes if alternative flag # is used.
594
+ | p | Same as d.
595
+ | eEfgGaA | Converts integer to float and formats using the floating point rules.
596
+
597
+ Defaults to `d`.
598
+
599
+ #### Float to String
600
+
601
+ | Format | Float formats
602
+ | ------ | -------------
603
+ | f | Floating point in non exponential notation.
604
+ | e E | Exponential notation with 'e' or 'E'.
605
+ | g G | Conditional exponential with 'e' or 'E' if exponent < -4 or >= the precision.
606
+ | a A | Hexadecimal exponential form, using 'x'/'X' as prefix and 'p'/'P' before exponent.
607
+ | s | Converted to string using format p, then applying string formatting rule, alternate form # quotes result.
608
+ | p | Same as f format with minimum significant number of fractional digits, prec has no effect.
609
+ | dxXobBc | Converts float to integer and formats using the integer rules.
610
+
611
+ Defaults to `p`.
612
+
613
+ #### String to String
614
+
615
+ | Format | String
616
+ | ------ | ------
617
+ | s | Unquoted string, verbatim output of control chars.
618
+ | p | Programmatic representation - strings are quoted, interior quotes and control chars are escaped.
619
+ | C | Each `::` name segment capitalized, quoted if alternative flag `#` is used.
620
+ | c | Capitalized string, quoted if alternative flag `#` is used.
621
+ | d | Downcased string, quoted if alternative flag `#` is used.
622
+ | u | Upcased string, quoted if alternative flag `#` is used.
623
+ | t | Trims leading and trailing whitespace from the string, quoted if alternative flag `#` is used.
624
+
625
+ Defaults to `s` at top level and `p` inside array or hash.
626
+
627
+ #### Boolean to String
628
+
629
+ | Format | Boolean Formats
630
+ | ---- | -------------------
631
+ | t T | String 'true'/'false' or 'True'/'False', first char if alternate form is used (i.e. 't'/'f' or 'T'/'F').
632
+ | y Y | String 'yes'/'no', 'Yes'/'No', 'y'/'n' or 'Y'/'N' if alternative flag `#` is used.
633
+ | dxXobB | Numeric value 0/1 in accordance with the given format which must be valid integer format.
634
+ | eEfgGaA | Numeric value 0.0/1.0 in accordance with the given float format and flags.
635
+ | s | String 'true' / 'false'.
636
+ | p | String 'true' / 'false'.
637
+
638
+ #### Regexp to String
639
+
640
+ | Format | Regexp Formats
641
+ | ---- | --------------
642
+ | s | No delimiters, quoted if alternative flag `#` is used.
643
+ | p | Delimiters `/ /`.
644
+
645
+ #### Undef to String
646
+
647
+ | Format | Undef formats
648
+ | ------ | -------------
649
+ | s | Empty string, or quoted empty string if alternative flag `#` is used.
650
+ | p | String 'undef', or quoted '"undef"' if alternative flag `#` is used.
651
+ | n | String 'nil', or 'null' if alternative flag `#` is used.
652
+ | dxXobB | String 'NaN'.
653
+ | eEfgGaA | String 'NaN'.
654
+ | v | String 'n/a'.
655
+ | V | String 'N/A'.
656
+ | u | String 'undef', or 'undefined' if alternative `#` flag is used.
657
+
658
+ #### Default value to String
659
+
660
+ | Format | Default formats
661
+ | ------ | ---------------
662
+ | d D | String 'default' or 'Default', alternative form `#` causes value to be quoted.
663
+ | s | Same as d.
664
+ | p | Same as d.
665
+
666
+ #### Binary value to String
667
+
668
+ | Format | Default formats
669
+ | ------ | ---------------
670
+ | s | binary as unquoted UTF-8 characters (errors if byte sequence is invalid UTF-8). Alternate form escapes non ascii bytes.
671
+ | p | 'Binary("<base64strict>")'
672
+ | b | '<base64>' - base64 string with newlines inserted
673
+ | B | '<base64strict>' - base64 strict string (without newlines inserted)
674
+ | u | '<base64urlsafe>' - base64 urlsafe string
675
+ | t | 'Binary' - outputs the name of the type only
676
+ | T | 'BINARY' - output the name of the type in all caps only
677
+
678
+ * The alternate form flag `#` will quote the binary or base64 text output.
679
+ * The format `%#s` allows invalid UTF-8 characters and outputs all non ascii bytes
680
+ as hex escaped characters on the form `\\xHH` where `H` is a hex digit.
681
+ * The width and precision values are applied to the text part only in `%p` format.
682
+
683
+ #### Array & Tuple to String
684
+
685
+ | Format | Array/Tuple Formats
686
+ | ------ | -------------
687
+ | a | Formats with `[ ]` delimiters and `,`, alternate form `#` indents nested arrays/hashes.
688
+ | s | Same as a.
689
+ | p | Same as a.
690
+
691
+ See "Flags" `<[({\|` for formatting of delimiters, and "Additional parameters for containers; Array and Hash" for
692
+ more information about options.
693
+
694
+ The alternate form flag `#` will cause indentation of nested array or hash containers. If width is also set
695
+ it is taken as the maximum allowed length of a sequence of elements (not including delimiters). If this max length
696
+ is exceeded, each element will be indented.
697
+
698
+ #### Hash & Struct to String
699
+
700
+ | Format | Hash/Struct Formats
701
+ | ------ | -------------
702
+ | h | Formats with `{ }` delimiters, `,` element separator and ` => ` inner element separator unless overridden by flags.
703
+ | s | Same as h.
704
+ | p | Same as h.
705
+ | a | Converts the hash to an array of [k,v] tuples and formats it using array rule(s).
706
+
707
+ See "Flags" `<[({\|` for formatting of delimiters, and "Additional parameters for containers; Array and Hash" for
708
+ more information about options.
709
+
710
+ The alternate form flag `#` will format each hash key/value entry indented on a separate line.
711
+
712
+ #### Type to String
713
+
714
+ | Format | Array/Tuple Formats
715
+ | ------ | -------------
716
+ | s | The same as `p`, quoted if alternative flag `#` is used.
717
+ | p | Outputs the type in string form as specified by the Puppet Language.
718
+
719
+ #### Flags
720
+
721
+ | Flag | Effect
722
+ | ------ | ------
723
+ | (space) | A space instead of `+` for numeric output (`-` is shown), for containers skips delimiters.
724
+ | # | Alternate format; prefix 0x/0x, 0 (octal) and 0b/0B for binary, Floats force decimal '.'. For g/G keep trailing 0.
725
+ | + | Show sign +/- depending on value's sign, changes x, X, o, b, B format to not use 2's complement form.
726
+ | - | Left justify the value in the given width.
727
+ | 0 | Pad with 0 instead of space for widths larger than value.
728
+ | <[({\| | Defines an enclosing pair <> [] () {} or \| \| when used with a container type.
729
+
730
+ ### Conversion to Boolean
731
+
732
+ Accepts a single value as argument:
733
+
734
+ * Float 0.0 is `false`, all other float values are `true`
735
+ * Integer 0 is `false`, all other integer values are `true`
736
+ * Strings
737
+ * `true` if 'true', 'yes', 'y' (case independent compare)
738
+ * `false` if 'false', 'no', 'n' (case independent compare)
739
+ * Boolean is already boolean and is simply returned
740
+
741
+ ### Conversion to Array and Tuple
742
+
743
+ When given a single value as argument:
744
+
745
+ * A non empty `Hash` is converted to an array matching `Array[Tuple[Any,Any], 1]`.
746
+ * An empty `Hash` becomes an empty array.
747
+ * An `Array` is simply returned.
748
+ * An `Iterable[T]` is turned into an array of `T` instances.
749
+ * A `Binary` is converted to an `Array[Integer[0,255]]` of byte values
750
+
751
+
752
+ When given a second Boolean argument:
753
+
754
+ * if `true`, a value that is not already an array is returned as a one element array.
755
+ * if `false`, (the default), converts the first argument as shown above.
756
+
757
+ **Example:** Ensuring value is an array
758
+
759
+ ```puppet
760
+ $arr = Array($value, true)
761
+ ```
762
+
763
+ Conversion to a `Tuple` works exactly as conversion to an `Array`, only that the constructed array is
764
+ asserted against the given tuple type.
765
+
766
+ ### Conversion to Hash and Struct
767
+
768
+ Accepts a single value as argument:
769
+
770
+ * An empty `Array` becomes an empty `Hash`
771
+ * An `Array` matching `Array[Tuple[Any,Any], 1]` is converted to a hash where each tuple describes a key/value entry
772
+ * An `Array` with an even number of entries is interpreted as `[key1, val1, key2, val2, ...]`
773
+ * An `Iterable` is turned into an `Array` and then converted to hash as per the array rules
774
+ * A `Hash` is simply returned
775
+
776
+ Alternatively, a tree can be constructed by giving two values; an array of tuples on the form `[path, value]`
777
+ (where the `path` is the path from the root of a tree, and `value` the value at that position in the tree), and
778
+ either the option `'tree'` (do not convert arrays to hashes except the top level), or
779
+ `'hash_tree'` (convert all arrays to hashes).
780
+
781
+ The tree/hash_tree forms of Hash creation are suited for transforming the result of an iteration
782
+ using `tree_each` and subsequent filtering or mapping.
783
+
784
+ **Example:** Mapping a hash tree
785
+
786
+ Mapping an arbitrary structure in a way that keeps the structure, but where some values are replaced
787
+ can be done by using the `tree_each` function, mapping, and then constructing a new Hash from the result:
788
+
789
+ ```puppet
790
+ # A hash tree with 'water' at different locations
791
+ $h = { a => { b => { x => 'water'}}, b => { y => 'water'} }
792
+ # a helper function that turns water into wine
793
+ function make_wine($x) { if $x == 'water' { 'wine' } else { $x } }
794
+ # create a flattened tree with water turned into wine
795
+ $flat_tree = $h.tree_each.map |$entry| { [$entry[0], make_wine($entry[1])] }
796
+ # create a new Hash and log it
797
+ notice Hash($flat_tree, 'hash_tree')
798
+ ```
799
+
800
+ Would notice the hash `{a => {b => {x => wine}}, b => {y => wine}}`
801
+
802
+ Conversion to a `Struct` works exactly as conversion to a `Hash`, only that the constructed hash is
803
+ asserted against the given struct type.
804
+
805
+ ### Conversion to a Regexp
806
+
807
+ A `String` can be converted into a `Regexp`
808
+
809
+ **Example**: Converting a String into a Regexp
810
+ ```puppet
811
+ $s = '[a-z]+\.com'
812
+ $r = Regexp($s)
813
+ if('foo.com' =~ $r) {
814
+ ...
815
+ }
816
+ ```
817
+
818
+ ### Creating a SemVer
819
+
820
+ A SemVer object represents a single [Semantic Version](http://semver.org/).
821
+ It can be created from a String, individual values for its parts, or a hash specifying the value per part.
822
+ See the specification at [semver.org](http://semver.org/) for the meaning of the SemVer's parts.
823
+
824
+ The signatures are:
825
+
826
+ ```puppet
827
+ type PositiveInteger = Integer[0,default]
828
+ type SemVerQualifier = Pattern[/\A(?<part>[0-9A-Za-z-]+)(?:\.\g<part>)*\Z/]
829
+ type SemVerString = String[1]
830
+ type SemVerHash =Struct[{
831
+ major => PositiveInteger,
832
+ minor => PositiveInteger,
833
+ patch => PositiveInteger,
834
+ Optional[prerelease] => SemVerQualifier,
835
+ Optional[build] => SemVerQualifier
836
+ }]
837
+
838
+ function SemVer.new(SemVerString $str)
839
+
840
+ function SemVer.new(
841
+ PositiveInteger $major
842
+ PositiveInteger $minor
843
+ PositiveInteger $patch
844
+ Optional[SemVerQualifier] $prerelease = undef
845
+ Optional[SemVerQualifier] $build = undef
846
+ )
847
+
848
+ function SemVer.new(SemVerHash $hash_args)
849
+ ```
850
+
851
+ **Examples:** SemVer and SemVerRange usage
852
+
853
+ ```puppet
854
+ # As a type, SemVer can describe disjunct ranges which versions can be
855
+ # matched against - here the type is constructed with two
856
+ # SemVerRange objects.
857
+ #
858
+ $t = SemVer[
859
+ SemVerRange('>=1.0.0 <2.0.0'),
860
+ SemVerRange('>=3.0.0 <4.0.0')
861
+ ]
862
+ notice(SemVer('1.2.3') =~ $t) # true
863
+ notice(SemVer('2.3.4') =~ $t) # false
864
+ notice(SemVer('3.4.5') =~ $t) # true
865
+ ```
866
+
867
+ ### Creating a SemVerRange
868
+
869
+ A `SemVerRange` object represents a range of `SemVer`. It can be created from
870
+ a `String`, or from two `SemVer` instances, where either end can be given as
871
+ a literal `default` to indicate infinity. The string format of a `SemVerRange` is specified by
872
+ the [Semantic Version Range Grammar](https://github.com/npm/node-semver#ranges).
873
+
874
+ > Use of the comparator sets described in the grammar (joining with `||`) is not supported.
875
+
876
+ The signatures are:
877
+
878
+ ```puppet
879
+ type SemVerRangeString = String[1]
880
+ type SemVerRangeHash = Struct[{
881
+ min => Variant[Default, SemVer],
882
+ Optional[max] => Variant[Default, SemVer],
883
+ Optional[exclude_max] => Boolean
884
+ }]
885
+
886
+ function SemVerRange.new(
887
+ SemVerRangeString $semver_range_string
888
+ )
889
+
890
+ function SemVerRange.new(
891
+ Variant[Default,SemVer] $min
892
+ Variant[Default,SemVer] $max
893
+ Optional[Boolean] $exclude_max = undef
894
+ )
895
+
896
+ function SemVerRange.new(
897
+ SemVerRangeHash $semver_range_hash
898
+ )
899
+ ```
900
+
901
+ For examples of `SemVerRange` use, see "Creating a SemVer".
902
+
903
+ ### Creating a Binary
904
+
905
+ A `Binary` object represents a sequence of bytes and it can be created from a String in Base64 format,
906
+ an Array containing byte values. A Binary can also be created from a Hash containing the value to convert to
907
+ a `Binary`.
908
+
909
+ The signatures are:
910
+
911
+ ```puppet
912
+ type ByteInteger = Integer[0,255]
913
+ type Base64Format = Enum["%b", "%u", "%B", "%s"]
914
+ type StringHash = Struct[{value => String, "format" => Optional[Base64Format]}]
915
+ type ArrayHash = Struct[{value => Array[ByteInteger]}]
916
+ type BinaryArgsHash = Variant[StringHash, ArrayHash]
917
+
918
+ function Binary.new(
919
+ String $base64_str,
920
+ Optional[Base64Format] $format
921
+ )
922
+
923
+ function Binary.new(
924
+ Array[ByteInteger] $byte_array
925
+ }
926
+
927
+ # Same as for String, or for Array, but where arguments are given in a Hash.
928
+ function Binary.new(BinaryArgsHash $hash_args)
929
+ ```
930
+
931
+ The formats have the following meaning:
932
+
933
+ | format | explanation |
934
+ | ---- | ---- |
935
+ | B | The data is in base64 strict encoding
936
+ | u | The data is in URL safe base64 encoding
937
+ | b | The data is in base64 encoding, padding as required by base64 strict, is added by default
938
+ | s | The data is a puppet string. The string must be valid UTF-8, or convertible to UTF-8 or an error is raised.
939
+ | r | (Ruby Raw) the byte sequence in the given string is used verbatim irrespective of possible encoding errors
940
+
941
+ * The default format is `%B`.
942
+ * Note that the format `%r` should be used sparingly, or not at all. It exists for backwards compatibility reasons when someone receiving
943
+ 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.
944
+
945
+ **Examples:** Creating a Binary
946
+
947
+ ```puppet
948
+ # create the binary content "abc"
949
+ $a = Binary('YWJj')
950
+
951
+ # create the binary content from content in a module's file
952
+ $b = binary_file('mymodule/mypicture.jpg')
953
+ ```
954
+
955
+ * Since 4.5.0
956
+ * Binary type since 4.8.0
957
+
958
+ Creating an instance of a `Type` using the `Init` type.
959
+ -------
960
+
961
+ The type `Init[T]` describes a value that can be used when instantiating a type. When used as the first argument in a call to `new`, it
962
+ will dispatch the call to its contained type and optionally augment the parameter list with additional arguments.
963
+
964
+ **Example:** Creating an instance of Integer using Init[Integer]
965
+
966
+ ```puppet
967
+ # The following declaration
968
+ $x = Init[Integer].new('128')
969
+ # is exactly the same as
970
+ $x = Integer.new('128')
971
+ ```
972
+
973
+ or, with base 16 and using implicit new
974
+
975
+ ```puppet
976
+ # The following declaration
977
+ $x = Init[Integer,16]('80')
978
+ # is exactly the same as
979
+ $x = Integer('80', 16)
980
+ ```
981
+
982
+ **Example:** Creating an instance of String using a predefined format
983
+
984
+ ```puppet
985
+ $fmt = Init[String,'%#x']
986
+ notice($fmt(256)) # will notice '0x100'
987
+ ```
988
+
989
+ DOC
990
+ ) do |_args|
990
991
  Puppet::Parser::Functions::Error.is4x('new')
991
992
  end
992
993