mirror of
https://github.com/pocketpy/pocketpy
synced 2025-10-20 19:40:18 +00:00
...
This commit is contained in:
blueloveTH
parent
cb6d302b2f
commit
386ab595a9
@ -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.
|
||||
|
||||
@ -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(...)`.
|
||||
17
docs/C-API/specials.md
Normal file
17
docs/C-API/specials.md
Normal file
@ -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.
|
||||
@ -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*)`
|
||||
|
||||
#### `bool pkpy_push_function(pkpy_vm*, pkpy_function, int argc)`
|
||||
Pop the top value from the stack.
|
||||
|
||||
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
|
||||
+ `bool pkpy_dup_top(pkpy_vm*)`
|
||||
|
||||
#### `bool pkpy_push_int(pkpy_vm*, int)`
|
||||
Duplicate the top value on the stack.
|
||||
|
||||
Push an integer onto the stack.
|
||||
+ `bool pkpy_rot_two(pkpy_vm*)`
|
||||
|
||||
#### `bool pkpy_push_float(pkpy_vm*, double)`
|
||||
Swap the top two values on the stack.
|
||||
|
||||
Push a float onto the stack.
|
||||
+ `int pkpy_stack_size(pkpy_vm*)`
|
||||
|
||||
#### `bool pkpy_push_bool(pkpy_vm*, bool)`
|
||||
Get the element count of the stack.
|
||||
|
||||
Push a boolean onto the stack.
|
||||
|
||||
#### `bool pkpy_push_string(pkpy_vm*, const char*)`
|
||||
### Basic push, check and convert
|
||||
|
||||
Push a string onto the stack.
|
||||
+ `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.
|
||||
|
||||
#### `bool pkpy_push_stringn(pkpy_vm*, const char*, int length)`
|
||||
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.
|
||||
|
||||
Push a string onto the stack.
|
||||
```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);
|
||||
|
||||
+ `length`: the length of the string
|
||||
// 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);
|
||||
|
||||
#### `bool pkpy_push_voidp(pkpy_vm*, void*)`
|
||||
// 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);
|
||||
|
||||
Push a void pointer onto the stack.
|
||||
// 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);
|
||||
|
||||
#### `bool pkpy_push_none(pkpy_vm*)`
|
||||
// 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);
|
||||
|
||||
Push `None` onto the stack.
|
||||
// none
|
||||
PK_EXPORT bool pkpy_push_none(pkpy_vm*);
|
||||
PK_EXPORT bool pkpy_is_none(pkpy_vm*, int i);
|
||||
```
|
||||
|
||||
## Size Queries
|
||||
### Special push
|
||||
|
||||
#### `bool pkpy_check_stack(pkpy_vm*, int free)`
|
||||
+ `pkpy_push_null(pkpy_vm*)`
|
||||
|
||||
Return true if at least `free` empty slots remain on the stack.
|
||||
Push a `PY_NULL` onto the stack.
|
||||
|
||||
#### `int pkpy_stack_size(pkpy_vm*)`
|
||||
+ `pkpy_push_function(pkpy_vm*, const char* sig, pkpy_CFunction f)`
|
||||
|
||||
Return the number of elements on the stack.
|
||||
Push a function onto the stack. `sig` is the function signature, e.g. `add(a: int, b: int) -> int`. `f` is the function pointer.
|
||||
|
||||
## Conversion
|
||||
+ `pkpy_push_module(pkpy_vm*, const char* name)`
|
||||
|
||||
#### `bool pkpy_to_int(pkpy_vm*, int index, int* ret)`
|
||||
Push a new module onto the stack. `name` is the module name. This is not `import`. It creates a new module object.
|
||||
|
||||
Convert the value at the given index to an integer.
|
||||
### Advanced operations
|
||||
|
||||
#### `bool pkpy_to_float(pkpy_vm*, int index, double* ret)`
|
||||
<!-- PK_EXPORT bool pkpy_getattr(pkpy_vm*, pkpy_CName);
|
||||
PK_EXPORT bool pkpy_setattr(pkpy_vm*, pkpy_CName);
|
||||
PK_EXPORT bool pkpy_getglobal(pkpy_vm*, pkpy_CName);
|
||||
PK_EXPORT bool pkpy_setglobal(pkpy_vm*, pkpy_CName);
|
||||
PK_EXPORT bool pkpy_eval(pkpy_vm*, const char* source);
|
||||
PK_EXPORT bool pkpy_unpack_sequence(pkpy_vm*, int size);
|
||||
PK_EXPORT bool pkpy_get_unbound_method(pkpy_vm*, pkpy_CName); -->
|
||||
|
||||
Convert the value at the given index to a float.
|
||||
+ `bool pkpy_getattr(pkpy_vm*, pkpy_CName name)`
|
||||
|
||||
#### `bool pkpy_to_bool(pkpy_vm*, int index, bool* ret)`
|
||||
Push `b.<name>` onto the stack.
|
||||
|
||||
Convert the value at the given index to a boolean.
|
||||
```
|
||||
[b] -> [b.<name>]
|
||||
```
|
||||
|
||||
#### `bool pkpy_to_voidp(pkpy_vm*, int index, void** ret)`
|
||||
+ `bool pkpy_setattr(pkpy_vm*, pkpy_CName name)`
|
||||
|
||||
Convert the value at the given index to a void pointer.
|
||||
Set `b.<name>` to the value at the top of the stack.
|
||||
First push the value, then push `b`.
|
||||
|
||||
#### `bool pkpy_to_string(pkpy_vm*, int index, char** ret)`
|
||||
```
|
||||
[b, value] -> []
|
||||
```
|
||||
|
||||
Convert the value at the given index to a string (strong reference).
|
||||
+ `bool pkpy_getglobal(pkpy_vm*, pkpy_CName name)`
|
||||
|
||||
+ `ret` is null terminated.
|
||||
+ You are responsible for freeing the string when you are done with it.
|
||||
Push a global variable onto the stack.
|
||||
|
||||
#### `bool pkpy_to_stringn(pkpy_vm*, int index, const char** ret, int* size)`
|
||||
+ `bool pkpy_setglobal(pkpy_vm*, pkpy_CName name)`
|
||||
|
||||
Convert the value at the given index to a string (weak reference).
|
||||
Set a global variable to the value at the top of the stack.
|
||||
|
||||
+ `ret` is not null terminated.
|
||||
+ `size` is the length of the string.
|
||||
+ The string is only valid until the next API call.
|
||||
+ `bool pkpy_eval(pkpy_vm*, const char* source)`
|
||||
|
||||
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.<name> self]
|
||||
```
|
||||
|
||||
@ -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`.
|
||||
@ -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.
|
||||
@ -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.
|
||||
Get a REPL for this vm. Use its `input` method to feed strings to the REPL. This function is experimental.
|
||||
@ -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*);
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user