Call extended

Purpose: Call external function or macro (extended mode only).

 call-extended <function> "( " [ & ]<variable>  [ , ... ]  " )"

call-extended calls <function> (which can be a function or macro) with a list of parameter variables. The <function> is defined either in:

a library with C interop - note that such library can be written in many different languages. Most compiled languages can produce such libraries (such as Rust, C/C++ and others),
a ".c" file residing in the directory that contains application source code - again such a C file can in turn call code from libraries produced by any language that supports C interop (most do).
if a macro, in a ".h" file residing in the directory that contains application source code.

The <function> must be declared via C-style declaration in a ".h" file residing in the application source code directory. You can use "--lflag" and "--cflag" options of gg to supply libraries used. In addition, if you need to, you can also have any number of ".c" and ".h" files which will be automatically included in your project. A macro must be defined in ".h" file.

call-extended statement can only be used in extended mode (see extended-mode). By default, Gliimly code runs in safe mode which does not allow use of call-extended statement. Note that using call-extended statement does not automatically make your application unsafe; rather, extended code can be written in a memory-safe language (such as Rust), or even if written in C it can be made in such a way not to cause out-of-band memory reads and writes.

C signature, input/output variables, types

Each <variable> can be of C type (or a pointer to C type):

"gg_num" which is a signed integer 8 bytes in length (int64_t type). This represents Gliimly number.
"char *" which is a pointer to an array of characters. This represents Gliimly string value.
"bool" which is a boolean variable. This represents Gliimly boolean.

A <function> should not return a value. Rather, use a variable passed as a pointer if you wish to pass the function's output back to your Gliimly code.

Examples

For instance, consider C file "calc.c":

 #include "gliim.h"

 // Compute factorial of f, and store result into res
 void factorial(gg_num f, gg_num *res)
 {
     *res = 1;
     gg_num i;
     for (i = 2; i <= f; i++) {
         *res *= i;
     }
 }

Declare this C function in a header file, for instance "calc.h":

 void factorial(gg_num f, gg_num *res);

You can also have macros in a header file, so for example "calc.h" could be:

 void factorial(gg_num f, gg_num *res);

 #define mod10(n, m) m=(n)%10

In this case you have defined a macro that calculates the moduo of 10 and stores a result into another variable.

Use these in your Gliimly code with call-extended statement, for instance to use a function "factorial()":

 extended-mode

 begin-handler /fact
     set-number fact
     call-extended factorial (10, &fact)
     p-num fact
 end-handler

In the above example, number "fact" is passed by reference (as a pointer), and it will contain the value of factorial of 10 on return. The result printed out is "3628800".

To use macro "mod10()":

 extended-mode

 begin-handler /mod
     set-number mod
     call-extended mod10(103, mod)
     p-num mod
 end-handler

In this example, you are using a C macro, so number "fact" is assigned a value directly, per C language rules. The result printed out is "3".