.. _namingconvention:

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.

.. _filenamingconvention:

Generic file naming policy
---------------------------

Here are our generic file naming conventions.

The regular expression that validates our file naming policy is:

.. code-block:: python

    NAME_REGEXP = re.compile(r"^[a-z0-9_]*$")

You can see that it is preferable to only use lowercase ASCII letters, numbers and the `"_"` (undescore) character. 
The snake case typographic convention is therefore used.

Dynamically built family naming policy
------------------------------------------

Regarding the :ref:`dynamically built families <dynfam>` the file naming policy is slightly different.
ASCII letters, numbers and the `"_"` (undescore) character are allowed, that is we allow uppercase characters.

Why allowing uppercase letters for a dynamic familly? 
Because we have choosed to write :term:`identifiers <identifier>` in uppercase.

.. note:: The identifier is in uppercase, but the dynamic familly name is in lowercase. 
          You can then choose the corresponding structure filenames in lowercase.

.. seealso:: For more information about dynamic famillies, please have a look at the 
             :ref:`dynamic family tutorial <dynfam>`