diff --git a/docs/tutorial/nullable.rst b/docs/tutorial/nullable.rst index 77726fd81..4da8d4d5b 100644 --- a/docs/tutorial/nullable.rst +++ b/docs/tutorial/nullable.rst @@ -6,7 +6,7 @@ Nullable variable Now in this section we would like to make it possible that it is not necessary to specify a value for a variable. - With rougail, it is possible for a variable's setttings to have no value (nothing, null, None), + With Rougail, it is possible for a variable's settings to have no value (nothing, null, None), that is, neither a default value nor a user assigned value. .. prerequisites:: Prerequisites @@ -31,9 +31,8 @@ Nullable variable Variable with the value "null" ------------------------------------ - .. note:: It is important to keep in mind that in Rougail a variable is :term:`mandatory` by default, - meaning that it must either have a :term:`default value` set or a :term:`user data` value assigned in the :term:`user data file`\ . + meaning that it must either have a :term:`default value` set or a :term:`user data` value assigned for example in a :term:`user data file`\ . This is Rougail's default behavior. Besides, note that the explicit keyword to express the setting "no value, nothing" in YAML is the `null` explicit keyword. @@ -42,9 +41,9 @@ Here is how we are going to specify a "no value" (nothing, `null`) as a possible There are a few things to set in the variable. We need to: -- explicitely disable the default :term:`mandatory` behavior of the `address` variable(just by setting it to `false`), +- explicitely disable the default :term:`mandatory` behavior of the `address` variable (just by setting it to `false`), - redefine the `address` variable inside the `socks_proxy` because this family uses the `proxy` type definition, -- finally set the `address` default value to `null`. +- finally removes the `address` default value as determined in the `proxy` type definition. .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_090/firefox/20-manual.yml :language: yaml @@ -122,7 +121,7 @@ Variables disabled when condition is null But actually, why did we want a variable to be non-mandatory? -Well, what we want is we need to be able to :term:`disable ` either the `port` and the `version` in case of the `address` has no value set: +Well, what we need is to be able to :term:`disable ` either the `port` and the `version` in case of the `address` has no value set: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_091/firefox/20-manual.yml :language: yaml @@ -184,13 +183,23 @@ For the `disabled` property to trigger, the condition `when: null` must appear, pointing to the `_.address` variable, that is the `socks_proxy.address` variable. +.. note:: The `_.` notation means the current path (of the current family). + + As we are in the `socks_proxy` family, we can say:: + + _.address == socks_proxy.address + .. keypoints:: Key points - We learned how to define a variable as having no value; it's possible with Rougail. - It's `default: null` and `mandatory: false`. + As one of the main objectives of Rougail is to determine if a variable has a value, + therefore the value of a variable is in principle *required*. + We say that a value is :term:`mandatory` by default. + However, it is possible to change this default behavior with the `mandatory: false` parameter + explicitely declared in a variable. + In this section we learned how to define a variable as having no value; it's possible with Rougail. - We also learned to continue using type redefinition, which we learned in the previous section. - And have continued to :term:`disable ` a variable depending this on + In this section we also continued using some type redefinition, which we learned in the previous section. + And we have :term:`disabled` a variable depending this on the presence or absence of a value.