proofreader
This commit is contained in:
gwen
parent
a3d7258a64
commit
f7701917d0
4 changed files with 88 additions and 71 deletions
|
|
@ -6,9 +6,9 @@ The `hidden` property
|
|||
In this section we will:
|
||||
|
||||
- use a new family or variable's property: the `hidden` property
|
||||
- create a new variable's type: `boolean`
|
||||
- create a variable with a new type, the `boolean` type
|
||||
- reuse a value of a variable for another variable
|
||||
(in this use case we will reuse the HTTP configuration variables values for the HTTPS configuration).
|
||||
(in this use case we will reuse the HTTP configuration variables values for the configuration of the HTTPS).
|
||||
|
||||
.. prerequisites:: Reminder
|
||||
|
||||
|
|
@ -32,7 +32,7 @@ Whe have the `proxy_mode` configuration here:
|
|||
- Automatic proxy configuration URL
|
||||
default: No proxy
|
||||
|
||||
With the `manual` subfamily that is used in case of the `"Manual proxy configuration"` value of the `proxy_mode` variable has been chosen:
|
||||
With the `manual` family that is used in case of the `"Manual proxy configuration"` value of the `proxy_mode` variable has been chosen:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/firefox/10-manual.yml
|
||||
:language: yaml
|
||||
|
|
@ -68,7 +68,7 @@ Now we will focus on configuring the HTTPS mode in case of `"Manual proxy config
|
|||
|
||||
.. image:: images/firefox_manual_https.png
|
||||
|
||||
Let's set two other variables for the HTTPS use only:
|
||||
We are going to define two other variables for the HTTPS use only:
|
||||
|
||||
.. confval:: https_proxy.address
|
||||
:type: `domainname`
|
||||
|
|
@ -80,7 +80,7 @@ Let's set two other variables for the HTTPS use only:
|
|||
|
||||
This is a port setting for the manual HTTPS configuration
|
||||
|
||||
- So we have two very similar variables, a `manual.http_proxy.address` variable and a `manual.https_proxy.address` variable
|
||||
- There are now two very similar variables, a `manual.http_proxy.address` variable and a `manual.https_proxy.address` variable
|
||||
- In the same way, we have a `manual.http_proxy.port` variable and a `manual.https_proxy.port` variable.
|
||||
|
||||
The context
|
||||
|
|
@ -93,10 +93,10 @@ Let's introduce a new Rougail concept here:
|
|||
context
|
||||
|
||||
A :term:`configuration` is highly statefull and can change at any moment.
|
||||
Sometimes somes minor changes in the :term:`user datas` involves chain reactions
|
||||
in the whole :term:`configuration`.
|
||||
Sometimes somes minor changes in the :term:`user datas` may involve chain reactions
|
||||
in the whole :term:`configuration`.
|
||||
The **context** is the state of the user datas at one moment. The set of the values of the variables
|
||||
in a given moment.
|
||||
at a given moment.
|
||||
This term also refers
|
||||
to the ability of a system to handle the *statefull* state of a configuration.
|
||||
It expresses the transition between one situation to another situation,
|
||||
|
|
@ -117,7 +117,7 @@ Let's create a new variable, named `use_for_https` here:
|
|||
:type: `boolean`
|
||||
:default: `true`
|
||||
|
||||
This is a setting that enables to reuse the HTTP proxy configuration for HTTPS
|
||||
This is a setting that enables to reuse or not the HTTP proxy configuration for HTTPS
|
||||
|
||||
.. questions:: Question: how does it work?
|
||||
|
||||
|
|
@ -140,7 +140,7 @@ Its description in the structure file gives us this:
|
|||
|
||||
.. prerequisites:: Reminder
|
||||
|
||||
So now we have three new variables in the `manual` family which expresses the manual mode of the http proxy configuration.
|
||||
So now we have three new variables in the `manual` family (with its `https_proxy` subfamily) which express the manual mode of the http proxy configuration.
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_032/firefox/20-manual.yml
|
||||
:language: yaml
|
||||
|
|
@ -183,16 +183,16 @@ And with this :confval:`use_for_https` boolean variable, there are two possibili
|
|||
It is absolutely not a question of deactivating them. The `manual.https_proxy.address`
|
||||
and the `manual.http_proxy.port` variables shall not be disabled (deactivated) in the manual mode.
|
||||
|
||||
Let's introduce here a new concept here.
|
||||
We have to create a new property here.
|
||||
|
||||
The hidden property
|
||||
---------------------
|
||||
The `hidden` property
|
||||
----------------------
|
||||
|
||||
.. glossary::
|
||||
|
||||
hidden
|
||||
|
||||
A variable or family's property is hidden if its value shall not be seen in a given consistency.
|
||||
A variable or family's property is hidden if its value **shall not be seen** in a given :term:`context`.
|
||||
Anyway, these variables can be used again if the context evolves. This is the main difference
|
||||
between the `hidden` and the `disabled` properties.
|
||||
|
||||
|
|
|
|||
|
|
@ -5,17 +5,19 @@ The `disabled` property
|
|||
|
||||
In this section we will learn:
|
||||
|
||||
- how to disable a family,(yes, a family can disapear in the outerspace)
|
||||
- what a *property* is
|
||||
- what the `disabled` property is
|
||||
- how to disable a family (yes, a family can disapear in the outerspace)
|
||||
- explain the `disabled` property
|
||||
|
||||
What is a disabled variable or family is, and why it is interesting to do that.
|
||||
We will see what is a disabled variable or family is, and why it is interesting to do that.
|
||||
|
||||
.. prerequisites:: Reminder
|
||||
|
||||
- We have three variables: :confval:`proxy_mode`, :confval:`address` and :confval:`port` placed in the `http_proxy` subfamily.
|
||||
|
||||
.. type-along:: The disabled property
|
||||
A disabled property assigned to a family
|
||||
---------------------------------------------
|
||||
|
||||
|
||||
.. glossary::
|
||||
|
||||
|
|
@ -25,10 +27,6 @@ The `disabled` property
|
|||
of a family, a subfamily or a variable. These properties may vary
|
||||
depending on the context.
|
||||
|
||||
|
||||
A disabled family
|
||||
-----------------------
|
||||
|
||||
.. glossary::
|
||||
|
||||
disabled
|
||||
|
|
@ -52,11 +50,13 @@ The five choices are:
|
|||
If the `Manual proxy configuration` is not selected, we don't need to set
|
||||
the :confval:`address` and :confval:`port` variables, there is no point
|
||||
in setting them. It's not just that: if we fill them in, there might be a problem in the overall integrity of the configuration. We shall fill and use in these variables
|
||||
only in the `Manual proxy configuration` context. Otherwise, we need to disable them.
|
||||
only in the `Manual proxy configuration` context. Otherwise, **we need to disable them when they are not necessary**.
|
||||
|
||||
.. important:: We need to have the ability to **disable** variables that are not used
|
||||
in a given context.
|
||||
|
||||
.. type-along:: disabling the :confval:`address` and :confval:`port` variables
|
||||
|
||||
If we don't choose the manual mode, we need to **disable** these variables.
|
||||
They are not used anymore.
|
||||
|
||||
|
|
@ -92,11 +92,17 @@ disable the variables that are placed in it.
|
|||
|
||||
We can see here the `disabled: true` parameter set in the `manual` family.
|
||||
|
||||
.. attention:: We will intentionally create an inconsistency here in order to
|
||||
explore the `disabled` property's behavior.
|
||||
A conditional disabled family
|
||||
------------------------------
|
||||
|
||||
Let's decide to make an inconsistency in the configuration: we are going to
|
||||
select **the manual mode** as its variables are disabled.
|
||||
.. warning:: In this section, we will **intentionally** create an inconsistency in the configuration
|
||||
in order to explore the `disabled` property's behavior.
|
||||
|
||||
|
||||
We are going to
|
||||
|
||||
- select **the manual mode** value for the `proxy_mode`
|
||||
- assing the `example.net` value to the `address` validate in the user data file.
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_027/config/03/config.yaml
|
||||
:linenos:
|
||||
|
|
@ -110,6 +116,8 @@ select **the manual mode** as its variables are disabled.
|
|||
http_proxy:
|
||||
address: example.net
|
||||
|
||||
.. warning:: Remember that the `manual` family is disabled, so are the variables it contains.
|
||||
|
||||
|
||||
Now let's validate the consitency of the configuration:
|
||||
|
||||
|
|
@ -137,23 +145,25 @@ As expected, we encounter an error:
|
|||
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: Manual proxy configuration (<span style="color: #00aa00">No proxy</span>)
|
||||
</pre>
|
||||
|
||||
To avoid this type of error, What we need is a *dynamic setting* of the disable/enable property.
|
||||
.. questions:: Question
|
||||
|
||||
How to avoid these error messages?
|
||||
|
||||
Contextual setting of a property
|
||||
------------------------------------
|
||||
|
||||
To avoid this type of error, what we need is a *dynamic setting* of the disable/enable property of the `manual` family.
|
||||
|
||||
.. type-along:: The conditional disabled property
|
||||
|
||||
|
||||
A conditional disabled family
|
||||
------------------------------
|
||||
|
||||
|
||||
If the manual mode for the proxy is not selected, then the `manual` family shall be disabled.
|
||||
On the other hand, if the manual proxy's configuration mode is selected,
|
||||
then we need to activate the `manual` family.
|
||||
then we need to activate (enable) the `manual` family.
|
||||
|
||||
And we understand that this activation/deactivation of the `manual` family
|
||||
depends on the value of the `proxy_mode` variable.
|
||||
|
||||
In rougail, we can set a property's value **depending on** the value of another variable. That is, it is conditioned by another variable.
|
||||
In rougail, we can set a property's value **depending on** the value of another variable. That is, **it is conditioned by** another variable.
|
||||
|
||||
Here is how we can achieve this:
|
||||
|
||||
|
|
@ -196,27 +206,31 @@ Here we have the `disabled` property like this:
|
|||
variable: proxy_mode
|
||||
when_not: 'Manual proxy configuration'
|
||||
|
||||
It means that the `disabled` property **depends on** the value of another variable.
|
||||
Here the `disabled` property **depends on** the value of another variable.
|
||||
The `variable` parameter allows you to define the name of the target variable on which the `disabled` property depends.
|
||||
|
||||
What does it allow you to do?
|
||||
|
||||
- if `proxy_mode` is not `'Manual proxy configuration'` it disables the `manual` family
|
||||
- if `proxy_mode == 'Manual proxy configuration'` it enables the `manual` family
|
||||
|
||||
.. keypoints:: Key points progress
|
||||
|
||||
**summary**
|
||||
|
||||
We have the ability to build a contextual setting:
|
||||
|
||||
- if `proxy_mode` is not `'Manual proxy configuration'` it disables the `manual` family
|
||||
- if `proxy_mode == 'Manual proxy configuration'` it enables the `manual` family
|
||||
|
||||
**Keywords**
|
||||
|
||||
- the :term:`property` concept
|
||||
- the `disabled` property
|
||||
- disabled variable or family
|
||||
- the `variable` target property
|
||||
- a disabled variable or family
|
||||
- raising a configuration's consistency error
|
||||
- variable based conditional disabled family
|
||||
- a variable based contextual disabled family
|
||||
|
||||
**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`.
|
||||
- We have disabled the `manual` family (and the `http_proxy` sub family).
|
||||
- We have dynamically disabled the `manual` family (and the `http_proxy` sub family).
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ Preliminaries
|
|||
Making a structure file
|
||||
-------------------------
|
||||
|
||||
.. exercise:: The folder structure
|
||||
.. demo:: The folder structure
|
||||
|
||||
Here is the tree structure we want to have::
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
The `manual` family
|
||||
Let's dive in
|
||||
====================
|
||||
|
||||
.. objectives:: Objectives
|
||||
|
|
@ -15,7 +15,9 @@ The `manual` family
|
|||
- 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
|
||||
.. type-along:: let's recap: we have this choice type variable
|
||||
|
||||
In the structure description file, we have:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml
|
||||
:linenos:
|
||||
|
|
@ -37,10 +39,10 @@ The `manual` family
|
|||
|
||||
.. We're gonna put it in a :term:`family`.
|
||||
|
||||
.. note:: The variables, families, etc. will be created in several files for educational purposes.
|
||||
.. warning:: 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
|
||||
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.
|
||||
|
||||
|
|
@ -50,10 +52,10 @@ So we have now a `proxy_mode` variable.
|
|||
|
||||
This is a setting that controls the proxy's type
|
||||
|
||||
A family named `manual`
|
||||
-------------------------
|
||||
Creating a new family
|
||||
-----------------------
|
||||
|
||||
Let's create a family named `manual`
|
||||
Let's create a family named `manual` which obviously corresponds to the proxy's manual configuration choice.
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_020/firefox/10-manual.yml
|
||||
:language: yaml
|
||||
|
|
@ -69,17 +71,18 @@ Let's create a family named `manual`
|
|||
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
|
||||
.. warning::
|
||||
|
||||
We need to specify the :term:`family` type here because if we don't,
|
||||
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 just indent the lines) and the Rougail's type inference engine will implicitely infer it as a family.
|
||||
We have to force the family type inference.
|
||||
|
||||
It's because we don't have set any :term:`variable` inside yet. When we will have a variable inside of this family,
|
||||
we will make a YAML block (that is, we just indent the lines) and the Rougail's type inference engine will implicitely infer the variable's container as a family type.
|
||||
|
||||
.. type-along:: A family inside a family
|
||||
|
||||
Creating a family hierarchy is very easy, here is an example:
|
||||
Creating a family hierarchy of family container types 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
|
||||
|
|
@ -101,8 +104,8 @@ 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:
|
||||
Let's create a variable in the `http_proxy` family.
|
||||
This time, the type of this new variable is a `domainname` type:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_024/firefox/10-manual.yml
|
||||
:language: yaml
|
||||
|
|
@ -123,9 +126,9 @@ The type of this variable is a `choice` type:
|
|||
description: HTTP address
|
||||
type: domainname
|
||||
|
||||
The :term:`operator` can now then set :term:`a value <value>` to the :confval:`address` variable
|
||||
Now that the :confval:`address` variable is declarde, the :term:`operator` can set :term:`a value <value>` to the :confval:`address` variable
|
||||
|
||||
So we have now an `address` variable.
|
||||
So we have now an :confval:`address` variable:
|
||||
|
||||
.. confval:: address
|
||||
:type: `domainname`
|
||||
|
|
@ -133,8 +136,8 @@ So we have now an `address` variable.
|
|||
|
||||
This is the HTTP address of the proxy
|
||||
|
||||
.. note:: We encountered here a new type of variable there: the `domainname` type
|
||||
|
||||
.. note:: We encountered here a new type of variable there: the `domainname` type.
|
||||
There are a bunch of types available in Rougail.
|
||||
|
||||
Assigning a user value
|
||||
------------------------------------
|
||||
|
|
@ -152,7 +155,7 @@ otherwise we will get an error if we try to access this variable:
|
|||
<span style="color: #ff0000">┗━━ </span> - manual.http_proxy.address (HTTP address)
|
||||
</pre>
|
||||
|
||||
Because this variable is :term:`mandatory`.
|
||||
Because the :term:`mandatory` variable attribute is infered by default for this variable.
|
||||
|
||||
.. type-along:: user data files are where the user values lives
|
||||
|
||||
|
|
@ -162,14 +165,14 @@ And we need to set the values in separate files too, called `user data fil
|
|||
|
||||
user data file
|
||||
|
||||
A user data file is a file where only the user datas are assigned.
|
||||
A user data file is a file where only :term:`user datas` are set.
|
||||
|
||||
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 :term:`operator`\ .
|
||||
|
||||
see also :term:`user datas`
|
||||
|
||||
Let's set user values in user data files
|
||||
.. type-along:: let's set user values in a user data file
|
||||
|
||||
Here is a user data file sample:
|
||||
|
||||
|
|
@ -233,6 +236,8 @@ Variables can have parameters
|
|||
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.
|
||||
|
||||
.. type-along:: let's create a variable parameter named `allow_ip`
|
||||
|
||||
..
|
||||
---
|
||||
manual:
|
||||
|
|
@ -275,7 +280,7 @@ with IPs.
|
|||
|
||||
A parameter is a property of a variable that can refine its behavior
|
||||
|
||||
.. type-along:: One more variable
|
||||
.. type-along:: a second variable in the `http_proxy` family
|
||||
|
||||
Let's create a `port` variable in the `http_proxy` family:
|
||||
|
||||
|
|
@ -312,9 +317,7 @@ Here is the new :file:`firefox/10-manual.yml` structure file:
|
|||
type: port
|
||||
default: 8080
|
||||
|
||||
Take a look at lines 14 to 17.
|
||||
|
||||
.. keypoints:: Key points progress
|
||||
.. keypoints:: let's review the key points
|
||||
|
||||
**Keywords**
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue