Amiga Elysian Archive

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Elysian Archive / AmigaElysianArchive.iso / newlibs / rawil110.lha / RawIN.doc next >

Wrap

Text File | 1992-08-04 | 21KB | 715 lines

=================== RawIN.lib V1.10 Documentation - August 4, 1992 - =================== Copyright (c) 1992 by Sam Yee. All rights reserved. ===================================================================== COPYRIGHT ========= The link-time library RawIN.lib and its documentation are written and copyrighted by Sam Yee. They may be distributed freely providing the following restrictions are satisfied: o Distributors may not charge more than the cost of a diskette used for the distribution of this library. o Distributors may only distribute the unmodified copy of the original library, along with its documentation, and copyright notices intact. ===================================================================== DISCLAIMER ========== This library and the test program and its documentation is provided "as is". No warranties are made with respect to the accuracy, reliability, performance or operation of this software and information. You are using this program at your own risk. The author is not liable for any damages that may have been caused by using this software. ===================================================================== INTRODUCTION ============ Have you ever wanted to write a program that runs in the CLI, taking input from the user and at the same time checking for other things, like signals and messages from other processes? You found out that you couldn't use AmigaDOS's Read() function or C's built-in input functions, like scanf(), or getchar() to get the job done. Some of you may have tried using the WaitForChar() function in conjunction with the Read() function, but reading a line cannot be completed until the user presses the carriage return. I have writen numerous utilities for bulletin board systems (BBSs) and have found that using Read() or other synchronous input functions are inappropriate for such applications. These synchronous functions do not return until they accomplish their tasks. For example, if you send a break signal to a process to tell it to abort, and this process is getting input from the user, the program would not exit until the user has pressed a carriage return. This is a big problem if the BBS is attempting to terminate a user who is running this program and whose time has expired. This is where RawIN.lib comes in. It allows you to get input from the user and at the same time check for other special events (such as an abort signal). It also provides a set of command history routines. ===================================================================== USER MANUAL =========== Read the RawINTest.c file to get a better idea of how most of the following functions work together. You should put RawIN.lib into the directory where your other link-time libraries are. If you are using SAS/C, you can link the library with the following command line arguments: blink lib:c.o,prg.o to prg lib lib:RawIN.lib,lib:lc.lib,lib:amiga.lib To make your program systems friendly they should exit when a break signal (C) has been received or the end-of-file of standard input has been reached. You can check for the break signal by calling Wait(), SetSignal() or CheckSignal (OS 2.04). Note that only if you use RawIN.lib's functions will the LNF_BREAKC flag be set in the Line struture. For end-of-file of standard input, check the LNF_EOF flag. The autodocs are as follows. --------------------------------------------------------------------- NAME AllocLine -- Allocate a line structure to be used for raw input. SYNOPSIS line = AllocLine(buf_size,hist_size) struct Line *line; unsigned long buf_size; unsigned long hist_size; FUNCTIONS Allocate and prepare a line structure. Allocate all necessary buffers. Initialize all variables, etc. This routine must be the first one to be called before you can call any other RawIN.lib routines. EXAMPLE struct Line *line; if (!(line = AllocLine(512,100))) /* 512 char buffer, 10 history lines */ { printf("AllocLine() fails. :-(\n"); exit(10); } ... FreeLine(line); INPUT buf_size = Size to allocate for command buffer. hist_size = Number of history lines. The history buffers are not allocated at this point. RESULT line = Allocated Line structure. NULL if unsuccessful. SEE ALSO FreeLine --------------------------------------------------------------------- NAME BuildLine -- Inserts a character into the command buffer if applicable. Some control codes will change the state of the buffer. SYNOPSIS eol = BuildLine(line,max_chars,echo) BOOL eol; struct Line *line; long max_chars; BOOL echo FUNCTION This routine takes the input character in line->InputChar and stores it into the buffer and echoes it back onto the screen if the buffer is non-full. Control codes such as cursor movements will alter the state of the buffer. Read the "COMMAND LINE EDITING FEATURES" section for these codes. EXAMPLE struct Line *line; ... if (BuildLine(Output(),line,-1L)) printf("You've typed %s\n",line->buf); INPUTS line = The line structure in which the character is to affect. max_chars = The maximum number of characters the current command line can allow. If -1L, use the default. echo = If TRUE, output changes to the command line. RESULT eol = If TRUE, user has pressed a carriage return, and thus ending the command line. SEE ALSO ResetLine --------------------------------------------------------------------- NAME DeleteHistory -- Delete the specified history line. SYNOPSIS void DeleteHistory(line,num) struct Line *line; long num; FUNCTIONS Remove the specified history node from the history list. INPUT line = Line structure where the history list is found. num = History number to remove. The first one is 1, and the last one is -1L. RESULT none EXAMPLE struct Line *line; ... while(line->hist_linecount) /* delete all history lines */ DeleteHistory(line,1); SEE ALSO MakeHistory ShowHistory GetHistory --------------------------------------------------------------------- NAME FreeLine -- Deallocate all the buffers allocated by a Line structure. SYNOPSIS void FreeLine(line) struct Line *line; FUNCTIONS Simply free all the memory associated with a Line structure, including itself. If there is a read pending, wait for it to complete. INPUT line = Line structure whose contents to be freed. RESULT none SEE ALSO AllocLine --------------------------------------------------------------------- NAME GetHistory -- Travers the history list to find the specified history buffer. SYNOPSIS history = GetHistory(line,num) struct History *history; struct Line *line; long num; FUNCTIONS This routine will find the numbered history line buffer you specify. It will search through the whole history list. EXAMPLE struct Line *line; struct History *hist; ... if (hist = GetHistory(line,1L)) printf("The first history line is '%s'\n",hist->buf); else printf("No history.\n"); INPUTS line = The line structure to search for the specified history. num = The history number to search (starting from 1). RESULT history = Pointer to the history structure node if found, else NULL. EXAMPLE struct Line *line; struct History *history; ... history = GetHistory(line,1); if (history) printf("%s\n",history->buf); SEE ALSO MakeHistory ShowHistory DeleteHistory --------------------------------------------------------------------- NAME GetKey -- Get a character from the standard input if there is one, else return immediately. SYNOPSIS key = GetKey(line,caps,echo) char key; struct Line *line; BOOL caps; BOOL echo; FUNCTION Read a character from the standard input if possible, else return immediately. This is particular useful for "hot-keys" in menuing systems. INPUTS line = line structure caps = if TRUE capitalize the character typed. echo = if TRUE echo the character typed. RESULT key = if non-zero this is the character typed. SEE ALSO WaitKey --------------------------------------------------------------------- NAME KeyPressed -- Check if the user has pressed a key. SYNOPSIS pressed = KeyPressed(line); BOOL pressed; struct Line *line; FUNCTION After StartAsyncRead() has been called use this routine to check if any key has been pressed or end-of-file has been reached. If line->flag has LNF_EOF set then the file has reached end, in which case your program should exit. If a key is pressed it will be stored in line->InputChar. You should not use GetMsg(line->ReadReplyPort) or WaitPort(line->ReadReplyPort) because this routine does more than that, it sets important variables. After a key has been pressed call StartAsyncRead() for the next character to be read. INPUT line = line structure to check of any key presses. RESULT pressed = if TRUE a key has been pressed. Read line->InputChar for the character. SEE ALSO StartAsyncRead --------------------------------------------------------------------- NAME MakeHistory -- Add a buffer to the history list. SYNOPSIS void MakeHistory(line,buf,len) struct Line *line; char *buf; long len; FUNCTIONS This routine will add a new history line into history list. If the current number of history lines is at maximum, the oldest history line will be deleted, and the new one added. After the user enters a command line buffer, it automatically adds it to the history list, so you need not call this routine yourself. INPUT line = Line structure in which to put the new history. buf = Buffer to add to history list. len = Length of buffer, if -1L it'll use strlen(buf). If len == 0, buf is not added to the history list. RESULT none EXAMPLE struct Line *line; ... MakeHistory(line,"New history line coming in...",-1L); SEE ALSO DeleteHistory GetHistory ShowHistory --------------------------------------------------------------------- NAME PauseKey -- Check to see if the user has typed a character that should cause the standard output to pause. SYNOPSIS key = PauseKey(line,pause_key,unpause_key,pause_text) char key; struct Line *line; char pause_key; char unpause_key; char *pause_text; FUNCTION This routine is particular useful for checking if the user has pressed a key to pause of the output on the screen. When the user has pressed the pause key, this routine will not return until either the unpause key is pressed, a break signal is received, or the end-of-life is reached. If any exceptions occured, you should read line->flag. EXAMPLE int i; struct Line *line; ... printf("Press ^S to pause output, ^Q to resume.\n"); for (i = 0; i < 100; ++i) { printf("%ld\n",i); PauseKey(line,0x13,0x11,"[PAUSED]"); } INPUTS line = line structure. pause_key = the key the user needs to press to cause the routine to block until the unpause character is pressed. -1 if any key can be used to cause outputting to pause. unpause_key = the key the user needs to press to unblock the program when he/she has pressed the paused key. -1 if any key can be used to cause outputting to be unpaused. pause_text = text to display when the user has pressed the pause key. NULL if such output is not wanted. The text will be erased when the unpause key is pressed. RESULT key = if non-zero, the key the user typed when this routine is called. Generally, this character is the same as unpause_key, unless no pause key is pressed. SEE ALSO WaitKey GetKey --------------------------------------------------------------------- NAME RawGets -- Synchronously get a command buffer from the standard input handler. SYNOPSIS count = RawGets(line,buf,buflen,defsize,hotkey,caps,echo) long count; struct Line *line; char *buf; unsigned long buflen; unsigned long defsize; BOOL hotkey; BOOL caps; BOOL echo; FUNCTION Get a line of input from the user. This routine will not return until either the user has pressed a carriage return, the break signal is received, or end of file is reached. EXAMPLE void main(void) { char name[30], pass[30], comp[30], key[2]; printf("Enter your name => "); RawGets(name,30,0,FALSE,FALSE,TRUE); printf("Enter your password => "); RawGets(pass,30,0,FALSE,FALSE,FALSE); printf("Enter your computer type => "); strcpy(comp,"Amiga!"); /* if user just presses return, "Amiga!" is accepted */ RawGets(comp,30,strlen(comp),FALSE,FALSE,TRUE); printf("Press any key to continue..."); RawGets(key,2,0,TRUE,FALSE,FALSE); } INPUT buflen = Length of buffer, including the null-termination char. line = Line structure allocated by AllocLine(). defsize = The default size of the buffer to display. hotkey = If TRUE return when the user has typed one character. caps = If TRUE capitalizes everything the users types. echo = If TRUE echo back what the user typed. RESULT count = Number of characters entered by the user. 0 if the user pressed return on a blank line. -1 if failure, either due to EOF or signal break. --------------------------------------------------------------------- NAME RawMode -- Turn the standard input file handle into raw mode. SYNOPSIS void RawMode(line,raw) struct Line *line; BOOL raw; FUNCTION This routine sends a ACTION_SCREEN_MODE packet to the standard input file handle to tell it to go into raw mode if it's not already in raw mode. In raw mode, characters can be read one at a time, without making the user press return for the line to be accepted. You normally would not need to call this routine yourself as all of RawIN.lib's routines call it for you. EXAMPLE RawMode(line,FALSE); system("list c:"); INPUTS line = line structure. raw = if TRUE to go into raw mode, FALSE to go into cooked mode. RESULT none --------------------------------------------------------------------- NAME ResetLine -- Prepare a Line structure for the next use. SYNOPSIS void ResetLine(line) struct Line *line; FUNCTIONS Reset all indices, etc. so that Line structure can be used again. INPUT line = Line to reset. RESULT none --------------------------------------------------------------------- NAME ShowHistory -- Display any number of history lines in any range or order. SYNOPSIS void ShowHistory(line,hist_start,hist_lines,reverse) struct Line *line; long hist_start; long hist_lines; BOOL reverse; FUNCTIONS Display the numbered history lines in the order and range specified. If the order is reverse, the last line will be displayed first, and the first displayed last. INPUT line = Line structure where the history lines are found. hist_start = The location where history lines start to display. 1 is first, -1 is last. hist_lines = The number of history lines to display. If -1, display all. reverse = If TRUE then display in descending order, else otherwise. RESULT none SEE ALSO MakeHistory GetHistory DeleteHistory --------------------------------------------------------------------- NAME StartAsyncRead -- Start an asynchronous read from the standard input. SYNOPSIS void StartAsyncRead(line) struct Line *line; FUNCTION A ACTION_READ packet is sent to the input handler to tell it we want to get a character. Use KeyPressed() to check if the user has typed something or there is an EOF. Look at line->InputChar for the character returned. INPUTS line = line structure. RESULT none SEE ALSO KeyPressed --------------------------------------------------------------------- NAME WaitKey -- Get a character from the standard input. SYNOPSIS key = WaitKey(line,caps,echo) char key; struct Line *line; BOOL caps; BOOL echo; FUNCTION This routine will attempt to read a character from the standard input. Your program will be blocked until either a character is typed, a break signal is received, or end of file. This routine is particular useful for single character respones from the user. EXAMPLE struct Line *line; char key; ... printf("Press any key to continue..."); key = WaitKey(line,FALSE,FALSE); INPUTS line = line structure. caps = capitalizes the character typed. echo = if TRUE echo the character back, else don't echo. RESULT key = A non-zero ASCII character if successful. Otherwise, read line->flag for reason. SEE ALSO GetKey --------------------------------------------------------------------- ===================================================================== COMMAND LINE EDITING FEATURES ============================= Key ANSI Effect --------------------------------------------------------------------- Cursor-left ^[[D move one character to the left Cursor-right ^[[C move one character to the right Shift-cursor-left ^[[ A,^A move to the beginning of the line Shift-cursor-right ^[[ @,^Z move to the end of the line Backspace ^H delete last character Del 127 delete the character under the cursor Return/Enter ^M process command line ^W move cursor one tab stop to the right ^X delete current line ^K delete everything from the cursor forward to the end of the line ^U delete everything from the cursor backward to the start of the line Cursor-up ^[[A move backward in the history buffer (earlier lines) Cursor-down ^[[B move forward in the history buffer (latter lines) Shift-cursor-up ^[[T,^R search backward through history buffer for given command line or fragment Shift-cursor-down ^[[S move to the bottom of the history buffer, with cusor on blank line ^F move to last word ^G move to next word ^V move halfway backward toward the start of the line ^B move halfway forward toward the end of the line ^E delete the word under the cursor --------------------------------------------------------------------- NOTE: 1. ^x is Ctrl-x (Hold down the control "Ctrl" key and type x) 2. Some terminal programs do not support shifted cursor keys. ===================================================================== REQUIREMENTS ============ The test program and the library runs on any Amiga with OS 1.2 or higher. ===================================================================== LAST WORDS ========== No fee is required for usage of this program, but I will accept any donations of money. If you donate over $5 and request it, I will send you the latest version of RawIN.lib, including the source code. Please let me know if you find this library useful, so that will give me incentive to write other similiar libraries. Donations, comments, and bug reports should be sent to: Home Address: Sam Yee c/o Utilities 4595 Nanaimo St. Vancouver, B.C. Canada V5N-5J5 Internet: samy@sfu.ca (starting September '92) flui@sfu.ca (before September '92) FidoNet: 1:153/765 (Terra Firma BBS 604-434-3665)