Clean up and improve docs in embedder API. Fix #133.

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

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);