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

Markdown links migration part 1 (#20319)

Browse Source 
Markdown link migration part 1

Also the warning is improved a bit.

Local links (targeting inside its document) which had had a full anchor
were turned into concise form.
The very fact that they existed may be due to the bug in
reference to subsections fixed https://github.com/nim-lang/Nim/pull/20279,
now they are working well (both in RST syntax and
new Pandoc Markdown syntax implemented in
https://github.com/nim-lang/Nim/pull/20304)
This commit is contained in:
Andrey Makarov
2022-09-09 17:45:54 +03:00
committed by GitHub
parent 89e6540fd3
commit f6ee066ee2
12 changed files with 256 additions and 240 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
doc/backends.md
View File

@@ -17,7 +17,7 @@
Introduction
============
The `Nim Compiler User Guide <nimc.html>`_ documents the typical
The [Nim Compiler User Guide](nimc.html) documents the typical
compiler invocation, 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
@@ -26,12 +26,12 @@ to compile to C++, Objective-C, or JavaScript. This document tries to
concentrate in a single place all the backend and interfacing options.
The Nim compiler supports mainly two backend families: the C, C++ and
Objective-C targets and the JavaScript target. `The C like targets
<#backends-the-c-like-targets>`_ creates source files that can be compiled
into a library or a final executable. `The JavaScript target
<#backends-the-javascript-target>`_ can generate a ``.js`` file which you
reference from an HTML file or create a `standalone Node.js program
<http://nodejs.org>`_.
Objective-C targets and the JavaScript target. [The C like targets](
#backends-the-c-like-targets) creates source files that can be compiled
into a library or a final executable. [The JavaScript target](
#backends-the-javascript-target) can generate a ``.js`` file which you
reference from an HTML file or create a [standalone Node.js program](
http://nodejs.org).
On top of generating libraries or standalone applications, Nim offers
bidirectional interfacing with the backend targets through generic and
@@ -64,8 +64,8 @@ line invocations:
```
The compiler commands select the target backend, but if needed you can
`specify additional switches for cross-compilation
<nimc.html#crossminuscompilation>`_ to select the target CPU, operative system
[specify additional switches for cross-compilation](
nimc.html#crossminuscompilation) to select the target CPU, operative system
or compiler/linker commands.
@@ -89,15 +89,15 @@ available. This includes:
* some modules of the standard library
* proper 64-bit integer arithmetic
To compensate, the standard library has modules `catered to the JS backend
<lib.html#pure-libraries-modules-for-js-backend>`_
To compensate, the standard library has modules [catered to the JS backend](
lib.html#pure-libraries-modules-for-js-backend)
and more support will come in the future (for instance, Node.js bindings
to get OS info).
To compile a Nim module into a ``.js`` file use the `js`:option: command; the
default is a ``.js`` file that is supposed to be referenced in an ``.html``
file. However, you can also run the code with `nodejs`:idx:
(`<http://nodejs.org>`_):
(http://nodejs.org):
```cmd
nim js -d:nodejs -r examples/hallo.nim
@@ -120,14 +120,14 @@ component?).
Nim code calling the backend
----------------------------
Nim code can interface with the backend through the `Foreign function
interface <manual.html#foreign-function-interface>`_ mainly through the
`importc pragma <manual.html#foreign-function-interface-importc-pragma>`_.
Nim code can interface with the backend through the [Foreign function
interface](manual.html#foreign-function-interface) mainly through the
[importc pragma](manual.html#foreign-function-interface-importc-pragma).
The `importc` pragma is the *generic* way of making backend symbols available
in Nim and is available in all the target backends (JavaScript too). The C++
or Objective-C backends have their respective `ImportCpp
<manual.html#implementation-specific-pragmas-importcpp-pragma>`_ and
`ImportObjC <manual.html#implementation-specific-pragmas-importobjc-pragma>`_
or Objective-C backends have their respective [ImportCpp](
manual.html#implementation-specific-pragmas-importcpp-pragma) and
[ImportObjC](manual.html#implementation-specific-pragmas-importobjc-pragma)
pragmas to call methods from classes.
Whenever you use any of these pragmas you need to integrate native code into
@@ -139,19 +139,20 @@ However, for the C like targets you need to link external code either
statically or dynamically. The preferred way of integrating native code is to
use dynamic linking because it allows you to compile Nim programs without
the need for having the related development libraries installed. This is done
through the `dynlib pragma for import
<manual.html#foreign-function-interface-dynlib-pragma-for-import>`_, though
more specific control can be gained using the `dynlib module <dynlib.html>`_.
through the [dynlib pragma for import](
manual.html#foreign-function-interface-dynlib-pragma-for-import), though
more specific control can be gained using the [dynlib module](dynlib.html).
The `dynlibOverride <nimc.html#dynliboverride>`_ command line switch allows
The [dynlibOverride](nimc.html#dynliboverride) command line switch allows
to avoid dynamic linking if you need to statically link something instead.
Nim wrappers designed to statically link source files can use the `compile
pragma <manual.html#implementation-specific-pragmas-compile-pragma>`_ if
Nim wrappers designed to statically link source files can use the [compile
pragma](manual.html#implementation-specific-pragmas-compile-pragma) if
there are few sources or providing them along the Nim code is easier than using
a system library. Libraries installed on the host system can be linked in with
the `PassL pragma <manual.html#implementation-specific-pragmas-passl-pragma>`_.
the [PassL pragma](manual.html#implementation-specific-pragmas-passl-pragma).
To wrap native code, take a look at the `c2nim tool <https://github.com/nim-lang/c2nim/blob/master/doc/c2nim.rst>`_ which helps
To wrap native code, take a look at the [c2nim tool](
https://github.com/nim-lang/c2nim/blob/master/doc/c2nim.rst) which helps
with the process of scanning and transforming header files into a Nim
interface.
@@ -223,16 +224,16 @@ from the previous section):
Compile the Nim code to JavaScript with `nim js -o:calculator.js
calculator.nim`:cmd: and open ``host.html`` in a browser. If the browser supports
javascript, you should see the value `10` in the browser's console. Use the
`dom module <dom.html>`_ for specific DOM querying and modification procs
or take a look at `karax <https://github.com/pragmagic/karax>`_ for how to
[dom module](dom.html) for specific DOM querying and modification procs
or take a look at [karax](https://github.com/pragmagic/karax) for how to
develop browser-based applications.
Backend code calling Nim
------------------------
Backend code can interface with Nim code exposed through the `exportc
pragma <manual.html#foreign-function-interface-exportc-pragma>`_. The
Backend code can interface with Nim code exposed through the [exportc
pragma](manual.html#foreign-function-interface-exportc-pragma). The
`exportc` pragma is the *generic* way of making Nim symbols available to
the backends. By default, the Nim compiler will mangle all the Nim symbols to
avoid any name collision, so the most significant thing the `exportc` pragma
@@ -347,8 +348,8 @@ Nimcache naming logic
The `nimcache`:idx: directory is generated during compilation and will hold
either temporary or final files depending on your backend target. The default
name for the directory depends on the used backend and on your OS but you can
use the `--nimcache`:option: `compiler switch
<nimc.html#compiler-usage-commandminusline-switches>`_ to change it.
use the `--nimcache`:option: [compiler switch](
nimc.html#compiler-usage-commandminusline-switches) to change it.
Memory management
@@ -366,15 +367,15 @@ aware of who controls what to avoid crashing.
Strings and C strings
---------------------
The manual mentions that `Nim strings are implicitly convertible to
cstrings <manual.html#types-cstring-type>`_ which makes interaction usually
The manual mentions that [Nim strings are implicitly convertible to
cstrings](manual.html#types-cstring-type) which makes interaction usually
painless. Most C functions accepting a Nim string converted to a
`cstring` will likely not need to keep this string around and by the time
they return the string won't be needed anymore. However, for the rare cases
where a Nim string has to be preserved and made available to the C backend
as a `cstring`, you will need to manually prevent the string data
from being freed with `GC_ref <system.html#GC_ref,string>`_ and `GC_unref
<system.html#GC_unref,string>`_.
from being freed with [GC_ref](system.html#GC_ref,string) and [GC_unref](
system.html#GC_unref,string).
A similar thing happens with C code invoking Nim code which returns a
`cstring`. Consider the following proc:
@@ -393,10 +394,10 @@ Custom data types
Just like strings, custom data types that are to be shared between Nim and
the backend will need careful consideration of who controls who. If you want
to hand a Nim reference to C code, you will need to use `GC_ref
<system.html#GC_ref,ref.T>`_ to mark the reference as used, so it does not get
freed. And for the C backend you will need to expose the `GC_unref
<system.html#GC_unref,ref.T>`_ proc to clean up this memory when it is not
to hand a Nim reference to C code, you will need to use [GC_ref](
system.html#GC_ref,ref.T) to mark the reference as used, so it does not get
freed. And for the C backend you will need to expose the [GC_unref](
system.html#GC_unref,ref.T) proc to clean up this memory when it is not
required anymore.
Again, if you are wrapping a library which *mallocs* and *frees* data

19
doc/contributing.md
View File

@@ -216,7 +216,7 @@ must be marked as deprecated using the `deprecated` pragma:
```
See also `Deprecated <manual.html#pragmas-deprecated-pragma>`_
See also [Deprecated](manual.html#pragmas-deprecated-pragma)
pragma in the manual.
@@ -242,7 +242,7 @@ as well as `testament`:cmd: and guarantee they stay in sync.
result = a & "Bar"
```
See `parentDir <os.html#parentDir,string>`_ example.
See [parentDir](os.html#parentDir,string) example.
The RestructuredText Nim uses has a special syntax for including code snippets
embedded in documentation; these are not run by `nim doc`:cmd: and therefore are
@@ -297,7 +297,7 @@ the first is preferred.
When you specify an *RST role* (highlighting/interpretation marker) do it
in the postfix form for uniformity, that is after \`text in backticks\`.
For example an ``:idx:`` role for referencing a topic ("SQLite" in the
example below) from `Nim Index`_ can be used in doc comment this way:
example below) from [Nim Index] can be used in doc comment this way:
```nim
## A higher level `SQLite`:idx: database wrapper.
@@ -466,8 +466,8 @@ General commit rules
2. If you introduce changes which affect backward compatibility,
make breaking changes, or have PR which is tagged as ``[feature]``,
the changes should be mentioned in `the changelog
<https://github.com/nim-lang/Nim/blob/devel/changelog.md>`_.
the changes should be mentioned in [the changelog](
https://github.com/nim-lang/Nim/blob/devel/changelog.md).
3. All changes introduced by the commit (diff lines) must be related to the
subject of the commit.
@@ -525,8 +525,10 @@ Continuous Integration (CI)
documentation only changes), add ``[skip ci]`` to your commit message title.
This convention is supported by our GitHub actions pipelines and our azure pipeline
(using custom logic, which should complete in < 1mn) as well as our former other pipelines:
`Appveyor <https://www.appveyor.com/docs/how-to/filtering-commits/#skip-directive-in-commit-message>`_
and `Travis <https://docs.travis-ci.com/user/customizing-the-build/#skipping-a-build>`_.
[Appveyor](
https://www.appveyor.com/docs/how-to/filtering-commits/#skip-directive-in-commit-message)
and [Travis](
https://docs.travis-ci.com/user/customizing-the-build/#skipping-a-build).
2. Consider enabling CI (azure, GitHub actions and builds.sr.ht) in your own Nim fork, and
waiting for CI to be green in that fork (fixing bugs as needed) before
@@ -568,7 +570,8 @@ Code reviews
2. When reviewing large diffs that may involve code moving around, GitHub's interface
doesn't help much, as it doesn't highlight moves. Instead, you can use something
like this, see visual results `here <https://github.com/nim-lang/Nim/pull/10431#issuecomment-456968196>`_:
like this, see visual results [here](
https://github.com/nim-lang/Nim/pull/10431#issuecomment-456968196):
```cmd
git fetch origin pull/10431/head && git checkout FETCH_HEAD

3
doc/destructors.md
View File

@@ -98,7 +98,8 @@ Lifetime-tracking hooks
The memory management for Nim's standard `string` and `seq` types as
well as other standard collections is performed via so-called
"Lifetime-tracking hooks", which are particular `type bound operators <manual.html#procedures-type-bound-operators>`_.
"Lifetime-tracking hooks", which are particular [type bound operators](
manual.html#procedures-type-bound-operators).
There are 4 different hooks for each (generic or concrete) object type `T` (`T` can also be a
`distinct` type) that are called implicitly by the compiler.

54
doc/docgen.md
View File

@@ -14,7 +14,7 @@ Introduction
============
This document describes the `documentation generation tools`:idx: built into
the `Nim compiler <nimc.html>`_, which can generate HTML, Latex and JSON output
the [Nim compiler](nimc.html), which can generate HTML, Latex and JSON output
from input ``.nim`` files and projects, as well as HTML and LaTeX from input RST
(reStructuredText) files. The output documentation will include the module
dependencies (`import`), any top-level documentation comments (`##`), and
@@ -59,8 +59,8 @@ Documentation Comments
----------------------
Any comments which are preceded by a double-hash (`##`), are interpreted as
documentation. Comments are parsed as RST (see `reference
<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_), providing
documentation. Comments are parsed as RST (see [reference](
http://docutils.sourceforge.net/docs/user/rst/quickref.html)), providing
Nim module authors the ability to easily generate richly formatted
documentation with only their well-documented code!
Basic Markdown syntax is also supported inside the doc comments.
@@ -148,7 +148,7 @@ Partial Output::
proc helloWorld(times: int) {.raises: [], tags: [].}
...
The full output can be seen here: `docgen_sample.html <docgen_sample.html>`_.
The full output can be seen here: [docgen_sample.html](docgen_sample.html).
It runs after semantic checking and includes pragmas attached implicitly by the
compiler.
@@ -247,7 +247,7 @@ Link text is either one word or a group of words enclosed by backticks `\``
Link text will be displayed *as is* while *link target* will be set to
the anchor \[*] of Nim symbol that corresponds to link text.
[*] anchors' format is described in `HTML anchor generation`_ section below.
\[*] anchors' format is described in [HTML anchor generation] section below.
If you have a constant:
@@ -435,11 +435,11 @@ This will generate an index of all the exported symbols in the input Nim
module, and put it into a neighboring file with the extension of ``.idx``. The
index file is line-oriented (newlines have to be escaped). Each line
represents a tab-separated record of several columns, the first two mandatory,
the rest optional. See the `Index (idx) file format`_ section for details.
the rest optional. See the [Index (idx) file format] section for details.
Once index files have been generated for one or more modules, the Nim
compiler command `buildIndex directory` can be run to go over all the index
files in the specified directory to generate a `theindex.html <theindex.html>`_
files in the specified directory to generate a [theindex.html](theindex.html)
file.
See source switch
@@ -488,7 +488,7 @@ the `rst2html`:option: and `rst2tex`:option: commands. Documents like this one a
initially written in a dialect of RST which adds support for Nim source code
highlighting with the ``.. code-block:: nim`` prefix. ``code-block`` also
supports highlighting of a few other languages supported by the
`packages/docutils/highlite module <highlite.html>`_.
[packages/docutils/highlite module](highlite.html).
Usage:
@@ -550,38 +550,38 @@ Callable type Suffix
The relationship of type to suffix is made by the proc `complexName` in the
``compiler/docgen.nim`` file. Here are some examples of complex names for
symbols in the `system module <system.html>`_.
symbols in the [system module](system.html).
* `type SomeSignedInt = int | int8 | int16 | int32 | int64` **=>**
`#SomeSignedInt <system.html#SomeSignedInt>`_
[#SomeSignedInt](system.html#SomeSignedInt)
* `var globalRaiseHook: proc (e: ref E_Base): bool {.nimcall.}` **=>**
`#globalRaiseHook <system.html#globalRaiseHook>`_
[#globalRaiseHook](system.html#globalRaiseHook)
* `const NimVersion = "0.0.0"` **=>**
`#NimVersion <system.html#NimVersion>`_
[#NimVersion](system.html#NimVersion)
* `proc getTotalMem(): int {.rtl, raises: [], tags: [].}` **=>**
`#getTotalMem, <system.html#getTotalMem>`_
[#getTotalMem](system.html#getTotalMem)
* `proc len[T](x: seq[T]): int {.magic: "LengthSeq", noSideEffect.}` **=>**
`#len,seq[T] <system.html#len,seq[T]>`_
[#len,seq[T]](system.html#len,seq[T])
* `iterator pairs[T](a: seq[T]): tuple[key: int, val: T] {.inline.}` **=>**
`#pairs.i,seq[T] <iterators.html#pairs.i,seq[T]>`_
[#pairs.i,seq[T]](iterators.html#pairs.i,seq[T])
* `template newException[](exceptn: typedesc; message: string;
parentException: ref Exception = nil): untyped` **=>**
`#newException.t,typedesc,string,ref.Exception
<system.html#newException.t,typedesc,string,ref.Exception>`_
[#newException.t,typedesc,string,ref.Exception](
system.html#newException.t,typedesc,string,ref.Exception)
Index (idx) file format
=======================
Files with the ``.idx`` extension are generated when you use the `Index
switch <#related-options-index-switch>`_ along with commands to generate
Files with the ``.idx`` extension are generated when you use the [Index
switch] along with commands to generate
documentation from source or text files. You can programmatically generate
indices with the `setIndexTerm()
<rstgen.html#setIndexTerm,RstGenerator,string,string,string,string,string>`_
indices with the [setIndexTerm()](
rstgen.html#setIndexTerm,RstGenerator,string,string,string,string,string)
and `writeIndexFile() <rstgen.html#writeIndexFile,RstGenerator,string>`_ procs.
The purpose of `idx` files is to hold the interesting symbols and their HTML
references so they can be later concatenated into a big index file with
`mergeIndexes() <rstgen.html#mergeIndexes,string>`_. This section documents
[mergeIndexes()](rstgen.html#mergeIndexes,string). This section documents
the file format in detail.
Index files are line-oriented and tab-separated (newline and tab characters
@@ -626,16 +626,16 @@ final index, and TOC entries found in ``.nim`` files are discarded.
Additional resources
====================
* `Nim Compiler User Guide <nimc.html#compiler-usage-commandminusline-switches>`_
* [Nim Compiler User Guide](nimc.html#compiler-usage-commandminusline-switches)
* Documentation for `rst module <rst.html>`_ -- Nim RST/Markdown parser.
* Documentation for [rst module](rst.html) -- Nim RST/Markdown parser.
* `RST Quick Reference
<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
* [RST Quick Reference](
http://docutils.sourceforge.net/docs/user/rst/quickref.html)
The output for HTML and LaTeX comes from the ``config/nimdoc.cfg`` and
``config/nimdoc.tex.cfg`` configuration files. You can add and modify these
files to your project to change the look of the docgen output.
You can import the `packages/docutils/rstgen module <rstgen.html>`_ in your
You can import the [packages/docutils/rstgen module](rstgen.html) in your
programs if you want to reuse the compiler's documentation generation procs.

148
doc/manual.md
View File

@@ -22,16 +22,16 @@ About this document
precise wording. This manual is constantly evolving into a proper specification.
**Note**: The experimental features of Nim are
covered `here <manual_experimental.html>`_.
covered [here](manual_experimental.html).
**Note**: Assignments, moves, and destruction are specified in
the `destructors <destructors.html>`_ document.
the [destructors](destructors.html) document.
This document describes the lexis, the syntax, and the semantics of the Nim language.
To learn how to compile Nim programs and generate documentation see
the `Compiler User Guide <nimc.html>`_ and the `DocGen Tools Guide <docgen.html>`_.
the [Compiler User Guide](nimc.html) and the [DocGen Tools Guide](docgen.html).
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
@@ -94,8 +94,8 @@ In a typical Nim program, most of the code is compiled into the executable.
However, some 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
supported at compile-time, but there are some restrictions -- see [Restrictions
on Compile-Time Execution] for
details. We use the term `runtime`:idx: to cover both compile-time execution
and code execution in the executable.
@@ -111,7 +111,7 @@ A `panic`:idx: is an error that the implementation detects
and reports at runtime. The method for reporting such errors is via
*raising exceptions* or *dying with a fatal error*. However, the implementation
provides a means to disable these `runtime checks`:idx:. See the section
pragmas_ for details.
[Pragmas] for details.
Whether a panic results in an exception or in a fatal error is
implementation specific. Thus, the following program is invalid; even though the
@@ -499,7 +499,7 @@ Rationale: It enables the efficient support of `array[char, int]` or
`set[char]`.
The `Rune` type can represent any Unicode character.
`Rune` is declared in the `unicode module <unicode.html>`_.
`Rune` is declared in the [unicode module](unicode.html).
A character literal that does not end in `'` is interpreted as `'` if there
is a preceding backtick token. There must be no whitespace between the preceding
@@ -507,7 +507,7 @@ backtick token and the character literal. This special case ensures that a decla
like ``proc `'customLiteral`(s: string)`` is valid. ``proc `'customLiteral`(s: string)``
is the same as ``proc `'\''customLiteral`(s: string)``.
See also `custom numeric literals <#custom-numeric-literals>`_.
See also [custom numeric literals].
Numeric literals
@@ -713,7 +713,7 @@ Syntax
======
This section lists Nim's standard syntax. How the parser handles
the indentation is already described in the `Lexical Analysis`_ section.
the indentation is already described in the [Lexical Analysis] section.
Nim allows user-definable operators.
Binary operators have 11 different levels of precedence.
@@ -1100,8 +1100,7 @@ if the literal's value fits this smaller type and such a conversion is less
expensive than other implicit conversions, so `myInt16 + 34` produces
an `int16` result.
For further details, see `Convertible relation
<#type-relations-convertible-relation>`_.
For further details, see [Convertible relation].
Subrange types
@@ -1148,8 +1147,7 @@ The following floating-point types are pre-defined:
Automatic type conversion in expressions with different kinds of floating-point
types is performed: See `Convertible relation
<#type-relations-convertible-relation>`_ for further details. Arithmetic
types is performed: See [Convertible relation] for further details. Arithmetic
performed on floating-point types follows the IEEE standard. Integer types are
not converted to floating-point types automatically and vice versa.
@@ -1229,7 +1227,7 @@ The character type is named `char` in Nim. Its size is one byte.
Thus, it cannot represent a UTF-8 character, but a part of it.
The `Rune` type is used for Unicode characters, it can represent any Unicode
character. `Rune` is declared in the `unicode module <unicode.html>`_.
character. `Rune` is declared in the [unicode module](unicode.html).
@@ -1315,7 +1313,7 @@ as `MyEnum.value`:
echo MyEnum.amb # OK.
```
To implement bit fields with enums see `Bit fields <#set-type-bit-fields>`_
To implement bit fields with enums see [Bit fields].
String type
@@ -1375,8 +1373,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
<unicode.html>`_ can be used for iteration over all Unicode characters.
i-th *unichar*. The iterator `runes` from the [unicode module](unicode.html)
can be used for iteration over all Unicode characters.
cstring type
@@ -1733,8 +1731,8 @@ introduce new object roots apart from `system.RootObj`.
```
The assignment operator for tuples and objects copies each component.
The methods to override this copying behavior are described `here
<manual.html#procedures-type-bound-operations>`_.
The methods to override this copying behavior are described [here][type
bound operators].
Object construction
@@ -1947,8 +1945,8 @@ dereferencing operations for reference types:
```
Automatic dereferencing can be performed for the first argument of a routine
call, but this is an experimental feature and is described `here
<manual_experimental.html#automatic-dereferencing>`_.
call, but this is an experimental feature and is described [here](
manual_experimental.html#automatic-dereferencing).
In order to simplify structural type checking, recursive tuples are not valid:
@@ -1973,7 +1971,7 @@ This feature is useful if an object should only gain reference semantics:
To allocate a new traced object, the built-in procedure `new` has to be used.
To deal with untraced memory, the procedures `alloc`, `dealloc` and
`realloc` can be used. The documentation of the `system <system.html>`_ module
`realloc` can be used. The documentation of the [system](system.html) module
contains further information.
@@ -2225,7 +2223,7 @@ the proc that deals with the distinct type's base type, so no code is
generated.
But it seems all this boilerplate code needs to be repeated for the `Euro`
currency. This can be solved with templates_.
currency. This can be solved with [templates].
```nim test = "nim c $1"
template additive(typ: typedesc) =
@@ -2341,8 +2339,8 @@ conversions from `string` to `SQL` are allowed:
Now we have compile-time checking against SQL injection attacks. Since
`"".SQL` is transformed to `SQL("")` no new syntax is needed for nice
looking `SQL` string literals. The hypothetical `SQL` type actually
exists in the library as the `SqlQuery type <db_common.html#SqlQuery>`_ of
modules like `db_sqlite <db_sqlite.html>`_.
exists in the library as the [SqlQuery type](db_common.html#SqlQuery) of
modules like [db_sqlite](db_sqlite.html).
Auto type
@@ -2671,7 +2669,7 @@ metatypes `typed` and `typedesc` are not lazy.
Varargs matching
----------------
See `Varargs <#types-varargs>`_.
See [Varargs].
iterable
@@ -2989,8 +2987,7 @@ A const section declares constants whose values are constant expressions:
Once declared, a constant's symbol can be used as a constant expression.
See `Constants and Constant Expressions <#constants-and-constant-expressions>`_
for details.
See [Constants and Constant Expressions] for details.
Static statement/expression
---------------------------
@@ -3018,8 +3015,7 @@ Even some code that has side effects is permitted in a static block:
```
There are limitations on what Nim code can be executed at compile time;
see `Restrictions on Compile-Time Execution
<#restrictions-on-compileminustime-execution>`_ for details.
see [Restrictions on Compile-Time Execution] for details.
It's a static error if the compiler cannot execute the block at compile
time.
@@ -3273,7 +3269,7 @@ The `yield` statement is used instead of the `return` statement in
iterators. It is only valid in iterators. Execution is returned to the body
of the for loop that called the iterator. Yield does not end the iteration
process, but the execution is passed back to the iterator if the next iteration
starts. See the section about iterators (`Iterators and the for statement`_)
starts. See the section about iterators ([Iterators and the for statement])
for further information.
@@ -3786,8 +3782,7 @@ The method call syntax conflicts with explicit generic instantiations:
`p[T](x)` cannot be written as `x.p[T]` because `x.p[T]` is always
parsed as `(x.p)[T]`.
See also: `Limitations of the method call syntax
<#templates-limitations-of-the-method-call-syntax>`_.
See also: [Limitations of the method call syntax].
The `[: ]` notation has been designed to mitigate this issue: `x.p[:T]`
is rewritten by the parser to `p[T](x)`, `x.p[:T](y)` is rewritten to
@@ -3873,7 +3868,7 @@ more argument in this case:
```
The command invocation syntax also can't have complex expressions as arguments.
For example: (`anonymous procs <#procedures-anonymous-procs>`_), `if`,
For example: [anonymous procedures], `if`,
`case` or `try`. Function calls with no arguments still need () to
distinguish between a call and the function itself as a first-class value.
@@ -3893,9 +3888,9 @@ or on the stack if the compiler determines that this would be safe.
### Creating closures in loops
Since closures capture local variables by reference it is often not wanted
behavior inside loop bodies. See `closureScope
<system.html#closureScope.t,untyped>`_ and `capture
<sugar.html#capture.m,varargs[typed],untyped>`_ for details on how to change this behavior.
behavior inside loop bodies. See [closureScope](
system.html#closureScope.t,untyped) and [capture](
sugar.html#capture.m,varargs[typed],untyped) for details on how to change this behavior.
Anonymous procedures
--------------------
@@ -3912,7 +3907,7 @@ procedures:
Procs as expressions can appear both as nested procs and inside top-level
executable code. The `sugar <sugar.html>`_ module contains the `=>` macro
executable code. The [sugar](sugar.html) module contains the `=>` macro
which enables a more succinct syntax for anonymous procedures resembling
lambdas as they are in languages like JavaScript, C#, etc.
@@ -3982,7 +3977,7 @@ Type bound operators
A type bound operator is a `proc` or `func` whose name starts with `=` but isn't an operator
(i.e. containing only symbols, such as `==`). These are unrelated to setters
(see `properties <manual.html#procedures-properties>`_), which instead end in `=`.
(see [Properties]), which instead end in `=`.
A type bound operator declared for a type applies to the type regardless of whether
the operator is in scope (including if it is private).
@@ -4024,7 +4019,7 @@ This also means that one cannot override `deepCopy` for both `ptr T` and
used for one pointer type.
For more details on some of those procs, see
`Lifetime-tracking hooks <destructors.html#lifetimeminustracking-hooks>`_.
[Lifetime-tracking hooks](destructors.html#lifetimeminustracking-hooks).
Nonoverloadable builtins
------------------------
@@ -4037,7 +4032,8 @@ simplicity (they require specialized semantic checking)::
Thus, they act more like keywords than like ordinary identifiers; unlike a
keyword however, a redefinition may `shadow`:idx: the definition in
the system_ module. From this list the following should not be written in dot
the [system](system.html) module.
From this list the following should not be written in dot
notation `x.f` since `x` cannot be type-checked before it gets passed
to `f`::
@@ -4589,14 +4585,13 @@ would. For example:
```
See also see `iterable <#overloading-resolution-iterable>`_ for passing iterators to templates and macros.
See also [iterable] for passing iterators to templates and macros.
Converters
==========
A converter is like an ordinary proc except that it enhances
the "implicitly convertible" type relation (see `Convertible relation
<#type-relations-convertible-relation>`_):
the "implicitly convertible" type relation (see [Convertible relation]):
```nim
# bad style ahead: Nim is not C.
@@ -4859,7 +4854,7 @@ exception.
Exception hierarchy
-------------------
The exception tree is defined in the `system <system.html>`_ module.
The exception tree is defined in the [system](system.html) module.
Every exception inherits from `system.Exception`. Exceptions that indicate
programming bugs inherit from `system.Defect` (which is a subtype of `Exception`)
and are strictly speaking not catchable as they can also be mapped to an operation
@@ -5146,8 +5141,8 @@ or global variable and it does not call any routine that has a side effect.
It is a static error to mark a proc/iterator to have no side effect if the compiler cannot verify this.
As a special semantic rule, the built-in `debugEcho
<system.html#debugEcho,varargs[typed,]>`_ pretends to be free of side effects
As a special semantic rule, the built-in [debugEcho](
system.html#debugEcho,varargs[typed,]) pretends to be free of side effects
so that it can be used for debugging routines marked as `noSideEffect`.
`func` is syntactic sugar for a proc with no side effects:
@@ -5202,7 +5197,7 @@ be used:
See also:
- `Shared heap memory management <mm.html>`_.
- [Shared heap memory management](mm.html).
@@ -6146,8 +6141,8 @@ and are not looked up again. As the example shows, `bindSym` does work with
overloaded symbols implicitly.
Note that the symbol names passed to `bindSym` have to be constant. The
experimental feature `dynamicBindSym` (`experimental manual
<manual_experimental.html#dynamic-arguments-for-bindsym>`_)
experimental feature `dynamicBindSym` ([experimental manual](
manual_experimental.html#dynamic-arguments-for-bindsym))
allows this value to be computed dynamically.
Post-statement blocks
@@ -6287,8 +6282,8 @@ macro to call.
Special Types
=============
static[T]
---------
static\[T]
----------
As their name suggests, static parameters must be constant expressions:
@@ -6341,8 +6336,8 @@ expression by coercing it to a corresponding `static` type:
The compiler will report any failure to evaluate the expression or a
possible type mismatch error.
typedesc[T]
-----------
typedesc\[T]
------------
In many contexts, Nim treats the names of types as regular
values. These values exist only during the compilation phase, but since
@@ -7051,8 +7046,7 @@ extension the pragma is simply ignored.
immediate pragma
----------------
The immediate pragma is obsolete. See `Typed vs untyped parameters
<#templates-typed-vs-untyped-parameters>`_.
The immediate pragma is obsolete. See [Typed vs untyped parameters].
redefine pragma
---------------
@@ -7230,7 +7224,7 @@ The `experimental` pragma enables experimental language features. Depending
on the concrete feature, this means that the feature is either considered
too unstable for an otherwise stable release or that the future of the feature
is uncertain (it may be removed at any time). See the
`experimental manual <manual_experimental.html>`_ for more details.
[experimental manual](manual_experimental.html) for more details.
Example:
@@ -7449,7 +7443,7 @@ compiler like one would use the command-line switch `--passc`:option:\:
{.passc: "-Wall -Werror".}
```
Note that one can use `gorge` from the `system module <system.html>`_ to
Note that one can use `gorge` from the [system module](system.html) to
embed parameters from an external command that will be executed
during semantic analysis:
@@ -7480,7 +7474,7 @@ like one would be using the command-line switch `--passl`:option:\:
{.passl: "-lSDLmain -lSDL".}
```
Note that one can use `gorge` from the `system module <system.html>`_ to
Note that one can use `gorge` from the [system module](system.html) to
embed parameters from an external command that will be executed
during semantic analysis:
@@ -7553,13 +7547,13 @@ the code should be emitted can be influenced via the prefixes
ImportCpp pragma
----------------
**Note**: `c2nim <https://github.com/nim-lang/c2nim/blob/master/doc/c2nim.rst>`_ can parse a large subset of C++ and knows
**Note**: [c2nim](https://github.com/nim-lang/c2nim/blob/master/doc/c2nim.rst)
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.
Similar to the `importc pragma for C
<#foreign-function-interface-importc-pragma>`_, the
Similar to the [importc pragma] for C, the
`importcpp` pragma can be used to import `C++`:idx: methods or C++ symbols
in general. The generated code then uses the C++ method calling
syntax: `obj->method(arg)`:cpp:. In combination with the `header` and `emit`
@@ -7791,7 +7785,7 @@ Produces:
ImportJs pragma
---------------
Similar to the `importcpp pragma for C++ <#implementation-specific-pragmas-importcpp-pragma>`_,
Similar to the [importcpp pragma] for C++,
the `importjs` pragma can be used to import Javascript methods or
symbols in general. The generated code then uses the Javascript method
calling syntax: ``obj.method(arg)``.
@@ -7799,8 +7793,7 @@ calling syntax: ``obj.method(arg)``.
ImportObjC pragma
-----------------
Similar to the `importc pragma for C
<#foreign-function-interface-importc-pragma>`_, the `importobjc` pragma can
Similar to the [importc pragma] for C, the `importobjc` pragma can
be used to import `Objective C`:idx: methods. The generated code then uses the
Objective C method calling syntax: ``[obj method param1: arg]``.
In addition with the `header` and `emit` pragmas this
@@ -8016,7 +8009,7 @@ definitions, statements, etc.
The macros module includes helpers which can be used to simplify custom pragma
access `hasCustomPragma`, `getCustomPragmaVal`. Please consult the
`macros <macros.html>`_ module documentation for details. These macros are not
[macros](macros.html) module documentation for details. These macros are not
magic, everything they do can also be achieved by walking the AST of the object
representation.
@@ -8084,8 +8077,8 @@ the same way.
There are a few more applications of macro pragmas, such as in type,
variable and constant declarations, but this behavior is considered to be
experimental and is documented in the `experimental manual
<manual_experimental.html#extended-macro-pragmas>`_ instead.
experimental and is documented in the [experimental manual](
manual_experimental.html#extended-macro-pragmas) instead.
Foreign function interface
@@ -8123,9 +8116,9 @@ JS backend for JS objects and functions. Other backends do provide
the same feature under the same name. Also, when the target language
is not set to C, other pragmas are available:
* `importcpp <manual.html#implementation-specific-pragmas-importcpp-pragma>`_
* `importobjc <manual.html#implementation-specific-pragmas-importobjc-pragma>`_
* `importjs <manual.html#implementation-specific-pragmas-importjs-pragma>`_
* [importcpp][importcpp pragma]
* [importobjc][importobjc pragma]
* [importjs][importjs pragma]
The string literal passed to `importc` can be a format string:
@@ -8163,7 +8156,7 @@ is available and a literal dollar sign must be written as ``$$``.
If the symbol should also be exported to a dynamic library, the `dynlib`
pragma should be used in addition to the `exportc` pragma. See
`Dynlib pragma for export <#foreign-function-interface-dynlib-pragma-for-export>`_.
[Dynlib pragma for export].
Extern pragma
@@ -8296,7 +8289,7 @@ because of order of initialization problems.
**Note**: A `dynlib` import can be overridden with
the `--dynlibOverride:name`:option: command-line option. The
`Compiler User Guide <nimc.html>`_ contains further information.
[Compiler User Guide](nimc.html) contains further information.
Dynlib pragma for export
@@ -8319,10 +8312,10 @@ Threads
=======
To enable thread support the `--threads:on`:option: command-line switch needs to
be used. The system_ module then contains several threading primitives.
See the `channels <channels_builtin.html>`_ modules
be used. The [system module](system.html) module then contains several threading primitives.
See the [channels](channels_builtin.html) modules
for the low-level thread API. There are also high-level parallelism constructs
available. See `spawn <manual_experimental.html#parallel-amp-spawn>`_ for
available. See [spawn](manual_experimental.html#parallel-amp-spawn) for
further details.
Nim's memory model for threads is quite different than that of other common
@@ -8452,7 +8445,8 @@ model low level lockfree mechanisms:
The `locks` pragma takes a list of lock expressions `locks: [a, b, ...]`
in order to support *multi lock* statements. Why these are essential is
explained in the `lock levels <#guards-and-locks-lock-levels>`_ section.
explained in the [lock levels](manual_experimental.md#lock-levels) section
of experimental manual.
### Protecting general locations

14
doc/manual_experimental.md
View File

@@ -233,7 +233,7 @@ from a module. The syntax `import foo {.all.}` can be used to import all
symbols from the module `foo`. Note that importing private symbols is
generally not recommended.
See also the experimental `importutils <importutils.html>`_ module.
See also the experimental [importutils](importutils.html) module.
Code reordering
@@ -464,7 +464,7 @@ to use this operator.
Extended macro pragmas
======================
Macro pragmas as described in `the manual <manual.html#userminusdefined-pragmas-macro-pragmas>`_
Macro pragmas as described in [the manual](manual.html#userminusdefined-pragmas-macro-pragmas)
can also be applied to type, variable and constant declarations.
For types:
@@ -630,7 +630,7 @@ For example:
The algorithm behind this analysis is described in
the `view types section <#view-types-algorithm>`_.
the [view types algorithm].
View types
@@ -744,7 +744,7 @@ has `source` as the owner. A path expression `e` is defined recursively:
If a view type is used as a return type, the location must borrow from a location
that is derived from the first parameter that is passed to the proc.
See `the manual <manual.html#procedures-var-return-type>`_
See [the manual](manual.html#procedures-var-return-type)
for details about how this is done for `var T`.
A mutable view can borrow from a mutable location, an immutable view can borrow
@@ -785,7 +785,7 @@ The scope of the view does not matter:
The analysis requires as much precision about mutations as is reasonably obtainable,
so it is more effective with the experimental `strict funcs <#strict-funcs>`_
so it is more effective with the experimental [strict funcs]
feature. In other words `--experimental:views`:option: works better
with `--experimental:strictFuncs`:option:.
@@ -1340,7 +1340,7 @@ object inheritance syntax involving the `of` keyword:
like channels, to implement thread safe automatic memory management.
The builtin `deepCopy` can even clone closures and their environments. See
the documentation of `spawn <#parallel-amp-spawn-spawn-statement>`_ for details.
the documentation of [spawn][spawn statement] for details.
Dynamic arguments for bindSym
@@ -1771,7 +1771,7 @@ Nim has two flavors of parallelism:
Nim has a builtin thread pool that can be used for CPU intensive tasks. For
IO intensive tasks the `async` and `await` features should be
used instead. Both parallel and spawn need the `threadpool <threadpool.html>`_
used instead. Both parallel and spawn need the [threadpool](threadpool.html)
module to work.
Somewhat confusingly, `spawn` is also used in the `parallel` statement

4
doc/sets_fragment.txt
View File

@@ -21,7 +21,7 @@ Attempting to declare a set with a larger type will result in an error:
```
**Note:** Nim also offers `hash sets <sets.html>`_ (which you need to import
**Note:** Nim also offers [hash sets](sets.html) (which you need to import
with `import sets`), which have no such restrictions.
Sets can be constructed via the set constructor: `{}` is the empty set. The
@@ -90,4 +90,4 @@ Note how the set turns enum values into powers of 2.
If using enums and sets with C, use distinct cint.
For interoperability with C see also the
`bitsize pragma <manual.html#implementation-specific-pragmas-bitsize-pragma>`_.
[bitsize pragma](manual.html#implementation-specific-pragmas-bitsize-pragma).

125
doc/tut1.md
View File

@@ -22,14 +22,14 @@ like variables, types, or statements.
Here are several other resources for learning Nim:
* `Nim Basics tutorial <https://narimiran.github.io/nim-basics/>`_ - a gentle
* [Nim Basics tutorial](https://narimiran.github.io/nim-basics/) - a gentle
introduction of the concepts mentioned above
* `Learn Nim in 5 minutes <https://learnxinyminutes.com/docs/nim/>`_ - quick,
* [Learn Nim in 5 minutes](https://learnxinyminutes.com/docs/nim/) - quick,
five-minute introduction to Nim
* `The Nim manual <manual.html>`_ - many more examples of the advanced language features
* [The Nim manual](manual.html) - 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 <nep1.html>`_.
Nim's documentation, follow the [Nim style guide](nep1.html).
The first program
@@ -49,7 +49,7 @@ Save this code to the file "greetings.nim". Now compile and run it::
nim compile --run greetings.nim
With the ``--run`` `switch <nimc.html#compiler-usage-commandminusline-switches>`_ Nim
With the ``--run`` [switch](nimc.html#compiler-usage-commandminusline-switches) Nim
executes the file automatically after compilation. You can give your program
command-line arguments by appending them after the filename::
@@ -66,8 +66,8 @@ To compile a release version use::
By default, the Nim compiler generates a large number of runtime checks
aiming for your debugging pleasure. With ``-d:release`` some checks are
`turned off and optimizations are turned on
<nimc.html#compiler-usage-compileminustime-symbols>`_.
[turned off and optimizations are turned on](
nimc.html#compiler-usage-compileminustime-symbols).
For benchmarking or production code, use the ``-d:release`` switch.
For comparing the performance with unsafe languages like C, use the ``-d:danger`` switch
@@ -81,8 +81,8 @@ done with spaces only, tabulators are not allowed.
String literals are enclosed in double-quotes. The `var` statement declares
a new variable named `name` of type `string` with the value that is
returned by the `readLine <syncio.html#readLine,File>`_ procedure. Since the
compiler knows that `readLine <syncio.html#readLine,File>`_ returns a string,
returned by the [readLine](syncio.html#readLine,File) procedure. Since the
compiler knows that [readLine](syncio.html#readLine,File) returns a string,
you can leave out the type in the declaration (this is called `local type
inference`:idx:). So this will work too:
@@ -94,8 +94,8 @@ Note that this is basically the only form of type inference that exists in
Nim: it is a good compromise between brevity and readability.
The "hello world" program contains several identifiers that are already known
to the compiler: `echo`, `readLine <syncio.html#readLine,File>`_, etc.
These built-ins are declared in the system_ module which is implicitly
to the compiler: `echo`, [readLine](syncio.html#readLine,File), etc.
These built-ins are declared in the [system](system.html) module which is implicitly
imported by any other module.
@@ -340,7 +340,7 @@ the compiler that for every other value nothing should be done:
else: discard
```
The empty `discard statement <#procedures-discard-statement>`_ is a *do
The empty [discard statement] is a *do
nothing* statement. The compiler knows that a case statement with an else part
cannot fail and thus the error disappears. Note that it is impossible to cover
all possible string values: that is why string cases always need an `else`
@@ -372,8 +372,8 @@ For statement
-------------
The `for` statement is a construct to loop over any element an *iterator*
provides. The example uses the built-in `countup
<system.html#countup.i,T,T,Positive>`_ iterator:
provides. The example uses the built-in [countup](
system.html#countup.i,T,T,Positive) iterator:
```nim test = "nim c $1"
echo "Counting to ten: "
@@ -383,8 +383,8 @@ provides. The example uses the built-in `countup
```
The variable `i` is implicitly declared by the
`for` loop and has the type `int`, because that is what `countup
<system.html#countup.i,T,T,Positive>`_ returns. `i` runs through the values
`for` loop and has the type `int`, because that is what [countup](
system.html#countup.i,T,T,Positive) returns. `i` runs through the values
1, 2, .., 10. Each value is `echo`-ed. This code does the same:
```nim
@@ -396,8 +396,8 @@ The variable `i` is implicitly declared by the
# --> Outputs 1 2 3 4 5 6 7 8 9 10 on different lines
```
Since counting up occurs so often in programs, Nim also has a `..
<system.html#...i,T,T>`_ iterator that does the same:
Since counting up occurs so often in programs, Nim also has a [..](
system.html#...i,T,T) iterator that does the same:
```nim
for i in 1 .. 10:
@@ -414,7 +414,7 @@ Counting down can be achieved as easily (but is less often needed):
```
Zero-indexed counting has two shortcuts `..<` and `.. ^1`
(`backward index operator <system.html#^.t%2Cint>`_) to simplify
([backward index operator](system.html#^.t%2Cint)) to simplify
counting to one less than the higher index:
```nim
@@ -600,11 +600,11 @@ an expression is allowed:
Procedures
==========
To define new commands like `echo <system.html#echo,varargs[typed,]>`_
and `readLine <syncio.html#readLine,File>`_ in the examples, the concept of a
To define new commands like [echo](system.html#echo,varargs[typed,])
and [readLine](syncio.html#readLine,File) in the examples, the concept of a
*procedure* is needed. You might be used to them being called *methods* or
*functions* in other languages, but Nim
`differentiates these concepts <tut1.html#procedures-funcs-and-methods>`_. In
[differentiates these concepts](tut1.html#procedures-funcs-and-methods). In
Nim, new procedures are defined with the `proc` keyword:
```nim test = "nim c $1"
@@ -808,7 +808,7 @@ Nim provides the ability to overload procedures similar to C++:
assert toString(true) == "yep" # calls the toString(x: bool) proc
```
(Note that `toString` is usually the `$ <dollars.html>`_ operator in
(Note that `toString` is usually the [$](dollars.html) operator in
Nim.) The compiler chooses the most appropriate proc for the `toString`
calls. How this overloading resolution algorithm works exactly is not
discussed here -- see the manual for details. Ambiguous calls are reported as errors.
@@ -833,7 +833,7 @@ User-defined operators are allowed. Nothing stops you from defining your own
`@!?+~` operator, but doing so may reduce readability.
The operator's precedence is determined by its first character. The details
can be `found in the manual <manual.html#syntax-precedence>`_.
can be [found in the manual](manual.html#syntax-precedence).
To define a new operator enclose the operator in backticks "`":
@@ -882,7 +882,7 @@ Here `odd` depends on `even` and vice versa. Thus `even` needs to be
introduced to the compiler before it is completely defined. The syntax for
such a forward declaration is simple: just omit the `=` and the
procedure's body. The `assert` just adds border conditions, and will be
covered later in `Modules`_ section.
covered later in [Modules] section.
Later versions of the language will weaken the requirements for forward
declarations.
@@ -913,7 +913,7 @@ programming. If you overload a procedure (two procedures with the same name but
of different types or with different sets of arguments are said to be overloaded), the procedure to use is determined
at compile-time. Methods, on the other hand, depend on objects that inherit from
the `RootObj`. This is something that is covered in much greater depth in
the `second part of the tutorial<tut2.html#object-oriented-programming-dynamic-dispatch>`_.
the [second part of the tutorial](tut2.html#object-oriented-programming-dynamic-dispatch).
Iterators
@@ -927,7 +927,7 @@ Let's return to the simple counting example:
echo i
```
Can a `countup <system.html#countup.i,T,T,Positive>`_ proc be written that
Can a [countup](system.html#countup.i,T,T,Positive) proc be written that
supports this loop? Let's try:
```nim
@@ -964,12 +964,13 @@ important differences:
(This restriction will be gone in a future version of the compiler.)
However, you can also use a closure iterator to get a different set of
restrictions. See `first-class iterators <manual.html#iterators-and-the-for-statement-firstminusclass-iterators>`_
restrictions. See [first-class iterators](
manual.html#iterators-and-the-for-statement-firstminusclass-iterators)
for details. Iterators can have the same name and parameters as a proc since
essentially they have their own namespaces. Therefore, it is common to
wrap iterators in procs of the same name which accumulate the result of the
iterator and return it as a sequence, like `split` from the `strutils module
<strutils.html>`_.
iterator and return it as a sequence, like `split` from the [strutils module](
strutils.html).
Basic types
@@ -1095,8 +1096,8 @@ floats and follow the IEEE-754 standard.
Automatic type conversion in expressions with different kinds of floating-point types is performed: the smaller type is converted to the larger. Integer
types are **not** converted to floating-point types automatically, nor vice
versa. Use the `toInt <system.html#toInt,float>`_ and
`toFloat <system.html#toFloat,int>`_ procs for these conversions.
versa. Use the [toInt](system.html#toInt,float) and
[toFloat](system.html#toFloat,int) procs for these conversions.
Type Conversion
@@ -1117,13 +1118,13 @@ type as a function:
Internal type representation
============================
As mentioned earlier, the built-in `$ <dollars.html>`_ (stringify) operator
As mentioned earlier, the built-in [$](dollars.html) (stringify) operator
turns any basic type into a string, which you can then print to the console
using the `echo` proc. However, advanced types, and your own custom types,
won't work with the `$` operator until you define it for them.
Sometimes you just want to debug the current value of a complex type without
having to write its `$` operator. You can use then the `repr
<system.html#repr,T>`_ proc which works with any type and even complex data
having to write its `$` operator. You can use then the [repr](
system.html#repr,T) proc which works with any type and even complex data
graphs with cycles. The following example shows that even for basic types
there is a difference between the `$` and `repr` outputs:
@@ -1216,8 +1217,8 @@ Operation Comment
================= ========================================================
The `inc <system.html#inc,T,int>`_, `dec <system.html#dec,T,int>`_, `succ
<system.html#succ,T,int>`_ and `pred <system.html#pred,T,int>`_ operations can
The [inc](system.html#inc,T,int), [dec](system.html#dec,T,int), [succ](
system.html#succ,T,int) and [pred](system.html#pred,T,int) operations can
fail by raising an `RangeDefect` or `OverflowDefect`. (If the code has been
compiled with the proper runtime checks turned on.)
@@ -1239,8 +1240,8 @@ to 5. Assigning any other value to a variable of type `MySubrange` is a
compile-time or runtime error. Assignments from the base type to one of its
subrange types (and vice versa) are allowed.
The `system` module defines the important `Natural <system.html#Natural>`_
type as `range[0..high(int)]` (`high <system.html#high,typedesc[T]>`_ returns
The `system` module defines the important [Natural](system.html#Natural)
type as `range[0..high(int)]` ([high](system.html#high,typedesc[T]) returns
the maximal value). Other programming languages may suggest the use of unsigned
integers for natural numbers. This is often **unwise**: you don't want unsigned
arithmetic (which wraps around) just because the numbers cannot be negative.
@@ -1278,9 +1279,9 @@ checks can be disabled via pragmas or invoking the compiler with the
Arrays are value types, like any other Nim type. The assignment operator
copies the whole array contents.
The built-in `len <system.html#len,TOpenArray>`_ proc returns the array's
length. `low(a) <system.html#low,openArray[T]>`_ returns the lowest valid index
for the array `a` and `high(a) <system.html#high,openArray[T]>`_ the highest
The built-in [len](system.html#len,TOpenArray) proc returns the array's
length. [low(a)](system.html#low,openArray[T]) returns the lowest valid index
for the array `a` and [high(a)](system.html#high,openArray[T]) the highest
valid index.
```nim test = "nim c $1"
@@ -1358,14 +1359,14 @@ Sequences are similar to arrays but of dynamic length which may change
during runtime (like strings). Since sequences are resizable they are always
allocated on the heap and garbage collected.
Sequences are always indexed with an `int` starting at position 0. The `len
<system.html#len,seq[T]>`_, `low <system.html#low,openArray[T]>`_ and `high
<system.html#high,openArray[T]>`_ operations are available for sequences too.
Sequences are always indexed with an `int` starting at position 0. The [len](
system.html#len,seq[T]), [low](system.html#low,openArray[T]) and [high](
system.html#high,openArray[T]) operations are available for sequences too.
The notation `x[i]` can be used to access the i-th element of `x`.
Sequences can be constructed by the array constructor `[]` in conjunction
with the array to sequence operator `@`. Another way to allocate space for
a sequence is to call the built-in `newSeq <system.html#newSeq>`_ procedure.
a sequence is to call the built-in [newSeq](system.html#newSeq) procedure.
A sequence may be passed to an openarray parameter.
@@ -1382,12 +1383,12 @@ Sequence variables are initialized with `@[]`.
The `for` statement can be used with one or two variables when used with a
sequence. When you use the one variable form, the variable will hold the value
provided by the sequence. The `for` statement is looping over the results
from the `items() <iterators.html#items.i,seq[T]>`_ iterator from the `system
<system.html>`_ module. But if you use the two-variable form, the first
from the [items()](iterators.html#items.i,seq[T]) iterator from the [system](
system.html) module. But if you use the two-variable form, the first
variable will hold the index position and the second variable will hold the
value. Here the `for` statement is looping over the results from the
`pairs() <iterators.html#pairs.i,seq[T]>`_ iterator from the `system
<system.html>`_ module. Examples:
[pairs()](iterators.html#pairs.i,seq[T]) iterator from the [system](
system.html) module. Examples:
```nim test = "nim c $1"
for value in @[3, 4, 5]:
@@ -1412,8 +1413,8 @@ Open arrays
Often fixed-size arrays turn out to be too inflexible; procedures should be
able to deal with arrays of different sizes. The `openarray`:idx: type allows
this. Openarrays are always indexed with an `int` starting at position 0.
The `len <system.html#len,TOpenArray>`_, `low <system.html#low,openArray[T]>`_
and `high <system.html#high,openArray[T]>`_ operations are available for open
The [len](system.html#len,TOpenArray), [low](system.html#low,openArray[T])
and [high](system.html#high,openArray[T]) operations are available for open
arrays too. Any array with a compatible base type can be passed to an
openarray parameter, the index type does not matter.
@@ -1471,8 +1472,8 @@ type conversions in this context:
myWriteln(stdout, [$123, $"abc", $4.0])
```
In this example `$ <dollars.html>`_ is applied to any argument that is passed
to the parameter `a`. Note that `$ <dollars.html>`_ applied to strings is a
In this example [$](dollars.html) is applied to any argument that is passed
to the parameter `a`. Note that [$](dollars.html) applied to strings is a
nop.
@@ -1515,7 +1516,7 @@ indices are
where `b[0 .. ^1]` is equivalent to `b[0 .. b.len-1]` and `b[0 ..< b.len]`, and it
can be seen that the `^1` provides a shorthand way of specifying the `b.len-1`. See
the `backwards index operator <system.html#^.t%2Cint>`_.
the [backwards index operator](system.html#^.t%2Cint).
In the above example, because the string ends in a period, to get the portion of the
string that is "useless" and replace it with "useful".
@@ -1526,7 +1527,7 @@ string that is "useless" and replace it with "useful".
Note 1: alternate ways of writing this are `b[^8 .. ^2] = "useful"` or
as `b[11 .. b.len-2] = "useful"` or as `b[11 ..< b.len-1] = "useful"`.
Note 2: As the `^` template returns a `distinct int <manual.html#types-distinct-type>`_
Note 2: As the `^` template returns a [distinct int](manual.html#types-distinct-type)
of type `BackwardsIndex`, we can have a `lastIndex` constant defined as `const lastIndex = ^1`,
and later used as `b[0 .. lastIndex]`.
@@ -1659,8 +1660,8 @@ having the same field types.
Tuples can be *unpacked* during variable assignment. This can
be handy to assign directly the fields of the tuples to individually named
variables. An example of this is the `splitFile <os.html#splitFile,string>`_
proc from the `os module <os.html>`_ which returns the directory, name, and
variables. An example of this is the [splitFile](os.html#splitFile,string)
proc from the [os module](os.html) which returns the directory, name, and
extension of a path at the same time. For tuple unpacking to work you must
use parentheses around the values you want to assign the unpacking to,
otherwise, you will be assigning the same value to all the individual
@@ -1743,7 +1744,7 @@ To allocate a new traced object, the built-in procedure `new` can be used:
```
To deal with untraced memory, the procedures `alloc`, `dealloc` and
`realloc` can be used. The `system <system.html>`_
`realloc` can be used. The [system](system.html)
module's documentation contains further details.
If a reference points to *nothing*, it has the value `nil`.
@@ -1776,7 +1777,7 @@ Example:
A subtle issue with procedural types is that the calling convention of the
procedure influences the type compatibility: procedural types are only compatible
if they have the same calling convention. The different calling conventions are
listed in the `manual <manual.html#types-procedural-type>`_.
listed in the [manual](manual.html#types-procedural-type).
Distinct type
-------------
@@ -1786,7 +1787,7 @@ subtype relationship between it and its base type".
You must **explicitly** define all behavior for the distinct type.
To help with this, both the distinct type and its base type can cast from one
type to the other.
Examples are provided in the `manual <manual.html#types-distinct-type>`_.
Examples are provided in the [manual](manual.html#types-distinct-type).
Modules
=======
@@ -1940,7 +1941,7 @@ Part 2
======
So, now that we are done with the basics, let's see what Nim offers apart
from a nice syntax for procedural programming: `Part II <tut2.html>`_
from a nice syntax for procedural programming: [Part II](tut2.html)
.. _strutils: strutils.html

18
doc/tut2.md
View File

@@ -17,7 +17,7 @@ Introduction
This document is a tutorial for the advanced constructs of the *Nim*
programming language. **Note that this document is somewhat obsolete as the**
`manual <manual.html>`_ **contains many more examples of the advanced language
[manual](manual.html) **contains many more examples of the advanced language
features.**
@@ -27,8 +27,8 @@ Pragmas
Pragmas are Nim's method to give the compiler additional information/
commands without introducing a massive number of new keywords. Pragmas are
enclosed in the special `{.` and `.}` curly dot brackets. This tutorial
does not cover pragmas. See the `manual <manual.html#pragmas>`_ or `user guide
<nimc.html#additional-features>`_ for a description of the available
does not cover pragmas. See the [manual](manual.html#pragmas) or [user guide](
nimc.html#additional-features) for a description of the available
pragmas.
@@ -337,7 +337,7 @@ Exceptions
==========
In Nim exceptions are objects. By convention, exception types are
suffixed with 'Error'. The `system <system.html>`_ module defines an
suffixed with 'Error'. The [system](system.html) module defines an
exception hierarchy that you might want to stick to. Exceptions derive from
`system.Exception`, which provides the common interface.
@@ -417,9 +417,9 @@ the rest of the procedure - that is not within a `finally` clause -
is not executed (if an exception occurs).
If you need to *access* the actual exception object or message inside an
`except` branch you can use the `getCurrentException()
<system.html#getCurrentException>`_ and `getCurrentExceptionMsg()
<system.html#getCurrentExceptionMsg>`_ procs from the `system <system.html>`_
`except` branch you can use the [getCurrentException()](
system.html#getCurrentException) and [getCurrentExceptionMsg()](
system.html#getCurrentExceptionMsg) procs from the [system](system.html)
module. Example:
```nim
@@ -464,7 +464,7 @@ tracking is part of Nim's effect system). Another more roundabout way to
find out the list of exceptions raised by a proc is to use the Nim ``doc``
command which generates documentation for a whole module and decorates all
procs with the list of raised exceptions. You can read more about Nim's
`effect system and related pragmas in the manual <manual.html#effect-system>`_.
[effect system and related pragmas in the manual](manual.html#effect-system).
Generics
@@ -694,4 +694,4 @@ JavaScript-compatible code you should remember the following:
Part 3
======
The next part is entirely about metaprogramming via macros: `Part III <tut3.html>`_
The next part is entirely about metaprogramming via macros: [Part III](tut3.html).

8
doc/tut3.md
View File

@@ -125,7 +125,7 @@ The Syntax Tree
In order to build a Nim syntax tree one needs to know how Nim source
code is represented as a syntax tree, and how such a tree needs to
look like so that the Nim compiler will understand it. The nodes of the
Nim syntax tree are documented in the `macros <macros.html>`_ module.
Nim syntax tree are documented in the [macros](macros.html) module.
But a more interactive way to explore the Nim
syntax tree is with `macros.treeRepr`, it converts a syntax tree
into a multi-line string for printing on the console. It can be used
@@ -366,7 +366,7 @@ recommended way. But still `strformat` is a good example for a
practical use case for a macro that is slightly more complex than the
`assert` macro.
`Strformat <https://github.com/nim-lang/Nim/blob/5845716df8c96157a047c2bd6bcdd795a7a2b9b1/lib/pure/strformat.nim#L280>`_
[Strformat](https://github.com/nim-lang/Nim/blob/5845716df8c96157a047c2bd6bcdd795a7a2b9b1/lib/pure/strformat.nim#L280)
Ast Pattern Matching
--------------------
@@ -375,7 +375,7 @@ Ast Pattern Matching is a macro library to aid in writing complex
macros. This can be seen as a good example of how to repurpose the
Nim syntax tree with new semantics.
`Ast Pattern Matching <https://github.com/krux02/ast-pattern-matching>`_
[Ast Pattern Matching](https://github.com/krux02/ast-pattern-matching)
OpenGL Sandbox
--------------
@@ -384,4 +384,4 @@ This project has a working Nim to GLSL compiler written entirely in
macros. It scans recursively through all used function symbols to
compile them so that cross library functions can be executed on the GPU.
`OpenGL Sandbox <https://github.com/krux02/opengl-sandbox>`_
[OpenGL Sandbox](https://github.com/krux02/opengl-sandbox)

6
lib/packages/docutils/rst.nim
View File

@@ -3578,7 +3578,7 @@ proc resolveLink(s: PRstSharedState, n: PRstNode) : PRstNode =
target: newLeaf(subst.refname),
info: subst.info, tooltip: subst.tooltip)
foundLinks.sort(cmp = cmp, order = Descending)
let linkText = addNodes(desc)
let aliasStr = addNodes(alias)
if foundLinks.len >= 1:
let kind = if foundLinks[0].ar == arHyperlink: rnHyperlink
elif foundLinks[0].ar == arNim: rnNimdocRef
@@ -3598,10 +3598,10 @@ proc resolveLink(s: PRstSharedState, n: PRstNode) : PRstNode =
targets.add t
rstMessage(s.filenames, s.msgHandler, n.info, mwAmbiguousLink,
"`$1`\n clash:\n$2" % [
linkText, targets.join("\n")])
aliasStr, targets.join("\n")])
else: # nothing found
result = n
rstMessage(s.filenames, s.msgHandler, n.info, mwBrokenLink, linkText)
rstMessage(s.filenames, s.msgHandler, n.info, mwBrokenLink, aliasStr)
proc resolveSubs*(s: PRstSharedState, n: PRstNode): PRstNode =
## Makes pass 2 of RST parsing.

16
tests/stdlib/trst.nim
View File

@@ -1181,6 +1181,22 @@ suite "Warnings":
"input(9, 6) Warning: broken link 'short.link'"
])
test "Pandoc Markdown concise link warning points to target":
var warnings = new seq[string]
check(
"ref [here][target]".toAst(warnings=warnings) ==
dedent"""
rnInner
rnLeaf 'ref'
rnLeaf ' '
rnPandocRef
rnInner
rnLeaf 'here'
rnInner
rnLeaf 'target'
""")
check warnings[] == @["input(1, 12) Warning: broken link 'target'"]
test "With include directive and blank lines at the beginning":
"other.rst".writeFile(dedent"""