rougail/docs/library/output.rst

Display the result
==================

After construct a configuration, loads user datas, you can choose this configuration in different output format.

First of create, let's create a structural file like this:

.. code-block:: yaml
   :caption: the :file:`dist/00-base.yml` file content

    %YAML 1.2
    ---
    version: 1.1

    my_variable: my value   # My first variable

    my_boolean_variable: true  # My boolean variable

    my_integer_variable: 1  # My integer variable

    my_secret_variable:
      description: My secret variable
      type: secret
      default: MyVeryStrongPassword
    ...

Display in a console
--------------------

We can display configuration directly in the console:

.. code-block:: python
    :caption: the :file:`script.py` file content

    from rougail import Rougail, RougailConfig
    from rougail.output_console import RougailOutputConsole

    RougailConfig["main_namespace"] = None
    RougailConfig["main_structural_directories"] = ["dist/"]
    RougailConfig["step.output"] = "console"
    rougail = Rougail()
    config = rougail.run()
    config.property.read_only()
    RougailOutputConsole(config).print()

.. FIXME display console!

console.key_is_description
''''''''''''''''''''''''''

By default, the key is the variable description, if you prefer have only the path:

.. code-block:: python
    :caption: the :file:`script.py` file content

    from rougail import Rougail, RougailConfig
    from rougail.output_json import RougailOutputJson

    RougailConfig["main_namespace"] = None
    RougailConfig["main_structural_directories"] = ["dist/"]
    RougailConfig["step.output"] = "console"
    rougail = Rougail()
    config = rougail.run()
    config.property.read_only()
    RougailOutputJson(config).print()


.. FIXME display console!

console.show_secrets
''''''''''''''''''''

Secrets are remplace by "*******", to display real secrets:

.. code-block:: python
    :caption: the :file:`script.py` file content

    from rougail import Rougail, RougailConfig
    from rougail.output_console import RougailOutputConsole

    RougailConfig["main_namespace"] = None
    RougailConfig["main_structural_directories"] = ["dist/"]
    RougailConfig["step.output"] = "console"
    RougailConfig["console.show_secrets"] = True
    rougail = Rougail()
    config = rougail.run()
    config.property.read_only()
    RougailOutputConsole(config).print()

.. FIXME display console!

console.mandatory
'''''''''''''''''

Before display configuration, mandatories variables are check. If you don't want, add the parameter `console.mandatory` to False:

.. code-block:: python
    :caption: the :file:`script.py` file content

    from rougail import Rougail, RougailConfig
    from rougail.output_console import RougailOutputConsole

    RougailConfig["main_namespace"] = None
    RougailConfig["main_structural_directories"] = ["dist/"]
    RougailConfig["step.output"] = "console"
    RougailConfig["console.mandatory"] = False
    rougail = Rougail()
    config = rougail.run()
    config.property.read_only()
    RougailOutputConsole(config).print()

.. FIXME display console!

JSON
----

Your script can return a JSON object:

.. code-block:: python
    :caption: the :file:`script.py` file content

    from rougail import Rougail, RougailConfig
    from rougail.output_console import RougailOutputConsole

    RougailConfig["main_namespace"] = None
    RougailConfig["main_structural_directories"] = ["dist/"]
    RougailConfig["step.output"] = "json"
    rougail = Rougail()
    config = rougail.run()
    config.property.read_only()
    RougailOutputConsole(config).print()

Let's try this script:

.. code-block:: bash

    $ python script.py
    {
      "my_variable": "my value",
      "my_boolean_variable": true,
      "my_integer_variable": 1,
      "my_secret_variable": "MyVeryStrongPassword"
    }

ANSIBLE
-------

It's possible to use Ansible has a output format.

The goal is here to use Ansible has a dynamic user's inventories structure manage by Rougail.

This output needs an extra namespace, named, by default, "hosts". This namespace define your hosts and groups.

Let's create a single group "my_group" with one host "group1.net":

.. code-block:: yaml
   :caption: the :file:`hosts/00-hosts.yml` file content

    %YAML 1.2
    ---
    version: 1.1

    hostnames:

      my_group:

        hosts:
          type: domainname
          default:
            - group1.net
    ...

Now we can generate Ansible inventory:

.. code-block:: python
    :caption: the :file:`script.py` file content

    #!/bin/env python
    from rougail import Rougail, RougailConfig
    from rougail.output_ansible import RougailOutputAnsible

    RougailConfig["main_namespace"] = "main"
    RougailConfig["main_structural_directories"] = ["dist/"]
    RougailConfig['extra_namespaces']['hosts'] = ['hosts/']
    RougailConfig["step.output"] = "ansible"
    rougail = Rougail()
    config = rougail.run()
    config.property.read_only()
    RougailOutputAnsible(config).print()

We will retrieved all ours variables associate to this group with all variables inside the namespace `main`:

.. code-block:: bash

    $ python script.py 
    {
      "_meta": {
        "hostvars": {
          "group1.net": {
            "ansible_host": "group1.net",
            "main": {
              "my_variable": "my value",
              "my_boolean_variable": true,
              "my_integer_variable": 1,
              "my_secret_variable": "MyVeryStrongPassword"
            }
          }
        }
      },
      "my_group": {
        "hosts": [
          "group1.net"
        ]
      }
    }

We can now use our script as an inventory source in Ansible:

.. code-block:: bash

   $ chmod +x script.py
   $ ansible-inventory -i script.py --list
    {
        "_meta": {
            "hostvars": {
                "group1.net": {
                    "ansible_host": "group1.net",
                    "main": {
                        "my_boolean_variable": true,
                        "my_integer_variable": 1,
                        "my_secret_variable": "MyVeryStrongPassword",
                        "my_variable": "my value"
                    }
                }
            }
        },
        "all": {
            "children": [
                "ungrouped",
                "my_group"
            ]
        },
        "my_group": {
            "hosts": [
                "group1.net"
            ]
        }
    }

DOC
---

We can generate the documentation of all the Rougail variable:

.. code-block:: python
    :caption: the :file:`script.py` file content

    from rougail import Rougail, RougailConfig
    from rougail.output_doc import RougailOutputDoc

    RougailConfig["main_namespace"] = "main"
    RougailConfig["main_structural_directories"] = ["dist/"]
    RougailConfig["step.output"] = "doc"
    rougail = Rougail()
    config = rougail.run()
    config.property.read_only()
    RougailOutputDoc(config).print()

.. FIXME : display