readline() -- Editing Function (libedit)

Read and edit a line of input
char *readline(prompt)
char *prompt;

The function  readline() displays on the standard output  the text to which
prompt 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  <return>, readline()  returns  the line  of text  with the  trailing
newline removed.

readline() returns a pointer to  the newly entered line.  This return value
can be passed  to the function add_history(), which adds  it to an internal
``history'' buffer.  The user can  use a command within readline() recall a
saved line, re-edit it, and re-submit it.

readline() 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.

Editing Commands

readline() 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.

readline() recognizes the following editing commands:

<ctrl-A>
        Move the cursor to the beginning of the line.
<ctrl-B>
        Move the cursor one character to the left (backwards).
<ctrl-D>
        Delete the  character  under which  the cursor  is positioned  (the
        ``current character'').
<ctrl-E>
        Move the cursor to end of line.
<ctrl-F>
        Move the cursor one character to the right (forwards).
<ctrl-G>
        Ring the bell.
<ctrl-H>
        Delete  the  character  to  the left  of  the  cursor.   Note  that
        <ctrl-H> is  the  character that  normally is  output by  the
        <backspace> key.
<ctrl-I>
        Complete file name.  Note that <ctrl-I> is the character that
        normally is output by the <tab> key.
<ctrl-J>
        Submit the line  for processing.   Note that <ctrl-J>  is the
        character that normally is output by the <return> key.
<ctrl-K>
        Kill all text from the cursor to end of line.
<ctrl-L>
        Redisplay the line.
<ctrl-M>
        Submit  the  line  for processing.   Note  that  on  some  systems,
        <ctrl-M> is output by the <return> key.
<ctrl-N>
        Get the next line from the history buffer.
<ctrl-P>
        Get the previous line from the history buffer.
<ctrl-R>
        Search backwards through the history buffer for a given string.
<ctrl-T>
        Transpose the character over  the cursor with the  character to its
        left.
<ctrl-V>
        Insert next  character  into the  line,  even if  it  is a  control
        character.  Note that  under MicroEMACS,  this command is  bound to
        <ctrl-Q>.
<ctrl-W>
        Kill (wipe) all text from the cursor to the mark.
<ctrl-X><ctrl-X>
        Move the cursor from  current position to the  mark; reset the mark
        at the previous position of the cursor.
<ctrl-Y>
        Yank back the most recently killed text.
<ctrl-]>c
        Move the cursor forward to next character c.
<ctrl-?>
        Delete the character  under which  the cursor is  positioned.  This
        command is identical with  <ctrl-D>. Note that <ctrl-?>
        is the character that normally is output by the <del> key.
<ctrl-[>
        Begin  an  escape  sequence.   Note   that  <ctrl-[>  is  the
        character that normally is output by the <esc> key.
<esc><ctrl-H>
        Delete the previous word  (the word to the left  of the cursor).  A
        word is delineated by white space.
<esc><del>
        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.
<esc><space>
        Set the mark.
<esc>.
        Get the last (or n'th) word from previous line.
<esc>?
        Show possible completions.  This feature is detailed below.
<esc><
        Move the cursor to the beginning of the history buffer.
<esc>>
        Move the cursor to the end of the history buffer.
<esc>B
        Move the cursor backwards (to the left) by one word.
<esc>D
        Delete the word under which the cursor is positioned.
<esc>F
        Move the cursor forward (to the right) by one word.
<esc>L
        Make the current word lower case.
<esc>M
        Toggle displaying  eight-bit  characters  normally (meta-mode),  or
        displaying them prefixed with the string M-.  In the meta-mode, you
        can generate  characters  with  the top  bit  set  by pressing  the
        <alt> key with  an alphanumeric key; this  is interpreted the
        same as <esc><key>.
<esc>U
        Make the current word upper case.
<esc>Y
        Yank back the most recently killed text.
<esc>V
        Show the version of the library libedit.a.
<esc>W
        Make yankable all text from the cursor to the mark.
<esc>n
        Set the argument to integer n.
<esc>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 <esc>,  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  <return>  to submit  a line  for
processing, regardless of where on the line the cursor is positioned.

readline() has  a modest macro facility.  If  you type <esc> followed
by an upper-case letter,  then readline() reads the contents of environment
variable _C_ as if you had typed them at the keyboard.

readline() 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 readline() and then press the <tab> key, readline() completes as
much of the name as it  can -- in this case, by adding oherent. Because the
name  is not  unique, readline()  then beeps.   If you  press <esc>?,
readline()  displays  the  two choices.   If  you  then  enter a  tie-break
character  (in this  case,  `.'), followed  by  the <tab>  character,
readline() completes the file name for you.

Using Line Editing

To include readline()  in your program, simply call it  as you do any other
function.  You must link the library libedit.a into your program.

Example

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;
}

See Also

add_history(),
libedit

Notes

readline()  calls malloc()  to allocate  space for the  text that  the user
enters.  Therefore, an application must call free() to free this space when
it has finished with it.

readline() cannot handle lines longer than 80 characters.

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

© 2012 by Stephen A. Ness