<!-- -*- mode: tm; mode: fold -*- -->

<!-- text-macro definitions  -->








<!doctype linuxdoc system>

<book>

<title> S-Lang Library C Programmer's Guide, V1.4.2
<author> John E. Davis, <tt>davis@space.mit.edu</tt>
<date> Jan 26, 2003

<toc>


<chapt>Preface<p> 

  <bf>S-Lang</bf> is an interpreted language that was designed from the start
  to be easily embedded into a program to provide it with a powerful
  extension language.  Examples of programs that use <bf>S-Lang</bf> as an
  extension language include the <bf>jed</bf> text editor, the <bf>slrn</bf>
  newsreader, and <bf>sldxe</bf> (unreleased), a numerical computation
  program.  For this reason, <bf>S-Lang</bf> does not exist as a separate
  application and many of the examples in this document are presented
  in the context of one of the above applications.

  <bf>S-Lang</bf> is also a programmer's library that permits a programmer to
  develop sophisticated platform-independent software.  In addition to
  providing the <bf>S-Lang</bf> extension language, the library provides
  facilities for screen management, keymaps, low-level terminal I/O,
  etc.  However, this document is concerned only with the extension
  language and does not address these other features of the <bf>S-Lang</bf>
  library.  For information about the other components of the library,
  the reader is referred to the <bf>The <bf>S-Lang</bf> Library Reference</bf>.

<sect>A Brief History of <bf>S-Lang</bf><p> 

  I first began working on <bf>S-Lang</bf> sometime during the fall of 1992.
  At that time I was writing a text editor (<bf>jed</bf>), which I wanted to
  endow with a macro language.  It occured to me that an
  application-independent language that could be embedded into the
  editor would prove more useful because I could envision embedding it
  into other programs.  As a result, <bf>S-Lang</bf> was born.  
  
  <bf>S-Lang</bf> was originally a stack language that supported a
  postscript-like syntax.  For that reason, I named it <bf>S-Lang</bf>, where
  the <em>S</em> was supposed to emphasize its stack-based nature.  About
  a year later, I began to work on a preparser that would allow one to
  write using a more traditional infix syntax making it easier to use
  for those unfamiliar with stack based languages.  Currently, the
  syntax of the language resembles C, nevertheless some
  postscript-like features still remain, e.g., the `<tt>%</tt>' character
  is still used as a comment delimiter.



<sect>Acknowledgements<p> 

   Since I first released <bf>S-Lang</bf>, I have received a lot feedback about
   the library and the language from many people.  This has given me
   the opportunity and pleasure to interact with several people to
   make the library portable and easy to use.  In particular, I would
   like to thank the following individuals:

     Luchesar Ionkov <tt>&lt;lionkov@sf.cit.bg&gt;</tt> for his comments and
     criticisms of the syntax of the language.  He was the person who
     made me realize that the low-level byte-code engine should be
     totally type-independent.  He also improved the tokenizer and
     preparser and impressed upon me that the language needed a
     grammar.

     Mark Olesen <tt>&lt;olesen@weber.me.queensu.ca&gt;</tt> for his many patches to
     various aspects of the library and his support on AIX. He also
     contributed a lot to the pre-processing (<tt>SLprep</tt>) routines.

     John Burnell <tt>&lt;j.burnell@irl.cri.nz&gt;</tt> for the OS/2 port of the
     video and keyboard routines.  He also made value suggestions
     regarding the interpreter interface.

     Darrel Hankerson <tt>&lt;hankedr@mail.auburn.edu&gt;</tt> for cleaning up and
     unifying some of the code and the makefiles.

     Dominik Wujastyk <tt>&lt;ucgadkw@ucl.ac.uk&gt;</tt> who was always willing to test
     new releases of the library.

     Michael Elkins <tt>&lt;me@muddcs.cs.hmc.edu&gt;</tt> for his work on the curses
     emulation.

     Ulli Horlacher <tt>&lt;framstag@belwue.de&gt;</tt> and Oezguer Kesim
     <tt>&lt;kesim@math.fu-berlin.de&gt;</tt> for the <bf>S-Lang</bf> newsgroup and mailing list.
     
     Hunter Goatley, Andy Harper <tt>&lt;Andy.Harper@kcl.ac.uk&gt;</tt>, and Martin
     P.J. Zinser <tt>&lt;zinser@decus.decus.de&gt;</tt> for their VMS support.
     
     Dave Sims <tt>&lt;sims@usa.acsys.com&gt;</tt> and Chin Huang
     <tt>&lt;cthuang@vex.net&gt;</tt> for Windows 95 and Windows NT support.
     
     Lloyd Zusman <tt>&lt;ljz@asfast.com&gt;</tt> and Rich Roth <tt>&lt;rich@on-the-net.com&gt;</tt>
     for creating and maintaining <tt>www.s-lang.org</tt>.

  I am also grateful to many other people who send in bug-reports and
  bug-fixes, for without such community involvement, <bf>S-Lang</bf> would not
  be as well-tested and stable as it is.  Finally, I would like to
  thank my wife for her support and understanding while I spent long
  weekend hours developing the library.





<chapt>Introduction<p> 

  <bf>S-Lang</bf> is a C programmer's library that includes routines for the rapid
  development of sophisticated, user friendly, multi-platform applications.
  The <bf>S-Lang</bf> library includes the following:

<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 (<tt>SLkp</tt>) for
       handling function and arrow keys.
<item>  High level screen management routines for manipulating both
       monochrome and color terminals.  These routines are <em>very</em>
       efficient. (<tt>SLsmg</tt>)
<item>  Low level terminal-independent routines for manipulating the display
       of a terminal. (<tt>SLtt</tt>)
<item>  Routines for reading single line input with line editing and recall
       capabilities. (<tt>SLrline</tt>)
<item>  Searching functions: both ordinary searches and regular expression
       searches. (<tt>SLsearch</tt>)
<item>  An embedded stack-based language interpreter with a C-like syntax.
</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
  <bf>S-Lang</bf>'s keyboard input routines--- one can use a different keyboard
  <tt>getkey</tt> routine if one desires.  This also means that linking
  to only part of the <bf>S-Lang</bf> library does not pull the whole library
  into the application.  Thus, <bf>S-Lang</bf> applications tend to be
  relatively small in comparison to programs that use libraries with
  similar capabilities.



<chapt>Interpreter Interface<p> 

  The <bf>S-Lang</bf> library provides an interpreter that when embedded into
  an application, makes the application extensible.  Examples of
  programs that embed the interpreter include the <bf>jed</bf> editor and the
  <bf>slrn</bf> 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 <bf>S-Lang</bf> 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<p> 

  Only one function needs to be called to embed the <bf>S-Lang</bf> interpreter
  into an application: <tt>SLang_init_slang</tt>.  This function
  initializes the interpreter's data structures and adds some intrinsic
  functions:
<tscreen><verb>
      if (-1 == SLang_init_slang ())
        exit (EXIT_FAILURE);
</verb></tscreen>
  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
<tscreen><verb>
     if ((-1 == SLang_init_slang ())    /* basic interpreter functions */
         || (-1 == SLang_init_slmath ()) /* sin, cos, etc... */
         || (-1 == SLang_init_stdio ()) /* stdio file I/O */
         || (-1 == SLang_init_posix_dir ()) /* mkdir, stat, etc. */
         || (-1 == SLang_init_posix_process ()) /* getpid, umask, etc. */
        )
       exit (EXIT_FAILURE);
</verb></tscreen>
  If you intend to enable all intrinsic functions, then it is simpler
  to initialize the interpreter via
<tscreen><verb>
     if (-1 == SLang_init_all ())
       exit (EXIT_FAILURE);
</verb></tscreen>
  See the \slang-run-time-library for more information about the
  intrinsic functions.
  




<sect>Calling the Interpreter<p> 

  There are several ways of calling the interpreter.  The most common
  method used by both <bf>jed</bf> and <bf>slrn</bf> is to use the
  <tt>SLang_load_file</tt> function to interprete a file.  For example,
  <bf>jed</bf> starts by loading a file called <tt>site.sl</tt>:
<tscreen><verb>
     if (-1 == SLang_load_file ("site.sl"))
       {
         SLang_restart (1);
         SLang_Error = 0;
       }
</verb></tscreen>
  The <tt>SLang_load_file</tt> function returns zero upon if successful, or <tt>-1</tt>
  upon failure.  The <tt>SLang_restart</tt> function resets the
  interpreter back to its default state; however, it does not reset
  <tt>SLang_Error</tt> to zero.  It is up to the application to
  re-initialize the <tt>SLang_Error</tt> variable.

  There are several other mechanisms for interacting with the
  interpreter.  For example, the <tt>SLang_load_string</tt> function
  loads a string into the interpreter and interprets it:
<tscreen><verb>
    if (-1 == SLang_load_string ("message (\"hello\");"))
      {
        SLang_restart (1);
        SLang_Error = 0;
      }
</verb></tscreen>
  
  Typically, an interactive application will load a file via
  <tt>SLang_load_file</tt> and then go into a loop that consists of
  reading lines of input and sending them to the interpreter, e.g.,
<tscreen><verb>
      while (EOF != fgets (buf, sizeof (buf), stdin))
        {
           if (-1 == SLang_load_string (buf))
             SLang_restart (1);
           SLang_Error = 0;
        }
</verb></tscreen>

  Both <bf>jed</bf> and <bf>slrn</bf> 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 <bf>S-Lang</bf> keymap
  interface.



<sect>Intrinsic Functions<p> 

  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, <bf>jed</bf> 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<p> 

  Intrinsic functions are required to follow a few rules to cooperate
  with the interpreter.  

  Intrinsic function must take only pointer arguments.  This is
  because when the interpreter calls an intrinsic function, it passes
  value to the function by reference and <em>not</em> by value.
  For example, intrinsic with the declarations:
<tscreen><verb>
     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);
</verb></tscreen>
  are all valid.  However, 
<tscreen><verb>
     int invalid_1 (char *s, int len);
</verb></tscreen>
  is not valid since the <tt>len</tt> parameter is not a pointer.
  
  Intrinsic functions can only return <tt>void</tt>, <tt>int</tt>,
  <tt>double</tt>, or <tt>char *</tt>.  A function such as 
<tscreen><verb>
    int *invalid (void);
</verb></tscreen>
  is not permitted since it does not return one of these types.  The
  current implementation limits the number of arguments to <tt>7</tt>.

  Another restriction is that the intrinsic should regard all its
  parameters as pointers to constant objects and make no attempt to
  modify the value to which they point.  For example,
<tscreen><verb>
      void truncate (char *s)
      {
         s[0] = 0;
      }
</verb></tscreen>
  is illegal since the function modifies the string <tt>s</tt>.




<sect1>Adding a New Intrinsic<p> 

  There are two basic mechanisms for adding an intrinsic function to the
  interpreter: <tt>SLadd_intrinsic_function</tt> and
  <tt>SLadd_intrin_fun_table</tt>.  Functions may be added to a specified
  namespace via <tt>SLns_add_intrinsic_function</tt> and
  <tt>SLns_add_intrin_fun_table</tt> functions.

  As an specific example, consider a function that will cause the
  program to exit via the <tt>exit</tt> 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 <tt>exit</tt> from a function that is
  suitable, e.g.,
<tscreen><verb>
     void intrin_exit (int *code)
     {
        exit (*code);
     }
</verb></tscreen>
  This function may be made available to the interpreter as as an
  intrinsic via the <tt>SLadd_intrinsic_function</tt> routine:
<tscreen><verb>
     if (-1 == SLadd_intrinsic_function ("exit", (FVOID_STAR) intrin_exit,
                                         SLANG_VOID_TYPE, 1,
                                         SLANG_INT_TYPE))
       exit (EXIT_FAILURE);
</verb></tscreen>
  This statement basically tells the interpreter that
  <tt>intrin_exit</tt> is a function that returns nothing and takes a
  single argument: a pointer to an integer (<tt>SLANG_INT_TYPE</tt>).
  A user can call this function from within the interpreter
  via
<tscreen><verb>
     message ("Calling the exit function");
     exit (0);
</verb></tscreen>
  After printing a message, this will cause the <tt>intrin_exit</tt>
  function to execute, which in turn calls <tt>exit</tt>.
  
  The most convenient mechanism for adding new intrinsic functions is
  to create a table of <tt>SLang_Intrin_Fun_Type</tt> objects and add the
  table via the <tt>SLadd_intrin_fun_table</tt> function.  The table will
  look like:
<tscreen><verb>
    SLang_Intrin_Fun_Type My_Intrinsics [] = 
    {
     /* table entries */
      MAKE_INTRINSIC_N(...),
      MAKE_INTRINSIC_N(...),
            .
            .
      MAKE_INTRINSIC_N(...),
      SLANG_END_INTRIN_FUN_TABLE
    };
</verb></tscreen>
  Construction of the table entries may be facilitated using a set of
  <tt>MAKE_INTRINSIC</tt> macros defined in <tt>slang.h</tt>.  The main
  macro is called <tt>MAKE_INTRINSIC_N</tt> and takes 11 arguments:
<tscreen><verb>
    MAKE_INTRINSIC_N(name, funct-ptr, return-type, num-args,
                     arg-1-type, arg-2-type, ... arg-7-type)
</verb></tscreen>
  Here <tt>name</tt> is the name of the intrinsic function that the
  interpreter is to give to the function. <tt>func-ptr</tt> is a pointer
  to the intrinsic function taking <tt>num-args</tt> and returning
  <tt>ret-type</tt>.  The final <tt>7</tt> arguments specifiy the argument
  types.  For example, the <tt>intrin_exit</tt> intrinsic described above
  may be added to the table using
<tscreen><verb>
    MAKE_INTRINSIC_N("exit", intrin_exit, SLANG_VOID_TYPE, 1,
                     SLANG_INT_TYPE, 0,0,0,0,0,0)
</verb></tscreen>

  While <tt>MAKE_INTRINSIC_N</tt> is the main macro for constructing
  table entries, <tt>slang.h</tt> defines other macros that may prove
  useful.  In particular, an entry for the <tt>intrin_exit</tt> function
  may also be created using any of the following forms:
<tscreen><verb>
    MAKE_INTRINSIC_1("exit", intrin_exit, SLANG_VOID_TYPE, SLANG_INT_TYPE)
    MAKE_INTRINSIC_I("exit", intrin_exit, SLANG_VOID_TYPE)
</verb></tscreen>
  See <tt>slang.h</tt> for related macros.  You are also encouraged to
  look at, e.g., <tt>slang/src/slstd.c</tt> for a more extensive examples.

  The table may be added via the <tt>SLadd_intrin_fun_table</tt>
  function, e.g.,
<tscreen><verb>
    if (-1 == SLadd_intrin_fun_table (My_Intrinsics, NULL))
      {
         /* an error occurred */
      }
</verb></tscreen>
  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 <tt>SLns_create_namespace</tt> function.  The
  following example illustrates how this function is used to add the 
  <tt>My_Intrinsics</tt> table to a namespace called <tt>my</tt>:
<tscreen><verb>
   SLang_NameSpace_Type *ns = SLns_create_namespace ("my");
   if (ns == NULL)
     return -1;

   return SLns_add_intrin_fun_table (ns, My_Intrinsics, "__MY__"));
</verb></tscreen>



<sect1>More Complicated Intrinsics<p> 
  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: 
<tscreen><verb>
     double intrin_min (double *a, double *b)
     {
        if (*a &lt; *b) return *a;
        return *b;
     }
</verb></tscreen>
  This function may be added to a table of intrinsics using
<tscreen><verb>
    MAKE_INTRINSIC_2("vmin", intrin_min, SLANG_DOUBLE_TYPE,
                     SLANG_DOUBLE_TYPE, SLANG_DOUBLE_TYPE)
</verb></tscreen>
  It is useful to extend this function to take an arbitray number of
  arguments and return the lesser.  Consider the following variant:
<tscreen><verb>
    double intrin_min_n (int *num_ptr)
    {
       double min_value, x;
       unsigned int num = (unsigned int) *num_ptr;
       
       if (-1 == SLang_pop_double (&amp;min_value, NULL, NULL))
         return 0.0;
       num--;
       
       while (num &gt; 0)
         {
            num--;
            if (-1 == SLang_pop_double (&amp;x, NULL, NULL))
              return 0.0;
            if (x &lt; min_value) min_value = x;
         }
       return min_value;
    }
</verb></tscreen>
  Here the number to compare is passed to the function and the actual
  numbers are removed from the stack via the <tt>SLang_pop_double</tt>
  function.  A suitable table entry for it is
<tscreen><verb>
    MAKE_INTRINSIC_I("vmin", intrin_min_n, SLANG_DOUBLE_TYPE)
</verb></tscreen>
  This function would be used in an interpreter script via a statement
  such as
<tscreen><verb>
      variable xmin = vmin (x0, x1, x2, x3, x4, 5);
</verb></tscreen>
  which computes the smallest of <tt>5</tt> 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
<tscreen><verb>
      variable xmin = vmin (x0, x1, x2, x3, x4);
</verb></tscreen>
  An intrinsic function can query the value of the variable
  <tt>SLang_Num_Function_Args</tt> to obtain the necessary information:
<tscreen><verb>
    double intrin_min (void)
    {
       double min_value, x;
       
       unsigned int num = SLang_Num_Function_Args;
       
       if (-1 == SLang_pop_double (&amp;min_value, NULL, NULL))
         return 0.0;
       num--;
       
       while (num &gt; 0)
         {
            num--;
            if (-1 == SLang_pop_double (&amp;x, NULL, NULL))
              return 0.0;
            if (x &lt; min_value) min_value = x;
         }
       return min_value;
    }
</verb></tscreen>
  This may be declared as an intrinsic using:
<tscreen><verb>
    MAKE_INTRINSIC_0("vmin", intrin_min, SLANG_DOUBLE_TYPE)    
</verb></tscreen>






<sect>Intrinsic Variables<p> 

  It is possible to access an application's global variables from
  within the interpreter.  The current implementation supports the
  access of variables of type <tt>int</tt>, <tt>char *</tt>, and
  <tt>double</tt>.

  There are two basic methods of making an intrinsic variable
  available to the interpreter.  The most straight forward method is
  to use the function <tt>SLadd_intrinsic_variable</tt>:
<tscreen><verb>
     int SLadd_intrinsic_variable (char *name, VOID_STAR addr, 
                                   unsigned char data_type, 
                                   int read_only);
</verb></tscreen>
  For example, suppose that <tt>I</tt> is an integer variable, e.g.,
<tscreen><verb>
     int I;
</verb></tscreen>
  One can make it known to the interpreter as <tt>I_Variable</tt> via a
  statement such as 
<tscreen><verb>
     if (-1 == SLadd_intrinsic_variable ("I_Variable", &amp;I, 
                                          SLANG_INT_TYPE, 0))
       exit (EXIT_FAILURE);
</verb></tscreen>
  Similarly, if <tt>S</tt> is declared as
<tscreen><verb>
    char *S;
</verb></tscreen>
  then 
<tscreen><verb>
     if (-1 == SLadd_intrinsic_variable ("S_Variable", &amp;S,
                                          SLANG_STRING_TYPE, 1))
       exit (EXIT_FAILURE);
</verb></tscreen>
  makes <tt>S</tt> available as a <em>read-only</em> variable with the name
  <tt>S_Variable</tt>.  Note that if a pointer variable is made available
  to the interpreter, its value is managed by the interpreter and
  not the application.  For this reason, it is recommended that such
  variables be declared as <em>read-only</em>.
  
  It is important to note that if <tt>S</tt> were declared as an array of
  characters, e.g.,
<tscreen><verb>
     char S[256];
</verb></tscreen>
  then it would not be possible to make it directly available to the
  interpreter.  However, one could create a pointer to it, i.e.,
<tscreen><verb>
     char *S_Ptr = S;
</verb></tscreen>
  and make <tt>S_Ptr</tt> 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:
<tscreen><verb>
     int do_not_try_this (void)
     {
        static char *names[3] = {"larry", "curly", "moe"};
        unsigned int i;

        for (i = 0; i &lt; 3; i++)
          {
             int value;
             if (-1 == SLadd_intrinsic_variable (names[i], (VOID_STAR) &amp;value,
                                                 SLANG_INT_TYPE, 1))
               return -1;
          }
        return 0;
     }
</verb></tscreen>
  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 <tt>SLang_Intrin_Var_Type</tt>
  objects and then add the array via <tt>SLadd_intrin_var_table</tt>.
  For example, the array
<tscreen><verb>
    static SLang_Intrin_Var_Type Intrin_Vars [] =
    {
       MAKE_VARIABLE("I_Variable", &amp;I, SLANG_INT_TYPE, 0),
       MAKE_VARIABLE("S_Variable", &amp;S_Ptr, SLANG_STRING_TYPE, 1),
       SLANG_END_TABLE
    };
</verb></tscreen>
  may be added via
<tscreen><verb>
    if (-1 == SLadd_intrin_var_table (Intrin_Vars, NULL))
      exit (EXIT_FAILURE);
</verb></tscreen>
  It should be rather obvious that the arguments to the
  <tt>MAKE_VARIABLE</tt> macro correspond to the parameters of the
  <tt>SLadd_intrinsic_variable</tt> 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<p> 
 An aggregate data object is an object that can contain more than one
 data value.  The <bf>S-Lang</bf> interpreter supports several such objects:
 arrays, structure, and associative arrays.  In the following
 sections, information about interacting with these objects is given.

<sect1>Arrays<p> 
 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:
<tscreen><verb>
   SLang_create_array
   SLang_pop_array_of_type
   SLang_push_array
   SLang_free_array
   SLang_get_array_element
   SLang_set_array_element
</verb></tscreen>
 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:
<tscreen><verb>
    void months_of_the_year (void)
    {
       static char *seasons[4] =
         {
            "Spring", "Summer", "Autumn", "Winter"
         };
       SLang_Array_Type *at;
       int i, four;
       
       four = 4;
       at = SLang_create_array (SLANG_STRING_TYPE, 0, NULL, &amp;four, 1);
       if (at == NULL)
         return;
       
       /* Now set the elements of the array */
       for (i = 0; i &lt; 4; i++)
         {
           if (-1 == SLang_set_array_element (at, &amp;i, &amp;seasons[i]))
             {
                SLang_free_array (at);
                return;
             }
         }
      
      (void) SLang_push_array (at, 0);
      SLang_free_array (at);
    }
</verb></tscreen>
 This example illustrates several points.  First of all, the
 <tt>SLang_create_array</tt> function was used to create a 1 dimensional
 array of 4 strings.  Since this function could fail, its return value
 was checked.  Then the <tt>SLang_set_array_element</tt> 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,
<tscreen><verb>
    SLang_set_array_element (at, &amp;i, seasons[i])
</verb></tscreen>
 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 <tt>1</tt>.  When it was pushed, the reference
 count was bumped up to <tt>2</tt>.  Then since it was nolonger needed by
 the function, <tt>SLang_free_array</tt> was called to decrement the
 reference count back to <tt>1</tt>.  For convenience, the second
 argument to <tt>SLang_push_array</tt> determines whether or not it is to
 also free the array.  So, instead of the two function calls:
<tscreen><verb>
   (void) SLang_push_array (at, 0);
   SLang_free_array (at);
</verb></tscreen>
 it is preferable to combine them as
<tscreen><verb>
   (void) SLang_push_array (at, 1);
</verb></tscreen>

 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:
<tscreen><verb>
   void make_diagonal_array (int n)
   {
      SLang_Array_Type *at;
      int dims[2];
      int 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 &lt; n; i++)
        {
           dims[0] = dims[1] = i;
           if (-1 == SLang_set_array_element (at, dims, &amp;one))
             {
                SLang_free_array (at);
                return;
             }
        }
      
      (void) SLang_push_array (at, 1);
   }
</verb></tscreen>
  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:
<tscreen><verb>
   double compute_trace (void)
   {
      SLang_Array_Type *at;
      double trace;
      int dims[2];

      if (-1 == SLang_pop_array_of_type (&amp;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-&gt;num_dims == 1) &amp;&amp; (at-&gt;dims[0] == 1))
          || ((at-&gt;num_dims == 2) &amp;&amp; (at-&gt;dims[0] == at-&gt;dims[1])))
        {
           double dtrace;
           int n = at-&gt;dims[0];

           for (i = 0; i &lt; n; i++)
             {
                dims[0] = dims[1] = i;
                (void) SLang_get_array_element (at, &amp;dims, &amp;dtrace);
                trace += dtrace;
             }
        }
     else SLang_verror (SL_TYPE_MISMATCH, "Expecting a square matrix");
     
     SLang_free_array (at);
     return trace;
   } 
</verb></tscreen>
 In this example, <tt>SLang_pop_array_of_type</tt> 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<p> 

 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 <bf>S-Lang</bf> interpreter structures.

<sect2>Interpreter Structures<p>

 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:
<tscreen><verb>
    int push_struct_example (char *string_value, int int_value)
    {
       char *field_names[2];
       unsigned char field_types[2];
       VOID_STAR field_values[2];
       
       field_names[0] = "string_field";
       field_types[0] = SLANG_STRING_TYPE;
       field_values[0] = &amp;string_value;
       
       field_names[1] = "int_field";
       field_types[1] = SLANG_INT_TYPE;
       field_values[1] = &amp;int_value;
       
       if (-1 == SLstruct_create_struct (2, field_names, 
                                            field_types, field_values))
         return -1;
       return 0;
    }
</verb></tscreen>
 Here, <tt>SLstruct_create_struct</tt> 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
<tscreen><verb>
    typedef struct 
    {
       char *s;
       int i;
    }
    SI_Type;
</verb></tscreen>
 Its layout may be specified via a table of
 <tt>SLang_CStruct_Field_Type</tt> entries:
<tscreen><verb>
    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
    };
</verb></tscreen>
   Here, MAKE_CSTRUCT_FIELD is a macro taking 5 arguments:
<tscreen><verb>
    MAKE_CSTRUCT_FIELD(C-structure-type, 
                       C-field-name, 
                       slang-field-name,
                       slang-data-type, 
                       is-read-only)
</verb></tscreen>
   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 <bf>S-Lang</bf> 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
   <bf>S-Lang</bf> version of the structure is trival:
<tscreen><verb>
    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)&amp;si, SI_Type_Layout);
    }
</verb></tscreen>
   
   This mechanism of structure creation also permits a <bf>S-Lang</bf>
   structure to be passed to an intrinsic function through the use of
   the SLang_pop_cstruct routine, e.g.,
<tscreen><verb>
     void print_si_struct (void)
     {
        SI_Type si;
        if (-1 == SLang_pop_cstruct ((VOID_STAR)&amp;si, SI_Type_Layout))
          return;
        printf ("si.i=%d", si.i);
        printf ("si.s=%s", si.s);
        SLang_free_cstruct ((VOID_STAR)&amp;si, SI_Type_Layout);
     }
</verb></tscreen>
   Assuming <tt>print_si_struct</tt> exists as an intrinsic function,
   the <bf>S-Lang</bf> code
<tscreen><verb>
     variable s = struct {string_field, int_field};
     s.string_field = "hello";
     s.int_field = 20;
     print_si_struct (s);
</verb></tscreen>
   would result in the display of
<tscreen><verb>
     si.i=20;
     si.s=hello
</verb></tscreen>
   Note that the <tt>SLang_free_cstruct</tt> function was called after
   the contents of <tt>si</tt> were nolonger needed.  This was necessary
   because <tt>SLang_pop_cstruct</tt> allocated memory to set the
   <tt>char *s</tt> field of <tt>si</tt>.  Calling
   <tt>SLang_free_cstruct</tt> frees up such memory.

   Now consider the following:
<tscreen><verb>
    typedef struct
    {
       pid_t pid;
       gid_t group;
    }
    X_t;
</verb></tscreen>
  How should the layout of this structure be defined?  One might be
  tempted to use:
<tscreen><verb>
    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
    };
</verb></tscreen>
  However, this assumes <tt>pid_t</tt> and <tt>gid_t</tt> have been
  typedefed as ints.  But what if <tt>gid_t</tt> is a <tt>short</tt>?  In
  such a case, using
<tscreen><verb>
      MAKE_CSTRUCT_FIELD(X_t, group, "group", SLANG_SHORT_TYPE, 0),
</verb></tscreen>
  would be the appropriate entry for the <tt>group</tt> field.  Of
  course, one has no way of knowing how <tt>gid_t</tt> is declared on
  other systems.  For this reason, it is preferable to use the
  <tt>MAKE_CSTRUCT_INT_FIELD</tt> macro in cases involving integer valued
  fields, e.g.,
<tscreen><verb>
    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
    };
</verb></tscreen>

 Before leaving this section, it is important to mention that that
 access to character array fields is not permitted via this 
 interface.  That is, a structure such as
<tscreen><verb>
     typedef struct
     {
        char name[32];
     }
     Name_Type;
</verb></tscreen>
 is not supported since <tt>char name[32]</tt> is not a
 <tt>SLANG_STRING_TYPE</tt> object.  Always keep in mind that a
 <tt>SLANG_STRING_TYPE</tt> object is a <tt>char *</tt>.  

<sect2>Intrinsic Structures<p>
 
 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
<tscreen><verb>
    typedef struct _Window_Type
    {
       char *title;
       int row;
       int col;
       int width;
       int height;
    } Window_Type;
</verb></tscreen>
 which defines a window object with a title, size (<tt>width</tt>,
 <tt>height</tt>), and location (<tt>row</tt>, <tt>col</tt>).

 We can make variables of type <tt>Window_Type</tt> available to the
 interpreter via a table as follows:
<tscreen><verb>
   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
   };
</verb></tscreen>
 More precisely, this defines the layout of the <tt>Window_Type</tt> structure.
 Here, the <tt>title</tt> has been declared as a read-only field.  Using
<tscreen><verb>
     MAKE_ISTRUCT_FIELD(Window_Type, title, "title", SLANG_STRING_TYPE, 0),
</verb></tscreen>
 would allow read-write access.

 Now suppose that <tt>My_Window</tt> is a pointer to a <tt>Window_Type</tt>
 object, i.e.,
<tscreen><verb>
    Window_Type *My_Window;
</verb></tscreen>
 We can make this variable available to the interpreter via the
 <tt>SLadd_istruct_table</tt> function:
<tscreen><verb>
    if (-1 == SLadd_istruct_table (Window_Type_Field_Table,
                                   (VOID_STAR) &amp;My_Window,
                                   "My_Win"))
      exit (1);
</verb></tscreen>
 This creates a S-Lang interpreter variable called <tt>My_Win</tt> whose value
 corresponds to to the <tt>My_Win</tt> structure.  This would permit one to
 access the fields of <tt>My_Window</tt> via <bf>S-Lang</bf> statements such as
<tscreen><verb>
     define set_width_and_height (w,h)
     {
         My_Win.width = w;
         My_Win.height = h;
     }
</verb></tscreen>

 It is extremely important to understand that the interface described in
 this section does not allow the interpreter to create new instances of
 <tt>Window_Type</tt> objects.  The interface merely defines an association or
 correspondence between an intrinsic structure pointer and a <bf>S-Lang</bf>
 variable.  For example, if the value of <tt>My_Window</tt> is <tt>NULL</tt>, then
 <tt>My_Win</tt> would also be <tt>NULL</tt>.

 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 <tt>SLang_create_slstring</tt> and <tt>SLang_free_slstring</tt>
 functions to set the character string field of the structure. 
 







<chapt>Keyboard Interface<p> 



  <bf>S-Lang</bf>'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 (<tt>SLkp</tt>) which utilize <bf>S-Lang</bf>'s keymap facility
  for reading multi-character sequences.

  To initialize the interface, one must first call the function
  <tt>SLang_init_tty</tt>. Before exiting the program, the function
  <tt>SLang_reset_tty</tt> must be called to restore the keyboard
  interface to its original state.  Once initialized, the low-level
  <tt>SLang_getkey</tt> function may be used to read <em>simgle</em>
  keyboard characters from the terminal.  An application using the the
  higher-level <tt>SLkp</tt> interface will read charcters using the
  <tt>SLkp_getkey</tt> 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<p> 

  The function <tt>SLang_init_tty</tt> 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:
<tscreen><verb>
      int SLang_init_tty (int abort_char, int flow_ctrl, int opost);
</verb></tscreen>
  It takes three parameters that are used to specify how the terminal is to
  be initialized.

  The first parameter, <tt>abort_char</tt>, is used to specify the interrupt
  character (<tt>SIGINT</tt>).  Under MSDOS, this value corresponds to the scan
  code of the character that will be used to generate the interrupt.  For
  example, under MSDOS, <tt>34</tt> should be used to make <tt>Ctrl-G</tt> generate an
  interrupt signal since 34 is the scan code for <tt>G</tt>.  On other
  systems, the value of <tt>abort_char</tt> will simply be the ascii value of
  the control character that will be used to generate the interrupt signal,
  e.g., <tt>7</tt> for <tt>Ctrl-G</tt>.  If <tt>-1</tt> is passed, the interrupt
  character will not be changed.

  Pressing the interrupt character specified by the first argument will
  generate a signal (<tt>SIGINT</tt>) that may or not be caught by the
  application.  It is up to the application to catch this signal.  <bf>S-Lang</bf>
  provides the function <tt>Slang_set_abort_signal</tt> 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., <tt>Ctrl-S</tt> and <tt>Ctrl-Q</tt>).
  For some systems such as MSDOS, this parameter is meaningless.
  
  The third parameter, <tt>opost</tt>, is used to turn output processing on or
  off.  If <tt>opost</tt> is zero, output processing is <em>not</em> turned on
  otherwise, output processing is turned on.

  The <tt>SLang_init_tty</tt> function returns -1 upon failure.  In addition,
  after it returns, the <bf>S-Lang</bf> global variable <tt>SLang_TT_Baud_Rate</tt>
  will be set to the baud rate of the terminal if this value can be
  determined.

  Example:
<tscreen><verb>
      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);
</verb></tscreen>
   Here the terminal is initialized such that flow control and output
   processing are turned off.  In addition, the character
   <tt>Ctrl-G</tt><footnote>For MSDOS systems, use the <em>scan code</em> 34
   instead of 7 for <tt>Ctrl-G</tt></footnote> has been specified to be the interrupt
   character.  The function <tt>SLang_set_abort_signal</tt> is used to
   install the default <bf>S-Lang</bf> interrupt signal handler.



<sect>Resetting the Keyboard Interface<p> 

  The function <tt>SLang_reset_tty</tt> must be called to reset the terminal
  to the state it was in before the call to <tt>SLang_init_tty</tt>.  The
  prototype for this function is:
<tscreen><verb>
      void SLang_reset_tty (void);
</verb></tscreen>
  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 <tt>SLkp</tt> Routines<p> 

  Extra initialization of the higher-level <tt>SLkp</tt> functions are
  required because they are layered on top of the lower level
  routines.  Since the <tt>SLkp_getkey</tt> function is able to process
  function and arrow keys in a terminal independent manner, it is
  necessary to call the <tt>SLtt_get_terminfo</tt> function to get
  information about the escape character sequences that the terminal's
  function keys send.  Once that information is available, the
  <tt>SLkp_init</tt> 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:

<tscreen><verb>
      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);
        }
</verb></tscreen>

  It is important to check the return status of the <tt>SLkp_init</tt>
  function which can failed if it cannot allocate enough memory for
  the keymap.
 


<sect>Setting the Interrupt Handler<p> 

  The function <tt>SLang_set_abort_signal</tt> may be used to associate an
  interrupt handler with the interrupt character that was previously
  specified by the <tt>SLang_init_tty</tt> function call.  The prototype for
  this function is:
<tscreen><verb>
      void SLang_set_abort_signal (void (*)(int));
</verb></tscreen>
  This function returns nothing and takes a single parameter which is a
  pointer to a function taking an integer value and returning
  <tt>void</tt>.  If a <tt>NULL</tt> pointer is passed, the default <bf>S-Lang</bf>
  interrupt handler will be used. The <bf>S-Lang</bf> default interrupt handler
  under Unix looks like:
<tscreen><verb>
      static void default_sigint (int sig)
      {
        SLsignal_intr (SIGINT, default_sigint);
        SLKeyBoard_Quit = 1;
        if (SLang_Ignore_User_Abort == 0) SLang_Error = USER_BREAK;
      }
</verb></tscreen>
  It simply sets the global variable <tt>SLKeyBoard_Quit</tt> to one and
  if the variable <tt>SLang_Ignore_User_Abort</tt> is non-zero,
  <tt>SLang_Error</tt> is set to indicate a user break condition.  (The
  function <tt>SLsignal_intr</tt> is similar to the standard C
  <tt>signal</tt> function <em>except that it will interrupt system
  calls</em>.  Some may not like this behavior and may wish to call
  this <tt>SLang_set_abort_signal</tt> 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
  <tt>int 9h</tt> is hooked).



<sect>Reading Keyboard Input with SLang_getkey<p> 

  After initializing the keyboard via <tt>SLang_init_tty</tt>,
  the <bf>S-Lang</bf> function <tt>SLang_getkey</tt> may be used to read
  characters from the terminal interface.  In addition, the function
  <tt>SLang_input_pending</tt> may be used to determine whether or not
  keyboard input is available to be read.

  These functions have prototypes:
<tscreen><verb>
      unsigned int SLang_getkey (void);
      int SLang_input_pending (int tsecs);
</verb></tscreen>
  The <tt>SLang_getkey</tt> function returns a single character from the
  terminal.  Upon failure, it returns <tt>0xFFFF</tt>.  If the interrupt
  character specified by the <tt>SLang_init_tty</tt> function is pressed
  while this function is called, the function will return the value of the
  interrupt character and set the <bf>S-Lang</bf> global variable
  <tt>SLKeyBoard_Quit</tt> to a non-zero value.  In addition, if the default
  <bf>S-Lang</bf> interrupt handler has been specified by a <tt>NULL</tt> argument to
  the <tt>SLang_set_abort_signal</tt> function, the global variable
  <tt>SLang_Error</tt> will be set to <tt>USER_BREAK</tt> <em>unless</em> the
  variable <tt>SLang_Ignore_User_Abort</tt> is non-zero.

  The <tt>SLang_getkey</tt> function waits until input is available to be
  read.  The <tt>SLang_input_pending</tt> 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</tt>.  Passing a value of zero causes the function
  to return right away.  <tt>SLang_input_pending</tt> 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 <tt>Ctrl-G</tt> or until 5 seconds have gone by with no input:
<tscreen><verb>
      #include &lt;stdio.h&gt;
      #include "slang.h"
      int main ()
      {
         int abort_char = 7;  /* For MSDOS, use 34 as scan code */
         unsigned int ch;
         
         if (-1 == SLang_init_tty (abort_char, 0, 1))
           {
              fprintf (stderr, "Unable to initialize the terminal.\n");
              exit (-1);
           }
         SLang_set_abort_signal (NULL);
         while (1)
           {
              fputs ("\nPress any key.  To quit, press Ctrl-G: ", stdout);
              fflush (stdout);
              if (SLang_input_pending (50) == 0)  /* 50/10 seconds */
                {
                   fputs ("Waited too long! Bye\n", stdout);
                   break;
                }
              
              ch = SLang_getkey ();
              if (SLang_Error == USER_BREAK)
                {
                   fputs ("Ctrl-G pressed!  Bye\n", stdout);
                   break;
                }
              putc ((int) ch, stdout);
           }
         SLang_reset_tty ();
         return 0;
      }
</verb></tscreen>




<sect>Reading Keyboard Input with SLkp_getkey<p> 

  Unlike the low-level function <tt>SLang_getkey</tt>, the
  <tt>SLkp_getkey</tt> function can read a multi-character sequence
  associated with function keys.  The <tt>SLkp_getkey</tt> function uses
  <tt>SLang_getkey</tt> and <bf>S-Lang</bf>'s keymap facility to process escape
  sequences.  It returns a single integer which describes the key that
  was pressed:
<tscreen><verb>
      int SLkp_getkey (void);
</verb></tscreen>
  That is, the <tt>SLkp_getkey</tt> function simple provides a mapping
  between keys and integers.  In this context the integers are called
  <em>keysyms</em>.
  
  For single character input such as generated by the <tt>a</tt> key on
  the keyboard, the function returns the character that was generated,
  e.g., <tt>'a'</tt>.  For single characters, <tt>SLkp_getkey</tt> will
  always return an keysym whose value ranges from 0 to 256. For
  keys that generate multiple character sequences, e.g., a function or
  arrow key, the function returns an keysym whose value is greater
  that 256.  The actual values of these keysyms are represented as
  macros defined in the <tt>slang.h</tt> include file.  For example, the
  up arrow key corresponds to the keysym whose value is
  <tt>SL_KEY_UP</tt>. 
  
  Since it is possible for the user to enter a character sequence that
  does not correspond to any key.  If this happens, the special keysym
  <tt>SL_KEY_ERR</tt> will be returned.
  
  Here is an example of how <tt>SLkp_getkey</tt> may be used by a file
  viewer:
<tscreen><verb>
      switch (SLkp_getkey ())
        {
           case ' ':
           case SL_KEY_NPAGE:
              next_page ();
              break;
           case 'b':
           case SL_KEY_PPAGE:
              previous_page ();
              break;
           case '\r':
           case SL_KEY_DOWN:
              next_line ();
              break;
               .
               .
           case SL_KEY_ERR:
           default:
              SLtt_beep ();
        }
</verb></tscreen>
   
   Unlike its lower-level counterpart, <tt>SLang_getkey</tt>, there do
   not yet exist any functions in the library that are capable of
   ``ungetting'' keysyms.  In particular, the <tt>SLang_ungetkey</tt>
   function will not work.
   


<sect>Buffering Input<p> 

  <bf>S-Lang</bf> has several functions pushing characters back onto the
  input stream to be read again later by <tt>SLang_getkey</tt>.  It
  should be noted that none of the above functions are designed to
  push back keysyms read by the <tt>SLkp_getkey</tt> function.  These
  functions are declared as follows:
<tscreen><verb>
      void SLang_ungetkey (unsigned char ch);
      void SLang_ungetkey_string (unsigned char *buf, int buflen);
      void SLang_buffer_keystring (unsigned char *buf, int buflen);
</verb></tscreen>

  <tt>SLang_ungetkey</tt> is the most simple of the three functions.  It takes
  a single character a pushes it back on to the input stream.  The next call to
  <tt>SLang_getkey</tt> will return this character.  This function may be used
  to <em>peek</em> at the character to be read by first reading it and then
  putting it back.

  <tt>SLang_ungetkey_string</tt> has the same function as
  <tt>SLang_ungetkey</tt> except that it is able to push more than one
  character back onto the input stream.  Since this function can push back
  null (ascii 0) characters, the number of characters to push is required as
  one of the parameters.

  The last of these three functions, <tt>SLang_buffer_keystring</tt> can
  handle more than one charater but unlike the other two, it places the
  characters at the <em>end</em> of the keyboard buffer instead of at the
  beginning.

  Note that the use of each of these three functions will cause
  <tt>SLang_input_pending</tt> to return right away with a non-zero value.

  Finally, the <bf>S-Lang</bf> keyboard interface includes the function
  <tt>SLang_flush_input</tt> with prototype
<tscreen><verb>
      void SLang_flush_input (void);
</verb></tscreen>
  It may be used to discard <em>all</em> input.
  
  Here is a simple example that looks to see what the next key to be read is
  if one is available:
<tscreen><verb>
      int peek_key ()
      {
         int ch;
         if (SLang_input_pending (0) == 0) return -1;
         ch = SLang_getkey ();
         SLang_ungetkey (ch);
         return ch;
      }
</verb></tscreen>




<sect>Global Variables<p> 
  Although the following <bf>S-Lang</bf> global variables have already been
  mentioned earlier, they are gathered together here for completeness.
  
  <tt>int SLang_Ignore_User_Abort;</tt>
  If non-zero, pressing the interrupt character will not result in
  <tt>SLang_Error</tt> being set to <tt>USER_BREAK</tt>.

  <tt>volatile int SLKeyBoard_Quit;</tt>
  This variable is set to a non-zero value when the interrupt
  character is pressed. If the interrupt character is pressed when
  <tt>SLang_getkey</tt> is called, the interrupt character will be
  returned from <tt>SLang_getkey</tt>.

  <tt>int SLang_TT_Baud_Rate;</tt> 
  On systems which support it, this variable is set to the value of the
  terminal's baud rate after the call to <tt>SLang_init_tty</tt>.





<chapt>Screen Management<p> 

  The <bf>S-Lang</bf> library provides two interfaces to terminal independent
  routines for manipulating the display on a terminal.  The highest level
  interface, known as the <tt>SLsmg</tt> interface is discussed in this
  section.  It provides high level screen management functions more
  manipulating the display in an optimal manner and is similar in spirit to
  the <tt>curses</tt> library.  The lowest level interface, or the
  <tt>SLtt</tt>
  interface, is used by the <tt>SLsmg</tt> routines to actually perform the
  task of writing to the display.  This interface is discussed in another
  section.  Like the keyboard routines, the <tt>SLsmg</tt> routines are
  <em>platform independent</em> and work the same on MSDOS, OS/2, Unix, and VMS.

  The screen management, or <tt>SLsmg</tt>, routines are initialized by
  function <tt>SLsmg_init_smg</tt>.  Once initialized, the application uses
  various <tt>SLsmg</tt> functions to write to a <em>virtual</em> display.  This does
  not cause the <em>physical</em> terminal display to be updated immediately.  
  The physical display is updated to look like the virtual display only
  after a call to the function <tt>SLsmg_refresh</tt>.  Before exiting, the
  application using these routines is required to call
  <tt>SLsmg_reset_smg</tt> to reset the display system.
  
  The following subsections explore <bf>S-Lang</bf>'s screen management system in
  greater detail.
  
<sect>Initialization<p>

  The function <tt>SLsmg_init_smg</tt> must be called before any other
  <tt>SLsmg</tt> function can be used.  It has the simple prototype:
<tscreen><verb>
      int SLsmg_init_smg (void);
</verb></tscreen>
  It returns zero if successful or -1 if it cannot allocate space for
  the virtual display.

  For this routine to properly initialize the virtual display, the
  capabilities of the terminal must be known as well as the size of
  the <em>physical</em> display.  For these reasons, the lower level <tt>SLtt</tt> routines
  come into play.  In particular, before the first call to
  <tt>SLsmg_init_smg</tt>, the application is required to call the function
  <tt>SLtt_get_terminfo</tt> before calling <tt>SLsmg_init_smg</tt>.

  The <tt>SLtt_get_terminfo</tt> function sets the global variables
  <tt>SLtt_Screen_Rows</tt> and <tt>SLtt_Screen_Cols</tt> to the values
  appropriate for the terminal.  It does this by calling the
  <tt>SLtt_get_screen_size</tt> function to query the terminal driver
  for the appropriate values for these variables.  From this point on,
  it is up to the application to maintain the correct values for these
  variables by calling the <tt>SLtt_get_screen_size</tt> function
  whenever the display size changes, e.g., in response to a
  <tt>SIGWINCH</tt> signal. Finally, if the application is going to read
  characters from the keyboard, it is also a good idea to initialize
  the keyboard routines at this point as well.

<sect>Resetting SLsmg<p>  

  Before the program exits or suspends, the function
  <tt>SLsmg_reset_tty</tt>
  should be called to shutdown the display system.  This function has the
  prototype
<tscreen><verb>
      void SLsmg_reset_smg (void);
</verb></tscreen>
  This will deallocate any memory allocated for the virtual screen and
  reset the terminal's display.
  
  Basically, a program that uses the <tt>SLsmg</tt> screen management functions
  and <bf>S-Lang</bf>'s keyboard interface will look something like:
<tscreen><verb>
      #include "slang.h"
      int main ()
      {
         SLtt_get_terminfo ();
         SLang_init_tty (-1, 0, 0);
         SLsmg_init_smg ();
         
         /* do stuff .... */
    
         SLsmg_reset_smg ();
         SLang_reset_tty ();
         return 0;
      }
</verb></tscreen>
  If this program is compiled and run, all it will do is clear the screen
  and position the cursor at the bottom of the display.  In the following
  sections, other <tt>SLsmg</tt> functions will be introduced which may be used
  to make this simple program do much more.

<sect>Handling Screen Resize Events<p>
  The function <tt>SLsmg_reinit_smg</tt> is designed to be used in
  conjunction with resize events.

  Under Unix-like operating systems, when the size of the display
  changes, the application will be sent a <tt>SIGWINCH</tt> signal.  To
  properly handle this signal, the <tt>SLsmg</tt> routines must be
  reinitialized to use the new display size.  This may be accomplished
  by calling <tt>SLtt_get_screen_size</tt> to get the new size, followed by
  <tt>SLsmg_reinit_smg</tt> to reinitialize the <tt>SLsmg</tt> interface
  to use the new size.  Keep in mind that these routines should
  not be called from within the signal handler.  The following code
  illustrates the main ideas involved in handling such events:
<tscreen><verb>
     static volatile int Screen_Size_Changed;
     static sigwinch_handler (int sig)
     {
        Screen_Size_Changed = 1;
        SLsignal (SIGWINCH, sigwinch_handler);
     }
     
     int main (int argc, char **argv)
     {
        SLsignal (SIGWINCH, sigwinch_handler);
        SLsmg_init_smg ();
          .
          .
        /* Now enter main loop */
        while (not_done)
          {
             if (Screen_Size_Changed)
               {
                  SLtt_get_screen_size ();
                  SLsmg_reinit_smg ();
                  redraw_display ();
               }
             .
             .
          }
       return 0;
     }
</verb></tscreen>
  

<sect>SLsmg Functions<p> 

  In the previous sections, functions for initializing and shutting down the
  <tt>SLsmg</tt> routines were discussed.  In this section, the rest of the
  <tt>SLsmg</tt> functions are presented.  These functions act only on the 
  <em>virtual</em> display.  The <em>physical</em> display is updated when the
  <tt>SLsmg_refresh</tt> function is called and <em>not until that time</em>.
  This function has the simple prototype:
<tscreen><verb>
     void SLsmg_refresh (void);
</verb></tscreen>
  
<sect1>Positioning the cursor<p>

  The <tt>SLsmg_gotorc</tt> function is used to position the cursor at a given
  row and column.  The prototype for this function is:
<tscreen><verb>
      void SLsmg_gotorc (int row, int col);
</verb></tscreen>
  The origin of the screen is at the top left corner and is given the
  coordinate (0, 0), i.e., the top row of the screen corresponds to
  <tt>row = 0</tt> and the first column corresponds to <tt>col = 0</tt>.  The last
  row of the screen is given by <tt>row = SLtt_Screen_Rows - 1</tt>.
  
  It is possible to change the origin of the coordinate system by using the
  function <tt>SLsmg_set_screen_start</tt> with prototype:
<tscreen><verb>
     void SLsmg_set_screen_start (int *r, int *c);
</verb></tscreen>
  This function takes pointers to the new values of the first row and first
  column.  It returns the previous values by modifying the values of the
  integers at the addresses specified by the parameter list.  A
  <tt>NULL</tt>
  pointer may be passed to indicate that the origin is to be set to its
  initial value of 0.  For example,
<tscreen><verb>
      int r = 10;
      SLsmg_set_screen_start (&amp;r, NULL);
</verb></tscreen>
  sets the origin to (10, 0) and after the function returns, the variable
  <tt>r</tt> will have the value of the previous row origin.

<sect1>Writing to the Display<p>
  
  <tt>SLsmg</tt> has several routines for outputting text to the virtual
  display.  The following points should be understood:
<itemize>   
<item> The text is output at the position of the cursor of the virtual
      display and the cursor is advanced to the position that corresponds to
      the end of the text.
      
<item> Text does <em>not</em> wrap at the boundary of the
      display--- it is trucated.  This behavior seems to be more useful in
      practice since most programs that would use screen management tend to
      be line oriented.
      
<item> Control characters are displayed in a two character sequence
      representation with <tt>^</tt> as the first character.  That is,
      <tt>Ctrl-X</tt> is output as <tt>^X</tt>.
      
<item> The newline character does <em>not</em> cause the cursor to advance to
      the next row.  Instead, when a newline character is encountered when
      outputting text, the output routine will return.  That is, outputting
      a string containing a newline character will only display the contents
      of the string up to the newline character.
</itemize> 

  Although the some of the above items might appear to be too restrictive, in
  practice this is not seem to be the case.  In fact, the design of the
  output routines was influenced by their actual use and modified to
  simplify the code of the application utilizing them.

  <tt>void SLsmg_write_char (char ch);</tt>
  Write a single character to the virtual display.
  
  <tt>void SLsmg_write_nchars (char *str, int len);</tt>
  Write <tt>len</tt> characters pointed to by <tt>str</tt> to the virtual display. 

  <tt>void SLsmg_write_string (char *str);</tt> 
  Write the null terminated string given by pointer <tt>str</tt> to the virtual
  display.  This function is a wrapper around <tt>SLsmg_write_nchars</tt>.

  <tt>void SLsmg_write_nstring (char *str, int n);</tt>
  Write the null terminated string given by pointer <tt>str</tt> to the virtual
  display.  At most, only <tt>n</tt> characters are written.  If the length of
  the string is less than <tt>n</tt>, then the string will be padded with blanks.
  This function is a wrapper around <tt>SLsmg_write_nchars</tt>.
  
  <tt>void SLsmg_printf (char *fmt, ...);</tt>
  This function is similar to <tt>printf</tt> except that it writes to the
  <tt>SLsmg</tt> virtual display.
  
  <tt>void SLsmg_vprintf (char *, va_list);</tt>
  Like <tt>SLsmg_printf</tt> but uses a variable argument list.

<sect1>Erasing the Display<p>

  The following functions may be used to fill portions of the display with
  blank characters.  The attributes of blank character are the current
  attributes.  (See below for a discussion of character attributes)
  
  <tt>void SLsmg_erase_eol (void);</tt>
  Erase line from current position to the end of the line.
  
  <tt>void SLsmg_erase_eos (void);</tt>
  Erase from the current position to the end of the screen.

  <tt>void SLsmg_cls (void);</tt>
  Clear the entire virtual display.

<sect1>Setting Character Attributes<p>

  Character attributes define the visual characteristics the character 
  possesses when it is displayed.  Visual characteristics include the
  foreground and background colors as well as other attributes such as
  blinking, bold, and so on.  Since <tt>SLsmg</tt> takes a different approach
  to this problem than other screen management libraries an explanation of
  this approach is given here.  This approach has been motivated by
  experience with programs that require some sort of screen management.

  Most programs that use <tt>SLsmg</tt> are composed of specific textual
  objects or objects made up of line drawing characters. For example,
  consider an application with a menu bar with drop down menus.  The menus
  might be enclosed by some sort of frame or perhaps a shadow.  The basic
  idea is to associate an integer to each of the objects (e.g., menu bar,
  shadow, current menu item, etc.) and create a mapping from the integer to
  the set of attributes.  In the terminology of <tt>SLsmg</tt>, the integer is
  simply called an <em>object</em>.

  For example, the menu bar might be associated with the object <tt>1</tt>, the
  drop down menu could be object <tt>2</tt>, the shadow could be object
  <tt>3</tt>,
  and so on.

  The range of values for the object integer is restricted from 0 up to
  and including 255 on all systems except MSDOS where the maximum allowed
  integer is 15<footnote>This difference is due to memory constraints
  imposed by MSDOS.  This restriction might be removed in a future version of
  the library.</footnote>. The object numbered zero should not be regarding as an
  object at all.  Rather it should be regarded as all <em>other</em> objects
  that have not explicitly been given an object number.  <tt>SLsmg</tt>, or
  more precisely <tt>SLtt</tt>, refers to the attributes of this special object
  as the <em>default</em> or <em>normal</em> attributes.

  The <tt>SLsmg</tt> routines know nothing about the mapping of the color to the
  attributes associated with the color.  The actual mapping takes place at a
  lower level in the <tt>SLtt</tt> routines.  Hence, to map an object to the
  actual set of attributes requires a call to any of the following
  <tt>SLtt</tt>
  routines:
<tscreen><verb>
     void SLtt_set_color (int obj, char *name, char *fg, char *bg);
     void SLtt_set_color_object (int obj, SLtt_Char_Type attr);
     void SLtt_set_mono (int obj, char *, SLtt_Char_Type attr);
</verb></tscreen>
  Only the first of these routines will be discussed briefly here.  The
  latter two functions allow more fine control over the object to attribute
  mapping (such as assigning a ``blink'' attribute to the object).  For a
  more full explanation on all of these routines see the section about the
  <tt>SLtt</tt> interface.

  The <tt>SLtt_set_color</tt> function takes four parameters.  The first
  parameter, <tt>obj</tt>, is simply the integer of the object for which
  attributes are to be assigned.  The second parameter is currently
  unused by these routines.  The third and forth parameters, <tt>fg</tt>
  and <tt>bg</tt>, are the names of the foreground and background color
  to be used associated with the object.  The strings that one can use
  for the third and fourth parameters can be any one of the 16 colors:
<tscreen><verb>
     "black"                "gray"
     "red"                  "brightred"
     "green"                "brightgreen"
     "brown"                "yellow"
     "blue"                 "brightblue"
     "magenta"              "brightmagenta"
     "cyan"                 "brightcyan"
     "lightgray"            "white"
</verb></tscreen>
  The value of the foreground parameter <tt>fg</tt> can be anyone of these
  sixteen colors.   However, on most terminals, the background color will
  can only be one of the colors listed in the first column<footnote>This is
  also true on the Linux console.  However, it need not be the case and
  hopefully the designers of Linux will someday remove this restriction.</footnote>.

  Of course not all terminals are color terminals.  If the <bf>S-Lang</bf> global
  variable <tt>SLtt_Use_Ansi_Colors</tt> is non-zero, the terminal is
  assumed to be a color terminal.  The <tt>SLtt_get_terminfo</tt> will
  try to determine whether or not the terminal supports colors and set
  this variable accordingly.  It does this by looking for the
  capability in the terminfo/termcap database.  Unfortunately many Unix
  databases lack this information and so the <tt>SLtt_get_terminfo</tt>
  routine will check whether or not the environment variable
  <tt>COLORTERM</tt> exists.  If it exists, the terminal will be assumed
  to support ANSI colors and <tt>SLtt_Use_Ansi_Colors</tt> will be set to one.
  Nevertheless, the application should provide some other mechanism to set
  this variable, e.g., via a command line parameter.

  When the <tt>SLtt_Use_Ansi_Colors</tt> variable is zero, all objects
  with numbers greater than one will be displayed in inverse
  video<footnote>This behavior can be modified by using the
  <tt>SLtt_set_mono</tt> function call.</footnote>.

  With this background, the <tt>SLsmg</tt> functions for setting the character
  attributes can now be defined.  These functions simply set the object
  attributes that are to be assigned to <em>subsequent</em> characters written
  to the virtual display.  For this reason, the new attribute is called the
  <em>current</em> attribute.

  <tt>void SLsmg_set_color (int obj);</tt>
  Set the current attribute to those of object <tt>obj</tt>.
  
  <tt>void SLsmg_normal_video (void);</tt>
  This function is equivalent to <tt>SLsmg_set_color (0)</tt>. 
  
  <tt>void SLsmg_reverse_video (void);</tt>
  This function is equivalent to <tt>SLsmg_set_color (1)</tt>.  On monochrome
  terminals, it is equivalent to setting the subsequent character attributes
  to inverse video.

  Unfortunately there does not seem to be a standard way for the
  application or, in particular, the library to determine which color
  will be used by the terminal for the default background.  Such
  information would be useful in initializing the foreground and
  background colors associated with the default color object (0).  FOr
  this reason, it is up to the application to provide some means for
  the user to indicate what these colors are for the particular
  terminal setup. To facilitate this, the <tt>SLtt_get_terminfo</tt>
  function checks for the existence of the <tt>COLORFGBG</tt>
  environment variable.  If this variable exists, its value will be
  used to initialize the colors associated with the default color
  object.  Specifically, the value is assumed to consist of a
  foreground color name and a background color name separated by a
  semicolon.  For example, if the value of <tt>COLORTERM</tt> is
  <tt>lightgray;blue</tt>, the default color object will be initialized
  to represent a <tt>lightgray</tt> foreground upon a <tt>blue</tt>
  background.

<sect1>Lines and Alternate Character Sets<p>
  The <bf>S-Lang</bf> screen management library also includes routines for turning
  on and turning off alternate character sets.  This is especially useful
  for drawing horizontal and vertical lines.
  
  <tt>void SLsmg_set_char_set (int flag);</tt>
  If <tt>flag</tt> is non-zero, subsequent write functions will use characters
  from the alternate character set.  If <tt>flag</tt> is zero, the default, or,
  ordinary character set will be used.
  
  <tt>void SLsmg_draw_hline (int len);</tt>
  Draw a horizontal line from the current position to the column that is
  <tt>len</tt> characters to the right.
  
  <tt>void SLsmg_draw_vline (int len);</tt>
  Draw a horizontal line from the current position to the row that is
  <tt>len</tt> rows below.
  
  <tt>void SLsmg_draw_box (int r, int c, int dr, int dc);</tt>
  Draw a box whose upper right corner is at row <tt>r</tt> and column
  <tt>c</tt>.
  The box spans <tt>dr</tt> rows and <tt>dc</tt> columns.  The current position
  will be left at row <tt>r</tt> and column <tt>c</tt>.
  
<sect1>Miscellaneous Functions<p>
 
  <tt>void SLsmg_touch_lines (int r, int n);</tt>
  Mark screen rows numbered <tt>r</tt>, <tt>r + 1</tt>, ... <tt>r +
  (n - 1)</tt> as
  modified.  When <tt>SLsmg_refresh</tt> is called, these rows will be
  completely redrawn.
  
  <tt>unsigned short SLsmg_char_at(void);</tt>
  Returns the character and its attributes object number at the current
  cursor position.  The character itself occupies the lower byte and the
  object attributes number forms the upper byte.  The object returned
  by this function call should not be written back out via any of the
  functions that write characters or character strings.




<sect>Variables<p> 

  The following <bf>S-Lang</bf> global variables are used by the <tt>SLsmg</tt>
  interface.  Some of these have been previously discussed.
  
  <tt>int SLtt_Screen_Rows;</tt>
  <tt>int SLtt_Screen_Cols;</tt>
  The number of rows and columns of the <em>physical</em> display.  If either of
  these numbers changes, the functions <tt>SLsmg_reset_smg</tt> and
  <tt>SLsmg_init_smg</tt> should be called again so that the <tt>SLsmg</tt>
  routines can re-adjust to the new size.
  
  <tt>int SLsmg_Tab_Width;</tt>
  Set this variable to the tab width that will be used when expanding tab
  characters.  The default is 8.
  
  <tt>int SLsmg_Display_Eight_Bit</tt>
  This variable determines how characters with the high bit set are to be
  output.  Specifically, a character with the high bit set with a value
  greater than or equal to this value is output as is; otherwise, it will be
  output in a 7-bit representation.  The default value for this variable is
  <tt>128</tt> for MSDOS and <tt>160</tt> for other systems (ISO-Latin).

  <tt>int SLtt_Use_Ansi_Colors;</tt>
  If this value is non-zero, the terminal is assumed to support ANSI colors
  otherwise it is assumed to be monochrome.  The default is 0.
  
  <tt>int SLtt_Term_Cannot_Scroll;</tt>
  If this value is zero, the <tt>SLsmg</tt> will attempt to scroll the physical
  display to optimize the update.  If it is non-zero, the screen management
  routines will not perform this optimization.  For some applications, this
  variable should be set to zero.  The default value is set by the
  <tt>SLtt_get_terminfo</tt> function.
  


<sect>Hints for using SLsmg<p>

  This section discusses some general design issues that one must face when
  writing an application that requires some sort of screen management.



<chapt>Signal Functions<p> 

 Almost all non-trivial programs must worry about signals.  This is
 especially true for programs that use the <bf>S-Lang</bf> terminal
 input/output and screen management routines.  Unfortunately, there is
 no fixed way to handle signals; otherwise, the Unix kernel would take
 care of all issues regarding signals and the application programmer
 would never have to worry about them.  For this reason, none of the
 routines in the <bf>S-Lang</bf> library catch signals; however, some of the
 routines block the delivery of signals during crucial moments.  It is
 up to the application programmer to install handlers for the various
 signals of interest.

 For the interpreter, the most important signal to worry about is
 <tt>SIGINT</tt>.  This signal is usually generated when the user presses
 <tt>Ctrl-C</tt> at the keyboard.  The interpreter checks the value of the
 <tt>SLang_Error</tt> variable to determine whether or not it should abort the
 interpreting process and return control back to the application.
 This means that if <tt>SIGINT</tt> is to be used to abort the interpreter, a
 signal handler for <tt>SIGINT</tt> should be installed.  The handler should
 set the value of <tt>SLang_Error</tt> to <tt>SL_USER_BREAK</tt>.

 Applications that use the <tt>tty</tt> <tt>getkey</tt> routines or the screen
 management routines must worry about about signals such as:
<tscreen><verb>
     SIGINT                interrupt
     SIGTSTP               stop
     SIGQUIT               quit
     SIGTTOU               background write
     SIGTTIN               background read
     SIGWINCH              window resize
</verb></tscreen>
 It is important that handlers be established for these signals while
 the either the <tt>SLsmg</tt> routines or the <tt>getkey</tt> routines are
 initialized.  The <tt>SLang_init_tty</tt>, <tt>SLang_reset_tty</tt>,
 <tt>SLsmg_init_smg</tt>, and <tt>SLsmg_reset_smg</tt> functions block these
 signals from occuring while they are being called.

 Since a signal can be delivered at any time, it is important for the
 signal handler to call only functions that can be called from a
 signal handler.  This usually means that such function must be
 re-entrant. In particular, the <tt>SLsmg</tt> routines are <em>not</em>
 re-entrant; hence, they should not be called when a signal is being
 processed unless the application can ensure that the signal was not
 delivered while an <tt>SLsmg</tt> function was called.  This statement
 applies to many other functions such as <tt>malloc</tt>, or, more
 generally, any function that calls <tt>malloc</tt>.  The upshot is that
 the signal handler should not attempt to do too much except set a
 global variable for the application to look at while not in a signal
 handler.

 The <bf>S-Lang</bf> library provides two functions for blocking and unblocking the
 above signals:
<tscreen><verb>
    int SLsig_block_signals (void);
    int SLsig_unblock_signals (void);
</verb></tscreen>
 It should be noted that for every call to <tt>SLsig_block_signals</tt>, a
 corresponding call should be made to <tt>SLsig_unblock_signals</tt>, e.g.,
<tscreen><verb>
    void update_screen ()
    {
       SLsig_block_signals ();
       
       /* Call SLsmg functions */
           .
           .
       SLsig_unblock_signals ();
    }
</verb></tscreen>
 See <tt>demo/pager.c</tt> for examples.




<chapt>Searching Functions<p> 

 The S-Lang library incorporates two types of searches: Regular expression
 pattern matching and ordinary searching.
 
<sect>Regular Expressions<p> 

             !!! No documentation available yet !!!



<sect>Simple Searches<p> 
 The routines for ordinary searching are defined in the
 <tt>slsearch.c</tt> file.
 To use these routines, simply include "slang.h" in your program and simply
 call the appropriate routines.
 
 The searches can go in either a forward or backward direction and can
 either be case or case insensitive.  The region that is searched may
 contain null characters (ASCII 0) however, the search string cannot in the
 current implementation.  In addition the length of the string to be found
 is currently limited to 256 characters.
 
 Before searching, the function <tt>SLsearch_init</tt> must first be called to
 <tt>`preprocess</tt>' the search string.
 


<sect>Initialization<p> 
 The function <tt>SLsearch_init</tt> must be called before a search can take place.
 Its prototype is:
<tscreen><verb>
    int SLsearch_init (char *key, int dir, int case_sens, SLsearch_Type *st);
</verb></tscreen>
 Here <tt>key</tt> is the string to be searched for.  <tt>dir</tt> specifies the direction
 of the search: a value greater than zero is used for searching forward and
 a value less than zero is used for searching backward.  The parameter
 <tt>case_sens</tt> specifies whether the search is case sensitive or not.  A
 non-zero value indicates that case is important.  <tt>st</tt> is a pointer to a
 structure of type <tt>SLsearch_Type</tt> defined in "slang.h".  This structure is
 initialized by this routine and must be passed to <tt>SLsearch</tt> when the
 search is actually performed.
 
 This routine returns the length of the string to be searched for.



<sect>SLsearch<p> 

<tscreen><verb>
      Prototype: unsigned char *SLsearch (unsigned char *pmin, 
                                          unsigned char *pmax, 
                                          SLsearch_Type *st);
</verb></tscreen>

 This function performs the search defined by a previous call to
 <tt>SLsearch_init</tt> over a region specified by the pointers
 <tt>pmin</tt> and <tt>pmax</tt>.

 It returns a pointer to the start of the match if successful or it will
 return <tt>NULL</tt> if a match was not found.
  





<appendix>

<chapt>Copyright<p>
 The <bf>S-Lang</bf> library is distributed under two copyrights: the GNU
 Genral Public License, and the Artistic License.  Any program
 that uses the interpreter must adhere to rules of one of these
 licenses.

<sect>The GNU Public License<p>
<tscreen><verb>
                   GNU GENERAL PUBLIC LICENSE
                      Version 2, June 1991

 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
                          675 Mass Ave, Cambridge, MA 02139, USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

                            Preamble
</verb></tscreen>
  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.
<tscreen><verb>
                    GNU GENERAL PUBLIC LICENSE
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
</verb></tscreen>
  0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term "modification".)  Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

  2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
<tscreen><verb>
    a) You must cause the modified files to carry prominent notices
    stating that you changed the files and the date of any change.

    b) You must cause any work that you distribute or publish, that in
    whole or in part contains or is derived from the Program or any
    part thereof, to be licensed as a whole at no charge to all third
    parties under the terms of this License.

    c) If the modified program normally reads commands interactively
    when run, you must cause it, when started running for such
    interactive use in the most ordinary way, to print or display an
    announcement including an appropriate copyright notice and a
    notice that there is no warranty (or else, saying that you provide
    a warranty) and that users may redistribute the program under
    these conditions, and telling the user how to view a copy of this
    License.  (Exception: if the Program itself is interactive but
    does not normally print such an announcement, your work based on
    the Program is not required to print an announcement.)
</verb></tscreen>
These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:
<tscreen><verb>
    a) Accompany it with the complete corresponding machine-readable
    source code, which must be distributed under the terms of Sections
    1 and 2 above on a medium customarily used for software interchange; or,

    b) Accompany it with a written offer, valid for at least three
    years, to give any third party, for a charge no more than your
    cost of physically performing source distribution, a complete
    machine-readable copy of the corresponding source code, to be
    distributed under the terms of Sections 1 and 2 above on a medium
    customarily used for software interchange; or,

    c) Accompany it with the information you received as to the offer
    to distribute corresponding source code.  (This alternative is
    allowed only for noncommercial distribution and only if you
    received the program in object code or executable form with such
    an offer, in accord with Subsection b above.)
</verb></tscreen>
The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

  5. You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

  7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

  9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

  10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
<tscreen><verb>
                            NO WARRANTY

  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

                     END OF TERMS AND CONDITIONS
</verb></tscreen>
        Appendix: How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<tscreen><verb>
    &lt;one line to give the program's name and a brief idea of what it does.&gt;
    Copyright (C) 19yy  &lt;name of author&gt;

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
</verb></tscreen>
Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
<tscreen><verb>
    Gnomovision version 69, Copyright (C) 19yy name of author
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.
</verb></tscreen>
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License.  Of course, the commands you use may
be called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary.  Here is a sample; alter the names:
<tscreen><verb>
  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
  `Gnomovision' (which makes passes at compilers) written by James Hacker.

  &lt;signature of Ty Coon&gt;, 1 April 1989
  Ty Coon, President of Vice
</verb></tscreen>
This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Library General
Public License instead of this License.

<sect>The Artistic License<p>
<tscreen><verb>
                         The "Artistic License"

                                Preamble
</verb></tscreen>
The intent of this document is to state the conditions under which a
Package may be copied, such that the Copyright Holder maintains some
semblance of artistic control over the development of the package,
while giving the users of the package the right to use and distribute
the Package in a more-or-less customary fashion, plus the right to make
reasonable modifications.

Definitions:
<tscreen><verb>
        "Package" refers to the collection of files distributed by the
        Copyright Holder, and derivatives of that collection of files
        created through textual modification.

        "Standard Version" refers to such a Package if it has not been
        modified, or has been modified in accordance with the wishes
        of the Copyright Holder as specified below.

        "Copyright Holder" is whoever is named in the copyright or
        copyrights for the package.

        "You" is you, if you're thinking about copying or distributing
        this Package.

        "Reasonable copying fee" is whatever you can justify on the
        basis of media cost, duplication charges, time of people involved,
        and so on.  (You will not be required to justify it to the
        Copyright Holder, but only to the computing community at large
        as a market that must bear the fee.)

        "Freely Available" means that no fee is charged for the item
        itself, though there may be fees involved in handling the item.
        It also means that recipients of the item may redistribute it
        under the same conditions they received it.
</verb></tscreen>
1. You may make and give away verbatim copies of the source form of the
Standard Version of this Package without restriction, provided that you
duplicate all of the original copyright notices and associated disclaimers.

2. You may apply bug fixes, portability fixes and other modifications
derived from the Public Domain or from the Copyright Holder.  A Package
modified in such a way shall still be considered the Standard Version.

3. You may otherwise modify your copy of this Package in any way, provided
that you insert a prominent notice in each changed file stating how and
when you changed that file, and provided that you do at least ONE of the
following:
<tscreen><verb>
    a) place your modifications in the Public Domain or otherwise make them
    Freely Available, such as by posting said modifications to Usenet or
    an equivalent medium, or placing the modifications on a major archive
    site such as uunet.uu.net, or by allowing the Copyright Holder to include
    your modifications in the Standard Version of the Package.

    b) use the modified Package only within your corporation or organization.

    c) rename any non-standard executables so the names do not conflict
    with standard executables, which must also be provided, and provide
    a separate manual page for each non-standard executable that clearly
    documents how it differs from the Standard Version.

    d) make other distribution arrangements with the Copyright Holder.
</verb></tscreen>
4. You may distribute the programs of this Package in object code or
executable form, provided that you do at least ONE of the following:
<tscreen><verb>
    a) distribute a Standard Version of the executables and library files,
    together with instructions (in the manual page or equivalent) on where
    to get the Standard Version.

    b) accompany the distribution with the machine-readable source of
    the Package with your modifications.

    c) give non-standard executables non-standard names, and clearly
    document the differences in manual pages (or equivalent), together
    with instructions on where to get the Standard Version.

    d) make other distribution arrangements with the Copyright Holder.
</verb></tscreen>
5. You may charge a reasonable copying fee for any distribution of this
Package.  You may charge any fee you choose for support of this
Package.  You may not charge a fee for this Package itself.  However,
you may distribute this Package in aggregate with other (possibly
commercial) programs as part of a larger (possibly commercial) software
distribution provided that you do not advertise this Package as a
product of your own.  You may embed this Package's interpreter within
an executable of yours (by linking); this shall be construed as a mere
form of aggregation, provided that the complete Standard Version of the
interpreter is so embedded.

6. The scripts and library files supplied as input to or produced as
output from the programs of this Package do not automatically fall
under the copyright of this Package, but belong to whomever generated
them, and may be sold commercially, and may be aggregated with this
Package.  If such scripts or library files are aggregated with this
Package via the so-called "undump" or "unexec" methods of producing a
binary executable image, then distribution of such an image shall
neither be construed as a distribution of this Package nor shall it
fall under the restrictions of Paragraphs 3 and 4, provided that you do
not represent such an executable image as a Standard Version of this
Package.

7. C subroutines (or comparably compiled subroutines in other
languages) supplied by you and linked into this Package in order to
emulate subroutines and variables of the language defined by this
Package shall not be considered part of this Package, but are the
equivalent of input as in Paragraph 6, provided these subroutines do
not change the language in any way that would cause it to fail the
regression tests for the language.

8. Aggregation of this Package with a commercial distribution is always
permitted provided that the use of this Package is embedded; that is,
when no overt attempt is made to make this Package's interfaces visible
to the end user of the commercial distribution.  Such use shall not be
construed as a distribution of this Package.

9. The name of the Copyright Holder may not be used to endorse or promote
products derived from this software without specific prior written permission.

10. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.


</book>
