The variables

Synopsis

variable: A variable is an abstract black box (container) paired with an associated symbolic name, most often an option configuration, which contains some defined or undefined data setting referred to as a value.
value: A value is a variable’s setting. Variable can have a default value, that is a setting defined in the structure file, or no value at all, then the value needs to be defined later by the operator.

Discussion

The variable is, by definition, strongly typed. Rougail uses static type definition and even type inference. Indeed, the constistency handling system heavyly relies on the type system definition. Variables may only be able to store a specified data type. OK, variables are the containers for storing the values. It has something to do with typing.

But consitency handling system is is not just about strong typing. It is more than that.

Names

It is with its name that we will be able to interact with the variable.

The name of a variable must be chosen carefully. It is the path that will allow users to retrieve their defined values. An obscure name will cause confusion.

By design, you cannot use just any character to name your variable.

The regular expression that validates our variable and family naming policy is:

re.compile(r"^[a-z0-9_]*$")

You can see that it is mandatory to only use lowercase ASCII letters, numbers and the "_" (undescore) character. The snake case typographic convention is therefore used.

Attention

The name must not starts with _ character.

Parameters

Parameter

Comments

description

string

Description of the variable.

User information to understand the usefulness of the variable.

See also

tutorial with a real world sample description parameter

help

string

Additional help associated with the variable.

See also

tutorial with a real world sample help parameter

mode

string

Variable’s mode.

The mode is a way of classifying the importance, the level of expertise required, or the access rights to a variable.

This parameter allows you to define the variable mode.

Attention

Mode is not configured by default. You have to define mode level before use this parameter.

Default value: The default mode of a variable is the mode of the parent family, but there is special cases:

a variable with an automatically modified value or an automatic read-only variable is by default in the smaller mode
if the variable is not in a family, the variable will have a medium mode by default
a mandatory variable without default value (calculate or not) will have the smaller mode

See also

tutorial with a real world sample mode parameter

tags

list of strings

A tag allows you to specialize a variable.

A tag can have several functions:

Additional information in the documentation
Variable exclusion
Variable selection
and so on

examples

list

List of examples to illustrate possible values for a variable

See also

tutorial with a real world sample examples parameter

test

list

The test parameter is a special parameter that allows structure file designers to influence a test robot by specifying useful values to test.

Concretely, the content of this parameter is recorded in the information parameter of the corresponding Tiramisu option object.

type

string

Type of the variable.

See the list of available type below.

See also

tutorial with a real world sample type parameter

params

object

Parameters to adjust type validation of the variable.

See the list of available parameters for each type below.

See also

tutorial with a real world sample params parameter

multi

boolean

The value of the variable is a list.

Default value: mostly false, but there is special cases:

the default value is a list
a variable with a variable multiple has default value

It possible to adjust multi parameters with params:

multi_length: number of expected values for a multiple variable
multi_min_length: maximum number of expected values for a multiple variable
multi_max_length: minimum number of expected values for a minimum variable

See also

tutorial with a real world sample multi parameter

validators

list

Value validators.

The value of the variable will be considered invalid if the Jinja template return an error.

See also

tutorial with a real world sample validators parameter

default

Default value(s) of the variable.

This value is typed, you must correctly fill out the YAML file to avoid defining a value with an incorrect type. For example, a integer must be a digit type, a multiple variable must be a list type, …

For a non leading multiple variable, the first value defined in the list will also be the default value proposed if a new value is added to this variable.

See also

tutorial with a real world sample default parameter

secret_manager

The variable use a secret manager to get value .. todo:: document it

auto_save

boolean

Variable with automatically modified value.

A variable with automatically modified value is a variable whose value will be considered as modified (that is, it is no longer the variable’s default value).

For example, if the value of this variable comes from a calculation, the value will no longer be recalculated.

These variables are usually required variables. In fact, these variables are only automatically modified if they have a value.

Default value: false

See also

tutorial with a real world sample auto_save parameter

mandatory

boolean or calculation

Mandatory variable.

Variable whose value is required.

For a multiple variable, this means that the list shall not be empty (means null (None) or empty list for a i:term:multiple <multi>).

Default value: true

See also

tutorial with a real world sample mandatory parameter

empty

boolean or calculation

The value null (None) is not allowed in multiple variable.

The mandatory control only if the length multiple variable is not 0. But the null value is not allowed. With empty parameter we can allowed it.

If null is an appropriate value, set empty: false.

Default value: true

unique

boolean

The multiple variable accepts the same value several times.

If unique is set to false, a multiple variable only accepts the same value once in the list.

Default value: false

hidden

boolean or calculation

Invisible variable.

Enables us to hide a variable.

This means that the variable will no longer be visible in read-write mode, but only for calculations or in read-only mode.

When a variable is made invisible, the user will not be able to modify its value; if he has already succeeded in modifying it, this value will not be taken into account.

Default value: false

See also

tutorial with a real world sample hidden parameter (the tutorial focuses on family, but the principle is the same for a variable)

disabled

boolean or calculation

Disabled variable.

Allows us to deactivate a variable.

This means that the variable will no longer be visible to the user but also to a calculation.

Default value: false

See also

tutorial with a real world sample disabled parameter (the tutorial focuses on family, but the principle is the same for a variable)

frozen

boolean or calculation

Read only variable.

Enables us to have an immutable variable’s value.

This means that the variable will be visible but user will not allowed to change the value.

Default value: false

redefine

boolean

It is possible to define a variable in one structure file and change its behavior in a second structure file. In this case you must explicitly redefine the variable.

Default value: false

exists

boolean

This parameter does two things:

creates a variable if it does not exist in another structure file (otherwise do nothing), in this case the value of the parameter must be true

in conjunction with the redefine parameter set to true, only modifies the behavior if it is pre-existing, in which case the parameter’s value must be false.

Default value: null

choices

calculation or a list of calculation or data

Available choices.

Important

This parameter is only available for variable with choice type.

regexp

string

Validation with a regular expressions.

Important

This parameter is only available for variable with regexp type.

Short-hand declaration

Short-hand declaration is a way to declare a variable in a condenced number of line.

To create a variable, just add a key with it’s name:

%YAML 1.2
---
version: 1.1

my_variable:
...

You can add a default value:

%YAML 1.2
---
version: 1.1

my_variable: my_value
...

Or a multi default value:

%YAML 1.2
---
version: 1.1

my_variable:
  - my_value_1
  - my_value_2
...

By default, the description of the variable is the variable name. It’s a good practice to describe a variable. Just add comment in same line of name, this comment is used as description:

%YAML 1.2
---
version: 1.1

my_variable: my_value  # This is a great variable
...

But in short-hand notation, you can only define variable name, default value, multi and description.

Attention

Any other parameters will create extra variables or families

Variable’s types

A variable always has a type. The system is strongly typed.

Depending on the definition of the variable type, the defined variable will accept values of the associated type.

Primitive Types

Value	Comments	Parameters	Samples
string	character string (default type)		example “1” “true”
integer	a integer	`min_integer`: minimum integer allowed (unlimited by default) `max_integer`: maximum integer allowed (unlimited by default)	42
float	a floating number		1.42
boolean	A boolean, if no value is defined the default value of this variable will be `true`, the variable will also be mandatory by default See also tutorial with a real world sample boolean type variable		`true` `false`

Specialized type

Value	Comments	Parameters	Samples
secret	a secret (like a password, a private key, etc.) See also tutorial with a real world sample secret type variable	`min_len`: minimum characters length for the secret (unlimited by default) `max_len`: maximum characters length for the secret (unlimited by default) `forbidden_char`: forbidden characters (no character default)	`hO_'hi`
mail	a mail address		test@rougail.example
unix_filename	a file name in the Unix meaning	`allow_relative`: this filename could be a relative path (`false` by default) `test_existence`: this file must exist (`false` by default) `types`: “file type allowed (“file”, “directory”)	`/etc/passwd`
date	a date in the format `%Y-%m-%d`		`2021-01-30`
unix_user	a user in the Unix meaning See also tutorial with a real world sample unix type variable		test
ip	any kind of IPv4 address	`private_only`: only private IPs (`false` by default) `allow_reserved`: allows reserved IPs (`true` by default) `cidr`: IP must be in CIDR format (`false` by default)	`1.2.3.4`
netmask	mask of an IPv4 address		`255.255.255.0`
network	network address	`cidr`: network must be in CIDR format (`false` by default) `private_only`: private network are allowed (`false` by default) `allow_reserved`: reserved network are allowed (`false` by default)	`192.168.1.0`
broadcast	broadcast address		`1.1.1.255`
domainname	domain name	`type`: type of domain name (`domainname` (by default), `netbios`, `hostname`) `allow_ip`: the domain name can be an IP (`false` by default) `allow_cidr_network`: the domain name can be network in CIDR format (`false` by default) `allow_without_dot`: the domain name can be a hostname (`false` by default) `allow_startswith_dot`: the domain name can starts by a dot (`false` by default) `test_existence`: the domain name must exist (`false` by default) See also tutorial with a real world sample domainname type variable or a more complet domainname type variable	`rougail.example`
web_address	web address	`type`: type of domain name (`domainname` (by default), `netbios`, `hostname`) `allow_ip`: the domain name can be an IP (`false` by default) `allow_cidr_network`: the domain name can be network in CIDR format (`false` by default) `allow_without_dot`: the domain name can be a hostname (`false` by default) `allow_startswith_dot`: the domain name can starts by a dot (`false` by default) `test_existence`: the domain name must exist (`false` by default) `allow_range`: can be range of port, for example 80:85 (`false` by default) `allow_zero`: port 0 is allowed (false by default) `allow_wellknown`: well-known ports (1 to 1023) are allowed (`true` by default) `allow_registred`: registred ports (1024 to 49151) are allowed (`true` by default) `allow_private`: private ports (greater than 49152) are allowed (`false` by default) See also tutorial with a real world sample web_address type variable	http://rougail.example
port	port	`allow_range`: can be range of port, for example 80:85 (`false` by default) `allow_zero`: port 0 is allowed (false by default) `allow_wellknown`: well-known ports (1 to 1023) are allowed (`true` by default) `allow_registred`: registred ports (1024 to 49151) are allowed (`true` by default) `allow_private`: private ports (greater than 49152) are allowed (`false` by default) See also tutorial with a real world sample port type variable	8080
mac	MAC address		11:11:11:11:11:11
unix_permissions	access rights to the file, directory, etc.		644
choice	available choices See also tutorial with a real world sample choice type variable
regexp	Validation with a regular expressions See also tutorial with a real world sample regexp type variable		r”^#(?:[0-9a-f]{3}){1,2}$”

Default type

If the type parameter is not set, Rougail has to define a logical type to valid correctly values:

if choices or regexp parameter is set, Rougail will set the choice or regexp type

See also

tutorial with a real world sample choice deducted type or regexp deducted type

if a default value is define, Rougail will infers default value type and set a primitive type to the variable

See also

tutorial with a real world sample type inference

if a variable calculation is define as default value, Rougail copy the type

See also

tutorial with a real world sample type copying

the default type is string