home | help 
SNOBOL4LOAD(3)			 CSNOBOL4 Manual		  SNOBOL4LOAD(3)

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  IN-
     TEGER 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)

CSNOBOL4B 2.3.1 		 March 31, 2022 		  SNOBOL4LOAD(3)
home | help