diff --git a/REFERENCE.md b/REFERENCE.md
index 42b492ae7..514edacae 100644
--- a/REFERENCE.md
+++ b/REFERENCE.md
@@ -178,12 +178,12 @@ in a hash.
* [`swapcase`](#swapcase): This function will swap the existing case of a string.
* [`time`](#time): This function will return the current time since epoch as an integer.
* [`to_bytes`](#to_bytes): Converts the argument into bytes, for example 4 kB becomes 4096.
-* [`to_json`](#to_json): }
+* [`to_json`](#to_json): Convert a data structure and output to JSON
* [`to_json_pretty`](#to_json_pretty): Convert data structure and output to pretty JSON
* [`to_python`](#to_python): Convert an object into a String containing its Python representation
* [`to_ruby`](#to_ruby): Convert an object into a String containing its Ruby representation
* [`to_toml`](#to_toml): Convert a data structure and output to TOML.
-* [`to_yaml`](#to_yaml): }
+* [`to_yaml`](#to_yaml): Convert a data structure and output it as YAML
* [`try_get_value`](#try_get_value)
* [`type`](#type): **DEPRECATED:** This function will cease to function on Puppet 4;
* [`type3x`](#type3x): **DEPRECATED:** This function will be removed when Puppet 3 support is dropped; please migrate to the new parser's typing system.
@@ -4569,19 +4569,41 @@ Returns: `Any` converted value into bytes
Type: Ruby 4.x API
+Convert a data structure and output to JSON
+
+#### Examples
+
+##### Output JSON to a file
+
+```puppet
+file { '/tmp/my.json':
+ ensure => file,
+ content => to_json($myhash),
}
+```
#### `to_json(Any $data)`
-}
+The to_json function.
+
+Returns: `String` Converted data to JSON
-Returns: `Any` converted data to json
+##### Examples
+
+###### Output JSON to a file
+
+```puppet
+file { '/tmp/my.json':
+ ensure => file,
+ content => to_json($myhash),
+}
+```
##### `data`
Data type: `Any`
-data structure which needs to be converted into JSON
+Data structure which needs to be converted into JSON
### `to_json_pretty`
@@ -4839,25 +4861,65 @@ Data structure which needs to be converted into TOML
Type: Ruby 4.x API
+Convert a data structure and output it as YAML
+
+#### Examples
+
+##### Output YAML to a file
+
+```puppet
+file { '/tmp/my.yaml':
+ ensure => file,
+ content => to_yaml($myhash),
}
+```
+
+##### Use options to control the output format
+
+```puppet
+file { '/tmp/my.yaml':
+ ensure => file,
+ content => to_yaml($myhash, {indentation => 4})
+}
+```
#### `to_yaml(Any $data, Optional[Hash] $options)`
+The to_yaml function.
+
+Returns: `String` The YAML document
+
+##### Examples
+
+###### Output YAML to a file
+
+```puppet
+file { '/tmp/my.yaml':
+ ensure => file,
+ content => to_yaml($myhash),
}
+```
-Returns: `String`
+###### Use options to control the output format
+
+```puppet
+file { '/tmp/my.yaml':
+ ensure => file,
+ content => to_yaml($myhash, {indentation => 4})
+}
+```
##### `data`
Data type: `Any`
-
+The data you want to convert to YAML
##### `options`
Data type: `Optional[Hash]`
-
+A hash of options that will be passed to Ruby's Psych library. Note, this could change between Puppet versions, but at time of writing these are `line_width`, `indentation`, and `canonical`.
### `try_get_value`
diff --git a/lib/puppet/functions/to_json.rb b/lib/puppet/functions/to_json.rb
index 7ff605d21..5f3be4464 100644
--- a/lib/puppet/functions/to_json.rb
+++ b/lib/puppet/functions/to_json.rb
@@ -4,17 +4,16 @@
# @summary
# Convert a data structure and output to JSON
#
-# @example how to output JSON
-# # output json to a file
-# file { '/tmp/my.json':
-# ensure => file,
-# content => to_json($myhash),
-# }
+# @example Output JSON to a file
+# file { '/tmp/my.json':
+# ensure => file,
+# content => to_json($myhash),
+# }
#
Puppet::Functions.create_function(:to_json) do
# @param data
- # data structure which needs to be converted into JSON
- # @return converted data to json
+ # Data structure which needs to be converted into JSON
+ # @return [String] Converted data to JSON
dispatch :to_json do
param 'Any', :data
end
diff --git a/lib/puppet/functions/to_yaml.rb b/lib/puppet/functions/to_yaml.rb
index 781ea3334..e7cc9bc5f 100644
--- a/lib/puppet/functions/to_yaml.rb
+++ b/lib/puppet/functions/to_yaml.rb
@@ -4,28 +4,29 @@
# @summary
# Convert a data structure and output it as YAML
#
-# @example How to output YAML
-# # output yaml to a file
-# file { '/tmp/my.yaml':
-# ensure => file,
-# content => to_yaml($myhash),
-# }
-# @example Use options control the output format
+# @example Output YAML to a file
# file { '/tmp/my.yaml':
# ensure => file,
-# content => to_yaml($myhash, {indentation: 4})
+# content => to_yaml($myhash),
+# }
+# @example Use options to control the output format
+# file { '/tmp/my.yaml':
+# ensure => file,
+# content => to_yaml($myhash, {indentation => 4})
# }
Puppet::Functions.create_function(:to_yaml) do
# @param data
+ # The data you want to convert to YAML
# @param options
+ # A hash of options that will be passed to Ruby's Psych library. Note, this could change between Puppet versions, but at time of writing these are `line_width`, `indentation`, and `canonical`.
#
- # @return [String]
+ # @return [String] The YAML document
dispatch :to_yaml do
param 'Any', :data
optional_param 'Hash', :options
end
def to_yaml(data, options = {})
- data.to_yaml(options)
+ data.to_yaml(options.transform_keys(&:to_sym))
end
end
diff --git a/spec/functions/to_yaml_spec.rb b/spec/functions/to_yaml_spec.rb
index 98985c404..de0e392eb 100644
--- a/spec/functions/to_yaml_spec.rb
+++ b/spec/functions/to_yaml_spec.rb
@@ -20,5 +20,5 @@
it { is_expected.to run.with_params('‰').and_return("--- \"‰\"\n") }
it { is_expected.to run.with_params('∇').and_return("--- \"∇\"\n") }
- it { is_expected.to run.with_params({ 'foo' => { 'bar' => true, 'baz' => false } }, indentation: 4).and_return("---\nfoo:\n bar: true\n baz: false\n") }
+ it { is_expected.to run.with_params({ 'foo' => { 'bar' => true, 'baz' => false } }, 'indentation' => 4).and_return("---\nfoo:\n bar: true\n baz: false\n") }
end