The `manual` family ==================== .. objectives:: Objectives We will learn how to: - create a :term:`family` - gather :term:`variable`\ s into a :term:`family` - make a variable within a variable, which turns this variable container into being a family .. prerequisites:: Reminders - We have an idea of what a :term:`structure description file` is - We have a folder named :file:`firefox` and we are putting all the structure description files into it .. type-along:: So we have this choice type variable in the structure file .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml :linenos: :language: yaml :caption: The `proxy_mode` choice type variable in the :file:`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 .. We're gonna put it in a :term:`family`. .. note:: The variables, families, etc. will be created in several files for educational purposes. Here we made a :file:`firefox/00-proxy.yml` structure file and we're gonna make a new structure file named :file:`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. .. confval:: 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` .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_020/firefox/10-manual.yml :language: yaml :caption: A family structure file description named `manual` in a :file:`firefox/10-manual.yml` file :name: RougailManualFamily .. --- manual: description: Manual proxy configuration type: family We can see that we have defined a :term:`family` here, and this family is *empty* (that is the family which is a container variable contains no variable yet). .. admonition:: If a family is empty We need to specify the :term:`family` type here because if we don't, the Rougail's type engine will infer it by default as a :term:`variable`. It's because we don't have set any :term:`variable` inside. If we have a variable inside of a family, we make a YAML block (that is, we indent) and the Rougail's type inference engine will implicitely infer it as a family. .. type-along:: A family inside a family Creating a family hierarchy is very easy, here is an example: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_021/firefox/10-manual.yml :language: yaml :caption: A rougail structure description file with a hierarchy. :name: RougailFirstFamilyHierarchy .. --- 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: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_024/firefox/10-manual.yml :language: yaml :caption: An `address` variable in the `http_proxy` family :name: RougailVariableInSubFamily .. --- manual: description: Manual proxy configuration type: family http_proxy: description: HTTP Proxy type: family address: description: HTTP address type: domainname The :term:`operator` can now then set :term:`a value ` to the :confval:`address` variable So we have now an `address` variable. .. confval:: 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 :confval:`address` variable, otherwise we will get an error if we try to access this variable: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_024/config/01/output_rw.html :class: error-box .. 
๐Ÿ›‘ ERRORS
    โ”ฃโ”โ” The following variables are mandatory but have no value:
    โ”—โ”โ”   - manual.http_proxy.address (HTTP address)
Because this variable is :term:`mandatory`. .. type-along:: user files are where the user values lives And we need to set the values โ€‹โ€‹in separate files too, called `user files`. .. glossary:: user file A user file is a file where users can set values, called user values -- that is variable's values that have been set by an :term:`operator`\ . Let's set user values in user files Here is a user file sample: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_024/config/03/config.yaml :language: yaml :caption: A user file named :file:`config/config.yaml` with a value set for the `address` variable :name: RougailAddresseVariableUserValue .. --- proxy_mode: Manual proxy configuration manual: http_proxy: address: example.net .. glossary:: 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: .. code-block:: text :class: terminal rougail -v 1.1 -m firefox/ -u file -ff config/config.yaml Everything is OK: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_024/config/03/output_rw.html :class: output .. 
โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ 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 --------------------------------- .. questions:: 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. .. --- manual: description: Manual proxy configuration http_proxy: description: HTTP Proxy address: description: HTTP address type: domainname params: allow_ip: true .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_025/firefox/10-manual.yml :language: yaml :caption: The `address` has a parameter set in the :file:`firefox/10-manual.yml` structure file :name: RougailAddressParameter :linenos: .. --- 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. .. type-along:: One more variable Let's create a `port` variable in the `http_proxy` family: .. confval:: port :type: `port` :default: 8080 The HTTP Port Here is the new :file:`firefox/10-manual.yml` structure file: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_026/firefox/10-manual.yml :language: yaml :caption: A rougail structure description file with a hierarchy. :name: RogailPortVariable :linenos: .. --- 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 Take a look at lines 14 to 17. .. glossary:: parameter A parameter is a property of a variable that can refine its behavior .. keypoints:: Key points progress **Keywords** - we know how to define :term:`variable`\ s inside of a family - we now know what a :term:`mandatory` variable is - we kwow how to set a variable's user value (in a :term:`user file`) - we have the big picture : the :term:`configuration`, which is (the structure files + the user files) - we can add :term:`parameter`\ s to variables to refine their behavior **Progress** - we have a :term:`family` named `manual` and a sub family named `http_proxy` - And we have now two variables: :confval:`proxy_mode` and :confval:`address`.