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

documentation improvements

Browse Source
This commit is contained in:
Araq
2011-01-31 08:50:30 +01:00
parent c9f4ad0613
commit 9387913b73
7 changed files with 73 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
doc/manual.txt
View File

@@ -533,11 +533,11 @@ The IEEE standard defines five types of floating-point exceptions:
precision, for example, 2.0 / 3.0, log(1.1) and 0.1 in input.
The IEEE exceptions are either ignored at runtime or mapped to the
Nimrod exceptions: `EFloatInvalidOp`:idx, `EFloatDivByZero`:idx:,
`EFloatOverflow`:idx:, `EFloatUnderflow`:idx:, and `EFloatInexact`:idx:\.
Nimrod exceptions: `EFloatInvalidOp`:idx:, `EFloatDivByZero`:idx:,
`EFloatOverflow`:idx:, `EFloatUnderflow`:idx:, and `EFloatInexact`:idx:.
These exceptions inherit from the `EFloatingPoint`:idx: base class.
Nimrod provides the pragmas `NaNChecks`:idx and `InfChecks`:idx:\ to control
Nimrod provides the pragmas `NaNChecks`:idx: and `InfChecks`:idx: to control
whether the IEEE exceptions are ignored or trap a Nimrod exception:
.. code-block:: nimrod
@@ -947,13 +947,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!
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
~~~~~~~~~~~~~~~
@@ -1719,8 +1750,18 @@ 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 ``'`'``.
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
~~~~~~~~~~~~~
@@ -1729,7 +1770,7 @@ An `if expression` is almost like an if statement, but it is an expression.
Example:
.. code-block:: nimrod
p(if x > 8: 9 else: 10)
var y = if x > 8: 9 else: 10
An if expression always results in a value, so the ``else`` part is
required. ``Elif`` parts are also allowed (but unlikely to be good
@@ -2040,7 +2081,7 @@ convention ``inline``.
If the iterator yields a tuple, there have to be as many iteration variables
as there are components in the tuple. The i'th iteration variable's type is
the one of the i'th component.
the type of the i'th component.
Type sections
@@ -2213,7 +2254,7 @@ special ``:`` syntax:
In the example the two ``writeln`` statements are bound to the ``actions``
parameter.
**Note:** Symbol binding rules in templates might change!
**Note:** Symbol binding rules for templates might change!
Symbol binding within templates happens after template instantation:
@@ -2768,7 +2809,8 @@ 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 {.cdecl, dynlib: "libgtk-x11-2.0.so", importc.}
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
options or linking with import libraries. This also implies that no *devel*

55
doc/tut1.txt
View File

@@ -10,7 +10,11 @@ Nimrod Tutorial (Part I)
Introduction
============
"Der Mensch ist doch ein Augentier -- schöne Dinge wünsch ich mir."
.. raw:: html
<blockquote><p>
"Der Mensch ist doch ein Augentier -- sch&ouml;ne Dinge w&uuml;nsch ich mir."
</p></blockquote>
This document is a tutorial for the programming language *Nimrod*. After this
tutorial you will have a decent knowledge about Nimrod. This tutorial assumes
@@ -91,8 +95,7 @@ means tabulator, etc. There are also *raw* string literals:
.. code-block:: Nimrod
r"C:\program files\nim"
In raw literals the backslash is not an escape character, so they fit
the principle *what you see is what you get*.
In raw literals the backslash is not an escape character.
The third and last way to write string literals are *long string literals*.
They are written with three quotes: ``""" ... """``; they can span over
@@ -121,7 +124,7 @@ aligned to the preceding one, it does not start a new comment:
Comments are tokens; they are only allowed at certain places in the input file
as they belong to the syntax tree! This feature enables perfect source-to-source
transformations (such as pretty-printing) and superior documentation generators.
transformations (such as pretty-printing) and simpler documentation generators.
A nice side-effect is that the human reader of the code always knows exactly
which code snippet the comment refers to. Since comments are a proper part of
the syntax, watch their indentation:
@@ -613,7 +616,7 @@ specify them:
Now the call to ``createWindow`` only needs to set the values that differ
from the defaults.
Note that type inference works for parameters with default values, there is
Note that type inference works for parameters with default values; there is
no need to write ``title: string = "unknown"``, for example.
@@ -806,7 +809,7 @@ a sequence of bytes. The index operation ``s[i]`` means the i-th *char* of
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. Thus one should use empty strings ``""``
raised) for performance reasons. One should 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.
@@ -1025,7 +1028,7 @@ operation meaning
================== ========================================================
Sets are often used to define a type for the *flags* of a procedure. This is
much cleaner (and type safe) solution than just defining integer
a much cleaner (and type safe) solution than just defining integer
constants that should be ``or``'ed together.
@@ -1034,8 +1037,7 @@ Arrays
An `array`:idx: is a simple fixed length container. Each element in
the array has the same type. The array's index type can be any ordinal type.
Arrays can be constructed via the array constructor: ``[]`` is the empty
array. The constructor can also be used to include elements.
Arrays can be constructed via ``[]``:
.. code-block:: nimrod
@@ -1199,41 +1201,6 @@ 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.
Procedural type
---------------

6
install.txt
View File

@@ -36,9 +36,9 @@ Installation on the Macintosh
-----------------------------
Only MacOS X is supported.
Since MacOS X is UNIX based too, it works like the installation on Linux. You
need to install Apple's developer's tools for the GNU Compiler Collection
though.
Since MacOS X is UNIX based too, it works like the installation on Linux.
However, for unknown reasons the symbolic link method does not work MacOS X.
You need to install Apple's developer's tools for the GNU Compiler Collection.
Installation on Windows

7
lib/system/alloc.nim
View File

@@ -329,7 +329,6 @@ proc ListRemove[T](head: var T, c: T) {.inline.} =
proc isSmallChunk(c: PChunk): bool {.inline.} =
return c.size <= SmallChunkSize-smallChunkOverhead()
#return c.size < SmallChunkSize
proc chunkUnused(c: PChunk): bool {.inline.} =
result = not c.used
@@ -377,9 +376,6 @@ proc freeBigChunk(a: var TAllocator, c: PBigChunk) =
proc splitChunk(a: var TAllocator, c: PBigChunk, size: int) =
var rest = cast[PBigChunk](cast[TAddress](c) +% size)
assert(rest notin a.freeChunksList)
# c_fprintf(c_stdout, "to add: %p\n", rest)
# writeFreeList(allocator)
# assert false
rest.size = c.size - size
rest.used = false
rest.next = nil
@@ -397,14 +393,11 @@ proc getBigChunk(a: var TAllocator, size: int): PBigChunk =
result = a.freeChunksList
block search:
while result != nil:
#if not chunkUnused(result):
# c_fprintf(c_stdout, "%lld\n", int(result.used))
assert chunkUnused(result)
if result.size == size:
ListRemove(a.freeChunksList, result)
break search
elif result.size > size:
#c_fprintf(c_stdout, "res size: %lld; size: %lld\n", result.size, size)
ListRemove(a.freeChunksList, result)
splitChunk(a, result, size)
break search

2
readme.txt
View File

@@ -17,5 +17,5 @@ priority).
See the file ``install.txt`` for installation instructions. See the file
``doc/intern.txt`` for the internal documentation for developers.
Copyright (c) 2004-2010 Andreas Rumpf.
Copyright (c) 2004-2011 Andreas Rumpf.
All rights reserved.

2
rod/astalgo.nim
View File

@@ -194,7 +194,7 @@ proc toYamlChar(c: Char): string =
of '\'', '\"', '\\': result = '\\' & c
else: result = c & ""
proc makeYamlString(s: string): PRope =
proc makeYamlString*(s: string): PRope =
# We have to split long strings into many ropes. Otherwise
# this could trigger InternalError(111). See the ropes module for
# further information.

2
rod/commands.nim
View File

@@ -280,7 +280,7 @@ proc addPath(path: string, info: TLineInfo) =
proc addPathRec(dir: string, info: TLineInfo) =
var pos = dir.len-1
if dir[pos] == '/': inc(pos)
if dir[pos] in {DirSep, AltSep}: inc(pos)
for k,p in os.walkDir(dir):
if k == pcDir and p[pos] != '.':
addPathRec(p, info)