From 4bb50361d5921083cef2d644427350d76109c358 Mon Sep 17 00:00:00 2001
From: Emmanuel Garette <egarette@silique.fr>
Date: Sun, 26 Oct 2025 14:31:48 +0100
Subject: [PATCH] feat: tags

---
 docs/index.rst         |   1 +
 docs/library/index.rst |   1 +
 docs/library/tags.rst  | 111 +++++++++++++++++++++++++++++++++++++++++
 docs/tags.rst          |  34 +++++++++++++
 docs/variable.rst      |   6 ++-
 5 files changed, 152 insertions(+), 1 deletion(-)
 create mode 100644 docs/library/tags.rst
 create mode 100644 docs/tags.rst

diff --git a/docs/index.rst b/docs/index.rst
index f12675523..370e8fc62 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -62,6 +62,7 @@ Explained differently, Rougail allows you to easily implement an integration of
 
    variable
    family
+   tags
    fill
    Value checks <check>
    condition
diff --git a/docs/library/index.rst b/docs/library/index.rst
index b2f37f1ce..66cc7fced 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -74,6 +74,7 @@ The Rougail CLI can output a rather complete view of the dataset:
    :caption: Use library
 
    parse
+   tags
    rougailconfig_load_from_cli
    extra
    custom_function
diff --git a/docs/library/tags.rst b/docs/library/tags.rst
new file mode 100644
index 000000000..ce3f4ed29
--- /dev/null
+++ b/docs/library/tags.rst
@@ -0,0 +1,111 @@
+Use tag informations
+====================
+
+When we set tags for a variable, it will add :term:`Tiramisu` properties and informations.
+
+We can filter those variables easily with tags.
+
+First of all, create our structural file:
+
+.. code-block:: yaml
+   :caption: the :file:`dist/00-base.yml` file content
+
+    %YAML 1.2
+    ---
+    version: 1.1
+
+    infra_name: my infra   # Name of this infrastructure
+
+    server1:  # the first server
+
+      internal_domain:
+        description: Server domaine name
+        type: domainname
+        tags:
+          - internal
+
+      external_domain:
+        description: Domain name to access to this server for Internet
+        type: domainname
+        tags:
+          - external
+
+    server2:  # the second server
+
+      address:
+        description: Server domaine name
+        type: domainname
+        tags:
+          - internal
+    ...
+
+Exclude variables with a specific tag
+-------------------------------------
+
+To exclude variables with a specific tag is very easy. When the variable has tags, properties with same name are automaticly create.
+So exclude a tag means exclude variable with a particular property.
+
+In this example we exclude variable with "internal" tag and display result of "server1" family:
+
+.. code-block:: python
+    :caption: the :file:`script.py` file content
+
+    from rougail import Rougail, RougailConfig
+    from pprint import pprint
+
+    RougailConfig['main_namespace'] = None
+    RougailConfig['main_structural_directories'] = ['dist']
+    rougail = Rougail()
+    config = rougail.run()
+    print("without filter:")
+    pprint(config.option("server1").value.get())
+    config.property.add('internal')
+    print("with filter:")
+    pprint(config.option("server1").value.get())
+
+Let's execute `script.py`:
+
+.. code-block:: bash
+
+    $ python3 script.py 
+    without filter:
+    {<TiramisuOption path="server1.external_domain">: None,
+     <TiramisuOption path="server1.internal_domain">: None}
+    with filter:
+    {<TiramisuOption path="server1.external_domain">: None}
+
+Only variable with a specific tag
+---------------------------------
+
+It's more difficult to see only variable with a specific tag.
+
+We have to walk through the configuration and retrieve variable with the selected tag.
+Tags are in properties but, are in information too.
+
+Here is a smal script that walk that the configuration and "print" option with "internal" tag:
+
+.. code-block:: python
+    :caption: the :file:`script.py` file content
+
+    from rougail import Rougail, RougailConfig
+    
+    RougailConfig['main_structural_directories'] = ['dist']
+    rougail = Rougail()
+    config = rougail.run()
+    
+    def walk(config):
+        for option in config:
+            if option.isoptiondescription():
+                walk(option)
+            elif "internal" in option.information.get('tags', []):
+                print(option.description())
+
+    if __name__ == '__main__':
+        walk(config)
+
+Let's execute `script.py`:
+
+.. code-block:: bash
+    $ python3 script.py 
+    server1.internal_domain (Server domaine name)
+    server2.address (Server domaine name)
diff --git a/docs/tags.rst b/docs/tags.rst
new file mode 100644
index 000000000..e5cd7bc46
--- /dev/null
+++ b/docs/tags.rst
@@ -0,0 +1,34 @@
+The variable tags
+==================
+
+A tag allows you to specialize a variable.
+
+A tag can have several functions:
+
+- Additional information in the documentation
+- Variable exclusion
+- Variable selection
+- ...
+
+Tags are only available for variable.
+
+Here is an example:
+
+.. code-block:: yaml
+
+    %YAML 1.2
+    ---
+    version: 1.1
+
+    internal_domain:
+      description: Server domaine name
+      type: domainname
+      tags:
+        - internal
+
+    external_domain:
+      description: Domain name to access to this server for Internet
+      type: domainname
+      tags:
+        - external
+    ...
diff --git a/docs/variable.rst b/docs/variable.rst
index 4fb61257b..a79bfe7ce 100644
--- a/docs/variable.rst
+++ b/docs/variable.rst
@@ -52,12 +52,16 @@ If you add a comment in the same line of the name, this comment will be used has
 
 .. code-block:: yaml
 
+    %YAML 1.2
     ---
-    version: '1.1'
+    version: 1.1
+
     my_variable: 1  # This is a great integer variable
+
     my_multi_variable:  # This is a great multi string variable
       - value1
       - value2
+    ...
 
 Parameters
 -------------