diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/advopt.txt | 10 | ||||
| -rw-r--r-- | doc/basicopt.txt | 3 | ||||
| -rw-r--r-- | doc/koch.rst | 33 | ||||
| -rw-r--r-- | doc/manual.rst | 113 | ||||
| -rw-r--r-- | doc/manual/var_t_return.rst | 20 | ||||
| -rw-r--r-- | doc/nimc.rst | 4 | ||||
| -rw-r--r-- | doc/tut1.rst | 26 |
7 files changed, 98 insertions, 111 deletions
diff --git a/doc/advopt.txt b/doc/advopt.txt index 214ac8dd2..685c8127d 100644 --- a/doc/advopt.txt +++ b/doc/advopt.txt @@ -35,7 +35,8 @@ Advanced options: --noLinking compile Nim and generated files but do not link --noMain do not generate a main procedure --genScript generate a compile script (in the 'nimcache' - subdirectory named 'compile_$project$scriptext') + subdirectory named 'compile_$$project$$scriptext'), + implies --compileOnly --genDeps generate a '.deps' file containing the dependencies --os:SYMBOL set the target operating system (cross-compilation) --cpu:SYMBOL set the target processor (cross-compilation) @@ -65,6 +66,8 @@ Advanced options: --excessiveStackTrace:on|off stack traces use full file paths --oldNewlines:on|off turn on|off the old behaviour of "\n" + --laxStrings:on|off when turned on, accessing the zero terminator in + strings is allowed; only for backwards compatibility --skipCfg do not read the general configuration file --skipUserCfg do not read the user's configuration file --skipParentCfg do not read the parent dirs' configuration files @@ -76,7 +79,7 @@ Advanced options: --NimblePath:PATH add a path for Nimble support --noNimblePath deactivate the Nimble path --noCppExceptions use default exception handling with C++ backend - --cppCompileToNamespace use namespace "Nim" for the generated C++ code + --cppCompileToNamespace use namespace "Nim" for the generated C++ code --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; @@ -88,5 +91,6 @@ Advanced options: --parallelBuild:0|1|... perform a parallel build value = number of processors (0 for auto-detect) --verbosity:0|1|2|3 set Nim's verbosity level (1 is default) - --experimental enable experimental language features + --experimental:$1 + enable experimental language feature -v, --version show detailed version information diff --git a/doc/basicopt.txt b/doc/basicopt.txt index 4db2d5af7..90c7ba09c 100644 --- a/doc/basicopt.txt +++ b/doc/basicopt.txt @@ -29,14 +29,13 @@ Options: --nanChecks:on|off turn NaN checks on|off --infChecks:on|off turn Inf checks on|off --nilChecks:on|off turn nil checks on|off - --deadCodeElim:on|off whole program dead code elimination on|off --opt:none|speed|size optimize not at all or for speed|size Note: use -d:release for a release build! --debugger:native|endb use native debugger (gdb) | ENDB (experimental) --app:console|gui|lib|staticlib generate a console app|GUI app|DLL|static library -r, --run run the compiled program with given arguments - --advanced show advanced command line switches + --fullhelp show all command line switches -h, --help show this help Note, single letter options that take an argument require a colon. E.g. -p:PATH. diff --git a/doc/koch.rst b/doc/koch.rst index ff62b8186..35cf9d8b6 100644 --- a/doc/koch.rst +++ b/doc/koch.rst @@ -35,32 +35,8 @@ options: By default a debug version is created, passing this option will force a release build, which is much faster and should be preferred unless you are debugging the compiler. --d:useGnuReadline - Includes the `rdstdin module <rdstdin.html>`_ for `interactive - 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: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 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>`_ - command on all ``nimcache`` directories, setting their backup - exclusion bit. - - You can use the following command to locate all ``nimcache`` - directories and check their backup exclusion bit:: - - $ find . -type d -name nimcache -exec tmutil isexcluded \{\} \; ---gc:refc|v2|markAndSweep|boehm|go|none - Selects which garbage collection strategy to use for the compiler - and generated code. See the `Nim's Garbage Collector <gc.html>`_ - documentation for more information. +-d:useLinenoise + Use the linenoise library for interactive mode (not needed on Windows). 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 @@ -104,8 +80,3 @@ be rerun in serial fashion so that meaninful error output can be gathered for inspection. The ``--parallelBuild:n`` switch or configuration option can be used to force a specific number of parallel jobs or run everything serially from the start (``n == 1``). - -zip command ------------ - -The `zip`:idx: command builds the installation ZIP package. diff --git a/doc/manual.rst b/doc/manual.rst index b114f0a8a..44e2ee5b5 100644 --- a/doc/manual.rst +++ b/doc/manual.rst @@ -1397,10 +1397,10 @@ dereferencing operations for reference types: Automatic dereferencing is also performed for the first argument of a routine call. But currently this feature has to be only enabled -via ``{.experimental.}``: +via ``{.experimental: "implicitDeref".}``: .. code-block:: nim - {.experimental.} + {.experimental: "implicitDeref".} proc depth(x: NodeObj): int = ... @@ -1471,7 +1471,7 @@ mysterious crashes. **Note**: The example only works because the memory is initialized to zero (``alloc0`` instead of ``alloc`` does this): ``d.s`` is thus initialized to -``nil`` which the string assignment can handle. One needs to know low level +binary zero which the string assignment can handle. One needs to know low level details like this when mixing garbage collected data with unmanaged memory. .. XXX finalizers for traced objects @@ -2512,8 +2512,8 @@ char '\\0' bool false ref or pointer type nil procedural type nil -sequence nil (*not* ``@[]``) -string nil (*not* "") +sequence ``@[]`` +string ``""`` tuple[x: A, y: B, ...] (default(A), default(B), ...) (analogous for objects) array[0..., T] [default(T), ...] @@ -3487,17 +3487,17 @@ returned value is an l-value and can be modified by the caller: .. code-block:: nim var g = 0 - proc WriteAccessToG(): var int = + proc writeAccessToG(): var int = result = g - WriteAccessToG() = 6 + writeAccessToG() = 6 assert g == 6 It is a compile time error if the implicitly introduced pointer could be used to access a location beyond its lifetime: .. code-block:: nim - proc WriteAccessToG(): var int = + proc writeAccessToG(): var int = var g = 0 result = g # Error! @@ -3512,6 +3512,24 @@ In the standard library every name of a routine that returns a ``var`` type starts with the prefix ``m`` per convention. +.. include:: manual/var_t_return.rst + +Future directions +~~~~~~~~~~~~~~~~~ + +Later versions of Nim can be more precise about the borrowing rule with +a syntax like: + +.. code-block:: nim + proc foo(other: Y; container: var X): var T from container + +Here ``var T from container`` explicitly exposes that the +location is deviated from the second parameter (called +'container' in this case). The syntax ``var T from p`` specifies a type +``varTy[T, 2]`` which is incompatible with ``varTy[T, 1]``. + + + Overloading of the subscript operator ------------------------------------- @@ -4252,7 +4270,7 @@ therefore very useful for type specialization within generic code: Table[Key, Value] = object keys: seq[Key] values: seq[Value] - when not (Key is string): # nil value for strings used for optimization + when not (Key is string): # empty value for strings used for optimization deletedKeys: seq[bool] @@ -5241,15 +5259,21 @@ chance to convert it into a sequence. Macros ====== -A macro is a special kind of low level template. Macros can be used -to implement `domain specific languages`:idx:. +A macro is a special function that is executed at compile-time. +Normally the input for a macro is an abstract syntax +tree (AST) of the code that is passed to it. The macro can then do +transformations on it and return the transformed AST. The +transformed AST is then passed to the compiler as if the macro +invocation would have been replaced by its result in the source +code. This can be used to implement `domain specific +languages`:idx:. While macros enable advanced compile-time code transformations, they 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 Nim concrete syntax is converted -to an abstract syntax tree. +to an AST. There are two ways to invoke a macro: (1) invoking a macro like a procedure call (`expression macros`) @@ -5269,19 +5293,21 @@ variable number of arguments: # ``macros`` module: import macros - macro debug(n: varargs[untyped]): untyped = - # `n` is a Nim AST that contains the whole macro invocation - # this macro returns a list of statements: - result = newNimNode(nnkStmtList, n) + macro debug(args: varargs[untyped]): untyped = + # `args` is a collection of `NimNode` values that each contain the + # AST for an argument of the macro. A macro always has to + # return a `NimNode`. A node of kind `nnkStmtList` is suitable for + # this use case. + result = nnkStmtList.newTree() # iterate over any argument that is passed to this macro: - for i in 0..n.len-1: + for n in args: # add a call to the statement list that writes the expression; # `toStrLit` converts an AST to its string representation: - add(result, newCall("write", newIdentNode("stdout"), toStrLit(n[i]))) + result.add newCall("write", newIdentNode("stdout"), newLit(n.repr)) # add a call to the statement list that writes ": " - add(result, newCall("write", newIdentNode("stdout"), newStrLitNode(": "))) + result.add newCall("write", newIdentNode("stdout"), newLit(": ")) # add a call to the statement list that writes the expressions value: - add(result, newCall("writeLine", newIdentNode("stdout"), n[i])) + result.add newCall("writeLine", newIdentNode("stdout"), n) var a: array[0..10, int] @@ -5562,7 +5588,7 @@ dot operators ------------- **Note**: Dot operators are still experimental and so need to be enabled -via ``{.experimental.}``. +via ``{.experimental: "dotOperators".}``. Nim offers a special family of dot operators that can be used to intercept and rewrite proc call and field access attempts, referring @@ -6272,6 +6298,9 @@ modules don't need to import a module's dependencies: var x: MyObject echo $x +When the exported symbol is another module, all of its definitions will +be forwarded. You can use an ``except`` list to exclude some of the symbols. + Note on paths ----------- In module related statements, if any part of the module name / @@ -6742,22 +6771,6 @@ the created global variables within a module is not defined, but all of them will be initialized after any top-level variables in their originating module and before any variable in a module that imports it. -deadCodeElim pragma -------------------- -The ``deadCodeElim`` pragma only applies to whole modules: It tells the -compiler to activate (or deactivate) dead code elimination for the module the -pragma appears in. - -The ``--deadCodeElim:on`` command line switch has the same effect as marking -every module with ``{.deadCodeElim:on}``. However, for some modules such as -the GTK wrapper it makes sense to *always* turn on dead code elimination - -no matter if it is globally active or not. - -Example: - -.. code-block:: nim - {.deadCodeElim: on.} - .. NoForward pragma @@ -6875,17 +6888,12 @@ is uncertain (it may be removed any time). Example: .. code-block:: nim - {.experimental.} - type - FooId = distinct int - BarId = distinct int - using - foo: FooId - bar: BarId + {.experimental: "parallel".} proc useUsing(bar, foo) = - echo "bar is of type BarId" - echo "foo is of type FooId" + parallel: + for i in 0..4: + echo "echo in parallel" Implementation Specific Pragmas @@ -7429,8 +7437,8 @@ code generation directly, but their presence can be detected by macros. Custom pragmas are defined using templates annotated with pragma ``pragma``: .. code-block:: nim - template dbTable(name: string, table_space: string = nil) {.pragma.} - template dbKey(name: string = nil, primary_key: bool = false) {.pragma.} + template dbTable(name: string, table_space: string = "") {.pragma.} + template dbKey(name: string = "", primary_key: bool = false) {.pragma.} template dbForeignKey(t: typedesc) {.pragma.} template dbIgnore {.pragma.} @@ -7793,8 +7801,9 @@ Future directions: Threadvar pragma ---------------- -A global variable can be marked with the ``threadvar`` pragma; it is -a `thread-local`:idx: variable then: +A variable can be marked with the ``threadvar`` pragma, which makes it a +`thread-local`:idx: variable; Additionally, this implies all the effects +of the ``global`` pragma. .. code-block:: nim var checkpoints* {.threadvar.}: seq[string] @@ -7907,7 +7916,7 @@ Example: # Compute PI in an inefficient way import strutils, math, threadpool - {.experimental.} + {.experimental: "parallel".} proc term(k: float): float = 4 * math.pow(-1, k) / (2*k + 1) @@ -8187,5 +8196,3 @@ validation errors: If the taint mode is turned off, ``TaintedString`` is simply an alias for ``string``. - - diff --git a/doc/manual/var_t_return.rst b/doc/manual/var_t_return.rst new file mode 100644 index 000000000..b9ff1d892 --- /dev/null +++ b/doc/manual/var_t_return.rst @@ -0,0 +1,20 @@ +Memory safety for returning by ``var T`` is ensured by a simple borrowing +rule: If ``result`` does not refer to a location pointing to the heap +(that is in ``result = X`` the ``X`` involves a ``ptr`` or ``ref`` access) +then it has to be deviated by the routine's first parameter: + +.. code-block:: nim + proc forward[T](x: var T): var T = + result = x # ok, deviated from the first parameter. + + proc p(param: var int): var int = + var x: int + # we know 'forward' provides a view into the location deviated by + # its first argument 'x'. + result = forward(x) # Error: location is derived from ``x`` + # which is not p's first parameter and lives + # on the stack. + +In other words, the lifetime of what ``result`` points to is attached to the +lifetime of the first parameter and that is enough knowledge to verify +memory safety at the callsite. diff --git a/doc/nimc.rst b/doc/nimc.rst index b275438ea..29dbdea42 100644 --- a/doc/nimc.rst +++ b/doc/nimc.rst @@ -181,7 +181,7 @@ generated; use the ``--symbolFiles:on`` command line switch to activate them. Unfortunately due to technical reasons the ``--symbolFiles:on`` needs to *aggregate* some generated C code. This means that the resulting executable -might contain some cruft even when dead code elimination is turned on. So +might contain some cruft even with dead code elimination. So the final release build should be done with ``--symbolFiles:off``. Due to the aggregation of C code it is also recommended that each project @@ -439,7 +439,7 @@ target. For example, to generate code for an `AVR`:idx: processor use this command:: - nim c --cpu:avr --os:standalone --deadCodeElim:on --genScript x.nim + nim c --cpu:avr --os:standalone --genScript x.nim For the ``standalone`` target one needs to provide a file ``panicoverride.nim``. diff --git a/doc/tut1.rst b/doc/tut1.rst index cbfef183e..f2251c463 100644 --- a/doc/tut1.rst +++ b/doc/tut1.rst @@ -944,12 +944,8 @@ String variables are **mutable**, so appending to a string is possible, and quite efficient. Strings in Nim are both zero-terminated and have a length field. A string's length can be retrieved with the builtin ``len`` procedure; the length never counts the terminating zero. Accessing the -terminating zero is not an error and often leads to simpler code: - -.. code-block:: nim - if s[i] == 'a' and s[i+1] == 'b': - # no need to check whether ``i < len(s)``! - ... +terminating zero is an error, it only exists so that a Nim string can be converted +to a ``cstring`` without doing a copy. The assignment operator for strings copies the string. You can use the ``&`` operator to concatenate strings and ``add`` to append to a string. @@ -960,11 +956,7 @@ 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*. -String variables are initialized with a special value, called ``nil``. However, -most string operations cannot deal with ``nil`` (leading to an exception being -raised) for performance reasons. It is best to use empty strings ``""`` -rather than ``nil`` as the *empty* value. But ``""`` often creates a string -object on the heap, so there is a trade-off to be made here. +A string variable is initialized with the empty string ``""``. Integers @@ -1309,11 +1301,7 @@ Example: x: seq[int] # a reference to a sequence of integers x = @[1, 2, 3, 4, 5, 6] # the @ turns the array into a sequence allocated on the heap -Sequence variables are initialized with ``nil``. However, most sequence -operations cannot deal with ``nil`` (leading to an exception being -raised) for performance reasons. Thus one should use empty sequences ``@[]`` -rather than ``nil`` as the *empty* value. But ``@[]`` creates a sequence -object on the heap, so there is a trade-off to be made here. +Sequence variables are initialized with ``@[]``. The ``for`` statement can be used with one or two variables when used with a sequence. When you use the one variable form, the variable will hold the value @@ -1355,11 +1343,9 @@ type does not matter. .. code-block:: nim :test: "nim c $1" var - fruits: seq[string] # reference to a sequence of strings that is initialized with 'nil' + fruits: seq[string] # reference to a sequence of strings that is initialized with '@[]' capitals: array[3, string] # array of strings with a fixed size - fruits = @[] # creates an empty sequence on the heap that will be referenced by 'fruits' - capitals = ["New York", "London", "Berlin"] # array 'capitals' allows assignment of only three elements fruits.add("Banana") # sequence 'fruits' is dynamically expandable during runtime fruits.add("Mango") @@ -1691,7 +1677,7 @@ rules apply: write(stdout, x(3)) # no error: A.x is called write(stdout, x("")) # no error: B.x is called - proc x*(a: int): string = nil + proc x*(a: int): string = discard write(stdout, x(3)) # ambiguous: which `x` is to call? |