diff --git a/docs/tutorial/customtype.rst b/docs/tutorial/customtype.rst index cc1a5ed2f..c4072cf10 100644 --- a/docs/tutorial/customtype.rst +++ b/docs/tutorial/customtype.rst @@ -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 `, 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,19 +114,22 @@ 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 - description: HTTP address - type: domainname - params: - allow_ip: true + description: HTTP address + type: domainname + 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. diff --git a/docs/tutorial/jinja.rst b/docs/tutorial/jinja.rst index 4f5ed680e..90c605249 100644 --- a/docs/tutorial/jinja.rst +++ b/docs/tutorial/jinja.rst @@ -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)?