...

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.
+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:
-+ `VM::bind_func<ARGC>`
-+ `VM::bind_builtin_func<ARGC>`
-+ `VM::bind_method<ARGC>`
-+ `VM::bind_constructor<ARGC>`
-
-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:
 
 ```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<ARGC>`:
 
 ```cpp
-VM* vm = pkpy_new_vm();
+PyObject* obj = vm->new_module("test");
-vm->bind_builtin_func<0>("input", [](VM* vm, ArgsView args){
-    static std::string line;
-    std::getline(std::cin, line);
-    return VAR(line);
-});
 
-//                        vvv function name
+//                     v [function name]
-vm->bind_builtin_func<2>("add", [](VM* vm, ArgsView args){
+vm->bind_func<2>(obj, "equals", [](VM* vm, ArgsView args){
-//                    ^ argument count
+//            ^ argument count
-	i64 lhs = CAST(i64, args[0]);
+    int a = CAST(int, args[0]);
-    i64 rhs = CAST(i64, args[1]);
+    int b = CAST(int, args[1]);
-    return VAR(lhs + rhs);
+    bool result = equals(a, b);
+    return VAR(result);
 });
-```
+```
+
++ 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<ARGC>` 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<ARGC>` usage is almost the same as `vm->bind_func<ARGC>`.
+The only difference is that `ARGC` in `vm->bind_method<ARGC>` 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.

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: