Return to rltech.texi CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / readline / doc

readline 6.3

    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