rougail/docs/tutorial/proxymode.rst
2024-10-28 21:08:22 +01:00

102 lines
2.9 KiB
ReStructuredText

The `proxy` family
====================
.. objectives:: Objectives
We will learn how to:
- create a :term:`family`
- gather variables into a family
- make a variable in a variable, which is a family too
.. type-along:: Reminders
- As a prerequisite we have an idea of what a :term:`structure file description <dictionary>` is.
- We have a :file:`firefox` folder and we are putting all the structure description files in it.
- We had at the :term:`structure description file <structure file>`
A `manual` family
--------------------
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_020/firefox/10-manual.yml
:linenos:
:language: yaml
:caption: A family structure file description named `manual` in the :file:`firefox/10-manual.yml` file
:name: RougailFirstDictionary
..
---
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 container 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 make a YAML block
(that is, if we indent), the Rougail's type inference engine will implicitely make it a family.
.. note:: The variables, families, etc. will be created in several files for educational purposes.
Obviously all the variables can be put in the same file.
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
:linenos:
: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.
Put a variable inside a family or a sub family
--------------------------------------------------
Let's create a variable in its family with a description and a default value.
The type of this variable is a `choice` type:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/firefox/10-manual.yml
:linenos:
: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
.. keypoints:: Key points progress
**Keywords**
- :term:`family`, and sub families
- variables defined in a family