rougail/docs/library/parse.rst

Retrieve all variables and families
===================================

Rougail returns a :term:`Tiramisu` config.

Let's retrieve our variables and families to manager this.

First of all, create our structural file:

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

    %YAML 1.2
    ---
    version: 1.1

    my_variable:  # a simple variable
      - value1
      - value2

    a_family:  # a simple family

      my_variable: my_value  # a simple variable inside the family

    a_dyn_family_{{ identifier }}:
      description: a dynamic family for "{{ identifier }}"
      dynamic:
        variable: _.my_variable

      a_leadership:
        description: a leader family

        a_leader:  # a leader variable
        a_follower:  # a follower variable
    ...

Walk through our config
-------------------------

Create our first script to walk through our config:

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

    from rougail import Rougail, RougailConfig

    RougailConfig['main_structural_directories'] = ["dist/"]
    rougail = Rougail()
    config = rougail.run()

    def walk(config):
        for option in config:
            print(option.description())
            if option.isoptiondescription():
                walk(option)

    if __name__ == '__main__':
        walk(config)

Let's execute `script.py`:

.. code-block:: bash

    $ python3 script.py
    rougail
    rougail.my_variable (a simple variable)
    rougail.a_family (a simple family)
    rougail.a_family.my_variable (a simple variable inside the family)
    rougail.a_dyn_family_value1 (a dynamic family for "value1")
    rougail.a_dyn_family_value1.a_leadership (a leader family)
    rougail.a_dyn_family_value1.a_leadership.a_leader (a leader variable)
    rougail.a_dyn_family_value1.a_leadership.a_follower (a follower variable)
    rougail.a_dyn_family_value2 (a dynamic family for "value2")
    rougail.a_dyn_family_value2.a_leadership (a leader family)
    rougail.a_dyn_family_value2.a_leadership.a_leader (a leader variable)
    rougail.a_dyn_family_value2.a_leadership.a_follower (a follower variable)

We retrieve alls description of variables and families.

Let us distinguish the variables of the families
------------------------------------------------

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

    from rougail import Rougail, RougailConfig

    RougailConfig['main_structural_directories'] = ["dist/"]
    rougail = Rougail()
    config = rougail.run()

    def walk(config, level=0):
        for option in config:
            if option.isoptiondescription():
                typ = "family"
            else:
                typ = "variable"
            prefix = "  " * level
            print(f"{prefix}{typ}: {option.description()}")
            if option.isoptiondescription():
                walk(option, level + 1)

    if __name__ == '__main__':
        walk(config)

Let's execute `script.py`:

.. code-block:: bash

    $ python3 script.py
    family: rougail
      variable: rougail.my_variable (a simple variable)
      family: rougail.a_family (a simple family)
        variable: rougail.a_family.my_variable (a simple variable inside the family)
      family: rougail.a_dyn_family_value1 (a dynamic family for "value1")
        family: rougail.a_dyn_family_value1.a_leadership (a leader family)
          variable: rougail.a_dyn_family_value1.a_leadership.a_leader (a leader variable)
          variable: rougail.a_dyn_family_value1.a_leadership.a_follower (a follower variable)
      family: rougail.a_dyn_family_value2 (a dynamic family for "value2")
        family: rougail.a_dyn_family_value2.a_leadership (a leader family)
          variable: rougail.a_dyn_family_value2.a_leadership.a_leader (a leader variable)
          variable: rougail.a_dyn_family_value2.a_leadership.a_follower (a follower variable)

Or if we want more precision:

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

    from rougail import Rougail, RougailConfig
    
    RougailConfig['main_structural_directories'] = ["dist/"]
    rougail = Rougail()
    config = rougail.run()
    
    def walk(config, level=0):
        for option in config:
            if option.isoptiondescription():
                if option.isleadership():
                    typ = "leadership"
                elif option.isdynamic():
                    typ = "dynamic family"
                else:
                    typ = "family"
            else:
                if option.isleader():
                    typ = "leader"
                elif option.isfollower():
                    typ = "follower"
                else:
                    typ = "option"
                if option.isdynamic():
                    typ = f"dynamic {typ}"
            prefix = "  " * level
            print(f"{prefix}{typ}: {option.description()}")
            if option.isoptiondescription():
                walk(option, level + 1)
    
    if __name__ == '__main__':
        walk(config)

Let's execute `script.py`:

.. code-block:: bash

    family: rougail
      option: rougail.my_variable (a simple variable)
      family: rougail.a_family (a simple family)
        option: rougail.a_family.my_variable (a simple variable inside the family)
      dynamic family: rougail.a_dyn_family_value1 (a dynamic family for "value1")
        dynamic family: rougail.a_dyn_family_value1.a_leadership (a leader family)
          dynamic option: rougail.a_dyn_family_value1.a_leadership.a_leader (a leader variable)
          dynamic option: rougail.a_dyn_family_value1.a_leadership.a_follower (a follower variable)
      dynamic family: rougail.a_dyn_family_value2 (a dynamic family for "value2")
        dynamic family: rougail.a_dyn_family_value2.a_leadership (a leader family)
          dynamic option: rougail.a_dyn_family_value2.a_leadership.a_leader (a leader variable)
          dynamic option: rougail.a_dyn_family_value2.a_leadership.a_follower (a follower variable)

Get variable values
-------------------

If we want to walk to get variables and their values:

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

    from rougail import Rougail, RougailConfig

    RougailConfig['main_structural_directories'] = ["dist/"]
    rougail = Rougail()
    config = rougail.run()

    def walk(config):
        for option in config:
            if option.isoptiondescription():
                walk(option)
            else:
                print(f"{option.description()}: {option.value.get()}")

    if __name__ == '__main__':
        walk(config)

Let's execute `script.py`:

.. code-block:: bash

    rougail.my_variable (a simple variable): ['value1', 'value2']
    rougail.a_family.my_variable (a simple variable inside the family): my_value
    rougail.a_dyn_family_value1.a_leadership.a_leader (a leader variable): None
    rougail.a_dyn_family_value1.a_leadership.a_follower (a follower variable): None
    rougail.a_dyn_family_value2.a_leadership.a_leader (a leader variable): None
    rougail.a_dyn_family_value2.a_leadership.a_follower (a follower variable): None

Modify variable values
----------------------

Some variables are mandatories but hasn't value. Here we set alls values:

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

    from rougail import Rougail, RougailConfig
    RougailConfig['main_structural_directories'] = ["dist/"]
    rougail = Rougail()
    config = rougail.run()


    def walk(config):
        for option in config:
            if option.isoptiondescription():
                walk(option)
            else:
                print(f"{option.description()}: {option.value.get()}")

    if __name__ == '__main__':
        print("Mandatories variables without value:")
        print(config.value.mandatory())
        config.value.set("rougail.my_variable", ["value 5", "value 6"])
        config.value.set("rougail.a_dyn_family_value_5.a_leadership.a_leader", "value 1")
        config.value.set("rougail.a_dyn_family_value_5.a_leadership.a_follower", "value 2")
        config.value.set("rougail.a_dyn_family_value_6.a_leadership.a_leader", "value 3")
        config.value.set("rougail.a_dyn_family_value_6.a_leadership.a_follower", "value 4")
        print("Mandatories variables without value:")
        print(config.value.mandatory())
        walk(config)


Let's execute `script.py`:

.. code-block:: bash

    Mandatories variables without value:
    [<TiramisuOption path="rougail.a_dyn_family_value1.a_leadership.a_leader">, <TiramisuOption path="rougail.a_dyn_family_value1.a_leadership.a_follower">, <TiramisuOption path="rougail.a_dyn_family_value2.a_leadership.a_leader">, <TiramisuOption path="rougail.a_dyn_family_value2.a_leadership.a_follower">]
    Mandatories variables without value:
    []
    rougail.my_variable (a simple variable): ['value 5', 'value 6']
    rougail.a_family.my_variable (a simple variable inside the family): my_value
    rougail.a_dyn_family_value_5.a_leadership.a_leader (a leader variable): value 1
    rougail.a_dyn_family_value_5.a_leadership.a_follower (a follower variable): value 2
    rougail.a_dyn_family_value_6.a_leadership.a_leader (a leader variable): value 3
    rougail.a_dyn_family_value_6.a_leadership.a_follower (a follower variable): value 4