Redefine a variable

We have already introduced the concept of variable mutability. To summarize, an integrator allows the structured data to evolve at any time.

redefine: A redefine is a redefinition of all or part of the parameters of a variable or a family as it was previously defined.

Note

Adding a variable to a family is not considered redefining the family. This is implicitly permitted. Redefining a family requires modifying one or more of its parameters.

Explicit redefine

The redefinition is explicit. This means that if an integrator defines the same tree twice for two variables, Rougail will consider that there is a naming conflict.

To illustrate, we could create two structure files:

%YAML 1.2
---
version: 1.1

my_variable:  # A description
...

%YAML 1.2
---
version: 1.1

my_variable:  # A redefined description
...

And the name conflict is detected:

$ 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:

%YAML 1.2
---
version: 1.1

my_variable:
  redefine: true
  description: A redefined description
...

Now we can see that the redefinition is correct:

 $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 structure file:

%YAML 1.2
---
version: 1.1

my_variable:
  redefine: true
  type: integer
...

$ 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.

Exception

We cannot change a parameter for a variable or a family implicitly.

This is always true, unless you want to change the default value of a child of a custom type in a family.