rreeaaddlliinnee() -- Editing Function (libedit)

Read and edit a line of input
cchhaarr *rreeaaddlliinnee(_p_r_o_m_p_t)
cchhaarr *_p_r_o_m_p_t;

The function  rreeaaddlliinnee() displays on the standard output  the text to which
_p_r_o_m_p_t points,  then accepts what  the user types.   It lets the  user type
simple,  EMACS-style commands  to edit  what she has  typed; when  the user
types  <rreettuurrnn>, rreeaaddlliinnee()  returns  the line  of text  with the  trailing
newline removed.

rreeaaddlliinnee() returns a pointer to  the newly entered line.  This return value
can be passed  to the function aadddd_hhiissttoorryy(), which adds  it to an internal
``history'' buffer.  The user can  use a command within rreeaaddlliinnee() recall a
saved line, re-edit it, and re-submit it.

rreeaaddlliinnee() returns NULL  when the user types EOF, or  if it cannot allocate
space for  the line  of input.   Otherwise, it returns  the address  of the
edited string that the user input.

_E_d_i_t_i_n_g _C_o_m_m_a_n_d_s
rreeaaddlliinnee() provides  a simple, EMACS-like editing  interface.  You can type
control characters or escape sequences to  edit a line before it is sent to
the calling program, much like the EMACS editing feature of the Korn shell.

rreeaaddlliinnee() recognizes the following editing commands:

<ccttrrll-AA>
        Move the cursor to the beginning of the line.
<ccttrrll-BB>
        Move the cursor one character to the left (backwards).
<ccttrrll-DD>
        Delete the  character  under which  the cursor  is positioned  (the
        ``current character'').
<ccttrrll-EE>
        Move the cursor to end of line.
<ccttrrll-FF>
        Move the cursor one character to the right (forwards).
<ccttrrll-GG>
        Ring the bell.
<ccttrrll-HH>
        Delete the character to the left of the cursor.  Note that <ccttrrll-HH>
        is the character that normally is output by the <bbaacckkssppaaccee> key.
<ccttrrll-II>
        Complete file  name.   Note  that <ccttrrll-II>  is  the character  that
        normally is output by the <ttaabb> key.
<ccttrrll-JJ>
        Submit  the  line  for  processing.   Note  that  <ccttrrll-JJ>  is  the
        character that normally is output by the <rreettuurrnn> key.
<ccttrrll-KK>
        Kill all text from the cursor to end of line.
<ccttrrll-LL>
        Redisplay the line.
<ccttrrll-MM>
        Submit the line for processing.  Note  that on some systems, <ccttrrll-
        MM> is output by the <rreettuurrnn> key.
<ccttrrll-NN>
        Get the next line from the history buffer.
<ccttrrll-PP>
        Get the previous line from the history buffer.
<ccttrrll-RR>
        Search backwards through the history buffer for a given string.
<ccttrrll-TT>
        Transpose the character over  the cursor with the  character to its
        left.
<ccttrrll-VV>
        Insert next  character  into the  line,  even if  it  is a  control
        character.  Note that  under MicroEMACS,  this command is  bound to
        <ccttrrll-QQ>.
<ccttrrll-WW>
        Kill (wipe) all text from the cursor to the mark.
<ccttrrll-XX><ccttrrll-XX>
        Move the cursor from  current position to the  mark; reset the mark
        at the previous position of the cursor.
<ccttrrll-YY>
        Yank back the most recently killed text.
<ccttrrll-]>_c
        Move the cursor forward to next character _c.
<ccttrrll-?>
        Delete the character  under which  the cursor is  positioned.  This
        command is  identical  with  <ccttrrll-DD>. Note  that  <ccttrrll-?> is  the
        character that normally is output by the <ddeell> key.
<ccttrrll-[>
        Begin an escape sequence.  Note that <ccttrrll-[> is the character that
        normally is output by the <eesscc> key.
<eesscc><ccttrrll-HH>
        Delete the previous word  (the word to the left  of the cursor).  A
        word is delineated by white space.
<eesscc><ddeell>
        Delete the current word  -- that is, from the cursor  to the end of
        the word as delineated by white space or the end of the line.
<eesscc><ssppaaccee>
        Set the mark.
<eesscc>.  Get the last (or _n'th) word from previous line.
<eesscc>?  Show possible completions.  This feature is detailed below.
<eesscc><  Move the cursor to the beginning of the history buffer.
<eesscc>>  Move the cursor to the end of the history buffer.
<eesscc>BB  Move the cursor backwards (to the left) by one word.
<eesscc>DD  Delete the word under which the cursor is positioned.
<eesscc>FF  Move the cursor forward (to the right) by one word.
<eesscc>LL  Make the current word lower case.
<eesscc>MM  Toggle displaying  eight-bit  characters  normally (meta-mode),  or
        displaying them prefixed with the string MM-.  In the meta-mode, you
        can generate characters with the top  bit set by pressing the <aalltt>
        key with  an  alphanumeric key;  this  is interpreted  the same  as
        <eesscc><_k_e_y>.
<eesscc>UU  Make the current word upper case.
<eesscc>YY  Yank back the most recently killed text.
<eesscc>VV  Show the version of the library lliibbeeddiitt.aa.
<eesscc>WW  Make yankable all text from the cursor to the mark.
<eesscc>_n  Set the argument to integer _n.
<eesscc>_C  Read input from environment variable __C_,  where _C is an upper-case
        letter.

Most editing  commands can be given  an argument _n, where  _n is an integer.
To enter a  numeric argument, type <eesscc>, the number,  and then the command
to execute.  For example,

    <esc> 4 <ctrl-F>

moves the cursor four characters forward.

Note that you can type an editing command on the line of input, not just at
the  beginning.  Likewise,  you  can type  <rreettuurrnn>  to submit  a line  for
processing, regardless of where on the line the cursor is positioned.

rreeaaddlliinnee() has a  modest macro facility.  If you type  <eesscc> followed by an
upper-case  letter,  then  rreeaaddlliinnee()  reads  the contents  of  environment
variable __C_ as if you had typed them at the keyboard.

rreeaaddlliinnee() also  can complete a  file name.  For example,  suppose that the
root directory contains the following files:

    coherent
    coherent.old

If you type

    rm /c

into rreeaaddlliinnee() and then press  the <ttaabb> key, rreeaaddlliinnee() completes as much
of the name as it can  -- in this case, by adding oohheerreenntt. Because the name
is  not unique,  rreeaaddlliinnee() then  beeps.  If  you press  <eesscc>?, rreeaaddlliinnee()
displays the two choices.  If you then enter a tie-break character (in this
case, `.'), followed by  the <ttaabb> character, rreeaaddlliinnee() completes the file
name for you.

_U_s_i_n_g _L_i_n_e _E_d_i_t_i_n_g
To include rreeaaddlliinnee()  in your program, simply call it  as you do any other
function.  You must link the library lliibbeeddiitt.aa into your program.

_E_x_a_m_p_l_e
The following  brief example lets  you enter a  line and edit  it, and then
displays it.

#include <stdlib.h>

extern char *readline();
extern void add_history();

int main(ac, av)
int ac; char *av[];
{
    char *p;

    while ((p = readline ("Enter a line:")) != NULL) {
        (void) printf ("%s\n", p);
        add_history (p);
        free (p);
    }
    return 0;
}

_S_e_e _A_l_s_o
aadddd_hhiissttoorryy(), lliibbeeddiitt

_N_o_t_e_s
rreeaaddlliinnee()  calls mmaalllloocc()  to allocate  space for the  text that  the user
enters.  Therefore, an application must call ffrreeee() to free this space when
it has finished with it.

rreeaaddlliinnee() cannot handle lines longer than 80 characters.

The   original   manual   page   was   written   by  David   W.   Sanderson
<dws@ssec.wisc.edu>.
