From db7d0e6a66f1c9fe45d4e584403f450a22fd90a3 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 30 Dec 2013 12:18:46 +0100 Subject: [PATCH 01/13] Adds using statement to the one and only true index. --- doc/manual.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/manual.txt b/doc/manual.txt index 2d8feca17c..88a7f38157 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -2206,12 +2206,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 From 338a93f1197fe135e31b13865ab0ef6aa9ee9864 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 30 Dec 2013 12:47:01 +0100 Subject: [PATCH 02/13] Adds docstrings to lines() iterators. --- lib/system.nim | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/lib/system.nim b/lib/system.nim index 56bb6fe75c..0257670f4c 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -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 iterated lines will be + ## stripped off the trailing newline character(s). 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 iterated lines will be stripped off the trailing newline + ## character(s). 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 From 9602349f308dd860f94b720f8f03476edf9cccaf Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 30 Dec 2013 13:11:06 +0100 Subject: [PATCH 03/13] Adds note about procs and multiple variable assignment. --- doc/tut1.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/tut1.txt b/doc/tut1.txt index 2070c69d60..817bc69054 100644 --- a/doc/tut1.txt +++ b/doc/tut1.txt @@ -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 ========= From 0029832ba1797cf6c78defd9ece3d972929864b6 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 30 Dec 2013 13:29:28 +0100 Subject: [PATCH 04/13] Adds note about iterators having same signature as procs. --- doc/tut1.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/tut1.txt b/doc/tut1.txt index 817bc69054..91bff41d74 100644 --- a/doc/tut1.txt +++ b/doc/tut1.txt @@ -813,7 +813,11 @@ important differences: However, you can also use a ``closure`` iterator to get a different set of restrictions. See `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 +`_. Basic types From 3cf46c2defb9ef92c7f7321349e41fdd3f93cc5f Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 30 Dec 2013 13:34:20 +0100 Subject: [PATCH 05/13] Documents wrapping named arguments in curly braces. --- doc/subexes.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/subexes.txt b/doc/subexes.txt index 3565dbf433..10e0f4cc11 100644 --- a/doc/subexes.txt +++ b/doc/subexes.txt @@ -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 From 74f94482cc61956bd61457ba9c7b9fd1b8c67ec9 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 30 Dec 2013 14:01:00 +0100 Subject: [PATCH 06/13] Adds parseopt2 module to documentation index. --- doc/lib.txt | 7 ++++++- lib/pure/parseopt.nim | 4 ++-- web/nimrod.ini | 2 +- 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/doc/lib.txt b/doc/lib.txt index 92a4a7c83c..e9aa9e857d 100644 --- a/doc/lib.txt +++ b/doc/lib.txt @@ -227,7 +227,12 @@ Parsers ------- * `parseopt `_ - 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 + `_ module instead. + +* `parseopt2 `_ + The ``parseopt2`` module implements a command line option parser. This supports long and short command options with optional values and command line arguments. diff --git a/lib/pure/parseopt.nim b/lib/pure/parseopt.nim index 6b2ee62825..68ae537c77 100644 --- a/lib/pure/parseopt.nim +++ b/lib/pure/parseopt.nim @@ -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 `_ +## module instead as this version has issues with spaces in arguments. {.deprecated.} {.push debugger: off.} diff --git a/web/nimrod.ini b/web/nimrod.ini index f10a4b2f21..6942f20a99 100644 --- a/web/nimrod.ini +++ b/web/nimrod.ini @@ -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" From 457497980ce9b3ac1c0da7060a65d22b825e1f9c Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 30 Dec 2013 16:34:39 +0100 Subject: [PATCH 07/13] Moves mongodb module to lower level wrapper group. --- doc/lib.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/lib.txt b/doc/lib.txt index e9aa9e857d..dbe8c6a043 100644 --- a/doc/lib.txt +++ b/doc/lib.txt @@ -386,9 +386,6 @@ Database support * `db_mongo `_ A higher level **mongodb** wrapper. -* `mongodb `_ - Lower level wrapper for the **mongodb** client C library. - Other ----- @@ -588,6 +585,8 @@ Database support Contains a wrapper for the mySQL API. * `sqlite3 `_ Contains a wrapper for SQLite 3 API. +* `mongodb `_ + Lower level wrapper for the **mongodb** client C library. * `odbcsql `_ interface to the ODBC driver. * `sphinx `_ From f3273757ed1a638f89d6b5f16258f929f434db1d Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 30 Dec 2013 16:46:41 +0100 Subject: [PATCH 08/13] Removes links to modules recently removed from stdlib. --- doc/lib.txt | 102 +--------------------------------------------------- 1 file changed, 1 insertion(+), 101 deletions(-) diff --git a/doc/lib.txt b/doc/lib.txt index dbe8c6a043..ba0cb0a905 100644 --- a/doc/lib.txt +++ b/doc/lib.txt @@ -448,45 +448,6 @@ UNIX specific * `posix `_ Contains a wrapper for the POSIX standard. -* `cursorfont `_ - Part of the wrapper for X11. -* `keysym `_ - Part of the wrapper for X11. -* `x `_ - Part of the wrapper for X11. -* `xatom `_ - Part of the wrapper for X11. -* `xcms `_ - Part of the wrapper for X11. -* `xf86dga `_ - Part of the wrapper for X11. -* `xf86vmode `_ - Part of the wrapper for X11. -* `xi `_ - Part of the wrapper for X11. -* `xinerama `_ - Part of the wrapper for X11. -* `xkb `_ - Part of the wrapper for X11. -* `xkblib `_ - Part of the wrapper for X11. -* `xlib `_ - Part of the wrapper for X11. -* `xrandr `_ - Part of the wrapper for X11. -* `xrender `_ - Part of the wrapper for X11. -* `xresource `_ - Part of the wrapper for X11. -* `xshm `_ - Part of the wrapper for X11. -* `xutil `_ - Part of the wrapper for X11. -* `xv `_ - Part of the wrapper for X11. -* `xvlib `_ - Part of the wrapper for X11. - * `readline `_ Part of the wrapper for the GNU readline library. * `history `_ @@ -507,15 +468,6 @@ Regular expressions Graphics libraries ------------------ -* `cairo `_ - Wrapper for the cairo library. -* `cairoft `_ - Wrapper for the cairoft library. -* `cairowin32 `_ - Wrapper for the cairowin32 library. -* `cairoxlib `_ - Wrapper for the cairoxlib library. - * `sdl `_ Part of the wrapper for SDL. * `sdl_gfx `_ @@ -531,47 +483,10 @@ Graphics libraries * `smpeg `_ Part of the wrapper for SDL. -* `gl `_ - Part of the wrapper for OpenGL. -* `glext `_ - Part of the wrapper for OpenGL. -* `glu `_ - Part of the wrapper for OpenGL. -* `glut `_ - Part of the wrapper for OpenGL. -* `glx `_ - Part of the wrapper for OpenGL. -* `wingl `_ - Part of the wrapper for OpenGL. - -* `opengl `_ - New wrapper for OpenGL supporting up to version 4.2. - GUI libraries ------------- -* `atk `_ - Wrapper for the atk library. -* `gdk2 `_ - Wrapper for the gdk2 library. -* `gdk2pixbuf `_ - Wrapper for the gdk2pixbuf library. -* `gdkglext `_ - Wrapper for the gdkglext library. -* `glib2 `_ - Wrapper for the glib2 library. -* `gtk2 `_ - Wrapper for the gtk2 library. -* `gtkglext `_ - Wrapper for the gtkglext library. -* `gtkhtml `_ - Wrapper for the gtkhtml library. -* `libglade2 `_ - Wrapper for the libglade2 library. -* `pango `_ - Wrapper for the pango library. -* `pangoutils `_ - Wrapper for the pangoutils library. + * `iup `_ Wrapper of the IUP GUI library. @@ -616,21 +531,6 @@ Network Programming and Internet Protocols Wrapper for OpenSSL. -Scripting languages -------------------- - -* `lua `_ - Part of the wrapper for Lua. -* `lualib `_ - Part of the wrapper for Lua. -* `lauxlib `_ - Part of the wrapper for Lua. -* `tcl `_ - Wrapper for the TCL programming language. -* `python `_ - Wrapper for the Python programming language. - - Data Compression and Archiving ------------------------------ From 077b8327ecefb201f0937263fc21e4a9f28c16a8 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Fri, 3 Jan 2014 22:59:57 +0100 Subject: [PATCH 09/13] Documents rstgen index related procs. --- lib/packages/docutils/rstgen.nim | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/lib/packages/docutils/rstgen.nim b/lib/packages/docutils/rstgen.nim index 988338da19..5afd703192 100644 --- a/lib/packages/docutils/rstgen.nim +++ b/lib/packages/docutils/rstgen.nim @@ -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 + ## ``termfile#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) From 7aa263bebf946339a71cb7d153ea98d3c8302839 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 6 Jan 2014 20:41:42 +0100 Subject: [PATCH 10/13] Duplicates string literal table for character literals. Hopefully the index spamming will lead more people here. --- doc/manual.txt | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/doc/manual.txt b/doc/manual.txt index 88a7f38157..d9849f0441 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -312,13 +312,36 @@ 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 +this. Another reason is that Nimrod can thus support ``array[char, int]`` or ``set[char]`` efficiently as many algorithms rely on this feature. From 63ab238f5d00a7d4c9501ae635efcbb28f2e4e1a Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Mon, 6 Jan 2014 20:52:30 +0100 Subject: [PATCH 11/13] Adds note about conflicts with using as a statement. --- doc/manual.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/manual.txt b/doc/manual.txt index d9849f0441..c8b1c079c2 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -2257,6 +2257,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 ------------- From 2c2174f2d0415f975adb0e1679822afe394eee7d Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Tue, 14 Jan 2014 10:38:03 +0100 Subject: [PATCH 12/13] Clarifies system.lines() docstring. Amends c087f905134b249cf20cbabc4066fbfa62dd668a. --- lib/system.nim | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/system.nim b/lib/system.nim index 0257670f4c..70c8a529a3 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -2238,8 +2238,8 @@ when not defined(JS): #and not defined(NimrodVM): iterator lines*(filename: string): TaintedString {.tags: [FReadIO].} = ## Iterates over any line in the file named `filename`. ## - ## If the file does not exist `EIO` is raised. The iterated lines will be - ## stripped off the trailing newline character(s). Example: + ## 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 @@ -2257,8 +2257,8 @@ when not defined(JS): #and not defined(NimrodVM): iterator lines*(f: TFile): TaintedString {.tags: [FReadIO].} = ## Iterate over any line in the file `f`. ## - ## The iterated lines will be stripped off the trailing newline - ## character(s). Example: + ## The trailing newline character(s) are removed from the iterated lines. + ## Example: ## ## .. code-block:: nimrod ## proc countZeros(filename: TFile): tuple[lines, zeros: int] = From 42f152569db36ea6894caf11189be8f6fd06a482 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Tue, 14 Jan 2014 10:46:31 +0100 Subject: [PATCH 13/13] References TRune, links unicode modules where mentioned. Amends 0f3941b0013ea5d390586719f930fcf02b929f4d. --- doc/manual.txt | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/manual.txt b/doc/manual.txt index c8b1c079c2..f6dd1f521e 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -342,7 +342,9 @@ 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. +``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 `_. Numerical constants @@ -773,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 `_. + @@ -870,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 +`_ can be used for iteration over all Unicode characters. CString type