|
|
|
|
@@ -152,7 +152,7 @@ statements (simplified example)::
|
|
|
|
|
Comments
|
|
|
|
|
--------
|
|
|
|
|
|
|
|
|
|
`Comments`:idx: start anywhere outside a string or character literal with the
|
|
|
|
|
Comments start anywhere outside a string or character literal with the
|
|
|
|
|
hash character ``#``.
|
|
|
|
|
Comments consist of a concatenation of `comment pieces`:idx:. A comment piece
|
|
|
|
|
starts with ``#`` and runs until the end of the line. The end of line characters
|
|
|
|
|
@@ -188,7 +188,7 @@ which code snippet the comment refers to.
|
|
|
|
|
Identifiers & Keywords
|
|
|
|
|
----------------------
|
|
|
|
|
|
|
|
|
|
`Identifiers`:idx: in Nimrod can be any string of letters, digits
|
|
|
|
|
Identifiers in Nimrod can be any string of letters, digits
|
|
|
|
|
and underscores, beginning with a letter. Two immediate following
|
|
|
|
|
underscores ``__`` are not allowed::
|
|
|
|
|
|
|
|
|
|
@@ -201,7 +201,7 @@ classified as a ``letter`` and may thus be part of an identifier but later
|
|
|
|
|
versions of the language may assign some Unicode characters to belong to the
|
|
|
|
|
operator characters instead.
|
|
|
|
|
|
|
|
|
|
The following `keywords`:idx: are reserved and cannot be used as identifiers:
|
|
|
|
|
The following keywords are reserved and cannot be used as identifiers:
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
:file: keywords.txt
|
|
|
|
|
@@ -224,7 +224,7 @@ String literals
|
|
|
|
|
|
|
|
|
|
Terminal symbol in the grammar: ``STR_LIT``.
|
|
|
|
|
|
|
|
|
|
`String literals`:idx: can be delimited by matching double quotes, and can
|
|
|
|
|
String literals can be delimited by matching double quotes, and can
|
|
|
|
|
contain the following `escape sequences`:idx:\ :
|
|
|
|
|
|
|
|
|
|
================== ===================================================
|
|
|
|
|
@@ -280,7 +280,7 @@ Raw string literals
|
|
|
|
|
|
|
|
|
|
Terminal symbol in the grammar: ``RSTR_LIT``.
|
|
|
|
|
|
|
|
|
|
There are also `raw string literals`:idx: that are preceded with the
|
|
|
|
|
There are also raw string literals that are preceded with the
|
|
|
|
|
letter ``r`` (or ``R``) and are delimited by matching double quotes (just
|
|
|
|
|
like ordinary string literals) and do not interpret the escape sequences.
|
|
|
|
|
This is especially convenient for regular expressions or Windows paths:
|
|
|
|
|
@@ -313,7 +313,7 @@ Terminal symbols in the grammar: ``GENERALIZED_STR_LIT``,
|
|
|
|
|
|
|
|
|
|
The construct ``identifier"string literal"`` (without whitespace between the
|
|
|
|
|
identifier and the opening quotation mark) is a
|
|
|
|
|
`generalized raw string literal`:idx:. It is a shortcut for the construct
|
|
|
|
|
generalized raw string literal. It is a shortcut for the construct
|
|
|
|
|
``identifier(r"string literal")``, so it denotes a procedure call with a
|
|
|
|
|
raw string literal as its only argument. Generalized raw string literals
|
|
|
|
|
are especially convenient for embedding mini languages directly into Nimrod
|
|
|
|
|
@@ -365,7 +365,7 @@ type is used for Unicode characters, it can represent any Unicode character.
|
|
|
|
|
Numerical constants
|
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
|
|
`Numerical constants`:idx: are of a single type and have the form::
|
|
|
|
|
Numerical constants are of a single type and have the form::
|
|
|
|
|
|
|
|
|
|
hexdigit = digit | 'A'..'F' | 'a'..'f'
|
|
|
|
|
octdigit = '0'..'7'
|
|
|
|
|
@@ -440,7 +440,7 @@ is approximately 1.72826e35 according to the IEEE floating point standard.
|
|
|
|
|
Operators
|
|
|
|
|
---------
|
|
|
|
|
|
|
|
|
|
In Nimrod one can define his own operators. An `operator`:idx: is any
|
|
|
|
|
In Nimrod one can define his own operators. An operator is any
|
|
|
|
|
combination of the following characters::
|
|
|
|
|
|
|
|
|
|
= + - * / < >
|
|
|
|
|
@@ -587,7 +587,7 @@ The grammar's start symbol is ``module``.
|
|
|
|
|
Types
|
|
|
|
|
=====
|
|
|
|
|
|
|
|
|
|
All expressions have a `type`:idx: which is known at compile time. Nimrod
|
|
|
|
|
All expressions have a type which is known at compile time. Nimrod
|
|
|
|
|
is statically typed. One can declare new types, which is in essence defining
|
|
|
|
|
an identifier that can be used to denote this custom type.
|
|
|
|
|
|
|
|
|
|
@@ -605,7 +605,7 @@ These are the major type classes:
|
|
|
|
|
|
|
|
|
|
Ordinal types
|
|
|
|
|
-------------
|
|
|
|
|
`Ordinal types`:idx: have the following characteristics:
|
|
|
|
|
Ordinal types have the following characteristics:
|
|
|
|
|
|
|
|
|
|
- Ordinal types are countable and ordered. This property allows
|
|
|
|
|
the operation of functions as ``Inc``, ``Ord``, ``Dec`` on ordinal types to
|
|
|
|
|
@@ -705,7 +705,7 @@ For further details, see `Convertible relation`_.
|
|
|
|
|
|
|
|
|
|
Subrange types
|
|
|
|
|
--------------
|
|
|
|
|
A `subrange`:idx: type is a range of values from an ordinal type (the base
|
|
|
|
|
A subrange type is a range of values from an ordinal type (the base
|
|
|
|
|
type). To define a subrange type, one must specify it's limiting values: the
|
|
|
|
|
lowest and highest value of the type:
|
|
|
|
|
|
|
|
|
|
@@ -806,7 +806,7 @@ the ``+``, ``-``, ``*``, ``/`` operators for floating point types.
|
|
|
|
|
|
|
|
|
|
Boolean type
|
|
|
|
|
------------
|
|
|
|
|
The `boolean`:idx: type is named `bool`:idx: in Nimrod and can be one of the two
|
|
|
|
|
The boolean type is named `bool`:idx: in Nimrod and can be one of the two
|
|
|
|
|
pre-defined values ``true`` and ``false``. Conditions in while,
|
|
|
|
|
if, elif, when statements need to be of type bool.
|
|
|
|
|
|
|
|
|
|
@@ -830,7 +830,7 @@ The size of the bool type is one byte.
|
|
|
|
|
|
|
|
|
|
Character type
|
|
|
|
|
--------------
|
|
|
|
|
The `character type`:idx: is named ``char`` in Nimrod. Its size is one byte.
|
|
|
|
|
The character type is named ``char`` in Nimrod. Its size is one byte.
|
|
|
|
|
Thus it cannot represent an UTF-8 character, but a part of it.
|
|
|
|
|
The reason for this is efficiency: for the overwhelming majority of use-cases,
|
|
|
|
|
the resulting programs will still handle UTF-8 properly as UTF-8 was specially
|
|
|
|
|
@@ -845,7 +845,7 @@ character. ``TRune`` is declared in the `unicode module <unicode.html>`_.
|
|
|
|
|
|
|
|
|
|
Enumeration types
|
|
|
|
|
-----------------
|
|
|
|
|
`Enumeration`:idx: types define a new type whose values consist of the ones
|
|
|
|
|
Enumeration types define a new type whose values consist of the ones
|
|
|
|
|
specified. The values are ordered. Example:
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
@@ -915,7 +915,7 @@ via ``TMyEnum.value``:
|
|
|
|
|
|
|
|
|
|
String type
|
|
|
|
|
-----------
|
|
|
|
|
All string literals are of the type `string`:idx:. A string in Nimrod is very
|
|
|
|
|
All string literals are of the type ``string``. A string in Nimrod is very
|
|
|
|
|
similar to a sequence of characters. However, strings in Nimrod are both
|
|
|
|
|
zero-terminated and have a length field. One can retrieve the length with the
|
|
|
|
|
builtin ``len`` procedure; the length never counts the terminating zero.
|
|
|
|
|
@@ -942,7 +942,7 @@ i-th *unichar*. The iterator ``runes`` from the `unicode module
|
|
|
|
|
|
|
|
|
|
CString type
|
|
|
|
|
------------
|
|
|
|
|
The `cstring`:idx: type represents a pointer to a zero-terminated char array
|
|
|
|
|
The ``cstring`` type represents a pointer to a zero-terminated char array
|
|
|
|
|
compatible to the type ``char*`` in Ansi C. Its primary purpose lies in easy
|
|
|
|
|
interfacing with C. The index operation ``s[i]`` means the i-th *char* of
|
|
|
|
|
``s``; however no bounds checking for ``cstring`` is performed making the
|
|
|
|
|
@@ -968,20 +968,20 @@ not work.
|
|
|
|
|
|
|
|
|
|
Structured types
|
|
|
|
|
----------------
|
|
|
|
|
A variable of a `structured type`:idx: can hold multiple values at the same
|
|
|
|
|
A variable of a structured type can hold multiple values at the same
|
|
|
|
|
time. Structured types can be nested to unlimited levels. Arrays, sequences,
|
|
|
|
|
tuples, objects and sets belong to the structured types.
|
|
|
|
|
|
|
|
|
|
Array and sequence types
|
|
|
|
|
------------------------
|
|
|
|
|
`Arrays`:idx: are a homogeneous type, meaning that each element in the array
|
|
|
|
|
Arrays are a homogeneous type, meaning that each element in the array
|
|
|
|
|
has the same type. Arrays always have a fixed length which is specified at
|
|
|
|
|
compile time (except for open arrays). They can be indexed by any ordinal type.
|
|
|
|
|
A parameter ``A`` may be an *open array*, in which case it is indexed by
|
|
|
|
|
integers from 0 to ``len(A)-1``. An array expression may be constructed by the
|
|
|
|
|
array constructor ``[]``.
|
|
|
|
|
|
|
|
|
|
`Sequences`:idx: are similar to arrays but of dynamic length which may change
|
|
|
|
|
Sequences are similar to arrays but of dynamic length which may change
|
|
|
|
|
during runtime (like strings). Sequences are implemented as growable arrays,
|
|
|
|
|
allocating pieces of memory as items are added. A sequence ``S`` is always
|
|
|
|
|
indexed by integers from 0 to ``len(S)-1`` and its bounds are checked.
|
|
|
|
|
@@ -1038,7 +1038,7 @@ supported because this is seldom needed and cannot be done efficiently.
|
|
|
|
|
Varargs
|
|
|
|
|
-------
|
|
|
|
|
|
|
|
|
|
A `varargs`:idx: parameter is an openarray parameter that additionally
|
|
|
|
|
A ``varargs`` parameter is an openarray parameter that additionally
|
|
|
|
|
allows to pass a variable number of arguments to a procedure. The compiler
|
|
|
|
|
converts the list of arguments to an array implicitly:
|
|
|
|
|
|
|
|
|
|
@@ -1073,7 +1073,7 @@ parameter ``a``. (Note that ``$`` applied to strings is a nop.)
|
|
|
|
|
|
|
|
|
|
Tuples and object types
|
|
|
|
|
-----------------------
|
|
|
|
|
A variable of a `tuple`:idx: or `object`:idx: type is a heterogeneous storage
|
|
|
|
|
A variable of a tuple or object type is a heterogeneous storage
|
|
|
|
|
container.
|
|
|
|
|
A tuple or object defines various named *fields* of a type. A tuple also
|
|
|
|
|
defines an *order* of the fields. Tuples are meant for heterogeneous storage
|
|
|
|
|
@@ -1153,7 +1153,7 @@ For a ``ref object`` type ``system.new`` is invoked implicitly.
|
|
|
|
|
Object variants
|
|
|
|
|
---------------
|
|
|
|
|
Often an object hierarchy is overkill in certain situations where simple
|
|
|
|
|
`variant`:idx: types are needed.
|
|
|
|
|
variant types are needed.
|
|
|
|
|
|
|
|
|
|
An example:
|
|
|
|
|
|
|
|
|
|
@@ -1211,7 +1211,7 @@ branch switch ``system.reset`` has to be used.
|
|
|
|
|
|
|
|
|
|
Set type
|
|
|
|
|
--------
|
|
|
|
|
The `set type`:idx: models the mathematical notion of a set. The set's
|
|
|
|
|
The set type models the mathematical notion of a set. The set's
|
|
|
|
|
basetype can only be an ordinal type. The reason is that sets are implemented
|
|
|
|
|
as high performance bit vectors.
|
|
|
|
|
|
|
|
|
|
@@ -1246,7 +1246,7 @@ operation meaning
|
|
|
|
|
|
|
|
|
|
Reference and pointer types
|
|
|
|
|
---------------------------
|
|
|
|
|
References (similar to `pointers`:idx: in other programming languages) are a
|
|
|
|
|
References (similar to pointers in other programming languages) are a
|
|
|
|
|
way to introduce many-to-one relationships. This means different references can
|
|
|
|
|
point to and modify the same location in memory (also called `aliasing`:idx:).
|
|
|
|
|
|
|
|
|
|
@@ -1344,7 +1344,7 @@ Not nil annotation
|
|
|
|
|
------------------
|
|
|
|
|
|
|
|
|
|
All types for that ``nil`` is a valid value can be annotated to
|
|
|
|
|
exclude ``nil`` as a valid value with the `not nil`:idx: annotation:
|
|
|
|
|
exclude ``nil`` as a valid value with the ``not nil`` annotation:
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
type
|
|
|
|
|
@@ -1369,7 +1369,7 @@ here.
|
|
|
|
|
Memory regions
|
|
|
|
|
--------------
|
|
|
|
|
|
|
|
|
|
The types ``ref`` and ``ptr`` can get an optional `region`:idx: annotation.
|
|
|
|
|
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
|
|
|
|
|
@@ -1428,7 +1428,7 @@ Future directions:
|
|
|
|
|
|
|
|
|
|
Procedural type
|
|
|
|
|
---------------
|
|
|
|
|
A `procedural type`:idx: is internally a pointer to a procedure. ``nil`` is
|
|
|
|
|
A procedural type is internally a pointer to a procedure. ``nil`` is
|
|
|
|
|
an allowed value for variables of a procedural type. Nimrod uses procedural
|
|
|
|
|
types to achieve `functional`:idx: programming techniques.
|
|
|
|
|
|
|
|
|
|
@@ -1536,7 +1536,7 @@ accesses its environment. If it does so, it has the calling convention
|
|
|
|
|
Distinct type
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
A `distinct type`:idx: is new type derived from a `base type`:idx: that is
|
|
|
|
|
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
|
|
|
|
|
@@ -1654,7 +1654,7 @@ Currently only the dot accessor can be borrowed in this way.
|
|
|
|
|
Void type
|
|
|
|
|
---------
|
|
|
|
|
|
|
|
|
|
The `void`:idx: type denotes the absense of any type. Parameters of
|
|
|
|
|
The ``void`` type denotes the absense of any type. Parameters of
|
|
|
|
|
type ``void`` are treated as non-existent, ``void`` as a return type means that
|
|
|
|
|
the procedure does not return a value:
|
|
|
|
|
|
|
|
|
|
@@ -1887,7 +1887,7 @@ To be written.
|
|
|
|
|
Statements and expressions
|
|
|
|
|
==========================
|
|
|
|
|
|
|
|
|
|
Nimrod uses the common statement/expression paradigm: `Statements`:idx: do not
|
|
|
|
|
Nimrod uses the common statement/expression paradigm: Statements do not
|
|
|
|
|
produce a value in contrast to expressions. However, some expressions are
|
|
|
|
|
statements.
|
|
|
|
|
|
|
|
|
|
@@ -1904,7 +1904,7 @@ Statement list expression
|
|
|
|
|
|
|
|
|
|
Statements can also occur in an expression context that looks
|
|
|
|
|
like ``(stmt1; stmt2; ...; ex)``. This is called
|
|
|
|
|
an `statement list expression`:idx: or ``(;)``. The type
|
|
|
|
|
an statement list expression or ``(;)``. The type
|
|
|
|
|
of ``(stmt1; stmt2; ...; ex)`` is the type of ``ex``. All the other statements
|
|
|
|
|
must be of type ``void``. (One can use ``discard`` to produce a ``void`` type.)
|
|
|
|
|
``(;)`` does not introduce a new scope.
|
|
|
|
|
@@ -1921,7 +1921,7 @@ Example:
|
|
|
|
|
|
|
|
|
|
discard p(3, 4) # discard the return value of `p`
|
|
|
|
|
|
|
|
|
|
The `discard`:idx: statement evaluates its expression for side-effects and
|
|
|
|
|
The ``discard`` statement evaluates its expression for side-effects and
|
|
|
|
|
throws the expression's resulting value away.
|
|
|
|
|
|
|
|
|
|
Ignoring the return value of a procedure without using a discard statement is
|
|
|
|
|
@@ -1949,7 +1949,7 @@ An empty ``discard`` statement is often used as a null statement:
|
|
|
|
|
Var statement
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
`Var`:idx: statements declare new local and global variables and
|
|
|
|
|
Var statements declare new local and global variables and
|
|
|
|
|
initialize them. A comma separated list of variables can be used to specify
|
|
|
|
|
variables of the same type:
|
|
|
|
|
|
|
|
|
|
@@ -2018,7 +2018,7 @@ initialized and does not rely on syntactic properties:
|
|
|
|
|
let statement
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
A `Let`:idx: statement declares new local and global `single assignment`:idx:
|
|
|
|
|
A ``let`` statement declares new local and global `single assignment`:idx:
|
|
|
|
|
variables and binds a value to them. The syntax is the of the ``var``
|
|
|
|
|
statement, except that the keyword ``var`` is replaced by the keyword ``let``.
|
|
|
|
|
Let variables are not l-values and can thus not be passed to ``var`` parameters
|
|
|
|
|
@@ -2060,7 +2060,7 @@ they contain such a type.
|
|
|
|
|
Static statement/expression
|
|
|
|
|
---------------------------
|
|
|
|
|
|
|
|
|
|
A `static`:idx: statement/expression can be used to enforce compile
|
|
|
|
|
A static statement/expression can be used to enforce compile
|
|
|
|
|
time evaluation explicitly. Enforced compile time evaluation can even evaluate
|
|
|
|
|
code that has side effects:
|
|
|
|
|
|
|
|
|
|
@@ -2094,7 +2094,7 @@ Example:
|
|
|
|
|
else:
|
|
|
|
|
echo("Boring name...")
|
|
|
|
|
|
|
|
|
|
The `if`:idx: statement is a simple way to make a branch in the control flow:
|
|
|
|
|
The ``if`` statement is a simple way to make a branch in the control flow:
|
|
|
|
|
The expression after the keyword ``if`` is evaluated, if it is true
|
|
|
|
|
the corresponding statements after the ``:`` are executed. Otherwise
|
|
|
|
|
the expression after the ``elif`` is evaluated (if there is an
|
|
|
|
|
@@ -2140,7 +2140,7 @@ Example:
|
|
|
|
|
else: echo("unknown command")
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The `case`:idx: statement is similar to the if statement, but it represents
|
|
|
|
|
The ``case`` statement is similar to the if statement, but it represents
|
|
|
|
|
a multi-branch selection. The expression after the keyword ``case`` is
|
|
|
|
|
evaluated and if its value is in a *slicelist* the corresponding statements
|
|
|
|
|
(after the ``of`` keyword) are executed. If the value is not in any
|
|
|
|
|
@@ -2194,7 +2194,7 @@ Example:
|
|
|
|
|
else:
|
|
|
|
|
echo("cannot happen!")
|
|
|
|
|
|
|
|
|
|
The `when`:idx: statement is almost identical to the ``if`` statement with some
|
|
|
|
|
The ``when`` statement is almost identical to the ``if`` statement with some
|
|
|
|
|
exceptions:
|
|
|
|
|
|
|
|
|
|
* Each condition (``expr``) has to be a constant expression (of type ``bool``).
|
|
|
|
|
@@ -2216,7 +2216,7 @@ Example:
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
return 40+2
|
|
|
|
|
|
|
|
|
|
The `return`:idx: statement ends the execution of the current procedure.
|
|
|
|
|
The ``return`` statement ends the execution of the current procedure.
|
|
|
|
|
It is only allowed in procedures. If there is an ``expr``, this is syntactic
|
|
|
|
|
sugar for:
|
|
|
|
|
|
|
|
|
|
@@ -2243,7 +2243,7 @@ Example:
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
yield (1, 2, 3)
|
|
|
|
|
|
|
|
|
|
The `yield`:idx: statement is used instead of the ``return`` statement in
|
|
|
|
|
The ``yield`` statement is used instead of the ``return`` statement in
|
|
|
|
|
iterators. It is only valid in iterators. Execution is returned to the body
|
|
|
|
|
of the for loop that called the iterator. Yield does not end the iteration
|
|
|
|
|
process, but execution is passed back to the iterator if the next iteration
|
|
|
|
|
@@ -2266,7 +2266,7 @@ Example:
|
|
|
|
|
break myblock # leave the block, in this case both for-loops
|
|
|
|
|
echo(found)
|
|
|
|
|
|
|
|
|
|
The block statement is a means to group statements to a (named) `block`:idx:.
|
|
|
|
|
The block statement is a means to group statements to a (named) ``block``.
|
|
|
|
|
Inside the block, the ``break`` statement is allowed to leave the block
|
|
|
|
|
immediately. A ``break`` statement can contain a name of a surrounding
|
|
|
|
|
block to specify which block is to leave.
|
|
|
|
|
@@ -2280,7 +2280,7 @@ Example:
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
break
|
|
|
|
|
|
|
|
|
|
The `break`:idx: statement is used to leave a block immediately. If ``symbol``
|
|
|
|
|
The ``break`` statement is used to leave a block immediately. If ``symbol``
|
|
|
|
|
is given, it is the name of the enclosing block that is to leave. If it is
|
|
|
|
|
absent, the innermost block is left.
|
|
|
|
|
|
|
|
|
|
@@ -2298,7 +2298,7 @@ Example:
|
|
|
|
|
pw = readLine(stdin)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The `while`:idx: statement is executed until the ``expr`` evaluates to false.
|
|
|
|
|
The ``while`` statement is executed until the ``expr`` evaluates to false.
|
|
|
|
|
Endless loops are no error. ``while`` statements open an `implicit block`,
|
|
|
|
|
so that they can be left with a ``break`` statement.
|
|
|
|
|
|
|
|
|
|
@@ -2306,7 +2306,7 @@ so that they can be left with a ``break`` statement.
|
|
|
|
|
Continue statement
|
|
|
|
|
------------------
|
|
|
|
|
|
|
|
|
|
A `continue`:idx: statement leads to the immediate next iteration of the
|
|
|
|
|
A ``continue`` statement leads to the immediate next iteration of the
|
|
|
|
|
surrounding loop construct. It is only allowed within a loop. A continue
|
|
|
|
|
statement is syntactic sugar for a nested block:
|
|
|
|
|
|
|
|
|
|
@@ -2329,7 +2329,7 @@ Is equivalent to:
|
|
|
|
|
Assembler statement
|
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
|
|
The direct embedding of `assembler`:idx: code into Nimrod code is supported
|
|
|
|
|
The direct embedding of assembler code into Nimrod code is supported
|
|
|
|
|
by the unsafe ``asm`` statement. Identifiers in the assembler code that refer to
|
|
|
|
|
Nimrod identifiers shall be enclosed in a special character which can be
|
|
|
|
|
specified in the statement's pragmas. The default special character is ``'`'``:
|
|
|
|
|
@@ -2376,7 +2376,7 @@ Using statement
|
|
|
|
|
|
|
|
|
|
**Warning**: The ``using`` statement is highly experimental!
|
|
|
|
|
|
|
|
|
|
The `using statement`:idx: provides syntactic convenience for procs that
|
|
|
|
|
The using statement provides syntactic convenience for procs that
|
|
|
|
|
heavily use a single contextual parameter. When applied to a variable or a
|
|
|
|
|
constant, it will instruct Nimrod to automatically consider the used symbol as
|
|
|
|
|
a hidden leading parameter for any procedure calls, following the using
|
|
|
|
|
@@ -2461,7 +2461,7 @@ the last expression as the result value, much like in an `expr` template.
|
|
|
|
|
Table constructor
|
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
|
|
A `table constructor`:idx: is syntactic sugar for an array constructor:
|
|
|
|
|
A table constructor is syntactic sugar for an array constructor:
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
{"key1": "value1", "key2", "key3": "value2"}
|
|
|
|
|
@@ -2508,7 +2508,7 @@ only needed for low-level programming and are inherently unsafe.
|
|
|
|
|
|
|
|
|
|
The addr operator
|
|
|
|
|
-----------------
|
|
|
|
|
The `addr`:idx: operator returns the address of an l-value. If the type of the
|
|
|
|
|
The ``addr`` operator returns the address of an l-value. If the type of the
|
|
|
|
|
location is ``T``, the `addr` operator result is of the type ``ptr T``. An
|
|
|
|
|
address is always an untraced reference. Taking the address of an object that
|
|
|
|
|
resides on the stack is **unsafe**, as the pointer may live longer than the
|
|
|
|
|
@@ -2609,7 +2609,7 @@ For object oriented programming, the syntax ``obj.method(args)`` can be used
|
|
|
|
|
instead of ``method(obj, args)``. The parentheses can be omitted if there are no
|
|
|
|
|
remaining arguments: ``obj.len`` (instead of ``len(obj)``).
|
|
|
|
|
|
|
|
|
|
This `method call syntax`:idx: is not restricted to objects, it can be used
|
|
|
|
|
This method call syntax is not restricted to objects, it can be used
|
|
|
|
|
to supply any type of first argument for procedures:
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
@@ -2654,7 +2654,7 @@ Command invocation syntax
|
|
|
|
|
-------------------------
|
|
|
|
|
|
|
|
|
|
Routines can be invoked without the ``()`` if the call is syntatically
|
|
|
|
|
a statement. This `command invocation syntax`:idx: also works for
|
|
|
|
|
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
|
|
|
|
|
``echo(f(1, f(2)))``. The method call syntax may be used to provide one
|
|
|
|
|
@@ -2851,7 +2851,7 @@ The ``[]`` subscript operator for arrays/openarrays/sequences can be overloaded.
|
|
|
|
|
Multi-methods
|
|
|
|
|
=============
|
|
|
|
|
|
|
|
|
|
Procedures always use static dispatch. `Multi-methods`:idx: use dynamic
|
|
|
|
|
Procedures always use static dispatch. Multi-methods use dynamic
|
|
|
|
|
dispatch.
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
@@ -3104,7 +3104,7 @@ Example:
|
|
|
|
|
line: int # the line the symbol was declared in
|
|
|
|
|
code: PNode # the symbol's abstract syntax tree
|
|
|
|
|
|
|
|
|
|
A `type`:idx: section begins with the ``type`` keyword. It contains multiple
|
|
|
|
|
A type section begins with the ``type`` keyword. It contains multiple
|
|
|
|
|
type definitions. A type definition binds a type to a name. Type definitions
|
|
|
|
|
can be recursive or even mutually recursive. Mutually recursive types are only
|
|
|
|
|
possible within a single ``type`` section. Nominal types like ``objects``
|
|
|
|
|
@@ -3141,7 +3141,7 @@ Example:
|
|
|
|
|
close(f)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The statements after the `try`:idx: are executed in sequential order unless
|
|
|
|
|
The statements after the ``try`` are executed in sequential order unless
|
|
|
|
|
an exception ``e`` is raised. If the exception type of ``e`` matches any
|
|
|
|
|
listed in an ``except`` clause the corresponding statements are executed.
|
|
|
|
|
The statements following the ``except`` clauses are called
|
|
|
|
|
@@ -3163,7 +3163,7 @@ is not executed (if an exception occurs).
|
|
|
|
|
Except and finally statements
|
|
|
|
|
-----------------------------
|
|
|
|
|
|
|
|
|
|
`except`:idx: and `finally`:idx: can also be used as a stand-alone statements.
|
|
|
|
|
``except`` and ``finally`` can also be used as a stand-alone statements.
|
|
|
|
|
Any statements following them in the current block will be considered to be
|
|
|
|
|
in an implicit try block:
|
|
|
|
|
|
|
|
|
|
@@ -3212,9 +3212,9 @@ exception (unless a raise hook has been provided).
|
|
|
|
|
OnRaise builtin
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
``system.onRaise`` can be used to override the behaviour of ``raise`` for a
|
|
|
|
|
single ``try`` statement. `onRaise`:idx: has to be called within the ``try``
|
|
|
|
|
statement that should be affected.
|
|
|
|
|
`system.onRaise() <system.html#onRaise>`_ can be used to override the
|
|
|
|
|
behaviour of ``raise`` for a single ``try`` statement. ``onRaise`` has to be
|
|
|
|
|
called within the ``try`` statement that should be affected.
|
|
|
|
|
|
|
|
|
|
This allows for a Lisp-like `condition system`:idx:\:
|
|
|
|
|
|
|
|
|
|
@@ -3243,7 +3243,7 @@ Effect system
|
|
|
|
|
Exception tracking
|
|
|
|
|
------------------
|
|
|
|
|
|
|
|
|
|
Nimrod supports `exception tracking`:idx:. The `raises`:idx: pragma can be used
|
|
|
|
|
Nimrod supports exception tracking. The `raises`:idx: pragma can be used
|
|
|
|
|
to explicitly define which exceptions a proc/iterator/method/converter is
|
|
|
|
|
allowed to raise. The compiler verifies this:
|
|
|
|
|
|
|
|
|
|
@@ -3351,7 +3351,7 @@ exception tracking.
|
|
|
|
|
Effects pragma
|
|
|
|
|
--------------
|
|
|
|
|
|
|
|
|
|
The `effects`:idx: pragma has been designed to assist the programmer with the
|
|
|
|
|
The ``effects`` pragma has been designed to assist the programmer with the
|
|
|
|
|
effects analysis. It is a statement that makes the compiler output all inferred
|
|
|
|
|
effects up to the ``effects``'s position:
|
|
|
|
|
|
|
|
|
|
@@ -3420,7 +3420,7 @@ Example:
|
|
|
|
|
for str in inorder(root):
|
|
|
|
|
writeln(stdout, str)
|
|
|
|
|
|
|
|
|
|
`Generics`:idx: are Nimrod's means to parametrize procs, iterators or types with
|
|
|
|
|
Generics are Nimrod's means to parametrize procs, iterators or types with
|
|
|
|
|
`type parameters`:idx:. Depending on context, the brackets are used either to
|
|
|
|
|
introduce type parameters or to instantiate a generic proc, iterator or type.
|
|
|
|
|
|
|
|
|
|
@@ -3428,7 +3428,7 @@ introduce type parameters or to instantiate a generic proc, iterator or type.
|
|
|
|
|
Is operator
|
|
|
|
|
-----------
|
|
|
|
|
|
|
|
|
|
The `is`:idx: operator checks for type equivalence at compile time. It is
|
|
|
|
|
The ``is`` operator checks for type equivalence at compile time. It is
|
|
|
|
|
therefore very useful for type specialization within generic code:
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
@@ -3443,7 +3443,7 @@ therefore very useful for type specialization within generic code:
|
|
|
|
|
Type operator
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
The `type`:idx: (in many other languages called `typeof`:idx:) operator can
|
|
|
|
|
The ``type`` (in many other languages called `typeof`:idx:) operator can
|
|
|
|
|
be used to get the type of an expression:
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
@@ -3466,7 +3466,7 @@ other interpretations:
|
|
|
|
|
Type Classes
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
|
|
A `type class`:idx: is a special pseudo-type that can be used to match against
|
|
|
|
|
A type class is a special pseudo-type that can be used to match against
|
|
|
|
|
types in the context of overload resolution or the ``is`` operator.
|
|
|
|
|
Nimrod supports the following built-in type classes:
|
|
|
|
|
|
|
|
|
|
@@ -3684,7 +3684,7 @@ A symbol can be forced to be open by a `mixin`:idx: declaration:
|
|
|
|
|
Bind statement
|
|
|
|
|
--------------
|
|
|
|
|
|
|
|
|
|
The `bind`:idx: statement is the counterpart to the ``mixin`` statement. It
|
|
|
|
|
The ``bind`` statement is the counterpart to the ``mixin`` statement. It
|
|
|
|
|
can be used to explicitly declare identifiers that should be bound early (i.e.
|
|
|
|
|
the identifiers should be looked up in the scope of the template/generic
|
|
|
|
|
definition):
|
|
|
|
|
@@ -3712,7 +3712,7 @@ scope is the default.
|
|
|
|
|
Templates
|
|
|
|
|
=========
|
|
|
|
|
|
|
|
|
|
A `template`:idx: is a simple form of a macro: It is a simple substitution
|
|
|
|
|
A template is a simple form of a macro: It is a simple substitution
|
|
|
|
|
mechanism that operates on Nimrod's abstract syntax trees. It is processed in
|
|
|
|
|
the semantic pass of the compiler.
|
|
|
|
|
|
|
|
|
|
@@ -3744,7 +3744,7 @@ expected.
|
|
|
|
|
Ordinary vs immediate templates
|
|
|
|
|
-------------------------------
|
|
|
|
|
|
|
|
|
|
There are two different kinds of templates: `immediate`:idx: templates and
|
|
|
|
|
There are two different kinds of templates: immediate templates and
|
|
|
|
|
ordinary templates. Ordinary templates take part in overloading resolution. As
|
|
|
|
|
such their arguments need to be type checked before the template is invoked.
|
|
|
|
|
So ordinary templates cannot receive undeclared identifiers:
|
|
|
|
|
@@ -3939,7 +3939,7 @@ a template. ``inject`` and ``gensym`` have no effect in ``dirty`` templates.
|
|
|
|
|
Macros
|
|
|
|
|
======
|
|
|
|
|
|
|
|
|
|
A `macro`:idx: is a special kind of low level template. Macros can be used
|
|
|
|
|
A macro is a special kind of low level template. Macros can be used
|
|
|
|
|
to implement `domain specific languages`:idx:. Like templates, macros come in
|
|
|
|
|
the 2 flavors *immediate* and *ordinary*.
|
|
|
|
|
|
|
|
|
|
@@ -4317,7 +4317,7 @@ This operator will be matched against assignments to missing fields.
|
|
|
|
|
Term rewriting macros
|
|
|
|
|
=====================
|
|
|
|
|
|
|
|
|
|
`Term rewriting macros`:idx: are macros or templates that have not only
|
|
|
|
|
Term rewriting macros are macros or templates that have not only
|
|
|
|
|
a *name* but also a *pattern* that is searched for after the semantic checking
|
|
|
|
|
phase of the compiler: This means they provide an easy way to enhance the
|
|
|
|
|
compilation pipeline with user defined optimizations:
|
|
|
|
|
@@ -4653,7 +4653,7 @@ ordinary routines.
|
|
|
|
|
Move optimization
|
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
|
|
The ``call`` constraint is particularly useful to implement a `move`:idx:
|
|
|
|
|
The ``call`` constraint is particularly useful to implement a move
|
|
|
|
|
optimization for types that have copying semantics:
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
@@ -4679,7 +4679,7 @@ optimization for types that have copying semantics:
|
|
|
|
|
|
|
|
|
|
Modules
|
|
|
|
|
=======
|
|
|
|
|
Nimrod supports splitting a program into pieces by a `module`:idx: concept.
|
|
|
|
|
Nimrod supports splitting a program into pieces by a module concept.
|
|
|
|
|
Each module needs to be in its own file and has its own `namespace`:idx:.
|
|
|
|
|
Modules enable `information hiding`:idx: and `separate compilation`:idx:.
|
|
|
|
|
A module may gain access to symbols of another module by the `import`:idx:
|
|
|
|
|
@@ -4722,7 +4722,7 @@ This is best illustrated by an example:
|
|
|
|
|
Import statement
|
|
|
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
After the `import`:idx: statement a list of module names can follow or a single
|
|
|
|
|
After the ``import`` statement a list of module names can follow or a single
|
|
|
|
|
module name followed by an ``except`` to prevent some symbols to be imported:
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
@@ -4765,7 +4765,7 @@ Likewise the following does not make sense as the name is ``strutils`` already:
|
|
|
|
|
From import statement
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
After the `from`:idx: statement a module name follows followed by
|
|
|
|
|
After the ``from`` statement a module name follows followed by
|
|
|
|
|
an ``import`` to list the symbols one likes to use without explict
|
|
|
|
|
full qualification:
|
|
|
|
|
|
|
|
|
|
@@ -4784,7 +4784,7 @@ in ``module``.
|
|
|
|
|
Export statement
|
|
|
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
An `export`:idx: statement can be used for symbol fowarding so that client
|
|
|
|
|
An ``export`` statement can be used for symbol fowarding so that client
|
|
|
|
|
modules don't need to import a module's dependencies:
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
@@ -4812,7 +4812,7 @@ Scope rules
|
|
|
|
|
-----------
|
|
|
|
|
Identifiers are valid from the point of their declaration until the end of
|
|
|
|
|
the block in which the declaration occurred. The range where the identifier
|
|
|
|
|
is known is the `scope`:idx: of the identifier. The exact scope of an
|
|
|
|
|
is known is the scope of the identifier. The exact scope of an
|
|
|
|
|
identifier depends on the way it was declared.
|
|
|
|
|
|
|
|
|
|
Block scope
|
|
|
|
|
@@ -4885,7 +4885,7 @@ to access the feature becomes available.
|
|
|
|
|
|
|
|
|
|
noSideEffect pragma
|
|
|
|
|
-------------------
|
|
|
|
|
The `noSideEffect`:idx: pragma is used to mark a proc/iterator to have no side
|
|
|
|
|
The ``noSideEffect`` pragma is used to mark a proc/iterator to have no side
|
|
|
|
|
effects. This means that the proc/iterator only changes locations that are
|
|
|
|
|
reachable from its parameters and the return value only depends on the
|
|
|
|
|
arguments. If none of its parameters have the type ``var T``
|
|
|
|
|
@@ -4907,7 +4907,7 @@ proc with no side effects:
|
|
|
|
|
destructor pragma
|
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
|
|
The `destructor`:idx: pragma is used to mark a proc to act as a type destructor.
|
|
|
|
|
The ``destructor`` pragma is used to mark a proc to act as a type destructor.
|
|
|
|
|
The proc must have a single parameter with a concrete type (the name of a
|
|
|
|
|
generic type is allowed too).
|
|
|
|
|
|
|
|
|
|
@@ -4967,25 +4967,25 @@ the ``finalizer`` parameter to ``new``.
|
|
|
|
|
|
|
|
|
|
procvar pragma
|
|
|
|
|
--------------
|
|
|
|
|
The `procvar`:idx: pragma is used to mark a proc that it can be passed to a
|
|
|
|
|
The ``procvar`` pragma is used to mark a proc that it can be passed to a
|
|
|
|
|
procedural variable.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
compileTime pragma
|
|
|
|
|
------------------
|
|
|
|
|
The `compileTime`:idx: pragma is used to mark a proc to be used at compile
|
|
|
|
|
The ``compileTime`` pragma is used to mark a proc to be used at compile
|
|
|
|
|
time only. No code will be generated for it. Compile time procs are useful
|
|
|
|
|
as helpers for macros.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
noReturn pragma
|
|
|
|
|
---------------
|
|
|
|
|
The `noreturn`:idx: pragma is used to mark a proc that never returns.
|
|
|
|
|
The ``noreturn`` pragma is used to mark a proc that never returns.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Acyclic pragma
|
|
|
|
|
--------------
|
|
|
|
|
The `acyclic`:idx: pragma can be used for object types to mark them as acyclic
|
|
|
|
|
The ``acyclic`` pragma can be used for object types to mark them as acyclic
|
|
|
|
|
even though they seem to be cyclic. This is an **optimization** for the garbage
|
|
|
|
|
collector to not consider objects of this type as part of a cycle:
|
|
|
|
|
|
|
|
|
|
@@ -5016,13 +5016,13 @@ memory, but nothing worse happens.
|
|
|
|
|
|
|
|
|
|
Final pragma
|
|
|
|
|
------------
|
|
|
|
|
The `final`:idx: pragma can be used for an object type to specify that it
|
|
|
|
|
The ``final`` pragma can be used for an object type to specify that it
|
|
|
|
|
cannot be inherited from.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
shallow pragma
|
|
|
|
|
--------------
|
|
|
|
|
The `shallow`:idx: pragma affects the semantics of a type: The compiler is
|
|
|
|
|
The ``shallow`` pragma affects the semantics of a type: The compiler is
|
|
|
|
|
allowed to make a shallow copy. This can cause serious semantic issues and
|
|
|
|
|
break memory safety! However, it can speed up assignments considerably,
|
|
|
|
|
because the semantics of Nimrod require deep copying of sequences and strings.
|
|
|
|
|
@@ -5042,14 +5042,14 @@ structure:
|
|
|
|
|
|
|
|
|
|
Pure pragma
|
|
|
|
|
-----------
|
|
|
|
|
An object type can be marked with the `pure`:idx: pragma so that its type
|
|
|
|
|
An object type can be marked with the ``pure`` pragma so that its type
|
|
|
|
|
field which is used for runtime type identification is omitted. This is
|
|
|
|
|
necessary for binary compatibility with other compiled languages.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
AsmNoStackFrame pragma
|
|
|
|
|
----------------------
|
|
|
|
|
A proc can be marked with the `AsmNoStackFrame`:idx: pragma to tell the compiler
|
|
|
|
|
A proc can be marked with the ``AsmNoStackFrame`` pragma to tell the compiler
|
|
|
|
|
it should not generate a stack frame for the proc. There are also no exit
|
|
|
|
|
statements like ``return result;`` generated and the generated C function is
|
|
|
|
|
declared as ``__declspec(naked)`` or ``__attribute__((naked))`` (depending on
|
|
|
|
|
@@ -5060,7 +5060,7 @@ assembler statements.
|
|
|
|
|
|
|
|
|
|
error pragma
|
|
|
|
|
------------
|
|
|
|
|
The `error`:idx: pragma is used to make the compiler output an error message
|
|
|
|
|
The ``error`` pragma is used to make the compiler output an error message
|
|
|
|
|
with the given content. Compilation does not necessarily abort after an error
|
|
|
|
|
though.
|
|
|
|
|
|
|
|
|
|
@@ -5076,7 +5076,7 @@ operation is valid due to overloading and type conversions:
|
|
|
|
|
|
|
|
|
|
fatal pragma
|
|
|
|
|
------------
|
|
|
|
|
The `fatal`:idx: pragma is used to make the compiler output an error message
|
|
|
|
|
The ``fatal`` pragma is used to make the compiler output an error message
|
|
|
|
|
with the given content. In contrast to the ``error`` pragma, compilation
|
|
|
|
|
is guaranteed to be aborted by this pragma. Example:
|
|
|
|
|
|
|
|
|
|
@@ -5086,17 +5086,17 @@ is guaranteed to be aborted by this pragma. Example:
|
|
|
|
|
|
|
|
|
|
warning pragma
|
|
|
|
|
--------------
|
|
|
|
|
The `warning`:idx: pragma is used to make the compiler output a warning message
|
|
|
|
|
The ``warning`` pragma is used to make the compiler output a warning message
|
|
|
|
|
with the given content. Compilation continues after the warning.
|
|
|
|
|
|
|
|
|
|
hint pragma
|
|
|
|
|
-----------
|
|
|
|
|
The `hint`:idx: pragma is used to make the compiler output a hint message with
|
|
|
|
|
The ``hint`` pragma is used to make the compiler output a hint message with
|
|
|
|
|
the given content. Compilation continues after the hint.
|
|
|
|
|
|
|
|
|
|
line pragma
|
|
|
|
|
-----------
|
|
|
|
|
The `line`:idx: pragma can be used to affect line information of the annotated
|
|
|
|
|
The ``line`` pragma can be used to affect line information of the annotated
|
|
|
|
|
statement as seen in stack backtraces:
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
@@ -5114,7 +5114,7 @@ If the ``line`` pragma is used with a parameter, the parameter needs be a
|
|
|
|
|
|
|
|
|
|
linearScanEnd pragma
|
|
|
|
|
--------------------
|
|
|
|
|
The `linearScanEnd`:idx: pragma can be used to tell the compiler how to
|
|
|
|
|
The ``linearScanEnd`` pragma can be used to tell the compiler how to
|
|
|
|
|
compile a Nimrod `case`:idx: statement. Syntactically it has to be used as a
|
|
|
|
|
statement:
|
|
|
|
|
|
|
|
|
|
@@ -5142,7 +5142,7 @@ whole ``case`` statement, the whole ``case`` statement uses linear scanning.
|
|
|
|
|
|
|
|
|
|
computedGoto pragma
|
|
|
|
|
-------------------
|
|
|
|
|
The `computedGoto`:idx: pragma can be used to tell the compiler how to
|
|
|
|
|
The ``computedGoto`` pragma can be used to tell the compiler how to
|
|
|
|
|
compile a Nimrod `case`:idx: in a ``while true`` statement.
|
|
|
|
|
Syntactically it has to be used as a statement inside the loop:
|
|
|
|
|
|
|
|
|
|
@@ -5187,7 +5187,7 @@ extension the pragma is simply ignored.
|
|
|
|
|
|
|
|
|
|
unroll pragma
|
|
|
|
|
-------------
|
|
|
|
|
The `unroll`:idx: pragma can be used to tell the compiler that it should unroll
|
|
|
|
|
The ``unroll`` pragma can be used to tell the compiler that it should unroll
|
|
|
|
|
a `for`:idx: or `while`:idx: loop for runtime efficiency:
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
@@ -5266,7 +5266,7 @@ but are used to override the settings temporarily. Example:
|
|
|
|
|
|
|
|
|
|
register pragma
|
|
|
|
|
---------------
|
|
|
|
|
The `register`:idx: pragma is for variables only. It declares the variable as
|
|
|
|
|
The ``register`` pragma is for variables only. It declares the variable as
|
|
|
|
|
``register``, giving the compiler a hint that the variable should be placed
|
|
|
|
|
in a hardware register for faster access. C compilers usually ignore this
|
|
|
|
|
though and for good reasons: Often they do a better job without it anyway.
|
|
|
|
|
@@ -5277,7 +5277,7 @@ example) it may provide benefits, though.
|
|
|
|
|
|
|
|
|
|
global pragma
|
|
|
|
|
-------------
|
|
|
|
|
The `global`:idx: pragma can be applied to a variable within a proc to instruct
|
|
|
|
|
The ``global`` pragma can be applied to a variable within a proc to instruct
|
|
|
|
|
the compiler to store it in a global location and initialize it once at program
|
|
|
|
|
startup.
|
|
|
|
|
|
|
|
|
|
@@ -5294,7 +5294,7 @@ and before any variable in a module that imports it.
|
|
|
|
|
|
|
|
|
|
DeadCodeElim pragma
|
|
|
|
|
-------------------
|
|
|
|
|
The `deadCodeElim`:idx: pragma only applies to whole modules: It tells the
|
|
|
|
|
The ``deadCodeElim`` pragma only applies to whole modules: It tells the
|
|
|
|
|
compiler to activate (or deactivate) dead code elimination for the module the
|
|
|
|
|
pragma appears in.
|
|
|
|
|
|
|
|
|
|
@@ -5312,7 +5312,7 @@ Example:
|
|
|
|
|
..
|
|
|
|
|
NoForward pragma
|
|
|
|
|
----------------
|
|
|
|
|
The `noforward`:idx: pragma can be used to turn on and off a special compilation
|
|
|
|
|
The ``noforward`` pragma can be used to turn on and off a special compilation
|
|
|
|
|
mode that to large extent eliminates the need for forward declarations. In this
|
|
|
|
|
mode, the proc definitions may appear out of order and the compiler will postpone
|
|
|
|
|
their semantic analysis and compilation until it actually needs to generate code
|
|
|
|
|
@@ -5360,7 +5360,7 @@ Example:
|
|
|
|
|
Pragma pragma
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
The `pragma`:idx: pragma can be used to declare user defined pragmas. This is
|
|
|
|
|
The ``pragma`` pragma can be used to declare user defined pragmas. This is
|
|
|
|
|
useful because Nimrod's templates and macros do not affect pragmas. User
|
|
|
|
|
defined pragmas are in a different module-wide scope than all other symbols.
|
|
|
|
|
They cannot be imported from a module.
|
|
|
|
|
@@ -5404,7 +5404,7 @@ are documented here.
|
|
|
|
|
|
|
|
|
|
Importc pragma
|
|
|
|
|
--------------
|
|
|
|
|
The `importc`:idx: pragma provides a means to import a proc or a variable
|
|
|
|
|
The ``importc`` pragma provides a means to import a proc or a variable
|
|
|
|
|
from C. The optional argument is a string containing the C identifier. If
|
|
|
|
|
the argument is missing, the C name is the Nimrod identifier *exactly as
|
|
|
|
|
spelled*:
|
|
|
|
|
@@ -5418,7 +5418,7 @@ the same feature under the same name.
|
|
|
|
|
|
|
|
|
|
Exportc pragma
|
|
|
|
|
--------------
|
|
|
|
|
The `exportc`:idx: pragma provides a means to export a type, a variable, or a
|
|
|
|
|
The ``exportc`` pragma provides a means to export a type, a variable, or a
|
|
|
|
|
procedure to C. Enums and constants can't be exported. The optional argument
|
|
|
|
|
is a string containing the C identifier. If the argument is missing, the C
|
|
|
|
|
name is the Nimrod identifier *exactly as spelled*:
|
|
|
|
|
@@ -5432,7 +5432,7 @@ the same feature under the same name.
|
|
|
|
|
|
|
|
|
|
Extern pragma
|
|
|
|
|
-------------
|
|
|
|
|
Like ``exportc`` or ``importc`` the `extern`:idx: pragma affects name
|
|
|
|
|
Like ``exportc`` or ``importc``, the ``extern`` pragma affects name
|
|
|
|
|
mangling. The string literal passed to ``extern`` can be a format string:
|
|
|
|
|
|
|
|
|
|
.. code-block:: Nimrod
|
|
|
|
|
@@ -5445,7 +5445,7 @@ In the example the external name of ``p`` is set to ``prefixp``.
|
|
|
|
|
Bycopy pragma
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
The `bycopy`:idx: pragma can be applied to an object or tuple type and
|
|
|
|
|
The ``bycopy`` pragma can be applied to an object or tuple type and
|
|
|
|
|
instructs the compiler to pass the type by value to procs:
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
@@ -5457,13 +5457,13 @@ instructs the compiler to pass the type by value to procs:
|
|
|
|
|
Byref pragma
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
|
|
The `byref`:idx: pragma can be applied to an object or tuple type and instructs
|
|
|
|
|
The ``byref`` pragma can be applied to an object or tuple type and instructs
|
|
|
|
|
the compiler to pass the type by reference (hidden pointer) to procs.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Varargs pragma
|
|
|
|
|
--------------
|
|
|
|
|
The `varargs`:idx: pragma can be applied to procedures only (and procedure
|
|
|
|
|
The ``varargs`` pragma can be applied to procedures only (and procedure
|
|
|
|
|
types). It tells Nimrod that the proc can take a variable number of parameters
|
|
|
|
|
after the last specified parameter. Nimrod string values will be converted to C
|
|
|
|
|
strings automatically:
|
|
|
|
|
@@ -5476,7 +5476,7 @@ strings automatically:
|
|
|
|
|
|
|
|
|
|
Union pragma
|
|
|
|
|
------------
|
|
|
|
|
The `union`:idx: pragma can be applied to any ``object`` type. It means all
|
|
|
|
|
The ``union`` pragma can be applied to any ``object`` type. It means all
|
|
|
|
|
of the object's fields are overlaid in memory. This produces a ``union``
|
|
|
|
|
instead of a ``struct`` in the generated C/C++ code. The object declaration
|
|
|
|
|
then must not use inheritance or any GC'ed memory but this is currently not
|
|
|
|
|
@@ -5487,7 +5487,7 @@ should scan unions conservatively.
|
|
|
|
|
|
|
|
|
|
Packed pragma
|
|
|
|
|
-------------
|
|
|
|
|
The `packed`:idx: pragma can be applied to any ``object`` type. It ensures
|
|
|
|
|
The ``packed`` pragma can be applied to any ``object`` type. It ensures
|
|
|
|
|
that the fields of an object are packed back-to-back in memory. It is useful
|
|
|
|
|
to store packets or messages from/to network or hardware drivers, and for
|
|
|
|
|
interoperability with C. Combining packed pragma with inheritance is not
|
|
|
|
|
@@ -5498,7 +5498,7 @@ compile-time error. Usage with inheritance should be defined and documented.
|
|
|
|
|
|
|
|
|
|
Unchecked pragma
|
|
|
|
|
----------------
|
|
|
|
|
The `unchecked`:idx: pragma can be used to mark a named array as ``unchecked``
|
|
|
|
|
The ``unchecked`` pragma can be used to mark a named array as ``unchecked``
|
|
|
|
|
meaning its bounds are not checked. This is often useful when one wishes to
|
|
|
|
|
implement his own flexibly sized arrays. Additionally an unchecked array is
|
|
|
|
|
translated into a C array of undetermined size:
|
|
|
|
|
@@ -5533,7 +5533,7 @@ runtime size of the array.
|
|
|
|
|
|
|
|
|
|
Dynlib pragma for import
|
|
|
|
|
------------------------
|
|
|
|
|
With the `dynlib`:idx: pragma a procedure or a variable can be imported from
|
|
|
|
|
With the ``dynlib`` pragma a procedure or a variable can be imported from
|
|
|
|
|
a dynamic library (``.dll`` files for Windows, ``lib*.so`` files for UNIX).
|
|
|
|
|
The non-optional argument has to be the name of the dynamic library:
|
|
|
|
|
|
|
|
|
|
@@ -5623,7 +5623,7 @@ Thread pragma
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
A proc that is executed as a new thread of execution should be marked by the
|
|
|
|
|
`thread pragma`:idx:. The compiler checks procedures marked as ``thread`` for
|
|
|
|
|
``thread`` pragma. The compiler checks procedures marked as ``thread`` for
|
|
|
|
|
violations of the `no heap sharing restriction`:idx:\: This restriction implies
|
|
|
|
|
that it is invalid to construct a data structure that consists of memory
|
|
|
|
|
allocated from different (thread local) heaps.
|
|
|
|
|
@@ -5664,7 +5664,7 @@ Future directions:
|
|
|
|
|
Threadvar pragma
|
|
|
|
|
----------------
|
|
|
|
|
|
|
|
|
|
A global variable can be marked with the `threadvar`:idx: pragma; it is
|
|
|
|
|
A global variable can be marked with the ``threadvar`` pragma; it is
|
|
|
|
|
a `thread-local`:idx: variable then:
|
|
|
|
|
|
|
|
|
|
.. code-block:: nimrod
|
|
|
|
|
@@ -5716,7 +5716,7 @@ Taint mode
|
|
|
|
|
==========
|
|
|
|
|
|
|
|
|
|
The Nimrod compiler and most parts of the standard library support
|
|
|
|
|
a `taint mode`:idx:. Input strings are declared with the `TaintedString`:idx:
|
|
|
|
|
a taint mode. Input strings are declared with the `TaintedString`:idx:
|
|
|
|
|
string type declared in the ``system`` module.
|
|
|
|
|
|
|
|
|
|
If the taint mode is turned on (via the ``--taintMode:on`` command line
|
|
|
|
|
|
Grzegorz Adam Hankiewicz