home | help 
GETLINE(3)		    Library Functions Manual		      GETLINE(3)

NAME
     getline - command-line editing library with history

SYNOPSIS
     char *getline(char *prompt);

     void gl_histadd(char *line);
     void gl_setwidth(int width);
     void gl_strwidth(int (*width_func)());

     extern int (*gl_in_hook)(char *buf);
     extern int (*gl_out_hook)(char *buf);
     extern int (*gl_tab_hook)(char *buf, int prompt_width, int *cursor_loc);

DESCRIPTION
     The getline package is a set of library routines that implement an editable
     command-line history.

     Programming Interface
     getline  returns  a pointer to a line of text read from the user, prompting
     the user with the specified prompt.  The pointer refers to a static  buffer
     allocated by the getline package.	Clients may assume that the pointer get-
     line returns is always the same, and is never NULL.  The buffer getline re-
     turns  to	the caller contains the terminating newline character, except on
     end of file, in which case the first character in the buffer  is  0  (NUL).
     File  descriptors	0  and	1  must  be connected to the terminal (not redi-
     rected), so the caller should check for this condition (using isatty()) and
     call stdio routines if the session is not interactive.

     gl_histadd adds the given line to the getline history list if the	line  is
     not empty and if it is different from the last line in the history list (so
     the  caller need not check for these conditions).	gl_histadd makes its own
     copies of all the lines it adds to the history list.  This is so the caller
     can reuse the buffer it supplies to gl_histadd.

     gl_setwidth specifies the terminal width to use for  horizontal  scrolling.
     The  default  value  is 80 columns, and it is important to properly specify
     the width or lines may wrap inadvertently.

     gl_strwidth allows the application program to supply a prompt string  width
     calculation  function  that  returns the number of screen positions used by
     the argument string.  By default strlen is used, but if the prompt contains
     escape sequences the user can bind a function that returns the actual  num-
     ber of screen postitions used by the argument string, not including the es-
     cape characters.

     In  addition  to  the function call interface, getline has three externally
     accessible function pointers that act as hooks  if  bound	to  user-defined
     functions.   getline  supplies  each of the functions with a pointer to the
     current buffer as the first argument, and expects the return  value  to  be
     the index of the first change the function made in the buffer (or -1 if the
     function  did  not  alter the buffer).  After the functions return, getline
     updates the screen as necessary.  Note that the functions may not alter the
     size of the buffer.  Indeed, they do not even know how large the buffer is!

     getline calls gl_in_hook (initially NULL) each time it loads a new  buffer.
     More precisely, this is

     *	    at the first call to getline (with an empty buffer)

     *	    each  time	the user enters a new buffer from the history list (with
	    ^P or ^N)

     *	    when the user accepts an incremental search string	(when  the  user
	    terminates the search).

     getline  calls  gl_out_hook (initially NULL) when a line has been completed
     by the user entering a NEWLINE (^J) or RETURN (^M).  The buffer gl_out_hook
     sees does not yet have the newline appended, and gl_out_hook should not add
     a newline.

     getline calls gl_tab_hook whenever the user types a TAB.	In  addition  to
     the  buffer,  getline  supplies the current prompt_width (presumably needed
     for tabbing calculations) and cursor_loc, a pointer to the cursor location.
     (*cursor_loc = 0 corresponds to the first character in  the  buffer)  *cur-
     sor_loc  tells  gl_tab_hook where the TAB was typed.  Note that when it re-
     draws the screen, getline will honor any change  gl_tab_hook  may	make  to
     *cursor_loc.   Note also that prompt_width may not correspond to the actual
     width of  prompt  on  the	screen	if  prompt  contains  escape  sequences.
     gl_tab_hook  is  initially  bound	to  the getline internal static function
     gl_tab, which acts like a normal TAB key by inserting spaces.

     User Interface
     To edit, the user moves the cursor to the point needing correction and then
     inserts or deletes characters or words as needed.	All the editing commands
     are control characters, which typed by holding the CTRL key down while typ-
     ing another character.  Control characters are indicated below as the caret
     (^) followed by another character, such as ^A.

     All edit commands operate from any place on the line, not just at	the  be-
     ginning.

     These are the getline key bindings.

	    ^A	 Move cursor to beginning of line.
	    ^B	 Move cursor left (back) 1 column.
	 ESC-B	 Move cursor back one word.
	    ^D	 Delete the character under the cursor.
	    ^E	 Move cursor to end of line.
	    ^F	 Move cursor right (forward) 1 column.
	 ESC-F	 Move cursor forward one word.
	    ^H	 Delete the character left of the cursor.@
	    ^I	 Jump to next tab stop (may be redefined by the program).
	    ^J	 Return the current line.
	    ^K	 Kill from cursor to the end of the line (see ^Y).
	    ^L	 Redisplay current line.
	    ^M	 Return the current line.
	    ^N	 Fetches next line from the history list.
	    ^O	 Toggle overwrite/insert mode, initially in insert mode.
	    ^P	 Fetches previous line from the history list.
	    ^R	 Begin	a reverse incremental search through history list.  Each
		 printing character typed adds to  the	search	substring  (ini-
		 tially  empty), and getline finds and displays the first match-
		 ing location.	Typing ^R again marks the current starting loca-
		 tion and begins a new search for the current substring.  Typing
		 ^H or DEL deletes the last character from  the  search  string,
		 and  getline  restarts  the search from the last starting loca-
		 tion.	Repeated ^H or DEL characters therefore appear to unwind
		 the search to the match nearest the point where the  user  last
		 typed	^R  or	^S.  Typing ^H or DEL until the search string is
		 empty causes getline to reset the start of the  search  to  the
		 beginning of the history list.  Typing ESC or any other editing
		 character accepts the current match and terminates the search.
	    ^S	 Begin	a  forward  incremental search through the history list.
		 The behavior is like that of ^R but in the  opposite  direction
		 through the history list.
	    ^T	 Transpose current and previous character.
	    ^U	 Kill the entire line (see ^Y).
	    ^Y	 Yank previously killed text back at current location.
     BACKSPACE	 Delete the character left of the cursor.
	   DEL	 Delete the character left of the cursor.
	RETURN	 Return the current line.
	   TAB	 Jump to next tab stop (may be redefined by the program).

     getline  recognizes  DOS and ANSI arrow keys.  They cause the following ac-
     tions: up is the same as ^P, down is the same as ^N, left is  the	same  as
     ^P, and right is the same as ^F.

AUTHORS
     Program by Christopher R. Thewalt (thewalt@ce.berkeley.edu)

     Original  man  page by DaviD W. Sanderson (dws@cs.wisc.edu) and Christopher
     R. Thewalt

COPYRIGHT

     (C) Copyright 1992,1993 by Christopher R. Thewalt and  DaviD  W.  Sanderson
     (but freely redistributable)

								      GETLINE(3)
home | help