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

Removes many fake idx entries.

Browse source 
These *fake* entries are not needed any more now that the table of
contents of documentation files appear in the index.
This commit is contained in:
Grzegorz Adam Hankiewicz 2014-04-21 21:07:13 +02:00
commit 61ded5ab60
9 changed files with 167 additions and 167 deletions
Download patch file Download diff file Expand all files Collapse all files

6
doc/endb.txt
View file

@ -9,7 +9,7 @@
Nimrod comes with a platform independent debugger - Nimrod comes with a platform independent debugger -
the `Embedded Nimrod Debugger`:idx: (`ENDB`:idx:). The debugger is the Embedded Nimrod Debugger (ENDB). The debugger is
*embedded* into your executable if it has been *embedded* into your executable if it has been
compiled with the ``--debugger:on`` command line option. compiled with the ``--debugger:on`` command line option.
This also defines the conditional symbol ``ENDB`` for you. This also defines the conditional symbol ``ENDB`` for you.
@ -102,7 +102,7 @@ necessary: A special pragma has been defined for this:
The ``breakpoint`` pragma The ``breakpoint`` pragma
------------------------- -------------------------
The `breakpoint`:idx: pragma is syntactically a statement. It can be used The ``breakpoint`` pragma is syntactically a statement. It can be used
to mark the *following line* as a breakpoint: to mark the *following line* as a breakpoint:
.. code-block:: Nimrod .. code-block:: Nimrod
@ -122,7 +122,7 @@ debugging.
The ``watchpoint`` pragma The ``watchpoint`` pragma
------------------------- -------------------------
The `watchpoint`:idx: pragma is syntactically a statement. It can be used The ``watchpoint`` pragma is syntactically a statement. It can be used
to mark a location as a watchpoint: to mark a location as a watchpoint:
.. code-block:: Nimrod .. code-block:: Nimrod

2
doc/estp.txt
View file

@ -7,7 +7,7 @@
Nimrod comes with a platform independent profiler - Nimrod comes with a platform independent profiler -
the `Embedded Stack Trace Profiler`:idx: (`ESTP`:idx:). The profiler the Embedded Stack Trace Profiler (ESTP). The profiler
is *embedded* into your executable. To activate the profiler you need to do: is *embedded* into your executable. To activate the profiler you need to do:
* compile your program with the ``--profiler:on --stackTrace:on`` command * compile your program with the ``--profiler:on --stackTrace:on`` command

8
doc/filters.txt
View file

@ -26,7 +26,7 @@ available parameters depend on the invoked filter.
Pipe operator Pipe operator
============= =============
Filters can be combined with the ``|`` `pipe operator`:idx:\ :: Filters can be combined with the ``|`` pipe operator::
#! strip(startswith="<") | stdtmpl #! strip(startswith="<") | stdtmpl
#proc generateXML(name, age: string): string = #proc generateXML(name, age: string): string =
@ -46,7 +46,7 @@ after each filter application.
Replace filter Replace filter
-------------- --------------
The `replace`:idx: filter replaces substrings in each line. The replace filter replaces substrings in each line.
Parameters and their defaults: Parameters and their defaults:
@ -60,7 +60,7 @@ Parameters and their defaults:
Strip filter Strip filter
------------ ------------
The `strip`:idx: filter simply removes leading and trailing whitespace from The strip filter simply removes leading and trailing whitespace from
each line. each line.
Parameters and their defaults: Parameters and their defaults:
@ -79,7 +79,7 @@ Parameters and their defaults:
StdTmpl filter StdTmpl filter
-------------- --------------
The `stdtmpl`:idx: filter provides a simple templating engine for Nimrod. The The stdtmpl filter provides a simple templating engine for Nimrod. The
filter uses a line based parser: Lines prefixed with a *meta character* filter uses a line based parser: Lines prefixed with a *meta character*
(default: ``#``) contain Nimrod code, other lines are verbatim. Because (default: ``#``) contain Nimrod code, other lines are verbatim. Because
indentation-based parsing is not suited for a templating engine, control flow indentation-based parsing is not suited for a templating engine, control flow

4
doc/idetools.txt
View file

@ -16,7 +16,7 @@
Nimrod differs from many other compilers in that it is really fast, Nimrod differs from many other compilers in that it is really fast,
and being so fast makes it suited to provide external queries for and being so fast makes it suited to provide external queries for
text editors about the source code being written. Through the text editors about the source code being written. Through the
`idetools`:idx: command of `the compiler <nimrodc.html>`_, any IDE ``idetools`` command of `the compiler <nimrodc.html>`_, any IDE
can query a ``.nim`` source file and obtain useful information like can query a ``.nim`` source file and obtain useful information like
definition of symbols or suggestions for completion. definition of symbols or suggestions for completion.
@ -169,7 +169,7 @@ clicks it and after a second or two the IDE displays where that
symbol is defined. Such latencies would be terrible for features symbol is defined. Such latencies would be terrible for features
like symbol suggestion, plus why wait at all if we can avoid it? like symbol suggestion, plus why wait at all if we can avoid it?
The idetools command can be run as a compiler service (`caas`:idx:), The idetools command can be run as a compiler service (CAAS),
where you first launch the compiler and it will stay online as a where you first launch the compiler and it will stay online as a
server, accepting queries in a telnet like fashion. The advantage server, accepting queries in a telnet like fashion. The advantage
of staying on is that for many queries the compiler can cache the of staying on is that for many queries the compiler can cache the

2
doc/intern.txt
View file

@ -156,7 +156,7 @@ generator.
Compilation cache Compilation cache
================= =================
The implementation of the `compilation cache`:idx: is tricky: There are lots The implementation of the compilation cache is tricky: There are lots
of issues to be solved for the front- and backend. In the following of issues to be solved for the front- and backend. In the following
sections *global* means *shared between modules* or *property of the whole sections *global* means *shared between modules* or *property of the whole
program*. program*.

220
doc/manual.txt
View file

@ -152,7 +152,7 @@ statements (simplified example)::
Comments 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 ``#``. hash character ``#``.
Comments consist of a concatenation of `comment pieces`:idx:. A comment piece 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 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 & 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 and underscores, beginning with a letter. Two immediate following
underscores ``__`` are not allowed:: 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 versions of the language may assign some Unicode characters to belong to the
operator characters instead. 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 .. code-block:: nimrod
:file: keywords.txt :file: keywords.txt
@ -224,7 +224,7 @@ String literals
Terminal symbol in the grammar: ``STR_LIT``. 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:\ : contain the following `escape sequences`:idx:\ :
================== =================================================== ================== ===================================================
@ -280,7 +280,7 @@ Raw string literals
Terminal symbol in the grammar: ``RSTR_LIT``. 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 letter ``r`` (or ``R``) and are delimited by matching double quotes (just
like ordinary string literals) and do not interpret the escape sequences. like ordinary string literals) and do not interpret the escape sequences.
This is especially convenient for regular expressions or Windows paths: 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 The construct ``identifier"string literal"`` (without whitespace between the
identifier and the opening quotation mark) is a 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 ``identifier(r"string literal")``, so it denotes a procedure call with a
raw string literal as its only argument. Generalized raw string literals raw string literal as its only argument. Generalized raw string literals
are especially convenient for embedding mini languages directly into Nimrod 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
------------------- -------------------
`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' hexdigit = digit | 'A'..'F' | 'a'..'f'
octdigit = '0'..'7' octdigit = '0'..'7'
@ -440,7 +440,7 @@ is approximately 1.72826e35 according to the IEEE floating point standard.
Operators 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:: combination of the following characters::
= + - * / < > = + - * / < >
@ -587,7 +587,7 @@ The grammar's start symbol is ``module``.
Types 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 is statically typed. One can declare new types, which is in essence defining
an identifier that can be used to denote this custom type. 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
------------- -------------
`Ordinal types`:idx: have the following characteristics: Ordinal types have the following characteristics:
- Ordinal types are countable and ordered. This property allows - Ordinal types are countable and ordered. This property allows
the operation of functions as ``Inc``, ``Ord``, ``Dec`` on ordinal types to the operation of functions as ``Inc``, ``Ord``, ``Dec`` on ordinal types to
@ -705,7 +705,7 @@ For further details, see `Convertible relation`_.
Subrange types 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 type). To define a subrange type, one must specify it's limiting values: the
lowest and highest value of the type: lowest and highest value of the type:
@ -806,7 +806,7 @@ the ``+``, ``-``, ``*``, ``/`` operators for floating point types.
Boolean type 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, pre-defined values ``true`` and ``false``. Conditions in while,
if, elif, when statements need to be of type bool. 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 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. 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 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 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 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: specified. The values are ordered. Example:
.. code-block:: nimrod .. code-block:: nimrod
@ -915,7 +915,7 @@ via ``TMyEnum.value``:
String type 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 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 zero-terminated and have a length field. One can retrieve the length with the
builtin ``len`` procedure; the length never counts the terminating zero. 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 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 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 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 ``s``; however no bounds checking for ``cstring`` is performed making the
@ -968,20 +968,20 @@ not work.
Structured types 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, time. Structured types can be nested to unlimited levels. Arrays, sequences,
tuples, objects and sets belong to the structured types. tuples, objects and sets belong to the structured types.
Array and sequence 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 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. 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 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 integers from 0 to ``len(A)-1``. An array expression may be constructed by the
array constructor ``[]``. 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, during runtime (like strings). Sequences are implemented as growable arrays,
allocating pieces of memory as items are added. A sequence ``S`` is always 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. 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 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 allows to pass a variable number of arguments to a procedure. The compiler
converts the list of arguments to an array implicitly: 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 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. container.
A tuple or object defines various named *fields* of a type. A tuple also 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 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 Object variants
--------------- ---------------
Often an object hierarchy is overkill in certain situations where simple Often an object hierarchy is overkill in certain situations where simple
`variant`:idx: types are needed. variant types are needed.
An example: An example:
@ -1211,7 +1211,7 @@ branch switch ``system.reset`` has to be used.
Set type 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 basetype can only be an ordinal type. The reason is that sets are implemented
as high performance bit vectors. as high performance bit vectors.
@ -1246,7 +1246,7 @@ operation meaning
Reference and pointer types 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 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:). 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 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 .. code-block:: nimrod
type type
@ -1369,7 +1369,7 @@ here.
Memory regions 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. A region has to be an object type.
Regions are very useful to separate user space and kernel memory in the Regions are very useful to separate user space and kernel memory in the
@ -1428,7 +1428,7 @@ Future directions:
Procedural type 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 an allowed value for variables of a procedural type. Nimrod uses procedural
types to achieve `functional`:idx: programming techniques. 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 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 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 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 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 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 type ``void`` are treated as non-existent, ``void`` as a return type means that
the procedure does not return a value: the procedure does not return a value:
@ -1887,7 +1887,7 @@ To be written.
Statements and expressions 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 produce a value in contrast to expressions. However, some expressions are
statements. statements.
@ -1904,7 +1904,7 @@ Statement list expression
Statements can also occur in an expression context that looks Statements can also occur in an expression context that looks
like ``(stmt1; stmt2; ...; ex)``. This is called 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 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.) must be of type ``void``. (One can use ``discard`` to produce a ``void`` type.)
``(;)`` does not introduce a new scope. ``(;)`` does not introduce a new scope.
@ -1921,7 +1921,7 @@ Example:
discard p(3, 4) # discard the return value of `p` 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. throws the expression's resulting value away.
Ignoring the return value of a procedure without using a discard statement is 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 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 initialize them. A comma separated list of variables can be used to specify
variables of the same type: variables of the same type:
@ -2018,7 +2018,7 @@ initialized and does not rely on syntactic properties:
let statement 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`` 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``. 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 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 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 time evaluation explicitly. Enforced compile time evaluation can even evaluate
code that has side effects: code that has side effects:
@ -2094,7 +2094,7 @@ Example:
else: else:
echo("Boring name...") 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 expression after the keyword ``if`` is evaluated, if it is true
the corresponding statements after the ``:`` are executed. Otherwise the corresponding statements after the ``:`` are executed. Otherwise
the expression after the ``elif`` is evaluated (if there is an the expression after the ``elif`` is evaluated (if there is an
@ -2140,7 +2140,7 @@ Example:
else: echo("unknown command") 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 a multi-branch selection. The expression after the keyword ``case`` is
evaluated and if its value is in a *slicelist* the corresponding statements 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 (after the ``of`` keyword) are executed. If the value is not in any
@ -2194,7 +2194,7 @@ Example:
else: else:
echo("cannot happen!") 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: exceptions:
* Each condition (``expr``) has to be a constant expression (of type ``bool``). * Each condition (``expr``) has to be a constant expression (of type ``bool``).
@ -2216,7 +2216,7 @@ Example:
.. code-block:: nimrod .. code-block:: nimrod
return 40+2 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 It is only allowed in procedures. If there is an ``expr``, this is syntactic
sugar for: sugar for:
@ -2243,7 +2243,7 @@ Example:
.. code-block:: nimrod .. code-block:: nimrod
yield (1, 2, 3) 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 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 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 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 break myblock # leave the block, in this case both for-loops
echo(found) 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 Inside the block, the ``break`` statement is allowed to leave the block
immediately. A ``break`` statement can contain a name of a surrounding immediately. A ``break`` statement can contain a name of a surrounding
block to specify which block is to leave. block to specify which block is to leave.
@ -2280,7 +2280,7 @@ Example:
.. code-block:: nimrod .. code-block:: nimrod
break 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 is given, it is the name of the enclosing block that is to leave. If it is
absent, the innermost block is left. absent, the innermost block is left.
@ -2298,7 +2298,7 @@ Example:
pw = readLine(stdin) 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`, Endless loops are no error. ``while`` statements open an `implicit block`,
so that they can be left with a ``break`` statement. 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 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 surrounding loop construct. It is only allowed within a loop. A continue
statement is syntactic sugar for a nested block: statement is syntactic sugar for a nested block:
@ -2329,7 +2329,7 @@ Is equivalent to:
Assembler statement 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 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 Nimrod identifiers shall be enclosed in a special character which can be
specified in the statement's pragmas. The default special character is ``'`'``: specified in the statement's pragmas. The default special character is ``'`'``:
@ -2376,7 +2376,7 @@ Using statement
**Warning**: The ``using`` statement is highly experimental! **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 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 constant, it will instruct Nimrod to automatically consider the used symbol as
a hidden leading parameter for any procedure calls, following the using 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 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 .. code-block:: nimrod
{"key1": "value1", "key2", "key3": "value2"} {"key1": "value1", "key2", "key3": "value2"}
@ -2508,7 +2508,7 @@ only needed for low-level programming and are inherently unsafe.
The addr operator 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 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 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 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 instead of ``method(obj, args)``. The parentheses can be omitted if there are no
remaining arguments: ``obj.len`` (instead of ``len(obj)``). 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: to supply any type of first argument for procedures:
.. code-block:: nimrod .. code-block:: nimrod
@ -2654,7 +2654,7 @@ Command invocation syntax
------------------------- -------------------------
Routines can be invoked without the ``()`` if the call is syntatically 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 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 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 ``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 Multi-methods
============= =============
Procedures always use static dispatch. `Multi-methods`:idx: use dynamic Procedures always use static dispatch. Multi-methods use dynamic
dispatch. dispatch.
.. code-block:: nimrod .. code-block:: nimrod
@ -3104,7 +3104,7 @@ Example:
line: int # the line the symbol was declared in line: int # the line the symbol was declared in
code: PNode # the symbol's abstract syntax tree 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 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 can be recursive or even mutually recursive. Mutually recursive types are only
possible within a single ``type`` section. Nominal types like ``objects`` possible within a single ``type`` section. Nominal types like ``objects``
@ -3141,7 +3141,7 @@ Example:
close(f) 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 an exception ``e`` is raised. If the exception type of ``e`` matches any
listed in an ``except`` clause the corresponding statements are executed. listed in an ``except`` clause the corresponding statements are executed.
The statements following the ``except`` clauses are called The statements following the ``except`` clauses are called
@ -3163,7 +3163,7 @@ is not executed (if an exception occurs).
Except and finally statements 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 Any statements following them in the current block will be considered to be
in an implicit try block: in an implicit try block:
@ -3212,9 +3212,9 @@ exception (unless a raise hook has been provided).
OnRaise builtin OnRaise builtin
--------------- ---------------
``system.onRaise`` can be used to override the behaviour of ``raise`` for a `system.onRaise() <system.html#onRaise>`_ can be used to override the
single ``try`` statement. `onRaise`:idx: has to be called within the ``try`` behaviour of ``raise`` for a single ``try`` statement. ``onRaise`` has to be
statement that should be affected. called within the ``try`` statement that should be affected.
This allows for a Lisp-like `condition system`:idx:\: This allows for a Lisp-like `condition system`:idx:\:
@ -3243,7 +3243,7 @@ Effect system
Exception tracking 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 to explicitly define which exceptions a proc/iterator/method/converter is
allowed to raise. The compiler verifies this: allowed to raise. The compiler verifies this:
@ -3351,7 +3351,7 @@ exception tracking.
Effects pragma 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 analysis. It is a statement that makes the compiler output all inferred
effects up to the ``effects``'s position: effects up to the ``effects``'s position:
@ -3420,7 +3420,7 @@ Example:
for str in inorder(root): for str in inorder(root):
writeln(stdout, str) 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 `type parameters`:idx:. Depending on context, the brackets are used either to
introduce type parameters or to instantiate a generic proc, iterator or type. 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 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: therefore very useful for type specialization within generic code:
.. code-block:: nimrod .. code-block:: nimrod
@ -3443,7 +3443,7 @@ therefore very useful for type specialization within generic code:
Type operator 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: be used to get the type of an expression:
.. code-block:: nimrod .. code-block:: nimrod
@ -3466,7 +3466,7 @@ other interpretations:
Type Classes 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. types in the context of overload resolution or the ``is`` operator.
Nimrod supports the following built-in type classes: 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 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. 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 the identifiers should be looked up in the scope of the template/generic
definition): definition):
@ -3712,7 +3712,7 @@ scope is the default.
Templates 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 mechanism that operates on Nimrod's abstract syntax trees. It is processed in
the semantic pass of the compiler. the semantic pass of the compiler.
@ -3744,7 +3744,7 @@ expected.
Ordinary vs immediate templates 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 ordinary templates. Ordinary templates take part in overloading resolution. As
such their arguments need to be type checked before the template is invoked. such their arguments need to be type checked before the template is invoked.
So ordinary templates cannot receive undeclared identifiers: So ordinary templates cannot receive undeclared identifiers:
@ -3939,7 +3939,7 @@ a template. ``inject`` and ``gensym`` have no effect in ``dirty`` templates.
Macros 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 to implement `domain specific languages`:idx:. Like templates, macros come in
the 2 flavors *immediate* and *ordinary*. 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
===================== =====================
`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 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 phase of the compiler: This means they provide an easy way to enhance the
compilation pipeline with user defined optimizations: compilation pipeline with user defined optimizations:
@ -4653,7 +4653,7 @@ ordinary routines.
Move optimization 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: optimization for types that have copying semantics:
.. code-block:: nimrod .. code-block:: nimrod
@ -4679,7 +4679,7 @@ optimization for types that have copying semantics:
Modules 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:. Each module needs to be in its own file and has its own `namespace`:idx:.
Modules enable `information hiding`:idx: and `separate compilation`:idx:. Modules enable `information hiding`:idx: and `separate compilation`:idx:.
A module may gain access to symbols of another module by the `import`: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 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: module name followed by an ``except`` to prevent some symbols to be imported:
.. code-block:: nimrod .. code-block:: nimrod
@ -4765,7 +4765,7 @@ Likewise the following does not make sense as the name is ``strutils`` already:
From import statement 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 an ``import`` to list the symbols one likes to use without explict
full qualification: full qualification:
@ -4784,7 +4784,7 @@ in ``module``.
Export statement 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: modules don't need to import a module's dependencies:
.. code-block:: nimrod .. code-block:: nimrod
@ -4812,7 +4812,7 @@ Scope rules
----------- -----------
Identifiers are valid from the point of their declaration until the end of 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 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. identifier depends on the way it was declared.
Block scope Block scope
@ -4885,7 +4885,7 @@ to access the feature becomes available.
noSideEffect pragma 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 effects. This means that the proc/iterator only changes locations that are
reachable from its parameters and the return value only depends on the reachable from its parameters and the return value only depends on the
arguments. If none of its parameters have the type ``var T`` arguments. If none of its parameters have the type ``var T``
@ -4907,7 +4907,7 @@ proc with no side effects:
destructor pragma 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 The proc must have a single parameter with a concrete type (the name of a
generic type is allowed too). generic type is allowed too).
@ -4967,25 +4967,25 @@ the ``finalizer`` parameter to ``new``.
procvar pragma 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. procedural variable.
compileTime pragma 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 time only. No code will be generated for it. Compile time procs are useful
as helpers for macros. as helpers for macros.
noReturn pragma 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 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 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: collector to not consider objects of this type as part of a cycle:
@ -5016,13 +5016,13 @@ memory, but nothing worse happens.
Final pragma 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. cannot be inherited from.
shallow pragma 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 allowed to make a shallow copy. This can cause serious semantic issues and
break memory safety! However, it can speed up assignments considerably, break memory safety! However, it can speed up assignments considerably,
because the semantics of Nimrod require deep copying of sequences and strings. because the semantics of Nimrod require deep copying of sequences and strings.
@ -5042,14 +5042,14 @@ structure:
Pure pragma 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 field which is used for runtime type identification is omitted. This is
necessary for binary compatibility with other compiled languages. necessary for binary compatibility with other compiled languages.
AsmNoStackFrame pragma 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 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 statements like ``return result;`` generated and the generated C function is
declared as ``__declspec(naked)`` or ``__attribute__((naked))`` (depending on declared as ``__declspec(naked)`` or ``__attribute__((naked))`` (depending on
@ -5060,7 +5060,7 @@ assembler statements.
error pragma 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 with the given content. Compilation does not necessarily abort after an error
though. though.
@ -5076,7 +5076,7 @@ operation is valid due to overloading and type conversions:
fatal pragma 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 with the given content. In contrast to the ``error`` pragma, compilation
is guaranteed to be aborted by this pragma. Example: is guaranteed to be aborted by this pragma. Example:
@ -5086,17 +5086,17 @@ is guaranteed to be aborted by this pragma. Example:
warning pragma 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. with the given content. Compilation continues after the warning.
hint pragma 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. the given content. Compilation continues after the hint.
line pragma 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: statement as seen in stack backtraces:
.. code-block:: nimrod .. code-block:: nimrod
@ -5114,7 +5114,7 @@ If the ``line`` pragma is used with a parameter, the parameter needs be a
linearScanEnd pragma 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 compile a Nimrod `case`:idx: statement. Syntactically it has to be used as a
statement: statement:
@ -5142,7 +5142,7 @@ whole ``case`` statement, the whole ``case`` statement uses linear scanning.
computedGoto pragma 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. compile a Nimrod `case`:idx: in a ``while true`` statement.
Syntactically it has to be used as a statement inside the loop: Syntactically it has to be used as a statement inside the loop:
@ -5187,7 +5187,7 @@ extension the pragma is simply ignored.
unroll pragma 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: a `for`:idx: or `while`:idx: loop for runtime efficiency:
.. code-block:: nimrod .. code-block:: nimrod
@ -5266,7 +5266,7 @@ but are used to override the settings temporarily. Example:
register pragma 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 ``register``, giving the compiler a hint that the variable should be placed
in a hardware register for faster access. C compilers usually ignore this 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. 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 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 the compiler to store it in a global location and initialize it once at program
startup. startup.
@ -5294,7 +5294,7 @@ and before any variable in a module that imports it.
DeadCodeElim pragma 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 compiler to activate (or deactivate) dead code elimination for the module the
pragma appears in. pragma appears in.
@ -5312,7 +5312,7 @@ Example:
.. ..
NoForward pragma 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 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 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 their semantic analysis and compilation until it actually needs to generate code
@ -5360,7 +5360,7 @@ Example:
Pragma pragma 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 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. defined pragmas are in a different module-wide scope than all other symbols.
They cannot be imported from a module. They cannot be imported from a module.
@ -5404,7 +5404,7 @@ are documented here.
Importc pragma 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 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 the argument is missing, the C name is the Nimrod identifier *exactly as
spelled*: spelled*:
@ -5418,7 +5418,7 @@ the same feature under the same name.
Exportc pragma 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 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 is a string containing the C identifier. If the argument is missing, the C
name is the Nimrod identifier *exactly as spelled*: name is the Nimrod identifier *exactly as spelled*:
@ -5432,7 +5432,7 @@ the same feature under the same name.
Extern pragma 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: mangling. The string literal passed to ``extern`` can be a format string:
.. code-block:: Nimrod .. code-block:: Nimrod
@ -5445,7 +5445,7 @@ In the example the external name of ``p`` is set to ``prefixp``.
Bycopy pragma 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: instructs the compiler to pass the type by value to procs:
.. code-block:: nimrod .. code-block:: nimrod
@ -5457,13 +5457,13 @@ instructs the compiler to pass the type by value to procs:
Byref pragma 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. the compiler to pass the type by reference (hidden pointer) to procs.
Varargs pragma 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 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 after the last specified parameter. Nimrod string values will be converted to C
strings automatically: strings automatically:
@ -5476,7 +5476,7 @@ strings automatically:
Union pragma 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`` 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 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 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 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 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 to store packets or messages from/to network or hardware drivers, and for
interoperability with C. Combining packed pragma with inheritance is not 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 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 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 implement his own flexibly sized arrays. Additionally an unchecked array is
translated into a C array of undetermined size: translated into a C array of undetermined size:
@ -5533,7 +5533,7 @@ runtime size of the array.
Dynlib pragma for import 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). 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: 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 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 violations of the `no heap sharing restriction`:idx:\: This restriction implies
that it is invalid to construct a data structure that consists of memory that it is invalid to construct a data structure that consists of memory
allocated from different (thread local) heaps. allocated from different (thread local) heaps.
@ -5664,7 +5664,7 @@ Future directions:
Threadvar pragma 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: a `thread-local`:idx: variable then:
.. code-block:: nimrod .. code-block:: nimrod
@ -5716,7 +5716,7 @@ Taint mode
========== ==========
The Nimrod compiler and most parts of the standard library support 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. string type declared in the ``system`` module.
If the taint mode is turned on (via the ``--taintMode:on`` command line If the taint mode is turned on (via the ``--taintMode:on`` command line

44
doc/nimrodc.txt
View file

@ -116,7 +116,7 @@ The default build of a project is a `debug build`:idx:. To compile a
Search path handling Search path handling
-------------------- --------------------
Nimrod has the concept of a global `search path`:idx: (PATH) that is queried to Nimrod has the concept of a global search path (PATH) that is queried to
determine where to find imported modules or include files. If multiple files are determine where to find imported modules or include files. If multiple files are
found an ambiguity error is produced. found an ambiguity error is produced.
@ -174,7 +174,7 @@ is not shared between different projects.
Cross compilation Cross compilation
================= =================
To `cross compile`:idx:, use for example:: To cross compile, use for example::
nimrod c --cpu:i386 --os:linux --compile_only --gen_script myproject.nim nimrod c --cpu:i386 --os:linux --compile_only --gen_script myproject.nim
@ -200,7 +200,7 @@ DLL generation
Nimrod supports the generation of DLLs. However, there must be only one Nimrod supports the generation of DLLs. However, there must be only one
instance of the GC per process/address space. This instance is contained in instance of the GC per process/address space. This instance is contained in
``nimrtl.dll``. This means that every generated Nimrod `DLL`:idx: depends ``nimrtl.dll``. This means that every generated Nimrod DLL depends
on ``nimrtl.dll``. To generate the "nimrtl.dll" file, use the command:: on ``nimrtl.dll``. To generate the "nimrtl.dll" file, use the command::
nimrod c -d:release lib/nimrtl.nim nimrod c -d:release lib/nimrtl.nim
@ -251,7 +251,7 @@ generator and are subject to change.
NoDecl pragma NoDecl pragma
------------- -------------
The `noDecl`:idx: pragma can be applied to almost any symbol (variable, proc, The ``noDecl`` pragma can be applied to almost any symbol (variable, proc,
type, etc.) and is sometimes useful for interoperability with C: type, etc.) and is sometimes useful for interoperability with C:
It tells Nimrod that it should not generate a declaration for the symbol in It tells Nimrod that it should not generate a declaration for the symbol in
the C code. For example: the C code. For example:
@ -268,7 +268,7 @@ However, the ``header`` pragma is often the better alternative.
Header pragma Header pragma
------------- -------------
The `header`:idx: pragma is very similar to the ``noDecl`` pragma: It can be The ``header`` pragma is very similar to the ``noDecl`` pragma: It can be
applied to almost any symbol and specifies that it should not be declared applied to almost any symbol and specifies that it should not be declared
and instead the generated code should contain an ``#include``: and instead the generated code should contain an ``#include``:
@ -287,7 +287,7 @@ encloses the header file in ``""`` in the generated C code.
IncompleteStruct pragma IncompleteStruct pragma
----------------------- -----------------------
The `incompleteStruct`:idx: pragma tells the compiler to not use the The ``incompleteStruct`` pragma tells the compiler to not use the
underlying C ``struct`` in a ``sizeof`` expression: underlying C ``struct`` in a ``sizeof`` expression:
.. code-block:: Nimrod .. code-block:: Nimrod
@ -298,7 +298,7 @@ underlying C ``struct`` in a ``sizeof`` expression:
Compile pragma Compile pragma
-------------- --------------
The `compile`:idx: pragma can be used to compile and link a C/C++ source file The ``compile`` pragma can be used to compile and link a C/C++ source file
with the project: with the project:
.. code-block:: Nimrod .. code-block:: Nimrod
@ -311,7 +311,7 @@ of the file.
Link pragma Link pragma
----------- -----------
The `link`:idx: pragma can be used to link an additional file with the project: The ``link`` pragma can be used to link an additional file with the project:
.. code-block:: Nimrod .. code-block:: Nimrod
{.link: "myfile.o".} {.link: "myfile.o".}
@ -319,7 +319,7 @@ The `link`:idx: pragma can be used to link an additional file with the project:
PassC pragma PassC pragma
------------ ------------
The `passC`:idx: pragma can be used to pass additional parameters to the C The ``passC`` pragma can be used to pass additional parameters to the C
compiler like you would using the commandline switch ``--passC``: compiler like you would using the commandline switch ``--passC``:
.. code-block:: Nimrod .. code-block:: Nimrod
@ -333,7 +333,7 @@ embed parameters from an external command at compile time:
PassL pragma PassL pragma
------------ ------------
The `passL`:idx: pragma can be used to pass additional parameters to the linker The ``passL`` pragma can be used to pass additional parameters to the linker
like you would using the commandline switch ``--passL``: like you would using the commandline switch ``--passL``:
.. code-block:: Nimrod .. code-block:: Nimrod
@ -348,7 +348,7 @@ embed parameters from an external command at compile time:
Emit pragma Emit pragma
----------- -----------
The `emit`:idx: pragma can be used to directly affect the output of the The ``emit`` pragma can be used to directly affect the output of the
compiler's code generator. So it makes your code unportable to other code compiler's code generator. So it makes your code unportable to other code
generators/backends. Its usage is highly discouraged! However, it can be generators/backends. Its usage is highly discouraged! However, it can be
extremely useful for interfacing with `C++`:idx: or `Objective C`:idx: code. extremely useful for interfacing with `C++`:idx: or `Objective C`:idx: code.
@ -370,7 +370,7 @@ Example:
ImportCpp pragma ImportCpp pragma
---------------- ----------------
The `importcpp`:idx: pragma can be used to import `C++`:idx: methods. The The ``importcpp`` pragma can be used to import `C++`:idx: methods. The
generated code then uses the C++ method calling syntax: ``obj->method(arg)``. generated code then uses the C++ method calling syntax: ``obj->method(arg)``.
In addition with the ``header`` and ``emit`` pragmas this allows *sloppy* In addition with the ``header`` and ``emit`` pragmas this allows *sloppy*
interfacing with libraries written in C++: interfacing with libraries written in C++:
@ -408,7 +408,7 @@ emits C++ code.
ImportObjC pragma ImportObjC pragma
----------------- -----------------
The `importobjc`:idx: pragma can be used to import `Objective C`:idx: methods. The ``importobjc`` pragma can be used to import `Objective C`:idx: methods.
The generated code then uses the Objective C method calling The generated code then uses the Objective C method calling
syntax: ``[obj method param1: arg]``. syntax: ``[obj method param1: arg]``.
In addition with the ``header`` and ``emit`` pragmas this allows *sloppy* In addition with the ``header`` and ``emit`` pragmas this allows *sloppy*
@ -458,7 +458,7 @@ emits Objective C code.
CodegenDecl pragma CodegenDecl pragma
------------------ ------------------
The `codegenDecl`:idx: pragma can be used to directly influence Nimrod's code The ``codegenDecl`` pragma can be used to directly influence Nimrod's code
generator. It receives a format string that determines how the variable or generator. It receives a format string that determines how the variable or
proc is declared in the generated code: proc is declared in the generated code:
@ -473,7 +473,7 @@ proc is declared in the generated code:
InjectStmt pragma InjectStmt pragma
----------------- -----------------
The `injectStmt`:idx: pragma can be used to inject a statement before every The ``injectStmt`` pragma can be used to inject a statement before every
other statement in the current module. It is only supposed to be used for other statement in the current module. It is only supposed to be used for
debugging: debugging:
@ -485,28 +485,28 @@ debugging:
LineDir option LineDir option
-------------- --------------
The `lineDir`:idx: option can be turned on or off. If turned on the The ``lineDir`` option can be turned on or off. If turned on the
generated C code contains ``#line`` directives. This may be helpful for generated C code contains ``#line`` directives. This may be helpful for
debugging with GDB. debugging with GDB.
StackTrace option StackTrace option
----------------- -----------------
If the `stackTrace`:idx: option is turned on, the generated C contains code to If the ``stackTrace`` option is turned on, the generated C contains code to
ensure that proper stack traces are given if the program crashes or an ensure that proper stack traces are given if the program crashes or an
uncaught exception is raised. uncaught exception is raised.
LineTrace option LineTrace option
---------------- ----------------
The `lineTrace`:idx: option implies the ``stackTrace`` option. If turned on, The ``lineTrace`` option implies the ``stackTrace`` option. If turned on,
the generated C contains code to ensure that proper stack traces with line the generated C contains code to ensure that proper stack traces with line
number information are given if the program crashes or an uncaught exception number information are given if the program crashes or an uncaught exception
is raised. is raised.
Debugger option Debugger option
--------------- ---------------
The `debugger`:idx: option enables or disables the *Embedded Nimrod Debugger*. The ``debugger`` option enables or disables the *Embedded Nimrod Debugger*.
See the documentation of endb_ for further information. See the documentation of endb_ for further information.
@ -518,7 +518,7 @@ ENDB. See the documentation of `endb <endb.html>`_ for further information.
Volatile pragma Volatile pragma
--------------- ---------------
The `volatile`:idx: pragma is for variables only. It declares the variable as The ``volatile`` pragma is for variables only. It declares the variable as
``volatile``, whatever that means in C/C++ (its semantics are not well defined ``volatile``, whatever that means in C/C++ (its semantics are not well defined
in C/C++). in C/C++).
@ -530,7 +530,7 @@ DynlibOverride
By default Nimrod's ``dynlib`` pragma causes the compiler to generate By default Nimrod's ``dynlib`` pragma causes the compiler to generate
``GetProcAddress`` (or their Unix counterparts) ``GetProcAddress`` (or their Unix counterparts)
calls to bind to a DLL. With the `dynlibOverride`:idx: command line switch this calls to bind to a DLL. With the ``dynlibOverride`` command line switch this
can be prevented and then via ``--passL`` the static library can be linked can be prevented and then via ``--passL`` the static library can be linked
against. For instance, to link statically against Lua this command might work against. For instance, to link statically against Lua this command might work
on Linux:: on Linux::
@ -556,7 +556,7 @@ for further information.
Nimrod interactive mode Nimrod interactive mode
======================= =======================
The Nimrod compiler supports an `interactive mode`:idx:. This is also known as The Nimrod compiler supports an interactive mode. This is also known as
a `REPL`:idx: (*read eval print loop*). If Nimrod has been built with the a `REPL`:idx: (*read eval print loop*). If Nimrod has been built with the
``-d:useGnuReadline`` switch, it uses the GNU readline library for terminal ``-d:useGnuReadline`` switch, it uses the GNU readline library for terminal
input management. To start Nimrod in interactive mode use the command input management. To start Nimrod in interactive mode use the command

32
doc/tut1.txt
View file

@ -110,7 +110,7 @@ useful for embedding HTML code templates for example.
Comments 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 ``#``. Documentation comments start with ``##``. Multiline hash character ``#``. Documentation comments start with ``##``. Multiline
comments need to be aligned at the same column: comments need to be aligned at the same column:
@ -224,7 +224,7 @@ different values! For safety use only constant values.
Constants Constants
========= =========
`Constants`:idx: are symbols which are bound to a value. The constant's value Constants are symbols which are bound to a value. The constant's value
cannot change. The compiler must be able to evaluate the expression in a cannot change. The compiler must be able to evaluate the expression in a
constant declaration at compile time: constant declaration at compile time:
@ -369,7 +369,7 @@ he types in nothing (only presses RETURN).
For statement For statement
------------- -------------
The `for`:idx: statement is a construct to loop over any element an *iterator* The ``for`` statement is a construct to loop over any element an *iterator*
provides. The example uses the built-in ``countup`` iterator: provides. The example uses the built-in ``countup`` iterator:
.. code-block:: nimrod .. code-block:: nimrod
@ -481,7 +481,7 @@ Example:
else: else:
echo("unknown operating system") echo("unknown operating system")
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
differences: differences:
* Each condition has to be a constant expression since it is evaluated by the * Each condition has to be a constant expression since it is evaluated by the
@ -791,7 +791,7 @@ However, this cannot be done for mutually recursive procedures:
Here ``odd`` depends on ``even`` and vice versa. Thus ``even`` needs to be Here ``odd`` depends on ``even`` and vice versa. Thus ``even`` needs to be
introduced to the compiler before it is completely defined. The syntax for introduced to the compiler before it is completely defined. The syntax for
such a `forward declaration`:idx: is simple: just omit the ``=`` and the such a forward declaration is simple: just omit the ``=`` and the
procedure's body. procedure's body.
Later versions of the language may get rid of the need for forward Later versions of the language may get rid of the need for forward
@ -863,7 +863,7 @@ that are available for them in detail.
Booleans Booleans
-------- --------
The `boolean`:idx: type is named ``bool`` in Nimrod and consists of the two The boolean type is named ``bool`` in Nimrod and consists of the two
pre-defined values ``true`` and ``false``. Conditions in while, pre-defined values ``true`` and ``false``. Conditions in while,
if, elif, when statements need to be of type bool. if, elif, when statements need to be of type bool.
@ -1030,7 +1030,7 @@ Enumeration and object types cannot be defined on the fly, but only within a
Enumerations Enumerations
------------ ------------
A variable of an `enumeration`:idx: type can only be assigned a value of a A variable of an enumeration type can only be assigned a value of a
limited set. This set consists of ordered symbols. Each symbol is mapped limited set. This set consists of ordered symbols. Each symbol is mapped
to an integer value internally. The first symbol is represented to an integer value internally. The first symbol is represented
at runtime by 0, the second by 1 and so on. Example: at runtime by 0, the second by 1 and so on. Example:
@ -1069,7 +1069,7 @@ An explicit ordered enum can have *holes*:
Ordinal types Ordinal types
------------- -------------
Enumerations without holes, integer types, ``char`` and ``bool`` (and Enumerations without holes, integer types, ``char`` and ``bool`` (and
subranges) are called `ordinal`:idx: types. Ordinal types have quite subranges) are called ordinal types. Ordinal types have quite
a few special operations: a few special operations:
----------------- -------------------------------------------------------- ----------------- --------------------------------------------------------
@ -1094,7 +1094,7 @@ checks turned on.)
Subranges Subranges
--------- ---------
A `subrange`:idx: type is a range of values from an integer or enumeration type A subrange type is a range of values from an integer or enumeration type
(the base type). Example: (the base type). Example:
.. code-block:: nimrod .. code-block:: nimrod
@ -1117,7 +1117,7 @@ avoid this common programming error.
Sets Sets
---- ----
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 basetype can only be an ordinal type. The reason is that sets are implemented
as high performance bit vectors. as high performance bit vectors.
@ -1161,7 +1161,7 @@ constants that should be ``or``'ed together.
Arrays Arrays
------ ------
An `array`:idx: is a simple fixed length container. Each element in An array is a simple fixed length container. Each element in
the array has the same type. The array's index type can be any ordinal type. the array has the same type. The array's index type can be any ordinal type.
Arrays can be constructed via ``[]``: Arrays can be constructed via ``[]``:
@ -1253,7 +1253,7 @@ to specify a range from zero to the specified index minus one:
Sequences Sequences
--------- ---------
`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). Since sequences are resizable they are always during runtime (like strings). Since sequences are resizable they are always
allocated on the heap and garbage collected. allocated on the heap and garbage collected.
@ -1471,7 +1471,7 @@ won't compile:
Reference and pointer types 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 way to introduce many-to-one relationships. This means different references can
point to and modify the same location in memory. point to and modify the same location in memory.
@ -1513,7 +1513,7 @@ If a reference points to *nothing*, it has the value ``nil``.
Procedural type Procedural type
--------------- ---------------
A `procedural type`:idx: is a (somewhat abstract) pointer to a procedure. A procedural type is a (somewhat abstract) pointer to a procedure.
``nil`` is an allowed value for a variable of a procedural type. ``nil`` is an allowed value for a variable of a procedural type.
Nimrod uses procedural types to achieve `functional`:idx: programming Nimrod uses procedural types to achieve `functional`:idx: programming
techniques. techniques.
@ -1543,7 +1543,7 @@ listed in the `manual <manual.html>`_.
Modules Modules
======= =======
Nimrod supports splitting a program into pieces with a `module`:idx: concept. Nimrod supports splitting a program into pieces with a module concept.
Each module is in its own file. Modules enable `information hiding`:idx: and Each module is in its own file. Modules enable `information hiding`:idx: and
`separate compilation`:idx:. A module may gain access to symbols of another `separate compilation`:idx:. A module may gain access to symbols of another
module by the `import`:idx: statement. Only top-level symbols that are marked module by the `import`:idx: statement. Only top-level symbols that are marked
@ -1698,7 +1698,7 @@ define a shorter alias to use when qualifying symbols.
Include statement Include statement
----------------- -----------------
The `include`:idx: statement does something fundamentally different than The ``include`` statement does something fundamentally different than
importing a module: it merely includes the contents of a file. The ``include`` importing a module: it merely includes the contents of a file. The ``include``
statement is useful to split up a large module into several files: statement is useful to split up a large module into several files:

16
doc/tut2.txt
View file

@ -135,7 +135,7 @@ The ``EInvalidObjectConversion`` exception is raised if ``x`` is not a
Object variants Object variants
--------------- ---------------
Often an object hierarchy is overkill in certain situations where simple Often an object hierarchy is overkill in certain situations where simple
`variant`:idx: types are needed. variant types are needed.
An example: An example:
@ -182,7 +182,7 @@ bound to a class. This has disadvantages:
``join`` a string method or an array method? ``join`` a string method or an array method?
Nimrod avoids these problems by not assigning methods to a class. All methods Nimrod avoids these problems by not assigning methods to a class. All methods
in Nimrod are `multi-methods`:idx:. As we will see later, multi-methods are in Nimrod are multi-methods. As we will see later, multi-methods are
distinguished from procs only for dynamic binding purposes. distinguished from procs only for dynamic binding purposes.
@ -194,7 +194,7 @@ The syntax ``obj.method(args)`` can be used instead of ``method(obj, args)``.
If there are no remaining arguments, the parentheses can be omitted: If there are no remaining arguments, the parentheses can be omitted:
``obj.len`` (instead of ``len(obj)``). ``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
for any type: for any type:
.. code-block:: nimrod .. code-block:: nimrod
@ -343,7 +343,7 @@ evaluation or dead code elimination do not work with methods.
Exceptions Exceptions
========== ==========
In Nimrod `exceptions`:idx: are objects. By convention, exception types are In Nimrod exceptions are objects. By convention, exception types are
prefixed with an 'E', not 'T'. The `system <system.html>`_ module defines an prefixed with an 'E', not 'T'. The `system <system.html>`_ module defines an
exception hierarchy that you might want to stick to. Exceptions derive from exception hierarchy that you might want to stick to. Exceptions derive from
E_Base, which provides the common interface. E_Base, which provides the common interface.
@ -380,7 +380,7 @@ the template ``newException`` in the ``system`` module can be used:
Try statement Try statement
------------- -------------
The `try`:idx: statement handles exceptions: The ``try`` statement handles exceptions:
.. code-block:: nimrod .. code-block:: nimrod
# read the first two lines of a text file that should contain numbers # read the first two lines of a text file that should contain numbers
@ -513,7 +513,7 @@ procs with the list of raised exceptions. You can read more about Nimrod's
Generics Generics
======== ========
`Generics`:idx: are Nimrod's means to parametrize procs, iterators or types Generics are Nimrod's means to parametrize procs, iterators or types
with `type parameters`:idx:. They are most useful for efficient type safe with `type parameters`:idx:. They are most useful for efficient type safe
containers: containers:
@ -714,9 +714,9 @@ know how the Nimrod concrete syntax is converted to an abstract syntax tree
(AST). The AST is documented in the `macros <macros.html>`_ module. (AST). The AST is documented in the `macros <macros.html>`_ module.
Once your macro is finished, there are two ways to invoke it: Once your macro is finished, there are two ways to invoke it:
(1) invoking a macro like a procedure call (`expression macros`:idx:) (1) invoking a macro like a procedure call (expression macros)
(2) invoking a macro with the special ``macrostmt`` (2) invoking a macro with the special ``macrostmt``
syntax (`statement macros`:idx:) syntax (statement macros)
Expression Macros Expression Macros