jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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
commit 7e21218a07
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
20 changed files with 183 additions and 164 deletions
Download patch file Download diff file Expand all files Collapse all files

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