74 lines
2.3 KiB
ReStructuredText
74 lines
2.3 KiB
ReStructuredText
Naming convention
|
|
=====================
|
|
|
|
.. _filenamingconvention:
|
|
|
|
File naming convention
|
|
--------------------------
|
|
|
|
The structure files in a given folder
|
|
''''''''''''''''''''''''''''''''''''''''''
|
|
|
|
For the sake of clarity, we put the structure definitions in separate files.
|
|
It's a good way to organize your rougail structures this way,
|
|
in the real world we need separate files for different topics.
|
|
|
|
For example some files like this:
|
|
|
|
A file named :file:`firefox/00-proxy.yml` structure file and file named :file:`firefox/10-manual.yml`
|
|
|
|
::
|
|
|
|
.
|
|
└── firefox
|
|
├── 00-proxy.yml
|
|
└── 10-manual.yml
|
|
|
|
.. note:: We of course could have put everything in one file.
|
|
Again, it is better to separate the structures in different files
|
|
for reasons of ordering and clarity.
|
|
|
|
Ordering your structure files
|
|
'''''''''''''''''''''''''''''''''
|
|
|
|
The order in which files are loaded is important in Rougail.
|
|
In a given folder, files are loaded in alphabetical order.
|
|
|
|
Furthermore, for better readability of the order in which files are
|
|
loaded into a folder, we have adopted a convention.
|
|
To facilitate classification, we have defined a standard notation for structure file names:
|
|
|
|
::
|
|
|
|
XX-<name>.yml
|
|
|
|
Where `XX` is a two digits integer followed by an hyphen, and `<name>` is a name that describes
|
|
the structure that is in this file. We advise you to adopt this convention as well.
|
|
|
|
File naming convention
|
|
'''''''''''''''''''''''''''''
|
|
|
|
The is no restriction to the `<name>` name part of file name. But it is preferable to only use
|
|
lowercase ASCII letters, numbers and the `"_"` (undescore) character.
|
|
|
|
.. _namingconvention:
|
|
|
|
Variable and family naming convention
|
|
---------------------------------------
|
|
|
|
The name of a variable and a family must be chosen carefully.
|
|
It is the path that will allow users to retrieve their defined values.
|
|
An obscure name will cause confusion.
|
|
|
|
By design, you cannot use just any character to name your variable.
|
|
|
|
The regular expression that validates our variable and family naming policy is:
|
|
|
|
.. code-block:: python
|
|
|
|
re.compile(r"^[a-z0-9_]*$")
|
|
|
|
You can see that it is mandatory to only use lowercase ASCII letters, numbers and the `"_"` (undescore) character.
|
|
The snake case typographic convention is therefore used.
|
|
|
|
.. attention:: The name must not starts with `_` character.
|