NAME

snobol4load - Loading extension modules into SNOBOL4

SYNOPSIS

modulename.c:

    #ifdef HAVE_CONFIG_H


    #include "config.h"


    #endif

    #include "h.h"


    #include "snotypes.h"


    #include "macros.h"


    #include "load.h"


    #include "equ.h"

    SNOBOL_MODULE(modulename)

    /*


    **=pea


    **=sect NAME


    **modulename \- A SNOBOL4 extension module


    **=sect SYNOPSYS


    **=code


    **-INCLUDE 'modulename.sno'


    **=cut


    */

    /*


     * LOAD("FUNC_NAME(ARG_TYPES,....)RET_TYPE", MODULENAME_DL)


     */


    /*


    **=code


    **        result = B<FUNC_NAME(ARG_TYPES,....)>


    **=ecode


    */


    lret_t


    FUNC_NAME(LA_ALIST) {
	/* function body */


    }

SYNOPSIS

External C functions are loaded into SNOBOL4 via the LOAD() function. LOAD() is passed a prototype which names the function and may describe the minimum number and types of the parameters the function will be passed, as well as the return type.

The typedefs int_t and real_t should be used in C code for all SNOBOL4 INTEGER and REAL values, or value truncation may occur.

The function should use one of the following macros to return a value (the type of which should be compatible with the type in the prototype passed to the LOAD() function:

    RETINT(i)             /* return INTEGER (int_t) value */


    RETREAL(a)            /* return REAL (real_t) value */


    RETNULL               /* return null string */


    RETSTR_FREE(buf)      /* return C string and free malloc'ed buf */


    RETSTR2_FREE(buf,len) /* return counted str and free malloc'ed buf */


    RETSTR(buf)           /* return C string from static buffer */


    RETSTR2(buf,len)      /* return counted string from static buf */


    RETPRED(success)      /* return predicate value (NULL or failure) */


    RETFAIL               /* return failure */

Parameters are accessed positionally via the following macros. When a data type is specified in the LOAD() prototype, values passed to the function will automatically be converted to the specified data type. The following macros do NOT perform data type conversion, and using the wrong macro to access a parameter will return garbage, or worse.

    int_t i = LA_INT(0);    /* gets value of 1st parameter; returns int_t */


    real_t a = LA_REAL(1);  /* gets value of 2nd parameter; returns real_t */


    char *s = mgetstring(LA_PTR(2)); /* get string argument as C string
				      * in malloc'ed buffer. MUST be free'ed */


    const char *sp = LA_STR_PTR(2); /* get pointer (or NULL) */


    int sl = LA_STR_LEN(2); /* returns string length. */

External functions can be written to take polymorphic parameters by leaving the type name blank in the prototype, or passing arguments in excess of those described in the prototype. For example "FOO(,STRING)INTEGER" is a function with two parameters, the first is polymorphic. The LA_TYPE(n) macro must be used to determine the actual parameter data type;

I

arg n is an integer of C type int_t (fetch with LA_INT(n))

R

arg n is a real of C type real_t (fetch with LA_REAL(n))

S

arg n references a string (fetch with mgetstring etc).

Loadable code can be compiled and installed using snobol4setup(3), which generates a modulename.sno include file.

SEE ALSO

snobol4(1), snobol4setup(3), snopea(7)