documented NimScript

doc/nims.txt

@@ -0,0 +1,118 @@
+================================
+          NimScript
+================================
+
+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, but also replaces Nim's existing configuration
+system.
+
+So instead of a ``myproject.nim.cfg`` configuration file, you can use
+a ``myproject.nims`` file that simply contains Nim code controlling the
+compilation process.
+
+The VM cannot deal with ``importc``, the FFI is not available, so there are not
+many stdlib modules that you can use with Nim's VM. However, the following
+modules are available:
+
+* `strutils <strutils.html>`_
+* `ospaths <ospaths.html>`_
+* `math <math.html>`_
+
+The `system <system.html>`_ module in NimScript mode additionally supports
+these operations: `nimscript <nimscript.html>`_.
+
+
+NimScript as a configuration file
+=================================
+
+What is ``x.y.key = "value"`` in the configuration file
+becomes ``switch("x.y.key", "value")``. ``--option`` is ``switch("option")``.
+The ``system`` module also exports 2 ``--`` templates for convenience:
+
+.. code-block:: nim
+  --forceBuild
+  # is the same as:
+  switch("forceBuild")
+
+
+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 exampled defines a
+task ``build`` that is an alias for the ``c`` command:
+
+.. code-block:: nim
+  task build, "builds an example":
+    setCommand "c"
+
+
+In fact, as a convention the following tasks should be available:
+
+=========     ===================================================
+Task          Description
+=========     ===================================================
+``build``     Build the project with the required
+              backend (``c``, ``cpp`` or ``js``).
+``tests``     Runs the tests belonging to the project.
+``bench``     Runs benchmarks belonging to the project.
+=========     ===================================================
+
+
+If the task runs an external command via ``exec`` it should afterwards call
+``setCommand "nop"`` to tell the Nim compiler that nothing else needs to be
+done:
+
+.. code-block:: nim
+
+  task tests, "test regular expressions":
+    exec "nim c -r tests"
+    setCommand "nop"
+
+
+Nimble integration
+==================
+
+A ``project.nims`` file can also be used as an alternative to
+a ``project.nimble`` file to specify the meta information (for example, author,
+description) and dependencies of a Nimble package. This means you can easily
+have platform specific dependencies:
+
+.. code-block:: nim
+
+  version = "1.0"
+  author = "The green goo."
+  description = "Lexer generation and regex implementation for Nim."
+  license = "MIT"
+
+  when defined(windows):
+    requires "oldwinapi >= 1.0"
+  else:
+    requires "gtk2 >= 1.0"
+
+
+
+
+Standalone NimScript
+====================
+
+NimScript can also be used directly as a portable replacement for Bash and
+Batch files. Use ``nim e myscript.nims`` to run ``myscript.nims``. For example,
+installation of Nimble is done with this simple script:
+
+.. code-block:: nim
+
+  mode = ScriptMode.Verbose
+
+  var id = 0
+  while dirExists("nimble" & $id):
+    inc id
+
+  exec "git clone https://github.com/nim-lang/nimble.git nimble" & $id
+
+  withDir "nimble" & $id & "/src":
+    exec "nim c nimble"
+
+  mvFile "nimble" & $id & "/src/nimble".toExe, "bin/nimble".toExe
+

lib/pure/ospaths.nim

@@ -10,7 +10,7 @@
 # Included by the ``os`` module but a module in its own right for NimScript
 # support.
 
-when defined(nimscript):
+when defined(nimscript) or (defined(nimdoc) and not declared(os)):
   {.pragma: rtl.}
   {.push hint[ConvFromXtoItselfNotNeeded]:off.}
 
@@ -417,6 +417,7 @@ when not declared(getEnv) or defined(nimscript):
     else:
       when defined(nimscript):
         result = cmpic(pathA, pathB)
+      elif defined(nimdoc): discard
       else:
         result = cmpIgnoreCase(pathA, pathB)
 
@@ -490,6 +491,10 @@ when not declared(getEnv) or defined(nimscript):
           add result, path[i]
           inc(i)
 
+when defined(nimdoc) and not declared(os):
+  proc getEnv(x: string): string = discard
+  proc existsFile(x: string): bool = discard
+
 when declared(getEnv) or defined(nimscript):
   proc getHomeDir*(): string {.rtl, extern: "nos$1", tags: [ReadEnvEffect].} =
     ## Returns the home directory of the current user.
@@ -556,5 +561,5 @@ when declared(getEnv) or defined(nimscript):
       if existsFile(x): return x
     result = ""
 
-when defined(nimscript):
+when defined(nimscript) or (defined(nimdoc) and not declared(os)):
   {.pop.} # hint[ConvFromXtoItselfNotNeeded]:off

todo.txt

@@ -1,9 +1,7 @@
 version 0.11.4
 ==============
 
-- document NimScript
 - document special cased varargs[untyped] and varargs[typed]
-
 - The remaining bugs of the lambda lifting pass that is responsible to enable
   closures and closure iterators need to be fixed.
 - ``concept`` needs to be refined, a nice name for the feature is not enough.

tools/nimweb.nim

@@ -334,7 +334,7 @@ proc parseNewsTitles(inputFilename: string): seq[TRssItem] =
   result = @[]
   if not open(input, inputFilename):
     quit("Could not read $1 for rss generation" % [inputFilename])
-  finally: input.close()
+  defer: input.close()
   while input.readLine(line):
     if line =~ reYearMonthDayTitle:
       result.add(TRssItem(year: matches[0], month: matches[1], day: matches[2],
@@ -368,7 +368,7 @@ proc generateRss(outputFilename: string, news: seq[TRssItem]) =
 
   if not open(output, outputFilename, mode = fmWrite):
     quit("Could not write to $1 for rss generation" % [outputFilename])
-  finally: output.close()
+  defer: output.close()
 
   output.write("""<?xml version="1.0" encoding="utf-8"?>
 <feed xmlns="http://www.w3.org/2005/Atom">

web/documentation.txt

@@ -21,6 +21,9 @@ Nim's Documentation
       | The user guide lists command line arguments, special features of the
         compiler, etc.
 
+    - | `NimScript <docs/nims.html>`_
+      | NimScript is the upcoming new way to configure Nim.
+
     - | `Nim Backend Integration <docs/backends.html>`_
       | The Backend Integeration guide gives further information of how Nim can
         interact with C, C++, Objective C and JavaScript.

web/website.ini

@@ -31,9 +31,9 @@ file: ticker.txt
 [Documentation]
 doc: "endb;intern;apis;lib;manual.txt;tut1;tut2;nimc;overview;filters"
 doc: "tools;niminst;nimgrep;gc;estp;idetools;docgen;koch;backends.txt"
-doc: "nimfix.txt;nimsuggest.txt;nep1.txt"
+doc: "nimfix.txt;nimsuggest.txt;nep1.txt;nims.txt"
 pdf: "manual.txt;lib;tut1;tut2;nimc;niminst;gc"
-srcdoc2: "system.nim"
+srcdoc2: "system.nim;system/nimscript;pure/ospaths"
 srcdoc2: "core/macros;pure/marshal;core/typeinfo;core/unsigned"
 srcdoc2: "impure/re;pure/sockets;pure/typetraits"
 srcdoc2: "pure/concurrency/threadpool.nim;pure/concurrency/cpuinfo.nim"