From d0c4c738b955f2641baa55ece6b5b90d4e632d8c Mon Sep 17 00:00:00 2001 From: Miran Date: Thu, 12 Nov 2020 22:25:23 +0100 Subject: [PATCH] add a tester for rst2html (#15936) --- koch.nim | 1 + nimdoc/rst2html/expected/rst_examples.html | 319 +++++++++++++ nimdoc/rst2html/source/rst_examples.rst | 510 +++++++++++++++++++++ nimdoc/rsttester.nim | 34 ++ 4 files changed, 864 insertions(+) create mode 100644 nimdoc/rst2html/expected/rst_examples.html create mode 100644 nimdoc/rst2html/source/rst_examples.rst create mode 100644 nimdoc/rsttester.nim diff --git a/koch.nim b/koch.nim index 47bde9d182b2d..628c810989595 100644 --- a/koch.nim +++ b/koch.nim @@ -554,6 +554,7 @@ proc runCI(cmd: string) = execFold("test with -d:nimHasLibFFI", "$1 $2 -r testament/testament --nim:$1 r tests/misc/trunner.nim -d:nimTrunnerFfi" % [nimFFI, backend]) execFold("Run nimdoc tests", "nim c -r nimdoc/tester") + execFold("Run rst2html tests", "nim c -r nimdoc/rsttester") execFold("Run nimpretty tests", "nim c -r nimpretty/tester.nim") when defined(posix): execFold("Run nimsuggest tests", "nim c -r nimsuggest/tester") diff --git a/nimdoc/rst2html/expected/rst_examples.html b/nimdoc/rst2html/expected/rst_examples.html new file mode 100644 index 0000000000000..8a08e8df515c4 --- /dev/null +++ b/nimdoc/rst2html/expected/rst_examples.html @@ -0,0 +1,319 @@ + + + + + + + + + + + + + + + + + + +Not a Nim Manual + + + + + + + + +
+
+

Not a Nim Manual

+
+
+
+ +     Dark Mode +
+ +
+ Search: +
+
+ Group by: + +
+ + +
+ +
+
+ +

+ +
Authors: Andreas Rumpf, Zahary Karadjov
Version: |nimversion|

"Complexity" seems to be a lot like "energy": you can transfer it from the end-user to one/some of the other players, but the total amount seems to remain pretty much constant for a given task. -- Ran

+ +

About this document

Note: This document is a draft! Several of Nim's features may need more precise wording. This manual is constantly evolving into a proper specification.

+

Note: The experimental features of Nim are covered here.

+

Note: Assignments, moves, and destruction are specified in the destructors document.

+

The language constructs are explained using an extended BNF, in which (a)* means 0 or more a's, a+ means 1 or more a's, and (a)? means an optional a. Parentheses may be used to group elements.

+

& is the lookahead operator; &a means that an a is expected but not consumed. It will be consumed in the following rule.

+

Non-terminals start with a lowercase letter, abstract terminal symbols are in UPPERCASE. Verbatim terminal symbols (including keywords) are quoted with '. An example:

+ifStmt = 'if' expr ':' stmts ('elif' expr ':' stmts)* ('else' stmts)?
+

+

In a typical Nim program, most of the code is compiled into the executable. However, some of the code may be executed at compile-time. This can include constant expressions, macro definitions, and Nim procedures used by macro definitions. Most of the Nim language is supported at compile-time, but there are some restrictions -- see Restrictions on Compile-Time Execution for details. We use the term runtime to cover both compile-time execution and code execution in the executable.

+
var a: array[0..1, char]
+let i = 5
+try:
+  a[i] = 'N'
+except IndexDefect:
+  echo "invalid index"
+

Encoding

All Nim source files are in the UTF-8 encoding (or its ASCII subset). Other encodings are not supported. Any of the standard platform line termination sequences can be used - the Unix form using ASCII LF (linefeed), the Windows form using the ASCII sequence CR LF (return followed by linefeed), or the old Macintosh form using the ASCII CR (return) character. All of these forms can be used equally, regardless of the platform.

+ +

Indentation

Nim's standard grammar describes an indentation sensitive language. This means that all the control structures are recognized by indentation. Indentation consists only of spaces; tabulators are not allowed.

+

With this notation we can now easily define the core of the grammar: A block of statements (simplified example):

+ifStmt = 'if' expr ':' stmt
+         (IND{=} 'elif' expr ':' stmt)*
+         (IND{=} 'else' ':' stmt)?
+
+simpleStmt = ifStmt / ...
+
+stmt = IND{>} stmt ^+ IND{=} DED  # list of statements
+     / simpleStmt                 # or a simple statement
+

+

String literals can be delimited by matching double quotes, and can contain the following escape sequences:

+ + + + + + + + + + + + + + + + + +
Escape sequenceMeaning
\pplatform specific newline: CRLF on Windows, LF on Unix
\r, \ccarriage return
\n, \lline feed (often called newline)
\fform feed
\ttabulator
\vvertical tabulator
\\backslash
\"quotation mark
\'apostrophe
\ '0'..'9'+character with decimal value d; all decimal digits directly following are used for the character
\aalert
\bbackspace
\eescape [ESC]
\x HHcharacter with hex value HH; exactly two hex digits are allowed
\u HHHHunicode codepoint with hex value HHHH; exactly four hex digits are allowed
\u {H+}unicode codepoint; all hex digits enclosed in {} are used for the codepoint
""""long string within quotes""""

Produces:

+"long string within quotes"
+

+ +

Operators

Nim allows user defined operators. An operator is any combination of the following characters:

+=     +     -     *     /     <     >
+@     $     ~     &     %     |
+!     ?     ^     .     :     \
+

+

(The grammar uses the terminal OPR to refer to operator symbols as defined here.)

+

The following strings denote other tokens:

+`   (    )     {    }     [    ]    ,  ;   [.    .]  {.   .}  (.  .)  [:
+

+

Otherwise, precedence is determined by the first character.

+ + + + + + + + + + + + +
Precedence levelOperatorsFirst characterTerminal symbol
10 (highest)$ ^OP10
9* / div mod shl shr %* % \ /OP9
8+ -+ - ~ |OP8
7&&OP7
6...OP6
5== <= < >= > != in notin is isnot not of as from= < > !OP5
4andOP4
3or xorOP3
2@ : ?OP2
1assignment operator (like +=, *=)OP1
0 (lowest)arrow like operator (like ->, =>)OP0
+

Constants and Constant Expressions

A constant is a symbol that is bound to the value of a constant expression. Constant expressions are restricted to depend only on the following categories of values and operations, because these are either built into the language or declared and evaluated before semantic analysis of the constant expression:

+
  • literals
    • +
  • built-in operators
    • +
  • previously declared constants and compile-time variables
    • +
  • previously declared macros and templates
    • +
  • previously declared procedures that have no side effects beyond possibly modifying compile-time variables
    • +
+

These integer types are pre-defined:

+
int
+
the generic signed integer type; its size is platform-dependent and has the same size as a pointer. This type should be used in general. An integer literal that has no type suffix is of this type if it is in the range low(int32)..high(int32) otherwise the literal's type is int64.
+
intXX
+
additional signed integer types of XX bits use this naming scheme (example: int16 is a 16-bit wide integer). The current implementation supports int8, int16, int32, int64. Literals of these types have the suffix 'iXX.
+
uint
+
the generic unsigned integer type; its size is platform-dependent and has the same size as a pointer. An integer literal with the type suffix 'u is of this type.
+
+

Let T's be p's return type. NRVO applies for T if sizeof(T) >= N (where N is implementation dependent), in other words, it applies for "big" structures.

+

Apart from built-in operations like array indexing, memory allocation, etc. the raise statement is the only way to raise an exception.

+

typedesc used as a parameter type also introduces an implicit generic. typedesc has its own set of rules:

+

The !=, >, >=, in, notin, isnot operators are in fact templates:

+

a > b is transformed into b < a.
a in b is transformed into contains(b, a).
notin and isnot have the obvious meanings.

A template where every parameter is untyped is called an immediate template. For historical reasons templates can be explicitly annotated with an immediate pragma and then these templates do not take part in overloading resolution and the parameters' types are ignored by the compiler. Explicit immediate templates are now deprecated.

+ +

Symbol lookup in generics

+

Open and Closed symbols

The symbol binding rules in generics are slightly subtle: There are "open" and "closed" symbols. A "closed" symbol cannot be re-bound in the instantiation context, an "open" symbol can. Per default overloaded symbols are open and every other symbol is closed.

+

In templates identifiers can be constructed with the backticks notation:

+
template typedef(name: untyped, typ: typedesc) =
+  type
+    `T name`* {.inject.} = typ
+    `P name`* {.inject.} = ref `T name`
+
+typedef(myint, int)
+var x: PMyInt

In the example name is instantiated with myint, so `T name` becomes Tmyint.

+

Only top-level symbols that are marked with an asterisk (*) are exported.

+

The algorithm for compiling modules is:

+
  • compile the whole module as usual, following import statements recursively
    • +
  • if there is a cycle only import the already parsed symbols (that are exported); if an unknown identifier occurs then abort
    • +
+ +

Collective imports from a directory

The syntax import dir / [moduleA, moduleB] can be used to import multiple modules from the same directory.

+ +

Pragmas

Pragmas are Nim's method to give the compiler additional information / commands without introducing a massive number of new keywords. Pragmas are processed on the fly during semantic checking. Pragmas are enclosed in the special {. and .} curly brackets. Pragmas are also often used as a first implementation to play with a language feature before a nicer syntax to access the feature becomes available.

+ +

deprecated pragma

The deprecated pragma is used to mark a symbol as deprecated:

+

Note: c2nim can parse a large subset of C++ and knows about the importcpp pragma pattern language. It is not necessary to know all the details described here.

+

Pure libraries do not depend on any external *.dll or lib*.so binary while impure libraries do. A wrapper is an impure library that is a very low-level interface to a C library.

+ +

Pure libraries

+

Automatic imports

  • system Basic procs and operators that every program needs. It also provides IO facilities for reading and writing text and binary files. It is imported implicitly by the compiler. Do not import it directly. It relies on compiler magic to work.
    • +
  • threads Basic Nim thread support. Note: This is part of the system module. Do not import it explicitly. Enabled with --threads:on.
    • +
+ +

Code reordering

The code reordering feature can implicitly rearrange procedure, template, and macro definitions along with variable declarations and initializations at the top level scope so that, to a large extent, a programmer should not have to worry about ordering definitions correctly or be forced to use forward declarations to preface definitions inside a module.

+

Example:

+
{.experimental: "codeReordering".}
+
+proc foo(x: int) =
+  bar(x)
+
+proc bar(x: int) =
+  echo(x)
+
+foo(10)

It is important to note that reordering only works for symbols at top level scope. Therefore, the following will fail to compile:

+ +

Parameter constraints

The parameter constraint expression can use the operators | (or), & (and) and ~ (not) and the following predicates:

+ +

The ~ operator

The ~ operator is the not operator in patterns:

+ +

The ** operator

The ** is much like the * operator, except that it gathers not only all the arguments, but also the matched operators in reverse polish notation:

+

Nim significantly improves on the safety of these features via additional pragmas:

+
  1. A guard annotation is introduced to prevent data races.
    2. +
  2. Every access of a guarded memory location needs to happen in an appropriate locks statement.
    3. +
  3. Locks and routines can be annotated with lock levels to allow potential deadlocks to be detected during semantic analysis.
    4. +
+
  1. Two output parameters should never be aliased.
    2. +
  2. An input and an output parameter should not be aliased.
    3. +
  3. An output parameter should never be aliased with a global or thread local variable referenced by the called proc.
    4. +
  4. An input parameter should not be aliased with a global or thread local variable updated by the called proc.
    5. +
+

One problem with rules 3 and 4 is that they affect specific global or thread local variables, but Nim's effect tracking only tracks "uses no global variable" via .noSideEffect. The rules 3 and 4 can also be approximated by a different rule:

+
  1. A global or thread local variable (or a location derived from such a location) can only passed to a parameter of a .noSideEffect proc.
    2. +
+

These two procs are the two modus operandi of the real-time garbage collector:

+

(1) GC_SetMaxPause Mode

+

You can call GC_SetMaxPause at program startup and then each triggered garbage collector run tries to not take longer than maxPause time. However, it is possible (and common) that the work is nevertheless not evenly distributed as each call to new can trigger the garbage collector and thus take maxPause time.

+

(2) GC_step Mode

+

This allows the garbage collector to perform some work for up to us time. This is useful to call in the main loop to ensure the garbage collector can do its work. To bind all garbage collector activity to a GC_step call, deactivate the garbage collector with GC_disable at program startup. If strongAdvice is set to true, then the garbage collector will be forced to perform the collection cycle. Otherwise, the garbage collector may decide not to do anything, if there is not much garbage to collect. You may also specify the current stack size via stackSize parameter. It can improve performance when you know that there are no unique Nim references below a certain point on the stack. Make sure the size you specify is greater than the potential worst-case size.

+

It can improve performance when you know that there are no unique Nim references below a certain point on the stack. Make sure the size you specify is greater than the potential worst-case size.

+

+

These procs provide a "best effort" real-time guarantee; in particular the cycle collector is not aware of deadlines. Deactivate it to get more predictable real-time behaviour. Tests show that a 1ms max pause time will be met in almost all cases on modern CPUs (with the cycle collector disabled).

+ +

Time measurement with garbage collectors

The garbage collectors' way of measuring time uses (see lib/system/timers.nim for the implementation):

+
  1. QueryPerformanceCounter and QueryPerformanceFrequency on Windows.
    2. +
  2. mach_absolute_time on Mac OS X.
    3. +
  3. gettimeofday on Posix systems.
    4. +
+

As such it supports a resolution of nanoseconds internally; however, the API uses microseconds for convenience.

+ +

Introduction

+"Der Mensch ist doch ein Augentier -- schöne Dinge wünsch ich mir." +

This document is a tutorial for the programming language Nim. This tutorial assumes that you are familiar with basic programming concepts like variables, types, or statements but is kept very basic. The manual contains many more examples of the advanced language features. All code examples in this tutorial, as well as the ones found in the rest of Nim's documentation, follow the Nim style guide.

+

However, this does not work. The problem is that the procedure should not only return, but return and continue after an iteration has finished. This return and continue is called a yield statement. Now the only thing left to do is to replace the proc keyword by iterator and here it is - our first iterator:

+ + + + + +
A1 headerA2 | not fooled
C1C2 bold
D1 code |D2
E1 | text
F2 without pipe

not in table

+

+ +
+
+ +
+
+ +
+ Made with Nim. Generated: 1970-01-02 03:46:40 UTC +
+
+
+
+ + + diff --git a/nimdoc/rst2html/source/rst_examples.rst b/nimdoc/rst2html/source/rst_examples.rst new file mode 100644 index 0000000000000..c8d15aef85916 --- /dev/null +++ b/nimdoc/rst2html/source/rst_examples.rst @@ -0,0 +1,510 @@ +========== +Not a Nim Manual +========== + +:Authors: Andreas Rumpf, Zahary Karadjov +:Version: |nimversion| + +.. contents:: + + + "Complexity" seems to be a lot like "energy": you can transfer it from the + end-user to one/some of the other players, but the total amount seems to remain + pretty much constant for a given task. -- Ran + + +About this document +=================== + +**Note**: This document is a draft! Several of Nim's features may need more +precise wording. This manual is constantly evolving into a proper specification. + +**Note**: The experimental features of Nim are +covered `here `_. + +**Note**: Assignments, moves, and destruction are specified in +the `destructors `_ document. + +The language constructs are explained using an extended BNF, in which ``(a)*`` +means 0 or more ``a``'s, ``a+`` means 1 or more ``a``'s, and ``(a)?`` means an +optional *a*. Parentheses may be used to group elements. + +``&`` is the lookahead operator; ``&a`` means that an ``a`` is expected but +not consumed. It will be consumed in the following rule. + +Non-terminals start with a lowercase letter, abstract terminal symbols are in +UPPERCASE. Verbatim terminal symbols (including keywords) are quoted +with ``'``. An example:: + + ifStmt = 'if' expr ':' stmts ('elif' expr ':' stmts)* ('else' stmts)? + +In a typical Nim program, most of the code is compiled into the executable. +However, some of the code may be executed at +`compile-time`:idx:. This can include constant expressions, macro definitions, +and Nim procedures used by macro definitions. Most of the Nim language is +supported at compile-time, but there are some restrictions -- see `Restrictions +on Compile-Time Execution <#restrictions-on-compileminustime-execution>`_ for +details. We use the term `runtime`:idx: to cover both compile-time execution +and code execution in the executable. + +.. code-block:: nim + var a: array[0..1, char] + let i = 5 + try: + a[i] = 'N' + except IndexDefect: + echo "invalid index" + +Encoding +-------- + +All Nim source files are in the UTF-8 encoding (or its ASCII subset). Other +encodings are not supported. Any of the standard platform line termination +sequences can be used - the Unix form using ASCII LF (linefeed), the Windows +form using the ASCII sequence CR LF (return followed by linefeed), or the old +Macintosh form using the ASCII CR (return) character. All of these forms can be +used equally, regardless of the platform. + + +Indentation +----------- + +Nim's standard grammar describes an `indentation sensitive`:idx: language. +This means that all the control structures are recognized by indentation. +Indentation consists only of spaces; tabulators are not allowed. + +With this notation we can now easily define the core of the grammar: A block of +statements (simplified example):: + + ifStmt = 'if' expr ':' stmt + (IND{=} 'elif' expr ':' stmt)* + (IND{=} 'else' ':' stmt)? + + simpleStmt = ifStmt / ... + + stmt = IND{>} stmt ^+ IND{=} DED # list of statements + / simpleStmt # or a simple statement + + +String literals can be delimited by matching double quotes, and can +contain the following `escape sequences`:idx:\ : + +================== =================================================== + Escape sequence Meaning +================== =================================================== + ``\p`` platform specific newline: CRLF on Windows, + LF on Unix + ``\r``, ``\c`` `carriage return`:idx: + ``\n``, ``\l`` `line feed`:idx: (often called `newline`: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 + ``\u`` HHHH `unicode codepoint with hex value HHHH`:idx:; + exactly four hex digits are allowed + ``\u`` {H+} `unicode codepoint`:idx:; + all hex digits enclosed in ``{}`` are used for + the codepoint +================== =================================================== + +.. code-block:: nim + """"long string within quotes"""" + +Produces:: + + "long string within quotes" + +Operators +--------- + +Nim allows user defined operators. An operator is any combination of the +following characters:: + + = + - * / < > + @ $ ~ & % | + ! ? ^ . : \ + +(The grammar uses the terminal OPR to refer to operator symbols as +defined here.) + +The following strings denote other tokens:: + + ` ( ) { } [ ] , ; [. .] {. .} (. .) [: + + +Otherwise, precedence is determined by the first character. + +================ ======================================================= ================== =============== +Precedence level Operators First character Terminal symbol +================ ======================================================= ================== =============== + 10 (highest) ``$ ^`` OP10 + 9 ``* / div mod shl shr %`` ``* % \ /`` OP9 + 8 ``+ -`` ``+ - ~ |`` OP8 + 7 ``&`` ``&`` OP7 + 6 ``..`` ``.`` OP6 + 5 ``== <= < >= > != in notin is isnot not of as from`` ``= < > !`` OP5 + 4 ``and`` OP4 + 3 ``or xor`` OP3 + 2 ``@ : ?`` OP2 + 1 *assignment operator* (like ``+=``, ``*=``) OP1 + 0 (lowest) *arrow like operator* (like ``->``, ``=>``) OP0 +================ ======================================================= ================== =============== + + +Constants and Constant Expressions +================================== + +A `constant`:idx: is a symbol that is bound to the value of a constant +expression. Constant expressions are restricted to depend only on the following +categories of values and operations, because these are either built into the +language or declared and evaluated before semantic analysis of the constant +expression: + +* literals +* built-in operators +* previously declared constants and compile-time variables +* previously declared macros and templates +* previously declared procedures that have no side effects beyond + possibly modifying compile-time variables + +These integer types are pre-defined: + +``int`` + the generic signed integer type; its size is platform-dependent and has the + same size as a pointer. This type should be used in general. An integer + literal that has no type suffix is of this type if it is in the range + ``low(int32)..high(int32)`` otherwise the literal's type is ``int64``. + +intXX + additional signed integer types of XX bits use this naming scheme + (example: int16 is a 16-bit wide integer). + The current implementation supports ``int8``, ``int16``, ``int32``, ``int64``. + Literals of these types have the suffix 'iXX. + +``uint`` + the generic `unsigned integer`:idx: type; its size is platform-dependent and has the same size as a pointer. An integer literal with the type suffix ``'u`` is of this type. + +Let ``T``'s be ``p``'s return type. NRVO applies for ``T`` +if ``sizeof(T) >= N`` (where ``N`` is implementation dependent), +in other words, it applies for "big" structures. + +Apart from built-in operations like array indexing, memory allocation, etc. +the ``raise`` statement is the only way to raise an exception. + +.. XXX document this better! + +`typedesc` used as a parameter type also introduces an implicit +generic. `typedesc` has its own set of rules: + +The ``!=``, ``>``, ``>=``, ``in``, ``notin``, ``isnot`` operators are in fact +templates: + +| ``a > b`` is transformed into ``b < a``. +| ``a in b`` is transformed into ``contains(b, a)``. +| ``notin`` and ``isnot`` have the obvious meanings. + +A template where every parameter is ``untyped`` is called an `immediate`:idx: +template. For historical reasons templates can be explicitly annotated with +an ``immediate`` pragma and then these templates do not take part in +overloading resolution and the parameters' types are *ignored* by the +compiler. Explicit immediate templates are now deprecated. + + + +Symbol lookup in generics +------------------------- + +Open and Closed symbols +~~~~~~~~~~~~~~~~~~~~~~~ + +The symbol binding rules in generics are slightly subtle: There are "open" and +"closed" symbols. A "closed" symbol cannot be re-bound in the instantiation +context, an "open" symbol can. Per default overloaded symbols are open +and every other symbol is closed. + +In templates identifiers can be constructed with the backticks notation: + +.. code-block:: nim + :test: "nim c $1" + + template typedef(name: untyped, typ: typedesc) = + type + `T name`* {.inject.} = typ + `P name`* {.inject.} = ref `T name` + + typedef(myint, int) + var x: PMyInt + +In the example ``name`` is instantiated with ``myint``, so \`T name\` becomes +``Tmyint``. + +Only top-level symbols that are marked with an asterisk (``*``) are +exported. + +The algorithm for compiling modules is: + +- compile the whole module as usual, following import statements recursively + +- if there is a cycle only import the already parsed symbols (that are + exported); if an unknown identifier occurs then abort + + +Collective imports from a directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The syntax ``import dir / [moduleA, moduleB]`` can be used to import multiple modules +from the same directory. + + +Pragmas +======= + +Pragmas are Nim's method to give the compiler additional information / +commands without introducing a massive number of new keywords. Pragmas are +processed on the fly during semantic checking. Pragmas are enclosed in the +special ``{.`` and ``.}`` curly brackets. Pragmas are also often used as a +first implementation to play with a language feature before a nicer syntax +to access the feature becomes available. + + +deprecated pragma +----------------- + +The deprecated pragma is used to mark a symbol as deprecated: + +**Note**: `c2nim `_ can parse a large subset of C++ and knows +about the ``importcpp`` pragma pattern language. It is not necessary +to know all the details described here. + + + +Pure libraries do not depend on any external ``*.dll`` or ``lib*.so`` binary +while impure libraries do. A wrapper is an impure library that is a very +low-level interface to a C library. + + +Pure libraries +============== + +Automatic imports +----------------- + +* `system `_ + Basic procs and operators that every program needs. It also provides IO + facilities for reading and writing text and binary files. It is imported + implicitly by the compiler. Do not import it directly. It relies on compiler + magic to work. + +* `threads `_ + Basic Nim thread support. **Note**: This is part of the system module. Do not + import it explicitly. Enabled with ``--threads:on``. + +Code reordering +=============== + +The code reordering feature can implicitly rearrange procedure, template, and +macro definitions along with variable declarations and initializations at the top +level scope so that, to a large extent, a programmer should not have to worry +about ordering definitions correctly or be forced to use forward declarations to +preface definitions inside a module. + +.. + NOTE: The following was documentation for the code reordering precursor, + which was {.noForward.}. + + In this mode, procedure definitions may appear out of order and the compiler + will postpone their semantic analysis and compilation until it actually needs + to generate code using the definitions. In this regard, this mode is similar + to the modus operandi of dynamic scripting languages, where the function + calls are not resolved until the code is executed. Here is the detailed + algorithm taken by the compiler: + + 1. When a callable symbol is first encountered, the compiler will only note + the symbol callable name and it will add it to the appropriate overload set + in the current scope. At this step, it won't try to resolve any of the type + expressions used in the signature of the symbol (so they can refer to other + not yet defined symbols). + + 2. When a top level call is encountered (usually at the very end of the + module), the compiler will try to determine the actual types of all of the + symbols in the matching overload set. This is a potentially recursive process + as the signatures of the symbols may include other call expressions, whose + types will be resolved at this point too. + + 3. Finally, after the best overload is picked, the compiler will start + compiling the body of the respective symbol. This in turn will lead the + compiler to discover more call expressions that need to be resolved and steps + 2 and 3 will be repeated as necessary. + + Please note that if a callable symbol is never used in this scenario, its + body will never be compiled. This is the default behavior leading to best + compilation times, but if exhaustive compilation of all definitions is + required, using ``nim check`` provides this option as well. + +Example: + +.. code-block:: nim + + {.experimental: "codeReordering".} + + proc foo(x: int) = + bar(x) + + proc bar(x: int) = + echo(x) + + foo(10) + + +.. + TODO: Let's table this for now. This is an *experimental feature* and so the + specific manner in which ``declared`` operates with it can be decided in + eventuality, because right now it works a bit weirdly. + + The values of expressions involving ``declared`` are decided *before* the + code reordering process, and not after. As an example, the output of this + code is the same as it would be with code reordering disabled. + + .. code-block:: nim + {.experimental: "codeReordering".} + + proc x() = + echo(declared(foo)) + + var foo = 4 + + x() # "false" + +It is important to note that reordering *only* works for symbols at top level +scope. Therefore, the following will *fail to compile:* + + +Parameter constraints +--------------------- + +The `parameter constraint`:idx: expression can use the operators ``|`` (or), +``&`` (and) and ``~`` (not) and the following predicates: + + +The ``~`` operator +~~~~~~~~~~~~~~~~~~ + +The ``~`` operator is the **not** operator in patterns: + + +The ``**`` operator +~~~~~~~~~~~~~~~~~~~ + +The ``**`` is much like the ``*`` operator, except that it gathers not only +all the arguments, but also the matched operators in reverse polish notation: + +Nim significantly improves on the safety of these features via additional +pragmas: + +1) A `guard`:idx: annotation is introduced to prevent data races. +2) Every access of a guarded memory location needs to happen in an + appropriate `locks`:idx: statement. +3) Locks and routines can be annotated with `lock levels`:idx: to allow + potential deadlocks to be detected during semantic analysis. + +1. Two output parameters should never be aliased. +2. An input and an output parameter should not be aliased. +3. An output parameter should never be aliased with a global or thread local + variable referenced by the called proc. +4. An input parameter should not be aliased with a global or thread local + variable updated by the called proc. + +One problem with rules 3 and 4 is that they affect specific global or thread +local variables, but Nim's effect tracking only tracks "uses no global variable" +via ``.noSideEffect``. The rules 3 and 4 can also be approximated by a different rule: + +5. A global or thread local variable (or a location derived from such a location) + can only passed to a parameter of a ``.noSideEffect`` proc. + +These two procs are the two modus operandi of the real-time garbage collector: + +(1) GC_SetMaxPause Mode + + You can call ``GC_SetMaxPause`` at program startup and then each triggered + garbage collector run tries to not take longer than ``maxPause`` time. However, it is + possible (and common) that the work is nevertheless not evenly distributed + as each call to ``new`` can trigger the garbage collector and thus take ``maxPause`` + time. + +(2) GC_step Mode + + This allows the garbage collector to perform some work for up to ``us`` time. + This is useful to call in the main loop to ensure the garbage collector can do its work. + To bind all garbage collector activity to a ``GC_step`` call, + deactivate the garbage collector with ``GC_disable`` at program startup. + If ``strongAdvice`` is set to ``true``, + then the garbage collector will be forced to perform the collection cycle. + Otherwise, the garbage collector may decide not to do anything, + if there is not much garbage to collect. + You may also specify the current stack size via ``stackSize`` parameter. + It can improve performance when you know that there are no unique Nim references + below a certain point on the stack. Make sure the size you specify is greater + than the potential worst-case size. + + It can improve performance when you know that there are no unique Nim + references below a certain point on the stack. Make sure the size you specify + is greater than the potential worst-case size. + +These procs provide a "best effort" real-time guarantee; in particular the +cycle collector is not aware of deadlines. Deactivate it to get more +predictable real-time behaviour. Tests show that a 1ms max pause +time will be met in almost all cases on modern CPUs (with the cycle collector +disabled). + +Time measurement with garbage collectors +---------------------------------------- + +The garbage collectors' way of measuring time uses +(see ``lib/system/timers.nim`` for the implementation): + +1) ``QueryPerformanceCounter`` and ``QueryPerformanceFrequency`` on Windows. +2) ``mach_absolute_time`` on Mac OS X. +3) ``gettimeofday`` on Posix systems. + +As such it supports a resolution of nanoseconds internally; however, the API +uses microseconds for convenience. + +Introduction +============ + +.. raw:: html +

+ "Der Mensch ist doch ein Augentier -- schöne Dinge wünsch ich mir." +

+ + +This document is a tutorial for the programming language *Nim*. +This tutorial assumes that you are familiar with basic programming concepts +like variables, types, or statements but is kept very basic. The `manual +`_ contains many more examples of the advanced language features. +All code examples in this tutorial, as well as the ones found in the rest of +Nim's documentation, follow the `Nim style guide `_. + +However, this does not work. The problem is that the procedure should not +only ``return``, but return and **continue** after an iteration has +finished. This *return and continue* is called a `yield` statement. Now +the only thing left to do is to replace the ``proc`` keyword by ``iterator`` +and here it is - our first iterator: + +| A1 header | A2 \| not fooled +| :--- | ----: | +| C1 | C2 **bold** | ignored | +| D1 `code \|` | D2 | also ignored +| E1 \| text | +| | F2 without pipe +not in table diff --git a/nimdoc/rsttester.nim b/nimdoc/rsttester.nim new file mode 100644 index 0000000000000..6d41ffb86b7a0 --- /dev/null +++ b/nimdoc/rsttester.nim @@ -0,0 +1,34 @@ +import os, strutils + +const + baseDir = "nimdoc/rst2html" + +var failures = 0 + +proc exec(cmd: string) = + if execShellCmd(cmd) != 0: + quit("FAILURE: " & cmd) + +proc testRst2Html(fixup = false) = + putEnv("SOURCE_DATE_EPOCH", "100000") + const nimExe = getCurrentCompilerExe() # so that `bin/nim_temp r nimdoc/tester.nim` works + + for expectedHtml in walkDir(baseDir / "expected"): + let expectedHtml = expectedHtml.path + let sourceFile = expectedHtml.replace('\\', '/').replace("/expected/", "/source/").replace(".html", ".rst") + exec("$1 rst2html $2" % [nimExe, sourceFile]) + let producedHtml = expectedHtml.replace('\\', '/').replace("/expected/", "/source/htmldocs/") + if readFile(expectedHtml) != readFile(producedHtml): + discard execShellCmd("diff -uNdr " & expectedHtml & " " & producedHtml) + inc failures + if fixup: + copyFile(producedHtml, expectedHtml) + else: + echo "SUCCESS: files identical: ", producedHtml + if failures == 0: + removeDir(baseDir / "source/htmldocs") + +testRst2Html(defined(fixup)) + +# Check for failures +if failures > 0: quit($failures & " failures occurred.")