dictionary -> structure file
This commit is contained in:
gwen
parent
0f0d955e9f
commit
10a25b0cfe
6 changed files with 43 additions and 44 deletions
|
|
@ -1,16 +1,16 @@
|
|||
The dictionaries
|
||||
The structure files
|
||||
=====================
|
||||
|
||||
What do you mean by :term:`dictionary`?
|
||||
What do you mean by :term:`structure file`?
|
||||
-------------------------------------------
|
||||
|
||||
A :term:`dictionary` is a YAML file whose structure is described in this documentation page.
|
||||
A :term:`structure file` is a YAML file whose structure is described in this documentation page.
|
||||
|
||||
A dictionary contains a set of variables loaded into :term:`Tiramisu`, usable at any time, especially in a :term:`templates`.
|
||||
A structure file contains a set of variables loaded into :term:`Tiramisu`, usable at any time, especially in a :term:`templates`.
|
||||
|
||||
:term:`Families` and :term:`variables` can be defined in several dictionaries. These dictionaries are then aggregated.
|
||||
:term:`Families` and :term:`variables` can be defined in several structure files. These structure files are then aggregated.
|
||||
|
||||
Dictionaries are loaded in the directory order defined by the `dictionaries_dir` configuration parameter.
|
||||
Structure files are loaded in the directory order defined by the `dictionaries_dir` configuration parameter.
|
||||
Each directory is loaded one after the other.
|
||||
Inside these directories the YAML files will be classified in alphabetical order.
|
||||
|
||||
|
|
@ -21,11 +21,11 @@ It is also possible to :term:`redefine` elements to change the behavior of a fam
|
|||
The default namespace
|
||||
-------------------------
|
||||
|
||||
The families and variables contained in these dictionaries are ordered, by default, in the `rougail` namespace. It is possible to change the name of this namespace with the :term:`variable namespace <variable_namespace>` parameter of the :doc:`configuration <configuration>`.
|
||||
The families and variables contained in these structure files are ordered, by default, in the `rougail` namespace. It is possible to change the name of this namespace with the :term:`variable namespace <variable_namespace>` parameter of the :doc:`configuration <configuration>`.
|
||||
|
||||
This namespace is a bit special, it can access variables in another namespace.
|
||||
|
||||
The extra dictionaries
|
||||
The extra structure files
|
||||
---------------------------
|
||||
|
||||
An extra is a different namespace. The idea is to be able to classify the variables by theme.
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ What is a consistency handling system ?
|
|||
Here is the :xref:`tiramisu library`.
|
||||
|
||||
In the Rougail scope, we call it :term:`variable`\ s and :term:`families`.
|
||||
In Rougail, the families and variables are located in the :term:`structure files <dictionaries>`.
|
||||
In Rougail, the families and variables are located in the :term:`structure files <structure file>`.
|
||||
|
||||
The structure files
|
||||
---------------------
|
||||
|
|
@ -92,7 +92,7 @@ You can see that there is just a `version` specification.
|
|||
The variables
|
||||
-----------------
|
||||
|
||||
Here is a :term:`structure file <dictionary>` example with a variable into it:
|
||||
Here is a :term:`structure file` example with a variable into it:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
|
||||
:language: yaml
|
||||
|
|
|
|||
|
|
@ -14,14 +14,14 @@ To load the configuration you must import the `RougailConfig` class and set the
|
|||
|
||||
RougailConfig['dictionaries_dir'] = ['dict']
|
||||
|
||||
Let's convert a dictionary
|
||||
-----------------------------
|
||||
Let's convert a structure file
|
||||
-------------------------------
|
||||
|
||||
As a reminder, a :term:`dictionary` is a set of instructions that will allow us to create :term:`families` and :term:`variables`.
|
||||
As a reminder, a :term:`structure file` is a set of instructions that will allow us to create :term:`families` and :term:`variables`.
|
||||
|
||||
Let's start by creating a simple dictionary.
|
||||
Let's start by creating a simple structure file.
|
||||
|
||||
Here is a first :file:`dict/00-base.yml` dictionary:
|
||||
Here is a first :file:`dict/00-base.yml` structure file:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -68,8 +68,8 @@ The Rougail CLI can output a rather complete view of the dataset:
|
|||
|
||||
.. image:: images/UserDataOutput.png
|
||||
|
||||
Let's convert an extra dictionary
|
||||
-------------------------------------
|
||||
Let's convert an extra structure file
|
||||
---------------------------------------
|
||||
|
||||
.. index:: extras
|
||||
|
||||
|
|
@ -85,7 +85,7 @@ For example, here's how to add an `example` namespace:
|
|||
|
||||
RougailConfig['extra_dictionaries']['example'] = ['extras/']
|
||||
|
||||
Then let's create an extra :term:`dictionary` :file:`extras/00-base.yml`:
|
||||
Then let's create an extra :term:`structure file` :file:`extras/00-base.yml`:
|
||||
|
||||
.. code-block:: yaml
|
||||
:caption: the :file:`extras/00-base.yml` file content
|
||||
|
|
@ -117,7 +117,7 @@ Let's execute `script.py`:
|
|||
Let's create a custom function
|
||||
----------------------------------
|
||||
|
||||
We create the complementary :term:`dictionary` named :file:`dict/01-function.yml` so that the `my_variable_jinja` variable is :term:`calculated`:
|
||||
We create the complementary :term:`structure file` named :file:`dict/01-function.yml` so that the `my_variable_jinja` variable is :term:`calculated`:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -195,7 +195,7 @@ To add the new lipogram type in Rougail:
|
|||
>>> RougailConfig['custom_types']['lipogram'] = LipogramOption
|
||||
|
||||
Now, we can use lipogram type.
|
||||
Here is a :file:`dict/00-base.yml` dictionary:
|
||||
Here is a :file:`dict/00-base.yml` structure file:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -219,7 +219,7 @@ Upgrade dictionnaries to upper version
|
|||
All dictionnaries has a format version number.
|
||||
When a new format version is proposed, it is possible to automatically convert the files to the new version.
|
||||
|
||||
We create a term:`dictionary` named :file:`dict/01-upgrade.yml` with version 1.0:
|
||||
We create a term:`structure file` named :file:`dict/01-upgrade.yml` with version 1.0:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -240,7 +240,7 @@ We create a term:`dictionary` named :file:`dict/01-upgrade.yml` with version 1.0
|
|||
>>> upgrade = RougailUpgrade()
|
||||
>>> upgrade.load_dictionaries('dict_converted')
|
||||
|
||||
The term:`dictionary` named :file:`dict_converted/01-upgrade.yml` is in version 1.1:
|
||||
The term:`structure file` named :file:`dict_converted/01-upgrade.yml` is in version 1.1:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
|
|||
|
|
@ -5,8 +5,8 @@ Preliminaries
|
|||
|
||||
We will learn how to:
|
||||
|
||||
- create a Rougail :term:`structure description file <dictionary>`
|
||||
- define a Rougail :term:`structure description file <dictionary>` format version
|
||||
- create a Rougail :term:`structure description file <structure file>`
|
||||
- define a Rougail :term:`structure description file <structure file>` format version
|
||||
- define a Rougail :term:`variable` and set its :term:`value`
|
||||
|
||||
.. prerequisites:: Prerequisites
|
||||
|
|
@ -26,7 +26,7 @@ Preliminaries
|
|||
│ └── struct.yml
|
||||
|
||||
- Let's make a :file:`workplace` directory, with a :file:`firefox` subfolder.
|
||||
- First, we wil make a :term:`structure file <dictionary>`, so let's create a :file:`struct.yml` file
|
||||
- First, we wil make a :term:`structure file <structure file>`, so let's create a :file:`struct.yml` file
|
||||
located in the :file:`firefox` subfolder.
|
||||
|
||||
The structure file
|
||||
|
|
@ -37,7 +37,7 @@ This is an empty Rougail dictionnary
|
|||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
|
||||
:language: yaml
|
||||
:caption: An empty rougail dictionnary file with the version number only
|
||||
:name: RougailDictionaryEmptyFile
|
||||
:name: RougailStructVersion
|
||||
|
||||
..
|
||||
---
|
||||
|
|
@ -45,8 +45,7 @@ This is an empty Rougail dictionnary
|
|||
|
||||
.. type-along:: a first variable
|
||||
|
||||
Let's put a variable in the Rougail :term:`structure description file <dictionary>`
|
||||
|
||||
Let's put a variable in the Rougail :term:`structure description file <structure file>`
|
||||
|
||||
Defining a variable and its default value
|
||||
----------------------------------------------
|
||||
|
|
@ -101,7 +100,7 @@ Then we just add a variable's description, which is a good practice.
|
|||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/firefox/00-proxy.yml
|
||||
:language: yaml
|
||||
:caption: A Rougail dictionnary file with a variable and a description
|
||||
:name: RougailDictionaryFirstVariableDescription
|
||||
:name: RougailStructFirstVariableDescription
|
||||
|
||||
..
|
||||
---
|
||||
|
|
@ -144,7 +143,7 @@ So far we have only talked about the one that writes the structure files. It is
|
|||
|
||||
integrator
|
||||
|
||||
An integrator in the Rougail logic is the person who writes the :term:`structure files <dictionaries>`\ .
|
||||
An integrator in the Rougail logic is the person who writes the :term:`structure files <structure file>`\ .
|
||||
He has the responsibilité of the integration process, that is,
|
||||
defines the variables and the relationship between them, the variables that are allowed
|
||||
(or not) to be set, and so on. His responsabilites are the **structuration** and the **consistency**
|
||||
|
|
@ -159,7 +158,7 @@ Now we will talk about the one that defines the values. It is called the operato
|
|||
An operator ih the Rougail logic is the person who gives :term:`value`\ s to the pre-defined variables,
|
||||
his responsabilities are to set variable values correctly.
|
||||
|
||||
The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated by the :term:`structure file definition <dictionary>`.
|
||||
The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated by the :term:`structure file definition <structure file>`.
|
||||
|
||||
Values are mandatory
|
||||
-------------------------
|
||||
|
|
@ -309,7 +308,7 @@ We have the list of the possible (authorized) values:
|
|||
|
||||
**Keywords**
|
||||
|
||||
- :term:`structure file <dictionary>`: structure description file
|
||||
- :term:`structure file <structure file>`: structure description file
|
||||
- :term:`variable`: an option's name which has a value
|
||||
- a variable's description
|
||||
- a variable's type
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ The `proxy` family
|
|||
|
||||
.. type-along:: Reminders
|
||||
|
||||
- As a prerequisite we have an idea of what a :term:`structure file description <dictionary>` is.
|
||||
- As a prerequisite we have an idea of what a :term:`structure file description <structure file>` is.
|
||||
- We have a :file:`firefox` folder and we are putting all the structure description files in it.
|
||||
- We had at the :term:`structure description file <structure file>`
|
||||
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ Synopsis
|
|||
value
|
||||
|
||||
A value is a variable's setting.
|
||||
Variable can have a default value, that is a setting defined in the :term:`dictionary` structure,
|
||||
Variable can have a default value, that is a setting defined in the :term:`structure file`,
|
||||
or no value at all, then the value needs to be define later by the :term:`operator`.
|
||||
|
||||
.. discussion:: Discussion
|
||||
|
|
@ -161,7 +161,7 @@ Parameters
|
|||
* - **redefine**
|
||||
|
||||
`boolean`
|
||||
- It is possible to define a variable in one :term:`dictionary` and change its behavior in a second :term:`dictionary`. In this case you must explicitly redefine the variable.
|
||||
- It is possible to define a variable in one :term:`structure file` and change its behavior in a second :term:`structure file`. In this case you must explicitly redefine the variable.
|
||||
|
||||
**Default value**: `false`
|
||||
* - **exists**
|
||||
|
|
@ -169,14 +169,14 @@ Parameters
|
|||
`boolean`
|
||||
- This attribute does two things:
|
||||
|
||||
- creates a variable if it does not exist in another :term:`dictionary` (otherwise do nothing), in this case the value of the attribute must be `true`
|
||||
- creates a variable if it does not exist in another :term:`structure file` (otherwise do nothing), in this case the value of the attribute must be `true`
|
||||
- in conjunction with the `redefine` attribute set to `true`, only modifies the behavior if it is pre-existing, in which case the attribute's value must be `false`.
|
||||
|
||||
**Default value**: `null`
|
||||
* - **test**
|
||||
|
||||
`list`
|
||||
- The `test` attribute is a special attribute that allows :term:`dictionary` designers to influence a test robot by specifying useful values to test.
|
||||
- The `test` attribute is a special attribute that allows :term:`structure file` designers to influence a test robot by specifying useful values to test.
|
||||
|
||||
Concretely, the content of this attribute is recorded in the `information` attribute of the corresponding `Tiramisu` option object.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue