DOCUMENTATION:
  name: to_nice_yaml
  author: core team
  version_added: 'historical'
  short_description: Convert variable to YAML string
  description:
    - Converts an Ansible variable into a YAML string representation.
    - This filter functions as a wrapper to the L(Python PyYAML library, https://pypi.org/project/PyYAML/)'s C(yaml.dump) function.
    - Ansible internally auto-converts YAML strings into variable structures so this plugin is used to force it into a YAML string.
  positional: _input
  options:
    _input:
      description: A variable or expression that returns a data structure.
      type: raw
      required: true
    indent:
      description: Number of spaces to indent Python structures, mainly used for display to humans.
      type: integer
    sort_keys:
      description: Affects sorting of dictionary keys.
      default: True
      type: bool
    default_style:
      description:
        - Indicates the style of the scalar.
      choices:
        - ''
        - "'"
        - '"'
        - '|'
        - '>'
      type: string
    canonical:
      description:
        - If set to V(True), export tag type to the output.
      type: bool
    width:
      description: Set the preferred line width.
      type: int
    line_break:
      description: Specify the line break.
      type: string
    encoding:
      description: Specify the output encoding.
      type: string
    explicit_start:
      description: If set to V(True), adds an explicit start using "---".
      type: bool
    explicit_end:
      description: If set to V(True), adds an explicit end using "...".
      type: bool
  notes:
    - More options may be available, see L(PyYAML documentation, https://pyyaml.org/wiki/PyYAMLDocumentation) for details.
    - 'These parameters to C(yaml.dump) will be ignored, as they are overridden internally: I(default_flow_style), I(allow_unicode).'

EXAMPLES: |
  # dump variable in a template to create a YAML document
  {{ github_workflow | to_nice_yaml }}

RETURN:
  _value:
    description: The YAML serialized string representing the variable structure inputted.
    type: string
