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

follow-up #18013 - inline syntax highlighting (#18166)

Browse Source
This commit is contained in:
Andrey Makarov
2021-06-04 17:16:51 +03:00
committed by GitHub
parent 654a20166e
commit 7e21218a07
20 changed files with 183 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/destructors.rst
View File

@@ -5,8 +5,8 @@ Nim Destructors and Move Semantics
:Authors: Andreas Rumpf
:Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. default-role:: nim
.. contents::

2
doc/docgen.rst
View File

@@ -5,8 +5,8 @@
:Author: Erik O'Leary
:Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. default-role:: Nim
.. contents::

4
doc/drnim.rst
View File

@@ -5,8 +5,8 @@
:Author: Andreas Rumpf
:Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. default-role:: Nim
.. contents::
@@ -43,7 +43,7 @@ your code.
Installation
============
Run `koch drnim`:option:, the executable will afterwards be
Run `koch drnim`:cmd:, the executable will afterwards be
in ``$nim/bin/drnim``.

2
doc/estp.rst
View File

@@ -2,8 +2,8 @@
Embedded Stack Trace Profiler (ESTP) User Guide
===================================================
.. default-role:: code
.. include:: rstcommon.rst
.. default-role:: Nim
:Author: Andreas Rumpf
:Version: |nimversion|

31
doc/hcr.rst
View File

@@ -1,9 +1,10 @@
.. default-role:: code
===================================
Hot code reloading
===================================
.. default-role:: code
.. include:: rstcommon.rst
The `hotCodeReloading`:idx: option enables special compilation mode where
changes in the code can be applied automatically to a running program.
The code reloading happens at the granularity of an individual module.
@@ -22,7 +23,7 @@ during development resides.
In this example, we use SDL2 to create a window and we reload the logic
code when `F9` is pressed. The important lines are marked with `#***`.
To install SDL2 you can use `nimble install sdl2`.
To install SDL2 you can use `nimble install sdl2`:cmd:.
.. code-block:: nim
@@ -98,34 +99,40 @@ To install SDL2 you can use `nimble install sdl2`.
main()
Compile this example via::
Compile this example via:
```cmd
nim c --hotcodereloading:on mymain.nim
```
Now start the program and KEEP it running!
::
.. code:: cmd
# Unix:
mymain &
# or Windows (click on the .exe)
mymain.exe
# edit
For example, change the line::
For example, change the line:
```nim
discard renderer.setDrawColor(255, 128, 128, 0)
```
into::
into:
```nim
discard renderer.setDrawColor(255, 255, 128, 0)
```
(This will change the color of the rectangle.)
Then recompile the project, but do not restart or quit the mymain.exe program!
::
```cmd
nim c --hotcodereloading:on mymain.nim
```
Now give the `mymain` SDL window the focus, press F9, and watch the
updated version of the program.
@@ -188,15 +195,15 @@ Native code targets
===================
Native projects using the hot code reloading option will be implicitly
compiled with the `-d:useNimRtl` option and they will depend on both
compiled with the `-d:useNimRtl`:option: option and they will depend on both
the `nimrtl` library and the `nimhcr` library which implements the
hot code reloading run-time. Both libraries can be found in the `lib`
folder of Nim and can be compiled into dynamic libraries to satisfy
runtime demands of the example code above. An example of compiling
`nimhcr.nim` and `nimrtl.nim` when the source dir of Nim is installed
``nimhcr.nim`` and ``nimrtl.nim`` when the source dir of Nim is installed
with choosenim follows.
::
.. code:: console
# Unix/MacOS
# Make sure you are in the directory containing your .nim files

2
doc/intern.rst
View File

@@ -6,8 +6,8 @@
:Author: Andreas Rumpf
:Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. default-role:: Nim
.. contents::
"Abstraction is layering ignorance on top of reality." -- Richard Gabriel

27
doc/koch.rst
View File

@@ -1,11 +1,11 @@
.. default-role:: code
===============================
Nim maintenance script
===============================
:Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. contents::
.. raw:: html
@@ -19,7 +19,7 @@ Introduction
The `koch`:idx: program is Nim's maintenance script. It is a replacement
for make and shell scripting with the advantage that it is much more portable.
The word *koch* means *cook* in German. `koch` is used mainly to build the
The word *koch* means *cook* in German. `koch`:cmd: is used mainly to build the
Nim compiler, but it can also be used for other tasks. This document
describes the supported commands and their options.
@@ -33,12 +33,11 @@ boot command
The `boot`:idx: command bootstraps the compiler, and it accepts different
options:
-d:release
By default a debug version is created, passing this option will
-d:release By default a debug version is created, passing this option will
force a release build, which is much faster and should be preferred
unless you are debugging the compiler.
-d:nimUseLinenoise
Use the linenoise library for interactive mode (not needed on Windows).
-d:nimUseLinenoise Use the linenoise library for interactive mode
(not needed on Windows).
After compilation is finished you will hopefully end up with the nim
compiler in the `bin` directory. You can add Nim's `bin` directory to
@@ -56,16 +55,16 @@ temp command
------------
The temp command builds the Nim compiler but with a different final name
(`nim_temp`), so it doesn't overwrite your normal compiler. You can use
(`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>`_.
test command
------------
The `test`:idx: command can also be invoked with the alias `tests`. This
command will compile and run `testament/tester.nim`, which is the main
driver of Nim's test suite. You can pass options to the `test` command,
The `test`:idx: command can also be invoked with the alias `tests`:option:. This
command will compile and run ``testament/tester.nim``, which is the main
driver of Nim's test suite. You can pass options to the `test`:option: command,
they will be forwarded to the tester. See its source code for available
options.
@@ -74,13 +73,13 @@ web command
The `web`:idx: command converts the documentation in the `doc` directory
from rst to HTML. It also repeats the same operation but places the result in
the `web/upload` which can be used to update the website at
the ``web/upload`` which can be used to update the website at
https://nim-lang.org.
By default, the documentation will be built in parallel using the number of
available CPU cores. If any documentation build sub-commands fail, they will
be rerun in serial fashion so that meaningful error output can be gathered for
inspection. The `--parallelBuild:n` switch or configuration option can be
inspection. The `--parallelBuild:n`:option: switch or configuration option can be
used to force a specific number of parallel jobs or run everything serially
from the start (`n == 1`).
@@ -89,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/pdflatex <https://www.latex-project.org/get>`_ first.
`install Latex/xelatex <https://www.latex-project.org/get>`_ first.

12
doc/lib.rst
View File

@@ -1,5 +1,3 @@
.. default-role:: code
====================
Nim Standard Library
====================
@@ -7,11 +5,13 @@ Nim Standard Library
:Author: Andreas Rumpf
:Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. contents::
Nim's library is divided into *pure libraries*, *impure libraries*, and *wrappers*.
Pure libraries do not depend on any external `*.dll` or `lib*.so` binary
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.
@@ -39,11 +39,11 @@ Automatic imports
* `threads <threads.html>`_
Basic Nim thread support. **Note:** This is part of the system module. Do not
import it explicitly. Enabled with `--threads:on`.
import it explicitly. Enabled with `--threads:on`:option:.
* `channels <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`.
system module. Do not import it explicitly. Enabled with `--threads:on`:option:.
Core
@@ -366,7 +366,7 @@ Parsers
* `parsecfg <parsecfg.html>`_
The `parsecfg` module implements a high-performance configuration file
parser. The configuration file's syntax is similar to the Windows `.ini`
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.

48
doc/manual.rst
View File

@@ -572,7 +572,8 @@ In the following examples, `-1` is a single token:
"abc";-1
In the following examples, `-1` is parsed as two separate tokens (as `- 1`):
In the following examples, `-1` is parsed as two separate tokens
(as `-`:tok: `1`:tok:):
.. code-block:: nim
@@ -2509,7 +2510,7 @@ of the argument.
range.
3. Generic match: `f` is a generic type and `a` matches, for
instance `a` is `int` and `f` is a generic (constrained) parameter
type (like in `[T]` or `[T: int|char]`.
type (like in `[T]` or `[T: int|char]`).
4. Subrange or subtype match: `a` is a `range[T]` and `T`
matches `f` exactly. Or: `a` is a subtype of `f`.
5. Integral conversion match: `a` is convertible to `f` and `f` and `a`
@@ -3840,7 +3841,7 @@ Type bound operators currently include:
(some of which are still implementation defined and not yet documented).
For more details on some of those procs, see
`lifetimeminustracking-hooks <destructors.html#lifetimeminustracking-hooks>`_.
`Lifetime-tracking hooks <destructors.html#lifetimeminustracking-hooks>`_.
Nonoverloadable builtins
------------------------
@@ -5283,7 +5284,7 @@ instantiations cross multiple different modules:
In module B has an `init` proc from module C in its scope that is not
taken into account when `genericB` is instantiated which leads to the
instantiation of `genericA`. The solution is to `forward`:idx these
instantiation of `genericA`. The solution is to `forward`:idx: these
symbols by a `bind` statement inside `genericB`.
@@ -7305,19 +7306,19 @@ Produces:
supplied pattern to denote the concrete type parameters of the generic type.
See the usage of the apostrophe operator in proc patterns for more details.
.. code-block:: nim
.. code-block:: nim
type
VectorIterator {.importcpp: "std::vector<'0>::iterator".} [T] = object
type
VectorIterator {.importcpp: "std::vector<'0>::iterator".} [T] = object
var x: VectorIterator[cint]
var x: VectorIterator[cint]
Produces:
Produces:
.. code-block:: C
.. code-block:: C
std::vector<int>::iterator x;
std::vector<int>::iterator x;
ImportJs pragma
@@ -7444,7 +7445,7 @@ compile-time define pragmas
---------------------------
The pragmas listed here can be used to optionally accept values from
the -d/--define option at compile time.
the `-d/--define`:option: option at compile time.
The implementation currently provides the following possible options (various
others may be added later).
@@ -7461,7 +7462,7 @@ pragma description
const FooBar {.intdefine.}: int = 5
echo FooBar
::
.. code:: cmd
nim c -d:FooBar=42 foobar.nim
In the above example, providing the `-d`:option: flag causes the symbol
@@ -7480,7 +7481,8 @@ pragma pragma
-------------
The `pragma` pragma can be used to declare user-defined pragmas. This is
useful because Nim's templates and macros do not affect pragmas. User-defined pragmas are in a different module-wide scope than all other symbols.
useful because Nim's templates and macros do not affect pragmas.
User-defined pragmas are in a different module-wide scope than all other symbols.
They cannot be imported from a module.
Example:
@@ -7553,18 +7555,18 @@ More examples with custom pragmas:
- Better serialization/deserialization control:
.. code-block:: nim
type MyObj = object
a {.dontSerialize.}: int
b {.defaultDeserialize: 5.}: int
c {.serializationKey: "_c".}: string
.. code-block:: nim
type MyObj = object
a {.dontSerialize.}: int
b {.defaultDeserialize: 5.}: int
c {.serializationKey: "_c".}: string
- Adopting type for gui inspector in a game engine:
.. code-block:: nim
type MyComponent = object
position {.editable, animatable.}: Vector3
alpha {.editRange: [0.0..1.0], animatable.}: float32
.. code-block:: nim
type MyComponent = object
position {.editable, animatable.}: Vector3
alpha {.editRange: [0.0..1.0], animatable.}: float32
Macro pragmas

20
doc/manual_experimental.rst
View File

@@ -1,5 +1,3 @@
.. default-role:: code
=========================
Nim Experimental Features
=========================
@@ -7,6 +5,8 @@ Nim Experimental Features
:Authors: Andreas Rumpf
:Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. contents::
@@ -15,7 +15,7 @@ About this document
This document describes features of Nim that are to be considered experimental.
Some of these are not covered by the `.experimental` pragma or
`--experimental` switch because they are already behind a special syntax and
`--experimental`:option: switch because they are already behind a special syntax and
one may want to use Nim libraries using these features without using them
oneself.
@@ -1109,7 +1109,7 @@ The `parameter constraint`:idx: expression can use the operators `|` (or),
Predicate Meaning
=================== =====================================================
`atom` The matching node has no children.
`lit` The matching node is a literal like "abc", 12.
`lit` The matching node is a literal like `"abc"`, `12`.
`sym` The matching node must be a symbol (a bound
identifier).
`ident` The matching node must be an identifier (an unbound
@@ -1185,7 +1185,7 @@ constant folding, so the following does not work:
The reason is that the compiler already transformed the 1 into "1" for
the `echo` statement. However, a term rewriting macro should not change the
semantics anyway. In fact they can be deactivated with the `--patterns:off`
semantics anyway. In fact they can be deactivated with the `--patterns:off`:option:
command line option or temporarily with the `patterns` pragma.
@@ -1779,7 +1779,7 @@ Noalias annotation
==================
Since version 1.4 of the Nim compiler, there is a `.noalias` annotation for variables
and parameters. It is mapped directly to C/C++'s `restrict` keyword and means that
and parameters. It is mapped directly to C/C++'s `restrict`:c: keyword and means that
the underlying pointer is pointing to a unique location in memory, no other aliases to
this location exist. It is *unchecked* that this alias restriction is followed, if the
restriction is violated, the backend optimizer is free to miscompile the code.
@@ -1832,8 +1832,8 @@ the `view types section <#view-types-algorithm>`_.
View types
==========
**Note**: `--experimental:views` is more effective
with `--experimental:strictFuncs`.
**Note**: `--experimental:views`:option: is more effective
with `--experimental:strictFuncs`:option:.
A view type is a type that is or contains one of the following types:
@@ -1981,8 +1981,8 @@ 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>`_
feature. In other words `--experimental:views` works better
with `--experimental:strictFuncs`.
feature. In other words `--experimental:views`:option: works better
with `--experimental:strictFuncs`:option:.
The analysis is currently control flow insensitive:

26
doc/manual_experimental_strictnotnil.rst
View File

@@ -1,8 +1,9 @@
.. default-role:: code
Strict not nil checking
=========================
.. default-role:: code
.. include:: rstcommon.rst
**Note:** This feature is experimental, you need to enable it with
.. code-block:: nim
@@ -10,7 +11,7 @@ Strict not nil checking
or
.. code-block:: bash
.. code-block:: cmd
nim c --experimental:strictNotNil <program>
In the second case it would check builtin and imported modules as well.
@@ -60,14 +61,16 @@ You can annotate a type where nil isn't a valid value with `not nil`.
If a type can include `nil` as a valid value, dereferencing values of the type
is checked by the compiler: if a value which might be nil is derefenced, this produces a warning by default, you can turn this into an error using the compiler options `--warningAsError:strictNotNil`
is checked by the compiler: if a value which might be nil is derefenced, this
produces a warning by default, you can turn this into an error using
the compiler options `--warningAsError:strictNotNil`:option:.
If a type is nilable, you should dereference its values only after a `isNil` or equivalent check.
local turn on/off
---------------------
You can still turn off nil checking on function/module level by using a `{.strictNotNil: off}.` pragma.
You can still turn off nil checking on function/module level by using a `{.strictNotNil: off.}` pragma.
Note: test that/TODO for code/manual.
nilability state
@@ -75,11 +78,14 @@ nilability state
Currently a nilable value can be `Safe`, `MaybeNil` or `Nil` : we use internally `Parent` and `Unreachable` but this is an implementation detail(a parent layer has the actual nilability).
`Safe` means it shouldn't be nil at that point: e.g. after assignment to a non-nil value or `not a.isNil` check
`MaybeNil` means it might be nil, but it might not be nil: e.g. an argument, a call argument or a value after an `if` and `else`.
`Nil` means it should be nil at that point; e.g. after an assignment to `nil` or a `.isNil` check.
`Unreachable` means it shouldn't be possible to access this in this branch: so we do generate a warning as well.
- `Safe` means it shouldn't be nil at that point: e.g. after assignment to
a non-nil value or `not a.isNil` check
- `MaybeNil` means it might be nil, but it might not be nil: e.g. an argument,
a call argument or a value after an `if` and `else`.
- `Nil` means it should be nil at that point; e.g. after an assignment to
`nil` or a `.isNil` check.
- `Unreachable` means it shouldn't be possible to access this in this branch:
so we do generate a warning as well.
We show an error for each dereference (`[]`, `.field`, `[index]` `()` etc) which is of a tracked expression which is
in `MaybeNil` or `Nil` state.

11
doc/nep1.rst
View File

@@ -1,11 +1,12 @@
.. default-role:: code
==========================================================
Nim Enhancement Proposal #1 - Standard Library Style Guide
==========================================================
:Author: Clay Sweetser, Dominik Picheta
:Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. contents::
@@ -139,7 +140,7 @@ Naming Conventions
- rotate and rotated
- When the 'returns transformed copy' version already exists like `strutils.replace`
an in-place version should get an `-In` suffix (`replaceIn` for this example).
an in-place version should get an ``-In`` suffix (`replaceIn` for this example).
- Use `subjectVerb`, not `verbSubject`, e.g.: `fileExists`, not `existsFile`.
@@ -225,8 +226,8 @@ indentation indent
Coding Conventions
------------------
- The 'return' statement should ideally be used when its control-flow properties
are required. Use a procedure's implicit 'result' variable whenever possible.
- The `return` statement should ideally be used when its control-flow properties
are required. Use a procedure's implicit `result` variable whenever possible.
This improves readability.
.. code-block:: nim

31
doc/nimgrep.rst
View File

@@ -1,14 +1,11 @@
.. default-role:: code
=========================
nimgrep User's manual
=========================
.. default-role:: literal
:Author: Andreas Rumpf
:Version: 1.6.0
.. default-role:: option
.. contents::
Nimgrep is a command line tool for search and replace tasks. It can search for
@@ -23,11 +20,12 @@ Apart from that it is a generic text manipulation tool.
Installation
============
Compile nimgrep with the command::
Compile nimgrep with the command:
.. code:: cmd
nim c -d:release tools/nimgrep.nim
And copy the executable somewhere in your `$PATH`.
And copy the executable somewhere in your ``$PATH``.
Command line switches
@@ -40,31 +38,32 @@ Examples
All examples below use default PCRE Regex patterns:
+ To search recursively in Nim files using style-insensitive identifiers::
+ To search recursively in Nim files using style-insensitive identifiers:
--recursive --ext:'nim|nims' --ignoreStyle
.. code:: cmd
nimgrep --recursive --ext:'nim|nims' --ignoreStyle
# short: -r --ext:'nim|nims' -y
.. Note:: we used `'` quotes to avoid special treatment of `|` symbol
for shells like Bash
+ To exclude version control directories (Git, Mercurial=hg, Subversion=svn)
from the search::
from the search:
--excludeDir:'^\.git$' --excludeDir:'^\.hg$' --excludeDir:'^\.svn$'
.. code:: cmd
nimgrep --excludeDir:'^\.git$' --excludeDir:'^\.hg$' --excludeDir:'^\.svn$'
# short: --ed:'^\.git$' --ed:'^\.hg$' --ed:'^\.svn$'
+ To search only in paths containing the `tests` sub-directory recursively::
--recursive --includeDir:'(^|/)tests($|/)'
.. code:: cmd
nimgrep --recursive --includeDir:'(^|/)tests($|/)'
# short: -r --id:'(^|/)tests($|/)'
.. Attention:: note the subtle difference between `--excludeDir` and
`--includeDir`: the former is applied to relative directory entries
.. Attention:: note the subtle difference between `--excludeDir`:option: and
`--includeDir`:option:\: the former is applied to relative directory entries
and the latter is applied to the whole paths
+ Nimgrep can search multi-line, e.g. to find files containing `import`
and then `strutils` use::
'import(.|\n)*?strutils'
and then `strutils` use pattern `'import(.|\n)*?strutils'`:option:.

24
doc/niminst.rst
View File

@@ -1,5 +1,3 @@
.. default-role:: code
=========================
niminst User's manual
=========================
@@ -7,6 +5,8 @@
:Author: Andreas Rumpf
:Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. contents::
Introduction
@@ -34,7 +34,7 @@ configuration file. Here's an example of how the syntax looks like:
The value of a key-value pair can reference user-defined variables via
the `$variable` notation: They can be defined in the command line with the
`--var:name=value` switch. This is useful to not hard-coding the
`--var:name=value`:option: switch. This is useful to not hard-coding the
program's version number into the configuration file, for instance.
It follows a description of each possible section and how it affects the
@@ -91,10 +91,10 @@ Documentation section
The `documentation` section supports the `files` key.
Listed files will be installed into the OS's native documentation directory
(which might be `$appdir/doc`).
(which might be ``$appdir/doc``).
There is a `start` key which determines whether the Windows installer
generates a link to e.g. the `index.html` of your documentation.
generates a link to e.g. the ``index.html`` of your documentation.
Other section
@@ -125,9 +125,9 @@ Other possible options are:
==================== =======================================================
Key description
==================== =======================================================
`BinPath` paths to add to the Windows `%PATH%` environment
`BinPath` paths to add to the Windows `%PATH%` environment
variable. Example: ``BinPath: r"bin;dist\mingw\bin"``
`InnoSetup` boolean flag whether an Inno Setup installer should be
`InnoSetup` boolean flag whether an Inno Setup installer should be
generated for Windows. Example: `InnoSetup: "Yes"`
==================== =======================================================
@@ -137,7 +137,7 @@ UnixBin section
The `UnixBin` section currently only supports the `files` key.
Listed files will be installed into the OS's native bin directory
(e.g. `/usr/local/bin`). The exact location depends on the
(e.g. ``/usr/local/bin``). The exact location depends on the
installation path the user specifies when running the `install.sh` script.
@@ -165,9 +165,9 @@ Possible options are:
==================== =======================================================
Key description
==================== =======================================================
`path` Path to Inno Setup.
`path` Path to Inno Setup.
Example: ``path = r"c:\inno setup 5\iscc.exe"``
`flags` Flags to pass to Inno Setup.
`flags` Flags to pass to Inno Setup.
Example: `flags = "/Q"`
==================== =======================================================
@@ -180,8 +180,8 @@ Possible options are:
==================== =======================================================
Key description
==================== =======================================================
`path` Path to the C compiler.
`flags` Flags to pass to the C Compiler.
`path` Path to the C compiler.
`flags` Flags to pass to the C Compiler.
Example: `flags = "-w"`
==================== =======================================================

45
doc/nims.rst
View File

@@ -1,32 +1,33 @@
.. default-role:: code
================================
NimScript
================================
.. default-role:: code
.. include:: rstcommon.rst
Strictly speaking, `NimScript` is the subset of Nim that can be evaluated
by Nim's builtin virtual machine (VM). This VM is used for Nim's compiletime
function evaluation features.
The `nim` executable processes the `.nims` configuration files in
The `nim`:cmd: executable processes the ``.nims`` configuration files in
the following directories (in this order; later files overwrite
previous settings):
1) If environment variable `XDG_CONFIG_HOME` is defined,
`$XDG_CONFIG_HOME/nim/config.nims` or
`~/.config/nim/config.nims` (POSIX) or
`%APPDATA%/nim/config.nims` (Windows). This file can be skipped
with the `--skipUserCfg` command line option.
2) `$parentDir/config.nims` where `$parentDir` stands for any
``$XDG_CONFIG_HOME/nim/config.nims`` or
``~/.config/nim/config.nims`` (POSIX) or
``%APPDATA%/nim/config.nims`` (Windows). This file can be skipped
with the `--skipUserCfg`:option: command line option.
2) ``$parentDir/config.nims`` where ``$parentDir`` stands for any
parent directory of the project file's path. These files can be
skipped with the `--skipParentCfg` command line option.
3) `$projectDir/config.nims` where `$projectDir` stands for the
project's path. This file can be skipped with the `--skipProjCfg`
skipped with the `--skipParentCfg`:option: command line option.
3) ``$projectDir/config.nims`` where ``$projectDir`` stands for the
project's path. This file can be skipped with the `--skipProjCfg`:option:
command line option.
4) A project can also have a project specific configuration file named
`$project.nims` that resides in the same directory as
`$project.nim`. This file can be skipped with the same
`--skipProjCfg` command line option.
``$project.nims`` that resides in the same directory as
``$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>`_.
@@ -111,8 +112,8 @@ See also:
NimScript as a configuration file
=================================
A command-line switch `--FOO` is written as `switch("FOO")` in
NimScript. Similarly, command-line `--FOO:VAL` translates to
A command-line switch `--FOO`:option: is written as `switch("FOO")` in
NimScript. Similarly, command-line `--FOO:VAL`:option: translates to
`switch("FOO", "VAL")`.
Here are few examples of using the `switch` proc:
@@ -125,7 +126,7 @@ Here are few examples of using the `switch` proc:
# command-line: --forceBuild
switch("forceBuild")
NimScripts also support `--` templates for convenience, which look
NimScripts also support `--`:option: templates for convenience, which look
like command-line switches written as-is in the NimScript file. So the
above example can be rewritten as:
@@ -136,7 +137,7 @@ above example can be rewritten as:
**Note**: In general, the *define* switches can also be set in
NimScripts using `switch` or `--`, as shown in above
examples. Only the `release` define (`-d:release`) cannot be set
examples. Only the `release` define (`-d:release`:option:) cannot be set
in NimScripts.
@@ -145,7 +146,7 @@ NimScript as a build tool
The `task` template that the `system` module defines allows a NimScript
file to be used as a build tool. The following example defines a
task `build` that is an alias for the `c` command:
task `build` that is an alias for the `c`:option: command:
.. code-block:: nim
task build, "builds an example":
@@ -159,7 +160,7 @@ Task Description
========= ===================================================
`help` List all the available NimScript tasks along with their docstrings.
`build` Build the project with the required
backend (`c`, `cpp` or `js`).
backend (`c`:option:, `cpp`:option: or `js`:option:).
`tests` Runs the tests belonging to the project.
`bench` Runs benchmarks belonging to the project.
========= ===================================================
@@ -180,7 +181,7 @@ Standalone NimScript
====================
NimScript can also be used directly as a portable replacement for Bash and
Batch files. Use `nim myscript.nims` to run `myscript.nims`. For example,
Batch files. Use `nim myscript.nims`:cmd: to run ``myscript.nims``. For example,
installation of Nimble could be accomplished with this simple script:
.. code-block:: nim
@@ -199,7 +200,7 @@ installation of Nimble could be accomplished with this simple script:
mvFile "nimble" & $id & "/src/nimble".toExe, "bin/nimble".toExe
On Unix, you can also use the shebang `#!/usr/bin/env nim`, as long as your filename
ends with `.nims`:
ends with ``.nims``:
.. code-block:: nim

37
doc/nimsuggest.rst
View File

@@ -1,5 +1,3 @@
.. default-role:: code
================================
Nim IDE Integration Guide
================================
@@ -7,14 +5,16 @@
:Author: Unknown
:Version: |nimversion|
.. default-role:: code
.. include:: rstcommon.rst
.. contents::
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
`nimsuggest` tool, any IDE
can query a `.nim` source file and obtain useful information like
`nimsuggest`:cmd: tool, 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
@@ -27,29 +27,30 @@ already available.
Installation
============
Nimsuggest is part of Nim's core. Build it via::
Nimsuggest is part of Nim's core. Build it via:
.. code:: cmd
koch nimsuggest
Nimsuggest invocation
=====================
Run it via `nimsuggest --stdin --debug myproject.nim`. Nimsuggest is a
Run it via `nimsuggest --stdin --debug myproject.nim`:cmd:. Nimsuggest is a
server that takes queries that are related to `myproject`. There is some
support so that you can throw random `.nim` files which are not part
support so that you can throw random ``.nim`` files which are not part
of `myproject` at Nimsuggest too, but usually the query refer to modules/files
that are part of `myproject`.
`--stdin` means that Nimsuggest reads the query from `stdin`. This is great
`--stdin`:option: means that Nimsuggest reads the query from `stdin`. This is great
for testing things out and playing with it but for an editor communication
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` flags and
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>`_
can be used to specify additional dependencies like
`nimsuggest --stdin --debug --path:"dependencies" myproject.nim`.
`nimsuggest --stdin --debug --path:"dependencies" myproject.nim`:cmd:.
Specifying the location of the query
@@ -60,25 +61,25 @@ cryptic 3 letter "command" `def` or `con` or `sug` or `use` followed by
a location. A query location consists of:
`file.nim`
``file.nim``
This is the name of the module or include file the query refers to.
`dirtyfile.nim`
``dirtyfile.nim``
This is optional.
The `file` parameter is enough for static analysis, but IDEs
tend to have *unsaved buffers* where the user may still be in
the middle of typing a line. In such situations the IDE can
save the current contents to a temporary file and then use the
`dirtyfile.nim` option to tell Nimsuggest that `foobar.nim` should
be taken from `temporary/foobar.nim`.
``dirtyfile.nim`` option to tell Nimsuggest that ``foobar.nim`` should
be taken from ``temporary/foobar.nim``.
`line`
``line``
An integer with the line you are going to query. For the compiler
lines start at **1**.
`col`
``col``
An integer with the column you are going to query. For the
compiler columns start at **0**.
@@ -149,9 +150,9 @@ tab characters (``\t``). The values of each column are:
1. Three characters indicating the type of returned answer (e.g.
`def` for definition, `sug` for suggestion, etc).
2. Type of the symbol. This can be `skProc`, `skLet`, and just
about any of the enums defined in the module `compiler/ast.nim`.
about any of the enums defined in the module ``compiler/ast.nim``.
3. Fully qualified path of the symbol. If you are querying a symbol
defined in the `proj.nim` file, this would have the form
defined in the ``proj.nim`` file, this would have the form
`proj.symbolName`.
4. Type/signature. For variables and enums this will contain the
type of the symbol, for procs, methods and templates this will

2
doc/packaging.rst
View File

@@ -45,7 +45,7 @@ The Debian package ships bash and ksh completion and manpages that can be reused
Hints on the build process:
::
.. code:: cmd
# build from C sources and then using koch
./build.sh --os $os_type --cpu $cpu_arch

4
doc/regexprs.txt
View File

@@ -47,9 +47,11 @@ full documentation of Perl's regular expressions.
Because the backslash ``\`` is a meta character both in the Nim
programming language and in regular expressions, it is strongly
recommended that one uses the *raw* strings of Nim, so that
backslashes are interpreted by the regular expression engine::
backslashes are interpreted by the regular expression engine:
```nim
r"\S" # matches any character that is not whitespace
```
A regular expression is a pattern that is matched against a subject string
from left to right. Most characters stand for themselves in a pattern, and

2
doc/testament.rst
View File

@@ -2,8 +2,8 @@
Testament
===========
.. default-role:: code
.. include:: rstcommon.rst
.. default-role:: nim
.. contents::
Testament is an advanced automatic unittests runner for Nim tests, is used for the development of Nim itself,

15
doc/tools.rst
View File

@@ -1,9 +1,10 @@
.. default-role:: code
========================
Tools available with Nim
========================
.. default-role:: code
.. include:: rstcommon.rst
The standard distribution ships with the following tools:
- | `Hot code reloading <hcr.html>`_
@@ -11,11 +12,11 @@ The standard distribution ships with the following tools:
document explaining how it works.
- | `Documentation generator <docgen.html>`_
| The builtin document generator `nim doc` generates HTML documentation
from `.nim` source files.
| The builtin document generator `nim doc`:cmd: generates HTML documentation
from ``.nim`` source files.
- | `Nimsuggest for IDE support <nimsuggest.html>`_
| Through the `nimsuggest` tool, any IDE can query a `.nim` source file
| 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.
@@ -29,11 +30,11 @@ The standard distribution ships with the following tools:
| Nim search and replace utility.
- | nimpretty
| `nimpretty` is a Nim source code beautifier,
| `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` is an advanced automatic *unittests runner* for Nim tests,
| `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)>`_,