From 95f9e18dd6e39a162d2690deba3c24933593f339 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Del=20Pino?= <stephane.delpino44@gmail.com>
Date: Sat, 21 May 2022 12:13:54 +0200
Subject: [PATCH] Improve user doc

Begin description of operators
---
 doc/userdoc.org | 294 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 284 insertions(+), 10 deletions(-)

diff --git a/doc/userdoc.org b/doc/userdoc.org
index d6d9c3fb0..4c2bc1352 100644
--- a/doc/userdoc.org
+++ b/doc/userdoc.org
@@ -617,6 +617,45 @@ This may sound strange but there are few reasons for that.
   nature in some sense .
 #+END_note
 
+**** Expression types
+
+The interpreter gives type to some special expressions.
+- special boolean (type ~B~) expressions. Two *keywords* allow to define
+  boolean values: ~true~ and ~false~.
+- Integers (type ~Z~) are defined as a contiguous list of digits.
+  - For instance, the code ~0123~ is interpreted as the integer $123$.
+  - However the sequence ~123 456~ is *not interpreted* as $123456$ but as
+    the two integers $123$ and $456$.
+- Real values (type ~R~) use the same syntax as in ~C++~. For instance,
+  the following expressions are accepted to define the number $1.23$.
+#+BEGIN_SRC pugs :exports both
+  1.23;
+  0.123E1;
+  .123e+1;
+  123e-2;
+  12.3E-1;
+#+END_SRC
+- ~string~ values are defined as the set of characters enclosed between
+  two double quotes ( ~"~ ). The string /Hello world!/ would be simply
+  written as ~"Hello world!"~. Strings support the following escape
+  sequences (similarly to ~C++~):
+  | escape | meaning         |
+  |--------+-----------------|
+  | ~\'~     | single quote    |
+  | ~\"~     | double quote    |
+  | ~\?~     | question mark   |
+  | ~\\~     | backslash       |
+  | ~\a~     | audible bell    |
+  | ~\b~     | backspace       |
+  | ~\f~     | new page        |
+  | ~\n~     | new line        |
+  | ~\r~     | carriage return |
+  | ~\t~     | horizontal tab  |
+  | ~\v~     | vertical tab    |
+  These special character are not interpreted by ~pugs~ itself but
+  interpreted by the system when an output is created. They are just
+  allowed in the definition of a ~string~.
+
 **** Variables of basic types are stored by value
 
 This means that each variable of basic type allocates its own memory
@@ -721,6 +760,240 @@ affectations are /instructions/.
 
 #+END_note
 
+***** List of defined operator ~=~ for basic types.
+
+As already mentioned, operator ~=~ is defined for *all* types in ~pugs~ if
+the right hand side expression has the *same* type as the left hand side
+variable. This is true for basic types as well as for high-level
+types. We now give the complete list of supported ~=~ affectations. The
+lists are sorted by type of left hand side variable.
+
+- ~B~: boolean left hand side variable. One is only allowed to affect boolean
+  values.
+  | allowed expression type |
+  |-------------------------|
+  | ~B~                       |
+
+- ~N~: natural integer ($\mathbb{N}$ or $\mathbb{Z}_{\ge0}$) left hand side variable.
+  | allowed expression type |
+  |-------------------------|
+  | ~B~                       |
+  | ~N~                       |
+  | ~Z~  (for convenience)    |
+
+- ~Z~: integer ($\mathbb{Z}$) left hand side variable.
+  | allowed expression type |
+  |-------------------------|
+  | ~B~                       |
+  | ~N~                       |
+  | ~Z~                       |
+
+- ~R~: real ($\mathbb{R}$) left hand side variable.
+  | allowed expression type |
+  |-------------------------|
+  | ~B~                       |
+  | ~N~                       |
+  | ~Z~                       |
+  | ~R~                       |
+
+- ~R^1~: vector of dimension 1 ($\mathbb{R}^1$) left hand side variable.
+  | allowed expression type |
+  |-------------------------|
+  | ~B~                       |
+  | ~N~                       |
+  | ~Z~                       |
+  | ~R~                       |
+  | ~R^1~                     |
+
+- ~R^2~: vector of dimension 2 ($\mathbb{R}^2$) left hand side variable.
+  | allowed expression type                     |
+  |---------------------------------------------|
+  | ~R^2~                                         |
+  | ~0~  (special value)                          |
+  | list of 2 scalar (~B~, ~N~, ~Z~ or ~R~) expressions |
+  An example of initialization using a list or the special value ~0~ is
+  #+NAME: affectation-to-R2-from-list
+  #+BEGIN_SRC pugs :exports both :results output
+    let u:R^2, u = (-3, 2.5);
+    let z:R^2, z = 0;
+    cout << "u = " << u << "\n";
+    cout << "z = " << z << "\n";
+  #+END_SRC
+  which produces
+  #+RESULTS: affectation-to-R2-from-list
+  Observe that ~0~ is a special value and *treated as a keyword*. There is no conversion from
+  integer values. For instance:
+  #+NAME: R2-invalid-integer-affectation
+  #+BEGIN_SRC pugs-error :exports both :results output
+    let z:R^2, z = 1-1;
+  #+END_SRC
+  produces the compilation error
+  #+results: R2-invalid-integer-affectation
+
+- ~R^3~: vector of dimension 3 ($\mathbb{R}^3$) left hand side variable.
+  | allowed expression type                     |
+  |---------------------------------------------|
+  | ~R^3~                                       |
+  | ~0~  (special value)                          |
+  | list of 3 scalar (~B~, ~N~, ~Z~ or ~R~) expressions |
+  An example of initialization using a list is
+  #+NAME: affectation-to-R3-from-list
+  #+BEGIN_SRC pugs :exports both :results output
+    let u:R^3, u = (-3, 2.5, 1E-2);
+    let z:R^3, z = 0;
+    cout << "u = " << u << "\n";
+    cout << "z = " << z << "\n";
+  #+END_SRC
+  the output is
+  #+RESULTS: affectation-to-R3-from-list
+
+- ~R^1x1~: matrix of dimensions $1\times1$ ($\mathbb{R}^1\times1$) left hand side variable.
+  | allowed expression type |
+  |-------------------------|
+  | ~B~                       |
+  | ~N~                       |
+  | ~Z~                       |
+  | ~R~                       |
+  | ~R^1x1~                   |
+
+- ~R^2x2~: matrix of dimension $2\times2$ ($\mathbb{R}^2x2$) left hand side variable.
+  | allowed expression type                     |
+  |---------------------------------------------|
+  | ~R^2x2~                                       |
+  | ~0~  (special value)                          |
+  | list of 4 scalar (~B~, ~N~, ~Z~ or ~R~) expressions |
+  An example of initialization using a list or the special value ~0~ is
+  #+NAME: affectation-to-R2x2-from-list
+  #+BEGIN_SRC pugs :exports both :results output
+    let u:R^2x2, u = (-3, 2.5,
+                       4, 1.2);
+    let z:R^2x2, z = 0;
+    cout << "u = " << u << "\n";
+    cout << "z = " << z << "\n";
+  #+END_SRC
+  which produces
+  #+RESULTS: affectation-to-R2x2-from-list
+
+- ~R^3x3~: matrix of dimension $3\times3$ ($\mathbb{R}^3x3$) left hand side variable.
+  | allowed expression type                     |
+  |---------------------------------------------|
+  | ~R^3x3~                                       |
+  | ~0~  (special value)                          |
+  | list of 9 scalar (~B~, ~N~, ~Z~ or ~R~) expressions |
+  An example of initialization using a list is
+  #+NAME: affectation-to-R3x3-from-list
+  #+BEGIN_SRC pugs :exports both :results output
+    let u:R^3x3, u = (-3, 2.5, 1E-2,
+                       2, 1.7,   -2,
+                     1.2,   4,  2.3);
+    let z:R^3x3, z = 0;
+    cout << "u = " << u << "\n";
+    cout << "z = " << z << "\n";
+  #+END_SRC
+  the output is
+  #+RESULTS: affectation-to-R3x3-from-list
+
+- ~string~ left hand side variable. Expressions of any basic types can
+  be used as the right hand side.
+  | allowed expression type |
+  |-------------------------|
+  | ~B~                       |
+  | ~N~                       |
+  | ~Z~                       |
+  | ~R~                       |
+  | ~R^1~                     |
+  | ~R^2~                     |
+  | ~R^3~                     |
+  | ~R^1x1~                   |
+  | ~R^2x2~                   |
+  | ~R^3x3~                   |
+  | ~string~                  |
+
+***** List of defined operator ~+=~ for basic types.
+
+- ~B~: the ~+=~ operator is not defined for left hand side boolean
+  variables.
+
+- ~N~: natural integer ($\mathbb{N}$ or $\mathbb{Z}_{\ge0}$) left hand side variable.
+  | allowed expression type |
+  |-------------------------|
+  | ~B~                       |
+  | ~N~                       |
+  | ~Z~  (for convenience)    |
+
+- ~Z~: integer ($\mathbb{Z}$) left hand side variable.
+  | allowed expression type |
+  |-------------------------|
+  | ~B~                       |
+  | ~N~                       |
+  | ~Z~                       |
+
+- ~R~: real ($\mathbb{R}$) left hand side variable.
+  | allowed expression type |
+  |-------------------------|
+  | ~B~                       |
+  | ~N~                       |
+  | ~Z~                       |
+  | ~R~                       |
+
+- ~R^1~: vector of dimension 1 ($\mathbb{R}^1$) left hand side variable.
+  | allowed expression type |
+  |-------------------------|
+  | ~R^1~                     |
+
+- ~R^2~: vector of dimension 2 ($\mathbb{R}^2$) left hand side variable.
+  | allowed expression type                     |
+  |---------------------------------------------|
+  | ~R^2~                                         |
+
+- ~R^3~: vector of dimension 3 ($\mathbb{R}^3$) left hand side variable.
+  | allowed expression type                     |
+  |---------------------------------------------|
+  | ~R^3~                                         |
+
+- ~R^1x1~: matrix of dimensions $1\times1$ ($\mathbb{R}^1\times1$) left hand side variable.
+  | allowed expression type |
+  |-------------------------|
+  | ~R^1x1~                   |
+
+- ~R^2x2~: matrix of dimension $2\times2$ ($\mathbb{R}^2x2$) left hand side variable.
+  | allowed expression type                     |
+  |---------------------------------------------|
+  | ~R^2x2~                                       |
+
+- ~R^3x3~: matrix of dimension $3\times3$ ($\mathbb{R}^3x3$) left hand side variable.
+  | allowed expression type                     |
+  |---------------------------------------------|
+  | ~R^3x3~                                       |
+
+- ~string~ left hand side variable. Expressions of any basic types can
+  be used as the right hand side.
+  | allowed expression type |
+  |-------------------------|
+  | ~B~                       |
+  | ~N~                       |
+  | ~Z~                       |
+  | ~R~                       |
+  | ~R^1~                     |
+  | ~R^2~                     |
+  | ~R^3~                     |
+  | ~R^1x1~                   |
+  | ~R^2x2~                   |
+  | ~R^3x3~                   |
+  | ~string~                  |
+
+***** TODO List of defined operator ~-=~ for basic types.
+
+- ~B~: the ~-=~ operator is not defined for left hand side boolean variables.
+
+***** TODO List of defined operator ~*=~ for basic types.
+
+- ~B~: the ~*=~ operator is not defined for left hand side boolean variables.
+
+***** TODO List of defined operator ~/=~ for basic types.
+
+- ~B~: the ~/=~ operator is not defined for left hand side boolean variables.
+
 **** Unary operators
 
 The ~pugs~ language allows the following tokens as unary operators
@@ -743,8 +1016,9 @@ The ~+~ unary operator is a convenient operator that is *elided* when
 parsing the script.
 
 For basic types, when these operators are defined, they return a value
-of the same type as the argument. These operators can be defined for
-high-level types.
+of the same type as the argument (except if the argument is a ~N~, then
+the result is a ~Z~). These operators can be defined for high-level
+types.
 - The ~not~ operator is only defined for boolean values (~B~)
 - the ~-~ unary operator is defined for numeric basic types: ~B~,
   ~N~, ~Z~, ~R~, ~R^1~, ~R^2~, ~R^3~, ~R^1x1~, ~R^2x2~ and ~R^3x3~. It is not defined
@@ -771,7 +1045,7 @@ produces the compilation error
 Again, this is done to simplify the syntax and to avoid weird
 constructions.
 
-**** Binary operators
+**** TODO Binary operators
 
 Syntax for binary operators follows again a classical structure if
 ~exp1~ and ~exp2~ denotes two expressions and if ~op~ denotes a binary
@@ -808,9 +1082,9 @@ they follow a few rules.
     \begin{equation*}
       \left|
         \begin{array}{rl}
-          \mathtt{and}:&\quad \mathbb{B}\times \mathbb{B} \to \mathbb{B}\\
-          \mathtt{or}:& \quad\mathbb{B}\times \mathbb{B} \to \mathbb{B}\\
-          \mathtt{xor}:& \quad \mathbb{B}\times \mathbb{B} \to \mathbb{B}
+          \mathtt{and}:&\quad \mathbb{B} \times \mathbb{B} \to \mathbb{B}\\
+          \mathtt{or}:& \quad\mathbb{B} \times \mathbb{B} \to \mathbb{B}\\
+          \mathtt{xor}:& \quad \mathbb{B} \times \mathbb{B} \to \mathbb{B}
         \end{array}
       \right.
     \end{equation*}
@@ -844,10 +1118,10 @@ they follow a few rules.
       \forall d \in \{1,2,3\},\quad
       \left|
         \begin{array}{rl}
-          \mathtt{==}:& \mathbb{R}^d\times \mathbb{R}^d \to \mathbb{B}\\
-          \mathtt{==}:& \mathbb{R}^{d\times d} \times \mathbb{R}^{d\times d} \to \mathbb{B}\\
-          \mathtt{!=}:& \mathbb{R}^d\times \mathbb{R}^d \to \mathbb{B}\\
-          \mathtt{!=}:& \mathbb{R}^{d\times d} \times \mathbb{R}^{d\times d} \to \mathbb{B}
+          \mathtt{==}:& \mathbb{R}^d \times \mathbb{R}^d \to \mathbb{B}\\
+          \mathtt{==}:& \mathbb{R}^{d \times d} \times \mathbb{R}^{d \times d} \to \mathbb{B}\\
+          \mathtt{!=}:& \mathbb{R}^d \times \mathbb{R}^d \to \mathbb{B}\\
+          \mathtt{!=}:& \mathbb{R}^{d \times d} \times \mathbb{R}^{d \times d} \to \mathbb{B}
         \end{array}
       \right.
     \end{equation*}
-- 
GitLab