diff --git a/docs/C-API/call.md b/docs/C-API/call.md index 06512849..f90bf135 100644 --- a/docs/C-API/call.md +++ b/docs/C-API/call.md @@ -1,18 +1,15 @@ --- -title: Callables +title: Call icon: dot order: 6 --- -#### `bool pkpy_call(pkpy_vm*, int argc)` +### `bool pkpy_vectorcall(pkpy_vm*, int argc)` -First push callable you want to call, then push the arguments to send. +Wraps `vm->vectorcall(argc)`. -+ `argc` is the number of arguments that was pushed (not counting the callable). +This is the only way to call a function in the C-APIs. -#### `bool pkpy_call_method(pkpy_vm*, const char* name, int argc)` - -First push the object the method belongs to (self), then push the the argments. - -+ `argc` is the number of arguments that was pushed (not counting the callable or self) -+ `name` is the name of the method to call on the object +1. First push the function to call. +2. Push `self` argument if it is a method call. Otherwise, call `pkpy_push_null`. +3. Push arguments from left to right. diff --git a/docs/C-API/introduction.md b/docs/C-API/introduction.md index f3e5aba6..4c31f3a3 100644 --- a/docs/C-API/introduction.md +++ b/docs/C-API/introduction.md @@ -13,31 +13,29 @@ The C-APIs are designed for these purposes: Our C-APIs take a lot of inspiration from the lua C-APIs. Methods return a `bool` indicating if the operation succeeded or not. - Special thanks for [@koltenpearson](https://github.com/koltenpearson)'s contribution. -## Basic Functions +!!! +**C-APIs are always stable and backward compatible** in order to support the second use case. +!!! -#### `pkpy_vm* pkpy_new_vm(bool enable_os)` +### Basic Functions -Create a new VM. ++ `pkpy_vm* pkpy_new_vm(bool enable_os)` -+ `enable_os`: if true, the VM will have access to the os library + Wraps `new VM(enable_os)` in C++. -#### `bool pkpy_vm_run(pkpy_vm* vm_handle, const char* source)` ++ `void pkpy_delete_vm(pkpy_vm*)` -Run the given source code in the VM. + Wraps `delete vm` in C++. -+ `source`: the source code to run ++ `bool pkpy_exec(pkpy_vm*, const char* source)` -#### `void pkpy_delete_vm(pkpy_vm* vm_handle)` + Wraps `vm->exec`. Execute a string of source code. -Dispose the VM. ++ `bool pkpy_exec_2(pkpy_vm*, const char* source, const char* filename, int mode, const char* module)` -#### `bool pkpy_vm_exec(pkpy_vm* vm_handle, const char* source)` + Wraps `vm->exec_2`. Execute a string of source code with more options. -A wrapper of `vm->exec(...)`. +### Basic Types -#### `bool pkpy_vm_exec_2(pkpy_vm* vm_handle, const char* source, const char* filename, int mode, const char* module)` - -A wrapper of `vm->exec_2(...)`. \ No newline at end of file diff --git a/docs/C-API/specials.md b/docs/C-API/specials.md new file mode 100644 index 00000000..378da643 --- /dev/null +++ b/docs/C-API/specials.md @@ -0,0 +1,17 @@ +--- +title: Specials +icon: dot +order: 6 +--- + ++ `void pkpy_free(void* p)` + + Wraps `free(p)` in C++. + ++ `pkpy_CString pkpy_string(const char*)` + + Construct a `pkpy_CString` from a null-terminated C string. + ++ `pkpy_CName pkpy_name(const char*)` + + Construct a `pkpy_CName` from a null-terminated C string. You should cache the result of this function if you are going to use it multiple times. \ No newline at end of file diff --git a/docs/C-API/stack.md b/docs/C-API/stack.md index 3f66c97a..3f25e3db 100644 --- a/docs/C-API/stack.md +++ b/docs/C-API/stack.md @@ -4,91 +4,135 @@ icon: dot order: 8 --- -!!! -Stack index is 0-based instead of 1-based. -!!! +### Stack manipulation -## Push and Pop ++ `bool pkpy_pop(pkpy_vm*, int)` -#### `bool pkpy_pop(pkpy_vm*, int n)` + Pop `n` values from the stack. -Pop `n` items from the stack. ++ `bool pkpy_pop_top(pkpy_vm*)` + + Pop the top value from the stack. -#### `bool pkpy_push_function(pkpy_vm*, pkpy_function, int argc)` ++ `bool pkpy_dup_top(pkpy_vm*)` -Push a function onto the stack. The function is of `typedef int (*pkpy_function)(pkpy_vm*);` -The provided function should return the number of return values it leaves on the stack + Duplicate the top value on the stack. -#### `bool pkpy_push_int(pkpy_vm*, int)` ++ `bool pkpy_rot_two(pkpy_vm*)` -Push an integer onto the stack. + Swap the top two values on the stack. -#### `bool pkpy_push_float(pkpy_vm*, double)` ++ `int pkpy_stack_size(pkpy_vm*)` -Push a float onto the stack. + Get the element count of the stack. -#### `bool pkpy_push_bool(pkpy_vm*, bool)` -Push a boolean onto the stack. +### Basic push, check and convert -#### `bool pkpy_push_string(pkpy_vm*, const char*)` ++ `pkpy_push_xxx` pushes a value onto the stack. ++ `pkpy_is_xxx` checks if the value at the given index is of the given type. ++ `pkpy_to_xxx` converts the value at the given index to the given type. -Push a string onto the stack. +Stack index is 0-based instead of 1-based. And it can be negative, which means the index is counted from the top of the stack. -#### `bool pkpy_push_stringn(pkpy_vm*, const char*, int length)` +```c +// int +PK_EXPORT bool pkpy_push_int(pkpy_vm*, int); +PK_EXPORT bool pkpy_is_int(pkpy_vm*, int i); +PK_EXPORT bool pkpy_to_int(pkpy_vm*, int i, int* out); -Push a string onto the stack. +// float +PK_EXPORT bool pkpy_push_float(pkpy_vm*, float); +PK_EXPORT bool pkpy_is_float(pkpy_vm*, int i); +PK_EXPORT bool pkpy_to_float(pkpy_vm*, int i, float* out); -+ `length`: the length of the string +// bool +PK_EXPORT bool pkpy_push_bool(pkpy_vm*, bool); +PK_EXPORT bool pkpy_is_bool(pkpy_vm*, int i); +PK_EXPORT bool pkpy_to_bool(pkpy_vm*, int i, bool* out); -#### `bool pkpy_push_voidp(pkpy_vm*, void*)` +// string +PK_EXPORT bool pkpy_push_string(pkpy_vm*, pkpy_CString); +PK_EXPORT bool pkpy_is_string(pkpy_vm*, int i); +PK_EXPORT bool pkpy_to_string(pkpy_vm*, int i, pkpy_CString* out); -Push a void pointer onto the stack. +// void_p +PK_EXPORT bool pkpy_push_voidp(pkpy_vm*, void*); +PK_EXPORT bool pkpy_is_voidp(pkpy_vm*, int i); +PK_EXPORT bool pkpy_to_voidp(pkpy_vm*, int i, void** out); -#### `bool pkpy_push_none(pkpy_vm*)` +// none +PK_EXPORT bool pkpy_push_none(pkpy_vm*); +PK_EXPORT bool pkpy_is_none(pkpy_vm*, int i); +``` -Push `None` onto the stack. +### Special push -## Size Queries ++ `pkpy_push_null(pkpy_vm*)` -#### `bool pkpy_check_stack(pkpy_vm*, int free)` + Push a `PY_NULL` onto the stack. -Return true if at least `free` empty slots remain on the stack. ++ `pkpy_push_function(pkpy_vm*, const char* sig, pkpy_CFunction f)` -#### `int pkpy_stack_size(pkpy_vm*)` + Push a function onto the stack. `sig` is the function signature, e.g. `add(a: int, b: int) -> int`. `f` is the function pointer. -Return the number of elements on the stack. ++ `pkpy_push_module(pkpy_vm*, const char* name)` -## Conversion + Push a new module onto the stack. `name` is the module name. This is not `import`. It creates a new module object. -#### `bool pkpy_to_int(pkpy_vm*, int index, int* ret)` +### Advanced operations -Convert the value at the given index to an integer. + -#### `bool pkpy_to_float(pkpy_vm*, int index, double* ret)` ++ `bool pkpy_getattr(pkpy_vm*, pkpy_CName name)` -Convert the value at the given index to a float. + Push `b.` onto the stack. -#### `bool pkpy_to_bool(pkpy_vm*, int index, bool* ret)` + ``` + [b] -> [b.] + ``` -Convert the value at the given index to a boolean. ++ `bool pkpy_setattr(pkpy_vm*, pkpy_CName name)` -#### `bool pkpy_to_voidp(pkpy_vm*, int index, void** ret)` + Set `b.` to the value at the top of the stack. + First push the value, then push `b`. -Convert the value at the given index to a void pointer. + ``` + [b, value] -> [] + ``` -#### `bool pkpy_to_string(pkpy_vm*, int index, char** ret)` ++ `bool pkpy_getglobal(pkpy_vm*, pkpy_CName name)` -Convert the value at the given index to a string (strong reference). + Push a global variable onto the stack. -+ `ret` is null terminated. -+ You are responsible for freeing the string when you are done with it. ++ `bool pkpy_setglobal(pkpy_vm*, pkpy_CName name)` -#### `bool pkpy_to_stringn(pkpy_vm*, int index, const char** ret, int* size)` + Set a global variable to the value at the top of the stack. -Convert the value at the given index to a string (weak reference). ++ `bool pkpy_eval(pkpy_vm*, const char* source)` -+ `ret` is not null terminated. -+ `size` is the length of the string. -+ The string is only valid until the next API call. + Evaluate a string and push the result onto the stack. ++ `bool pkpy_unpack_sequence(pkpy_vm*, int size)` + + Unpack a sequence at the top of the stack. `size` is the element count of the sequence. + + ``` + [a] -> [a[0], a[1], ..., a[size - 1]] + ``` + ++ `bool pkpy_get_unbound_method(pkpy_vm*, pkpy_CName name)` + + It is used for method call. + Get an unbound method from the object at the top of the stack. `name` is the method name. + Also push the object as self. + + ``` + [obj] -> [obj. self] + ``` diff --git a/docs/C-API/types.md b/docs/C-API/types.md deleted file mode 100644 index 0d7c4d5c..00000000 --- a/docs/C-API/types.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Type Checking -icon: dot -order: 7 ---- - -#### `bool pkpy_is_int(pkpy_vm*, int index)` - -Return true if the value at the given index is an integer. - -#### `bool pkpy_is_float(pkpy_vm*, int index)` - -Return true if the value at the given index is a float. - -#### `bool pkpy_is_bool(pkpy_vm*, int index)` - -Return true if the value at the given index is a boolean. - -#### `bool pkpy_is_string(pkpy_vm*, int index)` - -Return true if the value at the given index is a string. - -#### `bool pkpy_is_voidp(pkpy_vm*, int index)` - -Return true if the value at the given index is a void pointer. - -#### `bool pkpy_is_none(pkpy_vm*, int index)` - -Return true if the value at the given index is `None`. \ No newline at end of file diff --git a/docs/C-API/variables.md b/docs/C-API/variables.md deleted file mode 100644 index ec471ea4..00000000 --- a/docs/C-API/variables.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Variables -icon: dot -order: 6 ---- - - -#### `bool pkpy_check_global(pkpy_vm*, const char* name)` - -Return true if the global variable exists. - -#### `bool pkpy_set_global(pkpy_vm*, const char* name)` - -Set the global variable to the value at the top of the stack. - -#### `bool pkpy_get_global(pkpy_vm*, const char* name)` - -Get the global variable and push it to the top of the stack. - -#### `bool pkpy_getattr(pkpy_vm*, const char* name)` - -A wrapper of `OP_LOAD_ATTR` bytecode. - -#### `bool pkpy_setattr(pkpy_vm*, const char* name)` - -A wrapper of `OP_STORE_ATTR` bytecode. - -#### `bool pkpy_eval(pkpy_vm*, const char* code)` - -Evaluate the code and push the result to the top of the stack. \ No newline at end of file diff --git a/docs/modules/sys.md b/docs/modules/sys.md index dac6d940..86a44d13 100644 --- a/docs/modules/sys.md +++ b/docs/modules/sys.md @@ -7,6 +7,16 @@ label: sys The version of pkpy. +### `sys.platform` + +May be one of: ++ `win32` ++ `linux` ++ `darwin` ++ `android` ++ `ios` ++ `emscripten` + ### `sys._repl()` -Get a REPL for this vm. Use its `input` method to feed strings to the REPL. \ No newline at end of file +Get a REPL for this vm. Use its `input` method to feed strings to the REPL. This function is experimental. \ No newline at end of file diff --git a/include/pocketpy/pocketpy_c.h b/include/pocketpy/pocketpy_c.h index dffde873..2392afef 100644 --- a/include/pocketpy/pocketpy_c.h +++ b/include/pocketpy/pocketpy_c.h @@ -62,10 +62,8 @@ PK_EXPORT bool pkpy_to_voidp(pkpy_vm*, int i, void** out); PK_EXPORT bool pkpy_push_none(pkpy_vm*); PK_EXPORT bool pkpy_is_none(pkpy_vm*, int i); -// null -PK_EXPORT bool pkpy_push_null(pkpy_vm*); - // special push +PK_EXPORT bool pkpy_push_null(pkpy_vm*); PK_EXPORT bool pkpy_push_function(pkpy_vm*, const char*, pkpy_CFunction); PK_EXPORT bool pkpy_push_module(pkpy_vm*, const char*);