Merge pull request #1231 from alexjfisher/fix_to_yaml

Fix `to_yaml` `options` parameter

Author: ekohl

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
 
 ### <a name="to_json_pretty"></a>`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`.
 
 ### <a name="try_get_value"></a>`try_get_value`
 

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

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

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