1 Introduction =============== S-Lang is a C programmer's library that includes routines for the rapid development of sophisticated, user friendly, multi-platform applications. The S-Lang library includes the following: * Low level tty input routines for reading single characters at a time. * Keymap routines for defining keys and manipulating multiple keymaps. * High level screen management routines for manipulating both monochrome and color terminals. These routines are very efficient. (SLsmg) * Low level terminal-independent routines for manipulating the display of a terminal. (SLtt) * Routines for reading single line input with line editing and recall capabilities. (SLrline) * Searching functions: both ordinary searches and regular expression searches. (SLsearch) * An embedded stack-based language interpreter with a C-like syntax. * A malloc debugging package The interface to these routines has been implemented in such a way that it is very platform independent. The library is currently available for OS/2, MSDOS, Unix, and VMS systems. 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 S-Lang's keyboard input routines--- one can use a different keyboard getkey routine if one desires. This also means that linking to only part of the S-Lang library does not pull the whole library into the application. Thus, S-Lang 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 S-Lang interpreter is not discussed here. For information about it, consult the S-Lang Programmer's Guide. 2 Keyboard Interface ===================== S-Lang's keyboard interface has been designed to allow one to read a single character at a time in a system independent manner. To initialize the interface, one must first call the function SLang_init_tty. Before exiting the program, the function SLang_reset_tty must be called to restore the keyboard interface to its original state. The function SLang_getkey is used to read keyboard characters from the terminal. 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. 2.1 Initializing the Keyboard Interface ---------------------------------------- The function 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: int SLang_init_tty (int abort_char, int flow_ctrl, int opost); It takes three parameters that are used to specify how the terminal is to be initialized. The first parameter, abort_char, is used to specify the interrupt character (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, 34 should be used to make `Ctrl-G' generate an interrupt signal since 34 is the scan code for `G'. On other systems, the value of abort_char will simply be the ascii value of the control character that will be used to generate the interrupt signal, e.g., 7 for `Ctrl-G'. If -1 is passed, the interrupt character will not be changed. Pressing the interrupt character specified by the first argument will generate a signal (SIGINT) that may or not be caught by the application. It is up to the application to catch this signal. S-Lang provides the function 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., `Ctrl-S' and `Ctrl-Q'). For some systems such as MSDOS, this parameter is meaningless. The third parameter, opost, is used to turn output processing on or off. If opost is zero, output processing is not turned on otherwise, output processing is turned on. The SLang_init_tty function returns -1 upon failure. In addition, after it returns, the S-Lang global variable SLang_TT_Baud_Rate will be set to the baud rate of the terminal if this value can be determined. Example: 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); Here the terminal is initialized such that flow control and output processing are turned off. In addition, the character `Ctrl-G'\footnote For MSDOS systems, use the scan code 34 instead of 7 for `Ctrl-G' has been specified to be the interrupt character. The function SLang_set_abort_signal is used to install the default S-Lang interrupt signal handler. 2.2 Resetting the Keyboard Interface ------------------------------------- The function SLang_reset_tty must be called to reset the terminal to the state it was in before the call to SLang_init_tty. The prototype for this function is: void SLang_reset_tty (void); Usually this function is only called before the program exits. However, if the program is suspended it should also be called just before suspension. 2.3 Setting the Interrupt Handler ---------------------------------- The function SLang_set_abort_signal may be used to associate an interrupt handler with the interrupt character that was previously specified by the SLang_init_tty function call. The prototype for this function is: void SLang_set_abort_signal (void (*)(int)); This function returns nothing and takes a single parameter which is a pointer to a function taking an integer value and returning void. If a NULL pointer is passed, the default S-Lang interrupt handler will be used. The S-Lang default interrupt handler under Unix looks like: static void default_sigint (int sig) { signal (SIGINT, default_sigint); SLKeyBoard_Quit = 1; if (SLang_Ignore_User_Abort == 0) SLang_Error = USER_BREAK; } It simply sets the global variable SLKeyBoard_Quit to one and if the variable SLang_Ignore_User_Abort is non-zero, SLang_Error is set to indicate a user break condition. 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 int 9h is hooked). It is important to note that if the interrupt character is pressed while the function SLang_getkey is called, the variable SLKeyBoard_Quit will not be set to one. Rather, the value of the interrupt character will be returned just like any other character. However, if SLang_Ignore_User_Abort is non-zero, SLang_Error will be set to USER_BREAK. 2.4 Reading Keyboard Input --------------------------- After initializing the keyboard via the SLang_init_tty function, the S-Lang function SLang_getkey is used to read characters from the terminal interface. In addition, the function SLang_input_pending may be used to determine whether or not keyboard input is available to be read. These functions have prototypes: unsigned int SLang_getkey (void); int SLang_input_pending (int tsecs); The SLang_getkey function returns a single character from the terminal. Upon failure, it returns 0xFFFF. If the interrupt character specified by the SLang_init_tty function is pressed while this function is called, the function will return the value of the interrupt character and set the S-Lang global variable SLKeyBoard_Quit to a non-zero value. In addition, if the default S-Lang interrupt handler has been specified by a NULL argument to the SLang_set_abort_signal function, the global variable SLang_Error will be set to USER_BREAK unless the variable SLang_Ignore_User_Abort is non-zero. The SLang_getkey function waits until input is available to be read. The 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 10. Passing a value of zero causes the function to return right away. 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 `Ctrl-G' or until 5 seconds have gone by with no input: #include #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; } 2.5 Buffering Input -------------------- S-Lang has several functions pushing characters back onto the input stream to be read again later by SLang_getkey. These functions are declared as follows: void SLang_ungetkey (unsigned char ch); void SLang_ungetkey_string (unsigned char *buf, int buflen); void SLang_buffer_keystring (unsigned char *buf, int buflen); 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 SLang_getkey will return this character. This function may be used to peek at the character to be read by first reading it and then putting it back. SLang_ungetkey_string has the same function as 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, SLang_buffer_keystring can handle more than one charater but unlike the other two, it places the characters at the end of the keyboard buffer instead of at the beginning. Note that the use of each of these three functions will cause SLang_input_pending to return right away with a non-zero value. Finally, the S-Lang keyboard interface includes the function SLang_flush_input with prototype void SLang_flush_input (void); It may be used to discard all input. Here is a simple example that looks to see what the next key to be read is if one is available: int peek_key () { int ch; if (SLang_input_pending (0) == 0) return -1; ch = SLang_getkey (); SLang_ungetkey (ch); return ch; } 2.6 Global Variables --------------------- Although the following S-Lang global variables have already been mentioned earlier, they are gathered together here for completeness. int SLang_Ignore_User_Abort; If non-zero, pressing the interrupt character will not result in SLang_Error being set to USER_BREAK. volatile int SLKeyBoard_Quit; This variable is set to a non-zero value when the interrupt character is pressed unless the character is pressed during a call to SLang_getkey. If the interrupt character is pressed when SLang_getkey is called, the interrupt character will be returned from SLang_getkey and SLKeyBoard_Quit will be set to zero; however, SLang_Error might be set to USER_BREAK. 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 SLang_init_tty. 3 Screen Management ==================== The S-Lang library provides two interfaces to terminal independent routines for manipulating the display on a terminal. The highest level interface, known as the 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 curses library. The lowest level interface, or the SLtt interface, is used by the SLsmg routines to actually perform the task of writing to the display. This interface is discussed in another section. Like the keyboard routines, the SLsmg routines are platform independent and work the same on MSDOS, OS/2, Unix, and VMS. The screen management, or SLsmg, routines are initialized by function SLsmg_init_smg. Once initialized, the application uses various SLsmg functions to write to a virtual display. This does not cause the 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 SLsmg_refresh. Before exiting, the application using these routines is required to call SLsmg_reset_smg to reset the display system. The following subsections explore S-Lang's screen management system in greater detail. 3.1 Initialization ------------------- The function SLsmg_init_smg must be called before any other SLsmg function can be used. It has the simple prototype: int SLsmg_init_smg (void); 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 physical display. For these reasons, the lower level SLtt routines come into play. In particular, before the first call to SLsmg_init_smg, the application is required to call the function SLtt_get_terminfo before calling SLsmg_init_smg. The SLtt_get_terminfo function sets the global variables SLtt_Screen_Rows and SLtt_Screen_Cols to the values appropriate for the terminal. However, these values may not be correct for some terminals because S-Lang will initialize these variables based on information found in the terminal database. In particular, S-Lang does not query the tty driver for this information. It is recommended that the application make the appropriate system\footnote In a future release of the S-Lang library, convenience functions will be added to facilitate this task. call to determine the correct values before calling SLsmg_init_smg. In addition, if for some reason the size of the display changes, the global variables SLtt_Screen_Rows and SLtt_Screen_Cols should be updated to new the values appropriate for the physical terminal. If this happens, the application must re-initialize the SLsmg routines by calling 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. 3.2 Resetting SLsmg -------------------- Before the program exits or suspends, the function SLsmg_reset_tty should be called to shutdown the display system. This function has the prototype void SLsmg_reset_smg (void); Before calling this function, the cursor should be positioned at the bottom of the display using the SLsmg_gotorc function and then the SLsmg_refresh function to update the cursor position on the physical screen. Basically, a program that uses the SLsmg screen management functions and S-Lang's keyboard interface will look something like: #include "slang.h" int main () { SLtt_get_terminfo (); SLang_init_tty (7, 0, 0); SLsmg_init_smg (); /* do stuff .... */ SLsmg_gotorc (SLtt_Screen_Rows - 1, 0); SLsmg_refresh (); SLsmg_reset_smg (); SLang_reset_tty (); return 0; } 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 SLsmg functions will be introduced which may be used to make this simple program do much more. 3.3 SLsmg Functions -------------------- In the previous sections, functions for initializing and shutting down the SLsmg routines were discussed. In this section, the rest of the SLsmg functions are presented. These functions act only on the virtual display. The physical display is updated when the SLsmg_refresh function is called and not until that time. This function has the simple prototype: void SLsmg_refresh (void); 3.3.1 Positioning the cursor ............................. The SLsmg_gotorc function is used to position the cursor at a given row and column. The prototype for this function is: void SLsmg_gotorc (int row, int col); 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 row = 0 and the first column corresponds to col = 0. The last row of the screen is given by row = SLtt_Screen_Rows - 1. It is possible to change the origin of the coordinate system by using the function SLsmg_set_screen_start with prototype: void SLsmg_set_screen_start (int *r, int *c); 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 NULL pointer may be passed to indicate that the origin is to be set to its initial value of 0. For example, int r = 10; SLsmg_set_screen_start (&r, NULL); sets the origin to (10, 0) and after the function returns, the variable r will have the value of the previous row origin. 3.3.2 Writing to the Display ............................. SLsmg has several routines for outputting text to the virtual display. The following points should be understood: * 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. * Text does 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. * Control characters are displayed in a two character sequence representation with ^ as the first character. That is, `Ctrl-X' is output as ^X. * The newline character does 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. 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. void SLsmg_write_char (char ch); Write a single character to the virtual display. void SLsmg_write_nchars (char *str, int len); Write len characters pointed to by str to the virtual display. void SLsmg_write_string (char *str); Write the null terminated string given by pointer str to the virtual display. This function is a wrapper around SLsmg_write_nchars. void SLsmg_write_nstring (char *str, int n); Write the null terminated string given by pointer str to the virtual display. At most, only n characters are written. If the length of the string is less than n, then the string will be padded with blanks. This function is a wrapper around SLsmg_write_nchars. void SLsmg_printf (char *fmt, ...); This function is similar to printf except that it writes to the SLsmg virtual display. void SLsmg_vprintf (char *, va_list); Like SLsmg_printf but uses a variable argument list. 3.3.3 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) void SLsmg_erase_eol (void); Erase line from current position to the end of the line. void SLsmg_erase_eos (void); Erase from the current position to the end of the screen. void SLsmg_cls (void); Clear the entire virtual display. 3.3.4 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 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 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 SLsmg, the integer is simply called an object. For example, the menu bar might be associated with the object 1, the drop down menu could be object 2, the shadow could be object 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 other objects that have not explicitly been given an object number. SLsmg, or more precisely SLtt, refers to the attributes of this special object as the default or normal attributes. The 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 SLtt routines. Hence, to map an object to the actual set of attributes requires a call to any of the following SLtt routines: 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); 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 SLtt interface. The SLtt_set_color function takes four parameters. The first parameter, 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, fg and 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: "black" "gray" "red" "brightred" "green" "brightgreen" "brown" "yellow" "blue" "brightblue" "magenta" "brightmagenta" "cyan" "brightcyan" "lightgray" "white" The value of the foreground parameter 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 S-Lang global variable SLtt_Use_Ansi_Colors is non-zero, the terminal is assumed to be a color terminal. Its value is initialized to zero (a monochrome terminal) and it is up to the application to change it to the value that is appropriate to the terminal. If this 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 SLtt_set_mono function call.. With this background, the SLsmg functions for setting the character attributes can now be defined. These functions simply set the object attributes that are to be assigned to subsequent characters written to the virtual display. For this reason, the new attribute is called the current attribute. void SLsmg_set_color (int obj); Set the current attribute to those of object obj. void SLsmg_normal_video (void); This function is equivalent to SLsmg_set_color (0). void SLsmg_reverse_video (void); This function is equivalent to SLsmg_set_color (1). On monochrome terminals, it is equivalent to setting the subsequent character attributes to inverse video. 3.3.5 Lines and Alternate Character Sets ......................................... The S-Lang 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. void SLsmg_set_char_set (int flag); If flag is non-zero, subsequent write functions will use characters from the alternate character set. If flag is zero, the default, or, ordinary character set will be used. void SLsmg_draw_hline (int len); Draw a horizontal line from the current position to the column that is len characters to the right. void SLsmg_draw_vline (int len); Draw a horizontal line from the current position to the row that is len rows below. void SLsmg_draw_box (int r, int c, int dr, int dc); Draw a box whose upper right corner is at row r and column c. The box spans dr rows and dc columns. The current position will be left at row r and column c. 3.3.6 Miscellaneous Functions .............................. void SLsmg_touch_lines (int r, int n); Mark screen rows numbered r, r + 1, ...r + (n - 1) as modified. When SLsmg_refresh is called, these rows will be completely redrawn. 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. 3.4 Variables -------------- The following S-Lang global variables are used by the SLsmg interface. Some of these have been previously discussed. int SLtt_Screen_Rows; int SLtt_Screen_Cols; The number of rows and columns of the physical display. If either of these numbers changes, the functions SLsmg_reset_smg and SLsmg_init_smg should be called again so that the SLsmg routines can re-adjust to the new size. int SLsmg_Tab_Width; Set this variable to the tab width that will be used when expanding tab characters. The default is 8. 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 128 for MSDOS and 160 for other systems (ISO-Latin). 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. int SLtt_Term_Cannot_Scroll; If this value is zero, the 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 SLtt_get_terminfo function. 3.5 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. 1Searching-Functions The S-Lang library incorporates two types of searches: Regular expression pattern matching and ordinary searching. 3.6 Regular-Expressions ------------------------ !!! No documentation available yet !!! 3.7 Simple-Searches -------------------- The routines for ordinary searching are defined in the 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 SLsearch_init must first be called to `preprocess' the search string. 3.8 initialization ------------------- The function SLsearch_init must be called before a search can take place. Its prototype is: int SLsearch_init (char *key, int dir, int case_sens, SLsearch_Type *st); Here key is the string to be searched for. 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 case_sens specifies whether the search is case sensitive or not. A non-zero value indicates that case is important. st is a pointer to a structure of type SLsearch_Type defined in "slang.h". This structure is initialized by this routine and must be passed to SLsearch when the search is actually performed. This routine returns the length of the string to be searched for. 3.9 SLsearch ------------- Prototype: unsigned char *SLsearch (unsigned char *pmin, unsigned char *pmax, SLsearch_Type *st); This function performs the search defined by a previous call to SLsearch_init over a region specified by the pointers pmin and pmax. It returns a pointer to the start of the match if successful or it will return NULL if a match was not found.