diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/docgen.txt | 192 | ||||
| -rw-r--r-- | doc/docgen_sample.nim | 12 | ||||
| -rw-r--r-- | doc/gc.txt | 19 | ||||
| -rw-r--r-- | doc/grammar.txt | 33 | ||||
| -rw-r--r-- | doc/idetools.txt | 20 | ||||
| -rw-r--r-- | doc/intern.txt | 2 | ||||
| -rw-r--r-- | doc/keywords.txt | 3 | ||||
| -rw-r--r-- | doc/lib.txt | 119 | ||||
| -rw-r--r-- | doc/manual.txt | 477 | ||||
| -rw-r--r-- | doc/nimrodc.txt | 20 | ||||
| -rw-r--r-- | doc/subexes.txt | 4 | ||||
| -rw-r--r-- | doc/tut1.txt | 143 | ||||
| -rw-r--r-- | doc/tut2.txt | 308 |
13 files changed, 1046 insertions, 306 deletions
diff --git a/doc/docgen.txt b/doc/docgen.txt new file mode 100644 index 000000000..acd09f2eb --- /dev/null +++ b/doc/docgen.txt @@ -0,0 +1,192 @@ +=================================== + Nimrod DocGen Tools Guide +=================================== + +:Author: Erik O'Leary +:Version: |nimrodversion| + +.. contents:: + + +Introduction +============ + +This document describes the `documentation generation tools`:idx: built into +the `Nimrod compiler <nimrodc.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 +exported symbols (*), including procedures, types, and variables. + + +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 +documentation with only their well-documented code. + +Example: + +.. code-block:: nimrod + type TPerson* = object + ## This type contains a description of a person + name: string + age: int + +Outputs:: + TPerson* = object + name: string + age: int + +This type contains a description of a person + +Field documentation comments can be added to fields like so: + +.. code-block:: nimrod + var numValues: int ## \ + ## `numValues` stores the number of values + +Note that without the `*` following the name of the type, the documentation for +this type would not be generated. Documentation will only be generated for +*exported* types/procedures/etc. + + +Nimrod file input +----------------- + +The following examples will generate documentation for the below contrived +*Nimrod* module, aptly named 'sample.nim' + +sample.nim: + +.. code-block:: nimrod + ## This module is a sample. + + import strutils + + proc helloWorld*(times: int) = + ## Takes an integer and outputs + ## as many "hello world!"s + + for i in 0 .. times-1: + echo "hello world!" + + helloWorld(5) + + +Document Types +============== + + +HTML +---- + +Generation of HTML documents is done via both the ``doc`` and ``doc2`` +commands. These command take either a single .nim file, outputting a single +.html file with the same base filename, or multiple .nim files, outputting +multiple .html files and, optionally, an index file. + +The ``doc`` command:: + nimrod doc sample + +Partial Output:: + ... + proc helloWorld*(times: int) + ... + +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 +module(s), which allows it to process macros. + +The ``doc2`` command:: + nimrod doc2 sample + +Partial Output:: + ... + proc helloWorld(times: int) {.raises: [], tags: [].} + ... + +The full output can be seen here: `docgen_sample2.html <docgen_sample2.html>`_. +As you can see, the tool has extracted additional information provided to it by +the compiler beyond what the ``doc`` command provides, such as pragmas attached +implicitly by the compiler. This type of information is not available from +looking at the AST (Abstract Syntax Tree) prior to semantic checking, as the +``doc`` command does. + + +JSON +---- + +Generation of JSON documents is done via the ``jsondoc`` command. This command +takes in a .nim file, and outputs a .json file with the same base filename. +Note that this tool is built off of the ``doc`` command, and therefore is +performed before semantic checking. + +The ``jsondoc`` command:: + nimrod jsondoc sample + +Output:: + [ + { + "comment": "This module is a sample." + }, + { + "name": "helloWorld", + "type": "skProc", + "description": "Takes an integer and outputs as many "hello world!"s", + "code": "proc helloWorld*(times: int)" + } + ] + + +Related Options +=============== + +``--project`` switch +:: + nimrod doc2 --project sample + +This will recursively generate documentation of all nimrod 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! + + +``--index`` switch +:: + nimrod doc2 --index:on sample + +This will generate an index of all the exported symbols in the input Nimrod +module, and put it into a neighboring file with the extension of `.idx`. + + +Other Input Formats +=================== + +The *Nimrod 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 +supports highlighting of C++ and some other c-like languages. + +Usage:: + nimrod rst2html docgen.txt + +Output:: + You're reading it! + +The input can be viewed here `docgen.txt <docgen.txt>`_. The ``rst2tex`` +command is invoked identically to ``rst2html``, but outputs a .tex file instead +of .html. + + +Additional Resources +========= + +`Nimrod Compiler User Guide <nimrodc.html#command-line-switches>`_ + +`RST Quick Reference +<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ diff --git a/doc/docgen_sample.nim b/doc/docgen_sample.nim new file mode 100644 index 000000000..875993187 --- /dev/null +++ b/doc/docgen_sample.nim @@ -0,0 +1,12 @@ +## This module is a sample. + +import strutils + +proc helloWorld*(times: int) = + ## Takes an integer and outputs + ## as many "hello world!"s + + for i in 0 .. times-1: + echo "hello world!" + +helloWorld(5) diff --git a/doc/gc.txt b/doc/gc.txt index 854f9ce2a..18fb03b6d 100644 --- a/doc/gc.txt +++ b/doc/gc.txt @@ -13,7 +13,7 @@ Introduction This document describes how the GC works and how to tune it for (soft) `realtime systems`:idx:. -The basic algorithm is *Deferrent Reference Counting* with cycle detection. +The basic algorithm is *Deferred Reference Counting* with cycle detection. References on the stack are not counted for better performance (and easier C code generation). The GC **never** scans the whole heap but it may scan the delta-subgraph of the heap that changed since its last run. @@ -107,3 +107,20 @@ that up to 100 objects are traversed and freed before it checks again. Thus ``workPackage`` affects the timing granularity and may need to be tweaked in 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 +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: + +* getTotalMem(): returns the amount of total memory managed by the GC. +* getOccupiedMem(): bytes reserved by the GC and used by objects. +* getFreeMem(): bytes reserved by the GC and not in use. + +In addition to ``GC_ref`` and ``GC_unref`` you can avoid the GC by manually +allocating memory with procs like ``alloc``, ``allocShared``, or +``allocCStringArray``. The GC won't try to free them, you need to call their +respective *dealloc* pairs when you are done with them or they will leak. diff --git a/doc/grammar.txt b/doc/grammar.txt index 7fe2b56aa..63e898e11 100644 --- a/doc/grammar.txt +++ b/doc/grammar.txt @@ -42,14 +42,14 @@ par = '(' optInd (&parKeyw complexOrSimpleStmt ^+ ';' | simpleExpr ('=' expr (';' complexOrSimpleStmt ^+ ';' )? )? | (':' expr)? (',' (exprColonEqExpr comma?)*)? )? optPar ')' +literal = | INT_LIT | INT8_LIT | INT16_LIT | INT32_LIT | INT64_LIT + | UINT_LIT | UINT8_LIT | UINT16_LIT | UINT32_LIT | UINT64_LIT + | FLOAT_LIT | FLOAT32_LIT | FLOAT64_LIT + | STR_LIT | RSTR_LIT | TRIPLESTR_LIT + | CHAR_LIT + | NIL generalizedLit = GENERALIZED_STR_LIT | GENERALIZED_TRIPLESTR_LIT -identOrLiteral = generalizedLit | symbol - | INT_LIT | INT8_LIT | INT16_LIT | INT32_LIT | INT64_LIT - | UINT_LIT | UINT8_LIT | UINT16_LIT | UINT32_LIT | UINT64_LIT - | FLOAT_LIT | FLOAT32_LIT | FLOAT64_LIT - | STR_LIT | RSTR_LIT | TRIPLESTR_LIT - | CHAR_LIT - | NIL +identOrLiteral = generalizedLit | symbol | literal | par | arrayConstr | setOrTableConstr | castExpr tupleConstr = '(' optInd (exprColonEqExpr comma?)* optPar ')' @@ -59,6 +59,7 @@ primarySuffix = '(' (exprColonEqExpr comma?)* ')' doBlocks? | '.' optInd ('type' | 'addr' | symbol) generalizedLit? | '[' optInd indexExprList optPar ']' | '{' optInd indexExprList optPar '}' + | &( '`'|IDENT|literal|'cast') expr # command syntax condExpr = expr colcom expr optInd ('elif' expr colcom expr optInd)* 'else' colcom expr @@ -95,18 +96,19 @@ primary = typeKeyw typeDescK / 'bind' primary typeDesc = simpleExpr typeDefAux = simpleExpr + | 'generic' typeClass +macroColon = ':' stmt? ( IND{=} 'of' exprList ':' stmt + | IND{=} 'elif' expr ':' stmt + | IND{=} 'except' exprList ':' stmt + | IND{=} 'else' ':' stmt )* exprStmt = simpleExpr (( '=' optInd expr ) / ( expr ^+ comma doBlocks - / ':' stmt? ( IND{=} 'of' exprList ':' stmt - | IND{=} 'elif' expr ':' stmt - | IND{=} 'except' exprList ':' stmt - | IND{=} 'else' ':' stmt )* + / macroColon ))? -moduleName = expr ('as' expr)? -importStmt = 'import' optInd moduleName - ((comma moduleName)* +importStmt = 'import' optInd expr + ((comma expr)* / 'except' optInd (expr ^+ comma)) includeStmt = 'include' optInd expr ^+ comma fromStmt = 'from' moduleName 'import' optInd expr (comma expr)* @@ -161,6 +163,9 @@ objectCase = 'case' identWithPragma ':' typeDesc ':'? COMMENT? objectPart = IND{>} objectPart^+IND{=} DED / objectWhen / objectCase / 'nil' / declColonEquals object = 'object' pragma? ('of' typeDesc)? COMMENT? objectPart +typeClassParam = ('var')? symbol +typeClass = typeClassParam ^* ',' (pragma)? ('of' typeDesc ^* ',')? + &IND{>} stmt distinct = 'distinct' optInd typeDesc typeDef = identWithPragma genericParamList? '=' optInd typeDefAux indAndComment? diff --git a/doc/idetools.txt b/doc/idetools.txt index fdc4ebde6..c1eba9e5f 100644 --- a/doc/idetools.txt +++ b/doc/idetools.txt @@ -8,6 +8,11 @@ .. contents:: +.. raw:: html + <blockquote><p> + "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, and being so fast makes it suited to provide external queries for text editors about the source code being written. Through the @@ -522,21 +527,6 @@ 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 - $ nimrod c tests/tester.nim - -Running the tester without parameters will display some options. -To run the caas test suite (and other special tests) you need to -use the `special` command. You need to run this command from the -root of the checkout or it won't be able to open the required files:: - - $ ./tests/tester special - -However this is a roundabout way of running the test suite. You can -also compile and run ``tests/caasdriver.nim`` manually. In fact, -running it manually will allow you to specify special parameters -too. Example:: - $ cd my/nimrod/checkout/tests $ nimrod c caasdriver.nim diff --git a/doc/intern.txt b/doc/intern.txt index 9d9eb66cc..c602e4933 100644 --- a/doc/intern.txt +++ b/doc/intern.txt @@ -215,7 +215,7 @@ Backend issues - Init procs must not be "forgotten" to be called. - Files must not be "forgotten" to be linked. - Anything that is contained in ``nim__dat.c`` is shared between modules - implicitely. + implicitly. - Method dispatchers are global. - DLL loading via ``dlsym`` is global. - Emulated thread vars are global. diff --git a/doc/keywords.txt b/doc/keywords.txt index fa3ce4786..2d18d7969 100644 --- a/doc/keywords.txt +++ b/doc/keywords.txt @@ -7,13 +7,14 @@ finally for from generic if import in include interface is isnot iterator lambda let -macro method mixin using mod +macro method mixin mod nil not notin object of or out proc ptr raise ref return shared shl shr static template try tuple type +using var when while with without xor diff --git a/doc/lib.txt b/doc/lib.txt index 1b004aa9d..3214cdae2 100644 --- a/doc/lib.txt +++ b/doc/lib.txt @@ -64,6 +64,8 @@ Core 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. * `sets <sets.html>`_ @@ -225,7 +227,12 @@ Parsers ------- * `parseopt <parseopt.html>`_ - The ``parseopt`` module implements a command line option parser. This + The ``parseopt`` module implements a command line option parser. + **Deprecated since version 0.9.3:** Use the `parseopt2 + <parseopt2.html>`_ module instead. + +* `parseopt2 <parseopt2.html>`_ + The ``parseopt2`` module implements a command line option parser. This supports long and short command options with optional values and command line arguments. @@ -334,6 +341,9 @@ Miscellaneous * `endians <endians.html>`_ This module contains helpers that deal with different byte orders. +* `logging <logging.html>`_ + This module implements a simple logger. + Database support ---------------- @@ -379,9 +389,6 @@ Database support * `db_mongo <db_mongo.html>`_ A higher level **mongodb** wrapper. -* `mongodb <mongo.html>`_ - Lower level wrapper for the **mongodb** client C library. - Other ----- @@ -444,45 +451,6 @@ UNIX specific * `posix <posix.html>`_ Contains a wrapper for the POSIX standard. -* `cursorfont <cursorfont.html>`_ - Part of the wrapper for X11. -* `keysym <keysym.html>`_ - Part of the wrapper for X11. -* `x <x.html>`_ - Part of the wrapper for X11. -* `xatom <xatom.html>`_ - Part of the wrapper for X11. -* `xcms <xcms.html>`_ - Part of the wrapper for X11. -* `xf86dga <xf86dga.html>`_ - Part of the wrapper for X11. -* `xf86vmode <xf86vmode.html>`_ - Part of the wrapper for X11. -* `xi <xi.html>`_ - Part of the wrapper for X11. -* `xinerama <xinerama.html>`_ - Part of the wrapper for X11. -* `xkb <xkb.html>`_ - Part of the wrapper for X11. -* `xkblib <xkblib.html>`_ - Part of the wrapper for X11. -* `xlib <xlib.html>`_ - Part of the wrapper for X11. -* `xrandr <xrandr.html>`_ - Part of the wrapper for X11. -* `xrender <xrender.html>`_ - Part of the wrapper for X11. -* `xresource <xresource.html>`_ - Part of the wrapper for X11. -* `xshm <xshm.html>`_ - Part of the wrapper for X11. -* `xutil <xutil.html>`_ - Part of the wrapper for X11. -* `xv <xv.html>`_ - Part of the wrapper for X11. -* `xvlib <xvlib.html>`_ - Part of the wrapper for X11. - * `readline <readline.html>`_ Part of the wrapper for the GNU readline library. * `history <history.html>`_ @@ -503,15 +471,6 @@ Regular expressions Graphics libraries ------------------ -* `cairo <cairo.html>`_ - Wrapper for the cairo library. -* `cairoft <cairoft.html>`_ - Wrapper for the cairoft library. -* `cairowin32 <cairowin32.html>`_ - Wrapper for the cairowin32 library. -* `cairoxlib <cairoxlib.html>`_ - Wrapper for the cairoxlib library. - * `sdl <sdl.html>`_ Part of the wrapper for SDL. * `sdl_gfx <sdl_gfx.html>`_ @@ -527,47 +486,10 @@ Graphics libraries * `smpeg <smpeg.html>`_ Part of the wrapper for SDL. -* `gl <gl.html>`_ - Part of the wrapper for OpenGL. -* `glext <glext.html>`_ - Part of the wrapper for OpenGL. -* `glu <glu.html>`_ - Part of the wrapper for OpenGL. -* `glut <glut.html>`_ - Part of the wrapper for OpenGL. -* `glx <glx.html>`_ - Part of the wrapper for OpenGL. -* `wingl <wingl.html>`_ - Part of the wrapper for OpenGL. - -* `opengl <opengl.html>`_ - New wrapper for OpenGL supporting up to version 4.2. - GUI libraries ------------- -* `atk <atk.html>`_ - Wrapper for the atk library. -* `gdk2 <gdk2.html>`_ - Wrapper for the gdk2 library. -* `gdk2pixbuf <gdk2pixbuf.html>`_ - Wrapper for the gdk2pixbuf library. -* `gdkglext <gdkglext.html>`_ - Wrapper for the gdkglext library. -* `glib2 <glib2.html>`_ - Wrapper for the glib2 library. -* `gtk2 <gtk2.html>`_ - Wrapper for the gtk2 library. -* `gtkglext <gtkglext.html>`_ - Wrapper for the gtkglext library. -* `gtkhtml <gtkhtml.html>`_ - Wrapper for the gtkhtml library. -* `libglade2 <libglade2.html>`_ - Wrapper for the libglade2 library. -* `pango <pango.html>`_ - Wrapper for the pango library. -* `pangoutils <pangoutils.html>`_ - Wrapper for the pangoutils library. + * `iup <iup.html>`_ Wrapper of the IUP GUI library. @@ -581,6 +503,8 @@ Database support Contains a wrapper for the mySQL API. * `sqlite3 <sqlite3.html>`_ Contains a wrapper for SQLite 3 API. +* `mongodb <mongo.html>`_ + Lower level wrapper for the **mongodb** client C library. * `odbcsql <odbcsql.html>`_ interface to the ODBC driver. * `sphinx <sphinx.html>`_ @@ -610,21 +534,6 @@ Network Programming and Internet Protocols Wrapper for OpenSSL. -Scripting languages -------------------- - -* `lua <lua.html>`_ - Part of the wrapper for Lua. -* `lualib <lualib.html>`_ - Part of the wrapper for Lua. -* `lauxlib <lauxlib.html>`_ - Part of the wrapper for Lua. -* `tcl <tcl.html>`_ - Wrapper for the TCL programming language. -* `python <python.html>`_ - Wrapper for the Python programming language. - - Data Compression and Archiving ------------------------------ diff --git a/doc/manual.txt b/doc/manual.txt index c63df0304..520e4f62e 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -12,6 +12,8 @@ Nimrod Manual user to one/some of the other players, but the total amount seems to remain pretty much constant for a given task. -- Ran + + About this document =================== @@ -312,14 +314,39 @@ Character literals ------------------ Character literals are enclosed in single quotes ``''`` and can contain the -same escape sequences as strings - with one exception: ``\n`` is not allowed -as it may be wider than one character (often it is the pair CR/LF for example). +same escape sequences as strings - with one exception: `newline`:idx: (``\n``) +is not allowed as it may be wider than one character (often it is the pair +CR/LF for example). Here are the valid `escape sequences`:idx: for character +literals: + +================== =================================================== + Escape sequence Meaning +================== =================================================== + ``\r``, ``\c`` `carriage return`:idx: + ``\l`` `line feed`:idx: + ``\f`` `form feed`:idx: + ``\t`` `tabulator`:idx: + ``\v`` `vertical tabulator`:idx: + ``\\`` `backslash`:idx: + ``\"`` `quotation mark`:idx: + ``\'`` `apostrophe`:idx: + ``\`` '0'..'9'+ `character with decimal value d`:idx:; + all decimal digits directly + following are used for the character + ``\a`` `alert`:idx: + ``\b`` `backspace`:idx: + ``\e`` `escape`:idx: `[ESC]`:idx: + ``\x`` HH `character with hex value HH`:idx:; + exactly two hex digits are allowed +================== =================================================== + 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 -``set[char]`` efficiently as many algorithms rely on this feature. +this. Another reason is that Nimrod 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>`_. Numerical constants @@ -750,7 +777,8 @@ designed for this. Another reason is that Nimrod 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. +character. ``TRune`` is declared in the `unicode module <unicode.html>`_. + @@ -847,8 +875,8 @@ arrays, they can be used in case statements: Per convention, all strings are UTF-8 strings, but this is not enforced. For example, when reading strings from binary files, they are merely a sequence of bytes. The index operation ``s[i]`` means the i-th *char* of ``s``, not the -i-th *unichar*. The iterator ``runes`` from the ``unicode`` -module can be used for iteration over all Unicode characters. +i-th *unichar*. The iterator ``runes`` from the `unicode module +<unicode.html>`_ can be used for iteration over all Unicode characters. CString type @@ -1268,12 +1296,13 @@ exclude ``nil`` as a valid value with the `not nil`:idx: annotation: # compiler catches this: p(nil) - # but not this: + # and also this: var x: PObject p(x) -As shown in the example this is merely an annotation for documentation purposes; -for now the compiler can only catch the most trivial type violations. +The compiler ensures that every code path initializes variables which contain +not nilable pointers. The details of this analysis are still to be specified +here. Procedural type @@ -1286,12 +1315,9 @@ Examples: .. code-block:: nimrod - type - TCallback = proc (x: int) {.cdecl.} - - proc printItem(x: Int) = ... + proc printItem(x: int) = ... - proc forEach(c: TCallback) = + proc forEach(c: proc (x: int) {.cdecl.}) = ... forEach(printItem) # this will NOT work because calling conventions differ @@ -1306,7 +1332,7 @@ Examples: # has default calling convention echo "x: ", mouseX, " y: ", mouseY - proc setOnMouseMove(mouseMoveEvent: TOnMouseMove) = nil + proc setOnMouseMove(mouseMoveEvent: TOnMouseMove) = discard # ok, 'onMouseMove' has the default calling convention, which is compatible # to 'closure': @@ -1452,7 +1478,7 @@ But it seems all this boilerplate code needs to be repeated for the ``TEuro`` currency. This can be solved with templates_. .. code-block:: nimrod - template Additive(typ: typedesc): stmt = + template additive(typ: typedesc): stmt = proc `+` *(x, y: typ): typ {.borrow.} proc `-` *(x, y: typ): typ {.borrow.} @@ -1460,26 +1486,26 @@ currency. This can be solved with templates_. proc `+` *(x: typ): typ {.borrow.} proc `-` *(x: typ): typ {.borrow.} - template Multiplicative(typ, base: typedesc): stmt = + template multiplicative(typ, base: typedesc): stmt = proc `*` *(x: typ, y: base): typ {.borrow.} proc `*` *(x: base, y: typ): typ {.borrow.} proc `div` *(x: typ, y: base): typ {.borrow.} proc `mod` *(x: typ, y: base): typ {.borrow.} - template Comparable(typ: typedesc): stmt = + template comparable(typ: typedesc): stmt = proc `<` * (x, y: typ): bool {.borrow.} proc `<=` * (x, y: typ): bool {.borrow.} proc `==` * (x, y: typ): bool {.borrow.} - template DefineCurrency(typ, base: expr): stmt = + template defineCurrency(typ, base: expr): stmt = type typ* = distinct base - Additive(typ) - Multiplicative(typ, base) - Comparable(typ) + additive(typ) + multiplicative(typ, base) + comparable(typ) - DefineCurrency(TDollar, int) - DefineCurrency(TEuro, int) + defineCurrency(TDollar, int) + defineCurrency(TEuro, int) Void type @@ -1504,8 +1530,8 @@ The ``void`` type is particularly useful for generic code: else: p(x) - proc intProc(x: int) = nil - proc emptyProc() = nil + proc intProc(x: int) = discard + proc emptyProc() = discard callProc[int](intProc, 12) callProc[void](emptyProc) @@ -1767,6 +1793,15 @@ been declared with the `discardable`:idx: pragma: p(3, 4) # now valid +An empty ``discard`` statement is often used as a null statement: + +.. code-block:: nimrod + proc classify(s: string) = + case s[0] + of SymChars, '_': echo "an identifier" + of '0'..'9': echo "a number" + else: discard + Var statement ------------- @@ -1816,7 +1851,7 @@ If a proc is annotated with the ``noinit`` pragma this refers to its implicit ``result`` variable: .. code-block:: nimrod - proc returnUndefinedValue: int {.noinit.} = nil + proc returnUndefinedValue: int {.noinit.} = discard The implicit initialization can be also prevented by the `requiresInit`:idx: @@ -2196,12 +2231,14 @@ Instead of: 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 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. +**Warning**: The ``using`` statement is highly experimental! + +The `using statement`:idx: provides syntactic convenience for procs that +heavily use a single contextual parameter. When applied to a variable or a +constant, it will instruct Nimrod to automatically consider the used symbol as +a hidden leading parameter for any procedure calls, following the using +statement in the current scope. Thus, it behaves much like the hidden `this` +parameter available in some object-oriented programming languages. .. code-block:: nimrod @@ -2224,6 +2261,24 @@ from different modules having the same name. import windows, sdl using sdl.SetTimer +Note that ``using`` only *adds* to the current context, it doesn't remove or +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 + var a, b = "kill it" + using a + add(" with fire") + using b + add(" with water") + echo a + echo b + +When the compiler reaches the second ``add`` call, both ``a`` and ``b`` could +be used with the proc, so one gets ``Error: expression '(a|b)' has no type (or +is ambiguous)``. To solve this you would need to nest ``using`` with a +``block`` statement so as to control the reach of the ``using`` statement. If expression ------------- @@ -2314,8 +2369,8 @@ The `addr`:idx: operator returns the address of an l-value. If the type of the location is ``T``, the `addr` operator result is of the type ``ptr T``. An address is always an untraced reference. Taking the address of an object that resides on the stack is **unsafe**, as the pointer may live longer than the -object on the stack and can thus reference a non-existing object. You can get -the address of variables, but you can't use it on variables declared through +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 @@ -2403,6 +2458,83 @@ notation. (Thus an operator can have more than two parameters): assert `*+`(3, 4, 6) == `*`(a, `+`(b, c)) + +Method call syntax +------------------ + +For object oriented programming, the syntax ``obj.method(args)`` can be used +instead of ``method(obj, args)``. The parentheses can be omitted if there are no +remaining arguments: ``obj.len`` (instead of ``len(obj)``). + +This `method call syntax`:idx: is not restricted to objects, it can be used +to supply any type of first argument for procedures: + +.. code-block:: nimrod + + echo("abc".len) # is the same as echo(len("abc")) + echo("abc".toUpper()) + echo({'a', 'b', 'c'}.card) + stdout.writeln("Hallo") # the same as writeln(stdout, "Hallo") + +Another way to look at the method call syntax is that it provides the missing +postfix notation. + + +Properties +---------- +Nimrod 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 + + type + TSocket* = object of TObject + FHost: int # cannot be accessed from the outside of the module + # the `F` prefix is a convention to avoid clashes since + # the accessors are named `host` + + proc `host=`*(s: var TSocket, value: int) {.inline.} = + ## setter of hostAddr + s.FHost = value + + proc host*(s: TSocket): int {.inline.} = + ## getter of hostAddr + return s.FHost + + var + s: TSocket + s.host = 34 # same as `host=`(s, 34) + + +Command invocation syntax +------------------------- + +Routines can be invoked without the ``()`` if the call is syntatically +a statement. This `command invocation syntax`:idx: also works for +expressions, but then only a single argument may follow. This restriction +means ``echo f 1, f 2`` is parsed as ``echo(f(1), f(2))`` and not as +``echo(f(1, f(2)))``. The method call syntax may be used to provide one +more argument in this case: + +.. code-block:: nimrod + proc optarg(x:int, y:int = 0):int = x + y + proc singlearg(x:int):int = 20*x + + echo optarg 1, " ", singlearg 2 # prints "1 40" + + let fail = optarg 1, optarg 8 # Wrong. Too many arguments for a command call + let x = optarg(1, optarg 8) # traditional procedure call with 2 arguments + let y = 1.optarg optarg 8 # same thing as above, w/o the parenthesis + assert x == y + +The command invocation syntax also can't have complex expressions as arguments. +For example: (`anonymous procs`_), ``if``, ``case`` or ``try``. The (`do +notation`_) is limited, but usable for a single proc (see the example in the +corresponding section). Function calls with no arguments still needs () to +distinguish between a call and the function itself as a first class value. + + Closures -------- @@ -2415,6 +2547,7 @@ the closure and its enclosing scope (i.e. any modifications made to them are visible in both places). The closure environment may be allocated on the heap or on the stack if the compiler determines that this would be safe. + Anonymous Procs --------------- @@ -2441,6 +2574,9 @@ calls can use the ``do`` keyword: .. code-block:: nimrod sort(cities) do (x,y: string) -> int: cmp(x.len, y.len) + # Less parenthesis using the method plus command syntax: + cities = cities.map do (x:string) -> string: + "City of " & x ``do`` is written after the parentheses enclosing the regular proc params. The proc expression represented by the do block is appended to them. @@ -2710,7 +2846,7 @@ First class iterators There are 2 kinds of iterators in Nimrod: *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 -increasee in code size. Inline iterators are second class +increase in code size. Inline iterators are second class citizens; one cannot pass them around like first class procs. In contrast to that, a `closure iterator`:idx: can be passed around: @@ -2781,7 +2917,24 @@ a `collaborative tasking`:idx: system: The builtin ``system.finished`` can be used to determine if an iterator has finished its operation; no exception is raised on an attempt to invoke an -iterator that has already finished its work. +iterator that has already finished its work. + +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 + proc mycount(a, b: int): iterator (): int = + return iterator (): int = + var x = a + while x <= b: + yield x + inc x + + let foo = mycount 1, 4 + + for f in foo(): + echo f Type sections @@ -2869,9 +3022,9 @@ in an implicit try block: finally: close(f) ... -The ``except`` statement has a limitation in this form: you can't specify the -type of the exception, you have to catch everything. Also, if you want to use -both ``finally`` and ``except`` you need to reverse the usual sequence of the +The ``except`` statement has a limitation in this form: one can't specify the +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 @@ -3207,7 +3360,7 @@ Nimrod also allows for type classes and regular types to be specified as `type constraints`:idx: of the generic type parameter: .. code-block:: nimrod - proc onlyIntOrString[T: int|string](x, y: T) = nil + proc onlyIntOrString[T: int|string](x, y: T) = discard onlyIntOrString(450, 616) # valid onlyIntOrString(5.0, 0.0) # type mismatch @@ -3289,27 +3442,36 @@ Declarative type classes are written in the following form: for value in c: type(value) is T - -The identifiers following the `generic` keyword are treated as variables of -the matched type and the body of the type class consists of arbitrary code that -must be valid under these circumstances. - -Specifically, the type class will be matched if: +The type class will be matched if: a) all of the expressions within the body can be compiled for the tested type b) all statically evaluatable boolean expressions in the body must be true -Please note that the ``is`` operator allows you to easily verify the precise type -signatures of the required operations, but since type inference and default -parameters are still applied in the provided block, it's also possible to encode -usage protocols that doesn't reveal implementation details. +The identifiers following the `generic` keyword represent instances of the +currently matched type. These instances can act both as variables of the type, +when used in contexts, where a value is expected, and as the type itself, when +used in a contexts, where a type is expected. + +Please note that the ``is`` operator allows one to easily verify the precise +type signatures of the required operations, but since type inference and +default parameters are still applied in the provided block, it's also possible +to encode usage protocols that doesn't reveal implementation details. + +As a special rule providing further convenience when writing type classes, any +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 + type + OutputStream = generic S + write(var S, string) Much like generics, the user defined type classes will be instantiated exactly once for each tested type and any static code included within them will also be executed once. - Return Type Inference --------------------- @@ -3360,13 +3522,41 @@ A symbol can be forced to be open by a `mixin`:idx: declaration: .. code-block:: nimrod proc create*[T](): ref T = - # there is no overloaded 'mixin' here, so we need to state that it's an + # there is no overloaded 'init' here, so we need to state that it's an # open symbol explicitly: mixin init new result init result +Bind statement +-------------- + +The `bind`:idx: statement is the counterpart to the ``mixin`` statement. It +can be used to explicitly declare identifiers that should be bound early (i.e. +the identifiers should be looked up in the scope of the template/generic +definition): + +.. code-block:: nimrod + # Module A + var + lastId = 0 + + template genId*: expr = + bind lastId + inc(lastId) + lastId + +.. code-block:: nimrod + # Module B + import A + + echo genId() + +But a ``bind`` is rarely useful because symbol binding from the definition +scope is the default. + + Templates ========= @@ -3426,28 +3616,6 @@ receive undeclared identifiers: declareInt(x) # valid -Scoping in templates --------------------- - -The template body does not open a new scope. To open a new scope a ``block`` -statement can be used: - -.. 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 - - Passing a code block to a template ---------------------------------- @@ -3458,50 +3626,28 @@ special ``:`` syntax: .. code-block:: nimrod template withFile(f, fn, mode: expr, actions: stmt): stmt {.immediate.} = - block: - var f: TFile - if open(f, fn, mode): - try: - actions - finally: - close(f) - else: - quit("cannot open: " & fn) + var f: TFile + if open(f, fn, mode): + try: + actions + finally: + close(f) + else: + quit("cannot open: " & fn) withFile(txt, "ttempl3.txt", fmWrite): txt.writeln("line 1") txt.writeln("line 2") In the example the two ``writeln`` statements are bound to the ``actions`` -parameter. - -**Note:** The symbol binding rules for templates might change! +parameter. -Symbol binding within templates happens after template instantiation: -.. code-block:: nimrod - # Module A - var - lastId = 0 - - template genId*: expr = - inc(lastId) - lastId - -.. code-block:: nimrod - # Module B - import A - - echo genId() # Error: undeclared identifier: 'lastId' - - -Bind statement --------------- +Symbol binding in templates +--------------------------- -Exporting a template is a often a leaky abstraction as it can depend on -symbols that are not visible from a client module. However, to compensate for -this case, a `bind`:idx: statement can be used: It declares all identifiers -that should be bound early (i.e. when the template is parsed): +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 # Module A @@ -3509,7 +3655,6 @@ that should be bound early (i.e. when the template is parsed): lastId = 0 template genId*: expr = - bind lastId inc(lastId) lastId @@ -3517,9 +3662,11 @@ that should be bound early (i.e. when the template is parsed): # Module B import A - echo genId() # Works + echo genId() # Works as 'lastId' has been bound in 'genId's defining scope + +As in generics symbol binding can be influenced via ``mixin`` or ``bind`` +statements. -A ``bind`` statement can also be used in generics for the same purpose. Identifier construction @@ -3773,7 +3920,7 @@ regular expressions: macro case_token(n: stmt): stmt = # creates a lexical analyzer from regular expressions # ... (implementation is an exercise for the reader :-) - nil + discard case_token: # this colon tells the parser it is a macro statement of r"[A-Za-z_]+[A-Za-z_0-9]*": @@ -3802,22 +3949,76 @@ Whole routines (procs, iterators etc.) can also be passed to a template or a macro via the pragma notation: .. code-block:: nimrod - template m(s: stmt) = nil + template m(s: stmt) = discard - proc p() {.m.} = nil + proc p() {.m.} = discard This is a simple syntactic transformation into: .. code-block:: nimrod - template m(s: stmt) = nil + template m(s: stmt) = discard m: - proc p() = nil + proc p() = discard Special Types ============= +static[T] +--------- + +As their name suggests, static params must be known at compile-time: + +.. code-block:: nimrod + + proc precompiledRegex(pattern: static[string]): TRegEx = + var res {.global.} = re(pattern) + return res + + precompiledRegex("/d+") # Replaces the call with a precompiled + # regex, stored in a global variable + + precompiledRegex(paramStr(1)) # Error, command-line options + # are not known at compile-time + + +For the purposes of code generation, all static params are treated as +generic params - the proc will be compiled separately for each unique +supplied value (or combination of values). + +Furthermore, the system module defines a `semistatic[T]` type than can be +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 + + # The following proc will be compiled once for each unique static + # value and also once for the case handling all run-time values: + + proc re(pattern: semistatic[string]): TRegEx = + when isStatic(pattern): + return precompiledRegex(pattern) + else: + return compile(pattern) + +Static params can also appear in the signatures of generic types: + +.. code-block:: nimrod + + type + Matrix[M,N: static[int]; T: Number] = array[0..(M*N - 1), T] + # Note how `Number` is just a type constraint here, while + # `static[int]` requires us to supply a compile-time int value + + AffineTransform2D[T] = Matrix[3, 3, T] + AffineTransform3D[T] = Matrix[4, 4, T] + + AffineTransform3D[float] # OK + AffineTransform2D[string] # Error, `string` is not a `Number` + + typedesc -------- @@ -4133,9 +4334,9 @@ all the arguments, but also the matched operators in reverse polish notation: TMatrix = object dummy: int - proc `*`(a, b: TMatrix): TMatrix = nil - proc `+`(a, b: TMatrix): TMatrix = nil - proc `-`(a, b: TMatrix): TMatrix = nil + proc `*`(a, b: TMatrix): TMatrix = discard + proc `+`(a, b: TMatrix): TMatrix = discard + proc `-`(a, b: TMatrix): TMatrix = discard proc `$`(a: TMatrix): string = result = $a.dummy proc mat21(): TMatrix = result.dummy = 21 @@ -4551,10 +4752,16 @@ These rules ensure that the construction is tied to a variable and can easily be destructed at its scope exit. Later versions of the language will improve the support of destructors. +Be aware that destructors are not called for objects allocated with ``new``. +This may change in future versions of language, but for now use +the ``finalizer`` parameter to ``new``. + delegator pragma ---------------- +**Note**: The design of the delegator feature is subject to change. + The delegator pragma can be used to intercept and rewrite proc call and field access attempts referring to previously undeclared symbol names. It can be used to provide a fluent interface to objects lying outside the static confines of @@ -4699,7 +4906,11 @@ fatal pragma ------------ The `fatal`:idx: 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. +is guaranteed to be aborted by this pragma. Example: + +.. code-block:: nimrod + when not defined(objc): + {.fatal: "Compile this program with the objc command!".} warning pragma -------------- @@ -5033,9 +5244,9 @@ the same feature under the same name. Exportc pragma -------------- The `exportc`:idx: pragma provides a means to export a type, a variable, or a -procedure to C. The optional argument is a string containing the C identifier. -If the argument is missing, the C name is the Nimrod -identifier *exactly as spelled*: +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*: .. code-block:: Nimrod proc callme(formatstr: cstring) {.exportc: "callMe", varargs.} @@ -5044,6 +5255,18 @@ Note that this pragma is somewhat of a misnomer: Other backends will provide the same feature under the same name. +Extern pragma +------------- +Like ``exportc`` or ``importc`` the `extern`:idx: pragma affects name +mangling. The string literal passed to ``extern`` can be a format string: + +.. code-block:: Nimrod + proc p(s: string) {.extern: "prefix$1".} = + echo s + +In the example the external name of ``p`` is set to ``prefixp``. + + Bycopy pragma ------------- diff --git a/doc/nimrodc.txt b/doc/nimrodc.txt index d494a0922..52e0a6eaf 100644 --- a/doc/nimrodc.txt +++ b/doc/nimrodc.txt @@ -468,6 +468,19 @@ proc is declared in the generated code: proc myinterrupt() {.codegenDecl: "__interrupt $# $#$#".} = echo "realistic interrupt handler" + + +InjectStmt pragma +----------------- + +The `injectStmt`:idx: 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 + {.injectStmt: gcInvariants().} + + # ... complex code here that produces crashes ... LineDir option @@ -525,6 +538,13 @@ on Linux:: nimrod c --dynlibOverride:lua --passL:liblua.lib program.nim +Nimrod documentation tools +========================== + +Nimrod 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 =========================== diff --git a/doc/subexes.txt b/doc/subexes.txt index 3565dbf43..10e0f4cc1 100644 --- a/doc/subexes.txt +++ b/doc/subexes.txt @@ -14,7 +14,9 @@ Thanks to its conditional construct ``$[0|1|2|else]`` it supports Notation meaning ===================== ===================================================== ``$#`` use first or next argument -``$name`` use named argument +``$name`` use named argument, you can wrap the named argument + in curly braces (eg. ``${name}``) to separate it from + the next characters. ``$1`` use first argument ``$-1`` use last argument ``${1..3}`` use arguments 1 to 3 diff --git a/doc/tut1.txt b/doc/tut1.txt index 0cc9b05c1..b70f40f4a 100644 --- a/doc/tut1.txt +++ b/doc/tut1.txt @@ -189,9 +189,24 @@ to a storage location: var x = "abc" # introduces a new variable `x` and assigns a value to it x = "xyz" # assigns a new value to `x` -``=`` is the *assignment operator*. The assignment operator cannot -be overloaded, overwritten or forbidden, but this might change in a future -version of Nimrod. +``=`` 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 +statement and all the variables will have the same value: + +.. code-block:: + var x, y = 3 # assigns 3 to the variables `x` and `y` + echo "x ", x # outputs "x 3" + echo "y ", y # outputs "y 3" + x = 42 # changes `x` to 42 without changing `y` + echo "x ", x # outputs "x 42" + echo "y ", y # outputs "y 3" + +Note that declaring multiple variables with a single assignment which calls a +procedure can have unexpected results: the compiler will *unroll* the +assignments and end up calling the procedure several times. If the result of +the procedure depends on side effects, your variables may end up having +different values! For safety use only constant values. Constants @@ -309,12 +324,12 @@ the compiler that for every other value nothing should be done: case n of 0..2, 4..7: echo("The number is in the set: {0, 1, 2, 4, 5, 6, 7}") of 3, 8: echo("The number is 3 or 8") - else: nil + else: discard -The ``nil`` statement is a *do nothing* statement. The compiler knows that a -case statement with an else part cannot fail and thus the error disappears. Note -that it is impossible to cover all possible string values: that is why there is -no such check for string cases. +The empty ``discard`` statement is a *do nothing* statement. The compiler knows +that a case statement with an else part cannot fail and thus the error +disappears. Note that it is impossible to cover all possible string values: +that is why there is no such check for string cases. In general the case statement is used for subrange types or enumerations where it is of great help that the compiler checks that you covered any possible @@ -610,7 +625,7 @@ allow to silently throw away a return value: discard yes("May I ask a pointless question?") -The return value can be ignored implicitely if the called proc/iterator has +The return value can be ignored implicitly if the called proc/iterator has been declared with the ``discardable`` pragma: .. code-block:: nimrod @@ -798,7 +813,11 @@ important differences: However, you can also use a ``closure`` iterator to get a different set of restrictions. See `first class iterators <manual.html#first-class-iterators>`_ -for details. +for details. Iterators can have the same name and parameters as a proc, +essentially they have their own namespace. Therefore it is common practice to +wrap iterators in procs of the same name which accumulate the result of the +iterator and return it as a sequence, like ``split`` from the `strutils module +<strutils.html>`_. Basic types @@ -1077,7 +1096,7 @@ can also be used to include elements (and ranges of elements): TCharSet = set[char] var x: TCharSet - x = {'a'..'z', '0'..'9'} # This constructs a set that conains the + x = {'a'..'z', '0'..'9'} # This constructs a set that contains the # letters from 'a' to 'z' and the digits # from '0' to '9' @@ -1201,7 +1220,7 @@ to specify a range from zero to the specified index minus one: Sequences --------- `Sequences`:idx: are similar to arrays but of dynamic length which may change -during runtime (like strings). Since sequences are resizeable they are always +during runtime (like strings). Since sequences are resizable they are always allocated on the heap and garbage collected. Sequences are always indexed with an ``int`` starting at position 0. @@ -1302,6 +1321,30 @@ In this example ``$`` is applied to any argument that is passed to the parameter ``a``. Note that ``$`` applied to strings is a nop. +Slices +------ + +Slices look similar to subranges types in syntax but are used in a different +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 + + var + a = "Nimrod is a progamming language" + b = "Slices are useless." + + echo a[10..15] # --> 'a prog' + b[11.. -2] = "useful" + echo b # --> 'Slices are useful.' + +In the previous example slices are used to modify a part of a string, and even +a negative index is used. The slice's bounds can hold any value supported by +their type, but it is the proc using the slice object which defines what values +are accepted. + + Tuples ------ @@ -1352,6 +1395,45 @@ Even though you don't need to declare a type for a tuple to use it, tuples created with different field names will be considered different objects despite having the same field types. +Tuples can be *unpacked* during variable assignment (and only then!). This can +be handy to assign directly the fields of the tuples to individually named +variables. An example of this is the ``splitFile`` proc from the `os module +<os.html>`_ which returns the directory, name and extension of a path at the +same time. For tuple unpacking to work you have to 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 + + import os + + let + path = "usr/local/nimrodc.html" + (dir, name, ext) = splitFile(path) + baddir, badname, badext = splitFile(path) + echo dir # outputs `usr/local` + echo name # outputs `nimrodc` + echo ext # outputs `.html` + # All the following output the same line: + # `(dir: usr/local, name: nimrodc, ext: .html)` + echo baddir + echo badname + echo badext + +Tuple unpacking **only** works in ``var`` or ``let`` blocks. The following code +won't compile: + +.. code-block:: nimrod + + import os + + var + path = "usr/local/nimrodc.html" + dir, name, ext = "" + + (dir, name, ext) = splitFile(path) + # --> Error: '(dir, name, ext)' cannot be assigned to + Reference and pointer types --------------------------- @@ -1534,6 +1616,17 @@ rules apply: write(stdout, x(3)) # ambiguous: which `x` is to call? +Excluding symbols +----------------- + +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 + import mymodule except y + + From statement -------------- @@ -1544,10 +1637,34 @@ exported symbols. An alternative that only imports listed symbols is the .. code-block:: nimrod 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 + from mymodule import x, y, z + + x() # use x without any qualification + +.. code-block:: nimrod + from mymodule import nil + + mymodule.x() # must qualify x with the module name as prefix + + x() # using x here without qualification is a compile error + +Since module names are generally long to be descriptive, you can also +define a shorter alias to use when qualifying symbols. + +.. code-block:: nimrod + from mymodule as m import nil + + m.x() # m is aliasing mymodule + Include statement ----------------- -The `include`:idx: statement does something fundametally different than +The `include`:idx: 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: diff --git a/doc/tut2.txt b/doc/tut2.txt index e1e36bfc4..6738c5551 100644 --- a/doc/tut2.txt +++ b/doc/tut2.txt @@ -16,9 +16,9 @@ Introduction This document is a tutorial for the advanced constructs of the *Nimrod* -programming language. **Note that this document is somewhat obsolete as -the `manual <manual.html>`_ contains many more examples of the advanced -language features.** +programming language. **Note that this document is somewhat obsolete as the** +`manual <manual.html>`_ **contains many more examples of the advanced language +features.** Pragmas @@ -77,7 +77,7 @@ section. Inheritance is done with the ``object of`` syntax. Multiple inheritance is currently not supported. If an object type has no suitable ancestor, ``TObject`` can be used as its ancestor, but this is only a convention. Objects that have -no ancestor are implicitely ``final``. You can use the ``inheritable`` pragma +no ancestor are implicitly ``final``. You can use the ``inheritable`` pragma to introduce new object roots apart from ``system.TObject``. (This is used in the GTK wrapper for instance.) @@ -528,7 +528,7 @@ containers: proc newNode*[T](data: T): PBinaryTree[T] = # constructor for a node new(result) - result.dat = data + result.data = data proc add*[T](root: var PBinaryTree[T], n: PBinaryTree[T]) = # insert a node into the tree @@ -569,7 +569,7 @@ containers: var root: PBinaryTree[string] # instantiate a PBinaryTree with ``string`` - add(root, newNode("hallo")) # instantiates ``newNode`` and ``add`` + add(root, newNode("hello")) # instantiates ``newNode`` and ``add`` add(root, "world") # instantiates the second ``add`` proc for str in preorder(root): stdout.writeln(str) @@ -614,7 +614,7 @@ simple proc for logging: .. code-block:: nimrod const - debug = True + debug = true proc log(msg: string) {.inline.} = if debug: stdout.writeln(msg) @@ -631,7 +631,7 @@ Turning the ``log`` proc into a template solves this problem: .. code-block:: nimrod const - debug = True + debug = true template log(msg: string) = if debug: stdout.writeln(msg) @@ -674,16 +674,15 @@ via a special ``:`` syntax: template withFile(f: expr, filename: string, mode: TFileMode, body: stmt): stmt {.immediate.} = - block: - let fn = filename - var f: TFile - if open(f, fn, mode): - try: - body - finally: - close(f) - else: - quit("cannot open: " & fn) + let fn = filename + var f: TFile + if open(f, fn, mode): + try: + body + finally: + close(f) + else: + quit("cannot open: " & fn) withFile(txt, "ttempl3.txt", fmWrite): txt.writeln("line 1") @@ -699,15 +698,22 @@ once. 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. - -To write a macro, one needs to know how the Nimrod concrete syntax is converted -to an abstract syntax tree (AST). The AST is documented in the -`macros <macros.html>`_ module. - -There are two ways to invoke a macro: +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 +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 +time. + +There are two ways to write a macro, either *generating* Nimrod 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 +(AST). The AST is documented in the `macros <macros.html>`_ module. + +Once your macro is finished, there are two ways to invoke it: (1) invoking a macro like a procedure call (`expression macros`:idx:) (2) invoking a macro with the special ``macrostmt`` syntax (`statement macros`:idx:) @@ -777,7 +783,7 @@ regular expressions: macro case_token(n: stmt): stmt = # creates a lexical analyzer from regular expressions # ... (implementation is an exercise for the reader :-) - nil + discard case_token: # this colon tells the parser it is a macro statement of r"[A-Za-z_]+[A-Za-z_0-9]*": @@ -796,3 +802,249 @@ Term rewriting macros Term rewriting macros can be used to enhance the compilation process with user defined optimizations; see this `document <trmacros.html>`_ for further information. + + +Building your first macro +------------------------- + +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 + + import strutils, tables + + proc readCfgAtRuntime(cfgFilename: string): TTable[string, string] = + let + inputString = readFile(cfgFilename) + var + source = "" + + result = initTable[string, string]() + for line in inputString.splitLines: + # Ignore empty lines + if line.len < 1: continue + var chunks = split(line, ',') + if chunks.len != 2: + quit("Input needs comma split values, got: " & line) + result[chunks[0]] = chunks[1] + + if result.len < 1: quit("Input file empty!") + + let info = readCfgAtRuntime("data.cfg") + + when isMainModule: + echo info["licenseOwner"] + echo info["licenseKey"] + echo info["version"] + +Presumably this snippet of code could be used in a commercial software, reading +a configuration file to display information about the person who bought the +software. This external file would be generated by an online web shopping cart +to be included along the program containing the license information:: + + version,1.1 + licenseOwner,Hyori Lee + licenseKey,M1Tl3PjBWO2CC48m + +The ``readCfgAtRuntime`` proc will open the given filename and return a +``TTable`` from the `tables module <tables.html>`_. The parsing of the file is +done (without much care for handling invalid data or corner cases) using the +``splitLines`` proc from the `strutils module <strutils.html>`_. There are many +things which can fail; mind the purpose is explaining how to make this run at +compile time, not how to properly implement a DRM scheme. + +The reimplementation of this code as a compile time proc will allow us to get +rid of the ``data.cfg`` file we would need to distribute along the binary, plus +if the information is really constant, it doesn't make from a logical point of +view to have it *mutable* in a global variable, it would be better if it was a +constant. Finally, and likely the most valuable feature, we can implement some +verification at compile time. You could think of this as a *better unit +testing*, since it is impossible to obtain a binary unless everything is +correct, preventing you to ship to users a broken program which won't start +because a small critical file is missing or its contents changed by mistake to +something invalid. + + +Generating source code +++++++++++++++++++++++ + +Our first attempt will start by modifying the program to generate a compile +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 + import macros, strutils + + macro readCfgAndBuildSource(cfgFilename: string): stmt = + let + inputString = slurp(cfgFilename.strVal) + var + source = "" + + for line in inputString.splitLines: + # Ignore empty lines + if line.len < 1: continue + var chunks = split(line, ',') + if chunks.len != 2: + error("Input needs comma split values, got: " & line) + source &= "const cfg" & chunks[0] & "= \"" & chunks[1] & "\"\n" + + if source.len < 1: error("Input file empty!") + result = parseStmt(source) + + readCfgAndBuildSource("data.cfg") + + when isMainModule: + echo cfglicenseOwner + echo cfglicenseKey + echo cfgversion + +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 +to call the ``strVal`` proc from the `macros module <macros.html>`_ to obtain +the string being passed in to the macro. + +Second, we cannot use the ``readFile`` proc from the `system module +<system.html>`_ due to FFI restriction at compile time. If we try to use this +proc, or any other which depends on FFI, the compiler will error with the +message ``cannot evaluate`` and a dump of the macro's source code, along with a +stack trace where the compiler reached before bailing out. We can get around +this limitation by using the ``slurp`` proc from the `system module +<system.html>`_, which was precisely made for compilation time (just like +``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. +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 + const cfgversion= "1.1" + const cfglicenseOwner= "Hyori Lee" + const cfglicenseKey= "M1Tl3PjBWO2CC48m" + +You can verify this yourself adding the line ``echo source`` somewhere at the +end of the macro and compiling the program. Another difference is that instead +of calling the usual ``quit`` proc to abort (which we could still call) this +version calls the ``error`` proc. The ``error`` proc has the same behavior as +``quit`` but will dump also the source and file line information where the +error happened, making it easier for the programmer to find where compilation +failed. In this situation it would point to the line invoking the macro, but +**not** the line of ``data.cfg`` we are processing, that's something the macro +itself would need to control. + + +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 +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 + import macros + + dumpTree: + const cfgversion: string = "1.1" + const cfglicenseOwner= "Hyori Lee" + const cfglicenseKey= "M1Tl3PjBWO2CC48m" + +During compilation of the source code we should see the following lines in the +output (again, since this is a macro, compilation is enough, you don't have to +run any binary):: + + StmtList + ConstSection + ConstDef + Ident !"cfgversion" + Ident !"string" + StrLit 1.1 + ConstSection + ConstDef + Ident !"cfglicenseOwner" + Empty + StrLit Hyori Lee + ConstSection + ConstDef + Ident !"cfglicenseKey" + Empty + StrLit M1Tl3PjBWO2CC48m + +With this output we have a better idea of what kind of input the compiler +expects. We need to generate a list of statements. For each constant the source +code generates a ``ConstSection`` and a ``ConstDef``. If we were to move all +the constants to a single ``const`` block we would see only a single +``ConstSection`` with three children. + +Maybe you didn't notice, but in the ``dumpTree`` example the first constant +explicitly specifies the type of the constant. That's why in the tree output +the two last constants have their second child ``Empty`` but the first has a +string identifier. So basically a ``const`` definition is made up from an +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 + import macros, strutils + + macro readCfgAndBuildAST(cfgFilename: string): stmt = + let + inputString = slurp(cfgFilename.strVal) + + result = newNimNode(nnkStmtList) + for line in inputString.splitLines: + # Ignore empty lines + if line.len < 1: continue + var chunks = split(line, ',') + if chunks.len != 2: + error("Input needs comma split values, got: " & line) + var + section = newNimNode(nnkConstSection) + constDef = newNimNode(nnkConstDef) + constDef.add(newIdentNode("cfg" & chunks[0])) + constDef.add(newEmptyNode()) + constDef.add(newStrLitNode(chunks[1])) + section.add(constDef) + result.add(section) + + if result.len < 1: error("Input file empty!") + + readCfgAndBuildAST("data.cfg") + + when isMainModule: + echo cfglicenseOwner + echo cfglicenseKey + echo cfgversion + +Since we are building on the previous example generating source code, we will +only mention the differences to it. Instead of creating a temporary ``string`` +variable and writing into it source code as if it were written *by hand*, we +use the ``result`` variable directly and create a statement list node +(``nnkStmtList``) which will hold our children. + +For each input line we have to create a constant definition (``nnkConstDef``) +and wrap it inside a constant section (``nnkConstSection``). Once these +variables are created, we fill them hierarchichally like the previous AST dump +tree showed: the constant definition is a child of the section definition, and +the constant definition has an identifier node, an empty node (we let the +compiler figure out the type), and a string literal with the value. + +A last tip when writing a macro: if you are not sure the AST you are building +looks ok, you may be tempted to use the ``dumpTree`` macro. But you can't use +it *inside* the macro you are writting/debugging. Instead ``echo`` the string +generated by ``treeRepr``. If at the end of the this example you add ``echo +treeRepr(result)`` you should get the same output as using the ``dumpTree`` +macro, but of course you can call that at any point of the macro where you +might be having troubles. |