fixes merge conflict

7 files changed, 141 insertions, 151 deletions

diff --git a/doc/advopt.txt b/doc/advopt.txt
index 685c8127d..150025509 100644
--- a/doc/advopt.txt
+++ b/doc/advopt.txt
@@ -68,6 +68,8 @@ Advanced options:
   --oldNewlines:on|off      turn on|off the old behaviour of "\n"
   --laxStrings:on|off       when turned on, accessing the zero terminator in
                             strings is allowed; only for backwards compatibility
+  --nilseqs:on|off          allow 'nil' for strings/seqs for
+                            backwards compatibility
   --skipCfg                 do not read the general configuration file
   --skipUserCfg             do not read the user's configuration file
   --skipParentCfg           do not read the parent dirs' configuration files
diff --git a/doc/backends.txt b/doc/backends.txt
index b7f5308ab..13ef7bf4d 100644
--- a/doc/backends.txt
+++ b/doc/backends.txt
@@ -65,7 +65,6 @@ The JavaScript target
 ---------------------
 
 Nim can also generate `JavaScript`:idx: code through the ``js`` command.
-However, the JavaScript code generator is experimental!
 
 Nim targets JavaScript 1.5 which is supported by any widely used browser.
 Since JavaScript does not have a portable means to include another module,
@@ -77,7 +76,7 @@ available. This includes:
 * manual memory management (``alloc``, etc.)
 * casting and other unsafe operations (``cast`` operator, ``zeroMem``, etc.)
 * file management
-* most modules of the Standard library
+* most modules of the standard library
 * proper 64 bit integer arithmetic
 * unsigned integer arithmetic
 
@@ -87,9 +86,8 @@ However, the modules `strutils <strutils.html>`_, `math <math.html>`_, and
 
 To compile a Nim module into a ``.js`` file use the ``js`` command; the
 default is a ``.js`` file that is supposed to be referenced in an ``.html``
-file. However, you can also run the code with `nodejs`:idx:, a `software
-platform for easily building fast, scalable network applications
-<http://nodejs.org>`_::
+file. However, you can also run the code with `nodejs`:idx:
+(`<http://nodejs.org>`_)::
 
   nim js -d:nodejs -r examples/hallo.nim
 
@@ -330,8 +328,9 @@ Nimcache naming logic
 
 The `nimcache`:idx: directory is generated during compilation and will hold
 either temporary or final files depending on your backend target. The default
-name for the directory is ``nimcache`` but you can use the ``--nimcache``
-`compiler switch <nimc.html#command-line-switches>`_ to change it.
+name for the directory depends on the used backend and on your OS but you can
+use the ``--nimcache`` `compiler switch <nimc.html#command-line-switches>`_ to
+change it.
 
 Nimcache and C like targets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/docgen.rst b/doc/docgen.rst
index d196b3a18..fa23bdc79 100644
--- a/doc/docgen.rst
+++ b/doc/docgen.rst
@@ -97,24 +97,9 @@ Partial Output::
   proc helloWorld(times: int) {.raises: [], tags: [].}
   ...
 
-The full output can be seen here: `docgen_sample2.html <docgen_sample2.html>`_.
-
-The older version of the ``doc`` command, now renamed ``doc0`` runs before
-semantic checking which means it lacks some of the things ``doc`` will output.
-
-The ``doc0`` command::
-  nim doc0 sample
-
-Partial Output::
-  ...
-  proc helloWorld*(times: int)
-  ...
-
-Output can be viewed in full here: `docgen_sample.html <docgen_sample.html>`_.
-As you can see, the tool has extracted less information than what the ``doc``
-command provides, such as pragmas attached implicitly by the compiler. This type
-of information is not available from looking at the AST (Abstract Syntax Tree)
-prior to semantic checking, which is why ``doc0`` doesn't show it.
+The full output can be seen here: `docgen_sample.html <docgen_sample.html>`_.
+It runs after semantic checking, and includes pragmas attached implicitly by the
+compiler.
 
 
 JSON
diff --git a/doc/exception_hierarchy_fragment.txt b/doc/exception_hierarchy_fragment.txt
deleted file mode 100644
index a02d9ccef..000000000
--- a/doc/exception_hierarchy_fragment.txt
+++ /dev/null
@@ -1,28 +0,0 @@
-* `Exception <system.html#Exception>`_
-  * `AccessViolationError <system.html#AccessViolationError>`_
-  * `ArithmeticError <system.html#ArithmeticError>`_
-    * `DivByZeroError <system.html#DivByZeroError>`_
-    * `OverflowError <system.html#OverflowError>`_
-  * `AssertionError <system.html#AssertionError>`_
-  * `DeadThreadError <system.html#DeadThreadError>`_
-  * `FloatingPointError <system.html#FloatingPointError>`_
-    * `FloatDivByZeroError <system.html#FloatDivByZeroError>`_
-    * `FloatInexactError <system.html#FloatInexactError>`_
-    * `FloatInvalidOpError <system.html#FloatInvalidOpError>`_
-    * `FloatOverflowError <system.html#FloatOverflowError>`_
-    * `FloatUnderflowError <system.html#FloatUnderflowError>`_
-  * `FieldError <system.html#FieldError>`_
-  * `IndexError <system.html#IndexError>`_
-  * `ObjectAssignmentError <system.html#ObjectAssignmentError>`_
-  * `ObjectConversionError <system.html#ObjectConversionError>`_
-  * `ValueError <system.html#ValueError>`_
-    * `KeyError <system.html#KeyError>`_
-  * `ReraiseError <system.html#ReraiseError>`_
-  * `RangeError <system.html#RangeError>`_
-  * `OutOfMemoryError <system.html#OutOfMemoryError>`_
-  * `ResourceExhaustedError <system.html#ResourceExhaustedError>`_
-  * `StackOverflowError <system.html#StackOverflowError>`_
-  * `SystemError <system.html#SystemError>`_
-    * `IOError <system.html#IOError>`_
-    * `OSError <system.html#OSError>`_
-      * `LibraryError <system.html#LibraryError>`_
diff --git a/doc/manual.rst b/doc/manual.rst
index abdc4ce69..bb2650799 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -769,8 +769,8 @@ Pre-defined floating point types
 The following floating point types are pre-defined:
 
 ``float``
-  the generic floating point type; its size is platform dependent
-  (the compiler chooses the processor's fastest floating point type).
+  the generic floating point type; its size used to be platform dependent,
+  but now it is always mapped to ``float64``.
   This type should be used in general.
 
 floatXX
@@ -1507,68 +1507,6 @@ non nilable pointers. The details of this analysis are still to be specified
 here.
 
 
-Memory regions
---------------
-
-The types ``ref`` and ``ptr`` can get an optional ``region`` annotation.
-A region has to be an object type.
-
-Regions are very useful to separate user space and kernel memory in the
-development of OS kernels:
-
-.. code-block:: nim
-  type
-    Kernel = object
-    Userspace = object
-
-  var a: Kernel ptr Stat
-  var b: Userspace ptr Stat
-
-  # the following does not compile as the pointer types are incompatible:
-  a = b
-
-As the example shows ``ptr`` can also be used as a binary
-operator, ``region ptr T`` is a shortcut for ``ptr[region, T]``.
-
-In order to make generic code easier to write ``ptr T`` is a subtype
-of ``ptr[R, T]`` for any ``R``.
-
-Furthermore the subtype relation of the region object types is lifted to
-the pointer types: If ``A <: B`` then ``ptr[A, T] <: ptr[B, T]``. This can be
-used to model subregions of memory. As a special typing rule ``ptr[R, T]`` is
-not compatible to ``pointer`` to prevent the following from compiling:
-
-.. code-block:: nim
-  # from system
-  proc dealloc(p: pointer)
-
-  # wrap some scripting language
-  type
-    PythonsHeap = object
-    PyObjectHeader = object
-      rc: int
-      typ: pointer
-    PyObject = ptr[PythonsHeap, PyObjectHeader]
-
-  proc createPyObject(): PyObject {.importc: "...".}
-  proc destroyPyObject(x: PyObject) {.importc: "...".}
-
-  var foo = createPyObject()
-  # type error here, how convenient:
-  dealloc(foo)
-
-
-Future directions:
-
-* Memory regions might become available for  ``string`` and ``seq`` too.
-* Builtin regions like ``private``, ``global`` and ``local`` might be
-  useful for an OpenCL target.
-* Builtin "regions" can model ``lent`` and ``unique`` pointers.
-* An assignment operator can be attached to a region so that proper write
-  barriers can be generated. This would imply that the GC can be implemented
-  completely in user-space.
-
-
 Procedural type
 ---------------
 A procedural type is internally a pointer to a procedure. ``nil`` is
@@ -1673,7 +1611,8 @@ A ``distinct`` type is new type derived from a `base type`:idx: that is
 incompatible with its base type. In particular, it is an essential property
 of a distinct type that it **does not** imply a subtype relation between it
 and its base type. Explicit type conversions from a distinct type to its
-base type and vice versa are allowed.
+base type and vice versa are allowed. See also ``distinctBase`` to get the
+reverse operation.
 
 
 Modelling currencies
@@ -2336,6 +2275,8 @@ pointer type and overloading resolution is tried with ``a[]`` instead.
 Automatic self insertions
 -------------------------
 
+**Note**: The ``.this`` pragma is deprecated and should not be used anymore.
+
 Starting with version 0.14 of the language, Nim supports ``field`` as a
 shortcut for ``self.field`` comparable to the `this`:idx: keyword in Java
 or C++. This feature has to be explicitly enabled via a ``{.this: self.}``
@@ -4028,9 +3969,13 @@ exception.
 Exception hierarchy
 -------------------
 
-The exception tree is defined in the `system <system.html>`_ module:
-
-.. include:: exception_hierarchy_fragment.txt
+The exception tree is defined in the `system <system.html>`_ module.
+Every exception inherits from ``system.Exception``. Exceptions that indicate
+programming bugs inherit from ``system.Defect`` (which is a subtype of ``Exception``)
+and are stricly speaking not catchable as they can also be mapped to an operation
+that terminates the whole process. Exceptions that indicate any other runtime error
+that can be caught inherit from ``system.CatchableError``
+(which is a subtype of ``Exception``).
 
 
 Imported exceptions
@@ -5435,6 +5380,7 @@ type ``system.ForLoopStmt`` can rewrite the entirety of a ``for`` loop:
     :test: "nim c $1"
 
   import macros
+  {.experimental: "forLoopMacros".}
 
   macro enumerate(x: ForLoopStmt): untyped =
     expectKind x, nnkForStmt
@@ -5461,6 +5407,62 @@ type ``system.ForLoopStmt`` can rewrite the entirety of a ``for`` loop:
     echo a2, " ", b2
 
 
+Currently for loop macros must be enabled explicitly
+via ``{.experimental: "forLoopMacros".}``.
+
+
+Case statement macros
+---------------------
+
+A macro that needs to be called `match`:idx: can be used to
+rewrite ``case`` statements in order to
+implement `pattern matching`:idx: for certain types. The following
+example implements a simplistic form of pattern matching for tuples,
+leveraging the existing equality operator for tuples (as provided in
+ ``system.==``):
+
+.. code-block:: nim
+    :test: "nim c $1"
+
+  {.experimental: "caseStmtMacros".}
+
+  import macros
+
+  macro match(n: tuple): untyped =
+    result = newTree(nnkIfStmt)
+    let selector = n[0]
+    for i in 1 ..< n.len:
+      let it = n[i]
+      case it.kind
+      of nnkElse, nnkElifBranch, nnkElifExpr, nnkElseExpr:
+        result.add it
+      of nnkOfBranch:
+        for j in 0..it.len-2:
+          let cond = newCall("==", selector, it[j])
+          result.add newTree(nnkElifBranch, cond, it[^1])
+      else:
+        error "'match' cannot handle this node", it
+    echo repr result
+
+  case ("foo", 78)
+  of ("foo", 78): echo "yes"
+  of ("bar", 88): echo "no"
+  else: discard
+
+
+Currently case statement macros must be enabled explicitly
+via ``{.experimental: "caseStmtMacros".}``.
+
+``match`` macros are subject to overload resolution. First the
+``case``'s selector expression is used to determine which ``match``
+macro to call. To this macro is then the complete ``case`` statement
+body is passed and the macro is evaluated.
+
+In other words, the macro needs to transform the full ``case`` statement
+but only the statement's selector expression is used to determine which
+``macro`` to call.
+
+
 Special Types
 =============
 
@@ -7932,7 +7934,7 @@ that ``spawn`` takes is restricted:
 
 ``spawn`` executes the passed expression on the thread pool and returns
 a `data flow variable`:idx: ``FlowVar[T]`` that can be read from. The reading
-with the ``^`` operator is **blocking**. However, one can use ``awaitAny`` to
+with the ``^`` operator is **blocking**. However, one can use ``blockUntilAny`` to
 wait on multiple flow variables at the same time:
 
 .. code-block:: nim
@@ -7943,10 +7945,10 @@ wait on multiple flow variables at the same time:
     var responses = newSeq[FlowVarBase](3)
     for i in 0..2:
       responses[i] = spawn tellServer(Update, "key", "value")
-    var index = awaitAny(responses)
+    var index = blockUntilAny(responses)
     assert index >= 0
     responses.del(index)
-    discard awaitAny(responses)
+    discard blockUntilAny(responses)
 
 Data flow variables ensure that no data races
 are possible. Due to technical limitations not every type ``T`` is possible in
diff --git a/doc/nimc.rst b/doc/nimc.rst
index 0939f67e8..0682fac03 100644
--- a/doc/nimc.rst
+++ b/doc/nimc.rst
@@ -68,6 +68,46 @@ User                             Some user defined warning.
 ==========================       ============================================
 
 
+List of hints
+-------------
+
+Each hint can be activated individually with ``--hint[NAME]:on|off`` or in a
+``push`` pragma.
+
+==========================       ============================================
+Name                             Description
+==========================       ============================================
+CC                               Shows when the C compiler is called.
+CodeBegin
+CodeEnd
+CondTrue
+Conf                             A config file was loaded.
+ConvToBaseNotNeeded
+ConvFromXtoItselfNotNeeded
+Dependency
+Exec                             Program is executed.
+ExprAlwaysX
+ExtendedContext
+GCStats                          Dumps statistics about the Garbage Collector.
+GlobalVar                        Shows global variables declarations.
+LineTooLong                      Line exceeds the maximum length.
+Link                             Linking phase.
+Name
+Path                             Search paths modifications.
+Pattern
+Performance
+Processing                       Artifact being compiled.
+QuitCalled
+Source                           The source line that triggered a diagnostic
+                                 message.
+StackTrace
+Success, SuccessX                Successful compilation of a library or a binary.
+User
+UserRaw
+XDeclaredButNotUsed              Unused symbols in the code.
+==========================       ============================================
+
+
 Verbosity levels
 ----------------
 
@@ -114,7 +154,7 @@ passed as a command line argument to the compiler.
 The ``nim`` executable processes configuration files in the following
 directories (in this order; later files overwrite previous settings):
 
-1) ``$nim/config/nim.cfg``, ``/etc/nim.cfg`` (UNIX) or ``%NIMROD%/config/nim.cfg`` (Windows). This file can be skipped with the ``--skipCfg`` command line option.
+1) ``$nim/config/nim.cfg``, ``/etc/nim/nim.cfg`` (UNIX) or ``%NIM%/config/nim.cfg`` (Windows). This file can be skipped with the ``--skipCfg`` command line option.
 2) ``$HOME/.config/nim.cfg`` (POSIX) or  ``%APPDATA%/nim.cfg`` (Windows). This file can be skipped with the ``--skipUserCfg`` command line option.
 3) ``$parentDir/nim.cfg`` where ``$parentDir`` stands for any parent  directory of the project file's path. These files can be skipped with the ``--skipParentCfg`` command line option.
 4) ``$projectDir/nim.cfg`` where ``$projectDir`` stands for the project  file's path. This file can be skipped with the ``--skipProjCfg`` command line option.
@@ -157,38 +197,28 @@ the first matching file is used.
 Generated C code directory
 --------------------------
 The generated files that Nim produces all go into a subdirectory called
-``nimcache`` in your project directory. This makes it easy to delete all
+``nimcache``. Its full path is
+
+- ``$XDG_CACHE_HOME/nim/$projectname(_r|_d)`` or ``~/.cache/nim/$projectname(_r|_d)``
+  on Posix
+- ``$HOME/nimcache/$projectname(_r|_d)`` on Windows.
+
+The ``_r`` suffix is used for release builds, ``_d`` is for debug builds.
+
+This makes it easy to delete all
 generated files. Files generated in this directory follow a naming logic which
 you can read about in the `Nim Backend Integration document
 <backends.html#nimcache-naming-logic>`_.
 
+The ``--nimcache``
+`compiler switch <nimc.html#command-line-switches>`_ can be used to
+to change the ``nimcache`` directory.
+
 However, the generated C code is not platform independent. C code generated for
 Linux does not compile on Windows, for instance. The comment on top of the
 C file lists the OS, CPU and CC the file has been compiled for.
 
 
-Compilation cache
-=================
-
-**Warning**: The compilation cache is still highly experimental!
-
-The ``nimcache`` directory may also contain so called `rod`:idx:
-or `symbol files`:idx:. These files are pre-compiled modules that are used by
-the compiler to perform `incremental compilation`:idx:. This means that only
-modules that have changed since the last compilation (or the modules depending
-on them etc.) are re-compiled. However, per default no symbol files are
-generated; use the ``--symbolFiles:on`` command line switch to activate them.
-
-Unfortunately due to technical reasons the ``--symbolFiles:on`` needs
-to *aggregate* some generated C code. This means that the resulting executable
-might contain some cruft even with dead code elimination. So
-the final release build should be done with ``--symbolFiles:off``.
-
-Due to the aggregation of C code it is also recommended that each project
-resides in its own directory so that the generated ``nimcache`` directory
-is not shared between different projects.
-
-
 Compiler Selection
 ==================
 
diff --git a/doc/spawn.txt b/doc/spawn.txt
index 522c94464..ab667ff48 100644
--- a/doc/spawn.txt
+++ b/doc/spawn.txt
@@ -25,7 +25,7 @@ Spawn statement
 A standalone ``spawn`` statement is a simple construct. It executes
 the passed expression on the thread pool and returns a `data flow variable`:idx:
 ``FlowVar[T]`` that can be read from. The reading with the ``^`` operator is
-**blocking**. However, one can use ``awaitAny`` to wait on multiple flow
+**blocking**. However, one can use ``blockUntilAny`` to wait on multiple flow
 variables at the same time:
 
 .. code-block:: nim
@@ -36,10 +36,10 @@ variables at the same time:
     var responses = newSeq[FlowVarBase](3)
     for i in 0..2:
       responses[i] = spawn tellServer(Update, "key", "value")
-    var index = awaitAny(responses)
+    var index = blockUntilAny(responses)
     assert index >= 0
     responses.del(index)
-    discard awaitAny(responses)
+    discard blockUntilAny(responses)
 
 Data flow variables ensure that no data races
 are possible. Due to technical limitations not every type ``T`` is possible in