Imported from ../bash-1.14.7.tar.gz.
This commit is contained in:
Jari Aalto
55
lib/readline/doc/Makefile
Normal file
55
lib/readline/doc/Makefile
Normal file
@@ -0,0 +1,55 @@
|
||||
# This makefile for History library documentation is in -*- text -*- mode.
|
||||
# Emacs likes it that way.
|
||||
|
||||
DOC_SUPPORT = ../../doc-support/
|
||||
TEXINDEX = $(DOC_SUPPORT)/texindex
|
||||
|
||||
TEX = tex
|
||||
|
||||
RLSRC = rlman.texinfo rluser.texinfo rltech.texinfo
|
||||
HISTSRC = hist.texinfo hsuser.texinfo hstech.texinfo
|
||||
|
||||
DVIOBJ = readline.dvi history.dvi
|
||||
INFOOBJ = readline.info history.info
|
||||
PSOBJ = readline.ps history.ps
|
||||
|
||||
all: info dvi
|
||||
|
||||
readline.dvi: $(RLSRC)
|
||||
$(TEX) rlman.texinfo
|
||||
$(TEXINDEX) rlman.??
|
||||
$(TEX) rlman.texinfo
|
||||
mv rlman.dvi readline.dvi
|
||||
|
||||
readline.info: $(RLSRC)
|
||||
makeinfo rlman.texinfo
|
||||
|
||||
history.dvi: ${HISTSRC}
|
||||
$(TEX) hist.texinfo
|
||||
$(TEXINDEX) hist.??
|
||||
$(TEX) hist.texinfo
|
||||
mv hist.dvi history.dvi
|
||||
|
||||
history.info: ${HISTSRC}
|
||||
makeinfo hist.texinfo
|
||||
|
||||
readline.ps: readline.dvi
|
||||
dvips -D 300 -o $@ readline.dvi
|
||||
|
||||
history.ps: history.dvi
|
||||
dvips -D 300 -o $@ history.dvi
|
||||
|
||||
info: $(INFOOBJ)
|
||||
dvi: $(DVIOBJ)
|
||||
ps: $(PSOBJ)
|
||||
|
||||
|
||||
$(TEXINDEX):
|
||||
(cd $(DOC_SUPPORT); $(MAKE) $(MFLAGS) CFLAGS='$(CFLAGS)' texindex)
|
||||
|
||||
distclean mostlyclean clean:
|
||||
rm -f *.aux *.cp *.fn *.ky *.log *.pg *.toc *.tp *.vr *.cps *.pgs \
|
||||
*.fns *.kys *.tps *.vrs *.o core
|
||||
|
||||
maintainer-clean realclean: clean
|
||||
rm -f *.dvi *.info *.info-* *.ps
|
||||
113
lib/readline/doc/hist.texinfo
Normal file
113
lib/readline/doc/hist.texinfo
Normal file
@@ -0,0 +1,113 @@
|
||||
\input texinfo @c -*-texinfo-*-
|
||||
@c %**start of header (This is for running Texinfo on a region.)
|
||||
@setfilename history.info
|
||||
@settitle GNU History Library
|
||||
@c %**end of header (This is for running Texinfo on a region.)
|
||||
|
||||
@setchapternewpage odd
|
||||
|
||||
@ignore
|
||||
last change: Wed Jul 20 09:57:17 EDT 1994
|
||||
@end ignore
|
||||
|
||||
@set EDITION 2.0
|
||||
@set VERSION 2.0
|
||||
@set UPDATED 20 July 1994
|
||||
@set UPDATE-MONTH July 1994
|
||||
|
||||
@ifinfo
|
||||
This document describes the GNU History library, a programming tool that
|
||||
provides a consistent user interface for recalling lines of previously
|
||||
typed input.
|
||||
|
||||
Copyright (C) 1988, 1991 Free Software Foundation, Inc.
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of
|
||||
this manual provided the copyright notice and this permission notice
|
||||
pare preserved on all copies.
|
||||
|
||||
@ignore
|
||||
Permission is granted to process this file through TeX and print the
|
||||
results, provided the printed document carries copying permission
|
||||
notice identical to this one except for the removal of this paragraph
|
||||
(this paragraph not being relevant to the printed manual).
|
||||
@end ignore
|
||||
|
||||
Permission is granted to copy and distribute modified versions of this
|
||||
manual under the conditions for verbatim copying, provided that the entire
|
||||
resulting derived work is distributed under the terms of a permission
|
||||
notice identical to this one.
|
||||
|
||||
Permission is granted to copy and distribute translations of this manual
|
||||
into another language, under the above conditions for modified versions,
|
||||
except that this permission notice may be stated in a translation approved
|
||||
by the Foundation.
|
||||
@end ifinfo
|
||||
|
||||
@titlepage
|
||||
@sp 10
|
||||
@title GNU History Library
|
||||
@subtitle Edition @value{EDITION}, for @code{History Library} Version @value{VERSION}.
|
||||
@subtitle @value{UPDATE-MONTH}
|
||||
@author Brian Fox, Free Software Foundation
|
||||
@author Chet Ramey, Case Western Reserve University
|
||||
|
||||
@page
|
||||
This document describes the GNU History library, a programming tool that
|
||||
provides a consistent user interface for recalling lines of previously
|
||||
typed input.
|
||||
|
||||
Published by the Free Software Foundation @*
|
||||
675 Massachusetts Avenue, @*
|
||||
Cambridge, MA 02139 USA
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of
|
||||
this manual provided the copyright notice and this permission notice
|
||||
are preserved on all copies.
|
||||
|
||||
Permission is granted to copy and distribute modified versions of this
|
||||
manual under the conditions for verbatim copying, provided that the entire
|
||||
resulting derived work is distributed under the terms of a permission
|
||||
notice identical to this one.
|
||||
|
||||
Permission is granted to copy and distribute translations of this manual
|
||||
into another language, under the above conditions for modified versions,
|
||||
except that this permission notice may be stated in a translation approved
|
||||
by the Foundation.
|
||||
|
||||
@vskip 0pt plus 1filll
|
||||
Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
|
||||
@end titlepage
|
||||
|
||||
@ifinfo
|
||||
@node Top
|
||||
@top GNU History Library
|
||||
|
||||
This document describes the GNU History library, a programming tool that
|
||||
provides a consistent user interface for recalling lines of previously
|
||||
typed input.
|
||||
|
||||
@menu
|
||||
* Using History Interactively:: GNU History User's Manual.
|
||||
* Programming with GNU History:: GNU History Programmer's Manual.
|
||||
* Concept Index:: Index of concepts described in this manual.
|
||||
* Function and Variable Index:: Index of externally visible functions
|
||||
and variables.
|
||||
@end menu
|
||||
@end ifinfo
|
||||
|
||||
@syncodeindex fn vr
|
||||
|
||||
@include hsuser.texinfo
|
||||
@include hstech.texinfo
|
||||
|
||||
@node Concept Index
|
||||
@appendix Concept Index
|
||||
@printindex cp
|
||||
|
||||
@node Function and Variable Index
|
||||
@appendix Function and Variable Index
|
||||
@printindex vr
|
||||
|
||||
@contents
|
||||
@bye
|
||||
BIN
lib/readline/doc/history.dvi
Normal file
BIN
lib/readline/doc/history.dvi
Normal file
Binary file not shown.
744
lib/readline/doc/history.info
Normal file
744
lib/readline/doc/history.info
Normal file
@@ -0,0 +1,744 @@
|
||||
This is Info file history.info, produced by Makeinfo-1.55 from the
|
||||
input file hist.texinfo.
|
||||
|
||||
This document describes the GNU History library, a programming tool
|
||||
that provides a consistent user interface for recalling lines of
|
||||
previously typed input.
|
||||
|
||||
Copyright (C) 1988, 1991 Free Software Foundation, Inc.
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of this
|
||||
manual provided the copyright notice and this permission notice pare
|
||||
preserved on all copies.
|
||||
|
||||
Permission is granted to copy and distribute modified versions of
|
||||
this manual under the conditions for verbatim copying, provided that
|
||||
the entire resulting derived work is distributed under the terms of a
|
||||
permission notice identical to this one.
|
||||
|
||||
Permission is granted to copy and distribute translations of this
|
||||
manual into another language, under the above conditions for modified
|
||||
versions, except that this permission notice may be stated in a
|
||||
translation approved by the Foundation.
|
||||
|
||||
|
||||
File: history.info, Node: Top, Next: Using History Interactively, Prev: (DIR), Up: (DIR)
|
||||
|
||||
GNU History Library
|
||||
*******************
|
||||
|
||||
This document describes the GNU History library, a programming tool
|
||||
that provides a consistent user interface for recalling lines of
|
||||
previously typed input.
|
||||
|
||||
* Menu:
|
||||
|
||||
* Using History Interactively:: GNU History User's Manual.
|
||||
* Programming with GNU History:: GNU History Programmer's Manual.
|
||||
* Concept Index:: Index of concepts described in this manual.
|
||||
* Function and Variable Index:: Index of externally visible functions
|
||||
and variables.
|
||||
|
||||
|
||||
File: history.info, Node: Using History Interactively, Next: Programming with GNU History, Prev: Top, Up: Top
|
||||
|
||||
Using History Interactively
|
||||
***************************
|
||||
|
||||
This chapter describes how to use the GNU History Library
|
||||
interactively, from a user's standpoint. It should be considered a
|
||||
user's guide. For information on using the GNU History Library in your
|
||||
own programs, *note Programming with GNU History::..
|
||||
|
||||
* Menu:
|
||||
|
||||
* History Interaction:: What it feels like using History as a user.
|
||||
|
||||
|
||||
File: history.info, Node: History Interaction, Up: Using History Interactively
|
||||
|
||||
History Interaction
|
||||
===================
|
||||
|
||||
The History library provides a history expansion feature that is
|
||||
similar to the history expansion provided by `csh'. The following text
|
||||
describes the syntax used to manipulate the history information.
|
||||
|
||||
History expansion takes place in two parts. The first is to
|
||||
determine which line from the previous history should be used during
|
||||
substitution. The second is to select portions of that line for
|
||||
inclusion into the current one. The line selected from the previous
|
||||
history is called the "event", and the portions of that line that are
|
||||
acted upon are called "words". The line is broken into words in the
|
||||
same fashion that Bash does, so that several English (or Unix) words
|
||||
surrounded by quotes are considered as one word.
|
||||
|
||||
* Menu:
|
||||
|
||||
* Event Designators:: How to specify which history line to use.
|
||||
* Word Designators:: Specifying which words are of interest.
|
||||
* Modifiers:: Modifying the results of substitution.
|
||||
|
||||
|
||||
File: history.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
|
||||
|
||||
Event Designators
|
||||
-----------------
|
||||
|
||||
An event designator is a reference to a command line entry in the
|
||||
history list.
|
||||
|
||||
`!'
|
||||
Start a history substitution, except when followed by a space, tab,
|
||||
the end of the line, = or (.
|
||||
|
||||
`!!'
|
||||
Refer to the previous command. This is a synonym for `!-1'.
|
||||
|
||||
`!n'
|
||||
Refer to command line N.
|
||||
|
||||
`!-n'
|
||||
Refer to the command N lines back.
|
||||
|
||||
`!string'
|
||||
Refer to the most recent command starting with STRING.
|
||||
|
||||
`!?string'[`?']
|
||||
Refer to the most recent command containing STRING.
|
||||
|
||||
`!#'
|
||||
The entire command line typed so far.
|
||||
|
||||
`^string1^string2^'
|
||||
Quick Substitution. Repeat the last command, replacing STRING1
|
||||
with STRING2. Equivalent to `!!:s/string1/string2/'.
|
||||
|
||||
|
||||
File: history.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
|
||||
|
||||
Word Designators
|
||||
----------------
|
||||
|
||||
A : separates the event specification from the word designator. It
|
||||
can be omitted if the word designator begins with a ^, $, * or %.
|
||||
Words are numbered from the beginning of the line, with the first word
|
||||
being denoted by a 0 (zero).
|
||||
|
||||
`0 (zero)'
|
||||
The `0'th word. For many applications, this is the command word.
|
||||
|
||||
`n'
|
||||
The Nth word.
|
||||
|
||||
`^'
|
||||
The first argument; that is, word 1.
|
||||
|
||||
`$'
|
||||
The last argument.
|
||||
|
||||
`%'
|
||||
The word matched by the most recent `?string?' search.
|
||||
|
||||
`x-y'
|
||||
A range of words; `-Y' abbreviates `0-Y'.
|
||||
|
||||
`*'
|
||||
All of the words, except the `0'th. This is a synonym for `1-$'.
|
||||
It is not an error to use * if there is just one word in the event;
|
||||
the empty string is returned in that case.
|
||||
|
||||
`x*'
|
||||
Abbreviates `x-$'
|
||||
|
||||
`x-'
|
||||
Abbreviates `x-$' like `x*', but omits the last word.
|
||||
|
||||
|
||||
File: history.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
|
||||
|
||||
Modifiers
|
||||
---------
|
||||
|
||||
After the optional word designator, you can add a sequence of one or
|
||||
more of the following modifiers, each preceded by a :.
|
||||
|
||||
`h'
|
||||
Remove a trailing pathname component, leaving only the head.
|
||||
|
||||
`r'
|
||||
Remove a trailing suffix of the form `.'SUFFIX, leaving the
|
||||
basename.
|
||||
|
||||
`e'
|
||||
Remove all but the trailing suffix.
|
||||
|
||||
`t'
|
||||
Remove all leading pathname components, leaving the tail.
|
||||
|
||||
`p'
|
||||
Print the new command but do not execute it.
|
||||
|
||||
`s/old/new/'
|
||||
Substitute NEW for the first occurrence of OLD in the event line.
|
||||
Any delimiter may be used in place of /. The delimiter may be
|
||||
quoted in OLD and NEW with a single backslash. If & appears in
|
||||
NEW, it is replaced by OLD. A single backslash will quote the &.
|
||||
The final delimiter is optional if it is the last character on the
|
||||
input line.
|
||||
|
||||
`&'
|
||||
Repeat the previous substitution.
|
||||
|
||||
`g'
|
||||
Cause changes to be applied over the entire event line. Used in
|
||||
conjunction with `s', as in `gs/old/new/', or with `&'.
|
||||
|
||||
|
||||
File: history.info, Node: Programming with GNU History, Next: Concept Index, Prev: Using History Interactively, Up: Top
|
||||
|
||||
Programming with GNU History
|
||||
****************************
|
||||
|
||||
This chapter describes how to interface programs that you write with
|
||||
the GNU History Library. It should be considered a technical guide.
|
||||
For information on the interactive use of GNU History, *note Using
|
||||
History Interactively::..
|
||||
|
||||
* Menu:
|
||||
|
||||
* Introduction to History:: What is the GNU History library for?
|
||||
* History Storage:: How information is stored.
|
||||
* History Functions:: Functions that you can use.
|
||||
* History Variables:: Variables that control behaviour.
|
||||
* History Programming Example:: Example of using the GNU History Library.
|
||||
|
||||
|
||||
File: history.info, Node: Introduction to History, Next: History Storage, Up: Programming with GNU History
|
||||
|
||||
Introduction to History
|
||||
=======================
|
||||
|
||||
Many programs read input from the user a line at a time. The GNU
|
||||
History library is able to keep track of those lines, associate
|
||||
arbitrary data with each line, and utilize information from previous
|
||||
lines in composing new ones.
|
||||
|
||||
The programmer using the History library has available functions for
|
||||
remembering lines on a history list, associating arbitrary data with a
|
||||
line, removing lines from the list, searching through the list for a
|
||||
line containing an arbitrary text string, and referencing any line in
|
||||
the list directly. In addition, a history "expansion" function is
|
||||
available which provides for a consistent user interface across
|
||||
different programs.
|
||||
|
||||
The user using programs written with the History library has the
|
||||
benefit of a consistent user interface with a set of well-known
|
||||
commands for manipulating the text of previous lines and using that text
|
||||
in new commands. The basic history manipulation commands are similar to
|
||||
the history substitution provided by `csh'.
|
||||
|
||||
If the programmer desires, he can use the Readline library, which
|
||||
includes some history manipulation by default, and has the added
|
||||
advantage of command line editing.
|
||||
|
||||
|
||||
File: history.info, Node: History Storage, Next: History Functions, Prev: Introduction to History, Up: Programming with GNU History
|
||||
|
||||
History Storage
|
||||
===============
|
||||
|
||||
The history list is an array of history entries. A history entry is
|
||||
declared as follows:
|
||||
|
||||
typedef struct _hist_entry {
|
||||
char *line;
|
||||
char *data;
|
||||
} HIST_ENTRY;
|
||||
|
||||
The history list itself might therefore be declared as
|
||||
|
||||
HIST_ENTRY **the_history_list;
|
||||
|
||||
The state of the History library is encapsulated into a single
|
||||
structure:
|
||||
|
||||
/* A structure used to pass the current state of the history stuff around. */
|
||||
typedef struct _hist_state {
|
||||
HIST_ENTRY **entries; /* Pointer to the entries themselves. */
|
||||
int offset; /* The location pointer within this array. */
|
||||
int length; /* Number of elements within this array. */
|
||||
int size; /* Number of slots allocated to this array. */
|
||||
int flags;
|
||||
} HISTORY_STATE;
|
||||
|
||||
If the flags member includes `HS_STIFLED', the history has been
|
||||
stifled.
|
||||
|
||||
|
||||
File: history.info, Node: History Functions, Next: History Variables, Prev: History Storage, Up: Programming with GNU History
|
||||
|
||||
History Functions
|
||||
=================
|
||||
|
||||
This section describes the calling sequence for the various functions
|
||||
present in GNU History.
|
||||
|
||||
* Menu:
|
||||
|
||||
* Initializing History and State Management:: Functions to call when you
|
||||
want to use history in a
|
||||
program.
|
||||
* History List Management:: Functions used to manage the list
|
||||
of history entries.
|
||||
* Information About the History List:: Functions returning information about
|
||||
the history list.
|
||||
* Moving Around the History List:: Functions used to change the position
|
||||
in the history list.
|
||||
* Searching the History List:: Functions to search the history list
|
||||
for entries containing a string.
|
||||
* Managing the History File:: Functions that read and write a file
|
||||
containing the history list.
|
||||
* History Expansion:: Functions to perform csh-like history
|
||||
expansion.
|
||||
|
||||
|
||||
File: history.info, Node: Initializing History and State Management, Next: History List Management, Up: History Functions
|
||||
|
||||
Initializing History and State Management
|
||||
-----------------------------------------
|
||||
|
||||
This section describes functions used to initialize and manage the
|
||||
state of the History library when you want to use the history functions
|
||||
in your program.
|
||||
|
||||
- Function: void using_history ()
|
||||
Begin a session in which the history functions might be used. This
|
||||
initializes the interactive variables.
|
||||
|
||||
- Function: HISTORY_STATE * history_get_history_state ()
|
||||
Return a structure describing the current state of the input
|
||||
history.
|
||||
|
||||
- Function: void history_set_history_state (HISTORY_STATE *state)
|
||||
Set the state of the history list according to STATE.
|
||||
|
||||
|
||||
File: history.info, Node: History List Management, Next: Information About the History List, Prev: Initializing History and State Management, Up: History Functions
|
||||
|
||||
History List Management
|
||||
-----------------------
|
||||
|
||||
These functions manage individual entries on the history list, or set
|
||||
parameters managing the list itself.
|
||||
|
||||
- Function: void add_history (char *string)
|
||||
Place STRING at the end of the history list. The associated data
|
||||
field (if any) is set to `NULL'.
|
||||
|
||||
- Function: HIST_ENTRY * remove_history (int which)
|
||||
Remove history entry at offset WHICH from the history. The
|
||||
removed element is returned so you can free the line, data, and
|
||||
containing structure.
|
||||
|
||||
- Function: HIST_ENTRY * replace_history_entry (int which, char *line,
|
||||
char *data)
|
||||
Make the history entry at offset WHICH have LINE and DATA. This
|
||||
returns the old entry so you can dispose of the data. In the case
|
||||
of an invalid WHICH, a `NULL' pointer is returned.
|
||||
|
||||
- Function: void stifle_history (int max)
|
||||
Stifle the history list, remembering only the last MAX entries.
|
||||
|
||||
- Function: int unstifle_history ()
|
||||
Stop stifling the history. This returns the previous amount the
|
||||
history was stifled. The value is positive if the history was
|
||||
stifled, negative if it wasn't.
|
||||
|
||||
- Function: int history_is_stifled ()
|
||||
Returns non-zero if the history is stifled, zero if it is not.
|
||||
|
||||
|
||||
File: history.info, Node: Information About the History List, Next: Moving Around the History List, Prev: History List Management, Up: History Functions
|
||||
|
||||
Information About the History List
|
||||
----------------------------------
|
||||
|
||||
These functions return information about the entire history list or
|
||||
individual list entries.
|
||||
|
||||
- Function: HIST_ENTRY ** history_list ()
|
||||
Return a `NULL' terminated array of `HIST_ENTRY' which is the
|
||||
current input history. Element 0 of this list is the beginning of
|
||||
time. If there is no history, return `NULL'.
|
||||
|
||||
- Function: int where_history ()
|
||||
Returns the offset of the current history element.
|
||||
|
||||
- Function: HIST_ENTRY * current_history ()
|
||||
Return the history entry at the current position, as determined by
|
||||
`where_history ()'. If there is no entry there, return a `NULL'
|
||||
pointer.
|
||||
|
||||
- Function: HIST_ENTRY * history_get (int offset)
|
||||
Return the history entry at position OFFSET, starting from
|
||||
`history_base'. If there is no entry there, or if OFFSET is
|
||||
greater than the history length, return a `NULL' pointer.
|
||||
|
||||
- Function: int history_total_bytes ()
|
||||
Return the number of bytes that the primary history entries are
|
||||
using. This function returns the sum of the lengths of all the
|
||||
lines in the history.
|
||||
|
||||
|
||||
File: history.info, Node: Moving Around the History List, Next: Searching the History List, Prev: Information About the History List, Up: History Functions
|
||||
|
||||
Moving Around the History List
|
||||
------------------------------
|
||||
|
||||
These functions allow the current index into the history list to be
|
||||
set or changed.
|
||||
|
||||
- Function: int history_set_pos (int pos)
|
||||
Set the position in the history list to POS, an absolute index
|
||||
into the list.
|
||||
|
||||
- Function: HIST_ENTRY * previous_history ()
|
||||
Back up the current history offset to the previous history entry,
|
||||
and return a pointer to that entry. If there is no previous
|
||||
entry, return a `NULL' pointer.
|
||||
|
||||
- Function: HIST_ENTRY * next_history ()
|
||||
Move the current history offset forward to the next history entry,
|
||||
and return the a pointer to that entry. If there is no next
|
||||
entry, return a `NULL' pointer.
|
||||
|
||||
|
||||
File: history.info, Node: Searching the History List, Next: Managing the History File, Prev: Moving Around the History List, Up: History Functions
|
||||
|
||||
Searching the History List
|
||||
--------------------------
|
||||
|
||||
These functions allow searching of the history list for entries
|
||||
containing a specific string. Searching may be performed both forward
|
||||
and backward from the current history position. The search may be
|
||||
"anchored", meaning that the string must match at the beginning of the
|
||||
history entry.
|
||||
|
||||
- Function: int history_search (char *string, int direction)
|
||||
Search the history for STRING, starting at the current history
|
||||
offset. If DIRECTION < 0, then the search is through previous
|
||||
entries, else through subsequent. If STRING is found, then the
|
||||
current history index is set to that history entry, and the value
|
||||
returned is the offset in the line of the entry where STRING was
|
||||
found. Otherwise, nothing is changed, and a -1 is returned.
|
||||
|
||||
- Function: int history_search_prefix (char *string, int direction)
|
||||
Search the history for STRING, starting at the current history
|
||||
offset. The search is anchored: matching lines must begin with
|
||||
STRING. If DIRECTION < 0, then the search is through previous
|
||||
entries, else through subsequent. If STRING is found, then the
|
||||
current history index is set to that entry, and the return value
|
||||
is 0. Otherwise, nothing is changed, and a -1 is returned.
|
||||
|
||||
- Function: int history_search_pos (char *string, int direction, int
|
||||
pos)
|
||||
Search for STRING in the history list, starting at POS, an
|
||||
absolute index into the list. If DIRECTION is negative, the search
|
||||
proceeds backward from POS, otherwise forward. Returns the
|
||||
absolute index of the history element where STRING was found, or
|
||||
-1 otherwise.
|
||||
|
||||
|
||||
File: history.info, Node: Managing the History File, Next: History Expansion, Prev: Searching the History List, Up: History Functions
|
||||
|
||||
Managing the History File
|
||||
-------------------------
|
||||
|
||||
The History library can read the history from and write it to a file.
|
||||
This section documents the functions for managing a history file.
|
||||
|
||||
- Function: int read_history (char *filename)
|
||||
Add the contents of FILENAME to the history list, a line at a
|
||||
time. If FILENAME is `NULL', then read from `~/.history'.
|
||||
Returns 0 if successful, or errno if not.
|
||||
|
||||
- Function: int read_history_range (char *filename, int from, int to)
|
||||
Read a range of lines from FILENAME, adding them to the history
|
||||
list. Start reading at line FROM and end at TO. If FROM is zero,
|
||||
start at the beginning. If TO is less than FROM, then read until
|
||||
the end of the file. If FILENAME is `NULL', then read from
|
||||
`~/.history'. Returns 0 if successful, or `errno' if not.
|
||||
|
||||
- Function: int write_history (char *filename)
|
||||
Write the current history to FILENAME, overwriting FILENAME if
|
||||
necessary. If FILENAME is `NULL', then write the history list to
|
||||
`~/.history'. Values returned are as in `read_history ()'.
|
||||
|
||||
- Function: int append_history (int nelements, char *filename)
|
||||
Append the last NELEMENTS of the history list to FILENAME.
|
||||
|
||||
- Function: int history_truncate_file (char *filename, int nlines)
|
||||
Truncate the history file FILENAME, leaving only the last NLINES
|
||||
lines.
|
||||
|
||||
|
||||
File: history.info, Node: History Expansion, Prev: Managing the History File, Up: History Functions
|
||||
|
||||
History Expansion
|
||||
-----------------
|
||||
|
||||
These functions implement `csh'-like history expansion.
|
||||
|
||||
- Function: int history_expand (char *string, char **output)
|
||||
Expand STRING, placing the result into OUTPUT, a pointer to a
|
||||
string (*note History Interaction::.). Returns:
|
||||
`0'
|
||||
If no expansions took place (or, if the only change in the
|
||||
text was the de-slashifying of the history expansion
|
||||
character);
|
||||
|
||||
`1'
|
||||
if expansions did take place;
|
||||
|
||||
`-1'
|
||||
if there was an error in expansion;
|
||||
|
||||
`2'
|
||||
if the returned line should only be displayed, but not
|
||||
executed, as with the `:p' modifier (*note Modifiers::.).
|
||||
|
||||
If an error ocurred in expansion, then OUTPUT contains a
|
||||
descriptive error message.
|
||||
|
||||
- Function: char * history_arg_extract (int first, int last, char
|
||||
*string)
|
||||
Extract a string segment consisting of the FIRST through LAST
|
||||
arguments present in STRING. Arguments are broken up as in Bash.
|
||||
|
||||
- Function: char * get_history_event (char *string, int *cindex, int
|
||||
qchar)
|
||||
Returns the text of the history event beginning at STRING +
|
||||
*CINDEX. *CINDEX is modified to point to after the event
|
||||
specifier. At function entry, CINDEX points to the index into
|
||||
STRING where the history event specification begins. QCHAR is a
|
||||
character that is allowed to end the event specification in
|
||||
addition to the "normal" terminating characters.
|
||||
|
||||
- Function: char ** history_tokenize (char *string)
|
||||
Return an array of tokens parsed out of STRING, much as the shell
|
||||
might. The tokens are split on white space and on the characters
|
||||
`()<>;&|$', and shell quoting conventions are obeyed.
|
||||
|
||||
|
||||
File: history.info, Node: History Variables, Next: History Programming Example, Prev: History Functions, Up: Programming with GNU History
|
||||
|
||||
History Variables
|
||||
=================
|
||||
|
||||
This section describes the externally visible variables exported by
|
||||
the GNU History Library.
|
||||
|
||||
- Variable: int history_base
|
||||
The logical offset of the first entry in the history list.
|
||||
|
||||
- Variable: int history_length
|
||||
The number of entries currently stored in the history list.
|
||||
|
||||
- Variable: int max_input_history
|
||||
The maximum number of history entries. This must be changed using
|
||||
`stifle_history ()'.
|
||||
|
||||
- Variable: char history_expansion_char
|
||||
The character that starts a history event. The default is `!'.
|
||||
|
||||
- Variable: char history_subst_char
|
||||
The character that invokes word substitution if found at the start
|
||||
of a line. The default is `^'.
|
||||
|
||||
- Variable: char history_comment_char
|
||||
During tokenization, if this character is seen as the first
|
||||
character of a word, then it and all subsequent characters up to a
|
||||
newline are ignored, suppressing history expansion for the
|
||||
remainder of the line. This is disabled by default.
|
||||
|
||||
- Variable: char * history_no_expand_chars
|
||||
The list of characters which inhibit history expansion if found
|
||||
immediately following HISTORY_EXPANSION_CHAR. The default is
|
||||
whitespace and `='.
|
||||
|
||||
|
||||
File: history.info, Node: History Programming Example, Prev: History Variables, Up: Programming with GNU History
|
||||
|
||||
History Programming Example
|
||||
===========================
|
||||
|
||||
The following program demonstrates simple use of the GNU History
|
||||
Library.
|
||||
|
||||
main ()
|
||||
{
|
||||
char line[1024], *t;
|
||||
int len, done = 0;
|
||||
|
||||
line[0] = 0;
|
||||
|
||||
using_history ();
|
||||
while (!done)
|
||||
{
|
||||
printf ("history$ ");
|
||||
fflush (stdout);
|
||||
t = fgets (line, sizeof (line) - 1, stdin);
|
||||
if (t && *t)
|
||||
{
|
||||
len = strlen (t);
|
||||
if (t[len - 1] == '\n')
|
||||
t[len - 1] = '\0';
|
||||
}
|
||||
|
||||
if (!t)
|
||||
strcpy (line, "quit");
|
||||
|
||||
if (line[0])
|
||||
{
|
||||
char *expansion;
|
||||
int result;
|
||||
|
||||
result = history_expand (line, &expansion);
|
||||
if (result)
|
||||
fprintf (stderr, "%s\n", expansion);
|
||||
|
||||
if (result < 0 || result == 2)
|
||||
{
|
||||
free (expansion);
|
||||
continue;
|
||||
}
|
||||
|
||||
add_history (expansion);
|
||||
strncpy (line, expansion, sizeof (line) - 1);
|
||||
free (expansion);
|
||||
}
|
||||
|
||||
if (strcmp (line, "quit") == 0)
|
||||
done = 1;
|
||||
else if (strcmp (line, "save") == 0)
|
||||
write_history ("history_file");
|
||||
else if (strcmp (line, "read") == 0)
|
||||
read_history ("history_file");
|
||||
else if (strcmp (line, "list") == 0)
|
||||
{
|
||||
register HIST_ENTRY **the_list;
|
||||
register int i;
|
||||
|
||||
the_list = history_list ();
|
||||
if (the_list)
|
||||
for (i = 0; the_list[i]; i++)
|
||||
printf ("%d: %s\n", i + history_base, the_list[i]->line);
|
||||
}
|
||||
else if (strncmp (line, "delete", 6) == 0)
|
||||
{
|
||||
int which;
|
||||
if ((sscanf (line + 6, "%d", &which)) == 1)
|
||||
{
|
||||
HIST_ENTRY *entry = remove_history (which);
|
||||
if (!entry)
|
||||
fprintf (stderr, "No such entry %d\n", which);
|
||||
else
|
||||
{
|
||||
free (entry->line);
|
||||
free (entry);
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
fprintf (stderr, "non-numeric arg given to `delete'\n");
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
File: history.info, Node: Concept Index, Next: Function and Variable Index, Prev: Programming with GNU History, Up: Top
|
||||
|
||||
Concept Index
|
||||
*************
|
||||
|
||||
* Menu:
|
||||
|
||||
* anchored search: Searching the History List.
|
||||
* event designators: Event Designators.
|
||||
* expansion: History Interaction.
|
||||
* history events: Event Designators.
|
||||
* History Searching: Searching the History List.
|
||||
|
||||
|
||||
File: history.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top
|
||||
|
||||
Function and Variable Index
|
||||
***************************
|
||||
|
||||
* Menu:
|
||||
|
||||
* add_history: History List Management.
|
||||
* append_history: Managing the History File.
|
||||
* current_history: Information About the History List.
|
||||
* get_history_event: History Expansion.
|
||||
* history_arg_extract: History Expansion.
|
||||
* history_base: History Variables.
|
||||
* history_comment_char: History Variables.
|
||||
* history_expand: History Expansion.
|
||||
* history_expansion_char: History Variables.
|
||||
* history_get: Information About the History List.
|
||||
* history_get_history_state: Initializing History and State Management.
|
||||
* history_is_stifled: History List Management.
|
||||
* history_length: History Variables.
|
||||
* history_list: Information About the History List.
|
||||
* history_no_expand_chars: History Variables.
|
||||
* history_search: Searching the History List.
|
||||
* history_search_pos: Searching the History List.
|
||||
* history_search_prefix: Searching the History List.
|
||||
* history_set_history_state: Initializing History and State Management.
|
||||
* history_set_pos: Moving Around the History List.
|
||||
* history_subst_char: History Variables.
|
||||
* history_tokenize: History Expansion.
|
||||
* history_total_bytes: Information About the History List.
|
||||
* history_truncate_file: Managing the History File.
|
||||
* max_input_history: History Variables.
|
||||
* next_history: Moving Around the History List.
|
||||
* previous_history: Moving Around the History List.
|
||||
* read_history: Managing the History File.
|
||||
* read_history_range: Managing the History File.
|
||||
* remove_history: History List Management.
|
||||
* replace_history_entry: History List Management.
|
||||
* stifle_history: History List Management.
|
||||
* unstifle_history: History List Management.
|
||||
* using_history: Initializing History and State Management.
|
||||
* where_history: Information About the History List.
|
||||
* write_history: Managing the History File.
|
||||
|
||||
|
||||
|
||||
Tag Table:
|
||||
Node: Top975
|
||||
Node: Using History Interactively1569
|
||||
Node: History Interaction2077
|
||||
Node: Event Designators3122
|
||||
Node: Word Designators3952
|
||||
Node: Modifiers4936
|
||||
Node: Programming with GNU History6065
|
||||
Node: Introduction to History6791
|
||||
Node: History Storage8112
|
||||
Node: History Functions9205
|
||||
Node: Initializing History and State Management10176
|
||||
Node: History List Management10968
|
||||
Node: Information About the History List12396
|
||||
Node: Moving Around the History List13702
|
||||
Node: Searching the History List14587
|
||||
Node: Managing the History File16419
|
||||
Node: History Expansion17925
|
||||
Node: History Variables19769
|
||||
Node: History Programming Example21138
|
||||
Node: Concept Index23742
|
||||
Node: Function and Variable Index24223
|
||||
|
||||
End Tag Table
|
||||
2037
lib/readline/doc/history.ps
Normal file
2037
lib/readline/doc/history.ps
Normal file
File diff suppressed because it is too large
Load Diff
489
lib/readline/doc/hstech.texinfo
Normal file
489
lib/readline/doc/hstech.texinfo
Normal file
@@ -0,0 +1,489 @@
|
||||
@ignore
|
||||
This file documents the user interface to the GNU History library.
|
||||
|
||||
Copyright (C) 1988, 1991 Free Software Foundation, Inc.
|
||||
Authored by Brian Fox and Chet Ramey.
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of this manual
|
||||
provided the copyright notice and this permission notice are preserved on
|
||||
all copies.
|
||||
|
||||
Permission is granted to process this file through Tex and print the
|
||||
results, provided the printed document carries copying permission notice
|
||||
identical to this one except for the removal of this paragraph (this
|
||||
paragraph not being relevant to the printed manual).
|
||||
|
||||
Permission is granted to copy and distribute modified versions of this
|
||||
manual under the conditions for verbatim copying, provided also that the
|
||||
GNU Copyright statement is available to the distributee, and provided that
|
||||
the entire resulting derived work is distributed under the terms of a
|
||||
permission notice identical to this one.
|
||||
|
||||
Permission is granted to copy and distribute translations of this manual
|
||||
into another language, under the above conditions for modified versions.
|
||||
@end ignore
|
||||
|
||||
@node Programming with GNU History
|
||||
@chapter Programming with GNU History
|
||||
|
||||
This chapter describes how to interface programs that you write
|
||||
with the GNU History Library.
|
||||
It should be considered a technical guide.
|
||||
For information on the interactive use of GNU History, @pxref{Using
|
||||
History Interactively}.
|
||||
|
||||
@menu
|
||||
* Introduction to History:: What is the GNU History library for?
|
||||
* History Storage:: How information is stored.
|
||||
* History Functions:: Functions that you can use.
|
||||
* History Variables:: Variables that control behaviour.
|
||||
* History Programming Example:: Example of using the GNU History Library.
|
||||
@end menu
|
||||
|
||||
@node Introduction to History
|
||||
@section Introduction to History
|
||||
|
||||
Many programs read input from the user a line at a time. The GNU History
|
||||
library is able to keep track of those lines, associate arbitrary data with
|
||||
each line, and utilize information from previous lines in composing new
|
||||
ones.
|
||||
|
||||
The programmer using the History library has available functions
|
||||
for remembering lines on a history list, associating arbitrary data
|
||||
with a line, removing lines from the list, searching through the list
|
||||
for a line containing an arbitrary text string, and referencing any line
|
||||
in the list directly. In addition, a history @dfn{expansion} function
|
||||
is available which provides for a consistent user interface across
|
||||
different programs.
|
||||
|
||||
The user using programs written with the History library has the
|
||||
benefit of a consistent user interface with a set of well-known
|
||||
commands for manipulating the text of previous lines and using that text
|
||||
in new commands. The basic history manipulation commands are similar to
|
||||
the history substitution provided by @code{csh}.
|
||||
|
||||
If the programmer desires, he can use the Readline library, which
|
||||
includes some history manipulation by default, and has the added
|
||||
advantage of command line editing.
|
||||
|
||||
@node History Storage
|
||||
@section History Storage
|
||||
|
||||
The history list is an array of history entries. A history entry is
|
||||
declared as follows:
|
||||
|
||||
@example
|
||||
typedef struct _hist_entry @{
|
||||
char *line;
|
||||
char *data;
|
||||
@} HIST_ENTRY;
|
||||
@end example
|
||||
|
||||
The history list itself might therefore be declared as
|
||||
|
||||
@example
|
||||
HIST_ENTRY **the_history_list;
|
||||
@end example
|
||||
|
||||
The state of the History library is encapsulated into a single structure:
|
||||
|
||||
@example
|
||||
/* A structure used to pass the current state of the history stuff around. */
|
||||
typedef struct _hist_state @{
|
||||
HIST_ENTRY **entries; /* Pointer to the entries themselves. */
|
||||
int offset; /* The location pointer within this array. */
|
||||
int length; /* Number of elements within this array. */
|
||||
int size; /* Number of slots allocated to this array. */
|
||||
int flags;
|
||||
@} HISTORY_STATE;
|
||||
@end example
|
||||
|
||||
If the flags member includes @code{HS_STIFLED}, the history has been
|
||||
stifled.
|
||||
|
||||
@node History Functions
|
||||
@section History Functions
|
||||
|
||||
This section describes the calling sequence for the various functions
|
||||
present in GNU History.
|
||||
|
||||
@menu
|
||||
* Initializing History and State Management:: Functions to call when you
|
||||
want to use history in a
|
||||
program.
|
||||
* History List Management:: Functions used to manage the list
|
||||
of history entries.
|
||||
* Information About the History List:: Functions returning information about
|
||||
the history list.
|
||||
* Moving Around the History List:: Functions used to change the position
|
||||
in the history list.
|
||||
* Searching the History List:: Functions to search the history list
|
||||
for entries containing a string.
|
||||
* Managing the History File:: Functions that read and write a file
|
||||
containing the history list.
|
||||
* History Expansion:: Functions to perform csh-like history
|
||||
expansion.
|
||||
@end menu
|
||||
|
||||
@node Initializing History and State Management
|
||||
@subsection Initializing History and State Management
|
||||
|
||||
This section describes functions used to initialize and manage
|
||||
the state of the History library when you want to use the history
|
||||
functions in your program.
|
||||
|
||||
@deftypefun void using_history ()
|
||||
Begin a session in which the history functions might be used. This
|
||||
initializes the interactive variables.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {HISTORY_STATE *} history_get_history_state ()
|
||||
Return a structure describing the current state of the input history.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun void history_set_history_state (HISTORY_STATE *state)
|
||||
Set the state of the history list according to @var{state}.
|
||||
@end deftypefun
|
||||
|
||||
@node History List Management
|
||||
@subsection History List Management
|
||||
|
||||
These functions manage individual entries on the history list, or set
|
||||
parameters managing the list itself.
|
||||
|
||||
@deftypefun void add_history (char *string)
|
||||
Place @var{string} at the end of the history list. The associated data
|
||||
field (if any) is set to @code{NULL}.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {HIST_ENTRY *} remove_history (int which)
|
||||
Remove history entry at offset @var{which} from the history. The
|
||||
removed element is returned so you can free the line, data,
|
||||
and containing structure.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {HIST_ENTRY *} replace_history_entry (int which, char *line, char *data)
|
||||
Make the history entry at offset @var{which} have @var{line} and @var{data}.
|
||||
This returns the old entry so you can dispose of the data. In the case
|
||||
of an invalid @var{which}, a @code{NULL} pointer is returned.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun void stifle_history (int max)
|
||||
Stifle the history list, remembering only the last @var{max} entries.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int unstifle_history ()
|
||||
Stop stifling the history. This returns the previous amount the
|
||||
history was stifled. The value is positive if the history was
|
||||
stifled, negative if it wasn't.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int history_is_stifled ()
|
||||
Returns non-zero if the history is stifled, zero if it is not.
|
||||
@end deftypefun
|
||||
|
||||
@node Information About the History List
|
||||
@subsection Information About the History List
|
||||
|
||||
These functions return information about the entire history list or
|
||||
individual list entries.
|
||||
|
||||
@deftypefun {HIST_ENTRY **} history_list ()
|
||||
Return a @code{NULL} terminated array of @code{HIST_ENTRY} which is the
|
||||
current input history. Element 0 of this list is the beginning of time.
|
||||
If there is no history, return @code{NULL}.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int where_history ()
|
||||
Returns the offset of the current history element.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {HIST_ENTRY *} current_history ()
|
||||
Return the history entry at the current position, as determined by
|
||||
@code{where_history ()}. If there is no entry there, return a @code{NULL}
|
||||
pointer.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {HIST_ENTRY *} history_get (int offset)
|
||||
Return the history entry at position @var{offset}, starting from
|
||||
@code{history_base}. If there is no entry there, or if @var{offset}
|
||||
is greater than the history length, return a @code{NULL} pointer.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int history_total_bytes ()
|
||||
Return the number of bytes that the primary history entries are using.
|
||||
This function returns the sum of the lengths of all the lines in the
|
||||
history.
|
||||
@end deftypefun
|
||||
|
||||
@node Moving Around the History List
|
||||
@subsection Moving Around the History List
|
||||
|
||||
These functions allow the current index into the history list to be
|
||||
set or changed.
|
||||
|
||||
@deftypefun int history_set_pos (int pos)
|
||||
Set the position in the history list to @var{pos}, an absolute index
|
||||
into the list.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {HIST_ENTRY *} previous_history ()
|
||||
Back up the current history offset to the previous history entry, and
|
||||
return a pointer to that entry. If there is no previous entry, return
|
||||
a @code{NULL} pointer.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {HIST_ENTRY *} next_history ()
|
||||
Move the current history offset forward to the next history entry, and
|
||||
return the a pointer to that entry. If there is no next entry, return
|
||||
a @code{NULL} pointer.
|
||||
@end deftypefun
|
||||
|
||||
@node Searching the History List
|
||||
@subsection Searching the History List
|
||||
@cindex History Searching
|
||||
|
||||
These functions allow searching of the history list for entries containing
|
||||
a specific string. Searching may be performed both forward and backward
|
||||
from the current history position. The search may be @dfn{anchored},
|
||||
meaning that the string must match at the beginning of the history entry.
|
||||
@cindex anchored search
|
||||
|
||||
@deftypefun int history_search (char *string, int direction)
|
||||
Search the history for @var{string}, starting at the current history
|
||||
offset. If @var{direction} < 0, then the search is through previous entries,
|
||||
else through subsequent. If @var{string} is found, then
|
||||
the current history index is set to that history entry, and the value
|
||||
returned is the offset in the line of the entry where
|
||||
@var{string} was found. Otherwise, nothing is changed, and a -1 is
|
||||
returned.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int history_search_prefix (char *string, int direction)
|
||||
Search the history for @var{string}, starting at the current history
|
||||
offset. The search is anchored: matching lines must begin with
|
||||
@var{string}. If @var{direction} < 0, then the search is through previous
|
||||
entries, else through subsequent. If @var{string} is found, then the
|
||||
current history index is set to that entry, and the return value is 0.
|
||||
Otherwise, nothing is changed, and a -1 is returned.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int history_search_pos (char *string, int direction, int pos)
|
||||
Search for @var{string} in the history list, starting at @var{pos}, an
|
||||
absolute index into the list. If @var{direction} is negative, the search
|
||||
proceeds backward from @var{pos}, otherwise forward. Returns the absolute
|
||||
index of the history element where @var{string} was found, or -1 otherwise.
|
||||
@end deftypefun
|
||||
|
||||
@node Managing the History File
|
||||
@subsection Managing the History File
|
||||
|
||||
The History library can read the history from and write it to a file.
|
||||
This section documents the functions for managing a history file.
|
||||
|
||||
@deftypefun int read_history (char *filename)
|
||||
Add the contents of @var{filename} to the history list, a line at a
|
||||
time. If @var{filename} is @code{NULL}, then read from
|
||||
@file{~/.history}. Returns 0 if successful, or errno if not.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int read_history_range (char *filename, int from, int to)
|
||||
Read a range of lines from @var{filename}, adding them to the history list.
|
||||
Start reading at line @var{from} and end at @var{to}. If
|
||||
@var{from} is zero, start at the beginning. If @var{to} is less than
|
||||
@var{from}, then read until the end of the file. If @var{filename} is
|
||||
@code{NULL}, then read from @file{~/.history}. Returns 0 if successful,
|
||||
or @code{errno} if not.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int write_history (char *filename)
|
||||
Write the current history to @var{filename}, overwriting @var{filename}
|
||||
if necessary. If @var{filename} is
|
||||
@code{NULL}, then write the history list to @file{~/.history}. Values
|
||||
returned are as in @code{read_history ()}.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int append_history (int nelements, char *filename)
|
||||
Append the last @var{nelements} of the history list to @var{filename}.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int history_truncate_file (char *filename, int nlines)
|
||||
Truncate the history file @var{filename}, leaving only the last
|
||||
@var{nlines} lines.
|
||||
@end deftypefun
|
||||
|
||||
@node History Expansion
|
||||
@subsection History Expansion
|
||||
|
||||
These functions implement @code{csh}-like history expansion.
|
||||
|
||||
@deftypefun int history_expand (char *string, char **output)
|
||||
Expand @var{string}, placing the result into @var{output}, a pointer
|
||||
to a string (@pxref{History Interaction}). Returns:
|
||||
@table @code
|
||||
@item 0
|
||||
If no expansions took place (or, if the only change in
|
||||
the text was the de-slashifying of the history expansion
|
||||
character);
|
||||
@item 1
|
||||
if expansions did take place;
|
||||
@item -1
|
||||
if there was an error in expansion;
|
||||
@item 2
|
||||
if the returned line should only be displayed, but not executed,
|
||||
as with the @code{:p} modifier (@pxref{Modifiers}).
|
||||
@end table
|
||||
|
||||
If an error ocurred in expansion, then @var{output} contains a descriptive
|
||||
error message.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {char *} history_arg_extract (int first, int last, char *string)
|
||||
Extract a string segment consisting of the @var{first} through @var{last}
|
||||
arguments present in @var{string}. Arguments are broken up as in Bash.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {char *} get_history_event (char *string, int *cindex, int qchar)
|
||||
Returns the text of the history event beginning at @var{string} +
|
||||
@var{*cindex}. @var{*cindex} is modified to point to after the event
|
||||
specifier. At function entry, @var{cindex} points to the index into
|
||||
@var{string} where the history event specification begins. @var{qchar}
|
||||
is a character that is allowed to end the event specification in addition
|
||||
to the ``normal'' terminating characters.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {char **} history_tokenize (char *string)
|
||||
Return an array of tokens parsed out of @var{string}, much as the
|
||||
shell might. The tokens are split on white space and on the
|
||||
characters @code{()<>;&|$}, and shell quoting conventions are
|
||||
obeyed.
|
||||
@end deftypefun
|
||||
|
||||
@node History Variables
|
||||
@section History Variables
|
||||
|
||||
This section describes the externally visible variables exported by
|
||||
the GNU History Library.
|
||||
|
||||
@deftypevar int history_base
|
||||
The logical offset of the first entry in the history list.
|
||||
@end deftypevar
|
||||
|
||||
@deftypevar int history_length
|
||||
The number of entries currently stored in the history list.
|
||||
@end deftypevar
|
||||
|
||||
@deftypevar int max_input_history
|
||||
The maximum number of history entries. This must be changed using
|
||||
@code{stifle_history ()}.
|
||||
@end deftypevar
|
||||
|
||||
@deftypevar char history_expansion_char
|
||||
The character that starts a history event. The default is @samp{!}.
|
||||
@end deftypevar
|
||||
|
||||
@deftypevar char history_subst_char
|
||||
The character that invokes word substitution if found at the start of
|
||||
a line. The default is @samp{^}.
|
||||
@end deftypevar
|
||||
|
||||
@deftypevar char history_comment_char
|
||||
During tokenization, if this character is seen as the first character
|
||||
of a word, then it and all subsequent characters up to a newline are
|
||||
ignored, suppressing history expansion for the remainder of the line.
|
||||
This is disabled by default.
|
||||
@end deftypevar
|
||||
|
||||
@deftypevar {char *} history_no_expand_chars
|
||||
The list of characters which inhibit history expansion if found immediately
|
||||
following @var{history_expansion_char}. The default is whitespace and
|
||||
@samp{=}.
|
||||
@end deftypevar
|
||||
|
||||
@node History Programming Example
|
||||
@section History Programming Example
|
||||
|
||||
The following program demonstrates simple use of the GNU History Library.
|
||||
|
||||
@smallexample
|
||||
main ()
|
||||
@{
|
||||
char line[1024], *t;
|
||||
int len, done = 0;
|
||||
|
||||
line[0] = 0;
|
||||
|
||||
using_history ();
|
||||
while (!done)
|
||||
@{
|
||||
printf ("history$ ");
|
||||
fflush (stdout);
|
||||
t = fgets (line, sizeof (line) - 1, stdin);
|
||||
if (t && *t)
|
||||
@{
|
||||
len = strlen (t);
|
||||
if (t[len - 1] == '\n')
|
||||
t[len - 1] = '\0';
|
||||
@}
|
||||
|
||||
if (!t)
|
||||
strcpy (line, "quit");
|
||||
|
||||
if (line[0])
|
||||
@{
|
||||
char *expansion;
|
||||
int result;
|
||||
|
||||
result = history_expand (line, &expansion);
|
||||
if (result)
|
||||
fprintf (stderr, "%s\n", expansion);
|
||||
|
||||
if (result < 0 || result == 2)
|
||||
@{
|
||||
free (expansion);
|
||||
continue;
|
||||
@}
|
||||
|
||||
add_history (expansion);
|
||||
strncpy (line, expansion, sizeof (line) - 1);
|
||||
free (expansion);
|
||||
@}
|
||||
|
||||
if (strcmp (line, "quit") == 0)
|
||||
done = 1;
|
||||
else if (strcmp (line, "save") == 0)
|
||||
write_history ("history_file");
|
||||
else if (strcmp (line, "read") == 0)
|
||||
read_history ("history_file");
|
||||
else if (strcmp (line, "list") == 0)
|
||||
@{
|
||||
register HIST_ENTRY **the_list;
|
||||
register int i;
|
||||
|
||||
the_list = history_list ();
|
||||
if (the_list)
|
||||
for (i = 0; the_list[i]; i++)
|
||||
printf ("%d: %s\n", i + history_base, the_list[i]->line);
|
||||
@}
|
||||
else if (strncmp (line, "delete", 6) == 0)
|
||||
@{
|
||||
int which;
|
||||
if ((sscanf (line + 6, "%d", &which)) == 1)
|
||||
@{
|
||||
HIST_ENTRY *entry = remove_history (which);
|
||||
if (!entry)
|
||||
fprintf (stderr, "No such entry %d\n", which);
|
||||
else
|
||||
@{
|
||||
free (entry->line);
|
||||
free (entry);
|
||||
@}
|
||||
@}
|
||||
else
|
||||
@{
|
||||
fprintf (stderr, "non-numeric arg given to `delete'\n");
|
||||
@}
|
||||
@}
|
||||
@}
|
||||
@}
|
||||
@end smallexample
|
||||
198
lib/readline/doc/hsuser.texinfo
Normal file
198
lib/readline/doc/hsuser.texinfo
Normal file
@@ -0,0 +1,198 @@
|
||||
@ignore
|
||||
This file documents the user interface to the GNU History library.
|
||||
|
||||
Copyright (C) 1988, 1991 Free Software Foundation, Inc.
|
||||
Authored by Brian Fox and Chet Ramey.
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of this manual
|
||||
provided the copyright notice and this permission notice are preserved on
|
||||
all copies.
|
||||
|
||||
Permission is granted to process this file through Tex and print the
|
||||
results, provided the printed document carries copying permission notice
|
||||
identical to this one except for the removal of this paragraph (this
|
||||
paragraph not being relevant to the printed manual).
|
||||
|
||||
Permission is granted to copy and distribute modified versions of this
|
||||
manual under the conditions for verbatim copying, provided also that the
|
||||
GNU Copyright statement is available to the distributee, and provided that
|
||||
the entire resulting derived work is distributed under the terms of a
|
||||
permission notice identical to this one.
|
||||
|
||||
Permission is granted to copy and distribute translations of this manual
|
||||
into another language, under the above conditions for modified versions.
|
||||
@end ignore
|
||||
|
||||
@node Using History Interactively
|
||||
@chapter Using History Interactively
|
||||
|
||||
@ifset BashFeatures
|
||||
This chapter describes how to use the GNU History Library interactively,
|
||||
from a user's standpoint. It should be considered a user's guide. For
|
||||
information on using the GNU History Library in your own programs,
|
||||
see the GNU Readline Library Manual.
|
||||
@end ifset
|
||||
@ifclear BashFeatures
|
||||
This chapter describes how to use the GNU History Library interactively,
|
||||
from a user's standpoint. It should be considered a user's guide. For
|
||||
information on using the GNU History Library in your own programs,
|
||||
@pxref{Programming with GNU History}.
|
||||
@end ifclear
|
||||
|
||||
@menu
|
||||
* History Interaction:: What it feels like using History as a user.
|
||||
@end menu
|
||||
|
||||
@node History Interaction
|
||||
@section History Interaction
|
||||
@cindex expansion
|
||||
|
||||
The History library provides a history expansion feature that is similar
|
||||
to the history expansion provided by @code{csh}. The following text
|
||||
describes the syntax used to manipulate the history information.
|
||||
|
||||
History expansion takes place in two parts. The first is to determine
|
||||
which line from the previous history should be used during substitution.
|
||||
The second is to select portions of that line for inclusion into the
|
||||
current one. The line selected from the previous history is called the
|
||||
@dfn{event}, and the portions of that line that are acted upon are
|
||||
called @dfn{words}. The line is broken into words in the same fashion
|
||||
that Bash does, so that several English (or Unix) words
|
||||
surrounded by quotes are considered as one word.
|
||||
|
||||
@menu
|
||||
* Event Designators:: How to specify which history line to use.
|
||||
* Word Designators:: Specifying which words are of interest.
|
||||
* Modifiers:: Modifying the results of substitution.
|
||||
@end menu
|
||||
|
||||
@node Event Designators
|
||||
@subsection Event Designators
|
||||
@cindex event designators
|
||||
|
||||
An event designator is a reference to a command line entry in the
|
||||
history list.
|
||||
@cindex history events
|
||||
|
||||
@table @asis
|
||||
|
||||
@item @code{!}
|
||||
Start a history substitution, except when followed by a space, tab,
|
||||
the end of the line, @key{=} or @key{(}.
|
||||
|
||||
@item @code{!!}
|
||||
Refer to the previous command. This is a synonym for @code{!-1}.
|
||||
|
||||
@item @code{!n}
|
||||
Refer to command line @var{n}.
|
||||
|
||||
@item @code{!-n}
|
||||
Refer to the command @var{n} lines back.
|
||||
|
||||
@item @code{!string}
|
||||
Refer to the most recent command starting with @var{string}.
|
||||
|
||||
@item @code{!?string}[@code{?}]
|
||||
Refer to the most recent command containing @var{string}.
|
||||
|
||||
@item @code{!#}
|
||||
The entire command line typed so far.
|
||||
|
||||
@item @code{^string1^string2^}
|
||||
Quick Substitution. Repeat the last command, replacing @var{string1}
|
||||
with @var{string2}. Equivalent to
|
||||
@code{!!:s/string1/string2/}.
|
||||
|
||||
@end table
|
||||
|
||||
@node Word Designators
|
||||
@subsection Word Designators
|
||||
|
||||
A @key{:} separates the event specification from the word designator. It
|
||||
can be omitted if the word designator begins with a @key{^}, @key{$},
|
||||
@key{*} or @key{%}. Words are numbered from the beginning of the line,
|
||||
with the first word being denoted by a 0 (zero).
|
||||
|
||||
@table @code
|
||||
|
||||
@item 0 (zero)
|
||||
The @code{0}th word. For many applications, this is the command word.
|
||||
|
||||
@item n
|
||||
The @var{n}th word.
|
||||
|
||||
@item ^
|
||||
The first argument; that is, word 1.
|
||||
|
||||
@item $
|
||||
The last argument.
|
||||
|
||||
@item %
|
||||
The word matched by the most recent @code{?string?} search.
|
||||
|
||||
@item x-y
|
||||
A range of words; @code{-@var{y}} abbreviates @code{0-@var{y}}.
|
||||
|
||||
@item *
|
||||
All of the words, except the @code{0}th. This is a synonym for @code{1-$}.
|
||||
It is not an error to use @key{*} if there is just one word in the event;
|
||||
the empty string is returned in that case.
|
||||
|
||||
@item x*
|
||||
Abbreviates @code{x-$}
|
||||
|
||||
@item x-
|
||||
Abbreviates @code{x-$} like @code{x*}, but omits the last word.
|
||||
|
||||
@end table
|
||||
|
||||
@node Modifiers
|
||||
@subsection Modifiers
|
||||
|
||||
After the optional word designator, you can add a sequence of one or more
|
||||
of the following modifiers, each preceded by a @key{:}.
|
||||
|
||||
@table @code
|
||||
|
||||
@item h
|
||||
Remove a trailing pathname component, leaving only the head.
|
||||
|
||||
@item r
|
||||
Remove a trailing suffix of the form @samp{.}@var{suffix}, leaving the basename.
|
||||
|
||||
@item e
|
||||
Remove all but the trailing suffix.
|
||||
|
||||
@item t
|
||||
Remove all leading pathname components, leaving the tail.
|
||||
|
||||
@item p
|
||||
Print the new command but do not execute it.
|
||||
|
||||
@ifset BashFeatures
|
||||
@item q
|
||||
Quote the substituted words, escaping further substitutions.
|
||||
|
||||
@item x
|
||||
Quote the substituted words as with @code{q},
|
||||
but break into words at spaces, tabs, and newlines.
|
||||
@end ifset
|
||||
|
||||
@item s/old/new/
|
||||
Substitute @var{new} for the first occurrence of @var{old} in the
|
||||
event line. Any delimiter may be used in place of @key{/}.
|
||||
The delimiter may be quoted in @var{old} and @var{new}
|
||||
with a single backslash. If @key{&} appears in @var{new},
|
||||
it is replaced by @var{old}. A single backslash will quote
|
||||
the @key{&}. The final delimiter is optional if it is the last
|
||||
character on the input line.
|
||||
|
||||
@item &
|
||||
Repeat the previous substitution.
|
||||
|
||||
@item g
|
||||
Cause changes to be applied over the entire event line. Used in
|
||||
conjunction with @code{s}, as in @code{gs/old/new/}, or with
|
||||
@code{&}.
|
||||
|
||||
@end table
|
||||
BIN
lib/readline/doc/readline.dvi
Normal file
BIN
lib/readline/doc/readline.dvi
Normal file
Binary file not shown.
744
lib/readline/doc/readline.info
Normal file
744
lib/readline/doc/readline.info
Normal file
@@ -0,0 +1,744 @@
|
||||
This is Info file history.info, produced by Makeinfo-1.55 from the
|
||||
input file hist.texinfo.
|
||||
|
||||
This document describes the GNU History library, a programming tool
|
||||
that provides a consistent user interface for recalling lines of
|
||||
previously typed input.
|
||||
|
||||
Copyright (C) 1988, 1991 Free Software Foundation, Inc.
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of this
|
||||
manual provided the copyright notice and this permission notice pare
|
||||
preserved on all copies.
|
||||
|
||||
Permission is granted to copy and distribute modified versions of
|
||||
this manual under the conditions for verbatim copying, provided that
|
||||
the entire resulting derived work is distributed under the terms of a
|
||||
permission notice identical to this one.
|
||||
|
||||
Permission is granted to copy and distribute translations of this
|
||||
manual into another language, under the above conditions for modified
|
||||
versions, except that this permission notice may be stated in a
|
||||
translation approved by the Foundation.
|
||||
|
||||
|
||||
File: history.info, Node: Top, Next: Using History Interactively, Prev: (DIR), Up: (DIR)
|
||||
|
||||
GNU History Library
|
||||
*******************
|
||||
|
||||
This document describes the GNU History library, a programming tool
|
||||
that provides a consistent user interface for recalling lines of
|
||||
previously typed input.
|
||||
|
||||
* Menu:
|
||||
|
||||
* Using History Interactively:: GNU History User's Manual.
|
||||
* Programming with GNU History:: GNU History Programmer's Manual.
|
||||
* Concept Index:: Index of concepts described in this manual.
|
||||
* Function and Variable Index:: Index of externally visible functions
|
||||
and variables.
|
||||
|
||||
|
||||
File: history.info, Node: Using History Interactively, Next: Programming with GNU History, Prev: Top, Up: Top
|
||||
|
||||
Using History Interactively
|
||||
***************************
|
||||
|
||||
This chapter describes how to use the GNU History Library
|
||||
interactively, from a user's standpoint. It should be considered a
|
||||
user's guide. For information on using the GNU History Library in your
|
||||
own programs, *note Programming with GNU History::..
|
||||
|
||||
* Menu:
|
||||
|
||||
* History Interaction:: What it feels like using History as a user.
|
||||
|
||||
|
||||
File: history.info, Node: History Interaction, Up: Using History Interactively
|
||||
|
||||
History Interaction
|
||||
===================
|
||||
|
||||
The History library provides a history expansion feature that is
|
||||
similar to the history expansion provided by `csh'. The following text
|
||||
describes the syntax used to manipulate the history information.
|
||||
|
||||
History expansion takes place in two parts. The first is to
|
||||
determine which line from the previous history should be used during
|
||||
substitution. The second is to select portions of that line for
|
||||
inclusion into the current one. The line selected from the previous
|
||||
history is called the "event", and the portions of that line that are
|
||||
acted upon are called "words". The line is broken into words in the
|
||||
same fashion that Bash does, so that several English (or Unix) words
|
||||
surrounded by quotes are considered as one word.
|
||||
|
||||
* Menu:
|
||||
|
||||
* Event Designators:: How to specify which history line to use.
|
||||
* Word Designators:: Specifying which words are of interest.
|
||||
* Modifiers:: Modifying the results of substitution.
|
||||
|
||||
|
||||
File: history.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
|
||||
|
||||
Event Designators
|
||||
-----------------
|
||||
|
||||
An event designator is a reference to a command line entry in the
|
||||
history list.
|
||||
|
||||
`!'
|
||||
Start a history substitution, except when followed by a space, tab,
|
||||
the end of the line, = or (.
|
||||
|
||||
`!!'
|
||||
Refer to the previous command. This is a synonym for `!-1'.
|
||||
|
||||
`!n'
|
||||
Refer to command line N.
|
||||
|
||||
`!-n'
|
||||
Refer to the command N lines back.
|
||||
|
||||
`!string'
|
||||
Refer to the most recent command starting with STRING.
|
||||
|
||||
`!?string'[`?']
|
||||
Refer to the most recent command containing STRING.
|
||||
|
||||
`!#'
|
||||
The entire command line typed so far.
|
||||
|
||||
`^string1^string2^'
|
||||
Quick Substitution. Repeat the last command, replacing STRING1
|
||||
with STRING2. Equivalent to `!!:s/string1/string2/'.
|
||||
|
||||
|
||||
File: history.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
|
||||
|
||||
Word Designators
|
||||
----------------
|
||||
|
||||
A : separates the event specification from the word designator. It
|
||||
can be omitted if the word designator begins with a ^, $, * or %.
|
||||
Words are numbered from the beginning of the line, with the first word
|
||||
being denoted by a 0 (zero).
|
||||
|
||||
`0 (zero)'
|
||||
The `0'th word. For many applications, this is the command word.
|
||||
|
||||
`n'
|
||||
The Nth word.
|
||||
|
||||
`^'
|
||||
The first argument; that is, word 1.
|
||||
|
||||
`$'
|
||||
The last argument.
|
||||
|
||||
`%'
|
||||
The word matched by the most recent `?string?' search.
|
||||
|
||||
`x-y'
|
||||
A range of words; `-Y' abbreviates `0-Y'.
|
||||
|
||||
`*'
|
||||
All of the words, except the `0'th. This is a synonym for `1-$'.
|
||||
It is not an error to use * if there is just one word in the event;
|
||||
the empty string is returned in that case.
|
||||
|
||||
`x*'
|
||||
Abbreviates `x-$'
|
||||
|
||||
`x-'
|
||||
Abbreviates `x-$' like `x*', but omits the last word.
|
||||
|
||||
|
||||
File: history.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
|
||||
|
||||
Modifiers
|
||||
---------
|
||||
|
||||
After the optional word designator, you can add a sequence of one or
|
||||
more of the following modifiers, each preceded by a :.
|
||||
|
||||
`h'
|
||||
Remove a trailing pathname component, leaving only the head.
|
||||
|
||||
`r'
|
||||
Remove a trailing suffix of the form `.'SUFFIX, leaving the
|
||||
basename.
|
||||
|
||||
`e'
|
||||
Remove all but the trailing suffix.
|
||||
|
||||
`t'
|
||||
Remove all leading pathname components, leaving the tail.
|
||||
|
||||
`p'
|
||||
Print the new command but do not execute it.
|
||||
|
||||
`s/old/new/'
|
||||
Substitute NEW for the first occurrence of OLD in the event line.
|
||||
Any delimiter may be used in place of /. The delimiter may be
|
||||
quoted in OLD and NEW with a single backslash. If & appears in
|
||||
NEW, it is replaced by OLD. A single backslash will quote the &.
|
||||
The final delimiter is optional if it is the last character on the
|
||||
input line.
|
||||
|
||||
`&'
|
||||
Repeat the previous substitution.
|
||||
|
||||
`g'
|
||||
Cause changes to be applied over the entire event line. Used in
|
||||
conjunction with `s', as in `gs/old/new/', or with `&'.
|
||||
|
||||
|
||||
File: history.info, Node: Programming with GNU History, Next: Concept Index, Prev: Using History Interactively, Up: Top
|
||||
|
||||
Programming with GNU History
|
||||
****************************
|
||||
|
||||
This chapter describes how to interface programs that you write with
|
||||
the GNU History Library. It should be considered a technical guide.
|
||||
For information on the interactive use of GNU History, *note Using
|
||||
History Interactively::..
|
||||
|
||||
* Menu:
|
||||
|
||||
* Introduction to History:: What is the GNU History library for?
|
||||
* History Storage:: How information is stored.
|
||||
* History Functions:: Functions that you can use.
|
||||
* History Variables:: Variables that control behaviour.
|
||||
* History Programming Example:: Example of using the GNU History Library.
|
||||
|
||||
|
||||
File: history.info, Node: Introduction to History, Next: History Storage, Up: Programming with GNU History
|
||||
|
||||
Introduction to History
|
||||
=======================
|
||||
|
||||
Many programs read input from the user a line at a time. The GNU
|
||||
History library is able to keep track of those lines, associate
|
||||
arbitrary data with each line, and utilize information from previous
|
||||
lines in composing new ones.
|
||||
|
||||
The programmer using the History library has available functions for
|
||||
remembering lines on a history list, associating arbitrary data with a
|
||||
line, removing lines from the list, searching through the list for a
|
||||
line containing an arbitrary text string, and referencing any line in
|
||||
the list directly. In addition, a history "expansion" function is
|
||||
available which provides for a consistent user interface across
|
||||
different programs.
|
||||
|
||||
The user using programs written with the History library has the
|
||||
benefit of a consistent user interface with a set of well-known
|
||||
commands for manipulating the text of previous lines and using that text
|
||||
in new commands. The basic history manipulation commands are similar to
|
||||
the history substitution provided by `csh'.
|
||||
|
||||
If the programmer desires, he can use the Readline library, which
|
||||
includes some history manipulation by default, and has the added
|
||||
advantage of command line editing.
|
||||
|
||||
|
||||
File: history.info, Node: History Storage, Next: History Functions, Prev: Introduction to History, Up: Programming with GNU History
|
||||
|
||||
History Storage
|
||||
===============
|
||||
|
||||
The history list is an array of history entries. A history entry is
|
||||
declared as follows:
|
||||
|
||||
typedef struct _hist_entry {
|
||||
char *line;
|
||||
char *data;
|
||||
} HIST_ENTRY;
|
||||
|
||||
The history list itself might therefore be declared as
|
||||
|
||||
HIST_ENTRY **the_history_list;
|
||||
|
||||
The state of the History library is encapsulated into a single
|
||||
structure:
|
||||
|
||||
/* A structure used to pass the current state of the history stuff around. */
|
||||
typedef struct _hist_state {
|
||||
HIST_ENTRY **entries; /* Pointer to the entries themselves. */
|
||||
int offset; /* The location pointer within this array. */
|
||||
int length; /* Number of elements within this array. */
|
||||
int size; /* Number of slots allocated to this array. */
|
||||
int flags;
|
||||
} HISTORY_STATE;
|
||||
|
||||
If the flags member includes `HS_STIFLED', the history has been
|
||||
stifled.
|
||||
|
||||
|
||||
File: history.info, Node: History Functions, Next: History Variables, Prev: History Storage, Up: Programming with GNU History
|
||||
|
||||
History Functions
|
||||
=================
|
||||
|
||||
This section describes the calling sequence for the various functions
|
||||
present in GNU History.
|
||||
|
||||
* Menu:
|
||||
|
||||
* Initializing History and State Management:: Functions to call when you
|
||||
want to use history in a
|
||||
program.
|
||||
* History List Management:: Functions used to manage the list
|
||||
of history entries.
|
||||
* Information About the History List:: Functions returning information about
|
||||
the history list.
|
||||
* Moving Around the History List:: Functions used to change the position
|
||||
in the history list.
|
||||
* Searching the History List:: Functions to search the history list
|
||||
for entries containing a string.
|
||||
* Managing the History File:: Functions that read and write a file
|
||||
containing the history list.
|
||||
* History Expansion:: Functions to perform csh-like history
|
||||
expansion.
|
||||
|
||||
|
||||
File: history.info, Node: Initializing History and State Management, Next: History List Management, Up: History Functions
|
||||
|
||||
Initializing History and State Management
|
||||
-----------------------------------------
|
||||
|
||||
This section describes functions used to initialize and manage the
|
||||
state of the History library when you want to use the history functions
|
||||
in your program.
|
||||
|
||||
- Function: void using_history ()
|
||||
Begin a session in which the history functions might be used. This
|
||||
initializes the interactive variables.
|
||||
|
||||
- Function: HISTORY_STATE * history_get_history_state ()
|
||||
Return a structure describing the current state of the input
|
||||
history.
|
||||
|
||||
- Function: void history_set_history_state (HISTORY_STATE *state)
|
||||
Set the state of the history list according to STATE.
|
||||
|
||||
|
||||
File: history.info, Node: History List Management, Next: Information About the History List, Prev: Initializing History and State Management, Up: History Functions
|
||||
|
||||
History List Management
|
||||
-----------------------
|
||||
|
||||
These functions manage individual entries on the history list, or set
|
||||
parameters managing the list itself.
|
||||
|
||||
- Function: void add_history (char *string)
|
||||
Place STRING at the end of the history list. The associated data
|
||||
field (if any) is set to `NULL'.
|
||||
|
||||
- Function: HIST_ENTRY * remove_history (int which)
|
||||
Remove history entry at offset WHICH from the history. The
|
||||
removed element is returned so you can free the line, data, and
|
||||
containing structure.
|
||||
|
||||
- Function: HIST_ENTRY * replace_history_entry (int which, char *line,
|
||||
char *data)
|
||||
Make the history entry at offset WHICH have LINE and DATA. This
|
||||
returns the old entry so you can dispose of the data. In the case
|
||||
of an invalid WHICH, a `NULL' pointer is returned.
|
||||
|
||||
- Function: void stifle_history (int max)
|
||||
Stifle the history list, remembering only the last MAX entries.
|
||||
|
||||
- Function: int unstifle_history ()
|
||||
Stop stifling the history. This returns the previous amount the
|
||||
history was stifled. The value is positive if the history was
|
||||
stifled, negative if it wasn't.
|
||||
|
||||
- Function: int history_is_stifled ()
|
||||
Returns non-zero if the history is stifled, zero if it is not.
|
||||
|
||||
|
||||
File: history.info, Node: Information About the History List, Next: Moving Around the History List, Prev: History List Management, Up: History Functions
|
||||
|
||||
Information About the History List
|
||||
----------------------------------
|
||||
|
||||
These functions return information about the entire history list or
|
||||
individual list entries.
|
||||
|
||||
- Function: HIST_ENTRY ** history_list ()
|
||||
Return a `NULL' terminated array of `HIST_ENTRY' which is the
|
||||
current input history. Element 0 of this list is the beginning of
|
||||
time. If there is no history, return `NULL'.
|
||||
|
||||
- Function: int where_history ()
|
||||
Returns the offset of the current history element.
|
||||
|
||||
- Function: HIST_ENTRY * current_history ()
|
||||
Return the history entry at the current position, as determined by
|
||||
`where_history ()'. If there is no entry there, return a `NULL'
|
||||
pointer.
|
||||
|
||||
- Function: HIST_ENTRY * history_get (int offset)
|
||||
Return the history entry at position OFFSET, starting from
|
||||
`history_base'. If there is no entry there, or if OFFSET is
|
||||
greater than the history length, return a `NULL' pointer.
|
||||
|
||||
- Function: int history_total_bytes ()
|
||||
Return the number of bytes that the primary history entries are
|
||||
using. This function returns the sum of the lengths of all the
|
||||
lines in the history.
|
||||
|
||||
|
||||
File: history.info, Node: Moving Around the History List, Next: Searching the History List, Prev: Information About the History List, Up: History Functions
|
||||
|
||||
Moving Around the History List
|
||||
------------------------------
|
||||
|
||||
These functions allow the current index into the history list to be
|
||||
set or changed.
|
||||
|
||||
- Function: int history_set_pos (int pos)
|
||||
Set the position in the history list to POS, an absolute index
|
||||
into the list.
|
||||
|
||||
- Function: HIST_ENTRY * previous_history ()
|
||||
Back up the current history offset to the previous history entry,
|
||||
and return a pointer to that entry. If there is no previous
|
||||
entry, return a `NULL' pointer.
|
||||
|
||||
- Function: HIST_ENTRY * next_history ()
|
||||
Move the current history offset forward to the next history entry,
|
||||
and return the a pointer to that entry. If there is no next
|
||||
entry, return a `NULL' pointer.
|
||||
|
||||
|
||||
File: history.info, Node: Searching the History List, Next: Managing the History File, Prev: Moving Around the History List, Up: History Functions
|
||||
|
||||
Searching the History List
|
||||
--------------------------
|
||||
|
||||
These functions allow searching of the history list for entries
|
||||
containing a specific string. Searching may be performed both forward
|
||||
and backward from the current history position. The search may be
|
||||
"anchored", meaning that the string must match at the beginning of the
|
||||
history entry.
|
||||
|
||||
- Function: int history_search (char *string, int direction)
|
||||
Search the history for STRING, starting at the current history
|
||||
offset. If DIRECTION < 0, then the search is through previous
|
||||
entries, else through subsequent. If STRING is found, then the
|
||||
current history index is set to that history entry, and the value
|
||||
returned is the offset in the line of the entry where STRING was
|
||||
found. Otherwise, nothing is changed, and a -1 is returned.
|
||||
|
||||
- Function: int history_search_prefix (char *string, int direction)
|
||||
Search the history for STRING, starting at the current history
|
||||
offset. The search is anchored: matching lines must begin with
|
||||
STRING. If DIRECTION < 0, then the search is through previous
|
||||
entries, else through subsequent. If STRING is found, then the
|
||||
current history index is set to that entry, and the return value
|
||||
is 0. Otherwise, nothing is changed, and a -1 is returned.
|
||||
|
||||
- Function: int history_search_pos (char *string, int direction, int
|
||||
pos)
|
||||
Search for STRING in the history list, starting at POS, an
|
||||
absolute index into the list. If DIRECTION is negative, the search
|
||||
proceeds backward from POS, otherwise forward. Returns the
|
||||
absolute index of the history element where STRING was found, or
|
||||
-1 otherwise.
|
||||
|
||||
|
||||
File: history.info, Node: Managing the History File, Next: History Expansion, Prev: Searching the History List, Up: History Functions
|
||||
|
||||
Managing the History File
|
||||
-------------------------
|
||||
|
||||
The History library can read the history from and write it to a file.
|
||||
This section documents the functions for managing a history file.
|
||||
|
||||
- Function: int read_history (char *filename)
|
||||
Add the contents of FILENAME to the history list, a line at a
|
||||
time. If FILENAME is `NULL', then read from `~/.history'.
|
||||
Returns 0 if successful, or errno if not.
|
||||
|
||||
- Function: int read_history_range (char *filename, int from, int to)
|
||||
Read a range of lines from FILENAME, adding them to the history
|
||||
list. Start reading at line FROM and end at TO. If FROM is zero,
|
||||
start at the beginning. If TO is less than FROM, then read until
|
||||
the end of the file. If FILENAME is `NULL', then read from
|
||||
`~/.history'. Returns 0 if successful, or `errno' if not.
|
||||
|
||||
- Function: int write_history (char *filename)
|
||||
Write the current history to FILENAME, overwriting FILENAME if
|
||||
necessary. If FILENAME is `NULL', then write the history list to
|
||||
`~/.history'. Values returned are as in `read_history ()'.
|
||||
|
||||
- Function: int append_history (int nelements, char *filename)
|
||||
Append the last NELEMENTS of the history list to FILENAME.
|
||||
|
||||
- Function: int history_truncate_file (char *filename, int nlines)
|
||||
Truncate the history file FILENAME, leaving only the last NLINES
|
||||
lines.
|
||||
|
||||
|
||||
File: history.info, Node: History Expansion, Prev: Managing the History File, Up: History Functions
|
||||
|
||||
History Expansion
|
||||
-----------------
|
||||
|
||||
These functions implement `csh'-like history expansion.
|
||||
|
||||
- Function: int history_expand (char *string, char **output)
|
||||
Expand STRING, placing the result into OUTPUT, a pointer to a
|
||||
string (*note History Interaction::.). Returns:
|
||||
`0'
|
||||
If no expansions took place (or, if the only change in the
|
||||
text was the de-slashifying of the history expansion
|
||||
character);
|
||||
|
||||
`1'
|
||||
if expansions did take place;
|
||||
|
||||
`-1'
|
||||
if there was an error in expansion;
|
||||
|
||||
`2'
|
||||
if the returned line should only be displayed, but not
|
||||
executed, as with the `:p' modifier (*note Modifiers::.).
|
||||
|
||||
If an error ocurred in expansion, then OUTPUT contains a
|
||||
descriptive error message.
|
||||
|
||||
- Function: char * history_arg_extract (int first, int last, char
|
||||
*string)
|
||||
Extract a string segment consisting of the FIRST through LAST
|
||||
arguments present in STRING. Arguments are broken up as in Bash.
|
||||
|
||||
- Function: char * get_history_event (char *string, int *cindex, int
|
||||
qchar)
|
||||
Returns the text of the history event beginning at STRING +
|
||||
*CINDEX. *CINDEX is modified to point to after the event
|
||||
specifier. At function entry, CINDEX points to the index into
|
||||
STRING where the history event specification begins. QCHAR is a
|
||||
character that is allowed to end the event specification in
|
||||
addition to the "normal" terminating characters.
|
||||
|
||||
- Function: char ** history_tokenize (char *string)
|
||||
Return an array of tokens parsed out of STRING, much as the shell
|
||||
might. The tokens are split on white space and on the characters
|
||||
`()<>;&|$', and shell quoting conventions are obeyed.
|
||||
|
||||
|
||||
File: history.info, Node: History Variables, Next: History Programming Example, Prev: History Functions, Up: Programming with GNU History
|
||||
|
||||
History Variables
|
||||
=================
|
||||
|
||||
This section describes the externally visible variables exported by
|
||||
the GNU History Library.
|
||||
|
||||
- Variable: int history_base
|
||||
The logical offset of the first entry in the history list.
|
||||
|
||||
- Variable: int history_length
|
||||
The number of entries currently stored in the history list.
|
||||
|
||||
- Variable: int max_input_history
|
||||
The maximum number of history entries. This must be changed using
|
||||
`stifle_history ()'.
|
||||
|
||||
- Variable: char history_expansion_char
|
||||
The character that starts a history event. The default is `!'.
|
||||
|
||||
- Variable: char history_subst_char
|
||||
The character that invokes word substitution if found at the start
|
||||
of a line. The default is `^'.
|
||||
|
||||
- Variable: char history_comment_char
|
||||
During tokenization, if this character is seen as the first
|
||||
character of a word, then it and all subsequent characters up to a
|
||||
newline are ignored, suppressing history expansion for the
|
||||
remainder of the line. This is disabled by default.
|
||||
|
||||
- Variable: char * history_no_expand_chars
|
||||
The list of characters which inhibit history expansion if found
|
||||
immediately following HISTORY_EXPANSION_CHAR. The default is
|
||||
whitespace and `='.
|
||||
|
||||
|
||||
File: history.info, Node: History Programming Example, Prev: History Variables, Up: Programming with GNU History
|
||||
|
||||
History Programming Example
|
||||
===========================
|
||||
|
||||
The following program demonstrates simple use of the GNU History
|
||||
Library.
|
||||
|
||||
main ()
|
||||
{
|
||||
char line[1024], *t;
|
||||
int len, done = 0;
|
||||
|
||||
line[0] = 0;
|
||||
|
||||
using_history ();
|
||||
while (!done)
|
||||
{
|
||||
printf ("history$ ");
|
||||
fflush (stdout);
|
||||
t = fgets (line, sizeof (line) - 1, stdin);
|
||||
if (t && *t)
|
||||
{
|
||||
len = strlen (t);
|
||||
if (t[len - 1] == '\n')
|
||||
t[len - 1] = '\0';
|
||||
}
|
||||
|
||||
if (!t)
|
||||
strcpy (line, "quit");
|
||||
|
||||
if (line[0])
|
||||
{
|
||||
char *expansion;
|
||||
int result;
|
||||
|
||||
result = history_expand (line, &expansion);
|
||||
if (result)
|
||||
fprintf (stderr, "%s\n", expansion);
|
||||
|
||||
if (result < 0 || result == 2)
|
||||
{
|
||||
free (expansion);
|
||||
continue;
|
||||
}
|
||||
|
||||
add_history (expansion);
|
||||
strncpy (line, expansion, sizeof (line) - 1);
|
||||
free (expansion);
|
||||
}
|
||||
|
||||
if (strcmp (line, "quit") == 0)
|
||||
done = 1;
|
||||
else if (strcmp (line, "save") == 0)
|
||||
write_history ("history_file");
|
||||
else if (strcmp (line, "read") == 0)
|
||||
read_history ("history_file");
|
||||
else if (strcmp (line, "list") == 0)
|
||||
{
|
||||
register HIST_ENTRY **the_list;
|
||||
register int i;
|
||||
|
||||
the_list = history_list ();
|
||||
if (the_list)
|
||||
for (i = 0; the_list[i]; i++)
|
||||
printf ("%d: %s\n", i + history_base, the_list[i]->line);
|
||||
}
|
||||
else if (strncmp (line, "delete", 6) == 0)
|
||||
{
|
||||
int which;
|
||||
if ((sscanf (line + 6, "%d", &which)) == 1)
|
||||
{
|
||||
HIST_ENTRY *entry = remove_history (which);
|
||||
if (!entry)
|
||||
fprintf (stderr, "No such entry %d\n", which);
|
||||
else
|
||||
{
|
||||
free (entry->line);
|
||||
free (entry);
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
fprintf (stderr, "non-numeric arg given to `delete'\n");
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
File: history.info, Node: Concept Index, Next: Function and Variable Index, Prev: Programming with GNU History, Up: Top
|
||||
|
||||
Concept Index
|
||||
*************
|
||||
|
||||
* Menu:
|
||||
|
||||
* anchored search: Searching the History List.
|
||||
* event designators: Event Designators.
|
||||
* expansion: History Interaction.
|
||||
* history events: Event Designators.
|
||||
* History Searching: Searching the History List.
|
||||
|
||||
|
||||
File: history.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top
|
||||
|
||||
Function and Variable Index
|
||||
***************************
|
||||
|
||||
* Menu:
|
||||
|
||||
* add_history: History List Management.
|
||||
* append_history: Managing the History File.
|
||||
* current_history: Information About the History List.
|
||||
* get_history_event: History Expansion.
|
||||
* history_arg_extract: History Expansion.
|
||||
* history_base: History Variables.
|
||||
* history_comment_char: History Variables.
|
||||
* history_expand: History Expansion.
|
||||
* history_expansion_char: History Variables.
|
||||
* history_get: Information About the History List.
|
||||
* history_get_history_state: Initializing History and State Management.
|
||||
* history_is_stifled: History List Management.
|
||||
* history_length: History Variables.
|
||||
* history_list: Information About the History List.
|
||||
* history_no_expand_chars: History Variables.
|
||||
* history_search: Searching the History List.
|
||||
* history_search_pos: Searching the History List.
|
||||
* history_search_prefix: Searching the History List.
|
||||
* history_set_history_state: Initializing History and State Management.
|
||||
* history_set_pos: Moving Around the History List.
|
||||
* history_subst_char: History Variables.
|
||||
* history_tokenize: History Expansion.
|
||||
* history_total_bytes: Information About the History List.
|
||||
* history_truncate_file: Managing the History File.
|
||||
* max_input_history: History Variables.
|
||||
* next_history: Moving Around the History List.
|
||||
* previous_history: Moving Around the History List.
|
||||
* read_history: Managing the History File.
|
||||
* read_history_range: Managing the History File.
|
||||
* remove_history: History List Management.
|
||||
* replace_history_entry: History List Management.
|
||||
* stifle_history: History List Management.
|
||||
* unstifle_history: History List Management.
|
||||
* using_history: Initializing History and State Management.
|
||||
* where_history: Information About the History List.
|
||||
* write_history: Managing the History File.
|
||||
|
||||
|
||||
|
||||
Tag Table:
|
||||
Node: Top975
|
||||
Node: Using History Interactively1569
|
||||
Node: History Interaction2077
|
||||
Node: Event Designators3122
|
||||
Node: Word Designators3952
|
||||
Node: Modifiers4936
|
||||
Node: Programming with GNU History6065
|
||||
Node: Introduction to History6791
|
||||
Node: History Storage8112
|
||||
Node: History Functions9205
|
||||
Node: Initializing History and State Management10176
|
||||
Node: History List Management10968
|
||||
Node: Information About the History List12396
|
||||
Node: Moving Around the History List13702
|
||||
Node: Searching the History List14587
|
||||
Node: Managing the History File16419
|
||||
Node: History Expansion17925
|
||||
Node: History Variables19769
|
||||
Node: History Programming Example21138
|
||||
Node: Concept Index23742
|
||||
Node: Function and Variable Index24223
|
||||
|
||||
End Tag Table
|
||||
2037
lib/readline/doc/readline.ps
Normal file
2037
lib/readline/doc/readline.ps
Normal file
File diff suppressed because it is too large
Load Diff
111
lib/readline/doc/rlman.texinfo
Normal file
111
lib/readline/doc/rlman.texinfo
Normal file
@@ -0,0 +1,111 @@
|
||||
\input texinfo @c -*-texinfo-*-
|
||||
@comment %**start of header (This is for running Texinfo on a region.)
|
||||
@setfilename readline.info
|
||||
@settitle GNU Readline Library
|
||||
@comment %**end of header (This is for running Texinfo on a region.)
|
||||
@synindex vr fn
|
||||
@setchapternewpage odd
|
||||
|
||||
@ignore
|
||||
last change: Thu Jul 21 16:02:40 EDT 1994
|
||||
@end ignore
|
||||
|
||||
@set EDITION 2.0
|
||||
@set VERSION 2.0
|
||||
@set UPDATED 21 July 1994
|
||||
@set UPDATE-MONTH July 1994
|
||||
|
||||
@ifinfo
|
||||
This document describes the GNU Readline Library, a utility which aids
|
||||
in the consistency of user interface across discrete programs that need
|
||||
to provide a command line interface.
|
||||
|
||||
Copyright (C) 1988, 1991 Free Software Foundation, Inc.
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of
|
||||
this manual provided the copyright notice and this permission notice
|
||||
pare preserved on all copies.
|
||||
|
||||
@ignore
|
||||
Permission is granted to process this file through TeX and print the
|
||||
results, provided the printed document carries copying permission
|
||||
notice identical to this one except for the removal of this paragraph
|
||||
(this paragraph not being relevant to the printed manual).
|
||||
@end ignore
|
||||
|
||||
Permission is granted to copy and distribute modified versions of this
|
||||
manual under the conditions for verbatim copying, provided that the entire
|
||||
resulting derived work is distributed under the terms of a permission
|
||||
notice identical to this one.
|
||||
|
||||
Permission is granted to copy and distribute translations of this manual
|
||||
into another language, under the above conditions for modified versions,
|
||||
except that this permission notice may be stated in a translation approved
|
||||
by the Foundation.
|
||||
@end ifinfo
|
||||
|
||||
@titlepage
|
||||
@sp 10
|
||||
@title GNU Readline Library
|
||||
@subtitle Edition @value{EDITION}, for @code{Readline Library} Version @value{VERSION}.
|
||||
@subtitle @value{UPDATE-MONTH}
|
||||
@author Brian Fox, Free Software Foundation
|
||||
@author Chet Ramey, Case Western Reserve University
|
||||
|
||||
@page
|
||||
This document describes the GNU Readline Library, a utility which aids
|
||||
in the consistency of user interface across discrete programs that need
|
||||
to provide a command line interface.
|
||||
|
||||
Published by the Free Software Foundation @*
|
||||
675 Massachusetts Avenue, @*
|
||||
Cambridge, MA 02139 USA
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of
|
||||
this manual provided the copyright notice and this permission notice
|
||||
are preserved on all copies.
|
||||
|
||||
Permission is granted to copy and distribute modified versions of this
|
||||
manual under the conditions for verbatim copying, provided that the entire
|
||||
resulting derived work is distributed under the terms of a permission
|
||||
notice identical to this one.
|
||||
|
||||
Permission is granted to copy and distribute translations of this manual
|
||||
into another language, under the above conditions for modified versions,
|
||||
except that this permission notice may be stated in a translation approved
|
||||
by the Foundation.
|
||||
|
||||
@vskip 0pt plus 1filll
|
||||
Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
|
||||
@end titlepage
|
||||
|
||||
@ifinfo
|
||||
@node Top
|
||||
@top GNU Readline Library
|
||||
|
||||
This document describes the GNU Readline Library, a utility which aids
|
||||
in the consistency of user interface across discrete programs that need
|
||||
to provide a command line interface.
|
||||
|
||||
@menu
|
||||
* Command Line Editing:: GNU Readline User's Manual.
|
||||
* Programming with GNU Readline:: GNU Readline Programmer's Manual.
|
||||
* Concept Index:: Index of concepts described in this manual.
|
||||
* Function and Variable Index:: Index of externally visible functions
|
||||
and variables.
|
||||
@end menu
|
||||
@end ifinfo
|
||||
|
||||
@include rluser.texinfo
|
||||
@include rltech.texinfo
|
||||
|
||||
@node Concept Index
|
||||
@unnumbered Concept Index
|
||||
@printindex cp
|
||||
|
||||
@node Function and Variable Index
|
||||
@unnumbered Function and Variable Index
|
||||
@printindex fn
|
||||
|
||||
@contents
|
||||
@bye
|
||||
1406
lib/readline/doc/rltech.texinfo
Normal file
1406
lib/readline/doc/rltech.texinfo
Normal file
File diff suppressed because it is too large
Load Diff
875
lib/readline/doc/rluser.texinfo
Normal file
875
lib/readline/doc/rluser.texinfo
Normal file
@@ -0,0 +1,875 @@
|
||||
@comment %**start of header (This is for running Texinfo on a region.)
|
||||
@setfilename rluser.info
|
||||
@comment %**end of header (This is for running Texinfo on a region.)
|
||||
@setchapternewpage odd
|
||||
|
||||
@ignore
|
||||
This file documents the end user interface to the GNU command line
|
||||
editing features. It is to be an appendix to manuals for programs which
|
||||
use these features. There is a document entitled "readline.texinfo"
|
||||
which contains both end-user and programmer documentation for the GNU
|
||||
Readline Library.
|
||||
|
||||
Copyright (C) 1988 Free Software Foundation, Inc.
|
||||
|
||||
Authored by Brian Fox and Chet Ramey.
|
||||
|
||||
Permission is granted to process this file through Tex and print the
|
||||
results, provided the printed document carries copying permission notice
|
||||
identical to this one except for the removal of this paragraph (this
|
||||
paragraph not being relevant to the printed manual).
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of this manual
|
||||
provided the copyright notice and this permission notice are preserved on
|
||||
all copies.
|
||||
|
||||
Permission is granted to copy and distribute modified versions of this
|
||||
manual under the conditions for verbatim copying, provided also that the
|
||||
GNU Copyright statement is available to the distributee, and provided that
|
||||
the entire resulting derived work is distributed under the terms of a
|
||||
permission notice identical to this one.
|
||||
|
||||
Permission is granted to copy and distribute translations of this manual
|
||||
into another language, under the above conditions for modified versions.
|
||||
@end ignore
|
||||
|
||||
@comment If you are including this manual as an appendix, then set the
|
||||
@comment variable readline-appendix.
|
||||
|
||||
@node Command Line Editing
|
||||
@chapter Command Line Editing
|
||||
|
||||
This chapter describes the basic features of the GNU
|
||||
command line editing interface.
|
||||
|
||||
@menu
|
||||
* Introduction and Notation:: Notation used in this text.
|
||||
* Readline Interaction:: The minimum set of commands for editing a line.
|
||||
* Readline Init File:: Customizing Readline from a user's view.
|
||||
* Bindable Readline Commands:: A description of most of the Readline commands
|
||||
available for binding
|
||||
* Readline vi Mode:: A short description of how to make Readline
|
||||
behave like the vi editor.
|
||||
@end menu
|
||||
|
||||
@node Introduction and Notation
|
||||
@section Introduction to Line Editing
|
||||
|
||||
The following paragraphs describe the notation used to represent
|
||||
keystrokes.
|
||||
|
||||
The text @key{C-k} is read as `Control-K' and describes the character
|
||||
produced when the Control key is depressed and the @key{k} key is struck.
|
||||
|
||||
The text @key{M-k} is read as `Meta-K' and describes the character
|
||||
produced when the meta key (if you have one) is depressed, and the @key{k}
|
||||
key is struck. If you do not have a meta key, the identical keystroke
|
||||
can be generated by typing @key{ESC} @i{first}, and then typing @key{k}.
|
||||
Either process is known as @dfn{metafying} the @key{k} key.
|
||||
|
||||
The text @key{M-C-k} is read as `Meta-Control-k' and describes the
|
||||
character produced by @dfn{metafying} @key{C-k}.
|
||||
|
||||
In addition, several keys have their own names. Specifically,
|
||||
@key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all
|
||||
stand for themselves when seen in this text, or in an init file
|
||||
(@pxref{Readline Init File}, for more info).
|
||||
|
||||
@node Readline Interaction
|
||||
@section Readline Interaction
|
||||
@cindex interaction, readline
|
||||
|
||||
Often during an interactive session you type in a long line of text,
|
||||
only to notice that the first word on the line is misspelled. The
|
||||
Readline library gives you a set of commands for manipulating the text
|
||||
as you type it in, allowing you to just fix your typo, and not forcing
|
||||
you to retype the majority of the line. Using these editing commands,
|
||||
you move the cursor to the place that needs correction, and delete or
|
||||
insert the text of the corrections. Then, when you are satisfied with
|
||||
the line, you simply press @key{RETURN}. You do not have to be at the
|
||||
end of the line to press @key{RETURN}; the entire line is accepted
|
||||
regardless of the location of the cursor within the line.
|
||||
|
||||
@menu
|
||||
* Readline Bare Essentials:: The least you need to know about Readline.
|
||||
* Readline Movement Commands:: Moving about the input line.
|
||||
* Readline Killing Commands:: How to delete text, and how to get it back!
|
||||
* Readline Arguments:: Giving numeric arguments to commands.
|
||||
@end menu
|
||||
|
||||
@node Readline Bare Essentials
|
||||
@subsection Readline Bare Essentials
|
||||
|
||||
In order to enter characters into the line, simply type them. The typed
|
||||
character appears where the cursor was, and then the cursor moves one
|
||||
space to the right. If you mistype a character, you can use your
|
||||
erase character to back up and delete the mistyped character.
|
||||
|
||||
Sometimes you may miss typing a character that you wanted to type, and
|
||||
not notice your error until you have typed several other characters. In
|
||||
that case, you can type @key{C-b} to move the cursor to the left, and then
|
||||
correct your mistake. Afterwards, you can move the cursor to the right
|
||||
with @key{C-f}.
|
||||
|
||||
When you add text in the middle of a line, you will notice that characters
|
||||
to the right of the cursor are `pushed over' to make room for the text
|
||||
that you have inserted. Likewise, when you delete text behind the cursor,
|
||||
characters to the right of the cursor are `pulled back' to fill in the
|
||||
blank space created by the removal of the text. A list of the basic bare
|
||||
essentials for editing the text of an input line follows.
|
||||
|
||||
@table @asis
|
||||
@item @key{C-b}
|
||||
Move back one character.
|
||||
@item @key{C-f}
|
||||
Move forward one character.
|
||||
@item @key{DEL}
|
||||
Delete the character to the left of the cursor.
|
||||
@item @key{C-d}
|
||||
Delete the character underneath the cursor.
|
||||
@item @w{Printing characters}
|
||||
Insert the character into the line at the cursor.
|
||||
@item @key{C-_}
|
||||
Undo the last thing that you did. You can undo all the way back to an
|
||||
empty line.
|
||||
@end table
|
||||
|
||||
@node Readline Movement Commands
|
||||
@subsection Readline Movement Commands
|
||||
|
||||
|
||||
The above table describes the most basic possible keystrokes that you need
|
||||
in order to do editing of the input line. For your convenience, many
|
||||
other commands have been added in addition to @key{C-b}, @key{C-f},
|
||||
@key{C-d}, and @key{DEL}. Here are some commands for moving more rapidly
|
||||
about the line.
|
||||
|
||||
@table @key
|
||||
@item C-a
|
||||
Move to the start of the line.
|
||||
@item C-e
|
||||
Move to the end of the line.
|
||||
@item M-f
|
||||
Move forward a word.
|
||||
@item M-b
|
||||
Move backward a word.
|
||||
@item C-l
|
||||
Clear the screen, reprinting the current line at the top.
|
||||
@end table
|
||||
|
||||
Notice how @key{C-f} moves forward a character, while @key{M-f} moves
|
||||
forward a word. It is a loose convention that control keystrokes
|
||||
operate on characters while meta keystrokes operate on words.
|
||||
|
||||
@node Readline Killing Commands
|
||||
@subsection Readline Killing Commands
|
||||
|
||||
@cindex Killing text
|
||||
@cindex Yanking text
|
||||
|
||||
@dfn{Killing} text means to delete the text from the line, but to save
|
||||
it away for later use, usually by @dfn{yanking} (re-inserting)
|
||||
it back into the line.
|
||||
If the description for a command says that it `kills' text, then you can
|
||||
be sure that you can get the text back in a different (or the same)
|
||||
place later.
|
||||
|
||||
When you use a kill command, the text is saved in a @dfn{kill-ring}.
|
||||
Any number of consecutive kills save all of the killed text together, so
|
||||
that when you yank it back, you get it all. The kill
|
||||
ring is not line specific; the text that you killed on a previously
|
||||
typed line is available to be yanked back later, when you are typing
|
||||
another line.
|
||||
@cindex Kill ring
|
||||
|
||||
Here is the list of commands for killing text.
|
||||
|
||||
@table @key
|
||||
@item C-k
|
||||
Kill the text from the current cursor position to the end of the line.
|
||||
|
||||
@item M-d
|
||||
Kill from the cursor to the end of the current word, or if between
|
||||
words, to the end of the next word.
|
||||
|
||||
@item M-DEL
|
||||
Kill from the cursor the start of the previous word, or if between
|
||||
words, to the start of the previous word.
|
||||
|
||||
@item C-w
|
||||
Kill from the cursor to the previous whitespace. This is different than
|
||||
@key{M-DEL} because the word boundaries differ.
|
||||
|
||||
@end table
|
||||
|
||||
And, here is how to @dfn{yank} the text back into the line. Yanking
|
||||
means to copy the most-recently-killed text from the kill buffer.
|
||||
|
||||
@table @key
|
||||
@item C-y
|
||||
Yank the most recently killed text back into the buffer at the cursor.
|
||||
|
||||
@item M-y
|
||||
Rotate the kill-ring, and yank the new top. You can only do this if
|
||||
the prior command is @key{C-y} or @key{M-y}.
|
||||
@end table
|
||||
|
||||
@node Readline Arguments
|
||||
@subsection Readline Arguments
|
||||
|
||||
You can pass numeric arguments to Readline commands. Sometimes the
|
||||
argument acts as a repeat count, other times it is the @i{sign} of the
|
||||
argument that is significant. If you pass a negative argument to a
|
||||
command which normally acts in a forward direction, that command will
|
||||
act in a backward direction. For example, to kill text back to the
|
||||
start of the line, you might type @key{M--} @key{C-k}.
|
||||
|
||||
The general way to pass numeric arguments to a command is to type meta
|
||||
digits before the command. If the first `digit' you type is a minus
|
||||
sign (@key{-}), then the sign of the argument will be negative. Once
|
||||
you have typed one meta digit to get the argument started, you can type
|
||||
the remainder of the digits, and then the command. For example, to give
|
||||
the @key{C-d} command an argument of 10, you could type @key{M-1 0 C-d}.
|
||||
|
||||
|
||||
@node Readline Init File
|
||||
@section Readline Init File
|
||||
|
||||
Although the Readline library comes with a set of Emacs-like
|
||||
keybindings installed by default,
|
||||
it is possible that you would like to use a different set
|
||||
of keybindings. You can customize programs that use Readline by putting
|
||||
commands in an @dfn{init} file in your home directory. The name of this
|
||||
@ifset BashFeatures
|
||||
file is taken from the value of the shell variable @code{INPUTRC}. If
|
||||
@end ifset
|
||||
@ifclear BashFeatures
|
||||
file is taken from the value of the environment variable @code{INPUTRC}. If
|
||||
@end ifclear
|
||||
that variable is unset, the default is @file{~/.inputrc}.
|
||||
|
||||
When a program which uses the Readline library starts up, the
|
||||
init file is read, and the key bindings are set.
|
||||
|
||||
In addition, the @code{C-x C-r} command re-reads this init file, thus
|
||||
incorporating any changes that you might have made to it.
|
||||
|
||||
@menu
|
||||
* Readline Init Syntax:: Syntax for the commands in the inputrc file.
|
||||
* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
|
||||
@end menu
|
||||
|
||||
@node Readline Init Syntax
|
||||
@subsection Readline Init Syntax
|
||||
|
||||
There are only a few basic constructs allowed in the
|
||||
Readline init file. Blank lines are ignored.
|
||||
Lines beginning with a @key{#} are comments.
|
||||
Lines beginning with a @key{$} indicate conditional
|
||||
constructs (@pxref{Conditional Init Constructs}). Other lines
|
||||
denote variable settings and key bindings.
|
||||
|
||||
@table @asis
|
||||
@item Variable Settings
|
||||
You can change the state of a few variables in Readline by
|
||||
using the @code{set} command within the init file. Here is how you
|
||||
would specify that you wish to use @code{vi} line editing commands:
|
||||
|
||||
@example
|
||||
set editing-mode vi
|
||||
@end example
|
||||
|
||||
Right now, there are only a few variables which can be set;
|
||||
so few, in fact, that we just list them here:
|
||||
|
||||
@table @code
|
||||
|
||||
@item editing-mode
|
||||
@vindex editing-mode
|
||||
The @code{editing-mode} variable controls which editing mode you are
|
||||
using. By default, Readline starts up in Emacs editing mode, where
|
||||
the keystrokes are most similar to Emacs. This variable can be
|
||||
set to either @code{emacs} or @code{vi}.
|
||||
|
||||
@item horizontal-scroll-mode
|
||||
@vindex horizontal-scroll-mode
|
||||
This variable can be set to either @code{On} or @code{Off}. Setting it
|
||||
to @code{On} means that the text of the lines that you edit will scroll
|
||||
horizontally on a single screen line when they are longer than the width
|
||||
of the screen, instead of wrapping onto a new screen line. By default,
|
||||
this variable is set to @code{Off}.
|
||||
|
||||
@item mark-modified-lines
|
||||
@vindex mark-modified-lines
|
||||
This variable, when set to @code{On}, says to display an asterisk
|
||||
(@samp{*}) at the start of history lines which have been modified.
|
||||
This variable is @code{off} by default.
|
||||
|
||||
@item bell-style
|
||||
@vindex bell-style
|
||||
Controls what happens when Readline wants to ring the terminal bell.
|
||||
If set to @code{none}, Readline never rings the bell. If set to
|
||||
@code{visible}, Readline uses a visible bell if one is available.
|
||||
If set to @code{audible} (the default), Readline attempts to ring
|
||||
the terminal's bell.
|
||||
|
||||
@item comment-begin
|
||||
@vindex comment-begin
|
||||
The string to insert at the beginning of the line when the
|
||||
@code{vi-comment} command is executed. The default value
|
||||
is @code{"#"}.
|
||||
|
||||
@item meta-flag
|
||||
@vindex meta-flag
|
||||
If set to @code{on}, Readline will enable eight-bit input (it
|
||||
will not strip the eighth bit from the characters it reads),
|
||||
regardless of what the terminal claims it can support. The
|
||||
default value is @code{off}.
|
||||
|
||||
@item convert-meta
|
||||
@vindex convert-meta
|
||||
If set to @code{on}, Readline will convert characters with the
|
||||
eigth bit set to an ASCII key sequence by stripping the eigth
|
||||
bit and prepending an @key{ESC} character, converting them to a
|
||||
meta-prefixed key sequence. The default value is @code{on}.
|
||||
|
||||
@item output-meta
|
||||
@vindex output-meta
|
||||
If set to @code{on}, Readline will display characters with the
|
||||
eighth bit set directly rather than as a meta-prefixed escape
|
||||
sequence. The default is @code{off}.
|
||||
|
||||
@item completion-query-items
|
||||
@vindex completion-query-items
|
||||
The number of possible completions that determines when the user is
|
||||
asked whether he wants to see the list of possibilities. If the
|
||||
number of possible completions is greater than this value,
|
||||
Readline will ask the user whether or not he wishes to view
|
||||
them; otherwise, they are simply listed. The default limit is
|
||||
@code{100}.
|
||||
|
||||
@item keymap
|
||||
@vindex keymap
|
||||
Sets Readline's idea of the current keymap for key binding commands.
|
||||
Acceptable @code{keymap} names are
|
||||
@code{emacs},
|
||||
@code{emacs-standard},
|
||||
@code{emacs-meta},
|
||||
@code{emacs-ctlx},
|
||||
@code{vi},
|
||||
@code{vi-move},
|
||||
@code{vi-command}, and
|
||||
@code{vi-insert}.
|
||||
@code{vi} is equivalent to @code{vi-command}; @code{emacs} is
|
||||
equivalent to @code{emacs-standard}. The default value is @code{emacs}.
|
||||
The value of the @code{editing-mode} variable also affects the
|
||||
default keymap.
|
||||
|
||||
@item show-all-if-ambiguous
|
||||
@vindex show-all-if-ambiguous
|
||||
This alters the default behavior of the completion functions. If
|
||||
set to @code{on},
|
||||
words which have more than one possible completion cause the
|
||||
matches to be listed immediately instead of ringing the bell.
|
||||
The default value is @code{off}.
|
||||
|
||||
@item expand-tilde
|
||||
@vindex expand-tilde
|
||||
If set to @code{on}, tilde expansion is performed when Readline
|
||||
attempts word completion. The default is @code{off}.
|
||||
|
||||
@end table
|
||||
|
||||
@item Key Bindings
|
||||
The syntax for controlling key bindings in the init file is
|
||||
simple. First you have to know the name of the command that you
|
||||
want to change. The following pages contain tables of the command name,
|
||||
the default keybinding, and a short description of what the command
|
||||
does.
|
||||
|
||||
Once you know the name of the command, simply place the name of the key
|
||||
you wish to bind the command to, a colon, and then the name of the
|
||||
command on a line in the init file. The name of the key
|
||||
can be expressed in different ways, depending on which is most
|
||||
comfortable for you.
|
||||
|
||||
@table @asis
|
||||
@item @w{@var{keyname}: @var{function-name} or @var{macro}}
|
||||
@var{keyname} is the name of a key spelled out in English. For example:
|
||||
@example
|
||||
Control-u: universal-argument
|
||||
Meta-Rubout: backward-kill-word
|
||||
Control-o: ">&output"
|
||||
@end example
|
||||
|
||||
In the above example, @samp{C-u} is bound to the function
|
||||
@code{universal-argument}, and @samp{C-o} is bound to run the macro
|
||||
expressed on the right hand side (that is, to insert the text
|
||||
@samp{>&output} into the line).
|
||||
|
||||
@item @w{"@var{keyseq}": @var{function-name} or @var{macro}}
|
||||
@var{keyseq} differs from @var{keyname} above in that strings
|
||||
denoting an entire key sequence can be specified, by placing
|
||||
the key sequence in double quotes. Some GNU Emacs style key
|
||||
escapes can be used, as in the following example, but the
|
||||
special character names are not recognized.
|
||||
|
||||
@example
|
||||
"\C-u": universal-argument
|
||||
"\C-x\C-r": re-read-init-file
|
||||
"\e[11~": "Function Key 1"
|
||||
@end example
|
||||
|
||||
In the above example, @samp{C-u} is bound to the function
|
||||
@code{universal-argument} (just as it was in the first example),
|
||||
@samp{C-x C-r} is bound to the function @code{re-read-init-file}, and
|
||||
@samp{ESC [ 1 1 ~} is bound to insert the text @samp{Function Key 1}.
|
||||
The following escape sequences are available when specifying key
|
||||
sequences:
|
||||
|
||||
@table @code
|
||||
@item @kbd{\C-}
|
||||
control prefix
|
||||
@item @kbd{\M-}
|
||||
meta prefix
|
||||
@item @kbd{\e}
|
||||
an escape character
|
||||
@item @kbd{\\}
|
||||
backslash
|
||||
@item @kbd{\"}
|
||||
@key{"}
|
||||
@item @kbd{\'}
|
||||
@key{'}
|
||||
@end table
|
||||
|
||||
When entering the text of a macro, single or double quotes should
|
||||
be used to indicate a macro definition. Unquoted text
|
||||
is assumed to be a function name. Backslash
|
||||
will quote any character in the macro text, including @key{"}
|
||||
and @key{'}.
|
||||
For example, the following binding will make @kbd{C-x \}
|
||||
insert a single @key{\} into the line:
|
||||
@example
|
||||
"\C-x\\": "\\"
|
||||
@end example
|
||||
|
||||
@end table
|
||||
@end table
|
||||
|
||||
@node Conditional Init Constructs
|
||||
@subsection Conditional Init Constructs
|
||||
|
||||
Readline implements a facility similar in spirit to the conditional
|
||||
compilation features of the C preprocessor which allows key
|
||||
bindings and variable settings to be performed as the result
|
||||
of tests. There are three parser directives used.
|
||||
|
||||
@ftable @code
|
||||
@item $if
|
||||
The @code{$if} construct allows bindings to be made based on the
|
||||
editing mode, the terminal being used, or the application using
|
||||
Readline. The text of the test extends to the end of the line;
|
||||
no characters are required to isolate it.
|
||||
|
||||
@table @code
|
||||
@item mode
|
||||
The @code{mode=} form of the @code{$if} directive is used to test
|
||||
whether Readline is in @code{emacs} or @code{vi} mode.
|
||||
This may be used in conjunction
|
||||
with the @samp{set keymap} command, for instance, to set bindings in
|
||||
the @code{emacs-standard} and @code{emacs-ctlx} keymaps only if
|
||||
Readline is starting out in @code{emacs} mode.
|
||||
|
||||
@item term
|
||||
The @code{term=} form may be used to include terminal-specific
|
||||
key bindings, perhaps to bind the key sequences output by the
|
||||
terminal's function keys. The word on the right side of the
|
||||
@samp{=} is tested against the full name of the terminal and the
|
||||
portion of the terminal name before the first @samp{-}. This
|
||||
allows @var{sun} to match both @var{sun} and @var{sun-cmd},
|
||||
for instance.
|
||||
|
||||
@item application
|
||||
The @var{application} construct is used to include
|
||||
application-specific settings. Each program using the Readline
|
||||
library sets the @var{application name}, and you can test for it.
|
||||
This could be used to bind key sequences to functions useful for
|
||||
a specific program. For instance, the following command adds a
|
||||
key sequence that quotes the current or previous word in Bash:
|
||||
@example
|
||||
$if bash
|
||||
# Quote the current or previous word
|
||||
"\C-xq": "\eb\"\ef\""
|
||||
$endif
|
||||
@end example
|
||||
@end table
|
||||
|
||||
@item $endif
|
||||
This command, as you saw in the previous example, terminates an
|
||||
@code{$if} command.
|
||||
|
||||
@item $else
|
||||
Commands in this branch of the @code{$if} directive are executed if
|
||||
the test fails.
|
||||
@end ftable
|
||||
|
||||
@node Bindable Readline Commands
|
||||
@section Bindable Readline Commands
|
||||
|
||||
@menu
|
||||
* Commands For Moving:: Moving about the line.
|
||||
* Commands For History:: Getting at previous lines.
|
||||
* Commands For Text:: Commands for changing text.
|
||||
* Commands For Killing:: Commands for killing and yanking.
|
||||
* Numeric Arguments:: Specifying numeric arguments, repeat counts.
|
||||
* Commands For Completion:: Getting Readline to do the typing for you.
|
||||
* Keyboard Macros:: Saving and re-executing typed characters
|
||||
* Miscellaneous Commands:: Other miscellaneous commands.
|
||||
@end menu
|
||||
|
||||
@node Commands For Moving
|
||||
@subsection Commands For Moving
|
||||
@ftable @code
|
||||
@item beginning-of-line (C-a)
|
||||
Move to the start of the current line.
|
||||
|
||||
@item end-of-line (C-e)
|
||||
Move to the end of the line.
|
||||
|
||||
@item forward-char (C-f)
|
||||
Move forward a character.
|
||||
|
||||
@item backward-char (C-b)
|
||||
Move back a character.
|
||||
|
||||
@item forward-word (M-f)
|
||||
Move forward to the end of the next word. Words are composed of
|
||||
letters and digits.
|
||||
|
||||
@item backward-word (M-b)
|
||||
Move back to the start of this, or the previous, word. Words are
|
||||
composed of letters and digits.
|
||||
|
||||
@item clear-screen (C-l)
|
||||
Clear the screen and redraw the current line,
|
||||
leaving the current line at the top of the screen.
|
||||
|
||||
@item redraw-current-line ()
|
||||
Refresh the current line. By default, this is unbound.
|
||||
|
||||
@end ftable
|
||||
|
||||
@node Commands For History
|
||||
@subsection Commands For Manipulating The History
|
||||
|
||||
@ftable @code
|
||||
@item accept-line (Newline, Return)
|
||||
@ifset BashFeatures
|
||||
Accept the line regardless of where the cursor is. If this line is
|
||||
non-empty, add it to the history list according to the setting of
|
||||
the @code{HISTCONTROL} variable. If this line was a history
|
||||
line, then restore the history line to its original state.
|
||||
@end ifset
|
||||
@ifclear BashFeatures
|
||||
Accept the line regardless of where the cursor is. If this line is
|
||||
non-empty, add it to the history list. If this line was a history
|
||||
line, then restore the history line to its original state.
|
||||
@end ifclear
|
||||
|
||||
@item previous-history (C-p)
|
||||
Move `up' through the history list.
|
||||
|
||||
@item next-history (C-n)
|
||||
Move `down' through the history list.
|
||||
|
||||
@item beginning-of-history (M-<)
|
||||
Move to the first line in the history.
|
||||
|
||||
@item end-of-history (M->)
|
||||
Move to the end of the input history, i.e., the line you are entering.
|
||||
|
||||
@item reverse-search-history (C-r)
|
||||
Search backward starting at the current line and moving `up' through
|
||||
the history as necessary. This is an incremental search.
|
||||
|
||||
@item forward-search-history (C-s)
|
||||
Search forward starting at the current line and moving `down' through
|
||||
the the history as necessary. This is an incremental search.
|
||||
|
||||
@item non-incremental-reverse-search-history (M-p)
|
||||
Search backward starting at the current line and moving `up'
|
||||
through the history as necessary using a non-incremental search
|
||||
for a string supplied by the user.
|
||||
|
||||
@item non-incremental-forward-search-history (M-n)
|
||||
Search forward starting at the current line and moving `down'
|
||||
through the the history as necessary using a non-incremental search
|
||||
for a string supplied by the user.
|
||||
|
||||
@item history-search-forward ()
|
||||
Search forward through the history for the string of characters
|
||||
between the start of the current line and the current point. This
|
||||
is a non-incremental search. By default, this command is unbound.
|
||||
|
||||
@item history-search-backward ()
|
||||
Search backward through the history for the string of characters
|
||||
between the start of the current line and the current point. This
|
||||
is a non-incremental search. By default, this command is unbound.
|
||||
|
||||
@item yank-nth-arg (M-C-y)
|
||||
Insert the first argument to the previous command (usually
|
||||
the second word on the previous line). With an argument @var{n},
|
||||
insert the @var{n}th word from the previous command (the words
|
||||
in the previous command begin with word 0). A negative argument
|
||||
inserts the @var{n}th word from the end of the previous command.
|
||||
|
||||
@item yank-last-arg (M-., M-_)
|
||||
Insert last argument to the previous command (the last word on the
|
||||
previous line). With an
|
||||
argument, behave exactly like @code{yank-nth-arg}.
|
||||
|
||||
@end ftable
|
||||
|
||||
@node Commands For Text
|
||||
@subsection Commands For Changing Text
|
||||
|
||||
@ftable @code
|
||||
@item delete-char (C-d)
|
||||
Delete the character under the cursor. If the cursor is at the
|
||||
beginning of the line, there are no characters in the line, and
|
||||
the last character typed was not C-d, then return EOF.
|
||||
|
||||
@item backward-delete-char (Rubout)
|
||||
Delete the character behind the cursor. A numeric arg says to kill
|
||||
the characters instead of deleting them.
|
||||
|
||||
@item quoted-insert (C-q, C-v)
|
||||
Add the next character that you type to the line verbatim. This is
|
||||
how to insert key sequences like @key{C-q}, for example.
|
||||
|
||||
@item tab-insert (M-TAB)
|
||||
Insert a tab character.
|
||||
|
||||
@item self-insert (a, b, A, 1, !, ...)
|
||||
Insert yourself.
|
||||
|
||||
@item transpose-chars (C-t)
|
||||
Drag the character before the cursor forward over
|
||||
the character at the cursor, moving the
|
||||
cursor forward as well. If the insertion point
|
||||
is at the end of the line, then this
|
||||
transposes the last two characters of the line.
|
||||
Negative argumentss don't work.
|
||||
|
||||
@item transpose-words (M-t)
|
||||
Drag the word behind the cursor past the word in front of the cursor
|
||||
moving the cursor over that word as well.
|
||||
|
||||
@item upcase-word (M-u)
|
||||
Uppercase the current (or following) word. With a negative argument,
|
||||
do the previous word, but do not move the cursor.
|
||||
|
||||
@item downcase-word (M-l)
|
||||
Lowercase the current (or following) word. With a negative argument,
|
||||
do the previous word, but do not move the cursor.
|
||||
|
||||
@item capitalize-word (M-c)
|
||||
Capitalize the current (or following) word. With a negative argument,
|
||||
do the previous word, but do not move the cursor.
|
||||
|
||||
@end ftable
|
||||
|
||||
@node Commands For Killing
|
||||
@subsection Killing And Yanking
|
||||
|
||||
@ftable @code
|
||||
|
||||
@item kill-line (C-k)
|
||||
Kill the text from the current cursor position to the end of the line.
|
||||
|
||||
@item backward-kill-line (C-x Rubout)
|
||||
Kill backward to the beginning of the line.
|
||||
|
||||
@item unix-line-discard (C-u)
|
||||
Kill backward from the cursor to the beginning of the current line.
|
||||
Save the killed text on the kill-ring.
|
||||
|
||||
@item kill-whole-line ()
|
||||
Kill all characters on the current line, no matter where the
|
||||
cursor is. By default, this is unbound.
|
||||
|
||||
@item kill-word (M-d)
|
||||
Kill from the cursor to the end of the current word, or if between
|
||||
words, to the end of the next word. Word boundaries are the same
|
||||
as @code{forward-word}.
|
||||
|
||||
@item backward-kill-word (M-DEL)
|
||||
Kill the word behind the cursor. Word boundaries are the same
|
||||
as @code{backward-word}.
|
||||
|
||||
@item unix-word-rubout (C-w)
|
||||
Kill the word behind the cursor, using white space as a word
|
||||
boundary. The killed text is saved on the kill-ring.
|
||||
|
||||
@item delete-horizontal-space ()
|
||||
Delete all spaces and tabs around point. By default, this is unbound.
|
||||
|
||||
@item yank (C-y)
|
||||
Yank the top of the kill ring into the buffer at the current
|
||||
cursor position.
|
||||
|
||||
@item yank-pop (M-y)
|
||||
Rotate the kill-ring, and yank the new top. You can only do this if
|
||||
the prior command is yank or yank-pop.
|
||||
@end ftable
|
||||
|
||||
@node Numeric Arguments
|
||||
@subsection Specifying Numeric Arguments
|
||||
@ftable @code
|
||||
|
||||
@item digit-argument (M-0, M-1, ... M--)
|
||||
Add this digit to the argument already accumulating, or start a new
|
||||
argument. M-- starts a negative argument.
|
||||
|
||||
@item universal-argument ()
|
||||
Each time this is executed, the argument count is multiplied by four.
|
||||
The argument count is initially one, so executing this function the
|
||||
first time makes the argument count four. By default, this is not
|
||||
bound to a key.
|
||||
@end ftable
|
||||
|
||||
@node Commands For Completion
|
||||
@subsection Letting Readline Type For You
|
||||
|
||||
@ftable @code
|
||||
@item complete (TAB)
|
||||
Attempt to do completion on the text before the cursor. This is
|
||||
application-specific. Generally, if you are typing a filename
|
||||
argument, you can do filename completion; if you are typing a command,
|
||||
you can do command completion, if you are typing in a symbol to GDB, you
|
||||
can do symbol name completion, if you are typing in a variable to Bash,
|
||||
you can do variable name completion, and so on.
|
||||
@ifset BashFeatures
|
||||
See the Bash manual page for a complete list of available completion
|
||||
functions.
|
||||
@end ifset
|
||||
|
||||
@item possible-completions (M-?)
|
||||
List the possible completions of the text before the cursor.
|
||||
|
||||
@item insert-completions ()
|
||||
Insert all completions of the text before point that would have
|
||||
been generated by @code{possible-completions}. By default, this
|
||||
is not bound to a key.
|
||||
|
||||
@end ftable
|
||||
|
||||
@node Keyboard Macros
|
||||
@subsection Keyboard Macros
|
||||
@ftable @code
|
||||
|
||||
@item start-kbd-macro (C-x ()
|
||||
Begin saving the characters typed into the current keyboard macro.
|
||||
|
||||
@item end-kbd-macro (C-x ))
|
||||
Stop saving the characters typed into the current keyboard macro
|
||||
and save the definition.
|
||||
|
||||
@item call-last-kbd-macro (C-x e)
|
||||
Re-execute the last keyboard macro defined, by making the characters
|
||||
in the macro appear as if typed at the keyboard.
|
||||
|
||||
@end ftable
|
||||
|
||||
@node Miscellaneous Commands
|
||||
@subsection Some Miscellaneous Commands
|
||||
@ftable @code
|
||||
|
||||
@item re-read-init-file (C-x C-r)
|
||||
Read in the contents of your init file, and incorporate
|
||||
any bindings or variable assignments found there.
|
||||
|
||||
@item abort (C-g)
|
||||
Abort the current editing command and
|
||||
ring the terminal's bell (subject to the setting of
|
||||
@code{bell-style}).
|
||||
|
||||
@item do-uppercase-version (M-a, M-b, ...)
|
||||
Run the command that is bound to the corresoponding uppercase
|
||||
character.
|
||||
|
||||
@item prefix-meta (ESC)
|
||||
Make the next character that you type be metafied. This is for people
|
||||
without a meta key. Typing @samp{ESC f} is equivalent to typing
|
||||
@samp{M-f}.
|
||||
|
||||
@item undo (C-_, C-x C-u)
|
||||
Incremental undo, separately remembered for each line.
|
||||
|
||||
@item revert-line (M-r)
|
||||
Undo all changes made to this line. This is like typing the @code{undo}
|
||||
command enough times to get back to the beginning.
|
||||
|
||||
@item tilde-expand (M-~)
|
||||
Perform tilde expansion on the current word.
|
||||
|
||||
@item dump-functions ()
|
||||
Print all of the functions and their key bindings to the
|
||||
readline output stream. If a numeric argument is supplied,
|
||||
the output is formatted in such a way that it can be made part
|
||||
of an @var{inputrc} file.
|
||||
|
||||
@ifset BashFeatures
|
||||
@item display-shell-version (C-x C-v)
|
||||
Display version information about the current instance of Bash.
|
||||
|
||||
@item shell-expand-line (M-C-e)
|
||||
Expand the line the way the shell does when it reads it. This
|
||||
performs alias and history expansion as well as all of the shell
|
||||
word expansions.
|
||||
|
||||
@item history-expand-line (M-^)
|
||||
Perform history expansion on the current line.
|
||||
|
||||
@item insert-last-argument (M-., M-_)
|
||||
A synonym for @code{yank-last-arg}.
|
||||
|
||||
@item operate-and-get-next (C-o)
|
||||
Accept the current line for execution and fetch the next line
|
||||
relative to the current line from the history for editing. Any
|
||||
argument is ignored.
|
||||
|
||||
@item emacs-editing-mode (C-e)
|
||||
When in @code{vi} editing mode, this causes a switch back to
|
||||
emacs editing mode, as if the command @code{set -o emacs} had
|
||||
been executed.
|
||||
|
||||
@end ifset
|
||||
|
||||
@end ftable
|
||||
|
||||
@node Readline vi Mode
|
||||
@section Readline vi Mode
|
||||
|
||||
While the Readline library does not have a full set of @code{vi}
|
||||
editing functions, it does contain enough to allow simple editing
|
||||
of the line. The Readline @code{vi} mode behaves as specified in
|
||||
the Posix 1003.2 standard.
|
||||
|
||||
@ifset BashFeatures
|
||||
In order to switch interactively between @code{Emacs} and @code{Vi}
|
||||
editing modes, use the @code{set -o emacs} and @code{set -o vi}
|
||||
commands (@pxref{The Set Builtin}).
|
||||
@end ifset
|
||||
@ifclear BashFeatures
|
||||
In order to switch interactively between @code{Emacs} and @code{Vi}
|
||||
editing modes, use the command M-C-j (toggle-editing-mode).
|
||||
@end ifclear
|
||||
The Readline default is @code{emacs} mode.
|
||||
|
||||
When you enter a line in @code{vi} mode, you are already placed in
|
||||
`insertion' mode, as if you had typed an @samp{i}. Pressing @key{ESC}
|
||||
switches you into `command' mode, where you can edit the text of the
|
||||
line with the standard @code{vi} movement keys, move to previous
|
||||
history lines with @samp{k}, and following lines with @samp{j}, and
|
||||
so forth.
|
||||
1666
lib/readline/doc/texindex.c
Normal file
1666
lib/readline/doc/texindex.c
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user