1548 lines
51 KiB
Text
1548 lines
51 KiB
Text
@comment %**start of header (This is for running Texinfo on a region.)
|
|
@setfilename rltech.info
|
|
@comment %**end of header (This is for running Texinfo on a region.)
|
|
@setchapternewpage odd
|
|
|
|
@ifinfo
|
|
This document describes the GNU Readline Library, a utility for aiding
|
|
in the consitency of user interface across discrete programs that need
|
|
to provide a command line interface.
|
|
|
|
Copyright (C) 1988, 1994, 1996 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
|
|
|
|
@node Programming with GNU Readline
|
|
@chapter Programming with GNU Readline
|
|
|
|
This chapter describes the interface between the GNU Readline Library and
|
|
other programs. If you are a programmer, and you wish to include the
|
|
features found in GNU Readline
|
|
such as completion, line editing, and interactive history manipulation
|
|
in your own programs, this section is for you.
|
|
|
|
@menu
|
|
* Basic Behavior:: Using the default behavior of Readline.
|
|
* Custom Functions:: Adding your own functions to Readline.
|
|
* Readline Variables:: Variables accessible to custom
|
|
functions.
|
|
* Readline Convenience Functions:: Functions which Readline supplies to
|
|
aid in writing your own
|
|
* Custom Completers:: Supplanting or supplementing Readline's
|
|
completion functions.
|
|
@end menu
|
|
|
|
@node Basic Behavior
|
|
@section Basic Behavior
|
|
|
|
Many programs provide a command line interface, such as @code{mail},
|
|
@code{ftp}, and @code{sh}. For such programs, the default behaviour of
|
|
Readline is sufficient. This section describes how to use Readline in
|
|
the simplest way possible, perhaps to replace calls in your code to
|
|
@code{gets()} or @code{fgets ()}.
|
|
|
|
@findex readline
|
|
@cindex readline, function
|
|
The function @code{readline ()} prints a prompt and then reads and returns
|
|
a single line of text from the user. The line @code{readline}
|
|
returns is allocated with @code{malloc ()}; you should @code{free ()}
|
|
the line when you are done with it. The declaration for @code{readline}
|
|
in ANSI C is
|
|
|
|
@example
|
|
@code{char *readline (char *@var{prompt});}
|
|
@end example
|
|
|
|
@noindent
|
|
So, one might say
|
|
@example
|
|
@code{char *line = readline ("Enter a line: ");}
|
|
@end example
|
|
@noindent
|
|
in order to read a line of text from the user.
|
|
The line returned has the final newline removed, so only the
|
|
text remains.
|
|
|
|
If @code{readline} encounters an @code{EOF} while reading the line, and the
|
|
line is empty at that point, then @code{(char *)NULL} is returned.
|
|
Otherwise, the line is ended just as if a newline had been typed.
|
|
|
|
If you want the user to be able to get at the line later, (with
|
|
@key{C-p} for example), you must call @code{add_history ()} to save the
|
|
line away in a @dfn{history} list of such lines.
|
|
|
|
@example
|
|
@code{add_history (line)};
|
|
@end example
|
|
|
|
@noindent
|
|
For full details on the GNU History Library, see the associated manual.
|
|
|
|
It is preferable to avoid saving empty lines on the history list, since
|
|
users rarely have a burning need to reuse a blank line. Here is
|
|
a function which usefully replaces the standard @code{gets ()} library
|
|
function, and has the advantage of no static buffer to overflow:
|
|
|
|
@example
|
|
/* A static variable for holding the line. */
|
|
static char *line_read = (char *)NULL;
|
|
|
|
/* Read a string, and return a pointer to it. Returns NULL on EOF. */
|
|
char *
|
|
rl_gets ()
|
|
@{
|
|
/* If the buffer has already been allocated, return the memory
|
|
to the free pool. */
|
|
if (line_read)
|
|
@{
|
|
free (line_read);
|
|
line_read = (char *)NULL;
|
|
@}
|
|
|
|
/* Get a line from the user. */
|
|
line_read = readline ("");
|
|
|
|
/* If the line has any text in it, save it on the history. */
|
|
if (line_read && *line_read)
|
|
add_history (line_read);
|
|
|
|
return (line_read);
|
|
@}
|
|
@end example
|
|
|
|
This function gives the user the default behaviour of @key{TAB}
|
|
completion: completion on file names. If you do not want Readline to
|
|
complete on filenames, you can change the binding of the @key{TAB} key
|
|
with @code{rl_bind_key ()}.
|
|
|
|
@example
|
|
@code{int rl_bind_key (int @var{key}, int (*@var{function})());}
|
|
@end example
|
|
|
|
@code{rl_bind_key ()} takes two arguments: @var{key} is the character that
|
|
you want to bind, and @var{function} is the address of the function to
|
|
call when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert ()}
|
|
makes @key{TAB} insert itself.
|
|
@code{rl_bind_key ()} returns non-zero if @var{key} is not a valid
|
|
ASCII character code (between 0 and 255).
|
|
|
|
Thus, to disable the default @key{TAB} behavior, the following suffices:
|
|
@example
|
|
@code{rl_bind_key ('\t', rl_insert);}
|
|
@end example
|
|
|
|
This code should be executed once at the start of your program; you
|
|
might write a function called @code{initialize_readline ()} which
|
|
performs this and other desired initializations, such as installing
|
|
custom completers (@pxref{Custom Completers}).
|
|
|
|
@node Custom Functions
|
|
@section Custom Functions
|
|
|
|
Readline provides many functions for manipulating the text of
|
|
the line, but it isn't possible to anticipate the needs of all
|
|
programs. This section describes the various functions and variables
|
|
defined within the Readline library which allow a user program to add
|
|
customized functionality to Readline.
|
|
|
|
@menu
|
|
* The Function Type:: C declarations to make code readable.
|
|
* Function Writing:: Variables and calling conventions.
|
|
@end menu
|
|
|
|
@node The Function Type
|
|
@subsection The Function Type
|
|
|
|
For readabilty, we declare a new type of object, called
|
|
@dfn{Function}. A @code{Function} is a C function which
|
|
returns an @code{int}. The type declaration for @code{Function} is:
|
|
|
|
@noindent
|
|
@code{typedef int Function ();}
|
|
|
|
The reason for declaring this new type is to make it easier to write
|
|
code describing pointers to C functions. Let us say we had a variable
|
|
called @var{func} which was a pointer to a function. Instead of the
|
|
classic C declaration
|
|
|
|
@code{int (*)()func;}
|
|
|
|
@noindent
|
|
we may write
|
|
|
|
@code{Function *func;}
|
|
|
|
@noindent
|
|
Similarly, there are
|
|
|
|
@example
|
|
typedef void VFunction ();
|
|
typedef char *CPFunction (); @r{and}
|
|
typedef char **CPPFunction ();
|
|
@end example
|
|
|
|
@noindent
|
|
for functions returning no value, @code{pointer to char}, and
|
|
@code{pointer to pointer to char}, respectively.
|
|
|
|
@node Function Writing
|
|
@subsection Writing a New Function
|
|
|
|
In order to write new functions for Readline, you need to know the
|
|
calling conventions for keyboard-invoked functions, and the names of the
|
|
variables that describe the current state of the line read so far.
|
|
|
|
The calling sequence for a command @code{foo} looks like
|
|
|
|
@example
|
|
@code{foo (int count, int key)}
|
|
@end example
|
|
|
|
@noindent
|
|
where @var{count} is the numeric argument (or 1 if defaulted) and
|
|
@var{key} is the key that invoked this function.
|
|
|
|
It is completely up to the function as to what should be done with the
|
|
numeric argument. Some functions use it as a repeat count, some
|
|
as a flag, and others to choose alternate behavior (refreshing the current
|
|
line as opposed to refreshing the screen, for example). Some choose to
|
|
ignore it. In general, if a
|
|
function uses the numeric argument as a repeat count, it should be able
|
|
to do something useful with both negative and positive arguments.
|
|
At the very least, it should be aware that it can be passed a
|
|
negative argument.
|
|
|
|
@node Readline Variables
|
|
@section Readline Variables
|
|
|
|
These variables are available to function writers.
|
|
|
|
@deftypevar {char *} rl_line_buffer
|
|
This is the line gathered so far. You are welcome to modify the
|
|
contents of the line, but see @ref{Allowing Undoing}.
|
|
@end deftypevar
|
|
|
|
@deftypevar int rl_point
|
|
The offset of the current cursor position in @code{rl_line_buffer}
|
|
(the @emph{point}).
|
|
@end deftypevar
|
|
|
|
@deftypevar int rl_end
|
|
The number of characters present in @code{rl_line_buffer}. When
|
|
@code{rl_point} is at the end of the line, @code{rl_point} and
|
|
@code{rl_end} are equal.
|
|
@end deftypevar
|
|
|
|
@deftypevar int rl_mark
|
|
The mark (saved position) in the current line. If set, the mark
|
|
and point define a @emph{region}.
|
|
@end deftypevar
|
|
|
|
@deftypevar int rl_done
|
|
Setting this to a non-zero value causes Readline to return the current
|
|
line immediately.
|
|
@end deftypevar
|
|
|
|
@deftypevar int rl_pending_input
|
|
Setting this to a value makes it the next keystroke read. This is a
|
|
way to stuff a single character into the input stream.
|
|
@end deftypevar
|
|
|
|
@deftypevar {char *} rl_prompt
|
|
The prompt Readline uses. This is set from the argument to
|
|
@code{readline ()}, and should not be assigned to directly.
|
|
@end deftypevar
|
|
|
|
@deftypevar {char *} rl_library_version
|
|
The version number of this revision of the library.
|
|
@end deftypevar
|
|
|
|
@deftypevar {char *} rl_terminal_name
|
|
The terminal type, used for initialization.
|
|
@end deftypevar
|
|
|
|
@deftypevar {char *} rl_readline_name
|
|
This variable is set to a unique name by each application using Readline.
|
|
The value allows conditional parsing of the inputrc file
|
|
(@pxref{Conditional Init Constructs}).
|
|
@end deftypevar
|
|
|
|
@deftypevar {FILE *} rl_instream
|
|
The stdio stream from which Readline reads input.
|
|
@end deftypevar
|
|
|
|
@deftypevar {FILE *} rl_outstream
|
|
The stdio stream to which Readline performs output.
|
|
@end deftypevar
|
|
|
|
@deftypevar {Function *} rl_startup_hook
|
|
If non-zero, this is the address of a function to call just
|
|
before @code{readline} prints the first prompt.
|
|
@end deftypevar
|
|
|
|
@deftypevar {Function *} rl_event_hook
|
|
If non-zero, this is the address of a function to call periodically
|
|
when readline is waiting for terminal input.
|
|
@end deftypevar
|
|
|
|
@deftypevar {Function *} rl_getc_function
|
|
If non-zero, @code{readline} will call indirectly through this pointer
|
|
to get a character from the input stream. By default, it is set to
|
|
@code{rl_getc}, the default @code{readline} character input function
|
|
(@pxref{Utility Functions}).
|
|
@end deftypevar
|
|
|
|
@deftypevar {VFunction *} rl_redisplay_function
|
|
If non-zero, @code{readline} will call indirectly through this pointer
|
|
to update the display with the current contents of the editing buffer.
|
|
By default, it is set to @code{rl_redisplay}, the default @code{readline}
|
|
redisplay function (@pxref{Redisplay}).
|
|
@end deftypevar
|
|
|
|
@deftypevar {Keymap} rl_executing_keymap
|
|
This variable is set to the keymap (@pxref{Keymaps}) in which the
|
|
currently executing readline function was found.
|
|
@end deftypevar
|
|
|
|
@deftypevar {Keymap} rl_binding_keymap
|
|
This variable is set to the keymap (@pxref{Keymaps}) in which the
|
|
last key binding occurred.
|
|
@end deftypevar
|
|
|
|
@node Readline Convenience Functions
|
|
@section Readline Convenience Functions
|
|
|
|
@menu
|
|
* Function Naming:: How to give a function you write a name.
|
|
* Keymaps:: Making keymaps.
|
|
* Binding Keys:: Changing Keymaps.
|
|
* Associating Function Names and Bindings:: Translate function names to
|
|
key sequences.
|
|
* Allowing Undoing:: How to make your functions undoable.
|
|
* Redisplay:: Functions to control line display.
|
|
* Modifying Text:: Functions to modify @code{rl_line_buffer}.
|
|
* Utility Functions:: Generally useful functions and hooks.
|
|
* Alternate Interface:: Using Readline in a `callback' fashion.
|
|
@end menu
|
|
|
|
@node Function Naming
|
|
@subsection Naming a Function
|
|
|
|
The user can dynamically change the bindings of keys while using
|
|
Readline. This is done by representing the function with a descriptive
|
|
name. The user is able to type the descriptive name when referring to
|
|
the function. Thus, in an init file, one might find
|
|
|
|
@example
|
|
Meta-Rubout: backward-kill-word
|
|
@end example
|
|
|
|
This binds the keystroke @key{Meta-Rubout} to the function
|
|
@emph{descriptively} named @code{backward-kill-word}. You, as the
|
|
programmer, should bind the functions you write to descriptive names as
|
|
well. Readline provides a function for doing that:
|
|
|
|
@deftypefun int rl_add_defun (char *name, Function *function, int key)
|
|
Add @var{name} to the list of named functions. Make @var{function} be
|
|
the function that gets called. If @var{key} is not -1, then bind it to
|
|
@var{function} using @code{rl_bind_key ()}.
|
|
@end deftypefun
|
|
|
|
Using this function alone is sufficient for most applications. It is
|
|
the recommended way to add a few functions to the default functions that
|
|
Readline has built in. If you need to do something other
|
|
than adding a function to Readline, you may need to use the
|
|
underlying functions described below.
|
|
|
|
@node Keymaps
|
|
@subsection Selecting a Keymap
|
|
|
|
Key bindings take place on a @dfn{keymap}. The keymap is the
|
|
association between the keys that the user types and the functions that
|
|
get run. You can make your own keymaps, copy existing keymaps, and tell
|
|
Readline which keymap to use.
|
|
|
|
@deftypefun Keymap rl_make_bare_keymap ()
|
|
Returns a new, empty keymap. The space for the keymap is allocated with
|
|
@code{malloc ()}; you should @code{free ()} it when you are done.
|
|
@end deftypefun
|
|
|
|
@deftypefun Keymap rl_copy_keymap (Keymap map)
|
|
Return a new keymap which is a copy of @var{map}.
|
|
@end deftypefun
|
|
|
|
@deftypefun Keymap rl_make_keymap ()
|
|
Return a new keymap with the printing characters bound to rl_insert,
|
|
the lowercase Meta characters bound to run their equivalents, and
|
|
the Meta digits bound to produce numeric arguments.
|
|
@end deftypefun
|
|
|
|
@deftypefun void rl_discard_keymap (Keymap keymap)
|
|
Free the storage associated with @var{keymap}.
|
|
@end deftypefun
|
|
|
|
Readline has several internal keymaps. These functions allow you to
|
|
change which keymap is active.
|
|
|
|
@deftypefun Keymap rl_get_keymap ()
|
|
Returns the currently active keymap.
|
|
@end deftypefun
|
|
|
|
@deftypefun void rl_set_keymap (Keymap keymap)
|
|
Makes @var{keymap} the currently active keymap.
|
|
@end deftypefun
|
|
|
|
@deftypefun Keymap rl_get_keymap_by_name (char *name)
|
|
Return the keymap matching @var{name}. @var{name} is one which would
|
|
be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
|
|
@end deftypefun
|
|
|
|
@deftypefun {char *} rl_get_keymap_name (Keymap keymap)
|
|
Return the name matching @var{keymap}. @var{name} is one which would
|
|
be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
|
|
@end deftypefun
|
|
|
|
@node Binding Keys
|
|
@subsection Binding Keys
|
|
|
|
You associate keys with functions through the keymap. Readline has
|
|
several internal keymaps: @code{emacs_standard_keymap},
|
|
@code{emacs_meta_keymap}, @code{emacs_ctlx_keymap},
|
|
@code{vi_movement_keymap}, and @code{vi_insertion_keymap}.
|
|
@code{emacs_standard_keymap} is the default, and the examples in
|
|
this manual assume that.
|
|
|
|
These functions manage key bindings.
|
|
|
|
@deftypefun int rl_bind_key (int key, Function *function)
|
|
Binds @var{key} to @var{function} in the currently active keymap.
|
|
Returns non-zero in the case of an invalid @var{key}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_bind_key_in_map (int key, Function *function, Keymap map)
|
|
Bind @var{key} to @var{function} in @var{map}. Returns non-zero in the case
|
|
of an invalid @var{key}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_unbind_key (int key)
|
|
Bind @var{key} to the null function in the currently active keymap.
|
|
Returns non-zero in case of error.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_unbind_key_in_map (int key, Keymap map)
|
|
Bind @var{key} to the null function in @var{map}.
|
|
Returns non-zero in case of error.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_unbind_function_in_map (Function *function, Keymap map)
|
|
Unbind all keys that execute @var{function} in @var{map}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_unbind_command_in_map (char *command, Keymap map)
|
|
Unbind all keys that are bound to @var{command} in @var{map}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_generic_bind (int type, char *keyseq, char *data, Keymap map)
|
|
Bind the key sequence represented by the string @var{keyseq} to the arbitrary
|
|
pointer @var{data}. @var{type} says what kind of data is pointed to by
|
|
@var{data}; this can be a function (@code{ISFUNC}), a macro
|
|
(@code{ISMACR}), or a keymap (@code{ISKMAP}). This makes new keymaps as
|
|
necessary. The initial keymap in which to do bindings is @var{map}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_parse_and_bind (char *line)
|
|
Parse @var{line} as if it had been read from the @code{inputrc} file and
|
|
perform any key bindings and variable assignments found
|
|
(@pxref{Readline Init File}).
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_read_init_file (char *filename)
|
|
Read keybindings and variable assignments from @var{filename}
|
|
(@pxref{Readline Init File}).
|
|
@end deftypefun
|
|
|
|
@node Associating Function Names and Bindings
|
|
@subsection Associating Function Names and Bindings
|
|
|
|
These functions allow you to find out what keys invoke named functions
|
|
and the functions invoked by a particular key sequence.
|
|
|
|
@deftypefun {Function *} rl_named_function (char *name)
|
|
Return the function with name @var{name}.
|
|
@end deftypefun
|
|
|
|
@deftypefun {Function *} rl_function_of_keyseq (char *keyseq, Keymap map, int *type)
|
|
Return the function invoked by @var{keyseq} in keymap @var{map}.
|
|
If @var{map} is NULL, the current keymap is used. If @var{type} is
|
|
not NULL, the type of the object is returned in it (one of @code{ISFUNC},
|
|
@code{ISKMAP}, or @code{ISMACR}).
|
|
@end deftypefun
|
|
|
|
@deftypefun {char **} rl_invoking_keyseqs (Function *function)
|
|
Return an array of strings representing the key sequences used to
|
|
invoke @var{function} in the current keymap.
|
|
@end deftypefun
|
|
|
|
@deftypefun {char **} rl_invoking_keyseqs_in_map (Function *function, Keymap map)
|
|
Return an array of strings representing the key sequences used to
|
|
invoke @var{function} in the keymap @var{map}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void rl_function_dumper (int readable)
|
|
Print the readline function names and the key sequences currently
|
|
bound to them to @code{rl_outstream}. If @var{readable} is non-zero,
|
|
the list is formatted in such a way that it can be made part of an
|
|
@code{inputrc} file and re-read.
|
|
@end deftypefun
|
|
|
|
@deftypefun void rl_list_funmap_names ()
|
|
Print the names of all bindable Readline functions to @code{rl_outstream}.
|
|
@end deftypefun
|
|
|
|
@node Allowing Undoing
|
|
@subsection Allowing Undoing
|
|
|
|
Supporting the undo command is a painless thing, and makes your
|
|
functions much more useful. It is certainly easy to try
|
|
something if you know you can undo it. I could use an undo function for
|
|
the stock market.
|
|
|
|
If your function simply inserts text once, or deletes text once, and
|
|
uses @code{rl_insert_text ()} or @code{rl_delete_text ()} to do it, then
|
|
undoing is already done for you automatically.
|
|
|
|
If you do multiple insertions or multiple deletions, or any combination
|
|
of these operations, you should group them together into one operation.
|
|
This is done with @code{rl_begin_undo_group ()} and
|
|
@code{rl_end_undo_group ()}.
|
|
|
|
The types of events that can be undone are:
|
|
|
|
@example
|
|
enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @};
|
|
@end example
|
|
|
|
Notice that @code{UNDO_DELETE} means to insert some text, and
|
|
@code{UNDO_INSERT} means to delete some text. That is, the undo code
|
|
tells undo what to undo, not how to undo it. @code{UNDO_BEGIN} and
|
|
@code{UNDO_END} are tags added by @code{rl_begin_undo_group ()} and
|
|
@code{rl_end_undo_group ()}.
|
|
|
|
@deftypefun int rl_begin_undo_group ()
|
|
Begins saving undo information in a group construct. The undo
|
|
information usually comes from calls to @code{rl_insert_text ()} and
|
|
@code{rl_delete_text ()}, but could be the result of calls to
|
|
@code{rl_add_undo ()}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_end_undo_group ()
|
|
Closes the current undo group started with @code{rl_begin_undo_group
|
|
()}. There should be one call to @code{rl_end_undo_group ()}
|
|
for each call to @code{rl_begin_undo_group ()}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text)
|
|
Remember how to undo an event (according to @var{what}). The affected
|
|
text runs from @var{start} to @var{end}, and encompasses @var{text}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void free_undo_list ()
|
|
Free the existing undo list.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_do_undo ()
|
|
Undo the first thing on the undo list. Returns @code{0} if there was
|
|
nothing to undo, non-zero if something was undone.
|
|
@end deftypefun
|
|
|
|
Finally, if you neither insert nor delete text, but directly modify the
|
|
existing text (e.g., change its case), call @code{rl_modifying ()}
|
|
once, just before you modify the text. You must supply the indices of
|
|
the text range that you are going to modify.
|
|
|
|
@deftypefun int rl_modifying (int start, int end)
|
|
Tell Readline to save the text between @var{start} and @var{end} as a
|
|
single undo unit. It is assumed that you will subsequently modify
|
|
that text.
|
|
@end deftypefun
|
|
|
|
@node Redisplay
|
|
@subsection Redisplay
|
|
|
|
@deftypefun void rl_redisplay ()
|
|
Change what's displayed on the screen to reflect the current contents
|
|
of @code{rl_line_buffer}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_forced_update_display ()
|
|
Force the line to be updated and redisplayed, whether or not
|
|
Readline thinks the screen display is correct.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_on_new_line ()
|
|
Tell the update routines that we have moved onto a new (empty) line,
|
|
usually after ouputting a newline.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_reset_line_state ()
|
|
Reset the display state to a clean state and redisplay the current line
|
|
starting on a new line.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_message (va_alist)
|
|
The arguments are a string as would be supplied to @code{printf}. The
|
|
resulting string is displayed in the @dfn{echo area}. The echo area
|
|
is also used to display numeric arguments and search strings.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_clear_message ()
|
|
Clear the message in the echo area.
|
|
@end deftypefun
|
|
|
|
@node Modifying Text
|
|
@subsection Modifying Text
|
|
|
|
@deftypefun int rl_insert_text (char *text)
|
|
Insert @var{text} into the line at the current cursor position.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_delete_text (int start, int end)
|
|
Delete the text between @var{start} and @var{end} in the current line.
|
|
@end deftypefun
|
|
|
|
@deftypefun {char *} rl_copy_text (int start, int end)
|
|
Return a copy of the text between @var{start} and @var{end} in
|
|
the current line.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_kill_text (int start, int end)
|
|
Copy the text between @var{start} and @var{end} in the current line
|
|
to the kill ring, appending or prepending to the last kill if the
|
|
last command was a kill command. The text is deleted.
|
|
If @var{start} is less than @var{end},
|
|
the text is appended, otherwise prepended. If the last command was
|
|
not a kill, a new kill ring slot is used.
|
|
@end deftypefun
|
|
|
|
@node Utility Functions
|
|
@subsection Utility Functions
|
|
|
|
@deftypefun int rl_read_key ()
|
|
Return the next character available. This handles input inserted into
|
|
the input stream via @var{pending input} (@pxref{Readline Variables})
|
|
and @code{rl_stuff_char ()}, macros, and characters read from the keyboard.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_getc (FILE *)
|
|
Return the next character available from the keyboard.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_stuff_char (int c)
|
|
Insert @var{c} into the Readline input stream. It will be "read"
|
|
before Readline attempts to read characters from the terminal with
|
|
@code{rl_read_key ()}.
|
|
@end deftypefun
|
|
|
|
@deftypefun rl_extend_line_buffer (int len)
|
|
Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
|
|
characters, possibly reallocating it if necessary.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_initialize ()
|
|
Initialize or re-initialize Readline's internal state.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_reset_terminal (char *terminal_name)
|
|
Reinitialize Readline's idea of the terminal settings using
|
|
@var{terminal_name} as the terminal type (e.g., @code{vt100}).
|
|
@end deftypefun
|
|
|
|
@deftypefun int alphabetic (int c)
|
|
Return 1 if @var{c} is an alphabetic character.
|
|
@end deftypefun
|
|
|
|
@deftypefun int numeric (int c)
|
|
Return 1 if @var{c} is a numeric character.
|
|
@end deftypefun
|
|
|
|
@deftypefun int ding ()
|
|
Ring the terminal bell, obeying the setting of @code{bell-style}.
|
|
@end deftypefun
|
|
|
|
The following are implemented as macros, defined in @code{chartypes.h}.
|
|
|
|
@deftypefun int uppercase_p (int c)
|
|
Return 1 if @var{c} is an uppercase alphabetic character.
|
|
@end deftypefun
|
|
|
|
@deftypefun int lowercase_p (int c)
|
|
Return 1 if @var{c} is a lowercase alphabetic character.
|
|
@end deftypefun
|
|
|
|
@deftypefun int digit_p (int c)
|
|
Return 1 if @var{c} is a numeric character.
|
|
@end deftypefun
|
|
|
|
@deftypefun int to_upper (int c)
|
|
If @var{c} is a lowercase alphabetic character, return the corresponding
|
|
uppercase character.
|
|
@end deftypefun
|
|
|
|
@deftypefun int to_lower (int c)
|
|
If @var{c} is an uppercase alphabetic character, return the corresponding
|
|
lowercase character.
|
|
@end deftypefun
|
|
|
|
@deftypefun int digit_value (int c)
|
|
If @var{c} is a number, return the value it represents.
|
|
@end deftypefun
|
|
|
|
@node Alternate Interface
|
|
@subsection Alternate Interface
|
|
|
|
An alternate interface is available to plain @code{readline()}. Some
|
|
applications need to interleave keyboard I/O with file, device, or
|
|
window system I/O, typically by using a main loop to @code{select()}
|
|
on various file descriptors. To accomodate this need, readline can
|
|
also be invoked as a `callback' function from an event loop. There
|
|
are functions available to make this easy.
|
|
|
|
@deftypefun void rl_callback_handler_install (char *prompt, Vfunction *lhandler)
|
|
Set up the terminal for readline I/O and display the initial
|
|
expanded value of @var{prompt}. Save the value of @var{lhandler} to
|
|
use as a callback when a complete line of input has been entered.
|
|
@end deftypefun
|
|
|
|
@deftypefun void rl_callback_read_char ()
|
|
Whenever an application determines that keyboard input is available, it
|
|
should call @code{rl_callback_read_char()}, which will read the next
|
|
character from the current input source. If that character completes the
|
|
line, @code{rl_callback_read_char} will invoke the @var{lhandler}
|
|
function saved by @code{rl_callback_handler_install} to process the
|
|
line. @code{EOF} is indicated by calling @var{lhandler} with a
|
|
@code{NULL} line.
|
|
@end deftypefun
|
|
|
|
@deftypefun void rl_callback_handler_remove ()
|
|
Restore the terminal to its initial state and remove the line handler.
|
|
This may be called from within a callback as well as independently.
|
|
@end deftypefun
|
|
|
|
@subsection An Example
|
|
|
|
Here is a function which changes lowercase characters to their uppercase
|
|
equivalents, and uppercase characters to lowercase. If
|
|
this function was bound to @samp{M-c}, then typing @samp{M-c} would
|
|
change the case of the character under point. Typing @samp{M-1 0 M-c}
|
|
would change the case of the following 10 characters, leaving the cursor on
|
|
the last character changed.
|
|
|
|
@example
|
|
/* Invert the case of the COUNT following characters. */
|
|
int
|
|
invert_case_line (count, key)
|
|
int count, key;
|
|
@{
|
|
register int start, end, i;
|
|
|
|
start = rl_point;
|
|
|
|
if (rl_point >= rl_end)
|
|
return (0);
|
|
|
|
if (count < 0)
|
|
@{
|
|
direction = -1;
|
|
count = -count;
|
|
@}
|
|
else
|
|
direction = 1;
|
|
|
|
/* Find the end of the range to modify. */
|
|
end = start + (count * direction);
|
|
|
|
/* Force it to be within range. */
|
|
if (end > rl_end)
|
|
end = rl_end;
|
|
else if (end < 0)
|
|
end = 0;
|
|
|
|
if (start == end)
|
|
return (0);
|
|
|
|
if (start > end)
|
|
@{
|
|
int temp = start;
|
|
start = end;
|
|
end = temp;
|
|
@}
|
|
|
|
/* Tell readline that we are modifying the line, so it will save
|
|
the undo information. */
|
|
rl_modifying (start, end);
|
|
|
|
for (i = start; i != end; i++)
|
|
@{
|
|
if (uppercase_p (rl_line_buffer[i]))
|
|
rl_line_buffer[i] = to_lower (rl_line_buffer[i]);
|
|
else if (lowercase_p (rl_line_buffer[i]))
|
|
rl_line_buffer[i] = to_upper (rl_line_buffer[i]);
|
|
@}
|
|
/* Move point to on top of the last character changed. */
|
|
rl_point = (direction == 1) ? end - 1 : start;
|
|
return (0);
|
|
@}
|
|
@end example
|
|
|
|
@node Custom Completers
|
|
@section Custom Completers
|
|
|
|
Typically, a program that reads commands from the user has a way of
|
|
disambiguating commands and data. If your program is one of these, then
|
|
it can provide completion for commands, data, or both.
|
|
The following sections describe how your program and Readline
|
|
cooperate to provide this service.
|
|
|
|
@menu
|
|
* How Completing Works:: The logic used to do completion.
|
|
* Completion Functions:: Functions provided by Readline.
|
|
* Completion Variables:: Variables which control completion.
|
|
* A Short Completion Example:: An example of writing completer subroutines.
|
|
@end menu
|
|
|
|
@node How Completing Works
|
|
@subsection How Completing Works
|
|
|
|
In order to complete some text, the full list of possible completions
|
|
must be available. That is, it is not possible to accurately
|
|
expand a partial word without knowing all of the possible words
|
|
which make sense in that context. The Readline library provides
|
|
the user interface to completion, and two of the most common
|
|
completion functions: filename and username. For completing other types
|
|
of text, you must write your own completion function. This section
|
|
describes exactly what such functions must do, and provides an example.
|
|
|
|
There are three major functions used to perform completion:
|
|
|
|
@enumerate
|
|
@item
|
|
The user-interface function @code{rl_complete ()}. This function is
|
|
called with the same arguments as other Readline
|
|
functions intended for interactive use: @var{count} and
|
|
@var{invoking_key}. It isolates the word to be completed and calls
|
|
@code{completion_matches ()} to generate a list of possible completions.
|
|
It then either lists the possible completions, inserts the possible
|
|
completions, or actually performs the
|
|
completion, depending on which behavior is desired.
|
|
|
|
@item
|
|
The internal function @code{completion_matches ()} uses your
|
|
@dfn{generator} function to generate the list of possible matches, and
|
|
then returns the array of these matches. You should place the address
|
|
of your generator function in @code{rl_completion_entry_function}.
|
|
|
|
@item
|
|
The generator function is called repeatedly from
|
|
@code{completion_matches ()}, returning a string each time. The
|
|
arguments to the generator function are @var{text} and @var{state}.
|
|
@var{text} is the partial word to be completed. @var{state} is zero the
|
|
first time the function is called, allowing the generator to perform
|
|
any necessary initialization, and a positive non-zero integer for
|
|
each subsequent call. When the generator function returns
|
|
@code{(char *)NULL} this signals @code{completion_matches ()} that there are
|
|
no more possibilities left. Usually the generator function computes the
|
|
list of possible completions when @var{state} is zero, and returns them
|
|
one at a time on subsequent calls. Each string the generator function
|
|
returns as a match must be allocated with @code{malloc()}; Readline
|
|
frees the strings when it has finished with them.
|
|
|
|
@end enumerate
|
|
|
|
@deftypefun int rl_complete (int ignore, int invoking_key)
|
|
Complete the word at or before point. You have supplied the function
|
|
that does the initial simple matching selection algorithm (see
|
|
@code{completion_matches ()}). The default is to do filename completion.
|
|
@end deftypefun
|
|
|
|
@deftypevar {Function *} rl_completion_entry_function
|
|
This is a pointer to the generator function for @code{completion_matches
|
|
()}. If the value of @code{rl_completion_entry_function} is
|
|
@code{(Function *)NULL} then the default filename generator function,
|
|
@code{filename_completion_function ()}, is used.
|
|
@end deftypevar
|
|
|
|
@node Completion Functions
|
|
@subsection Completion Functions
|
|
|
|
Here is the complete list of callable completion functions present in
|
|
Readline.
|
|
|
|
@deftypefun int rl_complete_internal (int what_to_do)
|
|
Complete the word at or before point. @var{what_to_do} says what to do
|
|
with the completion. A value of @samp{?} means list the possible
|
|
completions. @samp{TAB} means do standard completion. @samp{*} means
|
|
insert all of the possible completions. @samp{!} means to display
|
|
all of the possible completions, if there is more than one, as well as
|
|
performing partial completion.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_complete (int ignore, int invoking_key)
|
|
Complete the word at or before point. You have supplied the function
|
|
that does the initial simple matching selection algorithm (see
|
|
@code{completion_matches ()} and @code{rl_completion_entry_function}).
|
|
The default is to do filename
|
|
completion. This calls @code{rl_complete_internal ()} with an
|
|
argument depending on @var{invoking_key}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_possible_completions (int count, int invoking_key))
|
|
List the possible completions. See description of @code{rl_complete
|
|
()}. This calls @code{rl_complete_internal ()} with an argument of
|
|
@samp{?}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int rl_insert_completions (int count, int invoking_key))
|
|
Insert the list of possible completions into the line, deleting the
|
|
partially-completed word. See description of @code{rl_complete ()}.
|
|
This calls @code{rl_complete_internal ()} with an argument of @samp{*}.
|
|
@end deftypefun
|
|
|
|
@deftypefun {char **} completion_matches (char *text, CPFunction *entry_func)
|
|
Returns an array of @code{(char *)} which is a list of completions for
|
|
@var{text}. If there are no completions, returns @code{(char **)NULL}.
|
|
The first entry in the returned array is the substitution for @var{text}.
|
|
The remaining entries are the possible completions. The array is
|
|
terminated with a @code{NULL} pointer.
|
|
|
|
@var{entry_func} is a function of two args, and returns a
|
|
@code{(char *)}. The first argument is @var{text}. The second is a
|
|
state argument; it is zero on the first call, and non-zero on subsequent
|
|
calls. @var{entry_func} returns a @code{NULL} pointer to the caller
|
|
when there are no more matches.
|
|
@end deftypefun
|
|
|
|
@deftypefun {char *} filename_completion_function (char *text, int state)
|
|
A generator function for filename completion in the general case. Note
|
|
that completion in Bash is a little different because of all
|
|
the pathnames that must be followed when looking up completions for a
|
|
command. The Bash source is a useful reference for writing custom
|
|
completion functions.
|
|
@end deftypefun
|
|
|
|
@deftypefun {char *} username_completion_function (char *text, int state)
|
|
A completion generator for usernames. @var{text} contains a partial
|
|
username preceded by a random character (usually @samp{~}). As with all
|
|
completion generators, @var{state} is zero on the first call and non-zero
|
|
for subsequent calls.
|
|
@end deftypefun
|
|
|
|
@node Completion Variables
|
|
@subsection Completion Variables
|
|
|
|
@deftypevar {Function *} rl_completion_entry_function
|
|
A pointer to the generator function for @code{completion_matches ()}.
|
|
@code{NULL} means to use @code{filename_entry_function ()}, the default
|
|
filename completer.
|
|
@end deftypevar
|
|
|
|
@deftypevar {CPPFunction *} rl_attempted_completion_function
|
|
A pointer to an alternative function to create matches.
|
|
The function is called with @var{text}, @var{start}, and @var{end}.
|
|
@var{start} and @var{end} are indices in @code{rl_line_buffer} saying
|
|
what the boundaries of @var{text} are. If this function exists and
|
|
returns @code{NULL}, or if this variable is set to @code{NULL}, then
|
|
@code{rl_complete ()} will call the value of
|
|
@code{rl_completion_entry_function} to generate matches, otherwise the
|
|
array of strings returned will be used.
|
|
@end deftypevar
|
|
|
|
@deftypevar {CPFunction *} rl_filename_quoting_function
|
|
A pointer to a function that will quote a filename in an application-
|
|
specific fashion. This is called if filename completion is being
|
|
attempted and one of the characters in @code{rl_filename_quote_characters}
|
|
appears in a completed filename. The function is called with
|
|
@var{text}, @var{match_type}, and @var{quote_pointer}. The @var{text}
|
|
is the filename to be quoted. The @var{match_type} is either
|
|
@code{SINGLE_MATCH}, if there is only one completion match, or
|
|
@code{MULT_MATCH}. Some functions use this to decide whether or not to
|
|
insert a closing quote character. The @var{quote_pointer} is a pointer
|
|
to any opening quote character the user typed. Some functions choose
|
|
to reset this character.
|
|
@end deftypevar
|
|
|
|
@deftypevar {CPFunction *} rl_filename_dequoting_function
|
|
A pointer to a function that will remove application-specific quoting
|
|
characters from a filename before completion is attempted, so those
|
|
characters do not interfere with matching the text against names in
|
|
the filesystem. It is called with @var{text}, the text of the word
|
|
to be dequoted, and @var{quote_char}, which is the quoting character
|
|
that delimits the filename (usually @samp{'} or @samp{"}). If
|
|
@var{quote_char} is zero, the filename was not in an embedded string.
|
|
@end deftypevar
|
|
|
|
@deftypevar {Function *} rl_char_is_quoted_p
|
|
A pointer to a function to call that determines whether or not a specific
|
|
character in the line buffer is quoted, according to whatever quoting
|
|
mechanism the program calling readline uses. The function is called with
|
|
two arguments: @var{text}, the text of the line, and @var{index}, the
|
|
index of the character in the line. It is used to decide whether a
|
|
character found in @code{rl_completer_word_break_characters} should be
|
|
used to break words for the completer.
|
|
@end deftypevar
|
|
|
|
@deftypevar int rl_completion_query_items
|
|
Up to this many items will be displayed in response to a
|
|
possible-completions call. After that, we ask the user if she is sure
|
|
she wants to see them all. The default value is 100.
|
|
@end deftypevar
|
|
|
|
@deftypevar {char *} rl_basic_word_break_characters
|
|
The basic list of characters that signal a break between words for the
|
|
completer routine. The default value of this variable is the characters
|
|
which break words for completion in Bash, i.e.,
|
|
@code{" \t\n\"\\'`@@$><=;|&@{("}.
|
|
@end deftypevar
|
|
|
|
@deftypevar {char *} rl_basic_quote_characters
|
|
List of quote characters which can cause a word break.
|
|
@end deftypevar
|
|
|
|
@deftypevar {char *} rl_completer_word_break_characters
|
|
The list of characters that signal a break between words for
|
|
@code{rl_complete_internal ()}. The default list is the value of
|
|
@code{rl_basic_word_break_characters}.
|
|
@end deftypevar
|
|
|
|
@deftypevar {char *} rl_completer_quote_characters
|
|
List of characters which can be used to quote a substring of the line.
|
|
Completion occurs on the entire substring, and within the substring
|
|
@code{rl_completer_word_break_characters} are treated as any other character,
|
|
unless they also appear within this list.
|
|
@end deftypevar
|
|
|
|
@deftypevar {char *} rl_filename_quote_characters
|
|
A list of characters that cause a filename to be quoted by the completer
|
|
when they appear in a completed filename. The default is the null string.
|
|
@end deftypevar
|
|
|
|
@deftypevar {char *} rl_special_prefixes
|
|
The list of characters that are word break characters, but should be
|
|
left in @var{text} when it is passed to the completion function.
|
|
Programs can use this to help determine what kind of completing to do.
|
|
For instance, Bash sets this variable to "$@@" so that it can complete
|
|
shell variables and hostnames.
|
|
@end deftypevar
|
|
|
|
@deftypevar {int} rl_completion_append_character
|
|
When a single completion alternative matches at the end of the command
|
|
line, this character is appended to the inserted completion text. The
|
|
default is a space character (@samp{ }). Setting this to the null
|
|
character (@samp{\0}) prevents anything being appended automatically.
|
|
This can be changed in custom completion functions to
|
|
provide the ``most sensible word separator character'' according to
|
|
an application-specific command line syntax specification.
|
|
@end deftypevar
|
|
|
|
@deftypevar int rl_ignore_completion_duplicates
|
|
If non-zero, then disallow duplicates in the matches. Default is 1.
|
|
@end deftypevar
|
|
|
|
@deftypevar int rl_filename_completion_desired
|
|
Non-zero means that the results of the matches are to be treated as
|
|
filenames. This is @emph{always} zero on entry, and can only be changed
|
|
within a completion entry generator function. If it is set to a non-zero
|
|
value, directory names have a slash appended and Readline attempts to
|
|
quote completed filenames if they contain any embedded word break
|
|
characters.
|
|
@end deftypevar
|
|
|
|
@deftypevar int rl_filename_quoting_desired
|
|
Non-zero means that the results of the matches are to be quoted using
|
|
double quotes (or an application-specific quoting mechanism) if the
|
|
completed filename contains any characters in
|
|
@code{rl_filename_quote_chars}. This is @emph{always} non-zero
|
|
on entry, and can only be changed within a completion entry generator
|
|
function. The quoting is effected via a call to the function pointed to
|
|
by @code{rl_filename_quoting_function}.
|
|
@end deftypevar
|
|
|
|
@deftypevar int rl_inhibit_completion
|
|
If this variable is non-zero, completion is inhibit<ed. The completion
|
|
character will be inserted as any other bound to @code{self-insert}.
|
|
@end deftypevar
|
|
|
|
@deftypevar {Function *} rl_ignore_some_completions_function
|
|
This function, if defined, is called by the completer when real filename
|
|
completion is done, after all the matching names have been generated.
|
|
It is passed a @code{NULL} terminated array of matches.
|
|
The first element (@code{matches[0]}) is the
|
|
maximal substring common to all matches. This function can
|
|
re-arrange the list of matches as required, but each element deleted
|
|
from the array must be freed.
|
|
@end deftypevar
|
|
|
|
@deftypevar {Function *} rl_directory_completion_hook
|
|
This function, if defined, is allowed to modify the directory portion
|
|
of filenames Readline completes. It is called with the address of a
|
|
string (the current directory name) as an argument. It could be used
|
|
to expand symbolic links or shell variables in pathnames.
|
|
@end deftypevar
|
|
|
|
@node A Short Completion Example
|
|
@subsection A Short Completion Example
|
|
|
|
Here is a small application demonstrating the use of the GNU Readline
|
|
library. It is called @code{fileman}, and the source code resides in
|
|
@file{examples/fileman.c}. This sample application provides
|
|
completion of command names, line editing features, and access to the
|
|
history list.
|
|
|
|
@page
|
|
@smallexample
|
|
/* fileman.c -- A tiny application which demonstrates how to use the
|
|
GNU Readline library. This application interactively allows users
|
|
to manipulate files and their modes. */
|
|
|
|
#include <stdio.h>
|
|
#include <sys/types.h>
|
|
#include <sys/file.h>
|
|
#include <sys/stat.h>
|
|
#include <sys/errno.h>
|
|
|
|
#include <readline/readline.h>
|
|
#include <readline/history.h>
|
|
|
|
extern char *getwd ();
|
|
extern char *xmalloc ();
|
|
|
|
/* The names of functions that actually do the manipulation. */
|
|
int com_list (), com_view (), com_rename (), com_stat (), com_pwd ();
|
|
int com_delete (), com_help (), com_cd (), com_quit ();
|
|
|
|
/* A structure which contains information on the commands this program
|
|
can understand. */
|
|
|
|
typedef struct @{
|
|
char *name; /* User printable name of the function. */
|
|
Function *func; /* Function to call to do the job. */
|
|
char *doc; /* Documentation for this function. */
|
|
@} COMMAND;
|
|
|
|
COMMAND commands[] = @{
|
|
@{ "cd", com_cd, "Change to directory DIR" @},
|
|
@{ "delete", com_delete, "Delete FILE" @},
|
|
@{ "help", com_help, "Display this text" @},
|
|
@{ "?", com_help, "Synonym for `help'" @},
|
|
@{ "list", com_list, "List files in DIR" @},
|
|
@{ "ls", com_list, "Synonym for `list'" @},
|
|
@{ "pwd", com_pwd, "Print the current working directory" @},
|
|
@{ "quit", com_quit, "Quit using Fileman" @},
|
|
@{ "rename", com_rename, "Rename FILE to NEWNAME" @},
|
|
@{ "stat", com_stat, "Print out statistics on FILE" @},
|
|
@{ "view", com_view, "View the contents of FILE" @},
|
|
@{ (char *)NULL, (Function *)NULL, (char *)NULL @}
|
|
@};
|
|
|
|
/* Forward declarations. */
|
|
char *stripwhite ();
|
|
COMMAND *find_command ();
|
|
|
|
/* The name of this program, as taken from argv[0]. */
|
|
char *progname;
|
|
|
|
/* When non-zero, this global means the user is done using this program. */
|
|
int done;
|
|
|
|
char *
|
|
dupstr (s)
|
|
int s;
|
|
@{
|
|
char *r;
|
|
|
|
r = xmalloc (strlen (s) + 1);
|
|
strcpy (r, s);
|
|
return (r);
|
|
@}
|
|
|
|
main (argc, argv)
|
|
int argc;
|
|
char **argv;
|
|
@{
|
|
char *line, *s;
|
|
|
|
progname = argv[0];
|
|
|
|
initialize_readline (); /* Bind our completer. */
|
|
|
|
/* Loop reading and executing lines until the user quits. */
|
|
for ( ; done == 0; )
|
|
@{
|
|
line = readline ("FileMan: ");
|
|
|
|
if (!line)
|
|
break;
|
|
|
|
/* Remove leading and trailing whitespace from the line.
|
|
Then, if there is anything left, add it to the history list
|
|
and execute it. */
|
|
s = stripwhite (line);
|
|
|
|
if (*s)
|
|
@{
|
|
add_history (s);
|
|
execute_line (s);
|
|
@}
|
|
|
|
free (line);
|
|
@}
|
|
exit (0);
|
|
@}
|
|
|
|
/* Execute a command line. */
|
|
int
|
|
execute_line (line)
|
|
char *line;
|
|
@{
|
|
register int i;
|
|
COMMAND *command;
|
|
char *word;
|
|
|
|
/* Isolate the command word. */
|
|
i = 0;
|
|
while (line[i] && whitespace (line[i]))
|
|
i++;
|
|
word = line + i;
|
|
|
|
while (line[i] && !whitespace (line[i]))
|
|
i++;
|
|
|
|
if (line[i])
|
|
line[i++] = '\0';
|
|
|
|
command = find_command (word);
|
|
|
|
if (!command)
|
|
@{
|
|
fprintf (stderr, "%s: No such command for FileMan.\n", word);
|
|
return (-1);
|
|
@}
|
|
|
|
/* Get argument to command, if any. */
|
|
while (whitespace (line[i]))
|
|
i++;
|
|
|
|
word = line + i;
|
|
|
|
/* Call the function. */
|
|
return ((*(command->func)) (word));
|
|
@}
|
|
|
|
/* Look up NAME as the name of a command, and return a pointer to that
|
|
command. Return a NULL pointer if NAME isn't a command name. */
|
|
COMMAND *
|
|
find_command (name)
|
|
char *name;
|
|
@{
|
|
register int i;
|
|
|
|
for (i = 0; commands[i].name; i++)
|
|
if (strcmp (name, commands[i].name) == 0)
|
|
return (&commands[i]);
|
|
|
|
return ((COMMAND *)NULL);
|
|
@}
|
|
|
|
/* Strip whitespace from the start and end of STRING. Return a pointer
|
|
into STRING. */
|
|
char *
|
|
stripwhite (string)
|
|
char *string;
|
|
@{
|
|
register char *s, *t;
|
|
|
|
for (s = string; whitespace (*s); s++)
|
|
;
|
|
|
|
if (*s == 0)
|
|
return (s);
|
|
|
|
t = s + strlen (s) - 1;
|
|
while (t > s && whitespace (*t))
|
|
t--;
|
|
*++t = '\0';
|
|
|
|
return s;
|
|
@}
|
|
|
|
/* **************************************************************** */
|
|
/* */
|
|
/* Interface to Readline Completion */
|
|
/* */
|
|
/* **************************************************************** */
|
|
|
|
char *command_generator ();
|
|
char **fileman_completion ();
|
|
|
|
/* Tell the GNU Readline library how to complete. We want to try to complete
|
|
on command names if this is the first word in the line, or on filenames
|
|
if not. */
|
|
initialize_readline ()
|
|
@{
|
|
/* Allow conditional parsing of the ~/.inputrc file. */
|
|
rl_readline_name = "FileMan";
|
|
|
|
/* Tell the completer that we want a crack first. */
|
|
rl_attempted_completion_function = (CPPFunction *)fileman_completion;
|
|
@}
|
|
|
|
/* Attempt to complete on the contents of TEXT. START and END bound the
|
|
region of rl_line_buffer that contains the word to complete. TEXT is
|
|
the word to complete. We can use the entire contents of rl_line_buffer
|
|
in case we want to do some simple parsing. Return the array of matches,
|
|
or NULL if there aren't any. */
|
|
char **
|
|
fileman_completion (text, start, end)
|
|
char *text;
|
|
int start, end;
|
|
@{
|
|
char **matches;
|
|
|
|
matches = (char **)NULL;
|
|
|
|
/* If this word is at the start of the line, then it is a command
|
|
to complete. Otherwise it is the name of a file in the current
|
|
directory. */
|
|
if (start == 0)
|
|
matches = completion_matches (text, command_generator);
|
|
|
|
return (matches);
|
|
@}
|
|
|
|
/* Generator function for command completion. STATE lets us know whether
|
|
to start from scratch; without any state (i.e. STATE == 0), then we
|
|
start at the top of the list. */
|
|
char *
|
|
command_generator (text, state)
|
|
char *text;
|
|
int state;
|
|
@{
|
|
static int list_index, len;
|
|
char *name;
|
|
|
|
/* If this is a new word to complete, initialize now. This includes
|
|
saving the length of TEXT for efficiency, and initializing the index
|
|
variable to 0. */
|
|
if (!state)
|
|
@{
|
|
list_index = 0;
|
|
len = strlen (text);
|
|
@}
|
|
|
|
/* Return the next name which partially matches from the command list. */
|
|
while (name = commands[list_index].name)
|
|
@{
|
|
list_index++;
|
|
|
|
if (strncmp (name, text, len) == 0)
|
|
return (dupstr(name));
|
|
@}
|
|
|
|
/* If no names matched, then return NULL. */
|
|
return ((char *)NULL);
|
|
@}
|
|
|
|
/* **************************************************************** */
|
|
/* */
|
|
/* FileMan Commands */
|
|
/* */
|
|
/* **************************************************************** */
|
|
|
|
/* String to pass to system (). This is for the LIST, VIEW and RENAME
|
|
commands. */
|
|
static char syscom[1024];
|
|
|
|
/* List the file(s) named in arg. */
|
|
com_list (arg)
|
|
char *arg;
|
|
@{
|
|
if (!arg)
|
|
arg = "";
|
|
|
|
sprintf (syscom, "ls -FClg %s", arg);
|
|
return (system (syscom));
|
|
@}
|
|
|
|
com_view (arg)
|
|
char *arg;
|
|
@{
|
|
if (!valid_argument ("view", arg))
|
|
return 1;
|
|
|
|
sprintf (syscom, "more %s", arg);
|
|
return (system (syscom));
|
|
@}
|
|
|
|
com_rename (arg)
|
|
char *arg;
|
|
@{
|
|
too_dangerous ("rename");
|
|
return (1);
|
|
@}
|
|
|
|
com_stat (arg)
|
|
char *arg;
|
|
@{
|
|
struct stat finfo;
|
|
|
|
if (!valid_argument ("stat", arg))
|
|
return (1);
|
|
|
|
if (stat (arg, &finfo) == -1)
|
|
@{
|
|
perror (arg);
|
|
return (1);
|
|
@}
|
|
|
|
printf ("Statistics for `%s':\n", arg);
|
|
|
|
printf ("%s has %d link%s, and is %d byte%s in length.\n", arg,
|
|
finfo.st_nlink,
|
|
(finfo.st_nlink == 1) ? "" : "s",
|
|
finfo.st_size,
|
|
(finfo.st_size == 1) ? "" : "s");
|
|
printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
|
|
printf (" Last access at: %s", ctime (&finfo.st_atime));
|
|
printf (" Last modified at: %s", ctime (&finfo.st_mtime));
|
|
return (0);
|
|
@}
|
|
|
|
com_delete (arg)
|
|
char *arg;
|
|
@{
|
|
too_dangerous ("delete");
|
|
return (1);
|
|
@}
|
|
|
|
/* Print out help for ARG, or for all of the commands if ARG is
|
|
not present. */
|
|
com_help (arg)
|
|
char *arg;
|
|
@{
|
|
register int i;
|
|
int printed = 0;
|
|
|
|
for (i = 0; commands[i].name; i++)
|
|
@{
|
|
if (!*arg || (strcmp (arg, commands[i].name) == 0))
|
|
@{
|
|
printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
|
|
printed++;
|
|
@}
|
|
@}
|
|
|
|
if (!printed)
|
|
@{
|
|
printf ("No commands match `%s'. Possibilties are:\n", arg);
|
|
|
|
for (i = 0; commands[i].name; i++)
|
|
@{
|
|
/* Print in six columns. */
|
|
if (printed == 6)
|
|
@{
|
|
printed = 0;
|
|
printf ("\n");
|
|
@}
|
|
|
|
printf ("%s\t", commands[i].name);
|
|
printed++;
|
|
@}
|
|
|
|
if (printed)
|
|
printf ("\n");
|
|
@}
|
|
return (0);
|
|
@}
|
|
|
|
/* Change to the directory ARG. */
|
|
com_cd (arg)
|
|
char *arg;
|
|
@{
|
|
if (chdir (arg) == -1)
|
|
@{
|
|
perror (arg);
|
|
return 1;
|
|
@}
|
|
|
|
com_pwd ("");
|
|
return (0);
|
|
@}
|
|
|
|
/* Print out the current working directory. */
|
|
com_pwd (ignore)
|
|
char *ignore;
|
|
@{
|
|
char dir[1024], *s;
|
|
|
|
s = getwd (dir);
|
|
if (s == 0)
|
|
@{
|
|
printf ("Error getting pwd: %s\n", dir);
|
|
return 1;
|
|
@}
|
|
|
|
printf ("Current directory is %s\n", dir);
|
|
return 0;
|
|
@}
|
|
|
|
/* The user wishes to quit using this program. Just set DONE non-zero. */
|
|
com_quit (arg)
|
|
char *arg;
|
|
@{
|
|
done = 1;
|
|
return (0);
|
|
@}
|
|
|
|
/* Function which tells you that you can't do this. */
|
|
too_dangerous (caller)
|
|
char *caller;
|
|
@{
|
|
fprintf (stderr,
|
|
"%s: Too dangerous for me to distribute. Write it yourself.\n",
|
|
caller);
|
|
@}
|
|
|
|
/* Return non-zero if ARG is a valid argument for CALLER, else print
|
|
an error message and return zero. */
|
|
int
|
|
valid_argument (caller, arg)
|
|
char *caller, *arg;
|
|
@{
|
|
if (!arg || !*arg)
|
|
@{
|
|
fprintf (stderr, "%s: Argument required.\n", caller);
|
|
return (0);
|
|
@}
|
|
|
|
return (1);
|
|
@}
|
|
@end smallexample
|