Let’s dive in

Objectives

We will learn how to:

create a family
gather variables into a family
make a variable within a variable, which turns this variable container into being a family

Reminders

We have an idea of what a structure description file is
We have a folder named firefox and we are putting all the structure description files into it

let’s recap: we have this choice type variable

In the structure description file, we have:

The proxy_mode choice type variable in the firefox/00-proxy.yml structure file

---
proxy_mode:
  description: Configure Proxy Access to the Internet
  type: choice
  choices:
    - No proxy
    - Auto-detect proxy settings for this network
    - Use system proxy settings
    - Manual proxy configuration
    - Automatic proxy configuration URL
  default: No proxy

Warning

The variables, families, etc. will be created in several files for educational purposes. Here we made a firefox/00-proxy.yml structure file and we’re gonna make a new structure file named firefox/10-manual.yml. We could of course have put everything in one file, we decided to separate the files for reasons of ordering and clarity.

So we have now a proxy_mode variable.

proxy_mode

Type:: choice
Default:: No proxy

This is a setting that controls the proxy’s type

Creating a new family

Let’s create a family named manual which obviously corresponds to the proxy’s manual configuration choice.

A family structure file description named manual in a firefox/10-manual.yml file

---
manual:
  description: Manual proxy configuration
  type: family

We can see that we have defined a family here, and this family is empty (that is the family which is a container variable contains no variable yet).

Warning

If a family is empty, we need to specify the family type here because if we don’t, the Rougail’s type engine will infer it by default as a variable. We have to force the family type inference.

It’s because we don’t have set any variable inside yet. When we will have a variable inside of this family, we will make a YAML block (that is, we just indent the lines) and the Rougail’s type inference engine will implicitely infer the variable’s container as a family type.

A family inside a family

Creating a family hierarchy of family container types is very easy, here is an example:

A rougail structure description file with a hierarchy.

---
manual:
  description: Manual proxy configuration
  type: family

  http_proxy:
    description: HTTP Proxy
    type: family

Here the http_proxy family lives inside the manual family.

Putting a variable inside of a family or a sub family

Let’s create a variable in the http_proxy family. This time, the type of this new variable is a domainname type:

An address variable in the http_proxy family

---
manual:
  description: Manual proxy configuration

  http_proxy:
    description: HTTP Proxy

    address:
      description: HTTP address
      type: domainname

Now that the address variable is declarde, the operator can set a value to the address variable

So we have now an address variable:

address

Type:: domainname
Default:: None

This is the HTTP address of the proxy

Note

We encountered here a new type of variable there: the domainname type. There are a bunch of types available in Rougail.

Assigning a user value

Now we need to set a value for the address variable, otherwise we will get an error if we try to access this variable:

🛑 ERRORS
┣━━ The following variables are mandatory but have no value:
┗━━   - manual.http_proxy.address (HTTP address)

Because the mandatory variable attribute is infered by default for this variable.

user data files are where the user values lives

And we need to set the values in separate files too, called user data files.

user data file

A user data file is a file where only user datas are set.

A user file is a file where there are only user datas in it, users can set values, called user values – that is variable’s values that have been set by an operator.

Variables can have parameters

Question

question: Does our address domain name variable accepts IP addresses ?

answer: Well it depends.

We need to specify whether our variable accepts to be filled using an IP or a domain name only. This is where the ability to parameterize our variable comes in.

let’s create a variable parameter named allow_ip

The address has a parameter set in the firefox/10-manual.yml structure file

---
manual:
  description: Manual proxy configuration

  http_proxy:
    description: HTTP Proxy

    address:
      description: HTTP address
      type: domainname
      params:
        allow_ip: true

We can see line 11 and 12 that the params allow the domain name address variable to be set with IPs.

parameter: A parameter is a property of a variable that can refine its behavior

a second variable in the http_proxy family

Let’s create a port variable in the http_proxy family:

port

Type:: port
Default:: 8080

The HTTP Port

Here is the new firefox/10-manual.yml structure file:

A rougail structure description file with a hierarchy.

---
manual:
  description: Manual proxy configuration

  http_proxy:
    description: HTTP Proxy

    address:
      description: HTTP address
      type: domainname
      params:
        allow_ip: true

    port:
      description: HTTP Port
      type: port
      default: 8080

let’s review the key points

Keywords

we know how to define variables inside of a family
we now know what a mandatory variable is
we kwow how to set a variable’s user value (in a user data file)
we have the big picture : the configuration, which is (the structure files + the user data files)
we can add parameters to variables to refine their behavior

Progress

we have a family named manual and a sub family named http_proxy
And we have now two variables: proxy_mode and address.