Merge pull request #1 from nim-lang/devel

upstream

14 files changed, 117 insertions, 75 deletions

diff --git a/doc/manual/ffi.txt b/doc/manual/ffi.txt
index 06fed1430..67a4c7caa 100644
--- a/doc/manual/ffi.txt
+++ b/doc/manual/ffi.txt
@@ -206,7 +206,7 @@ strings, because they are precompiled.
 **Note**: Passing variables to the ``dynlib`` pragma will fail at runtime
 because of order of initialization problems.
 
-**Note**: A ``dynlib`` import can be overriden with
+**Note**: A ``dynlib`` import can be overridden with
 the ``--dynlibOverride:name`` command line option. The Compiler User Guide
 contains further information.
 
diff --git a/doc/manual/generics.txt b/doc/manual/generics.txt
index cceea33c0..1ba62bb5c 100644
--- a/doc/manual/generics.txt
+++ b/doc/manual/generics.txt
@@ -9,26 +9,26 @@ The following example shows a generic binary tree can be modelled:
 
 .. code-block:: nim
   type
-    BinaryTreeObj[T] = object    # BinaryTreeObj is a generic type with
-                                 # with generic param ``T``
-      le, ri: BinaryTree[T]      # left and right subtrees; may be nil
-      data: T                    # the data stored in a node
-    BinaryTree[T] = ref BinaryTreeObj[T] # a shorthand for notational convenience
+    BinaryTree*[T] = ref object # BinaryTree is a generic type with
+                                # generic param ``T``
+      le, ri: BinaryTree[T]     # left and right subtrees; may be nil
+      data: T                   # the data stored in a node
 
-  proc newNode[T](data: T): BinaryTree[T] = # constructor for a node
+  proc newNode*[T](data: T): BinaryTree[T] =
+    # constructor for a node
     new(result)
     result.data = data
 
-  proc add[T](root: var BinaryTree[T], n: BinaryTree[T]) =
+  proc add*[T](root: var BinaryTree[T], n: BinaryTree[T]) =
+    # insert a node into the tree
     if root == nil:
       root = n
     else:
       var it = root
       while it != nil:
-        var c = cmp(it.data, n.data) # compare the data items; uses
-                                     # the generic ``cmp`` proc that works for
-                                     # any type that has a ``==`` and ``<``
-                                     # operator
+        # compare the data items; uses the generic ``cmp`` proc
+        # that works for any type that has a ``==`` and ``<`` operator
+        var c = cmp(it.data, n.data)
         if c < 0:
           if it.le == nil:
             it.le = n
@@ -40,20 +40,28 @@ The following example shows a generic binary tree can be modelled:
             return
           it = it.ri
 
-  iterator inorder[T](root: BinaryTree[T]): T =
-    # inorder traversal of a binary tree
-    # recursive iterators are not yet implemented, so this does not work in
-    # the current compiler!
-    if root.le != nil: yield inorder(root.le)
-    yield root.data
-    if root.ri != nil: yield inorder(root.ri)
+  proc add*[T](root: var BinaryTree[T], data: T) =
+    # convenience proc:
+    add(root, newNode(data))
+
+  iterator preorder*[T](root: BinaryTree[T]): T =
+    # Preorder traversal of a binary tree.
+    # Since recursive iterators are not yet implemented,
+    # this uses an explicit stack (which is more efficient anyway):
+    var stack: seq[BinaryTree[T]] = @[root]
+    while stack.len > 0:
+      var n = stack.pop()
+      while n != nil:
+        yield n.data
+        add(stack, n.ri)  # push right subtree onto the stack
+        n = n.le          # and follow the left pointer
 
   var
-    root: BinaryTree[string]  # instantiate a BinaryTree with the type string
-  add(root, newNode("hallo")) # instantiates generic procs ``newNode`` and
-  add(root, newNode("world")) # ``add``
-  for str in inorder(root):
-    writeLine(stdout, str)
+    root: BinaryTree[string] # instantiate a BinaryTree with ``string``
+  add(root, newNode("hello")) # instantiates ``newNode`` and ``add``
+  add(root, "world")          # instantiates the second ``add`` proc
+  for str in preorder(root):
+    stdout.writeLine(str)
 
 
 Is operator
diff --git a/doc/manual/locking.txt b/doc/manual/locking.txt
index c1bd5ca46..99ffe8970 100644
--- a/doc/manual/locking.txt
+++ b/doc/manual/locking.txt
@@ -2,7 +2,7 @@ Guards and locks
 ================
 
 Apart from ``spawn`` and ``parallel`` Nim also provides all the common low level
-concurrency mechanisms like locks, atomic intristics or condition variables.
+concurrency mechanisms like locks, atomic intrinsics or condition variables.
 
 Nim significantly improves on the safety of these features via additional
 pragmas:
@@ -74,7 +74,7 @@ model low level lockfree mechanisms:
 
 The ``locks`` pragma takes a list of lock expressions ``locks: [a, b, ...]``
 in order to support *multi lock* statements. Why these are essential is
-explained in the `lock levels`_ section.
+explained in the `lock levels <#guards-and-locks-lock-levels>`_ section.
 
 
 Protecting general locations
diff --git a/doc/manual/modules.txt b/doc/manual/modules.txt
index 9cb6a11af..4ef1bfd99 100644
--- a/doc/manual/modules.txt
+++ b/doc/manual/modules.txt
@@ -105,7 +105,7 @@ From import statement
 ~~~~~~~~~~~~~~~~~~~~~
 
 After the ``from`` statement a module name follows followed by
-an ``import`` to list the symbols one likes to use without explict
+an ``import`` to list the symbols one likes to use without explicit
 full qualification:
 
 .. code-block:: nim
@@ -123,7 +123,7 @@ in ``module``.
 Export statement
 ~~~~~~~~~~~~~~~~
 
-An ``export`` statement can be used for symbol fowarding so that client
+An ``export`` statement can be used for symbol forwarding so that client
 modules don't need to import a module's dependencies:
 
 .. code-block:: nim
diff --git a/doc/manual/pragmas.txt b/doc/manual/pragmas.txt
index bd90cd73d..835b6909d 100644
--- a/doc/manual/pragmas.txt
+++ b/doc/manual/pragmas.txt
@@ -70,7 +70,7 @@ compileTime pragma
 The ``compileTime`` pragma is used to mark a proc or variable to be used at
 compile time only. No code will be generated for it. Compile time procs are
 useful as helpers for macros. Since version 0.12.0 of the language, a proc
-that uses ``system.NimNode`` within its parameter types is implictly declared
+that uses ``system.NimNode`` within its parameter types is implicitly declared
 ``compileTime``:
 
 .. code-block:: nim
@@ -102,6 +102,14 @@ collector to not consider objects of this type as part of a cycle:
       left, right: Node
       data: string
 
+Or if we directly use a ref object:
+
+.. code-block:: nim
+  type
+    Node = ref object {.acyclic, final.}
+      left, right: Node
+      data: string
+
 In the example a tree structure is declared with the ``Node`` type. Note that
 the type definition is recursive and the GC has to assume that objects of
 this type may form a cyclic graph. The ``acyclic`` pragma passes the
@@ -316,7 +324,7 @@ factor.
 immediate pragma
 ----------------
 
-See `Ordinary vs immediate templates`_.
+See `Typed vs untyped parameters`_.
 
 
 compilation option pragmas
@@ -733,7 +741,8 @@ about the ``importcpp`` pragma pattern language. It is not necessary
 to know all the details described here.
 
 
-Similar to the `importc pragma for C <manual.html#importc-pragma>`_, the
+Similar to the `importc pragma for C 
+<#foreign-function-interface-importc-pragma>`_, the 
 ``importcpp`` pragma can be used to import `C++`:idx: methods or C++ symbols
 in general. The generated code then uses the C++ method calling
 syntax: ``obj->method(arg)``.  In combination with the ``header`` and ``emit``
@@ -955,10 +964,11 @@ Produces:
 
 ImportObjC pragma
 -----------------
-Similar to the `importc pragma for C <manual.html#importc-pragma>`_, the
-``importobjc`` pragma can be used to import `Objective C`:idx: methods.  The
-generated code then uses the Objective C method calling syntax: ``[obj method
-param1: arg]``.  In addition with the ``header`` and ``emit`` pragmas this
+Similar to the `importc pragma for C 
+<#foreign-function-interface-importc-pragma>`_, the ``importobjc`` pragma can 
+be used to import `Objective C`:idx: methods.  The generated code then uses the
+Objective C method calling syntax: ``[obj method param1: arg]``. 
+In addition with the ``header`` and ``emit`` pragmas this
 allows *sloppy* interfacing with libraries written in Objective C:
 
 .. code-block:: Nim
diff --git a/doc/manual/procs.txt b/doc/manual/procs.txt
index 6d09ac3f5..44aeb089a 100644
--- a/doc/manual/procs.txt
+++ b/doc/manual/procs.txt
@@ -142,10 +142,11 @@ The method call syntax conflicts with explicit generic instantiations:
 parsed as ``(x.p)[T]``.
 
 **Future directions**: ``p[.T.]`` might be introduced as an alternative syntax
-to pass explict types to a generic and then ``x.p[.T.]`` can be parsed as
+to pass explicit types to a generic and then ``x.p[.T.]`` can be parsed as
 ``x.(p[.T.])``.
 
-See also: `Limitations of the method call syntax`_.
+See also: `Limitations of the method call syntax
+<#templates-limitations-of-the-method-call-syntax>`_.
 
 
 Properties
@@ -178,7 +179,7 @@ different; for this a special setter syntax is needed:
 Command invocation syntax
 -------------------------
 
-Routines can be invoked without the ``()`` if the call is syntatically
+Routines can be invoked without the ``()`` if the call is syntactically
 a statement. This command invocation syntax also works for
 expressions, but then only a single argument may follow. This restriction
 means ``echo f 1, f 2`` is parsed as ``echo(f(1), f(2))`` and not as
diff --git a/doc/manual/special_ops.txt b/doc/manual/special_ops.txt
index 1c7136bec..93977f81b 100644
--- a/doc/manual/special_ops.txt
+++ b/doc/manual/special_ops.txt
@@ -17,8 +17,8 @@ or dynamic file formats such as JSON or XML.
 When Nim encounters an expression that cannot be resolved by the
 standard overload resolution rules, the current scope will be searched
 for a dot operator that can be matched against a re-written form of
-the expression, where the unknown field or proc name is converted to
-an additional static string parameter:
+the expression, where the unknown field or proc name is passed to
+an ``untyped`` parameter:
 
 .. code-block:: nim
   a.b # becomes `.`(a, "b")
@@ -28,7 +28,7 @@ The matched dot operators can be symbols of any callable kind (procs,
 templates and macros), depending on the desired effect:
 
 .. code-block:: nim
-  proc `.` (js: PJsonNode, field: string): JSON = js[field]
+  template `.` (js: PJsonNode, field: untyped): JSON = js[astToStr(field)]
 
   var js = parseJson("{ x: 1, y: 2}")
   echo js.x # outputs 1
diff --git a/doc/manual/stmts.txt b/doc/manual/stmts.txt
index 3a86a9730..721b5cff8 100644
--- a/doc/manual/stmts.txt
+++ b/doc/manual/stmts.txt
@@ -199,7 +199,7 @@ The rules for compile-time computability are:
    (possibly empty) list of compile-time computable arguments.
 
 
-Constants cannot be of type ``ptr``, ``ref``, ``var`` or ``object``, nor can
+Constants cannot be of type ``ptr``, ``ref`` or ``var``, nor can
 they contain such a type.
 
 
@@ -296,6 +296,10 @@ empty ``discard`` statement should be used.
 For non ordinal types it is not possible to list every possible value and so
 these always require an ``else`` part.
 
+As case statements perform compile-time exhaustiveness checks, the value in 
+every ``of`` branch must be known at compile time. This fact is also exploited
+to generate more performant code.
+
 As a special semantic extension, an expression in an ``of`` branch of a case
 statement may evaluate to a set or array constructor; the set or array is then
 expanded into a list of its elements:
diff --git a/doc/manual/templates.txt b/doc/manual/templates.txt
index f01a703cd..af184589c 100644
--- a/doc/manual/templates.txt
+++ b/doc/manual/templates.txt
@@ -293,7 +293,7 @@ Limitations of the method call syntax
 
 The expression ``x`` in ``x.f`` needs to be semantically checked (that means
 symbol lookup and type checking) before it can be decided that it needs to be
-rewritten to ``f(x)``. Therefore the dot syntax has some limiations when it
+rewritten to ``f(x)``. Therefore the dot syntax has some limitations when it
 is used to invoke templates/macros:
 
 .. code-block:: nim
diff --git a/doc/manual/threads.txt b/doc/manual/threads.txt
index 15121ab6d..53071b5a5 100644
--- a/doc/manual/threads.txt
+++ b/doc/manual/threads.txt
@@ -5,7 +5,7 @@ To enable thread support the ``--threads:on`` command line switch needs to
 be used. The ``system`` module then contains several threading primitives.
 See the `threads <threads.html>`_ and `channels <channels.html>`_ modules
 for the low level thread API. There are also high level parallelism constructs
-available. See `spawn`_ for further details.
+available. See `spawn <#parallel-spawn>`_ for further details.
 
 Nim's memory model for threads is quite different than that of other common
 programming languages (C, Pascal, Java): Each thread has its own (garbage
diff --git a/doc/manual/type_bound_ops.txt b/doc/manual/type_bound_ops.txt
index c707979fe..b531abf31 100644
--- a/doc/manual/type_bound_ops.txt
+++ b/doc/manual/type_bound_ops.txt
@@ -7,12 +7,12 @@ There are 3 operations that are bound to a type:
 2. Destruction
 3. Deep copying for communication between threads
 
-These operations can be *overriden* instead of *overloaded*. This means the
+These operations can be *overridden* instead of *overloaded*. This means the
 implementation is automatically lifted to structured types. For instance if type
-``T`` has an overriden assignment operator ``=`` this operator is also used
+``T`` has an overridden assignment operator ``=`` this operator is also used
 for assignments of the type ``seq[T]``. Since these operations are bound to a
 type they have to be bound to a nominal type for reasons of simplicity of
-implementation: This means an overriden ``deepCopy`` for ``ref T`` is really
+implementation: This means an overridden ``deepCopy`` for ``ref T`` is really
 bound to ``T`` and not to ``ref T``. This also means that one cannot override
 ``deepCopy`` for both ``ptr T`` and ``ref T`` at the same time; instead a
 helper distinct or object type has to be used for one pointer type.
diff --git a/doc/manual/type_rel.txt b/doc/manual/type_rel.txt
index 1d1425934..3372691fb 100644
--- a/doc/manual/type_rel.txt
+++ b/doc/manual/type_rel.txt
@@ -491,4 +491,4 @@ metatypes ``typed`` and ``typedesc`` are not lazy.
 Varargs matching
 ----------------
 
-See `Varargs`_.
+See `Varargs <#types-varargs>`_.
diff --git a/doc/manual/type_sections.txt b/doc/manual/type_sections.txt
index af761c77e..12b2a11ac 100644
--- a/doc/manual/type_sections.txt
+++ b/doc/manual/type_sections.txt
@@ -5,8 +5,7 @@ Example:
 
 .. code-block:: nim
   type # example demonstrating mutually recursive types
-    Node = ref NodeObj # a traced pointer to a NodeObj
-    NodeObj = object
+    Node = ref object  # an object managed by the garbage collector (ref)
       le, ri: Node     # left and right subtrees
       sym: ref Sym     # leaves contain a reference to a Sym
 
diff --git a/doc/manual/types.txt b/doc/manual/types.txt
index 2c4b019ad..1477995dd 100644
--- a/doc/manual/types.txt
+++ b/doc/manual/types.txt
@@ -41,7 +41,8 @@ These integer types are pre-defined:
 ``int``
   the generic signed integer type; its size is platform dependent and has the
   same size as a pointer. This type should be used in general. An integer
-  literal that has no type suffix is of this type.
+  literal that has no type suffix is of this type if it is in the range
+  ``low(int32)..high(int32)`` otherwise the literal's type is ``int64``.
 
 intXX
   additional signed integer types of XX bits use this naming scheme
@@ -114,7 +115,8 @@ if the literal's value fits this smaller type and such a conversion is less
 expensive than other implicit conversions, so ``myInt16 + 34`` produces
 an ``int16`` result.
 
-For further details, see `Convertible relation`_.
+For further details, see `Convertible relation
+<#type-relations-convertible-relation>`_.
 
 
 Subrange types
@@ -136,26 +138,6 @@ determined). Assignments from the base type to one of its subrange types
 
 A subrange type has the same size as its base type (``int`` in the example).
 
-Nim requires `interval arithmetic`:idx: for subrange types over a set
-of built-in operators that involve constants: ``x %% 3`` is of
-type ``range[0..2]``. The following built-in operators for integers are
-affected by this rule: ``-``, ``+``, ``*``, ``min``, ``max``, ``succ``,
-``pred``, ``mod``, ``div``, ``%%``, ``and`` (bitwise ``and``).
-
-Bitwise ``and`` only produces a ``range`` if one of its operands is a
-constant *x* so that (x+1) is a power of two.
-(Bitwise ``and`` is then a ``%%`` operation.)
-
-This means that the following code is accepted:
-
-.. code-block:: nim
-  case (x and 3) + 7
-  of 7: echo "A"
-  of 8: echo "B"
-  of 9: echo "C"
-  of 10: echo "D"
-  # note: no ``else`` required as (x and 3) + 7 has the type: range[7..10]
-
 
 Pre-defined floating point types
 --------------------------------
@@ -570,7 +552,7 @@ order. The *names* of the fields also have to be identical.
 
 The assignment operator for tuples copies each component.
 The default assignment operator for objects copies each component. Overloading
-of the assignment operator is described in `type-bound-operations-operator`_. 
+of the assignment operator is described in `type-bound-operations-operator`_.
 
 .. code-block:: nim
 
@@ -697,6 +679,44 @@ branch switch ``system.reset`` has to be used. Also, when the fields of a
 particular branch are specified during object construction, the correct value
 for the discriminator must be supplied at compile-time.
 
+Package level objects
+---------------------
+
+Every Nim module resides in a (nimble) package. An object type can be attached
+to the package it resides in. If that is done, the type can be referenced from
+other modules as an `incomplete`:idx: object type. This features allows to
+break up recursive type dependencies accross module boundaries. Incomplete
+object types are always passed ``byref`` and can only be used in pointer like
+contexts (``var/ref/ptr IncompleteObject``) in general since the compiler does
+not yet know the size of the object. To complete an incomplete object
+the ``package`` pragma has to be used. ``package`` implies ``byref``.
+
+As long as a type ``T`` is incomplete ``sizeof(T)`` or "runtime type
+information" for ``T`` is not available.
+
+
+Example:
+
+.. code-block:: nim
+
+  # module A (in an arbitrary package)
+  type
+    Pack.SomeObject = object ## declare as incomplete object of package 'Pack'
+    Triple = object
+      a, b, c: ref SomeObject ## pointers to incomplete objects are allowed
+
+  ## Incomplete objects can be used as parameters:
+  proc myproc(x: SomeObject) = discard
+
+
+.. code-block:: nim
+
+  # module B (in package "Pack")
+  type
+    SomeObject* {.package.} = object ## Use 'package' to complete the object
+      s, t: string
+      x, y: int
+
 
 Set type
 --------
@@ -905,8 +925,8 @@ not compatible to ``pointer`` to prevent the following from compiling:
 Future directions:
 
 * Memory regions might become available for  ``string`` and ``seq`` too.
-* Builtin regions like ``private``, ``global`` and ``local`` will
-  prove very useful for the upcoming OpenCL target.
+* 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