manual split up into multiple files; documented the new concurrency system

doc/manual/syntax.txt

@@ -0,0 +1,112 @@
+Syntax
+======
+
+This section lists Nim's standard syntax. How the parser handles
+the indentation is already described in the `Lexical Analysis`_ section.
+
+Nim allows user-definable operators.
+Binary operators have 10 different levels of precedence.
+
+Relevant character
+------------------
+
+An operator symbol's *relevant character* is its first
+character unless the first character is ``\`` and its length is greater than 1
+then it is the second character.
+
+This rule allows to escape operator symbols with ``\`` and keeps the operator's
+precedence and associativity; this is useful for meta programming.
+
+
+Associativity
+-------------
+
+Binary operators whose relevant character is ``^`` are right-associative, all
+other binary operators are left-associative.
+
+Precedence
+----------
+
+Unary operators always bind stronger than any binary 
+operator: ``$a + b`` is ``($a) + b`` and not ``$(a + b)``.
+
+If an unary operator's relevant character is ``@`` it is a `sigil-like`:idx: 
+operator which binds stronger than a ``primarySuffix``: ``@x.abc`` is parsed
+as ``(@x).abc`` whereas ``$x.abc`` is parsed as ``$(x.abc)``.
+
+
+For binary operators that are not keywords the precedence is determined by the
+following rules:
+
+If the operator ends with ``=`` and its relevant character is none of 
+``<``, ``>``, ``!``, ``=``, ``~``, ``?``, it is an *assignment operator* which
+has the lowest precedence.
+
+Otherwise precedence is determined by the relevant character.
+
+================  ===============================================  ==================  ===============
+Precedence level    Operators                                      Relevant character  Terminal symbol
+================  ===============================================  ==================  ===============
+  9 (highest)                                                      ``$  ^``            OP9
+  8               ``*    /    div   mod   shl  shr  %``            ``* % \  /``        OP8
+  7               ``+    -``                                       ``+  ~  |``         OP7
+  6               ``&``                                            ``&``               OP6
+  5               ``..``                                           ``.``               OP5
+  4               ``==  <= < >= > !=  in notin is isnot not of``   ``= <  > !``        OP4
+  3               ``and``                                                              OP3
+  2               ``or xor``                                                           OP2
+  1                                                                ``@  : ?``          OP1
+  0 (lowest)      *assignment operator* (like ``+=``, ``*=``)                          OP0
+================  ===============================================  ==================  ===============
+
+
+Strong spaces
+-------------
+
+The number of spaces preceeding a non-keyword operator affects precedence
+if the experimental parser directive ``#!strongSpaces`` is used. Indentation
+is not used to determine the number of spaces. If 2 or more operators have the
+same number of preceding spaces the precedence table applies, so ``1 + 3 * 4``
+is still parsed as ``1 + (3 * 4)``, but ``1+3 * 4`` is parsed as ``(1+3) * 4``:
+
+.. code-block:: nim
+  #! strongSpaces
+  if foo+4 * 4 == 8 and b&c | 9  ++
+      bar:
+    echo ""
+  # is parsed as
+  if ((foo+4)*4 == 8) and (((b&c) | 9) ++ bar): echo ""
+
+
+Furthermore whether an operator is used a prefix operator is affected by the
+number of spaces: 
+
+.. code-block:: nim
+  #! strongSpaces
+  echo $foo
+  # is parsed as
+  echo($foo)
+
+This also affects whether ``[]``, ``{}``, ``()`` are parsed as constructors
+or as accessors:
+
+.. code-block:: nim
+  #! strongSpaces
+  echo (1,2)
+  # is parsed as
+  echo((1,2))
+
+Only 0, 1, 2, 4 or 8 spaces are allowed to specify precedence and it is
+enforced that infix operators have the same amount of spaces before and after
+them. This rules does not apply when a newline follows after the operator,
+then only the preceding spaces are considered.
+
+
+Grammar
+-------
+
+The grammar's start symbol is ``module``.
+
+.. include:: grammar.txt
+   :literal:
+