Nimrod renamed to Nim

This commit is contained in:
Araq 2014-08-28 22:36:14 +02:00
commit 3ea6446900
30 changed files with 379 additions and 379 deletions

View file

@ -50,7 +50,7 @@ Advanced options:
--os:SYMBOL set the target operating system (cross-compilation) --os:SYMBOL set the target operating system (cross-compilation)
--cpu:SYMBOL set the target processor (cross-compilation) --cpu:SYMBOL set the target processor (cross-compilation)
--debuginfo enables debug information --debuginfo enables debug information
--debugger:on|off turn Embedded Nimrod Debugger on|off --debugger:on|off turn Embedded Nim Debugger on|off
-t, --passC:OPTION pass an option to the C compiler -t, --passC:OPTION pass an option to the C compiler
-l, --passL:OPTION pass an option to the linker -l, --passL:OPTION pass an option to the linker
--cincludes:DIR modify the C compiler header search path --cincludes:DIR modify the C compiler header search path
@ -58,7 +58,7 @@ Advanced options:
--clib:LIBNAME link an additional C library --clib:LIBNAME link an additional C library
(you should omit platform-specific extensions) (you should omit platform-specific extensions)
--genMapping generate a mapping file containing --genMapping generate a mapping file containing
(Nimrod, mangled) identifier pairs (Nim, mangled) identifier pairs
--project document the whole project (doc2) --project document the whole project (doc2)
--docSeeSrcUrl:url activate 'see source' for doc and doc2 commands --docSeeSrcUrl:url activate 'see source' for doc and doc2 commands
(see doc.item.seesrc in config/nimdoc.cfg) (see doc.item.seesrc in config/nimdoc.cfg)
@ -89,7 +89,7 @@ Advanced options:
--listCmd list the commands used to execute external programs --listCmd list the commands used to execute external programs
--parallelBuild=0|1|... perform a parallel build --parallelBuild=0|1|... perform a parallel build
value = number of processors (0 for auto-detect) value = number of processors (0 for auto-detect)
--verbosity:0|1|2|3 set Nimrod's verbosity level (1 is default) --verbosity:0|1|2|3 set Nim's verbosity level (1 is default)
--cs:none|partial set case sensitivity level (default: none); --cs:none|partial set case sensitivity level (default: none);
do not use! this setting affects the whole language do not use! this setting affects the whole language
-v, --version show detailed version information -v, --version show detailed version information

View file

@ -84,5 +84,5 @@ indentation indent
Coding Guidelines Coding Guidelines
================= =================
For coding guidelines see the `Internals of the Nimrod Compiler For coding guidelines see the `Internals of the Nim Compiler
<intern.html#coding-guidelines>`_ documentation. <intern.html#coding-guidelines>`_ documentation.

View file

@ -1,11 +1,11 @@
The AST in Nimrod The AST in Nim
================= =================
This section describes how the AST is modelled with Nimrod's type system. This section describes how the AST is modelled with Nim's type system.
The AST consists of nodes (``PNimrodNode``) with a variable number of The AST consists of nodes (``PNimrodNode``) with a variable number of
children. Each node has a field named ``kind`` which describes what the node children. Each node has a field named ``kind`` which describes what the node
contains: contains:
.. code-block:: nimrod .. code-block:: nim
type type
TNimrodNodeKind = enum ## kind of a node; only explanatory TNimrodNodeKind = enum ## kind of a node; only explanatory
@ -39,7 +39,7 @@ contains:
For the ``PNimrodNode`` type, the ``[]`` operator has been overloaded: For the ``PNimrodNode`` type, the ``[]`` operator has been overloaded:
``n[i]`` is ``n``'s ``i``-th child. ``n[i]`` is ``n``'s ``i``-th child.
To specify the AST for the different Nimrod constructs, the notation To specify the AST for the different Nim constructs, the notation
``nodekind(son1, son2, ...)`` or ``nodekind(value)`` or ``nodekind(son1, son2, ...)`` or ``nodekind(value)`` or
``nodekind(field=value)`` is used. ``nodekind(field=value)`` is used.
@ -53,7 +53,7 @@ A leaf of the AST often corresponds to a terminal symbol in the concrete
syntax. syntax.
----------------- --------------------------------------------- ----------------- ---------------------------------------------
Nimrod expression corresponding AST Nim expression corresponding AST
----------------- --------------------------------------------- ----------------- ---------------------------------------------
``42`` ``nnkIntLit(intVal = 42)`` ``42`` ``nnkIntLit(intVal = 42)``
``42'i8`` ``nnkInt8Lit(intVal = 42)`` ``42'i8`` ``nnkInt8Lit(intVal = 42)``
@ -87,12 +87,12 @@ Command call
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
echo "abc", "xyz" echo "abc", "xyz"
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkCommand(nnkIdent(!"echo"), nnkStrLit("abc"), nnkStrLit("xyz")) nnkCommand(nnkIdent(!"echo"), nnkStrLit("abc"), nnkStrLit("xyz"))
@ -101,12 +101,12 @@ Call with ``()``
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
echo("abc", "xyz") echo("abc", "xyz")
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkCall(nnkIdent(!"echo"), nnkStrLit("abc"), nnkStrLit("xyz")) nnkCall(nnkIdent(!"echo"), nnkStrLit("abc"), nnkStrLit("xyz"))
@ -115,12 +115,12 @@ Infix operator call
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
"abc" & "xyz" "abc" & "xyz"
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkInfix(nnkIdent(!"&"), nnkStrLit("abc"), nnkStrLit("xyz")) nnkInfix(nnkIdent(!"&"), nnkStrLit("abc"), nnkStrLit("xyz"))
@ -129,29 +129,29 @@ Prefix operator call
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
? "xyz" ? "xyz"
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkPrefix(nnkIdent(!"?"), nnkStrLit("abc")) nnkPrefix(nnkIdent(!"?"), nnkStrLit("abc"))
Postfix operator call Postfix operator call
--------------------- ---------------------
**Note:** There are no postfix operators in Nimrod. However, the **Note:** There are no postfix operators in Nim. However, the
``nnkPostfix`` node is used for the *asterisk export marker* ``*``: ``nnkPostfix`` node is used for the *asterisk export marker* ``*``:
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
identifier* identifier*
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkPostfix(nnkIdent(!"*"), nnkIdent(!"identifier")) nnkPostfix(nnkIdent(!"*"), nnkIdent(!"identifier"))
@ -160,12 +160,12 @@ Call with named arguments
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
writeln(file=stdout, "hallo") writeln(file=stdout, "hallo")
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkCall(nnkIdent(!"writeln"), nnkCall(nnkIdent(!"writeln"),
nnkExprEqExpr(nnkIdent(!"file"), nnkIdent(!"stdout")), nnkExprEqExpr(nnkIdent(!"file"), nnkIdent(!"stdout")),
nnkStrLit("hallo")) nnkStrLit("hallo"))
@ -176,12 +176,12 @@ Dereference operator ``^``
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
x^ x^
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkDerefExpr(nnkIdent(!"x")) nnkDerefExpr(nnkIdent(!"x"))
@ -190,12 +190,12 @@ Addr operator
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
addr(x) addr(x)
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkAddr(nnkIdent(!"x")) nnkAddr(nnkIdent(!"x"))
@ -204,12 +204,12 @@ Cast operator
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
cast[T](x) cast[T](x)
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkCast(nnkIdent(!"T"), nnkIdent(!"x")) nnkCast(nnkIdent(!"T"), nnkIdent(!"x"))
@ -218,12 +218,12 @@ Object access operator ``.``
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
x.y x.y
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkDotExpr(nnkIdent(!"x"), nnkIdent(!"y")) nnkDotExpr(nnkIdent(!"x"), nnkIdent(!"y"))
@ -232,12 +232,12 @@ Array access operator ``[]``
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
x[y] x[y]
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkBracketExpr(nnkIdent(!"x"), nnkIdent(!"y")) nnkBracketExpr(nnkIdent(!"x"), nnkIdent(!"y"))
@ -249,12 +249,12 @@ are built with the ``nnkPar`` node.
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
(1, 2, (3)) (1, 2, (3))
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkPar(nnkIntLit(1), nnkIntLit(2), nnkPar(nnkIntLit(3))) nnkPar(nnkIntLit(1), nnkIntLit(2), nnkPar(nnkIntLit(3)))
@ -265,12 +265,12 @@ Curly braces are used as the set constructor.
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
{1, 2, 3} {1, 2, 3}
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkCurly(nnkIntLit(1), nnkIntLit(2), nnkIntLit(3)) nnkCurly(nnkIntLit(1), nnkIntLit(2), nnkIntLit(3))
@ -281,12 +281,12 @@ Brackets are used as the array constructor.
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
[1, 2, 3] [1, 2, 3]
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkBracket(nnkIntLit(1), nnkIntLit(2), nnkIntLit(3)) nnkBracket(nnkIntLit(1), nnkIntLit(2), nnkIntLit(3))
@ -297,12 +297,12 @@ Ranges occur in set constructors, case statement branches or array slices.
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
1..3 1..3
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkRange(nnkIntLit(1), nnkIntLit(3)) nnkRange(nnkIntLit(1), nnkIntLit(3))
@ -313,12 +313,12 @@ The representation of the if expression is subtle, but easy to traverse.
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
if cond1: expr1 elif cond2: expr2 else: expr3 if cond1: expr1 elif cond2: expr2 else: expr3
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkIfExpr( nnkIfExpr(
nnkElifExpr(cond1, expr1), nnkElifExpr(cond1, expr1),
nnkElifExpr(cond2, expr2), nnkElifExpr(cond2, expr2),
@ -337,7 +337,7 @@ there is no ``else`` branch, no ``nnkElse`` child exists.
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
if cond1: if cond1:
stmt1 stmt1
elif cond2: elif cond2:
@ -349,7 +349,7 @@ Concrete syntax:
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkIfStmt( nnkIfStmt(
nnkElifBranch(cond1, stmt1), nnkElifBranch(cond1, stmt1),
nnkElifBranch(cond2, stmt2), nnkElifBranch(cond2, stmt2),
@ -369,12 +369,12 @@ Assignment
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
x = 42 x = 42
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkAsgn(nnkIdent(!"x"), nnkIntLit(42)) nnkAsgn(nnkIdent(!"x"), nnkIntLit(42))
@ -383,14 +383,14 @@ Statement list
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
stmt1 stmt1
stmt2 stmt2
stmt3 stmt3
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkStmtList(stmt1, stmt2, stmt3) nnkStmtList(stmt1, stmt2, stmt3)
@ -399,7 +399,7 @@ Case statement
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
case expr1 case expr1
of expr2, expr3..expr4: of expr2, expr3..expr4:
stmt1 stmt1
@ -412,7 +412,7 @@ Concrete syntax:
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkCaseStmt( nnkCaseStmt(
expr1, expr1,
nnkOfBranch(expr2, nnkRange(expr3, expr4), stmt1), nnkOfBranch(expr2, nnkRange(expr3, expr4), stmt1),
@ -429,13 +429,13 @@ While statement
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
while expr1: while expr1:
stmt1 stmt1
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkWhileStmt(expr1, stmt1) nnkWhileStmt(expr1, stmt1)
@ -444,13 +444,13 @@ For statement
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
for ident1, ident2 in expr1: for ident1, ident2 in expr1:
stmt1 stmt1
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkForStmt(ident1, ident2, expr1, stmt1) nnkForStmt(ident1, ident2, expr1, stmt1)
@ -459,7 +459,7 @@ Try statement
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
try: try:
stmt1 stmt1
except e1, e2: except e1, e2:
@ -473,7 +473,7 @@ Concrete syntax:
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkTryStmt( nnkTryStmt(
stmt1, stmt1,
nnkExceptBranch(e1, e2, stmt2), nnkExceptBranch(e1, e2, stmt2),
@ -488,12 +488,12 @@ Return statement
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
return expr1 return expr1
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkReturnStmt(expr1) nnkReturnStmt(expr1)
@ -514,12 +514,12 @@ Continue statement
Concrete syntax: Concrete syntax:
.. code-block:: nimrod .. code-block:: nim
continue continue
AST: AST:
.. code-block:: nimrod .. code-block:: nim
nnkContinueStmt() nnkContinueStmt()
Var section Var section

View file

@ -1,9 +1,9 @@
================================ ================================
Nimrod Backend Integration Nim Backend Integration
================================ ================================
:Author: Puppet Master :Author: Puppet Master
:Version: |nimrodversion| :Version: |nimversion|
.. contents:: .. contents::
"Heresy grows from idleness." -- Unknown. "Heresy grows from idleness." -- Unknown.
@ -12,20 +12,20 @@
Introduction Introduction
============ ============
The `Nimrod Compiler User Guide <nimrodc.html>`_ documents the typical The `Nim Compiler User Guide <nimc.html>`_ documents the typical
compiler invocation, using the ``compile`` or ``c`` command to transform a compiler invocation, using the ``compile`` or ``c`` command to transform a
``.nim`` file into one or more ``.c`` files which are then compiled with the ``.nim`` file into one or more ``.c`` files which are then compiled with the
platform's C compiler into a static binary. However there are other commands platform's C compiler into a static binary. However there are other commands
to compile to C++, Objective-C or JavaScript. This document tries to to compile to C++, Objective-C or JavaScript. This document tries to
concentrate in a single place all the backend and interfacing options. concentrate in a single place all the backend and interfacing options.
The Nimrod compiler supports mainly two backend families: the C, C++ and The Nim compiler supports mainly two backend families: the C, C++ and
Objective-C targets and the JavaScript target. `The C like targets`_ creates Objective-C targets and the JavaScript target. `The C like targets`_ creates
source files which can be compiled into a library or a final executable. `The source files which can be compiled into a library or a final executable. `The
JavaScript target`_ can generate a ``.js`` file which you reference from an JavaScript target`_ can generate a ``.js`` file which you reference from an
HTML file or create a `standalone nodejs program <http://nodejs.org>`_. HTML file or create a `standalone nodejs program <http://nodejs.org>`_.
On top of generating libraries or standalone applications, Nimrod offers On top of generating libraries or standalone applications, Nim offers
bidirectional interfacing with the backend targets through generic and bidirectional interfacing with the backend targets through generic and
specific pragmas. specific pragmas.
@ -49,25 +49,25 @@ project. This allows you to take the generated code and place it directly
into a project using any of these languages. Here are some typical command into a project using any of these languages. Here are some typical command
line invocations:: line invocations::
$ nimrod c hallo.nim $ nim c hallo.nim
$ nimrod cpp hallo.nim $ nim cpp hallo.nim
$ nimrod objc hallo.nim $ nim objc hallo.nim
The compiler commands select the target backend, but if needed you can The compiler commands select the target backend, but if needed you can
`specify additional switches for cross compilation `specify additional switches for cross compilation
<nimrodc.html#cross-compilation>`_ to select the target CPU, operative system <nimc.html#cross-compilation>`_ to select the target CPU, operative system
or compiler/linker commands. or compiler/linker commands.
The JavaScript target The JavaScript target
--------------------- ---------------------
Nimrod can also generate `JavaScript`:idx: code through the ``js`` command. Nim can also generate `JavaScript`:idx: code through the ``js`` command.
However, the JavaScript code generator is experimental! However, the JavaScript code generator is experimental!
Nimrod targets JavaScript 1.5 which is supported by any widely used browser. Nim targets JavaScript 1.5 which is supported by any widely used browser.
Since JavaScript does not have a portable means to include another module, Since JavaScript does not have a portable means to include another module,
Nimrod just generates a long ``.js`` file. Nim just generates a long ``.js`` file.
Features or modules that the JavaScript platform does not support are not Features or modules that the JavaScript platform does not support are not
available. This includes: available. This includes:
@ -83,35 +83,35 @@ However, the modules `strutils <strutils.html>`_, `math <math.html>`_, and
`times <times.html>`_ are available! To access the DOM, use the `dom `times <times.html>`_ are available! To access the DOM, use the `dom
<dom.html>`_ module that is only available for the JavaScript platform. <dom.html>`_ module that is only available for the JavaScript platform.
To compile a Nimrod module into a ``.js`` file use the ``js`` command; the To compile a Nim module into a ``.js`` file use the ``js`` command; the
default is a ``.js`` file that is supposed to be referenced in an ``.html`` default is a ``.js`` file that is supposed to be referenced in an ``.html``
file. However, you can also run the code with `nodejs`:idx:, a `software file. However, you can also run the code with `nodejs`:idx:, a `software
platform for easily building fast, scalable network applications platform for easily building fast, scalable network applications
<http://nodejs.org>`_:: <http://nodejs.org>`_::
nimrod js -d:nodejs -r examples/hallo.nim nim js -d:nodejs -r examples/hallo.nim
Interfacing Interfacing
=========== ===========
Nimrod offers bidirectional interfacing with the target backend. This means Nim offers bidirectional interfacing with the target backend. This means
that you can call backend code from Nimrod and Nimrod code can be called by that you can call backend code from Nim and Nim code can be called by
the backend code. Usually the direction of which calls which depends on your the backend code. Usually the direction of which calls which depends on your
software architecture (is Nimrod your main program or is Nimrod providing a software architecture (is Nim your main program or is Nim providing a
component?). component?).
Nimrod code calling the backend Nim code calling the backend
-------------------------------- --------------------------------
Nimrod code can interface with the backend through the `Foreign function Nim code can interface with the backend through the `Foreign function
interface <manual.html#foreign-function-interface>`_ mainly through the interface <manual.html#foreign-function-interface>`_ mainly through the
`importc pragma <manual.html#importc-pragma>`_. The ``importc`` pragma is the `importc pragma <manual.html#importc-pragma>`_. The ``importc`` pragma is the
*generic* way of making backend symbols available in Nimrod and is available *generic* way of making backend symbols available in Nim and is available
in all the target backends (JavaScript too). The C++ or Objective-C backends in all the target backends (JavaScript too). The C++ or Objective-C backends
have their respective `ImportCpp <nimrodc.html#importcpp-pragma>`_ and have their respective `ImportCpp <nimc.html#importcpp-pragma>`_ and
`ImportObjC <nimrodc.html#importobjc-pragma>`_ pragmas to call methods from `ImportObjC <nimc.html#importobjc-pragma>`_ pragmas to call methods from
classes. classes.
Whenever you use any of these pragmas you need to integrate native code into Whenever you use any of these pragmas you need to integrate native code into
@ -121,22 +121,22 @@ JavaScript functions which you are importing with ``importc``.
However, for the C like targets you need to link external code either However, for the C like targets you need to link external code either
statically or dynamically. The preferred way of integrating native code is to statically or dynamically. The preferred way of integrating native code is to
use dynamic linking because it allows you to compile Nimrod programs without use dynamic linking because it allows you to compile Nim programs without
the need for having the related development libraries installed. This is done the need for having the related development libraries installed. This is done
through the `dynlib pragma for import through the `dynlib pragma for import
<manual.html#dynlib-pragma-for-import>`_, though more specific control can be <manual.html#dynlib-pragma-for-import>`_, though more specific control can be
gained using the `dynlib module <dynlib.html>`_. gained using the `dynlib module <dynlib.html>`_.
The `dynlibOverride <nimrodc.html#dynliboverride>`_ command line switch allows The `dynlibOverride <nimc.html#dynliboverride>`_ command line switch allows
to avoid dynamic linking if you need to statically link something instead. to avoid dynamic linking if you need to statically link something instead.
Nimrod wrappers designed to statically link source files can use the `compile Nim wrappers designed to statically link source files can use the `compile
pragma <nimrodc.html#compile-pragma>`_ if there are few sources or providing pragma <nimc.html#compile-pragma>`_ if there are few sources or providing
them along the Nimrod code is easier than using a system library. Libraries them along the Nim code is easier than using a system library. Libraries
installed on the host system can be linked in with the `PassL pragma installed on the host system can be linked in with the `PassL pragma
<nimrodc.html#passl-pragma>`_. <nimc.html#passl-pragma>`_.
To wrap native code, take a look at the `c2nim tool <c2nim.html>`_ which helps To wrap native code, take a look at the `c2nim tool <c2nim.html>`_ which helps
with the process of scanning and transforming header files into a Nimrod with the process of scanning and transforming header files into a Nim
interface. interface.
C invocation example C invocation example
@ -152,7 +152,7 @@ Create a ``logic.c`` file with the following content:
Create a ``calculator.nim`` file with the following content: Create a ``calculator.nim`` file with the following content:
.. code-block:: nimrod .. code-block:: nim
{.compile: "logic.c".} {.compile: "logic.c".}
proc addTwoIntegers(a, b: cint): cint {.importc.} proc addTwoIntegers(a, b: cint): cint {.importc.}
@ -160,8 +160,8 @@ Create a ``calculator.nim`` file with the following content:
when isMainModule: when isMainModule:
echo addTwoIntegers(3, 7) echo addTwoIntegers(3, 7)
With these two files in place, you can run ``nimrod c -r calculator.nim`` and With these two files in place, you can run ``nim c -r calculator.nim`` and
the Nimrod compiler will compile the ``logic.c`` file in addition to the Nim compiler will compile the ``logic.c`` file in addition to
``calculator.nim`` and link both into an executable, which outputs ``10`` when ``calculator.nim`` and link both into an executable, which outputs ``10`` when
run. Another way to link the C file statically and get the same effect would run. Another way to link the C file statically and get the same effect would
be remove the line with the ``compile`` pragma and run the following typical be remove the line with the ``compile`` pragma and run the following typical
@ -169,7 +169,7 @@ Unix commands::
$ gcc -c logic.c $ gcc -c logic.c
$ ar rvs mylib.a logic.o $ ar rvs mylib.a logic.o
$ nimrod c --passL:mylib.a -r calculator.nim $ nim c --passL:mylib.a -r calculator.nim
Just like in this example we pass the path to the ``mylib.a`` library (and we Just like in this example we pass the path to the ``mylib.a`` library (and we
could as well pass ``logic.o``) we could be passing switches to link any other could as well pass ``logic.o``) we could be passing switches to link any other
@ -196,50 +196,50 @@ Create a ``host.html`` file with the following content:
Create a ``calculator.nim`` file with the following content (or reuse the one Create a ``calculator.nim`` file with the following content (or reuse the one
from the previous section): from the previous section):
.. code-block:: nimrod .. code-block:: nim
proc addTwoIntegers(a, b: int): int {.importc.} proc addTwoIntegers(a, b: int): int {.importc.}
when isMainModule: when isMainModule:
echo addTwoIntegers(3, 7) echo addTwoIntegers(3, 7)
Compile the Nimrod code to JavaScript with ``nimrod js -o:calculator.js Compile the Nim code to JavaScript with ``nim js -o:calculator.js
calculator.nim`` and open ``host.html`` in a browser. If the browser supports calculator.nim`` and open ``host.html`` in a browser. If the browser supports
javascript, you should see the value ``10``. In JavaScript the `echo proc javascript, you should see the value ``10``. In JavaScript the `echo proc
<system.html#echo>`_ will modify the HTML DOM and append the string. Use the <system.html#echo>`_ will modify the HTML DOM and append the string. Use the
`dom module <dom.html>`_ for specific DOM querying and modification procs. `dom module <dom.html>`_ for specific DOM querying and modification procs.
Backend code calling Nimrod Backend code calling Nim
--------------------------- ---------------------------
Backend code can interface with Nimrod code exposed through the `exportc Backend code can interface with Nim code exposed through the `exportc
pragma <manual.html#exportc-pragma>`_. The ``exportc`` pragma is the *generic* pragma <manual.html#exportc-pragma>`_. The ``exportc`` pragma is the *generic*
way of making Nimrod symbols available to the backends. By default the Nimrod way of making Nim symbols available to the backends. By default the Nim
compiler will mangle all the Nimrod symbols to avoid any name collision, so compiler will mangle all the Nim symbols to avoid any name collision, so
the most significant thing the ``exportc`` pragma does is maintain the Nimrod the most significant thing the ``exportc`` pragma does is maintain the Nim
symbol name, or if specified, use an alternative symbol for the backend in symbol name, or if specified, use an alternative symbol for the backend in
case the symbol rules don't match. case the symbol rules don't match.
The JavaScript target doesn't have any further interfacing considerations The JavaScript target doesn't have any further interfacing considerations
since it also has garbage collection, but the C targets require you to since it also has garbage collection, but the C targets require you to
initialize Nimrod's internals, which is done calling a ``NimMain`` function. initialize Nim's internals, which is done calling a ``NimMain`` function.
Also, C code requires you to specify a forward declaration for functions or Also, C code requires you to specify a forward declaration for functions or
the compiler will asume certain types for the return value and parameters the compiler will asume certain types for the return value and parameters
which will likely make your program crash at runtime. which will likely make your program crash at runtime.
The Nimrod compiler can generate a C interface header through the ``--header`` The Nim compiler can generate a C interface header through the ``--header``
command line switch. The generated header will contain all the exported command line switch. The generated header will contain all the exported
symbols and the ``NimMain`` proc which you need to call before any other symbols and the ``NimMain`` proc which you need to call before any other
Nimrod code. Nim code.
Nimrod invocation example from C Nim invocation example from C
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create a ``fib.nim`` file with the following content: Create a ``fib.nim`` file with the following content:
.. code-block:: nimrod .. code-block:: nim
proc fib(a: cint): cint {.exportc.} = proc fib(a: cint): cint {.exportc.} =
if a <= 2: if a <= 2:
@ -263,34 +263,34 @@ Create a ``maths.c`` file with the following content:
} }
Now you can run the following Unix like commands to first generate C sources Now you can run the following Unix like commands to first generate C sources
form the Nimrod code, then link them into a static binary along your main C form the Nim code, then link them into a static binary along your main C
program:: program::
$ nimrod c --noMain --noLinking --header:fib.h fib.nim $ nim c --noMain --noLinking --header:fib.h fib.nim
$ gcc -o m -Inimcache -Ipath/to/nimrod/lib nimcache/*.c maths.c $ gcc -o m -Inimcache -Ipath/to/nim/lib nimcache/*.c maths.c
The first command runs the Nimrod compiler with three special options to avoid The first command runs the Nim compiler with three special options to avoid
generating a ``main()`` function in the generated files, avoid linking the generating a ``main()`` function in the generated files, avoid linking the
object files into a final binary, and explicitly generate a header file for C object files into a final binary, and explicitly generate a header file for C
integration. All the generated files are placed into the ``nimcache`` integration. All the generated files are placed into the ``nimcache``
directory. That's why the next command compiles the ``maths.c`` source plus directory. That's why the next command compiles the ``maths.c`` source plus
all the ``.c`` files form ``nimcache``. In addition to this path, you also all the ``.c`` files form ``nimcache``. In addition to this path, you also
have to tell the C compiler where to find Nimrod's ``nimbase.h`` header file. have to tell the C compiler where to find Nim's ``nimbase.h`` header file.
Instead of depending on the generation of the individual ``.c`` files you can Instead of depending on the generation of the individual ``.c`` files you can
also ask the Nimrod compiler to generate a statically linked library:: also ask the Nim compiler to generate a statically linked library::
$ nimrod c --app:staticLib --noMain --header fib.nim $ nim c --app:staticLib --noMain --header fib.nim
$ gcc -o m -Inimcache -Ipath/to/nimrod/lib libfib.nim.a maths.c $ gcc -o m -Inimcache -Ipath/to/nim/lib libfib.nim.a maths.c
The Nimrod compiler will handle linking the source files generated in the The Nim compiler will handle linking the source files generated in the
``nimcache`` directory into the ``libfib.nim.a`` static library, which you can ``nimcache`` directory into the ``libfib.nim.a`` static library, which you can
then link into your C program. Note that these commands are generic and will then link into your C program. Note that these commands are generic and will
vary for each system. For instance, on Linux systems you will likely need to vary for each system. For instance, on Linux systems you will likely need to
use ``-ldl`` too to link in required dlopen functionality. use ``-ldl`` too to link in required dlopen functionality.
Nimrod invocation example from JavaScript Nim invocation example from JavaScript
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create a ``mhost.html`` file with the following content: Create a ``mhost.html`` file with the following content:
@ -307,7 +307,7 @@ Create a ``mhost.html`` file with the following content:
Create a ``fib.nim`` file with the following content (or reuse the one Create a ``fib.nim`` file with the following content (or reuse the one
from the previous section): from the previous section):
.. code-block:: nimrod .. code-block:: nim
proc fib(a: cint): cint {.exportc.} = proc fib(a: cint): cint {.exportc.} =
if a <= 2: if a <= 2:
@ -315,11 +315,11 @@ from the previous section):
else: else:
result = fib(a - 1) + fib(a - 2) result = fib(a - 1) + fib(a - 2)
Compile the Nimrod code to JavaScript with ``nimrod js -o:fib.js fib.nim`` and Compile the Nim code to JavaScript with ``nim js -o:fib.js fib.nim`` and
open ``mhost.html`` in a browser. If the browser supports javascript, you open ``mhost.html`` in a browser. If the browser supports javascript, you
should see an alert box displaying the text ``Fib for 9 is 34``. As mentioned should see an alert box displaying the text ``Fib for 9 is 34``. As mentioned
earlier, JavaScript doesn't require an initialisation call to ``NimMain`` or earlier, JavaScript doesn't require an initialisation call to ``NimMain`` or
similar function and you can call the exported Nimrod proc directly. similar function and you can call the exported Nim proc directly.
Nimcache naming logic Nimcache naming logic
@ -328,17 +328,17 @@ Nimcache naming logic
The `nimcache`:idx: directory is generated during compilation and will hold The `nimcache`:idx: directory is generated during compilation and will hold
either temporary or final files depending on your backend target. The default either temporary or final files depending on your backend target. The default
name for the directory is ``nimcache`` but you can use the ``--nimcache`` name for the directory is ``nimcache`` but you can use the ``--nimcache``
`compiler switch <nimrodc.html#command-line-switches>`_ to change it. `compiler switch <nimc.html#command-line-switches>`_ to change it.
Nimcache and C like targets Nimcache and C like targets
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
The C like backends will place their temporary ``.c``, ``.cpp`` or ``.m`` files The C like backends will place their temporary ``.c``, ``.cpp`` or ``.m`` files
in the ``nimcache`` directory. The naming of these files follows the pattern in the ``nimcache`` directory. The naming of these files follows the pattern
``babelPackageName_`` + ``nimrodSource``: ``babelPackageName_`` + ``nimSource``:
* Filenames for modules imported from `Babel packages * Filenames for modules imported from `Babel packages
<https://github.com/nimrod-code/babel>`_ will end up with <https://github.com/nim-code/babel>`_ will end up with
``babelPackageName_module.c``. For example, if you import the ``babelPackageName_module.c``. For example, if you import the
``argument_parser`` module from the same name Babel package you ``argument_parser`` module from the same name Babel package you
will end up with a ``argument_parser_argument_parser.c`` file will end up with a ``argument_parser_argument_parser.c`` file
@ -375,7 +375,7 @@ Nimcache and the Javascript target
Unless you explicitly use the ``-o:filename.js`` switch as mentioned in the Unless you explicitly use the ``-o:filename.js`` switch as mentioned in the
previous examples, the compiler will create a ``filename.js`` file in the previous examples, the compiler will create a ``filename.js`` file in the
``nimcache`` directory using the name of your input nimrod file. There are no ``nimcache`` directory using the name of your input nim file. There are no
other temporary files generated, the output is always a single self contained other temporary files generated, the output is always a single self contained
``.js`` file. ``.js`` file.
@ -387,38 +387,38 @@ In the previous sections the ``NimMain()`` function reared its head. Since
JavaScript already provides automatic memory management, you can freely pass JavaScript already provides automatic memory management, you can freely pass
objects between the two language without problems. In C and derivate languages objects between the two language without problems. In C and derivate languages
you need to be careful about what you do and how you share memory. The you need to be careful about what you do and how you share memory. The
previous examples only dealt with simple scalar values, but passing a Nimrod previous examples only dealt with simple scalar values, but passing a Nim
string to C, or reading back a C string in Nimrod already requires you to be string to C, or reading back a C string in Nim already requires you to be
aware of who controls what to avoid crashing. aware of who controls what to avoid crashing.
Strings and C strings Strings and C strings
--------------------- ---------------------
The manual mentions that `Nimrod strings are implicitly convertible to The manual mentions that `Nim strings are implicitly convertible to
cstrings <manual.html#cstring-type>`_ which makes interaction usually cstrings <manual.html#cstring-type>`_ which makes interaction usually
painless. Most C functions accepting a Nimrod string converted to a painless. Most C functions accepting a Nim string converted to a
``cstring`` will likely not need to keep this string around and by the time ``cstring`` will likely not need to keep this string around and by the time
they return the string won't be needed any more. However, for the rare cases they return the string won't be needed any more. However, for the rare cases
where a Nimrod string has to be preserved and made available to the C backend where a Nim string has to be preserved and made available to the C backend
as a ``cstring``, you will need to manually prevent the string data from being as a ``cstring``, you will need to manually prevent the string data from being
freed with `GC_ref <system.html#GC_ref>`_ and `GC_unref freed with `GC_ref <system.html#GC_ref>`_ and `GC_unref
<system.html#GC_unref>`_. <system.html#GC_unref>`_.
A similar thing happens with C code invoking Nimrod code which returns a A similar thing happens with C code invoking Nim code which returns a
``cstring``. Consider the following proc: ``cstring``. Consider the following proc:
.. code-block:: nimrod .. code-block:: nim
proc gimme(): cstring {.exportc.} = proc gimme(): cstring {.exportc.} =
result = "Hey there C code! " & $random(100) result = "Hey there C code! " & $random(100)
Since Nimrod's garbage collector is not aware of the C code, once the Since Nim's garbage collector is not aware of the C code, once the
``gimme`` proc has finished it can reclaim the memory of the ``cstring``. ``gimme`` proc has finished it can reclaim the memory of the ``cstring``.
However, from a practical standpoint, the C code invoking the ``gimme`` However, from a practical standpoint, the C code invoking the ``gimme``
function directly will be able to use it since Nimrod's garbage collector has function directly will be able to use it since Nim's garbage collector has
not had a chance to run *yet*. This gives you enough time to make a copy for not had a chance to run *yet*. This gives you enough time to make a copy for
the C side of the program, as calling any further Nimrod procs *might* trigger the C side of the program, as calling any further Nim procs *might* trigger
garbage collection making the previously returned string garbage. Or maybe you garbage collection making the previously returned string garbage. Or maybe you
are `triggering yourself the collection <gc.html>`_. are `triggering yourself the collection <gc.html>`_.
@ -426,35 +426,35 @@ are `triggering yourself the collection <gc.html>`_.
Custom data types Custom data types
----------------- -----------------
Just like strings, custom data types that are to be shared between Nimrod and Just like strings, custom data types that are to be shared between Nim and
the backend will need careful consideration of who controlls who. If you want the backend will need careful consideration of who controlls who. If you want
to hand a Nimrod reference to C code, you will need to use `GC_ref to hand a Nim reference to C code, you will need to use `GC_ref
<system.html#GC_ref>`_ to mark the reference as used, so it does not get <system.html#GC_ref>`_ to mark the reference as used, so it does not get
freed. And for the C backend you will need to expose the `GC_unref freed. And for the C backend you will need to expose the `GC_unref
<system.html#GC_unref>`_ proc to clean up this memory when it is not required <system.html#GC_unref>`_ proc to clean up this memory when it is not required
any more. any more.
Again, if you are wrapping a library which *mallocs* and *frees* data Again, if you are wrapping a library which *mallocs* and *frees* data
structures, you need to expose the appropriate *free* function to Nimrod so structures, you need to expose the appropriate *free* function to Nim so
you can clean it up. And of course, once cleaned you should avoid accessing it you can clean it up. And of course, once cleaned you should avoid accessing it
from Nimrod (or C for that matter). Typically C data structures have their own from Nim (or C for that matter). Typically C data structures have their own
``malloc_structure`` and ``free_structure`` specific functions, so wrapping ``malloc_structure`` and ``free_structure`` specific functions, so wrapping
these for the Nimrod side should be enough. these for the Nim side should be enough.
Thread coordination Thread coordination
------------------- -------------------
When the ``NimMain()`` function is called Nimrod initializes the garbage When the ``NimMain()`` function is called Nim initializes the garbage
collector to the current thread, which is usually the main thread of your collector to the current thread, which is usually the main thread of your
application. If your C code later spawns a different thread and calls Nimrod application. If your C code later spawns a different thread and calls Nim
code, the garbage collector will fail to work properly and you will crash. code, the garbage collector will fail to work properly and you will crash.
As long as you don't use the threadvar emulation Nimrod uses native thread As long as you don't use the threadvar emulation Nim uses native thread
variables, of which you get a fresh version whenever you create a thread. You variables, of which you get a fresh version whenever you create a thread. You
can then attach a GC to this thread via can then attach a GC to this thread via
.. code-block:: nimrod .. code-block:: nim
setStackBottom(addr(someLocal)) setStackBottom(addr(someLocal))
initGC() initGC()

View file

@ -1,11 +1,11 @@
Usage:: Usage::
nimrod command [options] [projectfile] [arguments] nim command [options] [projectfile] [arguments]
Command: Command:
//compile, c compile project with default code generator (C) //compile, c compile project with default code generator (C)
//doc generate the documentation for inputfile //doc generate the documentation for inputfile
//doc2 generate the documentation for the whole project //doc2 generate the documentation for the whole project
//i start Nimrod in interactive mode (limited) //i start Nim in interactive mode (limited)
Arguments: Arguments:
arguments are passed to the program being run (if --run option is selected) arguments are passed to the program being run (if --run option is selected)

View file

@ -1,9 +1,9 @@
=================================== ===================================
Nimrod DocGen Tools Guide Nim DocGen Tools Guide
=================================== ===================================
:Author: Erik O'Leary :Author: Erik O'Leary
:Version: |nimrodversion| :Version: |nimversion|
.. contents:: .. contents::
@ -12,7 +12,7 @@ Introduction
============ ============
This document describes the `documentation generation tools`:idx: built into This document describes the `documentation generation tools`:idx: built into
the `Nimrod compiler <nimrodc.html>`_, which can generate HTML and JSON output the `Nim compiler <nimc.html>`_, which can generate HTML and JSON output
from input .nim files and projects, as well as HTML and LaTeX from input RST from input .nim files and projects, as well as HTML and LaTeX from input RST
(reStructuredText) files. The output documentation will include module (reStructuredText) files. The output documentation will include module
dependencies (``import``), any top-level documentation comments (##), and dependencies (``import``), any top-level documentation comments (##), and
@ -25,12 +25,12 @@ Documentation Comments
Any comments which are preceded by a double-hash (##), are interpreted as Any comments which are preceded by a double-hash (##), are interpreted as
documentation. Comments are parsed as RST (see `reference documentation. Comments are parsed as RST (see `reference
<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_), providing <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_), providing
Nimrod module authors the ability to easily generate richly formatted Nim module authors the ability to easily generate richly formatted
documentation with only their well-documented code. documentation with only their well-documented code.
Example: Example:
.. code-block:: nimrod .. code-block:: nim
type TPerson* = object type TPerson* = object
## This type contains a description of a person ## This type contains a description of a person
name: string name: string
@ -45,7 +45,7 @@ This type contains a description of a person
Field documentation comments can be added to fields like so: Field documentation comments can be added to fields like so:
.. code-block:: nimrod .. code-block:: nim
var numValues: int ## \ var numValues: int ## \
## `numValues` stores the number of values ## `numValues` stores the number of values
@ -54,15 +54,15 @@ this type would not be generated. Documentation will only be generated for
*exported* types/procedures/etc. *exported* types/procedures/etc.
Nimrod file input Nim file input
----------------- -----------------
The following examples will generate documentation for the below contrived The following examples will generate documentation for the below contrived
*Nimrod* module, aptly named 'sample.nim' *Nim* module, aptly named 'sample.nim'
sample.nim: sample.nim:
.. code-block:: nimrod .. code-block:: nim
## This module is a sample. ## This module is a sample.
import strutils import strutils
@ -90,7 +90,7 @@ commands. These command take either a single .nim file, outputting a single
multiple .html files and, optionally, an index file. multiple .html files and, optionally, an index file.
The ``doc`` command:: The ``doc`` command::
nimrod doc sample nim doc sample
Partial Output:: Partial Output::
... ...
@ -99,11 +99,11 @@ Partial Output::
Output can be viewed in full here: `docgen_sample.html <docgen_sample.html>`_. Output can be viewed in full here: `docgen_sample.html <docgen_sample.html>`_.
The next command, called ``doc2``, is very similar to the ``doc`` command, but The next command, called ``doc2``, is very similar to the ``doc`` command, but
will be run after the compiler performs semantic checking on the input nimrod will be run after the compiler performs semantic checking on the input nim
module(s), which allows it to process macros. module(s), which allows it to process macros.
The ``doc2`` command:: The ``doc2`` command::
nimrod doc2 sample nim doc2 sample
Partial Output:: Partial Output::
... ...
@ -127,7 +127,7 @@ Note that this tool is built off of the ``doc`` command, and therefore is
performed before semantic checking. performed before semantic checking.
The ``jsondoc`` command:: The ``jsondoc`` command::
nimrod jsondoc sample nim jsondoc sample
Output:: Output::
[ [
@ -150,9 +150,9 @@ Project switch
-------------- --------------
:: ::
nimrod doc2 --project filename.nim nim doc2 --project filename.nim
This will recursively generate documentation of all nimrod modules imported This will recursively generate documentation of all nim modules imported
into the input module, including system modules. Be careful with this command, into the input module, including system modules. Be careful with this command,
as it may end up sprinkling html files all over your filesystem! as it may end up sprinkling html files all over your filesystem!
@ -161,15 +161,15 @@ Index switch
------------ ------------
:: ::
nimrod doc2 --index:on filename.nim nim doc2 --index:on filename.nim
This will generate an index of all the exported symbols in the input Nimrod This will generate an index of all the exported symbols in the input Nim
module, and put it into a neighboring file with the extension of ``.idx``. The module, and put it into a neighboring file with the extension of ``.idx``. The
index file is line oriented (newlines have to be escaped). Each line index file is line oriented (newlines have to be escaped). Each line
represents a tab separated record of several columns, the first two mandatory, represents a tab separated record of several columns, the first two mandatory,
the rest optional. See the `Index (idx) file format`_ section for details. the rest optional. See the `Index (idx) file format`_ section for details.
Once index files have been generated for one or more modules, the Nimrod Once index files have been generated for one or more modules, the Nim
compiler command ``buildIndex directory`` can be run to go over all the index compiler command ``buildIndex directory`` can be run to go over all the index
files in the specified directory to generate a `theindex.html <theindex.html>`_ files in the specified directory to generate a `theindex.html <theindex.html>`_
file. file.
@ -178,7 +178,7 @@ See source switch
----------------- -----------------
:: ::
nimrod doc2 --docSeeSrcUrl:txt filename.nim nim doc2 --docSeeSrcUrl:txt filename.nim
When you pass the ``docSeeSrcUrl`` switch to docgen, after each documented item When you pass the ``docSeeSrcUrl`` switch to docgen, after each documented item
in your source code the hyper link *See source* will appear pointing to the in your source code the hyper link *See source* will appear pointing to the
@ -191,25 +191,25 @@ hyper link to your own code repository. As you will see by the comments in that
file, the value ``txt`` passed on the command line will be used in the HTML file, the value ``txt`` passed on the command line will be used in the HTML
template along others like ``$path`` and ``$line``. template along others like ``$path`` and ``$line``.
In the case of Nimrod's own documentation, the ``txt`` value is just a commit In the case of Nim's own documentation, the ``txt`` value is just a commit
hash to append to a formatted URL to https://github.com/Araq/Nimrod. The hash to append to a formatted URL to https://github.com/Araq/Nim. The
``tools/nimweb.nim`` helper queries the current git commit hash during doc ``tools/nimweb.nim`` helper queries the current git commit hash during doc
generation, but since you might be working on an unpublished repository, it generation, but since you might be working on an unpublished repository, it
also allows specifying a ``githash`` value in ``web/nimrod.ini`` to force a also allows specifying a ``githash`` value in ``web/nim.ini`` to force a
specific commit in the output. specific commit in the output.
Other Input Formats Other Input Formats
=================== ===================
The *Nimrod compiler* also has support for RST (reStructuredText) files with The *Nim compiler* also has support for RST (reStructuredText) files with
the ``rst2html`` and ``rst2tex`` commands. Documents like this one are the ``rst2html`` and ``rst2tex`` commands. Documents like this one are
initially written in a dialect of RST which adds support for nimrod sourcecode initially written in a dialect of RST which adds support for nim sourcecode
highlighting with the ``.. code-block:: nimrod`` prefix. ``code-block`` also highlighting with the ``.. code-block:: nim`` prefix. ``code-block`` also
supports highlighting of C++ and some other c-like languages. supports highlighting of C++ and some other c-like languages.
Usage:: Usage::
nimrod rst2html docgen.txt nim rst2html docgen.txt
Output:: Output::
You're reading it! You're reading it!
@ -272,8 +272,8 @@ symbols in the `system module <system.html>`_.
`#TSignedInt <system.html#TSignedInt>`_ `#TSignedInt <system.html#TSignedInt>`_
* ``var globalRaiseHook: proc (e: ref E_Base): bool {.nimcall.}`` **=>** * ``var globalRaiseHook: proc (e: ref E_Base): bool {.nimcall.}`` **=>**
`#globalRaiseHook <system.html#globalRaiseHook>`_ `#globalRaiseHook <system.html#globalRaiseHook>`_
* ``const NimrodVersion = "0.0.0"`` **=>** * ``const NimVersion = "0.0.0"`` **=>**
`#NimrodVersion <system.html#NimrodVersion>`_ `#NimVersion <system.html#NimVersion>`_
* ``proc getTotalMem(): int {.rtl, raises: [], tags: [].}`` **=>** * ``proc getTotalMem(): int {.rtl, raises: [], tags: [].}`` **=>**
`#getTotalMem, <system.html#getTotalMem,>`_ `#getTotalMem, <system.html#getTotalMem,>`_
* ``proc len[T](x: seq[T]): int {.magic: "LengthSeq", noSideEffect.}`` **=>** * ``proc len[T](x: seq[T]): int {.magic: "LengthSeq", noSideEffect.}`` **=>**
@ -304,7 +304,7 @@ but can have up to four (additional columns are ignored). The content of these
columns is: columns is:
1. Mandatory term being indexed. Terms can include quoting according to 1. Mandatory term being indexed. Terms can include quoting according to
Nimrod's rules (eg. \`^\` like in `the actors module Nim's rules (eg. \`^\` like in `the actors module
<actors.html#^,ptr.TChannel[T]>`_). <actors.html#^,ptr.TChannel[T]>`_).
2. Base filename plus anchor hyper link (eg. 2. Base filename plus anchor hyper link (eg.
``algorithm.html#*,int,TSortOrder``). ``algorithm.html#*,int,TSortOrder``).
@ -342,7 +342,7 @@ final index, and TOC entries found in ``.nim`` files are discarded.
Additional resources Additional resources
==================== ====================
`Nimrod Compiler User Guide <nimrodc.html#command-line-switches>`_ `Nim Compiler User Guide <nimc.html#command-line-switches>`_
`RST Quick Reference `RST Quick Reference
<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_

View file

@ -1,18 +1,18 @@
The documentation consists of several documents: The documentation consists of several documents:
- | `Tutorial (part I) <tut1.html>`_ - | `Tutorial (part I) <tut1.html>`_
| The Nimrod tutorial part one deals with the basics. | The Nim tutorial part one deals with the basics.
- | `Tutorial (part II) <tut2.html>`_ - | `Tutorial (part II) <tut2.html>`_
| The Nimrod tutorial part two deals with the advanced language constructs. | The Nim tutorial part two deals with the advanced language constructs.
- | `Language Manual <manual.html>`_ - | `Language Manual <manual.html>`_
| The Nimrod manual is a draft that will evolve into a proper specification. | The Nim manual is a draft that will evolve into a proper specification.
- | `Library documentation <lib.html>`_ - | `Library documentation <lib.html>`_
| This document describes Nimrod's standard library. | This document describes Nim's standard library.
- | `Compiler user guide <nimrodc.html>`_ - | `Compiler user guide <nimc.html>`_
| The user guide lists command line arguments, special features of the | The user guide lists command line arguments, special features of the
compiler, etc. compiler, etc.
@ -20,11 +20,11 @@ The documentation consists of several documents:
| Description of some tools that come with the standard distribution. | Description of some tools that come with the standard distribution.
- | `GC <gc.html>`_ - | `GC <gc.html>`_
| Additional documentation about Nimrod's GC and how to operate it in a | Additional documentation about Nim's GC and how to operate it in a
| realtime setting. | realtime setting.
- | `Source code filters <filters.html>`_ - | `Source code filters <filters.html>`_
| The Nimrod compiler supports source code filters as a simple yet powerful | The Nim compiler supports source code filters as a simple yet powerful
builtin templating system. builtin templating system.
- | `Term rewriting macros <trmacros.html>`_ - | `Term rewriting macros <trmacros.html>`_

View file

@ -1,5 +1,5 @@
===================================================================== =====================================================================
Side effects in Nimrod Side effects in Nim
===================================================================== =====================================================================
Note: Side effects are implicit produced values! Maybe they should be Note: Side effects are implicit produced values! Maybe they should be
@ -13,7 +13,7 @@ difficult is the ``newString`` proc: If it is simply wrapped, it
should not be evaluated at compile time! On other occasions it can should not be evaluated at compile time! On other occasions it can
and should be evaluted: and should be evaluted:
.. code-block:: nimrod .. code-block:: nim
proc toUpper(s: string): string = proc toUpper(s: string): string =
result = newString(len(s)) result = newString(len(s))
for i in 0..len(s) - 1: for i in 0..len(s) - 1:

View file

@ -1,15 +1,15 @@
============================================== ==============================================
Embedded Nimrod Debugger (ENDB) User Guide Embedded Nim Debugger (ENDB) User Guide
============================================== ==============================================
:Author: Andreas Rumpf :Author: Andreas Rumpf
:Version: |nimrodversion| :Version: |nimversion|
.. contents:: .. contents::
Nimrod comes with a platform independent debugger - Nim comes with a platform independent debugger -
the Embedded Nimrod Debugger (ENDB). The debugger is the Embedded Nim 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.
@ -20,7 +20,7 @@ available for the debugger.
If you start your program the debugger will immediately show If you start your program the debugger will immediately show
a prompt on the console. You can now enter a command. The next sections a prompt on the console. You can now enter a command. The next sections
deal with the possible commands. As usual in Nimrod in all commands deal with the possible commands. As usual in Nim in all commands
underscores and case do not matter. Optional components of a command underscores and case do not matter. Optional components of a command
are listed in brackets ``[...]`` here. are listed in brackets ``[...]`` here.
@ -105,7 +105,7 @@ The ``breakpoint`` pragma
The ``breakpoint`` 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:: Nim
write("1") write("1")
{.breakpoint: "before_write_2".} {.breakpoint: "before_write_2".}
write("2") write("2")
@ -125,7 +125,7 @@ The ``watchpoint`` pragma
The ``watchpoint`` 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:: Nim
var a: array [0..20, int] var a: array [0..20, int]
{.watchpoint: a[3].} {.watchpoint: a[3].}
@ -141,7 +141,7 @@ is turned on, so you don't need to remove it from your source code after
debugging. debugging.
Due to the primitive implementation watchpoints are even slower than Due to the primitive implementation watchpoints are even slower than
breakpoints: After *every* executed Nimrod code line it is checked whether the breakpoints: After *every* executed Nim code line it is checked whether the
location changed. location changed.
@ -159,7 +159,7 @@ Data Display Commands
in the current stack frame, use the ``up`` or ``down`` command. in the current stack frame, use the ``up`` or ``down`` command.
Unfortunately, only inspecting variables is possible at the moment. Maybe Unfortunately, only inspecting variables is possible at the moment. Maybe
a future version will implement a full-blown Nimrod expression evaluator, a future version will implement a full-blown Nim expression evaluator,
but this is not easy to do and would bloat the debugger's code. but this is not easy to do and would bloat the debugger's code.
Since displaying the whole data structures is often not needed and Since displaying the whole data structures is often not needed and

View file

@ -3,10 +3,10 @@
=================================================== ===================================================
:Author: Andreas Rumpf :Author: Andreas Rumpf
:Version: |nimrodversion| :Version: |nimversion|
Nimrod comes with a platform independent profiler - Nim comes with a platform independent profiler -
the Embedded Stack Trace Profiler (ESTP). 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:
@ -49,7 +49,7 @@ Example results file
The results file lists stack traces ordered by significance. The results file lists stack traces ordered by significance.
The following example file has been generated by profiling the Nimrod compiler The following example file has been generated by profiling the Nim compiler
itself: It shows that in total 5.4% of the runtime has been spent itself: It shows that in total 5.4% of the runtime has been spent
in ``crcFromRope`` or its children. in ``crcFromRope`` or its children.
@ -74,7 +74,7 @@ often remains mysterious.
CommandCompileToC CommandCompileToC
MainCommand MainCommand
HandleCmdLine HandleCmdLine
nimrod nim
Entry: 1/3391 Calls: 46/4160 = 1.1% [sum: 130; 130/4160 = 3.1%] Entry: 1/3391 Calls: 46/4160 = 1.1% [sum: 130; 130/4160 = 3.1%]
updateCrc32 updateCrc32
newCrcFromRopeAux newCrcFromRopeAux
@ -90,7 +90,7 @@ often remains mysterious.
CommandCompileToC CommandCompileToC
MainCommand MainCommand
HandleCmdLine HandleCmdLine
nimrod nim
Entry: 2/3391 Calls: 41/4160 = 0.99% [sum: 171; 171/4160 = 4.1%] Entry: 2/3391 Calls: 41/4160 = 0.99% [sum: 171; 171/4160 = 4.1%]
updateCrc32 updateCrc32
updateCrc32 updateCrc32
@ -107,7 +107,7 @@ often remains mysterious.
CommandCompileToC CommandCompileToC
MainCommand MainCommand
HandleCmdLine HandleCmdLine
nimrod nim
Entry: 3/3391 Calls: 41/4160 = 0.99% [sum: 212; 212/4160 = 5.1%] Entry: 3/3391 Calls: 41/4160 = 0.99% [sum: 212; 212/4160 = 5.1%]
crcFromFile crcFromFile
writeRopeIfNotEqual writeRopeIfNotEqual
@ -121,7 +121,7 @@ often remains mysterious.
CommandCompileToC CommandCompileToC
MainCommand MainCommand
HandleCmdLine HandleCmdLine
nimrod nim
Entry: 4/3391 Calls: 41/4160 = 0.99% [sum: 253; 253/4160 = 6.1%] Entry: 4/3391 Calls: 41/4160 = 0.99% [sum: 253; 253/4160 = 6.1%]
updateCrc32 updateCrc32
crcFromFile crcFromFile
@ -136,7 +136,7 @@ often remains mysterious.
CommandCompileToC CommandCompileToC
MainCommand MainCommand
HandleCmdLine HandleCmdLine
nimrod nim
Entry: 5/3391 Calls: 32/4160 = 0.77% [sum: 285; 285/4160 = 6.9%] Entry: 5/3391 Calls: 32/4160 = 0.77% [sum: 285; 285/4160 = 6.9%]
pop pop
newCrcFromRopeAux newCrcFromRopeAux
@ -152,7 +152,7 @@ often remains mysterious.
CommandCompileToC CommandCompileToC
MainCommand MainCommand
HandleCmdLine HandleCmdLine
nimrod nim
Entry: 6/3391 Calls: 17/4160 = 0.41% [sum: 302; 302/4160 = 7.3%] Entry: 6/3391 Calls: 17/4160 = 0.41% [sum: 302; 302/4160 = 7.3%]
doOperation doOperation
forAllChildrenAux forAllChildrenAux
@ -171,7 +171,7 @@ often remains mysterious.
MainCommand MainCommand
HandleCmdLine HandleCmdLine
... ...
nimrod nim
Entry: 7/3391 Calls: 14/4160 = 0.34% [sum: 316; 316/4160 = 7.6%] Entry: 7/3391 Calls: 14/4160 = 0.34% [sum: 316; 316/4160 = 7.6%]
Contains Contains
isAccessible isAccessible

View file

@ -1,10 +1,10 @@
Short description of Nimrod's modules Short description of Nim's modules
------------------------------------- -------------------------------------
============== ========================================================== ============== ==========================================================
Module Description Module Description
============== ========================================================== ============== ==========================================================
nimrod main module: parses the command line and calls nim main module: parses the command line and calls
``main.MainCommand`` ``main.MainCommand``
main implements the top-level command dispatching main implements the top-level command dispatching
nimconf implements the config file reader nimconf implements the config file reader
@ -12,8 +12,8 @@ syntaxes dispatcher for the different parsers and filters
filter_tmpl standard template filter (``#! stdtempl``) filter_tmpl standard template filter (``#! stdtempl``)
lexbase buffer handling of the lexical analyser lexbase buffer handling of the lexical analyser
lexer lexical analyser lexer lexical analyser
parser Nimrod's parser parser Nim's parser
renderer Nimrod code renderer (AST back to its textual form) renderer Nim code renderer (AST back to its textual form)
options contains global and local compiler options options contains global and local compiler options
ast type definitions of the abstract syntax tree (AST) and ast type definitions of the abstract syntax tree (AST) and
node constructors node constructors
@ -37,7 +37,7 @@ pragmas semantic checking of pragmas
idents implements a general mapping from identifiers to an internal idents implements a general mapping from identifiers to an internal
representation (``PIdent``) that is used so that a simple representation (``PIdent``) that is used so that a simple
id-comparison suffices to say whether two Nimrod identifiers id-comparison suffices to say whether two Nim identifiers
are equivalent are equivalent
ropes implements long strings represented as trees for ropes implements long strings represented as trees for
lazy evaluation; used mainly by the code generators lazy evaluation; used mainly by the code generators

View file

@ -40,7 +40,7 @@ Filters can be combined with the ``|`` pipe operator::
Available filters Available filters
================= =================
**Hint:** With ``--verbosity:2`` (or higher) Nimrod lists the processed code **Hint:** With ``--verbosity:2`` (or higher) Nim lists the processed code
after each filter application. after each filter application.
Replace filter Replace filter
@ -79,19 +79,19 @@ Parameters and their defaults:
StdTmpl filter StdTmpl filter
-------------- --------------
The stdtmpl filter provides a simple templating engine for Nimrod. The The stdtmpl filter provides a simple templating engine for Nim. 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 Nim 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
statements need ``end X`` delimiters. statements need ``end X`` delimiters.
Parameters and their defaults: Parameters and their defaults:
``metaChar: char = '#'`` ``metaChar: char = '#'``
prefix for a line that contains Nimrod code prefix for a line that contains Nim code
``subsChar: char = '$'`` ``subsChar: char = '$'``
prefix for a Nimrod expression within a template line prefix for a Nim expression within a template line
``conc: string = " & "`` ``conc: string = " & "``
the operation for concatenation the operation for concatenation
@ -130,7 +130,7 @@ Example::
The filter transforms this into: The filter transforms this into:
.. code-block:: nimrod .. code-block:: nim
proc generateHTMLPage(title, currentTab, content: string, proc generateHTMLPage(title, currentTab, content: string,
tabs: openArray[string]): string = tabs: openArray[string]): string =
result = "" result = ""
@ -158,7 +158,7 @@ The filter transforms this into:
Each line that does not start with the meta character (ignoring leading Each line that does not start with the meta character (ignoring leading
whitespace) is converted to a string literal that is added to ``result``. whitespace) is converted to a string literal that is added to ``result``.
The substitution character introduces a Nimrod expression *e* within the The substitution character introduces a Nim expression *e* within the
string literal. *e* is converted to a string with the *toString* operation string literal. *e* is converted to a string with the *toString* operation
which defaults to ``$``. For strong type checking, set ``toString`` to the which defaults to ``$``. For strong type checking, set ``toString`` to the
empty string. *e* must match this PEG pattern:: empty string. *e* must match this PEG pattern::

View file

@ -1,9 +1,9 @@
========================== ==========================
Nimrod's Garbage Collector Nim's Garbage Collector
========================== ==========================
:Author: Andreas Rumpf :Author: Andreas Rumpf
:Version: |nimrodversion| :Version: |nimversion|
"The road to hell is paved with good intentions." "The road to hell is paved with good intentions."
@ -37,7 +37,7 @@ it is necessary to help this analysis with the ``acyclic`` pragma (see
You can also use the ``acyclic`` pragma for data that is cyclic in reality and You can also use the ``acyclic`` pragma for data that is cyclic in reality and
then break up the cycles explicitly with ``GC_addCycleRoot``. This can be a then break up the cycles explicitly with ``GC_addCycleRoot``. This can be a
very valuable optimization; the Nimrod compiler itself relies on this very valuable optimization; the Nim compiler itself relies on this
optimization trick to improve performance. Note that ``GC_addCycleRoot`` is optimization trick to improve performance. Note that ``GC_addCycleRoot`` is
a quick operation; the root is only registered for the next run of the a quick operation; the root is only registered for the next run of the
cycle collector. cycle collector.
@ -49,7 +49,7 @@ Realtime support
To enable realtime support, the symbol `useRealtimeGC`:idx: needs to be To enable realtime support, the symbol `useRealtimeGC`:idx: needs to be
defined. With this switch the GC supports the following operations: defined. With this switch the GC supports the following operations:
.. code-block:: nimrod .. code-block:: nim
proc GC_setMaxPause*(MaxPauseInUs: int) proc GC_setMaxPause*(MaxPauseInUs: int)
proc GC_step*(us: int, strongAdvice = false) proc GC_step*(us: int, strongAdvice = false)
@ -111,7 +111,7 @@ highly specialized environments or for older hardware.
Keeping track of memory Keeping track of memory
----------------------- -----------------------
If you need to pass around memory allocated by Nimrod to C, you can use the If you need to pass around memory allocated by Nim to C, you can use the
procs ``GC_ref`` and ``GC_unref`` to mark objects as referenced to avoid them procs ``GC_ref`` and ``GC_unref`` to mark objects as referenced to avoid them
being freed by the GC. Other useful procs from `system <system.html>`_ you can being freed by the GC. Other useful procs from `system <system.html>`_ you can
use to keep track of memory are: use to keep track of memory are:

View file

@ -1,9 +1,9 @@
================================ ================================
Nimrod IDE Integration Guide Nim IDE Integration Guide
================================ ================================
:Author: Britney Spears :Author: Britney Spears
:Version: |nimrodversion| :Version: |nimversion|
.. contents:: .. contents::
@ -13,17 +13,17 @@
"yes, I'm the creator" -- Araq, 2013-07-26 19:28:32. "yes, I'm the creator" -- Araq, 2013-07-26 19:28:32.
</p></blockquote> </p></blockquote>
Nimrod differs from many other compilers in that it is really fast, Nim 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`` command of `the compiler <nimrodc.html>`_, any IDE ``idetools`` command of `the compiler <nimc.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.
This document will guide you through the available options. If you This document will guide you through the available options. If you
want to look at practical examples of idetools support you can look want to look at practical examples of idetools support you can look
at the test files found in the `Test suite`_ or `various editor at the test files found in the `Test suite`_ or `various editor
integrations <https://github.com/Araq/Nimrod/wiki/Editor-Support>`_ integrations <https://github.com/Araq/Nim/wiki/Editor-Support>`_
already available. already available.
@ -37,11 +37,11 @@ All of the available idetools commands require you to specify a
query location through the ``--track`` or ``--trackDirty`` switches. query location through the ``--track`` or ``--trackDirty`` switches.
The general idetools invokations are:: The general idetools invokations are::
nimrod idetools --track:FILE,LINE,COL <switches> proj.nim nim idetools --track:FILE,LINE,COL <switches> proj.nim
Or:: Or::
nimrod idetools --trackDirty:DIRTY_FILE,FILE,LINE,COL <switches> proj.nim nim idetools --trackDirty:DIRTY_FILE,FILE,LINE,COL <switches> proj.nim
``proj.nim`` ``proj.nim``
This is the main *project* filename. Most of the time you will This is the main *project* filename. Most of the time you will
@ -97,7 +97,7 @@ provide the typical *Jump to definition* where a user puts the
cursor on a symbol or uses the mouse to select it and is redirected cursor on a symbol or uses the mouse to select it and is redirected
to the place where the symbol is located. to the place where the symbol is located.
Since Nimrod is implemented in Nimrod, one of the nice things of Since Nim is implemented in Nim, one of the nice things of
this feature is that any user with an IDE supporting it can quickly this feature is that any user with an IDE supporting it can quickly
jump around the standard library implementation and see exactly jump around the standard library implementation and see exactly
what a proc does, learning about the language and seeing real life what a proc does, learning about the language and seeing real life
@ -118,7 +118,7 @@ includes/imports) and when the user starts typing something a
completion box with different options appears. completion box with different options appears.
However such features are not context sensitive and work simply on However such features are not context sensitive and work simply on
string matching, which can be problematic in Nimrod especially due string matching, which can be problematic in Nim especially due
to the case insensitiveness of the language (plus underscores as to the case insensitiveness of the language (plus underscores as
separators!). separators!).
@ -179,16 +179,16 @@ in the millisecond range, thus being responsive enough for IDEs.
If you want to start the server using stdin/stdout as communication If you want to start the server using stdin/stdout as communication
you need to type:: you need to type::
nimrod serve --server.type:stdin proj.nim nim serve --server.type:stdin proj.nim
If you want to start the server using tcp and a port, you need to type:: If you want to start the server using tcp and a port, you need to type::
nimrod serve --server.type:tcp --server.port:6000 \ nim serve --server.type:tcp --server.port:6000 \
--server.address:hostname proj.nim --server.address:hostname proj.nim
In both cases the server will start up and await further commands. In both cases the server will start up and await further commands.
The syntax of the commands you can now send to the server is The syntax of the commands you can now send to the server is
practically the same as running the nimrod compiler on the commandline, practically the same as running the nim compiler on the commandline,
you only need to remove the name of the compiler since you are you only need to remove the name of the compiler since you are
already talking to it. The server will answer with as many lines already talking to it. The server will answer with as many lines
of text it thinks necessary plus an empty line to indicate the end of text it thinks necessary plus an empty line to indicate the end
@ -242,7 +242,7 @@ skConst
| **Fourth column**: the type of the const value. | **Fourth column**: the type of the const value.
| **Docstring**: always the empty string. | **Docstring**: always the empty string.
.. code-block:: nimrod .. code-block:: nim
const SOME_SEQUENCE = @[1, 2] const SOME_SEQUENCE = @[1, 2]
--> col 2: $MODULE.SOME_SEQUENCE --> col 2: $MODULE.SOME_SEQUENCE
col 3: seq[int] col 3: seq[int]
@ -256,7 +256,7 @@ skEnumField
| **Fourth column**: enum type grouping other enum fields. | **Fourth column**: enum type grouping other enum fields.
| **Docstring**: always the empty string. | **Docstring**: always the empty string.
.. code-block:: nimrod .. code-block:: nim
Open(filename, fmWrite) Open(filename, fmWrite)
--> col 2: system.TFileMode.fmWrite --> col 2: system.TFileMode.fmWrite
col 3: TFileMode col 3: TFileMode
@ -270,7 +270,7 @@ skForVar
| **Fourth column**: type of the var. | **Fourth column**: type of the var.
| **Docstring**: always the empty string. | **Docstring**: always the empty string.
.. code-block:: nimrod .. code-block:: nim
proc looper(filename = "tests.nim") = proc looper(filename = "tests.nim") =
for letter in filename: for letter in filename:
echo letter echo letter
@ -291,7 +291,7 @@ posterior instances of the iterator.
| **Fourth column**: signature of the iterator including return type. | **Fourth column**: signature of the iterator including return type.
| **Docstring**: docstring if available. | **Docstring**: docstring if available.
.. code-block:: nimrod .. code-block:: nim
let let
text = "some text" text = "some text"
letters = toSeq(runes(text)) letters = toSeq(runes(text))
@ -307,7 +307,7 @@ skLabel
| **Fourth column**: always the empty string. | **Fourth column**: always the empty string.
| **Docstring**: always the empty string. | **Docstring**: always the empty string.
.. code-block:: nimrod .. code-block:: nim
proc test(text: string) = proc test(text: string) =
var found = -1 var found = -1
block loops: block loops:
@ -323,7 +323,7 @@ skLet
| **Fourth column**: the type of the let variable. | **Fourth column**: the type of the let variable.
| **Docstring**: always the empty string. | **Docstring**: always the empty string.
.. code-block:: nimrod .. code-block:: nim
let let
text = "some text" text = "some text"
--> col 2: $MODULE.text --> col 2: $MODULE.text
@ -343,7 +343,7 @@ posterior instances of the macro.
| **Fourth column**: signature of the macro including return type. | **Fourth column**: signature of the macro including return type.
| **Docstring**: docstring if available. | **Docstring**: docstring if available.
.. code-block:: nimrod .. code-block:: nim
proc testMacro() = proc testMacro() =
expect(EArithmetic): expect(EArithmetic):
--> col 2: idetools_api.expect --> col 2: idetools_api.expect
@ -379,7 +379,7 @@ This may change in the future.
| **Fourth column**: signature of the method including return type. | **Fourth column**: signature of the method including return type.
| **Docstring**: docstring if available. | **Docstring**: docstring if available.
.. code-block:: nimrod .. code-block:: nim
method eval(e: PExpr): int = quit "to override!" method eval(e: PExpr): int = quit "to override!"
method eval(e: PLiteral): int = e.x method eval(e: PLiteral): int = e.x
method eval(e: PPlusExpr): int = eval(e.a) + eval(e.b) method eval(e: PPlusExpr): int = eval(e.a) + eval(e.b)
@ -396,7 +396,7 @@ skParam
| **Fourth column**: the type of the parameter. | **Fourth column**: the type of the parameter.
| **Docstring**: always the empty string. | **Docstring**: always the empty string.
.. code-block:: nimrod .. code-block:: nim
proc reader(filename = "tests.nim") = proc reader(filename = "tests.nim") =
let text = readFile(filename) let text = readFile(filename)
--> col 2: $MODULE.reader.filename --> col 2: $MODULE.reader.filename
@ -420,7 +420,7 @@ returned by idetools returns also the pragmas for the proc.
| **Fourth column**: signature of the proc including return type. | **Fourth column**: signature of the proc including return type.
| **Docstring**: docstring if available. | **Docstring**: docstring if available.
.. code-block:: nimrod .. code-block:: nim
Open(filename, fmWrite) Open(filename, fmWrite)
--> col 2: system.Open --> col 2: system.Open
col 3: proc (var TFile, string, TFileMode, int): bool col 3: proc (var TFile, string, TFileMode, int): bool
@ -438,7 +438,7 @@ skResult
| **Fourth column**: the type of the result. | **Fourth column**: the type of the result.
| **Docstring**: always the empty string. | **Docstring**: always the empty string.
.. code-block:: nimrod .. code-block:: nim
proc getRandomValue() : int = proc getRandomValue() : int =
return 4 return 4
--> col 2: $MODULE.getRandomValue.result --> col 2: $MODULE.getRandomValue.result
@ -458,7 +458,7 @@ posterior instances of the template.
| **Fourth column**: signature of the template including return type. | **Fourth column**: signature of the template including return type.
| **Docstring**: docstring if available. | **Docstring**: docstring if available.
.. code-block:: nimrod .. code-block:: nim
let let
text = "some text" text = "some text"
letters = toSeq(runes(text)) letters = toSeq(runes(text))
@ -469,7 +469,7 @@ posterior instances of the template.
Example: Example:
.. code-block:: nimrod .. code-block:: nim
let let
numeric = @[1, 2, 3, 4, 5, 6, 7, 8, 9] numeric = @[1, 2, 3, 4, 5, 6, 7, 8, 9]
odd_numbers = toSeq(filter(numeric) do (x: int) -> bool: odd_numbers = toSeq(filter(numeric) do (x: int) -> bool:
@ -485,7 +485,7 @@ skType
| **Fourth column**: the type. | **Fourth column**: the type.
| **Docstring**: always the empty string. | **Docstring**: always the empty string.
.. code-block:: nimrod .. code-block:: nim
proc writeTempFile() = proc writeTempFile() =
var output: TFile var output: TFile
--> col 2: system.TFile --> col 2: system.TFile
@ -500,7 +500,7 @@ skVar
| **Fourth column**: the type of the var. | **Fourth column**: the type of the var.
| **Docstring**: always the empty string. | **Docstring**: always the empty string.
.. code-block:: nimrod .. code-block:: nim
proc writeTempFile() = proc writeTempFile() =
var output: TFile var output: TFile
output.open("/tmp/somefile", fmWrite) output.open("/tmp/somefile", fmWrite)
@ -527,8 +527,8 @@ At the moment idetools support is still in development so the test
suite is not integrated with the main test suite and you have to suite is not integrated with the main test suite and you have to
run it manually. First you have to compile the tester:: run it manually. First you have to compile the tester::
$ cd my/nimrod/checkout/tests $ cd my/nim/checkout/tests
$ nimrod c testament/caasdriver.nim $ nim c testament/caasdriver.nim
Running the ``caasdriver`` without parameters will attempt to process Running the ``caasdriver`` without parameters will attempt to process
all the test cases in all three operation modes. If a test succeeds all the test cases in all three operation modes. If a test succeeds
@ -540,7 +540,7 @@ parameter ``verbose`` to force all output even on successfull tests.
The normal operation mode is called ``ProcRun`` and it involves The normal operation mode is called ``ProcRun`` and it involves
starting a process for each command or query, similar to running starting a process for each command or query, similar to running
manually the Nimrod compiler from the commandline. The ``CaasRun`` manually the Nim compiler from the commandline. The ``CaasRun``
mode starts a server process to answer all queries. The ``SymbolProcRun`` mode starts a server process to answer all queries. The ``SymbolProcRun``
mode is used by compiler developers. This means that running all mode is used by compiler developers. This means that running all
tests involves processing all ``*.txt`` files three times, which tests involves processing all ``*.txt`` files three times, which

View file

@ -1,10 +1,10 @@
========================================= =========================================
Internals of the Nimrod Compiler Internals of the Nim Compiler
========================================= =========================================
:Author: Andreas Rumpf :Author: Andreas Rumpf
:Version: |nimrodversion| :Version: |nimversion|
.. contents:: .. contents::
@ -14,23 +14,23 @@
Directory structure Directory structure
=================== ===================
The Nimrod project's directory structure is: The Nim project's directory structure is:
============ ============================================== ============ ==============================================
Path Purpose Path Purpose
============ ============================================== ============ ==============================================
``bin`` generated binary files ``bin`` generated binary files
``build`` generated C code for the installation ``build`` generated C code for the installation
``compiler`` the Nimrod compiler itself; note that this ``compiler`` the Nim compiler itself; note that this
code has been translated from a bootstrapping code has been translated from a bootstrapping
version written in Pascal, so the code is **not** version written in Pascal, so the code is **not**
a poster child of good Nimrod code a poster child of good Nim code
``config`` configuration files for Nimrod ``config`` configuration files for Nim
``dist`` additional packages for the distribution ``dist`` additional packages for the distribution
``doc`` the documentation; it is a bunch of ``doc`` the documentation; it is a bunch of
reStructuredText files reStructuredText files
``lib`` the Nimrod library ``lib`` the Nim library
``web`` website of Nimrod; generated by ``nimweb`` ``web`` website of Nim; generated by ``nimweb``
from the ``*.txt`` and ``*.tmpl`` files from the ``*.txt`` and ``*.tmpl`` files
============ ============================================== ============ ==============================================
@ -38,26 +38,26 @@ Path Purpose
Bootstrapping the compiler Bootstrapping the compiler
========================== ==========================
As of version 0.8.5 the compiler is maintained in Nimrod. (The first versions As of version 0.8.5 the compiler is maintained in Nim. (The first versions
have been implemented in Object Pascal.) The Python-based build system has have been implemented in Object Pascal.) The Python-based build system has
been rewritten in Nimrod too. been rewritten in Nim too.
Compiling the compiler is a simple matter of running:: Compiling the compiler is a simple matter of running::
nimrod c koch.nim nim c koch.nim
./koch boot ./koch boot
For a release version use:: For a release version use::
nimrod c koch.nim nim c koch.nim
./koch boot -d:release ./koch boot -d:release
And for a debug version compatible with GDB:: And for a debug version compatible with GDB::
nimrod c koch.nim nim c koch.nim
./koch boot --debuginfo --linedir:on ./koch boot --debuginfo --linedir:on
The ``koch`` program is Nimrod's maintenance script. It is a replacement for The ``koch`` program is Nim's maintenance script. It is a replacement for
make and shell scripting with the advantage that it is much more portable. make and shell scripting with the advantage that it is much more portable.
More information about its options can be found in the `koch <koch.html>`_ More information about its options can be found in the `koch <koch.html>`_
documentation. documentation.
@ -80,13 +80,13 @@ See also the `API naming design <apis.html>`_ document.
Porting to new platforms Porting to new platforms
======================== ========================
Porting Nimrod to a new architecture is pretty easy, since C is the most Porting Nim to a new architecture is pretty easy, since C is the most
portable programming language (within certain limits) and Nimrod generates portable programming language (within certain limits) and Nim generates
C code, porting the code generator is not necessary. C code, porting the code generator is not necessary.
POSIX-compliant systems on conventional hardware are usually pretty easy to POSIX-compliant systems on conventional hardware are usually pretty easy to
port: Add the platform to ``platform`` (if it is not already listed there), port: Add the platform to ``platform`` (if it is not already listed there),
check that the OS, System modules work and recompile Nimrod. check that the OS, System modules work and recompile Nim.
The only case where things aren't as easy is when the garbage The only case where things aren't as easy is when the garbage
collector needs some assembler tweaking to work. The standard collector needs some assembler tweaking to work. The standard
@ -98,7 +98,7 @@ replace this generic code by some assembler code.
Runtime type information Runtime type information
======================== ========================
*Runtime type information* (RTTI) is needed for several aspects of the Nimrod *Runtime type information* (RTTI) is needed for several aspects of the Nim
programming language: programming language:
Garbage collection Garbage collection
@ -108,7 +108,7 @@ Garbage collection
Complex assignments Complex assignments
Sequences and strings are implemented as Sequences and strings are implemented as
pointers to resizeable buffers, but Nimrod requires copying for pointers to resizeable buffers, but Nim requires copying for
assignments. Apart from RTTI the compiler could generate copy procedures assignments. Apart from RTTI the compiler could generate copy procedures
for any type that needs one. However, this would make the code bigger and for any type that needs one. However, this would make the code bigger and
the RTTI is likely already there for the GC. the RTTI is likely already there for the GC.
@ -121,12 +121,12 @@ Look at the file ``lib/system/hti.nim`` for more information.
The compiler's architecture The compiler's architecture
=========================== ===========================
Nimrod uses the classic compiler architecture: A lexer/scanner feds tokens to a Nim uses the classic compiler architecture: A lexer/scanner feds tokens to a
parser. The parser builds a syntax tree that is used by the code generator. parser. The parser builds a syntax tree that is used by the code generator.
This syntax tree is the interface between the parser and the code generator. This syntax tree is the interface between the parser and the code generator.
It is essential to understand most of the compiler's code. It is essential to understand most of the compiler's code.
In order to compile Nimrod correctly, type-checking has to be separated from In order to compile Nim correctly, type-checking has to be separated from
parsing. Otherwise generics cannot work. parsing. Otherwise generics cannot work.
.. include:: filelist.txt .. include:: filelist.txt
@ -172,7 +172,7 @@ Frontend issues
Methods and type converters Methods and type converters
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
Nimrod contains language features that are *global*. The best example for that Nim contains language features that are *global*. The best example for that
are multi methods: Introducing a new method with the same name and some are multi methods: Introducing a new method with the same name and some
compatible object parameter means that the method's dispatcher needs to take compatible object parameter means that the method's dispatcher needs to take
the new method into account. So the dispatching logic is only completely known the new method into account. So the dispatching logic is only completely known
@ -181,12 +181,12 @@ after the whole program has been translated!
Other features that are *implicitly* triggered cause problems for modularity Other features that are *implicitly* triggered cause problems for modularity
too. Type converters fall into this category: too. Type converters fall into this category:
.. code-block:: nimrod .. code-block:: nim
# module A # module A
converter toBool(x: int): bool = converter toBool(x: int): bool =
result = x != 0 result = x != 0
.. code-block:: nimrod .. code-block:: nim
# module B # module B
import A import A
@ -254,7 +254,7 @@ turned on".
Debugging Nimrod's memory management Debugging Nim's memory management
==================================== ====================================
The following paragraphs are mostly a reminder for myself. Things to keep The following paragraphs are mostly a reminder for myself. Things to keep
@ -262,7 +262,7 @@ in mind:
* Segmentation faults can have multiple reasons: One that is frequently * Segmentation faults can have multiple reasons: One that is frequently
forgotten is that *stack overflow* can trigger one! forgotten is that *stack overflow* can trigger one!
* If an assertion in Nimrod's memory manager or GC fails, the stack trace * If an assertion in Nim's memory manager or GC fails, the stack trace
keeps allocating memory! Thus a stack overflow may happen, hiding the keeps allocating memory! Thus a stack overflow may happen, hiding the
real issue. real issue.
* What seem to be C code generation problems is often a bug resulting from * What seem to be C code generation problems is often a bug resulting from
@ -300,7 +300,7 @@ set of pointers - this is called a ``TCellSet`` in the source code.
Inserting, deleting and searching are done in constant time. However, Inserting, deleting and searching are done in constant time. However,
modifying a ``TCellSet`` during traversation leads to undefined behaviour. modifying a ``TCellSet`` during traversation leads to undefined behaviour.
.. code-block:: Nimrod .. code-block:: Nim
type type
TCellSet # hidden TCellSet # hidden
@ -340,11 +340,11 @@ Complete traversal is done in this way::
Further complications Further complications
--------------------- ---------------------
In Nimrod the compiler cannot always know if a reference In Nim the compiler cannot always know if a reference
is stored on the stack or not. This is caused by var parameters. is stored on the stack or not. This is caused by var parameters.
Consider this example: Consider this example:
.. code-block:: Nimrod .. code-block:: Nim
proc setRef(r: var ref TNode) = proc setRef(r: var ref TNode) =
new(r) new(r)
@ -380,7 +380,7 @@ Code generation for closures is implemented by `lambda lifting`:idx:.
Design Design
------ ------
A ``closure`` proc var can call ordinary procs of the default Nimrod calling A ``closure`` proc var can call ordinary procs of the default Nim calling
convention. But not the other way round! A closure is implemented as a convention. But not the other way round! A closure is implemented as a
``tuple[prc, env]``. ``env`` can be nil implying a call without a closure. ``tuple[prc, env]``. ``env`` can be nil implying a call without a closure.
This means that a call through a closure generates an ``if`` but the This means that a call through a closure generates an ``if`` but the
@ -393,7 +393,7 @@ Tests with GCC on Amd64 showed that it's really beneficical if the
Proper thunk generation is harder because the proc that is to wrap Proper thunk generation is harder because the proc that is to wrap
could stem from a complex expression: could stem from a complex expression:
.. code-block:: nimrod .. code-block:: nim
receivesClosure(returnsDefaultCC[i]) receivesClosure(returnsDefaultCC[i])
A thunk would need to call 'returnsDefaultCC[i]' somehow and that would require A thunk would need to call 'returnsDefaultCC[i]' somehow and that would require
@ -405,7 +405,7 @@ to pass a proc pointer around via a generic ``ref`` type.
Example code: Example code:
.. code-block:: nimrod .. code-block:: nim
proc add(x: int): proc (y: int): int {.closure.} = proc add(x: int): proc (y: int): int {.closure.} =
return proc (y: int): int = return proc (y: int): int =
return x + y return x + y
@ -415,7 +415,7 @@ Example code:
This should produce roughly this code: This should produce roughly this code:
.. code-block:: nimrod .. code-block:: nim
type type
PEnv = ref object PEnv = ref object
x: int # data x: int # data
@ -436,7 +436,7 @@ This should produce roughly this code:
Beware of nesting: Beware of nesting:
.. code-block:: nimrod .. code-block:: nim
proc add(x: int): proc (y: int): proc (z: int): int {.closure.} {.closure.} = proc add(x: int): proc (y: int): proc (z: int): int {.closure.} {.closure.} =
return lamba (y: int): proc (z: int): int {.closure.} = return lamba (y: int): proc (z: int): int {.closure.} =
return lambda (z: int): int = return lambda (z: int): int =
@ -447,7 +447,7 @@ Beware of nesting:
This should produce roughly this code: This should produce roughly this code:
.. code-block:: nimrod .. code-block:: nim
type type
PEnvX = ref object PEnvX = ref object
x: int # data x: int # data
@ -492,7 +492,7 @@ environments. This is however not always possible.
Accumulator Accumulator
----------- -----------
.. code-block:: nimrod .. code-block:: nim
proc GetAccumulator(start: int): proc (): int {.closure} = proc GetAccumulator(start: int): proc (): int {.closure} =
var i = start var i = start
return lambda: int = return lambda: int =

View file

@ -1,8 +1,8 @@
=============================== ===============================
Nimrod maintenance script Nim maintenance script
=============================== ===============================
:Version: |nimrodversion| :Version: |nimversion|
.. contents:: .. contents::
@ -15,10 +15,10 @@
Introduction Introduction
============ ============
The `koch`:idx: program is Nimrod's maintenance script. It is a replacement The `koch`:idx: program is Nim's maintenance script. It is a replacement
for make and shell scripting with the advantage that it is much more portable. for make and shell scripting with the advantage that it is much more portable.
The word *koch* means *cook* in German. ``koch`` is used mainly to build the The word *koch* means *cook* in German. ``koch`` is used mainly to build the
Nimrod compiler, but it can also be used for other tasks. This document Nim compiler, but it can also be used for other tasks. This document
describes the supported commands and their options. describes the supported commands and their options.
@ -40,21 +40,21 @@ options:
option is not supported on Windows. option is not supported on Windows.
-d:useGnuReadline -d:useGnuReadline
Includes the `rdstdin module <rdstdin.html>`_ for `interactive Includes the `rdstdin module <rdstdin.html>`_ for `interactive
mode <nimrodc.html#nimrod-interactive-mode>`_ (aka ``nimrod i``). mode <nimc.html#nim-interactive-mode>`_ (aka ``nim i``).
This is not needed on Windows. On other platforms this may This is not needed on Windows. On other platforms this may
incorporate the GNU readline library. incorporate the GNU readline library.
-d:nativeStacktrace -d:nativeStacktrace
Use native stack traces (only for Mac OS X or Linux). Use native stack traces (only for Mac OS X or Linux).
-d:noCaas -d:noCaas
Builds Nimrod without compiler as a service (CAAS) support. CAAS Builds Nim without compiler as a service (CAAS) support. CAAS
support is required for functionality like Nimrod's `idetool support is required for functionality like Nim's `idetool
<idetools.html>`_ command used to integrate the compiler with <idetools.html>`_ command used to integrate the compiler with
`external IDEs <https://github.com/Araq/Nimrod/wiki/Editor-Support>`_. `external IDEs <https://github.com/Araq/Nim/wiki/Editor-Support>`_.
-d:avoidTimeMachine -d:avoidTimeMachine
Only for Mac OS X, activating this switch will force excluding Only for Mac OS X, activating this switch will force excluding
the generated ``nimcache`` directories from Time Machine backups. the generated ``nimcache`` directories from Time Machine backups.
By default ``nimcache`` directories will be included in backups, By default ``nimcache`` directories will be included in backups,
and just for the Nimrod compiler itself it means backing up 20MB and just for the Nim compiler itself it means backing up 20MB
of generated files each time you update the compiler. Using this of generated files each time you update the compiler. Using this
option will make the compiler invoke the `tmutil option will make the compiler invoke the `tmutil
<https://developer.apple.com/library/mac/documentation/Darwin/Reference/Manpages/man8/tmutil.8.html>`_ <https://developer.apple.com/library/mac/documentation/Darwin/Reference/Manpages/man8/tmutil.8.html>`_
@ -66,18 +66,18 @@ options:
$ find . -type d -name nimcache -exec tmutil isexcluded \{\} \; $ find . -type d -name nimcache -exec tmutil isexcluded \{\} \;
-d:useFFI -d:useFFI
Nimrod code can use the `foreign function interface (FFI) Nim code can use the `foreign function interface (FFI)
<manual.html#foreign-function-interface>`_ at runtime, but macros <manual.html#foreign-function-interface>`_ at runtime, but macros
are limited to pure Nimrod code at compilation time. Enabling are limited to pure Nim code at compilation time. Enabling
this switch will allow macros to execute non-nimrod code at this switch will allow macros to execute non-nim code at
compilation time (eg. open a file and write to it). compilation time (eg. open a file and write to it).
--gc:refc|v2|markAndSweep|boehm|none --gc:refc|v2|markAndSweep|boehm|none
Selects which garbage collection strategy to use for the compiler Selects which garbage collection strategy to use for the compiler
and generated code. See the `Nimrod's Garbage Collector <gc.html>`_ and generated code. See the `Nim's Garbage Collector <gc.html>`_
documentation for more information. documentation for more information.
After compilation is finished you will hopefully end up with the nimrod After compilation is finished you will hopefully end up with the nim
compiler in the ``bin`` directory. You can add Nimrod's ``bin`` directory to compiler in the ``bin`` directory. You can add Nim's ``bin`` directory to
your ``$PATH`` or use the `install command`_ to place it where it will be your ``$PATH`` or use the `install command`_ to place it where it will be
found. found.
@ -101,7 +101,7 @@ The `inno`:idx: command builds the `Inno Setup installer for Windows
install command install command
--------------- ---------------
The `install`:idx: command installs Nimrod to the specified directory, which The `install`:idx: command installs Nim to the specified directory, which
is required as a parameter. For example, on Unix platforms you could run:: is required as a parameter. For example, on Unix platforms you could run::
$ ./koch install /usr/local/bin $ ./koch install /usr/local/bin
@ -109,8 +109,8 @@ is required as a parameter. For example, on Unix platforms you could run::
temp command temp command
------------ ------------
The temp command builds the Nimrod compiler but with a different final name The temp command builds the Nim compiler but with a different final name
(``nimrod_temp``), so it doesn't overwrite your normal compiler. You can use (``nim_temp``), so it doesn't overwrite your normal compiler. You can use
this command to test different options, the same you would issue for the `boot this command to test different options, the same you would issue for the `boot
command`_. command`_.
@ -119,14 +119,14 @@ test command
The `test`:idx: command can also be invoked with the alias ``tests``. This The `test`:idx: command can also be invoked with the alias ``tests``. This
command will compile and run ``tests/testament/tester.nim``, which is the main command will compile and run ``tests/testament/tester.nim``, which is the main
driver of Nimrod's test suite. You can pass options to the ``test`` command, driver of Nim's test suite. You can pass options to the ``test`` command,
they will be forwarded to the tester. See its source code for available they will be forwarded to the tester. See its source code for available
options. options.
update command update command
-------------- --------------
The `update`:idx: command updates nimrod to the latest version from github. The `update`:idx: command updates nim to the latest version from github.
For this command to work you need to have compiled ``koch`` itself with the For this command to work you need to have compiled ``koch`` itself with the
``-d:withUpdate`` switch. ``-d:withUpdate`` switch.
@ -136,7 +136,7 @@ web command
The `web`:idx: command converts the documentation in the ``doc`` directory The `web`:idx: command converts the documentation in the ``doc`` directory
from rst to HTML. It also repeats the same operation but places the result in from rst to HTML. It also repeats the same operation but places the result in
the ``web/upload`` which can be used to update the website at the ``web/upload`` which can be used to update the website at
http://nimrod-lang.org. http://nim-lang.org.
zip command zip command
----------- -----------

View file

@ -10,7 +10,7 @@ Nimgrep is a command line tool for search&replace tasks. It can search for
regex or peg patterns and can search whole directories at once. User regex or peg patterns and can search whole directories at once. User
confirmation for every single replace operation can be requested. confirmation for every single replace operation can be requested.
Nimgrep has particularly good support for Nimrod's Nimgrep has particularly good support for Nim's
eccentric *style insensitivity*. Apart from that it is a generic text eccentric *style insensitivity*. Apart from that it is a generic text
manipulation tool. manipulation tool.
@ -20,7 +20,7 @@ Installation
Compile nimgrep with the command:: Compile nimgrep with the command::
nimrod c -d:release tools/nimgrep.nim nim c -d:release tools/nimgrep.nim
And copy the executable somewhere in your ``$PATH``. And copy the executable somewhere in your ``$PATH``.

View file

@ -3,14 +3,14 @@
========================= =========================
:Author: Andreas Rumpf :Author: Andreas Rumpf
:Version: |nimrodversion| :Version: |nimversion|
.. contents:: .. contents::
Introduction Introduction
============ ============
niminst is a tool to generate an installer for a Nimrod program. Currently niminst is a tool to generate an installer for a Nim program. Currently
it can create an installer for Windows it can create an installer for Windows
via `Inno Setup <http://www.jrsoftware.org/isinfo.php>`_ as well as via `Inno Setup <http://www.jrsoftware.org/isinfo.php>`_ as well as
installation/deinstallation scripts for UNIX. Later versions will support installation/deinstallation scripts for UNIX. Later versions will support
@ -24,7 +24,7 @@ systems.
Configuration file Configuration file
================== ==================
niminst uses the Nimrod `parsecfg <parsecfg.html>`_ module to parse the niminst uses the Nim `parsecfg <parsecfg.html>`_ module to parse the
configuration file. Here's an example of how the syntax looks like: configuration file. Here's an example of how the syntax looks like:
.. include:: doc/mytest.cfg .. include:: doc/mytest.cfg
@ -187,9 +187,9 @@ Key description
Real world example Real world example
================== ==================
The installers for the Nimrod compiler itself are generated by niminst. Have a The installers for the Nim compiler itself are generated by niminst. Have a
look at its configuration file: look at its configuration file:
.. include:: compiler/nimrod.ini .. include:: compiler/nim.ini
:literal: :literal:

View file

@ -1,9 +1,9 @@
============================= =============================
Nimrod Documentation Overview Nim Documentation Overview
============================= =============================
:Author: Andreas Rumpf :Author: Andreas Rumpf
:Version: |nimrodversion| :Version: |nimversion|
.. include:: ../doc/docs.txt .. include:: ../doc/docs.txt

View file

@ -171,7 +171,7 @@ The PEG parser implements this grammar (written in PEG syntax)::
expression, identifiers are not interpreted as non-terminals, but are expression, identifiers are not interpreted as non-terminals, but are
interpreted as verbatim string: interpreted as verbatim string:
.. code-block:: nimrod .. code-block:: nim
abc =~ peg"abc" # is true abc =~ peg"abc" # is true
So it is not necessary to write ``peg" 'abc' "`` in the above example. So it is not necessary to write ``peg" 'abc' "`` in the above example.
@ -182,17 +182,17 @@ Examples
Check if `s` matches Nim's "while" keyword: Check if `s` matches Nim's "while" keyword:
.. code-block:: nimrod .. code-block:: nim
s =~ peg" y'while'" s =~ peg" y'while'"
Exchange (key, val)-pairs: Exchange (key, val)-pairs:
.. code-block:: nimrod .. code-block:: nim
"key: val; key2: val2".replace(peg"{\ident} \s* ':' \s* {\ident}", "$2: $1") "key: val; key2: val2".replace(peg"{\ident} \s* ':' \s* {\ident}", "$2: $1")
Determine the ``#include``'ed files of a C file: Determine the ``#include``'ed files of a C file:
.. code-block:: nimrod .. code-block:: nim
for line in lines("myfile.c"): for line in lines("myfile.c"):
if line =~ peg"""s <- ws '#include' ws '"' {[^"]+} '"' ws if line =~ peg"""s <- ws '#include' ws '"' {[^"]+} '"' ws
comment <- '/*' @ '*/' / '//' .* comment <- '/*' @ '*/' / '//' .*

View file

@ -1,7 +1,7 @@
============================ ============================
Nimrod's documenation system Nim's documenation system
============================ ============================
This folder contains Nimrod's documentation. The documentation This folder contains Nim's documentation. The documentation
is written in a format called *reStructuredText*, a markup language that reads is written in a format called *reStructuredText*, a markup language that reads
like ASCII and can be converted to HTML automatically! like ASCII and can be converted to HTML automatically!

View file

@ -44,9 +44,9 @@ As the regular expressions supported by this module are enormous,
the reader is referred to http://perldoc.perl.org/perlre.html for the the reader is referred to http://perldoc.perl.org/perlre.html for the
full documentation of Perl's regular expressions. full documentation of Perl's regular expressions.
Because the backslash ``\`` is a meta character both in the Nimrod Because the backslash ``\`` is a meta character both in the Nim
programming language and in regular expressions, it is strongly programming language and in regular expressions, it is strongly
recommended that one uses the *raw* strings of Nimrod, so that recommended that one uses the *raw* strings of Nim, so that
backslashes are interpreted by the regular expression engine:: backslashes are interpreted by the regular expression engine::
r"\S" # matches any character that is not whitespace r"\S" # matches any character that is not whitespace

View file

@ -1,9 +1,9 @@
=========================================================================== ===========================================================================
Nimrod's implementation of |rst| Nim's implementation of |rst|
=========================================================================== ===========================================================================
:Author: Andreas Rumpf :Author: Andreas Rumpf
:Version: |nimrodversion| :Version: |nimversion|
.. contents:: .. contents::
@ -11,15 +11,15 @@ Introduction
============ ============
This document describes the subset of `Docutils`_' `reStructuredText`_ as it This document describes the subset of `Docutils`_' `reStructuredText`_ as it
has been implemented in the Nimrod compiler for generating documentation. has been implemented in the Nim compiler for generating documentation.
Elements of |rst| that are not listed here have not been implemented. Elements of |rst| that are not listed here have not been implemented.
Unfortunately, the specification of |rst| is quite vague, so Nimrod is not as Unfortunately, the specification of |rst| is quite vague, so Nim is not as
compatible to the original implementation as one would like. compatible to the original implementation as one would like.
Even though Nimrod's |rst| parser does not parse all constructs, it is pretty Even though Nim's |rst| parser does not parse all constructs, it is pretty
usable. The missing features can easily be circumvented. An indication of this usable. The missing features can easily be circumvented. An indication of this
fact is that Nimrod's *whole* documentation itself (including this document) is fact is that Nim's *whole* documentation itself (including this document) is
processed by Nimrod's |rst| parser. (Which is an order of magnitude faster than processed by Nim's |rst| parser. (Which is an order of magnitude faster than
Docutils' parser.) Docutils' parser.)
@ -65,19 +65,19 @@ Definition lists
Save this code to the file "greeting.nim". Now compile and run it: Save this code to the file "greeting.nim". Now compile and run it:
``nimrod run greeting.nim`` ``nim run greeting.nim``
As you see, with the ``run`` command Nimrod executes the file automatically As you see, with the ``run`` command Nim executes the file automatically
after compilation. You can even give your program command line arguments by after compilation. You can even give your program command line arguments by
appending them after the filename that is to be compiled and run: appending them after the filename that is to be compiled and run:
``nimrod run greeting.nim arg1 arg2`` ``nim run greeting.nim arg1 arg2``
Tables Tables
====== ======
Nimrod only implements simple tables of the form:: Nim only implements simple tables of the form::
================== =============== =================== ================== =============== ===================
header 1 header 2 header n header 1 header 2 header n

View file

@ -6,7 +6,7 @@ Sets can be constructed via the set constructor: ``{}`` is the empty set. The
empty set is type compatible with any concrete set type. The constructor empty set is type compatible with any concrete set type. The constructor
can also be used to include elements (and ranges of elements): can also be used to include elements (and ranges of elements):
.. code-block:: nimrod .. code-block:: nim
type type
TCharSet = set[char] TCharSet = set[char]
var var

View file

@ -2,7 +2,7 @@
Parallel & Spawn Parallel & Spawn
========================================================== ==========================================================
Nimrod has two flavors of parallelism: Nim has two flavors of parallelism:
1) `Structured`:idx parallelism via the ``parallel`` statement. 1) `Structured`:idx parallelism via the ``parallel`` statement.
2) `Unstructured`:idx: parallelism via the standalone ``spawn`` statement. 2) `Unstructured`:idx: parallelism via the standalone ``spawn`` statement.
@ -24,7 +24,7 @@ Parallel statement
Example: Example:
.. code-block:: nimrod .. code-block:: nim
# Compute PI in an inefficient way # Compute PI in an inefficient way
import strutils, math, threadpool import strutils, math, threadpool
@ -42,7 +42,7 @@ Example:
The parallel statement is the preferred mechanism to introduce parallelism The parallel statement is the preferred mechanism to introduce parallelism
in a Nimrod program. A subset of the Nimrod language is valid within a in a Nim program. A subset of the Nim language is valid within a
``parallel`` section. This subset is checked to be free of data races at ``parallel`` section. This subset is checked to be free of data races at
compile time. A sophisticated `disjoint checker`:idx: ensures that no data compile time. A sophisticated `disjoint checker`:idx: ensures that no data
races are possible even though shared memory is extensively supported! races are possible even though shared memory is extensively supported!
@ -77,7 +77,7 @@ the passed expression on the thread pool and returns a `data flow variable`:idx:
**blocking**. However, one can use ``awaitAny`` to wait on multiple flow **blocking**. However, one can use ``awaitAny`` to wait on multiple flow
variables at the same time: variables at the same time:
.. code-block:: nimrod .. code-block:: nim
import threadpool, ... import threadpool, ...
# wait until 2 out of 3 servers received the update: # wait until 2 out of 3 servers received the update:

View file

@ -45,7 +45,7 @@ Notation meaning
Examples Examples
======== ========
.. code-block:: nimrod .. code-block:: nim
subex"$1($', '{2..})" % ["f", "a", "b", "c"] == "f(a, b, c)" subex"$1($', '{2..})" % ["f", "a", "b", "c"] == "f(a, b, c)"

View file

@ -1,20 +1,20 @@
=========================== ===========================
Tools available with Nimrod Tools available with Nim
=========================== ===========================
The standard distribution ships with the following tools: The standard distribution ships with the following tools:
- | `Nimrod Installation Generator <niminst.html>`_ - | `Nim Installation Generator <niminst.html>`_
| How to generate a nice installer for your Nimrod program. | How to generate a nice installer for your Nim program.
- | `C2nim <c2nim.html>`_ - | `C2nim <c2nim.html>`_
| C to Nimrod source converter. Translates C header files to Nimrod. | C to Nim source converter. Translates C header files to Nim.
- | `nimgrep <nimgrep.html>`_ - | `nimgrep <nimgrep.html>`_
| Nimrod search and replace utility. | Nim search and replace utility.
- | `endb <endb.html>`_ - | `endb <endb.html>`_
| Nimrod's slow platform independent embedded debugger. | Nim's slow platform independent embedded debugger.
- | `estp <estp.html>`_ - | `estp <estp.html>`_
| Nimrod's slow platform independent embedded stack trace profiler. | Nim's slow platform independent embedded stack trace profiler.

View file

@ -858,7 +858,7 @@ The good news is not much has changed! First, we need to change the handling of
the input parameter. In the dynamic version the ``readCfgAtRuntime`` proc the input parameter. In the dynamic version the ``readCfgAtRuntime`` proc
receives a string parameter. However, in the macro version it is also declared receives a string parameter. However, in the macro version it is also declared
as string, but this is the *outside* interface of the macro. When the macro is as string, but this is the *outside* interface of the macro. When the macro is
run, it actually gets a ``PNimrodNode`` object instead of a string, and we have run, it actually gets a ``PNimNode`` object instead of a string, and we have
to call the ``strVal`` proc from the `macros module <macros.html>`_ to obtain to call the ``strVal`` proc from the `macros module <macros.html>`_ to obtain
the string being passed in to the macro. the string being passed in to the macro.

View file

@ -1,15 +1,15 @@
# Nimrod Compiler # Nim Compiler
This repo contains the Nimrod compiler, Nimrod's stdlib, tools and This repo contains the Nim compiler, Nim's stdlib, tools and
documentation. documentation.
## Compiling ## Compiling
Compiling the Nimrod compiler is quite straightforward. Because Compiling the Nim compiler is quite straightforward. Because
the Nimrod compiler itself is written in the Nimrod programming language the Nim compiler itself is written in the Nim programming language
the C source of an older version of the compiler are needed to bootstrap the the C source of an older version of the compiler are needed to bootstrap the
latest version. The C sources are available in a separate repo [here](http://github.com/nimrod-code/csources). latest version. The C sources are available in a separate repo [here](http://github.com/nim-code/csources).
Pre-compiled snapshots of the compiler are also available on Pre-compiled snapshots of the compiler are also available on
[Nimbuild](http://build.nimrod-lang.org/). Your platform however may not [Nimbuild](http://build.nim-lang.org/). Your platform however may not
currently be built for. currently be built for.
The compiler currently supports the following platform and architecture The compiler currently supports the following platform and architecture
@ -30,16 +30,16 @@ To build from source you will need:
If you are on a fairly modern *nix system, the following steps should work: If you are on a fairly modern *nix system, the following steps should work:
``` ```
$ git clone git://github.com/Araq/Nimrod.git $ git clone git://github.com/Araq/Nim.git
$ cd Nimrod $ cd Nim
$ git clone --depth 1 git://github.com/nimrod-code/csources $ git clone --depth 1 git://github.com/nim-code/csources
$ cd csources && sh build.sh $ cd csources && sh build.sh
$ cd .. $ cd ..
$ bin/nimrod c koch $ bin/nim c koch
$ ./koch boot -d:release $ ./koch boot -d:release
``` ```
``koch install [dir]`` may then be used to install Nimrod, or you can simply ``koch install [dir]`` may then be used to install Nim, or you can simply
add it to your PATH. More ``koch`` related options are documented in add it to your PATH. More ``koch`` related options are documented in
[doc/koch.txt](doc/koch.txt). [doc/koch.txt](doc/koch.txt).
@ -48,16 +48,16 @@ The above steps can be performed on Windows in a similar fashion, the
instead of ``build.sh``. instead of ``build.sh``.
## Getting help ## Getting help
A [forum](http://forum.nimrod-lang.org/) is available if you have any A [forum](http://forum.nim-lang.org/) is available if you have any
questions, and you can also get help in the IRC channel on questions, and you can also get help in the IRC channel on
[Freenode](irc://irc.freenode.net/nimrod) in #nimrod. If you ask questions on [Freenode](irc://irc.freenode.net/nim) in #nim. If you ask questions on
[StackOverflow use the nimrod [StackOverflow use the nim
tag](http://stackoverflow.com/questions/tagged/nimrod). tag](http://stackoverflow.com/questions/tagged/nim).
## License ## License
The compiler and the standard library are licensed under the MIT license, The compiler and the standard library are licensed under the MIT license,
except for some modules where the documentation suggests otherwise. This means except for some modules where the documentation suggests otherwise. This means
that you can use any license for your own programs developed with Nimrod, that you can use any license for your own programs developed with Nim,
allowing you to create commercial applications. allowing you to create commercial applications.
Read copying.txt for more details. Read copying.txt for more details.

View file

@ -1,15 +1,15 @@
# Nimrod Compiler # Nim Compiler
This repo contains the Nimrod compiler, Nimrod's stdlib, tools and This repo contains the Nim compiler, Nim's stdlib, tools and
documentation. documentation.
## Compiling ## Compiling
Compiling the Nimrod compiler is quite straightforward. Because Compiling the Nim compiler is quite straightforward. Because
the Nimrod compiler itself is written in the Nimrod programming language the Nim compiler itself is written in the Nim programming language
the C source of an older version of the compiler are needed to bootstrap the the C source of an older version of the compiler are needed to bootstrap the
latest version. The C sources are available in a separate repo [here](http://github.com/nimrod-code/csources). latest version. The C sources are available in a separate repo [here](http://github.com/nim-code/csources).
Pre-compiled snapshots of the compiler are also available on Pre-compiled snapshots of the compiler are also available on
[Nimbuild](http://build.nimrod-lang.org/). Your platform however may not [Nimbuild](http://build.nim-lang.org/). Your platform however may not
currently be built for. currently be built for.
The compiler currently supports the following platform and architecture The compiler currently supports the following platform and architecture
@ -30,16 +30,16 @@ To build from source you will need:
If you are on a fairly modern *nix system, the following steps should work: If you are on a fairly modern *nix system, the following steps should work:
``` ```
$ git clone git://github.com/Araq/Nimrod.git $ git clone git://github.com/Araq/Nim.git
$ cd Nimrod $ cd Nim
$ git clone --depth 1 git://github.com/nimrod-code/csources $ git clone --depth 1 git://github.com/nim-code/csources
$ cd csources && ./build.sh $ cd csources && ./build.sh
$ cd .. $ cd ..
$ bin/nimrod c koch $ bin/nim c koch
$ ./koch boot -d:release $ ./koch boot -d:release
``` ```
``koch install [dir]`` may then be used to install Nimrod, or you can simply ``koch install [dir]`` may then be used to install Nim, or you can simply
add it to your PATH. More ``koch`` related options are documented in add it to your PATH. More ``koch`` related options are documented in
[doc/koch.txt](doc/koch.txt). [doc/koch.txt](doc/koch.txt).
@ -48,16 +48,16 @@ The above steps can be performed on Windows in a similar fashion, the
instead of ``build.sh``. instead of ``build.sh``.
## Getting help ## Getting help
A [forum](http://forum.nimrod-lang.org/) is available if you have any A [forum](http://forum.nim-lang.org/) is available if you have any
questions, and you can also get help in the IRC channel on questions, and you can also get help in the IRC channel on
[Freenode](irc://irc.freenode.net/nimrod) in #nimrod. If you ask questions on [Freenode](irc://irc.freenode.net/nim) in #nim. If you ask questions on
[StackOverflow use the nimrod [StackOverflow use the nim
tag](http://stackoverflow.com/questions/tagged/nimrod). tag](http://stackoverflow.com/questions/tagged/nim).
## License ## License
The compiler and the standard library are licensed under the MIT license, The compiler and the standard library are licensed under the MIT license,
except for some modules where the documentation suggests otherwise. This means except for some modules where the documentation suggests otherwise. This means
that you can use any license for your own programs developed with Nimrod, that you can use any license for your own programs developed with Nim,
allowing you to create commercial applications. allowing you to create commercial applications.
Read copying.txt for more details. Read copying.txt for more details.