Help file for slang
1 Interpreter
See readme files for information--- no help file yet.
1 Keyboard-Interface
SLang's keyboard interface is designed to allow one to read a 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. This is particularly true for
MSDOS since INT-9 is hooked by S-Lang.
2 Functions
3 init_tty
Prototype: int SLang_init_tty (int abort_char, int flow_ctrl, int opost);
This function must be called to initialize the tty for single character
input. The first parameter `abort_char' must lie in the range 0-255 and
is used as an abort character. By default, pressing this character sets
the global variable `SLang_Error' to USER_BREAK. See help on the function
`SLang_set_abort_signal' to change the default action.
If the second parameter `flow_ctrl' is non-zero, flow control is enabled.
If the third parmeter `opost' is zero, output processing is NOT turned on.
A value of zero is required for SLang's screen management routines (SLsmg)
to work properly.
This function returns 0 upon success. In addition, if the global variable
SLang_TT_Baud_Rate == 0 when this function is called, SLang will attempt
to determine the terminals baud rate and set this variable accordingly. As
far as the SLang library is concerned, if SLang_TT_Baud_Rate is less than
or equal to zero, the baud rate is effectively infinite.
3 reset_tty
Prototype: void SLang_reset_tty (void);
This function must be called to reset the tty to the state the terminal
was in before a previous call to `SLang_init_tty'.
3 getkey
Prototype: unsigned int SLang_getkey (void);
This function returns a single key from the tty. If the read fails,
0xFFFF is returned. Before attempting to use this function, one myust
first call SLang_init_tty to initialize the terminal.
If the abort character is pressed while this function is called, it will
return the value of the abort character. In addition, the global variable
SLKeyBoard_Quit will be set and SLang_Error will will be set to USER_BREAK
unless the variable SLang_Ignore_User_Abort is non-zero.
3 unget_keystring
Prototype: void SLang_ungetkey_string (unsigned char *buf, int buflen);
3 buffer_keystring
Prototype: void SLang_buffer_keystring (unsigned char *buf, int buflen);
3 ungetkey
Prototype: void SLang_ungetkey (unsigned char ch);
3 flush_input
Prototype: void SLang_flush_input (void);
3 input_pending
Prototype int SLang_input_pending (int tsecs);
3 set_abort_signal
Prototype: void SLang_set_abort_signal (void (*f)(int));
If SIGINT is generated, the function p1 will be called. If `f' is NULL
the SLang default signal handler is called. This sets SLang_Error to
USER_BREAK. I suspect most users will simply want to pass NULL.
2 Variables
3 Abort_Char
int SLang_Abort_Char;
The value of the character (0-255) used to trigger SIGINT
3 Ignore_User_Abort
int SLang_Ignore_User_Abort;
If non-zero, pressing the abort character will not result in USER_BREAK
SLang_Error.
3 KeyBoard_Quit
volatile int SLKeyBoard_Quit
3 TT_Baud_Rate
int SLang_TT_Baud_Rate;
If this value is zero before SLang_init_tty is called, after the call, it
will be set to the baud rate if the terminal on systems which support it.
1Screen_Management
S-Lang's screen management routines are located in the slsmg.c file. All
exported functions and variables are prefixed by `SLsmg', e.g., `SLsmg_cls'.
The screen management code uses the `SLtt' routines for writing output to
the terminal.
To initialize the screen management system, call `SLtt_get_terminfo' first
to initialize the display system. Then call `SLsmg_init_smg' to initialize
the SLsmg routines. If you are going to read characters from the keyboard,
it is also a good idea to initialize the tty at this point via the
SLang_init_tty function (See `Keyboard').
Before exiting the program, call the approriate routines to reset the
terminal and display system. Basically, your program will look like
something like:
\begin{verbatim}
#include "slang.h"
int main ()
{
SLtt_get_terminfo ();
SLang_init_tty (7, 0, 0);
SLsmg_init_smg ();
/* do stuff .... */
SLsmg_reset_smg ();
SLang_reset_tty ();
return 0;
}
\end{verbatim}
2Functions
3erase_eol
Prototype: void SLsmg_erase_eol (void);
Erase line from current position to the end of the line.
3gotorc
Prototype: void SLsmg_gotorc (int row, int col);
Move cursor position to ('row', 'col'). (0,0) corresponds to the top left
corner of the screen.
3erase_eos
Prototype: void SLsmg_erase_eos (void);
Erase fro the current position to the end of the screen.
3reverse_video
Prototype: void SLsmg_reverse_video (void);
Start writing characters in reverse video.
3set_color
Prototype: void SLsmg_set_color (int obj);
Set the character attributes to those of 'obj'.
3normal_video
Prototype: void SLsmg_normal_video (void);
Turn off characters attributes and set attributes to object 0.
3printf
Prototype: void SLsmg_printf (char *, ...);
Write a formatted string to the virtual display.
3vprintf
Prototype: void SLsmg_vprintf (char *, va_list);
Like 'SLsmg_printf' but uses a variable argument list.
3write_string
Prototype: void SLsmg_write_string (char *);
3write_char
Prototype: void SLsmg_write_char (char);
3write_nchars
Prototype: void SLsmg_write_nchars (char *, int);
3cls
Prototype: void SLsmg_cls (void);
Clear the screen
3refresh
Prototype: void SLsmg_refresh (void);
Make the physical display look like the virtual display.
3touch_lines
Prototype: void SLsmg_touch_lines (int row, int n);
Mark screen rows 'row', 'row + 1', ... 'row + (n - 1)' as modified.
3init_smg
Prototype: int SLsmg_init_smg (void);
Must be called before any of the other routines will work.
3reset_smg
Prototype: void SLsmg_reset_smg (void);
3char_at
unsigned short SLsmg_char_at(void);
Prototype: unsigned short SLsmg_char_at(void);
Returns the character and its attributes object number at the current
cursor position.
2Variables
SLsmg_Tab_Width (Default is 8).
1Searching-Functions
The S-Lang library incorporates two types of searches: Regular expression
pattern matching and ordinary searching.
2Regular-Expressions
!!! No documentation available yet !!!
2Simple-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.
3initialization
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.
3SLsearch
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.
