in the consitency of user interface across discrete programs that need
to provide a command line interface.
-Copyright (C) 1988, 1994 Free Software Foundation, Inc.
+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
@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
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 {Function *} 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
* 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
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
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
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
@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
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 empty.
+@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.
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
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_completer_word_break_chars}. This is @emph{always} non-zero
+@code{rl_filename_quote_chars}. This is @emph{always} non-zero
on entry, and can only be changed within a completion entry generator
-function.
+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 inhibited. The completion
+character will be inserted as any other bound to @code{self-insert}.
@end deftypevar
@deftypevar {Function *} rl_ignore_some_completions_function
rl_attempted_completion_function = (CPPFunction *)fileman_completion;
@}
-/* Attempt to complete on the contents of TEXT. START and END show the
- region of TEXT that contains the word to complete. We can use the
- entire line in case we want to do some simple parsing. Return the
- array of matches, or NULL if there aren't any. */
+/* 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;
projects / platform / upstream / bash.git / blobdiff