diff --git a/docs/quick-start/bind.md b/docs/quick-start/bind.md index ebd08bc6..4e647cc1 100644 --- a/docs/quick-start/bind.md +++ b/docs/quick-start/bind.md @@ -4,48 +4,108 @@ label: 'Bind native function' order: 60 --- -In `VM` class, there are 4 methods to bind native function. - -+ `VM::bind_func` -+ `VM::bind_builtin_func` -+ `VM::bind_method` -+ `VM::bind_constructor` - -They are all template methods, the template argument is a `int` number, indicating the argument count. For variadic arguments, use `-1`. For methods, `ARGC` do not include `self`. - -!!! - -Native functions do not support keyword arguments. - -!!! - -pkpy uses a universal C function pointer for native functions: +pkpy allows to wrap a function pointer as a python function or method that can be called in python code. +This function pointer has the following signature: ```cpp typedef PyObject* (*NativeFuncC)(VM*, ArgsView); ``` ++ The first argument is the pointer of `VM` instance. ++ The second argument is an array-like object indicates the arguments list. You can use `[]` operator to get the element. ++ The return value is a `PyObject*`, which should not be `nullptr`. If there is no return value, return `vm->None`. -The first argument is the pointer of `VM` instance. +!!! +Native functions do not support keyword arguments. +!!! -The second argument is a view of an array. You can use `[]` operator to get the element. If you have specified `ARGC` other than `-1`, the interpreter will ensure `args.size() == ARGC`. No need to do size check. +### Bind a function -The return value is a `PyObject*`, which should not be `nullptr`. If there is no return value, return `vm->None`. +Assume you have a cpp function `bool equals(int a, int b)`. +```cpp +bool equals(int a, int b){ + return a == b; +} +``` -This is an example of binding the `input()` function to the `builtins` module. +You can bind it into `test.equals` by using `vm->bind_func`: ```cpp -VM* vm = pkpy_new_vm(); -vm->bind_builtin_func<0>("input", [](VM* vm, ArgsView args){ - static std::string line; - std::getline(std::cin, line); - return VAR(line); -}); +PyObject* obj = vm->new_module("test"); -// vvv function name -vm->bind_builtin_func<2>("add", [](VM* vm, ArgsView args){ -// ^ argument count - i64 lhs = CAST(i64, args[0]); - i64 rhs = CAST(i64, args[1]); - return VAR(lhs + rhs); +// v [function name] +vm->bind_func<2>(obj, "equals", [](VM* vm, ArgsView args){ +// ^ argument count + int a = CAST(int, args[0]); + int b = CAST(int, args[1]); + bool result = equals(a, b); + return VAR(result); }); -``` \ No newline at end of file +``` + ++ The first argument is the target object to bind. It can be any python object with an instance dict, such as a module, a class, or an instance. ++ The second argument is the function name. ++ The third argument is the function pointer. We often use lambda expression to wrap it. A non-capturing lambda expression can be converted to a function pointer. + +The template argument `ARGC` is the argument count of the function. If the function is variadic, use `-1` as the argument count. + +The interpreter will ensure `args.size() == ARGC` and throws `TypeError` if not. +For variadic functions, you need to check `args.size()` manually. + +If you want to bind a function into `builtins` module, use `vm->bind_builtin_func` instead. + + +### Bind a constructor + +The constructor of a class is a special function that returns an instance of the class. +It corresponds to the `__new__` magic method in python (not `__init__`). + +```cpp +vm->bind_constructor<3>(type, [](VM* vm, ArgsView args){ + float x = CAST_F(args[1]); + float y = CAST_F(args[2]); + return VAR(Vec2(x, y)); +}); +``` + +### Bind a method + +The `vm->bind_method` usage is almost the same as `vm->bind_func`. +The only difference is that `ARGC` in `vm->bind_method` does not include the `self` argument. + +```cpp +vm->bind_method<1>("int", "equals", [](VM* vm, ArgsView args){ + int self = CAST(int, args[0]); + int other = CAST(int, args[1]); + return VAR(self == other); +}); +``` + +### Bind a magic method + +For some magic methods, we provide specialized binding function. +They do not take universal function pointer as argument. +You need to provide the detailed `Type` object and the corresponding function pointer. + +```cpp +PyObject* __add__(PyObject* lhs, PyObject* rhs){ + int a = CAST(int, lhs); + int b = CAST(int, rhs); + return VAR(a + b); +} + +Type type = vm->tp_int; +vm->bind__add__(type, __add__); +``` + +This specialized binding function has optimizations and result in better performance when calling from python code. + +For example, `vm->bind__add__` is preferred over `vm->bind_method<1>(type, "__add__", ...)`. + +### Bind a property + +You can use `vm->property(...)` to create a `property` object and assign it to an type object. + +### Further reading + +See [linalg.h](src/linalg.h) for a complete example that uses all the binding functions +for `vec2`, `vec3` and `mat3x3` types. \ No newline at end of file diff --git a/docs/quick-start/modules.md b/docs/quick-start/modules.md index 4f67f75d..2df66a1f 100644 --- a/docs/quick-start/modules.md +++ b/docs/quick-start/modules.md @@ -48,7 +48,7 @@ print(test.add(1, 2)) # 3 ``` -### Module resolution +### Module resolution order When you do `import` a module, the VM will try to find it in the following order: