tm/crtl/slinterp.tm

\function{SLallocate_load_type}
\synopsis{Allocate a SLang_Load_Type object}
\usage{SLang_Load_Type *SLallocate_load_type (char *name)}
\description
  The \var{SLallocate_load_type} function allocates and initializes
  space for a \var{SLang_Load_Type} object and returns it.  Upon
  failure, the function returns \var{NULL}.  The parameter \var{name}
  must uniquely identify the object.  For example, if the object
  represents a file, then \var{name} could be the absolute path name
  of the file.
\seealso{SLdeallocate_load_type, SLang_load_object}
\done

\function{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
  \var{SLang_Load_Type} object that was acquired from a call to the
  \var{SLallocate_load_type} function.
\seealso{SLallocate_load_type, SLang_load_object}
\done

\function{SLang_load_object}
\synopsis{Load an object into the interpreter}
\usage{int SLang_load_object (SLang_Load_Type *obj)}
\description
  The function \var{SLang_load_object} is a generic function that may
  be used to loaded an object of type \var{SLang_Load_Type} into the
  interpreter.  For example, the functions \var{SLang_load_file} and
  \var{SLang_load_string} are wrappers around this function to load a
  file and a string, respectively.
\seealso{SLang_load_file, SLang_load_string, SLallocate_load_type}
\done

\function{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 \var{name}.  If
  successful, a pointer to the class is returned, or upon failure the
  function returns \var{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 \var{SLclass_set_push_function}, and the data
  type must be registered with the interpreter via
  \var{SLclass_register_class}.  See the \slang library programmer's
  guide for more information.
\seealso{SLclass_register_class, SLclass_set_push_function}
\done

\function{SLclass_register_class}
\synopsis{Register a new data type with the interpreter}
\usage{int SLclass_register_class (cl, type, sizeof_type, class_type)}
#v+
    SLang_Class_Type *cl
    SLtype type
    unsigned int sizeof_type
    SLclass_Type class_type
#v-
\description
  The \var{SLclass_register_class} function is used to register a new
  class or data type with the interpreter.  If successful, the
  function returns \exmp{0}, or upon failure, it returns \var{-1}.

  The first parameter, \var{cl}, must have been previously obtained
  via the \var{SLclass_allocate_class} function.

  The second parameter, \var{type} specifies the data type of the new
  class.  If set to \var{SLANG_VOID_TYPE} then the library will
  automatically allocate an unused value for the class (the allocated
  value can then be found using the \var{SLclass_get_class_id}
  function), otherwise a value greater than \exmp{255} should be
  used.  The values in the range \exmp{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, \var{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 \var{SLANG_CLASS_TYPE_VECTOR}
  or \var{SLANG_CLASS_TYPE_SCALAR}.  For pointer objects, the value
  of this parameter is just \var{sizeof(void *)}.

  The final parameter specifies the class type of the data type.  It must
  be one of the values:
#v+
     SLANG_CLASS_TYPE_SCALAR
     SLANG_CLASS_TYPE_VECTOR
     SLANG_CLASS_TYPE_PTR
     SLANG_CLASS_TYPE_MMT
#v-
  The \var{SLANG_CLASS_TYPE_SCALAR} indicates that the new data type
  is a scalar.  Examples of scalars in \var{SLANG_INT_TYPE} and
  \var{SLANG_DOUBLE_TYPE}.

  Setting \var{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
  \var{SLANG_COMPLEX_TYPE}, which represents complex numbers.

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

  Data types of class \var{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
  \em{memory managed type}.  An example of this data type is the
  \var{SLANG_FILEPTR_TYPE}.
\notes
   See the \slang-library-programmers-guide for more information.
\seealso{SLclass_allocate_class, SLclass_get_class_id}
\done

\function{SLclass_set_string_function}
\synopsis{Set a data type's string representation callback}
\usage{int SLclass_set_string_function (cl, sfun)}
#v+
   SLang_Class_Type *cl
   char *(*sfun) (SLtype, VOID_STAR);
#v-
\description
  The \var{SLclass_set_string_function} routine is used to define a
  callback function, \var{sfun}, that will be used when a string
  representation of an object of the data type represented by \var{cl}
  is needed.  \var{cl} must have already been obtained via a call to
  \var{SLclass_allocate_class}.  When called, \var{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 \em{malloced}
  string.

  Upon success, \var{SLclass_set_string_function} returns zero, or
  upon error it returns \-1.
\example
  A callback function that handles both \var{SLANG_STRING_TYPE} and
  \var{SLANG_INT_TYPE} variables looks like:
#v+
     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;
     }
#v-
\notes
  The default string callback simply returns the name of the data type.
\seealso{SLclass_allocate_class, SLclass_register_class}
\done

\function{SLclass_set_destroy_function}
\synopsis{Set the destroy method callback for a data type}
\usage{int SLclass_set_destroy_function (cl, destroy_fun)}
#v+
    SLang_Class_Type *cl
    void (*destroy_fun) (SLtype, VOID_STAR);
#v-
\description
  \var{SLclass_set_destroy_function} is used to set the destroy
  callback for a data type.  The data type's class \var{cl} must have
  been previously obtained via a call to \var{SLclass_allocate_class}.
  When called, \var{destroy_fun} will be passed two arguments: an
  SLtype which represents the data type, and the address of the
  object to be destroyed.

  \var{SLclass_set_destroy_function} returns zero upon success, and
  \-1 upon failure.
\example
  The destroy method for \var{SLANG_STRING_TYPE} looks like:
#v+
    static void string_destroy (SLtype type, VOID_STAR ptr)
    {
       char *s = *(char **) ptr;
       if (s != NULL) SLang_free_slstring (*(char **) s);
    }
#v-
\notes
  Data types of class SLANG_CLASS_TYPE_SCALAR do not require a destroy
  callback.  However, other classes do.
\seealso{SLclass_allocate_class, SLclass_register_class}
\done

\function{SLclass_set_push_function}
\synopsis{Set the push callback for a new data type}
\usage{int SLclass_set_push_function (cl, push_fun)}
#v+
    SLang_Class_Type *cl
    int (*push_fun) (SLtype, VOID_STAR);
#v-
\description
   \var{SLclass_set_push_function} is used to set the push callback
   for a new data type specified by \var{cl}, which must have been
   previously obtained via \var{SLclass_allocate_class}.

   The parameter \var{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.

   \var{SLclass_set_push_function} returns zero upon success, or \-1
   upon failure.
\example
   The push callback for \var{SLANG_COMPLEX_TYPE} looks like:
#v+
      static int complex_push (SLtype type, VOID_STAR ptr)
      {
         double *z = *(double **) ptr;
         return SLang_push_complex (z[0], z[1]);
      }
#v-
\seealso{SLclass_allocate_class, SLclass_register_class}
\done

\function{SLclass_set_pop_function}
\synopsis{Set the pop callback for a new data type}
\usage{int SLclass_set_pop_function (cl, pop_fun)}
#v+
    SLang_Class_Type *cl
    int (*pop_fun) (SLtype, VOID_STAR);
#v-
\description
   \var{SLclass_set_pop_function} is used to set the callback for
   popping an object from the stack for a new data type specified by
   \var{cl}, which must have been previously obtained via
   \var{SLclass_allocate_class}.

   The parameter \var{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.

   \var{SLclass_set_pop_function} returns zero upon success, or \-1
   upon failure.
\example
   The pop callback for \var{SLANG_COMPLEX_TYPE} looks like:
#v+
      static int complex_push (SLtype type, VOID_STAR ptr)
      {
         double *z = *(double **) ptr;
         return SLang_pop_complex (&z[0], &z[1]);
      }
#v-
\seealso{SLclass_allocate_class, SLclass_register_class}
\done

\function{SLclass_get_datatype_name}
\synopsis{Get the name of a data type}
\usage{char *SLclass_get_datatype_name (SLtype type)}
\description
  The \var{SLclass_get_datatype_name} function returns the name of the
  data type specified by \var{type}.  For example, if \var{type} is
  \var{SLANG_INT_TYPE}, the string \exmp{"Integer_Type"} will be
  returned.

  This function returns a pointer that should not be modified or freed.
\seealso{SLclass_allocate_class, SLclass_register_class}
\done

\function{SLang_free_mmt}
\synopsis{Free a memory managed type}
\usage{void SLang_free_mmt (SLang_MMT_Type *mmt)}
\description
  The \var{SLang_MMT_Type} function is used to free a memory managed
  data type.
\seealso{SLang_object_from_mmt, SLang_create_mmt}
\done

\function{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 \var{SLang_object_from_mmt} function returns a pointer to the
  actual object whose memory is being managed by the interpreter.
\seealso{SLang_free_mmt, SLang_create_mmt}
\done

\function{SLang_create_mmt}
\synopsis{Create a memory managed data type}
\usage{SLang_MMT_Type *SLang_create_mmt (SLtype t, VOID_STAR ptr)}
\description
  The \var{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 \var{ptr} which
  represents the application defined data type of type \var{t}.
\seealso{SLang_object_from_mmt, SLang_push_mmt, SLang_free_mmt}
\done

\function{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 \exmp{-1} upon
   failure.
\seealso{SLang_create_mmt, SLang_pop_mmt}
\done

\function{SLang_pop_mmt}
\synopsis{Pop a memory managed data type}
\usage{SLang_MMT_Type *SLang_pop_mmt (SLtype t)}
\description
  The \var{SLang_pop_mmt} function may be used to pop a memory managed
  type of type \var{t} from the stack.  It returns a pointer to the
  memory managed object upon success, or \var{NULL} upon failure.  The
  function \var{SLang_object_from_mmt} should be used to access the
  actual pointer to the data type.
\seealso{SLang_object_from_mmt, SLang_push_mmt}
\done

\function{SLang_inc_mmt}
\synopsis{Increment a memory managed type reference count}
\usage{void SLang_inc_mmt (SLang_MMT_Type *mmt);}
\description
  The \var{SLang_inc_mmt} function may be used to increment the
  reference count associated with the memory managed data type given
  by \var{mmt}.
\seealso{SLang_free_mmt, SLang_create_mmt, SLang_pop_mmt, SLang_pop_mmt}
\done

\function{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 \var{SLadd_intrin_fun_table} function adds an array, or table, of
  \var{SLang_Intrin_Fun_Type} objects to the interpreter.  The first
  parameter, \var{tbl} specifies the table to be added.  The second
  parameter \var{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.
\seealso{SLadd_intrin_var_table, SLadd_intrinsic_function, SLdefine_for_ifdef}
\done

\function{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 \var{SLadd_intrin_var_table} function adds an array, or table, of
  \var{SLang_Intrin_Var_Type} objects to the interpreter.  The first
  parameter, \var{tbl} specifies the table to be added.  The second
  parameter \var{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.
\seealso{SLadd_intrin_var_table, SLadd_intrinsic_function, SLdefine_for_ifdef}
\done

\function{SLang_load_file}
\synopsis{Load a file into the interpreter}
\usage{int SLang_load_file (char *fn)}
\description
  The \var{SLang_load_file} function opens the file whose name is
  specified by \var{fn} and feeds it to the interpreter, line by line,
  for execution.  If \var{fn} is \var{NULL}, the function will take
  input from \var{stdin}.

  If no error occurs, it returns \exmp{0}; otherwise,
  it returns \exmp{-1}, and sets \var{SLang_Error} accordingly.  For
  example, if it fails to open the file, it will return \exmp{-1} with
  \var{SLang_Error} set to \var{SL_OBJ_NOPEN}.
\notes
   If the hook \var{SLang_Load_File_Hook} declared as
#v+
      int (*SLang_Load_File_Hook)(char *);
#v-
   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.
\seealso{SLang_load_object, SLang_load_string}
\done

\function{SLang_restart}
\synopsis{Reset the interpreter after an error}
\usage{void SLang_restart (int full)}
\description
   The \var{SLang_restart} function should be called by the
   application at top level if an error occurs.  If the parameter
   \var{full} is non-zero, any objects on the \slang 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
   \var{setjmp}/\var{longjmp} is called).

   Calling \var{SLang_restart} does not reset the global variable
   \var{SLang_Error} to zero.  It is up to the application to reset
   that variable to zero after calling \var{SLang_restart}.
\example
#v+
      while (1)
        {
           if (SLang_Error)
             {
                SLang_restart (1);
                SLang_Error = 0;
             }
           (void) SLang_load_file (NULL);
        }
#v-
\seealso{SLang_init_slang, SLang_load_file}
\done

\function{SLang_byte_compile_file}
\synopsis{Byte-compile a file for faster loading}
\usage{int SLang_byte_compile_file(char *fn, int reserved)}
\description
  The \var{SLang_byte_compile_file} function ``byte-compiles'' the
  file \var{fn} for faster loading by the interpreter.  This produces
  a new file whose filename is equivalent to the one specified by
  \var{fn}, except that a \var{'c'} is appended to the name.  For
  example, if \var{fn} is set to \exmp{init.sl}, then the new file
  will have the name \exmp{init.slc}.  The meaning of the second
  parameter, \var{reserved}, is reserved for future use.  For now, set
  it to \var{0}.

  The function returns zero upon success, or \exmp{-1} upon error and
  sets SLang_Error accordingly.
\seealso{SLang_load_file, SLang_init_slang}
\done

\function{SLang_autoload}
\synopsis{Autoload a function from a file}
\usage{int SLang_autoload(char *funct, char *filename)}
\description
  The \var{SLang_autoload} function may be used to associate a
  \var{slang} function name \var{funct} with the file \var{filename}
  such that if \var{funct} has not already been defined when needed,
  it will be loaded from \var{filename}.

  \var{SLang_autoload} has no effect if \var{funct} has already been
  defined.  Otherwise it declares \var{funct} as a user-defined \slang
  function.  It returns \exmp{0} upon success, or \exmp{-1} upon error.
\seealso{SLang_load_file, SLang_is_defined}
\done

\function{SLang_load_string}
\synopsis{Interpret a string}
\usage{int SLang_load_string(char *str)}
\description
  The \var{SLang_load_string} function feeds the string specified by
  \var{str} to the interpreter for execution.  It returns zero upon
  success, or \exmp{-1} upon failure.
\seealso{SLang_load_file, SLang_load_object}
\done

\function{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 \var{-1} upon error (most likely due to a
   stack-underflow).
\seealso{SLdo_pop_n, SLang_pop_integer, SLang_pop_string}
\done

\function{SLdo_pop_n}
\synopsis{Delete n objects from the stack}
\usage{int SLdo_pop_n (unsigned int n)}
\description
   The \var{SLdo_pop_n} function removes the top \var{n} objects from
   the interpreter's run-time stack and frees all memory associated
   with the objects.  It returns zero upon success, or \var{-1} upon
   error (most likely due to a stack-underflow).
\seealso{SLdo_pop, SLang_pop_integer, SLang_pop_string}
\done

\function{SLang_pop_integer}
\synopsis{Pop an integer off the stack}
\usage{int SLang_pop_integer (int *i)}
\description
   The \var{SLang_pop_integer} function removes an integer from the
   top of the interpreter's run-time stack and returns its value via
   the pointer \var{i}.  If successful, it returns zero.  However, if
   the top stack item is not of type \var{SLANG_INT_TYPE}, or the
   stack is empty, the function will return \exmp{-1} and set
   \var{SLang_Error} accordingly.
\seealso{SLang_push_integer, SLang_pop_double}
\done

\function{SLpop_string}
\synopsis{Pop a string from the stack}
\usage{int SLpop_string (char **strptr);}
\description
   The \var{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 \var{free} or \var{SLfree}.  If
   successful, \var{SLpop_string} returns zero.  However, if the top
   stack item is not of type \var{SLANG_STRING_TYPE}, or the stack is
   empty, the function will return \exmp{-1} and set
   \var{SLang_Error} accordingly.
\example
#v+
      define print_string (void)
      {
         char *s;
         if (-1 == SLpop_string (&s))
           return;
         fputs (s, stdout);
         SLfree (s);
      }
#v-
\notes
   This function should not be confused with \var{SLang_pop_slstring},
   which pops a \em{hashed} string from the stack.
\seealso{SLang_pop_slstring. SLfree}
\done

\function{SLang_pop_string}
\synopsis{Pop a string from the stack}
\usage{int SLang_pop_string(char **strptr, int *do_free)}
\description
   The \var{SLpop_string} function pops a string from the stack and
   returns it as a malloced pointer via \var{strptr}.  After the
   function returns, the integer pointed to by the second parameter
   will be set to a non-zero value if \var{*strptr} should be freed via
   \var{free} or \var{SLfree}.  If successful, \var{SLpop_string}
   returns zero.  However, if the top stack item is not of type
   \var{SLANG_STRING_TYPE}, or the stack is empty, the function will
   return \exmp{-1} and set \var{SLang_Error} accordingly.
\notes
   This function is considered obsolete and should not be used by
   applications.  If one requires a malloced string for modification,
   \var{SLpop_string} should be used.  If one requires a constant
   string that will not be modifed by the application,
   \var{SLang_pop_slstring} should be used.
\seealso{SLang_pop_slstring, SLpop_string}
\done

\function{SLang_pop_slstring}
\synopsis{Pop a hashed string from the stack}
\usage{int SLang_pop_slstring (char **s_ptr)}
\description
   The \var{SLang_pop_slstring} function pops a hashed string from the
   \slang run-time stack and returns it via \var{s_ptr}.  It returns
   zero if successful, or \-1 upon failure.  The resulting string
   should be freed via a call to \var{SLang_free_slstring} after use.
\example
#v+
   void print_string (void)
   {
      char *s;
      if (-1 == SLang_pop_slstring (&s))
        return;
      fprintf (stdout, "%s\n", s);
      SLang_free_slstring (s);
   }
#v-
\notes
   \var{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 \em{never} free a hashed string using \var{free} or
   \var{SLfree}.  In addition, one must never make any attempt to
   modify a hashed string and doing so will result in memory
   corruption.
\seealso{SLang_free_slstring, SLpop_string}
\done

\function{SLang_pop_double}
\synopsis{Pop a double from the stack}
\usage{int SLang_pop_double (double *dptr)}
\description
   The \var{SLang_pop_double} function pops a double precision number
   from the stack and returns it via \var{dptr}.  This
   function returns \0 upon success, otherwise it returns \-1 and sets
   \var{SLang_Error} accordingly.
\seealso{SLang_pop_integer, SLang_push_double}
\done

\function{SLang_pop_complex}
\synopsis{Pop a complex number from the stack}
\usage{int SLang_pop_complex (double *re, double *im)}
\description
   \var{SLang_pop_complex} pops a complex number from the stack and
   returns it via the parameters \var{re} and \var{im} as the real and
   imaginary parts of the complex number, respectively.  This function
   automatically converts objects of type \var{SLANG_DOUBLE_TYPE} and
   \var{SLANG_INT_TYPE} to \var{SLANG_COMPLEX_TYPE}, if necessary.
   It returns zero upon success, or \-1 upon error setting
   \var{SLang_Error} accordingly.
\seealso{SLang_pop_integer, SLang_pop_double, SLang_push_complex}
\done

\function{SLang_push_complex}
\synopsis{Push a complex number onto the stack}
\usage{int SLang_push_complex (double re, double im)}
\description
   \var{SLang_push_complex} may be used to push the complex number
   whose real and imaginary parts are given by \var{re} and \var{im},
   respectively.  It returns zero upon success, or \-1 upon error
   setting \var{SLang_Error} accordingly.
\seealso{SLang_pop_complex, SLang_push_double}
\done

\function{SLang_push_double}
\synopsis{Push a double onto the stack}
\usage{int SLang_push_double(double d)}
\description
   \var{SLang_push_double} may be used to push the double precision
   floating point number \var{d} onto the interpreter's run-time
   stack.  It returns zero upon success, or \-1 upon error setting
   \var{SLang_Error} accordingly.
\seealso{SLang_pop_double, SLang_push_integer}
\done

\function{SLang_push_string}
\synopsis{Push a string onto the stack}
\usage{int SLang_push_string (char *s)}
\description
   \var{SLang_push_string} pushes a copy of the string specified by
   \var{s} onto the interpreter's run-time stack.  It returns zero
   upon success, or \-1 upon error setting \var{SLang_Error}
   accordingly.
\notes
   If \var{s} is \var{NULL}, this function pushes \var{NULL}
   (\var{SLANG_NULL_TYPE}) onto the stack.
\seealso{SLang_push_malloced_string}
\done

\function{SLang_push_integer}
\synopsis{Push an integer onto the stack}
\usage{int SLang_push_integer (int i)}
\description
   \var{SLang_push_integer} the integer \var{i} onto the interpreter's
   run-time stack.  It returns zero upon success, or \-1 upon error
   setting \var{SLang_Error} accordingly.
\seealso{SLang_pop_integer, SLang_push_double, SLang_push_string}
\done

\function{SLang_push_malloced_string}
\synopsis{Push a malloced string onto the stack}
\usage{int SLang_push_malloced_string (char *s);}
\description
   \var{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 \var{SLang_Error} accordingly.
\example
   The following example illustrates that it is up to the calling
   routine to free the string if \var{SLang_push_malloced_string} fails:
#v+
      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;
      }
#v-
\example
   The function \var{SLang_create_slstring} returns a hashed string.
   Such a string may not be malloced and should not be passed to
   \var{SLang_push_malloced_string}.
\notes
   If \var{s} is \var{NULL}, this function pushes \var{NULL}
   (\var{SLANG_NULL_TYPE}) onto the stack.
\seealso{SLang_push_string, SLmake_string}
\done

\function{SLang_is_defined}
\synopsis{Check to see if the interpreter defines an object}
\usage{int SLang_is_defined (char *nm)}
\description
   The \var{SLang_is_defined} function may be used to determine
   whether or not a variable or function whose name is given by
   \var{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:
#v+
      1    intrinsic function
      2    user-defined slang function
     -1    intrinsic variable
     -2    user-defined global variable
#v-
   Note that variables correspond to negative numbers and functions
   are represented by positive numbers.
\seealso{SLadd_intrinsic_function, SLang_run_hooks, SLang_execute_function}
\done

\function{SLang_run_hooks}
\synopsis{Run a user-defined hook with arguments}
\usage{int SLang_run_hooks (char *fname, unsigned int n, ...)}
\description
   The \var{SLang_run_hooks} function may be used to execute a
   user-defined function named \var{fname}.  Before execution of the
   function, the \var{n} string arguments specified by the variable
   parameter list are pushed onto the stack.  If the function
   \var{fname} does not exist, \var{SLang_run_hooks} returns zero;
   otherwise, it returns \exmp{1} upon successful execution of the
   function, or \-1 if an error occurred.
\example
   The \jed editor uses \var{SLang_run_hooks} to setup the mode of a
   buffer based on the filename extension of the file associated with
   the buffer:
#v+
      char *ext = get_filename_extension (filename);
      if (ext == NULL) return -1;
      if (-1 == SLang_run_hooks ("mode_hook", 1, ext))
        return -1;
      return 0;
#v-
\seealso{SLang_is_defined, SLang_execute_function}
\done

\function{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 \var{fname}.  It returns zero if \var{fname} is not defined, or
   \exmp{1} if the function was successfully executed, or \-1 upon
   error.
\notes
   The function \var{SLexecute_function} may be a better alternative
   for some uses.
\seealso{SLang_run_hooks, SLexecute_function, SLang_is_defined}
\done

\function{SLang_get_function}
\synopsis{Get a pointer to a \slang function}
\usage{SLang_Name_Type *SLang_get_function (char *fname)}
\description
  This function returns a pointer to the internal \slang table entry
  of a function whose name is given by \var{fname}.  It returns
  \var{NULL} upon failure.  The value returned by this function can be
  used \var{SLexecute_function} to call the function directly
  from C.
\seealso{SLexecute_function}
\done

\function{SLexecute_function}
\synopsis{Execute a \slang or intrinsic function}
\usage{int SLexecute_function (SLang_Name_Type *nt)}
\description
  The \var{SLexecute_function} allows an application to call the
  \slang function specified by the \var{SLang_Name_Type} pointer
  \var{nt}.  This parameter must be non \var{NULL} and must have been
   previously obtained by a call to \var{SLang_get_function}.
\example
   Consider the \slang function:
#v+
     define my_fun (x)
     {
        return x^2 - 2;
     }
#v-
   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 \var{SLang_execute_function} by passing
   the string \exmp{"my_fun"}.  A better way that is much faster is to
   use \var{SLexecute_function}:
#v+
      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;
      }
#v-
   Although not necessary in this case, \var{SLang_start_arg_list} and
   \var{SLang_end_arg_list} were used to provide the function with
   information about the number of parameters passed to it.
\seealso{SLang_get_function, SLang_start_arg_list, SLang_end_arg_list}
\done

\function{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 \var{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.
\seealso{SLang_pop_string, SLang_pop_integer}
\done

\function{SLang_pop_fileptr}
\synopsis{Pop a file pointer}
\usage{int SLang_pop_fileptr (SLang_MMT_Type **mmt, FILE **fp)}
\description
  \var{SLang_pop_fileptr} pops a file pointer from the \slang
  run-time stack.  It returns zero upon success, or \-1 upon failure.

  A \slang file pointer (SLANG_FILEPTR_TYPE) is actually a memory
  managed object.  For this reason, \var{SLang_pop_fileptr} also
  returns the memory managed object via the argument list.  It is up
  to the calling routine to call \var{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 \var{SLang_free_mmt}:
#v+
     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;
     }
#v-
  This function can be used by a \slang function as follows:
#v+
     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");
     }
#v-
\seealso{SLang_free_mmt, SLang_pop_double}
\done

\function{SLadd_intrinsic_function}
\synopsis{Add a new intrinsic function to the interpreter}
\usage{int SLadd_intrinsic_function (name, f, type, nargs, ...)}
#v+
    char *name
    FVOID_STAR f
    SLtype type
    unsigned int nargs
#v-
\description
  The \var{SLadd_intrinsic_function} function may be used to add a new
  intrinsic function.  The \slang name of the function is specified by
  \var{name} and the actual function pointer is given by \var{f}, cast
  to \var{FVOID_STAR}.  The third parameter, \var{type} specifies the
  return type of the function and must be one of the following values:
#v+
    SLANG_VOID_TYPE   (returns nothing)
    SLANG_INT_TYPE    (returns int)
    SLANG_DOUBLE_TYPE (returns double)
    SLANG_STRING_TYPE (returns char *)
#v-
  The \var{nargs} parameter specifies the number of parameters to pass
  to the function.  The variable argument list following \var{nargs}
  must consists of \var{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 \var{system}
  intrinsic function to the following:
#v+
     static int jed_system (char *cmd)
     {
        if (Jed_Secure_Mode)
          {
             msg_error ("Access denied.");
             return -1;
          }
        return SLsystem (cmd);
     }
#v-
  After initializing the interpreter with \var{SLang_init_slang},
  \jed calls \var{SLadd_intrinsic_function} to substitute the above
  definition for the default \slang definition:
#v+
     if (-1 == SLadd_intrinsic_function ("system", (FVOID_STAR)jed_system,
                                         SLANG_INT_TYPE, 1,
                                         SLANG_STRING_TYPE))
       return -1;
#v-
\seealso{SLadd_intrinsic_variable, SLadd_intrinsic_array}
\done

\function{SLadd_intrinsic_variable}
\synopsis{Add an intrinsic variable to the interpreter}
\usage{int SLadd_intrinsic_variable (name, addr, type, rdonly)}
#v+
    char *name
    VOID_STAR addr
    SLtype type
    int rdonly
#v-
\description
  The \var{SLadd_intrinsic_variable} function adds an intrinsic
  variable called \var{name} to the interpeter.  The second parameter
  \var{addr} specifies the address of the variable (cast to
  \var{VOID_STAR}).  The third parameter, \var{type}, specifies the
  data type of the variable.  If the fourth parameter, \var{rdonly},
  is non-zero, the variable will interpreted by the interpreter as
  read-only.

  If successful, \var{SLadd_intrinsic_variable} returns zero,
  otherwise it returns \-1.
\example
  Suppose that \var{My_Global_Int} is a global variable (at least not
  a local one):
#v+
    int My_Global_Int;
#v-
  It can be added to the interpreter via the function call
#v+
    if (-1 == SLadd_intrinsic_variable ("MyGlobalInt",
                                        (VOID_STAR)&My_Global_Int,
                                        SLANG_INT_TYPE, 0))
      exit (1);
#v-
\notes
  The current implementation requires all pointer type intrinsic
  variables to be read-only.  For example,
#v+
    char *My_Global_String;
#v-
  is of type \var{SLANG_STRING_TYPE}, and must be declared as
  read-only.  Finally, not that
#v+
   char My_Global_Char_Buf[256];
#v-
  is \em{not} a \var{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.
\seealso{SLadd_intrinsic_function, SLadd_intrinsic_array}
\done

\function{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
??
\seealso{??}
\done

\function{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
??
\seealso{??}
\done

\function{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
??
\seealso{??}
\done

\function{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
??
\seealso{??}
\done

\function{SLclass_add_typecast}
\synopsis{??}
\usage{int SLclass_add_typecast (SLtype, SLtype int (*)_PROTO((SLtype, VOID_STAR, unsigned int,SLtype, VOID_STAR)),int);}
\description
??
\seealso{??}
\done