diff options
| -rw-r--r-- | doc/nims.rst | 180 |
1 files changed, 172 insertions, 8 deletions
diff --git a/doc/nims.rst b/doc/nims.rst index 53199782c..8e3638d62 100644 --- a/doc/nims.rst +++ b/doc/nims.rst @@ -28,8 +28,9 @@ previous settings): For available procs and implementation details see `nimscript <nimscript.html>`_. + Limitations -================================= +=========== NimScript is subject to some limitations caused by the implementation of the VM (virtual machine): @@ -47,18 +48,50 @@ NimScript is subject to some limitations caused by the implementation of the VM * More than one level of `ref` is generally not supported (for example, the type `ref ref int`). -* multimethods are not available. +* Multimethods are not available. + +* ``random.randomize()`` requires an ``int64`` explicitly passed as argument, you *must* pass a Seed integer. + +* ``unicode`` can be imported, but not ``unidecode``. -Given the above restrictions, at least the following modules are available: + +Standard library modules +======================== + +At least the following standard library modules are available: * `macros <macros.html>`_ * `os <os.html>`_ * `strutils <strutils.html>`_ * `math <math.html>`_ * `distros <distros.html>`_ - -In addition to the standard Nim syntax (`system <system.html>`_ -module), NimScripts support the procs and templates defined in the +* `sugar <sugar.html>`_ +* `algorithm <algorithm.html>`_ +* `base64 <base64.html>`_ +* `bitops <bitops.html>`_ +* `chains <chains.html>`_ +* `colors <colors.html>`_ +* `complex <complex.html>`_ +* `htmlgen <htmlgen.html>`_ +* `httpcore <httpcore.html>`_ +* `lenientops <lenientops.html>`_ +* `mersenne <mersenne.html>`_ +* `options <options.html>`_ +* `parseutils <parseutils.html>`_ +* `punycode <punycode.html>`_ +* `random <punycode.html>`_ +* `stats <stats.html>`_ +* `strformat <strformat.html>`_ +* `strmisc <strmisc.html>`_ +* `strscans <strscans.html>`_ +* `unicode <unicode.html>`_ +* `uri <uri.html>`_ +* `std/editdistance <editdistance.html>`_ +* `std/wordwrap <wordwrap.html>`_ +* `std/sums <sums.html>`_ + +In addition to the standard Nim syntax (`system <system.html>`_ module), +NimScripts support the procs and templates defined in the `nimscript <nimscript.html>`_ module too. @@ -130,8 +163,6 @@ See the `Nimble readme <https://github.com/nim-lang/nimble#readme>`_ for more information. - - Standalone NimScript ==================== @@ -165,3 +196,136 @@ ends with ``.nims``: echo "hello world" Use ``#!/usr/bin/env -S nim --hints:off`` to disable hints. + + +Benefits +======== + +Cross-Platform +-------------- + +It is a cross-platform scripting language that can run where Nim can run, +e.g. you can not run Batch or PowerShell on Linux or Mac, +the Bash for Linux might not run on Mac, +there are no unit tests tools for Batch, etc. + +NimScript can detect on which platform, operating system, +architecture, and even which Linux distribution is running on, +allowing the same script to support a lot of systems. + +See the following (incomplete) example: + +.. code-block:: nim + + import distros + + # Architectures. + if defined(amd64): + echo "Architecture is x86 64Bits" + elif defined(i386): + echo "Architecture is x86 32Bits" + elif defined(arm): + echo "Architecture is ARM" + + # Operating Systems. + if defined(linux): + echo "Operating System is GNU Linux" + elif defined(windows): + echo "Operating System is Microsoft Windows" + elif defined(macosx): + echo "Operating System is Apple OS X" + + # Distros. + if detectOs(Ubuntu): + echo "Distro is Ubuntu" + elif detectOs(ArchLinux): + echo "Distro is ArchLinux" + elif detectOs(Debian): + echo "Distro is Debian" + + +Uniform Syntax +-------------- + +The syntax, style, and rest of the ecosystem is the same as for compiled Nim, +that means there is nothing new to learn, no context switch for developers. + + +Powerful Metaprogramming +------------------------ + +NimScript can use Nim's templates, macros, types, concepts, effect tracking system, and more, +you can create modules that work on compiled Nim and also on interpreted NimScript. + +``func`` will still check for side effects, ``debugEcho`` also works as expected, +making it ideal for functional scripting metaprogramming. + +This is an example of a third party module that uses macros and templates to +translate text strings on unmodified NimScript: + +.. code-block:: nim + + import nimterlingua + nimterlingua("translations.cfg") + echo "cat" # Run with -d:RU becomes "kot", -d:ES becomes "gato", ... + +translations.cfg + +.. code-block:: none + + [cat] + ES = gato + PT = minino + RU = kot + FR = chat + + +* `Nimterlingua <https://nimble.directory/pkg/nimterlingua>`_ + + +Graceful Fallback +----------------- + +Some features of compiled Nim may not work on NimScript, +but often a graceful and seamless fallback degradation is used. + +See the following NimScript: + +.. code-block:: nim + + if likely(true): + discard + elif unlikely(false): + discard + + proc foo() {.compiletime.} = echo NimVersion + + static: + echo CompileDate + + +``likely()``, ``unlikely()``, ``static:`` and ``{.compiletime.}`` +will produce no code at all when run on NimScript, +but still no error nor warning is produced and the code just works. + +Evolving Scripting language +--------------------------- + +NimScript evolves together with Nim, +`occasionally new features might become available on NimScript <https://github.com/nim-lang/Nim/pulls?utf8=%E2%9C%93&q=nimscript>`_ , +adapted from compiled Nim or added as new features on both. + +Scripting Language with a Package Manager +----------------------------------------- + +You can create your own modules to be compatible with NimScript, +and check `Nimble <https://nimble.directory>`_ +to search for third party modules that may work on NimScript. + +DevOps Scripting +---------------- + +You can use NimScript to deploy to production, run tests, build projects, do benchmarks, +generate documentation, and all kinds of DevOps/SysAdmin specific tasks. + +* `An example of a third party NimScript that can be used as a project-agnostic tool. <https://github.com/kaushalmodi/nim_config#list-available-tasks>`_ |