jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

fixes merge conflict

Browse source
This commit is contained in:
Andreas Rumpf 2018-08-19 15:14:03 +02:00
commit 696c0c48c7
195 changed files with 2049 additions and 1344 deletions
Download patch file Download diff file Expand all files Collapse all files

2
doc/advopt.txt
View file

@ -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

13
doc/backends.txt
View file

@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~

21
doc/docgen.rst
View file

@ -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

28
doc/exception_hierarchy_fragment.txt
View file

@ -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>`_

144
doc/manual.rst
View file

@ -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

78
doc/nimc.rst
View file

@ -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
==================

6
doc/spawn.txt
View file

@ -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