type definition
This commit is contained in:
gwen
parent
9a834b637b
commit
c9d32dce9f
2 changed files with 74 additions and 20 deletions
|
|
@ -3,8 +3,8 @@ Custom type
|
|||
|
||||
.. objectives:: Objectives
|
||||
|
||||
In this sections we are going to learn how to create custom types.
|
||||
In short, a custom type is nothing more than a kind of family template.
|
||||
In this sections we are going to learn how to create custom types with Rougail.
|
||||
In short, a custom type is nothing more than a kind of a template for a family.
|
||||
|
||||
.. prerequisites:: Prerequisites
|
||||
|
||||
|
|
@ -32,17 +32,22 @@ This feature is essential for having a truly adaptable tool.
|
|||
|
||||
.. note:: It is actually possible to add types,
|
||||
but that involves adding predefined types to the :term:`tiramisu` underlying consistency library itself,
|
||||
and that’s a different matter altogether. There is a simpler way to do this.
|
||||
and that’s a different matter altogether. There is a simpler way to achieve this: the Rougail type definition.
|
||||
|
||||
More simply, it's possible in Rougail to create custom types, much like defining families.
|
||||
It is possible in Rougail to create custom types in a very simple way, it is much like defining families.
|
||||
|
||||
Our folder structure will be expanded a bit:
|
||||
Now our folder structure will be expanded a bit:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/tree.html
|
||||
|
||||
Notice that we have now a new :file:`types` folder in our tree structure.
|
||||
This is where we place our new `proxy` type definition.
|
||||
This is where we will place our new `proxy` type definition.
|
||||
|
||||
.. note:: Choosing the :file:`types/proxy/00_type.yml` file name is not mandatory.
|
||||
You can name this folder whatever you want.
|
||||
It is simply a good practice to separate structure files from type definition files.
|
||||
We will see later on how to indicate to Rougail that a file contains a type declaration.
|
||||
|
||||
In accordance with our :ref:`naming policy <namingconvention>`, we have created a file named :file:`00_type.yml`
|
||||
inside the `proxy` folder.
|
||||
|
|
@ -74,14 +79,14 @@ Let's examine this more closely this :file:`types/proxy/00_type.yml` type defini
|
|||
variable: __.http_proxy.port
|
||||
...
|
||||
|
||||
The new type named `proxy` is declared.
|
||||
The new type named `proxy` is declared the same way we declare a family.
|
||||
It's more or less like a family declaration except it will be used as a type definition.
|
||||
|
||||
.. questions:: How do we use a new type?
|
||||
|
||||
Very simply. In the usual way: we will use the `type` parameter.
|
||||
Very simply. In the usual way: we will add a `type` parameter in our family declaration.
|
||||
|
||||
Here, we will declare that a family is of type `proxy` as follows:
|
||||
Let's declare that a family is of type `proxy` as follows:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/firefox/10-manual.yml
|
||||
:language: yaml
|
||||
|
|
@ -109,8 +114,10 @@ Here, we will declare that a family is of type `proxy` as follows:
|
|||
default: 8080
|
||||
...
|
||||
|
||||
We can see that the type declared for the `http_proxy` family is `type: proxy`. Very simple.
|
||||
For example in the `address` it is not necessary to specify the `domainname` type nor the `allow_ip` parameter:
|
||||
We can see that the type declared for the `http_proxy` family is `type: proxy`.
|
||||
It's perfectly natural in the rougail style.
|
||||
|
||||
Now in the `address` family it is not necessary to specify the `domainname` type nor the `allow_ip` parameter:
|
||||
|
||||
.. code-block:: yaml
|
||||
:caption: We can omit this now due to the type definition
|
||||
|
|
@ -120,8 +127,9 @@ For example in the `address` it is not necessary to specify the `domainname` typ
|
|||
params:
|
||||
allow_ip: true
|
||||
|
||||
So we have declared our new type. How do we make it available? Well, the Rougail CLI has a `--types` type declaration command line option.
|
||||
Let's launch the rougail CLI:
|
||||
But if we use our new type we need to declare it to Rougail in order to make it available.
|
||||
The Rougail CLI has a `--types` type declaration command line option for this purpose.
|
||||
Let's launch the rougail CLI with this command line parameter:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/config/01/cmd_ro.txt
|
||||
|
|
@ -129,15 +137,62 @@ Let's launch the rougail CLI:
|
|||
|
||||
The CLI output is entirely standard and does not specifically mention the call to a new type.
|
||||
The result is the same as usual, as if the type declaration were omitted, which is what we want.
|
||||
We want the same behavior.
|
||||
We want the same behavior as usual.
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/config/01/output_ro.html
|
||||
:class: output
|
||||
|
||||
The type definition adds nothing to the structural logic. It's just a very convenient way to save time when writing structure files.
|
||||
|
||||
HTTPS and SOCKS Proxy
|
||||
-----------------------
|
||||
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
||||
Now you need to checkout the `v1.1_081` version::
|
||||
|
||||
git switch --detach v1.1_081
|
||||
|
||||
With this use of a type, it is possible to define our HTTPS and SOCKS Proxy in a much more conscious way:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_081/firefox/20-manual.yml
|
||||
:language: yaml
|
||||
:caption: The :file:`firefox/20-manual.yml` structure file with less code due to the `proxy` type definition
|
||||
|
||||
..
|
||||
%YAML 1.2
|
||||
---
|
||||
version: 1.1
|
||||
|
||||
manual:
|
||||
|
||||
use_for_https: true # Also use this proxy for HTTPS
|
||||
|
||||
https_proxy:
|
||||
description: HTTPS Proxy
|
||||
type: proxy
|
||||
hidden:
|
||||
variable: _.use_for_https
|
||||
|
||||
socks_proxy:
|
||||
description: SOCKS Proxy
|
||||
type: proxy
|
||||
|
||||
version:
|
||||
description: SOCKS host version used by proxy
|
||||
choices:
|
||||
- v4
|
||||
- v5
|
||||
default: v5
|
||||
...
|
||||
|
||||
|
||||
.. keypoints:: Key points
|
||||
|
||||
- type declaration
|
||||
- type usage
|
||||
- more conscious family definition
|
||||
- the very practical aspects of type declaration
|
||||
|
||||
We have seen how the definition of type, used effectively, allows for a new expressiveness.
|
||||
|
|
|
|||
|
|
@ -588,7 +588,7 @@ Here is a Jinja code that return a boolean value:
|
|||
{{ my_identifier == 'HTTPS' and _.use_for_https }}
|
||||
|
||||
And in order to declare explicitly the use of this explicit non-truthiness pratice,
|
||||
we add a `return_type` parameter in the `hiden` property:
|
||||
we add a `return_type` parameter in the `hidden` property:
|
||||
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_073/firefox/20-manual.yml
|
||||
|
|
@ -640,7 +640,6 @@ we add a `return_type` parameter in the `hiden` property:
|
|||
when: HTTPS
|
||||
...
|
||||
|
||||
|
||||
.. questions:: What about the error message?
|
||||
|
||||
If no text is returned by the Jinja calculation, what about the error message (in case of an error)?
|
||||
|
|
|
|||
Loading…
Reference in a new issue