Document FFI library

Author: Sainan

docs/Runtime Environment/FFI.md

@@ -0,0 +1,161 @@
+Must be included via `require`.
+
+:::caution
+This is intended for advanced users.
+:::
+
+---
+### `ffi.open`
+Loads a DLL/SO (dynamic link library/shared object).
+#### Parameters
+1. The name of the library which is to be located by the operating system. A relative or absolute path also works.
+#### Returns
+An FFI library instance.
+#### Example
+The following C++ code:
+```cpp title="lib.cpp"
+#ifdef _WIN32
+    #define EXPORT __declspec(dllexport)
+#else
+    #define EXPORT
+#endif
+
+extern "C" EXPORT int MY_MAGIC_INT = 69;
+
+extern "C" EXPORT int add(int a, int b) {
+    return a + b;
+}
+```
+Compiled like this:
+- Windows: `clang -std=c++17 --shared -o lib.dll lib.cpp`
+- Linux/MacOS: `clang -std=c++17 --shared -o liblib.so lib.cpp`
+
+Can be used like this:
+```pluto
+local ffi = require "pluto:ffi"
+local lib = ffi.open(os.platform == "windows" ? "lib" : "./liblib.so")
+assert(lib:value("i32", "MY_MAGIC_INT") == 69)
+assert(lib:wrap("i32", "add", "i32", "i32")(38, 4) == 42)
+```
+---
+### `ffi.struct`
+Parses a subset of C for a struct.
+#### Paramters
+1. The C source code.
+#### Returns
+An FFI Struct Type instance.
+#### Example 
+```pluto
+local ffi = require "pluto:ffi"
+
+local Color = ffi.struct[[
+    struct Color {
+        uint8_t r;
+        uint8_t g;
+        uint8_t b;
+    };
+]]
+
+local c = new Color()
+c.r = 255
+print(c.r) --> 255
+```
+
+---
+### `ffi.new`
+Instantiate an FFI Struct Type by name or instance.
+#### Parameters
+1. An FFI Struct Type instance or the name of one stored on the FFI library itself.
+#### Returns
+A new instance of the struct.
+
+---
+### `ffi.cdef`
+Parses a subset of C for structs to be stored on the FFI library itself.
+#### Parameters
+1. The C source code.
+#### Example
+```pluto
+local ffi = require "pluto:ffi"
+
+ffi.cdef[[
+    struct Color {
+        uint8_t r;
+        uint8_t g;
+        uint8_t b;
+    };
+]]
+
+local c = ffi.new("Color")
+c.r = 255
+print(c.r) --> 255
+```
+
+---
+### `ffi.sizeof`
+Measures the size of an FFI Struct Type.
+#### Parameters
+1. An FFI Struct Type instance, the name of a struct stored on the FFI library itself, or an instance of the struct.
+#### Returns
+The size in bytes.
+
+---
+### `ffi.offsetof`
+Measures the offset of a field on an FFI Struct Type.
+#### Parameters
+1. An FFI Struct Type instance, the name of a struct stored on the FFI library itself, or an instance of the struct.
+2. The name of the field.
+#### Returns
+The offset in bytes.
+
+---
+### `ffi.nullptr`
+This constant can be used to give `0` to a "ptr"-type argument.
+
+---
+## FFI Library Class
+Obtained from `ffi.open`.
+
+### `wrap`
+Creates a function wrapper.
+#### Parameters
+1. The return type. Can be "void", "i8", "i16", "i32", "i64", "u8", "u16", "u32", "u64", "f32", "f64", "ptr" or "str".
+2. The name of the function.
+3. The argument type(s). Can be "void", "i8", "i16", "i32", "i64", "u8", "u16", "u32", "u64", "f32", "f64", "ptr" or "str".
+#### Returns
+A new function wrapper instance, which can be called.
+
+### `value`
+Gets an exported value and interprets it using the given type.
+#### Parameters
+1. The type. Can be "void", "i8", "i16", "i32", "i64", "u8", "u16", "u32", "u64", "f32", "f64", "ptr" or "str".
+2. The name of the export.
+#### Returns
+The interpreted value.
+
+### `cdef`
+Parses a subset of C for values and functions and puts them on the library instance.
+#### Parameters
+1. The C source code.
+#### Example
+```pluto
+local ffi = require "pluto:ffi"
+local lib = ffi.open(os.platform == "windows" ? "lib" : "./liblib.so")
+lib:cdef[[
+    int MY_MAGIC_INT;
+    int add(int a, int b);
+]]
+assert(lib.MY_MAGIC_INT == 69)
+assert(lib.add(38, 4) == 42)
+```
+This is equivalent to the following:
+```pluto
+local ffi = require "pluto:ffi"
+local lib = ffi.open(os.platform == "windows" ? "lib" : "./liblib.so")
+
+lib.MY_MAGIC_INT = lib:value("i32", "MY_MAGIC_INT")
+lib.add = lib:wrap("i32", "add", "i32", "i32")
+
+assert(lib.MY_MAGIC_INT == 69)
+assert(lib.add(38, 4) == 42)
+```

docusaurus.config.js

@@ -47,6 +47,7 @@ const config = {
       {
         theme: 'monokai-patched',
         langs: [
+          'c',
           'cpp',
           {
             id: 'pluto',

src/theme/Pluto.tmLanguage.json

@@ -147,6 +147,32 @@
           "match": "\\)",
           "name": "punctuation.section.group.end.pluto"
         },
+        {
+          "begin": "(?<=[\\.\\:]cdef|ffi\\.struct)\\s*(\\[(=*)\\[)",
+          "beginCaptures": {
+            "0": {
+              "name": "string.quoted.other.multiline.pluto"
+            },
+            "1": {
+              "name": "punctuation.definition.string.begin.pluto"
+            }
+          },
+          "contentName": "meta.embedded.pluto",
+          "end": "(\\]\\2\\])",
+          "endCaptures": {
+            "0": {
+              "name": "string.quoted.other.multiline.pluto"
+            },
+            "1": {
+              "name": "punctuation.definition.string.end.pluto"
+            }
+          },
+          "patterns": [
+            {
+              "include": "source.c"
+            }
+          ]
+        },
         {
           "begin": "(?<!--)\\[(=*)\\[",
           "beginCaptures": {