From 8869e0013f4d8da48cc5fe578fbabf4958cb0a2e Mon Sep 17 00:00:00 2001 From: Ganesh Viswanathan Date: Mon, 28 Jan 2019 10:53:08 -0600 Subject: [PATCH] Update documentation --- cimport.html | 45 +- cimport.idx | 1 + git.html | 2 +- plugin.html | 1297 ++++++++++++++++++++++++++++++++++++++++++++++++++ plugin.idx | 2 + types.html | 2 +- 6 files changed, 1340 insertions(+), 9 deletions(-) create mode 100644 plugin.html create mode 100644 plugin.idx diff --git a/cimport.html b/cimport.html index 7cfdec1..3e05dde 100644 --- a/cimport.html +++ b/cimport.html @@ -1265,6 +1265,8 @@ function main() { title="cOverride(body): untyped">cOverride
  • cSkipSymbol
    • +
  • cPlugin
  • cDebug

  • Imports

    -types +plugin, types

    Procs

    @@ -1322,7 +1324,7 @@ function main() {

    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() macro block so that Nimterop no longer defines these symbols.

    For example:

    -
    int svGetCallerInfo(const char** fileName, int *lineNumber);

    This could get mapped to:

    +
    int svGetCallerInfo(const char** fileName, int *lineNumber);

    This might map to:

    proc svGetCallerInfo(fileName: ptr cstring; lineNumber: var cint)

    Whereas it might mean:

    cOverride:
   proc svGetCallerInfo(fileName: var cstring; lineNumber: var cint)

    Using the cOverride() block, nimterop can be instructed to skip over svGetCallerInfo(). This works for procs, consts and types.

    @@ -1332,7 +1334,34 @@ function main() { 
    macro cSkipSymbol(skips: varargs[string]): untyped
    -Similar to cOverride(), this macro allows filtering out symbols not of interest from the generated output.
    cSkipSymbol "proc1", "Type2"
    +Similar to cOverride(), this macro allows filtering out symbols not of interest from the generated output. +

    Examples:

    +
    cSkipSymbol "proc1", "Type2"
    + +
    + +
    macro cPlugin(body): untyped
    +
    +When cOverride() and cSkipSymbol() are not adequate, the cPlugin() macro can be used to customize the generated Nim output. The following callbacks are available at this time.
    proc onSymbol(sym: var Symbol) {.exportc, dynlib.}

    onSymbol() can be used to handle symbol name modifications required due to invalid characters like leading/trailing _ or rename symbols that would clash due to Nim's style insensitivity. It can also be used to remove prefixes and suffixes like SDL_. The symbol name and type is provided to the callback and the name can be modified.

    +

    Returning a blank name will result in the symbol being skipped. This will fail for nskParam and nskField since the generated Nim code will be wrong.

    +

    Symbol types can be any of the following:

    +
    • nskConst for constants
      • +
    • nskType for type identifiers, including primitive
      • +
    • nskParam for param names
      • +
    • nskField for struct field names
      • +
    • nskEnumField for enum (field) names, though they are in the global namespace as nskConst
      • +
    • nskProc - for proc names
      • +
    +

    nimterop/plugins is implicitly imported to provide access to standard plugin facilities.

    + +

    Examples:

    +
    cPlugin:
+  import
+    strutils
+
+  proc onSymbol*(sym: var Symbol) {...}{.exportc, dynlib.} =
+    sym.name = sym.name.strip(chars = {'_'})
+
    @@ -1375,9 +1404,11 @@ Add an include directory that is forwarded to the C/C++ compiler using 
    macro cAddStdDir(mode = "c"): untyped

    Add the standard c [default] or cpp include paths to search path used in calls to cSearchPath()

    -

    This allows something like this:

    -
    cAddStdDir()
-cImport cSearchPath("math.h")
    +

    This allows something like this:

    + +

    Examples:

    +
    cAddStdDir()
+echo cSearchPath("math.h")
    @@ -1409,7 +1440,7 @@ Add an include directory that is forwarded to the C/C++ compiler using
    - Made with Nim. Generated: 2019-01-24 01:58:20 UTC + Made with Nim. Generated: 2019-01-28 16:53:06 UTC
    diff --git a/cimport.idx b/cimport.idx index 9ff94c3..87ea44f 100644 --- a/cimport.idx +++ b/cimport.idx @@ -1,5 +1,6 @@ cOverride cimport.html#cOverride.m, cimport: cOverride(body): untyped cSkipSymbol cimport.html#cSkipSymbol.m,varargs[string] cimport: cSkipSymbol(skips: varargs[string]): untyped +cPlugin cimport.html#cPlugin.m, cimport: cPlugin(body): untyped cSearchPath cimport.html#cSearchPath,string cimport: cSearchPath(path: string): string cDebug cimport.html#cDebug.m, cimport: cDebug(): untyped cDisableCaching cimport.html#cDisableCaching.m, cimport: cDisableCaching(): untyped diff --git a/git.html b/git.html index e3cf231..536004f 100644 --- a/git.html +++ b/git.html @@ -1324,7 +1324,7 @@ function main() {

    - Made with Nim. Generated: 2019-01-24 01:58:21 UTC + Made with Nim. Generated: 2019-01-28 16:53:07 UTC
    diff --git a/plugin.html b/plugin.html new file mode 100644 index 0000000..4f1cf32 --- /dev/null +++ b/plugin.html @@ -0,0 +1,1297 @@ + + + + + + + + + + + + + + + + + +plugin + + + + + + + + +
    +
    +

    plugin

    +
    +
    + +
    + Search: +
    +
    + Group by: + +
    + + +
    +
    +
    +

    +
    +

    Types

    +
    + +
    Symbol = object
+  name*: string
+  parent*: string
+  kind*: NimSymKind
+
    +
    + + +
    + +
    OnSymbol = proc (sym: var Symbol) {...}{.cdecl.}
    +
    + + +
    + +
    + +
    +
    + +
    +
    + +
    + Made with Nim. Generated: 2019-01-28 16:53:08 UTC +
    +
    +
    +
    + + + diff --git a/plugin.idx b/plugin.idx new file mode 100644 index 0000000..c5ac576 --- /dev/null +++ b/plugin.idx @@ -0,0 +1,2 @@ +Symbol plugin.html#Symbol plugin: Symbol +OnSymbol plugin.html#OnSymbol plugin: OnSymbol diff --git a/types.html b/types.html index e31f9cb..6f4d337 100644 --- a/types.html +++ b/types.html @@ -1288,7 +1288,7 @@ function main() {

    - Made with Nim. Generated: 2019-01-24 01:58:20 UTC + Made with Nim. Generated: 2019-01-28 16:53:02 UTC