diff --git a/doc/manual/ffi.txt b/doc/manual/ffi.txt index bc402b5705..f9056b1595 100644 --- a/doc/manual/ffi.txt +++ b/doc/manual/ffi.txt @@ -70,8 +70,8 @@ the compiler to pass the type by reference (hidden pointer) to procs. Varargs pragma -------------- -The ``varargs`` pragma can be applied to procedures only (and procedure -types). It tells Nim that the proc can take a variable number of parameters +The ``varargs`` pragma can be applied to procedures only (and procedure +types). It tells Nim that the proc can take a variable number of parameters after the last specified parameter. Nim string values will be converted to C strings automatically: @@ -94,20 +94,20 @@ should scan unions conservatively. Packed pragma ------------- -The ``packed`` pragma can be applied to any ``object`` type. It ensures -that the fields of an object are packed back-to-back in memory. It is useful -to store packets or messages from/to network or hardware drivers, and for -interoperability with C. Combining packed pragma with inheritance is not -defined, and it should not be used with GC'ed memory (ref's). +The ``packed`` pragma can be applied to any ``object`` type. It ensures +that the fields of an object are packed back-to-back in memory. It is useful +to store packets or messages from/to network or hardware drivers, and for +interoperability with C. Combining packed pragma with inheritance is not +defined, and it should not be used with GC'ed memory (ref's). -**Future directions**: Using GC'ed memory in packed pragma will result in +**Future directions**: Using GC'ed memory in packed pragma will result in compile-time error. Usage with inheritance should be defined and documented. Unchecked pragma ---------------- The ``unchecked`` pragma can be used to mark a named array as ``unchecked`` -meaning its bounds are not checked. This is often useful when one wishes to -implement their own flexibly sized arrays. Additionally an unchecked array is +meaning its bounds are not checked. This is often useful to +implement customized flexibly sized arrays. Additionally an unchecked array is translated into a C array of undetermined size: .. code-block:: nim @@ -141,7 +141,7 @@ runtime size of the array. Dynlib pragma for import ------------------------ With the ``dynlib`` pragma a procedure or a variable can be imported from -a dynamic library (``.dll`` files for Windows, ``lib*.so`` files for UNIX). +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:: Nim @@ -152,17 +152,17 @@ In general, importing a dynamic library does not require any special linker options or linking with import libraries. This also implies that no *devel* packages need to be installed. -The ``dynlib`` import mechanism supports a versioning scheme: +The ``dynlib`` import mechanism supports a versioning scheme: -.. code-block:: nim - proc Tcl_Eval(interp: pTcl_Interp, script: cstring): int {.cdecl, +.. code-block:: nim + proc Tcl_Eval(interp: pTcl_Interp, script: cstring): int {.cdecl, importc, dynlib: "libtcl(|8.5|8.4|8.3).so.(1|0)".} At runtime the dynamic library is searched for (in this order):: - + libtcl.so.1 libtcl.so.0 - libtcl8.5.so.1 + libtcl8.5.so.1 libtcl8.5.so.0 libtcl8.4.so.1 libtcl8.4.so.0 @@ -175,22 +175,22 @@ string expressions in general: .. code-block:: nim import os - proc getDllName: string = + proc getDllName: string = result = "mylib.dll" if existsFile(result): return result = "mylib2.dll" if existsFile(result): return quit("could not load dynamic library") - + proc myImport(s: cstring) {.cdecl, importc, dynlib: getDllName().} **Note**: Patterns like ``libtcl(|8.5|8.4).so`` are only supported in constant strings, because they are precompiled. -**Note**: Passing variables to the ``dynlib`` pragma will fail at runtime +**Note**: Passing variables to the ``dynlib`` pragma will fail at runtime because of order of initialization problems. -**Note**: A ``dynlib`` import can be overriden with +**Note**: A ``dynlib`` import can be overriden with the ``--dynlibOverride:name`` command line option. The Compiler User Guide contains further information. diff --git a/doc/tut1.txt b/doc/tut1.txt index 11a4d6adc6..2dc2c1d86a 100644 --- a/doc/tut1.txt +++ b/doc/tut1.txt @@ -333,7 +333,7 @@ The while statement is a simple looping construct: name = readLine(stdin) # no ``var``, because we do not declare a new variable here -The example uses a while loop to keep asking the user for their name, as long +The example uses a while loop to keep asking the users for their name, as long as the user types in nothing (only presses RETURN). @@ -774,7 +774,7 @@ proc even(n: int): bool = Here ``odd`` depends on ``even`` and vice versa. Thus ``even`` needs to be introduced to the compiler before it is completely defined. The syntax for such a forward declaration is simple: just omit the ``=`` and the -procedure's body. The ``assert`` just adds border conditions, and will be +procedure's body. The ``assert`` just adds border conditions, and will be covered later in `Modules`_ section. Later versions of the language will weaken the requirements for forward