Flags for toast, docs update

1 files changed, 44 insertions, 31 deletions

diff --git a/nimterop/cimport.nim b/nimterop/cimport.nim
index 1249ee9..8c3d6c7 100644
--- a/nimterop/cimport.nim
+++ b/nimterop/cimport.nim
@@ -124,7 +124,8 @@ proc getNimCheckError(output: string): tuple[tmpFile, errors: string] =
 
   result.errors = "\n\n" & check
 
-proc getToast(fullpath: string, recurse: bool = false, dynlib: string = "", noNimout = false): string =
+proc getToast(fullpath: string, recurse: bool = false, dynlib: string = "",
+  mode = "c", flags = "", noNimout = false): string =
   var
     ret = 0
     cmd = when defined(Windows): "cmd /c " else: ""
@@ -137,6 +138,9 @@ proc getToast(fullpath: string, recurse: bool = false, dynlib: string = "", noNi
   if recurse:
     cmd.add " --recurse"
 
+  if flags.len != 0:
+    cmd.add flags
+
   for i in gStateCT.defines:
     cmd.add &" --defines+={i.quoteShell}"
 
@@ -175,7 +179,7 @@ proc getGccPaths(mode = "c"): string =
 macro cOverride*(body): untyped =
   ## When the wrapper code generated by nimterop is missing certain symbols or not
   ## accurate, it may be required to hand wrap them. Define them in a
-  ## `cOverride() <cimport.html#cOverride.m,>`_ macro block so that Nimterop no
+  ## `cOverride() <cimport.html#cOverride.m>`_ macro block so that Nimterop no
   ## longer defines these symbols.
   ##
   ## For example:
@@ -197,12 +201,12 @@ macro cOverride*(body): untyped =
   ##    cOverride:
   ##      proc svGetCallerInfo(fileName: var cstring; lineNumber: var cint)
   ##
-  ## Using the `cOverride() <cimport.html#cOverride.m,>`_ block, nimterop
+  ## Using the `cOverride() <cimport.html#cOverride.m>`_ block, nimterop
   ## can be instructed to skip over ``svGetCallerInfo()``. This works for procs,
   ## consts and types.
   ##
-  ## `cOverride() <cimport.html#cOverride.m,>`_ only affects calls to
-  ## `cImport() <cimport.html#cImport.m,>`_ that follow it.
+  ## `cOverride() <cimport.html#cOverride.m>`_ only affects calls to
+  ## `cImport() <cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring>`_ that follow it.
 
   proc recFindIdent(node: NimNode): seq[string] =
     if node.kind != nnkIdent:
@@ -222,18 +226,18 @@ macro cOverride*(body): untyped =
     echo "# Overriding " & gStateCT.symOverride.join(" ")
 
 proc cSkipSymbol*(skips: seq[string]) {.compileTime.} =
-  ## Similar to `cOverride() <cimport.html#cOverride.m,>`_, this macro allows
+  ## Similar to `cOverride() <cimport.html#cOverride.m>`_, this macro allows
   ## filtering out symbols not of interest from the generated output.
   ##
-  ## `cSkipSymbol() <cimport.html#cSkipSymbol.m%2Cseq[string]>`_ only affects calls to
-  ## `cImport() <cimport.html#cImport.m,>`_ that follow it.
+  ## `cSkipSymbol() <cimport.html#cSkipSymbol%2Cseq[T][string]>`_ only affects calls to
+  ## `cImport() <cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring>`_ that follow it.
   runnableExamples:
     static: cSkipSymbol @["proc1", "Type2"]
   gStateCT.symOverride.add skips
 
 macro cPlugin*(body): untyped =
-  ## When `cOverride() <cimport.html#cOverride.m,>`_ and `cSkipSymbol() <cimport.html#cSkipSymbol.m%2Cseq[string]>`_
-  ## are not adequate, the `cPlugin() <cimport.html#cPlugin.m,>`_ macro can be used
+  ## When `cOverride() <cimport.html#cOverride.m>`_ and `cSkipSymbol() <cimport.html#cSkipSymbol%2Cseq[T][string]>`_
+  ## are not adequate, the `cPlugin() <cimport.html#cPlugin.m>`_ macro can be used
   ## to customize the generated Nim output. The following callbacks are available at
   ## this time.
   ##
@@ -259,8 +263,8 @@ macro cPlugin*(body): untyped =
   ##
   ## ``nimterop/plugins`` is implicitly imported to provide access to standard plugin facilities.
   ##
-  ## `cPlugin() <cimport.html#cPlugin.m,>`_  only affects calls to
-  ## `cImport() <cimport.html#cImport.m,>`_ that follow it.
+  ## `cPlugin() <cimport.html#cPlugin.m>`_  only affects calls to
+  ## `cImport() <cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring>`_ that follow it.
   runnableExamples:
     cPlugin:
       import strutils
@@ -292,13 +296,13 @@ macro cPlugin*(body): untyped =
 
 proc cSearchPath*(path: string): string {.compileTime.}=
   ## Get full path to file or directory ``path`` in search path configured
-  ## using `cAddSearchDir() <cimport.html#cAddSearchDir,>`_ and
+  ## using `cAddSearchDir() <cimport.html#cAddSearchDir%2Cstring>`_ and
   ## `cAddStdDir() <cimport.html#cAddStdDir,string>`_.
   ##
   ## This can be used to locate files or directories that can be passed onto
-  ## `cCompile() <cimport.html#cCompile.m,,string>`_,
-  ## `cIncludeDir() <cimport.html#cIncludeDir.m,>`_ and
-  ## `cImport() <cimport.html#cImport.m,>`_.
+  ## `cCompile() <cimport.html#cCompile.m%2C%2Cstring%2Cstring>`_,
+  ## `cIncludeDir() <cimport.html#cIncludeDir.m>`_ and
+  ## `cImport() <cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring>`_.
 
   result = findPath(path, fail = false)
   if result.len == 0:
@@ -318,9 +322,9 @@ proc cDebug*() {.compileTime.} =
 proc cDisableCaching*() {.compileTime.} =
   ## Disable caching of generated Nim code - useful during wrapper development
   ##
-  ## If files included by header being processed by `cImport() <cimport.html#cImport.m,>`_
+  ## If files included by header being processed by `cImport() <cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring>`_
   ## change and affect the generated content, they will be ignored and the cached
-  ## value will continue to be used . Use `cDisableCaching() <cimport.html#cDisableCaching,>`_
+  ## value will continue to be used . Use `cDisableCaching() <cimport.html#cDisableCaching>`_
   ## to avoid this scenario during development.
   ##
   ## ``nim -f`` was broken prior to 0.19.4 but can also be used to flush the cached content.
@@ -328,8 +332,10 @@ proc cDisableCaching*() {.compileTime.} =
   gStateCT.nocache = true
 
 macro cDefine*(name: static string, val: static string = ""): untyped =
-  ## ``#define`` an identifer that is forwarded to the C/C++ compiler
-  ## using ``{.passC: "-DXXX".}``
+  ## ``#define`` an identifer that is forwarded to the C/C++ preprocessor if
+  ## called within `cImport() <cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring>`_
+  ## or `c2nImport() <cimport.html#c2nImport.m%2C%2Cstring%2Cstring%2Cstring>`_ as well as to the
+  ## C/C++ compiler during Nim compilation using ``{.passC: "-DXXX".}``
 
   result = newNimNode(nnkStmtList)
 
@@ -362,9 +368,10 @@ proc cAddSearchDir*(dir: string) {.compileTime.} =
     gStateCT.searchDirs.add(dir)
 
 macro cIncludeDir*(dir: static string): untyped =
-  ## Add an include directory that is forwarded to the C/C++ compiler
-  ## using ``{.passC: "-IXXX".}``. This is also provided to the
-  ## preprocessor during Nim code generation.
+  ## Add an include directory that is forwarded to the C/C++ preprocessor if
+  ## called within `cImport() <cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring>`_
+  ## or `c2nImport() <cimport.html#c2nImport.m%2C%2Cstring%2Cstring%2Cstring>`_ as well as to the
+  ## C/C++ compiler during Nim compilation using ``{.passC: "-IXXX".}``.
 
   var dir = interpPath(dir)
   result = newNimNode(nnkStmtList)
@@ -489,16 +496,17 @@ macro cCompile*(path: static string, mode = "c", exclude = ""): untyped =
   if gStateCT.debug:
     echo result.repr
 
-macro cImport*(filename: static string, recurse: static bool = false, dynlib: static string = ""): untyped =
+macro cImport*(filename: static string, recurse: static bool = false, dynlib: static string = "",
+  mode: static string = "c", flags: static string = ""): untyped =
   ## Import all supported definitions from specified header file. Generated
   ## content is cached in ``nimcache`` until ``filename`` changes unless
-  ## `cDisableCaching() <cimport.html#cDisableCaching,>`_ is set. ``nim -f``
+  ## `cDisableCaching() <cimport.html#cDisableCaching>`_ is set. ``nim -f``
   ## can also be used after Nim v0.19.4 to flush the cache.
   ##
   ## ``recurse`` can be used to generate Nim wrappers from ``#include`` files
   ## referenced in ``filename``. This is only done for files in the same
   ## directory as ``filename`` or in a directory added using
-  ## `cIncludeDir() <cimport.html#cIncludeDir.m,>`_
+  ## `cIncludeDir() <cimport.html#cIncludeDir.m>`_
   ##
   ## ``dynlib`` can be used to specify the Nim string to use to specify the dynamic
   ## library to load the imported symbols from. For example:
@@ -520,8 +528,13 @@ macro cImport*(filename: static string, recurse: static bool = false, dynlib: st
   ##    cImport("pcre.h", dynlib="dynpcre")
   ##
   ## If ``dynlib`` is not specified, the C/C++ implementation files can be compiled in
-  ## with `cCompile() <cimport.html#cCompile.m,,string>`_, or the ``{.passL.}`` pragma
+  ## with `cCompile() <cimport.html#cCompile.m%2C%2Cstring%2Cstring>`_, or the ``{.passL.}`` pragma
   ## can be used to specify the static lib to link.
+  ##
+  ## ``mode`` is purely for forward compatibility when toast adds C++ support. It can
+  ## be ignored for the foreseeable future.
+  ##
+  ## ``flags`` can be used to pass any other command line arguments to ``toast``.
 
   result = newNimNode(nnkStmtList)
 
@@ -531,7 +544,7 @@ macro cImport*(filename: static string, recurse: static bool = false, dynlib: st
   echo "# Importing " & fullpath
 
   let
-    output = getToast(fullpath, recurse, dynlib)
+    output = getToast(fullpath, recurse, dynlib, mode, flags)
 
   if gStateCT.debug:
     echo output
@@ -549,10 +562,10 @@ macro c2nImport*(filename: static string, recurse: static bool = false, dynlib:
   mode: static string = "c", flags: static string = ""): untyped =
   ## Import all supported definitions from specified header file using ``c2nim``
   ##
-  ## Similar to `cImport() <cimport.html#cImport.m,>`_ but uses ``c2nim`` to generate
+  ## Similar to `cImport() <cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring>`_ but uses ``c2nim`` to generate
   ## the Nim wrapper instead of ``toast``. Note that neither
-  ## `cOverride() <cimport.html#cOverride.m,>`_, `cSkipSymbol() <cimport.html#cSkipSymbol.m%2Cseq[string]>`_
-  ## nor `cPlugin() <cimport.html#cPlugin.m,>`_ have any impact on ``c2nim``.
+  ## `cOverride() <cimport.html#cOverride.m>`_, `cSkipSymbol() <cimport.html#cSkipSymbol%2Cseq[T][string]>`_
+  ## nor `cPlugin() <cimport.html#cPlugin.m>`_ have any impact on ``c2nim``.
   ##
   ## ``toast`` is only used to preprocess the header file and recurse
   ## if specified.