     VRL(3)                                                     VRL(3)

     NAME
            vrl - command-line editing library

     SYNOPSIS
            char  *readline(prompt)
            char  *prompt;

            void  add_history(line)
            char  *line;

            int rl_reset_terminal(terminal_name)
            char *terminal_name;

     DESCRIPTION
            Vrl is a library that allows an application to read a line
            from the terminal,  giving  the  user  additional  editing
            capabilities like cursor movement, filename completion and
            command history.

            It is a kind of a lightweight version of the GNU  readline
            library,  having  the  necessary functions but smaller and
            faster (like Rick Salz' editline  library).  It  has  been
            developed to work with the rc-shell, but may be useful for
            other things as well.

            readline() will display the given prompt  on  the  screen,
            and allows the user to enter a line of text. When the user
            is done with it, the line will be returned to  the  caller
            with  the  trailing  newline  removed.  The  caller should
            free() the buffer afterward.  If  the  user  generates  an
            EOF, NULL is returned.

            add_history()  should  be used to add commands to the his-
            tory, readline() does not do that itself.

            Normally, the vrl library will check $TERM  and  $TERMCAP,
            and  reinitialise  if  either  of them changes. If a shell
            does not update these variables in its own environment, it
            should  use  rl_reset_terminal() to inform the vrl library
            about this.

            The vrl library will catch SIGWINCH so that it is informed
            of window size changes, and re-generates it just before it
            returns from readline().  The tty's susp,  intr  and  quit
            characters will generate SIGTSTP, SIGINT, and SIGQUIT just
            before returning an empty line to the caller.

     EDITING COMMANDS
            The available commands are listed below:

            ^A     Move to the start of the line

            ^B     Move cursor backward

     vrl-1.3                                                         1

     VRL(3)                                                     VRL(3)

            ^D     Delete char under cursor. If the line is empty  and
                   the  previous character typed was not a delete-char
                   command, EOF is generated.

            ^E     Move to the end of the line

            ^F     Move cursor forward

            ^H     Delete char left of cursor

            ^I     Apply filename completion to  the  word  under  the
                   cursor (^I is the [TAB] key)

            ^J     Accept  the  line  (^J  usually  corresponds to the
                   [NEWLINE] or [ENTER] key)

            ^K     Delete to the end of the line

            ^L     Redisplay the line

            ^M     Accept the line

            ^N     Display next history line

            ^O     Re-read the initialisation file

            ^P     Display previous history line

            ^R     Backward history search

            ^T     Transpose chars

            ^U     Kill the whole line

            ^V     Insert next character as is, even if it is  a  com-
                   mand

            ^W     Delete the word under the cursor

            ^?     Delete  char  under  the  cursor (^? usually corre-
                   sponds to the [DEL] key)

            ESC-ESC or ESC-?
                   List all possible completions without changing  the
                   command-line.

            ESC-*  Replace the expression with all matching filenames.

            ESC-v  Display the version of the vrl library on stdout

            In addition to this, the  following  keypad  and  keyboard
            function keys are recognised:

     vrl-1.3                                                         2

     VRL(3)                                                     VRL(3)

            Left-arrow
                   Move cursor backward

            Right-arrow
                   Move cursor forward

            Up-arrow
                   Display previous history line

            Down-arrow
                   Display next history line

            Delete-key
                   Delete char under cursor

            Backspace-key
                   Delete char left of cursor

            Insert-key
                   Toggle insert/overwrite mode

            Home-key
                   Move to the start of the line

            End-key
                   Move to the end of the line

            Lastly,  the  following  special  characters  (as set with
            stty(1) ) are recognised. They are ignored if they  happen
            to correspond to one of the built-in command characters.

            erase  Delete char left of cursor (usually ^H or ^?)

            kill   Kill the whole line (usually ^U)

            eof    Accept  the  line if it is not empty, EOF otherwise
                   (usually ^D)

            werase Delete the word under the cursor (usually ^W)

            lnext  Insert the next character as is (usually ^V)

            reprint
                   Redisplay the line (usually ^R)

            susp   Suspend the current process. Vrl will send a  SIGT-
                   STP  to the application, and readline() will return
                   an empty line (usually ^Z)

            intr   Interrupt the current process. Vrl will send a SIG-
                   INT  to the application, and readline() will return
                   an empty line (usually ^C)

            quit   Interrupt the current  process.  Vrl  will  send  a

     vrl-1.3                                                         3

     VRL(3)                                                     VRL(3)

                   SIGQUIT  to  the  application,  and readline() will
                   return an empty line (usually ^)

     FILENAME COMPLETION
            The filename completion function acts on  the  text  under
            the  cursor.  The  text may contain wildcards like '*' and
            '?', and environment variables are expanded,

            If the completion is unique, the text will be replaced  by
            the  filename.   If  the completion is ambiguous, the text
            will be replaced by the common prefix of all the  possible
            completions.  Whether they are listed is controlled by the
            "completion" flag described below.

     INITIALISATION FILE
            At startup, the vrl library will look  for  a  file  named
            .vrlrc in the user's home directory. This file should con-
            tain one keyword+value pair  per  line,  empty  lines  and
            lines starting with a '#' are ignored.

            The  '^O'  command (see above) can be used to force vrl to
            re-read this file.

            The following option keywords are recognised:

            beep on | off
                   If set to "on", vrl will beep  when  the  requested
                   operation   is  impossible,  setting  it  to  "off"
                   silences it. Default is "on".

            insertmode on | off
                   If "on", characters typed will be inserted. If  set
                   to  "off", new characters will overwrite the exist-
                   ing ones. Default is "on".

            histmax <num>
                   The maximum number of entries to store in the  com-
                   mand history.

            histmode all | norepeat | nodups
                   This  option  defines how commands are added to the
                   history. If set to "all", every  command  is  added
                   without  hesitation. When set to "norepeat", a com-
                   mand is only added if it is different from the pre-
                   vious  one. Lastly, when it is set to "nodups", the
                   command is added but all  previous  occurrences  in
                   the history are removed. Default is "norepeat".

            completion always | nochange | never
                   This  option  defines  what happens when a filename
                   completion is ambiguous. If set  to  "always",  all
                   alternatives  are  listed automatically, "nochange"
                   means that they are only listed when  the  filename
                   to  complete  didn't  change (i.e. it didn't become

     vrl-1.3                                                         4

     VRL(3)                                                     VRL(3)

                   longer), and setting it to "never" means that noth-
                   ing will be listed, ever. Default is "nochange".

            ansicursorkeys on | off
                   On  some  terminals  (e.g.  xterm),  you can't type
                   ahead with the cursor keys since they don't  gener-
                   ate  the  same sequence as when the keypad is acti-
                   vated. The symptom is that  instead  of  displaying
                   the  previous  command  on  cursor-up, ^[[A is dis-
                   played. Setting this option to "on" allows  vrl  to
                   recognise  ^[[A,  ^[[B,  ^[[C, and ^[[D as alterna-
                   tives for  cursor-up,  -down,  -right,  and  -left,
                   which makes type-ahead possible on a number of ter-
                   minals (e.g. xterm, vt100, ...). Default is "on".

     FILES
            $HOME/.vrlrc The user's personal initialisation file

     SEE ALSO
            editline(3), readline(3)

     AUTHOR
            Gert-Jan Vons <vons@usa.net>

     vrl-1.3                                                         5