#d proto#1 \tag{\tt{$1}}
#d documentstyle book
#d SLinterface#1 \bf{$1}
#d SLsmg \SLinterface{SLsmg}
#d SLtt \SLinterface{SLtt}
#d SLsearch \SLinterface{SLsearch}
#%}}}
\linuxdoc
\begin{\documentstyle}
\title S-Lang Library C Programmer's Guide, V2.0.4
\author John E. Davis, \tt{jed@jedsoft.org}
\date \__today__
\toc
#i preface.tm
\chapter{Introduction} #%{{{
\slang is a C programmer's library that includes routines for the rapid
development of sophisticated, user friendly, multi-platform applications.
The \slang library includes the following:
\begin{itemize}
\item Low level tty input routines for reading single characters at a time.
\item Keymap routines for defining keys and manipulating multiple keymaps.
\item A high-level keyprocessing interface (\verb{SLkp}) for
handling function and arrow keys.
\item High level screen management routines for manipulating both
monochrome and color terminals. These routines are \em{very}
efficient. (\tt{SLsmg})
\item Low level terminal-independent routines for manipulating the display
of a terminal. (\tt{SLtt})
\item Routines for reading single line input with line editing and recall
capabilities. (\tt{SLrline})
\item Searching functions: both ordinary searches and regular expression
searches. (\tt{SLsearch})
\item An embedded stack-based language interpreter with a C-like syntax.
\end{itemize}
The library is currently available for OS/2, MSDOS, Unix, and VMS
systems. For the most part, the interface to library routines has
been implemented in such a way that it appears to be platform
independent from the point of view of the application. In addition,
care has been taken to ensure that the routines are ``independent''
of one another as much as possible. For example, although the
keymap routines require keyboard input, they are not tied to
\slang's keyboard input routines--- one can use a different keyboard
\verb{getkey} routine if one desires. This also means that linking
to only part of the \slang library does not pull the whole library
into the application. Thus, \slang applications tend to be
relatively small in comparison to programs that use libraries with
similar capabilities.
#%}}}
\chapter{Error Handling} #%{{{
Many of the \slang functions return 0 upon success or -1 to signify
failure. Other functions may return \NULL to indicate failure. In
addition, upon failure, many will set the error state of the library
to a value that indicates the nature of the error. The value of this
state may be queried via the \cfun{SLang_get_error} function. This
function will return 0 to indicate that there is no error, or a
non-zero value such as one of the following constants:
#v+
SL_Any_Error SL_Index_Error
SL_OS_Error SL_Parse_Error
SL_Malloc_Error SL_Syntax_Error
SL_IO_Error SL_DuplicateDefinition_Error
SL_Write_Error SL_UndefinedName_Error
SL_Read_Error SL_Usage_Error
SL_Open_Error SL_Application_Error
SL_RunTime_Error SL_Internal_Error
SL_InvalidParm_Error SL_NotImplemented_Error
SL_TypeMismatch_Error SL_LimitExceeded_Error
SL_UserBreak_Error SL_Forbidden_Error
SL_Stack_Error SL_Math_Error
SL_StackOverflow_Error SL_DivideByZero_Error
SL_StackUnderflow_Error SL_ArithOverflow_Error
SL_ReadOnly_Error SL_ArithUnderflow_Error
SL_VariableUninitialized_Error SL_Domain_Error
SL_NumArgs_Error SL_Data_Error
SL_Unknown_Error SL_Unicode_Error
SL_Import_Error SL_InvalidUTF8_Error
#v-
For example, if a function tries to allocate memory but fails, then
\cfun{SLang_get_error} will return \var{SL_Malloc_Error}.
If the application makes use of the interpreter, then it is
important that application-specific functions called from the
interpreter set the error state of the library in order for
exception handling to work. This may be accomplished using the
\cfun{SLang_set_error} function, e.g.,
#v+
if (NULL == (fp = fopen (file, "r")))
SLang_set_error (SL_Open_Error);
#v-
Often it is desirable to give error message that contains more
information about the error. The \cfun{SLang_verror} function may
be used for this purpose:
#v+
if (NULL == (fp = fopen (file, "r")))
SLang_verror (SL_Open_Error, "Failed to open %s: errno=%d",
file, errno);
#v-
By default, \cfun{SLang_verror} will write the error message to
\var{stderr}. For applications that make use of the \SLsmg routines
it is probably better for the error message to be printed to a
specific area of the display. The \var{SLang_Error_Hook} variable
may be used to redirect error messages to an application defined
function, e.g.,
#v+
static void write_error (char *err)
{
SLsmg_gotorc (0, 0);
SLsmg_set_color (ERROR_COLOR);
SLsmg_write_string (err);
}
int main (int argc, char **argv)
{
/* Redirect error messages to write_error */
SLang_Error_Hook = write_error;
.
.
}
#v-
Under extremely rare circumstances the library will call the C
\cfun{exit} function causing the application to exit. This will
happen if the \cfun{SLtt_get_terminfo} is called but the terminal is
not sufficiently powerful. If this behavior is undesirable, then
another function exists (\cfun{SLtt_initialize}) that returns an
error code. The other times the library will exit are when the
interpreter is called upon to do something but has not been properly
initialized by the application. Such a condition is regarded as
misuse of the libary and should be caught by routine testing of the
application during development. In any case, when the library does
call the exit function, it will call an application-defined exit
hook specified by the SLang_Exit_Error_Hook variable:
#v+
static int exit_error_hook (char *fmt, va_list ap)
{
fprintf (stderr, "Fatal Error. Reason:");
vfprintf (stderr, fmt, va_list);
}
int main (int argc, char **argv)
{
SLang_Exit_Error_Hook = exit_error_hook;
.
.
}
#v-
The idea is that the hook can be used to perform some cleanup, free
resources, and other tasks that the application needs to do for a
clean exit.
#%}}}
\chapter{Unicode Support} #%{{{
\slang has native support for the UTF-8 encoding of unicode in a
number of its interfaces including the the \SLsmg screen mangement
interface as well as the interpreter. UTF-8 is a variable length
multibyte encoding where unicode characters are represented by one
to six bytes. A technical description of the UTF-encoding is beyond
the scope of this document, and as such the reader is advised to
look elsewhere for a more detailed specification of the encoding.
By default, the library's handling of UTF-8 is turned off. It may
be enabled by a call to the \ifun{SLutf8_enable} function:
#v+
int SLutf8_enable (int mode)
#v-
If the value of \exmp{mode} is 1, then the library will be put in
UTF-8 mode. If the value of \exmp{mode} is 0, then the library will
be initialized with UTF-8 support disabled. If the value is -1,
then the mode will determined through an OS-dependent manner, e.g.,
for Unix, the standard locale mechanism will be used. The return
value of this function will be 1 if UTF-8 support was activated, or
0 if not.
The above function determines the UTF-8 state of the library as a
whole. For some purposes it may be desirable to have more
fine-grained control of the UTF-8 support. For example, one might
be using the \jed editor to view a UTF-8 encoded file but
the terminal associated with the editor may not support UTF-8. In
such a case, one would want the \SLsmg interface to be in UTF-8 mode
but lower-level \SLtt interface to not be in UTF-8 mode. Hence, the
following activation functions are also provided:
#v+
int SLsmg_utf8_enable (int mode);
int SLtt_utf8_enable (int mode);
int SLinterp_utf8_enable (int mode);
#v-
Note that once one of these interface specific functions has been
called, any further calls to the umbrella function
\cfun{SLutf8_enable} will have no effect on that interface. For
this reason, it is best to call \cfun{SLutf8_enable} first before
the calling one of the interface-specific functions.
Until support for Unicode is more widespread among users, it is
expected that most users will still be using a national character
set such as ASCII or iso-8869-1. For example, iso-8869-1 is a very
widespread character set used on Usenet. As a result, applications
will still have to provide support for such character sets.
Unfortunately there appears to be no best way to do this.
For the most part, the UTF-8 support should be largely transparent
to the user. For example, the interpreter treats all multibyte
characters as a single character which means that the user does not
have to be concerned about the internal representation of a
character. Rather one must keep in mind the distinction between a
character and a byte.
#%}}}
\chapter{Interpreter Interface} #%{{{
The \slang library provides an interpreter that when embedded into
an application, makes the application extensible. Examples of
programs that embed the interpreter include the \jed editor and the
\slrn newsreader.
Embedding the interpreter is easy. The hard part is to decide what
application specific built-in or intrinsic functions should be
provided by the application. The \slang library provides some
pre-defined intrinsic functions, such as string processing
functions, and simple file input-output routines. However, the
basic philosophy behind the interpreter is that it is not a
standalone program and it derives much of its power from the
application that embeds it.
\sect{Embedding the Interpreter} #%{{{
Only one function needs to be called to embed the \slang interpreter
into an application: \cfun{SLang_init_slang}. This function
initializes the interpreter's data structures and adds some intrinsic
functions:
#v+
if (-1 == SLang_init_slang ())
exit (EXIT_FAILURE);
#v-
This function does not provide file input output intrinsic nor does
it provide mathematical functions. To make these as well as some
posix system calls available use
#v+
if ((-1 == SLang_init_slang ()) /* basic interpreter functions */
|| (-1 == SLang_init_slmath ()) /* sin, cos, etc... */
|| (-1 == SLang_init_array ()) /* sum, min, max, transpose... */
|| (-1 == SLang_init_stdio ()) /* stdio file I/O */
|| (-1 == SLang_init_ospath ()) /* path_concat, etc... */
|| (-1 == SLang_init_posix_dir ()) /* mkdir, stat, etc. */
|| (-1 == SLang_init_posix_process ()) /* getpid, umask, etc. */
|| (-1 == SLang_init_posix_io ()) /* open, close, read, ... */
|| (-1 == SLang_init_signal ()) /* signal, alarm, ... */
)
exit (EXIT_FAILURE);
#v-
If you intend to enable all intrinsic functions, then it is simpler
to initialize the interpreter via
#v+
if (-1 == SLang_init_all ())
exit (EXIT_FAILURE);
#v-
See the \slang-run-time-library for more information about the
intrinsic functions.
#%}}}
\sect{Calling the Interpreter} #%{{{
There are several ways of calling the interpreter. The two most common
method is to load a file containing \slang code, or to load a
string.
\sect1{Loading Files}
The \cfun{SLang_load_file} and \cfun{SLns_load_file} functions may
be used to interpret a file. Both these functions return zero if
successful, or \-1 upon failure. If either of these functions fail,
the interpreter will accept no more code unless the error state is
cleared. This is done by calling \cfun{SLang_restart} function to
set the interpreter to its default state:
#v+
if (-1 == SLang_load_file ("site.sl"))
{
/* Clear the error and reset the interpreter */
SLang_restart (1);
}
#v-
When a file is loaded via \cfun{SLang_load_file}, any non-public
variables and functions defined in the file will be placed into a
namespace that is local to the file itself. The
\cfun{SLns_load_file} function may be used to load a file using a
specified namespace, e.g.,
#v+
if (-1 == SLns_load_file ("site.sl", "NS"))
{
SLang_restart (1);
SLang_set_error (0);
}
#v-
will load \exfile{site.sl} into a namespace called \exns{NS}. If such a
namespace does not exist, then it will be created.
Both the \cfun{SLang_load_file} and \cfun{SLns_load_file} functions
search for files along an application-specified search path. This
path may be set using the \cfun{SLpath_set_load_path} function, as
well as from interpeted code via the \ifun{set_slang_load_path}
function. By default, no search path is defined.
\bf{
NOTE: It is highly recommended that an application embedding the
interpreter include the \slsh lib directory in the search path. The
\exfile{.sl} files that are part of \slsh are both useful and
and should work with any application embedding the interpreter.
Moreover, if the application permits dynamically loaded modules,
then there are a growing number of excellent quality modules for
\slsh that can be utilized by it. Applications that follow this
recommendation are said to be conforming.
}
Files are searched as follows: If the name begins with the
equivalent of \exstr{./} or \exstr{../}, then it is searched for
with respect to the current directory, and not along the load-path.
If no such file exists, then an error will be generated. Otherwise,
the file is searched for in each of the directories of the load-path
by concatenating the path element with the specified file name. The
first such file found to exist by this process will be loaded. If a
matching file still has not been found, and the file name lacks an
extension, then the path is searched with \exstr{.sl} and
\exstr{.slc} appended to the filename. If two such files are found
(one ending with \exstr{.sl} and the other with \exstr{.slc}), then
the more recent of the two will be used. If no matching file has
been found by this process, then the search will cease and an error
generated.
The search path is a delimiter separated list of directories that
specify where the interpreter looks for files. By default, the
value of the delimiter is OS-dependent following the convention of
the underlying OS. For example, on Unix the delimiter is
represented by a colon, on DOS/Windows it is a semi-colon, and on
VMS it is a space. The \cfun{SLpath_set_delimiter} and
\cfun{SLpath_get_delimiter} may be used to set and query the
delimiter's value, respectively.
\sect1{Loading Strings}
There are several other mechanisms for interacting with the
interpreter. For example, the \cfun{SLang_load_string} function
loads a string into the interpreter and interprets it:
#v+
if (-1 == SLang_load_string ("message (\"hello\");"))
return;
#v-
Similarly, the \cfun{SLns_load_string} function may be used to load
a string into a specified namespace.
Typically, an interactive application will load a file via
\cfun{SLang_load_file} and then go into a loop that consists of
reading lines of input and sending them to the interpreter, e.g.,
#v+
while (EOF != fgets (buf, sizeof (buf), stdin))
{
if (-1 == SLang_load_string (buf))
{
SLang_restart (1);
}
}
#v-
Finally, some applications such as \jed and \slrn use another method of
interacting with the interpreter. They read key sequences from the
keyboard and map those key sequences to interpreter functions via
the \slang keymap interface.
#%}}}
\sect{Intrinsic Functions} #%{{{
An intrinsic function is simply a function that is written in C and
is made available to the interpreter as a built-in function. For
this reason, the words `intrinsic' and `built-in' are often used
interchangeably.
Applications are expected to add application specific functions to
the interpreter. For example, \jed adds nearly 300 editor-specific
intrinsic functions. The application designer should think
carefully about what intrinsic functions to add to the interpreter.
\sect1{Restrictions on Intrinsic Functions} #%{{{
When implementing intrinsic functions, it is necessary to follow a
few rules to cooperate with the interpreter.
The C version of an intrinsic function takes only pointer arguments.
This is because when the interpreter calls an intrinsic function, it
passes values to the function by reference and \em{not} by value. For
example, intrinsic with the declarations:
#v+
int intrinsic_0 (void);
int intrinsic_1 (char *s);
void intrinsic_2 (char *s, int *i);
void intrinsic_3 (int *i, double *d, double *e);
#v-
are all valid. However,
#v+
int invalid_1 (char *s, int len);
#v-
is not valid since the \var{len} parameter is not a pointer.
The return value of an intrinsic function must be one of the
following types: \var{void}, \var{char}, \var{short}, \var{int},
\var{long}, \var{double}, \var{char *}, as well as unsigned versions
of the integer types. A function such as
#v+
int *invalid (void);
#v-
is not permitted since \var{int*} is not a valid return-type for an
intrinsic function. Any other type of value can be passed back to
the interpreter by explicitly pushing the object onto the
interpreter's stack via the appropriate "push" function.
The current implementation limits the number of arguments of an
intrinsic function to \exmp{7}. The "pop" functions can be used to
allow the function to take an arbitrary number as seen from an
interpreter script.
Another restriction is that the intrinsic function should regard all its
parameters as pointers to constant objects and make no attempt to
modify the value to which they point. For example,
#v+
void truncate (char *s)
{
s[0] = 0;
}
#v-
is illegal since the function modifies the string \var{s}.
#%}}}
\sect1{Adding a New Intrinsic} #%{{{
There are two basic mechanisms for adding an intrinsic function to the
interpreter: \cfun{SLadd_intrinsic_function} and
\cfun{SLadd_intrin_fun_table}. Functions may be added to a specified
namespace via \cfun{SLns_add_intrinsic_function} and
\cfun{SLns_add_intrin_fun_table} functions.
As an specific example, consider a function that will cause the
program to exit via the \var{exit} C library function. It is not
possible to make this function an intrinsic because it does not meet
the specifications for an intrinsic function that were described
earlier. However, one can call \var{exit} from a function that is
suitable, e.g.,
#v+
void intrin_exit (int *code)
{
exit (*code);
}
#v-
This function may be made available to the interpreter as an
intrinsic via the \cfun{SLadd_intrinsic_function} routine:
#v+
if (-1 == SLadd_intrinsic_function ("exit", (FVOID_STAR) intrin_exit,
SLANG_VOID_TYPE, 1,
SLANG_INT_TYPE))
exit (EXIT_FAILURE);
#v-
This statement basically tells the interpreter that
\var{intrin_exit} is a function that returns nothing and takes a
single argument: a pointer to an integer (\var{SLANG_INT_TYPE}).
A user can call this function from within the interpreter
via
#v+
message ("Calling the exit function");
exit (0);
#v-
After printing a message, this will cause the \var{intrin_exit}
function to execute, which in turn calls \var{exit}.
The most convenient mechanism for adding new intrinsic functions is
to create a table of \cfun{SLang_Intrin_Fun_Type} objects and add the
table via the \cfun{SLadd_intrin_fun_table} function. The table will
look like:
#v+
SLang_Intrin_Fun_Type My_Intrinsics [] =
{
/* table entries */
MAKE_INTRINSIC_N(...),
MAKE_INTRINSIC_N(...),
.
.
MAKE_INTRINSIC_N(...),
SLANG_END_INTRIN_FUN_TABLE
};
#v-
Construction of the table entries may be facilitated using a set of
\var{MAKE_INTRINSIC} macros defined in \var{slang.h}. The main
macro is called \var{MAKE_INTRINSIC_N} and takes 11 arguments:
#v+
MAKE_INTRINSIC_N(name, funct-ptr, return-type, num-args,
arg-1-type, arg-2-type, ... arg-7-type)
#v-
Here \var{name} is the name of the intrinsic function that the
interpreter is to give to the function. \var{func-ptr} is a pointer
to the intrinsic function taking \var{num-args} and returning
\var{ret-type}. The final \exmp{7} arguments specify the argument
types. For example, the \var{intrin_exit} intrinsic described above
may be added to the table using
#v+
MAKE_INTRINSIC_N("exit", intrin_exit, SLANG_VOID_TYPE, 1,
SLANG_INT_TYPE, 0,0,0,0,0,0)
#v-
While \var{MAKE_INTRINSIC_N} is the main macro for constructing
table entries, \var{slang.h} defines other macros that may prove
useful. In particular, an entry for the \var{intrin_exit} function
may also be created using any of the following forms:
#v+
MAKE_INTRINSIC_1("exit", intrin_exit, SLANG_VOID_TYPE, SLANG_INT_TYPE)
MAKE_INTRINSIC_I("exit", intrin_exit, SLANG_VOID_TYPE)
#v-
See \var{slang.h} for related macros. You are also encouraged to
look at, e.g., \var{slang/src/slstd.c} for a more extensive examples.
The table may be added via the \cfun{SLadd_intrin_fun_table}
function, e.g.,
#v+
if (-1 == SLadd_intrin_fun_table (My_Intrinsics, NULL))
{
/* an error occurred */
}
#v-
Please note that there is no need to load a given table more than
once, and it is considered to be an error on the part of the
application it adds the same table multiple times. For performance
reasons, no checking is performed by the library to see if a table
has already been added.
Earlier it was mentioned that intrinsics may be added to a specified
namespace. To this end, one must first get a pointer to the
namespace via the \cfun{SLns_create_namespace} function. The
following example illustrates how this function is used to add the
\var{My_Intrinsics} table to a namespace called \exmp{my}:
#v+
SLang_NameSpace_Type *ns = SLns_create_namespace ("my");
if (ns == NULL)
return -1;
return SLns_add_intrin_fun_table (ns, My_Intrinsics, "__MY__"));
#v-
#%}}}
\sect1{More Complicated Intrinsics} #%{{{
The intrinsic functions described in the previous example were
functions that took a fixed number of arguments. In this section we
explore more complex intrinsics such as those that take a variable
number of arguments.
Consider a function that takes two double precision numbers and
returns the lesser:
#v+
double intrin_min (double *a, double *b)
{
if (*a < *b) return *a;
return *b;
}
#v-
This function may be added to a table of intrinsics using
#v+
MAKE_INTRINSIC_2("vmin", intrin_min, SLANG_DOUBLE_TYPE,
SLANG_DOUBLE_TYPE, SLANG_DOUBLE_TYPE)
#v-
It is useful to extend this function to take an arbitray number of
arguments and return the lesser. Consider the following variant:
#v+
double intrin_min_n (int *num_ptr)
{
double min_value, x;
unsigned int num = (unsigned int) *num_ptr;
if (-1 == SLang_pop_double (&min_value))
return 0.0;
num--;
while (num > 0)
{
num--;
if (-1 == SLang_pop_double (&x))
return 0.0;
if (x < min_value) min_value = x;
}
return min_value;
}
#v-
Here the number to compare is passed to the function and the actual
numbers are removed from the stack via the \cfun{SLang_pop_double}
function. A suitable table entry for it is
#v+
MAKE_INTRINSIC_I("vmin", intrin_min_n, SLANG_DOUBLE_TYPE)
#v-
This function would be used in an interpreter script via a statement
such as
#v+
variable xmin = vmin (x0, x1, x2, x3, x4, 5);
#v-
which computes the smallest of \exmp{5} values.
The problem with this intrinsic function is that the user must
explicitly specify how many numbers to compare. It would be more
convenient to simply use
#v+
variable xmin = vmin (x0, x1, x2, x3, x4);
#v-
An intrinsic function can query the value of the variable
\var{SLang_Num_Function_Args} to obtain the necessary information:
#v+
double intrin_min (void)
{
double min_value, x;
unsigned int num = SLang_Num_Function_Args;
if (-1 == SLang_pop_double (&min_value, NULL, NULL))
return 0.0;
num--;
while (num > 0)
{
num--;
if (-1 == SLang_pop_double (&x, NULL, NULL))
return 0.0;
if (x < min_value) min_value = x;
}
return min_value;
}
#v-
This may be declared as an intrinsic using:
#v+
MAKE_INTRINSIC_0("vmin", intrin_min, SLANG_DOUBLE_TYPE)
#v-
#%}}}
#%}}}
\sect{Intrinsic Variables} #%{{{
It is possible to access an application's global variables from
within the interpreter. The current implementation supports the
access of variables of type \var{int}, \var{char *}, and
\var{double}.
There are two basic methods of making an intrinsic variable
available to the interpreter. The most straight forward method is
to use the function \cfun{SLadd_intrinsic_variable}:
#v+
int SLadd_intrinsic_variable (char *name, VOID_STAR addr,
SLtype data_type,
int read_only);
#v-
For example, suppose that \var{I} is an integer variable, e.g.,
#v+
int I;
#v-
One can make it known to the interpreter as \var{I_Variable} via a
statement such as
#v+
if (-1 == SLadd_intrinsic_variable ("I_Variable", &I,
SLANG_INT_TYPE, 0))
exit (EXIT_FAILURE);
#v-
Similarly, if \var{S} is declared as
#v+
char *S;
#v-
then
#v+
if (-1 == SLadd_intrinsic_variable ("S_Variable", &S,
SLANG_STRING_TYPE, 1))
exit (EXIT_FAILURE);
#v-
makes \var{S} available as a \em{read-only} variable with the name
\var{S_Variable}. Note that if a pointer variable is made available
to the interpreter, it should be declared as being \em{read-only} to
prevent the interpreter from changing the pointer's value.
It is important to note that if \var{S} were declared as an array of
characters, e.g.,
#v+
char S[256];
#v-
then it would not be possible to make it directly available to the
interpreter. However, one could create a pointer to it, i.e.,
#v+
char *S_Ptr = S;
#v-
and make \var{S_Ptr} available as a read-only variable.
One should not make the mistake of trying to use the same address
for different variables as the following example illustrates:
#v+
int do_not_try_this (void)
{
static char *names[3] = {"larry", "curly", "moe"};
unsigned int i;
for (i = 0; i < 3; i++)
{
int value;
if (-1 == SLadd_intrinsic_variable (names[i], (VOID_STAR) &value,
SLANG_INT_TYPE, 1))
return -1;
}
return 0;
}
#v-
Not only does this piece of code create intrinsic variables that use
the same address, it also uses the address of a local variable that
will go out of scope.
The most convenient method for adding many intrinsic variables to
the interpreter is to create an array of \var{SLang_Intrin_Var_Type}
objects and then add the array via \cfun{SLadd_intrin_var_table}.
For example, the array
#v+
static SLang_Intrin_Var_Type Intrin_Vars [] =
{
MAKE_VARIABLE("I_Variable", &I, SLANG_INT_TYPE, 0),
MAKE_VARIABLE("S_Variable", &S_Ptr, SLANG_STRING_TYPE, 1),
SLANG_END_TABLE
};
#v-
may be added via
#v+
if (-1 == SLadd_intrin_var_table (Intrin_Vars, NULL))
exit (EXIT_FAILURE);
#v-
It should be rather obvious that the arguments to the
\var{MAKE_VARIABLE} macro correspond to the parameters of the
\cfun{SLadd_intrinsic_variable} function.
Finally, variables may be added to a specific namespace via the
SLns_add_intrin_var_table and SLns_add_intrinsic_variable functions.
#%}}}
\sect{Aggregate Data Objects} #%{{{
An aggregate data object is an object that can contain more than one
data value. The \slang interpreter supports several such objects:
arrays, structure, and associative arrays. In the following
sections, information about interacting with these objects is given.
\sect1{Arrays} #%{{{
An intrinsic function may interact with an array in several different
ways. For example, an intrinsic may create an array and return it.
The basic functions for manipulating arrays include:
#v+
SLang_create_array
SLang_pop_array_of_type
SLang_push_array
SLang_free_array
SLang_get_array_element
SLang_set_array_element
#v-
The use of these functions will be illustrated via a few simple
examples.
The first example shows how to create an return an array of strings
to the interpreter. In particular, the names of the four seasons of
the year will be returned:
#v+
void months_of_the_year (void)
{
static char *seasons[4] =
{
"Spring", "Summer", "Autumn", "Winter"
};
SLang_Array_Type *at;
SLindex_Type i, four;
four = 4;
at = SLang_create_array (SLANG_STRING_TYPE, 0, NULL, &four, 1);
if (at == NULL)
return;
/* Now set the elements of the array */
for (i = 0; i < 4; i++)
{
if (-1 == SLang_set_array_element (at, &i, &seasons[i]))
{
SLang_free_array (at);
return;
}
}
(void) SLang_push_array (at, 0);
SLang_free_array (at);
}
#v-
This example illustrates several points:
First of all, the
\cfun{SLang_create_array} function was used to create a 1 dimensional
array of 4 strings. Since this function could fail, its return value
was checked. Also \var{SLindex_Type} was used for the array size and
index types. In \slang version 2, \var{SLindex_Type} is typedefed to
be an \var{int}. However, as this will change in a future version of
the library, \var{SLindex_Type} should be used.
The \cfun{SLang_set_array_element} function was
used to set the elements of the newly created array. Note that the
address containing the value of the array element was passed and not
the value of the array element itself. That is,
#v+
SLang_set_array_element (at, &i, seasons[i])
#v-
was not used. The return value from this function was also checked
because it too could also fail.
Finally, the array was pushed onto the interpreter's stack and then
it was freed. It is important to understand why it was freed. This
is because arrays are reference-counted. When the array was created,
it was returned with a reference count of \var{1}. When it was
pushed, the reference count was bumped up to \var{2}. Then since it
was nolonger needed by the function, \cfun{SLang_free_array} was
called to decrement the reference count back to \var{1}. For
convenience, the second argument to \cfun{SLang_push_array}
determines whether or not it is to also free the array. So, instead
of the two function calls:
#v+
(void) SLang_push_array (at, 0);
SLang_free_array (at);
#v-
it is preferable to combine them as
#v+
(void) SLang_push_array (at, 1);
#v-
The second example returns a diagonal array of a specified size to
the stack. A diagonal array is a 2-d array with all elements zero
except for those along the diagonal, which have a value of one:
#v+
void make_diagonal_array (SLindex_Type n)
{
SLang_Array_Type *at;
SLindex_Type dims[2];
SLindex_Type i, one;
dims[0] = dims[1] = n;
at = SLang_create_array (SLANG_INT_TYPE, 0, NULL, dims, 2);
if (at == NULL)
return;
one = 1;
for (i = 0; i < n; i++)
{
dims[0] = dims[1] = i;
if (-1 == SLang_set_array_element (at, dims, &one))
{
SLang_free_array (at);
return;
}
}
(void) SLang_push_array (at, 1);
}
#v-
In this example, only the diagonal elements of the array were set.
This is bacause when the array was created, all its elements were
set to zero.
Now consider an example that acts upon an existing array. In
particular, consider one that computes the trace of a 2-d matrix,
i.e., the sum of the diagonal elements:
#v+
double compute_trace (void)
{
SLang_Array_Type *at;
double trace;
SLindex_Type dims[2];
if (-1 == SLang_pop_array_of_type (&at, SLANG_DOUBLE_TYPE))
return 0.0;
/* We want a 2-d square matrix. If the matrix is 1-d and has only one
element, then return that element. */
trace = 0.0;
if (((at->num_dims == 1) && (at->dims[0] == 1))
|| ((at->num_dims == 2) && (at->dims[0] == at->dims[1])))
{
double dtrace;
SLindex_Type n = at->dims[0];
for (i = 0; i < n; i++)
{
dims[0] = dims[1] = i;
(void) SLang_get_array_element (at, &dims, &dtrace);
trace += dtrace;
}
}
else SLang_verror (SL_TYPE_MISMATCH, "Expecting a square matrix");
SLang_free_array (at);
return trace;
}
#v-
In this example, \cfun{SLang_pop_array_of_type} was used to pop an
array of doubles from the stack. This function will make implicit
typecasts in order to return an array of the requested type.
#%}}}
\sect1{Structures} #%{{{
For the purposes of this section, we shall differentiate structures
according to whether or not they correspond to an application defined
C structure. Those that do are called intrinsic structures, and
those do not are called \slang interpreter structures.
\sect2{Interpreter Structures}
The following simple example shows one method that may be used to
create and return a structure with a string and integer field to the
interpreter's stack:
#v+
int push_struct_example (char *string_value, int int_value)
{
char *field_names[2];
SLtype field_types[2];
VOID_STAR field_values[2];
field_names[0] = "string_field";
field_types[0] = SLANG_STRING_TYPE;
field_values[0] = &string_value;
field_names[1] = "int_field";
field_types[1] = SLANG_INT_TYPE;
field_values[1] = &int_value;
if (-1 == SLstruct_create_struct (2, field_names,
field_types, field_values))
return -1;
return 0;
}
#v-
Here, \cfun{SLstruct_create_struct} is used to push a
structure with the specified field names and values onto the
interpreter's stack.
A simpler mechanism exists provided that one has already defined a C
structure with a description of how the structure is laid out. For
example, consider a C structure defined by
#v+
typedef struct
{
char *s;
int i;
}
SI_Type;
#v-
Its layout may be specified via a table of
\var{SLang_CStruct_Field_Type} entries:
#v+
SLang_CStruct_Field_Type SI_Type_Layout [] =
{
MAKE_CSTRUCT_FIELD(SI_Type, s, "string_field", SLANG_STRING_TYPE, 0),
MAKE_CSTRUCT_FIELD(SI_Type, i, "int_field", SLANG_INT_TYPE, 0),
SLANG_END_CSTRUCT_TABLE
};
#v-
Here, MAKE_CSTRUCT_FIELD is a macro taking 5 arguments:
#v+
MAKE_CSTRUCT_FIELD(C-structure-type,
C-field-name,
slang-field-name,
slang-data-type,
is-read-only)
#v-
The first argument is the structure type, the second is the name of
a field of the structure, the third is a string that specifies the
name of the corresponding field of the \slang structure, the fourth
argument specifies the field's type, and the last argument
specifies whether or not the field should be regarded as read-only.
Once the layout of the structure has been specified, pushing a
\slang version of the structure is trival:
#v+
int push_struct_example (char *string_value, int int_value)
{
SI_Type si;
si.s = string_value;
si.i = int_value;
return SLang_push_cstruct ((VOID_STAR)&si, SI_Type_Layout);
}
#v-
This mechanism of structure creation also permits a \slang
structure to be passed to an intrinsic function through the use of
the SLang_pop_cstruct routine, e.g.,
#v+
void print_si_struct (void)
{
SI_Type si;
if (-1 == SLang_pop_cstruct ((VOID_STAR)&si, SI_Type_Layout))
return;
printf ("si.i=%d", si.i);
printf ("si.s=%s", si.s);
SLang_free_cstruct ((VOID_STAR)&si, SI_Type_Layout);
}
#v-
Assuming \exmp{print_si_struct} exists as an intrinsic function,
the \slang code
#v+
variable s = struct {string_field, int_field};
s.string_field = "hello";
s.int_field = 20;
print_si_struct (s);
#v-
would result in the display of
#v+
si.i=20;
si.s=hello
#v-
Note that the \cfun{SLang_free_cstruct} function was called after
the contents of \exmp{si} were nolonger needed. This was necessary
because \cfun{SLang_pop_cstruct} allocated memory to set the
\exmp{char *s} field of \exmp{si}. Calling
\cfun{SLang_free_cstruct} frees up such memory.
Now consider the following:
#v+
typedef struct
{
pid_t pid;
gid_t group;
}
X_t;
#v-
How should the layout of this structure be defined? One might be
tempted to use:
#v+
SLang_CStruct_Field_Type X_t_Layout [] =
{
MAKE_CSTRUCT_FIELD(X_t, pid, "pid", SLANG_INT_TYPE, 0),
MAKE_CSTRUCT_FIELD(X_t, group, "group", SLANG_INT_TYPE, 0),
SLANG_END_CSTRUCT_TABLE
};
#v-
However, this assumes \exmp{pid_t} and \exmp{gid_t} have been
typedefed as ints. But what if \exmp{gid_t} is a \exmp{short}? In
such a case, using
#v+
MAKE_CSTRUCT_FIELD(X_t, group, "group", SLANG_SHORT_TYPE, 0),
#v-
would be the appropriate entry for the \exmp{group} field. Of
course, one has no way of knowing how \exmp{gid_t} is declared on
other systems. For this reason, it is preferable to use the
\var{MAKE_CSTRUCT_INT_FIELD} macro in cases involving integer valued
fields, e.g.,
#v+
SLang_CStruct_Field_Type X_t_Layout [] =
{
MAKE_CSTRUCT_INT_FIELD(X_t, pid, "pid", 0),
MAKE_CSTRUCT_INT_FIELD(X_t, group, "group", 0),
SLANG_END_CSTRUCT_TABLE
};
#v-
Before leaving this section, it is important to mention that
access to character array fields is not permitted via this
interface. That is, a structure such as
#v+
typedef struct
{
char name[32];
}
Name_Type;
#v-
is not supported since \exmp{char name[32]} is not a
\var{SLANG_STRING_TYPE} object. Always keep in mind that a
\var{SLANG_STRING_TYPE} object is a \exmp{char *}.
\sect2{Intrinsic Structures}
Here we show how to make intrinsic structures available to
the interpreter.
The simplest interface is to structure pointers and not
to the actual structures themselves. The latter would require the
interpreter to be involved with the creation and destruction of the
structures. Dealing with the pointers themselves is far simpler.
As an example, consider an object such as
#v+
typedef struct _Window_Type
{
char *title;
int row;
int col;
int width;
int height;
} Window_Type;
#v-
which defines a window object with a title, size (\var{width},
\var{height}), and location (\var{row}, \var{col}).
We can make variables of type \var{Window_Type} available to the
interpreter via a table as follows:
#v+
static SLang_IStruct_Field_Type Window_Type_Field_Table [] =
{
MAKE_ISTRUCT_FIELD(Window_Type, title, "title", SLANG_STRING_TYPE, 1),
MAKE_ISTRUCT_FIELD(Window_Type, row, "row", SLANG_INT_TYPE, 0),
MAKE_ISTRUCT_FIELD(Window_Type, col, "col", SLANG_INT_TYPE, 0),
MAKE_ISTRUCT_FIELD(Window_Type, width, "width", SLANG_INT_TYPE, 0),
MAKE_ISTRUCT_FIELD(Window_Type, height, "height", SLANG_INT_TYPE, 0),
SLANG_END_ISTRUCT_TABLE
};
#v-
More precisely, this defines the layout of the \var{Window_Type} structure.
Here, the \var{title} has been declared as a read-only field. Using
#v+
MAKE_ISTRUCT_FIELD(Window_Type, title, "title", SLANG_STRING_TYPE, 0),
#v-
would allow read-write access.
Now suppose that \var{My_Window} is a pointer to a \var{Window_Type}
object, i.e.,
#v+
Window_Type *My_Window;
#v-
We can make this variable available to the interpreter via the
\cfun{SLadd_istruct_table} function:
#v+
if (-1 == SLadd_istruct_table (Window_Type_Field_Table,
(VOID_STAR) &My_Window,
"My_Win"))
exit (1);
#v-
This creates a S-Lang interpreter variable called \var{My_Win} whose value
corresponds to the \var{My_Win} structure. This would permit one to
access the fields of \var{My_Window} via \slang statements such as
#v+
define set_width_and_height (w,h)
{
My_Win.width = w;
My_Win.height = h;
}
#v-
It is extremely important to understand that the interface described in
this section does not allow the interpreter to create new instances of
\var{Window_Type} objects. The interface merely defines an association or
correspondence between an intrinsic structure pointer and a \slang
variable. For example, if the value of \var{My_Window} is \var{NULL}, then
\var{My_Win} would also be \var{NULL}.
One should be careful in allowing read/write access to character string
fields. If read/write access is allowed, then the application should
always use the \cfun{SLang_create_slstring} and \cfun{SLang_free_slstring}
functions to set the character string field of the structure.
#%}}}
#%}}}
\sect{Signals} #%{{{
If your program that embeds the interpreter processes signals, then
it may be undesirable to allow access to all signals from the
interpreter. For example, if your program has a signal handler for
\ivar{SIGHUP} then it is possible that an interpreter script could
specify a different signal handler, which may or may not be desirable.
If you do not want to allow the interpreter access to some signal,
then that signal can be made off-limits to the interpreter via the
\cfun{SLsig_forbid_signal} function:
#v+
/* forbid a signal handler for SIGHUP */
SLsig_forbid_signal (SIGHUP, 1);
/* Allow a signal handler for SIGTERM */
SLsig_forbid_signal (SIGTERM, 0);
#v-
By default, all signals are allowed access from the interpreter.
#%}}}
\sect{Exceptions}
#%}}}
\chapter{Keyboard Interface} #%{{{
#%{{{ Overview
\slang's keyboard interface has been designed to allow an
application to read keyboard input from the user in a
system-independent manner. The interface consists of a set of low
routines for reading single character data as well as a higher
level interface (\grp{SLkp}) which utilize \slang's keymap facility
for reading multi-character sequences.
To initialize the interface, one must first call the function
\verb{SLang_init_tty}. Before exiting the program, the function
\verb{SLang_reset_tty} must be called to restore the keyboard
interface to its original state. Once initialized, the low-level
\verb{SLang_getkey} function may be used to read \em{simgle}
keyboard characters from the terminal. An application using the
higher-level \grp{SLkp} interface will read charcters using the
\verb{SLkp_getkey} function.
In addition to these basic functions, there are also functions to
``unget'' keyboard characters, flush the input, detect pending-input
with a timeout, etc. These functions are defined below.
#%}}}
\sect{Initializing the Keyboard Interface} #%{{{
The function \verb{SLang_init_tty} must be called to initialize the
terminal for single character input. This puts the terminal in a mode
usually referred to as ``raw'' mode.
The prototype for the function is:
#v+
int SLang_init_tty (int abort_char, int flow_ctrl, int opost);
#v-
It takes three parameters that are used to specify how the terminal is to
be initialized.
#%+
Although the \slang keyboard interface has been
%designed to be as system independent as possible, there are semantic
% differences.
#%-
The first parameter, \verb{abort_char}, is used to specify the interrupt
character (\tt{SIGINT}). Under MSDOS, this value corresponds to the scan
code of the character that will be used to generate the interrupt. For
example, under MSDOS, \verb{34} should be used to make \key{Ctrl-G} generate an
interrupt signal since 34 is the scan code for \key{G}. On other
systems, the value of \verb{abort_char} will simply be the ascii value of
the control character that will be used to generate the interrupt signal,
e.g., \tt{7} for \key{Ctrl-G}. If \verb{-1} is passed, the interrupt
character will not be changed.
Pressing the interrupt character specified by the first argument will
generate a signal (\tt{SIGINT}) that may or not be caught by the
application. It is up to the application to catch this signal. \slang
provides the function \verb{Slang_set_abort_signal} to make it easy to
facilitate this task.
The second parameter is used to specify whether or not flow control should
be used. If this parameter is zero, flow control is enabled otherwise
it is disabled. Disabling flow control is necessary to pass certain
characters to the application (e.g., \key{Ctrl-S} and \key{Ctrl-Q}).
For some systems such as MSDOS, this parameter is meaningless.
The third parameter, \verb{opost}, is used to turn output processing on or
off. If \verb{opost} is zero, output processing is \em{not} turned on
otherwise, output processing is turned on.
The \verb{SLang_init_tty} function returns -1 upon failure. In addition,
after it returns, the \slang global variable \verb{SLang_TT_Baud_Rate}
will be set to the baud rate of the terminal if this value can be
determined.
Example:
#v+
if (-1 == SLang_init_tty (7, 0, 0)) /* For MSDOS, use 34 as scan code */
{
fprintf (stderr, "Unable to initialize the terminal.\n");
exit (1);
}
SLang_set_abort_signal (NULL);
#v-
Here the terminal is initialized such that flow control and output
processing are turned off. In addition, the character
\key{Ctrl-G}\footnote{For MSDOS systems, use the \em{scan code} 34
instead of 7 for \key{Ctrl-G}} has been specified to be the interrupt
character. The function \verb{SLang_set_abort_signal} is used to
install the default \slang interrupt signal handler.
#%}}}
\sect{Resetting the Keyboard Interface} #%{{{
The function \verb{SLang_reset_tty} must be called to reset the terminal
to the state it was in before the call to \verb{SLang_init_tty}. The
prototype for this function is:
#v+
void SLang_reset_tty (void);
#v-
Usually this function is only called before the program exits. However,
if the program is suspended it should also be called just before suspension.
#%}}}
\sect{Initializing the \grp{SLkp} Routines} #%{{{
Extra initialization of the higher-level \grp{SLkp} functions are
required because they are layered on top of the lower level
routines. Since the \verb{SLkp_getkey} function is able to process
function and arrow keys in a terminal independent manner, it is
necessary to call the \verb{SLtt_get_terminfo} function to get
information about the escape character sequences that the terminal's
function keys send. Once that information is available, the
\verb{SLkp_init} function can construct the proper keymaps to
process the escape sequences.
This part of the initialization process for an application using
this interface will look something like:
#v+
SLtt_get_terminfo ();
if (-1 == SLkp_init ())
{
SLang_doerror ("SLkp_init failed.");
exit (1);
}
if (-1 == SLang_init_tty (-1, 0, 1))
{
SLang_doerror ("SLang_init_tty failed.");
exit (1);
}
#v-
It is important to check the return status of the \verb{SLkp_init}
function which can failed if it cannot allocate enough memory for
the keymap.
#%}}}
\sect{Setting the Interrupt Handler} #%{{{
The function \verb{SLang_set_abort_signal} may be used to associate an
interrupt handler with the interrupt character that was previously
specified by the \verb{SLang_init_tty} function call. The prototype for
this function is:
#v+
void SLang_set_abort_signal (void (*)(int));
#v-
This function returns nothing and takes a single parameter which is a
pointer to a function taking an integer value and returning
\verb{void}. If a \verb{NULL} pointer is passed, the default \slang
interrupt handler will be used. The \slang default interrupt handler
under Unix looks like:
#v+
static void default_sigint (int sig)
{
SLsignal_intr (SIGINT, default_sigint);
SLKeyBoard_Quit = 1;
if (SLang_Ignore_User_Abort == 0)
SLang_set_error (SL_UserBreak_Error);
}
#v-
It simply sets the global variable \verb{SLKeyBoard_Quit} to one and
if the variable \verb{SLang_Ignore_User_Abort} is non-zero,
the error state is set to indicate a user break condition. (The
function \verb{SLsignal_intr} is similar to the standard C
\verb{signal} function \em{except that it will interrupt system
calls}. Some may not like this behavior and may wish to call
this \verb{SLang_set_abort_signal} with a different handler.)
Although the function expressed above is specific to Unix, the
analogous routines for other operating systems are equivalent in
functionality even though the details of the implementation may vary
drastically (e.g., under MSDOS, the hardware keyboard interrupt
\verb{int 9h} is hooked).
#%}}}
\sect{Reading Keyboard Input with SLang_getkey} #%{{{
After initializing the keyboard via \verb{SLang_init_tty},
the \slang function \verb{SLang_getkey} may be used to read
characters from the terminal interface. In addition, the function
\verb{SLang_input_pending} may be used to determine whether or not
keyboard input is available to be read.
These functions have prototypes:
#v+
unsigned int SLang_getkey (void);
int SLang_input_pending (int tsecs);
#v-
The \verb{SLang_getkey} function returns a single character from the
terminal. Upon failure, it returns \verb{0xFFFF}. If the interrupt
character specified by the \verb{SLang_init_tty} function is pressed
while this function is called, the function will return the value of
the interrupt character and set the \slang global variable
\verb{SLKeyBoard_Quit} to a non-zero value. In addition, if the
default \slang interrupt handler has been specified by a \verb{NULL}
argument to the \verb{SLang_set_abort_signal} function, the error
state of the library will be set to \verb{SL_UserBreak_Error}
\em{unless} the variable \verb{SLang_Ignore_User_Abort} is non-zero.
The \verb{SLang_getkey} function waits until input is available to be
read. The \verb{SLang_input_pending} function may be used to determine
whether or not input is ready. It takes a single parameter that indicates
the amount of time to wait for input before returning with information
regarding the availability of input. This parameter has units of one
tenth (1/10) of a second, i.e., to wait one second, the value of the
parameter should be \tt{10}. Passing a value of zero causes the function
to return right away. \verb{SLang_input_pending} returns a positive
integer if input is available or zero if input is not available. It will
return -1 if an error occurs.
Here is a simple example that reads keys from the terminal until one
presses \key{Ctrl-G} or until 5 seconds have gone by with no input:
#v+
#include