diff options
Diffstat (limited to 'doc')
| -rwxr-xr-x | doc/advopt.txt | 5 | ||||
| -rwxr-xr-x | doc/grammar.txt | 10 | ||||
| -rwxr-xr-x | doc/intern.txt | 2 | ||||
| -rwxr-xr-x | doc/lib.txt | 5 | ||||
| -rwxr-xr-x | doc/manual.txt | 111 | ||||
| -rwxr-xr-x | doc/nimrodc.txt | 15 | ||||
| -rwxr-xr-x | doc/tut1.txt | 39 |
7 files changed, 140 insertions, 47 deletions
diff --git a/doc/advopt.txt b/doc/advopt.txt index 7aba243ed..9a642addb 100755 --- a/doc/advopt.txt +++ b/doc/advopt.txt @@ -13,8 +13,9 @@ Advanced commands: //idetools compiler support for IDEs: possible options: --track:FILE,LINE,COL track a file/cursor position --suggest suggest all possible symbols at position - --def list all possible symbols at position + --def list all possible definitions at position --context list possible invokation context + --usages list all usages of the symbol at position Advanced options: -m, --mainmodule:FILE set the project main module @@ -29,6 +30,8 @@ Advanced options: --import:PATH add an automatically imported module --include:PATH add an automatically included module --nimcache:PATH set the path used for generated files + --header:FILE the compiler should produce a .h file (FILE + is optional) -c, --compileOnly compile only; do not assemble or link --noLinking compile but do not link --noMain do not generate a main procedure diff --git a/doc/grammar.txt b/doc/grammar.txt index 4dcb2d3f8..1e54d1116 100755 --- a/doc/grammar.txt +++ b/doc/grammar.txt @@ -1,6 +1,8 @@ module ::= ([COMMENT] [SAD] stmt)* comma ::= ',' [COMMENT] [IND] +semicolon ::= ';' [COMMENT] [IND] + operator ::= OP0 | OP1 | OP2 | OP3 | OP4 | OP5 | OP6 | OP7 | OP8 | OP9 | 'or' | 'xor' | 'and' | 'is' | 'isnot' | 'in' | 'notin' | 'of' @@ -135,20 +137,20 @@ staticStmt ::= 'static' ':' stmt filename ::= symbol | STR_LIT | RSTR_LIT | TRIPLESTR_LIT importStmt ::= 'import' filename (comma filename)* includeStmt ::= 'include' filename (comma filename)* -bindStmt ::= 'bind' IDENT (comma IDENT)* +bindStmt ::= 'bind' qualifiedIdent (comma qualifiedIdent)* fromStmt ::= 'from' filename 'import' symbol (comma symbol)* pragma ::= '{.' optInd (colonExpr [comma])* optPar ('.}' | '}') param ::= symbol (comma symbol)* (':' typeDesc ['=' expr] | '=' expr) -paramList ::= ['(' [param (comma param)*] optPar ')'] [':' typeDesc] +paramList ::= ['(' [param (comma|semicolon param)*] optPar ')'] [':' typeDesc] genericConstraint ::= 'object' | 'tuple' | 'enum' | 'proc' | 'ref' | 'ptr' | 'var' | 'distinct' | primary genericConstraints ::= genericConstraint ( '|' optInd genericConstraint )* genericParam ::= symbol [':' genericConstraints] ['=' expr] -genericParams ::= '[' genericParam (comma genericParam)* optPar ']' +genericParams ::= '[' genericParam (comma|semicolon genericParam)* optPar ']' routineDecl := symbol ['*'] [genericParams] paramList [pragma] ['=' stmt] @@ -180,7 +182,7 @@ objectCase ::= 'case' expr ':' typeDesc [COMMENT] objectPart ::= objectWhen | objectCase | objectIdentPart | 'nil' | indPush objectPart (SAD objectPart)* DED indPop -tupleDesc ::= '[' optInd [param (comma param)*] optPar ']' +tupleDesc ::= '[' optInd [param (comma|semicolon param)*] optPar ']' objectDef ::= 'object' [pragma] ['of' typeDesc] objectPart enumField ::= symbol ['=' expr] diff --git a/doc/intern.txt b/doc/intern.txt index 748b648fb..c84797251 100755 --- a/doc/intern.txt +++ b/doc/intern.txt @@ -518,5 +518,3 @@ backend somehow. We deal with this by modifying ``s.ast[paramPos]`` to contain the formal hidden parameter, but not ``s.typ``! - - diff --git a/doc/lib.txt b/doc/lib.txt index 8436f486c..f5bef435c 100755 --- a/doc/lib.txt +++ b/doc/lib.txt @@ -31,6 +31,11 @@ Core implicitly by the compiler. Do not import it directly. It relies on compiler magic to work. +* `unsigned <unsigned.html>`_ + This module implements basic arithmetic operators for unsigned integers. + To discourage users from using unsigned integers, it's not part + of ``system``, but an extra import. + * `threads <threads.html>`_ Nimrod thread support. **Note**: This is part of the system module. Do not import it explicitely. diff --git a/doc/manual.txt b/doc/manual.txt index f526d9d22..665ca265c 100755 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -614,11 +614,11 @@ Nimrod requires `interval arithmetic`:idx: for subrange types over a set of built-in operators that involve constants: ``x mod 3`` is of type ``range[0..2]``. The following built-in operators for integers are affected by this rule: ``-``, ``+``, ``*``, ``min``, ``max``, ``succ``, -``pred``, ``mod``, ``div``, ``and`` (bitwise and). +``pred``, ``mod``, ``div``, ``and`` (bitwise ``and``). -Bitwise and only produces a ``range`` if one of its operands is a +Bitwise ``and`` only produces a ``range`` if one of its operands is a constant *x* so that (x+1) is a number of two. -(Bitwise and then behaves as a ``mod`` operation.) +(Bitwise ``and`` is then a ``mod`` operation.) This means that the following code is accepted: @@ -924,8 +924,8 @@ order. The assignment operator for tuples copies each component. The default assignment operator for objects copies each component. Overloading -of the assignment operator for objects is not possible, but this may change in -future versions of the compiler. +of the assignment operator for objects is not possible, but this will change +in future versions of the compiler. .. code-block:: nimrod @@ -940,7 +940,16 @@ future versions of the compiler. person = ("Peter", 30) The implementation aligns the fields for best access performance. The alignment -is compatible with the way the C compiler does it. +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 + + type + TPerson = tuple # type representing a person + name: string # a person consists of a name + age: natural # and an age Objects provide many features that tuples do not. Object provide inheritance and information hiding. Objects have access to their type at runtime, so that @@ -1086,6 +1095,18 @@ dereferencing operations for reference types: new(n) n.data = 9 # no need to write n[].data; in fact n[].data is highly discouraged! + +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 + + type + Node = ref object + le, ri: Node + data: int + To allocate a new traced object, the built-in procedure ``new`` has to be used. To deal with untraced memory, the procedures ``alloc``, ``dealloc`` and @@ -1177,6 +1198,17 @@ that expects a proc of the calling convention ``closure``. Nimrod supports these `calling conventions`:idx:\: +`nimcall`:idx: + is the default convention used for a Nimrod **proc**. It is the + same as ``fastcall``, but only for C compilers that support ``fastcall``. + +`closure`:idx: + is the default calling convention for a **procedural type** that lacks + any pragma annotations. It indicates that the procedure has a hidden + implicit parameter (an *environment*). Proc vars that have the calling + convention ``closure`` take up two machine words: One for the proc pointer + and another one for the pointer to implicitely passed environment. + `stdcall`:idx: This the stdcall convention as specified by Microsoft. The generated C procedure is declared with the ``__stdcall`` keyword. @@ -1203,16 +1235,6 @@ Nimrod supports these `calling conventions`:idx:\: Fastcall means different things to different C compilers. One gets whatever the C ``__fastcall`` means. -`nimcall`:idx: - Nimcall is the default convention used for Nimrod procedures. It is the - same as ``fastcall``, but only for C compilers that support ``fastcall``. - -`closure`:idx: - indicates that the procedure has a hidden implicit parameter - (an *environment*). Proc vars that have the calling convention ``closure`` - take up two machine words: One for the proc pointer and another one for - the pointer to implicitely passed environment. - `syscall`:idx: The syscall convention is the same as ``__syscall`` in C. It is used for interrupts. @@ -1977,14 +1999,18 @@ exception handler may raise another exception. If the exception is not handled, it is propagated through the call stack. This means that often the rest of the procedure - that is not within a ``finally`` clause - is not executed (if an exception occurs). + + +Except and finally statements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ `except`:idx: and `finally`:idx: can also be used as a stand-alone statements. Any statements following them in the current block will be considered to be in an implicit try block: .. code-block:: nimrod - var f = fopen("numbers.txt", "r") - finally: fcsole(f) + var f = open("numbers.txt") + finally: close(f) ... @@ -2932,6 +2958,47 @@ In templates identifiers can be constructed with the backticks notation: In the example ``name`` is instantiated with ``myint``, so \`T name\` becomes ``Tmyint``. + +Lookup rules for template parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 +covered by the same argument name even when fully qualified: + +.. code-block:: nimrod + # module 'm' + + type + TLev = enum + levA, levB + + var abclev = levB + + template tstLev(abclev: TLev) = + echo abclev, " ", m.abclev + + tstLev(levA) + # produces: 'levA levA' + +But the global symbol can properly be captured by a ``bind`` statement: + +.. code-block:: nimrod + # module 'm' + + type + TLev = enum + levA, levB + + var abclev = levB + + template tstLev(abclev: TLev) = + bind m.abclev + echo abclev, " ", m.abclev + + tstLev(levA) + # produces: 'levA levB' + Macros ------ @@ -3589,11 +3656,9 @@ strings automatically: Dynlib pragma for import ------------------------ -With the `dynlib`:idx: pragma a procedure 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: +With the `dynlib`:idx: 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 proc gtk_image_new(): PGtkWidget {. diff --git a/doc/nimrodc.txt b/doc/nimrodc.txt index b131acca1..0b740025a 100755 --- a/doc/nimrodc.txt +++ b/doc/nimrodc.txt @@ -103,7 +103,20 @@ To `cross compile`:idx:, use for example:: nimrod 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. +Linux i386 machine and run the script. + +Another way is to make Nimrod invoke a cross compiler toolchain:: + + nimrod 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 +system is used to provide meaningful defaults. For example for ``ARM`` your +configuration file should contain something like:: + + arm.linux.gcc.path = "/usr/bin" + arm.linux.gcc.exe = "arm-linux-gcc" + arm.linux.gcc.linkerexe = "arm-linux-gcc" DLL generation diff --git a/doc/tut1.txt b/doc/tut1.txt index 2b77c67ce..78f5dfecd 100755 --- a/doc/tut1.txt +++ b/doc/tut1.txt @@ -221,6 +221,16 @@ value cannot change: let x = "abc" # introduces a new variable `x` and binds a value to it x = "xyz" # Illegal: assignment to `x` +The difference between ``let`` and ``const`` is: ``let`` introduces a variable +that can not be re-assigned, ``const`` means "enforce compile time evaluation +and put it into a data section": + +.. code-block:: + const input = readline(stdin) # Error: constant expression expected + +.. code-block:: + let input = readline(stdin) # works + Control flow statements ======================= @@ -356,16 +366,13 @@ Counting down can be achieved as easily (but is less often needed): for i in countdown(10, 1): echo($i) -Since counting up occurs so often in programs, Nimrod has a special syntax that -calls the ``countup`` iterator implicitly: +Since counting up occurs so often in programs, Nimrod also has a ``..`` iterator +that does the same: .. code-block:: nimrod for i in 1..10: ... -The syntax ``for i in 1..10`` is sugar for ``for i in countup(1, 10)``. -``countdown`` does not have any such sugar. - Scopes and the block statement ------------------------------ @@ -387,14 +394,14 @@ statement can be used to open a new block explicitly: var x = "hi" echo(x) # does not work either -The block's `label` (``myblock`` in the example) is optional. +The block's *label* (``myblock`` in the example) is optional. Break statement --------------- 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: +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 block myblock: @@ -452,9 +459,6 @@ differences: The ``when`` statement is useful for writing platform specific code, similar to the ``#ifdef`` construct in the C programming language. -**Note**: The documentation generator currently always follows the first branch -of when statements. - **Note**: To comment out a large piece of code, it is often better to use a ``when false:`` statement than to use real comments. This way nesting is possible. @@ -566,7 +570,7 @@ efficient way. If the procedure needs to modify the argument for the caller, a ``var`` parameter can be used: .. code-block:: nimrod - proc divmod(a, b: int, res, remainder: var int) = + proc divmod(a, b: int; res, remainder: var int) = res = a div b # integer division remainder = a mod b # integer modulo operation @@ -611,7 +615,7 @@ 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 - proc createWindow(x, y, width, height: int, title: string, + proc createWindow(x, y, width, height: int; title: string; show: bool): Window = ... @@ -698,8 +702,8 @@ To define a new operator enclose the operator in "``": # now the $ operator also works with myDataType, overloading resolution # ensures that $ works for built-in types just like before -The "``" notation can also be used to call an operator just like a procedure -with a real name: +The "``" notation can also be used to call an operator just like any other +procedure: .. code-block:: nimrod if `==`( `+`(3, 4), 7): echo("True") @@ -729,6 +733,9 @@ introduced to the compiler before it is completely defined. The syntax for such a `forward declaration`:idx: is simple: just omit the ``=`` and the procedure's body. +Later versions of the language may get rid of the need for forward +declarations. + Iterators ========= @@ -1248,7 +1255,7 @@ Example: A subtle issue with procedural types is that the calling convention of the procedure influences the type compatibility: procedural types are only compatible if they have the same calling convention. The different calling conventions are -listed in the `user guide <nimrodc.html>`_. +listed in the `manual <manual.html>`_. Modules |