Issue/6409 improve language reference documentation

changelogs/unreleased/6409-improve-language-reference-documentation.yml

@@ -0,0 +1,4 @@
+description: Add language reference documentation.
+issue-nr: 6409
+change-type: patch
+destination-branches: [master, iso6]

docs/language.rst

@@ -177,6 +177,122 @@ Lists of primitive types are also primitive types: ``string[]``, ``number[]``, `
     # incorrect, can't assign to dict after construction
     # a["otherkey"] = "othervalue"
 
+Strings
++++++++
+
+
+There are four kinds of strings in the Inmanta language:
+
+- regular strings
+
+.. code-block:: inmanta
+
+    regular_string_1 = "This is...\n...a basic string."
+
+    # Expected output e.g. when displayed:
+    # This is...
+    # ...a basic string.
+
+
+    regular_string_2 = 'This one too.'
+
+    # Expected output e.g. when displayed:
+    # This one too.
+
+- multi-line strings
+
+It is possible to make a string span multiple lines by triple quoting it e.g.:
+
+.. code-block:: inmanta
+
+    multi_line_string = """This
+    string
+    spans
+    multiple
+    lines"""
+
+    # Expected output e.g. when displayed:
+    # This
+    # string
+    # spans
+    # multiple
+    # lines
+
+.. note::
+    Unlike python's multi-line strings, only double quotes are supported to define a multi-line string i.e. ``"""`` is
+    valid, but ``'''`` is not.
+
+- raw strings
+
+Raw strings are similar to python's raw strings in that they treat backslashes as regular characters.
+On the other hand, in regular and multi-line strings, escape characters (e.g. ``\n``, ``\t``...) are interpreted and
+therefore backslashes need to be escaped in order to be displayed.
+
+.. code-block:: inmanta
+
+    raw_string = r"This is...\n...a raw string."
+
+    # Expected output e.g. when displayed:
+    # This is...\n...a raw string.
+
+
+
+.. _language_reference_string_formatting:
+
+- f-strings
+
+
+An alternative syntax similar to python's `f-strings <https://peps.python.org/pep-3101/>`_ can be used for string formatting.
+
+.. code-block:: inmanta
+
+    hostname = "serv1.example.org"
+    motd = f"Welcome to {hostname}"
+
+    # Expected output e.g. when displayed:
+    # Welcome to serv1.example.org
+
+
+Python's format specification `mini-language <https://docs.python.org/3.9/library/string.html#format-specification-mini-language>`_
+can be used for fine-grained formatting:
+
+.. code-block:: inmanta
+
+    width = 10
+    precision = 2
+    arg = 12.34567
+
+    std::print(f"result: {arg:{width}.{precision}f}")
+
+    # Expected output:
+    # result:      12.35
+
+.. note::
+    The \'=\' character specifier added in `python 3.8 <https://docs.python.org/3/whatsnew/3.8.html#f-strings-support-for-self-documenting-expressions-and-debugging>`_ is not supported yet in the Inmanta language.
+
+.. note::
+    Unlike in python, raw and format string cannot be used together in the same string e.g.
+    ``raw_and_format = rf"Both specifiers"`` is not allowed.
+
+
+.. _language_reference_string_interpolation:
+
+String interpolation
+####################
+
+An alternative syntax to f-strings is string interpolation. It allows variables to be included as parameters inside
+a regular or multi-line string. The included variables are resolved in the lexical scope of the string they are
+included in:
+
+
+.. code-block:: inmanta
+
+    hostname = "serv1.example.org"
+    motd = "Welcome to {{hostname}}"
+
+    # Expected output e.g. when displayed:
+    # Welcome to serv1.example.org
+
 
 .. _lang-conditions:
 
@@ -384,7 +500,7 @@ any values to the relation attribute.
     // adding a value twice does not affect the relation,
     // s1.files still equals [f1, f2, f3]
 
-In addition, attributes can be assigned in a constructor using keyword arguments by using `**dct` where `dct` is a dictionary that contains
+In addition, attributes can be assigned in a constructor using keyword arguments by using ``**dct`` where ``dct`` is a dictionary that contains
 attribute names as keys and the desired values as values. For example:
 
 .. code-block:: inmanta
@@ -395,6 +511,22 @@ attribute names as keys and the desired values as values. For example:
     file1_config = {"path": "/opt/1"}
     f1 = File(host=h1, **file1_config)
 
+It is also possible to add elements to a relation with the ``+=`` operator:
+
+.. code-block:: inmanta
+
+    Host.files [0:] -- File.host [1]
+
+    h1 = Host("test")
+    h1.files += f1
+    h1.files += f2
+    h1.files += f3
+
+    // h1.files equals [f1, f2, f3]
+
+
+.. note::
+    This syntax is only defined for relations. The ``+=`` operator can not be used on variables, which are immutable.
 
 Referring to instances
 ++++++++++++++++++++++
@@ -436,10 +568,11 @@ When nesting constructors, short names can be used for the nested constructors,
         )
     )
 
-However, when relying on type inference,
+However, when relying on type inference:
+
 1. avoid creating sibling types with the same name, but different fully qualified name, as they may become indistinguishable, breaking the inference on existing models.
 
-    1. if multiple types exist with the same name, and one is in scope, that one is selected (i.e it is defined in this module, a parent module or `std`)
+    1. if multiple types exist with the same name, and one is in scope, that one is selected (i.e. it is defined in this module, a parent module or ``std``)
     2. if multiple types exist that are all out of scope, inference fails
 
 2. make sure the type you want to infer is imported somewhere in the model. Otherwise the compiler will not find it.
@@ -657,58 +790,6 @@ At the lowest level of abstraction the configuration of an infrastructure often
 configuration files. To construct configuration files, templates and string interpolation can be used.
 
 
-String interpolation
-++++++++++++++++++++
-
-String interpolation allows variables to be included as parameters inside a string.
-
-The included variables are resolved in the lexical scope of the string they are included in.
-
-Interpolating strings
-
-.. code-block:: inmanta
-
-    hostname = "serv1.example.org"
-    motd = "Welcome to {{hostname}}\n"
-
-To prevent string interpolation, use raw strings
-
-.. code-block:: inmanta
-
-    # this string will go into the variable as is
-    # containing the {{ and \n
-    motd = r"Welcome to {{hostname}}\n"
-
-
-String formatting
-+++++++++++++++++
-
-An alternative syntax similar to python's `f-strings <https://peps.python.org/pep-3101/>`_ can be used for string formatting.
-
-Formatting strings
-
-.. code-block:: inmanta
-
-    hostname = "serv1.example.org"
-    motd = f"Welcome to {hostname}\n"
-
-Python's format specification `mini-language <https://docs.python.org/3.9/library/string.html#format-specification-mini-language>`_
-can be used for fine-grained formatting:
-
-.. code-block:: inmanta
-
-    width = 10
-    precision = 2
-    arg = 12.34567
-
-    std::print(f"result: {arg:{width}.{precision}f}")
-
-    # Expected output:
-    # "result:      12.35"
-
-.. note::
-    The \'=\' character specifier added in `python 3.8 <https://docs.python.org/3/whatsnew/3.8.html#f-strings-support-for-self-documenting-expressions-and-debugging>`_ is not supported yet in the Inmanta language.
-
 Templates
 +++++++++
 

src/inmanta/protocol/methods_v2.py

@@ -1309,11 +1309,13 @@ def get_environment_metrics(
     :param end_interval: The end of the time window for which the metrics should be returned.
     :param nb_datapoints: The amount of datapoint that will be returned within the given time interval for each metric.
     :param round_timestamps: If this parameter is set to True, the timestamps in the reply will be rounded to a full hour.
-                             All time windows in the reply will have an equal size. To achieve this the start_interval,
-                             end_interval and nb_datapoint in the reply may differ from the ones requested.
-                               * The start_interval may be smaller than requested
-                               * The end_interval may be larger than requested
-                               * The nb_datapoints may be larger than requested
+        All time windows in the reply will have an equal size. To achieve this the start_interval, end_interval and
+        nb_datapoint in the reply may differ from the ones requested.
+
+            * The start_interval may be smaller than requested
+            * The end_interval may be larger than requested
+            * The nb_datapoints may be larger than requested
+
     :raises BadRequest: start_interval >= end_interval
     :raises BadRequest: nb_datapoints < 0
     :raises BadRequest: The provided metrics list is an empty list.