Annotation of embedaddon/readline/doc/rltech.texi, revision 1.1
1.1 ! misho 1: @comment %**start of header (This is for running Texinfo on a region.)
! 2: @setfilename rltech.info
! 3: @comment %**end of header (This is for running Texinfo on a region.)
! 4:
! 5: @ifinfo
! 6: This document describes the GNU Readline Library, a utility for aiding
! 7: in the consistency of user interface across discrete programs that need
! 8: to provide a command line interface.
! 9:
! 10: Copyright (C) 1988--2014 Free Software Foundation, Inc.
! 11:
! 12: Permission is granted to make and distribute verbatim copies of
! 13: this manual provided the copyright notice and this permission notice
! 14: pare preserved on all copies.
! 15:
! 16: @ignore
! 17: Permission is granted to process this file through TeX and print the
! 18: results, provided the printed document carries copying permission
! 19: notice identical to this one except for the removal of this paragraph
! 20: (this paragraph not being relevant to the printed manual).
! 21: @end ignore
! 22:
! 23: Permission is granted to copy and distribute modified versions of this
! 24: manual under the conditions for verbatim copying, provided that the entire
! 25: resulting derived work is distributed under the terms of a permission
! 26: notice identical to this one.
! 27:
! 28: Permission is granted to copy and distribute translations of this manual
! 29: into another language, under the above conditions for modified versions,
! 30: except that this permission notice may be stated in a translation approved
! 31: by the Foundation.
! 32: @end ifinfo
! 33:
! 34: @node Programming with GNU Readline
! 35: @chapter Programming with GNU Readline
! 36:
! 37: This chapter describes the interface between the @sc{gnu} Readline Library and
! 38: other programs. If you are a programmer, and you wish to include the
! 39: features found in @sc{gnu} Readline
! 40: such as completion, line editing, and interactive history manipulation
! 41: in your own programs, this section is for you.
! 42:
! 43: @menu
! 44: * Basic Behavior:: Using the default behavior of Readline.
! 45: * Custom Functions:: Adding your own functions to Readline.
! 46: * Readline Variables:: Variables accessible to custom
! 47: functions.
! 48: * Readline Convenience Functions:: Functions which Readline supplies to
! 49: aid in writing your own custom
! 50: functions.
! 51: * Readline Signal Handling:: How Readline behaves when it receives signals.
! 52: * Custom Completers:: Supplanting or supplementing Readline's
! 53: completion functions.
! 54: @end menu
! 55:
! 56: @node Basic Behavior
! 57: @section Basic Behavior
! 58:
! 59: Many programs provide a command line interface, such as @code{mail},
! 60: @code{ftp}, and @code{sh}. For such programs, the default behaviour of
! 61: Readline is sufficient. This section describes how to use Readline in
! 62: the simplest way possible, perhaps to replace calls in your code to
! 63: @code{gets()} or @code{fgets()}.
! 64:
! 65: @findex readline
! 66: @cindex readline, function
! 67:
! 68: The function @code{readline()} prints a prompt @var{prompt}
! 69: and then reads and returns a single line of text from the user.
! 70: If @var{prompt} is @code{NULL} or the empty string, no prompt is displayed.
! 71: The line @code{readline} returns is allocated with @code{malloc()};
! 72: the caller should @code{free()} the line when it has finished with it.
! 73: The declaration for @code{readline} in ANSI C is
! 74:
! 75: @example
! 76: @code{char *readline (const char *@var{prompt});}
! 77: @end example
! 78:
! 79: @noindent
! 80: So, one might say
! 81: @example
! 82: @code{char *line = readline ("Enter a line: ");}
! 83: @end example
! 84: @noindent
! 85: in order to read a line of text from the user.
! 86: The line returned has the final newline removed, so only the
! 87: text remains.
! 88:
! 89: If @code{readline} encounters an @code{EOF} while reading the line, and the
! 90: line is empty at that point, then @code{(char *)NULL} is returned.
! 91: Otherwise, the line is ended just as if a newline had been typed.
! 92:
! 93: If you want the user to be able to get at the line later, (with
! 94: @key{C-p} for example), you must call @code{add_history()} to save the
! 95: line away in a @dfn{history} list of such lines.
! 96:
! 97: @example
! 98: @code{add_history (line)};
! 99: @end example
! 100:
! 101: @noindent
! 102: For full details on the GNU History Library, see the associated manual.
! 103:
! 104: It is preferable to avoid saving empty lines on the history list, since
! 105: users rarely have a burning need to reuse a blank line. Here is
! 106: a function which usefully replaces the standard @code{gets()} library
! 107: function, and has the advantage of no static buffer to overflow:
! 108:
! 109: @example
! 110: /* A static variable for holding the line. */
! 111: static char *line_read = (char *)NULL;
! 112:
! 113: /* Read a string, and return a pointer to it.
! 114: Returns NULL on EOF. */
! 115: char *
! 116: rl_gets ()
! 117: @{
! 118: /* If the buffer has already been allocated,
! 119: return the memory to the free pool. */
! 120: if (line_read)
! 121: @{
! 122: free (line_read);
! 123: line_read = (char *)NULL;
! 124: @}
! 125:
! 126: /* Get a line from the user. */
! 127: line_read = readline ("");
! 128:
! 129: /* If the line has any text in it,
! 130: save it on the history. */
! 131: if (line_read && *line_read)
! 132: add_history (line_read);
! 133:
! 134: return (line_read);
! 135: @}
! 136: @end example
! 137:
! 138: This function gives the user the default behaviour of @key{TAB}
! 139: completion: completion on file names. If you do not want Readline to
! 140: complete on filenames, you can change the binding of the @key{TAB} key
! 141: with @code{rl_bind_key()}.
! 142:
! 143: @example
! 144: @code{int rl_bind_key (int @var{key}, rl_command_func_t *@var{function});}
! 145: @end example
! 146:
! 147: @code{rl_bind_key()} takes two arguments: @var{key} is the character that
! 148: you want to bind, and @var{function} is the address of the function to
! 149: call when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert()}
! 150: makes @key{TAB} insert itself.
! 151: @code{rl_bind_key()} returns non-zero if @var{key} is not a valid
! 152: ASCII character code (between 0 and 255).
! 153:
! 154: Thus, to disable the default @key{TAB} behavior, the following suffices:
! 155: @example
! 156: @code{rl_bind_key ('\t', rl_insert);}
! 157: @end example
! 158:
! 159: This code should be executed once at the start of your program; you
! 160: might write a function called @code{initialize_readline()} which
! 161: performs this and other desired initializations, such as installing
! 162: custom completers (@pxref{Custom Completers}).
! 163:
! 164: @node Custom Functions
! 165: @section Custom Functions
! 166:
! 167: Readline provides many functions for manipulating the text of
! 168: the line, but it isn't possible to anticipate the needs of all
! 169: programs. This section describes the various functions and variables
! 170: defined within the Readline library which allow a user program to add
! 171: customized functionality to Readline.
! 172:
! 173: Before declaring any functions that customize Readline's behavior, or
! 174: using any functionality Readline provides in other code, an
! 175: application writer should include the file @code{<readline/readline.h>}
! 176: in any file that uses Readline's features. Since some of the definitions
! 177: in @code{readline.h} use the @code{stdio} library, the file
! 178: @code{<stdio.h>} should be included before @code{readline.h}.
! 179:
! 180: @code{readline.h} defines a C preprocessor variable that should
! 181: be treated as an integer, @code{RL_READLINE_VERSION}, which may
! 182: be used to conditionally compile application code depending on
! 183: the installed Readline version. The value is a hexadecimal
! 184: encoding of the major and minor version numbers of the library,
! 185: of the form 0x@var{MMmm}. @var{MM} is the two-digit major
! 186: version number; @var{mm} is the two-digit minor version number.
! 187: For Readline 4.2, for example, the value of
! 188: @code{RL_READLINE_VERSION} would be @code{0x0402}.
! 189:
! 190: @menu
! 191: * Readline Typedefs:: C declarations to make code readable.
! 192: * Function Writing:: Variables and calling conventions.
! 193: @end menu
! 194:
! 195: @node Readline Typedefs
! 196: @subsection Readline Typedefs
! 197:
! 198: For readability, we declare a number of new object types, all pointers
! 199: to functions.
! 200:
! 201: The reason for declaring these new types is to make it easier to write
! 202: code describing pointers to C functions with appropriately prototyped
! 203: arguments and return values.
! 204:
! 205: For instance, say we want to declare a variable @var{func} as a pointer
! 206: to a function which takes two @code{int} arguments and returns an
! 207: @code{int} (this is the type of all of the Readline bindable functions).
! 208: Instead of the classic C declaration
! 209:
! 210: @code{int (*func)();}
! 211:
! 212: @noindent
! 213: or the ANSI-C style declaration
! 214:
! 215: @code{int (*func)(int, int);}
! 216:
! 217: @noindent
! 218: we may write
! 219:
! 220: @code{rl_command_func_t *func;}
! 221:
! 222: The full list of function pointer types available is
! 223:
! 224: @table @code
! 225: @item typedef int rl_command_func_t (int, int);
! 226:
! 227: @item typedef char *rl_compentry_func_t (const char *, int);
! 228:
! 229: @item typedef char **rl_completion_func_t (const char *, int, int);
! 230:
! 231: @item typedef char *rl_quote_func_t (char *, int, char *);
! 232:
! 233: @item typedef char *rl_dequote_func_t (char *, int);
! 234:
! 235: @item typedef int rl_compignore_func_t (char **);
! 236:
! 237: @item typedef void rl_compdisp_func_t (char **, int, int);
! 238:
! 239: @item typedef int rl_hook_func_t (void);
! 240:
! 241: @item typedef int rl_getc_func_t (FILE *);
! 242:
! 243: @item typedef int rl_linebuf_func_t (char *, int);
! 244:
! 245: @item typedef int rl_intfunc_t (int);
! 246: @item #define rl_ivoidfunc_t rl_hook_func_t
! 247: @item typedef int rl_icpfunc_t (char *);
! 248: @item typedef int rl_icppfunc_t (char **);
! 249:
! 250: @item typedef void rl_voidfunc_t (void);
! 251: @item typedef void rl_vintfunc_t (int);
! 252: @item typedef void rl_vcpfunc_t (char *);
! 253: @item typedef void rl_vcppfunc_t (char **);
! 254:
! 255: @end table
! 256:
! 257: @node Function Writing
! 258: @subsection Writing a New Function
! 259:
! 260: In order to write new functions for Readline, you need to know the
! 261: calling conventions for keyboard-invoked functions, and the names of the
! 262: variables that describe the current state of the line read so far.
! 263:
! 264: The calling sequence for a command @code{foo} looks like
! 265:
! 266: @example
! 267: @code{int foo (int count, int key)}
! 268: @end example
! 269:
! 270: @noindent
! 271: where @var{count} is the numeric argument (or 1 if defaulted) and
! 272: @var{key} is the key that invoked this function.
! 273:
! 274: It is completely up to the function as to what should be done with the
! 275: numeric argument. Some functions use it as a repeat count, some
! 276: as a flag, and others to choose alternate behavior (refreshing the current
! 277: line as opposed to refreshing the screen, for example). Some choose to
! 278: ignore it. In general, if a
! 279: function uses the numeric argument as a repeat count, it should be able
! 280: to do something useful with both negative and positive arguments.
! 281: At the very least, it should be aware that it can be passed a
! 282: negative argument.
! 283:
! 284: A command function should return 0 if its action completes successfully,
! 285: and a non-zero value if some error occurs.
! 286: This is the convention obeyed by all of the builtin Readline bindable
! 287: command functions.
! 288:
! 289: @node Readline Variables
! 290: @section Readline Variables
! 291:
! 292: These variables are available to function writers.
! 293:
! 294: @deftypevar {char *} rl_line_buffer
! 295: This is the line gathered so far. You are welcome to modify the
! 296: contents of the line, but see @ref{Allowing Undoing}. The
! 297: function @code{rl_extend_line_buffer} is available to increase
! 298: the memory allocated to @code{rl_line_buffer}.
! 299: @end deftypevar
! 300:
! 301: @deftypevar int rl_point
! 302: The offset of the current cursor position in @code{rl_line_buffer}
! 303: (the @emph{point}).
! 304: @end deftypevar
! 305:
! 306: @deftypevar int rl_end
! 307: The number of characters present in @code{rl_line_buffer}. When
! 308: @code{rl_point} is at the end of the line, @code{rl_point} and
! 309: @code{rl_end} are equal.
! 310: @end deftypevar
! 311:
! 312: @deftypevar int rl_mark
! 313: The @var{mark} (saved position) in the current line. If set, the mark
! 314: and point define a @emph{region}.
! 315: @end deftypevar
! 316:
! 317: @deftypevar int rl_done
! 318: Setting this to a non-zero value causes Readline to return the current
! 319: line immediately.
! 320: @end deftypevar
! 321:
! 322: @deftypevar int rl_num_chars_to_read
! 323: Setting this to a positive value before calling @code{readline()} causes
! 324: Readline to return after accepting that many characters, rather
! 325: than reading up to a character bound to @code{accept-line}.
! 326: @end deftypevar
! 327:
! 328: @deftypevar int rl_pending_input
! 329: Setting this to a value makes it the next keystroke read. This is a
! 330: way to stuff a single character into the input stream.
! 331: @end deftypevar
! 332:
! 333: @deftypevar int rl_dispatching
! 334: Set to a non-zero value if a function is being called from a key binding;
! 335: zero otherwise. Application functions can test this to discover whether
! 336: they were called directly or by Readline's dispatching mechanism.
! 337: @end deftypevar
! 338:
! 339: @deftypevar int rl_erase_empty_line
! 340: Setting this to a non-zero value causes Readline to completely erase
! 341: the current line, including any prompt, any time a newline is typed as
! 342: the only character on an otherwise-empty line. The cursor is moved to
! 343: the beginning of the newly-blank line.
! 344: @end deftypevar
! 345:
! 346: @deftypevar {char *} rl_prompt
! 347: The prompt Readline uses. This is set from the argument to
! 348: @code{readline()}, and should not be assigned to directly.
! 349: The @code{rl_set_prompt()} function (@pxref{Redisplay}) may
! 350: be used to modify the prompt string after calling @code{readline()}.
! 351: @end deftypevar
! 352:
! 353: @deftypevar {char *} rl_display_prompt
! 354: The string displayed as the prompt. This is usually identical to
! 355: @var{rl_prompt}, but may be changed temporarily by functions that
! 356: use the prompt string as a message area, such as incremental search.
! 357: @end deftypevar
! 358:
! 359: @deftypevar int rl_already_prompted
! 360: If an application wishes to display the prompt itself, rather than have
! 361: Readline do it the first time @code{readline()} is called, it should set
! 362: this variable to a non-zero value after displaying the prompt.
! 363: The prompt must also be passed as the argument to @code{readline()} so
! 364: the redisplay functions can update the display properly.
! 365: The calling application is responsible for managing the value; Readline
! 366: never sets it.
! 367: @end deftypevar
! 368:
! 369: @deftypevar {const char *} rl_library_version
! 370: The version number of this revision of the library.
! 371: @end deftypevar
! 372:
! 373: @deftypevar int rl_readline_version
! 374: An integer encoding the current version of the library. The encoding is
! 375: of the form 0x@var{MMmm}, where @var{MM} is the two-digit major version
! 376: number, and @var{mm} is the two-digit minor version number.
! 377: For example, for Readline-4.2, @code{rl_readline_version} would have the
! 378: value 0x0402.
! 379: @end deftypevar
! 380:
! 381: @deftypevar {int} rl_gnu_readline_p
! 382: Always set to 1, denoting that this is @sc{gnu} readline rather than some
! 383: emulation.
! 384: @end deftypevar
! 385:
! 386: @deftypevar {const char *} rl_terminal_name
! 387: The terminal type, used for initialization. If not set by the application,
! 388: Readline sets this to the value of the @env{TERM} environment variable
! 389: the first time it is called.
! 390: @end deftypevar
! 391:
! 392: @deftypevar {const char *} rl_readline_name
! 393: This variable is set to a unique name by each application using Readline.
! 394: The value allows conditional parsing of the inputrc file
! 395: (@pxref{Conditional Init Constructs}).
! 396: @end deftypevar
! 397:
! 398: @deftypevar {FILE *} rl_instream
! 399: The stdio stream from which Readline reads input.
! 400: If @code{NULL}, Readline defaults to @var{stdin}.
! 401: @end deftypevar
! 402:
! 403: @deftypevar {FILE *} rl_outstream
! 404: The stdio stream to which Readline performs output.
! 405: If @code{NULL}, Readline defaults to @var{stdout}.
! 406: @end deftypevar
! 407:
! 408: @deftypevar int rl_prefer_env_winsize
! 409: If non-zero, Readline gives values found in the @env{LINES} and
! 410: @env{COLUMNS} environment variables greater precedence than values fetched
! 411: from the kernel when computing the screen dimensions.
! 412: @end deftypevar
! 413:
! 414: @deftypevar {rl_command_func_t *} rl_last_func
! 415: The address of the last command function Readline executed. May be used to
! 416: test whether or not a function is being executed twice in succession, for
! 417: example.
! 418: @end deftypevar
! 419:
! 420: @deftypevar {rl_hook_func_t *} rl_startup_hook
! 421: If non-zero, this is the address of a function to call just
! 422: before @code{readline} prints the first prompt.
! 423: @end deftypevar
! 424:
! 425: @deftypevar {rl_hook_func_t *} rl_pre_input_hook
! 426: If non-zero, this is the address of a function to call after
! 427: the first prompt has been printed and just before @code{readline}
! 428: starts reading input characters.
! 429: @end deftypevar
! 430:
! 431: @deftypevar {rl_hook_func_t *} rl_event_hook
! 432: If non-zero, this is the address of a function to call periodically
! 433: when Readline is waiting for terminal input.
! 434: By default, this will be called at most ten times a second if there
! 435: is no keyboard input.
! 436: @end deftypevar
! 437:
! 438: @deftypevar {rl_getc_func_t *} rl_getc_function
! 439: If non-zero, Readline will call indirectly through this pointer
! 440: to get a character from the input stream. By default, it is set to
! 441: @code{rl_getc}, the default Readline character input function
! 442: (@pxref{Character Input}).
! 443: In general, an application that sets @var{rl_getc_function} should consider
! 444: setting @var{rl_input_available_hook} as well.
! 445: @end deftypevar
! 446:
! 447: @deftypevar {rl_hook_func_t *} rl_signal_event_hook
! 448: If non-zero, this is the address of a function to call if a read system
! 449: call is interrupted when Readline is reading terminal input.
! 450: @end deftypevar
! 451:
! 452: @deftypevar {rl_hook_func_t *} rl_input_available_hook
! 453: If non-zero, Readline will use this function's return value when it needs
! 454: to determine whether or not there is available input on the current input
! 455: source.
! 456: The default hook checks @code{rl_instream}; if an application is using a
! 457: different input source, it should set the hook appropriately.
! 458: Readline queries for available input when implementing intra-key-sequence
! 459: timeouts during input and incremental searches.
! 460: This may use an application-specific timeout before returning a value;
! 461: Readline uses the value passed to @code{rl_set_keyboard_input_timeout()}
! 462: or the value of the user-settable @var{keyseq-timeout} variable.
! 463: This is designed for use by applications using Readline's callback interface
! 464: (@pxref{Alternate Interface}), which may not use the traditional
! 465: @code{read(2)} and file descriptor interface, or other applications using
! 466: a different input mechanism.
! 467: If an application uses an input mechanism or hook that can potentially exceed
! 468: the value of @var{keyseq-timeout}, it should increase the timeout or set
! 469: this hook appropriately even when not using the callback interface.
! 470: In general, an application that sets @var{rl_getc_function} should consider
! 471: setting @var{rl_input_available_hook} as well.
! 472: @end deftypevar
! 473:
! 474: @deftypevar {rl_voidfunc_t *} rl_redisplay_function
! 475: If non-zero, Readline will call indirectly through this pointer
! 476: to update the display with the current contents of the editing buffer.
! 477: By default, it is set to @code{rl_redisplay}, the default Readline
! 478: redisplay function (@pxref{Redisplay}).
! 479: @end deftypevar
! 480:
! 481: @deftypevar {rl_vintfunc_t *} rl_prep_term_function
! 482: If non-zero, Readline will call indirectly through this pointer
! 483: to initialize the terminal. The function takes a single argument, an
! 484: @code{int} flag that says whether or not to use eight-bit characters.
! 485: By default, this is set to @code{rl_prep_terminal}
! 486: (@pxref{Terminal Management}).
! 487: @end deftypevar
! 488:
! 489: @deftypevar {rl_voidfunc_t *} rl_deprep_term_function
! 490: If non-zero, Readline will call indirectly through this pointer
! 491: to reset the terminal. This function should undo the effects of
! 492: @code{rl_prep_term_function}.
! 493: By default, this is set to @code{rl_deprep_terminal}
! 494: (@pxref{Terminal Management}).
! 495: @end deftypevar
! 496:
! 497: @deftypevar {Keymap} rl_executing_keymap
! 498: This variable is set to the keymap (@pxref{Keymaps}) in which the
! 499: currently executing readline function was found.
! 500: @end deftypevar
! 501:
! 502: @deftypevar {Keymap} rl_binding_keymap
! 503: This variable is set to the keymap (@pxref{Keymaps}) in which the
! 504: last key binding occurred.
! 505: @end deftypevar
! 506:
! 507: @deftypevar {char *} rl_executing_macro
! 508: This variable is set to the text of any currently-executing macro.
! 509: @end deftypevar
! 510:
! 511: @deftypevar int rl_executing_key
! 512: The key that caused the dispatch to the currently-executing Readline function.
! 513: @end deftypevar
! 514:
! 515: @deftypevar {char *} rl_executing_keyseq
! 516: The full key sequence that caused the dispatch to the currently-executing
! 517: Readline function.
! 518: @end deftypevar
! 519:
! 520: @deftypevar int rl_key_sequence_length
! 521: The number of characters in @var{rl_executing_keyseq}.
! 522: @end deftypevar
! 523:
! 524: @deftypevar {int} rl_readline_state
! 525: A variable with bit values that encapsulate the current Readline state.
! 526: A bit is set with the @code{RL_SETSTATE} macro, and unset with the
! 527: @code{RL_UNSETSTATE} macro. Use the @code{RL_ISSTATE} macro to test
! 528: whether a particular state bit is set. Current state bits include:
! 529:
! 530: @table @code
! 531: @item RL_STATE_NONE
! 532: Readline has not yet been called, nor has it begun to initialize.
! 533: @item RL_STATE_INITIALIZING
! 534: Readline is initializing its internal data structures.
! 535: @item RL_STATE_INITIALIZED
! 536: Readline has completed its initialization.
! 537: @item RL_STATE_TERMPREPPED
! 538: Readline has modified the terminal modes to do its own input and redisplay.
! 539: @item RL_STATE_READCMD
! 540: Readline is reading a command from the keyboard.
! 541: @item RL_STATE_METANEXT
! 542: Readline is reading more input after reading the meta-prefix character.
! 543: @item RL_STATE_DISPATCHING
! 544: Readline is dispatching to a command.
! 545: @item RL_STATE_MOREINPUT
! 546: Readline is reading more input while executing an editing command.
! 547: @item RL_STATE_ISEARCH
! 548: Readline is performing an incremental history search.
! 549: @item RL_STATE_NSEARCH
! 550: Readline is performing a non-incremental history search.
! 551: @item RL_STATE_SEARCH
! 552: Readline is searching backward or forward through the history for a string.
! 553: @item RL_STATE_NUMERICARG
! 554: Readline is reading a numeric argument.
! 555: @item RL_STATE_MACROINPUT
! 556: Readline is currently getting its input from a previously-defined keyboard
! 557: macro.
! 558: @item RL_STATE_MACRODEF
! 559: Readline is currently reading characters defining a keyboard macro.
! 560: @item RL_STATE_OVERWRITE
! 561: Readline is in overwrite mode.
! 562: @item RL_STATE_COMPLETING
! 563: Readline is performing word completion.
! 564: @item RL_STATE_SIGHANDLER
! 565: Readline is currently executing the readline signal handler.
! 566: @item RL_STATE_UNDOING
! 567: Readline is performing an undo.
! 568: @item RL_STATE_INPUTPENDING
! 569: Readline has input pending due to a call to @code{rl_execute_next()}.
! 570: @item RL_STATE_TTYCSAVED
! 571: Readline has saved the values of the terminal's special characters.
! 572: @item RL_STATE_CALLBACK
! 573: Readline is currently using the alternate (callback) interface
! 574: (@pxref{Alternate Interface}).
! 575: @item RL_STATE_VIMOTION
! 576: Readline is reading the argument to a vi-mode "motion" command.
! 577: @item RL_STATE_MULTIKEY
! 578: Readline is reading a multiple-keystroke command.
! 579: @item RL_STATE_VICMDONCE
! 580: Readline has entered vi command (movement) mode at least one time during
! 581: the current call to @code{readline()}.
! 582: @item RL_STATE_DONE
! 583: Readline has read a key sequence bound to @code{accept-line}
! 584: and is about to return the line to the caller.
! 585: @end table
! 586:
! 587: @end deftypevar
! 588:
! 589: @deftypevar {int} rl_explicit_arg
! 590: Set to a non-zero value if an explicit numeric argument was specified by
! 591: the user. Only valid in a bindable command function.
! 592: @end deftypevar
! 593:
! 594: @deftypevar {int} rl_numeric_arg
! 595: Set to the value of any numeric argument explicitly specified by the user
! 596: before executing the current Readline function. Only valid in a bindable
! 597: command function.
! 598: @end deftypevar
! 599:
! 600: @deftypevar {int} rl_editing_mode
! 601: Set to a value denoting Readline's current editing mode. A value of
! 602: @var{1} means Readline is currently in emacs mode; @var{0}
! 603: means that vi mode is active.
! 604: @end deftypevar
! 605:
! 606:
! 607: @node Readline Convenience Functions
! 608: @section Readline Convenience Functions
! 609:
! 610: @menu
! 611: * Function Naming:: How to give a function you write a name.
! 612: * Keymaps:: Making keymaps.
! 613: * Binding Keys:: Changing Keymaps.
! 614: * Associating Function Names and Bindings:: Translate function names to
! 615: key sequences.
! 616: * Allowing Undoing:: How to make your functions undoable.
! 617: * Redisplay:: Functions to control line display.
! 618: * Modifying Text:: Functions to modify @code{rl_line_buffer}.
! 619: * Character Input:: Functions to read keyboard input.
! 620: * Terminal Management:: Functions to manage terminal settings.
! 621: * Utility Functions:: Generally useful functions and hooks.
! 622: * Miscellaneous Functions:: Functions that don't fall into any category.
! 623: * Alternate Interface:: Using Readline in a `callback' fashion.
! 624: * A Readline Example:: An example Readline function.
! 625: * Alternate Interface Example:: An example program using the alternate interface.
! 626: @end menu
! 627:
! 628: @node Function Naming
! 629: @subsection Naming a Function
! 630:
! 631: The user can dynamically change the bindings of keys while using
! 632: Readline. This is done by representing the function with a descriptive
! 633: name. The user is able to type the descriptive name when referring to
! 634: the function. Thus, in an init file, one might find
! 635:
! 636: @example
! 637: Meta-Rubout: backward-kill-word
! 638: @end example
! 639:
! 640: This binds the keystroke @key{Meta-Rubout} to the function
! 641: @emph{descriptively} named @code{backward-kill-word}. You, as the
! 642: programmer, should bind the functions you write to descriptive names as
! 643: well. Readline provides a function for doing that:
! 644:
! 645: @deftypefun int rl_add_defun (const char *name, rl_command_func_t *function, int key)
! 646: Add @var{name} to the list of named functions. Make @var{function} be
! 647: the function that gets called. If @var{key} is not -1, then bind it to
! 648: @var{function} using @code{rl_bind_key()}.
! 649: @end deftypefun
! 650:
! 651: Using this function alone is sufficient for most applications.
! 652: It is the recommended way to add a few functions to the default
! 653: functions that Readline has built in.
! 654: If you need to do something other than adding a function to Readline,
! 655: you may need to use the underlying functions described below.
! 656:
! 657: @node Keymaps
! 658: @subsection Selecting a Keymap
! 659:
! 660: Key bindings take place on a @dfn{keymap}. The keymap is the
! 661: association between the keys that the user types and the functions that
! 662: get run. You can make your own keymaps, copy existing keymaps, and tell
! 663: Readline which keymap to use.
! 664:
! 665: @deftypefun Keymap rl_make_bare_keymap (void)
! 666: Returns a new, empty keymap. The space for the keymap is allocated with
! 667: @code{malloc()}; the caller should free it by calling
! 668: @code{rl_free_keymap()} when done.
! 669: @end deftypefun
! 670:
! 671: @deftypefun Keymap rl_copy_keymap (Keymap map)
! 672: Return a new keymap which is a copy of @var{map}.
! 673: @end deftypefun
! 674:
! 675: @deftypefun Keymap rl_make_keymap (void)
! 676: Return a new keymap with the printing characters bound to rl_insert,
! 677: the lowercase Meta characters bound to run their equivalents, and
! 678: the Meta digits bound to produce numeric arguments.
! 679: @end deftypefun
! 680:
! 681: @deftypefun void rl_discard_keymap (Keymap keymap)
! 682: Free the storage associated with the data in @var{keymap}.
! 683: The caller should free @var{keymap}.
! 684: @end deftypefun
! 685:
! 686: @deftypefun void rl_free_keymap (Keymap keymap)
! 687: Free all storage associated with @var{keymap}. This calls
! 688: @code{rl_discard_keymap} to free subordindate keymaps and macros.
! 689: @end deftypefun
! 690:
! 691: Readline has several internal keymaps. These functions allow you to
! 692: change which keymap is active.
! 693:
! 694: @deftypefun Keymap rl_get_keymap (void)
! 695: Returns the currently active keymap.
! 696: @end deftypefun
! 697:
! 698: @deftypefun void rl_set_keymap (Keymap keymap)
! 699: Makes @var{keymap} the currently active keymap.
! 700: @end deftypefun
! 701:
! 702: @deftypefun Keymap rl_get_keymap_by_name (const char *name)
! 703: Return the keymap matching @var{name}. @var{name} is one which would
! 704: be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
! 705: @end deftypefun
! 706:
! 707: @deftypefun {char *} rl_get_keymap_name (Keymap keymap)
! 708: Return the name matching @var{keymap}. @var{name} is one which would
! 709: be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
! 710: @end deftypefun
! 711:
! 712: @node Binding Keys
! 713: @subsection Binding Keys
! 714:
! 715: Key sequences are associate with functions through the keymap.
! 716: Readline has several internal keymaps: @code{emacs_standard_keymap},
! 717: @code{emacs_meta_keymap}, @code{emacs_ctlx_keymap},
! 718: @code{vi_movement_keymap}, and @code{vi_insertion_keymap}.
! 719: @code{emacs_standard_keymap} is the default, and the examples in
! 720: this manual assume that.
! 721:
! 722: Since @code{readline()} installs a set of default key bindings the first
! 723: time it is called, there is always the danger that a custom binding
! 724: installed before the first call to @code{readline()} will be overridden.
! 725: An alternate mechanism is to install custom key bindings in an
! 726: initialization function assigned to the @code{rl_startup_hook} variable
! 727: (@pxref{Readline Variables}).
! 728:
! 729: These functions manage key bindings.
! 730:
! 731: @deftypefun int rl_bind_key (int key, rl_command_func_t *function)
! 732: Binds @var{key} to @var{function} in the currently active keymap.
! 733: Returns non-zero in the case of an invalid @var{key}.
! 734: @end deftypefun
! 735:
! 736: @deftypefun int rl_bind_key_in_map (int key, rl_command_func_t *function, Keymap map)
! 737: Bind @var{key} to @var{function} in @var{map}.
! 738: Returns non-zero in the case of an invalid @var{key}.
! 739: @end deftypefun
! 740:
! 741: @deftypefun int rl_bind_key_if_unbound (int key, rl_command_func_t *function)
! 742: Binds @var{key} to @var{function} if it is not already bound in the
! 743: currently active keymap.
! 744: Returns non-zero in the case of an invalid @var{key} or if @var{key} is
! 745: already bound.
! 746: @end deftypefun
! 747:
! 748: @deftypefun int rl_bind_key_if_unbound_in_map (int key, rl_command_func_t *function, Keymap map)
! 749: Binds @var{key} to @var{function} if it is not already bound in @var{map}.
! 750: Returns non-zero in the case of an invalid @var{key} or if @var{key} is
! 751: already bound.
! 752: @end deftypefun
! 753:
! 754: @deftypefun int rl_unbind_key (int key)
! 755: Bind @var{key} to the null function in the currently active keymap.
! 756: Returns non-zero in case of error.
! 757: @end deftypefun
! 758:
! 759: @deftypefun int rl_unbind_key_in_map (int key, Keymap map)
! 760: Bind @var{key} to the null function in @var{map}.
! 761: Returns non-zero in case of error.
! 762: @end deftypefun
! 763:
! 764: @deftypefun int rl_unbind_function_in_map (rl_command_func_t *function, Keymap map)
! 765: Unbind all keys that execute @var{function} in @var{map}.
! 766: @end deftypefun
! 767:
! 768: @deftypefun int rl_unbind_command_in_map (const char *command, Keymap map)
! 769: Unbind all keys that are bound to @var{command} in @var{map}.
! 770: @end deftypefun
! 771:
! 772: @deftypefun int rl_bind_keyseq (const char *keyseq, rl_command_func_t *function)
! 773: Bind the key sequence represented by the string @var{keyseq} to the function
! 774: @var{function}, beginning in the current keymap.
! 775: This makes new keymaps as necessary.
! 776: The return value is non-zero if @var{keyseq} is invalid.
! 777: @end deftypefun
! 778:
! 779: @deftypefun int rl_bind_keyseq_in_map (const char *keyseq, rl_command_func_t *function, Keymap map)
! 780: Bind the key sequence represented by the string @var{keyseq} to the function
! 781: @var{function}. This makes new keymaps as necessary.
! 782: Initial bindings are performed in @var{map}.
! 783: The return value is non-zero if @var{keyseq} is invalid.
! 784: @end deftypefun
! 785:
! 786: @deftypefun int rl_set_key (const char *keyseq, rl_command_func_t *function, Keymap map)
! 787: Equivalent to @code{rl_bind_keyseq_in_map}.
! 788: @end deftypefun
! 789:
! 790: @deftypefun int rl_bind_keyseq_if_unbound (const char *keyseq, rl_command_func_t *function)
! 791: Binds @var{keyseq} to @var{function} if it is not already bound in the
! 792: currently active keymap.
! 793: Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is
! 794: already bound.
! 795: @end deftypefun
! 796:
! 797: @deftypefun int rl_bind_keyseq_if_unbound_in_map (const char *keyseq, rl_command_func_t *function, Keymap map)
! 798: Binds @var{keyseq} to @var{function} if it is not already bound in @var{map}.
! 799: Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is
! 800: already bound.
! 801: @end deftypefun
! 802:
! 803: @deftypefun int rl_generic_bind (int type, const char *keyseq, char *data, Keymap map)
! 804: Bind the key sequence represented by the string @var{keyseq} to the arbitrary
! 805: pointer @var{data}. @var{type} says what kind of data is pointed to by
! 806: @var{data}; this can be a function (@code{ISFUNC}), a macro
! 807: (@code{ISMACR}), or a keymap (@code{ISKMAP}). This makes new keymaps as
! 808: necessary. The initial keymap in which to do bindings is @var{map}.
! 809: @end deftypefun
! 810:
! 811: @deftypefun int rl_parse_and_bind (char *line)
! 812: Parse @var{line} as if it had been read from the @code{inputrc} file and
! 813: perform any key bindings and variable assignments found
! 814: (@pxref{Readline Init File}).
! 815: @end deftypefun
! 816:
! 817: @deftypefun int rl_read_init_file (const char *filename)
! 818: Read keybindings and variable assignments from @var{filename}
! 819: (@pxref{Readline Init File}).
! 820: @end deftypefun
! 821:
! 822: @node Associating Function Names and Bindings
! 823: @subsection Associating Function Names and Bindings
! 824:
! 825: These functions allow you to find out what keys invoke named functions
! 826: and the functions invoked by a particular key sequence. You may also
! 827: associate a new function name with an arbitrary function.
! 828:
! 829: @deftypefun {rl_command_func_t *} rl_named_function (const char *name)
! 830: Return the function with name @var{name}.
! 831: @end deftypefun
! 832:
! 833: @deftypefun {rl_command_func_t *} rl_function_of_keyseq (const char *keyseq, Keymap map, int *type)
! 834: Return the function invoked by @var{keyseq} in keymap @var{map}.
! 835: If @var{map} is @code{NULL}, the current keymap is used. If @var{type} is
! 836: not @code{NULL}, the type of the object is returned in the @code{int} variable
! 837: it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}).
! 838: @end deftypefun
! 839:
! 840: @deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *function)
! 841: Return an array of strings representing the key sequences used to
! 842: invoke @var{function} in the current keymap.
! 843: @end deftypefun
! 844:
! 845: @deftypefun {char **} rl_invoking_keyseqs_in_map (rl_command_func_t *function, Keymap map)
! 846: Return an array of strings representing the key sequences used to
! 847: invoke @var{function} in the keymap @var{map}.
! 848: @end deftypefun
! 849:
! 850: @deftypefun void rl_function_dumper (int readable)
! 851: Print the readline function names and the key sequences currently
! 852: bound to them to @code{rl_outstream}. If @var{readable} is non-zero,
! 853: the list is formatted in such a way that it can be made part of an
! 854: @code{inputrc} file and re-read.
! 855: @end deftypefun
! 856:
! 857: @deftypefun void rl_list_funmap_names (void)
! 858: Print the names of all bindable Readline functions to @code{rl_outstream}.
! 859: @end deftypefun
! 860:
! 861: @deftypefun {const char **} rl_funmap_names (void)
! 862: Return a NULL terminated array of known function names. The array is
! 863: sorted. The array itself is allocated, but not the strings inside. You
! 864: should free the array, but not the pointers, using @code{free} or
! 865: @code{rl_free} when you are done.
! 866: @end deftypefun
! 867:
! 868: @deftypefun int rl_add_funmap_entry (const char *name, rl_command_func_t *function)
! 869: Add @var{name} to the list of bindable Readline command names, and make
! 870: @var{function} the function to be called when @var{name} is invoked.
! 871: @end deftypefun
! 872:
! 873: @node Allowing Undoing
! 874: @subsection Allowing Undoing
! 875:
! 876: Supporting the undo command is a painless thing, and makes your
! 877: functions much more useful. It is certainly easy to try
! 878: something if you know you can undo it.
! 879:
! 880: If your function simply inserts text once, or deletes text once, and
! 881: uses @code{rl_insert_text()} or @code{rl_delete_text()} to do it, then
! 882: undoing is already done for you automatically.
! 883:
! 884: If you do multiple insertions or multiple deletions, or any combination
! 885: of these operations, you should group them together into one operation.
! 886: This is done with @code{rl_begin_undo_group()} and
! 887: @code{rl_end_undo_group()}.
! 888:
! 889: The types of events that can be undone are:
! 890:
! 891: @smallexample
! 892: enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @};
! 893: @end smallexample
! 894:
! 895: Notice that @code{UNDO_DELETE} means to insert some text, and
! 896: @code{UNDO_INSERT} means to delete some text. That is, the undo code
! 897: tells what to undo, not how to undo it. @code{UNDO_BEGIN} and
! 898: @code{UNDO_END} are tags added by @code{rl_begin_undo_group()} and
! 899: @code{rl_end_undo_group()}.
! 900:
! 901: @deftypefun int rl_begin_undo_group (void)
! 902: Begins saving undo information in a group construct. The undo
! 903: information usually comes from calls to @code{rl_insert_text()} and
! 904: @code{rl_delete_text()}, but could be the result of calls to
! 905: @code{rl_add_undo()}.
! 906: @end deftypefun
! 907:
! 908: @deftypefun int rl_end_undo_group (void)
! 909: Closes the current undo group started with @code{rl_begin_undo_group
! 910: ()}. There should be one call to @code{rl_end_undo_group()}
! 911: for each call to @code{rl_begin_undo_group()}.
! 912: @end deftypefun
! 913:
! 914: @deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text)
! 915: Remember how to undo an event (according to @var{what}). The affected
! 916: text runs from @var{start} to @var{end}, and encompasses @var{text}.
! 917: @end deftypefun
! 918:
! 919: @deftypefun void rl_free_undo_list (void)
! 920: Free the existing undo list.
! 921: @end deftypefun
! 922:
! 923: @deftypefun int rl_do_undo (void)
! 924: Undo the first thing on the undo list. Returns @code{0} if there was
! 925: nothing to undo, non-zero if something was undone.
! 926: @end deftypefun
! 927:
! 928: Finally, if you neither insert nor delete text, but directly modify the
! 929: existing text (e.g., change its case), call @code{rl_modifying()}
! 930: once, just before you modify the text. You must supply the indices of
! 931: the text range that you are going to modify.
! 932:
! 933: @deftypefun int rl_modifying (int start, int end)
! 934: Tell Readline to save the text between @var{start} and @var{end} as a
! 935: single undo unit. It is assumed that you will subsequently modify
! 936: that text.
! 937: @end deftypefun
! 938:
! 939: @node Redisplay
! 940: @subsection Redisplay
! 941:
! 942: @deftypefun void rl_redisplay (void)
! 943: Change what's displayed on the screen to reflect the current contents
! 944: of @code{rl_line_buffer}.
! 945: @end deftypefun
! 946:
! 947: @deftypefun int rl_forced_update_display (void)
! 948: Force the line to be updated and redisplayed, whether or not
! 949: Readline thinks the screen display is correct.
! 950: @end deftypefun
! 951:
! 952: @deftypefun int rl_on_new_line (void)
! 953: Tell the update functions that we have moved onto a new (empty) line,
! 954: usually after outputting a newline.
! 955: @end deftypefun
! 956:
! 957: @deftypefun int rl_on_new_line_with_prompt (void)
! 958: Tell the update functions that we have moved onto a new line, with
! 959: @var{rl_prompt} already displayed.
! 960: This could be used by applications that want to output the prompt string
! 961: themselves, but still need Readline to know the prompt string length for
! 962: redisplay.
! 963: It should be used after setting @var{rl_already_prompted}.
! 964: @end deftypefun
! 965:
! 966: @deftypefun int rl_reset_line_state (void)
! 967: Reset the display state to a clean state and redisplay the current line
! 968: starting on a new line.
! 969: @end deftypefun
! 970:
! 971: @deftypefun int rl_crlf (void)
! 972: Move the cursor to the start of the next screen line.
! 973: @end deftypefun
! 974:
! 975: @deftypefun int rl_show_char (int c)
! 976: Display character @var{c} on @code{rl_outstream}.
! 977: If Readline has not been set to display meta characters directly, this
! 978: will convert meta characters to a meta-prefixed key sequence.
! 979: This is intended for use by applications which wish to do their own
! 980: redisplay.
! 981: @end deftypefun
! 982:
! 983: @deftypefun int rl_message (const char *, @dots{})
! 984: The arguments are a format string as would be supplied to @code{printf},
! 985: possibly containing conversion specifications such as @samp{%d}, and
! 986: any additional arguments necessary to satisfy the conversion specifications.
! 987: The resulting string is displayed in the @dfn{echo area}. The echo area
! 988: is also used to display numeric arguments and search strings.
! 989: You should call @code{rl_save_prompt} to save the prompt information
! 990: before calling this function.
! 991: @end deftypefun
! 992:
! 993: @deftypefun int rl_clear_message (void)
! 994: Clear the message in the echo area. If the prompt was saved with a call to
! 995: @code{rl_save_prompt} before the last call to @code{rl_message},
! 996: call @code{rl_restore_prompt} before calling this function.
! 997: @end deftypefun
! 998:
! 999: @deftypefun void rl_save_prompt (void)
! 1000: Save the local Readline prompt display state in preparation for
! 1001: displaying a new message in the message area with @code{rl_message()}.
! 1002: @end deftypefun
! 1003:
! 1004: @deftypefun void rl_restore_prompt (void)
! 1005: Restore the local Readline prompt display state saved by the most
! 1006: recent call to @code{rl_save_prompt}.
! 1007: if @code{rl_save_prompt} was called to save the prompt before a call
! 1008: to @code{rl_message}, this function should be called before the
! 1009: corresponding call to @code{rl_clear_message}.
! 1010: @end deftypefun
! 1011:
! 1012: @deftypefun int rl_expand_prompt (char *prompt)
! 1013: Expand any special character sequences in @var{prompt} and set up the
! 1014: local Readline prompt redisplay variables.
! 1015: This function is called by @code{readline()}. It may also be called to
! 1016: expand the primary prompt if the @code{rl_on_new_line_with_prompt()}
! 1017: function or @code{rl_already_prompted} variable is used.
! 1018: It returns the number of visible characters on the last line of the
! 1019: (possibly multi-line) prompt.
! 1020: Applications may indicate that the prompt contains characters that take
! 1021: up no physical screen space when displayed by bracketing a sequence of
! 1022: such characters with the special markers @code{RL_PROMPT_START_IGNORE}
! 1023: and @code{RL_PROMPT_END_IGNORE} (declared in @file{readline.h}. This may
! 1024: be used to embed terminal-specific escape sequences in prompts.
! 1025: @end deftypefun
! 1026:
! 1027: @deftypefun int rl_set_prompt (const char *prompt)
! 1028: Make Readline use @var{prompt} for subsequent redisplay. This calls
! 1029: @code{rl_expand_prompt()} to expand the prompt and sets @code{rl_prompt}
! 1030: to the result.
! 1031: @end deftypefun
! 1032:
! 1033: @node Modifying Text
! 1034: @subsection Modifying Text
! 1035:
! 1036: @deftypefun int rl_insert_text (const char *text)
! 1037: Insert @var{text} into the line at the current cursor position.
! 1038: Returns the number of characters inserted.
! 1039: @end deftypefun
! 1040:
! 1041: @deftypefun int rl_delete_text (int start, int end)
! 1042: Delete the text between @var{start} and @var{end} in the current line.
! 1043: Returns the number of characters deleted.
! 1044: @end deftypefun
! 1045:
! 1046: @deftypefun {char *} rl_copy_text (int start, int end)
! 1047: Return a copy of the text between @var{start} and @var{end} in
! 1048: the current line.
! 1049: @end deftypefun
! 1050:
! 1051: @deftypefun int rl_kill_text (int start, int end)
! 1052: Copy the text between @var{start} and @var{end} in the current line
! 1053: to the kill ring, appending or prepending to the last kill if the
! 1054: last command was a kill command. The text is deleted.
! 1055: If @var{start} is less than @var{end},
! 1056: the text is appended, otherwise prepended. If the last command was
! 1057: not a kill, a new kill ring slot is used.
! 1058: @end deftypefun
! 1059:
! 1060: @deftypefun int rl_push_macro_input (char *macro)
! 1061: Cause @var{macro} to be inserted into the line, as if it had been invoked
! 1062: by a key bound to a macro. Not especially useful; use
! 1063: @code{rl_insert_text()} instead.
! 1064: @end deftypefun
! 1065:
! 1066: @node Character Input
! 1067: @subsection Character Input
! 1068:
! 1069: @deftypefun int rl_read_key (void)
! 1070: Return the next character available from Readline's current input stream.
! 1071: This handles input inserted into
! 1072: the input stream via @var{rl_pending_input} (@pxref{Readline Variables})
! 1073: and @code{rl_stuff_char()}, macros, and characters read from the keyboard.
! 1074: While waiting for input, this function will call any function assigned to
! 1075: the @code{rl_event_hook} variable.
! 1076: @end deftypefun
! 1077:
! 1078: @deftypefun int rl_getc (FILE *stream)
! 1079: Return the next character available from @var{stream}, which is assumed to
! 1080: be the keyboard.
! 1081: @end deftypefun
! 1082:
! 1083: @deftypefun int rl_stuff_char (int c)
! 1084: Insert @var{c} into the Readline input stream. It will be "read"
! 1085: before Readline attempts to read characters from the terminal with
! 1086: @code{rl_read_key()}. Up to 512 characters may be pushed back.
! 1087: @code{rl_stuff_char} returns 1 if the character was successfully inserted;
! 1088: 0 otherwise.
! 1089: @end deftypefun
! 1090:
! 1091: @deftypefun int rl_execute_next (int c)
! 1092: Make @var{c} be the next command to be executed when @code{rl_read_key()}
! 1093: is called. This sets @var{rl_pending_input}.
! 1094: @end deftypefun
! 1095:
! 1096: @deftypefun int rl_clear_pending_input (void)
! 1097: Unset @var{rl_pending_input}, effectively negating the effect of any
! 1098: previous call to @code{rl_execute_next()}. This works only if the
! 1099: pending input has not already been read with @code{rl_read_key()}.
! 1100: @end deftypefun
! 1101:
! 1102: @deftypefun int rl_set_keyboard_input_timeout (int u)
! 1103: While waiting for keyboard input in @code{rl_read_key()}, Readline will
! 1104: wait for @var{u} microseconds for input before calling any function
! 1105: assigned to @code{rl_event_hook}. @var{u} must be greater than or equal
! 1106: to zero (a zero-length timeout is equivalent to a poll).
! 1107: The default waiting period is one-tenth of a second.
! 1108: Returns the old timeout value.
! 1109: @end deftypefun
! 1110:
! 1111: @node Terminal Management
! 1112: @subsection Terminal Management
! 1113:
! 1114: @deftypefun void rl_prep_terminal (int meta_flag)
! 1115: Modify the terminal settings for Readline's use, so @code{readline()}
! 1116: can read a single character at a time from the keyboard.
! 1117: The @var{meta_flag} argument should be non-zero if Readline should
! 1118: read eight-bit input.
! 1119: @end deftypefun
! 1120:
! 1121: @deftypefun void rl_deprep_terminal (void)
! 1122: Undo the effects of @code{rl_prep_terminal()}, leaving the terminal in
! 1123: the state in which it was before the most recent call to
! 1124: @code{rl_prep_terminal()}.
! 1125: @end deftypefun
! 1126:
! 1127: @deftypefun void rl_tty_set_default_bindings (Keymap kmap)
! 1128: Read the operating system's terminal editing characters (as would be
! 1129: displayed by @code{stty}) to their Readline equivalents.
! 1130: The bindings are performed in @var{kmap}.
! 1131: @end deftypefun
! 1132:
! 1133: @deftypefun void rl_tty_unset_default_bindings (Keymap kmap)
! 1134: Reset the bindings manipulated by @code{rl_tty_set_default_bindings} so
! 1135: that the terminal editing characters are bound to @code{rl_insert}.
! 1136: The bindings are performed in @var{kmap}.
! 1137: @end deftypefun
! 1138:
! 1139: @deftypefun int rl_reset_terminal (const char *terminal_name)
! 1140: Reinitialize Readline's idea of the terminal settings using
! 1141: @var{terminal_name} as the terminal type (e.g., @code{vt100}).
! 1142: If @var{terminal_name} is @code{NULL}, the value of the @code{TERM}
! 1143: environment variable is used.
! 1144: @end deftypefun
! 1145:
! 1146: @node Utility Functions
! 1147: @subsection Utility Functions
! 1148:
! 1149: @deftypefun int rl_save_state (struct readline_state *sp)
! 1150: Save a snapshot of Readline's internal state to @var{sp}.
! 1151: The contents of the @var{readline_state} structure are documented
! 1152: in @file{readline.h}.
! 1153: The caller is responsible for allocating the structure.
! 1154: @end deftypefun
! 1155:
! 1156: @deftypefun int rl_restore_state (struct readline_state *sp)
! 1157: Restore Readline's internal state to that stored in @var{sp}, which must
! 1158: have been saved by a call to @code{rl_save_state}.
! 1159: The contents of the @var{readline_state} structure are documented
! 1160: in @file{readline.h}.
! 1161: The caller is responsible for freeing the structure.
! 1162: @end deftypefun
! 1163:
! 1164: @deftypefun void rl_free (void *mem)
! 1165: Deallocate the memory pointed to by @var{mem}. @var{mem} must have been
! 1166: allocated by @code{malloc}.
! 1167: @end deftypefun
! 1168:
! 1169: @deftypefun void rl_replace_line (const char *text, int clear_undo)
! 1170: Replace the contents of @code{rl_line_buffer} with @var{text}.
! 1171: The point and mark are preserved, if possible.
! 1172: If @var{clear_undo} is non-zero, the undo list associated with the
! 1173: current line is cleared.
! 1174: @end deftypefun
! 1175:
! 1176: @deftypefun void rl_extend_line_buffer (int len)
! 1177: Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
! 1178: characters, possibly reallocating it if necessary.
! 1179: @end deftypefun
! 1180:
! 1181: @deftypefun int rl_initialize (void)
! 1182: Initialize or re-initialize Readline's internal state.
! 1183: It's not strictly necessary to call this; @code{readline()} calls it before
! 1184: reading any input.
! 1185: @end deftypefun
! 1186:
! 1187: @deftypefun int rl_ding (void)
! 1188: Ring the terminal bell, obeying the setting of @code{bell-style}.
! 1189: @end deftypefun
! 1190:
! 1191: @deftypefun int rl_alphabetic (int c)
! 1192: Return 1 if @var{c} is an alphabetic character.
! 1193: @end deftypefun
! 1194:
! 1195: @deftypefun void rl_display_match_list (char **matches, int len, int max)
! 1196: A convenience function for displaying a list of strings in
! 1197: columnar format on Readline's output stream. @code{matches} is the list
! 1198: of strings, in argv format, such as a list of completion matches.
! 1199: @code{len} is the number of strings in @code{matches}, and @code{max}
! 1200: is the length of the longest string in @code{matches}. This function uses
! 1201: the setting of @code{print-completions-horizontally} to select how the
! 1202: matches are displayed (@pxref{Readline Init File Syntax}).
! 1203: When displaying completions, this function sets the number of columns used
! 1204: for display to the value of @code{completion-display-width}, the value of
! 1205: the environment variable @env{COLUMNS}, or the screen width, in that order.
! 1206: @end deftypefun
! 1207:
! 1208: The following are implemented as macros, defined in @code{chardefs.h}.
! 1209: Applications should refrain from using them.
! 1210:
! 1211: @deftypefun int _rl_uppercase_p (int c)
! 1212: Return 1 if @var{c} is an uppercase alphabetic character.
! 1213: @end deftypefun
! 1214:
! 1215: @deftypefun int _rl_lowercase_p (int c)
! 1216: Return 1 if @var{c} is a lowercase alphabetic character.
! 1217: @end deftypefun
! 1218:
! 1219: @deftypefun int _rl_digit_p (int c)
! 1220: Return 1 if @var{c} is a numeric character.
! 1221: @end deftypefun
! 1222:
! 1223: @deftypefun int _rl_to_upper (int c)
! 1224: If @var{c} is a lowercase alphabetic character, return the corresponding
! 1225: uppercase character.
! 1226: @end deftypefun
! 1227:
! 1228: @deftypefun int _rl_to_lower (int c)
! 1229: If @var{c} is an uppercase alphabetic character, return the corresponding
! 1230: lowercase character.
! 1231: @end deftypefun
! 1232:
! 1233: @deftypefun int _rl_digit_value (int c)
! 1234: If @var{c} is a number, return the value it represents.
! 1235: @end deftypefun
! 1236:
! 1237: @node Miscellaneous Functions
! 1238: @subsection Miscellaneous Functions
! 1239:
! 1240: @deftypefun int rl_macro_bind (const char *keyseq, const char *macro, Keymap map)
! 1241: Bind the key sequence @var{keyseq} to invoke the macro @var{macro}.
! 1242: The binding is performed in @var{map}. When @var{keyseq} is invoked, the
! 1243: @var{macro} will be inserted into the line. This function is deprecated;
! 1244: use @code{rl_generic_bind()} instead.
! 1245: @end deftypefun
! 1246:
! 1247: @deftypefun void rl_macro_dumper (int readable)
! 1248: Print the key sequences bound to macros and their values, using
! 1249: the current keymap, to @code{rl_outstream}.
! 1250: If @var{readable} is non-zero, the list is formatted in such a way
! 1251: that it can be made part of an @code{inputrc} file and re-read.
! 1252: @end deftypefun
! 1253:
! 1254: @deftypefun int rl_variable_bind (const char *variable, const char *value)
! 1255: Make the Readline variable @var{variable} have @var{value}.
! 1256: This behaves as if the readline command
! 1257: @samp{set @var{variable} @var{value}} had been executed in an @code{inputrc}
! 1258: file (@pxref{Readline Init File Syntax}).
! 1259: @end deftypefun
! 1260:
! 1261: @deftypefun {char *} rl_variable_value (const char *variable)
! 1262: Return a string representing the value of the Readline variable @var{variable}.
! 1263: For boolean variables, this string is either @samp{on} or @samp{off}.
! 1264: @end deftypefun
! 1265:
! 1266: @deftypefun void rl_variable_dumper (int readable)
! 1267: Print the readline variable names and their current values
! 1268: to @code{rl_outstream}.
! 1269: If @var{readable} is non-zero, the list is formatted in such a way
! 1270: that it can be made part of an @code{inputrc} file and re-read.
! 1271: @end deftypefun
! 1272:
! 1273: @deftypefun int rl_set_paren_blink_timeout (int u)
! 1274: Set the time interval (in microseconds) that Readline waits when showing
! 1275: a balancing character when @code{blink-matching-paren} has been enabled.
! 1276: @end deftypefun
! 1277:
! 1278: @deftypefun {char *} rl_get_termcap (const char *cap)
! 1279: Retrieve the string value of the termcap capability @var{cap}.
! 1280: Readline fetches the termcap entry for the current terminal name and
! 1281: uses those capabilities to move around the screen line and perform other
! 1282: terminal-specific operations, like erasing a line. Readline does not
! 1283: use all of a terminal's capabilities, and this function will return
! 1284: values for only those capabilities Readline uses.
! 1285: @end deftypefun
! 1286:
! 1287: @deftypefun {void} rl_clear_history (void)
! 1288: Clear the history list by deleting all of the entries, in the same manner
! 1289: as the History library's @code{clear_history()} function.
! 1290: This differs from @code{clear_history} because it frees private data
! 1291: Readline saves in the history list.
! 1292: @end deftypefun
! 1293:
! 1294: @node Alternate Interface
! 1295: @subsection Alternate Interface
! 1296:
! 1297: An alternate interface is available to plain @code{readline()}. Some
! 1298: applications need to interleave keyboard I/O with file, device, or
! 1299: window system I/O, typically by using a main loop to @code{select()}
! 1300: on various file descriptors. To accommodate this need, readline can
! 1301: also be invoked as a `callback' function from an event loop. There
! 1302: are functions available to make this easy.
! 1303:
! 1304: @deftypefun void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler)
! 1305: Set up the terminal for readline I/O and display the initial
! 1306: expanded value of @var{prompt}. Save the value of @var{lhandler} to
! 1307: use as a handler function to call when a complete line of input has been
! 1308: entered.
! 1309: The handler function receives the text of the line as an argument.
! 1310: @end deftypefun
! 1311:
! 1312: @deftypefun void rl_callback_read_char (void)
! 1313: Whenever an application determines that keyboard input is available, it
! 1314: should call @code{rl_callback_read_char()}, which will read the next
! 1315: character from the current input source.
! 1316: If that character completes the line, @code{rl_callback_read_char} will
! 1317: invoke the @var{lhandler} function installed by
! 1318: @code{rl_callback_handler_install} to process the line.
! 1319: Before calling the @var{lhandler} function, the terminal settings are
! 1320: reset to the values they had before calling
! 1321: @code{rl_callback_handler_install}.
! 1322: If the @var{lhandler} function returns,
! 1323: and the line handler remains installed,
! 1324: the terminal settings are modified for Readline's use again.
! 1325: @code{EOF} is indicated by calling @var{lhandler} with a
! 1326: @code{NULL} line.
! 1327: @end deftypefun
! 1328:
! 1329: @deftypefun void rl_callback_handler_remove (void)
! 1330: Restore the terminal to its initial state and remove the line handler.
! 1331: This may be called from within a callback as well as independently.
! 1332: If the @var{lhandler} installed by @code{rl_callback_handler_install}
! 1333: does not exit the program, either this function or the function referred
! 1334: to by the value of @code{rl_deprep_term_function} should be called before
! 1335: the program exits to reset the terminal settings.
! 1336: @end deftypefun
! 1337:
! 1338: @node A Readline Example
! 1339: @subsection A Readline Example
! 1340:
! 1341: Here is a function which changes lowercase characters to their uppercase
! 1342: equivalents, and uppercase characters to lowercase. If
! 1343: this function was bound to @samp{M-c}, then typing @samp{M-c} would
! 1344: change the case of the character under point. Typing @samp{M-1 0 M-c}
! 1345: would change the case of the following 10 characters, leaving the cursor on
! 1346: the last character changed.
! 1347:
! 1348: @example
! 1349: /* Invert the case of the COUNT following characters. */
! 1350: int
! 1351: invert_case_line (count, key)
! 1352: int count, key;
! 1353: @{
! 1354: register int start, end, i;
! 1355:
! 1356: start = rl_point;
! 1357:
! 1358: if (rl_point >= rl_end)
! 1359: return (0);
! 1360:
! 1361: if (count < 0)
! 1362: @{
! 1363: direction = -1;
! 1364: count = -count;
! 1365: @}
! 1366: else
! 1367: direction = 1;
! 1368:
! 1369: /* Find the end of the range to modify. */
! 1370: end = start + (count * direction);
! 1371:
! 1372: /* Force it to be within range. */
! 1373: if (end > rl_end)
! 1374: end = rl_end;
! 1375: else if (end < 0)
! 1376: end = 0;
! 1377:
! 1378: if (start == end)
! 1379: return (0);
! 1380:
! 1381: if (start > end)
! 1382: @{
! 1383: int temp = start;
! 1384: start = end;
! 1385: end = temp;
! 1386: @}
! 1387:
! 1388: /* Tell readline that we are modifying the line,
! 1389: so it will save the undo information. */
! 1390: rl_modifying (start, end);
! 1391:
! 1392: for (i = start; i != end; i++)
! 1393: @{
! 1394: if (_rl_uppercase_p (rl_line_buffer[i]))
! 1395: rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]);
! 1396: else if (_rl_lowercase_p (rl_line_buffer[i]))
! 1397: rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]);
! 1398: @}
! 1399: /* Move point to on top of the last character changed. */
! 1400: rl_point = (direction == 1) ? end - 1 : start;
! 1401: return (0);
! 1402: @}
! 1403: @end example
! 1404:
! 1405: @node Alternate Interface Example
! 1406: @subsection Alternate Interface Example
! 1407:
! 1408: Here is a complete program that illustrates Readline's alternate interface.
! 1409: It reads lines from the terminal and displays them, providing the
! 1410: standard history and TAB completion functions.
! 1411: It understands the EOF character or "exit" to exit the program.
! 1412:
! 1413: @example
! 1414: /* Standard include files. stdio.h is required. */
! 1415: #include <stdlib.h>
! 1416: #include <unistd.h>
! 1417:
! 1418: /* Used for select(2) */
! 1419: #include <sys/types.h>
! 1420: #include <sys/select.h>
! 1421:
! 1422: #include <stdio.h>
! 1423:
! 1424: /* Standard readline include files. */
! 1425: #include <readline/readline.h>
! 1426: #include <readline/history.h>
! 1427:
! 1428: static void cb_linehandler (char *);
! 1429:
! 1430: int running;
! 1431: const char *prompt = "rltest$ ";
! 1432:
! 1433: /* Callback function called for each line when accept-line executed, EOF
! 1434: seen, or EOF character read. This sets a flag and returns; it could
! 1435: also call exit(3). */
! 1436: static void
! 1437: cb_linehandler (char *line)
! 1438: @{
! 1439: /* Can use ^D (stty eof) or `exit' to exit. */
! 1440: if (line == NULL || strcmp (line, "exit") == 0)
! 1441: @{
! 1442: if (line == 0)
! 1443: printf ("\n");
! 1444: printf ("exit\n");
! 1445: /* This function needs to be called to reset the terminal settings,
! 1446: and calling it from the line handler keeps one extra prompt from
! 1447: being displayed. */
! 1448: rl_callback_handler_remove ();
! 1449:
! 1450: running = 0;
! 1451: @}
! 1452: else
! 1453: @{
! 1454: if (*line)
! 1455: add_history (line);
! 1456: printf ("input line: %s\n", line);
! 1457: free (line);
! 1458: @}
! 1459: @}
! 1460:
! 1461: int
! 1462: main (int c, char **v)
! 1463: @{
! 1464: fd_set fds;
! 1465: int r;
! 1466:
! 1467: /* Install the line handler. */
! 1468: rl_callback_handler_install (prompt, cb_linehandler);
! 1469:
! 1470: /* Enter a simple event loop. This waits until something is available
! 1471: to read on readline's input stream (defaults to standard input) and
! 1472: calls the builtin character read callback to read it. It does not
! 1473: have to modify the user's terminal settings. */
! 1474: running = 1;
! 1475: while (running)
! 1476: @{
! 1477: FD_ZERO (&fds);
! 1478: FD_SET (fileno (rl_instream), &fds);
! 1479:
! 1480: r = select (FD_SETSIZE, &fds, NULL, NULL, NULL);
! 1481: if (r < 0)
! 1482: @{
! 1483: perror ("rltest: select");
! 1484: rl_callback_handler_remove ();
! 1485: break;
! 1486: @}
! 1487:
! 1488: if (FD_ISSET (fileno (rl_instream), &fds))
! 1489: rl_callback_read_char ();
! 1490: @}
! 1491:
! 1492: printf ("rltest: Event loop has exited\n");
! 1493: return 0;
! 1494: @}
! 1495: @end example
! 1496:
! 1497: @node Readline Signal Handling
! 1498: @section Readline Signal Handling
! 1499:
! 1500: Signals are asynchronous events sent to a process by the Unix kernel,
! 1501: sometimes on behalf of another process. They are intended to indicate
! 1502: exceptional events, like a user pressing the interrupt key on his terminal,
! 1503: or a network connection being broken. There is a class of signals that can
! 1504: be sent to the process currently reading input from the keyboard. Since
! 1505: Readline changes the terminal attributes when it is called, it needs to
! 1506: perform special processing when such a signal is received in order to
! 1507: restore the terminal to a sane state, or provide application writers with
! 1508: functions to do so manually.
! 1509:
! 1510: Readline contains an internal signal handler that is installed for a
! 1511: number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM},
! 1512: @code{SIGHUP},
! 1513: @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}).
! 1514: When one of these signals is received, the signal handler
! 1515: will reset the terminal attributes to those that were in effect before
! 1516: @code{readline()} was called, reset the signal handling to what it was
! 1517: before @code{readline()} was called, and resend the signal to the calling
! 1518: application.
! 1519: If and when the calling application's signal handler returns, Readline
! 1520: will reinitialize the terminal and continue to accept input.
! 1521: When a @code{SIGINT} is received, the Readline signal handler performs
! 1522: some additional work, which will cause any partially-entered line to be
! 1523: aborted (see the description of @code{rl_free_line_state()} below).
! 1524:
! 1525: There is an additional Readline signal handler, for @code{SIGWINCH}, which
! 1526: the kernel sends to a process whenever the terminal's size changes (for
! 1527: example, if a user resizes an @code{xterm}). The Readline @code{SIGWINCH}
! 1528: handler updates Readline's internal screen size information, and then calls
! 1529: any @code{SIGWINCH} signal handler the calling application has installed.
! 1530: Readline calls the application's @code{SIGWINCH} signal handler without
! 1531: resetting the terminal to its original state. If the application's signal
! 1532: handler does more than update its idea of the terminal size and return (for
! 1533: example, a @code{longjmp} back to a main processing loop), it @emph{must}
! 1534: call @code{rl_cleanup_after_signal()} (described below), to restore the
! 1535: terminal state.
! 1536:
! 1537: Readline provides two variables that allow application writers to
! 1538: control whether or not it will catch certain signals and act on them
! 1539: when they are received. It is important that applications change the
! 1540: values of these variables only when calling @code{readline()}, not in
! 1541: a signal handler, so Readline's internal signal state is not corrupted.
! 1542:
! 1543: @deftypevar int rl_catch_signals
! 1544: If this variable is non-zero, Readline will install signal handlers for
! 1545: @code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM},
! 1546: @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}.
! 1547:
! 1548: The default value of @code{rl_catch_signals} is 1.
! 1549: @end deftypevar
! 1550:
! 1551: @deftypevar int rl_catch_sigwinch
! 1552: If this variable is set to a non-zero value,
! 1553: Readline will install a signal handler for @code{SIGWINCH}.
! 1554:
! 1555: The default value of @code{rl_catch_sigwinch} is 1.
! 1556: @end deftypevar
! 1557:
! 1558: @deftypevar int rl_change_environment
! 1559: If this variable is set to a non-zero value,
! 1560: and Readline is handling @code{SIGWINCH}, Readline will modify the
! 1561: @var{LINES} and @var{COLUMNS} environment variables upon receipt of a
! 1562: @code{SIGWINCH}
! 1563:
! 1564: The default value of @code{rl_change_environment} is 1.
! 1565: @end deftypevar
! 1566:
! 1567: If an application does not wish to have Readline catch any signals, or
! 1568: to handle signals other than those Readline catches (@code{SIGHUP},
! 1569: for example),
! 1570: Readline provides convenience functions to do the necessary terminal
! 1571: and internal state cleanup upon receipt of a signal.
! 1572:
! 1573: @deftypefun void rl_cleanup_after_signal (void)
! 1574: This function will reset the state of the terminal to what it was before
! 1575: @code{readline()} was called, and remove the Readline signal handlers for
! 1576: all signals, depending on the values of @code{rl_catch_signals} and
! 1577: @code{rl_catch_sigwinch}.
! 1578: @end deftypefun
! 1579:
! 1580: @deftypefun void rl_free_line_state (void)
! 1581: This will free any partial state associated with the current input line
! 1582: (undo information, any partial history entry, any partially-entered
! 1583: keyboard macro, and any partially-entered numeric argument). This
! 1584: should be called before @code{rl_cleanup_after_signal()}. The
! 1585: Readline signal handler for @code{SIGINT} calls this to abort the
! 1586: current input line.
! 1587: @end deftypefun
! 1588:
! 1589: @deftypefun void rl_reset_after_signal (void)
! 1590: This will reinitialize the terminal and reinstall any Readline signal
! 1591: handlers, depending on the values of @code{rl_catch_signals} and
! 1592: @code{rl_catch_sigwinch}.
! 1593: @end deftypefun
! 1594:
! 1595: If an application does not wish Readline to catch @code{SIGWINCH}, it may
! 1596: call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force
! 1597: Readline to update its idea of the terminal size when a @code{SIGWINCH}
! 1598: is received.
! 1599:
! 1600: @deftypefun void rl_echo_signal_char (int sig)
! 1601: If an application wishes to install its own signal handlers, but still
! 1602: have readline display characters that generate signals, calling this
! 1603: function with @var{sig} set to @code{SIGINT}, @code{SIGQUIT}, or
! 1604: @code{SIGTSTP} will display the character generating that signal.
! 1605: @end deftypefun
! 1606:
! 1607: @deftypefun void rl_resize_terminal (void)
! 1608: Update Readline's internal screen size by reading values from the kernel.
! 1609: @end deftypefun
! 1610:
! 1611: @deftypefun void rl_set_screen_size (int rows, int cols)
! 1612: Set Readline's idea of the terminal size to @var{rows} rows and
! 1613: @var{cols} columns. If either @var{rows} or @var{columns} is less than
! 1614: or equal to 0, Readline's idea of that terminal dimension is unchanged.
! 1615: @end deftypefun
! 1616:
! 1617: If an application does not want to install a @code{SIGWINCH} handler, but
! 1618: is still interested in the screen dimensions, Readline's idea of the screen
! 1619: size may be queried.
! 1620:
! 1621: @deftypefun void rl_get_screen_size (int *rows, int *cols)
! 1622: Return Readline's idea of the terminal's size in the
! 1623: variables pointed to by the arguments.
! 1624: @end deftypefun
! 1625:
! 1626: @deftypefun void rl_reset_screen_size (void)
! 1627: Cause Readline to reobtain the screen size and recalculate its dimensions.
! 1628: @end deftypefun
! 1629:
! 1630: The following functions install and remove Readline's signal handlers.
! 1631:
! 1632: @deftypefun int rl_set_signals (void)
! 1633: Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT},
! 1634: @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN},
! 1635: @code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of
! 1636: @code{rl_catch_signals} and @code{rl_catch_sigwinch}.
! 1637: @end deftypefun
! 1638:
! 1639: @deftypefun int rl_clear_signals (void)
! 1640: Remove all of the Readline signal handlers installed by
! 1641: @code{rl_set_signals()}.
! 1642: @end deftypefun
! 1643:
! 1644: @node Custom Completers
! 1645: @section Custom Completers
! 1646: @cindex application-specific completion functions
! 1647:
! 1648: Typically, a program that reads commands from the user has a way of
! 1649: disambiguating commands and data. If your program is one of these, then
! 1650: it can provide completion for commands, data, or both.
! 1651: The following sections describe how your program and Readline
! 1652: cooperate to provide this service.
! 1653:
! 1654: @menu
! 1655: * How Completing Works:: The logic used to do completion.
! 1656: * Completion Functions:: Functions provided by Readline.
! 1657: * Completion Variables:: Variables which control completion.
! 1658: * A Short Completion Example:: An example of writing completer subroutines.
! 1659: @end menu
! 1660:
! 1661: @node How Completing Works
! 1662: @subsection How Completing Works
! 1663:
! 1664: In order to complete some text, the full list of possible completions
! 1665: must be available. That is, it is not possible to accurately
! 1666: expand a partial word without knowing all of the possible words
! 1667: which make sense in that context. The Readline library provides
! 1668: the user interface to completion, and two of the most common
! 1669: completion functions: filename and username. For completing other types
! 1670: of text, you must write your own completion function. This section
! 1671: describes exactly what such functions must do, and provides an example.
! 1672:
! 1673: There are three major functions used to perform completion:
! 1674:
! 1675: @enumerate
! 1676: @item
! 1677: The user-interface function @code{rl_complete()}. This function is
! 1678: called with the same arguments as other bindable Readline functions:
! 1679: @var{count} and @var{invoking_key}.
! 1680: It isolates the word to be completed and calls
! 1681: @code{rl_completion_matches()} to generate a list of possible completions.
! 1682: It then either lists the possible completions, inserts the possible
! 1683: completions, or actually performs the
! 1684: completion, depending on which behavior is desired.
! 1685:
! 1686: @item
! 1687: The internal function @code{rl_completion_matches()} uses an
! 1688: application-supplied @dfn{generator} function to generate the list of
! 1689: possible matches, and then returns the array of these matches.
! 1690: The caller should place the address of its generator function in
! 1691: @code{rl_completion_entry_function}.
! 1692:
! 1693: @item
! 1694: The generator function is called repeatedly from
! 1695: @code{rl_completion_matches()}, returning a string each time. The
! 1696: arguments to the generator function are @var{text} and @var{state}.
! 1697: @var{text} is the partial word to be completed. @var{state} is zero the
! 1698: first time the function is called, allowing the generator to perform
! 1699: any necessary initialization, and a positive non-zero integer for
! 1700: each subsequent call. The generator function returns
! 1701: @code{(char *)NULL} to inform @code{rl_completion_matches()} that there are
! 1702: no more possibilities left. Usually the generator function computes the
! 1703: list of possible completions when @var{state} is zero, and returns them
! 1704: one at a time on subsequent calls. Each string the generator function
! 1705: returns as a match must be allocated with @code{malloc()}; Readline
! 1706: frees the strings when it has finished with them.
! 1707: Such a generator function is referred to as an
! 1708: @dfn{application-specific completion function}.
! 1709:
! 1710: @end enumerate
! 1711:
! 1712: @deftypefun int rl_complete (int ignore, int invoking_key)
! 1713: Complete the word at or before point. You have supplied the function
! 1714: that does the initial simple matching selection algorithm (see
! 1715: @code{rl_completion_matches()}). The default is to do filename completion.
! 1716: @end deftypefun
! 1717:
! 1718: @deftypevar {rl_compentry_func_t *} rl_completion_entry_function
! 1719: This is a pointer to the generator function for
! 1720: @code{rl_completion_matches()}.
! 1721: If the value of @code{rl_completion_entry_function} is
! 1722: @code{NULL} then the default filename generator
! 1723: function, @code{rl_filename_completion_function()}, is used.
! 1724: An @dfn{application-specific completion function} is a function whose
! 1725: address is assigned to @code{rl_completion_entry_function} and whose
! 1726: return values are used to generate possible completions.
! 1727: @end deftypevar
! 1728:
! 1729: @node Completion Functions
! 1730: @subsection Completion Functions
! 1731:
! 1732: Here is the complete list of callable completion functions present in
! 1733: Readline.
! 1734:
! 1735: @deftypefun int rl_complete_internal (int what_to_do)
! 1736: Complete the word at or before point. @var{what_to_do} says what to do
! 1737: with the completion. A value of @samp{?} means list the possible
! 1738: completions. @samp{TAB} means do standard completion. @samp{*} means
! 1739: insert all of the possible completions. @samp{!} means to display
! 1740: all of the possible completions, if there is more than one, as well as
! 1741: performing partial completion. @samp{@@} is similar to @samp{!}, but
! 1742: possible completions are not listed if the possible completions share
! 1743: a common prefix.
! 1744: @end deftypefun
! 1745:
! 1746: @deftypefun int rl_complete (int ignore, int invoking_key)
! 1747: Complete the word at or before point. You have supplied the function
! 1748: that does the initial simple matching selection algorithm (see
! 1749: @code{rl_completion_matches()} and @code{rl_completion_entry_function}).
! 1750: The default is to do filename
! 1751: completion. This calls @code{rl_complete_internal()} with an
! 1752: argument depending on @var{invoking_key}.
! 1753: @end deftypefun
! 1754:
! 1755: @deftypefun int rl_possible_completions (int count, int invoking_key)
! 1756: List the possible completions. See description of @code{rl_complete
! 1757: ()}. This calls @code{rl_complete_internal()} with an argument of
! 1758: @samp{?}.
! 1759: @end deftypefun
! 1760:
! 1761: @deftypefun int rl_insert_completions (int count, int invoking_key)
! 1762: Insert the list of possible completions into the line, deleting the
! 1763: partially-completed word. See description of @code{rl_complete()}.
! 1764: This calls @code{rl_complete_internal()} with an argument of @samp{*}.
! 1765: @end deftypefun
! 1766:
! 1767: @deftypefun int rl_completion_mode (rl_command_func_t *cfunc)
! 1768: Returns the appropriate value to pass to @code{rl_complete_internal()}
! 1769: depending on whether @var{cfunc} was called twice in succession and
! 1770: the values of the @code{show-all-if-ambiguous} and
! 1771: @code{show-all-if-unmodified} variables.
! 1772: Application-specific completion functions may use this function to present
! 1773: the same interface as @code{rl_complete()}.
! 1774: @end deftypefun
! 1775:
! 1776: @deftypefun {char **} rl_completion_matches (const char *text, rl_compentry_func_t *entry_func)
! 1777: Returns an array of strings which is a list of completions for
! 1778: @var{text}. If there are no completions, returns @code{NULL}.
! 1779: The first entry in the returned array is the substitution for @var{text}.
! 1780: The remaining entries are the possible completions. The array is
! 1781: terminated with a @code{NULL} pointer.
! 1782:
! 1783: @var{entry_func} is a function of two args, and returns a
! 1784: @code{char *}. The first argument is @var{text}. The second is a
! 1785: state argument; it is zero on the first call, and non-zero on subsequent
! 1786: calls. @var{entry_func} returns a @code{NULL} pointer to the caller
! 1787: when there are no more matches.
! 1788: @end deftypefun
! 1789:
! 1790: @deftypefun {char *} rl_filename_completion_function (const char *text, int state)
! 1791: A generator function for filename completion in the general case.
! 1792: @var{text} is a partial filename.
! 1793: The Bash source is a useful reference for writing application-specific
! 1794: completion functions (the Bash completion functions call this and other
! 1795: Readline functions).
! 1796: @end deftypefun
! 1797:
! 1798: @deftypefun {char *} rl_username_completion_function (const char *text, int state)
! 1799: A completion generator for usernames. @var{text} contains a partial
! 1800: username preceded by a random character (usually @samp{~}). As with all
! 1801: completion generators, @var{state} is zero on the first call and non-zero
! 1802: for subsequent calls.
! 1803: @end deftypefun
! 1804:
! 1805: @node Completion Variables
! 1806: @subsection Completion Variables
! 1807:
! 1808: @deftypevar {rl_compentry_func_t *} rl_completion_entry_function
! 1809: A pointer to the generator function for @code{rl_completion_matches()}.
! 1810: @code{NULL} means to use @code{rl_filename_completion_function()},
! 1811: the default filename completer.
! 1812: @end deftypevar
! 1813:
! 1814: @deftypevar {rl_completion_func_t *} rl_attempted_completion_function
! 1815: A pointer to an alternative function to create matches.
! 1816: The function is called with @var{text}, @var{start}, and @var{end}.
! 1817: @var{start} and @var{end} are indices in @code{rl_line_buffer} defining
! 1818: the boundaries of @var{text}, which is a character string.
! 1819: If this function exists and returns @code{NULL}, or if this variable is
! 1820: set to @code{NULL}, then @code{rl_complete()} will call the value of
! 1821: @code{rl_completion_entry_function} to generate matches, otherwise the
! 1822: array of strings returned will be used.
! 1823: If this function sets the @code{rl_attempted_completion_over}
! 1824: variable to a non-zero value, Readline will not perform its default
! 1825: completion even if this function returns no matches.
! 1826: @end deftypevar
! 1827:
! 1828: @deftypevar {rl_quote_func_t *} rl_filename_quoting_function
! 1829: A pointer to a function that will quote a filename in an
! 1830: application-specific fashion. This is called if filename completion is being
! 1831: attempted and one of the characters in @code{rl_filename_quote_characters}
! 1832: appears in a completed filename. The function is called with
! 1833: @var{text}, @var{match_type}, and @var{quote_pointer}. The @var{text}
! 1834: is the filename to be quoted. The @var{match_type} is either
! 1835: @code{SINGLE_MATCH}, if there is only one completion match, or
! 1836: @code{MULT_MATCH}. Some functions use this to decide whether or not to
! 1837: insert a closing quote character. The @var{quote_pointer} is a pointer
! 1838: to any opening quote character the user typed. Some functions choose
! 1839: to reset this character.
! 1840: @end deftypevar
! 1841:
! 1842: @deftypevar {rl_dequote_func_t *} rl_filename_dequoting_function
! 1843: A pointer to a function that will remove application-specific quoting
! 1844: characters from a filename before completion is attempted, so those
! 1845: characters do not interfere with matching the text against names in
! 1846: the filesystem. It is called with @var{text}, the text of the word
! 1847: to be dequoted, and @var{quote_char}, which is the quoting character
! 1848: that delimits the filename (usually @samp{'} or @samp{"}). If
! 1849: @var{quote_char} is zero, the filename was not in an embedded string.
! 1850: @end deftypevar
! 1851:
! 1852: @deftypevar {rl_linebuf_func_t *} rl_char_is_quoted_p
! 1853: A pointer to a function to call that determines whether or not a specific
! 1854: character in the line buffer is quoted, according to whatever quoting
! 1855: mechanism the program calling Readline uses. The function is called with
! 1856: two arguments: @var{text}, the text of the line, and @var{index}, the
! 1857: index of the character in the line. It is used to decide whether a
! 1858: character found in @code{rl_completer_word_break_characters} should be
! 1859: used to break words for the completer.
! 1860: @end deftypevar
! 1861:
! 1862: @deftypevar {rl_compignore_func_t *} rl_ignore_some_completions_function
! 1863: This function, if defined, is called by the completer when real filename
! 1864: completion is done, after all the matching names have been generated.
! 1865: It is passed a @code{NULL} terminated array of matches.
! 1866: The first element (@code{matches[0]}) is the
! 1867: maximal substring common to all matches. This function can
! 1868: re-arrange the list of matches as required, but each element deleted
! 1869: from the array must be freed.
! 1870: @end deftypevar
! 1871:
! 1872: @deftypevar {rl_icppfunc_t *} rl_directory_completion_hook
! 1873: This function, if defined, is allowed to modify the directory portion
! 1874: of filenames Readline completes.
! 1875: It could be used to expand symbolic links or shell variables in pathnames.
! 1876: It is called with the address of a string (the current directory name) as an
! 1877: argument, and may modify that string.
! 1878: If the string is replaced with a new string, the old value should be freed.
! 1879: Any modified directory name should have a trailing slash.
! 1880: The modified value will be used as part of the completion, replacing
! 1881: the directory portion of the pathname the user typed.
! 1882: At the least, even if no other expansion is performed, this function should
! 1883: remove any quote characters from the directory name, because its result will
! 1884: be passed directly to @code{opendir()}.
! 1885:
! 1886: The directory completion hook returns an integer that should be non-zero if
! 1887: the function modifies its directory argument.
! 1888: The function should not modify the directory argument if it returns 0.
! 1889: @end deftypevar
! 1890:
! 1891: @deftypevar {rl_icppfunc_t *} rl_directory_rewrite_hook;
! 1892: If non-zero, this is the address of a function to call when completing
! 1893: a directory name. This function takes the address of the directory name
! 1894: to be modified as an argument. Unlike @code{rl_directory_completion_hook},
! 1895: it only modifies the directory name used in @code{opendir}, not what is
! 1896: displayed when the possible completions are printed or inserted. It is
! 1897: called before rl_directory_completion_hook.
! 1898: At the least, even if no other expansion is performed, this function should
! 1899: remove any quote characters from the directory name, because its result will
! 1900: be passed directly to @code{opendir()}.
! 1901:
! 1902: The directory rewrite hook returns an integer that should be non-zero if
! 1903: the function modfies its directory argument.
! 1904: The function should not modify the directory argument if it returns 0.
! 1905: @end deftypevar
! 1906:
! 1907: @deftypevar {rl_icppfunc_t *} rl_filename_stat_hook
! 1908: If non-zero, this is the address of a function for the completer to
! 1909: call before deciding which character to append to a completed name.
! 1910: This function modifies its filename name argument, and the modified value
! 1911: is passed to @code{stat()} to determine the file's type and characteristics.
! 1912: This function does not need to remove quote characters from the filename.
! 1913:
! 1914: The stat hook returns an integer that should be non-zero if
! 1915: the function modfies its directory argument.
! 1916: The function should not modify the directory argument if it returns 0.
! 1917: @end deftypevar
! 1918:
! 1919: @deftypevar {rl_dequote_func_t *} rl_filename_rewrite_hook
! 1920: If non-zero, this is the address of a function called when reading
! 1921: directory entries from the filesystem for completion and comparing
! 1922: them to the partial word to be completed. The function should
! 1923: perform any necessary application or system-specific conversion on
! 1924: the filename, such as converting between character sets or converting
! 1925: from a filesystem format to a character input format.
! 1926: The function takes two arguments: @var{fname}, the filename to be converted,
! 1927: and @var{fnlen}, its length in bytes.
! 1928: It must either return its first argument (if no conversion takes place)
! 1929: or the converted filename in newly-allocated memory. The converted
! 1930: form is used to compare against the word to be completed, and, if it
! 1931: matches, is added to the list of matches. Readline will free the
! 1932: allocated string.
! 1933: @end deftypevar
! 1934:
! 1935: @deftypevar {rl_compdisp_func_t *} rl_completion_display_matches_hook
! 1936: If non-zero, then this is the address of a function to call when
! 1937: completing a word would normally display the list of possible matches.
! 1938: This function is called in lieu of Readline displaying the list.
! 1939: It takes three arguments:
! 1940: (@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length})
! 1941: where @var{matches} is the array of matching strings,
! 1942: @var{num_matches} is the number of strings in that array, and
! 1943: @var{max_length} is the length of the longest string in that array.
! 1944: Readline provides a convenience function, @code{rl_display_match_list},
! 1945: that takes care of doing the display to Readline's output stream. That
! 1946: function may be called from this hook.
! 1947: @end deftypevar
! 1948:
! 1949: @deftypevar {const char *} rl_basic_word_break_characters
! 1950: The basic list of characters that signal a break between words for the
! 1951: completer routine. The default value of this variable is the characters
! 1952: which break words for completion in Bash:
! 1953: @code{" \t\n\"\\'`@@$><=;|&@{("}.
! 1954: @end deftypevar
! 1955:
! 1956: @deftypevar {const char *} rl_basic_quote_characters
! 1957: A list of quote characters which can cause a word break.
! 1958: @end deftypevar
! 1959:
! 1960: @deftypevar {const char *} rl_completer_word_break_characters
! 1961: The list of characters that signal a break between words for
! 1962: @code{rl_complete_internal()}. The default list is the value of
! 1963: @code{rl_basic_word_break_characters}.
! 1964: @end deftypevar
! 1965:
! 1966: @deftypevar {rl_cpvfunc_t *} rl_completion_word_break_hook
! 1967: If non-zero, this is the address of a function to call when Readline is
! 1968: deciding where to separate words for word completion. It should return
! 1969: a character string like @code{rl_completer_word_break_characters} to be
! 1970: used to perform the current completion. The function may choose to set
! 1971: @code{rl_completer_word_break_characters} itself. If the function
! 1972: returns @code{NULL}, @code{rl_completer_word_break_characters} is used.
! 1973: @end deftypevar
! 1974:
! 1975: @deftypevar {const char *} rl_completer_quote_characters
! 1976: A list of characters which can be used to quote a substring of the line.
! 1977: Completion occurs on the entire substring, and within the substring
! 1978: @code{rl_completer_word_break_characters} are treated as any other character,
! 1979: unless they also appear within this list.
! 1980: @end deftypevar
! 1981:
! 1982: @deftypevar {const char *} rl_filename_quote_characters
! 1983: A list of characters that cause a filename to be quoted by the completer
! 1984: when they appear in a completed filename. The default is the null string.
! 1985: @end deftypevar
! 1986:
! 1987: @deftypevar {const char *} rl_special_prefixes
! 1988: The list of characters that are word break characters, but should be
! 1989: left in @var{text} when it is passed to the completion function.
! 1990: Programs can use this to help determine what kind of completing to do.
! 1991: For instance, Bash sets this variable to "$@@" so that it can complete
! 1992: shell variables and hostnames.
! 1993: @end deftypevar
! 1994:
! 1995: @deftypevar int rl_completion_query_items
! 1996: Up to this many items will be displayed in response to a
! 1997: possible-completions call. After that, readline asks the user if she is sure
! 1998: she wants to see them all. The default value is 100. A negative value
! 1999: indicates that Readline should never ask the user.
! 2000: @end deftypevar
! 2001:
! 2002: @deftypevar {int} rl_completion_append_character
! 2003: When a single completion alternative matches at the end of the command
! 2004: line, this character is appended to the inserted completion text. The
! 2005: default is a space character (@samp{ }). Setting this to the null
! 2006: character (@samp{\0}) prevents anything being appended automatically.
! 2007: This can be changed in application-specific completion functions to
! 2008: provide the ``most sensible word separator character'' according to
! 2009: an application-specific command line syntax specification.
! 2010: @end deftypevar
! 2011:
! 2012: @deftypevar int rl_completion_suppress_append
! 2013: If non-zero, @var{rl_completion_append_character} is not appended to
! 2014: matches at the end of the command line, as described above.
! 2015: It is set to 0 before any application-specific completion function
! 2016: is called, and may only be changed within such a function.
! 2017: @end deftypevar
! 2018:
! 2019: @deftypevar int rl_completion_quote_character
! 2020: When Readline is completing quoted text, as delimited by one of the
! 2021: characters in @var{rl_completer_quote_characters}, it sets this variable
! 2022: to the quoting character found.
! 2023: This is set before any application-specific completion function is called.
! 2024: @end deftypevar
! 2025:
! 2026: @deftypevar int rl_completion_suppress_quote
! 2027: If non-zero, Readline does not append a matching quote character when
! 2028: performing completion on a quoted string.
! 2029: It is set to 0 before any application-specific completion function
! 2030: is called, and may only be changed within such a function.
! 2031: @end deftypevar
! 2032:
! 2033: @deftypevar int rl_completion_found_quote
! 2034: When Readline is completing quoted text, it sets this variable
! 2035: to a non-zero value if the word being completed contains or is delimited
! 2036: by any quoting characters, including backslashes.
! 2037: This is set before any application-specific completion function is called.
! 2038: @end deftypevar
! 2039:
! 2040: @deftypevar int rl_completion_mark_symlink_dirs
! 2041: If non-zero, a slash will be appended to completed filenames that are
! 2042: symbolic links to directory names, subject to the value of the
! 2043: user-settable @var{mark-directories} variable.
! 2044: This variable exists so that application-specific completion functions
! 2045: can override the user's global preference (set via the
! 2046: @var{mark-symlinked-directories} Readline variable) if appropriate.
! 2047: This variable is set to the user's preference before any
! 2048: application-specific completion function is called, so unless that
! 2049: function modifies the value, the user's preferences are honored.
! 2050: @end deftypevar
! 2051:
! 2052: @deftypevar int rl_ignore_completion_duplicates
! 2053: If non-zero, then duplicates in the matches are removed.
! 2054: The default is 1.
! 2055: @end deftypevar
! 2056:
! 2057: @deftypevar int rl_filename_completion_desired
! 2058: Non-zero means that the results of the matches are to be treated as
! 2059: filenames. This is @emph{always} zero when completion is attempted,
! 2060: and can only be changed
! 2061: within an application-specific completion function. If it is set to a
! 2062: non-zero value by such a function, directory names have a slash appended
! 2063: and Readline attempts to quote completed filenames if they contain any
! 2064: characters in @code{rl_filename_quote_characters} and
! 2065: @code{rl_filename_quoting_desired} is set to a non-zero value.
! 2066: @end deftypevar
! 2067:
! 2068: @deftypevar int rl_filename_quoting_desired
! 2069: Non-zero means that the results of the matches are to be quoted using
! 2070: double quotes (or an application-specific quoting mechanism) if the
! 2071: completed filename contains any characters in
! 2072: @code{rl_filename_quote_chars}. This is @emph{always} non-zero
! 2073: when completion is attempted, and can only be changed within an
! 2074: application-specific completion function.
! 2075: The quoting is effected via a call to the function pointed to
! 2076: by @code{rl_filename_quoting_function}.
! 2077: @end deftypevar
! 2078:
! 2079: @deftypevar int rl_attempted_completion_over
! 2080: If an application-specific completion function assigned to
! 2081: @code{rl_attempted_completion_function} sets this variable to a non-zero
! 2082: value, Readline will not perform its default filename completion even
! 2083: if the application's completion function returns no matches.
! 2084: It should be set only by an application's completion function.
! 2085: @end deftypevar
! 2086:
! 2087: @deftypevar int rl_sort_completion_matches
! 2088: If an application sets this variable to 0, Readline will not sort the
! 2089: list of completions (which implies that it cannot remove any duplicate
! 2090: completions). The default value is 1, which means that Readline will
! 2091: sort the completions and, depending on the value of
! 2092: @code{rl_ignore_completion_duplicates}, will attempt to remove duplicate
! 2093: matches.
! 2094: @end deftypevar
! 2095:
! 2096: @deftypevar int rl_completion_type
! 2097: Set to a character describing the type of completion Readline is currently
! 2098: attempting; see the description of @code{rl_complete_internal()}
! 2099: (@pxref{Completion Functions}) for the list of characters.
! 2100: This is set to the appropriate value before any application-specific
! 2101: completion function is called, allowing such functions to present
! 2102: the same interface as @code{rl_complete()}.
! 2103: @end deftypevar
! 2104:
! 2105: @deftypevar int rl_completion_invoking_key
! 2106: Set to the final character in the key sequence that invoked one of the
! 2107: completion functions that call @code{rl_complete_internal()}. This is
! 2108: set to the appropriate value before any application-specific completion
! 2109: function is called.
! 2110: @end deftypevar
! 2111:
! 2112: @deftypevar int rl_inhibit_completion
! 2113: If this variable is non-zero, completion is inhibited. The completion
! 2114: character will be inserted as any other bound to @code{self-insert}.
! 2115: @end deftypevar
! 2116:
! 2117: @node A Short Completion Example
! 2118: @subsection A Short Completion Example
! 2119:
! 2120: Here is a small application demonstrating the use of the GNU Readline
! 2121: library. It is called @code{fileman}, and the source code resides in
! 2122: @file{examples/fileman.c}. This sample application provides
! 2123: completion of command names, line editing features, and access to the
! 2124: history list.
! 2125:
! 2126: @page
! 2127: @smallexample
! 2128: /* fileman.c -- A tiny application which demonstrates how to use the
! 2129: GNU Readline library. This application interactively allows users
! 2130: to manipulate files and their modes. */
! 2131:
! 2132: #ifdef HAVE_CONFIG_H
! 2133: # include <config.h>
! 2134: #endif
! 2135:
! 2136: #include <sys/types.h>
! 2137: #ifdef HAVE_SYS_FILE_H
! 2138: # include <sys/file.h>
! 2139: #endif
! 2140: #include <sys/stat.h>
! 2141:
! 2142: #ifdef HAVE_UNISTD_H
! 2143: # include <unistd.h>
! 2144: #endif
! 2145:
! 2146: #include <fcntl.h>
! 2147: #include <stdio.h>
! 2148: #include <errno.h>
! 2149:
! 2150: #if defined (HAVE_STRING_H)
! 2151: # include <string.h>
! 2152: #else /* !HAVE_STRING_H */
! 2153: # include <strings.h>
! 2154: #endif /* !HAVE_STRING_H */
! 2155:
! 2156: #ifdef HAVE_STDLIB_H
! 2157: # include <stdlib.h>
! 2158: #endif
! 2159:
! 2160: #include <time.h>
! 2161:
! 2162: #include <readline/readline.h>
! 2163: #include <readline/history.h>
! 2164:
! 2165: extern char *xmalloc PARAMS((size_t));
! 2166:
! 2167: /* The names of functions that actually do the manipulation. */
! 2168: int com_list PARAMS((char *));
! 2169: int com_view PARAMS((char *));
! 2170: int com_rename PARAMS((char *));
! 2171: int com_stat PARAMS((char *));
! 2172: int com_pwd PARAMS((char *));
! 2173: int com_delete PARAMS((char *));
! 2174: int com_help PARAMS((char *));
! 2175: int com_cd PARAMS((char *));
! 2176: int com_quit PARAMS((char *));
! 2177:
! 2178: /* A structure which contains information on the commands this program
! 2179: can understand. */
! 2180:
! 2181: typedef struct @{
! 2182: char *name; /* User printable name of the function. */
! 2183: rl_icpfunc_t *func; /* Function to call to do the job. */
! 2184: char *doc; /* Documentation for this function. */
! 2185: @} COMMAND;
! 2186:
! 2187: COMMAND commands[] = @{
! 2188: @{ "cd", com_cd, "Change to directory DIR" @},
! 2189: @{ "delete", com_delete, "Delete FILE" @},
! 2190: @{ "help", com_help, "Display this text" @},
! 2191: @{ "?", com_help, "Synonym for `help'" @},
! 2192: @{ "list", com_list, "List files in DIR" @},
! 2193: @{ "ls", com_list, "Synonym for `list'" @},
! 2194: @{ "pwd", com_pwd, "Print the current working directory" @},
! 2195: @{ "quit", com_quit, "Quit using Fileman" @},
! 2196: @{ "rename", com_rename, "Rename FILE to NEWNAME" @},
! 2197: @{ "stat", com_stat, "Print out statistics on FILE" @},
! 2198: @{ "view", com_view, "View the contents of FILE" @},
! 2199: @{ (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL @}
! 2200: @};
! 2201:
! 2202: /* Forward declarations. */
! 2203: char *stripwhite ();
! 2204: COMMAND *find_command ();
! 2205:
! 2206: /* The name of this program, as taken from argv[0]. */
! 2207: char *progname;
! 2208:
! 2209: /* When non-zero, this global means the user is done using this program. */
! 2210: int done;
! 2211:
! 2212: char *
! 2213: dupstr (s)
! 2214: char *s;
! 2215: @{
! 2216: char *r;
! 2217:
! 2218: r = xmalloc (strlen (s) + 1);
! 2219: strcpy (r, s);
! 2220: return (r);
! 2221: @}
! 2222:
! 2223: main (argc, argv)
! 2224: int argc;
! 2225: char **argv;
! 2226: @{
! 2227: char *line, *s;
! 2228:
! 2229: progname = argv[0];
! 2230:
! 2231: initialize_readline (); /* Bind our completer. */
! 2232:
! 2233: /* Loop reading and executing lines until the user quits. */
! 2234: for ( ; done == 0; )
! 2235: @{
! 2236: line = readline ("FileMan: ");
! 2237:
! 2238: if (!line)
! 2239: break;
! 2240:
! 2241: /* Remove leading and trailing whitespace from the line.
! 2242: Then, if there is anything left, add it to the history list
! 2243: and execute it. */
! 2244: s = stripwhite (line);
! 2245:
! 2246: if (*s)
! 2247: @{
! 2248: add_history (s);
! 2249: execute_line (s);
! 2250: @}
! 2251:
! 2252: free (line);
! 2253: @}
! 2254: exit (0);
! 2255: @}
! 2256:
! 2257: /* Execute a command line. */
! 2258: int
! 2259: execute_line (line)
! 2260: char *line;
! 2261: @{
! 2262: register int i;
! 2263: COMMAND *command;
! 2264: char *word;
! 2265:
! 2266: /* Isolate the command word. */
! 2267: i = 0;
! 2268: while (line[i] && whitespace (line[i]))
! 2269: i++;
! 2270: word = line + i;
! 2271:
! 2272: while (line[i] && !whitespace (line[i]))
! 2273: i++;
! 2274:
! 2275: if (line[i])
! 2276: line[i++] = '\0';
! 2277:
! 2278: command = find_command (word);
! 2279:
! 2280: if (!command)
! 2281: @{
! 2282: fprintf (stderr, "%s: No such command for FileMan.\n", word);
! 2283: return (-1);
! 2284: @}
! 2285:
! 2286: /* Get argument to command, if any. */
! 2287: while (whitespace (line[i]))
! 2288: i++;
! 2289:
! 2290: word = line + i;
! 2291:
! 2292: /* Call the function. */
! 2293: return ((*(command->func)) (word));
! 2294: @}
! 2295:
! 2296: /* Look up NAME as the name of a command, and return a pointer to that
! 2297: command. Return a NULL pointer if NAME isn't a command name. */
! 2298: COMMAND *
! 2299: find_command (name)
! 2300: char *name;
! 2301: @{
! 2302: register int i;
! 2303:
! 2304: for (i = 0; commands[i].name; i++)
! 2305: if (strcmp (name, commands[i].name) == 0)
! 2306: return (&commands[i]);
! 2307:
! 2308: return ((COMMAND *)NULL);
! 2309: @}
! 2310:
! 2311: /* Strip whitespace from the start and end of STRING. Return a pointer
! 2312: into STRING. */
! 2313: char *
! 2314: stripwhite (string)
! 2315: char *string;
! 2316: @{
! 2317: register char *s, *t;
! 2318:
! 2319: for (s = string; whitespace (*s); s++)
! 2320: ;
! 2321:
! 2322: if (*s == 0)
! 2323: return (s);
! 2324:
! 2325: t = s + strlen (s) - 1;
! 2326: while (t > s && whitespace (*t))
! 2327: t--;
! 2328: *++t = '\0';
! 2329:
! 2330: return s;
! 2331: @}
! 2332:
! 2333: /* **************************************************************** */
! 2334: /* */
! 2335: /* Interface to Readline Completion */
! 2336: /* */
! 2337: /* **************************************************************** */
! 2338:
! 2339: char *command_generator PARAMS((const char *, int));
! 2340: char **fileman_completion PARAMS((const char *, int, int));
! 2341:
! 2342: /* Tell the GNU Readline library how to complete. We want to try to complete
! 2343: on command names if this is the first word in the line, or on filenames
! 2344: if not. */
! 2345: initialize_readline ()
! 2346: @{
! 2347: /* Allow conditional parsing of the ~/.inputrc file. */
! 2348: rl_readline_name = "FileMan";
! 2349:
! 2350: /* Tell the completer that we want a crack first. */
! 2351: rl_attempted_completion_function = fileman_completion;
! 2352: @}
! 2353:
! 2354: /* Attempt to complete on the contents of TEXT. START and END bound the
! 2355: region of rl_line_buffer that contains the word to complete. TEXT is
! 2356: the word to complete. We can use the entire contents of rl_line_buffer
! 2357: in case we want to do some simple parsing. Return the array of matches,
! 2358: or NULL if there aren't any. */
! 2359: char **
! 2360: fileman_completion (text, start, end)
! 2361: const char *text;
! 2362: int start, end;
! 2363: @{
! 2364: char **matches;
! 2365:
! 2366: matches = (char **)NULL;
! 2367:
! 2368: /* If this word is at the start of the line, then it is a command
! 2369: to complete. Otherwise it is the name of a file in the current
! 2370: directory. */
! 2371: if (start == 0)
! 2372: matches = rl_completion_matches (text, command_generator);
! 2373:
! 2374: return (matches);
! 2375: @}
! 2376:
! 2377: /* Generator function for command completion. STATE lets us know whether
! 2378: to start from scratch; without any state (i.e. STATE == 0), then we
! 2379: start at the top of the list. */
! 2380: char *
! 2381: command_generator (text, state)
! 2382: const char *text;
! 2383: int state;
! 2384: @{
! 2385: static int list_index, len;
! 2386: char *name;
! 2387:
! 2388: /* If this is a new word to complete, initialize now. This includes
! 2389: saving the length of TEXT for efficiency, and initializing the index
! 2390: variable to 0. */
! 2391: if (!state)
! 2392: @{
! 2393: list_index = 0;
! 2394: len = strlen (text);
! 2395: @}
! 2396:
! 2397: /* Return the next name which partially matches from the command list. */
! 2398: while (name = commands[list_index].name)
! 2399: @{
! 2400: list_index++;
! 2401:
! 2402: if (strncmp (name, text, len) == 0)
! 2403: return (dupstr(name));
! 2404: @}
! 2405:
! 2406: /* If no names matched, then return NULL. */
! 2407: return ((char *)NULL);
! 2408: @}
! 2409:
! 2410: /* **************************************************************** */
! 2411: /* */
! 2412: /* FileMan Commands */
! 2413: /* */
! 2414: /* **************************************************************** */
! 2415:
! 2416: /* String to pass to system (). This is for the LIST, VIEW and RENAME
! 2417: commands. */
! 2418: static char syscom[1024];
! 2419:
! 2420: /* List the file(s) named in arg. */
! 2421: com_list (arg)
! 2422: char *arg;
! 2423: @{
! 2424: if (!arg)
! 2425: arg = "";
! 2426:
! 2427: sprintf (syscom, "ls -FClg %s", arg);
! 2428: return (system (syscom));
! 2429: @}
! 2430:
! 2431: com_view (arg)
! 2432: char *arg;
! 2433: @{
! 2434: if (!valid_argument ("view", arg))
! 2435: return 1;
! 2436:
! 2437: #if defined (__MSDOS__)
! 2438: /* more.com doesn't grok slashes in pathnames */
! 2439: sprintf (syscom, "less %s", arg);
! 2440: #else
! 2441: sprintf (syscom, "more %s", arg);
! 2442: #endif
! 2443: return (system (syscom));
! 2444: @}
! 2445:
! 2446: com_rename (arg)
! 2447: char *arg;
! 2448: @{
! 2449: too_dangerous ("rename");
! 2450: return (1);
! 2451: @}
! 2452:
! 2453: com_stat (arg)
! 2454: char *arg;
! 2455: @{
! 2456: struct stat finfo;
! 2457:
! 2458: if (!valid_argument ("stat", arg))
! 2459: return (1);
! 2460:
! 2461: if (stat (arg, &finfo) == -1)
! 2462: @{
! 2463: perror (arg);
! 2464: return (1);
! 2465: @}
! 2466:
! 2467: printf ("Statistics for `%s':\n", arg);
! 2468:
! 2469: printf ("%s has %d link%s, and is %d byte%s in length.\n",
! 2470: arg,
! 2471: finfo.st_nlink,
! 2472: (finfo.st_nlink == 1) ? "" : "s",
! 2473: finfo.st_size,
! 2474: (finfo.st_size == 1) ? "" : "s");
! 2475: printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
! 2476: printf (" Last access at: %s", ctime (&finfo.st_atime));
! 2477: printf (" Last modified at: %s", ctime (&finfo.st_mtime));
! 2478: return (0);
! 2479: @}
! 2480:
! 2481: com_delete (arg)
! 2482: char *arg;
! 2483: @{
! 2484: too_dangerous ("delete");
! 2485: return (1);
! 2486: @}
! 2487:
! 2488: /* Print out help for ARG, or for all of the commands if ARG is
! 2489: not present. */
! 2490: com_help (arg)
! 2491: char *arg;
! 2492: @{
! 2493: register int i;
! 2494: int printed = 0;
! 2495:
! 2496: for (i = 0; commands[i].name; i++)
! 2497: @{
! 2498: if (!*arg || (strcmp (arg, commands[i].name) == 0))
! 2499: @{
! 2500: printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
! 2501: printed++;
! 2502: @}
! 2503: @}
! 2504:
! 2505: if (!printed)
! 2506: @{
! 2507: printf ("No commands match `%s'. Possibilties are:\n", arg);
! 2508:
! 2509: for (i = 0; commands[i].name; i++)
! 2510: @{
! 2511: /* Print in six columns. */
! 2512: if (printed == 6)
! 2513: @{
! 2514: printed = 0;
! 2515: printf ("\n");
! 2516: @}
! 2517:
! 2518: printf ("%s\t", commands[i].name);
! 2519: printed++;
! 2520: @}
! 2521:
! 2522: if (printed)
! 2523: printf ("\n");
! 2524: @}
! 2525: return (0);
! 2526: @}
! 2527:
! 2528: /* Change to the directory ARG. */
! 2529: com_cd (arg)
! 2530: char *arg;
! 2531: @{
! 2532: if (chdir (arg) == -1)
! 2533: @{
! 2534: perror (arg);
! 2535: return 1;
! 2536: @}
! 2537:
! 2538: com_pwd ("");
! 2539: return (0);
! 2540: @}
! 2541:
! 2542: /* Print out the current working directory. */
! 2543: com_pwd (ignore)
! 2544: char *ignore;
! 2545: @{
! 2546: char dir[1024], *s;
! 2547:
! 2548: s = getcwd (dir, sizeof(dir) - 1);
! 2549: if (s == 0)
! 2550: @{
! 2551: printf ("Error getting pwd: %s\n", dir);
! 2552: return 1;
! 2553: @}
! 2554:
! 2555: printf ("Current directory is %s\n", dir);
! 2556: return 0;
! 2557: @}
! 2558:
! 2559: /* The user wishes to quit using this program. Just set DONE non-zero. */
! 2560: com_quit (arg)
! 2561: char *arg;
! 2562: @{
! 2563: done = 1;
! 2564: return (0);
! 2565: @}
! 2566:
! 2567: /* Function which tells you that you can't do this. */
! 2568: too_dangerous (caller)
! 2569: char *caller;
! 2570: @{
! 2571: fprintf (stderr,
! 2572: "%s: Too dangerous for me to distribute. Write it yourself.\n",
! 2573: caller);
! 2574: @}
! 2575:
! 2576: /* Return non-zero if ARG is a valid argument for CALLER, else print
! 2577: an error message and return zero. */
! 2578: int
! 2579: valid_argument (caller, arg)
! 2580: char *caller, *arg;
! 2581: @{
! 2582: if (!arg || !*arg)
! 2583: @{
! 2584: fprintf (stderr, "%s: Argument required.\n", caller);
! 2585: return (0);
! 2586: @}
! 2587:
! 2588: return (1);
! 2589: @}
! 2590: @end smallexample
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to rltech.texi CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / readline / doc