1019 строки
37 KiB
Tcl
1019 строки
37 KiB
Tcl
\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
|