143 lines
4.4 KiB
ReStructuredText
143 lines
4.4 KiB
ReStructuredText
The `proxy` 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<structure 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 <value>` to the :confval:`address` variable
|
|
|
|
So we have now an `address` variable.
|
|
|
|
.. confval:: address
|
|
:type: `string` (a *domain name*)
|
|
:default: None
|
|
|
|
This is a setting that controls the value of the answer.
|
|
|
|
.. keypoints:: Key points progress
|
|
|
|
**Keywords**
|
|
|
|
- :term:`family`, and sub families
|
|
- :term:`variable`\ s defined inside of a family
|
|
|
|
We have two variables :confval:`proxy_mode` and :confval:`address`.
|