cref.txt

一个C格式的脚本处理函数库源代码,可让你的C程序具有执行C格式的脚本文件

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
--------------------------------------------------------------

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 exmp{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
--------------------------------------------------------------

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
--------------------------------------------------------------

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
--------------------------------------------------------------

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
--------------------------------------------------------------

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
--------------------------------------------------------------

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
--------------------------------------------------------------

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
--------------------------------------------------------------

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
--------------------------------------------------------------

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
--------------------------------------------------------------

SLang_pop_double

 SYNOPSIS
   Pop a double from the stack

 USAGE
   int SLang_pop_double (double *dptr, int *iptr, int *conv)

 DESCRIPTION
   The `SLang_pop_double' function pops a double precision number
   from the stack and returns it via `dptr'.  If the number was
   derived from an integer, `*conv' will be set to `1' upon
   return, otherwise, `*conv' will be set to `0'.  This
   function returns 0 upon success, otherwise it returns -1 and sets
   `SLang_Error' accordingly.

 NOTES
   If one does not care whether or not `*dptr' was derived from
   an integer, `iptr' and `conv' may be passed as `NULL'
   pointers.

 SEE ALSO
   SLang_pop_integer, SLang_push_double
--------------------------------------------------------------

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
--------------------------------------------------------------

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
--------------------------------------------------------------

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
--------------------------------------------------------------

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
--------------------------------------------------------------

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
--------------------------------------------------------------

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
--------------------------------------------------------------

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.  Othewise it returns a non-zero value whose meaning
   is given by the following table:

         1    intrinsic function  (SLANG_INTRINSIC)
         2    user-defined slang function (SLANG_FUNCTION)
        -1    intrinsic variable (SLANG_IVARIABLE)
        -2    user-defined global variable (SLANG_GVARIABLE)


 SEE ALSO
   SLadd_intrinsic_function, SLang_run_hooks, SLang_execute_function
--------------------------------------------------------------

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.