% -*- mode: tex; mode: fold -*-
\documentstyle{article}
%{{{ Title, border, etc. 

\setlength{\oddsidemargin}{0mm}
\setlength{\evensidemargin}{0mm}
\setlength{\textwidth}{160mm}
\setlength{\topmargin}{-10mm}
\setlength{\textheight}{210mm}
\parindent=0mm
\parskip=5mm

\def\mytitle{S-Lang C Programmer's Guide}

\newlength{\pagewidth}
\setlength{\pagewidth}{\textwidth}
%\addtolength\pagewidth\marginparwidth
% \addtolength\pagewidth\marginparsep

\makeatletter
\def\ps@headings{\def\@oddfoot{}%
\def\@oddhead{\makebox[\textwidth][l]{\underline{\hbox to \pagewidth{\bf
\mytitle\hfill\thepage}}}}%
\def\@evenfoot{}%
\def\@evenhead{\makebox[\textwidth][l]{\underline{\hbox to \pagewidth{\bf
\mytitle\hfill\thepage}}}}}%
\pagestyle{headings}

%}}}

%{{{ Macros 

\newcommand{\slang}{{\bf S-Lang}}
\newcommand{\jed}{{\bf jed}}

\newcommand{\grp}[1]{{\bf #1}}
\newcommand{\exmp}[1]{{\tt #1}}
\newcommand{\var}[1]{{\tt #1}}
\newcommand{\key}[1]{{\sc #1}}
\newcommand{\file}[1]{{\tt #1}}

%}}}

\begin{document}
\tableofcontents
\pagebreak

\section{Introduction} %{{{

  \slang{} is a C programmer's library that includes routines for the rapid
  development of sophisticated, user friendly, multi-platform applications.
  The \slang{} library includes the following:

\begin{itemize} 
\item  Low level tty input routines for reading single characters at a time.
\item  Keymap routines for defining keys and manipulating multiple keymaps.
\item  A high-level keyprocessing interface (\verb|SLkp|) for
       handling function and arrow keys.
\item  High level screen management routines for manipulating both
       monochrome and color terminals.  These routines are {\em very}
       efficient. ({\tt SLsmg})
\item  Low level terminal-independent routines for manipulating the display
       of a terminal. ({\tt SLtt})
\item  Routines for reading single line input with line editing and recall
       capabilities. ({\tt SLrline})
\item  Searching functions: both ordinary searches and regular expression
       searches. ({\tt SLsearch})
\item  An embedded stack-based language interpreter with a C-like syntax.
\end{itemize} 

  The library is currently available for OS/2, MSDOS, Unix, and VMS
  systems.  For the most part, the interface to library routines has
  been implemented in such a way that it appears to be platform
  independent from the point of view of the application.  In addition,
  care has been taken to ensure that the routines are ``independent''
  of one another as much as possible.  For example, although the
  keymap routines require keyboard input, they are not tied to
  \slang's keyboard input routines--- one can use a different keyboard
  \verb|getkey| routine if one desires.  This also means that linking
  to only part of the \slang{} library does not pull the whole library
  into the application.  Thus, \slang{} applications tend to be
  relatively small in comparison to programs that use libraries with
  similar capabilities.

  In the following sections, the C interface to this library is described.
  The actual syntax of the embedded \slang{} interpreter is not discussed
  here.  For information about it, consult the {\em S-Lang Programmer's
  Guide}.

%}}}

\section{Keyboard Interface} %{{{

%{{{ Overview 

  \slang's keyboard interface has been designed to allow an
  application to read keyboard input from the user in a
  system-independent manner.  The interface consists of a set of low
  routines for reading single character data as well as a higher
  level interface (\grp{SLkp}) which utilize \slang's keymap facility
  for reading multi-character sequences.

  To initialize the interface, one must first call the function
  \verb|SLang_init_tty|. Before exiting the program, the function
  \verb|SLang_reset_tty| must be called to restore the keyboard
  interface to its original state.  Once initialized, the low-level
  \verb|SLang_getkey| function may be used to read {\em simgle}
  keyboard characters from the terminal.  An application using the the
  higher-level \grp{SLkp} interface will read charcters using the
  \verb|SLkp_getkey| function.

  In addition to these basic functions, there are also functions to
  ``unget'' keyboard characters, flush the input, detect pending-input
  with a timeout, etc. These functions are defined below.

%}}}

\subsection{Initializing the Keyboard Interface} %{{{

  The function \verb|SLang_init_tty| must be called to initialize the
  terminal for single character input.  This puts the terminal in a mode
  usually referred to as ``raw'' mode.  
  
  The prototype for the function is:
\begin{verbatim} 
      int SLang_init_tty (int abort_char, int flow_ctrl, int opost);
\end{verbatim}
  It takes three parameters that are used to specify how the terminal is to
  be initialized.
  %Although the \slang{} keyboard interface has been
  %designed to be as system independent as possible, there are semantic
  % differences.

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

  Pressing the interrupt character specified by the first argument will
  generate a signal ({\tt SIGINT}) that may or not be caught by the
  application.  It is up to the application to catch this signal.  \slang{}
  provides the function \verb|Slang_set_abort_signal| to make it easy to
  facilitate this task.

  The second parameter is used to specify whether or not flow control should
  be used. If this parameter is non-zero, flow control is enabled otherwise
  it is disabled.  Disabling flow control is necessary to pass certain
  characters to the application (e.g., \key{Ctrl-S} and \key{Ctrl-Q}).
  For some systems such as MSDOS, this parameter is meaningless.
  
  The third parameter, \verb|opost|, is used to turn output processing on or
  off.  If \verb|opost| is zero, output processing is {\em not} turned on
  otherwise, output processing is turned on.

  The \verb|SLang_init_tty| function returns -1 upon failure.  In addition,
  after it returns, the \slang{} global variable \verb|SLang_TT_Baud_Rate|
  will be set to the baud rate of the terminal if this value can be
  determined.

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

%}}}

\subsection{Resetting the Keyboard Interface} %{{{

  The function \verb|SLang_reset_tty| must be called to reset the terminal
  to the state it was in before the call to \verb|SLang_init_tty|.  The
  prototype for this function is:
\begin{verbatim}
      void SLang_reset_tty (void);
\end{verbatim}
  Usually this function is only called before the program exits.  However,
  if the program is suspended it should also be called just before suspension.
  
%}}}

\subsection{Initializing the \grp{SLkp} Routines} %{{{

  Extra initialization of the higher-level \grp{SLkp} functions are
  required because they are layered on top of the lower level
  routines.  Since the \verb|SLkp_getkey| function is able to process
  function and arrow keys in a terminal independent manner, it is
  necessary to call the \verb|SLtt_get_terminfo| function to get
  information about the escape character sequences that the terminal's
  function keys send.  Once that information is available, the
  \verb|SLkp_init| function can construct the proper keymaps to
  process the escape sequences.
  
  This part of the initialization process for an application using
  this interface will look something like:

\begin{verbatim} 
      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);
        }
\end{verbatim} 

  It is important to check the return status of the \verb|SLkp_init|
  function which can failed if it cannot allocate enough memory for
  the keymap.
 
%}}}

\subsection{Setting the Interrupt Handler} %{{{

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

  Although the function expressed above is specific to Unix, the
  analogous routines for other operating systems are equivalent in
  functionality even though the details of the implementation may vary
  drastically (e.g., under MSDOS, the hardware keyboard interrupt
  \verb|int 9h| is hooked).

%}}}

\subsection{Reading Keyboard Input with SLang\_getkey} %{{{

  After initializing the keyboard via \verb|SLang_init_tty|,
  the \slang{} function \verb|SLang_getkey| may be used to read
  characters from the terminal interface.  In addition, the function
  \verb|SLang_input_pending| may be used to determine whether or not
  keyboard input is available to be read.

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

  The \verb|SLang_getkey| function waits until input is available to be
  read.  The \verb|SLang_input_pending| function may be used to determine
  whether or not input is ready.  It takes a single parameter that indicates
  the amount of time to wait for input before returning with information
  regarding the availability of input.  This parameter has units of one
  tenth ($1/10$) of a second, i.e., to wait one second, the value of the
  parameter should be {\tt 10}.  Passing a value of zero causes the function
  to return right away.  \verb|SLang_input_pending| returns a positive
  integer if input is available or zero if input is not available.  It will
  return -1 if an error occurs.

  Here is a simple example that reads keys from the terminal until one
  presses \key{Ctrl-G} or until $5$ seconds have gone by with no input:
\begin{verbatim} 
      #include <stdio.h>
      #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;
      }
\end{verbatim} 


%}}}

\subsection{Reading Keyboard Input with SLkp\_getkey} %{{{

  Unlike the low-level function \verb|SLang_getkey|, the
  \verb|SLkp_getkey| function can read a multi-character sequence
  associated with function keys.  The \verb|SLkp_getkey| function uses
  \verb|SLang_getkey| and \slang's keymap facility to process escape
  sequences.  It returns a single integer which describes the key that
  was pressed:
\begin{verbatim} 
      int SLkp_getkey (void);
\end{verbatim}
  That is, the \verb|SLkp_getkey| function simple provides a mapping
  between keys and integers.  In this context the integers are called
  {\em keysyms}.
  
  For single character input such as generated by the \key{a} key on
  the keyboard, the function returns the character that was generated,
  e.g., \verb|'a'|.  For single characters, \verb|SLkp_getkey| 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 \file{slang.h} include file.  For example, the
  up arrow key corresponds to the keysym whose value is
  \verb|SL_KEY_UP|. 
  
  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
  \verb|SL_KEY_ERR| will be returned.
  
  Here is an example of how \verb|SLkp_getkey| may be used by a file
  viewer:
\begin{verbatim} 
      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 ();
        }
\end{verbatim} 
   
   Unlike its lower-level counterpart, \verb|SLang_getkey|, there do
   not yet exist any functions in the library that are capable of
   ``ungetting'' keysyms.  In particular, the \verb|SLang_ungetkey|
   function will not work.
   
%}}}

\subsection{Buffering Input} %{{{

  \slang{} has several functions pushing characters back onto the
  input stream to be read again later by \verb|SLang_getkey|.  It
  should be noted that none of the above functions are designed to
  push back keysyms read by the \verb|SLkp_getkey| function.  These
  functions are declared as follows:
\begin{verbatim}
      void SLang_ungetkey (unsigned char ch);
      void SLang_ungetkey_string (unsigned char *buf, int buflen);
      void SLang_buffer_keystring (unsigned char *buf, int buflen);
\end{verbatim}

  \verb|SLang_ungetkey| 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
  \verb|SLang_getkey| will return this character.  This function may be used
  to {\em peek} at the character to be read by first reading it and then
  putting it back.

  \verb|SLang_ungetkey_string| has the same function as
  \verb|SLang_ungetkey| 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, \verb|SLang_buffer_keystring| can
  handle more than one charater but unlike the other two, it places the
  characters at the {\em end} of the keyboard buffer instead of at the
  beginning.

  Note that the use of each of these three functions will cause
  \verb|SLang_input_pending| to return right away with a non-zero value.

  Finally, the \slang{} keyboard interface includes the function
  \verb|SLang_flush_input| with prototype
\begin{verbatim}
      void SLang_flush_input (void);
\end{verbatim} 
  It may be used to discard {\em all} input.
  
  Here is a simple example that looks to see what the next key to be read is
  if one is available:
\begin{verbatim} 
      int peek_key ()
      {
         int ch;
         if (SLang_input_pending (0) == 0) return -1;
         ch = SLang_getkey ();
         SLang_ungetkey (ch);
         return ch;
      }
\end{verbatim}       


%}}}

\subsection{Global Variables} %{{{
  Although the following \slang{} global variables have already been
  mentioned earlier, they are gathered together here for completeness.
  
  \verb|int SLang_Ignore_User_Abort;|\\
  If non-zero, pressing the interrupt character will not result in
  \verb|SLang_Error| being set to \verb|USER_BREAK|.

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

  \verb|int SLang_TT_Baud_Rate;|\\ 
  On systems which support it, this variable is set to the value of the
  terminal's baud rate after the call to \verb|SLang_init_tty|.

%}}}

%}}}

\section{Screen Management} %{{{

  The \slang{} library provides two interfaces to terminal independent
  routines for manipulating the display on a terminal.  The highest level
  interface, known as the \verb|SLsmg| 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 \verb|curses| library.  The lowest level interface, or the \verb|SLtt|
  interface, is used by the \verb|SLsmg| routines to actually perform the
  task of writing to the display.  This interface is discussed in another
  section.  Like the keyboard routines, the \verb|SLsmg| routines are {\em
  platform independent} and work the same on MSDOS, OS/2, Unix, and VMS.

  The screen management, or \verb|SLsmg|, routines are initialized by
  function \verb|SLsmg_init_smg|.  Once initialized, the application uses
  various \verb|SLsmg| functions to write to a {\em virtual} display.  This does
  not cause the {\em physical} terminal display to be updated immediately.  
  The physical display is updated to look like the virtual display only
  after a call to the function \verb|SLsmg_refresh|.  Before exiting, the
  application using these routines is required to call
  \verb|SLsmg_reset_smg| to reset the display system.
  
  The following subsections explore \slang's screen management system in
  greater detail.
  
\subsection{Initialization}

  The function \verb|SLsmg_init_smg| must be called before any other
  \verb|SLsmg| function can be used.  It has the simple prototype:
\begin{verbatim}
      int SLsmg_init_smg (void);
\end{verbatim} 
  It returns non-zero if successful or zero 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} display.  For these reasons, the lower level \verb|SLtt| routines
  come into play.  In particular, before the first call to
  \verb|SLsmg_init_smg|, the application is required to call the function
  \verb|SLtt_get_terminfo| before calling \verb|SLsmg_init_smg|.

  The \verb|SLtt_get_terminfo| function sets the global variables
  \verb|SLtt_Screen_Rows| and \verb|SLtt_Screen_Cols| to the values
  appropriate for the terminal.  It does this by calling the
  \verb|SLtt_get_screen_size| 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 \verb|SLtt_get_screen_size| function
  whenever the display size changes, e.g., in response to a
  \verb|SIGWINCH| signal.  If the screen size changes, the application
  must also re-initialize the \verb|SLsmg| routines by calling
  \verb|SLsmg_init_tty| again so that the size of the virtual screen
  can be adjusted accordingly.

  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.

\subsection{Resetting SLsmg}  

  Before the program exits or suspends, the function \verb|SLsmg_reset_tty|
  should be called to shutdown the display system.  This function has the
  prototype
\begin{verbatim} 
      void SLsmg_reset_smg (void);
\end{verbatim}
  This will deallocate any memory allocated for the virtual screen and
  reset the terminal's display.
  
  Basically, a program that uses the \verb|SLsmg| screen management functions
  and \slang's keyboard interface will look something like:
\begin{verbatim}  
      #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;
      }
\end{verbatim}
  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 \verb|SLsmg| functions will be introduced which may be used
  to make this simple program do much more.

\subsection{SLsmg Functions}

  In the previous sections, functions for initializing and shutting down the
  \verb|SLsmg| routines were discussed.  In this section, the rest of the
  \verb|SLsmg| functions are presented.  These functions act only on the {\em
  virtual} display.  The {\em physical} display is updated when the
  \verb|SLsmg_refresh| function is called and {\em not until that time}.
  This function has the simple prototype:
\begin{verbatim}   
     void SLsmg_refresh (void);
\end{verbatim} 
  
\subsubsection{Positioning the cursor}

  The \verb|SLsmg_gotorc| function is used to position the cursor at a given
  row and column.  The prototype for this function is:
\begin{verbatim} 
      void SLsmg_gotorc (int row, int col);
\end{verbatim}
  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
  \verb|row = 0| and the first column corresponds to \verb|col = 0|.  The last
  row of the screen is given by \verb|row = SLtt_Screen_Rows - 1|.
  
  It is possible to change the origin of the coordinate system by using the
  function \verb|SLsmg_set_screen_start| with prototype:
\begin{verbatim}   
     void SLsmg_set_screen_start (int *r, int *c);
\end{verbatim}
  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 \verb|NULL|
  pointer may be passed to indicate that the origin is to be set to its
  initial value of $0$.  For example,
\begin{verbatim} 
      int r = 10;
      SLsmg_set_screen_start (&r, NULL);
\end{verbatim}
  sets the origin to $(10, 0)$ and after the function returns, the variable
  \verb|r| will have the value of the previous row origin.

\subsubsection{Writing to the Display}
  
  \verb|SLsmg| has several routines for outputting text to the virtual
  display.  The following points should be understood:
\begin{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} 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 \verb|^| as the first character.  That is,
      \key{Ctrl-X} is output as \verb|^X|.
      
\item The newline character does {\em not} 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.
\end{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.

  \verb|void SLsmg_write_char (char ch);|\\
  Write a single character to the virtual display.
  
  \verb|void SLsmg_write_nchars (char *str, int len);|\\
  Write \verb|len| characters pointed to by \verb|str| to the virtual display. 

  \verb|void SLsmg_write_string (char *str);|\\ 
  Write the null terminated string given by pointer \verb|str| to the virtual
  display.  This function is a wrapper around \verb|SLsmg_write_nchars|.

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

\subsubsection{Erasing the Display}

  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)
  
  \verb|void SLsmg_erase_eol (void);|\\
  Erase line from current position to the end of the line.
  
  \verb|void SLsmg_erase_eos (void);|\\
  Erase from the current position to the end of the screen.

  \verb|void SLsmg_cls (void);|\\
  Clear the entire virtual display.

\subsubsection{Setting Character Attributes}

  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 \verb|SLsmg| 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 \verb|SLsmg| 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 \verb|SLsmg|, the integer is
  simply called an {\em object}.

  For example, the menu bar might be associated with the object \verb|1|, the
  drop down menu could be object \verb|2|, the shadow could be object \verb|3|,
  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.}. The object numbered zero should not be regarding as an
  object at all.  Rather it should be regarded as all {\em other} objects
  that have not explicitly been given an object number.  \verb|SLsmg|, or
  more precisely \verb|SLtt|, refers to the attributes of this special object
  as the {\em default} or {\em normal} attributes.

  The \verb|SLsmg| 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 \verb|SLtt| routines.  Hence, to map an object to the
  actual set of attributes requires a call to any of the following \verb|SLtt|
  routines:
\begin{verbatim}   
     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);
\end{verbatim}
  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
  \verb|SLtt| interface.

  The \verb|SLtt_set_color| function takes four parameters.  The first
  parameter, \verb|obj|, 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, \verb|fg| and \verb|bg|,
  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:
\begin{verbatim}
     "black"                "gray"
     "red"                  "brightred"
     "green"                "brightgreen"
     "brown"                "yellow"
     "blue"                 "brightblue"
     "magenta"              "brightmagenta"
     "cyan"                 "brightcyan"
     "lightgray"            "white"
\end{verbatim} 
  The value of the foreground parameter \verb|fg| 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.}.

  Of course not all terminals are color terminals.  If the \slang{} global
  variable \verb|SLtt_Use_Ansi_Colors| is non-zero, the terminal is
  assumed to be a color terminal.  The \verb|SLtt_get_terminfo| 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 \verb|SLtt_get_terminfo|
  routine will check whether or not the environment variable
  \verb|COLORTERM| exists.  If it exists, the terminal will be assumed
  to support ANSI colors and \verb|SLtt_Use_Ansi_Colors| 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 \verb|SLtt_Use_Ansi_Colors| 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} function call.}.

  With this background, the \verb|SLsmg| 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} characters written
  to the virtual display.  For this reason, the new attribute is called the
  {\em current} attribute.

  \verb|void SLsmg_set_color (int obj);|\\
  Set the current attribute to those of object \verb|obj|.
  
  \verb|void SLsmg_normal_video (void);|\\
  This function is equivalent to \verb|SLsmg_set_color (0)|. 
  
  \verb|void SLsmg_reverse_video (void);|\\
  This function is equivalent to \verb|SLsmg_set_color (1)|.  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 \verb|SLtt_get_terminfo|
  function checks for the existence of the \verb|COLORFGBG|
  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 \verb|COLORTERM| is
  \verb|lightgray;blue|, the default color object will be initialized
  to represent a \verb|lightgray| foreground upon a \verb|blue|
  background.

\subsubsection{Lines and Alternate Character Sets}
  The \slang{} 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.
  
  \verb|void SLsmg_set_char_set (int flag);|\\
  If \verb|flag| is non-zero, subsequent write functions will use characters
  from the alternate character set.  If \verb|flag| is zero, the default, or,
  ordinary character set will be used.
  
  \verb|void SLsmg_draw_hline (int len);|\\
  Draw a horizontal line from the current position to the column that is
  \verb|len| characters to the right.
  
  \verb|void SLsmg_draw_vline (int len);|\\
  Draw a horizontal line from the current position to the row that is
  \verb|len| rows below.
  
  \verb|void SLsmg_draw_box (int r, int c, int dr, int dc);|\\
  Draw a box whose upper right corner is at row \verb|r| and column \verb|c|.
  The box spans \verb|dr| rows and \verb|dc| columns.  The current position
  will be left at row \verb|r| and column \verb|c|.
  
\subsubsection{Miscellaneous Functions}
 
  \verb|void SLsmg_touch_lines (int r, int n);|\\
  Mark screen rows numbered \verb|r|, \verb|r + 1|, \ldots \verb|r + (n - 1)| as
  modified.  When \verb|SLsmg_refresh| is called, these rows will be
  completely redrawn.
  
  \verb|unsigned short SLsmg_char_at(void);|\\
  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.
  
\subsection{Variables}

  The following \slang{} global variables are used by the \verb|SLsmg|
  interface.  Some of these have been previously discussed.
  
  \verb|int SLtt_Screen_Rows;|\\
  \verb|int SLtt_Screen_Cols;|\\
  The number of rows and columns of the {\em physical} display.  If either of
  these numbers changes, the functions \verb|SLsmg_reset_smg| and
  \verb|SLsmg_init_smg| should be called again so that the \verb|SLsmg|
  routines can re-adjust to the new size.
  
  \verb|int SLsmg_Tab_Width;|\\
  Set this variable to the tab width that will be used when expanding tab
  characters.  The default is 8.
  
  \verb|int SLsmg_Display_Eight_Bit|\\
  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
  \verb|128| for MSDOS and \verb|160| for other systems (ISO-Latin).

  \verb|int SLtt_Use_Ansi_Colors;|\\
  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.
  
  \verb|int SLtt_Term_Cannot_Scroll;|\\
  If this value is zero, the \verb|SLsmg| 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
  \verb|SLtt_get_terminfo| function.
  
\subsection{Hints for using SLsmg}

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


%}}}

\section{Searching Functions} %{{{

 The S-Lang library incorporates two types of searches: Regular expression
 pattern matching and ordinary searching.
 
\subsection{Regular Expressions} %{{{

             !!! No documentation available yet !!!

%}}}

\subsection{Simple Searches} %{{{
 The routines for ordinary searching are defined in the \verb|slsearch.c| 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 \verb|SLsearch_init| must first be called to
 \verb|`preprocess|' the search string.
 
%}}}

\subsection{Initialization} %{{{
 The function \verb|SLsearch_init| must be called before a search can take place.
 Its prototype is:
\begin{verbatim}  
    int SLsearch_init (char *key, int dir, int case_sens, SLsearch_Type *st);
\end{verbatim} 
 Here \verb|key| is the string to be searched for.  \verb|dir| 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
 \verb|case_sens| specifies whether the search is case sensitive or not.  A
 non-zero value indicates that case is important.  \verb|st| is a pointer to a
 structure of type \verb|SLsearch_Type| defined in "slang.h".  This structure is
 initialized by this routine and must be passed to \verb|SLsearch| when the
 search is actually performed.
 
 This routine returns the length of the string to be searched for.

%}}}

\subsection{SLsearch} %{{{

\begin{verbatim} 
      Prototype: unsigned char *SLsearch (unsigned char *pmin, 
                                          unsigned char *pmax, 
                                          SLsearch_Type *st);
\end{verbatim} 

 This function performs the search defined by a previous call to
 \verb|SLsearch_init| over a region specified by the pointers
 \verb|pmin| and \verb|pmax|.

 It returns a pointer to the start of the match if successful or it will
 return \verb|NULL| if a match was not found.
  

%}}}

%}}}

\end{document}
