mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2025-12-28 17:04:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

follow-up #17837: add Console for interactive sessions (#17930)

Browse Source 
* follow-up #17837: add `Console` for interactive sessions

* fix Latex
This commit is contained in:
Andrey Makarov
2021-05-06 11:58:01 +03:00
committed by GitHub
parent 706562f661
commit 436af88d8c
14 changed files with 252 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
config/nimdoc.tex.cfg
View File

@@ -137,6 +137,8 @@ bottomline=false}
\newcommand{\spanReference}[1]{#1}
\newcommand{\spanOther}[1]{#1}
\newcommand{\spantok}[1]{\frame{#1}}
\newcommand{\spanPrompt}[1]{\textcolor{red}{\textbf{#1}}}
\newcommand{\spanProgramOutput}[1]{\textcolor{gray}{\textbf{#1}}}
\newcommand{\spanprogram}[1]{\textbf{\underline{#1}}}
\newcommand{\spanoption}[1]{\textbf{#1}}

15
doc/destructors.rst
View File

@@ -1,5 +1,3 @@
.. default-role:: code
==================================
Nim Destructors and Move Semantics
==================================
@@ -7,6 +5,8 @@ Nim Destructors and Move Semantics
:Authors: Andreas Rumpf
:Version: |nimversion|
.. include:: rstcommon.rst
.. default-role:: nim
.. contents::
@@ -273,7 +273,7 @@ Sink parameter inference
========================
The current implementation can do a limited form of sink parameter
inference. But it has to be enabled via `--sinkInference:on`, either
inference. But it has to be enabled via `--sinkInference:on`:option:, either
on the command line or via a `push` pragma.
To enable it for a section of code, one can
@@ -496,10 +496,11 @@ for expressions of type `lent T` or of type `var T`.
The .cursor annotation
======================
Under the `--gc:arc|orc` modes Nim's `ref` type is implemented via the same runtime
"hooks" and thus via reference counting. This means that cyclic structures cannot be freed
immediately (`--gc:orc` ships with a cycle collector). With the `.cursor` annotation
one can break up cycles declaratively:
Under the `--gc:arc|orc`:option: modes Nim's `ref` type is implemented
via the same runtime "hooks" and thus via reference counting.
This means that cyclic structures cannot be freed
immediately (`--gc:orc`:option: ships with a cycle collector).
With the `.cursor` annotation one can break up cycles declaratively:
.. code-block:: nim

145
doc/docgen.rst
View File

@@ -1,5 +1,3 @@
.. default-role:: code
===================================
Nim DocGen Tools Guide
===================================
@@ -7,6 +5,8 @@
:Author: Erik O'Leary
:Version: |nimversion|
.. include:: rstcommon.rst
.. default-role:: Nim
.. contents::
@@ -17,20 +17,22 @@ This document describes the `documentation generation tools`:idx: built into
the `Nim compiler <nimc.html>`_, which can generate HTML 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
exported symbols (*), including procedures, types, and variables.
dependencies (`import`), any top-level documentation comments (`##`), and
exported symbols (`*`), including procedures, types, and variables.
Quick start
-----------
Generate HTML documentation for a file:
::
.. code:: cmd
nim doc <filename>.nim
Generate HTML documentation for a whole project:
::
.. code:: cmd
# delete any htmldocs/*.idx file before starting
nim doc --project --index:on --git.url:<url> --git.commit:<tag> --outdir:htmldocs <main_filename>.nim
# this will generate html files, a theindex.html index, css and js under `htmldocs`
@@ -39,15 +41,15 @@ Generate HTML documentation for a whole project:
# CORS will prevent opening file:// urls; this works:
python3 -m http.server 7029 --directory htmldocs
# When --outdir is omitted it defaults to $projectPath/htmldocs,
or `$nimcache/htmldocs` with `--usenimcache` which avoids clobbering your sources;
and likewise without `--project`.
Adding `-r` will open in a browser directly.
# or `$nimcache/htmldocs` with `--usenimcache` which avoids clobbering your sources;
# and likewise without `--project`.
# Adding `-r` will open in a browser directly.
Documentation Comments
----------------------
Any comments which are preceded by a double-hash (##), are interpreted as
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
Nim module authors the ability to easily generate richly formatted
@@ -66,7 +68,7 @@ Outputs::
name: string
age: int
This type contains a description of a person
This type contains a description of a person
Field documentation comments can be added to fields like so:
@@ -127,12 +129,15 @@ Document Types
HTML
----
The generation of HTML documents is done via the `doc` command. This command
takes either a single .nim file, outputting a single .html file with the same
base filename, or multiple .nim files, outputting multiple .html files and,
The generation of HTML documents is done via the `doc`:option: command. This command
takes either a single ``.nim`` file, outputting a single ``.html`` file with the same
base filename, or multiple ``.nim`` files, outputting multiple ``.html`` files and,
optionally, an index file.
The `doc` command::
The `doc`:option: command:
.. code:: cmd
nim doc sample
Partial Output::
@@ -148,12 +153,16 @@ compiler.
JSON
----
The generation of JSON documents is done via the `jsondoc` command. This command
takes in a .nim file and outputs a .json file with the same base filename. Note
that this tool is built off of the `doc` command (previously `doc2`), and
contains the same information.
The generation of JSON documents is done via the `jsondoc`:option: command.
This command takes in a ``.nim`` file and outputs a ``.json`` file with
the same base filename.
Note that this tool is built off of the `doc`:option: command
(previously `doc2`:option:), and contains the same information.
The `jsondoc`:option: command:
.. code:: cmd
The `jsondoc` command::
nim jsondoc sample
Output::
@@ -173,10 +182,13 @@ Output::
]
}
Similarly to the old `doc` command, the old `jsondoc` command has been
renamed to `jsondoc0`.
Similarly to the old `doc`:option: command, the old `jsondoc`:option: command has been
renamed to `jsondoc0`:option:.
The `jsondoc0`:option: command:
.. code:: cmd
The `jsondoc0` command::
nim jsondoc0 sample
Output::
@@ -192,8 +204,8 @@ Output::
}
]
Note that the `jsondoc` command outputs it's JSON without pretty-printing it,
while `jsondoc0` outputs pretty-printed JSON.
Note that the `jsondoc`:option: command outputs it's JSON without pretty-printing it,
while `jsondoc0`:option: outputs pretty-printed JSON.
Related Options
===============
@@ -201,22 +213,24 @@ Related Options
Project switch
--------------
::
.. code:: cmd
nim doc --project filename.nim
This will recursively generate documentation of all nim modules imported
into the input module that belong to the Nimble package that `filename.nim`
into the input module that belong to the Nimble package that ``filename.nim``
belongs to.
Index switch
------------
::
.. code:: cmd
nim doc --index:on filename.nim
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
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.
@@ -229,31 +243,37 @@ file.
See source switch
-----------------
::
.. code:: cmd
nim doc --git.url:<url> filename.nim
With the `git.url` switch the *See source* hyperlink will appear below each
With the `git.url`:option: switch the *See source* hyperlink will appear below each
documented item in your source code pointing to the implementation of that
item on a GitHub repository.
You can click the link to see the implementation of the item.
The `git.commit` switch overrides the hardcoded `devel` branch in config/nimdoc.cfg.
This is useful to link to a different branch e.g. `--git.commit:master`,
or to a tag e.g. `--git.commit:1.2.3` or a commit.
The `git.commit`:option: switch overrides the hardcoded `devel` branch in config/nimdoc.cfg.
This is useful to link to a different branch e.g. `--git.commit:master`:option:,
or to a tag e.g. `--git.commit:1.2.3`:option: or a commit.
Source URLs are generated as `href="${url}/tree/${commit}/${path}#L${line}"` by default and this compatible with GitHub but not with GitLab.
Source URLs are generated as ``href="${url}/tree/${commit}/${path}#L${line}"``
by default and this compatible with GitHub but not with GitLab.
Similarly, `git.devel` switch overrides the hardcoded `devel` branch for the `Edit` link which is also useful if you have a different working branch than `devel` e.g. `--git.devel:master`.
Similarly, `git.devel`:option: switch overrides the hardcoded `devel` branch
for the `Edit` link which is also useful if you have a different working
branch than `devel` e.g. `--git.devel:master`:option:.
Edit URLs are generated as `href="${url}/tree/${devel}/${path}#L${line}"` by default.
Edit URLs are generated as ``href="${url}/tree/${devel}/${path}#L${line}"``
by default.
You can edit `config/nimdoc.cfg` and modify the `doc.item.seesrc` value with a hyperlink to your own code repository.
You can edit ``config/nimdoc.cfg`` and modify the ``doc.item.seesrc`` value
with a hyperlink to your own code repository.
In the case of Nim's own documentation, the `commit` value is just a commit
hash to append to a formatted URL to https://github.com/nim-lang/Nim. The
`tools/nimweb.nim` helper queries the current git commit hash during the doc
``tools/nimweb.nim`` helper queries the current git commit hash during the doc
generation, but since you might be working on an unpublished repository, it
also allows specifying a `githash` value in `web/website.ini` to force a
also allows specifying a `githash` value in ``web/website.ini`` to force a
specific commit in the output.
@@ -261,28 +281,31 @@ Other Input Formats
===================
The *Nim compiler* also has support for RST (reStructuredText) files with
the `rst2html` and `rst2tex` commands. Documents like this one are
the `rst2html`:option: and `rst2tex`:option: commands. Documents like this one are
initially written in a dialect of RST which adds support for nim source code
highlighting with the `.. code-block:: nim` prefix. `code-block` also
highlighting with the ``.. code-block:: nim`` prefix. ``code-block`` also
supports highlighting of C++ and some other c-like languages.
Usage::
nim rst2html docgen.txt
Usage:
.. code:: cmd
nim rst2html docgen.rst
Output::
You're reading it!
The `rst2tex` command is invoked identically to `rst2html`, but outputs
a .tex file instead of .html.
The `rst2tex`:option: command is invoked identically to `rst2html`:option:,
but outputs a ``.tex`` file instead of ``.html``.
HTML anchor generation
======================
When you run the `rst2html` command, all sections in the RST document will
When you run the `rst2html`:option: command, all sections in the RST document will
get an anchor you can hyperlink to. Usually, you can guess the anchor lower
casing the section title and replacing spaces with dashes, and in any case, you
can get it from the table of contents. But when you run the `doc`
can get it from the table of contents. But when you run the `doc`:option:
command to generate API documentation, some symbol get one or two anchors at
the same time: a numerical identifier, or a plain name plus a complex name.
@@ -314,15 +337,15 @@ suffix may be added depending on the type of the callable:
Callable type Suffix
------------- --------------
proc *empty string*
macro `.m`
method `.e`
iterator `.i`
template `.t`
converter `.c`
macro ``.m``
method ``.e``
iterator ``.i``
template ``.t``
converter ``.c``
------------- --------------
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
``compiler/docgen.nim`` file. Here are some examples of complex names for
symbols in the `system module <system.html>`_.
* `type SomeSignedInt = int | int8 | int16 | int32 | int64` **=>**
@@ -346,7 +369,7 @@ symbols in the `system module <system.html>`_.
Index (idx) file format
=======================
Files with the `.idx` extension are generated when you use the `Index
Files with the ``.idx`` extension are generated when you use the `Index
switch <#related-options-index-switch>`_ along with commands to generate
documentation from source or text files. You can programmatically generate
indices with the `setIndexTerm()
@@ -364,7 +387,7 @@ columns is:
1. Mandatory term being indexed. Terms can include quoting according to
Nim's rules (e.g. \`^\`).
2. Base filename plus anchor hyperlink (e.g. `algorithm.html#*,int,SortOrder`).
2. Base filename plus anchor hyperlink (e.g. ``algorithm.html#*,int,SortOrder``).
3. Optional human-readable string to display as a hyperlink. If the value is not
present or is the empty string, the hyperlink will be rendered
using the term. Prefix whitespace indicates that this entry is
@@ -373,8 +396,8 @@ columns is:
this as a tooltip after hovering a moment over the hyperlink.
The index generation tools try to differentiate between documentation
generated from `.nim` files and documentation generated from `.txt` or
`.rst` files. The former are always closely related to source code and
generated from ``.nim`` files and documentation generated from ``.txt`` or
``.rst`` files. The former are always closely related to source code and
consist mainly of API entries. The latter are generic documents meant for
human reading.
@@ -393,7 +416,7 @@ the index file with their third column having as much prefix spaces as their
level is in the TOC (at least 1 character). The prefix whitespace helps to
filter TOC entries from API or text symbols. This is important because the
amount of spaces is used to replicate the hierarchy for document TOCs in the
final index, and TOC entries found in `.nim` files are discarded.
final index, and TOC entries found in ``.nim`` files are discarded.
Additional resources
@@ -404,8 +427,8 @@ Additional resources
`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
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

7
doc/drnim.rst
View File

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

22
doc/estp.rst
View File

@@ -1,9 +1,10 @@
.. default-role:: code
===================================================
Embedded Stack Trace Profiler (ESTP) User Guide
===================================================
.. include:: rstcommon.rst
.. default-role:: Nim
:Author: Andreas Rumpf
:Version: |nimversion|
@@ -12,7 +13,7 @@ Nim comes with a platform independent profiler -
the Embedded Stack Trace Profiler (ESTP). The profiler
is *embedded* into your executable. To activate the profiler you need to do:
* compile your program with the `--profiler:on --stackTrace:on` command
* compile your program with the `--profiler:on --stackTrace:on`:option: command
line options
* import the `nimprof` module
* run your program as usual.
@@ -20,10 +21,10 @@ is *embedded* into your executable. To activate the profiler you need to do:
You can in fact look at `nimprof`'s source code to see how to implement
your own profiler.
The setting `--profiler:on` defines the conditional symbol `profiler`.
The setting `--profiler:on`:option: defines the conditional symbol `profiler`.
You can use `when compileOption("profiler")` to make the switch seamless.
If `profiler` is `off`, your program runs normally. Otherwise your program
is profiled.
If `profiler`:option: is `off`:option:, your program runs normally.
Otherwise your program is profiled.
```nim
when compileOption("profiler"):
@@ -31,10 +32,10 @@ when compileOption("profiler"):
```
After your program has finished the profiler will create a
file `profile_results.txt` containing the profiling results.
file ``profile_results.txt`` containing the profiling results.
Since the profiler works by examining stack traces, it's essential that
the option `--stackTrace:on` is active! Unfortunately this means that a
the option `--stackTrace:on`:option: is active! Unfortunately this means that a
profiling build is much slower than a release build.
@@ -45,8 +46,9 @@ You can also use ESTP as a memory profiler to see which stack traces allocate
the most memory and thus create the most GC pressure. It may also help to
find memory leaks. To activate the memory profiler you need to do:
* compile your program with the `--profiler:off --stackTrace:on -d:memProfiler`
command line options. Yes it's `--profiler:off`.
* compile your program with the
`--profiler:off --stackTrace:on -d:memProfiler`:option:
command line options. Yes it's `--profiler:off`:option:.
* import the `nimprof` module
* run your program as usual.

4
doc/filelist.txt
View File

@@ -5,7 +5,7 @@ Short description of Nim's modules
Module Description
============== ==========================================================
nim main module: parses the command line and calls
``main.MainCommand``
`main.MainCommand`
main implements the top-level command dispatching
nimconf implements the config file reader
syntaxes dispatcher for the different parsers and filters
@@ -36,7 +36,7 @@ evals contains an AST interpreter for compile time evaluation
pragmas semantic checking of pragmas
idents implements a general mapping from identifiers to an internal
representation (``PIdent``) that is used so that a simple
representation (`PIdent`) that is used so that a simple
id-comparison suffices to establish whether two Nim
identifiers are equivalent
ropes implements long strings represented as trees for

28
doc/filters.rst
View File

@@ -1,9 +1,9 @@
.. default-role:: code
===================
Source Code Filters
===================
.. include:: rstcommon.rst
.. default-role:: code
.. contents::
A `Source Code Filter (SCF)` transforms the input character stream to an in-memory
@@ -25,8 +25,8 @@ just like an ordinary procedure call with named or positional arguments. The
available parameters depend on the invoked filter. Before version 0.12.0 of
the language `#!` was used instead of `#?`.
**Hint:** With `--hint[codeBegin]:on` or `--verbosity:2`
(or higher) while compiling or `nim check`, Nim lists the processed code after
**Hint:** With `--hint[codeBegin]:on`:option: or `--verbosity:2`:option:
(or higher) while compiling or `nim check`:cmd:, Nim lists the processed code after
each filter application.
Usage
@@ -70,10 +70,10 @@ The replace filter replaces substrings in each line.
Parameters and their defaults:
`sub: string = ""`
* `sub: string = ""`
the substring that is searched for
`by: string = ""`
* `by: string = ""`
the string the substring is replaced with
@@ -85,14 +85,14 @@ each line.
Parameters and their defaults:
`startswith: string = ""`
* `startswith: string = ""`
strip only the lines that start with *startswith* (ignoring leading
whitespace). If empty every line is stripped.
`leading: bool = true`
* `leading: bool = true`
strip leading whitespace
`trailing: bool = true`
* `trailing: bool = true`
strip trailing whitespace
@@ -107,19 +107,19 @@ statements need `end X` delimiters.
Parameters and their defaults:
`metaChar: char = '#'`
* `metaChar: char = '#'`
prefix for a line that contains Nim code
`subsChar: char = '$'`
* `subsChar: char = '$'`
prefix for a Nim expression within a template line
`conc: string = " & "`
* `conc: string = " & "`
the operation for concatenation
`emit: string = "result.add"`
* `emit: string = "result.add"`
the operation to emit a string literal
`toString: string = "$"`
* `toString: string = "$"`
the operation that is applied to each expression
Example::

44
doc/intern.rst
View File

@@ -1,5 +1,3 @@
.. default-role:: code
=========================================
Internals of the Nim Compiler
=========================================
@@ -8,6 +6,8 @@
:Author: Andreas Rumpf
:Version: |nimversion|
.. include:: rstcommon.rst
.. default-role:: Nim
.. contents::
"Abstraction is layering ignorance on top of reality." -- Richard Gabriel
@@ -38,25 +38,31 @@ Path Purpose
Bootstrapping the compiler
==========================
**Note**: Add ``.`` to your PATH so that `koch` can be used without the `./`.
**Note**: Add ``.`` to your PATH so that `koch`:cmd: can be used without the ``./``.
Compiling the compiler is a simple matter of running::
Compiling the compiler is a simple matter of running:
.. code:: cmd
nim c koch.nim
koch boot -d:release
For a debug version use::
For a debug version use:
.. code:: cmd
nim c koch.nim
koch boot
And for a debug version compatible with GDB::
And for a debug version compatible with GDB:
.. code:: cmd
nim c koch.nim
koch boot --debuginfo --linedir:on
The `koch` program is Nim's maintenance script. It is a replacement for
The `koch`:cmd: program is Nim's maintenance script. It is a replacement for
make and shell scripting with the advantage that it is much more portable.
More information about its options can be found in the `koch <koch.html>`_
documentation.
@@ -65,15 +71,17 @@ documentation.
Developing the compiler
=======================
To create a new compiler for each run, use `koch temp`::
To create a new compiler for each run, use `koch temp`:cmd:\:
.. code:: cmd
koch temp c test.nim
`koch temp` creates a debug build of the compiler, which is useful
`koch temp`:cmd: creates a debug build of the compiler, which is useful
to create stacktraces for compiler debugging.
You can of course use GDB or Visual Studio to debug the
compiler (via `--debuginfo --lineDir:on`). However, there
compiler (via `--debuginfo --lineDir:on`:option:). However, there
are also lots of procs that aid in debugging:
@@ -136,16 +144,18 @@ examples how the AST represents each syntactic structure.
Bisecting for regressions
=========================
`koch temp` returns 125 as the exit code in case the compiler
compilation fails. This exit code tells `git bisect` to skip the
current commit.::
`koch temp`:cmd: returns 125 as the exit code in case the compiler
compilation fails. This exit code tells `git bisect`:cmd: to skip the
current commit:
.. code:: cmd
git bisect start bad-commit good-commit
git bisect run ./koch temp -r c test-source.nim
You can also bisect using custom options to build the compiler, for example if
you don't need a debug version of the compiler (which runs slower), you can replace
`./koch temp` by explicit compilation command, see `Rebuilding the compiler`_.
`./koch temp`:cmd: by explicit compilation command, see `Rebuilding the compiler`_.
Runtimes
@@ -182,7 +192,7 @@ check that the OS, System modules work and recompile Nim.
The only case where things aren't as easy is when old runtime's garbage
collectors need some assembler tweaking to work. The default
implementation uses C's `setjmp` function to store all registers
implementation uses C's `setjmp`:c: function to store all registers
on the hardware stack. It may be necessary that the new platform needs to
replace this generic code by some assembler code.
@@ -207,7 +217,7 @@ Complex assignments
We already know the type information as a graph in the compiler.
Thus we need to serialize this graph as RTTI for C code generation.
Look at the file `lib/system/hti.nim` for more information.
Look at the file ``lib/system/hti.nim`` for more information.
Magics and compilerProcs
@@ -368,7 +378,7 @@ pass generates code to setup the environment and to pass it around. However,
this pass does not change the types! So we have some kind of mismatch here; on
the one hand the proc expression becomes an explicit tuple, on the other hand
the tyProc(ccClosure) type is not changed. For C code generation it's also
important the hidden formal param is `void*` and not something more
important the hidden formal param is `void*`:c: and not something more
specialized. However the more specialized env type needs to passed to the
backend somehow. We deal with this by modifying `s.ast[paramPos]` to contain
the formal hidden parameter, but not `s.typ`!

8
doc/nimdoc.css
View File

@@ -938,6 +938,14 @@ span.option {
color: var(--option);
}
span.Prompt {
font-weight: bold;
color: red; }
span.ProgramOutput {
font-weight: bold;
color: #808080; }
span.program {
font-weight: bold;
color: var(--program);

60
doc/testament.rst
View File

@@ -1,4 +1,10 @@
.. default-role:: code
===========
Testament
===========
.. 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,
offers process isolation for your tests, it can generate statistics about test cases,
@@ -11,29 +17,34 @@ so can be useful to run your tests, even the most complex ones.
Test files location
===================
By default Testament looks for test files on `"./tests/*.nim"`.
You can overwrite this pattern glob using `pattern <glob>`.
By default Testament looks for test files on ``"./tests/*.nim"``.
You can overwrite this pattern glob using `pattern <glob>`:option:.
The default working directory path can be changed using
`--directory:"folder/subfolder/"`.
`--directory:"folder/subfolder/"`:option:.
Testament uses the `nim` compiler on `PATH`.
You can change that using `--nim:"folder/subfolder/nim"`.
Running JavaScript tests with `--targets:"js"` requires a working NodeJS on
`PATH`.
Testament uses the `nim`:cmd: compiler on `PATH`.
You can change that using `--nim:"folder/subfolder/nim"`:option:.
Running JavaScript tests with `--targets:"js"`:option: requires
a working NodeJS on `PATH`.
Options
=======
* `--print` Also print results to the console
* `--simulate` See what tests would be run but don't run them (for debugging)
* `--failing` Only show failing/ignored tests
* `--targets:"c cpp js objc"` Run tests for specified targets (default: all)
* `--nim:path` Use a particular nim executable (default: `$PATH/nim`)
* `--directory:dir` Change to directory dir before reading the tests or doing anything else.
* `--colors:on|off` Turn messages coloring on|off.
* `--backendLogging:on|off` Disable or enable backend logging. By default turned on.
* `--skipFrom:file` Read tests to skip from `file` - one test per line, # comments ignored
--print Also print results to the console
--simulate See what tests would be run but don't run them
(for debugging)
--failing Only show failing/ignored tests
--targets:"c cpp js objc"
Run tests for specified targets (default: all)
--nim:path Use a particular nim executable (default: $PATH/nim)
--directory:dir Change to directory dir before reading the tests
or doing anything else.
--colors:on|off Turn messages coloring on|off.
--backendLogging:on|off Disable or enable backend logging.
By default turned on.
--skipFrom:file Read tests to skip from ``file`` - one test per
line, # comments ignored
Running a single test
@@ -42,27 +53,26 @@ Running a single test
This is a minimal example to understand the basics,
not very useful for production, but easy to understand:
.. code::
.. code:: console
$ mkdir tests
$ echo "assert 42 == 42" > tests/test0.nim
$ testament run test0.nim
PASS: tests/test0.nim C ( 0.2 sec)
PASS: tests/test0.nim C ( 0.2 sec)
$ testament r test0
PASS: tests/test0.nim C ( 0.2 sec)
PASS: tests/test0.nim C ( 0.2 sec)
Running all tests from a directory
==================================
.. code::
.. code:: console
$ testament pattern "tests/*.nim"
To search for tests deeper in a directory, use
.. code::
.. code:: console
$ testament pattern "tests/**/*.nim" # one level deeper
$ testament pattern "tests/**/**/*.nim" # two levels deeper
@@ -70,10 +80,10 @@ To search for tests deeper in a directory, use
HTML Reports
============
Generate HTML Reports `testresults.html` from unittests,
Generate HTML Reports ``testresults.html`` from unittests,
you have to run at least 1 test *before* generating a report:
.. code::
.. code:: console
$ testament html

36
lib/packages/docutils/highlite.nim
View File

@@ -49,6 +49,11 @@
## `nimgrep --ext:'nim|nims' file.name`:cmd: shows how to input ``|``.
## Any argument that contains ``.`` or ``/`` or ``\`` will be treated
## as a file or directory.
##
## In addition to `Cmd` there is also `Console` language for
## displaying interactive sessions.
## Lines with a command should start with ``$``, other lines are considered
## as program output.
import
strutils
@@ -57,7 +62,7 @@ from algorithm import binarySearch
type
SourceLanguage* = enum
langNone, langNim, langCpp, langCsharp, langC, langJava,
langYaml, langPython, langCmd
langYaml, langPython, langCmd, langConsole
TokenClass* = enum
gtEof, gtNone, gtWhitespace, gtDecNumber, gtBinNumber, gtHexNumber,
gtOctNumber, gtFloatNumber, gtIdentifier, gtKeyword, gtStringLit,
@@ -65,7 +70,7 @@ type
gtOperator, gtPunctuation, gtComment, gtLongComment, gtRegularExpression,
gtTagStart, gtTagEnd, gtKey, gtValue, gtRawData, gtAssembler,
gtPreprocessor, gtDirective, gtCommand, gtRule, gtHyperlink, gtLabel,
gtReference, gtProgram, gtOption, gtOther
gtReference, gtPrompt, gtProgramOutput, gtProgram, gtOption, gtOther
GeneralTokenizer* = object of RootObj
kind*: TokenClass
start*, length*: int
@@ -76,14 +81,17 @@ type
const
sourceLanguageToStr*: array[SourceLanguage, string] = ["none",
"Nim", "C++", "C#", "C", "Java", "Yaml", "Python", "Cmd"]
"Nim", "C++", "C#", "C", "Java", "Yaml", "Python", "Cmd", "Console"]
sourceLanguageToAlpha*: array[SourceLanguage, string] = ["none",
"Nim", "cpp", "csharp", "C", "Java", "Yaml", "Python", "Cmd", "Console"]
## list of languages spelled with alpabetic characters
tokenClassToStr*: array[TokenClass, string] = ["Eof", "None", "Whitespace",
"DecNumber", "BinNumber", "HexNumber", "OctNumber", "FloatNumber",
"Identifier", "Keyword", "StringLit", "LongStringLit", "CharLit",
"EscapeSequence", "Operator", "Punctuation", "Comment", "LongComment",
"RegularExpression", "TagStart", "TagEnd", "Key", "Value", "RawData",
"Assembler", "Preprocessor", "Directive", "Command", "Rule", "Hyperlink",
"Label", "Reference",
"Label", "Reference", "Prompt", "ProgramOutput",
# start from lower-case if there is a corresponding RST role (see rst.nim)
"program", "option",
"Other"]
@@ -103,9 +111,11 @@ const
"xor", "yield"]
proc getSourceLanguage*(name: string): SourceLanguage =
for i in countup(succ(low(SourceLanguage)), high(SourceLanguage)):
for i in succ(low(SourceLanguage)) .. high(SourceLanguage):
if cmpIgnoreStyle(name, sourceLanguageToStr[i]) == 0:
return i
if cmpIgnoreStyle(name, sourceLanguageToAlpha[i]) == 0:
return i
result = langNone
proc initGeneralTokenizer*(g: var GeneralTokenizer, buf: cstring) =
@@ -915,17 +925,17 @@ proc pythonNextToken(g: var GeneralTokenizer) =
"with", "yield"]
nimNextToken(g, keywords)
proc cmdNextToken(g: var GeneralTokenizer) =
proc cmdNextToken(g: var GeneralTokenizer, dollarPrompt = false) =
var pos = g.pos
g.start = g.pos
if g.state == low(TokenClass):
g.state = gtProgram
g.state = if dollarPrompt: gtPrompt else: gtProgram
case g.buf[pos]
of ' ', '\t'..'\r':
g.kind = gtWhitespace
while g.buf[pos] in {' ', '\t'..'\r'}:
if g.buf[pos] == '\n':
g.state = gtProgram
g.state = if dollarPrompt: gtPrompt else: gtProgram
inc(pos)
of '\'', '"':
g.kind = gtOption
@@ -955,6 +965,15 @@ proc cmdNextToken(g: var GeneralTokenizer) =
g.kind = gtOperator
inc(pos)
of '\0': g.kind = gtEof
elif dollarPrompt and g.state == gtPrompt:
if g.buf[pos] == '$' and g.buf[pos+1] in {' ', '\t'}:
g.kind = gtPrompt
inc pos, 2
g.state = gtProgram
else:
g.kind = gtProgramOutput
while g.buf[pos] notin {'\n', '\0'}:
inc(pos)
else:
if g.state == gtProgram:
g.kind = gtProgram
@@ -986,6 +1005,7 @@ proc getNextToken*(g: var GeneralTokenizer, lang: SourceLanguage) =
of langYaml: yamlNextToken(g)
of langPython: pythonNextToken(g)
of langCmd: cmdNextToken(g)
of langConsole: cmdNextToken(g, dollarPrompt=true)
proc tokenize*(text: string, lang: SourceLanguage): seq[(string, TokenClass)] =
var g: GeneralTokenizer

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

@@ -89,6 +89,8 @@
##
## - generic command line highlighting roles:
## - ``:cmd:`` for commands and common shells syntax
## - ``:console:`` the same for interactive sessions
## (commands should be prepended by ``$``)
## - ``:program:`` for executable names [cmp:Sphinx]_
## (one can just use ``:cmd:`` on single word)
## - ``:option:`` for command line options [cmp:Sphinx]_
@@ -168,6 +170,7 @@
import
os, strutils, rstast, std/enumutils, algorithm, lists, sequtils,
std/private/miscdollars
from highlite import SourceLanguage, getSourceLanguage
type
RstParseOption* = enum ## options for the RST parser
@@ -549,10 +552,6 @@ proc defaultFindFile*(filename: string): string =
proc defaultRole(options: RstParseOptions): string =
if roNimFile in options: "nim" else: "literal"
# mirror highlite.nim sourceLanguageToStr with substitutions c++ cpp, c# csharp
const supportedLanguages = ["nim", "yaml", "python", "java", "c",
"cpp", "csharp", "cmd"]
proc whichRoleAux(sym: string): RstNodeKind =
let r = sym.toLowerAscii
case r
@@ -566,7 +565,7 @@ proc whichRoleAux(sym: string): RstNodeKind =
of "code": result = rnInlineLiteral
of "program", "option", "tok": result = rnCodeFragment
# c++ currently can be spelled only as cpp, c# only as csharp
elif r in supportedLanguages:
elif getSourceLanguage(r) != langNone:
result = rnInlineCode
else: # unknown role
result = rnUnknownRole
@@ -2614,7 +2613,7 @@ proc dirRole(p: var RstParser): PRstNode =
result = parseDirective(p, rnDirective, {hasArg, hasOptions}, nil)
# just check that language is supported, TODO: real role association
let lang = getFieldValue(result, "language").strip
if lang != "" and lang notin supportedLanguages:
if lang != "" and getSourceLanguage(lang) == langNone:
rstMessage(p, mwUnsupportedLanguage, lang)
proc dirRawAux(p: var RstParser, result: var PRstNode, kind: RstNodeKind,

8
nimdoc/testproject/expected/nimdoc.out.css
View File

@@ -938,6 +938,14 @@ span.option {
color: var(--option);
}
span.Prompt {
font-weight: bold;
color: red; }
span.ProgramOutput {
font-weight: bold;
color: #808080; }
span.program {
font-weight: bold;
color: var(--program);

17
tests/stdlib/thighlite.nim
View File

@@ -1,8 +1,8 @@
import unittest
import unittest, strutils
import ../../lib/packages/docutils/highlite
block: # Nim tokenizing"
block: # Nim tokenizing
test "string literals and escape seq":
check("\"ok1\\nok2\\nok3\"".tokenize(langNim) ==
@[("\"ok1", gtStringLit), ("\\n", gtEscapeSequence), ("ok2", gtStringLit),
@@ -11,3 +11,16 @@ block: # Nim tokenizing"
check("\"\"\"ok1\\nok2\\nok3\"\"\"".tokenize(langNim) ==
@[("\"\"\"ok1\\nok2\\nok3\"\"\"", gtLongStringLit)
])
block: # Cmd (shell) tokenizing
test "cmd with dollar and output":
check(
dedent"""
$ nim c file.nim
out: file [SuccessX]"""
.tokenize(langConsole) ==
@[("$ ", gtPrompt), ("nim", gtProgram),
(" ", gtWhitespace), ("c", gtOption), (" ", gtWhitespace),
("file.nim", gtIdentifier), ("\n", gtWhitespace),
("out: file [SuccessX]", gtProgramOutput)
])