30
30
PLUG_API int yarg_subroutine(void);
32
The argc arguments are on the interpreter's stack. When you return
32
The argc arguments are on the interpreter stack. When you return
33
33
from my_builtin, the top of the stack becomes the return value of your
34
34
function. This API refers to elements on the stack by an index iarg;
35
35
iarg=0 means the top of the stack, iarg=1 is the second stack element,
94
95
PLUG_API int yarg_typeid(int iarg);
95
96
PLUG_API int yarg_scratch(int iarg);
96
97
PLUG_API int yarg_list(int iarg);
98
PLUG_API int yarg_true(int iarg);
98
100
There are ten possible array data types, internally identified by the
99
101
typeid value 0-9. The char, short, int, long, float, complex, string,
275
278
n stack elements, and yarg_swap for interchanging stack elements
276
279
(generally to set up for yarg_drop). As long as you make sure your
277
280
return value is at the top of the stack when you return from
278
my_builtin, you probably won't need these.
281
my_builtin, you probably will not need these.
280
283
PLUG_API void yarg_drop(int n);
281
284
PLUG_API void yarg_swap(int iarg1, int iarg2);
291
294
The yarg_conform routine checks array conformability. The return
292
295
argument of yarg_conform is the cfmdims dimension list of the result
293
of a binary operation on arrays of dims1 and dims2; its return value
296
of a binary operation on arrays of dims1 and dims2- its return value
294
297
is -1 if dims1 and dims2 are not conformable, or the union of zero to
295
298
three of the flags Y_1_BCAST, Y_2_BCAST, Y_1_EXTEND, or Y_2_EXTEND.
296
299
If the Y_1_BCAST flags is set, it means that one or more of the dims1
389
392
void (*on_free)(void *);
390
393
void (*on_print)(void *);
391
394
void (*on_eval)(void *, int);
392
void (*on_extract)(void *, long);
395
void (*on_extract)(void *, char *);
395
398
PLUG_API void *ypush_obj(y_userobj_t *uo_type, unsigned long size);
417
420
member on_extract is called as a result of interpreted code
418
421
object.member_name
419
422
producing the compiled call
420
on_extract(object, index)
421
where index is the index in the global symbol table corresponding to
422
the variable named member_name (the value of that variable is
423
irrelevant). Again, you should leave the result on the top of the
424
stack. If on_eval or on_extract is zero, that operation will cause a
425
runtime error (the default behavior). Note that you can use the
426
yarg_kw_init function (with kiargs=0) to retrieve name indices.
423
on_extract(object, member_name)
424
Again, you should leave the result on the top of the stack. If
425
on_eval or on_extract is zero, that operation will cause a runtime
426
error (the default behavior). Note that you can use the yarg_kw_init
427
function (with kiargs=0) to retrieve name indices.
428
429
An object created by ypush_obj can be retrieved by yget_obj. Passing
429
430
uo_type=0 to yget_obj returns the type_name for the object at iarg;
430
431
otherwise it returns the pointer to the object itself, as created by
432
ypush_obj. For example,
433
y_userobj_t examp1_ops = { "example1 user object",
434
&examp1_free, &examp1_print, &examp1_eval, &examp1_extract, 0 };
435
y_userobj_t examp2_ops = { "example2 user object",
436
&examp2_free, &examp2_print, &examp2_eval, &examp2_extract, 0 };
437
A function which expects an example1 object at iarg=0 would simply
438
call yget_obj(iarg, &examp1_ops). However, if either an example1 or
439
an example2 object were an acceptable iarg=0 argument, you would call
440
name=yget_obj(iarg,0), then check whether name==examp1_ops.type_name or
441
name==examp2_ops.type_name. Note that the string itself is irrelevant --
442
checking the string value is not only a waste of time, but also there is no
443
guarantee the value is unique. Instead, you want to check that the
444
address examp1_ops.type_name (or examp2_ops.type_name) is returned. Note
445
that you can easily write your own yarg_examp1(iarg) or yarg_examp2(iarg)
446
function that retrieves specific object types with whatever semantics
447
you like if the actual argument is not the correct type. Similarly, you
448
can write ypush_examp1 or ypush_examp2, with whatever constructor arguments
433
451
The y_print function must be used by the on_print callback to produce
434
452
output. Do not attempt to use y_print except in a on_print callback.
449
467
the opaque handle. You can use the ygeta_* or yget_obj functions to
450
468
get the pointers to the actual data. As a side effect, yget_use converts
451
469
a scalar double, long, or int stack element into a rank 0 array, since
452
you can't own a use of the scalars. This invalidates any existing pointer
470
you cannot own a use of the scalars. This invalidates any existing pointer
453
471
you may have retrieved using ygeta_*, so call yget_use first.
455
473
PLUG_API void *yget_use(int iarg);
486
504
PLUG_API void y_error(const char *msg);
487
505
PLUG_API void y_errorn(const char *msg_format, long n);
488
PLUG_API void y_errorq(const char *msg_format, char *q);
506
PLUG_API void y_errorq(const char *msg_format, const char *q);
489
507
PLUG_API void y_errquiet(void);
490
508
PLUG_API void y_warn(const char *msg);
491
509
PLUG_API void y_warnn(const char *msg_format, long n);
492
PLUG_API void y_warnq(const char *msg_format, char *q);
510
PLUG_API void y_warnq(const char *msg_format, const char *q);
512
/* hook function called inside y_error
514
* 1 - suppress printing error message or entering dbug mode
515
* (one time override of set_idler flag)
516
* 2 - use output after as index into global symbol table of
517
* alternate after_error function
518
* 4 - if bit 2 set, after_error left in dbug mode iff bit 4 set
520
PLUG_API int (*y_errhook)(const char *fullmsg, long *after);