feat(selectors): Refactor to use selectors (#33)

* feat(ffi-callback): support `ffi.Callback` params * feat(selectors): Refactor to use selectors BREAKING CHANGE: refactor `clangffi` cli arguments. BREAKING CHANGE: refactor `libclang-bindings` visit options to require `preprocessorDefinitions`. * fix(readme): update readme
RainwayApp · Jan 8, 2022 · 0801a4a · 0801a4a
1 parent 0f5c539
commit 0801a4a
Show file tree

Hide file tree

Showing 19 changed files with 13,024 additions and 12,364 deletions.
diff --git a/package.json b/package.json
@@ -5,10 +5,10 @@
   "description": "lerna workspace for clangffi, libclang-bindings tools",
   "scripts": {
     "clangffi": "node packages/clangffi/dist/bin/clangffi.js",
-    "generate-dogfood": "npm run clangffi -- -i vendor/llvm-project/clang/include/clang-c/Index.h -I vendor/llvm-project/clang/include/ -o packages/libclang-bindings/src/libclang.ts --allow-symbol time_t --allow-symbol __time32_t --allow-symbol __time64_t",
+    "generate-dogfood": "npm run clangffi -- -i vendor/llvm-project/clang/include/clang-c/Index.h -I vendor/llvm-project/clang/include/ -o packages/libclang-bindings/src/libclang.ts --include *time*_t --include-file vendor/llvm-project/clang/include/clang-c/",
     "bootstrap": "lerna bootstrap",
     "build": "lerna run build --stream",
-    "test": "lerna run test --stream -- -- --passWithNoTests"
+    "test": "lerna run test --stream"
   },
   "author": "Ben Greenier <ben@rainway.com>",
   "license": "MIT",

diff --git a/packages/clangffi/README.md b/packages/clangffi/README.md
@@ -28,36 +28,79 @@ For more information see `npx clangffi --help`:
 
 ```
 Options:
-      --version            Show version number                         [boolean]
-  -i, --input              Input header path                 [string] [required]
-  -o, --output             Output typescript file path       [string] [required]
-  -L, --language           Language to parse input as
-                                   [string] [choices: "c", "cpp"] [default: "c"]
-  -I, --include-directory  Additional include directories to use during parsing
-                                                           [array] [default: []]
-      --lib-path           The path to the libclang binary to load.     [string]
-      --allow-file         Additional file paths to allow symbols from
-                                                           [array] [default: []]
-      --allow-symbol       Additional symbol name to allow regardless of it's
-                           location                        [array] [default: []]
-      --crlf               Use crlf endings instead of lf
-                                                      [boolean] [default: false]
-      --no-sibling         Does not include sibling file symbols in the
-                           generated bindings         [boolean] [default: false]
-      --no-prettier        Does not run prettier on the generated binding output
-                                                      [boolean] [default: false]
-      --help               Show help                                   [boolean]
+      --version              Show version number                                                                                                                                                                                                    [boolean]
+  -i, --input                Path to the header from which we will generate bindings.                                                                                                                                                     [string] [required]
+  -o, --output               Path to the output typescript file into which we will write the generated bindings.                                                                                                                          [string] [required]
+  -L, --language             The language libclang should parse the input as.                                                                                                                                   [string] [choices: "c", "cpp"] [default: "c"]
+  -I, --include-directory    Additional include directories to use during parsing.                                                                                                                                                      [array] [default: []]
+  -D, --define               Preprocessor definitions to use during parsing.                                                                                                                                                            [array] [default: []]
+  -R, --remap                Custom native symbol mappings that override the default.                                                                                                                                                   [array] [default: []]
+      --crlf                 Flag indicating if `crlf` line endings should be used instead of `lf`.                                                                                                                                [boolean] [default: false]
+      --prettier             Flag indicating if `prettier` will be run against the bindings before output.                                                                                                                          [boolean] [default: true]
+      --lib-path             Specifies an absolute path to `libclang` which will be used instead of searching `PATH`.                                                                                                                                [string]
+      --default-symbols      Flag indicating if symbols in the `input` file will be automatically included in the bindings.                                                                                                         [boolean] [default: true]
+      --include              Symbols to explicitly include in the bindings.                                                                                                                                                             [array] [default: []]
+      --include-file         File paths to explicitly include symbols from, in addition to the default. If a directory path is given symbols from all files in that directory will be included.                                         [array] [default: []]
+      --exclude              Symbols to explicitly exclude from the bindings. Overrides `include` if there is a conflict.                                                                                                               [array] [default: []]
+      --hard-remap, --remap  Custom native to node symbol mappings that override the default.                                                                                                                                           [array] [default: []]
+      --help                 Show help                                                                                                                                                                                                              [boolean]
+
+Examples:
+  clangffi --input path/to/header.h --output path/to/output.ts                                           Generate bindings with `libclang` in `PATH`.
+  clangffi --lib-path path/to/libclang --input path/to/header.h --output path/to/output.ts               Generate bindings with a custom `libclang` path.
+  clangffi --input path/to/header.h --output path/to/output.ts --include *Cb                             Generate bindings, including all symbols with names ending in `Cb`.
+  clangffi --input path/to/header.h --output path/to/output.ts --remap 'time_t=long long'                Generate bindings, remapping symbol `time_t` to native type `long long`.
+  clangffi --input path/to/header.h --output path/to/output.ts --hard-remap 'time_t=ref.types.longlong'  Generate bindings, hard remapping symbol `time_t` to node type `ref.types.longlong`.
 
 Generate typescript ffi-napi bindings for any c/c++ library using libclang.
 ```
 
 ## Selecting symbols
 
-By default, only symbols that are directly sourced from the `input` header or included files that are next to the input header on disk (e.g. "sibling" files) will be included in the bindings.
+By default, only symbols from the `input` file are included. This behavior can be disabled with `--no-default-symbols`.
 
-To include other symbols, specify the `--allow-file` flag, passing other source files. E.g. `--input path/to/initial/header.h --allow-file path/to/included/header.h`. It is also possible to allow specific symbols with the `--allow-symbol` flag, which includes symbols with a particular name regardless of their source location. E.g. `--input path/to/initial/header.h --allow-symbol YourSymbolName`.
+To include additional symbols, use `--include` and `--include-file` - these flags include symbols by name, or symbols within a file, respectively. Further, to exclude symbols use `--exclude`, which will override any explicitly included symbols if there's a conflict.
 
-When both `--allow-file` and `--allow-symbol` are used, all symbols from the `--allow-file` files are included, as well as any symbols that are specified from `--allow-symbol`. Further - Just to clarify - if a symbol matches both `--allow-file` and `--allow-symbol` it's included (hopefully that's what you'd expect).
+### Selection strings
+
+> This type of string is accepted for `--include`, `--exclude`. It is also used for the key value in `--remap` and `--hard-remap`.
+
+A selection string can be used to filter symbols by their names. They support wildcards (e.g. `*`) to match any character in a symbol name. They also provide a way to identify a symbol based on it's parent, using `:` as a separator. For instance, to match a child field named `MyField` of a struct named `MyStruct` we could use the selector string `MyStruct:MyField`. This notation can be expanded to succinctly identify multiple children, e.g. `MyStruct:{MyFirstField, MySecondField}`. Further, it can be used to identify function parameters by their index - e.g. `MyFunc:0` to select the first parameter in a function named `MyFunc`. The full spec for a selection string can be found below:
+
+`<symbolTitle>[:<symbolChild>]` or `<symbolTitle>[:{<symbolChild>, ...}]`
+
+Where **symbolTitle** is:
+
+```
+[*A-Za-z0-9_\-]+
+```
+
+Where **symbolChild** is:
+
+```
+[*A-Za-z0-9_\- ]+
+```
+
+For example, here are some **valid selectors**:
+
+```
+MyType
+MyType:MyParam
+MyType:*Param
+MyType:{MyParam1, MyParam2}
+MyFunc:0
+```
+
+And some **invalid selectors**:
+
+```
+Fn1:param1, Fn2:param2
+Fn1:{param1
+Fn1:param1, param2
+Fn1:param1}
+```
+
+See [the tests](./packages/clangffi/src/lib/selector.test.ts) for more info.
 
 ## Logging
 

diff --git a/packages/clangffi/babel.config.js → packages/clangffi/babel.config.cjs b/packages/clangffi/babel.config.js → packages/clangffi/babel.config.cjs