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

Merge pull request #817 from gradha/pr_improves_docs2

Browse Source 
Improves docs2
This commit is contained in:
Simon Hafner
2014-01-16 07:34:37 -08:00
parent 0132f350af 42f152569d
commit 8f499db4c3
8 changed files with 120 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
doc/lib.txt
View File

@@ -227,7 +227,12 @@ Parsers
-------
* `parseopt <parseopt.html>`_
The ``parseopt`` module implements a command line option parser. This
The ``parseopt`` module implements a command line option parser.
**Deprecated since version 0.9.3:** Use the `parseopt2
<parseopt2.html>`_ module instead.
* `parseopt2 <parseopt2.html>`_
The ``parseopt2`` module implements a command line option parser. This
supports long and short command options with optional values and command line
arguments.
@@ -381,9 +386,6 @@ Database support
* `db_mongo <db_mongo.html>`_
A higher level **mongodb** wrapper.
* `mongodb <mongo.html>`_
Lower level wrapper for the **mongodb** client C library.
Other
-----
@@ -446,45 +448,6 @@ UNIX specific
* `posix <posix.html>`_
Contains a wrapper for the POSIX standard.
* `cursorfont <cursorfont.html>`_
Part of the wrapper for X11.
* `keysym <keysym.html>`_
Part of the wrapper for X11.
* `x <x.html>`_
Part of the wrapper for X11.
* `xatom <xatom.html>`_
Part of the wrapper for X11.
* `xcms <xcms.html>`_
Part of the wrapper for X11.
* `xf86dga <xf86dga.html>`_
Part of the wrapper for X11.
* `xf86vmode <xf86vmode.html>`_
Part of the wrapper for X11.
* `xi <xi.html>`_
Part of the wrapper for X11.
* `xinerama <xinerama.html>`_
Part of the wrapper for X11.
* `xkb <xkb.html>`_
Part of the wrapper for X11.
* `xkblib <xkblib.html>`_
Part of the wrapper for X11.
* `xlib <xlib.html>`_
Part of the wrapper for X11.
* `xrandr <xrandr.html>`_
Part of the wrapper for X11.
* `xrender <xrender.html>`_
Part of the wrapper for X11.
* `xresource <xresource.html>`_
Part of the wrapper for X11.
* `xshm <xshm.html>`_
Part of the wrapper for X11.
* `xutil <xutil.html>`_
Part of the wrapper for X11.
* `xv <xv.html>`_
Part of the wrapper for X11.
* `xvlib <xvlib.html>`_
Part of the wrapper for X11.
* `readline <readline.html>`_
Part of the wrapper for the GNU readline library.
* `history <history.html>`_
@@ -505,15 +468,6 @@ Regular expressions
Graphics libraries
------------------
* `cairo <cairo.html>`_
Wrapper for the cairo library.
* `cairoft <cairoft.html>`_
Wrapper for the cairoft library.
* `cairowin32 <cairowin32.html>`_
Wrapper for the cairowin32 library.
* `cairoxlib <cairoxlib.html>`_
Wrapper for the cairoxlib library.
* `sdl <sdl.html>`_
Part of the wrapper for SDL.
* `sdl_gfx <sdl_gfx.html>`_
@@ -529,47 +483,10 @@ Graphics libraries
* `smpeg <smpeg.html>`_
Part of the wrapper for SDL.
* `gl <gl.html>`_
Part of the wrapper for OpenGL.
* `glext <glext.html>`_
Part of the wrapper for OpenGL.
* `glu <glu.html>`_
Part of the wrapper for OpenGL.
* `glut <glut.html>`_
Part of the wrapper for OpenGL.
* `glx <glx.html>`_
Part of the wrapper for OpenGL.
* `wingl <wingl.html>`_
Part of the wrapper for OpenGL.
* `opengl <opengl.html>`_
New wrapper for OpenGL supporting up to version 4.2.
GUI libraries
-------------
* `atk <atk.html>`_
Wrapper for the atk library.
* `gdk2 <gdk2.html>`_
Wrapper for the gdk2 library.
* `gdk2pixbuf <gdk2pixbuf.html>`_
Wrapper for the gdk2pixbuf library.
* `gdkglext <gdkglext.html>`_
Wrapper for the gdkglext library.
* `glib2 <glib2.html>`_
Wrapper for the glib2 library.
* `gtk2 <gtk2.html>`_
Wrapper for the gtk2 library.
* `gtkglext <gtkglext.html>`_
Wrapper for the gtkglext library.
* `gtkhtml <gtkhtml.html>`_
Wrapper for the gtkhtml library.
* `libglade2 <libglade2.html>`_
Wrapper for the libglade2 library.
* `pango <pango.html>`_
Wrapper for the pango library.
* `pangoutils <pangoutils.html>`_
Wrapper for the pangoutils library.
* `iup <iup.html>`_
Wrapper of the IUP GUI library.
@@ -583,6 +500,8 @@ Database support
Contains a wrapper for the mySQL API.
* `sqlite3 <sqlite3.html>`_
Contains a wrapper for SQLite 3 API.
* `mongodb <mongo.html>`_
Lower level wrapper for the **mongodb** client C library.
* `odbcsql <odbcsql.html>`_
interface to the ODBC driver.
* `sphinx <sphinx.html>`_
@@ -612,21 +531,6 @@ Network Programming and Internet Protocols
Wrapper for OpenSSL.
Scripting languages
-------------------
* `lua <lua.html>`_
Part of the wrapper for Lua.
* `lualib <lualib.html>`_
Part of the wrapper for Lua.
* `lauxlib <lauxlib.html>`_
Part of the wrapper for Lua.
* `tcl <tcl.html>`_
Wrapper for the TCL programming language.
* `python <python.html>`_
Wrapper for the Python programming language.
Data Compression and Archiving
------------------------------

72
doc/manual.txt
View File

@@ -312,14 +312,39 @@ Character literals
------------------
Character literals are enclosed in single quotes ``''`` and can contain the
same escape sequences as strings - with one exception: ``\n`` is not allowed
as it may be wider than one character (often it is the pair CR/LF for example).
same escape sequences as strings - with one exception: `newline`:idx: (``\n``)
is not allowed as it may be wider than one character (often it is the pair
CR/LF for example). Here are the valid `escape sequences`:idx: for character
literals:
================== ===================================================
Escape sequence Meaning
================== ===================================================
``\r``, ``\c`` `carriage return`:idx:
``\l`` `line feed`:idx:
``\f`` `form feed`:idx:
``\t`` `tabulator`:idx:
``\v`` `vertical tabulator`:idx:
``\\`` `backslash`:idx:
``\"`` `quotation mark`:idx:
``\'`` `apostrophe`: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:
``\x`` HH `character with hex value HH`:idx:;
exactly two hex digits are allowed
================== ===================================================
A character is not an Unicode character but a single byte. The reason for this
is efficiency: for the overwhelming majority of use-cases, the resulting
programs will still handle UTF-8 properly as UTF-8 was specially designed for
this.
Another reason is that Nimrod can thus support ``array[char, int]`` or
``set[char]`` efficiently as many algorithms rely on this feature.
this. Another reason is that Nimrod can thus support ``array[char, int]`` or
``set[char]`` efficiently as many algorithms rely on this feature. The `TRune`
type is used for Unicode characters, it can represent any Unicode character.
``TRune`` is declared in the `unicode module <unicode.html>`_.
Numerical constants
@@ -750,7 +775,8 @@ designed for this.
Another reason is that Nimrod can support ``array[char, int]`` or
``set[char]`` efficiently as many algorithms rely on this feature. The
`TRune` type is used for Unicode characters, it can represent any Unicode
character. ``TRune`` is declared in the ``unicode`` module.
character. ``TRune`` is declared in the `unicode module <unicode.html>`_.
@@ -847,8 +873,8 @@ arrays, they can be used in case statements:
Per convention, all strings are UTF-8 strings, but this is not 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*. The iterator ``runes`` from the ``unicode``
module can be used for iteration over all Unicode characters.
i-th *unichar*. The iterator ``runes`` from the `unicode module
<unicode.html>`_ can be used for iteration over all Unicode characters.
CString type
@@ -2206,12 +2232,12 @@ Instead of:
Using statement
---------------
The using statement provides syntactic convenience for procs that heavily use a
single contextual parameter. When applied to a variable or a constant, it will
instruct Nimrod to automatically consider the used symbol as a hidden leading
parameter for any procedure calls, following the using statement in the current
scope. Thus, it behaves much like the hidden `this` parameter available in some
object-oriented programming languages.
The `using statement`:idx: provides syntactic convenience for procs that
heavily use a single contextual parameter. When applied to a variable or a
constant, it will instruct Nimrod to automatically consider the used symbol as
a hidden leading parameter for any procedure calls, following the using
statement in the current scope. Thus, it behaves much like the hidden `this`
parameter available in some object-oriented programming languages.
.. code-block:: nimrod
@@ -2234,6 +2260,24 @@ from different modules having the same name.
import windows, sdl
using sdl.SetTimer
Note that ``using`` only *adds* to the current context, it doesn't remove or
replace, **neither** does it create a new scope. What this means is that if you
apply this to multiple variables the compiler will find conflicts in what
variable to use:
.. code-block:: nimrod
var a, b = "kill it"
using a
add(" with fire")
using b
add(" with water")
echo a
echo b
When the compiler reaches the second ``add`` call, both ``a`` and ``b`` could
be used with the proc, so you get ``Error: expression '(a|b)' has no type (or
is ambiguous)``. To solve this you would need to nest ``using`` with a
``block`` statement so as to control the reach of the ``using`` statement.
If expression
-------------

4
doc/subexes.txt
View File

@@ -14,7 +14,9 @@ Thanks to its conditional construct ``$[0|1|2|else]`` it supports
Notation meaning
===================== =====================================================
``$#`` use first or next argument
``$name`` use named argument
``$name`` use named argument, you can wrap the named argument
in curly braces (eg. ``${name}``) to separate it from
the next characters.
``$1`` use first argument
``$-1`` use last argument
``${1..3}`` use arguments 1 to 3

12
doc/tut1.txt
View File

@@ -202,6 +202,12 @@ statement and all the variables will have the same value:
echo "x ", x # outputs "x 42"
echo "y ", y # outputs "y 3"
Note that declaring multiple variables with a single assignment which calls a
procedure can have unexpected results: the compiler will *unroll* the
assignments and end up calling the procedure several times. If the result of
the procedure depends on side effects, your variables may end up having
different values! For safety use only constant values.
Constants
=========
@@ -807,7 +813,11 @@ important differences:
However, you can also use a ``closure`` iterator to get a different set of
restrictions. See `first class iterators <manual.html#first-class-iterators>`_
for details.
for details. Iterators can have the same name and parameters as a proc,
essentially they have their own namespace. Therefore it is common practice to
wrap iterators in procs of the same name which accumulate the result of the
iterator and return it as a sequence, like ``split`` from the `strutils module
<strutils.html>`_.
Basic types

13
lib/packages/docutils/rstgen.nim
View File

@@ -44,7 +44,7 @@ type
splitAfter*: int # split too long entries in the TOC
tocPart*: seq[TTocEntry]
hasToc*: bool
theIndex: string
theIndex: string # Contents of the index file to be dumped at the end.
options*: TRstParseOptions
findFile*: TFindFileHandler
msgHandler*: TMsgHandler
@@ -111,6 +111,10 @@ proc initRstGenerator*(g: var TRstGenerator, target: TOutputTarget,
for i in low(g.meta)..high(g.meta): g.meta[i] = ""
proc writeIndexFile*(g: var TRstGenerator, outfile: string) =
## Writes the current index buffer to the specified output file.
##
## You previously need to add entries to the index with the ``setIndexTerm``
## proc. If the index is empty the file won't be created.
if g.theIndex.len > 0: writeFile(outfile, g.theIndex)
proc addXmlChar(dest: var string, c: char) =
@@ -224,6 +228,13 @@ proc renderAux(d: PDoc, n: PRstNode, frmtA, frmtB: string, result: var string) =
# ---------------- index handling --------------------------------------------
proc setIndexTerm*(d: var TRstGenerator, id, term: string) =
## Adds a `term` to the index using the specified hyperlink identifier.
##
## The ``d.theIndex`` string will be used to append the term in the format
## ``term<tab>file#id``. The anchor will be the based on the name of the file
## currently being parsed plus the `id`, which will be appended after a hash.
##
## The index won't be written to disk unless you call ``writeIndexFile``.
d.theIndex.add(term)
d.theIndex.add('\t')
let htmlFile = changeFileExt(extractFilename(d.filename), HtmlExt)

4
lib/pure/parseopt.nim
View File

@@ -11,8 +11,8 @@
## It supports one convenience iterator over all command line options and some
## lower-level features.
##
## DEPRECATED. Use parseopt2 instead as this version has issues with spaces
## in arguments.
## **Deprecated since version 0.9.3:** Use the `parseopt2 <parseopt2.html>`_
## module instead as this version has issues with spaces in arguments.
{.deprecated.}
{.push debugger: off.}

26
lib/system.nim
View File

@@ -2236,8 +2236,19 @@ when not defined(JS): #and not defined(NimrodVM):
when hostOS != "standalone":
iterator lines*(filename: string): TaintedString {.tags: [FReadIO].} =
## Iterate over any line in the file named `filename`.
## If the file does not exist `EIO` is raised.
## Iterates over any line in the file named `filename`.
##
## If the file does not exist `EIO` is raised. The trailing newline
## character(s) are removed from the iterated lines. Example:
##
## .. code-block:: nimrod
## import strutils
##
## proc transformLetters(filename: string) =
## var buffer = ""
## for line in filename.lines:
## buffer.add(line.replace("a", "0") & '\x0A')
## writeFile(filename, buffer)
var f = open(filename)
var res = TaintedString(newStringOfCap(80))
while f.readLine(res): yield res
@@ -2245,6 +2256,17 @@ when not defined(JS): #and not defined(NimrodVM):
iterator lines*(f: TFile): TaintedString {.tags: [FReadIO].} =
## Iterate over any line in the file `f`.
##
## The trailing newline character(s) are removed from the iterated lines.
## Example:
##
## .. code-block:: nimrod
## proc countZeros(filename: TFile): tuple[lines, zeros: int] =
## for line in filename.lines:
## for letter in line:
## if letter == '0':
## result.zeros += 1
## result.lines += 1
var res = TaintedString(newStringOfCap(80))
while f.readLine(res): yield res

2
web/nimrod.ini
View File

@@ -45,7 +45,7 @@ srcdoc2: "impure/re;pure/sockets"
srcdoc: "system/threads.nim;system/channels.nim;js/dom"
srcdoc2: "pure/os;pure/strutils;pure/math;pure/matchers;pure/algorithm"
srcdoc2: "pure/complex;pure/times;pure/osproc;pure/pegs;pure/dynlib"
srcdoc2: "pure/parseopt;pure/hashes;pure/strtabs;pure/lexbase"
srcdoc2: "pure/parseopt;pure/parseopt2;pure/hashes;pure/strtabs;pure/lexbase"
srcdoc2: "pure/parsecfg;pure/parsexml;pure/parsecsv;pure/parsesql"
srcdoc2: "pure/streams;pure/terminal;pure/cgi;impure/web;pure/unicode"
srcdoc2: "impure/zipfiles;pure/htmlgen;pure/parseutils;pure/browsers"