diff options
author | Andreas Rumpf <rumpf_a@web.de> | 2017-11-02 10:46:30 +0100 |
---|---|---|
committer | Andreas Rumpf <rumpf_a@web.de> | 2017-11-02 10:46:30 +0100 |
commit | 1eaeccc15d15d15d2f62ea1648f7dd64722dbd37 (patch) | |
tree | b922cdabc780fa3a8837a6804d2df31793d9e2ca /doc/manual | |
parent | e9243a16167b24899d4fcf051f3252b3a5804811 (diff) | |
parent | bd19b5f4d36bb40b4af93d7e15fdfa582e9fe3b7 (diff) | |
download | Nim-1eaeccc15d15d15d2f62ea1648f7dd64722dbd37.tar.gz |
Merge branch 'devel' into araq
Diffstat (limited to 'doc/manual')
-rw-r--r-- | doc/manual/ffi.txt | 2 | ||||
-rw-r--r-- | doc/manual/locking.txt | 4 | ||||
-rw-r--r-- | doc/manual/modules.txt | 4 | ||||
-rw-r--r-- | doc/manual/pragmas.txt | 14 | ||||
-rw-r--r-- | doc/manual/procs.txt | 7 | ||||
-rw-r--r-- | doc/manual/stmts.txt | 2 | ||||
-rw-r--r-- | doc/manual/templates.txt | 2 | ||||
-rw-r--r-- | doc/manual/threads.txt | 2 | ||||
-rw-r--r-- | doc/manual/type_bound_ops.txt | 6 | ||||
-rw-r--r-- | doc/manual/type_rel.txt | 2 | ||||
-rw-r--r-- | doc/manual/types.txt | 47 |
11 files changed, 67 insertions, 25 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/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..023895f73 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 @@ -733,7 +733,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 +956,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/stmts.txt b/doc/manual/stmts.txt index 3a86a9730..b24ec3b4a 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. 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/types.txt b/doc/manual/types.txt index 5d2ad01d7..56584f257 100644 --- a/doc/manual/types.txt +++ b/doc/manual/types.txt @@ -114,7 +114,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 @@ -550,7 +551,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 @@ -677,6 +678,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 -------- @@ -885,8 +924,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 |