From 9fb35f69bae4d93c0b20ef0a5692c7b893e96f32 Mon Sep 17 00:00:00 2001 From: blueloveTH Date: Sun, 7 May 2023 20:50:51 +0800 Subject: [PATCH] ... --- docs/C-API/general.md | 13 ----- docs/C-API/index.yml | 2 +- docs/C-API/vm.md | 16 +++++- docs/LuaC-API/call.md | 18 +++++++ docs/LuaC-API/error.md | 17 +++++++ docs/LuaC-API/index.yml | 3 ++ docs/LuaC-API/introduction.md | 33 +++++++++++++ docs/LuaC-API/stack.md | 93 +++++++++++++++++++++++++++++++++++ docs/LuaC-API/types.md | 29 +++++++++++ docs/LuaC-API/variables.md | 19 +++++++ docs/coding_style_guide.md | 2 +- docs/developer_guide.md | 2 +- docs/license.md | 2 +- docs/performance.md | 2 +- 14 files changed, 232 insertions(+), 19 deletions(-) delete mode 100644 docs/C-API/general.md create mode 100644 docs/LuaC-API/call.md create mode 100644 docs/LuaC-API/error.md create mode 100644 docs/LuaC-API/index.yml create mode 100644 docs/LuaC-API/introduction.md create mode 100644 docs/LuaC-API/stack.md create mode 100644 docs/LuaC-API/types.md create mode 100644 docs/LuaC-API/variables.md diff --git a/docs/C-API/general.md b/docs/C-API/general.md deleted file mode 100644 index da67f668..00000000 --- a/docs/C-API/general.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: General -icon: dot -order: 7 ---- -#### `void pkpy_delete(void* p)` - -Delete a pointer allocated by `pkpy_xxx_xxx`. -It can be `VM*`, `REPL*`, `char*`, etc. - -!!! -If the pointer is not allocated by `pkpy_xxx_xxx`, the behavior is undefined. -!!! diff --git a/docs/C-API/index.yml b/docs/C-API/index.yml index 15195ecd..9fb3bab8 100644 --- a/docs/C-API/index.yml +++ b/docs/C-API/index.yml @@ -1,3 +1,3 @@ -label: C-API +label: Legacy C-API icon: code order: 1 \ No newline at end of file diff --git a/docs/C-API/vm.md b/docs/C-API/vm.md index 89a6fb37..02aba913 100644 --- a/docs/C-API/vm.md +++ b/docs/C-API/vm.md @@ -3,6 +3,11 @@ title: VM icon: dot order: 10 --- + +!!! +Lua Style C-API cannot be mixed with Legacy C-API. +!!! + #### `VM* pkpy_new_vm()` Create a virtual machine. @@ -27,4 +32,13 @@ Run a given source on a virtual machine. Get a global variable of a virtual machine. Return `__repr__` of the result. -If the variable is not found, return `nullptr`. \ No newline at end of file +If the variable is not found, return `nullptr`. + +#### `void pkpy_delete(void* p)` + +Delete a pointer allocated by `pkpy_xxx_xxx`. +It can be `VM*`, `REPL*`, `char*`, etc. + +!!! +If the pointer is not allocated by `pkpy_xxx_xxx`, the behavior is undefined. +!!! diff --git a/docs/LuaC-API/call.md b/docs/LuaC-API/call.md new file mode 100644 index 00000000..06512849 --- /dev/null +++ b/docs/LuaC-API/call.md @@ -0,0 +1,18 @@ +--- +title: Callables +icon: dot +order: 6 +--- + +#### `bool pkpy_call(pkpy_vm*, int argc)` + +First push callable you want to call, then push the arguments to send. + ++ `argc` is the number of arguments that was pushed (not counting the callable). + +#### `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 diff --git a/docs/LuaC-API/error.md b/docs/LuaC-API/error.md new file mode 100644 index 00000000..54f3d460 --- /dev/null +++ b/docs/LuaC-API/error.md @@ -0,0 +1,17 @@ +--- +title: Error Handling +icon: dot +order: 5 +--- + +#### `bool pkpy_clear_error(pkpy_vm*, char** message)` + ++ If a method returns false, call the `pkpy_clear_error` method to check the error and clear it ++ If `pkpy_clear_error` returns false, it means that no error was set, and it takes no action ++ If `pkpy_clear_error` returns true, it means there was an error and it was cleared. It will provide a string summary of the error in the message parameter (if it is not NULL) If null is passed in as message, and it will just print the message to stderr. ++ You are responsible for freeing `message`. + +#### `bool pkpy_check_error(pkpy_vm*)` + +Return true if the vm is currently in an error state. + diff --git a/docs/LuaC-API/index.yml b/docs/LuaC-API/index.yml new file mode 100644 index 00000000..38d435a3 --- /dev/null +++ b/docs/LuaC-API/index.yml @@ -0,0 +1,3 @@ +label: Lua Style C-API +icon: code +order: 2 \ No newline at end of file diff --git a/docs/LuaC-API/introduction.md b/docs/LuaC-API/introduction.md new file mode 100644 index 00000000..38b9322d --- /dev/null +++ b/docs/LuaC-API/introduction.md @@ -0,0 +1,33 @@ +--- +title: Introduction +icon: dot +order: 10 +--- + +We take a lot of inspiration from the lua api for these bindings. +The key difference being most methods return a bool, +true if it succeeded false if it did not. + +!!! +Special thanks for [@koltenpearson](https://github.com/koltenpearson) for bringing us the Lua Style API implementation. +!!! + +## Basic Functions + +#### `pkpy_vm* pkpy_vm_create(bool use_stdio, bool enable_os)` + +Creates a new Lua Style VM. + ++ `use_stdio`: if true, the VM will use stdout and stderr ++ `enable_os`: if true, the VM will have access to the os library + +#### `bool pkpy_vm_run(pkpy_vm*, const char* source)` + +Runs the given source code in the VM. + ++ `source`: the source code to run + +#### `void pkpy_vm_destroy(pkpy_vm*)` + +Destroys the VM. + diff --git a/docs/LuaC-API/stack.md b/docs/LuaC-API/stack.md new file mode 100644 index 00000000..ec4d3310 --- /dev/null +++ b/docs/LuaC-API/stack.md @@ -0,0 +1,93 @@ +--- +title: Stack Manipulation +icon: dot +order: 8 +--- + +!!! +Stack index is 0-based instead of 1-based. +!!! + +## Push and Pop + +#### `bool pkpy_pop(pkpy_vm*, int n)` + +Pop `n` items from the stack. + +#### `bool pkpy_push_function(pkpy_vm*, pkpy_function)` + +Push a function onto the stack. The function is of `typedef int (*pkpy_function)(pkpy_vm*);` + +#### `bool pkpy_push_int(pkpy_vm*, int)` + +Push an integer onto the stack. + +#### `bool pkpy_push_float(pkpy_vm*, double)` + +Push a float onto the stack. + +#### `bool pkpy_push_bool(pkpy_vm*, bool)` + +Push a boolean onto the stack. + +#### `bool pkpy_push_string(pkpy_vm*, const char*)` + +Push a string onto the stack. + +#### `bool pkpy_push_stringn(pkpy_vm*, const char*, int length)` + +Push a string onto the stack. + ++ `length`: the length of the string + +#### `bool pkpy_push_voidp(pkpy_vm*, void*)` + +Push a void pointer onto the stack. + +#### `bool pkpy_push_none(pkpy_vm*)` + +Push `None` onto the stack. + +## Size Queries + +#### `bool pkpy_check_stack(pkpy_vm*, int free)` + +Return true if at least `free` empty slots remain on the stack. + +#### `int pkpy_stack_size(pkpy_vm*)` + +Return the number of elements on the stack. + +## Conversion + +#### `bool pkpy_to_int(pkpy_vm*, int index, int* ret)` + +Convert the value at the given index to an integer. + +#### `bool pkpy_to_float(pkpy_vm*, int index, double* ret)` + +Convert the value at the given index to a float. + +#### `bool pkpy_to_bool(pkpy_vm*, int index, bool* ret)` + +Convert the value at the given index to a boolean. + +#### `bool pkpy_to_voidp(pkpy_vm*, int index, void** ret)` + +Convert the value at the given index to a void pointer. + +#### `bool pkpy_to_string(pkpy_vm*, int index, char** ret)` + +Convert the value at the given index to a string (strong reference). + ++ `ret` is null terminated. ++ You are responsible for freeing the string when you are done with it. + +#### `bool pkpy_to_stringn(pkpy_vm*, int index, const char** ret, int* size)` + +Convert the value at the given index to a string (weak reference). + ++ `ret` is not null terminated. ++ `size` is the length of the string. ++ The string is only valid until the next API call. + diff --git a/docs/LuaC-API/types.md b/docs/LuaC-API/types.md new file mode 100644 index 00000000..0d7c4d5c --- /dev/null +++ b/docs/LuaC-API/types.md @@ -0,0 +1,29 @@ +--- +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/LuaC-API/variables.md b/docs/LuaC-API/variables.md new file mode 100644 index 00000000..2a04ee33 --- /dev/null +++ b/docs/LuaC-API/variables.md @@ -0,0 +1,19 @@ +--- +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. + diff --git a/docs/coding_style_guide.md b/docs/coding_style_guide.md index 717e8012..50026a98 100644 --- a/docs/coding_style_guide.md +++ b/docs/coding_style_guide.md @@ -1,6 +1,6 @@ --- icon: book -order: 2 +order: 0 label: Coding style guide --- diff --git a/docs/developer_guide.md b/docs/developer_guide.md index 1cedc783..d05b702d 100644 --- a/docs/developer_guide.md +++ b/docs/developer_guide.md @@ -1,6 +1,6 @@ --- icon: book -order: 2 +order: 0 label: Developer guide --- diff --git a/docs/license.md b/docs/license.md index a25a58c1..557d067c 100644 --- a/docs/license.md +++ b/docs/license.md @@ -1,6 +1,6 @@ --- icon: verified -order: 0 +order: -10 label: License --- diff --git a/docs/performance.md b/docs/performance.md index cf682e86..3ff42425 100644 --- a/docs/performance.md +++ b/docs/performance.md @@ -1,6 +1,6 @@ --- icon: zap -order: 1 +order: -1 label: Performance ---