4.2 API for embedding

Instead of letting codger generate simple wrapper functions for you, you can omit the PROTOTYPE comment, and write Y_my_func yourself. Its prototype is

extern void Y_my_func(int argc);

The argc argument is the count of the number of items on the stack containing the arguments the interpreter is passing to Y_my_func. This would be simply the number of arguments the caller is passing to your function, were it not for the possibility of keyword arguments. Each actual keyword argument takes two spaces on the stack – one for the name of the keyword and a second for its value. If your function does not accept keywords, you can ignore the distinction between argc and the number of arguments being passed to your function.

When your function exits, whatever you leave on top of the stack becomes its return value. This section explains the programming interface (or API) which permits you to get your arguments off the stack, push new items onto the stack, set or get global variable values, and otherwise interact with the yorick interpreter. All of these functions are declared in the yapi.h header, which your C (or C++) source file should include.

The following examples do not illustrate all of the functions in yapi.h; you need to read the header file itslef for a comprehensive list. For more examples of yapi.h usage, read the yorick source file yorick/ystr.c.