Merge remote-tracking branch 'upstream/devel' into improve-xmltree

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

lib/system.nim

@@ -1173,12 +1173,12 @@ const
     ## "i386", "alpha", "powerpc", "powerpc64", "powerpc64el", "sparc",
     ## "amd64", "mips", "mipsel", "arm", "arm64".
 
-  nimvm* {.magic: "Nimvm".}: bool = false
+  seqShallowFlag = low(int)
+
+let nimvm* {.magic: "Nimvm".}: bool = false
     ## may be used only in "when" expression.
     ## It is true in Nim VM context and false otherwise
 
-  seqShallowFlag = low(int)
-
 proc compileOption*(option: string): bool {.
   magic: "CompileOption", noSideEffect.}
   ## can be used to determine an on|off compile-time option. Example:

lib/system/nimscript.nim

@@ -13,23 +13,51 @@
 
 template builtin = discard
 
-proc listDirs*(dir: string): seq[string] = builtin
-proc listFiles*(dir: string): seq[string] = builtin
+proc listDirs*(dir: string): seq[string] =
+  ## Lists all the subdirectories (non-recursively) in the directory `dir`.
+  builtin
+proc listFiles*(dir: string): seq[string] =
+  ## Lists all the files (non-recursively) in the directory `dir`.
+  builtin
 
-proc removeDir(dir: string) = builtin
-proc removeFile(dir: string) = builtin
-proc moveFile(src, dest: string) = builtin
-proc copyFile(src, dest: string) = builtin
-proc createDir(dir: string) = builtin
+proc removeDir(dir: string){.
+  tags: [ReadIOEffect, WriteIOEffect], raises: [OSError].} = builtin
+proc removeFile(dir: string) {.
+  tags: [ReadIOEffect, WriteIOEffect], raises: [OSError].} = builtin
+proc moveFile(src, dest: string) {.
+  tags: [ReadIOEffect, WriteIOEffect], raises: [OSError].} = builtin
+proc copyFile(src, dest: string) {.
+  tags: [ReadIOEffect, WriteIOEffect], raises: [OSError].} = builtin
+proc createDir(dir: string) {.tags: [WriteIOEffect], raises: [OSError].} = builtin
 proc getOsError: string = builtin
 proc setCurrentDir(dir: string) = builtin
 proc getCurrentDir(): string = builtin
-proc paramStr*(i: int): string = builtin
-proc paramCount*(): int = builtin
+proc rawExec(cmd: string): int {.tags: [ExecIOEffect], raises: [OSError].} =
+  builtin
+
+proc paramStr*(i: int): string =
+  ## Retrieves the ``i``'th command line parameter.
+  builtin
+
+proc paramCount*(): int =
+  ## Retrieves the number of command line parameters.
+  builtin
+
+proc switch*(key: string, val="") =
+  ## Sets a Nim compiler command line switch, for
+  ## example ``switch("checks", "on")``.
+  builtin
+
+proc getCommand*(): string =
+  ## Gets the Nim command that the compiler has been invoked with, for example
+  ## "c", "js", "build", "help".
+  builtin
+
+proc setCommand*(cmd: string) =
+  ## Sets the Nim command that should be continued with after this Nimscript
+  ## has finished.
+  builtin
 
-proc switch*(key: string, val="") = builtin
-proc getCommand*(): string = builtin
-proc setCommand*(cmd: string) = builtin
 proc cmpIgnoreStyle(a, b: string): int = builtin
 proc cmpIgnoreCase(a, b: string): int = builtin
 
@@ -37,11 +65,23 @@ proc cmpic*(a, b: string): int = cmpIgnoreCase(a, b)
 
 proc getEnv*(key: string): string = builtin
 proc existsEnv*(key: string): bool = builtin
-proc fileExists*(filename: string): bool = builtin
-proc dirExists*(dir: string): bool = builtin
 
-proc existsFile*(filename: string): bool = fileExists(filename)
-proc existsDir*(dir: string): bool = dirExists(dir)
+proc fileExists*(filename: string): bool {.tags: [ReadIOEffect].} =
+  ## Checks if the file exists.
+  builtin
+
+proc dirExists*(dir: string): bool {.
+  tags: [ReadIOEffect].} =
+  ## Checks if the directory `dir` exists.
+  builtin
+
+proc existsFile*(filename: string): bool =
+  ## An alias for ``fileExists``.
+  fileExists(filename)
+
+proc existsDir*(dir: string): bool =
+  ## An alias for ``dirExists``.
+  dirExists(dir)
 
 proc toExe*(filename: string): string =
   ## On Windows adds ".exe" to `filename`, else returns `filename` unmodified.
@@ -60,10 +100,11 @@ template `--`*(key, val: untyped) = switch(astToStr(key), strip astToStr(val))
 template `--`*(key: untyped) = switch(astToStr(key), "")
 
 type
-  ScriptMode* {.pure.} = enum
-    Silent,
-    Verbose,
-    Whatif
+  ScriptMode* {.pure.} = enum ## Controls the behaviour of the script.
+    Silent,                   ## Be silent.
+    Verbose,                  ## Be verbose.
+    Whatif                    ## Do not run commands, instead just echo what
+                              ## would have been done.
 
 var
   mode*: ScriptMode ## Set this to influence how mkDir, rmDir, rmFile etc.
@@ -80,31 +121,44 @@ template log(msg: string, body: untyped) =
     body
 
 proc rmDir*(dir: string) {.raises: [OSError].} =
+  ## Removes the directory `dir`.
   log "rmDir: " & dir:
     removeDir dir
     checkOsError()
 
-proc rmFile*(dir: string) {.raises: [OSError].} =
-  log "rmFile: " & dir:
-    removeFile dir
+proc rmFile*(file: string) {.raises: [OSError].} =
+  ## Removes the `file`.
+  log "rmFile: " & file:
+    removeFile file
     checkOsError()
 
 proc mkDir*(dir: string) {.raises: [OSError].} =
+  ## Creates the directory `dir` including all necessary subdirectories. If
+  ## the directory already exists, no error is raised.
   log "mkDir: " & dir:
     createDir dir
     checkOsError()
 
 proc mvFile*(`from`, to: string) {.raises: [OSError].} =
+  ## Moves the file `from` to `to`.
   log "mvFile: " & `from` & ", " & to:
     moveFile `from`, to
     checkOsError()
 
 proc cpFile*(`from`, to: string) {.raises: [OSError].} =
+  ## Copies the file `from` to `to`.
   log "mvFile: " & `from` & ", " & to:
     copyFile `from`, to
     checkOsError()
 
-proc exec*(command: string, input = "", cache = "") =
+proc exec*(command: string) =
+  ## Executes an external process.
+  log "exec: " & command:
+    if rawExec(command) != 0:
+      raise newException(OSError, "FAILED: " & command)
+    checkOsError()
+
+proc exec*(command: string, input: string, cache = "") =
   ## Executes an external process.
   log "exec: " & command:
     echo staticExec(command, input, cache)
@@ -166,6 +220,11 @@ proc writeTask(name, desc: string) =
 
 template task*(name: untyped; description: string; body: untyped): untyped =
   ## Defines a task. Hidden tasks are supported via an empty description.
+  ## Example:
+  ##
+  ## .. code-block:: nim
+  ##  task build, "default build is via the C backend":
+  ##    setCommand "c"
   proc `name Task`() = body
 
   let cmd = getCommand()
@@ -177,13 +236,23 @@ template task*(name: untyped; description: string; body: untyped): untyped =
     `name Task`()
 
 var
-  packageName* = ""
-  version*, author*, description*, license*, srcdir*,
-    binDir*, backend*: string
+  packageName* = ""    ## Nimble support: Set this to the package name. It
+                       ## is usually not required to do that, nims' filename is
+                       ## the default.
+  version*: string     ## Nimble support: The package's version.
+  author*: string      ## Nimble support: The package's author.
+  description*: string ## Nimble support: The package's description.
+  license*: string     ## Nimble support: The package's license.
+  srcdir*: string      ## Nimble support: The package's source directory.
+  binDir*: string      ## Nimble support: The package's binary directory.
+  backend*: string     ## Nimble support: The package's backend.
 
   skipDirs*, skipFiles*, skipExt*, installDirs*, installFiles*,
-    installExt*, bin*: seq[string] = @[]
-  requiresData*: seq[string] = @[]
+    installExt*, bin*: seq[string] = @[] ## Nimble metadata.
+  requiresData*: seq[string] = @[] ## Exposes the list of requirements for read
+                                   ## and write accesses.
 
 proc requires*(deps: varargs[string]) =
+  ## Nimble support: Call this to set the list of requirements of your Nimble
+  ## package.
   for d in deps: requiresData.add(d)