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

Markdown link migration part 2 (#20371)

Browse Source
This commit is contained in:
Andrey Makarov
2022-09-20 01:24:40 +03:00
committed by GitHub
parent 2147b116a1
commit c4ba4f06f8
18 changed files with 287 additions and 283 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
doc/docs.md
View File

@@ -1,38 +1,38 @@
The documentation consists of several documents:
- | `Tutorial (part I) <tut1.html>`_
- | [Tutorial (part I)](tut1.html)
| The Nim tutorial part one deals with the basics.
- | `Tutorial (part II) <tut2.html>`_
- | [Tutorial (part II)](tut2.html)
| The Nim tutorial part two deals with the advanced language constructs.
- | `Tutorial (part III) <tut3.html>`_
- | [Tutorial (part III)](tut3.html)
| The Nim tutorial part three about Nim's macro system.
- | `Language Manual <manual.html>`_
- | [Language Manual](manual.html)
| The Nim manual is a draft that will evolve into a proper specification.
- | `Library documentation <lib.html>`_
- | [Library documentation](lib.html)
| This document describes Nim's standard library.
- | `Compiler user guide <nimc.html>`_
- | [Compiler user guide](nimc.html)
| The user guide lists command line arguments, special features of the
compiler, etc.
- | `Tools documentation <tools.html>`_
- | [Tools documentation](tools.html)
| Description of some tools that come with the standard distribution.
- | `Memory management <mm.html>`_
- | [Memory management](mm.html)
| Additional documentation about Nim's memory management strategies
| and how to operate them in a realtime setting.
- | `Source code filters <filters.html>`_
- | [Source code filters](filters.html)
| The Nim compiler supports source code filters as a simple yet powerful
builtin templating system.
- | `Internal documentation <intern.html>`_
- | [Internal documentation](intern.html)
| The internal documentation describes how the compiler is implemented. Read
this if you want to hack the compiler.
- | `Index <theindex.html>`_
- | [Index](theindex.html)
| The generated index. **Index + (Ctrl+F) == Joy**

2
doc/docstyle.md
View File

@@ -4,7 +4,7 @@ Documentation Style
General Guidelines
------------------
* See also `nep1<https://nim-lang.github.io/Nim/nep1.html>`_ which should probably be merged here.
* See also [nep1](nep1.html) which should probably be merged here.
* Authors should document anything that is exported; documentation for private
procs can be useful too (visible via `nim doc --docInternal foo.nim`:cmd:).
* Within documentation, a period (`.`) should follow each sentence (or sentence fragment) in a comment block.

2
doc/drnim.md
View File

@@ -14,7 +14,7 @@ Introduction
============
This document describes the usage of the *DrNim* tool. DrNim combines
the Nim frontend with the `Z3 <https://github.com/Z3Prover/z3>`_ proof
the Nim frontend with the [Z3](https://github.com/Z3Prover/z3) proof
engine, in order to allow verify/validate software written in Nim.
DrNim's command-line options are the same as the Nim compiler's.

20
doc/idetools.md
View File

@@ -12,19 +12,19 @@
> "yes, I'm the creator" -- Araq, 2013-07-26 19:28:32.
Note: this is mostly outdated, see instead `nimsuggest <nimsuggest.html>`_
Note: this is mostly outdated, see instead [nimsuggest](nimsuggest.html)
Nim differs from many other compilers in that it is really fast,
and being so fast makes it suited to provide external queries for
text editors about the source code being written. Through the
`idetools` command of `the compiler <nimc.html>`_, any IDE
`idetools` command of [the compiler](nimc.html), any IDE
can query a `.nim` source file and obtain useful information like
definition of symbols or suggestions for completion.
This document will guide you through the available options. If you
want to look at practical examples of idetools support you can look
at the test files found in the `Test suite`_ or `various editor
integrations <https://github.com/Araq/Nim/wiki/Editor-Support>`_
at the test files found in the [Test suite] or [various editor
integrations](https://github.com/Araq/Nim/wiki/Editor-Support)
already available.
@@ -124,8 +124,8 @@ to the case insensitiveness of the language (plus underscores as
separators!).
The typical usage scenario for this option is to call it after the
user has typed the dot character for `the object oriented call
syntax <tut2.html#object-oriented-programming-method-call-syntax>`_.
user has typed the dot character for [the object oriented call
syntax](tut2.html#object-oriented-programming-method-call-syntax).
Idetools will try to return the suggestions sorted first by scope
(from innermost to outermost) and then by item name.
@@ -196,7 +196,7 @@ of text it thinks necessary plus an empty line to indicate the end
of the answer.
You can find examples of client/server communication in the idetools
tests found in the `Test suite`_.
tests found in the [Test suite].
Parsing idetools output
@@ -367,8 +367,8 @@ defined, since at that point in the file the parser hasn't processed
the full line yet. The signature will be returned complete in
posterior instances of the method.
Methods imply `dynamic dispatch
<tut2.html#object-oriented-programming-dynamic-dispatch>`_ and
Methods imply [dynamic dispatch](
tut2.html#object-oriented-programming-dynamic-dispatch) and
idetools performs a static analysis on the code. For this reason
idetools may not return the definition of the correct method you
are querying because it may be impossible to know until the code
@@ -590,7 +590,7 @@ All the `tests/caas/*.txt` files encode a session with the compiler:
modes, you can prefix a line with the mode and the line will be
processed only in that mode.
* The rest of the line is treated as a `regular expression <re.html>`_,
* The rest of the line is treated as a [regular expression](re.html),
so be careful escaping metacharacters like parenthesis.
Before the line is processed as a regular expression, some basic

14
doc/intern.md
View File

@@ -64,7 +64,7 @@ And for a debug version compatible with GDB:
The `koch`:cmd: program is Nim's maintenance script. It is a replacement for
make and shell scripting with the advantage that it is much more portable.
More information about its options can be found in the `koch <koch.html>`_
More information about its options can be found in the [koch](koch.html)
documentation.
@@ -105,7 +105,7 @@ current commit:
You can also bisect using custom options to build the compiler, for example if
you don't need a debug version of the compiler (which runs slower), you can replace
`./koch temp`:cmd: by explicit compilation command, see `Bootstrapping the compiler`_.
`./koch temp`:cmd: by explicit compilation command, see [Bootstrapping the compiler].
Building an instrumented compiler
@@ -269,7 +269,7 @@ Native debugging
Stepping through the compiler with a native debugger is a very powerful tool to
both learn and debug it. However, there is still the need to constrain when
breakpoints are triggered. The same methods as in `Debug logging`_ can be applied
breakpoints are triggered. The same methods as in [Debug logging] can be applied
here when combined with calls to the debug helpers `enteringDebugSection()`:nim:
and `exitingDebugSection()`:nim:.
@@ -309,7 +309,7 @@ The syntax tree consists of nodes which may have an arbitrary number of
children. Types and symbols are represented by other nodes, because they
may contain cycles. The AST changes its shape after semantic checking. This
is needed to make life easier for the code generators. See the "ast" module
for the type definitions. The `macros <macros.html>`_ module contains many
for the type definitions. The [macros](macros.html) module contains many
examples how the AST represents each syntactic structure.
@@ -324,7 +324,7 @@ ARC/ORC. The new runtime is active `when defined(nimV2)`.
Coding Guidelines
=================
* We follow Nim's official style guide, see `<nep1.html>`_.
* We follow Nim's official style guide, see [NEP1](nep1.html).
* Max line length is 100 characters.
* Provide spaces around binary operators if that enhances readability.
* Use a space after a colon, but not before it.
@@ -332,7 +332,7 @@ Coding Guidelines
pointers/references which start with `P`.
* Prefer `import package`:nim: over `from package import symbol`:nim:.
See also the `API naming design <apis.html>`_ document.
See also the [API naming design](apis.html) document.
Porting to new platforms
@@ -452,7 +452,7 @@ could stem from a complex expression:
receivesClosure(returnsDefaultCC[i])
```
A thunk would need to call 'returnsDefaultCC[i]' somehow and that would require
A thunk would need to call `returnsDefaultCC[i]` somehow and that would require
an *additional* closure generation... Ok, not really, but it requires to pass
the function to call. So we'd end up with 2 indirect calls instead of one.
Another much more severe problem with this solution is that it's not GC-safe

10
doc/koch.md
View File

@@ -48,16 +48,16 @@ csource command
---------------
The `csource`:idx: command builds the C sources for installation. It accepts
the same options as you would pass to the `boot command
<#commands-boot-command>`_.
the same options as you would pass to the [boot command](
#commands-boot-command).
temp command
------------
The temp command builds the Nim compiler but with a different final name
(`nim_temp`:cmd:), so it doesn't overwrite your normal compiler. You can use
this command to test different options, the same you would issue for the `boot
command <#commands-boot-command>`_.
this command to test different options, the same you would issue for the [boot
command](#commands-boot-command).
test command
------------
@@ -88,4 +88,4 @@ pdf command
The `pdf`:idx: command builds PDF versions of Nim documentation: Manual,
Tutorial and a few other documents. To run it one needs to
`install Latex/xelatex <https://www.latex-project.org/get>`_ first.
[install Latex/xelatex](https://www.latex-project.org/get) first.

278
doc/lib.md
View File

@@ -15,14 +15,14 @@ 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.
Read this `document <apis.html>`_ for a quick overview of the API design.
Read [this document](apis.html) for a quick overview of the API design.
Nimble
======
Nim's standard library only covers the basics, check
out `<https://nimble.directory/>`_ for a list of 3rd party packages.
out https://nimble.directory/ for a list of 3rd party packages.
Pure libraries
@@ -31,17 +31,17 @@ Pure libraries
Automatic imports
-----------------
* `system <system.html>`_
* [system](system.html)
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 <threads.html>`_
* [threads](threads.html)
Basic Nim thread support. **Note:** This is part of the system module. Do not
import it explicitly. Enabled with `--threads:on`:option:.
* `channels_builtin <channels_builtin.html>`_
* [channels_builtin](channels_builtin.html)
Nim message passing support for threads. **Note:** This is part of the
system module. Do not import it explicitly. Enabled with `--threads:on`:option:.
@@ -49,40 +49,40 @@ Automatic imports
Core
----
* `atomics <atomics.html>`_
* [atomics](atomics.html)
Types and operations for atomic operations and lockless algorithms.
* `bitops <bitops.html>`_
* [bitops](bitops.html)
Provides a series of low-level methods for bit manipulation.
* `cpuinfo <cpuinfo.html>`_
* [cpuinfo](cpuinfo.html)
This module implements procs to determine the number of CPUs / cores.
* `endians <endians.html>`_
* [endians](endians.html)
This module contains helpers that deal with different byte orders.
* `lenientops <lenientops.html>`_
* [lenientops](lenientops.html)
Provides binary operators for mixed integer/float expressions for convenience.
* `locks <locks.html>`_
* [locks](locks.html)
Locks and condition variables for Nim.
* `macrocache <macrocache.html>`_
* [macrocache](macrocache.html)
Provides an API for macros to collect compile-time information across modules.
* `macros <macros.html>`_
* [macros](macros.html)
Contains the AST API and documentation of Nim for writing macros.
* `rlocks <rlocks.html>`_
* [rlocks](rlocks.html)
Reentrant locks for Nim.
* `typeinfo <typeinfo.html>`_
* [typeinfo](typeinfo.html)
Provides (unsafe) access to Nim's run-time type information.
* `typetraits <typetraits.html>`_
* [typetraits](typetraits.html)
This module defines compile-time reflection procs for working with types.
* `volatile <volatile.html>`_
* [volatile](volatile.html)
This module contains code for generating volatile loads and stores,
which are useful in embedded and systems programming.
@@ -90,169 +90,169 @@ Core
Algorithms
----------
* `algorithm <algorithm.html>`_
* [algorithm](algorithm.html)
This module implements some common generic algorithms like sort or binary search.
* `enumutils <enumutils.html>`_
* [enumutils](enumutils.html)
This module adds functionality for the built-in `enum` type.
* `sequtils <sequtils.html>`_
* [sequtils](sequtils.html)
This module implements operations for the built-in `seq` type
which were inspired by functional programming languages.
* `setutils <setutils.html>`_
* [setutils](setutils.html)
This module adds functionality for the built-in `set` type.
Collections
-----------
* `critbits <critbits.html>`_
* [critbits](critbits.html)
This module implements a *crit bit tree* which is an efficient
container for a sorted set of strings, or a sorted mapping of strings.
* `deques <deques.html>`_
* [deques](deques.html)
Implementation of a double-ended queue.
The underlying implementation uses a `seq`.
* `heapqueue <heapqueue.html>`_
* [heapqueue](heapqueue.html)
Implementation of a binary heap data structure that can be used as a priority queue.
* `intsets <intsets.html>`_
* [intsets](intsets.html)
Efficient implementation of a set of ints as a sparse bit set.
* `lists <lists.html>`_
* [lists](lists.html)
Nim linked list support. Contains singly and doubly linked lists and
circular lists ("rings").
* `options <options.html>`_
* [options](options.html)
The option type encapsulates an optional value.
* `packedsets <packedsets.html>`_
* [packedsets](packedsets.html)
Efficient implementation of a set of ordinals as a sparse bit set.
* `sets <sets.html>`_
* [sets](sets.html)
Nim hash set support.
* `tables <tables.html>`_
* [tables](tables.html)
Nim hash table support. Contains tables, ordered tables, and count tables.
String handling
---------------
* `cstrutils <cstrutils.html>`_
* [cstrutils](cstrutils.html)
Utilities for `cstring` handling.
* `editdistance <editdistance.html>`_
* [editdistance](editdistance.html)
This module contains an algorithm to compute the edit distance between two
Unicode strings.
* `encodings <encodings.html>`_
* [encodings](encodings.html)
Converts between different character encodings. On UNIX, this uses
the `iconv` library, on Windows the Windows API.
* `parseutils <parseutils.html>`_
* [parseutils](parseutils.html)
This module contains helpers for parsing tokens, numbers, identifiers, etc.
* `pegs <pegs.html>`_
* [pegs](pegs.html)
This module contains procedures and operators for handling PEGs.
* `punycode <punycode.html>`_
* [punycode](punycode.html)
Implements a representation of Unicode with the limited ASCII character subset.
* `ropes <ropes.html>`_
* [ropes](ropes.html)
This module contains support for a *rope* data type.
Ropes can represent very long strings efficiently;
in particular, concatenation is done in O(1) instead of O(n).
* `strbasics <strbasics.html>`_
* [strbasics](strbasics.html)
This module provides some high performance string operations.
* `strformat <strformat.html>`_
* [strformat](strformat.html)
Macro based standard string interpolation/formatting. Inspired by
Python's f-strings.
* `strmisc <strmisc.html>`_
* [strmisc](strmisc.html)
This module contains uncommon string handling operations that do not
fit with the commonly used operations in strutils.
* `strscans <strscans.html>`_
* [strscans](strscans.html)
This module contains a `scanf` macro for convenient parsing of mini languages.
* `strtabs <strtabs.html>`_
* [strtabs](strtabs.html)
The `strtabs` module implements an efficient hash table that is a mapping
from strings to strings. Supports a case-sensitive, case-insensitive and
style-insensitive modes.
* `strutils <strutils.html>`_
* [strutils](strutils.html)
This module contains common string handling operations like changing
case of a string, splitting a string into substrings, searching for
substrings, replacing substrings.
* `unicode <unicode.html>`_
* [unicode](unicode.html)
This module provides support to handle the Unicode UTF-8 encoding.
* `unidecode <unidecode.html>`_
* [unidecode](unidecode.html)
It provides a single proc that does Unicode to ASCII transliterations.
Based on Python's Unidecode module.
* `wordwrap <wordwrap.html>`_
* [wordwrap](wordwrap.html)
This module contains an algorithm to wordwrap a Unicode string.
Time handling
-------------
* `monotimes <monotimes.html>`_
* [monotimes](monotimes.html)
The `monotimes` module implements monotonic timestamps.
* `times <times.html>`_
* [times](times.html)
The `times` module contains support for working with time.
Generic Operating System Services
---------------------------------
* `distros <distros.html>`_
* [distros](distros.html)
This module implements the basics for OS distribution ("distro") detection
and the OS's native package manager.
Its primary purpose is to produce output for Nimble packages,
but it also contains the widely used **Distribution** enum
that is useful for writing platform-specific code.
See `packaging <packaging.html>`_ for hints on distributing Nim using OS packages.
See [packaging](packaging.html) for hints on distributing Nim using OS packages.
* `dynlib <dynlib.html>`_
* [dynlib](dynlib.html)
This module implements the ability to access symbols from shared libraries.
* `marshal <marshal.html>`_
* [marshal](marshal.html)
Contains procs for serialization and deserialization of arbitrary Nim
data structures.
* `memfiles <memfiles.html>`_
* [memfiles](memfiles.html)
This module provides support for memory-mapped files (Posix's `mmap`)
on the different operating systems.
* `os <os.html>`_
* [os](os.html)
Basic operating system facilities like retrieving environment variables,
reading command line arguments, working with directories, running shell
commands, etc.
* `osproc <osproc.html>`_
* [osproc](osproc.html)
Module for process communication beyond `os.execShellCmd`.
* `streams <streams.html>`_
* [streams](streams.html)
This module provides a stream interface and two implementations thereof:
the `FileStream` and the `StringStream` which implement the stream
interface for Nim file objects (`File`) and strings. Other modules
may provide other implementations for this standard stream interface.
* `terminal <terminal.html>`_
* [terminal](terminal.html)
This module contains a few procedures to control the *terminal*
(also called *console*). The implementation simply uses ANSI escape
sequences and does not depend on any other module.
* `tempfiles <tempfiles.html>`_
* [tempfiles](tempfiles.html)
This module provides some utils to generate temporary path names and
create temporary files and directories.
@@ -260,131 +260,131 @@ Generic Operating System Services
Math libraries
--------------
* `complex <complex.html>`_
* [complex](complex.html)
This module implements complex numbers and relevant mathematical operations.
* `fenv <fenv.html>`_
* [fenv](fenv.html)
Floating-point environment. Handling of floating-point rounding and
exceptions (overflow, zero-divide, etc.).
* `math <math.html>`_
* [math](math.html)
Mathematical operations like cosine, square root.
* `random <random.html>`_
* [random](random.html)
Fast and tiny random number generator.
* `rationals <rationals.html>`_
* [rationals](rationals.html)
This module implements rational numbers and relevant mathematical operations.
* `stats <stats.html>`_
* [stats](stats.html)
Statistical analysis.
* `sums <sums.html>`_
* [sums](sums.html)
Accurate summation functions.
* `sysrand <sysrand.html>`_
* [sysrand](sysrand.html)
Cryptographically secure pseudorandom number generator.
Internet Protocols and Support
------------------------------
* `asyncdispatch <asyncdispatch.html>`_
* [asyncdispatch](asyncdispatch.html)
This module implements an asynchronous dispatcher for IO operations.
* `asyncfile <asyncfile.html>`_
* [asyncfile](asyncfile.html)
This module implements asynchronous file reading and writing using
`asyncdispatch`.
* `asyncftpclient <asyncftpclient.html>`_
This module implements an asynchronous FTP client using the `asyncnet`
* `asyncftpclient](asyncftpclient.html)
[his module implements an asynchronous FTP client using the `asyncnet`
module.
* `asynchttpserver <asynchttpserver.html>`_
This module implements an asynchronous HTTP server using the `asyncnet`
* `asynchttpserver](asynchttpserver.html)
[his module implements an asynchronous HTTP server using the `asyncnet`
module.
* `asyncnet <asyncnet.html>`_
* [asyncnet](asyncnet.html)
This module implements asynchronous sockets based on the `asyncdispatch`
module.
* `asyncstreams <asyncstreams.html>`_
* [asyncstreams](asyncstreams.html)
This module provides `FutureStream` - a future that acts as a queue.
* `cgi <cgi.html>`_
* [cgi](cgi.html)
This module implements helpers for CGI applications.
* `cookies <cookies.html>`_
* [cookies](cookies.html)
This module contains helper procs for parsing and generating cookies.
* `httpclient <httpclient.html>`_
* [httpclient](httpclient.html)
This module implements a simple HTTP client which supports both synchronous
and asynchronous retrieval of web pages.
* `mimetypes <mimetypes.html>`_
* [mimetypes](mimetypes.html)
This module implements a mimetypes database.
* `nativesockets <nativesockets.html>`_
* [nativesockets](nativesockets.html)
This module implements a low-level sockets API.
* `net <net.html>`_
* [net](net.html)
This module implements a high-level sockets API. It replaces the
`sockets` module.
* `selectors <selectors.html>`_
* [selectors](selectors.html)
This module implements a selector API with backends specific to each OS.
Currently, epoll on Linux and select on other operating systems.
* `smtp <smtp.html>`_
* [smtp](smtp.html)
This module implements a simple SMTP client.
* `uri <uri.html>`_
* [uri](uri.html)
This module provides functions for working with URIs.
Threading
---------
* `threadpool <threadpool.html>`_
Implements Nim's `spawn <manual_experimental.html#parallel-amp-spawn>`_.
* [threadpool](threadpool.html)
Implements Nim's [spawn](manual_experimental.html#parallel-amp-spawn).
Parsers
-------
* `htmlparser <htmlparser.html>`_
* [htmlparser](htmlparser.html)
This module parses an HTML document and creates its XML tree representation.
* `json <json.html>`_
* [json](json.html)
High-performance JSON parser.
* `jsonutils <jsonutils.html>`_
* [jsonutils](jsonutils.html)
This module implements a hookable (de)serialization for arbitrary types.
* `lexbase <lexbase.html>`_
* [lexbase](lexbase.html)
This is a low-level module that implements an extremely efficient buffering
scheme for lexers and parsers. This is used by the diverse parsing modules.
* `parsecfg <parsecfg.html>`_
* [parsecfg](parsecfg.html)
The `parsecfg` module implements a high-performance configuration file
parser. The configuration file's syntax is similar to the Windows ``.ini``
format, but much more powerful, as it is not a line based parser. String
literals, raw string literals, and triple quote string literals are supported
as in the Nim programming language.
* `parsecsv <parsecsv.html>`_
* [parsecsv](parsecsv.html)
The `parsecsv` module implements a simple high-performance CSV parser.
* `parsejson <parsejson.html>`_
This module implements a JSON parser. It is used and exported by the `json <json.html>`_ module, but can also be used in its own right.
* [parsejson](parsejson.html)
This module implements a JSON parser. It is used and exported by the [json](json.html) module, but can also be used in its own right.
* `parseopt <parseopt.html>`_
* [parseopt](parseopt.html)
The `parseopt` module implements a command line option parser.
* `parsesql <parsesql.html>`_
* [parsesql](parsesql.html)
The `parsesql` module implements a simple high-performance SQL parser.
* `parsexml <parsexml.html>`_
* [parsexml](parsexml.html)
The `parsexml` module implements a simple high performance XML/HTML parser.
The only encoding that is supported is UTF-8. The parser has been designed
to be somewhat error-correcting, so that even some "wild HTML" found on the
@@ -394,37 +394,37 @@ Parsers
Docutils
--------
* `packages/docutils/highlite <highlite.html>`_
* [packages/docutils/highlite](highlite.html)
Source highlighter for programming or markup languages. Currently,
only a few languages are supported, other languages may be added.
The interface supports one language nested in another.
* `packages/docutils/rst <rst.html>`_
* [packages/docutils/rst](rst.html)
This module implements a reStructuredText parser. A large subset
is implemented. Some features of the markdown wiki syntax are also supported.
* `packages/docutils/rstast <rstast.html>`_
* [packages/docutils/rstast](rstast.html)
This module implements an AST for the reStructuredText parser.
* `packages/docutils/rstgen <rstgen.html>`_
* [packages/docutils/rstgen](rstgen.html)
This module implements a generator of HTML/Latex from reStructuredText.
XML Processing
--------------
* `xmltree <xmltree.html>`_
* [xmltree](xmltree.html)
A simple XML tree. More efficient and simpler than the DOM. It also
contains a macro for XML/HTML code generation.
* `xmlparser <xmlparser.html>`_
* [xmlparser](xmlparser.html)
This module parses an XML document and creates its XML tree representation.
Generators
----------
* `htmlgen <htmlgen.html>`_
* [htmlgen](htmlgen.html)
This module implements a simple XML and HTML code
generator. Each commonly used HTML tag has a corresponding macro
that generates a string with its HTML representation.
@@ -433,81 +433,81 @@ Generators
Hashing
-------
* `base64 <base64.html>`_
* [base64](base64.html)
This module implements a Base64 encoder and decoder.
* `hashes <hashes.html>`_
* [hashes](hashes.html)
This module implements efficient computations of hash values for diverse
Nim types.
* `md5 <md5.html>`_
* [md5](md5.html)
This module implements the MD5 checksum algorithm.
* `oids <oids.html>`_
* [oids](oids.html)
An OID is a global ID that consists of a timestamp,
a unique counter, and a random value. This combination should suffice to
produce a globally distributed unique ID. This implementation was extracted
from the MongoDB interface and it thus binary compatible with a MongoDB OID.
* `sha1 <sha1.html>`_
* [sha1](sha1.html)
This module implements the SHA-1 checksum algorithm.
Miscellaneous
-------------
* `browsers <browsers.html>`_
* [browsers](browsers.html)
This module implements procs for opening URLs with the user's default
browser.
* `colors <colors.html>`_
* [colors](colors.html)
This module implements color handling for Nim.
* `coro <coro.html>`_
* [coro](coro.html)
This module implements experimental coroutines in Nim.
* `enumerate <enumerate.html>`_
* [enumerate](enumerate.html)
This module implements `enumerate` syntactic sugar based on Nim's macro system.
* `logging <logging.html>`_
* [logging](logging.html)
This module implements a simple logger.
* `segfaults <segfaults.html>`_
* [segfaults](segfaults.html)
Turns access violations or segfaults into a `NilAccessDefect` exception.
* `sugar <sugar.html>`_
* [sugar](sugar.html)
This module implements nice syntactic sugar based on Nim's macro system.
* `unittest <unittest.html>`_
* [unittest](unittest.html)
Implements a Unit testing DSL.
* `varints <varints.html>`_
* [varints](varints.html)
Decode variable-length integers that are compatible with SQLite.
* `with <with.html>`_
* [with](with.html)
This module implements the `with` macro for easy function chaining.
Modules for the JS backend
--------------------------
* `asyncjs <asyncjs.html>`_
* [asyncjs](asyncjs.html)
Types and macros for writing asynchronous procedures in JavaScript.
* `dom <dom.html>`_
* [dom](dom.html)
Declaration of the Document Object Model for the JS backend.
* `jsbigints <jsbigints.html>`_
* [jsbigints](jsbigints.html)
Arbitrary precision integers.
* `jsconsole <jsconsole.html>`_
* [jsconsole](jsconsole.html)
Wrapper for the `console` object.
* `jscore <jscore.html>`_
* [jscore](jscore.html)
The wrapper of core JavaScript functions. For most purposes, you should be using
the `math`, `json`, and `times` stdlib modules instead of this module.
* `jsffi <jsffi.html>`_
* [jsffi](jsffi.html)
Types and macros for easier interaction with JavaScript.
@@ -517,7 +517,7 @@ Impure libraries
Regular expressions
-------------------
* `re <re.html>`_
* [re](re.html)
This module contains procedures and operators for handling regular
expressions. The current implementation uses PCRE.
@@ -525,15 +525,15 @@ Regular expressions
Database support
----------------
* `db_postgres <db_postgres.html>`_
* [db_postgres](db_postgres.html)
A higher level PostgreSQL database wrapper. The same interface is implemented
for other databases too.
* `db_mysql <db_mysql.html>`_
* [db_mysql](db_mysql.html)
A higher level MySQL database wrapper. The same interface is implemented
for other databases too.
* `db_sqlite <db_sqlite.html>`_
* [db_sqlite](db_sqlite.html)
A higher level SQLite database wrapper. The same interface is implemented
for other databases too.
@@ -541,7 +541,7 @@ Database support
Generic Operating System Services
---------------------------------
* `rdstdin <rdstdin.html>`_
* [rdstdin](rdstdin.html)
This module contains code for reading from stdin.
@@ -555,43 +555,43 @@ not contained in the distribution. You can then find them on the website.
Windows-specific
----------------
* `winlean <winlean.html>`_
* [winlean](winlean.html)
Contains a wrapper for a small subset of the Win32 API.
* `registry <registry.html>`_
* [registry](registry.html)
Windows registry support.
UNIX specific
-------------
* `posix <posix.html>`_
* [posix](posix.html)
Contains a wrapper for the POSIX standard.
* `posix_utils <posix_utils.html>`_
* [posix_utils](posix_utils.html)
Contains helpers for the POSIX standard or specialized for Linux and BSDs.
Regular expressions
-------------------
* `pcre <pcre.html>`_
* [pcre](pcre.html)
Wrapper for the PCRE library.
Database support
----------------
* `postgres <postgres.html>`_
* [postgres](postgres.html)
Contains a wrapper for the PostgreSQL API.
* `mysql <mysql.html>`_
* [mysql](mysql.html)
Contains a wrapper for the mySQL API.
* `sqlite3 <sqlite3.html>`_
* [sqlite3](sqlite3.html)
Contains a wrapper for the SQLite 3 API.
* `odbcsql <odbcsql.html>`_
* [odbcsql](odbcsql.html)
interface to the ODBC driver.
Network Programming and Internet Protocols
------------------------------------------
* `openssl <openssl.html>`_
* [openssl](openssl.html)
Wrapper for OpenSSL.

10
doc/mm.md
View File

@@ -35,7 +35,7 @@ the involved heap sizes.
The reference counting operations (= "RC ops") do not use atomic instructions and do not have to --
instead entire subgraphs are *moved* between threads. The Nim compiler also aggressively
optimizes away RC ops and exploits `move semantics <destructors.html#move-semantics>`_.
optimizes away RC ops and exploits [move semantics](destructors.html#move-semantics).
Nim performs a fair share of optimizations for ARC/ORC; you can inspect what it did
to your time critical function via `--expandArc:functionName`.
@@ -62,7 +62,7 @@ Other MM modes
--mm:refc This is the default memory management strategy. It's a
deferred reference counting based garbage collector
with a simple Mark&Sweep backup GC in order to collect cycles. Heaps are thread-local.
`This document <refc.html>`_ contains further information.
[This document](refc.html) contains further information.
--mm:markAndSweep Simple Mark-And-Sweep based garbage collector.
Heaps are thread-local.
--mm:boehm Boehm based garbage collector, it offers a shared heap.
@@ -89,7 +89,7 @@ None Manual Manual Manual `--mm:none`
.. default-role:: code
.. include:: rstcommon.rst
JavaScript's garbage collector is used for the `JavaScript and NodeJS
<backends.html#backends-the-javascript-target>`_ compilation targets.
The `NimScript <nims.html>`_ target uses the memory management strategy built into
JavaScript's garbage collector is used for the [JavaScript and NodeJS](
backends.html#backends-the-javascript-target) compilation targets.
The [NimScript](nims.html) target uses the memory management strategy built into
the Nim compiler.

2
doc/nep1.md
View File

@@ -21,7 +21,7 @@ library should follow.
Note that there can be exceptions to these rules. Nim being as flexible as it
is, there will be parts of this style guide that don't make sense in certain
contexts. Furthermore, just as
`Python's style guide<http://legacy.python.org/dev/peps/pep-0008/>`_ changes
[Python's style guide](http://legacy.python.org/dev/peps/pep-0008/) changes
over time, this style guide will too.
These rules will only be enforced for contributions to the Nim

50
doc/nimc.md
View File

@@ -21,10 +21,10 @@ Introduction
This document describes the usage of the *Nim compiler*
on the different supported platforms. It is not a definition of the Nim
programming language (which is covered in the `manual <manual.html>`_).
programming language (which is covered in the [manual](manual.html)).
Nim is free software; it is licensed under the
`MIT License <http://www.opensource.org/licenses/mit-license.php>`_.
[MIT License](http://www.opensource.org/licenses/mit-license.php).
Compiler Usage
@@ -130,13 +130,13 @@ Level Description
===== ============================================
0 Minimal output level for the compiler.
1 Displays compilation of all the compiled files, including those imported
by other modules or through the `compile pragma
<manual.html#implementation-specific-pragmas-compile-pragma>`_.
by other modules or through the [compile pragma](
manual.html#implementation-specific-pragmas-compile-pragma).
This is the default level.
2 Displays compilation statistics, enumerates the dynamic
libraries that will be loaded by the final binary, and dumps to
standard output the result of applying `a filter to the source code
<filters.html>`_ if any filter was used during compilation.
standard output the result of applying [a filter to the source code](
filters.html) if any filter was used during compilation.
3 In addition to the previous levels dumps a debug stack trace
for compiler developers.
===== ============================================
@@ -147,16 +147,16 @@ Compile-time symbols
Through the `-d:x`:option: or `--define:x`:option: switch you can define compile-time
symbols for conditional compilation. The defined switches can be checked in
source code with the `when statement
<manual.html#statements-and-expressions-when-statement>`_ and
`defined proc <system.html#defined,untyped>`_. The typical use of this switch is
source code with the [when statement](
manual.html#statements-and-expressions-when-statement) and
[defined proc](system.html#defined,untyped). The typical use of this switch is
to enable builds in release mode (`-d:release`:option:) where optimizations are
enabled for better performance. Another common use is the `-d:ssl`:option: switch to
activate SSL sockets.
Additionally, you may pass a value along with the symbol: `-d:x=y`:option:
which may be used in conjunction with the `compile-time define
pragmas<manual.html#implementation-specific-pragmas-compileminustime-define-pragmas>`_
which may be used in conjunction with the [compile-time define
pragmas](manual.html#implementation-specific-pragmas-compileminustime-define-pragmas)
to override symbols during build time.
Compile-time symbols are completely **case insensitive** and underscores are
@@ -268,7 +268,7 @@ The `_r` suffix is used for release builds, `_d` is for debug builds.
This makes it easy to delete all generated files.
The `--nimcache`:option:
`compiler switch <#compiler-usage-commandminusline-switches>`_ can be used to
[compiler switch][command-line switches] can be used to
to change the ``nimcache`` directory.
However, the generated C code is not platform-independent. C code generated for
@@ -355,7 +355,7 @@ There are two ways to compile for Android: terminal programs (Termux) and with
the NDK (Android Native Development Kit).
The first one is to treat Android as a simple Linux and use
`Termux <https://wiki.termux.com>`_ to connect and run the Nim compiler
[Termux](https://wiki.termux.com) to connect and run the Nim compiler
directly on android as if it was Linux. These programs are console-only
programs that can't be distributed in the Play Store.
@@ -363,8 +363,8 @@ Use regular `nim c`:cmd: inside termux to make Android terminal programs.
Normal Android apps are written in Java, to use Nim inside an Android app
you need a small Java stub that calls out to a native library written in
Nim using the `NDK <https://developer.android.com/ndk>`_. You can also use
`native-activity <https://developer.android.com/ndk/samples/sample_na>`_
Nim using the [NDK](https://developer.android.com/ndk). You can also use
[native-activity](https://developer.android.com/ndk/samples/sample_na)
to have the Java stub be auto-generated for you.
Use `nim c -c --cpu:arm --os:android -d:androidNDK --noMain:on`:cmd: to
@@ -444,8 +444,8 @@ or setup a ``nim.cfg`` file like so::
--passL="-specs=$DEVKITPRO/libnx/switch.specs -L$DEVKITPRO/libnx/lib -lnx"
The devkitPro setup must be the same as the default with their new installer
`here for Mac/Linux <https://github.com/devkitPro/pacman/releases>`_ or
`here for Windows <https://github.com/devkitPro/installer/releases>`_.
[here for Mac/Linux](https://github.com/devkitPro/pacman/releases) or
[here for Windows](https://github.com/devkitPro/installer/releases).
For example, with the above-mentioned config:
@@ -455,7 +455,7 @@ For example, with the above-mentioned config:
This will generate a file called ``switchhomebrew.elf`` which can then be turned into
an nro file with the `elf2nro`:cmd: tool in the devkitPro release. Examples can be found at
`the nim-libnx github repo <https://github.com/jyapayne/nim-libnx.git>`_.
[the nim-libnx github repo](https://github.com/jyapayne/nim-libnx.git).
There are a few things that don't work because the devkitPro libraries don't support them.
They are:
@@ -512,7 +512,7 @@ Define Effect
This only works with `--mm:none`:option:,
`--mm:arc`:option: and `--mm:orc`:option:.
`useRealtimeGC` Enables support of Nim's GC for *soft* realtime
systems. See the documentation of the `mm <mm.html>`_
systems. See the documentation of the [mm](mm.html)
for further information.
`logGC` Enable GC logging to stdout.
`nodejs` The JS target is actually ``node.js``.
@@ -591,7 +591,7 @@ The typical compiler usage involves using the `compile`:option: or `c`:option:
command to transform a ``.nim`` file into one or more ``.c`` files which are then
compiled with the platform's C compiler into a static binary. However, there
are other commands to compile to C++, Objective-C, or JavaScript. More details
can be read in the `Nim Backend Integration document <backends.html>`_.
can be read in the [Nim Backend Integration document](backends.html).
Nim documentation tools
@@ -599,13 +599,13 @@ Nim documentation tools
Nim provides the `doc`:idx: command to generate HTML
documentation from ``.nim`` source files. Only exported symbols will appear in
the output. For more details `see the docgen documentation <docgen.html>`_.
the output. For more details see [the docgen documentation](docgen.html).
Nim idetools integration
========================
Nim provides language integration with external IDEs through the
idetools command. See the documentation of `idetools <idetools.html>`_
idetools command. See the documentation of [idetools](idetools.html)
for further information.
..
@@ -666,7 +666,7 @@ The `--opt:size`:option: flag instructs Nim to optimize code generation for smal
size (with the help of the C compiler), the `-flto`:option: flags enable link-time
optimization in the compiler and linker.
Check the `Cross-compilation`_ section for instructions on how to compile the
Check the [Cross-compilation] section for instructions on how to compile the
program for your target.
@@ -717,8 +717,8 @@ Currently only Zephyr and FreeRTOS support these configurations.
Nim for realtime systems
========================
See the `--mm:arc` or `--mm:orc` memory management settings in `MM <mm.html>`_ for further
information.
See the `--mm:arc` or `--mm:orc` memory management settings in
[MM](mm.html) for further information.
Signal handling in Nim

4
doc/niminst.md
View File

@@ -14,7 +14,7 @@ Introduction
niminst is a tool to generate an installer for a Nim program. Currently
it can create an installer for Windows
via `Inno Setup <http://www.jrsoftware.org/isinfo.php>`_ as well as
via [Inno Setup](http://www.jrsoftware.org/isinfo.php) as well as
installation/deinstallation scripts for UNIX. Later versions will support
Linux' package management systems.
@@ -26,7 +26,7 @@ systems.
Configuration file
==================
niminst uses the Nim `parsecfg <parsecfg.html>`_ module to parse the
niminst uses the Nim [parsecfg](parsecfg.html) module to parse the
configuration file. Here's an example of how the syntax looks like:
.. include:: mytest.cfg

101
doc/nims.md
View File

@@ -29,7 +29,7 @@ previous settings):
``$project.nim``. This file can be skipped with the same
`--skipProjCfg`:option: command line option.
For available procs and implementation details see `nimscript <nimscript.html>`_.
For available procs and implementation details see [nimscript](nimscript.html).
Limitations
@@ -61,52 +61,53 @@ Standard library modules
At least the following standard library modules are available:
* `macros <macros.html>`_
* `os <os.html>`_
* `strutils <strutils.html>`_
* `math <math.html>`_
* `distros <distros.html>`_
* `sugar <sugar.html>`_
* `algorithm <algorithm.html>`_
* `base64 <base64.html>`_
* `bitops <bitops.html>`_
* `chains <chains.html>`_
* `colors <colors.html>`_
* `complex <complex.html>`_
* `htmlgen <htmlgen.html>`_
* `httpcore <httpcore.html>`_
* `lenientops <lenientops.html>`_
* `mersenne <mersenne.html>`_
* `options <options.html>`_
* `parseutils <parseutils.html>`_
* `punycode <punycode.html>`_
* `random <punycode.html>`_
* `stats <stats.html>`_
* `strformat <strformat.html>`_
* `strmisc <strmisc.html>`_
* `strscans <strscans.html>`_
* `unicode <unicode.html>`_
* `uri <uri.html>`_
* `std/editdistance <editdistance.html>`_
* `std/wordwrap <wordwrap.html>`_
* `std/sums <sums.html>`_
* `parsecsv <parsecsv.html>`_
* `parsecfg <parsecfg.html>`_
* `parsesql <parsesql.html>`_
* `xmlparser <xmlparser.html>`_
* `htmlparser <htmlparser.html>`_
* `ropes <ropes.html>`_
* `json <json.html>`_
* `parsejson <parsejson.html>`_
* `strtabs <strtabs.html>`_
* `unidecode <unidecode.html>`_
* [macros](macros.html)
* [os](os.html)
* [strutils](strutils.html)
* [math](math.html)
* [distros](distros.html)
* [sugar](sugar.html)
* [algorithm](algorithm.html)
* [base64](base64.html)
* [bitops](bitops.html)
* [chains](chains.html)
* [colors](colors.html)
* [complex](complex.html)
* [htmlgen](htmlgen.html)
* [httpcore](httpcore.html)
* [lenientops](lenientops.html)
* [mersenne](mersenne.html)
* [options](options.html)
* [parseutils](parseutils.html)
* [punycode](punycode.html)
* [random](punycode.html)
* [stats](stats.html)
* [strformat](strformat.html)
* [strmisc](strmisc.html)
* [strscans](strscans.html)
* [unicode](unicode.html)
* [uri](uri.html)
* [std/editdistance](editdistance.html)
* [std/wordwrap](wordwrap.html)
* [std/sums](sums.html)
* [parsecsv](parsecsv.html)
* [parsecfg](parsecfg.html)
* [parsesql](parsesql.html)
* [xmlparser](xmlparser.html)
* [htmlparser](htmlparser.html)
* [ropes](ropes.html)
* [json](json.html)
* [parsejson](parsejson.html)
* [strtabs](strtabs.html)
* [unidecode](unidecode.html)
In addition to the standard Nim syntax (`system <system.html>`_ module),
In addition to the standard Nim syntax ([system](system.html) module),
NimScripts support the procs and templates defined in the
`nimscript <nimscript.html>`_ module too.
[nimscript](nimscript.html) module too.
See also:
* `Check the tests for more information about modules compatible with NimScript. <https://github.com/nim-lang/Nim/blob/devel/tests/test_nimscript.nims>`_
* [Check the tests for more information about modules compatible with NimScript](
https://github.com/nim-lang/Nim/blob/devel/tests/test_nimscript.nims)
NimScript as a configuration file
@@ -169,14 +170,14 @@ Task Description
========= ===================================================
Look at the module `distros <distros.html>`_ for some support of the
Look at the module [distros](distros.html) for some support of the
OS's native package managers.
Nimble integration
==================
See the `Nimble readme <https://github.com/nim-lang/nimble#readme>`_
See the [Nimble readme](https://github.com/nim-lang/nimble#readme)
for more information.
@@ -297,7 +298,7 @@ translations.cfg
```
* `Nimterlingua <https://nimble.directory/pkg/nimterlingua>`_
* [Nimterlingua](https://nimble.directory/pkg/nimterlingua)
Graceful Fallback
@@ -329,14 +330,15 @@ Evolving Scripting language
---------------------------
NimScript evolves together with Nim,
`occasionally new features might become available on NimScript <https://github.com/nim-lang/Nim/pulls?utf8=%E2%9C%93&q=nimscript>`_ ,
[occasionally new features might become available on NimScript](
https://github.com/nim-lang/Nim/pulls?utf8=%E2%9C%93&q=nimscript),
adapted from compiled Nim or added as new features on both.
Scripting Language with a Package Manager
-----------------------------------------
You can create your own modules to be compatible with NimScript,
and check `Nimble <https://nimble.directory>`_
and check [Nimble](https://nimble.directory)
to search for third party modules that may work on NimScript.
DevOps Scripting
@@ -345,4 +347,5 @@ DevOps Scripting
You can use NimScript to deploy to production, run tests, build projects, do benchmarks,
generate documentation, and all kinds of DevOps/SysAdmin specific tasks.
* `An example of a third party NimScript that can be used as a project-agnostic tool. <https://github.com/kaushalmodi/nim_config#list-available-tasks>`_
* [An example of a third party NimScript that can be used as a project-agnostic
tool.](https://github.com/kaushalmodi/nim_config#list-available-tasks)

8
doc/nimsuggest.md
View File

@@ -20,7 +20,7 @@ definition of symbols or suggestions for completion.
This document will guide you through the available options. If you
want to look at practical examples of nimsuggest support you can look
at the
`various editor integrations <https://github.com/Araq/Nim/wiki/Editor-Support>`_
[various editor integrations](https://github.com/Araq/Nim/wiki/Editor-Support)
already available.
@@ -49,7 +49,7 @@ via sockets is more reasonable so that is the default. It listens to port 6000
by default.
Nimsuggest is basically a frontend for the nim compiler so `--path`:option: flags and
`config files <https://nim-lang.org/docs/nimc.html#compiler-usage-configuration-files>`_
[config files](https://nim-lang.org/docs/nimc.html#compiler-usage-configuration-files)
can be used to specify additional dependencies like
`nimsuggest --stdin --debug --path:"dependencies" myproject.nim`:cmd:.
@@ -113,8 +113,8 @@ The `sug` Nimsuggest command performs a query about possible
completion symbols at some point in the file.
The typical usage scenario for this option is to call it after the
user has typed the dot character for `the object oriented call
syntax <tut2.html#object-oriented-programming-method-call-syntax>`_.
user has typed the dot character for [the object oriented call
syntax](tut2.html#object-oriented-programming-method-call-syntax).
Nimsuggest will try to return the suggestions sorted first by scope
(from innermost to outermost) and then by item name.

4
doc/packaging.md
View File

@@ -4,9 +4,9 @@ Packaging Nim
This page provide hints on distributing Nim using OS packages.
See `distros <distros.html>`_ for tools to detect Linux distribution at runtime.
See [distros](distros.html) for tools to detect Linux distribution at runtime.
See `here <intern.html#bootstrapping-the-compiler-reproducible-builds>`_ for how to
See [here](intern.html#bootstrapping-the-compiler-reproducible-builds) for how to
compile reproducible builds.
Supported architectures

2
doc/refc.md
View File

@@ -121,7 +121,7 @@ Keeping track of memory
If you need to pass around memory allocated by Nim to C, you can use the
procs `GC_ref` and `GC_unref` to mark objects as referenced to avoid them
being freed by the garbage collector.
Other useful procs from `system <system.html>`_ you can use to keep track of memory are:
Other useful procs from [system](system.html) you can use to keep track of memory are:
* `getTotalMem()` Returns the amount of total memory managed by the garbage collector.
* `getOccupiedMem()` Bytes reserved by the garbage collector and used by objects.

2
doc/spawn.txt
View File

@@ -6,7 +6,7 @@ Nim has two flavors of parallelism:
1) `Structured`:idx parallelism via the ``parallel`` statement.
2) `Unstructured`:idx: parallelism via the standalone ``spawn`` statement.
Both need the `threadpool <threadpool.html>`_ module to work.
Both need the [threadpool](threadpool.html) module to work.
Somewhat confusingly, ``spawn`` is also used in the ``parallel`` statement
with slightly different semantics. ``spawn`` always takes a call expression of

23
doc/testament.md
View File

@@ -9,7 +9,7 @@
Testament is an advanced automatic unittests runner for Nim tests, is used for the development of Nim itself,
offers process isolation for your tests, it can generate statistics about test cases,
supports multiple targets (C, C++, ObjectiveC, JavaScript, etc.),
simulated `Dry-Runs <https://en.wikipedia.org/wiki/Dry_run_(testing)>`_,
simulated [Dry-Runs](https://en.wikipedia.org/wiki/Dry_run_(testing)),
has logging, can generate HTML reports, skip tests from a file, and more,
so can be useful to run your tests, even the most complex ones.
@@ -185,8 +185,10 @@ Example "template" **to edit** and write a Testament unittest:
* As you can see the "Spec" is just a `discard """ """`.
* Spec has sane defaults, so you don't need to provide them all, any simple assert will work just fine.
* `This is not the full spec of Testament, check the Testament Spec on GitHub, see parseSpec(). <https://github.com/nim-lang/Nim/blob/devel/testament/specs.nim#L238>`_
* `Nim itself uses Testament, so there are plenty of test examples. <https://github.com/nim-lang/Nim/tree/devel/tests>`_
* This is not the full spec of Testament, check [the Testament Spec on GitHub,
see parseSpec()](https://github.com/nim-lang/Nim/blob/devel/testament/specs.nim#L315).
* Nim itself uses Testament, so [there are plenty of test examples](
https://github.com/nim-lang/Nim/tree/devel/tests).
* Has some built-in CI compatibility, like Azure Pipelines, etc.
@@ -195,11 +197,10 @@ Inline hints, warnings and errors (notes)
Testing the line, column, kind and message of hints, warnings and errors can
be written inline like so:
.. code-block:: nim
```nim
{.warning: "warning!!"} #[tt.Warning
^ warning!! [User] ]#
```
The opening `#[tt.` marks the message line.
The `^` marks the message column.
@@ -207,18 +208,17 @@ The `^` marks the message column.
Inline messages can be combined with `nimout` when `nimoutFull` is false (default).
This allows testing for expected messages from other modules:
.. code-block:: nim
```nim
discard """
nimout: "config.nims(1, 1) Hint: some hint message [User]"
"""
{.warning: "warning!!"} #[tt.Warning
^ warning!! [User] ]#
```
Multiple messages for a line can be checked by delimiting messages with ';':
.. code-block:: nim
```nim
discard """
matrix: "--errorMax:0 --styleCheck:error"
"""
@@ -227,6 +227,7 @@ Multiple messages for a line can be checked by delimiting messages with ';':
^ 'generic_proc' should be: 'genericProc'; tt.Error
^ 'a_a' should be: 'aA' ]#
discard
```
Use `--errorMax:0` in `matrix`, or `cmd: "nim check $file"` when testing
for multiple 'Error' messages.
@@ -327,4 +328,4 @@ Tests without Spec:
See also:
* `Unittest <unittest.html>`_
* [Unittest](unittest.html)

16
doc/tools.md
View File

@@ -7,36 +7,36 @@ Tools available with Nim
The standard distribution ships with the following tools:
- | `Hot code reloading <hcr.html>`_
- | [Hot code reloading](hcr.html)
| The "Hot code reloading" feature is built into the compiler but has its own
document explaining how it works.
- | `Documentation generator <docgen.html>`_
- | [Documentation generator](docgen.html)
| The builtin document generator `nim doc`:cmd: generates HTML documentation
from ``.nim`` source files.
- | `Nimsuggest for IDE support <nimsuggest.html>`_
- | [Nimsuggest for IDE support](nimsuggest.html)
| Through the `nimsuggest`:cmd: tool, any IDE can query a ``.nim`` source file
and obtain useful information like the definition of symbols or suggestions for
completion.
- | `C2nim <https://github.com/nim-lang/c2nim/blob/master/doc/c2nim.rst>`_
- | [C2nim](https://github.com/nim-lang/c2nim/blob/master/doc/c2nim.rst)
| C to Nim source converter. Translates C header files to Nim.
- | `niminst <niminst.html>`_
- | [niminst](niminst.html)
| niminst is a tool to generate an installer for a Nim program.
- | `nimgrep <nimgrep.html>`_
- | [nimgrep](nimgrep.html)
| Nim search and replace utility.
- | nimpretty
| `nimpretty`:cmd: is a Nim source code beautifier,
to format code according to the official style guide.
- | `testament <https://nim-lang.github.io/Nim/testament.html>`_
- | [testament](https://nim-lang.github.io/Nim/testament.html)
| `testament`:cmd: is an advanced automatic *unittests runner* for Nim tests,
is used for the development of Nim itself, offers process isolation for your tests,
it can generate statistics about test cases, supports multiple targets (C, JS, etc),
`simulated Dry-Runs <https://en.wikipedia.org/wiki/Dry_run_(testing)>`_,
[simulated Dry-Runs](https://en.wikipedia.org/wiki/Dry_run_(testing)),
has logging, can generate HTML reports, skip tests from a file, and more,
so can be useful to run your tests, even the most complex ones.