The manual family

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

So we have this choice type variable in the structure file

The proxy_mode choice type variable in the firefox/00-proxy.yml structure file
 1---
 2proxy_mode:
 3  description: Configure Proxy Access to the Internet
 4  type: choice
 5  choices:
 6    - No proxy
 7    - Auto-detect proxy settings for this network
 8    - Use system proxy settings
 9    - Manual proxy configuration
10    - Automatic proxy configuration URL
11  default: No proxy

Note

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

A family named manual

Let’s create a family named manual

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

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.

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

A family inside a family

Creating a family hierarchy 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 its family. The type of this variable is a choice 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

The operator can now then 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

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 this variable is mandatory.

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 the user datas are assigned.

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.

see also user datas

Let’s set user values in user data files

Here is a user data file sample:

A user file named config/config.yaml with a value set for the address variable
---
proxy_mode: Manual proxy configuration
manual:
  http_proxy:
    address: example.net
configuration

We call configuration the whole system structure and user values, and when we speak of consistency, it is in relation to this whole set.

Let’s validate the consitency of the configuration:

 rougail -v 1.1 -m firefox/ -u file -ff config/config.yaml

Everything is OK:

╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           Default value            │
│ Undocumented variable              Modified value           │
│ Undocumented but modified variable (Original default value) │
╰─────────────────────────────────────────────────────────────╯
Variables:
┣━━ 📓 proxy_mode: Manual proxy configuration (No proxy)
┗━━ 📂 manual
    ┗━━ 📂 http_proxy
        ┗━━ 📓 address: example.net

  • the proxy_mode value is in green because its value is set by default

  • the address value is in black because its value has been set by a user

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.

The address has a parameter set in the firefox/10-manual.yml structure file
 1---
 2manual:
 3  description: Manual proxy configuration
 4
 5  http_proxy:
 6    description: HTTP Proxy
 7
 8    address:
 9      description: HTTP address
10      type: domainname
11      params:
12        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

One more variable

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.
 1---
 2manual:
 3  description: Manual proxy configuration
 4
 5  http_proxy:
 6    description: HTTP Proxy
 7
 8    address:
 9      description: HTTP address
10      type: domainname
11      params:
12        allow_ip: true
13
14    port:
15      description: HTTP Port
16      type: port
17      default: 8080

Take a look at lines 14 to 17.

Key points progress

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.