diff --git a/docs/DoxygenLayout.xml b/docs/DoxygenLayout.xml index 1140d1e..5078c6c 100644 --- a/docs/DoxygenLayout.xml +++ b/docs/DoxygenLayout.xml @@ -3,6 +3,7 @@ + diff --git a/docs/c_functions.md b/docs/c_functions.md index dd632e6..af81440 100644 --- a/docs/c_functions.md +++ b/docs/c_functions.md @@ -1,3 +1,67 @@ ## Binding C Functions {#c_functions} +Whether you're embedding Kuroko in an application or writing an extension module, binding a C function is something you'll want to do. +### The Easy Way + +```c +#include +#include +#include + +KRK_FUNC(myfunction,{ + FUNCTION_TAKES_EXACTLY(1); + CHECK_ARG(0,int,krk_integer_type,myarg); + return INTEGER_VAL(myarg*myarg); +}) + +int main(int argc, char *argv[]) { + krk_initVM(0); + BIND_FUNC(vm.builtins, myfunction); + krk_startModule("__main__"); + krk_interpret("print(myfunction(42))",""); + krk_freeVM(); + return 0; +} +``` + +This demo uses the utility macros provided in `` to easily create a function with argument checking and bind it to the builtin namespace. + +`KRK_FUNC()` takes care of the function signature, function naming, and default return value of `None`. + +`FUNCTION_TAKES_EXACTLY()` provides simple argument count validation. `FUNCTION_TAKES_AT_LEAST()` and `FUNCTION_TAKES_AT_MOST()` are also available. + +`CHECK_ARG()` validates the type of arguments passed to the function and unboxes them to C types. + +`INTEGER_VAL()` converts a C integer to a Kuroko `int` value. + +`BIND_FUNC()` binds the function to a namespace table. + +### The Hard Way + +While the macros above provide a convenient way to bind functions, they are just wrappers around lower-level functionality of the API. + +```c +#include +#include + +static KrkValue myfunction(int argc, KrkValue argv[], int hasKw) { + int myarg; + + if (argc != 1) return krk_runtimeError(vm.exceptions->argumentError, "myfunction() expects exactly 1 argument, %d given", argc); + if (!IS_INTEGER(argv[0])) return krk_runtimeError(vm.exceptions->typeError, "expected int, not '%s'", krk_typeName(argv[0])); + + myarg = AS_INTEGER(argv[0]); + + return INTEGER_VAL(myarg*myarg); +} + +int main(int argc, char *argv[]) { + krk_initVM(0); + krk_defineNative(&vm.builtins->fields, "myfunction", myfunction); + krk_startModule("__main__"); + krk_interpret("print(myfunction(42))", ""); + krk_freeVM(); + return 0; +} +``` diff --git a/docs/doxy.css b/docs/doxy.css index c70bca0..d949e8f 100644 --- a/docs/doxy.css +++ b/docs/doxy.css @@ -45,6 +45,8 @@ } .header { margin-top: 1em; + margin-left: 1rem; + margin-right: 1rem; } .header a { text-decoration: none; } .header a:hover { text-decoration: underline; } @@ -53,10 +55,11 @@ font-size: small; } .header>.headertitle { - font-size: 25px; + font-size: 26px; font-weight: bold; } .contents { + margin: 1rem; margin-bottom: 2rem; } .contents a { text-decoration: none; } @@ -69,6 +72,12 @@ .contents h2 { font-size: 26px; } +.contents h3 { + font-size: 22px; +} +.contents h4 { + font-size: 18px; +} .contents a { scroll-margin-top: 4rem; } @@ -264,11 +273,11 @@ div.memdoc { white-space: pre-wrap; } .fragment { - margin: 1rem; background-color: #1f1f1f; padding: 0.5rem; border-radius: 5px; color: #e6e6e6; + margin-bottom: 0.5rem; } .fragment a { color: inherit; diff --git a/docs/embedding.md b/docs/embedding.md index b5fc138..c40eae6 100644 --- a/docs/embedding.md +++ b/docs/embedding.md @@ -27,8 +27,6 @@ Kuroko's public API is exposed primarily through the `` header. `` provides internal functions for finer control over how the VM operates. -@bsnote{warning,Headers are in the process of being reorganized and the above statements are not necessarily true _yet_.} - Other headers provide convenience functions and macros for building C extensions. #### Initializing the VM diff --git a/docs/index.md b/docs/index.md index ebf8dfa..b3acecc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,5 +3,3 @@ Take a look at the @ref modulelist or learn how to embed Kuroko with the @ref embedding. You can also find a complete list of all classes provided by the standard library in the @ref classindex and all functions in the @ref functionindex. - -@bsnote{This documentation is a work-in-progress.} diff --git a/src/kuroko/vm.h b/src/kuroko/vm.h index 2f23c2b..1615446 100644 --- a/src/kuroko/vm.h +++ b/src/kuroko/vm.h @@ -622,8 +622,8 @@ extern KrkValue krk_set_of(int argc, KrkValue argv[], int hasKw); * Calls the callable @p argCount stack entries down from the top * of the stack, passing @p argCount arguments. Resumes execution * of the VM for managed calls until they are completed. Pops - * @p argCount items from the stack and returns the result of - * the call. + * all arguments and the callable from the stack and returns the + * return value of the call. * * @param argCount Arguments to collect from the stack. * @return The return value of the function.