dynfam and identifier
This commit is contained in:
gwen
parent
15bd2c4986
commit
1da10b7970
1 changed files with 108 additions and 23 deletions
|
|
@ -1,3 +1,4 @@
|
|||
.. _dynfam:
|
||||
|
||||
A dynamic family
|
||||
================
|
||||
|
|
@ -13,25 +14,28 @@ A dynamic family
|
|||
|
||||
.. image:: images/soksv5.png
|
||||
|
||||
In fact we shall not only handle the HTTPS configuration but the SOCKS configuration too.
|
||||
And we can see that these two group of variables are very similar:
|
||||
they both have two variables, that is a host and a port.
|
||||
We see that we need to handle the SOCKS configuration in addition to the HTTPs configuration.
|
||||
Moreover, we can see that these two group of variables are very similar:
|
||||
they both have a host and a port.
|
||||
|
||||
Creating a generic family
|
||||
----------------------------
|
||||
|
||||
|
||||
There are two proxies that are to be configured :
|
||||
|
||||
- the HTTP proxy
|
||||
- the SOCKS proxy
|
||||
|
||||
It's not the place here to describe what the HTTP and SOCKS protocols are.
|
||||
The interesting point is that :
|
||||
The interesting point here is that they are very similar in our firefox's configuration.
|
||||
|
||||
- they are similar in terms of our firefox's configuration
|
||||
- we can use a generic family declaration mode in this use case (we call this genericity "dynamic creation")
|
||||
With Rougail, we can create some kind of a model of family.
|
||||
we can use a generic family declaration mode in this use case.
|
||||
We call this genericity family a "dynamic creation" because as we will see below,
|
||||
these families exist at the very moment we define their identifiers.
|
||||
|
||||
Instead of doing something like this:
|
||||
what we could do with our current knowledge:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -47,11 +51,6 @@ Instead of doing something like this:
|
|||
description: HTTPS Port
|
||||
...
|
||||
|
||||
And this:
|
||||
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
sock_proxy:
|
||||
description: SOCKS Proxy
|
||||
...
|
||||
|
|
@ -64,7 +63,7 @@ And this:
|
|||
description: SOCKS Port
|
||||
...
|
||||
|
||||
With Rougail we have the ability to say this:
|
||||
With Rougail we have the ability to declare our families this way:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_037/firefox/20-manual.yml
|
||||
:language: yaml
|
||||
|
|
@ -73,9 +72,46 @@ With Rougail we have the ability to say this:
|
|||
What is an identifier?
|
||||
-------------------------
|
||||
|
||||
We define what we call an :term:`identifier`, which is a local variable, used only for creating
|
||||
multiple families at one time (that is, being more generic in our declaration style).
|
||||
This is this syntax that allows the declaration of multiple families at one time:
|
||||
If you know a YAML declaration tool named Ansible,
|
||||
the variable used to iterate over multiple values in a task is called an **`item`**.
|
||||
|
||||
It is used in the context of a loop. For example:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
- name: Loop example with 'item'
|
||||
ansible.builtin.debug:
|
||||
msg: "The current value is {{ item }}"
|
||||
loop:
|
||||
- value1
|
||||
- value2
|
||||
- value3
|
||||
|
||||
This code will output:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
The current value is value1
|
||||
The current value is value2
|
||||
The current value is value3
|
||||
|
||||
In the Rougail context, we name this item an identifier because it is an item
|
||||
that allow us to define dynamically family names.
|
||||
|
||||
.. glossary::
|
||||
|
||||
identifier
|
||||
|
||||
In the :ref:`dynamic family creation field <dynfam>` we call an identifier
|
||||
an item that defines a family name. An item is a variable on which an iteration
|
||||
on keywords will be carried out.
|
||||
|
||||
An :term:`identifier` is a local variable, used only for creating multiple
|
||||
iterations, used for creating multiple families in only one declaration.
|
||||
|
||||
It allows us to declare very similar families in a more generic way.
|
||||
|
||||
Here is the syntax we are using that allows the declaration of multiple families at one time:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -85,17 +121,66 @@ This is this syntax that allows the declaration of multiple families at one time
|
|||
- HTTPS
|
||||
- SOCKS
|
||||
|
||||
This identifier is a parameter that enables us to create two families named `https_proxy` and `socks_proxy`.
|
||||
This identifier is a parameter that enables us to create two families named `https_proxy` and `socks_proxy`:
|
||||
|
||||
.. note:: The declaration syntax is a :term:`jinja` templating syntax, which is commonly used
|
||||
in the python coding field.
|
||||
|
||||
So yes, we have gained in genericity but we have lost in readability, you would say.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
https_proxy:
|
||||
description: "HTTPS Proxy"
|
||||
|
||||
socks_proxy:
|
||||
description: "SOCKS Proxy"
|
||||
|
||||
.. note:: The declaration syntax used is the :term:`Jinja <jinja>` templating syntax,
|
||||
Jinja which is widely used in python.
|
||||
|
||||
.. attention:: Be careful when choosing your identifiers items: the family
|
||||
that will be dynamically created shall not exist already.
|
||||
|
||||
If you define a dynamic family with the `https` item that will
|
||||
build a `https_proxy` family and if this familiy already exist,
|
||||
then rougail will raise a warning.
|
||||
|
||||
|
||||
Besides, when we launch the rougail command line, we can have a look at the concrete variables here:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
rougail -m structfile/proxy.yml -u yaml --yaml.filename userdata/proxy.yml
|
||||
╭─────────────────── Caption ────────────────────╮
|
||||
│ Variable Default value │
|
||||
│ Unmodifiable variable Modified value │
|
||||
│ (Original default value) │
|
||||
╰────────────────────────────────────────────────╯
|
||||
Variables:
|
||||
┗━━ 📂 Manual proxy configuration
|
||||
┣━━ 📂 HTTP Proxy
|
||||
┃ ┣━━ 📓 HTTP address: ... (loaded from the YAML file "userdata/proxy.yml")
|
||||
┃ ┗━━ 📓 HTTP Port: ... (8080 - loaded from the YAML file "userdata/proxy.yml")
|
||||
┣━━ 📓 Also use this proxy for HTTPS: true
|
||||
┣━━ 📂 HTTPS Proxy
|
||||
┃ ┣━━ 📓 HTTPS address: ...
|
||||
┃ ┗━━ 📓 HTTPS port: ...
|
||||
┗━━ 📂 SOCKS Proxy
|
||||
┣━━ 📓 SOCKS address: ...
|
||||
┗━━ 📓 SOCKS port: ...
|
||||
|
||||
We can see that the dynamic family has created:
|
||||
|
||||
- an `HTTPS Proxy` family
|
||||
- a `SOCKS Proxy` family
|
||||
|
||||
as we wanted.
|
||||
|
||||
|
||||
A conditional hidden familiy
|
||||
--------------------------------
|
||||
|
||||
Yes we have gained in genericity but we have lost in readability, you would say.
|
||||
But we haven't just been generic. We now have the ability to create conditional hidden family
|
||||
(and not only conditionnal hidden variables like we did earlier).
|
||||
|
||||
A conditional hidden family with jinja
|
||||
------------------------------------------
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue