From 2cee4c83bd05b32fecbdf2039f16c951cc77481a Mon Sep 17 00:00:00 2001 From: Bob Nystrom Date: Thu, 22 Jan 2015 07:05:55 -0800 Subject: [PATCH] Clean up and improve docs in embedder API. Fix #133. --- include/wren.h | 61 +++++++++++++++++++++++++++++++------------------- src/wren_vm.c | 20 +++++++---------- 2 files changed, 46 insertions(+), 35 deletions(-) diff --git a/include/wren.h b/include/wren.h index 2ef2185b..787b5266 100644 --- a/include/wren.h +++ b/include/wren.h @@ -115,43 +115,58 @@ void wrenDefineStaticMethod(WrenVM* vm, const char* className, const char* methodName, int numParams, WrenForeignMethodFn method); -// Reads a boolean argument for a foreign call. This must only be called within -// a function provided to [wrenDefineMethod]. Retrieves the argument at [index] -// which ranges from 0 to the number of parameters the method expects - 1. +// The following functions read one of the arguments passed to a foreign call. +// They may only be called while within a function provided to +// [wrenDefineMethod] or [wrenDefineStaticMethod] that Wren has invoked. +// +// They retreive the argument at a given index which ranges from 0 to the number +// of parameters the method expects. The zeroth parameter is used for the +// receiver of the method. For example, given a foreign method "foo" on String +// invoked like: +// +// "receiver".foo("one", "two", "three") +// +// The foreign function will be able to access the arguments like so: +// +// 0: "receiver" +// 1: "one" +// 2: "two" +// 3: "three" +// +// It is an error to pass an invalid argument index. + +// Reads a boolean argument for a foreign call. Returns false if the argument +// is not a boolean. bool wrenGetArgumentBool(WrenVM* vm, int index); -// Reads a numeric argument for a foreign call. This must only be called within -// a function provided to [wrenDefineMethod]. Retrieves the argument at [index] -// which ranges from 0 to the number of parameters the method expects - 1. +// Reads a numeric argument for a foreign call. Returns 0 if the argument is not +// a number. double wrenGetArgumentDouble(WrenVM* vm, int index); -// Reads an string argument for a foreign call. This must only be called within -// a function provided to [wrenDefineMethod]. Retrieves the argument at [index] -// which ranges from 0 to the number of parameters the method expects - 1. +// Reads an string argument for a foreign call. Returns NULL if the argument is +// not a string. // // The memory for the returned string is owned by Wren. You can inspect it // while in your foreign function, but cannot keep a pointer to it after the // function returns, since the garbage collector may reclaim it. const char* wrenGetArgumentString(WrenVM* vm, int index); -// Provides a boolean return value for a foreign call. This must only be called -// within a function provided to [wrenDefineMethod]. Once this is called, the -// foreign call is done, and no more arguments can be read or return calls made. +// The following functions provide the return value for a foreign method back +// to Wren. Like above, they may only be called during a foreign call invoked +// by Wren. +// +// If none of these is called by the time the foreign function returns, the +// method implicitly returns `null`. Within a given foreign call, you may only +// call one of these once. It is an error to access any of the foreign calls +// arguments after one of these has been called. + +// Provides a boolean return value for a foreign call. void wrenReturnBool(WrenVM* vm, bool value); -// Provides a numeric return value for a foreign call. This must only be called -// within a function provided to [wrenDefineMethod]. Once this is called, the -// foreign call is done, and no more arguments can be read or return calls made. +// Provides a numeric return value for a foreign call. void wrenReturnDouble(WrenVM* vm, double value); -// Provides a null return value for a foreign call. This must only be called -// within a function provided to [wrenDefineMethod]. Once this is called, the -// foreign call is done, and no more arguments can be read or return calls made. -void wrenReturnNull(WrenVM* vm); - -// Provides a string return value for a foreign call. This must only be called -// within a function provided to [wrenDefineMethod]. Once this is called, the -// foreign call is done, and no more arguments can be read or return calls made. +// Provides a string return value for a foreign call. // // The [text] will be copied to a new string within Wren's heap, so you can // free memory used by it after this is called. If [length] is non-zero, Wren diff --git a/src/wren_vm.c b/src/wren_vm.c index f42c23cf..30252607 100644 --- a/src/wren_vm.c +++ b/src/wren_vm.c @@ -1193,7 +1193,8 @@ bool wrenGetArgumentBool(WrenVM* vm, int index) ASSERT(index >= 0, "index cannot be negative."); ASSERT(index < vm->foreignCallNumArgs, "Not that many arguments."); - // TODO: Check actual value type first. + if (!IS_BOOL(*(vm->foreignCallSlot + index))) return false; + return AS_BOOL(*(vm->foreignCallSlot + index)); } @@ -1203,7 +1204,8 @@ double wrenGetArgumentDouble(WrenVM* vm, int index) ASSERT(index >= 0, "index cannot be negative."); ASSERT(index < vm->foreignCallNumArgs, "Not that many arguments."); - // TODO: Check actual value type first. + if (!IS_NUM(*(vm->foreignCallSlot + index))) return 0.0; + return AS_NUM(*(vm->foreignCallSlot + index)); } @@ -1213,7 +1215,8 @@ const char* wrenGetArgumentString(WrenVM* vm, int index) ASSERT(index >= 0, "index cannot be negative."); ASSERT(index < vm->foreignCallNumArgs, "Not that many arguments."); - // TODO: Check actual value type first. + if (!IS_STRING(*(vm->foreignCallSlot + index))) return NULL; + return AS_CSTRING(*(vm->foreignCallSlot + index)); } @@ -1233,18 +1236,11 @@ void wrenReturnDouble(WrenVM* vm, double value) vm->foreignCallSlot = NULL; } -void wrenReturnNull(WrenVM* vm) -{ - ASSERT(vm->foreignCallSlot != NULL, "Must be in foreign call."); - - *vm->foreignCallSlot = NULL_VAL; - vm->foreignCallSlot = NULL; -} - void wrenReturnString(WrenVM* vm, const char* text, int length) { ASSERT(vm->foreignCallSlot != NULL, "Must be in foreign call."); - + ASSERT(text != NULL, "String cannot be NULL."); + size_t size = length; if (length == -1) size = strlen(text);