diff options
Diffstat (limited to 'lib/readline/doc/rltech.texi')
| -rw-r--r-- | lib/readline/doc/rltech.texi | 178 |
1 files changed, 134 insertions, 44 deletions
diff --git a/lib/readline/doc/rltech.texi b/lib/readline/doc/rltech.texi index ecff106..c98d3b9 100644 --- a/lib/readline/doc/rltech.texi +++ b/lib/readline/doc/rltech.texi @@ -1,14 +1,13 @@ @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 consistency of user interface across discrete programs that need to provide a command line interface. -Copyright (C) 1988-2006 Free Software Foundation, Inc. +Copyright (C) 1988-2007 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -351,6 +350,12 @@ The @code{rl_set_prompt()} function (@pxref{Redisplay}) may be used to modify the prompt string after calling @code{readline()}. @end deftypevar +@deftypevar {char *} rl_display_prompt +The string displayed as the prompt. This is usually identical to +@var{rl_prompt}, but may be changed temporarily by functions that +use the prompt string as a message area, such as incremental search. +@end deftypevar + @deftypevar int rl_already_prompted If an application wishes to display the prompt itself, rather than have Readline do it the first time @code{readline()} is called, it should set @@ -518,6 +523,20 @@ Readline is performing word completion. Readline is currently executing the readline signal handler. @item RL_STATE_UNDOING Readline is performing an undo. +@item RL_STATE_INPUTPENDING +Readline has input pending due to a call to @code{rl_execute_next()}. +@item RL_STATE_TTYCSAVED +Readline has saved the values of the terminal's special characters. +@item RL_STATE_CALLBACK +Readline is currently using the alternate (callback) interface +(@pxref{Alternate Interface}). +@item RL_STATE_VIMOTION +Readline is reading the argument to a vi-mode "motion" command. +@item RL_STATE_MULTIKEY +Readline is reading a multiple-keystroke command. +@item RL_STATE_VICMDONCE +Readline has entered vi command (movement) mode at least one time during +the current call to @code{readline()}. @item RL_STATE_DONE Readline has read a key sequence bound to @code{accept-line} and is about to return the line to the caller. @@ -793,7 +812,8 @@ Print the names of all bindable Readline functions to @code{rl_outstream}. @deftypefun {const char **} rl_funmap_names (void) Return a NULL terminated array of known function names. The array is sorted. The array itself is allocated, but not the strings inside. You -should @code{free()} the array when you are done, but not the pointers. +should free the array, but not the pointers, using @code{free} or +@code{rl_free} when you are done. @end deftypefun @deftypefun int rl_add_funmap_entry (const char *name, rl_command_func_t *function) @@ -1077,6 +1097,26 @@ environment variable is used. @node Utility Functions @subsection Utility Functions +@deftypefun int rl_save_state (struct readline_state *sp) +Save a snapshot of Readline's internal state to @var{sp}. +The contents of the @var{readline_state} structure are documented +in @file{readline.h}. +The caller is responsible for allocating the structure. +@end deftypefun + +@deftypefun int rl_restore_state (struct readline_state *sp) +Restore Readline's internal state to that stored in @var{sp}, which must +have been saved by a call to @code{rl_save_state}. +The contents of the @var{readline_state} structure are documented +in @file{readline.h}. +The caller is responsible for freeing the structure. +@end deftypefun + +@deftypefun void rl_free (void *mem) +Deallocate the memory pointed to by @var{mem}. @var{mem} must have been +allocated by @code{malloc}. +@end deftypefun + @deftypefun void rl_replace_line (const char *text, int clear_undo) Replace the contents of @code{rl_line_buffer} with @var{text}. The point and mark are preserved, if possible. @@ -1084,7 +1124,7 @@ If @var{clear_undo} is non-zero, the undo list associated with the current line is cleared. @end deftypefun -@deftypefun int rl_extend_line_buffer (int len) +@deftypefun void 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 @@ -1394,6 +1434,13 @@ call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force Readline to update its idea of the terminal size when a @code{SIGWINCH} is received. +@deftypefun void rl_echo_signal_char (int sig) +If an application wishes to install its own signal handlers, but still +have readline display characters that generate signals, calling this +function with @var{sig} set to @code{SIGINT}, @code{SIGQUIT}, or +@code{SIGTSTP} will display the character generating that signal. +@end deftypefun + @deftypefun void rl_resize_terminal (void) Update Readline's internal screen size by reading values from the kernel. @end deftypefun @@ -1827,6 +1874,15 @@ if the application's completion function returns no matches. It should be set only by an application's completion function. @end deftypevar +@deftypevar int rl_sort_completion_matches +If an application sets this variable to 0, Readline will not sort the +list of completions (which implies that it cannot remove any duplicate +completions). The default value is 1, which means that Readline will +sort the completions and, depending on the value of +@code{rl_ignore_completion_duplicates}, will attempt to remove duplicate +matches. +@end deftypevar + @deftypevar int rl_completion_type Set to a character describing the type of completion Readline is currently attempting; see the description of @code{rl_complete_internal()} @@ -1836,6 +1892,13 @@ completion function is called, allowing such functions to present the same interface as @code{rl_complete()}. @end deftypevar +@deftypevar int rl_completion_invoking_key +Set to the final character in the key sequence that invoked one of the +completion functions that call @code{rl_complete_internal()}. This is +set to the appropriate value before any application-specific completion +function is called. +@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}. @@ -1856,27 +1919,51 @@ history list. GNU Readline library. This application interactively allows users to manipulate files and their modes. */ -#include <stdio.h> +#ifdef HAVE_CONFIG_H +# include <config.h> +#endif + #include <sys/types.h> -#include <sys/file.h> +#ifdef HAVE_SYS_FILE_H +# include <sys/file.h> +#endif #include <sys/stat.h> -#include <sys/errno.h> + +#ifdef HAVE_UNISTD_H +# include <unistd.h> +#endif + +#include <fcntl.h> +#include <stdio.h> +#include <errno.h> + +#if defined (HAVE_STRING_H) +# include <string.h> +#else /* !HAVE_STRING_H */ +# include <strings.h> +#endif /* !HAVE_STRING_H */ + +#ifdef HAVE_STDLIB_H +# include <stdlib.h> +#endif + +#include <time.h> #include <readline/readline.h> #include <readline/history.h> -extern char *xmalloc (); +extern char *xmalloc PARAMS((size_t)); /* The names of functions that actually do the manipulation. */ -int com_list __P((char *)); -int com_view __P((char *)); -int com_rename __P((char *)); -int com_stat __P((char *)); -int com_pwd __P((char *)); -int com_delete __P((char *)); -int com_help __P((char *)); -int com_cd __P((char *)); -int com_quit __P((char *)); +int com_list PARAMS((char *)); +int com_view PARAMS((char *)); +int com_rename PARAMS((char *)); +int com_stat PARAMS((char *)); +int com_pwd PARAMS((char *)); +int com_delete PARAMS((char *)); +int com_help PARAMS((char *)); +int com_cd PARAMS((char *)); +int com_quit PARAMS((char *)); /* A structure which contains information on the commands this program can understand. */ @@ -1909,12 +1996,12 @@ COMMAND *find_command (); /* The name of this program, as taken from argv[0]. */ char *progname; -/* When non-zero, this means the user is done using this program. */ +/* When non-zero, this global means the user is done using this program. */ int done; char * dupstr (s) - int s; + char *s; @{ char *r; @@ -2039,12 +2126,12 @@ stripwhite (string) /* */ /* **************************************************************** */ -char *command_generator __P((const char *, int)); -char **fileman_completion __P((const char *, int, int)); +char *command_generator PARAMS((const char *, int)); +char **fileman_completion PARAMS((const char *, int, int)); -/* 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. */ +/* 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. */ @@ -2054,11 +2141,11 @@ initialize_readline () rl_attempted_completion_function = 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. Returnthe 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) const char *text; @@ -2077,9 +2164,9 @@ fileman_completion (text, start, end) 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. */ +/* 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) const char *text; @@ -2088,17 +2175,16 @@ command_generator (text, 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 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. */ + /* Return the next name which partially matches from the command list. */ while (name = commands[list_index].name) @{ list_index++; @@ -2138,7 +2224,12 @@ com_view (arg) if (!valid_argument ("view", arg)) return 1; +#if defined (__MSDOS__) + /* more.com doesn't grok slashes in pathnames */ + sprintf (syscom, "less %s", arg); +#else sprintf (syscom, "more %s", arg); +#endif return (system (syscom)); @} @@ -2165,7 +2256,8 @@ com_stat (arg) printf ("Statistics for `%s':\n", arg); - printf ("%s has %d link%s, and is %d byte%s in length.\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, @@ -2254,8 +2346,7 @@ com_pwd (ignore) return 0; @} -/* The user wishes to quit using this program. Just set DONE - non-zero. */ +/* The user wishes to quit using this program. Just set DONE non-zero. */ com_quit (arg) char *arg; @{ @@ -2268,13 +2359,12 @@ too_dangerous (caller) char *caller; @{ fprintf (stderr, - "%s: Too dangerous for me to distribute.\n", + "%s: Too dangerous for me to distribute. Write it yourself.\n", caller); - fprintf (stderr, "Write it yourself.\n"); @} -/* Return non-zero if ARG is a valid argument for CALLER, - else print an error message and return zero. */ +/* 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; |