Improve documentation of basic types and the associated operators

doc/userdoc.org

@@ -585,7 +585,7 @@ It produces the following error
 #+results: invalid-compound-definition
 which is easy to fix.
 
-*** TODO Basic types<<basic-types>>
+*** Basic types<<basic-types>>
 
 Basic types in ~pugs~ are boolean ~B~, natural integers ~N~, integers ~Z~,
 real ~R~, small vectors ~R^1~, ~R^2~ and ~R^3~, small matrices ~R^1x1~, ~R^2x2~
@@ -670,13 +670,13 @@ This will be detailed in section [[functions]].
 #+END_note
 
 This means that all affectation, unary and binary operators are
-defined for all types.
+defined explicitly for supported types.
 
 *** Operators
 
 **** Affectation operators
 
-In the ~pugs~ language the affectation operators are the following.
+In the ~pugs~ language, the affectation operators are the following.
 | operator | description          |
 |----------+----------------------|
 | ~=~        | affectation operator |
@@ -700,7 +700,7 @@ but does not produce the expected result.
   }
 #+END_SRC
 Obviously the mistake is that the test should have been ~(b==false)~,
-since otherwise, the following block is never executed (in ~C++~, the
+since otherwise, the conditional block is never executed (in ~C++~, the
 result of an affectation is the value affected to the variable, which
 is always false in that case.
 
@@ -716,18 +716,146 @@ This cannot happen with ~pugs~. A similar example
 produces the following error
 #+results: no-affectation-result
 
-#+END_note
-
-Here is the complete list of supported affectation operators according
-to left hand side variable type (/lvalue/ type) and right hand side
-expression type (/rvalue/ type).
-
+Actually, affectations are /expressions/ in ~C++~, in ~pugs~ language,
+affectations are /instructions/.
 
+#+END_note
 
 **** Unary operators
 
+The ~pugs~ language allows the following tokens as unary operators
+| operator | description          |
+|----------+----------------------|
+| ~not~      | not operator         |
+| ~+~        | plus unary operator  |
+| ~-~        | minus unary operator |
+|----------+----------------------|
+| ~++~       | increment operator   |
+| ~--~       | decrement operator   |
+
+The ~not~, ~+~ and ~-~ operators apply to the *expression* on their right. ~++~
+and ~--~ operators apply only to a *variable* that can be positioned
+before (post increment/decrement) or after the token (pre
+increment/decrement). These operators are also inspired from their ~C++~
+counterparts for commodity.
+
+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.
+- 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
+  for ~string~ variables.
+- pre and post increment operators, ~--~ and ~++~, are defined for all
+  scalar basic types: ~N~, ~Z~ and ~R~. They are not defined for ~B~, ~R^1~,
+  ~R^2~, ~R^3~, ~R^1x1~, ~R^2x2~, ~R^3x3~ and ~string~ variables.
+
+Note that the pre increment/decrement operators behave slightly
+differently than their ~C++~ counterparts since they are not allowed to
+be chained. In ~C++~, the following code is allowed
+#+BEGIN_SRC C++ :exports source
+  int i = 0;
+  int j = ++ ++i;
+#+END_SRC
+In ~pugs~, it is forbidden:
+#+NAME: double-pre-incr-result
+#+BEGIN_SRC pugs-error :exports both :results output
+  let i:N, i=0;
+  let j:N, j = ++ ++i;
+#+END_SRC
+produces the compilation error
+#+results: double-pre-incr-result
+Again, this is done to simplify the syntax and to avoid weird
+constructions.
+
 **** Binary operators
 
+Syntax for binary operators follows again a classical structure if
+~exp1~ and ~exp2~ denotes two expressions and if ~op~ denotes a binary
+operator, one writes simply ~exp1 op exp2~.
+
+Here is the list of binary operators
+| keyword | operator              |
+|---------+-----------------------|
+| ~and~     | logic and             |
+| ~or~      | logic and             |
+| ~xor~     | logic exclusive or    |
+|---------+-----------------------|
+| ~==~      | equality              |
+| ~!=~      | non-equality          |
+| ~<~       | lower than            |
+| ~<=~      | lower than or equal   |
+| ~>~       | greater than          |
+| ~>=~      | greater than or equal |
+|---------+-----------------------|
+| ~<<~      | shift left            |
+| ~>>~      | shift right           |
+|---------+-----------------------|
+| ~+~       | sum                   |
+| ~-~       | difference            |
+| ~*~       | product               |
+| ~/~       | division              |
+
+Binary operators can be defined for high-level types. For basic types,
+they follow a few rules.
+
+- Logical operators ~and~, ~or~ and ~xor~ are defined for boolean operands
+  (type is ~B~) only. The result of the expression is a boolean.
+  #+begin_src latex :results drawer :exports results
+    \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}
+        \end{array}
+      \right.
+    \end{equation*}
+  #+end_src
+- Comparison operators ~==~, ~!=~, ~<~, ~<=~, ~>~ and ~>=~ are defined for all
+  basic scalar type and return a boolean value.
+  #+begin_src latex :results drawer :exports results
+    \begin{equation*}
+      \forall \mathbb{S}_1, \mathbb{S}_2 \in \{\mathbb{B},\mathbb{N},\mathbb{Z},\mathbb{R}\},
+      \quad
+      \left|
+        \begin{array}{rl}
+          \mathtt{==}:& \mathbb{S}_1 \times \mathbb{S}_2 \to \mathbb{B}\\
+          \mathtt{!=}:& \mathbb{S}_1 \times \mathbb{S}_2 \to \mathbb{B}\\
+          \mathtt{<}: & \mathbb{S}_1 \times \mathbb{S}_2 \to \mathbb{B}\\
+          \mathtt{<=}:& \mathbb{S}_1 \times \mathbb{S}_2 \to \mathbb{B}\\
+          \mathtt{>}: & \mathbb{S}_1 \times \mathbb{S}_2 \to \mathbb{B}\\
+          \mathtt{>=}:& \mathbb{S}_1 \times \mathbb{S}_2 \to \mathbb{B}
+        \end{array}
+      \right.
+    \end{equation*}
+  #+end_src
+  When comparing a boolean value (type ~B~) with another scalar value
+  type (~N~, ~Z~ or ~R~), the value ~true~ is interpreted as $1$ and the value
+  ~false~ as $0$.
+\\
+  For vector and matrix basic types, the only allowed operators are ~==~
+  and ~!=~.
+  #+begin_src latex :results drawer :exports results
+    \begin{equation*}
+      \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}
+        \end{array}
+      \right.
+    \end{equation*}
+  #+end_src
+- Shift operators ~<<~ and ~>>~ are not used to define binary operators
+  between two basic types
+- Arithmetic operators are defined
+
 *** TODO High-level types<<high-level-types>>
 
 *** TODO Lists