diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/advopt.txt | 11 | ||||
| -rw-r--r-- | doc/apis.txt | 2 | ||||
| -rw-r--r-- | doc/astspec.txt | 112 | ||||
| -rw-r--r-- | doc/backends.txt | 162 | ||||
| -rw-r--r-- | doc/basicopt.txt | 6 | ||||
| -rw-r--r-- | doc/docgen.txt | 60 | ||||
| -rw-r--r-- | doc/docs.txt | 14 | ||||
| -rw-r--r-- | doc/effects.txt | 4 | ||||
| -rw-r--r-- | doc/endb.txt | 20 | ||||
| -rw-r--r-- | doc/estp.txt | 20 | ||||
| -rw-r--r-- | doc/exception_hierarchy_fragment.txt | 59 | ||||
| -rw-r--r-- | doc/filelist.txt | 10 | ||||
| -rw-r--r-- | doc/filters.txt | 14 | ||||
| -rw-r--r-- | doc/gc.txt | 10 | ||||
| -rw-r--r-- | doc/idetools.txt | 60 | ||||
| -rw-r--r-- | doc/intern.txt | 72 | ||||
| -rw-r--r-- | doc/koch.txt | 42 | ||||
| -rw-r--r-- | doc/lib.txt | 60 | ||||
| -rw-r--r-- | doc/manual.txt | 704 | ||||
| -rw-r--r-- | doc/nimc.txt (renamed from doc/nimrodc.txt) | 192 | ||||
| -rw-r--r-- | doc/nimgrep.txt | 4 | ||||
| -rw-r--r-- | doc/niminst.txt | 10 | ||||
| -rw-r--r-- | doc/overview.txt | 4 | ||||
| -rw-r--r-- | doc/pegdocs.txt | 12 | ||||
| -rw-r--r-- | doc/readme.txt | 4 | ||||
| -rw-r--r-- | doc/regexprs.txt | 4 | ||||
| -rw-r--r-- | doc/rst.txt | 22 | ||||
| -rw-r--r-- | doc/sets_fragment.txt | 2 | ||||
| -rw-r--r-- | doc/spawn.txt | 8 | ||||
| -rw-r--r-- | doc/subexes.txt | 2 | ||||
| -rw-r--r-- | doc/tools.txt | 18 | ||||
| -rw-r--r-- | doc/tut1.txt | 301 | ||||
| -rw-r--r-- | doc/tut2.txt | 141 |
33 files changed, 1055 insertions, 1111 deletions
diff --git a/doc/advopt.txt b/doc/advopt.txt index 7a11e9041..2ddba12e8 100644 --- a/doc/advopt.txt +++ b/doc/advopt.txt @@ -12,7 +12,6 @@ Advanced commands: module dependency graph //dump dump all defined conditionals and search paths //check checks the project for syntax and semantic - //pretty homogenizes source code style //idetools compiler support for IDEs: possible options: --track:FILE,LINE,COL track a file/cursor position --trackDirty:DIRTY_FILE,ORIG_FILE,LINE,COL @@ -28,7 +27,6 @@ Advanced commands: --server.address:HOST binds to that address, by default "" Advanced options: - -m, --mainmodule:FILE set the project main module -o, --out:FILE set the output filename --stdout output to stdout --listFullPaths list full paths in messages @@ -50,7 +48,7 @@ Advanced options: --os:SYMBOL set the target operating system (cross-compilation) --cpu:SYMBOL set the target processor (cross-compilation) --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 -l, --passL:OPTION pass an option to the linker --cincludes:DIR modify the C compiler header search path @@ -58,7 +56,7 @@ Advanced options: --clib:LIBNAME link an additional C library (you should omit platform-specific extensions) --genMapping generate a mapping file containing - (Nimrod, mangled) identifier pairs + (Nim, mangled) identifier pairs --project document the whole project (doc2) --docSeeSrcUrl:url activate 'see source' for doc and doc2 commands (see doc.item.seesrc in config/nimdoc.cfg) @@ -79,7 +77,8 @@ Advanced options: select the GC to use; default is 'refc' --index:on|off turn index file generation on|off --putenv:key=value set an environment variable - --babelPath:PATH add a path for Babel support + --NimblePath:PATH add a path for Nimble support + --noNimblePath deactivate the Nimble path --excludePath:PATH exclude a path from the list of search paths --dynlibOverride:SYMBOL marks SYMBOL so that dynlib:SYMBOL has no effect and can be statically linked instead; @@ -89,7 +88,7 @@ Advanced options: --listCmd list the commands used to execute external programs --parallelBuild=0|1|... perform a parallel build 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); do not use! this setting affects the whole language -v, --version show detailed version information diff --git a/doc/apis.txt b/doc/apis.txt index 9906f6bbc..e0510d85f 100644 --- a/doc/apis.txt +++ b/doc/apis.txt @@ -84,5 +84,5 @@ indentation indent 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. diff --git a/doc/astspec.txt b/doc/astspec.txt index 6b6242614..5c4274093 100644 --- a/doc/astspec.txt +++ b/doc/astspec.txt @@ -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 children. Each node has a field named ``kind`` which describes what the node contains: -.. code-block:: nimrod +.. code-block:: nim type TNimrodNodeKind = enum ## kind of a node; only explanatory @@ -39,7 +39,7 @@ contains: For the ``PNimrodNode`` type, the ``[]`` operator has been overloaded: ``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(field=value)`` is used. @@ -53,7 +53,7 @@ A leaf of the AST often corresponds to a terminal symbol in the concrete syntax. ----------------- --------------------------------------------- -Nimrod expression corresponding AST +Nim expression corresponding AST ----------------- --------------------------------------------- ``42`` ``nnkIntLit(intVal = 42)`` ``42'i8`` ``nnkInt8Lit(intVal = 42)`` @@ -87,12 +87,12 @@ Command call Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim echo "abc", "xyz" AST: -.. code-block:: nimrod +.. code-block:: nim nnkCommand(nnkIdent(!"echo"), nnkStrLit("abc"), nnkStrLit("xyz")) @@ -101,12 +101,12 @@ Call with ``()`` Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim echo("abc", "xyz") AST: -.. code-block:: nimrod +.. code-block:: nim nnkCall(nnkIdent(!"echo"), nnkStrLit("abc"), nnkStrLit("xyz")) @@ -115,12 +115,12 @@ Infix operator call Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim "abc" & "xyz" AST: -.. code-block:: nimrod +.. code-block:: nim nnkInfix(nnkIdent(!"&"), nnkStrLit("abc"), nnkStrLit("xyz")) @@ -129,29 +129,29 @@ Prefix operator call Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim ? "xyz" AST: -.. code-block:: nimrod +.. code-block:: nim nnkPrefix(nnkIdent(!"?"), nnkStrLit("abc")) 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* ``*``: Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim identifier* AST: -.. code-block:: nimrod +.. code-block:: nim nnkPostfix(nnkIdent(!"*"), nnkIdent(!"identifier")) @@ -160,12 +160,12 @@ Call with named arguments Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim writeln(file=stdout, "hallo") AST: -.. code-block:: nimrod +.. code-block:: nim nnkCall(nnkIdent(!"writeln"), nnkExprEqExpr(nnkIdent(!"file"), nnkIdent(!"stdout")), nnkStrLit("hallo")) @@ -176,12 +176,12 @@ Dereference operator ``^`` Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim x^ AST: -.. code-block:: nimrod +.. code-block:: nim nnkDerefExpr(nnkIdent(!"x")) @@ -190,12 +190,12 @@ Addr operator Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim addr(x) AST: -.. code-block:: nimrod +.. code-block:: nim nnkAddr(nnkIdent(!"x")) @@ -204,12 +204,12 @@ Cast operator Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim cast[T](x) AST: -.. code-block:: nimrod +.. code-block:: nim nnkCast(nnkIdent(!"T"), nnkIdent(!"x")) @@ -218,12 +218,12 @@ Object access operator ``.`` Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim x.y AST: -.. code-block:: nimrod +.. code-block:: nim nnkDotExpr(nnkIdent(!"x"), nnkIdent(!"y")) @@ -232,12 +232,12 @@ Array access operator ``[]`` Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim x[y] AST: -.. code-block:: nimrod +.. code-block:: nim nnkBracketExpr(nnkIdent(!"x"), nnkIdent(!"y")) @@ -249,12 +249,12 @@ are built with the ``nnkPar`` node. Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim (1, 2, (3)) AST: -.. code-block:: nimrod +.. code-block:: nim nnkPar(nnkIntLit(1), nnkIntLit(2), nnkPar(nnkIntLit(3))) @@ -265,12 +265,12 @@ Curly braces are used as the set constructor. Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim {1, 2, 3} AST: -.. code-block:: nimrod +.. code-block:: nim nnkCurly(nnkIntLit(1), nnkIntLit(2), nnkIntLit(3)) @@ -281,12 +281,12 @@ Brackets are used as the array constructor. Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim [1, 2, 3] AST: -.. code-block:: nimrod +.. code-block:: nim nnkBracket(nnkIntLit(1), nnkIntLit(2), nnkIntLit(3)) @@ -297,12 +297,12 @@ Ranges occur in set constructors, case statement branches or array slices. Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim 1..3 AST: -.. code-block:: nimrod +.. code-block:: nim nnkRange(nnkIntLit(1), nnkIntLit(3)) @@ -313,12 +313,12 @@ The representation of the if expression is subtle, but easy to traverse. Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim if cond1: expr1 elif cond2: expr2 else: expr3 AST: -.. code-block:: nimrod +.. code-block:: nim nnkIfExpr( nnkElifExpr(cond1, expr1), nnkElifExpr(cond2, expr2), @@ -337,7 +337,7 @@ there is no ``else`` branch, no ``nnkElse`` child exists. Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim if cond1: stmt1 elif cond2: @@ -349,7 +349,7 @@ Concrete syntax: AST: -.. code-block:: nimrod +.. code-block:: nim nnkIfStmt( nnkElifBranch(cond1, stmt1), nnkElifBranch(cond2, stmt2), @@ -369,12 +369,12 @@ Assignment Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim x = 42 AST: -.. code-block:: nimrod +.. code-block:: nim nnkAsgn(nnkIdent(!"x"), nnkIntLit(42)) @@ -383,14 +383,14 @@ Statement list Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim stmt1 stmt2 stmt3 AST: -.. code-block:: nimrod +.. code-block:: nim nnkStmtList(stmt1, stmt2, stmt3) @@ -399,7 +399,7 @@ Case statement Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim case expr1 of expr2, expr3..expr4: stmt1 @@ -412,7 +412,7 @@ Concrete syntax: AST: -.. code-block:: nimrod +.. code-block:: nim nnkCaseStmt( expr1, nnkOfBranch(expr2, nnkRange(expr3, expr4), stmt1), @@ -429,13 +429,13 @@ While statement Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim while expr1: stmt1 AST: -.. code-block:: nimrod +.. code-block:: nim nnkWhileStmt(expr1, stmt1) @@ -444,13 +444,13 @@ For statement Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim for ident1, ident2 in expr1: stmt1 AST: -.. code-block:: nimrod +.. code-block:: nim nnkForStmt(ident1, ident2, expr1, stmt1) @@ -459,7 +459,7 @@ Try statement Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim try: stmt1 except e1, e2: @@ -473,7 +473,7 @@ Concrete syntax: AST: -.. code-block:: nimrod +.. code-block:: nim nnkTryStmt( stmt1, nnkExceptBranch(e1, e2, stmt2), @@ -488,12 +488,12 @@ Return statement Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim return expr1 AST: -.. code-block:: nimrod +.. code-block:: nim nnkReturnStmt(expr1) @@ -514,12 +514,12 @@ Continue statement Concrete syntax: -.. code-block:: nimrod +.. code-block:: nim continue AST: -.. code-block:: nimrod +.. code-block:: nim nnkContinueStmt() Var section diff --git a/doc/backends.txt b/doc/backends.txt index c2dbb0af6..307f141b2 100644 --- a/doc/backends.txt +++ b/doc/backends.txt @@ -1,9 +1,9 @@ ================================ - Nimrod Backend Integration + Nim Backend Integration ================================ :Author: Puppet Master -:Version: |nimrodversion| +:Version: |nimversion| .. contents:: "Heresy grows from idleness." -- Unknown. @@ -12,20 +12,20 @@ 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 ``.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 to compile to C++, Objective-C or JavaScript. This document tries to 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 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 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 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 line invocations:: - $ nimrod c hallo.nim - $ nimrod cpp hallo.nim - $ nimrod objc hallo.nim + $ nim c hallo.nim + $ nim cpp hallo.nim + $ nim objc hallo.nim The compiler commands select the target backend, but if needed you can `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. 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! -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, -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 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 <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`` file. However, you can also run the code with `nodejs`:idx:, a `software platform for easily building fast, scalable network applications <http://nodejs.org>`_:: - nimrod js -d:nodejs -r examples/hallo.nim + nim js -d:nodejs -r examples/hallo.nim Interfacing =========== -Nimrod offers bidirectional interfacing with the target backend. This means -that you can call backend code from Nimrod and Nimrod code can be called by +Nim offers bidirectional interfacing with the target backend. This means +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 -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?). -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 `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 -have their respective `ImportCpp <nimrodc.html#importcpp-pragma>`_ and -`ImportObjC <nimrodc.html#importobjc-pragma>`_ pragmas to call methods from +have their respective `ImportCpp <nimc.html#importcpp-pragma>`_ and +`ImportObjC <nimc.html#importobjc-pragma>`_ pragmas to call methods from classes. 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 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 through the `dynlib pragma for import <manual.html#dynlib-pragma-for-import>`_, though more specific control can be 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. -Nimrod wrappers designed to statically link source files can use the `compile -pragma <nimrodc.html#compile-pragma>`_ if there are few sources or providing -them along the Nimrod code is easier than using a system library. Libraries +Nim wrappers designed to statically link source files can use the `compile +pragma <nimc.html#compile-pragma>`_ if there are few sources or providing +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 -<nimrodc.html#passl-pragma>`_. +<nimc.html#passl-pragma>`_. 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. 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: -.. code-block:: nimrod +.. code-block:: nim {.compile: "logic.c".} proc addTwoIntegers(a, b: cint): cint {.importc.} @@ -160,8 +160,8 @@ Create a ``calculator.nim`` file with the following content: when isMainModule: echo addTwoIntegers(3, 7) -With these two files in place, you can run ``nimrod c -r calculator.nim`` and -the Nimrod compiler will compile the ``logic.c`` file in addition to +With these two files in place, you can run ``nim c -r calculator.nim`` and +the Nim compiler will compile the ``logic.c`` file in addition to ``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 be remove the line with the ``compile`` pragma and run the following typical @@ -169,7 +169,7 @@ Unix commands:: $ gcc -c logic.c $ 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 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 from the previous section): -.. code-block:: nimrod +.. code-block:: nim proc addTwoIntegers(a, b: int): int {.importc.} when isMainModule: 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 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 `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* -way of making Nimrod symbols available to the backends. By default the Nimrod -compiler will mangle all the Nimrod symbols to avoid any name collision, so -the most significant thing the ``exportc`` pragma does is maintain the Nimrod +way of making Nim symbols available to the backends. By default the Nim +compiler will mangle all the Nim symbols to avoid any name collision, so +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 case the symbol rules don't match. The JavaScript target doesn't have any further interfacing considerations 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 the compiler will asume certain types for the return value and parameters 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 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: -.. code-block:: nimrod +.. code-block:: nim proc fib(a: cint): cint {.exportc.} = 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 -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:: - $ nimrod c --noMain --noLinking --header:fib.h fib.nim - $ gcc -o m -Inimcache -Ipath/to/nimrod/lib nimcache/*.c maths.c + $ nim c --noMain --noLinking --header:fib.h fib.nim + $ 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 object files into a final binary, and explicitly generate a header file for C integration. All the generated files are placed into the ``nimcache`` 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 -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 -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 - $ gcc -o m -Inimcache -Ipath/to/nimrod/lib libfib.nim.a maths.c + $ nim c --app:staticLib --noMain --header fib.nim + $ 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 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 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: @@ -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 from the previous section): -.. code-block:: nimrod +.. code-block:: nim proc fib(a: cint): cint {.exportc.} = if a <= 2: @@ -315,11 +315,11 @@ from the previous section): else: 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 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 -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 @@ -328,17 +328,17 @@ Nimcache naming logic The `nimcache`:idx: directory is generated during compilation and will hold either temporary or final files depending on your backend target. The default name for the directory is ``nimcache`` but you can use the ``--nimcache`` -`compiler switch <nimrodc.html#command-line-switches>`_ to change it. +`compiler switch <nimc.html#command-line-switches>`_ to change it. Nimcache and C like targets ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 -``babelPackageName_`` + ``nimrodSource``: +``babelPackageName_`` + ``nimSource``: * 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 ``argument_parser`` module from the same name Babel package you 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 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 ``.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 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 -previous examples only dealt with simple scalar values, but passing a Nimrod -string to C, or reading back a C string in Nimrod already requires you to be +previous examples only dealt with simple scalar values, but passing a Nim +string to C, or reading back a C string in Nim already requires you to be aware of who controls what to avoid crashing. 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 -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 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 freed with `GC_ref <system.html#GC_ref>`_ and `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: -.. code-block:: nimrod +.. code-block:: nim proc gimme(): cstring {.exportc.} = 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``. 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 -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 are `triggering yourself the collection <gc.html>`_. @@ -426,35 +426,35 @@ are `triggering yourself the collection <gc.html>`_. 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 -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 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 any more. 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 -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 -these for the Nimrod side should be enough. +these for the Nim side should be enough. 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 -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. -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 can then attach a GC to this thread via -.. code-block:: nimrod +.. code-block:: nim setStackBottom(addr(someLocal)) initGC() diff --git a/doc/basicopt.txt b/doc/basicopt.txt index fdb0e36e1..e8aaa2e4c 100644 --- a/doc/basicopt.txt +++ b/doc/basicopt.txt @@ -1,11 +1,11 @@ Usage:: - nimrod command [options] [projectfile] [arguments] + nim command [options] [projectfile] [arguments] Command: //compile, c compile project with default code generator (C) //doc generate the documentation for inputfile //doc2 generate the documentation for the whole project - //i start Nimrod in interactive mode (limited) + //i start Nim in interactive mode (limited) Arguments: arguments are passed to the program being run (if --run option is selected) @@ -35,3 +35,5 @@ Options: -r, --run run the compiled program with given arguments --advanced show advanced command line switches -h, --help show this help + +Note: Even single letter options require the colon: -p:PATH. diff --git a/doc/docgen.txt b/doc/docgen.txt index 30d0c6ff2..554f69838 100644 --- a/doc/docgen.txt +++ b/doc/docgen.txt @@ -1,9 +1,9 @@ =================================== - Nimrod DocGen Tools Guide + Nim DocGen Tools Guide =================================== :Author: Erik O'Leary -:Version: |nimrodversion| +:Version: |nimversion| .. contents:: @@ -12,7 +12,7 @@ Introduction ============ 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 (reStructuredText) files. The output documentation will include module 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 documentation. Comments are parsed as RST (see `reference <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. Example: -.. code-block:: nimrod +.. code-block:: nim type TPerson* = object ## This type contains a description of a person name: string @@ -45,7 +45,7 @@ This type contains a description of a person Field documentation comments can be added to fields like so: -.. code-block:: nimrod +.. code-block:: nim var numValues: int ## \ ## `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. -Nimrod file input +Nim file input ----------------- The following examples will generate documentation for the below contrived -*Nimrod* module, aptly named 'sample.nim' +*Nim* module, aptly named 'sample.nim' sample.nim: -.. code-block:: nimrod +.. code-block:: nim ## This module is a sample. 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. The ``doc`` command:: - nimrod doc sample + nim doc sample Partial Output:: ... @@ -99,11 +99,11 @@ Partial Output:: 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 -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. The ``doc2`` command:: - nimrod doc2 sample + nim doc2 sample Partial Output:: ... @@ -127,7 +127,7 @@ Note that this tool is built off of the ``doc`` command, and therefore is performed before semantic checking. The ``jsondoc`` command:: - nimrod jsondoc sample + nim jsondoc sample 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, 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 index file is line oriented (newlines have to be escaped). Each line represents a tab separated record of several columns, the first two mandatory, 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 files in the specified directory to generate a `theindex.html <theindex.html>`_ 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 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 template along others like ``$path`` and ``$line``. -In the case of Nimrod's own documentation, the ``txt`` value is just a commit -hash to append to a formatted URL to https://github.com/Araq/Nimrod. The +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/Nim. The ``tools/nimweb.nim`` helper queries the current git commit hash during doc 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. 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 -initially written in a dialect of RST which adds support for nimrod sourcecode -highlighting with the ``.. code-block:: nimrod`` prefix. ``code-block`` also +initially written in a dialect of RST which adds support for nim sourcecode +highlighting with the ``.. code-block:: nim`` prefix. ``code-block`` also supports highlighting of C++ and some other c-like languages. Usage:: - nimrod rst2html docgen.txt + nim rst2html docgen.txt Output:: You're reading it! @@ -272,8 +272,8 @@ symbols in the `system module <system.html>`_. `#TSignedInt <system.html#TSignedInt>`_ * ``var globalRaiseHook: proc (e: ref E_Base): bool {.nimcall.}`` **=>** `#globalRaiseHook <system.html#globalRaiseHook>`_ -* ``const NimrodVersion = "0.0.0"`` **=>** - `#NimrodVersion <system.html#NimrodVersion>`_ +* ``const NimVersion = "0.0.0"`` **=>** + `#NimVersion <system.html#NimVersion>`_ * ``proc getTotalMem(): int {.rtl, raises: [], tags: [].}`` **=>** `#getTotalMem, <system.html#getTotalMem,>`_ * ``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: 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]>`_). 2. Base filename plus anchor hyper link (eg. ``algorithm.html#*,int,TSortOrder``). @@ -342,7 +342,7 @@ final index, and TOC entries found in ``.nim`` files are discarded. Additional resources ==================== -`Nimrod Compiler User Guide <nimrodc.html#command-line-switches>`_ +`Nim Compiler User Guide <nimc.html#command-line-switches>`_ `RST Quick Reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ diff --git a/doc/docs.txt b/doc/docs.txt index 8126da86c..ecf0cc268 100644 --- a/doc/docs.txt +++ b/doc/docs.txt @@ -1,18 +1,18 @@ The documentation consists of several documents: - | `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>`_ - | 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>`_ - | 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>`_ - | 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 compiler, etc. @@ -20,11 +20,11 @@ The documentation consists of several documents: | Description of some tools that come with the standard distribution. - | `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. - | `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. - | `Term rewriting macros <trmacros.html>`_ diff --git a/doc/effects.txt b/doc/effects.txt index 8084ae17a..4ed1d09f1 100644 --- a/doc/effects.txt +++ b/doc/effects.txt @@ -1,5 +1,5 @@ ===================================================================== - Side effects in Nimrod + Side effects in Nim ===================================================================== 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 and should be evaluted: -.. code-block:: nimrod +.. code-block:: nim proc toUpper(s: string): string = result = newString(len(s)) for i in 0..len(s) - 1: diff --git a/doc/endb.txt b/doc/endb.txt index e9a01b583..049f9d40d 100644 --- a/doc/endb.txt +++ b/doc/endb.txt @@ -1,15 +1,17 @@ ============================================== - Embedded Nimrod Debugger (ENDB) User Guide + Embedded Nim Debugger (ENDB) User Guide ============================================== :Author: Andreas Rumpf -:Version: |nimrodversion| +:Version: |nimversion| .. contents:: +**WARNING**: ENDB is not maintained anymore! Please help if you're interested +in this tool. -Nimrod comes with a platform independent debugger - -the Embedded Nimrod Debugger (ENDB). The debugger is +Nim comes with a platform independent debugger - +the Embedded Nim Debugger (ENDB). The debugger is *embedded* into your executable if it has been compiled with the ``--debugger:on`` command line option. This also defines the conditional symbol ``ENDB`` for you. @@ -20,7 +22,7 @@ available for the debugger. If you start your program the debugger will immediately show 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 are listed in brackets ``[...]`` here. @@ -105,7 +107,7 @@ The ``breakpoint`` pragma The ``breakpoint`` pragma is syntactically a statement. It can be used to mark the *following line* as a breakpoint: -.. code-block:: Nimrod +.. code-block:: Nim write("1") {.breakpoint: "before_write_2".} write("2") @@ -125,7 +127,7 @@ The ``watchpoint`` pragma The ``watchpoint`` pragma is syntactically a statement. It can be used to mark a location as a watchpoint: -.. code-block:: Nimrod +.. code-block:: Nim var a: array [0..20, int] {.watchpoint: a[3].} @@ -141,7 +143,7 @@ is turned on, so you don't need to remove it from your source code after debugging. 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. @@ -159,7 +161,7 @@ Data Display Commands in the current stack frame, use the ``up`` or ``down`` command. 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. Since displaying the whole data structures is often not needed and diff --git a/doc/estp.txt b/doc/estp.txt index 704bc33f2..500ee52a5 100644 --- a/doc/estp.txt +++ b/doc/estp.txt @@ -3,10 +3,10 @@ =================================================== :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 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 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 in ``crcFromRope`` or its children. @@ -74,7 +74,7 @@ often remains mysterious. CommandCompileToC MainCommand HandleCmdLine - nimrod + nim Entry: 1/3391 Calls: 46/4160 = 1.1% [sum: 130; 130/4160 = 3.1%] updateCrc32 newCrcFromRopeAux @@ -90,7 +90,7 @@ often remains mysterious. CommandCompileToC MainCommand HandleCmdLine - nimrod + nim Entry: 2/3391 Calls: 41/4160 = 0.99% [sum: 171; 171/4160 = 4.1%] updateCrc32 updateCrc32 @@ -107,7 +107,7 @@ often remains mysterious. CommandCompileToC MainCommand HandleCmdLine - nimrod + nim Entry: 3/3391 Calls: 41/4160 = 0.99% [sum: 212; 212/4160 = 5.1%] crcFromFile writeRopeIfNotEqual @@ -121,7 +121,7 @@ often remains mysterious. CommandCompileToC MainCommand HandleCmdLine - nimrod + nim Entry: 4/3391 Calls: 41/4160 = 0.99% [sum: 253; 253/4160 = 6.1%] updateCrc32 crcFromFile @@ -136,7 +136,7 @@ often remains mysterious. CommandCompileToC MainCommand HandleCmdLine - nimrod + nim Entry: 5/3391 Calls: 32/4160 = 0.77% [sum: 285; 285/4160 = 6.9%] pop newCrcFromRopeAux @@ -152,7 +152,7 @@ often remains mysterious. CommandCompileToC MainCommand HandleCmdLine - nimrod + nim Entry: 6/3391 Calls: 17/4160 = 0.41% [sum: 302; 302/4160 = 7.3%] doOperation forAllChildrenAux @@ -171,7 +171,7 @@ often remains mysterious. MainCommand HandleCmdLine ... - nimrod + nim Entry: 7/3391 Calls: 14/4160 = 0.34% [sum: 316; 316/4160 = 7.6%] Contains isAccessible diff --git a/doc/exception_hierarchy_fragment.txt b/doc/exception_hierarchy_fragment.txt index 6ca68921f..f4a419fc4 100644 --- a/doc/exception_hierarchy_fragment.txt +++ b/doc/exception_hierarchy_fragment.txt @@ -1,31 +1,28 @@ -* `E_Base <system.html#E_Base>`_ - * `EAccessViolation <system.html#EAccessViolation>`_ - * `EArithmetic <system.html#EArithmetic>`_ - * `EDivByZero <system.html#EDivByZero>`_ - * `EOverflow <system.html#EOverflow>`_ - * `EAssertionFailed <system.html#EAssertionFailed>`_ - * `EAsynch <system.html#EAsynch>`_ - * `EControlC <system.html#EControlC>`_ - * `EDeadThread <system.html#EDeadThread>`_ - * `EFloatingPoint <system.html#EFloatingPoint>`_ - * `EFloatDivByZero <system.html#EFloatDivByZero>`_ - * `EFloatInexact <system.html#EFloatInexact>`_ - * `EFloatInvalidOp <system.html#EFloatInvalidOp>`_ - * `EFloatOverflow <system.html#EFloatOverflow>`_ - * `EFloatUnderflow <system.html#EFloatUnderflow>`_ - * `EInvalidField <system.html#EInvalidField>`_ - * `EInvalidIndex <system.html#EInvalidIndex>`_ - * `EInvalidObjectAssignment <system.html#EInvalidObjectAssignment>`_ - * `EInvalidObjectConversion <system.html#EInvalidObjectConversion>`_ - * `EInvalidValue <system.html#EInvalidValue>`_ - * `EInvalidKey <system.html#EInvalidKey>`_ - * `ENoExceptionToReraise <system.html#ENoExceptionToReraise>`_ - * `EOutOfRange <system.html#EOutOfRange>`_ - * `ESynch <system.html#ESynch>`_ - * `EOutOfMemory <system.html#EOutOfMemory>`_ - * `EResourceExhausted <system.html#EResourceExhausted>`_ - * `EStackOverflow <system.html#EStackOverflow>`_ - * `ESystem <system.html#ESystem>`_ - * `EIO <system.html#EIO>`_ - * `EOS <system.html#EOS>`_ - * `EInvalidLibrary <system.html#EInvalidLibrary>`_ +* `Exception <system.html#Exception>`_ + * `AccessViolationError <system.html#AccessViolationError>`_ + * `ArithmeticError <system.html#ArithmeticError>`_ + * `DivByZeroError <system.html#DivByZeroError>`_ + * `OverflowError <system.html#OverflowError>`_ + * `AssertionError <system.html#AssertionError>`_ + * `DeadThreadError <system.html#DeadThreadError>`_ + * `FloatingPointError <system.html#FloatingPointError>`_ + * `FloatDivByZeroError <system.html#FloatDivByZeroError>`_ + * `FloatInexactError <system.html#FloatInexactError>`_ + * `FloatInvalidOpError <system.html#FloatInvalidOpError>`_ + * `FloatOverflowError <system.html#FloatOverflowError>`_ + * `FloatUnderflowError <system.html#FloatUnderflowError>`_ + * `FieldError <system.html#InvalidFieldError>`_ + * `IndexError <system.html#InvalidIndexError>`_ + * `ObjectAssignmentError <system.html#ObjectAssignmentError>`_ + * `ObjectConversionError <system.html#ObjectConversionError>`_ + * `ValueError <system.html#ValueError>`_ + * `KeyError <system.html#KeyError>`_ + * `ReraiseError <system.html#ReraiseError>`_ + * `RangeError <system.html#RangeError>`_ + * `OutOfMemoryError <system.html#OutOfMemoryError>`_ + * `ResourceExhaustedError <system.html#ResourceExhaustedError>`_ + * `StackOverflowError <system.html#StackOverflowError>`_ + * `SystemError <system.html#SystemError>`_ + * `IOError <system.html#IOError>`_ + * `OSError <system.html#OSError>`_ + * `LibraryError <system.html#LibraryError>`_ diff --git a/doc/filelist.txt b/doc/filelist.txt index f71547f86..beff8f6c8 100644 --- a/doc/filelist.txt +++ b/doc/filelist.txt @@ -1,10 +1,10 @@ -Short description of Nimrod's modules +Short description of Nim's modules ------------------------------------- ============== ========================================================== Module Description ============== ========================================================== -nimrod main module: parses the command line and calls +nim main module: parses the command line and calls ``main.MainCommand`` main implements the top-level command dispatching nimconf implements the config file reader @@ -12,8 +12,8 @@ syntaxes dispatcher for the different parsers and filters filter_tmpl standard template filter (``#! stdtempl``) lexbase buffer handling of the lexical analyser lexer lexical analyser -parser Nimrod's parser -renderer Nimrod code renderer (AST back to its textual form) +parser Nim's parser +renderer Nim code renderer (AST back to its textual form) options contains global and local compiler options ast type definitions of the abstract syntax tree (AST) and node constructors @@ -37,7 +37,7 @@ pragmas semantic checking of pragmas idents implements a general mapping from identifiers to an internal 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 ropes implements long strings represented as trees for lazy evaluation; used mainly by the code generators diff --git a/doc/filters.txt b/doc/filters.txt index 961a0ea49..22df63490 100644 --- a/doc/filters.txt +++ b/doc/filters.txt @@ -40,7 +40,7 @@ Filters can be combined with the ``|`` pipe operator:: 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. Replace filter @@ -79,19 +79,19 @@ Parameters and their defaults: 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* -(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 statements need ``end X`` delimiters. Parameters and their defaults: ``metaChar: char = '#'`` - prefix for a line that contains Nimrod code + prefix for a line that contains Nim code ``subsChar: char = '$'`` - prefix for a Nimrod expression within a template line + prefix for a Nim expression within a template line ``conc: string = " & "`` the operation for concatenation @@ -130,7 +130,7 @@ Example:: The filter transforms this into: -.. code-block:: nimrod +.. code-block:: nim proc generateHTMLPage(title, currentTab, content: string, tabs: openArray[string]): string = result = "" @@ -158,7 +158,7 @@ The filter transforms this into: Each line that does not start with the meta character (ignoring leading 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 which defaults to ``$``. For strong type checking, set ``toString`` to the empty string. *e* must match this PEG pattern:: diff --git a/doc/gc.txt b/doc/gc.txt index 18fb03b6d..fdb1d1b6c 100644 --- a/doc/gc.txt +++ b/doc/gc.txt @@ -1,9 +1,9 @@ ========================== -Nimrod's Garbage Collector +Nim's Garbage Collector ========================== :Author: Andreas Rumpf -:Version: |nimrodversion| +:Version: |nimversion| "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 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 a quick operation; the root is only registered for the next run of the cycle collector. @@ -49,7 +49,7 @@ Realtime support To enable realtime support, the symbol `useRealtimeGC`:idx: needs to be defined. With this switch the GC supports the following operations: -.. code-block:: nimrod +.. code-block:: nim proc GC_setMaxPause*(MaxPauseInUs: int) proc GC_step*(us: int, strongAdvice = false) @@ -111,7 +111,7 @@ highly specialized environments or for older hardware. 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 being freed by the GC. Other useful procs from `system <system.html>`_ you can use to keep track of memory are: diff --git a/doc/idetools.txt b/doc/idetools.txt index 97e110b1d..5429d0c07 100644 --- a/doc/idetools.txt +++ b/doc/idetools.txt @@ -1,9 +1,9 @@ ================================ - Nimrod IDE Integration Guide + Nim IDE Integration Guide ================================ :Author: Britney Spears -:Version: |nimrodversion| +:Version: |nimversion| .. contents:: @@ -13,17 +13,17 @@ "yes, I'm the creator" -- Araq, 2013-07-26 19:28:32. </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 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 definition of symbols or suggestions for completion. This document will guide you through the available options. If you want to look at practical examples of idetools support you can look 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. @@ -37,11 +37,11 @@ All of the available idetools commands require you to specify a query location through the ``--track`` or ``--trackDirty`` switches. The general idetools invokations are:: - nimrod idetools --track:FILE,LINE,COL <switches> proj.nim + nim idetools --track:FILE,LINE,COL <switches> proj.nim 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`` 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 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 jump around the standard library implementation and see exactly 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. 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 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 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:: - nimrod serve --server.type:tcp --server.port:6000 \ + nim serve --server.type:tcp --server.port:6000 \ --server.address:hostname proj.nim 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 -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 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 @@ -242,7 +242,7 @@ skConst | **Fourth column**: the type of the const value. | **Docstring**: always the empty string. -.. code-block:: nimrod +.. code-block:: nim const SOME_SEQUENCE = @[1, 2] --> col 2: $MODULE.SOME_SEQUENCE col 3: seq[int] @@ -256,7 +256,7 @@ skEnumField | **Fourth column**: enum type grouping other enum fields. | **Docstring**: always the empty string. -.. code-block:: nimrod +.. code-block:: nim Open(filename, fmWrite) --> col 2: system.TFileMode.fmWrite col 3: TFileMode @@ -270,7 +270,7 @@ skForVar | **Fourth column**: type of the var. | **Docstring**: always the empty string. -.. code-block:: nimrod +.. code-block:: nim proc looper(filename = "tests.nim") = for letter in filename: echo letter @@ -291,7 +291,7 @@ posterior instances of the iterator. | **Fourth column**: signature of the iterator including return type. | **Docstring**: docstring if available. -.. code-block:: nimrod +.. code-block:: nim let text = "some text" letters = toSeq(runes(text)) @@ -307,7 +307,7 @@ skLabel | **Fourth column**: always the empty string. | **Docstring**: always the empty string. -.. code-block:: nimrod +.. code-block:: nim proc test(text: string) = var found = -1 block loops: @@ -323,7 +323,7 @@ skLet | **Fourth column**: the type of the let variable. | **Docstring**: always the empty string. -.. code-block:: nimrod +.. code-block:: nim let text = "some text" --> col 2: $MODULE.text @@ -343,7 +343,7 @@ posterior instances of the macro. | **Fourth column**: signature of the macro including return type. | **Docstring**: docstring if available. -.. code-block:: nimrod +.. code-block:: nim proc testMacro() = expect(EArithmetic): --> col 2: idetools_api.expect @@ -379,7 +379,7 @@ This may change in the future. | **Fourth column**: signature of the method including return type. | **Docstring**: docstring if available. -.. code-block:: nimrod +.. code-block:: nim method eval(e: PExpr): int = quit "to override!" method eval(e: PLiteral): int = e.x method eval(e: PPlusExpr): int = eval(e.a) + eval(e.b) @@ -396,7 +396,7 @@ skParam | **Fourth column**: the type of the parameter. | **Docstring**: always the empty string. -.. code-block:: nimrod +.. code-block:: nim proc reader(filename = "tests.nim") = let text = readFile(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. | **Docstring**: docstring if available. -.. code-block:: nimrod +.. code-block:: nim Open(filename, fmWrite) --> col 2: system.Open col 3: proc (var TFile, string, TFileMode, int): bool @@ -438,7 +438,7 @@ skResult | **Fourth column**: the type of the result. | **Docstring**: always the empty string. -.. code-block:: nimrod +.. code-block:: nim proc getRandomValue() : int = return 4 --> col 2: $MODULE.getRandomValue.result @@ -458,7 +458,7 @@ posterior instances of the template. | **Fourth column**: signature of the template including return type. | **Docstring**: docstring if available. -.. code-block:: nimrod +.. code-block:: nim let text = "some text" letters = toSeq(runes(text)) @@ -469,7 +469,7 @@ posterior instances of the template. Example: - .. code-block:: nimrod + .. code-block:: nim let numeric = @[1, 2, 3, 4, 5, 6, 7, 8, 9] odd_numbers = toSeq(filter(numeric) do (x: int) -> bool: @@ -485,7 +485,7 @@ skType | **Fourth column**: the type. | **Docstring**: always the empty string. -.. code-block:: nimrod +.. code-block:: nim proc writeTempFile() = var output: TFile --> col 2: system.TFile @@ -500,7 +500,7 @@ skVar | **Fourth column**: the type of the var. | **Docstring**: always the empty string. -.. code-block:: nimrod +.. code-block:: nim proc writeTempFile() = var output: TFile 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 run it manually. First you have to compile the tester:: - $ cd my/nimrod/checkout/tests - $ nimrod c testament/caasdriver.nim + $ cd my/nim/checkout/tests + $ nim c testament/caasdriver.nim Running the ``caasdriver`` without parameters will attempt to process 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 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 is used by compiler developers. This means that running all tests involves processing all ``*.txt`` files three times, which diff --git a/doc/intern.txt b/doc/intern.txt index 1dcf27774..6cd1987aa 100644 --- a/doc/intern.txt +++ b/doc/intern.txt @@ -1,10 +1,10 @@ ========================================= - Internals of the Nimrod Compiler + Internals of the Nim Compiler ========================================= :Author: Andreas Rumpf -:Version: |nimrodversion| +:Version: |nimversion| .. contents:: @@ -14,23 +14,23 @@ Directory structure =================== -The Nimrod project's directory structure is: +The Nim project's directory structure is: ============ ============================================== Path Purpose ============ ============================================== ``bin`` generated binary files ``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 version written in Pascal, so the code is **not** - a poster child of good Nimrod code -``config`` configuration files for Nimrod + a poster child of good Nim code +``config`` configuration files for Nim ``dist`` additional packages for the distribution ``doc`` the documentation; it is a bunch of reStructuredText files -``lib`` the Nimrod library -``web`` website of Nimrod; generated by ``nimweb`` +``lib`` the Nim library +``web`` website of Nim; generated by ``nimweb`` from the ``*.txt`` and ``*.tmpl`` files ============ ============================================== @@ -38,26 +38,26 @@ Path Purpose 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 -been rewritten in Nimrod too. +been rewritten in Nim too. Compiling the compiler is a simple matter of running:: - nimrod c koch.nim + nim c koch.nim ./koch boot For a release version use:: - nimrod c koch.nim + nim c koch.nim ./koch boot -d:release And for a debug version compatible with GDB:: - nimrod c koch.nim + nim c koch.nim ./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. More information about its options can be found in the `koch <koch.html>`_ documentation. @@ -80,13 +80,13 @@ See also the `API naming design <apis.html>`_ document. Porting to new platforms ======================== -Porting Nimrod to a new architecture is pretty easy, since C is the most -portable programming language (within certain limits) and Nimrod generates +Porting Nim to a new architecture is pretty easy, since C is the most +portable programming language (within certain limits) and Nim generates C code, porting the code generator is not necessary. POSIX-compliant systems on conventional hardware are usually pretty easy to 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 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* (RTTI) is needed for several aspects of the Nimrod +*Runtime type information* (RTTI) is needed for several aspects of the Nim programming language: Garbage collection @@ -108,7 +108,7 @@ Garbage collection Complex assignments 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 for any type that needs one. However, this would make the code bigger and 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 =========================== -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. This syntax tree is the interface between the parser and the code generator. 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. .. include:: filelist.txt @@ -172,7 +172,7 @@ Frontend issues 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 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 @@ -181,12 +181,12 @@ after the whole program has been translated! Other features that are *implicitly* triggered cause problems for modularity too. Type converters fall into this category: -.. code-block:: nimrod +.. code-block:: nim # module A converter toBool(x: int): bool = result = x != 0 -.. code-block:: nimrod +.. code-block:: nim # module B 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 @@ -262,7 +262,7 @@ in mind: * Segmentation faults can have multiple reasons: One that is frequently 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 real issue. * 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, modifying a ``TCellSet`` during traversation leads to undefined behaviour. -.. code-block:: Nimrod +.. code-block:: Nim type TCellSet # hidden @@ -340,11 +340,11 @@ Complete traversal is done in this way:: 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. Consider this example: -.. code-block:: Nimrod +.. code-block:: Nim proc setRef(r: var ref TNode) = new(r) @@ -380,7 +380,7 @@ Code generation for closures is implemented by `lambda lifting`:idx:. 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 ``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 @@ -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 could stem from a complex expression: -.. code-block:: nimrod +.. code-block:: nim receivesClosure(returnsDefaultCC[i]) 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: -.. code-block:: nimrod +.. code-block:: nim proc add(x: int): proc (y: int): int {.closure.} = return proc (y: int): int = return x + y @@ -415,7 +415,7 @@ Example code: This should produce roughly this code: -.. code-block:: nimrod +.. code-block:: nim type PEnv = ref object x: int # data @@ -436,7 +436,7 @@ This should produce roughly this code: Beware of nesting: -.. code-block:: nimrod +.. code-block:: nim proc add(x: int): proc (y: int): proc (z: int): int {.closure.} {.closure.} = return lamba (y: int): proc (z: int): int {.closure.} = return lambda (z: int): int = @@ -447,7 +447,7 @@ Beware of nesting: This should produce roughly this code: -.. code-block:: nimrod +.. code-block:: nim type PEnvX = ref object x: int # data @@ -492,7 +492,7 @@ environments. This is however not always possible. Accumulator ----------- -.. code-block:: nimrod +.. code-block:: nim proc GetAccumulator(start: int): proc (): int {.closure} = var i = start return lambda: int = diff --git a/doc/koch.txt b/doc/koch.txt index 7be2be6d4..7da137458 100644 --- a/doc/koch.txt +++ b/doc/koch.txt @@ -1,8 +1,8 @@ =============================== - Nimrod maintenance script + Nim maintenance script =============================== -:Version: |nimrodversion| +:Version: |nimversion| .. contents:: @@ -15,10 +15,10 @@ 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. 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. @@ -40,21 +40,21 @@ options: option is not supported on Windows. -d:useGnuReadline 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 incorporate the GNU readline library. -d:nativeStacktrace Use native stack traces (only for Mac OS X or Linux). -d:noCaas - Builds Nimrod without compiler as a service (CAAS) support. CAAS - support is required for functionality like Nimrod's `idetool + Builds Nim without compiler as a service (CAAS) support. CAAS + support is required for functionality like Nim's `idetool <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 Only for Mac OS X, activating this switch will force excluding the generated ``nimcache`` directories from Time Machine 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 option will make the compiler invoke the `tmutil <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 \{\} \; -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 - are limited to pure Nimrod code at compilation time. Enabling - this switch will allow macros to execute non-nimrod code at + are limited to pure Nim code at compilation time. Enabling + this switch will allow macros to execute non-nim code at compilation time (eg. open a file and write to it). --gc:refc|v2|markAndSweep|boehm|none 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. -After compilation is finished you will hopefully end up with the nimrod -compiler in the ``bin`` directory. You can add Nimrod's ``bin`` directory to +After compilation is finished you will hopefully end up with the nim +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 found. @@ -101,7 +101,7 @@ The `inno`:idx: command builds the `Inno Setup installer for Windows 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:: $ ./koch install /usr/local/bin @@ -109,8 +109,8 @@ is required as a parameter. For example, on Unix platforms you could run:: temp command ------------ -The temp command builds the Nimrod compiler but with a different final name -(``nimrod_temp``), so it doesn't overwrite your normal compiler. You can use +The temp command builds the Nim compiler but with a different final name +(``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 command`_. @@ -119,14 +119,14 @@ test command 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 -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 options. 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 ``-d:withUpdate`` switch. @@ -136,7 +136,7 @@ web command 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 the ``web/upload`` which can be used to update the website at -http://nimrod-lang.org. +http://nim-lang.org. By default the documentation will be built in parallel using the number of available CPU cores. If any documentation build sub commands fail, they will diff --git a/doc/lib.txt b/doc/lib.txt index 26ea1b735..a29e32429 100644 --- a/doc/lib.txt +++ b/doc/lib.txt @@ -1,15 +1,15 @@ -======================= -Nimrod Standard Library -======================= +==================== +Nim Standard Library +==================== :Author: Andreas Rumpf -:Version: |nimrodversion| +:Version: |nimversion| .. contents:: "The good thing about reinventing the wheel is that you can get a round one." -Though the Nimrod Standard Library is still evolving, it is already quite +Though the Nim Standard Library is still evolving, it is already quite usable. It is divided into *pure libraries*, *impure libraries* and *wrappers*. Pure libraries do not depend on any external ``*.dll`` or ``lib*.so`` binary @@ -19,7 +19,7 @@ low-level interface to a C library. Read this `document <apis.html>`_ for a quick overview of the API design. The `bottom <#babel>`_ of this page includes a list of 3rd party packages -created by the Nimrod community. These packages are a useful addition to the +created by the Nim community. These packages are a useful addition to the modules in the standard library. @@ -41,27 +41,27 @@ Core of ``system``, but an extra import. * `threads <threads.html>`_ - Nimrod thread support. **Note**: This is part of the system module. Do not + Nim thread support. **Note**: This is part of the system module. Do not import it explicitly. * `channels <channels.html>`_ - Nimrod message passing support for threads. **Note**: This is part of the + Nim message passing support for threads. **Note**: This is part of the system module. Do not import it explicitly. * `locks <locks.html>`_ - Locks and condition variables for Nimrod. + Locks and condition variables for Nim. * `macros <macros.html>`_ - Contains the AST API and documentation of Nimrod for writing macros. + Contains the AST API and documentation of Nim for writing macros. * `typeinfo <typeinfo.html>`_ - Provides (unsafe) access to Nimrod's run time type information. + Provides (unsafe) access to Nim's run time type information. * `typetraits <typetraits.html>`_ This module defines compile-time reflection procs for working with types. * `actors <actors.html>`_ - Actor support for Nimrod; implemented as a layer on top of the threads and + Actor support for Nim; implemented as a layer on top of the threads and channels modules. @@ -71,11 +71,11 @@ Collections and algorithms * `algorithm <algorithm.html>`_ Implements some common generic algorithms like sort or binary search. * `tables <tables.html>`_ - Nimrod hash table support. Contains tables, ordered tables and count tables. + Nim hash table support. Contains tables, ordered tables and count tables. * `sets <sets.html>`_ - Nimrod hash and bit set support. + Nim hash and bit set support. * `lists <lists.html>`_ - Nimrod linked list support. Contains singly and doubly linked lists and + Nim linked list support. Contains singly and doubly linked lists and circular lists ("rings"). * `queues <queues.html>`_ Implementation of a queue. The underlying implementation uses a ``seq``. @@ -153,11 +153,11 @@ Generic Operating System Services * `streams <streams.html>`_ This module provides a stream interface and two implementations thereof: the `PFileStream` and the `PStringStream` which implement the stream - interface for Nimrod file objects (`TFile`) and strings. Other modules + interface for Nim file objects (`TFile`) and strings. Other modules may provide other implementations for this standard stream interface. * `marshal <marshal.html>`_ - Contains procs for serialization and deseralization of arbitrary Nimrod + Contains procs for serialization and deseralization of arbitrary Nim data structures. * `terminal <terminal.html>`_ @@ -273,7 +273,7 @@ Parsers parser. The configuration file's syntax is similar to the Windows ``.ini`` format, but much more powerful, as it is not a line based parser. String literals, raw string literals and triple quote string literals are supported - as in the Nimrod programming language. + as in the Nim programming language. * `parsexml <parsexml.html>`_ The ``parsexml`` module implements a simple high performance XML/HTML parser. @@ -340,7 +340,7 @@ Cryptography and Hashing * `hashes <hashes.html>`_ This module implements efficient computations of hash values for diverse - Nimrod types. + Nim types. * `md5 <md5.html>`_ This module implements the MD5 checksum algorithm. @@ -353,7 +353,7 @@ Multimedia support ------------------ * `colors <colors.html>`_ - This module implements color handling for Nimrod. It is used by + This module implements color handling for Nim. It is used by the ``graphics`` module. @@ -426,12 +426,12 @@ Other ----- * `graphics <graphics.html>`_ - This module implements graphical output for Nimrod; the current + This module implements graphical output for Nim; the current implementation uses SDL but the interface is meant to support multiple backends some day. * `dialogs <dialogs.html>`_ - This module implements portable dialogs for Nimrod; the implementation + This module implements portable dialogs for Nim; the implementation builds on the GTK interface. On Windows, native dialogs are shown if appropriate. @@ -444,7 +444,7 @@ Other * `ssl <ssl.html>`_ This module provides an easy to use sockets-style - Nimrod interface to the OpenSSL library. + Nim interface to the OpenSSL library. * `rdstdin <rdstdin.html>`_ This module contains code for reading from `stdin`:idx:. On UNIX the GNU @@ -532,7 +532,7 @@ Database support * `odbcsql <odbcsql.html>`_ interface to the ODBC driver. * `sphinx <sphinx.html>`_ - Nimrod wrapper for ``sphinx``. + Nim wrapper for ``sphinx``. XML Processing @@ -578,15 +578,15 @@ Scientific computing Babel ==================== -Babel is a package manager for the Nimrod programming language. +Babel is a package manager for the Nim programming language. For instructions on how to install Babel packages see -`its README <https://github.com/nimrod-code/babel#readme>`_. +`its README <https://github.com/nim-code/babel#readme>`_. Official packages ----------------- These packages are officially supported and will therefore be continually -maintained to ensure that they work with the latest versions of the Nimrod +maintained to ensure that they work with the latest versions of the Nim compiler. .. raw:: html @@ -597,9 +597,9 @@ compiler. Unofficial packages ------------------- -These packages have been developed by independent Nimrod developers and as +These packages have been developed by independent Nim developers and as such may not always be up to date with the latest developments in the -Nimrod programming language. +Nim programming language. .. raw:: html @@ -607,4 +607,4 @@ Nimrod programming language. babelpkglist.js or have javascript disabled in your browser.</b></div> <script type="text/javascript" src="babelpkglist.js"></script> - <script type="text/javascript" src="http://build.nimrod-lang.org/packages?callback=gotPackageList"></script> + <script type="text/javascript" src="http://build.nim-lang.org/packages?callback=gotPackageList"></script> diff --git a/doc/manual.txt b/doc/manual.txt index 7b713bf93..3d44110f5 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -1,9 +1,9 @@ -============= -Nimrod Manual -============= +========== +Nim Manual +========== :Authors: Andreas Rumpf, Zahary Karadjov -:Version: |nimrodversion| +:Version: |nimversion| .. contents:: @@ -17,11 +17,11 @@ Nimrod Manual About this document =================== -**Note**: This document is a draft! Several of Nimrod's features need more +**Note**: This document is a draft! Several of Nim's features need more precise wording. This manual will evolve into a proper specification some day. -This document describes the lexis, the syntax, and the semantics of Nimrod. +This document describes the lexis, the syntax, and the semantics of Nim. The language constructs are explained using an extended BNF, in which ``(a)*`` means 0 or more ``a``'s, ``a+`` means 1 or more ``a``'s, and @@ -48,14 +48,14 @@ and ``a ^* b`` is short for ``(a (b a)*)?``. Example:: arrayConstructor = '[' expr ^* ',' ']' -Other parts of Nimrod - like scoping rules or runtime semantics are only +Other parts of Nim - like scoping rules or runtime semantics are only described in an informal manner for now. Definitions =========== -A Nimrod program specifies a computation that acts on a memory consisting of +A Nim program specifies a computation that acts on a memory consisting of components called `locations`:idx:. A variable is basically a name for a location. Each variable and location is of a certain `type`:idx:. The variable's type is called `static type`:idx:, the location's type is called @@ -87,7 +87,7 @@ Wether a checked runtime error results in an exception or in a fatal error at runtime is implementation specific. Thus the following program is always invalid: -.. code-block:: nimrod +.. code-block:: nim var a: array[0..1, char] let i = 5 try: @@ -107,7 +107,7 @@ Lexical Analysis Encoding -------- -All Nimrod source files are in the UTF-8 encoding (or its ASCII subset). Other +All Nim source files are in the UTF-8 encoding (or its ASCII subset). Other encodings are not supported. Any of the standard platform line termination sequences can be used - the Unix form using ASCII LF (linefeed), the Windows form using the ASCII sequence CR LF (return followed by linefeed), or the old @@ -118,13 +118,13 @@ used equally, regardless of platform. Indentation ----------- -Nimrod's standard grammar describes an `indentation sensitive`:idx: language. +Nim's standard grammar describes an `indentation sensitive`:idx: language. This means that all the control structures are recognized by indentation. Indentation consists only of spaces; tabulators are not allowed. The indentation handling is implemented as follows: The lexer annotates the following token with the preceding number of spaces; indentation is not -a separate token. This trick allows parsing of Nimrod with only 1 token of +a separate token. This trick allows parsing of Nim with only 1 token of lookahead. The parser uses a stack of indentation levels: the stack consists of integers @@ -156,39 +156,26 @@ Comments start anywhere outside a string or character literal with the hash character ``#``. Comments consist of a concatenation of `comment pieces`:idx:. A comment piece starts with ``#`` and runs until the end of the line. The end of line characters -belong to the piece. If the next line only consists of a comment piece which is -aligned to the preceding one, it does not start a new comment: +belong to the piece. If the next line only consists of a comment piece with +no other tokens between it and the preceding one, it does not start a new +comment: -.. code-block:: nimrod - i = 0 # This is a single comment over multiple lines belonging to the - # assignment statement. The scanner merges these two pieces. - # This is a new comment belonging to the current block, but to no particular - # statement. - i = i + 1 # This a new comment that is NOT - echo(i) # continued here, because this comment refers to the echo statement +.. code-block:: nim + i = 0 # This is a single comment over multiple lines. + # The scanner merges these two pieces. + # The comment continues here. -The alignment requirement does not hold if the preceding comment piece ends in -a backslash (followed by optional whitespace): - -.. code-block:: nimrod - type - TMyObject {.final, pure, acyclic.} = object # comment continues: \ - # we have lots of space here to comment 'TMyObject'. - # This line belongs to the comment as it's properly aligned. - -Comments are tokens; they are only allowed at certain places in the input file -as they belong to the syntax tree! This feature enables perfect source-to-source -transformations (such as pretty-printing) and superior documentation generators. -A nice side-effect is that the human reader of the code always knows exactly -which code snippet the comment refers to. +`Documentation comments`:idx: are comments that start with two ``##``. +Documentation comments are tokens; they are only allowed at certain places in +the input file as they belong to the syntax tree! Identifiers & Keywords ---------------------- -Identifiers in Nimrod can be any string of letters, digits +Identifiers in Nim can be any string of letters, digits and underscores, beginning with a letter. Two immediate following underscores ``__`` are not allowed:: @@ -203,18 +190,18 @@ operator characters instead. The following keywords are reserved and cannot be used as identifiers: -.. code-block:: nimrod +.. code-block:: nim :file: keywords.txt Some keywords are unused; they are reserved for future developments of the language. -Nimrod is a `style-insensitive`:idx: language. This means that it is not +Nim is a `style-insensitive`:idx: language. This means that it is not case-sensitive and even underscores are ignored: **type** is a reserved word, and so is **TYPE** or **T_Y_P_E**. The idea behind this is that this allows programmers to use their own preferred spelling style and libraries written by different programmers cannot use incompatible -conventions. A Nimrod-aware editor or IDE can show the identifiers as +conventions. A Nim-aware editor or IDE can show the identifiers as preferred. Another advantage is that it frees the programmer from remembering the exact spelling of an identifier. @@ -250,7 +237,7 @@ contain the following `escape sequences`:idx:\ : ================== =================================================== -Strings in Nimrod may contain any 8-bit value, even embedded zeros. However +Strings in Nim may contain any 8-bit value, even embedded zeros. However some operations may interpret the first binary zero as a terminator. @@ -268,7 +255,7 @@ be whitespace between the opening ``"""`` and the newline), the newline (and the preceding whitespace) is not included in the string. The ending of the string literal is defined by the pattern ``"""[^"]``, so this: -.. code-block:: nimrod +.. code-block:: nim """"long string within quotes"""" Produces:: @@ -286,13 +273,13 @@ letter ``r`` (or ``R``) and are delimited by matching double quotes (just like ordinary string literals) and do not interpret the escape sequences. This is especially convenient for regular expressions or Windows paths: -.. code-block:: nimrod +.. code-block:: nim var f = openFile(r"C:\texts\text.txt") # a raw string, so ``\t`` is no tab To produce a single ``"`` within a raw string literal, it has to be doubled: -.. code-block:: nimrod +.. code-block:: nim r"a""b" @@ -317,7 +304,7 @@ identifier and the opening quotation mark) is a generalized raw string literal. It is a shortcut for the construct ``identifier(r"string literal")``, so it denotes a procedure call with a raw string literal as its only argument. Generalized raw string literals -are especially convenient for embedding mini languages directly into Nimrod +are especially convenient for embedding mini languages directly into Nim (for example regular expressions). The construct ``identifier"""string literal"""`` exists too. It is a shortcut @@ -357,7 +344,7 @@ literals: A character is not an Unicode character but a single byte. The reason for this is efficiency: for the overwhelming majority of use-cases, the resulting programs will still handle UTF-8 properly as UTF-8 was specially designed for -this. Another reason is that Nimrod can thus support ``array[char, int]`` or +this. Another reason is that Nim can thus support ``array[char, int]`` or ``set[char]`` efficiently as many algorithms rely on this feature. The `TRune` type is used for Unicode characters, it can represent any Unicode character. ``TRune`` is declared in the `unicode module <unicode.html>`_. @@ -441,7 +428,7 @@ is approximately 1.72826e35 according to the IEEE floating point standard. Operators --------- -In Nimrod one can define his own operators. An operator is any +In Nim one can define his own operators. An operator is any combination of the following characters:: = + - * / < > @@ -474,10 +461,10 @@ and not the two tokens `{.`:tok:, `.}`:tok:. Syntax ====== -This section lists Nimrod's standard syntax. How the parser handles +This section lists Nim's standard syntax. How the parser handles the indentation is already described in the `Lexical Analysis`_ section. -Nimrod allows user-definable operators. +Nim allows user-definable operators. Binary operators have 10 different levels of precedence. Relevant character @@ -542,7 +529,7 @@ is not used to determine the number of spaces. If 2 or more operators have the same number of preceding spaces the precedence table applies, so ``1 + 3 * 4`` is still parsed as ``1 + (3 * 4)``, but ``1+3 * 4`` is parsed as ``(1+3) * 4``: -.. code-block:: nimrod +.. code-block:: nim #! strongSpaces if foo+4 * 4 == 8 and b&c | 9 ++ bar: @@ -554,7 +541,7 @@ is still parsed as ``1 + (3 * 4)``, but ``1+3 * 4`` is parsed as ``(1+3) * 4``: Furthermore whether an operator is used a prefix operator is affected by the number of spaces: -.. code-block:: nimrod +.. code-block:: nim #! strongSpaces echo $foo # is parsed as @@ -563,7 +550,7 @@ number of spaces: This also affects whether ``[]``, ``{}``, ``()`` are parsed as constructors or as accessors: -.. code-block:: nimrod +.. code-block:: nim #! strongSpaces echo (1,2) # is parsed as @@ -588,7 +575,7 @@ The grammar's start symbol is ``module``. Types ===== -All expressions have a type which is known at compile time. Nimrod +All expressions have a type which is known at compile time. Nim is statically typed. One can declare new types, which is in essence defining an identifier that can be used to denote this custom type. @@ -609,7 +596,7 @@ Ordinal types Ordinal types have the following characteristics: - Ordinal types are countable and ordered. This property allows - the operation of functions as ``Inc``, ``Ord``, ``Dec`` on ordinal types to + the operation of functions as ``inc``, ``ord``, ``dec`` on ordinal types to be defined. - Ordinal values have a smallest possible value. Trying to count further down than the smallest value gives a checked runtime or static error. @@ -686,10 +673,10 @@ kinds of integer types are used: the smaller type is converted to the larger. A `narrowing type conversion`:idx: converts a larger to a smaller type (for example ``int32 -> int16``. A `widening type conversion`:idx: converts a -smaller type to a larger type (for example ``int16 -> int32``). In Nimrod only +smaller type to a larger type (for example ``int16 -> int32``). In Nim only widening type conversions are *implicit*: -.. code-block:: nimrod +.. code-block:: nim var myInt16 = 5i16 var myInt: int myInt16 + 34 # of type ``int16`` @@ -710,20 +697,20 @@ A subrange type is a range of values from an ordinal type (the base type). To define a subrange type, one must specify it's limiting values: the lowest and highest value of the type: -.. code-block:: nimrod +.. code-block:: nim type - TSubrange = range[0..5] + Subrange = range[0..5] -``TSubrange`` is a subrange of an integer which can only hold the values 0 -to 5. Assigning any other value to a variable of type ``TSubrange`` is a +``Subrange`` is a subrange of an integer which can only hold the values 0 +to 5. Assigning any other value to a variable of type ``Subrange`` is a checked runtime error (or static error if it can be statically determined). Assignments from the base type to one of its subrange types (and vice versa) are allowed. A subrange type has the same size as its base type (``int`` in the example). -Nimrod requires `interval arithmetic`:idx: for subrange types over a set +Nim requires `interval arithmetic`:idx: for subrange types over a set of built-in operators that involve constants: ``x %% 3`` is of type ``range[0..2]``. The following built-in operators for integers are affected by this rule: ``-``, ``+``, ``*``, ``min``, ``max``, ``succ``, @@ -735,7 +722,7 @@ constant *x* so that (x+1) is a number of two. This means that the following code is accepted: -.. code-block:: nimrod +.. code-block:: nim case (x and 3) + 7 of 7: echo "A" of 8: echo "B" @@ -781,14 +768,14 @@ The IEEE standard defines five types of floating-point exceptions: precision, for example, 2.0 / 3.0, log(1.1) and 0.1 in input. The IEEE exceptions are either ignored at runtime or mapped to the -Nimrod exceptions: `EFloatInvalidOp`:idx:, `EFloatDivByZero`:idx:, +Nim exceptions: `EFloatInvalidOp`:idx:, `EFloatDivByZero`:idx:, `EFloatOverflow`:idx:, `EFloatUnderflow`:idx:, and `EFloatInexact`:idx:. These exceptions inherit from the `EFloatingPoint`:idx: base class. -Nimrod provides the pragmas `NaNChecks`:idx: and `InfChecks`:idx: to control -whether the IEEE exceptions are ignored or trap a Nimrod exception: +Nim provides the pragmas `NaNChecks`:idx: and `InfChecks`:idx: to control +whether the IEEE exceptions are ignored or trap a Nim exception: -.. code-block:: nimrod +.. code-block:: nim {.NanChecks: on, InfChecks: on.} var a = 1.0 var b = 0.0 @@ -804,10 +791,14 @@ turned off as default. The only operations that are affected by the ``floatChecks`` pragma are the ``+``, ``-``, ``*``, ``/`` operators for floating point types. +An implementation should always use the maximum precision available to evaluate +floating pointer values at compile time; this means expressions like +``0.09'f32 + 0.01'f32 == 0.09'f64 + 0.01'f64`` are true. + Boolean type ------------ -The boolean type is named `bool`:idx: in Nimrod and can be one of the two +The boolean type is named `bool`:idx: in Nim and can be one of the two pre-defined values ``true`` and ``false``. Conditions in while, if, elif, when statements need to be of type bool. @@ -819,7 +810,7 @@ The operators ``not, and, or, xor, <, <=, >, >=, !=, ==`` are defined for the bool type. The ``and`` and ``or`` operators perform short-cut evaluation. Example: -.. code-block:: nimrod +.. code-block:: nim while p != nil and p.name != "xyz": # p.name is not evaluated if p == nil @@ -831,12 +822,12 @@ The size of the bool type is one byte. Character type -------------- -The character type is named ``char`` in Nimrod. Its size is one byte. +The character type is named ``char`` in Nim. Its size is one byte. Thus it cannot represent an UTF-8 character, but a part of it. The reason for this is efficiency: for the overwhelming majority of use-cases, the resulting programs will still handle UTF-8 properly as UTF-8 was specially designed for this. -Another reason is that Nimrod can support ``array[char, int]`` or +Another reason is that Nim can support ``array[char, int]`` or ``set[char]`` efficiently as many algorithms rely on this feature. The `TRune` type is used for Unicode characters, it can represent any Unicode character. ``TRune`` is declared in the `unicode module <unicode.html>`_. @@ -849,7 +840,7 @@ Enumeration types Enumeration types define a new type whose values consist of the ones specified. The values are ordered. Example: -.. code-block:: nimrod +.. code-block:: nim type TDirection = enum @@ -873,7 +864,7 @@ explicitly given is assigned the value of the previous field + 1. An explicit ordered enum can have *holes*: -.. code-block:: nimrod +.. code-block:: nim type TTokenType = enum a = 2, b = 4, c = 89 # holes are valid @@ -887,7 +878,7 @@ The compiler supports the built-in stringify operator ``$`` for enumerations. The stringify's result can be controlled by explicitly giving the string values to use: -.. code-block:: nimrod +.. code-block:: nim type TMyEnum = enum @@ -904,7 +895,7 @@ An enum can be marked with the ``pure`` pragma so that it's fields are not added to the current scope, so they always need to be accessed via ``TMyEnum.value``: -.. code-block:: nimrod +.. code-block:: nim type TMyEnum {.pure.} = enum @@ -916,8 +907,8 @@ via ``TMyEnum.value``: String type ----------- -All string literals are of the type ``string``. A string in Nimrod is very -similar to a sequence of characters. However, strings in Nimrod are both +All string literals are of the type ``string``. A string in Nim is very +similar to a sequence of characters. However, strings in Nim are both zero-terminated and have a length field. One can retrieve the length with the builtin ``len`` procedure; the length never counts the terminating zero. The assignment operator for strings always copies the string. @@ -927,7 +918,7 @@ Strings are compared by their lexicographical order. All comparison operators are available. Strings can be indexed like arrays (lower bound is 0). Unlike arrays, they can be used in case statements: -.. code-block:: nimrod +.. code-block:: nim case paramStr(i) of "-v": incl(options, optVerbose) @@ -949,11 +940,11 @@ interfacing with C. The index operation ``s[i]`` means the i-th *char* of ``s``; however no bounds checking for ``cstring`` is performed making the index operation unsafe. -A Nimrod ``string`` is implicitly convertible -to ``cstring`` for convenience. If a Nimrod string is passed to a C-style +A Nim ``string`` is implicitly convertible +to ``cstring`` for convenience. If a Nim string is passed to a C-style variadic proc, it is implicitly converted to ``cstring`` too: -.. code-block:: nimrod +.. code-block:: nim proc printf(formatstr: cstring) {.importc: "printf", varargs, header: "<stdio.h>".} @@ -966,10 +957,10 @@ stack roots conservatively. One can use the builtin procs ``GC_ref`` and ``GC_unref`` to keep the string data alive for the rare cases where it does not work. -A `$` proc is defined for cstrings that returns a string. Thus to get a nimrod +A `$` proc is defined for cstrings that returns a string. Thus to get a nim string from a cstring: -.. code-block:: nimrod +.. code-block:: nim var str: string = "Hello!" var cstr: cstring = s var newstr: string = $cstr @@ -1002,7 +993,7 @@ A sequence may be passed to a parameter that is of type *open array*. Example: -.. code-block:: nimrod +.. code-block:: nim type TIntArray = array[0..5, int] # an array that is indexed with 0..5 @@ -1051,7 +1042,7 @@ A ``varargs`` parameter is an openarray parameter that additionally allows to pass a variable number of arguments to a procedure. The compiler converts the list of arguments to an array implicitly: -.. code-block:: nimrod +.. code-block:: nim proc myWriteln(f: TFile, a: varargs[string]) = for s in items(a): write(f, s) @@ -1065,7 +1056,7 @@ This transformation is only done if the varargs parameter is the last parameter in the procedure header. It is also possible to perform type conversions in this context: -.. code-block:: nimrod +.. code-block:: nim proc myWriteln(f: TFile, a: varargs[string, `$`]) = for s in items(a): write(f, s) @@ -1098,7 +1089,7 @@ The default assignment operator for objects copies each component. Overloading of the assignment operator for objects is not possible, but this will change in future versions of the compiler. -.. code-block:: nimrod +.. code-block:: nim type TPerson = tuple[name: string, age: int] # type representing a person: @@ -1116,7 +1107,7 @@ is compatible with the way the C compiler does it. For consistency with ``object`` declarations, tuples in a ``type`` section can also be defined with indentation instead of ``[]``: -.. code-block:: nimrod +.. code-block:: nim type TPerson = tuple # type representing a person name: string # a person consists of a name @@ -1126,7 +1117,7 @@ Objects provide many features that tuples do not. Object provide inheritance and information hiding. Objects have access to their type at runtime, so that the ``of`` operator can be used to determine the object's type. -.. code-block:: nimrod +.. code-block:: nim type TPerson {.inheritable.} = object name*: string # the * means that `name` is accessible from other modules @@ -1154,7 +1145,7 @@ Objects can also be created with an `object construction expression`:idx: that has the syntax ``T(fieldA: valueA, fieldB: valueB, ...)`` where ``T`` is an ``object`` type or a ``ref object`` type: -.. code-block:: nimrod +.. code-block:: nim var student = TStudent(name: "Anton", age: 5, id: 3) For a ``ref object`` type ``system.new`` is invoked implicitly. @@ -1167,9 +1158,9 @@ variant types are needed. An example: -.. code-block:: nimrod +.. code-block:: nim - # This is an example how an abstract syntax tree could be modelled in Nimrod + # This is an example how an abstract syntax tree could be modelled in Nim type TNodeKind = enum # the different node types nkInt, # a leaf with an integer value @@ -1230,7 +1221,7 @@ References (similar to pointers in other programming languages) are a way to introduce many-to-one relationships. This means different references can point to and modify the same location in memory (also called `aliasing`:idx:). -Nimrod distinguishes between `traced`:idx: and `untraced`:idx: references. +Nim distinguishes between `traced`:idx: and `untraced`:idx: references. Untraced references are also called *pointers*. Traced references point to objects of a garbage collected heap, untraced references point to manually allocated objects or to objects somewhere else in memory. Thus @@ -1249,7 +1240,7 @@ The ``.`` (access a tuple/object field operator) and ``[]`` (array/string/sequence index operator) operators perform implicit dereferencing operations for reference types: -.. code-block:: nimrod +.. code-block:: nim type PNode = ref TNode @@ -1267,7 +1258,7 @@ As a syntactical extension ``object`` types can be anonymous if declared in a type section via the ``ref object`` or ``ptr object`` notations. This feature is useful if an object should only gain reference semantics: -.. code-block:: nimrod +.. code-block:: nim type Node = ref object @@ -1287,7 +1278,7 @@ traced references, strings or sequences: in order to free everything properly, the built-in procedure ``GCunref`` has to be called before freeing the untraced memory manually: -.. code-block:: nimrod +.. code-block:: nim type TData = tuple[x, y: int, s: string] @@ -1326,7 +1317,7 @@ Not nil annotation All types for that ``nil`` is a valid value can be annotated to exclude ``nil`` as a valid value with the ``not nil`` annotation: -.. code-block:: nimrod +.. code-block:: nim type PObject = ref TObj not nil TProc = (proc (x, y: int)) not nil @@ -1355,7 +1346,7 @@ A region has to be an object type. Regions are very useful to separate user space and kernel memory in the development of OS kernels: -.. code-block:: nimrod +.. code-block:: nim type Kernel = object Userspace = object @@ -1377,7 +1368,7 @@ the pointer types: If ``A <: B`` then ``ptr[A, T] <: ptr[B, T]``. This can be used to model subregions of memory. As a special typing rule ``ptr[R, T]`` is not compatible to ``pointer`` to prevent the following from compiling: -.. code-block:: nimrod +.. code-block:: nim # from system proc dealloc(p: pointer) @@ -1409,12 +1400,12 @@ Future directions: Procedural type --------------- A procedural type is internally a pointer to a procedure. ``nil`` is -an allowed value for variables of a procedural type. Nimrod uses procedural +an allowed value for variables of a procedural type. Nim uses procedural types to achieve `functional`:idx: programming techniques. Examples: -.. code-block:: nimrod +.. code-block:: nim proc printItem(x: int) = ... @@ -1424,7 +1415,7 @@ Examples: forEach(printItem) # this will NOT compile because calling conventions differ -.. code-block:: nimrod +.. code-block:: nim type TOnMouseMove = proc (x, y: int) {.closure.} @@ -1446,10 +1437,10 @@ compatible if they have the same calling convention. As a special extension, a procedure of the calling convention ``nimcall`` can be passed to a parameter that expects a proc of the calling convention ``closure``. -Nimrod supports these `calling conventions`:idx:\: +Nim supports these `calling conventions`:idx:\: `nimcall`:idx: - is the default convention used for a Nimrod **proc**. It is the + is the default convention used for a Nim **proc**. It is the same as ``fastcall``, but only for C compilers that support ``fastcall``. `closure`:idx: @@ -1476,7 +1467,7 @@ Nimrod supports these `calling conventions`:idx:\: `inline`:idx: The inline convention means the the caller should not call the procedure, - but inline its code directly. Note that Nimrod does not inline, but leaves + but inline its code directly. Note that Nim does not inline, but leaves this to the C compiler; it generates ``__inline`` procedures. This is only a hint for the compiler: it may completely ignore it and it may inline procedures that are not marked as ``inline``. @@ -1492,7 +1483,7 @@ Nimrod supports these `calling conventions`:idx:\: `noconv`:idx: The generated C code will not have any explicit calling convention and thus use the C compiler's default calling convention. This is needed because - Nimrod's default calling convention for procedures is ``fastcall`` to + Nim's default calling convention for procedures is ``fastcall`` to improve speed. Most calling conventions exist only for the Windows 32-bit platform. @@ -1532,7 +1523,7 @@ numerical base type, for example. The following example models currencies. Different currencies should not be mixed in monetary calculations. Distinct types are a perfect tool to model different currencies: -.. code-block:: nimrod +.. code-block:: nim type TDollar = distinct int TEuro = distinct int @@ -1570,7 +1561,7 @@ should not generate all this code only to optimize it away later - after all The pragma `borrow`:idx: has been designed to solve this problem; in principle it generates the above trivial implementations: -.. code-block:: nimrod +.. code-block:: nim proc `*` (x: TDollar, y: int): TDollar {.borrow.} proc `*` (x: int, y: TDollar): TDollar {.borrow.} proc `div` (x: TDollar, y: int): TDollar {.borrow.} @@ -1582,7 +1573,7 @@ generated. But it seems all this boilerplate code needs to be repeated for the ``TEuro`` currency. This can be solved with templates_. -.. code-block:: nimrod +.. code-block:: nim template additive(typ: typedesc): stmt = proc `+` *(x, y: typ): typ {.borrow.} proc `-` *(x, y: typ): typ {.borrow.} @@ -1616,7 +1607,7 @@ currency. This can be solved with templates_. The borrow pragma can also be used to annotate the distinct type to allow certain builtin operations to be lifted: -.. code-block:: nimrod +.. code-block:: nim type Foo = object a, b: int @@ -1636,11 +1627,11 @@ Currently only the dot accessor can be borrowed in this way. Avoiding SQL injection attacks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -An SQL statement that is passed from Nimrod to an SQL database might be +An SQL statement that is passed from Nim to an SQL database might be modelled as a string. However, using string templates and filling in the values is vulnerable to the famous `SQL injection attack`:idx:\: -.. code-block:: nimrod +.. code-block:: nim import strutils proc query(db: TDbHandle, statement: string) = ... @@ -1655,7 +1646,7 @@ This can be avoided by distinguishing strings that contain SQL from strings that don't. Distinct types provide a means to introduce a new string type ``TSQL`` that is incompatible with ``string``: -.. code-block:: nimrod +.. code-block:: nim type TSQL = distinct string @@ -1672,7 +1663,7 @@ It is an essential property of abstract types that they **do not** imply a subtype relation between the abtract type and its base type. Explict type conversions from ``string`` to ``TSQL`` are allowed: -.. code-block:: nimrod +.. code-block:: nim import strutils, sequtils proc properQuote(s: string): TSQL = @@ -1703,7 +1694,7 @@ The ``void`` type denotes the absense of any type. Parameters of type ``void`` are treated as non-existent, ``void`` as a return type means that the procedure does not return a value: -.. code-block:: nimrod +.. code-block:: nim proc nothing(x, y: void): void = echo "ha" @@ -1711,7 +1702,7 @@ the procedure does not return a value: The ``void`` type is particularly useful for generic code: -.. code-block:: nimrod +.. code-block:: nim proc callProc[T](p: proc (x: T), x: T) = when T is void: p() @@ -1726,7 +1717,7 @@ The ``void`` type is particularly useful for generic code: However, a ``void`` type cannot be inferred in generic code: -.. code-block:: nimrod +.. code-block:: nim callProc(emptyProc) # Error: type mismatch: got (proc ()) # but expected one of: @@ -1745,11 +1736,11 @@ describe the type checking done by the compiler. Type equality ------------- -Nimrod uses structural type equivalence for most types. Only for objects, +Nim uses structural type equivalence for most types. Only for objects, enumerations and distinct types name equivalence is used. The following algorithm (in pseudo-code) determines type equality: -.. code-block:: nimrod +.. code-block:: nim proc typeEqualsAux(a, b: PType, s: var set[PType * PType]): bool = if (a,b) in s: return true @@ -1795,7 +1786,7 @@ The following algorithm (in pseudo-code) determines whether two types are equal with no respect to ``distinct`` types. For brevity the cycle check with an auxiliary set ``s`` is omitted: -.. code-block:: nimrod +.. code-block:: nim proc typeEqualsOrDistinct(a, b: PType): bool = if a.kind == b.kind: case a.kind @@ -1835,7 +1826,7 @@ Subtype relation If object ``a`` inherits from ``b``, ``a`` is a subtype of ``b``. This subtype relation is extended to the types ``var``, ``ref``, ``ptr``: -.. code-block:: nimrod +.. code-block:: nim proc isSubtype(a, b: PType): bool = if a.kind == b.kind: case a.kind @@ -1854,7 +1845,7 @@ Convertible relation A type ``a`` is **implicitly** convertible to type ``b`` iff the following algorithm returns true: -.. code-block:: nimrod +.. code-block:: nim # XXX range types? proc isImplicitlyConvertible(a, b: PType): bool = case a.kind @@ -1884,7 +1875,7 @@ algorithm returns true: A type ``a`` is **explicitly** convertible to type ``b`` iff the following algorithm returns true: -.. code-block:: nimrod +.. code-block:: nim proc isIntegralType(t: PType): bool = result = isOrdinal(t) or t.kind in {float, float32, float64} @@ -1898,7 +1889,7 @@ algorithm returns true: The convertible relation can be relaxed by a user-defined type `converter`:idx:. -.. code-block:: nimrod +.. code-block:: nim converter toInt(x: char): int = result = ord(x) var @@ -1932,7 +1923,7 @@ To be written. Statements and expressions ========================== -Nimrod uses the common statement/expression paradigm: Statements do not +Nim uses the common statement/expression paradigm: Statements do not produce a value in contrast to expressions. However, some expressions are statements. @@ -1960,7 +1951,7 @@ Discard statement Example: -.. code-block:: nimrod +.. code-block:: nim proc p(x, y: int): int = result = x + y @@ -1975,7 +1966,7 @@ a static error. The return value can be ignored implicitly if the called proc/iterator has been declared with the `discardable`:idx: pragma: -.. code-block:: nimrod +.. code-block:: nim proc p(x, y: int): int {.discardable.} = result = x + y @@ -1983,7 +1974,7 @@ been declared with the `discardable`:idx: pragma: An empty ``discard`` statement is often used as a null statement: -.. code-block:: nimrod +.. code-block:: nim proc classify(s: string) = case s[0] of SymChars, '_': echo "an identifier" @@ -1998,7 +1989,7 @@ Var statements declare new local and global variables and initialize them. A comma separated list of variables can be used to specify variables of the same type: -.. code-block:: nimrod +.. code-block:: nim var a: int = 0 @@ -2031,14 +2022,14 @@ T = enum cast[T](0); this may be an invalid value The implicit initialization can be avoided for optimization reasons with the `noinit`:idx: pragma: -.. code-block:: nimrod +.. code-block:: nim var a {.noInit.}: array [0..1023, char] If a proc is annotated with the ``noinit`` pragma this refers to its implicit ``result`` variable: -.. code-block:: nimrod +.. code-block:: nim proc returnUndefinedValue: int {.noinit.} = discard @@ -2047,7 +2038,7 @@ type pragma. The compiler requires an explicit initialization then. However it does a `control flow analysis`:idx: to prove the variable has been initialized and does not rely on syntactic properties: -.. code-block:: nimrod +.. code-block:: nim type TMyObject = object {.requiresInit.} @@ -2079,10 +2070,10 @@ Const section cannot change. The compiler must be able to evaluate the expression in a constant declaration at compile time. -Nimrod contains a sophisticated compile-time evaluator, so procedures which +Nim contains a sophisticated compile-time evaluator, so procedures which have no side-effect can be used in constant expressions too: -.. code-block:: nimrod +.. code-block:: nim import strutils const constEval = contains("abc", 'b') # computed at compile time! @@ -2119,7 +2110,7 @@ time. The current implementation poses some restrictions for compile time evaluation: Code which contains ``cast`` or makes use of the foreign function -interface cannot be evaluated at compile time. Later versions of Nimrod will +interface cannot be evaluated at compile time. Later versions of Nim will support the FFI at compile time. @@ -2128,7 +2119,7 @@ If statement Example: -.. code-block:: nimrod +.. code-block:: nim var name = readLine(stdin) @@ -2152,7 +2143,7 @@ The scoping for an ``if`` statement is slightly subtle to support an important use case. A new scope starts for the ``if``/``elif`` condition and ends after the corresponding *then* block: -.. code-block:: nimrod +.. code-block:: nim if {| (let m = input =~ re"(\w+)=\w+"; m.isMatch): echo "key ", m[0], " value ", m[1] |} elif {| (let m = input =~ re""; m.isMatch): @@ -2168,7 +2159,7 @@ Case statement Example: -.. code-block:: nimrod +.. code-block:: nim case readline(stdin) of "delete-everything", "restart-computer": @@ -2205,7 +2196,7 @@ As a special semantic extension, an expression in an ``of`` branch of a case statement may evaluate to a set or array constructor; the set or array is then expanded into a list of its elements: -.. code-block:: nimrod +.. code-block:: nim const SymChars: set[char] = {'a'..'z', 'A'..'Z', '\x80'..'\xFF'} @@ -2228,7 +2219,7 @@ When statement Example: -.. code-block:: nimrod +.. code-block:: nim when sizeof(int) == 2: echo("running on a 16 bit system!") @@ -2258,14 +2249,14 @@ Return statement Example: -.. code-block:: nimrod +.. code-block:: nim return 40+2 The ``return`` statement ends the execution of the current procedure. It is only allowed in procedures. If there is an ``expr``, this is syntactic sugar for: -.. code-block:: nimrod +.. code-block:: nim result = expr return result @@ -2275,7 +2266,7 @@ the proc has a return type. The `result`:idx: variable is always the return value of the procedure. It is automatically declared by the compiler. As all variables, ``result`` is initialized to (binary) zero: -.. code-block:: nimrod +.. code-block:: nim proc returnZero(): int = # implicitly returns 0 @@ -2285,7 +2276,7 @@ Yield statement Example: -.. code-block:: nimrod +.. code-block:: nim yield (1, 2, 3) The ``yield`` statement is used instead of the ``return`` statement in @@ -2301,7 +2292,7 @@ Block statement Example: -.. code-block:: nimrod +.. code-block:: nim var found = false block myblock: for i in 0..3: @@ -2322,7 +2313,7 @@ Break statement Example: -.. code-block:: nimrod +.. code-block:: nim break The ``break`` statement is used to leave a block immediately. If ``symbol`` @@ -2335,7 +2326,7 @@ While statement Example: -.. code-block:: nimrod +.. code-block:: nim echo("Please tell me your password: \n") var pw = readLine(stdin) while pw != "12345": @@ -2355,7 +2346,7 @@ A ``continue`` statement leads to the immediate next iteration of the surrounding loop construct. It is only allowed within a loop. A continue statement is syntactic sugar for a nested block: -.. code-block:: nimrod +.. code-block:: nim while expr1: stmt1 continue @@ -2363,7 +2354,7 @@ statement is syntactic sugar for a nested block: Is equivalent to: -.. code-block:: nimrod +.. code-block:: nim while expr1: block myBlockName: stmt1 @@ -2374,12 +2365,12 @@ Is equivalent to: Assembler statement ------------------- -The direct embedding of assembler code into Nimrod code is supported +The direct embedding of assembler code into Nim code is supported by the unsafe ``asm`` statement. Identifiers in the assembler code that refer to -Nimrod identifiers shall be enclosed in a special character which can be +Nim identifiers shall be enclosed in a special character which can be specified in the statement's pragmas. The default special character is ``'`'``: -.. code-block:: nimrod +.. code-block:: nim {.push stackTrace:off.} proc addInt(a, b: int): int = # a in eax, and b in edx @@ -2394,7 +2385,7 @@ specified in the statement's pragmas. The default special character is ``'`'``: If the GNU assembler is used, quotes and newlines are inserted automatically: -.. code-block:: nimrod +.. code-block:: nim proc addInt(a, b: int): int = asm """ addl %%ecx, %%eax @@ -2407,7 +2398,7 @@ If the GNU assembler is used, quotes and newlines are inserted automatically: Instead of: -.. code-block:: nimrod +.. code-block:: nim proc addInt(a, b: int): int = asm """ "addl %%ecx, %%eax\n" @@ -2425,12 +2416,12 @@ Using statement The using statement provides syntactic convenience for procs that heavily use a single contextual parameter. When applied to a variable or a -constant, it will instruct Nimrod to automatically consider the used symbol as +constant, it will instruct Nim to automatically consider the used symbol as a hidden leading parameter for any procedure calls, following the using statement in the current scope. Thus, it behaves much like the hidden `this` parameter available in some object-oriented programming languages. -.. code-block:: nimrod +.. code-block:: nim var s = socket() using s @@ -2447,7 +2438,7 @@ When applied to a callable symbol, it brings the designated symbol in the current scope. Thus, it can be used to disambiguate between imported symbols from different modules having the same name. -.. code-block:: nimrod +.. code-block:: nim import windows, sdl using sdl.SetTimer @@ -2456,7 +2447,7 @@ replace, **neither** does it create a new scope. What this means is that if one applies this to multiple variables the compiler will find conflicts in what variable to use: -.. code-block:: nimrod +.. code-block:: nim var a, b = "kill it" using a add(" with fire") @@ -2476,7 +2467,7 @@ If expression An `if expression` is almost like an if statement, but it is an expression. Example: -.. code-block:: nimrod +.. code-block:: nim var y = if x > 8: 9 else: 10 An if expression always results in a value, so the ``else`` part is @@ -2492,7 +2483,7 @@ Case expression The `case expression` is again very similar to the case statement: -.. code-block:: nimrod +.. code-block:: nim var favoriteFood = case animal of "dog": "bones" of "cat": "mice" @@ -2502,7 +2493,7 @@ The `case expression` is again very similar to the case statement: "ice cream" As seen in the above example, the case expression can also introduce side -effects. When multiple statements are given for a branch, Nimrod will use +effects. When multiple statements are given for a branch, Nim will use the last expression as the result value, much like in an `expr` template. Table constructor @@ -2510,7 +2501,7 @@ Table constructor A table constructor is syntactic sugar for an array constructor: -.. code-block:: nimrod +.. code-block:: nim {"key1": "value1", "key2", "key3": "value2"} # is the same as: @@ -2545,7 +2536,7 @@ Type casts ---------- Example: -.. code-block:: nimrod +.. code-block:: nim cast[int](x) Type casts are a crude mechanism to interpret the bit pattern of @@ -2563,7 +2554,7 @@ object on the stack and can thus reference a non-existing object. One can get the address of variables, but one can't use it on variables declared through ``let`` statements: -.. code-block:: nimrod +.. code-block:: nim let t1 = "Hello" var @@ -2582,7 +2573,7 @@ Procedures ========== What most programming languages call `methods`:idx: or `functions`:idx: are -called `procedures`:idx: in Nimrod (which is the correct terminology). A +called `procedures`:idx: in Nim (which is the correct terminology). A procedure declaration defines an identifier and associates it with a block of code. A procedure may call itself recursively. A parameter may be given a default @@ -2594,7 +2585,7 @@ variable named `result`:idx: that represents the return value. Procs can be overloaded. The overloading resolution algorithm tries to find the proc that is the best match for the arguments. Example: -.. code-block:: nimrod +.. code-block:: nim proc toLower(c: Char): Char = # toLower for characters if c in {'A'..'Z'}: @@ -2609,7 +2600,7 @@ the best match for the arguments. Example: Calling a procedure can be done in many different ways: -.. code-block:: nimrod +.. code-block:: nim proc callme(x, y: int, s: string = "", c: char, b: bool = false) = ... # call with positional arguments # parameter bindings: @@ -2627,7 +2618,7 @@ A procedure cannot modify its parameters (unless the parameters have the type `Operators`:idx: are procedures with a special operator symbol as identifier: -.. code-block:: nimrod +.. code-block:: nim proc `$` (x: int): string = # converts an integer to a string; this is a prefix operator. result = intToStr(x) @@ -2641,7 +2632,7 @@ grammar explicitly. Any operator can be called like an ordinary proc with the '`opr`' notation. (Thus an operator can have more than two parameters): -.. code-block:: nimrod +.. code-block:: nim proc `*+` (a, b, c: int): int = # Multiply and add result = a * b + c @@ -2659,7 +2650,7 @@ remaining arguments: ``obj.len`` (instead of ``len(obj)``). This method call syntax is not restricted to objects, it can be used to supply any type of first argument for procedures: -.. code-block:: nimrod +.. code-block:: nim echo("abc".len) # is the same as echo(len("abc")) echo("abc".toUpper()) @@ -2672,11 +2663,11 @@ postfix notation. Properties ---------- -Nimrod has no need for *get-properties*: Ordinary get-procedures that are called +Nim has no need for *get-properties*: Ordinary get-procedures that are called with the *method call syntax* achieve the same. But setting a value is different; for this a special setter syntax is needed: -.. code-block:: nimrod +.. code-block:: nim type TSocket* = object of TObject @@ -2707,7 +2698,7 @@ means ``echo f 1, f 2`` is parsed as ``echo(f(1), f(2))`` and not as ``echo(f(1, f(2)))``. The method call syntax may be used to provide one more argument in this case: -.. code-block:: nimrod +.. code-block:: nim proc optarg(x:int, y:int = 0):int = x + y proc singlearg(x:int):int = 20*x @@ -2744,7 +2735,7 @@ Anonymous Procs Procs can also be treated as expressions, in which case it's allowed to omit the proc's name. -.. code-block:: nimrod +.. code-block:: nim var cities = @["Frankfurt", "Tokyo", "New York"] cities.sort(proc (x,y: string): int = @@ -2761,7 +2752,7 @@ Do notation As a special more convenient notation, proc expressions involved in procedure calls can use the ``do`` keyword: -.. code-block:: nimrod +.. code-block:: nim sort(cities) do (x,y: string) -> int: cmp(x.len, y.len) # Less parenthesis using the method plus command syntax: @@ -2773,7 +2764,7 @@ The proc expression represented by the do block is appended to them. More than one ``do`` block can appear in a single call: -.. code-block:: nimrod +.. code-block:: nim proc performWithUndo(task: proc(), undo: proc()) = ... performWithUndo do: @@ -2806,7 +2797,7 @@ Var parameters -------------- The type of a parameter may be prefixed with the ``var`` keyword: -.. code-block:: nimrod +.. code-block:: nim proc divmod(a, b: int; res, remainder: var int) = res = a div b remainder = a mod b @@ -2824,7 +2815,7 @@ visible to the caller. The argument passed to a var parameter has to be an l-value. Var parameters are implemented as hidden pointers. The above example is equivalent to: -.. code-block:: nimrod +.. code-block:: nim proc divmod(a, b: int; res, remainder: ptr int) = res[] = a div b remainder[] = a mod b @@ -2838,7 +2829,7 @@ above example is equivalent to: In the examples, var parameters or pointers are used to provide two return values. This can be done in a cleaner way by returning a tuple: -.. code-block:: nimrod +.. code-block:: nim proc divmod(a, b: int): tuple[res, remainder: int] = (a div b, a mod b) @@ -2849,7 +2840,7 @@ return values. This can be done in a cleaner way by returning a tuple: One can use `tuple unpacking`:idx: to access the tuple's fields: -.. code-block:: nimrod +.. code-block:: nim var (x, y) = divmod(8, 5) # tuple unpacking assert x == 1 assert y == 3 @@ -2861,7 +2852,7 @@ Var return type A proc, converter or iterator may return a ``var`` type which means that the returned value is an l-value and can be modified by the caller: -.. code-block:: nimrod +.. code-block:: nim var g = 0 proc WriteAccessToG(): var int = @@ -2873,14 +2864,14 @@ returned value is an l-value and can be modified by the caller: It is a compile time error if the implicitly introduced pointer could be used to access a location beyond its lifetime: -.. code-block:: nimrod +.. code-block:: nim proc WriteAccessToG(): var int = var g = 0 result = g # Error! For iterators, a component of a tuple return type can have a ``var`` type too: -.. code-block:: nimrod +.. code-block:: nim iterator mpairs(a: var seq[string]): tuple[key: int, val: var string] = for i in 0..a.high: yield (i, a[i]) @@ -2901,7 +2892,7 @@ Multi-methods Procedures always use static dispatch. Multi-methods use dynamic dispatch. -.. code-block:: nimrod +.. code-block:: nim type TExpr = object ## abstract base class for an expression TLiteral = object of TExpr @@ -2937,7 +2928,7 @@ requires dynamic binding. In a multi-method all parameters that have an object type are used for the dispatching: -.. code-block:: nimrod +.. code-block:: nim type TThing = object TUnit = object of TThing @@ -2961,7 +2952,7 @@ Invocation of a multi-method cannot be ambiguous: collide 2 is preferred over collide 1 because the resolution works from left to right. In the example ``TUnit, TThing`` is preferred over ``TThing, TUnit``. -**Performance note**: Nimrod does not produce a virtual method table, but +**Performance note**: Nim does not produce a virtual method table, but generates dispatch trees. This avoids the expensive indirect branch for method calls and enables inlining. However, other optimizations like compile time evaluation or dead code elimination do not work with methods. @@ -2987,7 +2978,7 @@ reached the data is bound to the ``for`` loop variables and control continues in the body of the ``for`` loop. The iterator's local variables and execution state are automatically saved between calls. Example: -.. code-block:: nimrod +.. code-block:: nim # this definition exists in the system module iterator items*(a: string): char {.inline.} = var i = 0 @@ -3000,7 +2991,7 @@ state are automatically saved between calls. Example: The compiler generates code as if the programmer would have written this: -.. code-block:: nimrod +.. code-block:: nim var i = 0 while i < len(a): var ch = a[i] @@ -3019,7 +3010,7 @@ If the for loop expression ``e`` does not denote an iterator and the for loop has exactly 1 variable, the for loop expression is rewritten to ``items(e)``; ie. an ``items`` iterator is implicitly invoked: -.. code-block:: nimrod +.. code-block:: nim for x in [1,2,3]: echo x If the for loop has exactly 2 variables, a ``pairs`` iterator is implicitly @@ -3033,7 +3024,7 @@ into account. First class iterators --------------------- -There are 2 kinds of iterators in Nimrod: *inline* and *closure* iterators. +There are 2 kinds of iterators in Nim: *inline* and *closure* iterators. An `inline iterator`:idx: is an iterator that's always inlined by the compiler leading to zero overhead for the abstraction, but may result in a heavy increase in code size. Inline iterators are second class citizens; @@ -3042,7 +3033,7 @@ templates, macros and other inline iterators. In contrast to that, a `closure iterator`:idx: can be passed around more freely: -.. code-block:: nimrod +.. code-block:: nim iterator count0(): int {.closure.} = yield 0 @@ -3073,7 +3064,7 @@ The ``iterator`` type is always of the calling convention ``closure`` implicitly; the following example shows how to use iterators to implement a `collaborative tasking`:idx: system: -.. code-block:: nimrod +.. code-block:: nim # simple tasking: type TTask = iterator (ticker: int) @@ -3112,7 +3103,7 @@ Closure iterators are *resumable functions* and so one has to provide the arguments to every call. To get around this limitation one can capture parameters of an outer factory proc: -.. code-block:: nimrod +.. code-block:: nim proc mycount(a, b: int): iterator (): int = result = iterator (): int = var x = a @@ -3139,7 +3130,7 @@ Type sections Example: -.. code-block:: nimrod +.. code-block:: nim type # example demonstrating mutually recursive types PNode = ref TNode # a traced pointer to a TNode TNode = object @@ -3166,7 +3157,7 @@ Try statement Example: -.. code-block:: nimrod +.. code-block:: nim # read the first two lines of a text file that should contain numbers # and tries to add them var @@ -3214,7 +3205,7 @@ Except and finally statements Any statements following them in the current block will be considered to be in an implicit try block: -.. code-block:: nimrod +.. code-block:: nim var f = open("numbers.txt") finally: close(f) ... @@ -3224,7 +3215,7 @@ type of the exception, one has to catch everything. Also, if one wants to use both ``finally`` and ``except`` one needs to reverse the usual sequence of the statements. Example: -.. code-block:: nimrod +.. code-block:: nim proc test() = raise newException(E_base, "Hey ho") @@ -3242,7 +3233,7 @@ Raise statement Example: -.. code-block:: nimrod +.. code-block:: nim raise newEOS("operating system failed") Apart from built-in operations like array indexing, memory allocation, etc. @@ -3265,7 +3256,7 @@ called within the ``try`` statement that should be affected. This allows for a Lisp-like `condition system`:idx:\: -.. code-block:: nimrod +.. code-block:: nim var myFile = open("broken.txt", fmWrite) try: onRaise do (e: ref E_Base)-> bool: @@ -3290,18 +3281,18 @@ Effect system Exception tracking ------------------ -Nimrod supports exception tracking. The `raises`:idx: pragma can be used +Nim supports exception tracking. The `raises`:idx: pragma can be used to explicitly define which exceptions a proc/iterator/method/converter is allowed to raise. The compiler verifies this: -.. code-block:: nimrod +.. code-block:: nim proc p(what: bool) {.raises: [EIO, EOS].} = if what: raise newException(EIO, "IO") else: raise newException(EOS, "OS") An empty ``raises`` list (``raises: []``) means that no exception may be raised: -.. code-block:: nimrod +.. code-block:: nim proc p(): bool {.raises: [].} = try: unsafeCall() @@ -3313,7 +3304,7 @@ An empty ``raises`` list (``raises: []``) means that no exception may be raised: A ``raises`` list can also be attached to a proc type. This affects type compatibility: -.. code-block:: nimrod +.. code-block:: nim type TCallback = proc (s: string) {.raises: [EIO].} var @@ -3348,7 +3339,7 @@ possibly raised exceptions; the algorithm operates on ``p``'s call graph: Rules 1-2 ensure the following works: -.. code-block:: nimrod +.. code-block:: nim proc noRaise(x: proc()) {.raises: [].} = # unknown call that might raise anything, but valid: x() @@ -3367,11 +3358,11 @@ conservative in its effect analysis. Tag tracking ------------ -The exception tracking is part of Nimrod's `effect system`:idx:. Raising an +The exception tracking is part of Nim's `effect system`:idx:. Raising an exception is an *effect*. Other effects can also be defined. A user defined effect is a means to *tag* a routine and to perform checks against this tag: -.. code-block:: nimrod +.. code-block:: nim type IO = object ## input/output effect proc readLine(): string {.tags: [IO].} @@ -3402,7 +3393,7 @@ The ``effects`` pragma has been designed to assist the programmer with the effects analysis. It is a statement that makes the compiler output all inferred effects up to the ``effects``'s position: -.. code-block:: nimrod +.. code-block:: nim proc p(what: bool) = if what: raise newException(EIO, "IO") @@ -3419,7 +3410,7 @@ Generics Example: -.. code-block:: nimrod +.. code-block:: nim type TBinaryTree[T] = object # TBinaryTree is a generic type with # with generic param ``T`` @@ -3467,7 +3458,7 @@ Example: for str in inorder(root): writeln(stdout, str) -Generics are Nimrod's means to parametrize procs, iterators or types with +Generics are Nim's means to parametrize procs, iterators or types with `type parameters`:idx:. Depending on context, the brackets are used either to introduce type parameters or to instantiate a generic proc, iterator or type. @@ -3478,7 +3469,7 @@ Is operator The ``is`` operator checks for type equivalence at compile time. It is therefore very useful for type specialization within generic code: -.. code-block:: nimrod +.. code-block:: nim type TTable[TKey, TValue] = object keys: seq[TKey] @@ -3493,7 +3484,7 @@ Type operator The ``type`` (in many other languages called `typeof`:idx:) operator can be used to get the type of an expression: -.. code-block:: nimrod +.. code-block:: nim var x = 0 var y: type(x) # y has type int @@ -3502,7 +3493,7 @@ call ``c(X)`` (where ``X`` stands for a possibly empty list of arguments), the interpretation where ``c`` is an iterator is preferred over the other interpretations: -.. code-block:: nimrod +.. code-block:: nim import strutils # strutils contains both a ``split`` proc and iterator, but since an @@ -3515,7 +3506,7 @@ Type Classes A type class is a special pseudo-type that can be used to match against types in the context of overload resolution or the ``is`` operator. -Nimrod supports the following built-in type classes: +Nim supports the following built-in type classes: ================== =================================================== type class matches @@ -3541,7 +3532,7 @@ name that will match any instantiation of the generic type. Type classes can be combined using the standard boolean operators to form more complex type classes: -.. code-block:: nimrod +.. code-block:: nim # create a type class that will match all tuple and object types type TRecordType = tuple or object @@ -3553,10 +3544,10 @@ Procedures utilizing type classes in such manner are considered to be `implicitly generic`:idx:. They will be instantiated once for each unique combination of param types used within the program. -Nimrod also allows for type classes and regular types to be specified +Nim also allows for type classes and regular types to be specified as `type constraints`:idx: of the generic type parameter: -.. code-block:: nimrod +.. code-block:: nim proc onlyIntOrString[T: int|string](x, y: T) = discard onlyIntOrString(450, 616) # valid @@ -3567,7 +3558,7 @@ By default, during overload resolution each named type class will bind to exactly one concrete type. Here is an example taken directly from the system module to illustrate this: -.. code-block:: nimrod +.. code-block:: nim proc `==`*(x, y: tuple): bool = ## requires `x` and `y` to be of the same tuple type ## generic ``==`` operator for tuples that is lifted from the components @@ -3579,10 +3570,10 @@ module to illustrate this: Alternatively, the ``distinct`` type modifier can be applied to the type class to allow each param matching the type class to bind to a different type. -If a proc param doesn't have a type specified, Nimrod will use the +If a proc param doesn't have a type specified, Nim will use the ``distinct auto`` type class (also known as ``any``): -.. code-block:: nimrod +.. code-block:: nim # allow any combination of param types proc concat(a, b): string = $a & $b @@ -3590,7 +3581,7 @@ Procs written with the implicitly generic style will often need to refer to the type parameters of the matched generic type. They can be easily accessed using the dot syntax: -.. code-block:: nimrod +.. code-block:: nim type TMatrix[T, Rows, Columns] = object ... @@ -3603,7 +3594,7 @@ effect when anonymous or distinct type classes are used. When a generic type is instantiated with a type class instead of a concrete type, this results in another more specific type class: -.. code-block:: nimrod +.. code-block:: nim seq[ref object] # Any sequence storing references to any object type type T1 = auto @@ -3630,7 +3621,7 @@ matched type must satisfy. Declarative type classes are written in the following form: -.. code-block:: nimrod +.. code-block:: nim type Comparable = generic x, y (x < y) is bool @@ -3661,7 +3652,7 @@ type value appearing in a callable expression will be treated as a variable of the designated type for overload resolution purposes, unless the type value was passed in its explicit ``typedesc[T]`` form: -.. code-block:: nimrod +.. code-block:: nim type OutputStream = generic S write(var S, string) @@ -3671,23 +3662,29 @@ once for each tested type and any static code included within them will also be executed once. -Return Type Inference ---------------------- +Type inference with type classes +-------------------------------- If a type class is used as the return type of a proc and it won't be bound to -a concrete type by some of the proc params, Nimrod will infer the return type +a concrete type by some of the proc params, Nim will infer the return type from the proc body. This is usually used with the ``auto`` type class: -.. code-block:: nimrod +.. code-block:: nim proc makePair(a, b): auto = (first: a, second: b) -The return type will be treated as additional generic param and can be +The return type will be treated as an additional generic param and can be explicitly specified at call sites as any other generic param. -Future versions of Nimrod may also support overloading based on the return type +Future versions of Nim may also support overloading based on the return type of the overloads. In such settings, the expected result type at call sites may also influence the inferred return type. +.. + Likewise, if a type class is used in another position where Nim expects a + concrete type (e.g. a variable declaration or a type coercion), Nim will try + to infer the concrete type by applying the matching algorithm that also used + in overload resolution. + Symbol lookup in generics ------------------------- @@ -3700,7 +3697,7 @@ and every other symbol is closed. Open symbols are looked up in two different contexts: Both the context at definition and the context at instantiation are considered: -.. code-block:: nimrod +.. code-block:: nim type TIndex = distinct int @@ -3719,7 +3716,7 @@ too. A symbol can be forced to be open by a `mixin`:idx: declaration: -.. code-block:: nimrod +.. code-block:: nim proc create*[T](): ref T = # there is no overloaded 'init' here, so we need to state that it's an # open symbol explicitly: @@ -3736,7 +3733,7 @@ can be used to explicitly declare identifiers that should be bound early (i.e. the identifiers should be looked up in the scope of the template/generic definition): -.. code-block:: nimrod +.. code-block:: nim # Module A var lastId = 0 @@ -3746,7 +3743,7 @@ definition): inc(lastId) lastId -.. code-block:: nimrod +.. code-block:: nim # Module B import A @@ -3760,14 +3757,14 @@ Templates ========= A template is a simple form of a macro: It is a simple substitution -mechanism that operates on Nimrod's abstract syntax trees. It is processed in +mechanism that operates on Nim's abstract syntax trees. It is processed in the semantic pass of the compiler. The syntax to *invoke* a template is the same as calling a procedure. Example: -.. code-block:: nimrod +.. code-block:: nim template `!=` (a, b: expr): expr = # this definition exists in the System module not (a == b) @@ -3796,7 +3793,7 @@ ordinary templates. Ordinary templates take part in overloading resolution. As such their arguments need to be type checked before the template is invoked. So ordinary templates cannot receive undeclared identifiers: -.. code-block:: nimrod +.. code-block:: nim template declareInt(x: expr) = var x: int @@ -3807,7 +3804,7 @@ An ``immediate`` template does not participate in overload resolution and so its arguments are not checked for semantics before invocation. So they can receive undeclared identifiers: -.. code-block:: nimrod +.. code-block:: nim template declareInt(x: expr) {.immediate.} = var x: int @@ -3822,7 +3819,7 @@ If there is a ``stmt`` parameter it should be the last in the template declaration, because statements are passed to a template via a special ``:`` syntax: -.. code-block:: nimrod +.. code-block:: nim template withFile(f, fn, mode: expr, actions: stmt): stmt {.immediate.} = var f: TFile @@ -3848,7 +3845,7 @@ Symbol binding in templates A template is a `hygienic`:idx: macro and so opens a new scope. Most symbols are bound from the definition scope of the template: -.. code-block:: nimrod +.. code-block:: nim # Module A var lastId = 0 @@ -3857,7 +3854,7 @@ bound from the definition scope of the template: inc(lastId) lastId -.. code-block:: nimrod +.. code-block:: nim # Module B import A @@ -3873,7 +3870,7 @@ Identifier construction In templates identifiers can be constructed with the backticks notation: -.. code-block:: nimrod +.. code-block:: nim template typedef(name: expr, typ: typedesc) {.immediate.} = type @@ -3894,7 +3891,7 @@ A parameter ``p`` in a template is even substituted in the expression ``x.p``. Thus template arguments can be used as field names and a global symbol can be shadowed by the same argument name even when fully qualified: -.. code-block:: nimrod +.. code-block:: nim # module 'm' type @@ -3911,7 +3908,7 @@ shadowed by the same argument name even when fully qualified: But the global symbol can properly be captured by a ``bind`` statement: -.. code-block:: nimrod +.. code-block:: nim # module 'm' type @@ -3934,7 +3931,7 @@ Hygiene in templates Per default templates are `hygienic`:idx:\: Local identifiers declared in a template cannot be accessed in the instantiation context: -.. code-block:: nimrod +.. code-block:: nim template newException*(exceptn: typedesc, message: string): expr = var @@ -3957,7 +3954,7 @@ is ``gensym`` and for ``proc``, ``iterator``, ``converter``, ``template``, ``macro`` is ``inject``. However, if the name of the entity is passed as a template parameter, it is an inject'ed symbol: -.. code-block:: nimrod +.. code-block:: nim template withFile(f, fn, mode: expr, actions: stmt): stmt {.immediate.} = block: var f: TFile # since 'f' is a template param, it's injected implicitly @@ -3971,7 +3968,7 @@ template parameter, it is an inject'ed symbol: The ``inject`` and ``gensym`` pragmas are second class annotations; they have no semantics outside of a template definition and cannot be abstracted over: -.. code-block:: nimrod +.. code-block:: nim {.pragma myInject: inject.} template t() = @@ -3991,10 +3988,10 @@ to implement `domain specific languages`:idx:. Like templates, macros come in the 2 flavors *immediate* and *ordinary*. While macros enable advanced compile-time code transformations, they -cannot change Nimrod's syntax. However, this is no real restriction because -Nimrod's syntax is flexible enough anyway. +cannot change Nim's syntax. However, this is no real restriction because +Nim's syntax is flexible enough anyway. -To write macros, one needs to know how the Nimrod concrete syntax is converted +To write macros, one needs to know how the Nim concrete syntax is converted to an abstract syntax tree. There are two ways to invoke a macro: @@ -4008,13 +4005,13 @@ Expression Macros The following example implements a powerful ``debug`` command that accepts a variable number of arguments: -.. code-block:: nimrod - # to work with Nimrod syntax trees, we need an API that is defined in the +.. code-block:: nim + # to work with Nim syntax trees, we need an API that is defined in the # ``macros`` module: import macros macro debug(n: varargs[expr]): stmt = - # `n` is a Nimrod AST that contains the whole macro invocation + # `n` is a Nim AST that contains the whole macro invocation # this macro returns a list of statements: result = newNimNode(nnkStmtList, n) # iterate over any argument that is passed to this macro: @@ -4037,7 +4034,7 @@ variable number of arguments: The macro call expands to: -.. code-block:: nimrod +.. code-block:: nim write(stdout, "a[0]") write(stdout, ": ") writeln(stdout, a[0]) @@ -4065,7 +4062,7 @@ instantiating context. There is a way to use bound identifiers (aka `symbols`:idx:) instead of using unbound identifiers. The ``bindSym`` builtin can be used for that: -.. code-block:: nimrod +.. code-block:: nim import macros macro debug(n: varargs[expr]): stmt = @@ -4086,7 +4083,7 @@ builtin can be used for that: The macro call expands to: -.. code-block:: nimrod +.. code-block:: nim write(stdout, "a[0]") write(stdout, ": ") writeln(stdout, a[0]) @@ -4113,7 +4110,7 @@ invoked by an expression following a colon. The following example outlines a macro that generates a lexical analyzer from regular expressions: -.. code-block:: nimrod +.. code-block:: nim import macros macro case_token(n: stmt): stmt = @@ -4147,14 +4144,14 @@ Macros as pragmas Whole routines (procs, iterators etc.) can also be passed to a template or a macro via the pragma notation: -.. code-block:: nimrod +.. code-block:: nim template m(s: stmt) = discard proc p() {.m.} = discard This is a simple syntactic transformation into: -.. code-block:: nimrod +.. code-block:: nim template m(s: stmt) = discard m: @@ -4171,7 +4168,7 @@ static[T] As their name suggests, static params must be known at compile-time: -.. code-block:: nimrod +.. code-block:: nim proc precompiledRegex(pattern: static[string]): TRegEx = var res {.global.} = re(pattern) @@ -4193,7 +4190,7 @@ used to declare procs accepting both static and run-time values, which can optimize their body according to the supplied param using the `isStatic(p)` predicate: -.. code-block:: nimrod +.. code-block:: nim # The following proc will be compiled once for each unique static # value and also once for the case handling all run-time values: @@ -4206,7 +4203,7 @@ predicate: Static params can also appear in the signatures of generic types: -.. code-block:: nimrod +.. code-block:: nim type Matrix[M,N: static[int]; T: Number] = array[0..(M*N - 1), T] @@ -4231,7 +4228,7 @@ When used as a regular proc param, typedesc acts as a type class. The proc will be instantiated for each unique type parameter and one can refer to the instantiation type using the param name: -.. code-block:: nimrod +.. code-block:: nim proc new(T: typedesc): ref T = echo "allocating ", T.name @@ -4244,7 +4241,7 @@ When multiple typedesc params are present, they act like a distinct type class (i.e. they will bind freely to different types). To force a bind-once behavior one can use a named alias or an explicit `typedesc` generic param: -.. code-block:: nimrod +.. code-block:: nim # `type1` and `type2` are aliases for typedesc available from system.nim proc acceptOnlyTypePairs(A, B: type1; C, D: type2) @@ -4252,7 +4249,7 @@ one can use a named alias or an explicit `typedesc` generic param: Once bound, typedesc params can appear in the rest of the proc signature: -.. code-block:: nimrod +.. code-block:: nim template declareVariableWithType(T: typedesc, value: T) = var x: T = value @@ -4266,7 +4263,7 @@ typedesc acts as any other type. One can create variables, store typedesc values inside containers and so on. For example, here is how one can create a type-safe wrapper for the unsafe `printf` function from C: -.. code-block:: nimrod +.. code-block:: nim macro safePrintF(formatString: string{lit}, args: varargs[expr]): expr = var i = 0 for c in formatChars(formatString): @@ -4295,7 +4292,7 @@ a type-safe wrapper for the unsafe `printf` function from C: Overload resolution can be further influenced by constraining the set of types that will match the typedesc param: -.. code-block:: nimrod +.. code-block:: nim template maxval(T: typedesc[int]): int = high(int) template maxval(T: typedesc[float]): float = Inf @@ -4313,27 +4310,27 @@ Special Operators dot operators ------------- -Nimrod offers a special family of dot operators that can be used to +Nim offers a special family of dot operators that can be used to intercept and rewrite proc call and field access attempts, referring to previously undeclared symbol names. They can be used to provide a fluent interface to objects lying outside the static confines of the type system such as values from dynamic scripting languages or dynamic file formats such as JSON or XML. -When Nimrod encounters an expression that cannot be resolved by the +When Nim encounters an expression that cannot be resolved by the standard overload resolution rules, the current scope will be searched for a dot operator that can be matched against a re-written form of the expression, where the unknown field or proc name is converted to an additional static string parameter: -.. code-block:: nimrod +.. code-block:: nim a.b # becomes `.`(a, "b") a.b(c, d) # becomes `.`(a, "b", c, d) The matched dot operators can be symbols of any callable kind (procs, templates and macros), depending on the desired effect: -.. code-block:: nimrod +.. code-block:: nim proc `.` (js: PJsonNode, field: string): JSON = js[field] var js = parseJson("{ x: 1, y: 2}") @@ -4357,7 +4354,7 @@ operator `.=` ------------- This operator will be matched against assignments to missing fields. -.. code-block:: nimrod +.. code-block:: nim a.b = c # becomes `.=`(a, "b", c) @@ -4408,7 +4405,7 @@ destructors in both user-defined and generated destructors will be inserted. A destructor is attached to the type it destructs; expressions of this type can then only be used in *destructible contexts* and as parameters: -.. code-block:: nimrod +.. code-block:: nim type TMyObj = object x, y: int @@ -4460,7 +4457,7 @@ language may weaken this restriction.) The signature has to be: -.. code-block:: nimrod +.. code-block:: nim proc deepCopy(x: T): T {.override.} This mechanism is used by most data structures that support shared memory like @@ -4478,7 +4475,7 @@ a *name* but also a *pattern* that is searched for after the semantic checking phase of the compiler: This means they provide an easy way to enhance the compilation pipeline with user defined optimizations: -.. code-block:: nimrod +.. code-block:: nim template optMul{`*`(a, 2)}(a: int): int = a+a let x = 3 @@ -4494,7 +4491,7 @@ needs to be used. Unfortunately optimizations are hard to get right and even the tiny example is **wrong**: -.. code-block:: nimrod +.. code-block:: nim template optMul{`*`(a, 2)}(a: int): int = a+a proc f(): int = @@ -4504,9 +4501,9 @@ is **wrong**: echo f() * 2 We cannot duplicate 'a' if it denotes an expression that has a side effect! -Fortunately Nimrod supports side effect analysis: +Fortunately Nim supports side effect analysis: -.. code-block:: nimrod +.. code-block:: nim template optMul{`*`(a, 2)}(a: int{noSideEffect}): int = a+a proc f(): int = @@ -4519,12 +4516,12 @@ So what about ``2 * a``? We should tell the compiler ``*`` is commutative. We cannot really do that however as the following code only swaps arguments blindly: -.. code-block:: nimrod +.. code-block:: nim template mulIsCommutative{`*`(a, b)}(a, b: int): int = b*a What optimizers really need to do is a *canonicalization*: -.. code-block:: nimrod +.. code-block:: nim template canonMul{`*`(a, b)}(a: int{lit}, b: int): int = b*a The ``int{lit}`` parameter pattern matches against an expression of @@ -4581,7 +4578,7 @@ The ``alias`` and ``noalias`` predicates refer not only to the matching AST, but also to every other bound parameter; syntactially they need to occur after the ordinary AST predicates: -.. code-block:: nimrod +.. code-block:: nim template ex{a = b + c}(a: int{noalias}, b, c: int) = # this transformation is only valid if 'b' and 'c' do not alias 'a': a = b @@ -4600,7 +4597,7 @@ The ``|`` operator The ``|`` operator if used as infix operator creates an ordered choice: -.. code-block:: nimrod +.. code-block:: nim template t{0|1}(): expr = 3 let a = 1 # outputs 3: @@ -4609,7 +4606,7 @@ The ``|`` operator if used as infix operator creates an ordered choice: The matching is performed after the compiler performed some optimizations like constant folding, so the following does not work: -.. code-block:: nimrod +.. code-block:: nim template t{0|1}(): expr = 3 # outputs 1: echo 1 @@ -4626,7 +4623,7 @@ The ``{}`` operator A pattern expression can be bound to a pattern parameter via the ``expr{param}`` notation: -.. code-block:: nimrod +.. code-block:: nim template t{(0|1|2){x}}(x: expr): expr = x+1 let a = 1 # outputs 2: @@ -4638,7 +4635,7 @@ The ``~`` operator The ``~`` operator is the **not** operator in patterns: -.. code-block:: nimrod +.. code-block:: nim template t{x = (~x){y} and (~x){z}}(x, y, z: bool): stmt = x = y if x: x = z @@ -4657,7 +4654,7 @@ The ``*`` operator The ``*`` operator can *flatten* a nested binary expression like ``a & b & c`` to ``&(a, b, c)``: -.. code-block:: nimrod +.. code-block:: nim var calls = 0 @@ -4681,7 +4678,7 @@ is passed to ``optConc`` in ``a`` as a special list (of kind ``nkArgList``) which is flattened into a call expression; thus the invocation of ``optConc`` produces: -.. code-block:: nimrod +.. code-block:: nim `&&`("my", space & "awe", "some ", "concat") @@ -4691,7 +4688,7 @@ The ``**`` operator The ``**`` is much like the ``*`` operator, except that it gathers not only all the arguments, but also the matched operators in reverse polish notation: -.. code-block:: nimrod +.. code-block:: nim import macros type @@ -4735,7 +4732,7 @@ Parameters in a pattern are type checked in the matching process. If a parameter is of the type ``varargs`` it is treated specially and it can match 0 or more arguments in the AST to be matched against: -.. code-block:: nimrod +.. code-block:: nim template optWrite{ write(f, x) ((write|writeln){w})(f, y) @@ -4750,7 +4747,7 @@ Example: Partial evaluation The following example shows how some simple partial evaluation can be implemented with term rewriting: -.. code-block:: nimrod +.. code-block:: nim proc p(x, y: int; cond: bool): int = result = if cond: x + y else: x - y @@ -4763,7 +4760,7 @@ Example: Hoisting The following example shows how some form of hoisting can be implemented: -.. code-block:: nimrod +.. code-block:: nim import pegs template optPeg{peg(pattern)}(pattern: string{lit}): TPeg = @@ -4786,7 +4783,7 @@ AST based overloading Parameter constraints can also be used for ordinary routine parameters; these constraints affect ordinary overloading resolution then: -.. code-block:: nimrod +.. code-block:: nim proc optLit(a: string{lit|`const`}) = echo "string literal" proc optLit(a: string) = @@ -4812,7 +4809,7 @@ Move optimization The ``call`` constraint is particularly useful to implement a move optimization for types that have copying semantics: -.. code-block:: nimrod +.. code-block:: nim proc `[]=`*(t: var TTable, key: string, val: string) = ## puts a (key, value)-pair into `t`. The semantics of string require ## a copy here: @@ -4835,7 +4832,7 @@ optimization for types that have copying semantics: Modules ======= -Nimrod supports splitting a program into pieces by a module concept. +Nim supports splitting a program into pieces by a module concept. Each module needs to be in its own file and has its own `namespace`:idx:. Modules enable `information hiding`:idx: and `separate compilation`:idx:. A module may gain access to symbols of another module by the `import`:idx: @@ -4852,7 +4849,7 @@ The algorithm for compiling modules is: This is best illustrated by an example: -.. code-block:: nimrod +.. code-block:: nim # Module A type T1* = int # Module A exports the type ``T1`` @@ -4864,7 +4861,7 @@ This is best illustrated by an example: main() -.. code-block:: nimrod +.. code-block:: nim # Module B import A # A is not parsed here! Only the already known symbols # of A are imported. @@ -4881,7 +4878,7 @@ Import statement After the ``import`` statement a list of module names can follow or a single module name followed by an ``except`` to prevent some symbols to be imported: -.. code-block:: nimrod +.. code-block:: nim import strutils except `%` # doesn't work then: @@ -4893,7 +4890,7 @@ Module names in imports A module alias can be introduced via the ``as`` keyword: -.. code-block:: nimrod +.. code-block:: nim import strutils as su, sequtils as qu echo su.format("$1", "lalelu") @@ -4902,19 +4899,19 @@ The original module name is then not accessible. The notations ``path/to/module`` or ``path.to.module`` or ``"path/to/module"`` can be used to refer to a module in subdirectories: -.. code-block:: nimrod +.. code-block:: nim import lib.pure.strutils, lib/pure/os, "lib/pure/times" Note that the module name is still ``strutils`` and not ``lib.pure.strutils`` and so one **cannot** do: -.. code-block:: nimrod +.. code-block:: nim import lib.pure.strutils echo lib.pure.strutils Likewise the following does not make sense as the name is ``strutils`` already: -.. code-block:: nimrod +.. code-block:: nim import lib.pure.strutils as strutils @@ -4925,7 +4922,7 @@ After the ``from`` statement a module name follows followed by an ``import`` to list the symbols one likes to use without explict full qualification: -.. code-block:: nimrod +.. code-block:: nim from strutils import `%` echo "$1" % "abc" @@ -4943,11 +4940,11 @@ Export statement An ``export`` statement can be used for symbol fowarding so that client modules don't need to import a module's dependencies: -.. code-block:: nimrod +.. code-block:: nim # module B type TMyObject* = object -.. code-block:: nimrod +.. code-block:: nim # module A import B export B.TMyObject @@ -4955,7 +4952,7 @@ modules don't need to import a module's dependencies: proc `$`*(x: TMyObject): string = "my object" -.. code-block:: nimrod +.. code-block:: nim # module C import A @@ -5002,15 +4999,15 @@ If a module imports an identifier by two different modules, each occurrence of the identifier has to be qualified, unless it is an overloaded procedure or iterator in which case the overloading resolution takes place: -.. code-block:: nimrod +.. code-block:: nim # Module A var x*: string -.. code-block:: nimrod +.. code-block:: nim # Module B var x*: int -.. code-block:: nimrod +.. code-block:: nim # Module C import A, B write(stdout, x) # error: x is ambiguous @@ -5023,7 +5020,7 @@ iterator in which case the overloading resolution takes place: Compiler Messages ================= -The Nimrod compiler emits different kinds of messages: `hint`:idx:, +The Nim compiler emits different kinds of messages: `hint`:idx:, `warning`:idx:, and `error`:idx: messages. An *error* message is emitted if the compiler encounters any static error. @@ -5031,7 +5028,7 @@ the compiler encounters any static error. Pragmas ======= -Pragmas are Nimrod's method to give the compiler additional information / +Pragmas are Nim's method to give the compiler additional information / commands without introducing a massive number of new keywords. Pragmas are processed on the fly during semantic checking. Pragmas are enclosed in the special ``{.`` and ``.}`` curly brackets. Pragmas are also often used as a @@ -5056,7 +5053,7 @@ routines marked as ``noSideEffect``. **Future directions**: ``func`` may become a keyword and syntactic sugar for a proc with no side effects: -.. code-block:: nimrod +.. code-block:: nim func `+` (x, y: int): int @@ -5097,7 +5094,7 @@ The ``acyclic`` pragma can be used for object types to mark them as acyclic even though they seem to be cyclic. This is an **optimization** for the garbage collector to not consider objects of this type as part of a cycle: -.. code-block:: nimrod +.. code-block:: nim type PNode = ref TNode TNode {.acyclic, final.} = object @@ -5114,7 +5111,7 @@ memory, but nothing worse happens. **Future directions**: The ``acyclic`` pragma may become a property of a ``ref`` type: -.. code-block:: nimrod +.. code-block:: nim type PNode = acyclic ref TNode TNode = object @@ -5133,11 +5130,11 @@ shallow pragma The ``shallow`` pragma affects the semantics of a type: The compiler is allowed to make a shallow copy. This can cause serious semantic issues and break memory safety! However, it can speed up assignments considerably, -because the semantics of Nimrod require deep copying of sequences and strings. +because the semantics of Nim require deep copying of sequences and strings. This can be expensive, especially if sequences are used to build a tree structure: -.. code-block:: nimrod +.. code-block:: nim type TNodeKind = enum nkLeaf, nkInner TNode {.final, shallow.} = object @@ -5177,7 +5174,7 @@ annotate a symbol (like an iterator or proc). The *usage* of the symbol then triggers a compile-time error. This is especially useful to rule out that some operation is valid due to overloading and type conversions: -.. code-block:: nimrod +.. code-block:: nim ## check that underlying int values are compared and not the pointers: proc `==`(x, y: ptr int): bool {.error.} @@ -5188,7 +5185,7 @@ The ``fatal`` pragma is used to make the compiler output an error message with the given content. In contrast to the ``error`` pragma, compilation is guaranteed to be aborted by this pragma. Example: -.. code-block:: nimrod +.. code-block:: nim when not defined(objc): {.fatal: "Compile this program with the objc command!".} @@ -5207,7 +5204,7 @@ line pragma The ``line`` pragma can be used to affect line information of the annotated statement as seen in stack backtraces: -.. code-block:: nimrod +.. code-block:: nim template myassert*(cond: expr, msg = "") = if not cond: @@ -5223,10 +5220,10 @@ If the ``line`` pragma is used with a parameter, the parameter needs be a linearScanEnd pragma -------------------- The ``linearScanEnd`` pragma can be used to tell the compiler how to -compile a Nimrod `case`:idx: statement. Syntactically it has to be used as a +compile a Nim `case`:idx: statement. Syntactically it has to be used as a statement: -.. code-block:: nimrod +.. code-block:: nim case myInt of 0: echo "most common case" @@ -5251,10 +5248,10 @@ whole ``case`` statement, the whole ``case`` statement uses linear scanning. computedGoto pragma ------------------- The ``computedGoto`` pragma can be used to tell the compiler how to -compile a Nimrod `case`:idx: in a ``while true`` statement. +compile a Nim `case`:idx: in a ``while true`` statement. Syntactically it has to be used as a statement inside the loop: -.. code-block:: nimrod +.. code-block:: nim type MyEnum = enum @@ -5298,7 +5295,7 @@ unroll pragma The ``unroll`` pragma can be used to tell the compiler that it should unroll a `for`:idx: or `while`:idx: loop for runtime efficiency: -.. code-block:: nimrod +.. code-block:: nim proc searchChar(s: string, c: char): int = for i in 0 .. s.high: {.unroll: 4.} @@ -5354,7 +5351,7 @@ callconv cdecl|... Specifies the default calling convention for Example: -.. code-block:: nimrod +.. code-block:: nim {.checks: off, optimization: speed.} # compile without runtime checks and optimize for speed @@ -5364,7 +5361,7 @@ push and pop pragmas The `push/pop`:idx: pragmas are very similar to the option directive, but are used to override the settings temporarily. Example: -.. code-block:: nimrod +.. code-block:: nim {.push checks: off.} # compile this section without runtime checks as it is # speed critical @@ -5389,7 +5386,7 @@ The ``global`` pragma can be applied to a variable within a proc to instruct the compiler to store it in a global location and initialize it once at program startup. -.. code-block:: nimrod +.. code-block:: nim proc isHexNumber(s: string): bool = var pattern {.global.} = re"[0-9a-fA-F]+" result = s.match(pattern) @@ -5413,7 +5410,7 @@ no matter if it is globally active or not. Example: -.. code-block:: nimrod +.. code-block:: nim {.deadCodeElim: on.} @@ -5448,11 +5445,11 @@ Example: Please note that if a callable symbol is never used in this scenario, its body will never be compiled. This is the default behavior leading to best compilation times, but if exhaustive compilation of all definitions is required, using - ``nimrod check`` provides this option as well. + ``nim check`` provides this option as well. Example: - .. code-block:: nimrod + .. code-block:: nim {.noforward: on.} @@ -5469,13 +5466,13 @@ Pragma pragma ------------- The ``pragma`` pragma can be used to declare user defined pragmas. This is -useful because Nimrod's templates and macros do not affect pragmas. User +useful because Nim's templates and macros do not affect pragmas. User defined pragmas are in a different module-wide scope than all other symbols. They cannot be imported from a module. Example: -.. code-block:: nimrod +.. code-block:: nim when appType == "lib": {.pragma: rtl, exportc, dynlib, cdecl.} else: @@ -5491,12 +5488,12 @@ generation. Disabling certain messages -------------------------- -Nimrod generates some warnings and hints ("line too long") that may annoy the +Nim generates some warnings and hints ("line too long") that may annoy the user. A mechanism for disabling certain messages is provided: Each hint and warning message contains a symbol in brackets. This is the message's identifier that can be used to enable or disable it: -.. code-block:: Nimrod +.. code-block:: Nim {.hint[LineTooLong]: off.} # turn off the hint about too long lines This is often better than disabling all warnings at once. @@ -5505,7 +5502,7 @@ This is often better than disabling all warnings at once. Foreign function interface ========================== -Nimrod's `FFI`:idx: (foreign function interface) is extensive and only the +Nim's `FFI`:idx: (foreign function interface) is extensive and only the parts that scale to other future backends (like the LLVM/JavaScript backends) are documented here. @@ -5514,7 +5511,7 @@ Importc pragma -------------- The ``importc`` pragma provides a means to import a proc or a variable from C. The optional argument is a string containing the C identifier. If -the argument is missing, the C name is the Nimrod identifier *exactly as +the argument is missing, the C name is the Nim identifier *exactly as spelled*: .. code-block:: @@ -5522,9 +5519,9 @@ spelled*: Note that this pragma is somewhat of a misnomer: Other backends will provide the same feature under the same name. Also, if one is interfacing with C++ -the `ImportCpp pragma <nimrodc.html#importcpp-pragma>`_ and +the `ImportCpp pragma <nimc.html#importcpp-pragma>`_ and interfacing with Objective-C the `ImportObjC pragma -<nimrodc.html#importobjc-pragma>`_ can be used. +<nimc.html#importobjc-pragma>`_ can be used. Exportc pragma @@ -5532,9 +5529,9 @@ Exportc pragma The ``exportc`` pragma provides a means to export a type, a variable, or a procedure to C. Enums and constants can't be exported. The optional argument is a string containing the C identifier. If the argument is missing, the C -name is the Nimrod identifier *exactly as spelled*: +name is the Nim identifier *exactly as spelled*: -.. code-block:: Nimrod +.. code-block:: Nim proc callme(formatstr: cstring) {.exportc: "callMe", varargs.} Note that this pragma is somewhat of a misnomer: Other backends will provide @@ -5546,7 +5543,7 @@ Extern pragma Like ``exportc`` or ``importc``, the ``extern`` pragma affects name mangling. The string literal passed to ``extern`` can be a format string: -.. code-block:: Nimrod +.. code-block:: Nim proc p(s: string) {.extern: "prefix$1".} = echo s @@ -5559,7 +5556,7 @@ Bycopy pragma The ``bycopy`` pragma can be applied to an object or tuple type and instructs the compiler to pass the type by value to procs: -.. code-block:: nimrod +.. code-block:: nim type TVector {.bycopy, pure.} = object x, y, z: float @@ -5575,11 +5572,11 @@ the compiler to pass the type by reference (hidden pointer) to procs. Varargs pragma -------------- The ``varargs`` pragma can be applied to procedures only (and procedure -types). It tells Nimrod that the proc can take a variable number of parameters -after the last specified parameter. Nimrod string values will be converted to C +types). It tells Nim that the proc can take a variable number of parameters +after the last specified parameter. Nim string values will be converted to C strings automatically: -.. code-block:: Nimrod +.. code-block:: Nim proc printf(formatstr: cstring) {.nodecl, varargs.} printf("hallo %s", "world") # "world" will be passed as C string @@ -5614,7 +5611,7 @@ meaning its bounds are not checked. This is often useful when one wishes to implement his own flexibly sized arrays. Additionally an unchecked array is translated into a C array of undetermined size: -.. code-block:: nimrod +.. code-block:: nim type ArrayPart{.unchecked.} = array[0..0, int] MySeq = object @@ -5648,7 +5645,7 @@ With the ``dynlib`` pragma a procedure or a variable can be imported from a dynamic library (``.dll`` files for Windows, ``lib*.so`` files for UNIX). The non-optional argument has to be the name of the dynamic library: -.. code-block:: Nimrod +.. code-block:: Nim proc gtk_image_new(): PGtkWidget {.cdecl, dynlib: "libgtk-x11-2.0.so", importc.} @@ -5658,7 +5655,7 @@ packages need to be installed. The ``dynlib`` import mechanism supports a versioning scheme: -.. code-block:: nimrod +.. code-block:: nim proc Tcl_Eval(interp: pTcl_Interp, script: cstring): int {.cdecl, importc, dynlib: "libtcl(|8.5|8.4|8.3).so.(1|0)".} @@ -5676,7 +5673,7 @@ At runtime the dynamic library is searched for (in this order):: The ``dynlib`` pragma supports not only constant strings as argument but also string expressions in general: -.. code-block:: nimrod +.. code-block:: nim import os proc getDllName: string = @@ -5706,7 +5703,7 @@ With the ``dynlib`` pragma a procedure can also be exported to a dynamic library. The pragma then has no argument and has to be used in conjunction with the ``exportc`` pragma: -.. code-block:: Nimrod +.. code-block:: Nim proc exportme(): int {.cdecl, exportc, dynlib.} This is only useful if the program is compiled as a dynamic library via the @@ -5721,7 +5718,7 @@ be used. The ``system`` module then contains several threading primitives. See the `threads <threads.html>`_ and `channels <channels.html>`_ modules for the thread API. -Nimrod's memory model for threads is quite different than that of other common +Nim's memory model for threads is quite different than that of other common programming languages (C, Pascal, Java): Each thread has its own (garbage collected) heap and sharing of memory is restricted to global variables. This helps to prevent race conditions. GC efficiency is improved quite a lot, @@ -5778,7 +5775,7 @@ Threadvar pragma A global variable can be marked with the ``threadvar`` pragma; it is a `thread-local`:idx: variable then: -.. code-block:: nimrod +.. code-block:: nim var checkpoints* {.threadvar.}: seq[string] Due to implementation restrictions thread local variables cannot be @@ -5797,11 +5794,11 @@ exception in one thread terminates the whole *process*! Spawn ----- -Nimrod has a builtin thread pool that can be used for CPU intensive tasks. For +Nim has a builtin thread pool that can be used for CPU intensive tasks. For IO intensive tasks the upcoming ``async`` and ``await`` features should be -used instead. `spawn`:idx: is used to pass a task to the thread pool: +used. `spawn`:idx: is used to pass a task to the thread pool: -.. code-block:: nimrod +.. code-block:: nim proc processLine(line: string) = # do some heavy lifting here: discard @@ -5828,7 +5825,7 @@ Currently the expression that ``spawn`` takes is however quite restricted: Taint mode ========== -The Nimrod compiler and most parts of the standard library support +The Nim compiler and most parts of the standard library support a taint mode. Input strings are declared with the `TaintedString`:idx: string type declared in the ``system`` module. @@ -5836,7 +5833,7 @@ If the taint mode is turned on (via the ``--taintMode:on`` command line option) it is a distinct string type which helps to detect input validation errors: -.. code-block:: nimrod +.. code-block:: nim echo "your name: " var name: TaintedString = stdin.readline # it is safe here to output the name without any input validation, so @@ -5845,4 +5842,3 @@ validation errors: If the taint mode is turned off, ``TaintedString`` is simply an alias for ``string``. - diff --git a/doc/nimrodc.txt b/doc/nimc.txt index 016f0ed50..8af045e2e 100644 --- a/doc/nimrodc.txt +++ b/doc/nimc.txt @@ -1,9 +1,9 @@ =================================== - Nimrod Compiler User Guide + Nim Compiler User Guide =================================== :Author: Andreas Rumpf -:Version: |nimrodversion| +:Version: |nimversion| .. contents:: @@ -15,11 +15,11 @@ Introduction ============ -This document describes the usage of the *Nimrod compiler* -on the different supported platforms. It is not a definition of the Nimrod +This document describes the usage of the *Nim compiler* +on the different supported platforms. It is not a definition of the Nim programming language (therefore is the `manual <manual.html>`_). -Nimrod is free software; it is licensed under the +Nim is free software; it is licensed under the `MIT License <http://www.opensource.org/licenses/mit-license.php>`_. @@ -107,14 +107,14 @@ Configuration files passed as a command line argument to the compiler. -The ``nimrod`` executable processes configuration files in the following +The ``nim`` executable processes configuration files in the following directories (in this order; later files overwrite previous settings): -1) ``$nimrod/config/nimrod.cfg``, ``/etc/nimrod.cfg`` (UNIX) or ``%NIMROD%/config/nimrod.cfg`` (Windows). This file can be skipped with the ``--skipCfg`` command line option. -2) ``/home/$user/.config/nimrod.cfg`` (UNIX) or ``%APPDATA%/nimrod.cfg`` (Windows). This file can be skipped with the ``--skipUserCfg`` command line option. -3) ``$parentDir/nimrod.cfg`` where ``$parentDir`` stands for any parent directory of the project file's path. These files can be skipped with the ``--skipParentCfg`` command line option. -4) ``$projectDir/nimrod.cfg`` where ``$projectDir`` stands for the project file's path. This file can be skipped with the ``--skipProjCfg`` command line option. -5) A project can also have a project specific configuration file named ``$project.nimrod.cfg`` that resides in the same directory as ``$project.nim``. This file can be skipped with the ``--skipProjCfg`` command line option. +1) ``$nim/config/nim.cfg``, ``/etc/nim.cfg`` (UNIX) or ``%NIMROD%/config/nim.cfg`` (Windows). This file can be skipped with the ``--skipCfg`` command line option. +2) ``/home/$user/.config/nim.cfg`` (UNIX) or ``%APPDATA%/nim.cfg`` (Windows). This file can be skipped with the ``--skipUserCfg`` command line option. +3) ``$parentDir/nim.cfg`` where ``$parentDir`` stands for any parent directory of the project file's path. These files can be skipped with the ``--skipParentCfg`` command line option. +4) ``$projectDir/nim.cfg`` where ``$projectDir`` stands for the project file's path. This file can be skipped with the ``--skipProjCfg`` command line option. +5) A project can also have a project specific configuration file named ``$project.nim.cfg`` that resides in the same directory as ``$project.nim``. This file can be skipped with the ``--skipProjCfg`` command line option. Command line settings have priority over configuration file settings. @@ -122,17 +122,17 @@ Command line settings have priority over configuration file settings. The default build of a project is a `debug build`:idx:. To compile a `release build`:idx: define the ``release`` symbol:: - nimrod c -d:release myproject.nim + nim c -d:release myproject.nim Search path handling -------------------- -Nimrod has the concept of a global search path (PATH) that is queried to +Nim has the concept of a global search path (PATH) that is queried to determine where to find imported modules or include files. If multiple files are found an ambiguity error is produced. -``nimrod dump`` shows the contents of the PATH. +``nim dump`` shows the contents of the PATH. However before the PATH is used the current directory is checked for the file's existance. So if PATH contains ``$lib`` and ``$lib/bar`` and the @@ -152,10 +152,10 @@ the first matching file is used. Generated C code directory -------------------------- -The generated files that Nimrod produces all go into a subdirectory called +The generated files that Nim produces all go into a subdirectory called ``nimcache`` in your project directory. This makes it easy to delete all generated files. Files generated in this directory follow a naming logic which -you can read about in the `Nimrod Backend Integration document +you can read about in the `Nim Backend Integration document <backends.html#nimcache-naming-logic>`_. However, the generated C code is not platform independent. C code generated for @@ -190,14 +190,14 @@ Cross compilation To cross compile, use for example:: - nimrod c --cpu:i386 --os:linux --compile_only --gen_script myproject.nim + nim c --cpu:i386 --os:linux --compile_only --gen_script myproject.nim Then move the C code and the compile script ``compile_myproject.sh`` to your Linux i386 machine and run the script. -Another way is to make Nimrod invoke a cross compiler toolchain:: +Another way is to make Nim invoke a cross compiler toolchain:: - nimrod c --cpu:arm --os:linux myproject.nim + nim c --cpu:arm --os:linux myproject.nim For cross compilation, the compiler invokes a C compiler named like ``$cpu.$os.$cc`` (for example arm.linux.gcc) and the configuration @@ -212,16 +212,16 @@ configuration file should contain something like:: DLL generation ============== -Nimrod supports the generation of DLLs. However, there must be only one +Nim supports the generation of DLLs. However, there must be only one instance of the GC per process/address space. This instance is contained in -``nimrtl.dll``. This means that every generated Nimrod DLL depends +``nimrtl.dll``. This means that every generated Nim DLL depends on ``nimrtl.dll``. To generate the "nimrtl.dll" file, use the command:: - nimrod c -d:release lib/nimrtl.nim + nim c -d:release lib/nimrtl.nim To link against ``nimrtl.dll`` use the command:: - nimrod c -d:useNimRtl myprog.nim + nim c -d:useNimRtl myprog.nim **Note**: Currently the creation of ``nimrtl.dll`` with thread support has never been tested and is unlikely to work! @@ -243,9 +243,9 @@ Define Effect version. ``useFork`` Makes ``osproc`` use ``fork`` instead of ``posix_spawn``. ``useNimRtl`` Compile and link against ``nimrtl.dll``. -``useMalloc`` Makes Nimrod use C's `malloc`:idx: instead of Nimrod's +``useMalloc`` Makes Nim use C's `malloc`:idx: instead of Nim's own memory manager. This only works with ``gc:none``. -``useRealtimeGC`` Enables support of Nimrod's GC for *soft* realtime +``useRealtimeGC`` Enables support of Nim's GC for *soft* realtime systems. See the documentation of the `gc <gc.html>`_ for further information. ``nodejs`` The JS target is actually ``node.js``. @@ -258,8 +258,8 @@ Define Effect Additional Features =================== -This section describes Nimrod's additional features that are not listed in the -Nimrod manual. Some of the features here only make sense for the C code +This section describes Nim's additional features that are not listed in the +Nim manual. Some of the features here only make sense for the C code generator and are subject to change. @@ -267,13 +267,13 @@ NoDecl pragma ------------- The ``noDecl`` pragma can be applied to almost any symbol (variable, proc, type, etc.) and is sometimes useful for interoperability with C: -It tells Nimrod that it should not generate a declaration for the symbol in +It tells Nim that it should not generate a declaration for the symbol in the C code. For example: -.. code-block:: Nimrod +.. code-block:: Nim var EACCES {.importc, noDecl.}: cint # pretend EACCES was a variable, as - # Nimrod does not know its value + # Nim does not know its value However, the ``header`` pragma is often the better alternative. @@ -286,14 +286,14 @@ The ``header`` pragma is very similar to the ``noDecl`` pragma: It can be applied to almost any symbol and specifies that it should not be declared and instead the generated code should contain an ``#include``: -.. code-block:: Nimrod +.. code-block:: Nim type PFile {.importc: "FILE*", header: "<stdio.h>".} = distinct pointer - # import C's FILE* type; Nimrod will treat it as a new pointer type + # import C's FILE* type; Nim will treat it as a new pointer type The ``header`` pragma always expects a string constant. The string contant contains the header file: As usual for C, a system header file is enclosed -in angle brackets: ``<>``. If no angle brackets are given, Nimrod +in angle brackets: ``<>``. If no angle brackets are given, Nim encloses the header file in ``""`` in the generated C code. **Note**: This will not work for the LLVM backend. @@ -304,7 +304,7 @@ IncompleteStruct pragma The ``incompleteStruct`` pragma tells the compiler to not use the underlying C ``struct`` in a ``sizeof`` expression: -.. code-block:: Nimrod +.. code-block:: Nim type TDIR* {.importc: "DIR", header: "<dirent.h>", final, pure, incompleteStruct.} = object @@ -315,10 +315,10 @@ Compile pragma The ``compile`` pragma can be used to compile and link a C/C++ source file with the project: -.. code-block:: Nimrod +.. code-block:: Nim {.compile: "myfile.cpp".} -**Note**: Nimrod computes a CRC checksum and only recompiles the file if it +**Note**: Nim computes a CRC checksum and only recompiles the file if it has changed. You can use the ``-f`` command line option to force recompilation of the file. @@ -327,7 +327,7 @@ Link pragma ----------- The ``link`` pragma can be used to link an additional file with the project: -.. code-block:: Nimrod +.. code-block:: Nim {.link: "myfile.o".} @@ -336,13 +336,13 @@ PassC pragma The ``passC`` pragma can be used to pass additional parameters to the C compiler like you would using the commandline switch ``--passC``: -.. code-block:: Nimrod +.. code-block:: Nim {.passC: "-Wall -Werror".} Note that you can use ``gorge`` from the `system module <system.html>`_ to embed parameters from an external command at compile time: -.. code-block:: Nimrod +.. code-block:: Nim {.passC: gorge("pkg-config --cflags sdl").} PassL pragma @@ -350,13 +350,13 @@ PassL pragma The ``passL`` pragma can be used to pass additional parameters to the linker like you would using the commandline switch ``--passL``: -.. code-block:: Nimrod +.. code-block:: Nim {.passL: "-lSDLmain -lSDL".} Note that you can use ``gorge`` from the `system module <system.html>`_ to embed parameters from an external command at compile time: -.. code-block:: Nimrod +.. code-block:: Nim {.passL: gorge("pkg-config --libs sdl").} @@ -369,16 +369,16 @@ extremely useful for interfacing with `C++`:idx: or `Objective C`:idx: code. Example: -.. code-block:: Nimrod +.. code-block:: Nim {.emit: """ static int cvariable = 420; """.} {.push stackTrace:off.} proc embedsC() = - var nimrodVar = 89 - # use backticks to access Nimrod symbols within an emit section: - {.emit: """fprintf(stdout, "%d\n", cvariable + (int)`nimrodVar`);""".} + var nimVar = 89 + # use backticks to access Nim symbols within an emit section: + {.emit: """fprintf(stdout, "%d\n", cvariable + (int)`nimVar`);""".} {.pop.} embedsC() @@ -392,7 +392,7 @@ code then uses the C++ method calling syntax: ``obj->method(arg)``. In addition with the ``header`` and ``emit`` pragmas this allows *sloppy* interfacing with libraries written in C++: -.. code-block:: Nimrod +.. code-block:: Nim # Horrible example of how to interface with a C++ engine ... ;-) {.link: "/usr/lib/libIrrlicht.so".} @@ -431,7 +431,7 @@ generated code then uses the Objective C method calling syntax: ``[obj method param1: arg]``. In addition with the ``header`` and ``emit`` pragmas this allows *sloppy* interfacing with libraries written in Objective C: -.. code-block:: Nimrod +.. code-block:: Nim # horrible example of how to interface with GNUStep ... {.passL: "-lobjc".} @@ -475,11 +475,11 @@ emits Objective C code. CodegenDecl pragma ------------------ -The ``codegenDecl`` pragma can be used to directly influence Nimrod's code +The ``codegenDecl`` pragma can be used to directly influence Nim's code generator. It receives a format string that determines how the variable or proc is declared in the generated code: -.. code-block:: nimrod +.. code-block:: nim var a {.codegenDecl: "$# progmem $#".}: int @@ -494,7 +494,7 @@ The ``injectStmt`` pragma can be used to inject a statement before every other statement in the current module. It is only supposed to be used for debugging: -.. code-block:: nimrod +.. code-block:: nim {.injectStmt: gcInvariants().} # ... complex code here that produces crashes ... @@ -523,7 +523,7 @@ is raised. Debugger option --------------- -The ``debugger`` option enables or disables the *Embedded Nimrod Debugger*. +The ``debugger`` option enables or disables the *Embedded Nim Debugger*. See the documentation of endb_ for further information. @@ -545,11 +545,11 @@ in C/C++). Source code style ================= -Nimrod allows you to `mix freely case and underscores as identifier separators +Nim allows you to `mix freely case and underscores as identifier separators <manual.html#identifiers-keywords>`_, so variables named ``MyPrecioussInt`` and ``my_preciouss_int`` are equivalent: -.. code-block:: Nimrod +.. code-block:: Nim var MyPrecioussInt = 3 # Following line compiles fine! echo my_preciouss_int @@ -557,16 +557,16 @@ Nimrod allows you to `mix freely case and underscores as identifier separators Since this can lead to many variants of the same source code (you can use `nimgrep <nimgrep.html>`_ instead of your typical ``grep`` to ignore style problems) the compiler provides the command ``pretty`` to help unifying the -style of source code. Running ``nimrod pretty ugly_test.nim`` with this +style of source code. Running ``nim pretty ugly_test.nim`` with this example will generate a secondary file named ``ugly_test.pretty.nim`` with the following content: -.. code-block:: Nimrod +.. code-block:: Nim var MyPrecioussInt = 3 # Following line compiles fine! echo MyPrecioussInt -During execution the ``pretty`` command will also run on Nimrod's standard +During execution the ``pretty`` command will also run on Nim's standard library, since it doesn't differentiate the standard library as something special, and hence will warn of many *errors* which are out of your hand to fix, creating respective ``.pretty.nim`` files all the way. You can ignore @@ -583,11 +583,11 @@ important changes for you to review. In this case the command is warning that a variable name should not start with a capital letter, which is usually reserved to `object types <tut2.html#objects>`_. To learn about the accepted `camel case style <https://en.wikipedia.org/wiki/Camelcase>`_ read `Coding Guidelines in -the Internals of Nimrod Compiler <intern.html#coding-guidelines>`_ or `Coding -Guidelines <https://github.com/Araq/Nimrod/wiki/Coding-Guidelines>`_ and `NEP 1 -: Style Guide for Nimrod Code -<https://github.com/Araq/Nimrod/wiki/NEP-1-:-Style-Guide-for-Nimrod-Code>`_ -from the Nimrod `GitHub wiki<https://github.com/Araq/Nimrod/wiki>`_. +the Internals of Nim Compiler <intern.html#coding-guidelines>`_ or `Coding +Guidelines <https://github.com/Araq/Nim/wiki/Coding-Guidelines>`_ and `NEP 1 +: Style Guide for Nim Code +<https://github.com/Araq/Nim/wiki/NEP-1-:-Style-Guide-for-Nim-Code>`_ +from the Nim `GitHub wiki<https://github.com/Araq/Nim/wiki>`_. This command is safe to run because it will never attempt to overwrite your existing sources, but the respective ``.pretty.nim`` files **will** be @@ -597,14 +597,14 @@ overwritten without notice. DynlibOverride ============== -By default Nimrod's ``dynlib`` pragma causes the compiler to generate +By default Nim's ``dynlib`` pragma causes the compiler to generate ``GetProcAddress`` (or their Unix counterparts) calls to bind to a DLL. With the ``dynlibOverride`` command line switch this can be prevented and then via ``--passL`` the static library can be linked against. For instance, to link statically against Lua this command might work on Linux:: - nimrod c --dynlibOverride:lua --passL:liblua.lib program.nim + nim c --dynlibOverride:lua --passL:liblua.lib program.nim Backend language options @@ -614,32 +614,32 @@ The typical compiler usage involves using the ``compile`` or ``c`` command to transform a ``.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 to compile to C++, Objective-C or Javascript. More details -can be read in the `Nimrod Backend Integration document <backends.html>`_. +can be read in the `Nim Backend Integration document <backends.html>`_. -Nimrod documentation tools -========================== +Nim documentation tools +======================= -Nimrod provides the `doc`:idx: and `doc2`:idx: commands to generate HTML +Nim provides the `doc`:idx: and `doc2`:idx: commands to generate HTML documentation from ``.nim`` source files. Only exported symbols will appear in the output. For more details `see the docgen documentation <docgen.html>`_. -Nimrod idetools integration -=========================== +Nim idetools integration +======================== -Nimrod provides language integration with external IDEs through the +Nim provides language integration with external IDEs through the idetools command. See the documentation of `idetools <idetools.html>`_ for further information. -Nimrod interactive mode -======================= +Nim interactive mode +==================== -The Nimrod compiler supports an interactive mode. This is also known as -a `REPL`:idx: (*read eval print loop*). If Nimrod has been built with the +The Nim compiler supports an interactive mode. This is also known as +a `REPL`:idx: (*read eval print loop*). If Nim has been built with the ``-d:useGnuReadline`` switch, it uses the GNU readline library for terminal -input management. To start Nimrod in interactive mode use the command -``nimrod i``. To quit use the ``quit()`` command. To determine whether an input +input management. To start Nim in interactive mode use the command +``nim i``. To quit use the ``quit()`` command. To determine whether an input line is an incomplete statement to be continued these rules are used: 1. The line ends with ``[-+*/\\<>!\?\|%&$@~,;:=#^]\s*$`` (operator symbol followed by optional whitespace). @@ -648,8 +648,8 @@ line is an incomplete statement to be continued these rules are used: does not work if the line contains more than one ``"""``. -Nimrod for embedded systems -=========================== +Nim for embedded systems +======================== The standard library can be avoided to a point where C code generation for 16bit micro controllers is feasible. Use the `standalone`:idx: target @@ -661,7 +661,7 @@ target. For example, to generate code for an `AVR`:idx: processor use this command:: - nimrod c --cpu:avr --os:standalone --deadCodeElim:on --genScript x.nim + nim c --cpu:avr --os:standalone --deadCodeElim:on --genScript x.nim For the ``standalone`` target you need to provide a file ``panicoverride.nim``. @@ -669,27 +669,27 @@ See ``tests/manyloc/standalone/panicoverride.nim`` for an example implementation. -Nimrod for realtime systems -=========================== +Nim for realtime systems +======================== -See the documentation of Nimrod's soft realtime `GC <gc.html>`_ for further +See the documentation of Nim's soft realtime `GC <gc.html>`_ for further information. -Debugging with Nimrod -===================== +Debugging with Nim +================== -Nimrod comes with its own *Embedded Nimrod Debugger*. See +Nim comes with its own *Embedded Nim Debugger*. See the documentation of endb_ for further information. -Optimizing for Nimrod -===================== +Optimizing for Nim +================== -Nimrod has no separate optimizer, but the C code that is produced is very +Nim has no separate optimizer, but the C code that is produced is very efficient. Most C compilers have excellent optimizers, so usually it is -not needed to optimize one's code. Nimrod has been designed to encourage -efficient code: The most readable code in Nimrod is often the most efficient +not needed to optimize one's code. Nim has been designed to encourage +efficient code: The most readable code in Nim is often the most efficient too. However, sometimes one has to optimize. Do it in the following order: @@ -706,32 +706,32 @@ This section can only help you with the last item. Optimizing string handling -------------------------- -String assignments are sometimes expensive in Nimrod: They are required to +String assignments are sometimes expensive in Nim: They are required to copy the whole string. However, the compiler is often smart enough to not copy strings. Due to the argument passing semantics, strings are never copied when passed to subroutines. The compiler does not copy strings that are a result from a procedure call, because the callee returns a new string anyway. Thus it is efficient to do: -.. code-block:: Nimrod +.. code-block:: Nim var s = procA() # assignment will not copy the string; procA allocates a new # string already However it is not efficient to do: -.. code-block:: Nimrod +.. code-block:: Nim var s = varA # assignment has to copy the whole string into a new buffer! For ``let`` symbols a copy is not always necessary: -.. code-block:: Nimrod +.. code-block:: Nim let s = varA # may only copy a pointer if it safe to do so If you know what you're doing, you can also mark single string (or sequence) objects as `shallow`:idx:\: -.. code-block:: Nimrod +.. code-block:: Nim var s = "abc" shallow(s) # mark 's' as shallow string var x = s # now might not copy the string! @@ -744,7 +744,7 @@ The compiler optimizes string case statements: A hashing scheme is used for them if several different string constants are used. So code like this is reasonably efficient: -.. code-block:: Nimrod +.. code-block:: Nim case normalize(k.key) of "name": c.name = v of "displayname": c.displayName = v diff --git a/doc/nimgrep.txt b/doc/nimgrep.txt index 67aaa427e..e2f7b228f 100644 --- a/doc/nimgrep.txt +++ b/doc/nimgrep.txt @@ -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 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 manipulation tool. @@ -20,7 +20,7 @@ Installation 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``. diff --git a/doc/niminst.txt b/doc/niminst.txt index 8d95d01c9..d743c5187 100644 --- a/doc/niminst.txt +++ b/doc/niminst.txt @@ -3,14 +3,14 @@ ========================= :Author: Andreas Rumpf -:Version: |nimrodversion| +:Version: |nimversion| .. contents:: 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 via `Inno Setup <http://www.jrsoftware.org/isinfo.php>`_ as well as installation/deinstallation scripts for UNIX. Later versions will support @@ -24,7 +24,7 @@ systems. 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: .. include:: doc/mytest.cfg @@ -187,9 +187,9 @@ Key description 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: -.. include:: compiler/nimrod.ini +.. include:: compiler/nim.ini :literal: diff --git a/doc/overview.txt b/doc/overview.txt index 242039086..5b41752ae 100644 --- a/doc/overview.txt +++ b/doc/overview.txt @@ -1,9 +1,9 @@ ============================= -Nimrod Documentation Overview +Nim Documentation Overview ============================= :Author: Andreas Rumpf -:Version: |nimrodversion| +:Version: |nimversion| .. include:: ../doc/docs.txt diff --git a/doc/pegdocs.txt b/doc/pegdocs.txt index eb7f4562f..d22d81a5a 100644 --- a/doc/pegdocs.txt +++ b/doc/pegdocs.txt @@ -171,7 +171,7 @@ The PEG parser implements this grammar (written in PEG syntax):: expression, identifiers are not interpreted as non-terminals, but are interpreted as verbatim string: -.. code-block:: nimrod +.. code-block:: nim abc =~ peg"abc" # is true So it is not necessary to write ``peg" 'abc' "`` in the above example. @@ -180,19 +180,19 @@ So it is not necessary to write ``peg" 'abc' "`` in the above example. Examples -------- -Check if `s` matches Nimrod's "while" keyword: +Check if `s` matches Nim's "while" keyword: -.. code-block:: nimrod +.. code-block:: nim s =~ peg" y'while'" Exchange (key, val)-pairs: -.. code-block:: nimrod +.. code-block:: nim "key: val; key2: val2".replace(peg"{\ident} \s* ':' \s* {\ident}", "$2: $1") Determine the ``#include``'ed files of a C file: -.. code-block:: nimrod +.. code-block:: nim for line in lines("myfile.c"): if line =~ peg"""s <- ws '#include' ws '"' {[^"]+} '"' ws comment <- '/*' @ '*/' / '//' .* @@ -212,7 +212,7 @@ example ``*`` should not be greedy, so ``\[.*?\]`` should be used instead. PEG construction ---------------- -There are two ways to construct a PEG in Nimrod code: +There are two ways to construct a PEG in Nim code: (1) Parsing a string into an AST which consists of `TPeg` nodes with the `peg` proc. (2) Constructing the AST directly with proc calls. This method does not diff --git a/doc/readme.txt b/doc/readme.txt index 7f509bd39..e5d9e2c27 100644 --- a/doc/readme.txt +++ b/doc/readme.txt @@ -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 like ASCII and can be converted to HTML automatically! diff --git a/doc/regexprs.txt b/doc/regexprs.txt index 930352948..d912c623e 100644 --- a/doc/regexprs.txt +++ b/doc/regexprs.txt @@ -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 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 -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:: r"\S" # matches any character that is not whitespace diff --git a/doc/rst.txt b/doc/rst.txt index 4199598d1..1e858d617 100644 --- a/doc/rst.txt +++ b/doc/rst.txt @@ -1,9 +1,9 @@ =========================================================================== - Nimrod's implementation of |rst| + Nim's implementation of |rst| =========================================================================== :Author: Andreas Rumpf -:Version: |nimrodversion| +:Version: |nimversion| .. contents:: @@ -11,15 +11,15 @@ Introduction ============ 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. -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. -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 -fact is that Nimrod's *whole* documentation itself (including this document) is -processed by Nimrod's |rst| parser. (Which is an order of magnitude faster than +fact is that Nim's *whole* documentation itself (including this document) is +processed by Nim's |rst| parser. (Which is an order of magnitude faster than Docutils' parser.) @@ -65,19 +65,19 @@ Definition lists 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 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 ====== -Nimrod only implements simple tables of the form:: +Nim only implements simple tables of the form:: ================== =============== =================== header 1 header 2 header n diff --git a/doc/sets_fragment.txt b/doc/sets_fragment.txt index fba355269..32dbac1c2 100644 --- a/doc/sets_fragment.txt +++ b/doc/sets_fragment.txt @@ -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 can also be used to include elements (and ranges of elements): -.. code-block:: nimrod +.. code-block:: nim type TCharSet = set[char] var diff --git a/doc/spawn.txt b/doc/spawn.txt index c5c96ecf8..b2496285f 100644 --- a/doc/spawn.txt +++ b/doc/spawn.txt @@ -2,7 +2,7 @@ Parallel & Spawn ========================================================== -Nimrod has two flavors of parallelism: +Nim has two flavors of parallelism: 1) `Structured`:idx parallelism via the ``parallel`` statement. 2) `Unstructured`:idx: parallelism via the standalone ``spawn`` statement. @@ -24,7 +24,7 @@ Parallel statement Example: -.. code-block:: nimrod +.. code-block:: nim # Compute PI in an inefficient way import strutils, math, threadpool @@ -42,7 +42,7 @@ Example: 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 compile time. A sophisticated `disjoint checker`:idx: ensures that no data 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 variables at the same time: -.. code-block:: nimrod +.. code-block:: nim import threadpool, ... # wait until 2 out of 3 servers received the update: diff --git a/doc/subexes.txt b/doc/subexes.txt index 3b688fd0a..7cad183b9 100644 --- a/doc/subexes.txt +++ b/doc/subexes.txt @@ -45,7 +45,7 @@ Notation meaning Examples ======== -.. code-block:: nimrod +.. code-block:: nim subex"$1($', '{2..})" % ["f", "a", "b", "c"] == "f(a, b, c)" diff --git a/doc/tools.txt b/doc/tools.txt index 0127bc4a8..0b39762c6 100644 --- a/doc/tools.txt +++ b/doc/tools.txt @@ -1,20 +1,20 @@ -=========================== -Tools available with Nimrod -=========================== +======================== +Tools available with Nim +======================== The standard distribution ships with the following tools: -- | `Nimrod Installation Generator <niminst.html>`_ - | How to generate a nice installer for your Nimrod program. +- | `Nim Installation Generator <niminst.html>`_ + | How to generate a nice installer for your Nim program. - | `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>`_ - | Nimrod search and replace utility. + | Nim search and replace utility. - | `endb <endb.html>`_ - | Nimrod's slow platform independent embedded debugger. + | Nim's slow platform independent embedded debugger. - | `estp <estp.html>`_ - | Nimrod's slow platform independent embedded stack trace profiler. + | Nim's slow platform independent embedded stack trace profiler. diff --git a/doc/tut1.txt b/doc/tut1.txt index ee642ce17..b90736bd0 100644 --- a/doc/tut1.txt +++ b/doc/tut1.txt @@ -1,9 +1,9 @@ -======================== -Nimrod Tutorial (Part I) -======================== +===================== +Nim Tutorial (Part I) +===================== :Author: Andreas Rumpf -:Version: |nimrodversion| +:Version: |nimversion| .. contents:: @@ -16,7 +16,7 @@ Introduction </p></blockquote> -This document is a tutorial for the programming language *Nimrod*. +This document is a tutorial for the programming language *Nim*. This tutorial assumes that you are familiar with basic programming concepts like variables, types or statements but is kept very basic. The `manual <manual.html>`_ contains many more examples of the advanced language features. @@ -28,7 +28,7 @@ The first program We start the tour with a modified "hello world" program: -.. code-block:: Nimrod +.. code-block:: Nim # This is a comment echo("What's your name? ") var name: string = readLine(stdin) @@ -37,30 +37,30 @@ We start the tour with a modified "hello world" program: Save this code to the file "greetings.nim". Now compile and run it:: - nimrod compile --run greetings.nim + nim compile --run greetings.nim -With the ``--run`` `switch <nimrodc.html#command-line-switches>`_ Nimrod +With the ``--run`` `switch <nimc.html#command-line-switches>`_ Nim executes the file automatically after compilation. You can give your program command line arguments by appending them after the filename:: - nimrod compile --run greetings.nim arg1 arg2 + nim compile --run greetings.nim arg1 arg2 Commonly used commands and switches have abbreviations, so you can also use:: - nimrod c -r greetings.nim + nim c -r greetings.nim To compile a release version use:: - nimrod c -d:release greetings.nim + nim c -d:release greetings.nim -By default the Nimrod compiler generates a large amount of runtime checks +By default the Nim compiler generates a large amount of runtime checks aiming for your debugging pleasure. With ``-d:release`` these checks are `turned off and optimizations are turned on -<nimrodc.html#compile-time-symbols>`_. +<nimc.html#compile-time-symbols>`_. Though it should be pretty obvious what the program does, I will explain the syntax: statements which are not indented are executed when the program -starts. Indentation is Nimrod's way of grouping statements. Indentation is +starts. Indentation is Nim's way of grouping statements. Indentation is done with spaces only, tabulators are not allowed. String literals are enclosed in double quotes. The ``var`` statement declares @@ -70,11 +70,11 @@ compiler knows that `readLine <system.html#readLine,TFile>`_ returns a string, you can leave out the type in the declaration (this is called `local type inference`:idx:). So this will work too: -.. code-block:: Nimrod +.. code-block:: Nim var name = readLine(stdin) Note that this is basically the only form of type inference that exists in -Nimrod: it is a good compromise between brevity and readability. +Nim: it is a good compromise between brevity and readability. The "hello world" program contains several identifiers that are already known to the compiler: ``echo``, `readLine <system.html#readLine,TFile>`_, etc. @@ -85,8 +85,8 @@ imported by any other module. Lexical elements ================ -Let us look at Nimrod's lexical elements in more detail: like other -programming languages Nimrod consists of (string) literals, identifiers, +Let us look at Nim's lexical elements in more detail: like other +programming languages Nim consists of (string) literals, identifiers, keywords, comments, operators, and other punctuation marks. @@ -97,7 +97,7 @@ String literals are enclosed in double quotes; character literals in single quotes. Special characters are escaped with ``\``: ``\n`` means newline, ``\t`` means tabulator, etc. There are also *raw* string literals: -.. code-block:: Nimrod +.. code-block:: Nim r"C:\program files\nim" In raw literals the backslash is not an escape character. @@ -112,54 +112,23 @@ Comments -------- Comments start anywhere outside a string or character literal with the -hash character ``#``. Documentation comments start with ``##``. Multiline -comments need to be aligned at the same column: - -.. code-block:: nimrod - - i = 0 # This is a single comment over multiple lines belonging to the - # assignment statement. - # This is a new comment belonging to the current block, but to no particular - # statement. - i = i + 1 # This a new comment that is NOT - echo(i) # continued here, because this comment refers to the echo statement - - -The alignment requirement does not hold if the preceding comment piece ends in -a backslash: +hash character ``#``. Documentation comments start with ``##``: -.. code-block:: nimrod - type - TMyObject {.final, pure, acyclic.} = object # comment continues: \ - # we have lots of space here to comment 'TMyObject'. - # This line belongs to the comment as it's properly aligned. - - -Comments are tokens; they are only allowed at certain places in the input file -as they belong to the syntax tree! This feature enables perfect source-to-source -transformations (such as pretty-printing) and simpler documentation generators. -A nice side-effect is that the human reader of the code always knows exactly -which code snippet the comment refers to. Since comments are a proper part of -the syntax, watch their indentation: +.. code-block:: nim + # A comment. + + var myVariable: int ## a documentation comment -.. code-block:: - echo("Hello!") - # comment has the same indentation as above statement -> fine - echo("Hi!") - # comment has not the correct indentation level -> syntax error! - -**Note**: To comment out a large piece of code, it is often better to use a -``when false:`` statement. -.. code-block:: nimrod - when false: - brokenCode() +Documentation comments are tokens; they are only allowed at certain places in +the input file as they belong to the syntax tree! This feature enables simpler +documentation generators. -Another option is to use the `discard statement`_ together with *long string +You can also use the `discard statement`_ together with *long string literals* to create block comments: -.. code-block:: nimrod - discard """ You can have any Nimrod code text commented +.. code-block:: nim + discard """ You can have any Nim code text commented out inside this with no indentation restrictions. yes("May I ask a pointless question?") """ @@ -204,7 +173,7 @@ to a storage location: ``=`` is the *assignment operator*. The assignment operator cannot be overloaded, overwritten or forbidden, but this might change in a future version -of Nimrod. You can declare multiple variables with a single assignment +of Nim. You can declare multiple variables with a single assignment statement and all the variables will have the same value: .. code-block:: @@ -229,7 +198,7 @@ Constants are symbols which are bound to a value. The constant's value cannot change. The compiler must be able to evaluate the expression in a constant declaration at compile time: -.. code-block:: nimrod +.. code-block:: nim const x = "abc" # the constant x contains the string "abc" Indentation can be used after the ``const`` keyword to list a whole section of @@ -277,7 +246,7 @@ If statement The if statement is one way to branch the control flow: -.. code-block:: nimrod +.. code-block:: nim let name = readLine(stdin) if name == "": echo("Poor soul, you lost your name?") @@ -298,7 +267,7 @@ Case statement Another way to branch is provided by the case statement. A case statement is a multi-branch: -.. code-block:: nimrod +.. code-block:: nim let name = readLine(stdin) case name of "": @@ -317,7 +286,7 @@ The case statement can deal with integers, other ordinal types and strings. (What an ordinal type is will be explained soon.) For integers or other ordinal types value ranges are also possible: -.. code-block:: nimrod +.. code-block:: nim # this statement will be explained later: from strutils import parseInt @@ -333,7 +302,7 @@ every value that ``n`` may contain, but the code only handles the values (though it is possible thanks to the range notation), we fix this by telling the compiler that for every other value nothing should be done: -.. code-block:: nimrod +.. code-block:: nim ... case n of 0..2, 4..7: echo("The number is in the set: {0, 1, 2, 4, 5, 6, 7}") @@ -355,7 +324,7 @@ While statement The while statement is a simple looping construct: -.. code-block:: nimrod +.. code-block:: nim echo("What's your name? ") var name = readLine(stdin) @@ -375,7 +344,7 @@ The ``for`` statement is a construct to loop over any element an *iterator* provides. The example uses the built-in `countup <system.html#countup>`_ iterator: -.. code-block:: nimrod +.. code-block:: nim echo("Counting to ten: ") for i in countup(1, 10): echo($i) @@ -387,7 +356,7 @@ other types into a string. The variable ``i`` is implicitly declared by the <system.html#countup>`_ returns. ``i`` runs through the values 1, 2, .., 10. Each value is ``echo``-ed. This code does the same: -.. code-block:: nimrod +.. code-block:: nim echo("Counting to 10: ") var i = 1 while i <= 10: @@ -397,16 +366,16 @@ Each value is ``echo``-ed. This code does the same: Counting down can be achieved as easily (but is less often needed): -.. code-block:: nimrod +.. code-block:: nim echo("Counting down from 10 to 1: ") for i in countdown(10, 1): echo($i) # --> Outputs 10 9 8 7 6 5 4 3 2 1 on different lines -Since counting up occurs so often in programs, Nimrod also has a `.. +Since counting up occurs so often in programs, Nim also has a `.. <system.html#...i,S,T>`_ iterator that does the same: -.. code-block:: nimrod +.. code-block:: nim for i in 1..10: ... @@ -417,7 +386,7 @@ Control flow statements have a feature not covered yet: they open a new scope. This means that in the following example, ``x`` is not accessible outside the loop: -.. code-block:: nimrod +.. code-block:: nim while false: var x = "hi" echo(x) # does not work @@ -426,7 +395,7 @@ A while (for) statement introduces an implicit block. Identifiers are only visible within the block they have been declared. The ``block`` statement can be used to open a new block explicitly: -.. code-block:: nimrod +.. code-block:: nim block myblock: var x = "hi" echo(x) # does not work either @@ -440,7 +409,7 @@ A block can be left prematurely with a ``break`` statement. The break statement can leave a ``while``, ``for``, or a ``block`` statement. It leaves the innermost construct, unless a label of a block is given: -.. code-block:: nimrod +.. code-block:: nim block myblock: echo("entering block") while true: @@ -461,7 +430,7 @@ Continue statement Like in many other programming languages, a ``continue`` statement starts the next iteration immediately: -.. code-block:: nimrod +.. code-block:: nim while true: let x = readLine(stdin) if x == "": continue @@ -473,7 +442,7 @@ When statement Example: -.. code-block:: nimrod +.. code-block:: nim when system.hostOS == "windows": echo("running on Windows!") @@ -504,17 +473,17 @@ possible. Statements and indentation ========================== -Now that we covered the basic control flow statements, let's return to Nimrod +Now that we covered the basic control flow statements, let's return to Nim indentation rules. -In Nimrod there is a distinction between *simple statements* and *complex +In Nim there is a distinction between *simple statements* and *complex statements*. *Simple statements* cannot contain other statements: Assignment, procedure calls or the ``return`` statement belong to the simple statements. *Complex statements* like ``if``, ``when``, ``for``, ``while`` can contain other statements. To avoid ambiguities, complex statements always have to be indented, but single simple statements do not: -.. code-block:: nimrod +.. code-block:: nim # no indentation needed for single assignment statement: if x: x = false @@ -535,7 +504,7 @@ to be indented, but single simple statements do not: condition in an if statement is an example for an expression. Expressions can contain indentation at certain places for better readability: -.. code-block:: nimrod +.. code-block:: nim if thisIsaLongCondition() and thisIsAnotherLongCondition(1, @@ -548,7 +517,7 @@ an open parenthesis and after commas. With parenthesis and semicolons ``(;)`` you can use statements where only an expression is allowed: -.. code-block:: nimrod +.. code-block:: nim # computes fac(4) at compile time: const fac4 = (var x = 1; for i in 1..4: x *= i; x) @@ -558,10 +527,10 @@ Procedures To define new commands like `echo <system.html#echo>`_ and `readLine <system.html#readLine,TFile>`_ in the examples, the concept of a `procedure` -is needed. (Some languages call them *methods* or *functions*.) In Nimrod new +is needed. (Some languages call them *methods* or *functions*.) In Nim new procedures are defined with the ``proc`` keyword: -.. code-block:: nimrod +.. code-block:: nim proc yes(question: string): bool = echo(question, " (y/n)") while true: @@ -597,7 +566,7 @@ shorthand for ``return result``. The ``result`` value is always returned automatically at the end a procedure if there is no ``return`` statement at the exit. -.. code-block:: nimrod +.. code-block:: nim proc sumTillNegative(x: varargs[int]): int = for i in x: if i < 0: @@ -624,7 +593,7 @@ most efficient way. If a mutable variable is needed inside the procedure, it has to be declared with ``var`` in the procedure body. Shadowing the parameter name is possible, and actually an idiom: -.. code-block:: nimrod +.. code-block:: nim proc printSeq(s: seq, nprinted: int = -1) = var nprinted = if nprinted == -1: s.len else: min(nprinted, s.len) for i in 0 .. <nprinted: @@ -633,7 +602,7 @@ is possible, and actually an idiom: If the procedure needs to modify the argument for the caller, a ``var`` parameter can be used: -.. code-block:: nimrod +.. code-block:: nim proc divmod(a, b: int; res, remainder: var int) = res = a div b # integer division remainder = a mod b # integer modulo operation @@ -653,17 +622,17 @@ a tuple as a return value instead of using var parameters. Discard statement ----------------- To call a procedure that returns a value just for its side effects and ignoring -its return value, a ``discard`` statement **has** to be used. Nimrod does not +its return value, a ``discard`` statement **has** to be used. Nim does not allow to silently throw away a return value: -.. code-block:: nimrod +.. code-block:: nim discard yes("May I ask a pointless question?") The return value can be ignored implicitly if the called proc/iterator has been declared with the ``discardable`` pragma: -.. code-block:: nimrod +.. code-block:: nim proc p(x, y: int): int {.discardable.} = return x + y @@ -681,7 +650,7 @@ parameters appear. This is especially true for procedures that construct a complex data type. Therefore the arguments to a procedure can be named, so that it is clear which argument belongs to which parameter: -.. code-block:: nimrod +.. code-block:: nim proc createWindow(x, y, width, height: int; title: string; show: bool): Window = ... @@ -693,7 +662,7 @@ Now that we use named arguments to call ``createWindow`` the argument order does not matter anymore. Mixing named arguments with ordered arguments is also possible, but not very readable: -.. code-block:: nimrod +.. code-block:: nim var w = createWindow(0, 0, title = "My Application", height = 600, width = 800, true) @@ -706,7 +675,7 @@ To make the ``createWindow`` proc easier to use it should provide `default values`, these are values that are used as arguments if the caller does not specify them: -.. code-block:: nimrod +.. code-block:: nim proc createWindow(x = 0, y = 0, width = 500, height = 700, title = "unknown", show = true): Window = @@ -723,9 +692,9 @@ no need to write ``title: string = "unknown"``, for example. Overloaded procedures --------------------- -Nimrod provides the ability to overload procedures similar to C++: +Nim provides the ability to overload procedures similar to C++: -.. code-block:: nimrod +.. code-block:: nim proc toString(x: int): string = ... proc toString(x: bool): string = if x: result = "true" @@ -735,7 +704,7 @@ Nimrod provides the ability to overload procedures similar to C++: echo(toString(true)) # calls the toString(x: bool) proc (Note that ``toString`` is usually the `$ <system.html#$>`_ operator in -Nimrod.) The compiler chooses the most appropriate proc for the ``toString`` +Nim.) The compiler chooses the most appropriate proc for the ``toString`` calls. How this overloading resolution algorithm works exactly is not discussed here (it will be specified in the manual soon). However, it does not lead to nasty surprises and is based on a quite simple unification @@ -744,13 +713,13 @@ algorithm. Ambiguous calls are reported as errors. Operators --------- -The Nimrod library makes heavy use of overloading - one reason for this is that +The Nim library makes heavy use of overloading - one reason for this is that each operator like ``+`` is a just an overloaded proc. The parser lets you use operators in `infix notation` (``a + b``) or `prefix notation` (``+ a``). An infix operator always receives two arguments, a prefix operator always one. Postfix operators are not possible, because this would be ambiguous: does ``a @ @ b`` mean ``(a) @ (@b)`` or ``(a@) @ (b)``? It always means -``(a) @ (@b)``, because there are no postfix operators in Nimrod. +``(a) @ (@b)``, because there are no postfix operators in Nim. Apart from a few built-in keyword operators such as ``and``, ``or``, ``not``, operators always consist of these characters: @@ -764,7 +733,7 @@ can be found in the manual. To define a new operator enclose the operator in backticks "``": -.. code-block:: nimrod +.. code-block:: nim proc `$` (x: myDataType): string = ... # now the $ operator also works with myDataType, overloading resolution # ensures that $ works for built-in types just like before @@ -772,7 +741,7 @@ To define a new operator enclose the operator in backticks "``": The "``" notation can also be used to call an operator just like any other procedure: -.. code-block:: nimrod +.. code-block:: nim if `==`( `+`(3, 4), 7): echo("True") @@ -783,7 +752,7 @@ Every variable, procedure, etc. needs to be declared before it can be used. (The reason for this is compilation efficiency.) However, this cannot be done for mutually recursive procedures: -.. code-block:: nimrod +.. code-block:: nim # forward declaration: proc even(n: int): bool @@ -810,7 +779,7 @@ Iterators Let's return to the boring counting example: -.. code-block:: nimrod +.. code-block:: nim echo("Counting to ten: ") for i in countup(1, 10): echo($i) @@ -818,7 +787,7 @@ Let's return to the boring counting example: Can a `countup <system.html#countup>`_ proc be written that supports this loop? Lets try: -.. code-block:: nimrod +.. code-block:: nim proc countup(a, b: int): int = var res = a while res <= b: @@ -831,7 +800,7 @@ finished. This *return and continue* is called a `yield` statement. Now the only thing left to do is to replace the ``proc`` keyword by ``iterator`` and there it is - our first iterator: -.. code-block:: nimrod +.. code-block:: nim iterator countup(a, b: int): int = var res = a while res <= b: @@ -868,7 +837,7 @@ that are available for them in detail. Booleans -------- -The boolean type is named ``bool`` in Nimrod and consists of the two +The boolean type is named ``bool`` in Nim and consists of the two pre-defined values ``true`` and ``false``. Conditions in while, if, elif, when statements need to be of type bool. @@ -876,7 +845,7 @@ The operators ``not, and, or, xor, <, <=, >, >=, !=, ==`` are defined for the bool type. The ``and`` and ``or`` operators perform short-cut evaluation. Example: -.. code-block:: nimrod +.. code-block:: nim while p != nil and p.name != "xyz": # p.name is not evaluated if p == nil @@ -885,7 +854,7 @@ evaluation. Example: Characters ---------- -The `character type` is named ``char`` in Nimrod. Its size is one byte. +The `character type` is named ``char`` in Nim. Its size is one byte. Thus it cannot represent an UTF-8 character, but a part of it. The reason for this is efficiency: for the overwhelming majority of use-cases, the resulting programs will still handle UTF-8 properly as UTF-8 was specially @@ -900,13 +869,13 @@ Converting from an integer to a ``char`` is done with the ``chr`` proc. Strings ------- -String variables in Nimrod are **mutable**, so appending to a string -is quite efficient. Strings in Nimrod are both zero-terminated and have a +String variables in Nim are **mutable**, so appending to a string +is quite efficient. Strings in Nim are both zero-terminated and have a length field. One can retrieve a string's length with the builtin ``len`` procedure; the length never counts the terminating zero. Accessing the terminating zero is no error and often leads to simpler code: -.. code-block:: nimrod +.. code-block:: nim if s[i] == 'a' and s[i+1] == 'b': # no need to check whether ``i < len(s)``! ... @@ -929,14 +898,14 @@ object on the heap, so there is a trade-off to be made here. Integers -------- -Nimrod has these integer types built-in: +Nim has these integer types built-in: ``int int8 int16 int32 int64 uint uint8 uint16 uint32 uint64``. The default integer type is ``int``. Integer literals can have a *type suffix* to mark them to be of another integer type: -.. code-block:: nimrod +.. code-block:: nim let x = 0 # x is of type ``int`` y = 0'i8 # y is of type ``int8`` @@ -964,7 +933,7 @@ cannot be detected at compile time). Floats ------ -Nimrod has these floating point types built-in: ``float float32 float64``. +Nim has these floating point types built-in: ``float float32 float64``. The default float type is ``float``. In the current implementation, ``float`` is always 64 bit wide. @@ -972,7 +941,7 @@ The default float type is ``float``. In the current implementation, Float literals can have a *type suffix* to mark them to be of another float type: -.. code-block:: nimrod +.. code-block:: nim var x = 0.0 # x is of type ``float`` y = 0.0'f32 # y is of type ``float32`` @@ -1001,11 +970,11 @@ having to write its ``$`` operator. You can use then the `repr graphs with cycles. The following example shows that even for basic types there is a difference between the ``$`` and ``repr`` outputs: -.. code-block:: nimrod +.. code-block:: nim var myBool = true myCharacter = 'n' - myString = "nimrod" + myString = "nim" myInteger = 42 myFloat = 3.14 echo($myBool, ":", repr(myBool)) @@ -1013,7 +982,7 @@ there is a difference between the ``$`` and ``repr`` outputs: echo($myCharacter, ":", repr(myCharacter)) # --> n:'n' echo($myString, ":", repr(myString)) - # --> nimrod:0x10fa8c050"nimrod" + # --> nim:0x10fa8c050"nim" echo($myInteger, ":", repr(myInteger)) # --> 42:42 echo($myFloat, ":", repr(myFloat)) @@ -1023,9 +992,9 @@ there is a difference between the ``$`` and ``repr`` outputs: Advanced types ============== -In Nimrod new types can be defined within a ``type`` statement: +In Nim new types can be defined within a ``type`` statement: -.. code-block:: nimrod +.. code-block:: nim type biggestInt = int64 # biggest integer type that is available biggestFloat = float64 # biggest float type that is available @@ -1041,7 +1010,7 @@ limited set. This set consists of ordered symbols. Each symbol is mapped to an integer value internally. The first symbol is represented at runtime by 0, the second by 1 and so on. Example: -.. code-block:: nimrod +.. code-block:: nim type TDirection = enum @@ -1050,7 +1019,7 @@ at runtime by 0, the second by 1 and so on. Example: var x = south # `x` is of type `TDirection`; its value is `south` echo($x) # writes "south" to `stdout` -(To prefix a new type with the letter ``T`` is a convention in Nimrod.) +(To prefix a new type with the letter ``T`` is a convention in Nim.) All comparison operators can be used with enumeration types. An enumeration's symbol can be qualified to avoid ambiguities: @@ -1066,7 +1035,7 @@ explicitly given is assigned the value of the previous symbol + 1. An explicit ordered enum can have *holes*: -.. code-block:: nimrod +.. code-block:: nim type TMyEnum = enum a = 2, b = 4, c = 89 @@ -1104,7 +1073,7 @@ Subranges A subrange type is a range of values from an integer or enumeration type (the base type). Example: -.. code-block:: nimrod +.. code-block:: nim type TSubrange = range[0..5] @@ -1119,7 +1088,7 @@ type as ``range[0..high(int)]`` (`high <system.html#high>`_ returns the maximal value). Other programming languages mandate the usage of unsigned integers for natural numbers. This is often **wrong**: you don't want unsigned arithmetic (which wraps around) just because the numbers cannot be negative. -Nimrod's ``Natural`` type helps to avoid this common programming error. +Nim's ``Natural`` type helps to avoid this common programming error. Sets @@ -1134,7 +1103,7 @@ the array has the same type. The array's index type can be any ordinal type. Arrays can be constructed via ``[]``: -.. code-block:: nimrod +.. code-block:: nim type TIntArray = array[0..5, int] # an array that is indexed with 0..5 @@ -1149,14 +1118,14 @@ Array access is always bounds checked (at compile-time or at runtime). These checks can be disabled via pragmas or invoking the compiler with the ``--bound_checks:off`` command line switch. -Arrays are value types, like any other Nimrod type. The assignment operator +Arrays are value types, like any other Nim type. The assignment operator copies the whole array contents. The built-in `len <system.html#len,TOpenArray>`_ proc returns the array's length. `low(a) <system.html#low>`_ returns the lowest valid index for the array `a` and `high(a) <system.html#high>`_ the highest valid index. -.. code-block:: nimrod +.. code-block:: nim type TDirection = enum north, east, south, west @@ -1175,13 +1144,13 @@ array `a` and `high(a) <system.html#high>`_ the highest valid index. The syntax for nested arrays (multidimensional) in other languages is a matter of appending more brackets because usually each dimension is restricted to the -same index type as the others. In nimrod you can have different dimensions with +same index type as the others. In Nim you can have different dimensions with different index types, so the nesting syntax is slightly different. Building on the previous example where a level is defined as an array of enums indexed by yet another enum, we can add the following lines to add a light tower type subdivided in height levels accessed through their integer index: -.. code-block:: nimrod +.. code-block:: nim type TLightTower = array[1..10, TLevelSetting] var @@ -1200,14 +1169,14 @@ length. Another way of defining the ``TLightTower`` to show better its nested nature would be to omit the previous definition of the ``TLevelSetting`` type and instead write it embedded directly as the type of the first dimension: -.. code-block:: nimrod +.. code-block:: nim type TLightTower = array[1..10, array[north..west, TBlinkLights]] It is quite frequent to have arrays start at zero, so there's a shortcut syntax to specify a range from zero to the specified index minus one: -.. code-block:: nimrod +.. code-block:: nim type TIntArray = array[0..5, int] # an array that is indexed with 0..5 TQuickArray = array[6, int] # an array that is indexed with 0..5 @@ -1239,7 +1208,7 @@ A sequence may be passed to an openarray parameter. Example: -.. code-block:: nimrod +.. code-block:: nim var x: seq[int] # a sequence of integers @@ -1261,7 +1230,7 @@ value. Here the ``for`` statement is looping over the results from the `pairs() <system.html#pairs.i,seq[T]>`_ iterator from the `system <system.html>`_ module. Examples: -.. code-block:: nimrod +.. code-block:: nim for i in @[3, 4, 5]: echo($i) # --> 3 @@ -1299,7 +1268,7 @@ also a means to implement passing a variable number of arguments to a procedure. The compiler converts the list of arguments to an array automatically: -.. code-block:: nimrod +.. code-block:: nim proc myWriteln(f: TFile, a: varargs[string]) = for s in items(a): write(f, s) @@ -1313,7 +1282,7 @@ This transformation is only done if the varargs parameter is the last parameter in the procedure header. It is also possible to perform type conversions in this context: -.. code-block:: nimrod +.. code-block:: nim proc myWriteln(f: TFile, a: varargs[string, `$`]) = for s in items(a): write(f, s) @@ -1336,10 +1305,10 @@ context. A slice is just an object of type TSlice which contains two bounds, `a` and `b`. By itself a slice is not very useful, but other collection types define operators which accept TSlice objects to define ranges. -.. code-block:: nimrod +.. code-block:: nim var - a = "Nimrod is a progamming language" + a = "Nim is a progamming language" b = "Slices are useless." echo a[10..15] # --> 'a prog' @@ -1366,7 +1335,7 @@ The assignment operator for tuples copies each component. The notation ``t[i]`` to access the ``i``'th field. Here ``i`` needs to be a constant integer. -.. code-block:: nimrod +.. code-block:: nim type TPerson = tuple[name: string, age: int] # type representing a person: @@ -1411,19 +1380,19 @@ use parenthesis around the values you want to assign the unpacking to, otherwise you will be assigning the same value to all the individual variables! Example: -.. code-block:: nimrod +.. code-block:: nim import os let - path = "usr/local/nimrodc.html" + path = "usr/local/nimc.html" (dir, name, ext) = splitFile(path) baddir, badname, badext = splitFile(path) echo dir # outputs `usr/local` - echo name # outputs `nimrodc` + echo name # outputs `nimc` echo ext # outputs `.html` # All the following output the same line: - # `(dir: usr/local, name: nimrodc, ext: .html)` + # `(dir: usr/local, name: nimc, ext: .html)` echo baddir echo badname echo badext @@ -1431,12 +1400,12 @@ variables! Example: Tuple unpacking **only** works in ``var`` or ``let`` blocks. The following code won't compile: -.. code-block:: nimrod +.. code-block:: nim import os var - path = "usr/local/nimrodc.html" + path = "usr/local/nimc.html" dir, name, ext = "" (dir, name, ext) = splitFile(path) @@ -1449,7 +1418,7 @@ References (similar to pointers in other programming languages) are a way to introduce many-to-one relationships. This means different references can point to and modify the same location in memory. -Nimrod distinguishes between `traced`:idx: and `untraced`:idx: references. +Nim distinguishes between `traced`:idx: and `untraced`:idx: references. Untraced references are also called *pointers*. Traced references point to objects of a garbage collected heap, untraced references point to manually allocated objects or to objects somewhere else in memory. Thus @@ -1464,7 +1433,7 @@ meaning to retrieve the item the reference points to. The ``.`` (access a tuple/object field operator) and ``[]`` (array/string/sequence index operator) operators perform implicit dereferencing operations for reference types: -.. code-block:: nimrod +.. code-block:: nim type PNode = ref TNode @@ -1489,12 +1458,12 @@ Procedural type --------------- A procedural type is a (somewhat abstract) pointer to a procedure. ``nil`` is an allowed value for a variable of a procedural type. -Nimrod uses procedural types to achieve `functional`:idx: programming +Nim uses procedural types to achieve `functional`:idx: programming techniques. Example: -.. code-block:: nimrod +.. code-block:: nim proc echoItem(x: int) = echo(x) proc forEach(action: proc (x: int)) = @@ -1513,13 +1482,13 @@ listed in the `manual <manual.html>`_. Modules ======= -Nimrod supports splitting a program into pieces with a module concept. +Nim supports splitting a program into pieces with a module concept. Each module is in its own file. Modules enable `information hiding`:idx: and `separate compilation`:idx:. A module may gain access to symbols of another module by the `import`:idx: statement. Only top-level symbols that are marked with an asterisk (``*``) are exported: -.. code-block:: nimrod +.. code-block:: nim # Module A var x*, y: int @@ -1554,7 +1523,7 @@ The algorithm for compiling modules is: This is best illustrated by an example: -.. code-block:: nimrod +.. code-block:: nim # Module A type T1* = int # Module A exports the type ``T1`` @@ -1565,7 +1534,7 @@ This is best illustrated by an example: main() -.. code-block:: nimrod +.. code-block:: nim # Module B import A # A is not parsed here! Only the already known symbols # of A are imported. @@ -1581,15 +1550,15 @@ the symbol is ambiguous, it even *has* to be qualified. A symbol is ambiguous if it is defined in two (or more) different modules and both modules are imported by a third one: -.. code-block:: nimrod +.. code-block:: nim # Module A var x*: string -.. code-block:: nimrod +.. code-block:: nim # Module B var x*: int -.. code-block:: nimrod +.. code-block:: nim # Module C import A, B write(stdout, x) # error: x is ambiguous @@ -1602,15 +1571,15 @@ imported by a third one: But this rule does not apply to procedures or iterators. Here the overloading rules apply: -.. code-block:: nimrod +.. code-block:: nim # Module A proc x*(a: int): string = result = $a -.. code-block:: nimrod +.. code-block:: nim # Module B proc x*(a: string): string = result = $a -.. code-block:: nimrod +.. code-block:: nim # Module C import A, B write(stdout, x(3)) # no error: A.x is called @@ -1627,7 +1596,7 @@ The normal ``import`` statement will bring in all exported symbols. These can be limited by naming symbols which should be excluded with the ``except`` qualifier. -.. code-block:: nimrod +.. code-block:: nim import mymodule except y @@ -1638,19 +1607,19 @@ We have already seen the simple ``import`` statement that just imports all exported symbols. An alternative that only imports listed symbols is the ``from import`` statement: -.. code-block:: nimrod +.. code-block:: nim from mymodule import x, y, z The ``from`` statement can also force namespace qualification on symbols, thereby making symbols available, but needing to be qualified to be used. -.. code-block:: nimrod +.. code-block:: nim from mymodule import x, y, z x() # use x without any qualification -.. code-block:: nimrod +.. code-block:: nim from mymodule import nil mymodule.x() # must qualify x with the module name as prefix @@ -1660,7 +1629,7 @@ to be used. Since module names are generally long to be descriptive, you can also define a shorter alias to use when qualifying symbols. -.. code-block:: nimrod +.. code-block:: nim from mymodule as m import nil m.x() # m is aliasing mymodule @@ -1672,7 +1641,7 @@ The ``include`` statement does something fundamentally different than importing a module: it merely includes the contents of a file. The ``include`` statement is useful to split up a large module into several files: -.. code-block:: nimrod +.. code-block:: nim include fileA, fileB, fileC **Note**: The documentation generator currently does not follow ``include`` @@ -1683,7 +1652,7 @@ generated documentation. Part 2 ====== -So, now that we are done with the basics, let's see what Nimrod offers apart +So, now that we are done with the basics, let's see what Nim offers apart from a nice syntax for procedural programming: `Part II <tut2.html>`_ diff --git a/doc/tut2.txt b/doc/tut2.txt index 2f42bcefc..0c54fa9a1 100644 --- a/doc/tut2.txt +++ b/doc/tut2.txt @@ -1,9 +1,9 @@ -========================= -Nimrod Tutorial (Part II) -========================= +====================== +Nim Tutorial (Part II) +====================== :Author: Andreas Rumpf -:Version: |nimrodversion| +:Version: |nimversion| .. contents:: @@ -15,7 +15,7 @@ Introduction only have originated in California." --Edsger Dijkstra -This document is a tutorial for the advanced constructs of the *Nimrod* +This document is a tutorial for the advanced constructs of the *Nim* programming language. **Note that this document is somewhat obsolete as the** `manual <manual.html>`_ **contains many more examples of the advanced language features.** @@ -24,18 +24,18 @@ features.** Pragmas ======= -Pragmas are Nimrod's method to give the compiler additional information/ +Pragmas are Nim's method to give the compiler additional information/ commands without introducing a massive number of new keywords. Pragmas are enclosed in the special ``{.`` and ``.}`` curly dot brackets. This tutorial does not cover pragmas. See the `manual <manual.html#pragmas>`_ or `user guide -<nimrodc.html#additional-features>`_ for a description of the available +<nimc.html#additional-features>`_ for a description of the available pragmas. Object Oriented Programming =========================== -While Nimrod's support for object oriented programming (OOP) is minimalistic, +While Nim's support for object oriented programming (OOP) is minimalistic, powerful OOP technics can be used. OOP is seen as *one* way to design a program, not *the only* way. Often a procedural approach leads to simpler and more efficient code. In particular, prefering composition over inheritance @@ -55,7 +55,7 @@ a *constructor*). Objects have access to their type at runtime. There is an ``of`` operator that can be used to check the object's type: -.. code-block:: nimrod +.. code-block:: nim type TPerson = object of TObject name*: string # the * means that `name` is accessible from other modules @@ -86,20 +86,20 @@ in the GTK wrapper for instance.) **Note**: Composition (*has-a* relation) is often preferable to inheritance (*is-a* relation) for simple code reuse. Since objects are value types in -Nimrod, composition is as efficient as inheritance. +Nim, composition is as efficient as inheritance. Mutually recursive types ------------------------ Objects, tuples and references can model quite complex data structures which -depend on each other; they are *mutually recursive*. In Nimrod +depend on each other; they are *mutually recursive*. In Nim these types can only be declared within a single type section. (Anything else would require arbitrary symbol lookahead which slows down compilation.) Example: -.. code-block:: nimrod +.. code-block:: nim type PNode = ref TNode # a traced reference to a TNode TNode = object @@ -114,7 +114,7 @@ Example: Type conversions ---------------- -Nimrod distinguishes between `type casts`:idx: and `type conversions`:idx:. +Nim distinguishes between `type casts`:idx: and `type conversions`:idx:. Casts are done with the ``cast`` operator and force the compiler to interpret a bit pattern to be of another type. @@ -126,7 +126,7 @@ raised. The syntax for type conversions is ``destination_type(expression_to_convert)`` (like an ordinary call): -.. code-block:: nimrod +.. code-block:: nim proc getID(x: TPerson): int = TStudent(x).id @@ -141,9 +141,9 @@ variant types are needed. An example: -.. code-block:: nimrod +.. code-block:: nim - # This is an example how an abstract syntax tree could be modeled in Nimrod + # This is an example how an abstract syntax tree could be modeled in Nim type TNodeKind = enum # the different node types nkInt, # a leaf with an integer value @@ -183,8 +183,8 @@ bound to a class. This has disadvantages: * Often it is unclear where the method should belong to: is ``join`` a string method or an array method? -Nimrod avoids these problems by not assigning methods to a class. All methods -in Nimrod are multi-methods. As we will see later, multi-methods are +Nim avoids these problems by not assigning methods to a class. All methods +in Nim are multi-methods. As we will see later, multi-methods are distinguished from procs only for dynamic binding purposes. @@ -199,7 +199,7 @@ If there are no remaining arguments, the parentheses can be omitted: This method call syntax is not restricted to objects, it can be used for any type: -.. code-block:: nimrod +.. code-block:: nim echo("abc".len) # is the same as echo(len("abc")) echo("abc".toUpper()) @@ -211,7 +211,7 @@ postfix notation.) So "pure object oriented" code is easy to write: -.. code-block:: nimrod +.. code-block:: nim import strutils stdout.writeln("Give a list of numbers (separated by spaces): ") @@ -221,12 +221,12 @@ So "pure object oriented" code is easy to write: Properties ---------- -As the above example shows, Nimrod has no need for *get-properties*: +As the above example shows, Nim has no need for *get-properties*: Ordinary get-procedures that are called with the *method call syntax* achieve the same. But setting a value is different; for this a special setter syntax is needed: -.. code-block:: nimrod +.. code-block:: nim type TSocket* = object of TObject @@ -252,7 +252,7 @@ is needed: The ``[]`` array access operator can be overloaded to provide `array properties`:idx:\ : -.. code-block:: nimrod +.. code-block:: nim type TVector* = object x, y, z: float @@ -283,7 +283,7 @@ Dynamic dispatch Procedures always use static dispatch. For dynamic dispatch replace the ``proc`` keyword by ``method``: -.. code-block:: nimrod +.. code-block:: nim type PExpr = ref object of TObject ## abstract base class for an expression PLiteral = ref object of PExpr @@ -311,7 +311,7 @@ requires dynamic binding. In a multi-method all parameters that have an object type are used for the dispatching: -.. code-block:: nimrod +.. code-block:: nim type TThing = object of TObject @@ -336,7 +336,7 @@ As the example demonstrates, invocation of a multi-method cannot be ambiguous: Collide 2 is preferred over collide 1 because the resolution works from left to right. Thus ``TUnit, TThing`` is preferred over ``TThing, TUnit``. -**Perfomance note**: Nimrod does not produce a virtual method table, but +**Perfomance note**: Nim does not produce a virtual method table, but generates dispatch trees. This avoids the expensive indirect branch for method calls and enables inlining. However, other optimizations like compile time evaluation or dead code elimination do not work with methods. @@ -345,7 +345,7 @@ evaluation or dead code elimination do not work with methods. Exceptions ========== -In Nimrod exceptions are objects. By convention, exception types are +In Nim exceptions are objects. By convention, exception types are prefixed with an 'E', not 'T'. The `system <system.html>`_ module defines an exception hierarchy that you might want to stick to. Exceptions derive from E_Base, which provides the common interface. @@ -364,7 +364,7 @@ Raise statement --------------- Raising an exception is done with the ``raise`` statement: -.. code-block:: nimrod +.. code-block:: nim var e: ref EOS new(e) @@ -375,7 +375,7 @@ If the ``raise`` keyword is not followed by an expression, the last exception is *re-raised*. For the purpose of avoiding repeating this common code pattern, the template ``newException`` in the ``system`` module can be used: -.. code-block:: nimrod +.. code-block:: nim raise newException(EOS, "the request to the OS failed") @@ -384,7 +384,7 @@ Try statement The ``try`` statement handles exceptions: -.. code-block:: nimrod +.. code-block:: nim # read the first two lines of a text file that should contain numbers # and tries to add them var @@ -428,7 +428,7 @@ If you need to *access* the actual exception object or message inside an <system.html#getCurrentExceptionMsg>`_ procs from the `system <system.html>`_ module. Example: -.. code-block:: nimrod +.. code-block:: nim try: doSomethingHere() except: @@ -460,7 +460,7 @@ instance, if you specify that a proc raises ``EIO``, and at some point it (or one of the procs it calls) starts raising a new exception the compiler will prevent that proc from compiling. Usage example: -.. code-block:: nimrod +.. code-block:: nim proc complexProc() {.raises: [EIO, EArithmetic].} = ... @@ -476,21 +476,21 @@ help you locate the offending code which has changed. If you want to add the ``{.raises.}`` pragma to existing code, the compiler can also help you. You can add the ``{.effects.}`` pragma statement to your proc and the compiler will output all inferred effects up to that point (exception -tracking is part of Nimrod's effect system). Another more roundabout way to -find out the list of exceptions raised by a proc is to use the Nimrod ``doc2`` +tracking is part of Nim's effect system). Another more roundabout way to +find out the list of exceptions raised by a proc is to use the Nim ``doc2`` command which generates documentation for a whole module and decorates all -procs with the list of raised exceptions. You can read more about Nimrod's +procs with the list of raised exceptions. You can read more about Nim's `effect system and related pragmas in the manual <manual.html#effect-system>`_. Generics ======== -Generics are Nimrod's means to parametrize procs, iterators or types +Generics are Nim's means to parametrize procs, iterators or types with `type parameters`:idx:. They are most useful for efficient type safe containers: -.. code-block:: nimrod +.. code-block:: nim type TBinaryTree[T] = object # TBinaryTree is a generic type with # with generic param ``T`` @@ -557,7 +557,7 @@ is not hidden and is used in the ``preorder`` iterator. Templates ========= -Templates are a simple substitution mechanism that operates on Nimrod's +Templates are a simple substitution mechanism that operates on Nim's abstract syntax trees. Templates are processed in the semantic pass of the compiler. They integrate well with the rest of the language and share none of C's preprocessor macros flaws. @@ -566,7 +566,7 @@ To *invoke* a template, call it like a procedure. Example: -.. code-block:: nimrod +.. code-block:: nim template `!=` (a, b: expr): expr = # this definition exists in the System module not (a == b) @@ -585,7 +585,7 @@ for IEEE floating point numbers - NaN breaks basic boolean logic.) Templates are especially useful for lazy evaluation purposes. Consider a simple proc for logging: -.. code-block:: nimrod +.. code-block:: nim const debug = true @@ -602,7 +602,7 @@ evaluation for procedures is *eager*). Turning the ``log`` proc into a template solves this problem: -.. code-block:: nimrod +.. code-block:: nim const debug = true @@ -618,32 +618,11 @@ The parameters' types can be ordinary types or the meta types ``expr`` (stands for *type description*). If the template has no explicit return type, ``stmt`` is used for consistency with procs and methods. -The template body does not open a new scope. To open a new scope use a ``block`` -statement: - -.. code-block:: nimrod - template declareInScope(x: expr, t: typeDesc): stmt {.immediate.} = - var x: t - - template declareInNewScope(x: expr, t: typeDesc): stmt {.immediate.} = - # open a new scope: - block: - var x: t - - declareInScope(a, int) - a = 42 # works, `a` is known here - - declareInNewScope(b, int) - b = 42 # does not work, `b` is unknown - -(The `manual explains <manual.html#ordinary-vs-immediate-templates>`_ why the -``immediate`` pragma is needed for these templates.) - If there is a ``stmt`` parameter it should be the last in the template declaration. The reason is that statements can be passed to a template via a special ``:`` syntax: -.. code-block:: nimrod +.. code-block:: nim template withFile(f: expr, filename: string, mode: TFileMode, body: stmt): stmt {.immediate.} = @@ -672,18 +651,18 @@ Macros ====== Macros enable advanced compile-time code transformations, but they cannot -change Nimrod's syntax. However, this is no real restriction because Nimrod's -syntax is flexible enough anyway. Macros have to be implemented in pure Nimrod +change Nim's syntax. However, this is no real restriction because Nim's +syntax is flexible enough anyway. Macros have to be implemented in pure Nim code if `foreign function interface (FFI) <manual.html#foreign-function-interface>`_ is not enabled in the compiler, but other than that restriction (which at some point in the future will go away) -you can write any kind of Nimrod code and the compiler will run it at compile +you can write any kind of Nim code and the compiler will run it at compile time. -There are two ways to write a macro, either *generating* Nimrod source code and +There are two ways to write a macro, either *generating* Nim source code and letting the compiler parse it, or creating manually an abstract syntax tree (AST) which you feed to the compiler. In order to build the AST one needs to -know how the Nimrod concrete syntax is converted to an abstract syntax tree +know how the Nim concrete syntax is converted to an abstract syntax tree (AST). The AST is documented in the `macros <macros.html>`_ module. Once your macro is finished, there are two ways to invoke it: @@ -698,13 +677,13 @@ Expression Macros The following example implements a powerful ``debug`` command that accepts a variable number of arguments: -.. code-block:: nimrod - # to work with Nimrod syntax trees, we need an API that is defined in the +.. code-block:: nim + # to work with Nim syntax trees, we need an API that is defined in the # ``macros`` module: import macros macro debug(n: varargs[expr]): stmt = - # `n` is a Nimrod AST that contains a list of expressions; + # `n` is a Nim AST that contains a list of expressions; # this macro returns a list of statements: result = newNimNode(nnkStmtList, n) # iterate over any argument that is passed to this macro: @@ -727,7 +706,7 @@ variable number of arguments: The macro call expands to: -.. code-block:: nimrod +.. code-block:: nim write(stdout, "a[0]") write(stdout, ": ") writeln(stdout, a[0]) @@ -751,7 +730,7 @@ invoked by an expression following a colon. The following example outlines a macro that generates a lexical analyzer from regular expressions: -.. code-block:: nimrod +.. code-block:: nim macro case_token(n: stmt): stmt = # creates a lexical analyzer from regular expressions @@ -784,7 +763,7 @@ To give a footstart to writing macros we will show now how to turn your typical dynamic code into something that compiles statically. For the exercise we will use the following snippet of code as the starting point: -.. code-block:: nimrod +.. code-block:: nim import strutils, tables @@ -848,7 +827,7 @@ time string with the *generated source code*, which we then pass to the ``parseStmt`` proc from the `macros module <macros.html>`_. Here is the modified source code implementing the macro: -.. code-block:: nimrod +.. code-block:: nim import macros, strutils macro readCfgAndBuildSource(cfgFilename: string): stmt = @@ -879,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 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 -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 the string being passed in to the macro. @@ -893,13 +872,13 @@ this limitation by using the ``slurp`` proc from the `system module ``gorge`` which executes an external program and captures its output). The interesting thing is that our macro does not return a runtime ``TTable`` -object. Instead, it builds up Nimrod source code into the ``source`` variable. +object. Instead, it builds up Nim source code into the ``source`` variable. For each line of the configuration file a ``const`` variable will be generated. To avoid conflicts we prefix these variables with ``cfg``. In essence, what the compiler is doing is replacing the line calling the macro with the following snippet of code: -.. code-block:: nimrod +.. code-block:: nim const cfgversion= "1.1" const cfglicenseOwner= "Hyori Lee" const cfglicenseKey= "M1Tl3PjBWO2CC48m" @@ -919,14 +898,14 @@ Generating AST by hand ++++++++++++++++++++++ To generate an AST we would need to intimately know the structures used by the -Nimrod compiler exposed in the `macros module <macros.html>`_, which at first +Nim compiler exposed in the `macros module <macros.html>`_, which at first look seems a daunting task. But we can use as helper shortcut the ``dumpTree`` macro, which is used as a statement macro instead of an expression macro. Since we know that we want to generate a bunch of ``const`` symbols we can create the following source file and compile it to see what the compiler *expects* from us: -.. code-block:: nimrod +.. code-block:: nim import macros dumpTree: @@ -969,7 +948,7 @@ identifier, optionally a type (can be an *empty* node) and the value. Armed with this knowledge, let's look at the finished version of the AST building macro: -.. code-block:: nimrod +.. code-block:: nim import macros, strutils macro readCfgAndBuildAST(cfgFilename: string): stmt = |