mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2026-06-04 02:44:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

documentation improvements

Browse Source
This commit is contained in:
Araq
2011-02-06 15:39:06 +01:00
parent 0117f494ec
commit 783273032f
8 changed files with 100 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/docs.txt
View File

@@ -31,5 +31,5 @@ The documentation consists of several documents:
this if you want to hack the compiler.
- | `Index <theindex.html>`_
| The generated index. Often the quickest way to find the piece of
information you need.
| The generated index. **Index + (Ctrl+F) == Joy**

103
doc/manual.txt
View File

@@ -193,18 +193,19 @@ contain the following `escape sequences`:idx:\ :
``\\`` `backslash`:idx:
``\"`` `quotation mark`:idx:
``\'`` `apostrophe`:idx:
``\d+`` `character with decimal value d`: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:
``\xHH`` `character with hex value HH`:idx:;
``\x`` HH `character with hex value HH`:idx:;
exactly two hex digits are allowed
================== ===================================================
Strings in Nimrod may contain any 8-bit value, except embedded zeros.
Strings in Nimrod may contain any 8-bit value, even embedded zeros. However
some operations may interpret the first binary zero as terminator.
Triple quoted string literals
@@ -947,44 +948,44 @@ To deal with untraced memory, the procedures ``alloc``, ``dealloc`` and
further information.
If a reference points to *nothing*, it has the value ``nil``.
Special care has to be taken if an untraced object contains traced objects like
traced references, strings or sequences: in order to free everything properly,
the built-in procedure ``GCunref`` has to be called before freeing the untraced
memory manually:
.. code-block:: nimrod
type
TData = tuple[x, y: int, s: string]
# allocate memory for TData on the heap:
var d = cast[ptr TData](alloc0(sizeof(TData)))
# create a new string on the garbage collected heap:
d.s = "abc"
# tell the GC that the string is not needed anymore:
GCunref(d.s)
# free the memory:
dealloc(d)
Without the ``GCunref`` call the memory allocated for the ``d.s`` string would
never be freed. The example also demonstrates two important features for low
level programming: the ``sizeof`` proc returns the size of a type or value
in bytes. The ``cast`` operator can circumvent the type system: the compiler
is forced to treat the result of the ``alloc0`` call (which returns an untyped
pointer) as if it would have the type ``ptr TData``. Casting should only be
done if it is unavoidable: it breaks type safety and bugs can lead to
mysterious crashes.
**Note**: The example only works because the memory is initialized with zero
(``alloc0`` instead of ``alloc`` does this): ``d.s`` is thus initialized to
``nil`` which the string assignment can handle. You need to know low level
details like this when mixing garbage collected data with unmanaged memory.
Special care has to be taken if an untraced object contains traced objects like
traced references, strings or sequences: in order to free everything properly,
the built-in procedure ``GCunref`` has to be called before freeing the untraced
memory manually:
.. code-block:: nimrod
type
TData = tuple[x, y: int, s: string]
# allocate memory for TData on the heap:
var d = cast[ptr TData](alloc0(sizeof(TData)))
# create a new string on the garbage collected heap:
d.s = "abc"
# tell the GC that the string is not needed anymore:
GCunref(d.s)
# free the memory:
dealloc(d)
Without the ``GCunref`` call the memory allocated for the ``d.s`` string would
never be freed. The example also demonstrates two important features for low
level programming: the ``sizeof`` proc returns the size of a type or value
in bytes. The ``cast`` operator can circumvent the type system: the compiler
is forced to treat the result of the ``alloc0`` call (which returns an untyped
pointer) as if it would have the type ``ptr TData``. Casting should only be
done if it is unavoidable: it breaks type safety and bugs can lead to
mysterious crashes.
**Note**: The example only works because the memory is initialized with zero
(``alloc0`` instead of ``alloc`` does this): ``d.s`` is thus initialized to
``nil`` which the string assignment can handle. You need to know low level
details like this when mixing garbage collected data with unmanaged memory.
.. XXX finalizers for traced objects
Procedural type
~~~~~~~~~~~~~~~
@@ -1750,17 +1751,17 @@ Syntax::
The direct embedding of `assembler`:idx: code into Nimrod code is supported
by the unsafe ``asm`` statement. Identifiers in the assembler code that refer to
Nimrod identifiers shall be enclosed in a special character which can be
specified in the statement's pragmas. The default special character is ``'`'``:
.. code-block:: nimrod
proc addInt(a, b: int): int {.pure.} =
# a in eax, and b in edx
asm """
mov eax, `a`
add eax, `b`
jno theEnd
call `raiseOverflow`
theEnd:
specified in the statement's pragmas. The default special character is ``'`'``:
.. code-block:: nimrod
proc addInt(a, b: int): int {.pure.} =
# a in eax, and b in edx
asm """
mov eax, `a`
add eax, `b`
jno theEnd
call `raiseOverflow`
theEnd:
"""
If expression
@@ -2809,7 +2810,7 @@ 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 {.
proc gtk_image_new(): PGtkWidget {.
cdecl, dynlib: "libgtk-x11-2.0.so", importc.}
In general, importing a dynamic library does not require any special linker

11
doc/tut1.txt
View File

@@ -17,11 +17,13 @@ Introduction
This document is a tutorial for the programming language *Nimrod*. After this
tutorial you will have a decent knowledge about Nimrod. This tutorial assumes
tutorial you will have a decent knowledge of Nimrod. This tutorial assumes
that you are familiar with basic programming concepts like variables, types
or statements.
The first program
=================
@@ -44,10 +46,15 @@ appending them after the filename::
nimrod compile --run greetings.nim arg1 arg2
The most used commands and switches have abbreviations, so you can also use::
Commonly used commands and switches have abbreviations, so you can also use::
nimrod c -r greetings.nim
To compile a `release`:idx: version use::
nimrod c -d:release greetings.nim
Though it should be pretty obvious what the program does, I will explain the
syntax: statements which are not indented are executed when the program
starts. Indentation is Nimrod's way of grouping statements. Indentation is

24
lib/core/marshal.nim
View File

@@ -12,15 +12,31 @@
import streams
proc load*[T](s: PStream, data: var T) {.magic: "Load".}
proc load*[T](s: PStream, data: var T) =
## loads `data` from the stream `s`. Raises `EIO` in case of an error.
proc store*[T](s: PStream, data: T) {.magic: "Store".}
proc store*[T](s: PStream, data: T) =
## stores `data` into the stream `s`. Raises `EIO` in case of an error.
proc reprInt(x: int64): string {.compilerproc.} = return $x
proc reprFloat(x: float): string {.compilerproc.} = return $x
type
TTypeInfo = distinct whatever
TValue = object
t: TTypeInfo
x: pointer
proc rtti[T](x: T): TTypeInfo {.magic: "rtti".}
proc `[]` (a: TValue, i: int): TValue =
## works for arrays, objects, etc.
proc `[]=` (a: TValue, i: int, x: TValue) =
##
proc reprPointer(x: pointer): string {.compilerproc.} =
var buf: array [0..59, char]

24
lib/pure/os.nim
View File

@@ -284,7 +284,7 @@ proc fileNewer*(a, b: string): bool {.rtl, extern: "nos$1".} =
result = getLastModificationTime(a) - getLastModificationTime(b) > 0
proc getCurrentDir*(): string {.rtl, extern: "nos$1".} =
## Returns the current working directory.
## Returns the `current working directory`:idx:.
const bufsize = 512 # should be enough
result = newString(bufsize)
when defined(windows):
@@ -298,7 +298,7 @@ proc getCurrentDir*(): string {.rtl, extern: "nos$1".} =
OSError()
proc setCurrentDir*(newDir: string) {.inline.} =
## Sets the current working directory; `EOS` is raised if
## Sets the `current working directory`:idx:; `EOS` is raised if
## `newDir` cannot been set.
when defined(Windows):
if SetCurrentDirectoryA(newDir) == 0'i32: OSError()
@@ -661,7 +661,7 @@ proc executeShellCommand*(command: string): int {.deprecated.} =
result = csystem(command)
proc execShellCmd*(command: string): int {.rtl, extern: "nos$1".} =
## Executes a shell command.
## Executes a `shell command`:idx:.
##
## Command has the form 'program args' where args are the command
## line arguments given to program. The proc returns the error code
@@ -720,7 +720,7 @@ proc findEnvVar(key: string): int =
return -1
proc getEnv*(key: string): string =
## Returns the value of the environment variable named `key`.
## Returns the value of the `environment variable`:idx: named `key`.
##
## If the variable does not exist, "" is returned. To distinguish
## whether a variable exists or it's value is just "", call
@@ -740,7 +740,7 @@ proc existsEnv*(key: string): bool =
else: return findEnvVar(key) >= 0
proc putEnv*(key, val: string) =
## Sets the value of the environment variable named `key` to `val`.
## Sets the value of the `environment variable`:idx: named `key` to `val`.
## If an error occurs, `EInvalidEnvVar` is raised.
# Note: by storing the string in the environment sequence,
@@ -770,15 +770,17 @@ iterator iterOverEnvironment*(): tuple[key, value: string] {.deprecated.} =
yield (copy(environment[i], 0, p-1), copy(environment[i], p+1))
iterator envPairs*(): tuple[key, value: string] =
## Iterate over all environments variables. In the first component of the
## tuple is the name of the current variable stored, in the second its value.
## Iterate over all `environments variables`:idx:. In the first component
## of the tuple is the name of the current variable stored, in the second
## its value.
getEnvVarsC()
for i in 0..high(environment):
var p = find(environment[i], '=')
yield (copy(environment[i], 0, p-1), copy(environment[i], p+1))
iterator walkFiles*(pattern: string): string =
## Iterate over all the files that match the `pattern`.
## Iterate over all the files that match the `pattern`. On POSIX this uses
## the `glob`:idx: call.
##
## `pattern` is OS dependant, but at least the "\*.ext"
## notation is supported.
@@ -914,7 +916,7 @@ proc rawCreateDir(dir: string) =
OSError()
proc createDir*(dir: string) {.rtl, extern: "nos$1".} =
## Creates the directory `dir`.
## Creates the `directory`:idx: `dir`.
##
## The directory may contain several subdirectories that do not exist yet.
## The full path is created. If this fails, `EOS` is raised. It does **not**
@@ -1122,13 +1124,13 @@ when defined(windows):
ownArgv: seq[string]
proc paramCount*(): int {.rtl, extern: "nos$1".} =
## Returns the number of command line arguments given to the
## Returns the number of `command line arguments`:idx: given to the
## application.
if isNil(ownArgv): ownArgv = parseCmdLine($getCommandLineA())
result = ownArgv.len-1
proc paramStr*(i: int): string {.rtl, extern: "nos$1".} =
## Returns the `i`-th command line argument given to the
## Returns the `i`-th `command line argument`:idx: given to the
## application.
##
## `i` should be in the range `1..paramCount()`, else

1
lib/pure/strutils.nim
View File

@@ -205,6 +205,7 @@ proc `%` *(formatstr: string, a: openarray[string]): string {.noSideEffect,
##
## The substitution variables (the thing after the ``$``) are enumerated
## from 1 to ``a.len``.
## To produce a verbatim ``$``, use ``$$``.
## The notation ``$#`` can be used to refer to the next substitution variable:
##
## .. code-block:: nimrod

4
rod/docgen.nim
View File

@@ -254,7 +254,7 @@ proc setIndexForSourceTerm(d: PDoc, name: PRstNode, id: int) =
proc renderIndexTerm(d: PDoc, n: PRstNode): PRope =
inc(d.id)
result = dispF("<em id=\"$1\">$2</em>", "$2\\label{$1}",
result = dispF("<span id=\"$1\">$2</span>", "$2\\label{$1}",
[toRope(d.id), renderAux(d, n)])
var h = newRstNode(rnHyperlink)
var a = newRstNode(rnLeaf, d.indexValFilename & disp("#", "") & $d.id)
@@ -739,7 +739,7 @@ proc renderRstToOut(d: PDoc, n: PRstNode): PRope =
result = renderAux(d, n, disp("<cite>$1</cite>", "\\emph{$1}"))
of rnIdx:
if d.theIndex == nil:
result = renderAux(d, n, disp("<em>$1</em>", "\\emph{$1}"))
result = renderAux(d, n, disp("<span>$1</span>", "\\emph{$1}"))
else:
result = renderIndexTerm(d, n)
of rnInlineLiteral:

1
todo.txt
View File

@@ -1,6 +1,7 @@
- thread support: threadvar on Windows seems broken;
add --deadlock_prevention:on|off switch
- built-in serialization
- change how generalized raw string literals work
- we need a way to disable tests
- deprecate ^ and make it available as operator