The variables

Synopsis

variable

A variable is an abstract black box (container) paired with an associated symbolic name, most often an option configuration, hich 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 define 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

Variable name

Variable’s associated symbolic name.

See also

Have a look at the convention on variable naming link.

Shorthand declaration

Shorthand declaration is a way to declare a variable in a single line. But you can only define variable name, description, multi or default value.

To create a variable, just add a key with it’s name and default value as value. Be careful not to declare any other attributes.

To declare a multi variable just add a list as default value.

By default, the description of the variable is the variable name. If you add a comment in the same line of the name, this comment will be used has a description.

---
version: '1.1'
my_variable: 1  # This is a great integer variable
my_multi_variable:  # This is a great multi string variable
  - value1
  - value2

Parameters

Parameter	Comments
help string	Additional help associated with the variable.
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 number 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.
validators list	Value validators. Jinja template list. The value of the variable will be considered invalid if the template has a return value.
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. A leader or follower variable cannot have the auto_save property. Default value: false
mode string	Variable’s mode. Default value: The default mode of a variable is the mode of the parent family. Special cases : a variable with an automatically modified value or an automatic read-only variable is by default in basic mode if the variable is not in a family, the variable will have a standard mode by default a mandatory variable without default value (calculate or not) will have a basic mode
multi boolean	The value of the variable is a list. Default value: false
unique boolean	The multiple type 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
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.
mandatory boolean or calculation	Mandatory variable. Variable whose value is required. For a multiple variable, this means that the list shall not be empty. Default value: true
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 attribute 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 attribute must be true in conjunction with the redefine attribute set to true, only modifies the behavior if it is pre-existing, in which case the attribute’s value must be false. Default value: null
test list	The test attribute is a special attribute that allows structure file designers to influence a test robot by specifying useful values to test. Concretely, the content of this attribute is recorded in the information attribute of the corresponding Tiramisu option object.

Variables types

A variable has a type.

This type enables the variable to define the values that are accepted by this variable.

Value	Comments	Parameters	Samples
string	character string (default type)		test “1” “true”
number	a number	min_number: minimum number allowed max_number: maximum number allowed	1
float	a floating number		1.2
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		true false
secret	a secret (like a password, a private key, etc.)		hO_'hi
mail	a mail address		test@rougail.example
unix_filename	a file name in the Unix meaning		/etc/passwd
date	a date in the format %Y-%m-%d		2021-01-30
unix_user	a user in the Unix meaning		test
ip	any kind of IPv4 address	private_only: only private IPs (false by default) allow_reserved: allows reserved IPs (true by default)	1.2.3.4
cidr	any IPv4 address in the CIDR format	private_only: only private IPs (false by default) allow_reserved: allows reserved IPs (false by default)	1.2.3.4/24
netmask	mask of an IPv4 address		255.255.255.0
network	network address		192.168.1.0
network_cidr	network address in CIDR format		192.168.1.0/24
broadcast	broadcast address		255.255.255.255
netbios	netbios name		machine
domainname	domain name	allow_ip: allows an IP rather than a domain name (false by default) allow_cidr_network: allows a CIDR type network address (false by default) allow_without_dot: allows names without a dot (false by default) allow_startswith_dot: allows starting with a point (false by default)	rougail.example
hostname	host name	allow_ip: allows an IP rather than a domain name (false by default)	machine
web_address	web address	allow_ip: allows an IP rather than a domain name (false by default) allow_without_dot: allows names without a dot (true by default)	http://rougail.example
port	port	allow_range: allows a port range, for example 80:85 (false by default) allow_zero: allows port 0 (false by default) allow_wellknown: allows ports from 1 to 1023 (true by default) allow_registred: allows ports from 1024 to 49151 (true by default) allow_private: allows ports greater than 49152 (true by default) allow_protocol: allows the addition of the protocol, for example tcp:80 (false by default)	8080
mac	MAC address		11:11:11:11:11:11
unix_permissions	access rights to the file, directory, etc.		644
choice	choice variable