Next Previous Contents

5. Functions that deal with the interpreter

5.1 SLallocate_load_type

Synopsis

Allocate a SLang_Load_Type object

Usage

SLang_Load_Type *SLallocate_load_type (char *name)

Description

The SLallocate_load_type function allocates and initializes space for a SLang_Load_Type object and returns it. Upon failure, the function returns NULL. The parameter name must uniquely identify the object. For example, if the object represents a file, then name could be the absolute path name of the file.

See Also

SLdeallocate_load_type, SLang_load_object

5.2 SLdeallocate_load_type

Synopsis

Free a SLang_Load_Type object

Usage

void SLdeallocate_load_type (SLang_Load_Type *slt)

Description

This function frees the memory associated with a SLang_Load_Type object that was acquired from a call to the SLallocate_load_type function.

See Also

SLallocate_load_type, SLang_load_object

5.3 SLang_load_object

Synopsis

Load an object into the interpreter

Usage

int SLang_load_object (SLang_Load_Type *obj)

Description

The function SLang_load_object is a generic function that may be used to loaded an object of type SLang_Load_Type into the interpreter. For example, the functions SLang_load_file and SLang_load_string are wrappers around this function to load a file and a string, respectively.

See Also

SLang_load_file, SLang_load_string, SLallocate_load_type

5.4 SLclass_allocate_class

Synopsis

Allocate a class for a new data type

Usage

SLang_Class_Type *SLclass_allocate_class (char *name)

Description

The purpose of this function is to allocate and initialize space that defines a new data type or class called name. If successful, a pointer to the class is returned, or upon failure the function returns NULL.

This function does not automatically create the new data type. Callback functions must first be associated with the data type via functions such as SLclass_set_push_function, and the data type must be registered with the interpreter via SLclass_register_class. See the S-Lang library programmer's guide for more information.

See Also

SLclass_register_class, SLclass_set_push_function

5.5 SLclass_register_class

Synopsis

Register a new data type with the interpreter

Usage

int SLclass_register_class (cl, type, sizeof_type, class_type)

    SLang_Class_Type *cl
    SLtype type
    unsigned int sizeof_type
    SLclass_Type class_type

Description

The SLclass_register_class function is used to register a new class or data type with the interpreter. If successful, the function returns 0, or upon failure, it returns -1.

The first parameter, cl, must have been previously obtained via the SLclass_allocate_class function.

The second parameter, type specifies the data type of the new class. If set to SLANG_VOID_TYPE then the library will automatically allocate an unused value for the class (the allocated value can then be found using the SLclass_get_class_id function), otherwise a value greater than 255 should be used. The values in the range 0-255 are reserved for internal use by the library.

The size that the data type represents in bytes is specified by the third parameter, sizeof_type. This value should not be confused with the sizeof the structure that represents the data type, unless the data type is of class SLANG_CLASS_TYPE_VECTOR or SLANG_CLASS_TYPE_SCALAR. For pointer objects, the value of this parameter is just sizeof(void *).

The final parameter specifies the class type of the data type. It must be one of the values:

     SLANG_CLASS_TYPE_SCALAR
     SLANG_CLASS_TYPE_VECTOR
     SLANG_CLASS_TYPE_PTR
     SLANG_CLASS_TYPE_MMT
The SLANG_CLASS_TYPE_SCALAR indicates that the new data type is a scalar. Examples of scalars in SLANG_INT_TYPE and SLANG_DOUBLE_TYPE.

Setting class_type to SLANG_CLASS_TYPE_VECTOR implies that the new data type is a vector, or a 1-d array of scalar types. An example of a data type of this class is the SLANG_COMPLEX_TYPE, which represents complex numbers.

SLANG_CLASS_TYPE_PTR specifies the data type is of a pointer type. Examples of data types of this class include SLANG_STRING_TYPE and SLANG_ARRAY_TYPE. Such types must provide for their own memory management.

Data types of class SLANG_CLASS_TYPE_MMT are pointer types except that the memory management, i.e., creation and destruction of the type, is handled by the interpreter. Such a type is called a memory managed type. An example of this data type is the SLANG_FILEPTR_TYPE.

Notes

See the S-Lang Library C Programmer's Guide for more information.

See Also

SLclass_allocate_class, SLclass_get_class_id

5.6 SLclass_set_string_function

Synopsis

Set a data type's string representation callback

Usage

int SLclass_set_string_function (cl, sfun)

   SLang_Class_Type *cl
   char *(*sfun) (SLtype, VOID_STAR);

Description

The SLclass_set_string_function routine is used to define a callback function, sfun, that will be used when a string representation of an object of the data type represented by cl is needed. cl must have already been obtained via a call to SLclass_allocate_class. When called, sfun will be passed two arguments: an SLtype which represents the data type, and the address of the object for which a string represetation is required. The callback function must return a malloced string.

Upon success, SLclass_set_string_function returns zero, or upon error it returns -1.

Example

A callback function that handles both SLANG_STRING_TYPE and SLANG_INT_TYPE variables looks like:

     char *string_and_int_callback (SLtype type, VOID_STAR addr)
     {
        char buf[64];

        switch (type)
          {
           case SLANG_STRING_TYPE:
             return SLmake_string (*(char **)addr);

           case SLANG_INTEGER_TYPE:
             sprintf (buf, "%d", *(int *)addr);
             return SLmake_string (buf);
          }
        return NULL;
     }

Notes

The default string callback simply returns the name of the data type.

See Also

SLclass_allocate_class, SLclass_register_class

5.7 SLclass_set_destroy_function

Synopsis

Set the destroy method callback for a data type

Usage

int SLclass_set_destroy_function (cl, destroy_fun)

    SLang_Class_Type *cl
    void (*destroy_fun) (SLtype, VOID_STAR);

Description

SLclass_set_destroy_function is used to set the destroy callback for a data type. The data type's class cl must have been previously obtained via a call to SLclass_allocate_class. When called, destroy_fun will be passed two arguments: an SLtype which represents the data type, and the address of the object to be destroyed.

SLclass_set_destroy_function returns zero upon success, and -1 upon failure.

Example

The destroy method for SLANG_STRING_TYPE looks like:

    static void string_destroy (SLtype type, VOID_STAR ptr)
    {
       char *s = *(char **) ptr;
       if (s != NULL) SLang_free_slstring (*(char **) s);
    }

Notes

Data types of class SLANG_CLASS_TYPE_SCALAR do not require a destroy callback. However, other classes do.

See Also

SLclass_allocate_class, SLclass_register_class

5.8 SLclass_set_push_function

Synopsis

Set the push callback for a new data type

Usage

int SLclass_set_push_function (cl, push_fun)

    SLang_Class_Type *cl
    int (*push_fun) (SLtype, VOID_STAR);

Description

SLclass_set_push_function is used to set the push callback for a new data type specified by cl, which must have been previously obtained via SLclass_allocate_class.

The parameter push_fun is a pointer to the push callback. It is required to take two arguments: an SLtype representing the data type, and the address of the object to be pushed. It must return zero upon success, or -1 upon failure.

SLclass_set_push_function returns zero upon success, or -1 upon failure.

Example

The push callback for SLANG_COMPLEX_TYPE looks like:

      static int complex_push (SLtype type, VOID_STAR ptr)
      {
         double *z = *(double **) ptr;
         return SLang_push_complex (z[0], z[1]);
      }

See Also

SLclass_allocate_class, SLclass_register_class

5.9 SLclass_set_pop_function

Synopsis

Set the pop callback for a new data type

Usage

int SLclass_set_pop_function (cl, pop_fun)

    SLang_Class_Type *cl
    int (*pop_fun) (SLtype, VOID_STAR);

Description

SLclass_set_pop_function is used to set the callback for popping an object from the stack for a new data type specified by cl, which must have been previously obtained via SLclass_allocate_class.

The parameter pop_fun is a pointer to the pop callback function, which is required to take two arguments: an unsigned character representing the data type, and the address of the object to be popped. It must return zero upon success, or -1 upon failure.

SLclass_set_pop_function returns zero upon success, or -1 upon failure.

Example

The pop callback for SLANG_COMPLEX_TYPE looks like:

      static int complex_push (SLtype type, VOID_STAR ptr)
      {
         double *z = *(double **) ptr;
         return SLang_pop_complex (&z[0], &z[1]);
      }

See Also

SLclass_allocate_class, SLclass_register_class

5.10 SLclass_get_datatype_name

Synopsis

Get the name of a data type

Usage

char *SLclass_get_datatype_name (SLtype type)

Description

The SLclass_get_datatype_name function returns the name of the data type specified by type. For example, if type is SLANG_INT_TYPE, the string "Integer_Type" will be returned.

This function returns a pointer that should not be modified or freed.

See Also

SLclass_allocate_class, SLclass_register_class

5.11 SLang_free_mmt

Synopsis

Free a memory managed type

Usage

void SLang_free_mmt (SLang_MMT_Type *mmt)

Description

The SLang_MMT_Type function is used to free a memory managed data type.

See Also

SLang_object_from_mmt, SLang_create_mmt

5.12 SLang_object_from_mmt

Synopsis

Get a pointer to the value of a memory managed type

Usage

VOID_STAR SLang_object_from_mmt (SLang_MMT_Type *mmt)

Description

The SLang_object_from_mmt function returns a pointer to the actual object whose memory is being managed by the interpreter.

See Also

SLang_free_mmt, SLang_create_mmt

5.13 SLang_create_mmt

Synopsis

Create a memory managed data type

Usage

SLang_MMT_Type *SLang_create_mmt (SLtype t, VOID_STAR ptr)

Description

The SLang_create_mmt function returns a pointer to a new memory managed object. This object contains information necessary to manage the memory associated with the pointer ptr which represents the application defined data type of type t.

See Also

SLang_object_from_mmt, SLang_push_mmt, SLang_free_mmt

5.14 SLang_push_mmt

Synopsis

Push a memory managed type

Usage

int SLang_push_mmt (SLang_MMT_Type *mmt)

Description

This function is used to push a memory managed type onto the interpreter stack. It returns zero upon success, or -1 upon failure.

See Also

SLang_create_mmt, SLang_pop_mmt

5.15 SLang_pop_mmt

Synopsis

Pop a memory managed data type

Usage

SLang_MMT_Type *SLang_pop_mmt (SLtype t)

Description

The SLang_pop_mmt function may be used to pop a memory managed type of type t from the stack. It returns a pointer to the memory managed object upon success, or NULL upon failure. The function SLang_object_from_mmt should be used to access the actual pointer to the data type.

See Also

SLang_object_from_mmt, SLang_push_mmt

5.16 SLang_inc_mmt

Synopsis

Increment a memory managed type reference count

Usage

void SLang_inc_mmt (SLang_MMT_Type *mmt);

Description

The SLang_inc_mmt function may be used to increment the reference count associated with the memory managed data type given by mmt.

See Also

SLang_free_mmt, SLang_create_mmt, SLang_pop_mmt, SLang_pop_mmt

5.17 SLadd_intrin_fun_table

Synopsis

Add a table of intrinsic functions to the interpreter

Usage

int SLadd_intrin_fun_table(SLang_Intrin_Fun_Type *tbl, char *pp_name);

Description

The SLadd_intrin_fun_table function adds an array, or table, of SLang_Intrin_Fun_Type objects to the interpreter. The first parameter, tbl specifies the table to be added. The second parameter pp_name, if non-NULL will be added to the list of preprocessor symbols.

This function returns -1 upon failure or zero upon success.

Notes

A table should only be loaded one time and it is considered to be an error on the part of the application if it loads a table more than once.

See Also

SLadd_intrin_var_table, SLadd_intrinsic_function, SLdefine_for_ifdef

5.18 SLadd_intrin_var_table

Synopsis

Add a table of intrinsic variables to the interpreter

Usage

int SLadd_intrin_var_table (SLang_Intrin_Var_Type *tbl, char *pp_name);

Description

The SLadd_intrin_var_table function adds an array, or table, of SLang_Intrin_Var_Type objects to the interpreter. The first parameter, tbl specifies the table to be added. The second parameter pp_name, if non-NULL will be added to the list of preprocessor symbols.

This function returns -1 upon failure or zero upon success.

Notes

A table should only be loaded one time and it is considered to be an error on the part of the application if it loads a table more than once.

See Also

SLadd_intrin_var_table, SLadd_intrinsic_function, SLdefine_for_ifdef

5.19 SLang_load_file

Synopsis

Load a file into the interpreter

Usage

int SLang_load_file (char *fn)

Description

The SLang_load_file function opens the file whose name is specified by fn and feeds it to the interpreter, line by line, for execution. If fn is NULL, the function will take input from stdin.

If no error occurs, it returns 0; otherwise, it returns -1, and sets SLang_Error accordingly. For example, if it fails to open the file, it will return -1 with SLang_Error set to SL_OBJ_NOPEN.

Notes

If the hook SLang_Load_File_Hook declared as

      int (*SLang_Load_File_Hook)(char *);
is non-NULL, the function point to by it will be used to load the file. For example, the jed editor uses this hook to load files via its own routines.

See Also

SLang_load_object, SLang_load_string

5.20 SLang_restart

Synopsis

Reset the interpreter after an error

Usage

void SLang_restart (int full)

Description

The SLang_restart function should be called by the application at top level if an error occurs. If the parameter full is non-zero, any objects on the S-Lang run time stack will be removed from the stack; otherwise, the stack will be left intact. Any time the stack is believed to be trashed, this routine should be called with a non-zero argument (e.g., if setjmp/longjmp is called).

Calling SLang_restart does not reset the global variable SLang_Error to zero. It is up to the application to reset that variable to zero after calling SLang_restart.

Example

      while (1)
        {
           if (SLang_Error)
             {
                SLang_restart (1);
                SLang_Error = 0;
             }
           (void) SLang_load_file (NULL);
        }

See Also

SLang_init_slang, SLang_load_file

5.21 SLang_byte_compile_file

Synopsis

Byte-compile a file for faster loading

Usage

int SLang_byte_compile_file(char *fn, int reserved)

Description

The SLang_byte_compile_file function ``byte-compiles'' the file fn for faster loading by the interpreter. This produces a new file whose filename is equivalent to the one specified by fn, except that a 'c' is appended to the name. For example, if fn is set to init.sl, then the new file will have the name init.slc. The meaning of the second parameter, reserved, is reserved for future use. For now, set it to 0.

The function returns zero upon success, or -1 upon error and sets SLang_Error accordingly.

See Also

SLang_load_file, SLang_init_slang

5.22 SLang_autoload

Synopsis

Autoload a function from a file

Usage

int SLang_autoload(char *funct, char *filename)

Description

The SLang_autoload function may be used to associate a slang function name funct with the file filename such that if funct has not already been defined when needed, it will be loaded from filename.

SLang_autoload has no effect if funct has already been defined. Otherwise it declares funct as a user-defined S-Lang function. It returns 0 upon success, or -1 upon error.

See Also

SLang_load_file, SLang_is_defined

5.23 SLang_load_string

Synopsis

Interpret a string

Usage

int SLang_load_string(char *str)

Description

The SLang_load_string function feeds the string specified by str to the interpreter for execution. It returns zero upon success, or -1 upon failure.

See Also

SLang_load_file, SLang_load_object

5.24 SLdo_pop

Synopsis

Delete an object from the stack

Usage

int SLdo_pop(void)

Description

This function removes an object from the top of the interpeter's run-time stack and frees any memory associated with it. It returns zero upon success, or -1 upon error (most likely due to a stack-underflow).

See Also

SLdo_pop_n, SLang_pop_integer, SLang_pop_string

5.25 SLdo_pop_n

Synopsis

Delete n objects from the stack

Usage

int SLdo_pop_n (unsigned int n)

Description

The SLdo_pop_n function removes the top n objects from the interpreter's run-time stack and frees all memory associated with the objects. It returns zero upon success, or -1 upon error (most likely due to a stack-underflow).

See Also

SLdo_pop, SLang_pop_integer, SLang_pop_string

5.26 SLang_pop_integer

Synopsis

Pop an integer off the stack

Usage

int SLang_pop_integer (int *i)

Description

The SLang_pop_integer function removes an integer from the top of the interpreter's run-time stack and returns its value via the pointer i. If successful, it returns zero. However, if the top stack item is not of type SLANG_INT_TYPE, or the stack is empty, the function will return -1 and set SLang_Error accordingly.

See Also

SLang_push_integer, SLang_pop_double

5.27 SLpop_string

Synopsis

Pop a string from the stack

Usage

int SLpop_string (char **strptr);

Description

The SLpop_string function pops a string from the stack and returns it as a malloced pointer. It is up to the calling routine to free this string via a call to free or SLfree. If successful, SLpop_string returns zero. However, if the top stack item is not of type SLANG_STRING_TYPE, or the stack is empty, the function will return -1 and set SLang_Error accordingly.

Example

      define print_string (void)
      {
         char *s;
         if (-1 == SLpop_string (&s))
           return;
         fputs (s, stdout);
         SLfree (s);
      }

Notes

This function should not be confused with SLang_pop_slstring, which pops a hashed string from the stack.

See Also

SLang_pop_slstring. SLfree

5.28 SLang_pop_string

Synopsis

Pop a string from the stack

Usage

int SLang_pop_string(char **strptr, int *do_free)

Description

The SLpop_string function pops a string from the stack and returns it as a malloced pointer via strptr. After the function returns, the integer pointed to by the second parameter will be set to a non-zero value if *strptr should be freed via free or SLfree. If successful, SLpop_string returns zero. However, if the top stack item is not of type SLANG_STRING_TYPE, or the stack is empty, the function will return -1 and set SLang_Error accordingly.

Notes

This function is considered obsolete and should not be used by applications. If one requires a malloced string for modification, SLpop_string should be used. If one requires a constant string that will not be modifed by the application, SLang_pop_slstring should be used.

See Also

SLang_pop_slstring, SLpop_string

5.29 SLang_pop_slstring

Synopsis

Pop a hashed string from the stack

Usage

int SLang_pop_slstring (char **s_ptr)

Description

The SLang_pop_slstring function pops a hashed string from the S-Lang run-time stack and returns it via s_ptr. It returns zero if successful, or -1 upon failure. The resulting string should be freed via a call to SLang_free_slstring after use.

Example

   void print_string (void)
   {
      char *s;
      if (-1 == SLang_pop_slstring (&s))
        return;
      fprintf (stdout, "%s\n", s);
      SLang_free_slstring (s);
   }

Notes

SLang_free_slstring is the preferred function for popping strings. This is a result of the fact that the interpreter uses hashed strings as the native representation for string data.

One must never free a hashed string using free or SLfree. In addition, one must never make any attempt to modify a hashed string and doing so will result in memory corruption.

See Also

SLang_free_slstring, SLpop_string

5.30 SLang_pop_double

Synopsis

Pop a double from the stack

Usage

int SLang_pop_double (double *dptr)

Description

The SLang_pop_double function pops a double precision number from the stack and returns it via dptr. This function returns 0 upon success, otherwise it returns -1 and sets SLang_Error accordingly.

See Also

SLang_pop_integer, SLang_push_double

5.31 SLang_pop_complex

Synopsis

Pop a complex number from the stack

Usage

int SLang_pop_complex (double *re, double *im)

Description

SLang_pop_complex pops a complex number from the stack and returns it via the parameters re and im as the real and imaginary parts of the complex number, respectively. This function automatically converts objects of type SLANG_DOUBLE_TYPE and SLANG_INT_TYPE to SLANG_COMPLEX_TYPE, if necessary. It returns zero upon success, or -1 upon error setting SLang_Error accordingly.

See Also

SLang_pop_integer, SLang_pop_double, SLang_push_complex

5.32 SLang_push_complex

Synopsis

Push a complex number onto the stack

Usage

int SLang_push_complex (double re, double im)

Description

SLang_push_complex may be used to push the complex number whose real and imaginary parts are given by re and im, respectively. It returns zero upon success, or -1 upon error setting SLang_Error accordingly.

See Also

SLang_pop_complex, SLang_push_double

5.33 SLang_push_double

Synopsis

Push a double onto the stack

Usage

int SLang_push_double(double d)

Description

SLang_push_double may be used to push the double precision floating point number d onto the interpreter's run-time stack. It returns zero upon success, or -1 upon error setting SLang_Error accordingly.

See Also

SLang_pop_double, SLang_push_integer

5.34 SLang_push_string

Synopsis

Push a string onto the stack

Usage

int SLang_push_string (char *s)

Description

SLang_push_string pushes a copy of the string specified by s onto the interpreter's run-time stack. It returns zero upon success, or -1 upon error setting SLang_Error accordingly.

Notes

If s is NULL, this function pushes NULL (SLANG_NULL_TYPE) onto the stack.

See Also

SLang_push_malloced_string

5.35 SLang_push_integer

Synopsis

Push an integer onto the stack

Usage

int SLang_push_integer (int i)

Description

SLang_push_integer the integer i onto the interpreter's run-time stack. It returns zero upon success, or -1 upon error setting SLang_Error accordingly.

See Also

SLang_pop_integer, SLang_push_double, SLang_push_string

5.36 SLang_push_malloced_string

Synopsis

Push a malloced string onto the stack

Usage

int SLang_push_malloced_string (char *s);

Description

SLang_push_malloced_string may be used to push a malloced string onto the interpreter's run-time stack. It returns zero upon success, or -1 upon error setting SLang_Error accordingly.

Example

The following example illustrates that it is up to the calling routine to free the string if SLang_push_malloced_string fails:

      int push_hello (void)
      {
         char *s = malloc (6);
         if (s == NULL) return -1;
         strcpy (s, "hello");
         if (-1 == SLang_push_malloced_string (s))
           {
              free (s);
              return -1;
           }
         return 0;
      }

Example

The function SLang_create_slstring returns a hashed string. Such a string may not be malloced and should not be passed to SLang_push_malloced_string.

Notes

If s is NULL, this function pushes NULL (SLANG_NULL_TYPE) onto the stack.

See Also

SLang_push_string, SLmake_string

5.37 SLang_is_defined

Synopsis

Check to see if the interpreter defines an object

Usage

int SLang_is_defined (char *nm)

Description

The SLang_is_defined function may be used to determine whether or not a variable or function whose name is given by em has been defined. It returns zero if no such object has been defined. Otherwise it returns a non-zero value according to the following table:

      1    intrinsic function
      2    user-defined slang function
     -1    intrinsic variable
     -2    user-defined global variable
Note that variables correspond to negative numbers and functions are represented by positive numbers.

See Also

SLadd_intrinsic_function, SLang_run_hooks, SLang_execute_function

5.38 SLang_run_hooks

Synopsis

Run a user-defined hook with arguments

Usage

int SLang_run_hooks (char *fname, unsigned int n, ...)

Description

The SLang_run_hooks function may be used to execute a user-defined function named fname. Before execution of the function, the n string arguments specified by the variable parameter list are pushed onto the stack. If the function fname does not exist, SLang_run_hooks returns zero; otherwise, it returns 1 upon successful execution of the function, or -1 if an error occurred.

Example

The jed editor uses SLang_run_hooks to setup the mode of a buffer based on the filename extension of the file associated with the buffer:

      char *ext = get_filename_extension (filename);
      if (ext == NULL) return -1;
      if (-1 == SLang_run_hooks ("mode_hook", 1, ext))
        return -1;
      return 0;

See Also

SLang_is_defined, SLang_execute_function

5.39 SLang_execute_function

Synopsis

Execute a user or intrinsic function

Usage

int SLang_execute_function (char *fname)

Description

This function may be used to execute either a user-defined function or an intrinisic function. The name of the function is specified by fname. It returns zero if fname is not defined, or 1 if the function was successfully executed, or -1 upon error.

Notes

The function SLexecute_function may be a better alternative for some uses.

See Also

SLang_run_hooks, SLexecute_function, SLang_is_defined

5.40 SLang_get_function

Synopsis

Get a pointer to a S-Lang function

Usage

SLang_Name_Type *SLang_get_function (char *fname)

Description

This function returns a pointer to the internal S-Lang table entry of a function whose name is given by fname. It returns NULL upon failure. The value returned by this function can be used SLexecute_function to call the function directly from C.

See Also

SLexecute_function

5.41 SLexecute_function

Synopsis

Execute a S-Lang or intrinsic function

Usage

int SLexecute_function (SLang_Name_Type *nt)

Description

The SLexecute_function allows an application to call the S-Lang function specified by the SLang_Name_Type pointer nt. This parameter must be non NULL and must have been previously obtained by a call to SLang_get_function.

Example

Consider the S-Lang function:

     define my_fun (x)
     {
        return x^2 - 2;
     }
Suppose that it is desired to call this function many times with different values of x. There are at least two ways to do this. The easiest way is to use SLang_execute_function by passing the string "my_fun". A better way that is much faster is to use SLexecute_function:
      int sum_a_function (char *fname, double *result)
      {
         double sum, x, y;
         SLang_Name_Type *nt;

         if (NULL == (nt = SLang_get_function (fname)))
           return -1;

         sum = 0;
         for (x = 0; x < 10.0; x += 0.1)
           {
              SLang_start_arg_list ();
              if (-1 == SLang_push_double (x))
                return -1;
              SLang_end_arg_list ();
              if (-1 == SLexecute_function (nt))
                return -1;
              if (-1 == SLang_pop_double (&y))
                return -1;

              sum += y;
           }
         return sum;
      }
Although not necessary in this case, SLang_start_arg_list and SLang_end_arg_list were used to provide the function with information about the number of parameters passed to it.

See Also

SLang_get_function, SLang_start_arg_list, SLang_end_arg_list

5.42 SLang_peek_at_stack

Synopsis

Find the type of object on the top of the stack

Usage

int SLang_peek_at_stack (void)

Description

The SLang_peek_at_stack function is useful for determining the data type of the object at the top of the stack. It returns the data type, or -1 upon a stack-underflow error. It does not remove anything from the stack.

See Also

SLang_pop_string, SLang_pop_integer

5.43 SLang_pop_fileptr

Synopsis

Pop a file pointer

Usage

int SLang_pop_fileptr (SLang_MMT_Type **mmt, FILE **fp)

Description

SLang_pop_fileptr pops a file pointer from the S-Lang run-time stack. It returns zero upon success, or -1 upon failure.

A S-Lang file pointer (SLANG_FILEPTR_TYPE) is actually a memory managed object. For this reason, SLang_pop_fileptr also returns the memory managed object via the argument list. It is up to the calling routine to call SLang_free_mmt to free the object.

Example

The following example illustrates an application defined intrinsic function that writes a user defined double precision number to a file. Note the use of SLang_free_mmt:

     int write_double (void)
     {
        double t;
        SLang_MMT_Type *mmt;
        FILE *fp;
        int status;

        if (-1 == SLang_pop_double (&d, NULL, NULL))
          return -1;
        if (-1 == SLang_pop_fileptr (&mmt, &fp))
          return -1;

        status = fwrite (&d, sizeof (double), 1, fp);
        SLang_free_mmt (mmt);
        return status;
     }
This function can be used by a S-Lang function as follows:
     define write_some_values ()
     {
        variable fp, d;

        fp = fopen ("myfile.dat", "wb");
        if (fp == NULL)
          error ("file failed to open");
        for (d = 0; d < 10.0; d += 0.1)
          {
             if (-1 == write_double (fp, d))
               error ("write failed");
          }
        if (-1 == fclose (fp))
          error ("fclose failed");
     }

See Also

SLang_free_mmt, SLang_pop_double

5.44 SLadd_intrinsic_function

Synopsis

Add a new intrinsic function to the interpreter

Usage

int SLadd_intrinsic_function (name, f, type, nargs, ...)

    char *name
    FVOID_STAR f
    SLtype type
    unsigned int nargs

Description

The SLadd_intrinsic_function function may be used to add a new intrinsic function. The S-Lang name of the function is specified by name and the actual function pointer is given by f, cast to FVOID_STAR. The third parameter, type specifies the return type of the function and must be one of the following values:

    SLANG_VOID_TYPE   (returns nothing)
    SLANG_INT_TYPE    (returns int)
    SLANG_DOUBLE_TYPE (returns double)
    SLANG_STRING_TYPE (returns char *)
The nargs parameter specifies the number of parameters to pass to the function. The variable argument list following nargs must consists of nargs integers which specify the data type of each argument.

The function returns zero upon success or -1 upon failure.

Example

The jed editor uses this function to change the system intrinsic function to the following:

     static int jed_system (char *cmd)
     {
        if (Jed_Secure_Mode)
          {
             msg_error ("Access denied.");
             return -1;
          }
        return SLsystem (cmd);
     }
After initializing the interpreter with SLang_init_slang, jed calls SLadd_intrinsic_function to substitute the above definition for the default S-Lang definition:
     if (-1 == SLadd_intrinsic_function ("system", (FVOID_STAR)jed_system,
                                         SLANG_INT_TYPE, 1,
                                         SLANG_STRING_TYPE))
       return -1;

See Also

SLadd_intrinsic_variable, SLadd_intrinsic_array

5.45 SLadd_intrinsic_variable

Synopsis

Add an intrinsic variable to the interpreter

Usage

int SLadd_intrinsic_variable (name, addr, type, rdonly)

    char *name
    VOID_STAR addr
    SLtype type
    int rdonly

Description

The SLadd_intrinsic_variable function adds an intrinsic variable called name to the interpeter. The second parameter addr specifies the address of the variable (cast to VOID_STAR). The third parameter, type, specifies the data type of the variable. If the fourth parameter, rdonly, is non-zero, the variable will interpreted by the interpreter as read-only.

If successful, SLadd_intrinsic_variable returns zero, otherwise it returns -1.

Example

Suppose that My_Global_Int is a global variable (at least not a local one):

    int My_Global_Int;
It can be added to the interpreter via the function call
    if (-1 == SLadd_intrinsic_variable ("MyGlobalInt",
                                        (VOID_STAR)&My_Global_Int,
                                        SLANG_INT_TYPE, 0))
      exit (1);

Notes

The current implementation requires all pointer type intrinsic variables to be read-only. For example,

    char *My_Global_String;
is of type SLANG_STRING_TYPE, and must be declared as read-only. Finally, not that
   char My_Global_Char_Buf[256];
is not a SLANG_STRING_TYPE object. This difference is very important because internally the interpreter dereferences the address passed to it to get to the value of the variable.

See Also

SLadd_intrinsic_function, SLadd_intrinsic_array

5.46 SLclass_add_unary_op

Synopsis

??

Usage

int SLclass_add_unary_op (SLtype,int (*) (int, SLtype, VOID_STAR, unsigned int, VOID_STAR), int (*) (int, SLtype, SLtype *));

Description

??

See Also

??

5.47 SLclass_add_app_unary_op

Synopsis

??

Usage

int SLclass_add_app_unary_op (SLtype, int (*) (int,SLtype, VOID_STAR, unsigned int,VOID_STAR),int (*) (int, SLtype, SLtype *));

Description

??

See Also

??

5.48 SLclass_add_binary_op

Synopsis

??

Usage

int SLclass_add_binary_op (SLtype, SLtype,int (*)(int, SLtype, VOID_STAR, unsigned int,SLtype, VOID_STAR, unsigned int,VOID_STAR),int (*) (int, SLtype, SLtype, SLtype *));

Description

??

See Also

??

5.49 SLclass_add_math_op

Synopsis

??

Usage

int SLclass_add_math_op (SLtype,int (*)(int,SLtype, VOID_STAR, unsigned int,VOID_STAR),int (*)(int, SLtype, SLtype *));

Description

??

See Also

??

5.50 SLclass_add_typecast

Synopsis

??

Usage

int SLclass_add_typecast (SLtype, SLtype int (*)_PROTO((SLtype, VOID_STAR, unsigned int,SLtype, VOID_STAR)),int);

Description

??

See Also

??


Next Previous Contents