114 lines
3.4 KiB
ReStructuredText
114 lines
3.4 KiB
ReStructuredText
.. _redefine:
|
|
|
|
Redefine a variable
|
|
===================
|
|
|
|
We have already introduced the concept of :ref:`variable mutability <variable_mutability>`.
|
|
To summarize, an :term:`integrator` allows the :ref:`structured data <structured_data>` to evolve at any time.
|
|
|
|
.. glossary::
|
|
|
|
redefine
|
|
|
|
A redefine is a redefinition of all or part of the parameters of a variable as it was previously defined.
|
|
|
|
.. seealso::
|
|
|
|
See the tutorial with a real world sample :ref:`redefine <tutorial_redefine>`.
|
|
|
|
Explicit redefine
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
The redefinition is explicit.
|
|
This means that if an :term:`integrator` defines the same tree twice for two variables, Rougail will consider that there is a naming conflict.
|
|
|
|
To illustrate, we could create two :term:`structure files <structure file>`:
|
|
|
|
.. code-block:: yaml
|
|
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
my_variable: # A description
|
|
...
|
|
|
|
.. code-block:: yaml
|
|
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
my_variable: # A redefined description
|
|
...
|
|
|
|
And the name conflict is detected:
|
|
|
|
.. code-block:: bash
|
|
:class: terminal
|
|
|
|
$ rougail -m variable.yml redefine.yml
|
|
ERROR: variable "my_variable" define multiple time in "variable.yml" and "redefine.yml"
|
|
|
|
So we have to explicit redefine a variable like this:
|
|
|
|
.. code-block:: yaml
|
|
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
my_variable:
|
|
redefine: true
|
|
description: A redefined description
|
|
...
|
|
|
|
Now we can see that the redefinition is correct:
|
|
|
|
.. code-block:: bash
|
|
:class: terminal
|
|
|
|
$rougail -m variable.yml redefine.yml -o doc
|
|
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┓
|
|
┃ Variable ┃ Description ┃
|
|
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━┩
|
|
│ my_variable │ A redefined description. │
|
|
│ string mandatory │ │
|
|
└─────────────────────┴──────────────────────────┘
|
|
|
|
The new description has been taken into account.
|
|
|
|
Unify
|
|
~~~~~
|
|
|
|
When redefining a variable, we define the list of parameters that we wish to redefine.
|
|
|
|
In other words the variable is unify (combine) from multiple variables declarations.
|
|
|
|
The old parameters that were present before the redefinition are still present.
|
|
|
|
If we modify the `redefine.yml` :term:`structure file`:
|
|
|
|
.. code-block:: yaml
|
|
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
my_variable:
|
|
redefine: true
|
|
type: integer
|
|
...
|
|
|
|
.. code-block:: bash
|
|
:class: terminal
|
|
|
|
$ rougail -m variable.yml redefine.yml -o doc
|
|
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
|
|
┃ Variable ┃ Description ┃
|
|
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
|
|
│ my_variable │ A description. │
|
|
│ integer mandatory │ │
|
|
└──────────────────────┴────────────────┘
|
|
|
|
Here we can see that the variable has the original description, but the new type.
|