readline/doc/readline.html

   1 <HTML>
   2 <HEAD>
   3 <!-- This HTML file has been created by texi2html 1.52
   4      from /usr/homes/chet/src/bash/readline-src/doc/rlman.texinfo on 31 December 1998 -->
   5
   6 <TITLE>GNU Readline Library</TITLE>
   7 </HEAD>
   8 <BODY>
   9 <H1>GNU Readline Library</H1>
  10 <H2>Edition 4.0, for <CODE>Readline Library</CODE> Version 4.0.</H2>
  11 <H2>December 1998</H2>
  12 <ADDRESS>Brian Fox, Free Software Foundation</ADDRESS>
  13 <ADDRESS>Chet Ramey, Case Western Reserve University</ADDRESS>
  14 <P>
  15 <P><HR><P>
  16 <H1>Table of Contents</H1>
  17 <UL>
  18 <LI><A NAME="TOC1" HREF="readline.html#SEC1">Command Line Editing</A>
  19 <UL>
  20 <LI><A NAME="TOC2" HREF="readline.html#SEC2">Introduction to Line Editing</A>
  21 <LI><A NAME="TOC3" HREF="readline.html#SEC3">Readline Interaction</A>
  22 <UL>
  23 <LI><A NAME="TOC4" HREF="readline.html#SEC4">Readline Bare Essentials</A>
  24 <LI><A NAME="TOC5" HREF="readline.html#SEC5">Readline Movement Commands</A>
  25 <LI><A NAME="TOC6" HREF="readline.html#SEC6">Readline Killing Commands</A>
  26 <LI><A NAME="TOC7" HREF="readline.html#SEC7">Readline Arguments</A>
  27 <LI><A NAME="TOC8" HREF="readline.html#SEC8">Searching for Commands in the History</A>
  28 </UL>
  29 <LI><A NAME="TOC9" HREF="readline.html#SEC9">Readline Init File</A>
  30 <UL>
  31 <LI><A NAME="TOC10" HREF="readline.html#SEC10">Readline Init File Syntax</A>
  32 <LI><A NAME="TOC11" HREF="readline.html#SEC11">Conditional Init Constructs</A>
  33 <LI><A NAME="TOC12" HREF="readline.html#SEC12">Sample Init File</A>
  34 </UL>
  35 <LI><A NAME="TOC13" HREF="readline.html#SEC13">Bindable Readline Commands</A>
  36 <UL>
  37 <LI><A NAME="TOC14" HREF="readline.html#SEC14">Commands For Moving</A>
  38 <LI><A NAME="TOC15" HREF="readline.html#SEC15">Commands For Manipulating The History</A>
  39 <LI><A NAME="TOC16" HREF="readline.html#SEC16">Commands For Changing Text</A>
  40 <LI><A NAME="TOC17" HREF="readline.html#SEC17">Killing And Yanking</A>
  41 <LI><A NAME="TOC18" HREF="readline.html#SEC18">Specifying Numeric Arguments</A>
  42 <LI><A NAME="TOC19" HREF="readline.html#SEC19">Letting Readline Type For You</A>
  43 <LI><A NAME="TOC20" HREF="readline.html#SEC20">Keyboard Macros</A>
  44 <LI><A NAME="TOC21" HREF="readline.html#SEC21">Some Miscellaneous Commands</A>
  45 </UL>
  46 <LI><A NAME="TOC22" HREF="readline.html#SEC22">Readline vi Mode</A>
  47 </UL>
  48 <LI><A NAME="TOC23" HREF="readline.html#SEC23">Programming with GNU Readline</A>
  49 <UL>
  50 <LI><A NAME="TOC24" HREF="readline.html#SEC24">Basic Behavior</A>
  51 <LI><A NAME="TOC25" HREF="readline.html#SEC25">Custom Functions</A>
  52 <UL>
  53 <LI><A NAME="TOC26" HREF="readline.html#SEC26">The Function Type</A>
  54 <LI><A NAME="TOC27" HREF="readline.html#SEC27">Writing a New Function</A>
  55 </UL>
  56 <LI><A NAME="TOC28" HREF="readline.html#SEC28">Readline Variables</A>
  57 <LI><A NAME="TOC29" HREF="readline.html#SEC29">Readline Convenience Functions</A>
  58 <UL>
  59 <LI><A NAME="TOC30" HREF="readline.html#SEC30">Naming a Function</A>
  60 <LI><A NAME="TOC31" HREF="readline.html#SEC31">Selecting a Keymap</A>
  61 <LI><A NAME="TOC32" HREF="readline.html#SEC32">Binding Keys</A>
  62 <LI><A NAME="TOC33" HREF="readline.html#SEC33">Associating Function Names and Bindings</A>
  63 <LI><A NAME="TOC34" HREF="readline.html#SEC34">Allowing Undoing</A>
  64 <LI><A NAME="TOC35" HREF="readline.html#SEC35">Redisplay</A>
  65 <LI><A NAME="TOC36" HREF="readline.html#SEC36">Modifying Text</A>
  66 <LI><A NAME="TOC37" HREF="readline.html#SEC37">Utility Functions</A>
  67 <LI><A NAME="TOC38" HREF="readline.html#SEC38">Alternate Interface</A>
  68 <LI><A NAME="TOC39" HREF="readline.html#SEC39">An Example</A>
  69 </UL>
  70 <LI><A NAME="TOC40" HREF="readline.html#SEC40">Readline Signal Handling</A>
  71 <LI><A NAME="TOC41" HREF="readline.html#SEC41">Custom Completers</A>
  72 <UL>
  73 <LI><A NAME="TOC42" HREF="readline.html#SEC42">How Completing Works</A>
  74 <LI><A NAME="TOC43" HREF="readline.html#SEC43">Completion Functions</A>
  75 <LI><A NAME="TOC44" HREF="readline.html#SEC44">Completion Variables</A>
  76 <LI><A NAME="TOC45" HREF="readline.html#SEC45">A Short Completion Example</A>
  77 </UL>
  78 </UL>
  79 <LI><A NAME="TOC46" HREF="readline.html#SEC46">Concept Index</A>
  80 <LI><A NAME="TOC47" HREF="readline.html#SEC47">Function and Variable Index</A>
  81 </UL>
  82 <P><HR><P>
  83
  84 <P>
  85 This document describes the GNU Readline Library, a utility which aids
  86 in the consistency of user interface across discrete programs that need
  87 to provide a command line interface.
  88
  89 </P>
  90 <P>
  91 Published by the Free Software Foundation <BR>
  92 675 Massachusetts Avenue, <BR>
  93 Cambridge, MA 02139 USA
  94
  95 </P>
  96 <P>
  97 Permission is granted to make and distribute verbatim copies of
  98 this manual provided the copyright notice and this permission notice
  99 are preserved on all copies.
 100
 101 </P>
 102 <P>
 103 Permission is granted to copy and distribute modified versions of this
 104 manual under the conditions for verbatim copying, provided that the entire
 105 resulting derived work is distributed under the terms of a permission
 106 notice identical to this one.
 107
 108 </P>
 109 <P>
 110 Permission is granted to copy and distribute translations of this manual
 111 into another language, under the above conditions for modified versions,
 112 except that this permission notice may be stated in a translation approved
 113 by the Free Software Foundation.
 114
 115 </P>
 116 <P>
 117 Copyright (C) 1988-1999 Free Software Foundation, Inc.
 118
 119 </P>
 120
 121
 122
 123 <H1><A NAME="SEC1" HREF="readline.html#TOC1">Command Line Editing</A></H1>
 124
 125 <P>
 126 This chapter describes the basic features of the GNU
 127 command line editing interface.
 128
 129 </P>
 130
 131 <UL>
 132 <LI><A HREF="readline.html#SEC2">Introduction and Notation</A>: Notation used in this text.
 133 <LI><A HREF="readline.html#SEC3">Readline Interaction</A>: The minimum set of commands for editing a line.
 134 <LI><A HREF="readline.html#SEC9">Readline Init File</A>: Customizing Readline from a user's view.
 135 <LI><A HREF="readline.html#SEC13">Bindable Readline Commands</A>: A description of most of the Readline commands
 136                                 available for binding
 137 <LI><A HREF="readline.html#SEC22">Readline vi Mode</A>: A short description of how to make Readline
 138                                 behave like the vi editor.
 139 </UL>
 140
 141
 142
 143 <H2><A NAME="SEC2" HREF="readline.html#TOC2">Introduction to Line Editing</A></H2>
 144
 145 <P>
 146 The following paragraphs describe the notation used to represent
 147 keystrokes.
 148
 149 </P>
 150 <P>
 151 The text <KBD>C-k</KBD> is read as `Control-K' and describes the character
 152 produced when the <KBD>k</KBD> key is pressed while the Control key
 153 is depressed.
 154
 155 </P>
 156 <P>
 157 The text <KBD>M-k</KBD> is read as `Meta-K' and describes the character
 158 produced when the meta key (if you have one) is depressed, and the <KBD>k</KBD>
 159 key is pressed.  If you do not have a meta key, the identical keystroke
 160 can be generated by typing <KBD>ESC</KBD> <I>first</I>, and then typing <KBD>k</KBD>.
 161 Either process is known as <EM>metafying</EM> the <KBD>k</KBD> key.
 162
 163 </P>
 164 <P>
 165 The text <KBD>M-C-k</KBD> is read as `Meta-Control-k' and describes the
 166 character produced by <EM>metafying</EM> <KBD>C-k</KBD>.
 167
 168 </P>
 169 <P>
 170 In addition, several keys have their own names.  Specifically,
 171 <KBD>DEL</KBD>, <KBD>ESC</KBD>, <KBD>LFD</KBD>, <KBD>SPC</KBD>, <KBD>RET</KBD>, and <KBD>TAB</KBD> all
 172 stand for themselves when seen in this text, or in an init file
 173 (see section <A HREF="readline.html#SEC9">Readline Init File</A>).
 174
 175 </P>
 176
 177
 178 <H2><A NAME="SEC3" HREF="readline.html#TOC3">Readline Interaction</A></H2>
 179 <P>
 180 <A NAME="IDX1"></A>
 181
 182 </P>
 183 <P>
 184 Often during an interactive session you type in a long line of text,
 185 only to notice that the first word on the line is misspelled.  The
 186 Readline library gives you a set of commands for manipulating the text
 187 as you type it in, allowing you to just fix your typo, and not forcing
 188 you to retype the majority of the line.  Using these editing commands,
 189 you move the cursor to the place that needs correction, and delete or
 190 insert the text of the corrections.  Then, when you are satisfied with
 191 the line, you simply press <KBD>RETURN</KBD>.  You do not have to be at the
 192 end of the line to press <KBD>RETURN</KBD>; the entire line is accepted
 193 regardless of the location of the cursor within the line.
 194
 195 </P>
 196
 197 <UL>
 198 <LI><A HREF="readline.html#SEC4">Readline Bare Essentials</A>: The least you need to know about Readline.
 199 <LI><A HREF="readline.html#SEC5">Readline Movement Commands</A>: Moving about the input line.
 200 <LI><A HREF="readline.html#SEC6">Readline Killing Commands</A>: How to delete text, and how to get it back!
 201 <LI><A HREF="readline.html#SEC7">Readline Arguments</A>: Giving numeric arguments to commands.
 202 <LI><A HREF="readline.html#SEC8">Searching</A>: Searching through previous lines.
 203 </UL>
 204
 205
 206
 207 <H3><A NAME="SEC4" HREF="readline.html#TOC4">Readline Bare Essentials</A></H3>
 208 <P>
 209 <A NAME="IDX2"></A>
 210 <A NAME="IDX3"></A>
 211 <A NAME="IDX4"></A>
 212
 213 </P>
 214 <P>
 215 In order to enter characters into the line, simply type them.  The typed
 216 character appears where the cursor was, and then the cursor moves one
 217 space to the right.  If you mistype a character, you can use your
 218 erase character to back up and delete the mistyped character.
 219
 220 </P>
 221 <P>
 222 Sometimes you may miss typing a character that you wanted to type, and
 223 not notice your error until you have typed several other characters.  In
 224 that case, you can type <KBD>C-b</KBD> to move the cursor to the left, and then
 225 correct your mistake.  Afterwards, you can move the cursor to the right
 226 with <KBD>C-f</KBD>.
 227
 228 </P>
 229 <P>
 230 When you add text in the middle of a line, you will notice that characters
 231 to the right of the cursor are `pushed over' to make room for the text
 232 that you have inserted.  Likewise, when you delete text behind the cursor,
 233 characters to the right of the cursor are `pulled back' to fill in the
 234 blank space created by the removal of the text.  A list of the basic bare
 235 essentials for editing the text of an input line follows.
 236
 237 </P>
 238 <DL COMPACT>
 239
 240 <DT><KBD>C-b</KBD>
 241 <DD>
 242 Move back one character.
 243 <DT><KBD>C-f</KBD>
 244 <DD>
 245 Move forward one character.
 246 <DT><KBD>DEL</KBD>
 247 <DD>
 248 Delete the character to the left of the cursor.
 249 <DT><KBD>C-d</KBD>
 250 <DD>
 251 Delete the character underneath the cursor.
 252 <DT>Printing characters
 253 <DD>
 254 Insert the character into the line at the cursor.
 255 <DT><KBD>C-_</KBD>
 256 <DD>
 257 Undo the last editing command.  You can undo all the way back to an
 258 empty line.
 259 </DL>
 260
 261
 262
 263 <H3><A NAME="SEC5" HREF="readline.html#TOC5">Readline Movement Commands</A></H3>
 264
 265 <P>
 266 The above table describes the most basic possible keystrokes that you need
 267 in order to do editing of the input line.  For your convenience, many
 268 other commands have been added in addition to <KBD>C-b</KBD>, <KBD>C-f</KBD>,
 269 <KBD>C-d</KBD>, and <KBD>DEL</KBD>.  Here are some commands for moving more rapidly
 270 about the line.
 271
 272 </P>
 273 <DL COMPACT>
 274
 275 <DT><KBD>C-a</KBD>
 276 <DD>
 277 Move to the start of the line.
 278 <DT><KBD>C-e</KBD>
 279 <DD>
 280 Move to the end of the line.
 281 <DT><KBD>M-f</KBD>
 282 <DD>
 283 Move forward a word, where a word is composed of letters and digits.
 284 <DT><KBD>M-b</KBD>
 285 <DD>
 286 Move backward a word.
 287 <DT><KBD>C-l</KBD>
 288 <DD>
 289 Clear the screen, reprinting the current line at the top.
 290 </DL>
 291
 292 <P>
 293 Notice how <KBD>C-f</KBD> moves forward a character, while <KBD>M-f</KBD> moves
 294 forward a word.  It is a loose convention that control keystrokes
 295 operate on characters while meta keystrokes operate on words.
 296
 297 </P>
 298
 299
 300 <H3><A NAME="SEC6" HREF="readline.html#TOC6">Readline Killing Commands</A></H3>
 301
 302 <P>
 303 <A NAME="IDX5"></A>
 304 <A NAME="IDX6"></A>
 305
 306 </P>
 307 <P>
 308 <EM>Killing</EM> text means to delete the text from the line, but to save
 309 it away for later use, usually by <EM>yanking</EM> (re-inserting)
 310 it back into the line.
 311 If the description for a command says that it `kills' text, then you can
 312 be sure that you can get the text back in a different (or the same)
 313 place later.
 314
 315 </P>
 316 <P>
 317 When you use a kill command, the text is saved in a <EM>kill-ring</EM>.
 318 Any number of consecutive kills save all of the killed text together, so
 319 that when you yank it back, you get it all.  The kill
 320 ring is not line specific; the text that you killed on a previously
 321 typed line is available to be yanked back later, when you are typing
 322 another line.
 323 <A NAME="IDX7"></A>
 324
 325 </P>
 326 <P>
 327 Here is the list of commands for killing text.
 328
 329 </P>
 330 <DL COMPACT>
 331
 332 <DT><KBD>C-k</KBD>
 333 <DD>
 334 Kill the text from the current cursor position to the end of the line.
 335
 336 <DT><KBD>M-d</KBD>
 337 <DD>
 338 Kill from the cursor to the end of the current word, or if between
 339 words, to the end of the next word.
 340
 341 <DT><KBD>M-DEL</KBD>
 342 <DD>
 343 Kill from the cursor the start of the previous word, or if between
 344 words, to the start of the previous word.
 345
 346 <DT><KBD>C-w</KBD>
 347 <DD>
 348 Kill from the cursor to the previous whitespace.  This is different than
 349 <KBD>M-DEL</KBD> because the word boundaries differ.
 350
 351 </DL>
 352
 353 <P>
 354 Here is how to <EM>yank</EM> the text back into the line.  Yanking
 355 means to copy the most-recently-killed text from the kill buffer.
 356
 357 </P>
 358 <DL COMPACT>
 359
 360 <DT><KBD>C-y</KBD>
 361 <DD>
 362 Yank the most recently killed text back into the buffer at the cursor.
 363
 364 <DT><KBD>M-y</KBD>
 365 <DD>
 366 Rotate the kill-ring, and yank the new top.  You can only do this if
 367 the prior command is <KBD>C-y</KBD> or <KBD>M-y</KBD>.
 368 </DL>
 369
 370
 371
 372 <H3><A NAME="SEC7" HREF="readline.html#TOC7">Readline Arguments</A></H3>
 373
 374 <P>
 375 You can pass numeric arguments to Readline commands.  Sometimes the
 376 argument acts as a repeat count, other times it is the <I>sign</I> of the
 377 argument that is significant.  If you pass a negative argument to a
 378 command which normally acts in a forward direction, that command will
 379 act in a backward direction.  For example, to kill text back to the
 380 start of the line, you might type <SAMP>`M-- C-k'</SAMP>.
 381
 382 </P>
 383 <P>
 384 The general way to pass numeric arguments to a command is to type meta
 385 digits before the command.  If the first `digit' typed is a minus
 386 sign (<KBD>-</KBD>), then the sign of the argument will be negative.  Once
 387 you have typed one meta digit to get the argument started, you can type
 388 the remainder of the digits, and then the command.  For example, to give
 389 the <KBD>C-d</KBD> command an argument of 10, you could type <SAMP>`M-1 0 C-d'</SAMP>.
 390
 391 </P>
 392
 393
 394 <H3><A NAME="SEC8" HREF="readline.html#TOC8">Searching for Commands in the History</A></H3>
 395
 396 <P>
 397 Readline provides commands for searching through the command history
 398 for lines containing a specified string.
 399 There are two search modes:  <VAR>incremental</VAR> and <VAR>non-incremental</VAR>.
 400
 401 </P>
 402 <P>
 403 Incremental searches begin before the user has finished typing the
 404 search string.
 405 As each character of the search string is typed, Readline displays
 406 the next entry from the history matching the string typed so far.
 407 An incremental search requires only as many characters as needed to
 408 find the desired history entry.
 409 The characters present in the value of the <VAR>isearch-terminators</VAR> variable
 410 are used to terminate an incremental search.
 411 If that variable has not been assigned a value, the <KBD>ESC</KBD> and
 412 <KBD>C-J</KBD> characters will terminate an incremental search.
 413 <KBD>C-g</KBD> will abort an incremental search and restore the original line.
 414 When the search is terminated, the history entry containing the
 415 search string becomes the current line.
 416 To find other matching entries in the history list, type <KBD>C-s</KBD> or
 417 <KBD>C-r</KBD> as appropriate.
 418 This will search backward or forward in the history for the next
 419 entry matching the search string typed so far.
 420 Any other key sequence bound to a Readline command will terminate
 421 the search and execute that command.
 422 For instance, a <KBD>RET</KBD> will terminate the search and accept
 423 the line, thereby executing the command from the history list.
 424
 425 </P>
 426 <P>
 427 Non-incremental searches read the entire search string before starting
 428 to search for matching history lines.  The search string may be
 429 typed by the user or be part of the contents of the current line.
 430
 431 </P>
 432
 433
 434 <H2><A NAME="SEC9" HREF="readline.html#TOC9">Readline Init File</A></H2>
 435 <P>
 436 <A NAME="IDX8"></A>
 437
 438 </P>
 439 <P>
 440 Although the Readline library comes with a set of <CODE>emacs</CODE>-like
 441 keybindings installed by default, it is possible to use a different set
 442 of keybindings.
 443 Any user can customize programs that use Readline by putting
 444 commands in an <EM>inputrc</EM> file in his home directory.
 445 The name of this
 446 file is taken from the value of the environment variable <CODE>INPUTRC</CODE>.  If
 447 that variable is unset, the default is <TT>`~/.inputrc'</TT>.
 448
 449 </P>
 450 <P>
 451 When a program which uses the Readline library starts up, the
 452 init file is read, and the key bindings are set.
 453
 454 </P>
 455 <P>
 456 In addition, the <CODE>C-x C-r</CODE> command re-reads this init file, thus
 457 incorporating any changes that you might have made to it.
 458
 459 </P>
 460
 461 <UL>
 462 <LI><A HREF="readline.html#SEC10">Readline Init File Syntax</A>: Syntax for the commands in the inputrc file.
 463
 464 <LI><A HREF="readline.html#SEC11">Conditional Init Constructs</A>: Conditional key bindings in the inputrc file.
 465
 466 <LI><A HREF="readline.html#SEC12">Sample Init File</A>: An example inputrc file.
 467 </UL>
 468
 469
 470
 471 <H3><A NAME="SEC10" HREF="readline.html#TOC10">Readline Init File Syntax</A></H3>
 472
 473 <P>
 474 There are only a few basic constructs allowed in the
 475 Readline init file.  Blank lines are ignored.
 476 Lines beginning with a <SAMP>`#'</SAMP> are comments.
 477 Lines beginning with a <SAMP>`$'</SAMP> indicate conditional
 478 constructs (see section <A HREF="readline.html#SEC11">Conditional Init Constructs</A>).  Other lines
 479 denote variable settings and key bindings.
 480
 481 </P>
 482 <DL COMPACT>
 483
 484 <DT>Variable Settings
 485 <DD>
 486 You can modify the run-time behavior of Readline by
 487 altering the values of variables in Readline
 488 using the <CODE>set</CODE> command within the init file.  Here is how to
 489 change from the default Emacs-like key binding to use
 490 <CODE>vi</CODE> line editing commands:
 491
 492
 493 <PRE>
 494 set editing-mode vi
 495 </PRE>
 496
 497 A great deal of run-time behavior is changeable with the following
 498 variables.
 499
 500 <DL COMPACT>
 501
 502 <DT><CODE>bell-style</CODE>
 503 <DD>
 504 <A NAME="IDX9"></A>
 505 Controls what happens when Readline wants to ring the terminal bell.
 506 If set to <SAMP>`none'</SAMP>, Readline never rings the bell.  If set to
 507 <SAMP>`visible'</SAMP>, Readline uses a visible bell if one is available.
 508 If set to <SAMP>`audible'</SAMP> (the default), Readline attempts to ring
 509 the terminal's bell.
 510
 511 <DT><CODE>comment-begin</CODE>
 512 <DD>
 513 <A NAME="IDX10"></A>
 514 The string to insert at the beginning of the line when the
 515 <CODE>insert-comment</CODE> command is executed.  The default value
 516 is <CODE>"#"</CODE>.
 517
 518 <DT><CODE>completion-ignore-case</CODE>
 519 <DD>
 520 If set to <SAMP>`on'</SAMP>, Readline performs filename matching and completion
 521 in a case-insensitive fashion.
 522 The default value is <SAMP>`off'</SAMP>.
 523
 524 <DT><CODE>completion-query-items</CODE>
 525 <DD>
 526 <A NAME="IDX11"></A>
 527 The number of possible completions that determines when the user is
 528 asked whether he wants to see the list of possibilities.  If the
 529 number of possible completions is greater than this value,
 530 Readline will ask the user whether or not he wishes to view
 531 them; otherwise, they are simply listed.  The default limit is
 532 <CODE>100</CODE>.
 533
 534 <DT><CODE>convert-meta</CODE>
 535 <DD>
 536 <A NAME="IDX12"></A>
 537 If set to <SAMP>`on'</SAMP>, Readline will convert characters with the
 538 eighth bit set to an ASCII key sequence by stripping the eighth
 539 bit and prepending an <KBD>ESC</KBD> character, converting them to a
 540 meta-prefixed key sequence.  The default value is <SAMP>`on'</SAMP>.
 541
 542 <DT><CODE>disable-completion</CODE>
 543 <DD>
 544 <A NAME="IDX13"></A>
 545 If set to <SAMP>`On'</SAMP>, Readline will inhibit word completion.
 546 Completion  characters will be inserted into the line as if they had
 547 been mapped to <CODE>self-insert</CODE>.  The default is <SAMP>`off'</SAMP>.
 548
 549 <DT><CODE>editing-mode</CODE>
 550 <DD>
 551 <A NAME="IDX14"></A>
 552 The <CODE>editing-mode</CODE> variable controls which default set of
 553 key bindings is used.  By default, Readline starts up in Emacs editing
 554 mode, where the keystrokes are most similar to Emacs.  This variable can be
 555 set to either <SAMP>`emacs'</SAMP> or <SAMP>`vi'</SAMP>.
 556
 557 <DT><CODE>enable-keypad</CODE>
 558 <DD>
 559 <A NAME="IDX15"></A>
 560 When set to <SAMP>`on'</SAMP>, Readline will try to enable the application
 561 keypad when it is called.  Some systems need this to enable the
 562 arrow keys.  The default is <SAMP>`off'</SAMP>.
 563
 564 <DT><CODE>expand-tilde</CODE>
 565 <DD>
 566 <A NAME="IDX16"></A>
 567 If set to <SAMP>`on'</SAMP>, tilde expansion is performed when Readline
 568 attempts word completion.  The default is <SAMP>`off'</SAMP>.
 569
 570 <DT><CODE>horizontal-scroll-mode</CODE>
 571 <DD>
 572 <A NAME="IDX17"></A>
 573 This variable can be set to either <SAMP>`on'</SAMP> or <SAMP>`off'</SAMP>.  Setting it
 574 to <SAMP>`on'</SAMP> means that the text of the lines being edited will scroll
 575 horizontally on a single screen line when they are longer than the width
 576 of the screen, instead of wrapping onto a new screen line.  By default,
 577 this variable is set to <SAMP>`off'</SAMP>.
 578
 579 <DT><CODE>input-meta</CODE>
 580 <DD>
 581 <A NAME="IDX18"></A>
 582 <A NAME="IDX19"></A>
 583 If set to <SAMP>`on'</SAMP>, Readline will enable eight-bit input (it
 584 will not strip the eighth bit from the characters it reads),
 585 regardless of what the terminal claims it can support.  The
 586 default value is <SAMP>`off'</SAMP>.  The name <CODE>meta-flag</CODE> is a
 587 synonym for this variable.
 588
 589 <DT><CODE>isearch-terminators</CODE>
 590 <DD>
 591 <A NAME="IDX20"></A>
 592 The string of characters that should terminate an incremental search without
 593 subsequently executing the character as a command (see section <A HREF="readline.html#SEC8">Searching for Commands in the History</A>).
 594 If this variable has not been given a value, the characters <KBD>ESC</KBD> and
 595 <KBD>C-J</KBD> will terminate an incremental search.
 596
 597 <DT><CODE>keymap</CODE>
 598 <DD>
 599 <A NAME="IDX21"></A>
 600 Sets Readline's idea of the current keymap for key binding commands.
 601 Acceptable <CODE>keymap</CODE> names are
 602 <CODE>emacs</CODE>,
 603 <CODE>emacs-standard</CODE>,
 604 <CODE>emacs-meta</CODE>,
 605 <CODE>emacs-ctlx</CODE>,
 606 <CODE>vi</CODE>,
 607 <CODE>vi-command</CODE>, and
 608 <CODE>vi-insert</CODE>.
 609 <CODE>vi</CODE> is equivalent to <CODE>vi-command</CODE>; <CODE>emacs</CODE> is
 610 equivalent to <CODE>emacs-standard</CODE>.  The default value is <CODE>emacs</CODE>.
 611 The value of the <CODE>editing-mode</CODE> variable also affects the
 612 default keymap.
 613
 614 <DT><CODE>mark-directories</CODE>
 615 <DD>
 616 If set to <SAMP>`on'</SAMP>, completed directory names have a slash
 617 appended.  The default is <SAMP>`on'</SAMP>.
 618
 619 <DT><CODE>mark-modified-lines</CODE>
 620 <DD>
 621 <A NAME="IDX22"></A>
 622 This variable, when set to <SAMP>`on'</SAMP>, causes Readline to display an
 623 asterisk (<SAMP>`*'</SAMP>) at the start of history lines which have been modified.
 624 This variable is <SAMP>`off'</SAMP> by default.
 625
 626 <DT><CODE>output-meta</CODE>
 627 <DD>
 628 <A NAME="IDX23"></A>
 629 If set to <SAMP>`on'</SAMP>, Readline will display characters with the
 630 eighth bit set directly rather than as a meta-prefixed escape
 631 sequence.  The default is <SAMP>`off'</SAMP>.
 632
 633 <DT><CODE>print-completions-horizontally</CODE>
 634 <DD>
 635 If set to <SAMP>`on'</SAMP>, Readline will display completions with matches
 636 sorted horizontally in alphabetical order, rather than down the screen.
 637 The default is <SAMP>`off'</SAMP>.
 638
 639 <DT><CODE>show-all-if-ambiguous</CODE>
 640 <DD>
 641 <A NAME="IDX24"></A>
 642 This alters the default behavior of the completion functions.  If
 643 set to <SAMP>`on'</SAMP>,
 644 words which have more than one possible completion cause the
 645 matches to be listed immediately instead of ringing the bell.
 646 The default value is <SAMP>`off'</SAMP>.
 647
 648 <DT><CODE>visible-stats</CODE>
 649 <DD>
 650 <A NAME="IDX25"></A>
 651 If set to <SAMP>`on'</SAMP>, a character denoting a file's type
 652 is appended to the filename when listing possible
 653 completions.  The default is <SAMP>`off'</SAMP>.
 654
 655 </DL>
 656
 657 <DT>Key Bindings
 658 <DD>
 659 The syntax for controlling key bindings in the init file is
 660 simple.  First you have to know the name of the command that you
 661 want to change.  The following sections contain tables of the command
 662 name, the default keybinding, if any, and a short description of what
 663 the command does.
 664
 665 Once you know the name of the command, simply place the name of the key
 666 you wish to bind the command to, a colon, and then the name of the
 667 command on a line in the init file.  The name of the key
 668 can be expressed in different ways, depending on which is most
 669 comfortable for you.
 670
 671 <DL COMPACT>
 672
 673 <DT><VAR>keyname</VAR>: <VAR>function-name</VAR> or <VAR>macro</VAR>
 674 <DD>
 675 <VAR>keyname</VAR> is the name of a key spelled out in English.  For example:
 676
 677 <PRE>
 678 Control-u: universal-argument
 679 Meta-Rubout: backward-kill-word
 680 Control-o: "&#62; output"
 681 </PRE>
 682
 683 In the above example, <KBD>C-u</KBD> is bound to the function
 684 <CODE>universal-argument</CODE>, and <KBD>C-o</KBD> is bound to run the macro
 685 expressed on the right hand side (that is, to insert the text
 686 <SAMP>`&#62; output'</SAMP> into the line).
 687
 688 <DT>"<VAR>keyseq</VAR>": <VAR>function-name</VAR> or <VAR>macro</VAR>
 689 <DD>
 690 <VAR>keyseq</VAR> differs from <VAR>keyname</VAR> above in that strings
 691 denoting an entire key sequence can be specified, by placing
 692 the key sequence in double quotes.  Some GNU Emacs style key
 693 escapes can be used, as in the following example, but the
 694 special character names are not recognized.
 695
 696
 697 <PRE>
 698 "\C-u": universal-argument
 699 "\C-x\C-r": re-read-init-file
 700 "\e[11~": "Function Key 1"
 701 </PRE>
 702
 703 In the above example, <KBD>C-u</KBD> is bound to the function
 704 <CODE>universal-argument</CODE> (just as it was in the first example),
 705 <SAMP>`<KBD>C-x</KBD> <KBD>C-r</KBD>'</SAMP> is bound to the function <CODE>re-read-init-file</CODE>,
 706 and <SAMP>`<KBD>ESC</KBD> <KBD>[</KBD> <KBD>1</KBD> <KBD>1</KBD> <KBD>~</KBD>'</SAMP> is bound to insert
 707 the text <SAMP>`Function Key 1'</SAMP>.
 708
 709 </DL>
 710
 711 The following GNU Emacs style escape sequences are available when
 712 specifying key sequences:
 713
 714 <DL COMPACT>
 715
 716 <DT><CODE><KBD>\C-</KBD></CODE>
 717 <DD>
 718 control prefix
 719 <DT><CODE><KBD>\M-</KBD></CODE>
 720 <DD>
 721 meta prefix
 722 <DT><CODE><KBD>\e</KBD></CODE>
 723 <DD>
 724 an escape character
 725 <DT><CODE><KBD>\\</KBD></CODE>
 726 <DD>
 727 backslash
 728 <DT><CODE><KBD>\"</KBD></CODE>
 729 <DD>
 730 <KBD>"</KBD>
 731 <DT><CODE><KBD>\'</KBD></CODE>
 732 <DD>
 733 <KBD>'</KBD>
 734 </DL>
 735
 736 In addition to the GNU Emacs style escape sequences, a second
 737 set of backslash escapes is available:
 738
 739 <DL COMPACT>
 740
 741 <DT><CODE>\a</CODE>
 742 <DD>
 743 alert (bell)
 744 <DT><CODE>\b</CODE>
 745 <DD>
 746 backspace
 747 <DT><CODE>\d</CODE>
 748 <DD>
 749 delete
 750 <DT><CODE>\f</CODE>
 751 <DD>
 752 form feed
 753 <DT><CODE>\n</CODE>
 754 <DD>
 755 newline
 756 <DT><CODE>\r</CODE>
 757 <DD>
 758 carriage return
 759 <DT><CODE>\t</CODE>
 760 <DD>
 761 horizontal tab
 762 <DT><CODE>\v</CODE>
 763 <DD>
 764 vertical tab
 765 <DT><CODE>\<VAR>nnn</VAR></CODE>
 766 <DD>
 767 the character whose ASCII code is the octal value <VAR>nnn</VAR>
 768 (one to three digits)
 769 <DT><CODE>\x<VAR>nnn</VAR></CODE>
 770 <DD>
 771 the character whose ASCII code is the hexadecimal value <VAR>nnn</VAR>
 772 (one to three digits)
 773 </DL>
 774
 775 When entering the text of a macro, single or double quotes must
 776 be used to indicate a macro definition.
 777 Unquoted text is assumed to be a function name.
 778 In the macro body, the backslash escapes described above are expanded.
 779 Backslash will quote any other character in the macro text,
 780 including <SAMP>`"'</SAMP> and <SAMP>`''</SAMP>.
 781 For example, the following binding will make <SAMP>`C-x \'</SAMP>
 782 insert a single <SAMP>`\'</SAMP> into the line:
 783
 784 <PRE>
 785 "\C-x\\": "\\"
 786 </PRE>
 787
 788 </DL>
 789
 790
 791
 792 <H3><A NAME="SEC11" HREF="readline.html#TOC11">Conditional Init Constructs</A></H3>
 793
 794 <P>
 795 Readline implements a facility similar in spirit to the conditional
 796 compilation features of the C preprocessor which allows key
 797 bindings and variable settings to be performed as the result
 798 of tests.  There are four parser directives used.
 799
 800 </P>
 801 <DL COMPACT>
 802
 803 <DT><CODE>$if</CODE>
 804 <DD>
 805 The <CODE>$if</CODE> construct allows bindings to be made based on the
 806 editing mode, the terminal being used, or the application using
 807 Readline.  The text of the test extends to the end of the line;
 808 no characters are required to isolate it.
 809
 810 <DL COMPACT>
 811
 812 <DT><CODE>mode</CODE>
 813 <DD>
 814 The <CODE>mode=</CODE> form of the <CODE>$if</CODE> directive is used to test
 815 whether Readline is in <CODE>emacs</CODE> or <CODE>vi</CODE> mode.
 816 This may be used in conjunction
 817 with the <SAMP>`set keymap'</SAMP> command, for instance, to set bindings in
 818 the <CODE>emacs-standard</CODE> and <CODE>emacs-ctlx</CODE> keymaps only if
 819 Readline is starting out in <CODE>emacs</CODE> mode.
 820
 821 <DT><CODE>term</CODE>
 822 <DD>
 823 The <CODE>term=</CODE> form may be used to include terminal-specific
 824 key bindings, perhaps to bind the key sequences output by the
 825 terminal's function keys.  The word on the right side of the
 826 <SAMP>`='</SAMP> is tested against both the full name of the terminal and
 827 the portion of the terminal name before the first <SAMP>`-'</SAMP>.  This
 828 allows <CODE>sun</CODE> to match both <CODE>sun</CODE> and <CODE>sun-cmd</CODE>,
 829 for instance.
 830
 831 <DT><CODE>application</CODE>
 832 <DD>
 833 The <VAR>application</VAR> construct is used to include
 834 application-specific settings.  Each program using the Readline
 835 library sets the <VAR>application name</VAR>, and you can test for it.
 836 This could be used to bind key sequences to functions useful for
 837 a specific program.  For instance, the following command adds a
 838 key sequence that quotes the current or previous word in Bash:
 839
 840 <PRE>
 841 $if Bash
 842 # Quote the current or previous word
 843 "\C-xq": "\eb\"\ef\""
 844 $endif
 845 </PRE>
 846
 847 </DL>
 848
 849 <DT><CODE>$endif</CODE>
 850 <DD>
 851 This command, as seen in the previous example, terminates an
 852 <CODE>$if</CODE> command.
 853
 854 <DT><CODE>$else</CODE>
 855 <DD>
 856 Commands in this branch of the <CODE>$if</CODE> directive are executed if
 857 the test fails.
 858
 859 <DT><CODE>$include</CODE>
 860 <DD>
 861 This directive takes a single filename as an argument and reads commands
 862 and bindings from that file.
 863
 864 <PRE>
 865 $include /etc/inputrc
 866 </PRE>
 867
 868 </DL>
 869
 870
 871
 872 <H3><A NAME="SEC12" HREF="readline.html#TOC12">Sample Init File</A></H3>
 873
 874 <P>
 875 Here is an example of an inputrc file.  This illustrates key
 876 binding, variable assignment, and conditional syntax.
 877
 878 </P>
 879
 880 <PRE>
 881 # This file controls the behaviour of line input editing for
 882 # programs that use the Gnu Readline library.  Existing programs
 883 # include FTP, Bash, and Gdb.
 884 #
 885 # You can re-read the inputrc file with C-x C-r.
 886 # Lines beginning with '#' are comments.
 887 #
 888 # First, include any systemwide bindings and variable assignments from
 889 # /etc/Inputrc
 890 $include /etc/Inputrc
 891
 892 #
 893 # Set various bindings for emacs mode.
 894
 895 set editing-mode emacs
 896
 897 $if mode=emacs
 898
 899 Meta-Control-h: backward-kill-word      Text after the function name is ignored
 900
 901 #
 902 # Arrow keys in keypad mode
 903 #
 904 #"\M-OD":        backward-char
 905 #"\M-OC":        forward-char
 906 #"\M-OA":        previous-history
 907 #"\M-OB":        next-history
 908 #
 909 # Arrow keys in ANSI mode
 910 #
 911 "\M-[D":        backward-char
 912 "\M-[C":        forward-char
 913 "\M-[A":        previous-history
 914 "\M-[B":        next-history
 915 #
 916 # Arrow keys in 8 bit keypad mode
 917 #
 918 #"\M-\C-OD":       backward-char
 919 #"\M-\C-OC":       forward-char
 920 #"\M-\C-OA":       previous-history
 921 #"\M-\C-OB":       next-history
 922 #
 923 # Arrow keys in 8 bit ANSI mode
 924 #
 925 #"\M-\C-[D":       backward-char
 926 #"\M-\C-[C":       forward-char
 927 #"\M-\C-[A":       previous-history
 928 #"\M-\C-[B":       next-history
 929
 930 C-q: quoted-insert
 931
 932 $endif
 933
 934 # An old-style binding.  This happens to be the default.
 935 TAB: complete
 936
 937 # Macros that are convenient for shell interaction
 938 $if Bash
 939 # edit the path
 940 "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
 941 # prepare to type a quoted word -- insert open and close double quotes
 942 # and move to just after the open quote
 943 "\C-x\"": "\"\"\C-b"
 944 # insert a backslash (testing backslash escapes in sequences and macros)
 945 "\C-x\\": "\\"
 946 # Quote the current or previous word
 947 "\C-xq": "\eb\"\ef\""
 948 # Add a binding to refresh the line, which is unbound
 949 "\C-xr": redraw-current-line
 950 # Edit variable on current line.
 951 "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
 952 $endif
 953
 954 # use a visible bell if one is available
 955 set bell-style visible
 956
 957 # don't strip characters to 7 bits when reading
 958 set input-meta on
 959
 960 # allow iso-latin1 characters to be inserted rather than converted to
 961 # prefix-meta sequences
 962 set convert-meta off
 963
 964 # display characters with the eighth bit set directly rather than
 965 # as meta-prefixed characters
 966 set output-meta on
 967
 968 # if there are more than 150 possible completions for a word, ask the
 969 # user if he wants to see all of them
 970 set completion-query-items 150
 971
 972 # For FTP
 973 $if Ftp
 974 "\C-xg": "get \M-?"
 975 "\C-xt": "put \M-?"
 976 "\M-.": yank-last-arg
 977 $endif
 978 </PRE>
 979
 980
 981
 982 <H2><A NAME="SEC13" HREF="readline.html#TOC13">Bindable Readline Commands</A></H2>
 983
 984
 985 <UL>
 986 <LI><A HREF="readline.html#SEC14">Commands For Moving</A>: Moving about the line.
 987 <LI><A HREF="readline.html#SEC15">Commands For History</A>: Getting at previous lines.
 988 <LI><A HREF="readline.html#SEC16">Commands For Text</A>: Commands for changing text.
 989 <LI><A HREF="readline.html#SEC17">Commands For Killing</A>: Commands for killing and yanking.
 990 <LI><A HREF="readline.html#SEC18">Numeric Arguments</A>: Specifying numeric arguments, repeat counts.
 991 <LI><A HREF="readline.html#SEC19">Commands For Completion</A>: Getting Readline to do the typing for you.
 992 <LI><A HREF="readline.html#SEC20">Keyboard Macros</A>: Saving and re-executing typed characters
 993 <LI><A HREF="readline.html#SEC21">Miscellaneous Commands</A>: Other miscellaneous commands.
 994 </UL>
 995
 996 <P>
 997 This section describes Readline commands that may be bound to key
 998 sequences.
 999
1000 </P>
1001
1002
1003 <H3><A NAME="SEC14" HREF="readline.html#TOC14">Commands For Moving</A></H3>
1004 <DL COMPACT>
1005
1006 <DT><CODE>beginning-of-line (C-a)</CODE>
1007 <DD>
1008 <A NAME="IDX26"></A>
1009 Move to the start of the current line.
1010
1011 <DT><CODE>end-of-line (C-e)</CODE>
1012 <DD>
1013 <A NAME="IDX27"></A>
1014 Move to the end of the line.
1015
1016 <DT><CODE>forward-char (C-f)</CODE>
1017 <DD>
1018 <A NAME="IDX28"></A>
1019 Move forward a character.
1020
1021 <DT><CODE>backward-char (C-b)</CODE>
1022 <DD>
1023 <A NAME="IDX29"></A>
1024 Move back a character.
1025
1026 <DT><CODE>forward-word (M-f)</CODE>
1027 <DD>
1028 <A NAME="IDX30"></A>
1029 Move forward to the end of the next word.  Words are composed of
1030 letters and digits.
1031
1032 <DT><CODE>backward-word (M-b)</CODE>
1033 <DD>
1034 <A NAME="IDX31"></A>
1035 Move back to the start of this, or the previous, word.  Words are
1036 composed of letters and digits.
1037
1038 <DT><CODE>clear-screen (C-l)</CODE>
1039 <DD>
1040 <A NAME="IDX32"></A>
1041 Clear the screen and redraw the current line,
1042 leaving the current line at the top of the screen.
1043
1044 <DT><CODE>redraw-current-line ()</CODE>
1045 <DD>
1046 <A NAME="IDX33"></A>
1047 Refresh the current line.  By default, this is unbound.
1048
1049 </DL>
1050
1051
1052
1053 <H3><A NAME="SEC15" HREF="readline.html#TOC15">Commands For Manipulating The History</A></H3>
1054
1055 <DL COMPACT>
1056
1057 <DT><CODE>accept-line (Newline, Return)</CODE>
1058 <DD>
1059 <A NAME="IDX34"></A>
1060 Accept the line regardless of where the cursor is.  If this line is
1061 non-empty, add it to the history list.  If this line was a history
1062 line, then restore the history line to its original state.
1063
1064 <DT><CODE>previous-history (C-p)</CODE>
1065 <DD>
1066 <A NAME="IDX35"></A>
1067 Move `up' through the history list.
1068
1069 <DT><CODE>next-history (C-n)</CODE>
1070 <DD>
1071 <A NAME="IDX36"></A>
1072 Move `down' through the history list.
1073
1074 <DT><CODE>beginning-of-history (M-&#60;)</CODE>
1075 <DD>
1076 <A NAME="IDX37"></A>
1077 Move to the first line in the history.
1078
1079 <DT><CODE>end-of-history (M-&#62;)</CODE>
1080 <DD>
1081 <A NAME="IDX38"></A>
1082 Move to the end of the input history, i.e., the line currently
1083 being entered.
1084
1085 <DT><CODE>reverse-search-history (C-r)</CODE>
1086 <DD>
1087 <A NAME="IDX39"></A>
1088 Search backward starting at the current line and moving `up' through
1089 the history as necessary.  This is an incremental search.
1090
1091 <DT><CODE>forward-search-history (C-s)</CODE>
1092 <DD>
1093 <A NAME="IDX40"></A>
1094 Search forward starting at the current line and moving `down' through
1095 the the history as necessary.  This is an incremental search.
1096
1097 <DT><CODE>non-incremental-reverse-search-history (M-p)</CODE>
1098 <DD>
1099 <A NAME="IDX41"></A>
1100 Search backward starting at the current line and moving `up'
1101 through the history as necessary using a non-incremental search
1102 for a string supplied by the user.
1103
1104 <DT><CODE>non-incremental-forward-search-history (M-n)</CODE>
1105 <DD>
1106 <A NAME="IDX42"></A>
1107 Search forward starting at the current line and moving `down'
1108 through the the history as necessary using a non-incremental search
1109 for a string supplied by the user.
1110
1111 <DT><CODE>history-search-forward ()</CODE>
1112 <DD>
1113 <A NAME="IDX43"></A>
1114 Search forward through the history for the string of characters
1115 between the start of the current line and the current cursor
1116 position (the <VAR>point</VAR>).  This is a non-incremental search.  By
1117 default, this command is unbound.
1118
1119 <DT><CODE>history-search-backward ()</CODE>
1120 <DD>
1121 <A NAME="IDX44"></A>
1122 Search backward through the history for the string of characters
1123 between the start of the current line and the point.  This
1124 is a non-incremental search.  By default, this command is unbound.
1125
1126 <DT><CODE>yank-nth-arg (M-C-y)</CODE>
1127 <DD>
1128 <A NAME="IDX45"></A>
1129 Insert the first argument to the previous command (usually
1130 the second word on the previous line).  With an argument <VAR>n</VAR>,
1131 insert the <VAR>n</VAR>th word from the previous command (the words
1132 in the previous command begin with word 0).  A negative argument
1133 inserts the <VAR>n</VAR>th word from the end of the previous command.
1134
1135 <DT><CODE>yank-last-arg (M-., M-_)</CODE>
1136 <DD>
1137 <A NAME="IDX46"></A>
1138 Insert last argument to the previous command (the last word of the
1139 previous history entry).  With an
1140 argument, behave exactly like <CODE>yank-nth-arg</CODE>.
1141 Successive calls to <CODE>yank-last-arg</CODE> move back through the history
1142 list, inserting the last argument of each line in turn.
1143
1144 </DL>
1145
1146
1147
1148 <H3><A NAME="SEC16" HREF="readline.html#TOC16">Commands For Changing Text</A></H3>
1149
1150 <DL COMPACT>
1151
1152 <DT><CODE>delete-char (C-d)</CODE>
1153 <DD>
1154 <A NAME="IDX47"></A>
1155 Delete the character under the cursor.  If the cursor is at the
1156 beginning of the line, there are no characters in the line, and
1157 the last character typed was not bound to <CODE>delete-char</CODE>, then
1158 return <CODE>EOF</CODE>.
1159
1160 <DT><CODE>backward-delete-char (Rubout)</CODE>
1161 <DD>
1162 <A NAME="IDX48"></A>
1163 Delete the character behind the cursor.  A numeric argument means
1164 to kill the characters instead of deleting them.
1165
1166 <DT><CODE>forward-backward-delete-char ()</CODE>
1167 <DD>
1168 <A NAME="IDX49"></A>
1169 Delete the character under the cursor, unless the cursor is at the
1170 end of the line, in which case the character behind the cursor is
1171 deleted.  By default, this is not bound to a key.
1172
1173 <DT><CODE>quoted-insert (C-q, C-v)</CODE>
1174 <DD>
1175 <A NAME="IDX50"></A>
1176 Add the next character typed to the line verbatim.  This is
1177 how to insert key sequences like <KBD>C-q</KBD>, for example.
1178
1179 <DT><CODE>tab-insert (M-TAB)</CODE>
1180 <DD>
1181 <A NAME="IDX51"></A>
1182 Insert a tab character.
1183
1184 <DT><CODE>self-insert (a, b, A, 1, !, ...)</CODE>
1185 <DD>
1186 <A NAME="IDX52"></A>
1187 Insert yourself.
1188
1189 <DT><CODE>transpose-chars (C-t)</CODE>
1190 <DD>
1191 <A NAME="IDX53"></A>
1192 Drag the character before the cursor forward over
1193 the character at the cursor, moving the
1194 cursor forward as well.  If the insertion point
1195 is at the end of the line, then this
1196 transposes the last two characters of the line.
1197 Negative arguments don't work.
1198
1199 <DT><CODE>transpose-words (M-t)</CODE>
1200 <DD>
1201 <A NAME="IDX54"></A>
1202 Drag the word behind the cursor past the word in front of the cursor
1203 moving the cursor over that word as well.
1204
1205 <DT><CODE>upcase-word (M-u)</CODE>
1206 <DD>
1207 <A NAME="IDX55"></A>
1208 Uppercase the current (or following) word.  With a negative argument,
1209 uppercase the previous word, but do not move the cursor.
1210
1211 <DT><CODE>downcase-word (M-l)</CODE>
1212 <DD>
1213 <A NAME="IDX56"></A>
1214 Lowercase the current (or following) word.  With a negative argument,
1215 lowercase the previous word, but do not move the cursor.
1216
1217 <DT><CODE>capitalize-word (M-c)</CODE>
1218 <DD>
1219 <A NAME="IDX57"></A>
1220 Capitalize the current (or following) word.  With a negative argument,
1221 capitalize the previous word, but do not move the cursor.
1222
1223 </DL>
1224
1225
1226
1227 <H3><A NAME="SEC17" HREF="readline.html#TOC17">Killing And Yanking</A></H3>
1228
1229 <DL COMPACT>
1230
1231 <DT><CODE>kill-line (C-k)</CODE>
1232 <DD>
1233 <A NAME="IDX58"></A>
1234 Kill the text from the current cursor position to the end of the line.
1235
1236 <DT><CODE>backward-kill-line (C-x Rubout)</CODE>
1237 <DD>
1238 <A NAME="IDX59"></A>
1239 Kill backward to the beginning of the line.
1240
1241 <DT><CODE>unix-line-discard (C-u)</CODE>
1242 <DD>
1243 <A NAME="IDX60"></A>
1244 Kill backward from the cursor to the beginning of the current line.
1245 The killed text is saved on the kill-ring.
1246
1247 <DT><CODE>kill-whole-line ()</CODE>
1248 <DD>
1249 <A NAME="IDX61"></A>
1250 Kill all characters on the current line, no matter where the
1251 cursor is.  By default, this is unbound.
1252
1253 <DT><CODE>kill-word (M-d)</CODE>
1254 <DD>
1255 <A NAME="IDX62"></A>
1256 Kill from the cursor to the end of the current word, or if between
1257 words, to the end of the next word.  Word boundaries are the same
1258 as <CODE>forward-word</CODE>.
1259
1260 <DT><CODE>backward-kill-word (M-DEL)</CODE>
1261 <DD>
1262 <A NAME="IDX63"></A>
1263 Kill the word behind the cursor.  Word boundaries are the same
1264 as <CODE>backward-word</CODE>.
1265
1266 <DT><CODE>unix-word-rubout (C-w)</CODE>
1267 <DD>
1268 <A NAME="IDX64"></A>
1269 Kill the word behind the cursor, using white space as a word
1270 boundary.  The killed text is saved on the kill-ring.
1271
1272 <DT><CODE>delete-horizontal-space ()</CODE>
1273 <DD>
1274 <A NAME="IDX65"></A>
1275 Delete all spaces and tabs around point.  By default, this is unbound.
1276
1277 <DT><CODE>kill-region ()</CODE>
1278 <DD>
1279 <A NAME="IDX66"></A>
1280 Kill the text between the point and the <EM>mark</EM> (saved
1281 cursor position).  This text is referred to as the <VAR>region</VAR>.
1282 By default, this command is unbound.
1283
1284 <DT><CODE>copy-region-as-kill ()</CODE>
1285 <DD>
1286 <A NAME="IDX67"></A>
1287 Copy the text in the region to the kill buffer, so it can be yanked
1288 right away.  By default, this command is unbound.
1289
1290 <DT><CODE>copy-backward-word ()</CODE>
1291 <DD>
1292 <A NAME="IDX68"></A>
1293 Copy the word before point to the kill buffer.
1294 The word boundaries are the same as <CODE>backward-word</CODE>.
1295 By default, this command is unbound.
1296
1297 <DT><CODE>copy-forward-word ()</CODE>
1298 <DD>
1299 <A NAME="IDX69"></A>
1300 Copy the word following point to the kill buffer.
1301 The word boundaries are the same as <CODE>forward-word</CODE>.
1302 By default, this command is unbound.
1303
1304 <DT><CODE>yank (C-y)</CODE>
1305 <DD>
1306 <A NAME="IDX70"></A>
1307 Yank the top of the kill ring into the buffer at the current
1308 cursor position.
1309
1310 <DT><CODE>yank-pop (M-y)</CODE>
1311 <DD>
1312 <A NAME="IDX71"></A>
1313 Rotate the kill-ring, and yank the new top.  You can only do this if
1314 the prior command is yank or yank-pop.
1315 </DL>
1316
1317
1318
1319 <H3><A NAME="SEC18" HREF="readline.html#TOC18">Specifying Numeric Arguments</A></H3>
1320 <DL COMPACT>
1321
1322 <DT><CODE>digit-argument (M-0, M-1, ... M--)</CODE>
1323 <DD>
1324 <A NAME="IDX72"></A>
1325 Add this digit to the argument already accumulating, or start a new
1326 argument.  <KBD>M--</KBD> starts a negative argument.
1327
1328 <DT><CODE>universal-argument ()</CODE>
1329 <DD>
1330 <A NAME="IDX73"></A>
1331 This is another way to specify an argument.
1332 If this command is followed by one or more digits, optionally with a
1333 leading minus sign, those digits define the argument.
1334 If the command is followed by digits, executing <CODE>universal-argument</CODE>
1335 again ends the numeric argument, but is otherwise ignored.
1336 As a special case, if this command is immediately followed by a
1337 character that is neither a digit or minus sign, the argument count
1338 for the next command is multiplied by four.
1339 The argument count is initially one, so executing this function the
1340 first time makes the argument count four, a second time makes the
1341 argument count sixteen, and so on.
1342 By default, this is not bound to a key.
1343 </DL>
1344
1345
1346
1347 <H3><A NAME="SEC19" HREF="readline.html#TOC19">Letting Readline Type For You</A></H3>
1348
1349 <DL COMPACT>
1350
1351 <DT><CODE>complete (TAB)</CODE>
1352 <DD>
1353 <A NAME="IDX74"></A>
1354 Attempt to do completion on the text before the cursor.  This is
1355 application-specific.  Generally, if you are typing a filename
1356 argument, you can do filename completion; if you are typing a command,
1357 you can do command completion; if you are typing in a symbol to GDB, you
1358 can do symbol name completion; if you are typing in a variable to Bash,
1359 you can do variable name completion, and so on.
1360
1361 <DT><CODE>possible-completions (M-?)</CODE>
1362 <DD>
1363 <A NAME="IDX75"></A>
1364 List the possible completions of the text before the cursor.
1365
1366 <DT><CODE>insert-completions (M-*)</CODE>
1367 <DD>
1368 <A NAME="IDX76"></A>
1369 Insert all completions of the text before point that would have
1370 been generated by <CODE>possible-completions</CODE>.
1371
1372 <DT><CODE>menu-complete ()</CODE>
1373 <DD>
1374 <A NAME="IDX77"></A>
1375 Similar to <CODE>complete</CODE>, but replaces the word to be completed
1376 with a single match from the list of possible completions.
1377 Repeated execution of <CODE>menu-complete</CODE> steps through the list
1378 of possible completions, inserting each match in turn.
1379 At the end of the list of completions, the bell is rung and the
1380 original text is restored.
1381 An argument of <VAR>n</VAR> moves <VAR>n</VAR> positions forward in the list
1382 of matches; a negative argument may be used to move backward
1383 through the list.
1384 This command is intended to be bound to <CODE>TAB</CODE>, but is unbound
1385 by default.
1386
1387 <DT><CODE>delete-char-or-list ()</CODE>
1388 <DD>
1389 <A NAME="IDX78"></A>
1390 Deletes the character under the cursor if not at the beginning or
1391 end of the line (like <CODE>delete-char</CODE>).
1392 If at the end of the line, behaves identically to
1393 <CODE>possible-completions</CODE>.
1394 This command is unbound by default.
1395
1396 </DL>
1397
1398
1399
1400 <H3><A NAME="SEC20" HREF="readline.html#TOC20">Keyboard Macros</A></H3>
1401 <DL COMPACT>
1402
1403 <DT><CODE>start-kbd-macro (C-x ()</CODE>
1404 <DD>
1405 <A NAME="IDX79"></A>
1406 Begin saving the characters typed into the current keyboard macro.
1407
1408 <DT><CODE>end-kbd-macro (C-x ))</CODE>
1409 <DD>
1410 <A NAME="IDX80"></A>
1411 Stop saving the characters typed into the current keyboard macro
1412 and save the definition.
1413
1414 <DT><CODE>call-last-kbd-macro (C-x e)</CODE>
1415 <DD>
1416 <A NAME="IDX81"></A>
1417 Re-execute the last keyboard macro defined, by making the characters
1418 in the macro appear as if typed at the keyboard.
1419
1420 </DL>
1421
1422
1423
1424 <H3><A NAME="SEC21" HREF="readline.html#TOC21">Some Miscellaneous Commands</A></H3>
1425 <DL COMPACT>
1426
1427 <DT><CODE>re-read-init-file (C-x C-r)</CODE>
1428 <DD>
1429 <A NAME="IDX82"></A>
1430 Read in the contents of the inputrc file, and incorporate
1431 any bindings or variable assignments found there.
1432
1433 <DT><CODE>abort (C-g)</CODE>
1434 <DD>
1435 <A NAME="IDX83"></A>
1436 Abort the current editing command and
1437 ring the terminal's bell (subject to the setting of
1438 <CODE>bell-style</CODE>).
1439
1440 <DT><CODE>do-uppercase-version (M-a, M-b, M-<VAR>x</VAR>, ...)</CODE>
1441 <DD>
1442 <A NAME="IDX84"></A>
1443 If the metafied character <VAR>x</VAR> is lowercase, run the command
1444 that is bound to the corresponding uppercase character.
1445
1446 <DT><CODE>prefix-meta (ESC)</CODE>
1447 <DD>
1448 <A NAME="IDX85"></A>
1449 Make the next character typed be metafied.  This is for keyboards
1450 without a meta key.  Typing <SAMP>`ESC f'</SAMP> is equivalent to typing
1451 <SAMP>`M-f'</SAMP>.
1452
1453 <DT><CODE>undo (C-_, C-x C-u)</CODE>
1454 <DD>
1455 <A NAME="IDX86"></A>
1456 Incremental undo, separately remembered for each line.
1457
1458 <DT><CODE>revert-line (M-r)</CODE>
1459 <DD>
1460 <A NAME="IDX87"></A>
1461 Undo all changes made to this line.  This is like executing the <CODE>undo</CODE>
1462 command enough times to get back to the beginning.
1463
1464 <DT><CODE>tilde-expand (M-~)</CODE>
1465 <DD>
1466 <A NAME="IDX88"></A>
1467 Perform tilde expansion on the current word.
1468
1469 <DT><CODE>set-mark (C-@)</CODE>
1470 <DD>
1471 <A NAME="IDX89"></A>
1472 Set the mark to the current point.  If a
1473 numeric argument is supplied, the mark is set to that position.
1474
1475 <DT><CODE>exchange-point-and-mark (C-x C-x)</CODE>
1476 <DD>
1477 <A NAME="IDX90"></A>
1478 Swap the point with the mark.  The current cursor position is set to
1479 the saved position, and the old cursor position is saved as the mark.
1480
1481 <DT><CODE>character-search (C-])</CODE>
1482 <DD>
1483 <A NAME="IDX91"></A>
1484 A character is read and point is moved to the next occurrence of that
1485 character.  A negative count searches for previous occurrences.
1486
1487 <DT><CODE>character-search-backward (M-C-])</CODE>
1488 <DD>
1489 <A NAME="IDX92"></A>
1490 A character is read and point is moved to the previous occurrence
1491 of that character.  A negative count searches for subsequent
1492 occurrences.
1493
1494 <DT><CODE>insert-comment (M-#)</CODE>
1495 <DD>
1496 <A NAME="IDX93"></A>
1497 The value of the <CODE>comment-begin</CODE>
1498 variable is inserted at the beginning of the current line,
1499 and the line is accepted as if a newline had been typed.
1500
1501 <DT><CODE>dump-functions ()</CODE>
1502 <DD>
1503 <A NAME="IDX94"></A>
1504 Print all of the functions and their key bindings to the
1505 Readline output stream.  If a numeric argument is supplied,
1506 the output is formatted in such a way that it can be made part
1507 of an <VAR>inputrc</VAR> file.  This command is unbound by default.
1508
1509 <DT><CODE>dump-variables ()</CODE>
1510 <DD>
1511 <A NAME="IDX95"></A>
1512 Print all of the settable variables and their values to the
1513 Readline output stream.  If a numeric argument is supplied,
1514 the output is formatted in such a way that it can be made part
1515 of an <VAR>inputrc</VAR> file.  This command is unbound by default.
1516
1517 <DT><CODE>dump-macros ()</CODE>
1518 <DD>
1519 <A NAME="IDX96"></A>
1520 Print all of the Readline key sequences bound to macros and the
1521 strings they ouput.  If a numeric argument is supplied,
1522 the output is formatted in such a way that it can be made part
1523 of an <VAR>inputrc</VAR> file.  This command is unbound by default.
1524
1525 </DL>
1526
1527
1528
1529 <H2><A NAME="SEC22" HREF="readline.html#TOC22">Readline vi Mode</A></H2>
1530
1531 <P>
1532 While the Readline library does not have a full set of <CODE>vi</CODE>
1533 editing functions, it does contain enough to allow simple editing
1534 of the line.  The Readline <CODE>vi</CODE> mode behaves as specified in
1535 the POSIX 1003.2 standard.
1536
1537 </P>
1538 <P>
1539 In order to switch interactively between <CODE>emacs</CODE> and <CODE>vi</CODE>
1540 editing modes, use the command M-C-j (toggle-editing-mode).
1541 The Readline default is <CODE>emacs</CODE> mode.
1542
1543 </P>
1544 <P>
1545 When you enter a line in <CODE>vi</CODE> mode, you are already placed in
1546 `insertion' mode, as if you had typed an <SAMP>`i'</SAMP>.  Pressing <KBD>ESC</KBD>
1547 switches you into `command' mode, where you can edit the text of the
1548 line with the standard <CODE>vi</CODE> movement keys, move to previous
1549 history lines with <SAMP>`k'</SAMP> and subsequent lines with <SAMP>`j'</SAMP>, and
1550 so forth.
1551
1552 </P>
1553
1554
1555
1556 <H1><A NAME="SEC23" HREF="readline.html#TOC23">Programming with GNU Readline</A></H1>
1557
1558 <P>
1559 This chapter describes the interface between the GNU Readline Library and
1560 other programs.  If you are a programmer, and you wish to include the
1561 features found in GNU Readline
1562 such as completion, line editing, and interactive history manipulation
1563 in your own programs, this section is for you.
1564
1565 </P>
1566
1567 <UL>
1568 <LI><A HREF="readline.html#SEC24">Basic Behavior</A>: Using the default behavior of Readline.
1569 <LI><A HREF="readline.html#SEC25">Custom Functions</A>: Adding your own functions to Readline.
1570 <LI><A HREF="readline.html#SEC28">Readline Variables</A>: Variables accessible to custom
1571                                         functions.
1572 <LI><A HREF="readline.html#SEC29">Readline Convenience Functions</A>: Functions which Readline supplies to
1573                                         aid in writing your own custom
1574                                         functions.
1575 <LI><A HREF="readline.html#SEC40">Readline Signal Handling</A>: How Readline behaves when it receives signals.
1576 <LI><A HREF="readline.html#SEC41">Custom Completers</A>: Supplanting or supplementing Readline's
1577                         completion functions.
1578 </UL>
1579
1580
1581
1582 <H2><A NAME="SEC24" HREF="readline.html#TOC24">Basic Behavior</A></H2>
1583
1584 <P>
1585 Many programs provide a command line interface, such as <CODE>mail</CODE>,
1586 <CODE>ftp</CODE>, and <CODE>sh</CODE>.  For such programs, the default behaviour of
1587 Readline is sufficient.  This section describes how to use Readline in
1588 the simplest way possible, perhaps to replace calls in your code to
1589 <CODE>gets()</CODE> or <CODE>fgets ()</CODE>.
1590
1591 </P>
1592 <P>
1593 <A NAME="IDX97"></A>
1594 <A NAME="IDX98"></A>
1595 The function <CODE>readline ()</CODE> prints a prompt and then reads and returns
1596 a single line of text from the user.  The line <CODE>readline</CODE>
1597 returns is allocated with <CODE>malloc ()</CODE>; you should <CODE>free ()</CODE>
1598 the line when you are done with it.  The declaration for <CODE>readline</CODE>
1599 in ANSI C is
1600
1601 </P>
1602
1603 <PRE>
1604 <CODE>char *readline (char *<VAR>prompt</VAR>);</CODE>
1605 </PRE>
1606
1607 <P>
1608 So, one might say
1609
1610 <PRE>
1611 <CODE>char *line = readline ("Enter a line: ");</CODE>
1612 </PRE>
1613
1614 <P>
1615 in order to read a line of text from the user.
1616 The line returned has the final newline removed, so only the
1617 text remains.
1618
1619 </P>
1620 <P>
1621 If <CODE>readline</CODE> encounters an <CODE>EOF</CODE> while reading the line, and the
1622 line is empty at that point, then <CODE>(char *)NULL</CODE> is returned.
1623 Otherwise, the line is ended just as if a newline had been typed.
1624
1625 </P>
1626 <P>
1627 If you want the user to be able to get at the line later, (with
1628 <KBD>C-p</KBD> for example), you must call <CODE>add_history ()</CODE> to save the
1629 line away in a <EM>history</EM> list of such lines.
1630
1631 </P>
1632
1633 <PRE>
1634 <CODE>add_history (line)</CODE>;
1635 </PRE>
1636
1637 <P>
1638 For full details on the GNU History Library, see the associated manual.
1639
1640 </P>
1641 <P>
1642 It is preferable to avoid saving empty lines on the history list, since
1643 users rarely have a burning need to reuse a blank line.  Here is
1644 a function which usefully replaces the standard <CODE>gets ()</CODE> library
1645 function, and has the advantage of no static buffer to overflow:
1646
1647 </P>
1648
1649 <PRE>
1650 /* A static variable for holding the line. */
1651 static char *line_read = (char *)NULL;
1652
1653 /* Read a string, and return a pointer to it.  Returns NULL on EOF. */
1654 char *
1655 rl_gets ()
1656 {
1657   /* If the buffer has already been allocated, return the memory
1658      to the free pool. */
1659   if (line_read)
1660     {
1661       free (line_read);
1662       line_read = (char *)NULL;
1663     }
1664
1665   /* Get a line from the user. */
1666   line_read = readline ("");
1667
1668   /* If the line has any text in it, save it on the history. */
1669   if (line_read &#38;&#38; *line_read)
1670     add_history (line_read);
1671
1672   return (line_read);
1673 }
1674 </PRE>
1675
1676 <P>
1677 This function gives the user the default behaviour of <KBD>TAB</KBD>
1678 completion: completion on file names.  If you do not want Readline to
1679 complete on filenames, you can change the binding of the <KBD>TAB</KBD> key
1680 with <CODE>rl_bind_key ()</CODE>.
1681
1682 </P>
1683
1684 <PRE>
1685 <CODE>int rl_bind_key (int <VAR>key</VAR>, int (*<VAR>function</VAR>)());</CODE>
1686 </PRE>
1687
1688 <P>
1689 <CODE>rl_bind_key ()</CODE> takes two arguments: <VAR>key</VAR> is the character that
1690 you want to bind, and <VAR>function</VAR> is the address of the function to
1691 call when <VAR>key</VAR> is pressed.  Binding <KBD>TAB</KBD> to <CODE>rl_insert ()</CODE>
1692 makes <KBD>TAB</KBD> insert itself.
1693 <CODE>rl_bind_key ()</CODE> returns non-zero if <VAR>key</VAR> is not a valid
1694 ASCII character code (between 0 and 255).
1695
1696 </P>
1697 <P>
1698 Thus, to disable the default <KBD>TAB</KBD> behavior, the following suffices:
1699
1700 <PRE>
1701 <CODE>rl_bind_key ('\t', rl_insert);</CODE>
1702 </PRE>
1703
1704 <P>
1705 This code should be executed once at the start of your program; you
1706 might write a function called <CODE>initialize_readline ()</CODE> which
1707 performs this and other desired initializations, such as installing
1708 custom completers (see section <A HREF="readline.html#SEC41">Custom Completers</A>).
1709
1710 </P>
1711
1712
1713 <H2><A NAME="SEC25" HREF="readline.html#TOC25">Custom Functions</A></H2>
1714
1715 <P>
1716 Readline provides many functions for manipulating the text of
1717 the line, but it isn't possible to anticipate the needs of all
1718 programs.  This section describes the various functions and variables
1719 defined within the Readline library which allow a user program to add
1720 customized functionality to Readline.
1721
1722 </P>
1723
1724 <UL>
1725 <LI><A HREF="readline.html#SEC26">The Function Type</A>: C declarations to make code readable.
1726 <LI><A HREF="readline.html#SEC27">Function Writing</A>: Variables and calling conventions.
1727 </UL>
1728
1729
1730
1731 <H3><A NAME="SEC26" HREF="readline.html#TOC26">The Function Type</A></H3>
1732
1733 <P>
1734 For readabilty, we declare a new type of object, called
1735 <EM>Function</EM>.  A <CODE>Function</CODE> is a C function which
1736 returns an <CODE>int</CODE>.  The type declaration for <CODE>Function</CODE> is:
1737
1738 </P>
1739 <P>
1740 <CODE>typedef int Function ();</CODE>
1741
1742 </P>
1743 <P>
1744 The reason for declaring this new type is to make it easier to write
1745 code describing pointers to C functions.  Let us say we had a variable
1746 called <VAR>func</VAR> which was a pointer to a function.  Instead of the
1747 classic C declaration
1748
1749 </P>
1750 <P>
1751 <CODE>int (*)()func;</CODE>
1752
1753 </P>
1754 <P>
1755 we may write
1756
1757 </P>
1758 <P>
1759 <CODE>Function *func;</CODE>
1760
1761 </P>
1762 <P>
1763 Similarly, there are
1764
1765 </P>
1766
1767 <PRE>
1768 typedef void VFunction ();
1769 typedef char *CPFunction (); and
1770 typedef char **CPPFunction ();
1771 </PRE>
1772
1773 <P>
1774 for functions returning no value, <CODE>pointer to char</CODE>, and
1775 <CODE>pointer to pointer to char</CODE>, respectively.
1776
1777 </P>
1778
1779
1780 <H3><A NAME="SEC27" HREF="readline.html#TOC27">Writing a New Function</A></H3>
1781
1782 <P>
1783 In order to write new functions for Readline, you need to know the
1784 calling conventions for keyboard-invoked functions, and the names of the
1785 variables that describe the current state of the line read so far.
1786
1787 </P>
1788 <P>
1789 The calling sequence for a command <CODE>foo</CODE> looks like
1790
1791 </P>
1792
1793 <PRE>
1794 <CODE>foo (int count, int key)</CODE>
1795 </PRE>
1796
1797 <P>
1798 where <VAR>count</VAR> is the numeric argument (or 1 if defaulted) and
1799 <VAR>key</VAR> is the key that invoked this function.
1800
1801 </P>
1802 <P>
1803 It is completely up to the function as to what should be done with the
1804 numeric argument.  Some functions use it as a repeat count, some
1805 as a flag, and others to choose alternate behavior (refreshing the current
1806 line as opposed to refreshing the screen, for example).  Some choose to
1807 ignore it.  In general, if a
1808 function uses the numeric argument as a repeat count, it should be able
1809 to do something useful with both negative and positive arguments.
1810 At the very least, it should be aware that it can be passed a
1811 negative argument.
1812
1813 </P>
1814
1815
1816 <H2><A NAME="SEC28" HREF="readline.html#TOC28">Readline Variables</A></H2>
1817
1818 <P>
1819 These variables are available to function writers.
1820
1821 </P>
1822 <P>
1823 <DL>
1824 <DT><U>Variable:</U> char * <B>rl_line_buffer</B>
1825 <DD><A NAME="IDX99"></A>
1826 This is the line gathered so far.  You are welcome to modify the
1827 contents of the line, but see section <A HREF="readline.html#SEC34">Allowing Undoing</A>.
1828 </DL>
1829
1830 </P>
1831 <P>
1832 <DL>
1833 <DT><U>Variable:</U> int <B>rl_point</B>
1834 <DD><A NAME="IDX100"></A>
1835 The offset of the current cursor position in <CODE>rl_line_buffer</CODE>
1836 (the <EM>point</EM>).
1837 </DL>
1838
1839 </P>
1840 <P>
1841 <DL>
1842 <DT><U>Variable:</U> int <B>rl_end</B>
1843 <DD><A NAME="IDX101"></A>
1844 The number of characters present in <CODE>rl_line_buffer</CODE>.  When
1845 <CODE>rl_point</CODE> is at the end of the line, <CODE>rl_point</CODE> and
1846 <CODE>rl_end</CODE> are equal.
1847 </DL>
1848
1849 </P>
1850 <P>
1851 <DL>
1852 <DT><U>Variable:</U> int <B>rl_mark</B>
1853 <DD><A NAME="IDX102"></A>
1854 The mark (saved position) in the current line.  If set, the mark
1855 and point define a <EM>region</EM>.
1856 </DL>
1857
1858 </P>
1859 <P>
1860 <DL>
1861 <DT><U>Variable:</U> int <B>rl_done</B>
1862 <DD><A NAME="IDX103"></A>
1863 Setting this to a non-zero value causes Readline to return the current
1864 line immediately.
1865 </DL>
1866
1867 </P>
1868 <P>
1869 <DL>
1870 <DT><U>Variable:</U> int <B>rl_pending_input</B>
1871 <DD><A NAME="IDX104"></A>
1872 Setting this to a value makes it the next keystroke read.  This is a
1873 way to stuff a single character into the input stream.
1874 </DL>
1875
1876 </P>
1877 <P>
1878 <DL>
1879 <DT><U>Variable:</U> int <B>rl_erase_empty_line</B>
1880 <DD><A NAME="IDX105"></A>
1881 Setting this to a non-zero value causes Readline to completely erase
1882 the current line, including any prompt, any time a newline is typed as
1883 the only character on an otherwise-empty line.  The cursor is moved to
1884 the beginning of the newly-blank line.
1885 </DL>
1886
1887 </P>
1888 <P>
1889 <DL>
1890 <DT><U>Variable:</U> char * <B>rl_prompt</B>
1891 <DD><A NAME="IDX106"></A>
1892 The prompt Readline uses.  This is set from the argument to
1893 <CODE>readline ()</CODE>, and should not be assigned to directly.
1894 </DL>
1895
1896 </P>
1897 <P>
1898 <DL>
1899 <DT><U>Variable:</U> char * <B>rl_library_version</B>
1900 <DD><A NAME="IDX107"></A>
1901 The version number of this revision of the library.
1902 </DL>
1903
1904 </P>
1905 <P>
1906 <DL>
1907 <DT><U>Variable:</U> char * <B>rl_terminal_name</B>
1908 <DD><A NAME="IDX108"></A>
1909 The terminal type, used for initialization.
1910 </DL>
1911
1912 </P>
1913 <P>
1914 <DL>
1915 <DT><U>Variable:</U> char * <B>rl_readline_name</B>
1916 <DD><A NAME="IDX109"></A>
1917 This variable is set to a unique name by each application using Readline.
1918 The value allows conditional parsing of the inputrc file
1919 (see section <A HREF="readline.html#SEC11">Conditional Init Constructs</A>).
1920 </DL>
1921
1922 </P>
1923 <P>
1924 <DL>
1925 <DT><U>Variable:</U> FILE * <B>rl_instream</B>
1926 <DD><A NAME="IDX110"></A>
1927 The stdio stream from which Readline reads input.
1928 </DL>
1929
1930 </P>
1931 <P>
1932 <DL>
1933 <DT><U>Variable:</U> FILE * <B>rl_outstream</B>
1934 <DD><A NAME="IDX111"></A>
1935 The stdio stream to which Readline performs output.
1936 </DL>
1937
1938 </P>
1939 <P>
1940 <DL>
1941 <DT><U>Variable:</U> Function * <B>rl_startup_hook</B>
1942 <DD><A NAME="IDX112"></A>
1943 If non-zero, this is the address of a function to call just
1944 before <CODE>readline</CODE> prints the first prompt.
1945 </DL>
1946
1947 </P>
1948 <P>
1949 <DL>
1950 <DT><U>Variable:</U> Function * <B>rl_pre_input_hook</B>
1951 <DD><A NAME="IDX113"></A>
1952 If non-zero, this is the address of a function to call after
1953 the first prompt has been printed and just before <CODE>readline</CODE>
1954 starts reading input characters.
1955 </DL>
1956
1957 </P>
1958 <P>
1959 <DL>
1960 <DT><U>Variable:</U> Function * <B>rl_event_hook</B>
1961 <DD><A NAME="IDX114"></A>
1962 If non-zero, this is the address of a function to call periodically
1963 when readline is waiting for terminal input.
1964 </DL>
1965
1966 </P>
1967 <P>
1968 <DL>
1969 <DT><U>Variable:</U> Function * <B>rl_getc_function</B>
1970 <DD><A NAME="IDX115"></A>
1971 If non-zero, <CODE>readline</CODE> will call indirectly through this pointer
1972 to get a character from the input stream.  By default, it is set to
1973 <CODE>rl_getc</CODE>, the default <CODE>readline</CODE> character input function
1974 (see section <A HREF="readline.html#SEC37">Utility Functions</A>).
1975 </DL>
1976
1977 </P>
1978 <P>
1979 <DL>
1980 <DT><U>Variable:</U> VFunction * <B>rl_redisplay_function</B>
1981 <DD><A NAME="IDX116"></A>
1982 If non-zero, <CODE>readline</CODE> will call indirectly through this pointer
1983 to update the display with the current contents of the editing buffer.
1984 By default, it is set to <CODE>rl_redisplay</CODE>, the default <CODE>readline</CODE>
1985 redisplay function (see section <A HREF="readline.html#SEC35">Redisplay</A>).
1986 </DL>
1987
1988 </P>
1989 <P>
1990 <DL>
1991 <DT><U>Variable:</U> Keymap <B>rl_executing_keymap</B>
1992 <DD><A NAME="IDX117"></A>
1993 This variable is set to the keymap (see section <A HREF="readline.html#SEC31">Selecting a Keymap</A>) in which the
1994 currently executing readline function was found.
1995 </DL>
1996
1997 </P>
1998 <P>
1999 <DL>
2000 <DT><U>Variable:</U> Keymap <B>rl_binding_keymap</B>
2001 <DD><A NAME="IDX118"></A>
2002 This variable is set to the keymap (see section <A HREF="readline.html#SEC31">Selecting a Keymap</A>) in which the
2003 last key binding occurred.
2004 </DL>
2005
2006 </P>
2007
2008
2009 <H2><A NAME="SEC29" HREF="readline.html#TOC29">Readline Convenience Functions</A></H2>
2010
2011
2012 <UL>
2013 <LI><A HREF="readline.html#SEC30">Function Naming</A>: How to give a function you write a name.
2014 <LI><A HREF="readline.html#SEC31">Keymaps</A>: Making keymaps.
2015 <LI><A HREF="readline.html#SEC32">Binding Keys</A>: Changing Keymaps.
2016 <LI><A HREF="readline.html#SEC33">Associating Function Names and Bindings</A>: Translate function names to
2017                                                 key sequences.
2018 <LI><A HREF="readline.html#SEC34">Allowing Undoing</A>: How to make your functions undoable.
2019 <LI><A HREF="readline.html#SEC35">Redisplay</A>: Functions to control line display.
2020 <LI><A HREF="readline.html#SEC36">Modifying Text</A>: Functions to modify <CODE>rl_line_buffer</CODE>.
2021 <LI><A HREF="readline.html#SEC37">Utility Functions</A>: Generally useful functions and hooks.
2022 <LI><A HREF="readline.html#SEC38">Alternate Interface</A>: Using Readline in a `callback' fashion.
2023 </UL>
2024
2025
2026
2027 <H3><A NAME="SEC30" HREF="readline.html#TOC30">Naming a Function</A></H3>
2028
2029 <P>
2030 The user can dynamically change the bindings of keys while using
2031 Readline.  This is done by representing the function with a descriptive
2032 name.  The user is able to type the descriptive name when referring to
2033 the function.  Thus, in an init file, one might find
2034
2035 </P>
2036
2037 <PRE>
2038 Meta-Rubout:    backward-kill-word
2039 </PRE>
2040
2041 <P>
2042 This binds the keystroke <KBD>Meta-Rubout</KBD> to the function
2043 <EM>descriptively</EM> named <CODE>backward-kill-word</CODE>.  You, as the
2044 programmer, should bind the functions you write to descriptive names as
2045 well.  Readline provides a function for doing that:
2046
2047 </P>
2048 <P>
2049 <DL>
2050 <DT><U>Function:</U> int <B>rl_add_defun</B> <I>(char *name, Function *function, int key)</I>
2051 <DD><A NAME="IDX119"></A>
2052 Add <VAR>name</VAR> to the list of named functions.  Make <VAR>function</VAR> be
2053 the function that gets called.  If <VAR>key</VAR> is not -1, then bind it to
2054 <VAR>function</VAR> using <CODE>rl_bind_key ()</CODE>.
2055 </DL>
2056
2057 </P>
2058 <P>
2059 Using this function alone is sufficient for most applications.  It is
2060 the recommended way to add a few functions to the default functions that
2061 Readline has built in.  If you need to do something other
2062 than adding a function to Readline, you may need to use the
2063 underlying functions described below.
2064
2065 </P>
2066
2067
2068 <H3><A NAME="SEC31" HREF="readline.html#TOC31">Selecting a Keymap</A></H3>
2069
2070 <P>
2071 Key bindings take place on a <EM>keymap</EM>.  The keymap is the
2072 association between the keys that the user types and the functions that
2073 get run.  You can make your own keymaps, copy existing keymaps, and tell
2074 Readline which keymap to use.
2075
2076 </P>
2077 <P>
2078 <DL>
2079 <DT><U>Function:</U> Keymap <B>rl_make_bare_keymap</B> <I>()</I>
2080 <DD><A NAME="IDX120"></A>
2081 Returns a new, empty keymap.  The space for the keymap is allocated with
2082 <CODE>malloc ()</CODE>; you should <CODE>free ()</CODE> it when you are done.
2083 </DL>
2084
2085 </P>
2086 <P>
2087 <DL>
2088 <DT><U>Function:</U> Keymap <B>rl_copy_keymap</B> <I>(Keymap map)</I>
2089 <DD><A NAME="IDX121"></A>
2090 Return a new keymap which is a copy of <VAR>map</VAR>.
2091 </DL>
2092
2093 </P>
2094 <P>
2095 <DL>
2096 <DT><U>Function:</U> Keymap <B>rl_make_keymap</B> <I>()</I>
2097 <DD><A NAME="IDX122"></A>
2098 Return a new keymap with the printing characters bound to rl_insert,
2099 the lowercase Meta characters bound to run their equivalents, and
2100 the Meta digits bound to produce numeric arguments.
2101 </DL>
2102
2103 </P>
2104 <P>
2105 <DL>
2106 <DT><U>Function:</U> void <B>rl_discard_keymap</B> <I>(Keymap keymap)</I>
2107 <DD><A NAME="IDX123"></A>
2108 Free the storage associated with <VAR>keymap</VAR>.
2109 </DL>
2110
2111 </P>
2112 <P>
2113 Readline has several internal keymaps.  These functions allow you to
2114 change which keymap is active.
2115
2116 </P>
2117 <P>
2118 <DL>
2119 <DT><U>Function:</U> Keymap <B>rl_get_keymap</B> <I>()</I>
2120 <DD><A NAME="IDX124"></A>
2121 Returns the currently active keymap.
2122 </DL>
2123
2124 </P>
2125 <P>
2126 <DL>
2127 <DT><U>Function:</U> void <B>rl_set_keymap</B> <I>(Keymap keymap)</I>
2128 <DD><A NAME="IDX125"></A>
2129 Makes <VAR>keymap</VAR> the currently active keymap.
2130 </DL>
2131
2132 </P>
2133 <P>
2134 <DL>
2135 <DT><U>Function:</U> Keymap <B>rl_get_keymap_by_name</B> <I>(char *name)</I>
2136 <DD><A NAME="IDX126"></A>
2137 Return the keymap matching <VAR>name</VAR>.  <VAR>name</VAR> is one which would
2138 be supplied in a <CODE>set keymap</CODE> inputrc line (see section <A HREF="readline.html#SEC9">Readline Init File</A>).
2139 </DL>
2140
2141 </P>
2142 <P>
2143 <DL>
2144 <DT><U>Function:</U> char * <B>rl_get_keymap_name</B> <I>(Keymap keymap)</I>
2145 <DD><A NAME="IDX127"></A>
2146 Return the name matching <VAR>keymap</VAR>.  <VAR>name</VAR> is one which would
2147 be supplied in a <CODE>set keymap</CODE> inputrc line (see section <A HREF="readline.html#SEC9">Readline Init File</A>).
2148 </DL>
2149
2150 </P>
2151
2152
2153 <H3><A NAME="SEC32" HREF="readline.html#TOC32">Binding Keys</A></H3>
2154
2155 <P>
2156 You associate keys with functions through the keymap.  Readline has
2157 several internal keymaps: <CODE>emacs_standard_keymap</CODE>,
2158 <CODE>emacs_meta_keymap</CODE>, <CODE>emacs_ctlx_keymap</CODE>,
2159 <CODE>vi_movement_keymap</CODE>, and <CODE>vi_insertion_keymap</CODE>.
2160 <CODE>emacs_standard_keymap</CODE> is the default, and the examples in
2161 this manual assume that.
2162
2163 </P>
2164 <P>
2165 These functions manage key bindings.
2166
2167 </P>
2168 <P>
2169 <DL>
2170 <DT><U>Function:</U> int <B>rl_bind_key</B> <I>(int key, Function *function)</I>
2171 <DD><A NAME="IDX128"></A>
2172 Binds <VAR>key</VAR> to <VAR>function</VAR> in the currently active keymap.
2173 Returns non-zero in the case of an invalid <VAR>key</VAR>.
2174 </DL>
2175
2176 </P>
2177 <P>
2178 <DL>
2179 <DT><U>Function:</U> int <B>rl_bind_key_in_map</B> <I>(int key, Function *function, Keymap map)</I>
2180 <DD><A NAME="IDX129"></A>
2181 Bind <VAR>key</VAR> to <VAR>function</VAR> in <VAR>map</VAR>.  Returns non-zero in the case
2182 of an invalid <VAR>key</VAR>.
2183 </DL>
2184
2185 </P>
2186 <P>
2187 <DL>
2188 <DT><U>Function:</U> int <B>rl_unbind_key</B> <I>(int key)</I>
2189 <DD><A NAME="IDX130"></A>
2190 Bind <VAR>key</VAR> to the null function in the currently active keymap.
2191 Returns non-zero in case of error.
2192 </DL>
2193
2194 </P>
2195 <P>
2196 <DL>
2197 <DT><U>Function:</U> int <B>rl_unbind_key_in_map</B> <I>(int key, Keymap map)</I>
2198 <DD><A NAME="IDX131"></A>
2199 Bind <VAR>key</VAR> to the null function in <VAR>map</VAR>.
2200 Returns non-zero in case of error.
2201 </DL>
2202
2203 </P>
2204 <P>
2205 <DL>
2206 <DT><U>Function:</U> int <B>rl_unbind_function_in_map</B> <I>(Function *function, Keymap map)</I>
2207 <DD><A NAME="IDX132"></A>
2208 Unbind all keys that execute <VAR>function</VAR> in <VAR>map</VAR>.
2209 </DL>
2210
2211 </P>
2212 <P>
2213 <DL>
2214 <DT><U>Function:</U> int <B>rl_unbind_command_in_map</B> <I>(char *command, Keymap map)</I>
2215 <DD><A NAME="IDX133"></A>
2216 Unbind all keys that are bound to <VAR>command</VAR> in <VAR>map</VAR>.
2217 </DL>
2218
2219 </P>
2220 <P>
2221 <DL>
2222 <DT><U>Function:</U> int <B>rl_generic_bind</B> <I>(int type, char *keyseq, char *data, Keymap map)</I>
2223 <DD><A NAME="IDX134"></A>
2224 Bind the key sequence represented by the string <VAR>keyseq</VAR> to the arbitrary
2225 pointer <VAR>data</VAR>.  <VAR>type</VAR> says what kind of data is pointed to by
2226 <VAR>data</VAR>; this can be a function (<CODE>ISFUNC</CODE>), a macro
2227 (<CODE>ISMACR</CODE>), or a keymap (<CODE>ISKMAP</CODE>).  This makes new keymaps as
2228 necessary.  The initial keymap in which to do bindings is <VAR>map</VAR>.
2229 </DL>
2230
2231 </P>
2232 <P>
2233 <DL>
2234 <DT><U>Function:</U> int <B>rl_parse_and_bind</B> <I>(char *line)</I>
2235 <DD><A NAME="IDX135"></A>
2236 Parse <VAR>line</VAR> as if it had been read from the <CODE>inputrc</CODE> file and
2237 perform any key bindings and variable assignments found
2238 (see section <A HREF="readline.html#SEC9">Readline Init File</A>).
2239 </DL>
2240
2241 </P>
2242 <P>
2243 <DL>
2244 <DT><U>Function:</U> int <B>rl_read_init_file</B> <I>(char *filename)</I>
2245 <DD><A NAME="IDX136"></A>
2246 Read keybindings and variable assignments from <VAR>filename</VAR>
2247 (see section <A HREF="readline.html#SEC9">Readline Init File</A>).
2248 </DL>
2249
2250 </P>
2251
2252
2253 <H3><A NAME="SEC33" HREF="readline.html#TOC33">Associating Function Names and Bindings</A></H3>
2254
2255 <P>
2256 These functions allow you to find out what keys invoke named functions
2257 and the functions invoked by a particular key sequence.
2258
2259 </P>
2260 <P>
2261 <DL>
2262 <DT><U>Function:</U> Function * <B>rl_named_function</B> <I>(char *name)</I>
2263 <DD><A NAME="IDX137"></A>
2264 Return the function with name <VAR>name</VAR>.
2265 </DL>
2266
2267 </P>
2268 <P>
2269 <DL>
2270 <DT><U>Function:</U> Function * <B>rl_function_of_keyseq</B> <I>(char *keyseq, Keymap map, int *type)</I>
2271 <DD><A NAME="IDX138"></A>
2272 Return the function invoked by <VAR>keyseq</VAR> in keymap <VAR>map</VAR>.
2273 If <VAR>map</VAR> is NULL, the current keymap is used.  If <VAR>type</VAR> is
2274 not NULL, the type of the object is returned in it (one of <CODE>ISFUNC</CODE>,
2275 <CODE>ISKMAP</CODE>, or <CODE>ISMACR</CODE>).
2276 </DL>
2277
2278 </P>
2279 <P>
2280 <DL>
2281 <DT><U>Function:</U> char ** <B>rl_invoking_keyseqs</B> <I>(Function *function)</I>
2282 <DD><A NAME="IDX139"></A>
2283 Return an array of strings representing the key sequences used to
2284 invoke <VAR>function</VAR> in the current keymap.
2285 </DL>
2286
2287 </P>
2288 <P>
2289 <DL>
2290 <DT><U>Function:</U> char ** <B>rl_invoking_keyseqs_in_map</B> <I>(Function *function, Keymap map)</I>
2291 <DD><A NAME="IDX140"></A>
2292 Return an array of strings representing the key sequences used to
2293 invoke <VAR>function</VAR> in the keymap <VAR>map</VAR>.
2294 </DL>
2295
2296 </P>
2297 <P>
2298 <DL>
2299 <DT><U>Function:</U> void <B>rl_function_dumper</B> <I>(int readable)</I>
2300 <DD><A NAME="IDX141"></A>
2301 Print the readline function names and the key sequences currently
2302 bound to them to <CODE>rl_outstream</CODE>.  If <VAR>readable</VAR> is non-zero,
2303 the list is formatted in such a way that it can be made part of an
2304 <CODE>inputrc</CODE> file and re-read.
2305 </DL>
2306
2307 </P>
2308 <P>
2309 <DL>
2310 <DT><U>Function:</U> void <B>rl_list_funmap_names</B> <I>()</I>
2311 <DD><A NAME="IDX142"></A>
2312 Print the names of all bindable Readline functions to <CODE>rl_outstream</CODE>.
2313 </DL>
2314
2315 </P>
2316
2317
2318 <H3><A NAME="SEC34" HREF="readline.html#TOC34">Allowing Undoing</A></H3>
2319
2320 <P>
2321 Supporting the undo command is a painless thing, and makes your
2322 functions much more useful.  It is certainly easy to try
2323 something if you know you can undo it.  I could use an undo function for
2324 the stock market.
2325
2326 </P>
2327 <P>
2328 If your function simply inserts text once, or deletes text once, and
2329 uses <CODE>rl_insert_text ()</CODE> or <CODE>rl_delete_text ()</CODE> to do it, then
2330 undoing is already done for you automatically.
2331
2332 </P>
2333 <P>
2334 If you do multiple insertions or multiple deletions, or any combination
2335 of these operations, you should group them together into one operation.
2336 This is done with <CODE>rl_begin_undo_group ()</CODE> and
2337 <CODE>rl_end_undo_group ()</CODE>.
2338
2339 </P>
2340 <P>
2341 The types of events that can be undone are:
2342
2343 </P>
2344
2345 <PRE>
2346 enum undo_code { UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END };
2347 </PRE>
2348
2349 <P>
2350 Notice that <CODE>UNDO_DELETE</CODE> means to insert some text, and
2351 <CODE>UNDO_INSERT</CODE> means to delete some text.  That is, the undo code
2352 tells undo what to undo, not how to undo it.  <CODE>UNDO_BEGIN</CODE> and
2353 <CODE>UNDO_END</CODE> are tags added by <CODE>rl_begin_undo_group ()</CODE> and
2354 <CODE>rl_end_undo_group ()</CODE>.
2355
2356 </P>
2357 <P>
2358 <DL>
2359 <DT><U>Function:</U> int <B>rl_begin_undo_group</B> <I>()</I>
2360 <DD><A NAME="IDX143"></A>
2361 Begins saving undo information in a group construct.  The undo
2362 information usually comes from calls to <CODE>rl_insert_text ()</CODE> and
2363 <CODE>rl_delete_text ()</CODE>, but could be the result of calls to
2364 <CODE>rl_add_undo ()</CODE>.
2365 </DL>
2366
2367 </P>
2368 <P>
2369 <DL>
2370 <DT><U>Function:</U> int <B>rl_end_undo_group</B> <I>()</I>
2371 <DD><A NAME="IDX144"></A>
2372 Closes the current undo group started with <CODE>rl_begin_undo_group
2373 ()</CODE>.  There should be one call to <CODE>rl_end_undo_group ()</CODE>
2374 for each call to <CODE>rl_begin_undo_group ()</CODE>.
2375 </DL>
2376
2377 </P>
2378 <P>
2379 <DL>
2380 <DT><U>Function:</U> void <B>rl_add_undo</B> <I>(enum undo_code what, int start, int end, char *text)</I>
2381 <DD><A NAME="IDX145"></A>
2382 Remember how to undo an event (according to <VAR>what</VAR>).  The affected
2383 text runs from <VAR>start</VAR> to <VAR>end</VAR>, and encompasses <VAR>text</VAR>.
2384 </DL>
2385
2386 </P>
2387 <P>
2388 <DL>
2389 <DT><U>Function:</U> void <B>free_undo_list</B> <I>()</I>
2390 <DD><A NAME="IDX146"></A>
2391 Free the existing undo list.
2392 </DL>
2393
2394 </P>
2395 <P>
2396 <DL>
2397 <DT><U>Function:</U> int <B>rl_do_undo</B> <I>()</I>
2398 <DD><A NAME="IDX147"></A>
2399 Undo the first thing on the undo list.  Returns <CODE>0</CODE> if there was
2400 nothing to undo, non-zero if something was undone.
2401 </DL>
2402
2403 </P>
2404 <P>
2405 Finally, if you neither insert nor delete text, but directly modify the
2406 existing text (e.g., change its case), call <CODE>rl_modifying ()</CODE>
2407 once, just before you modify the text.  You must supply the indices of
2408 the text range that you are going to modify.
2409
2410 </P>
2411 <P>
2412 <DL>
2413 <DT><U>Function:</U> int <B>rl_modifying</B> <I>(int start, int end)</I>
2414 <DD><A NAME="IDX148"></A>
2415 Tell Readline to save the text between <VAR>start</VAR> and <VAR>end</VAR> as a
2416 single undo unit.  It is assumed that you will subsequently modify
2417 that text.
2418 </DL>
2419
2420 </P>
2421
2422
2423 <H3><A NAME="SEC35" HREF="readline.html#TOC35">Redisplay</A></H3>
2424
2425 <P>
2426 <DL>
2427 <DT><U>Function:</U> void <B>rl_redisplay</B> <I>()</I>
2428 <DD><A NAME="IDX149"></A>
2429 Change what's displayed on the screen to reflect the current contents
2430 of <CODE>rl_line_buffer</CODE>.
2431 </DL>
2432
2433 </P>
2434 <P>
2435 <DL>
2436 <DT><U>Function:</U> int <B>rl_forced_update_display</B> <I>()</I>
2437 <DD><A NAME="IDX150"></A>
2438 Force the line to be updated and redisplayed, whether or not
2439 Readline thinks the screen display is correct.
2440 </DL>
2441
2442 </P>
2443 <P>
2444 <DL>
2445 <DT><U>Function:</U> int <B>rl_on_new_line</B> <I>()</I>
2446 <DD><A NAME="IDX151"></A>
2447 Tell the update routines that we have moved onto a new (empty) line,
2448 usually after ouputting a newline.
2449 </DL>
2450
2451 </P>
2452 <P>
2453 <DL>
2454 <DT><U>Function:</U> int <B>rl_reset_line_state</B> <I>()</I>
2455 <DD><A NAME="IDX152"></A>
2456 Reset the display state to a clean state and redisplay the current line
2457 starting on a new line.
2458 </DL>
2459
2460 </P>
2461 <P>
2462 <DL>
2463 <DT><U>Function:</U> int <B>rl_message</B> <I>(va_alist)</I>
2464 <DD><A NAME="IDX153"></A>
2465 The arguments are a string as would be supplied to <CODE>printf</CODE>.  The
2466 resulting string is displayed in the <EM>echo area</EM>.  The echo area
2467 is also used to display numeric arguments and search strings.
2468 </DL>
2469
2470 </P>
2471 <P>
2472 <DL>
2473 <DT><U>Function:</U> int <B>rl_clear_message</B> <I>()</I>
2474 <DD><A NAME="IDX154"></A>
2475 Clear the message in the echo area.
2476 </DL>
2477
2478 </P>
2479 <P>
2480 <DL>
2481 <DT><U>Function:</U> void <B>rl_save_prompt</B> <I>()</I>
2482 <DD><A NAME="IDX155"></A>
2483 Save the local Readline prompt display state in preparation for
2484 displaying a new message in the message area with <CODE>rl_message</CODE>.
2485 </DL>
2486
2487 </P>
2488 <P>
2489 <DL>
2490 <DT><U>Function:</U> void <B>rl_restore_prompt</B> <I>()</I>
2491 <DD><A NAME="IDX156"></A>
2492 Restore the local Readline prompt display state saved by the most
2493 recent call to <CODE>rl_save_prompt</CODE>.
2494 </DL>
2495
2496 </P>
2497
2498
2499 <H3><A NAME="SEC36" HREF="readline.html#TOC36">Modifying Text</A></H3>
2500
2501 <P>
2502 <DL>
2503 <DT><U>Function:</U> int <B>rl_insert_text</B> <I>(char *text)</I>
2504 <DD><A NAME="IDX157"></A>
2505 Insert <VAR>text</VAR> into the line at the current cursor position.
2506 </DL>
2507
2508 </P>
2509 <P>
2510 <DL>
2511 <DT><U>Function:</U> int <B>rl_delete_text</B> <I>(int start, int end)</I>
2512 <DD><A NAME="IDX158"></A>
2513 Delete the text between <VAR>start</VAR> and <VAR>end</VAR> in the current line.
2514 </DL>
2515
2516 </P>
2517 <P>
2518 <DL>
2519 <DT><U>Function:</U> char * <B>rl_copy_text</B> <I>(int start, int end)</I>
2520 <DD><A NAME="IDX159"></A>
2521 Return a copy of the text between <VAR>start</VAR> and <VAR>end</VAR> in
2522 the current line.
2523 </DL>
2524
2525 </P>
2526 <P>
2527 <DL>
2528 <DT><U>Function:</U> int <B>rl_kill_text</B> <I>(int start, int end)</I>
2529 <DD><A NAME="IDX160"></A>
2530 Copy the text between <VAR>start</VAR> and <VAR>end</VAR> in the current line
2531 to the kill ring, appending or prepending to the last kill if the
2532 last command was a kill command.  The text is deleted.
2533 If <VAR>start</VAR> is less than <VAR>end</VAR>,
2534 the text is appended, otherwise prepended.  If the last command was
2535 not a kill, a new kill ring slot is used.
2536 </DL>
2537
2538 </P>
2539
2540
2541 <H3><A NAME="SEC37" HREF="readline.html#TOC37">Utility Functions</A></H3>
2542
2543 <P>
2544 <DL>
2545 <DT><U>Function:</U> int <B>rl_read_key</B> <I>()</I>
2546 <DD><A NAME="IDX161"></A>
2547 Return the next character available.  This handles input inserted into
2548 the input stream via <VAR>pending input</VAR> (see section <A HREF="readline.html#SEC28">Readline Variables</A>)
2549 and <CODE>rl_stuff_char ()</CODE>, macros, and characters read from the keyboard.
2550 </DL>
2551
2552 </P>
2553 <P>
2554 <DL>
2555 <DT><U>Function:</U> int <B>rl_getc</B> <I>(FILE *)</I>
2556 <DD><A NAME="IDX162"></A>
2557 Return the next character available from the keyboard.
2558 </DL>
2559
2560 </P>
2561 <P>
2562 <DL>
2563 <DT><U>Function:</U> int <B>rl_stuff_char</B> <I>(int c)</I>
2564 <DD><A NAME="IDX163"></A>
2565 Insert <VAR>c</VAR> into the Readline input stream.  It will be "read"
2566 before Readline attempts to read characters from the terminal with
2567 <CODE>rl_read_key ()</CODE>.
2568 </DL>
2569
2570 </P>
2571 <P>
2572 <DL>
2573 <DT><U>Function:</U> rl_extend_line_buffer <B>(int</B> <I>len)</I>
2574 <DD><A NAME="IDX164"></A>
2575 Ensure that <CODE>rl_line_buffer</CODE> has enough space to hold <VAR>len</VAR>
2576 characters, possibly reallocating it if necessary.
2577 </DL>
2578
2579 </P>
2580 <P>
2581 <DL>
2582 <DT><U>Function:</U> int <B>rl_initialize</B> <I>()</I>
2583 <DD><A NAME="IDX165"></A>
2584 Initialize or re-initialize Readline's internal state.
2585 </DL>
2586
2587 </P>
2588 <P>
2589 <DL>
2590 <DT><U>Function:</U> int <B>rl_reset_terminal</B> <I>(char *terminal_name)</I>
2591 <DD><A NAME="IDX166"></A>
2592 Reinitialize Readline's idea of the terminal settings using
2593 <VAR>terminal_name</VAR> as the terminal type (e.g., <CODE>vt100</CODE>).
2594 </DL>
2595
2596 </P>
2597 <P>
2598 <DL>
2599 <DT><U>Function:</U> int <B>alphabetic</B> <I>(int c)</I>
2600 <DD><A NAME="IDX167"></A>
2601 Return 1 if <VAR>c</VAR> is an alphabetic character.
2602 </DL>
2603
2604 </P>
2605 <P>
2606 <DL>
2607 <DT><U>Function:</U> int <B>numeric</B> <I>(int c)</I>
2608 <DD><A NAME="IDX168"></A>
2609 Return 1 if <VAR>c</VAR> is a numeric character.
2610 </DL>
2611
2612 </P>
2613 <P>
2614 <DL>
2615 <DT><U>Function:</U> int <B>ding</B> <I>()</I>
2616 <DD><A NAME="IDX169"></A>
2617 Ring the terminal bell, obeying the setting of <CODE>bell-style</CODE>.
2618 </DL>
2619
2620 </P>
2621 <P>
2622 <DL>
2623 <DT><U>Function:</U> void <B>rl_display_match_list</B> <I>(char **matches, int len, int max)</I>
2624 <DD><A NAME="IDX170"></A>
2625 A convenience function for displaying a list of strings in
2626 columnar format on Readline's output stream.  <CODE>matches</CODE> is the list
2627 of strings, in argv format, such as a list of completion matches.
2628 <CODE>len</CODE> is the number of strings in <CODE>matches</CODE>, and <CODE>max</CODE>
2629 is the length of the longest string in <CODE>matches</CODE>.  This function uses
2630 the setting of <CODE>print-completions-horizontally</CODE> to select how the
2631 matches are displayed (see section <A HREF="readline.html#SEC10">Readline Init File Syntax</A>).
2632 </DL>
2633
2634 </P>
2635 <P>
2636 The following are implemented as macros, defined in <CODE>chartypes.h</CODE>.
2637
2638 </P>
2639 <P>
2640 <DL>
2641 <DT><U>Function:</U> int <B>uppercase_p</B> <I>(int c)</I>
2642 <DD><A NAME="IDX171"></A>
2643 Return 1 if <VAR>c</VAR> is an uppercase alphabetic character.
2644 </DL>
2645
2646 </P>
2647 <P>
2648 <DL>
2649 <DT><U>Function:</U> int <B>lowercase_p</B> <I>(int c)</I>
2650 <DD><A NAME="IDX172"></A>
2651 Return 1 if <VAR>c</VAR> is a lowercase alphabetic character.
2652 </DL>
2653
2654 </P>
2655 <P>
2656 <DL>
2657 <DT><U>Function:</U> int <B>digit_p</B> <I>(int c)</I>
2658 <DD><A NAME="IDX173"></A>
2659 Return 1 if <VAR>c</VAR> is a numeric character.
2660 </DL>
2661
2662 </P>
2663 <P>
2664 <DL>
2665 <DT><U>Function:</U> int <B>to_upper</B> <I>(int c)</I>
2666 <DD><A NAME="IDX174"></A>
2667 If <VAR>c</VAR> is a lowercase alphabetic character, return the corresponding
2668 uppercase character.
2669 </DL>
2670
2671 </P>
2672 <P>
2673 <DL>
2674 <DT><U>Function:</U> int <B>to_lower</B> <I>(int c)</I>
2675 <DD><A NAME="IDX175"></A>
2676 If <VAR>c</VAR> is an uppercase alphabetic character, return the corresponding
2677 lowercase character.
2678 </DL>
2679
2680 </P>
2681 <P>
2682 <DL>
2683 <DT><U>Function:</U> int <B>digit_value</B> <I>(int c)</I>
2684 <DD><A NAME="IDX176"></A>
2685 If <VAR>c</VAR> is a number, return the value it represents.
2686 </DL>
2687
2688 </P>
2689
2690
2691 <H3><A NAME="SEC38" HREF="readline.html#TOC38">Alternate Interface</A></H3>
2692
2693 <P>
2694 An alternate interface is available to plain <CODE>readline()</CODE>.  Some
2695 applications need to interleave keyboard I/O with file, device, or
2696 window system I/O, typically by using a main loop to <CODE>select()</CODE>
2697 on various file descriptors.  To accomodate this need, readline can
2698 also be invoked as a `callback' function from an event loop.  There
2699 are functions available to make this easy.
2700
2701 </P>
2702 <P>
2703 <DL>
2704 <DT><U>Function:</U> void <B>rl_callback_handler_install</B> <I>(char *prompt, Vfunction *lhandler)</I>
2705 <DD><A NAME="IDX177"></A>
2706 Set up the terminal for readline I/O and display the initial
2707 expanded value of <VAR>prompt</VAR>.  Save the value of <VAR>lhandler</VAR> to
2708 use as a callback when a complete line of input has been entered.
2709 </DL>
2710
2711 </P>
2712 <P>
2713 <DL>
2714 <DT><U>Function:</U> void <B>rl_callback_read_char</B> <I>()</I>
2715 <DD><A NAME="IDX178"></A>
2716 Whenever an application determines that keyboard input is available, it
2717 should call <CODE>rl_callback_read_char()</CODE>, which will read the next
2718 character from the current input source.  If that character completes the
2719 line, <CODE>rl_callback_read_char</CODE> will invoke the <VAR>lhandler</VAR>
2720 function saved by <CODE>rl_callback_handler_install</CODE> to process the
2721 line.  <CODE>EOF</CODE> is  indicated by calling <VAR>lhandler</VAR> with a
2722 <CODE>NULL</CODE> line.
2723 </DL>
2724
2725 </P>
2726 <P>
2727 <DL>
2728 <DT><U>Function:</U> void <B>rl_callback_handler_remove</B> <I>()</I>
2729 <DD><A NAME="IDX179"></A>
2730 Restore the terminal to its initial state and remove the line handler.
2731 This may be called from within a callback as well as independently.
2732 </DL>
2733
2734 </P>
2735
2736
2737 <H3><A NAME="SEC39" HREF="readline.html#TOC39">An Example</A></H3>
2738
2739 <P>
2740 Here is a function which changes lowercase characters to their uppercase
2741 equivalents, and uppercase characters to lowercase.  If
2742 this function was bound to <SAMP>`M-c'</SAMP>, then typing <SAMP>`M-c'</SAMP> would
2743 change the case of the character under point.  Typing <SAMP>`M-1 0 M-c'</SAMP>
2744 would change the case of the following 10 characters, leaving the cursor on
2745 the last character changed.
2746
2747 </P>
2748
2749 <PRE>
2750 /* Invert the case of the COUNT following characters. */
2751 int
2752 invert_case_line (count, key)
2753      int count, key;
2754 {
2755   register int start, end, i;
2756
2757   start = rl_point;
2758
2759   if (rl_point &#62;= rl_end)
2760     return (0);
2761
2762   if (count &#60; 0)
2763     {
2764       direction = -1;
2765       count = -count;
2766     }
2767   else
2768     direction = 1;
2769
2770   /* Find the end of the range to modify. */
2771   end = start + (count * direction);
2772
2773   /* Force it to be within range. */
2774   if (end &#62; rl_end)
2775     end = rl_end;
2776   else if (end &#60; 0)
2777     end = 0;
2778
2779   if (start == end)
2780     return (0);
2781
2782   if (start &#62; end)
2783     {
2784       int temp = start;
2785       start = end;
2786       end = temp;
2787     }
2788
2789   /* Tell readline that we are modifying the line, so it will save
2790      the undo information. */
2791   rl_modifying (start, end);
2792
2793   for (i = start; i != end; i++)
2794     {
2795       if (uppercase_p (rl_line_buffer[i]))
2796         rl_line_buffer[i] = to_lower (rl_line_buffer[i]);
2797       else if (lowercase_p (rl_line_buffer[i]))
2798         rl_line_buffer[i] = to_upper (rl_line_buffer[i]);
2799     }
2800   /* Move point to on top of the last character changed. */
2801   rl_point = (direction == 1) ? end - 1 : start;
2802   return (0);
2803 }
2804 </PRE>
2805
2806
2807
2808 <H2><A NAME="SEC40" HREF="readline.html#TOC40">Readline Signal Handling</A></H2>
2809
2810 <P>
2811 Signals are asynchronous events sent to a process by the Unix kernel,
2812 sometimes on behalf of another process.  They are intended to indicate
2813 exceptional events, like a user pressing the interrupt key on his
2814 terminal, or a network connection being broken.  There is a class of
2815 signals that can be sent to the process currently reading input from
2816 the keyboard.  Since Readline changes the terminal attributes when it
2817 is called, it needs to perform special processing when a signal is
2818 received to restore the terminal to a sane state, or provide application
2819 writers with functions to do so manually.
2820
2821 </P>
2822 <P>
2823 Readline contains an internal signal handler that is installed for a
2824 number of signals (<CODE>SIGINT</CODE>, <CODE>SIGQUIT</CODE>, <CODE>SIGTERM</CODE>,
2825 <CODE>SIGALRM</CODE>, <CODE>SIGTSTP</CODE>, <CODE>SIGTTIN</CODE>, and <CODE>SIGTTOU</CODE>).
2826 When one of these signals is received, the signal handler
2827 will reset the terminal attributes to those that were in effect before
2828 <CODE>readline ()</CODE> was called, reset the signal handling to what it was
2829 before <CODE>readline ()</CODE> was called, and resend the signal to the calling
2830 application.
2831 If and when the calling application's signal handler returns, Readline
2832 will reinitialize the terminal and continue to accept input.
2833 When a <CODE>SIGINT</CODE> is received, the Readline signal handler performs
2834 some additional work, which will cause any partially-entered line to be
2835 aborted (see the description of <CODE>rl_free_line_state ()</CODE>).
2836
2837 </P>
2838 <P>
2839 There is an additional Readline signal handler, for <CODE>SIGWINCH</CODE>, which
2840 the kernel sends to a process whenever the terminal's size changes (for
2841 example, if a user resizes an <CODE>xterm</CODE>).  The Readline <CODE>SIGWINCH</CODE>
2842 handler updates Readline's internal screen size state, and then calls any
2843 <CODE>SIGWINCH</CODE> signal handler the calling application has installed.
2844 Readline calls the application's <CODE>SIGWINCH</CODE> signal handler without
2845 resetting the terminal to its original state.  If the application's signal
2846 handler does more than update its idea of the terminal size and return (for
2847 example, a <CODE>longjmp</CODE> back to a main processing loop), it <EM>must</EM>
2848 call <CODE>rl_cleanup_after_signal ()</CODE> (described below), to restore the
2849 terminal state.
2850
2851 </P>
2852 <P>
2853 Readline provides two variables that allow application writers to
2854 control whether or not it will catch certain signals and act on them
2855 when they are received.  It is important that applications change the
2856 values of these variables only when calling <CODE>readline ()</CODE>, not in
2857 a signal handler, so Readline's internal signal state is not corrupted.
2858
2859 </P>
2860 <P>
2861 <DL>
2862 <DT><U>Variable:</U> int <B>rl_catch_signals</B>
2863 <DD><A NAME="IDX180"></A>
2864 If this variable is non-zero, Readline will install signal handlers for
2865 <CODE>SIGINT</CODE>, <CODE>SIGQUIT</CODE>, <CODE>SIGTERM</CODE>, <CODE>SIGALRM</CODE>,
2866 <CODE>SIGTSTP</CODE>, <CODE>SIGTTIN</CODE>, and <CODE>SIGTTOU</CODE>.
2867
2868 </P>
2869 <P>
2870 The default value of <CODE>rl_catch_signals</CODE> is 1.
2871 </DL>
2872
2873 </P>
2874 <P>
2875 <DL>
2876 <DT><U>Variable:</U> int <B>rl_catch_sigwinch</B>
2877 <DD><A NAME="IDX181"></A>
2878 If this variable is non-zero, Readline will install a signal handler for
2879 <CODE>SIGWINCH</CODE>.
2880
2881 </P>
2882 <P>
2883 The default value of <CODE>rl_catch_sigwinch</CODE> is 1.
2884 </DL>
2885
2886 </P>
2887 <P>
2888 If an application does not wish to have Readline catch any signals, or
2889 to handle signals other than those Readline catches (<CODE>SIGHUP</CODE>,
2890 for example),
2891 Readline provides convenience functions to do the necessary terminal
2892 and internal state cleanup upon receipt of a signal.
2893
2894 </P>
2895 <P>
2896 <DL>
2897 <DT><U>Function:</U> void <B>rl_cleanup_after_signal</B> <I>(void)</I>
2898 <DD><A NAME="IDX182"></A>
2899 This function will reset the state of the terminal to what it was before
2900 <CODE>readline ()</CODE> was called, and remove the Readline signal handlers for
2901 all signals, depending on the values of <CODE>rl_catch_signals</CODE> and
2902 <CODE>rl_catch_sigwinch</CODE>.
2903 </DL>
2904
2905 </P>
2906 <P>
2907 <DL>
2908 <DT><U>Function:</U> void <B>rl_free_line_state</B> <I>(void)</I>
2909 <DD><A NAME="IDX183"></A>
2910 This will free any partial state associated with the current input line
2911 (undo information, any partial history entry, any partially-entered
2912 keyboard macro, and any partially-entered numeric argument).  This
2913 should be called before <CODE>rl_cleanup_after_signal ()</CODE>.  The
2914 Readline signal handler for <CODE>SIGINT</CODE> calls this to abort the
2915 current input line.
2916 </DL>
2917
2918 </P>
2919 <P>
2920 <DL>
2921 <DT><U>Function:</U> void <B>rl_reset_after_signal</B> <I>(void)</I>
2922 <DD><A NAME="IDX184"></A>
2923 This will reinitialize the terminal and reinstall any Readline signal
2924 handlers, depending on the values of <CODE>rl_catch_signals</CODE> and
2925 <CODE>rl_catch_sigwinch</CODE>.
2926 </DL>
2927
2928 </P>
2929 <P>
2930 If an application does not wish Readline to catch <CODE>SIGWINCH</CODE>, it may
2931 call <CODE>rl_resize_terminal ()</CODE> to force Readline to update its idea of
2932 the terminal size when a <CODE>SIGWINCH</CODE> is received.
2933
2934 </P>
2935 <P>
2936 <DL>
2937 <DT><U>Function:</U> void <B>rl_resize_terminal</B> <I>(void)</I>
2938 <DD><A NAME="IDX185"></A>
2939 Update Readline's internal screen size.
2940 </DL>
2941
2942 </P>
2943 <P>
2944 The following functions install and remove Readline's signal handlers.
2945
2946 </P>
2947 <P>
2948 <DL>
2949 <DT><U>Function:</U> int <B>rl_set_signals</B> <I>(void)</I>
2950 <DD><A NAME="IDX186"></A>
2951 Install Readline's signal handler for <CODE>SIGINT</CODE>, <CODE>SIGQUIT</CODE>,
2952 <CODE>SIGTERM</CODE>, <CODE>SIGALRM</CODE>, <CODE>SIGTSTP</CODE>, <CODE>SIGTTIN</CODE>,
2953 <CODE>SIGTTOU</CODE>, and <CODE>SIGWINCH</CODE>, depending on the values of
2954 <CODE>rl_catch_signals</CODE> and <CODE>rl_catch_sigwinch</CODE>.
2955 </DL>
2956
2957 </P>
2958 <P>
2959 <DL>
2960 <DT><U>Function:</U> int <B>rl_clear_signals</B> <I>(void)</I>
2961 <DD><A NAME="IDX187"></A>
2962 Remove all of the Readline signal handlers installed by
2963 <CODE>rl_set_signals ()</CODE>.
2964 </DL>
2965
2966 </P>
2967
2968
2969 <H2><A NAME="SEC41" HREF="readline.html#TOC41">Custom Completers</A></H2>
2970
2971 <P>
2972 Typically, a program that reads commands from the user has a way of
2973 disambiguating commands and data.  If your program is one of these, then
2974 it can provide completion for commands, data, or both.
2975 The following sections describe how your program and Readline
2976 cooperate to provide this service.
2977
2978 </P>
2979
2980 <UL>
2981 <LI><A HREF="readline.html#SEC42">How Completing Works</A>: The logic used to do completion.
2982 <LI><A HREF="readline.html#SEC43">Completion Functions</A>: Functions provided by Readline.
2983 <LI><A HREF="readline.html#SEC44">Completion Variables</A>: Variables which control completion.
2984 <LI><A HREF="readline.html#SEC45">A Short Completion Example</A>: An example of writing completer subroutines.
2985 </UL>
2986
2987
2988
2989 <H3><A NAME="SEC42" HREF="readline.html#TOC42">How Completing Works</A></H3>
2990
2991 <P>
2992 In order to complete some text, the full list of possible completions
2993 must be available.  That is, it is not possible to accurately
2994 expand a partial word without knowing all of the possible words
2995 which make sense in that context.  The Readline library provides
2996 the user interface to completion, and two of the most common
2997 completion functions:  filename and username.  For completing other types
2998 of text, you must write your own completion function.  This section
2999 describes exactly what such functions must do, and provides an example.
3000
3001 </P>
3002 <P>
3003 There are three major functions used to perform completion:
3004
3005 </P>
3006
3007 <OL>
3008 <LI>
3009
3010 The user-interface function <CODE>rl_complete ()</CODE>.  This function is
3011 called with the same arguments as other Readline
3012 functions intended for interactive use:  <VAR>count</VAR> and
3013 <VAR>invoking_key</VAR>.  It isolates the word to be completed and calls
3014 <CODE>completion_matches ()</CODE> to generate a list of possible completions.
3015 It then either lists the possible completions, inserts the possible
3016 completions, or actually performs the
3017 completion, depending on which behavior is desired.
3018
3019 <LI>
3020
3021 The internal function <CODE>completion_matches ()</CODE> uses your
3022 <EM>generator</EM> function to generate the list of possible matches, and
3023 then returns the array of these matches.  You should place the address
3024 of your generator function in <CODE>rl_completion_entry_function</CODE>.
3025
3026 <LI>
3027
3028 The generator function is called repeatedly from
3029 <CODE>completion_matches ()</CODE>, returning a string each time.  The
3030 arguments to the generator function are <VAR>text</VAR> and <VAR>state</VAR>.
3031 <VAR>text</VAR> is the partial word to be completed.  <VAR>state</VAR> is zero the
3032 first time the function is called, allowing the generator to perform
3033 any necessary initialization, and a positive non-zero integer for
3034 each subsequent call.  When the generator function returns
3035 <CODE>(char *)NULL</CODE> this signals <CODE>completion_matches ()</CODE> that there are
3036 no more possibilities left.  Usually the generator function computes the
3037 list of possible completions when <VAR>state</VAR> is zero, and returns them
3038 one at a time on subsequent calls.  Each string the generator function
3039 returns as a match must be allocated with <CODE>malloc()</CODE>; Readline
3040 frees the strings when it has finished with them.
3041
3042 </OL>
3043
3044 <P>
3045 <DL>
3046 <DT><U>Function:</U> int <B>rl_complete</B> <I>(int ignore, int invoking_key)</I>
3047 <DD><A NAME="IDX188"></A>
3048 Complete the word at or before point.  You have supplied the function
3049 that does the initial simple matching selection algorithm (see
3050 <CODE>completion_matches ()</CODE>).  The default is to do filename completion.
3051 </DL>
3052
3053 </P>
3054 <P>
3055 <DL>
3056 <DT><U>Variable:</U> Function * <B>rl_completion_entry_function</B>
3057 <DD><A NAME="IDX189"></A>
3058 This is a pointer to the generator function for <CODE>completion_matches
3059 ()</CODE>.  If the value of <CODE>rl_completion_entry_function</CODE> is
3060 <CODE>(Function *)NULL</CODE> then the default filename generator function,
3061 <CODE>filename_completion_function ()</CODE>, is used.
3062 </DL>
3063
3064 </P>
3065
3066
3067 <H3><A NAME="SEC43" HREF="readline.html#TOC43">Completion Functions</A></H3>
3068
3069 <P>
3070 Here is the complete list of callable completion functions present in
3071 Readline.
3072
3073 </P>
3074 <P>
3075 <DL>
3076 <DT><U>Function:</U> int <B>rl_complete_internal</B> <I>(int what_to_do)</I>
3077 <DD><A NAME="IDX190"></A>
3078 Complete the word at or before point.  <VAR>what_to_do</VAR> says what to do
3079 with the completion.  A value of <SAMP>`?'</SAMP> means list the possible
3080 completions.  <SAMP>`TAB'</SAMP> means do standard completion.  <SAMP>`*'</SAMP> means
3081 insert all of the possible completions.  <SAMP>`!'</SAMP> means to display
3082 all of the possible completions, if there is more than one, as well as
3083 performing partial completion.
3084 </DL>
3085
3086 </P>
3087 <P>
3088 <DL>
3089 <DT><U>Function:</U> int <B>rl_complete</B> <I>(int ignore, int invoking_key)</I>
3090 <DD><A NAME="IDX191"></A>
3091 Complete the word at or before point.  You have supplied the function
3092 that does the initial simple matching selection algorithm (see
3093 <CODE>completion_matches ()</CODE> and <CODE>rl_completion_entry_function</CODE>).
3094 The default is to do filename
3095 completion.  This calls <CODE>rl_complete_internal ()</CODE> with an
3096 argument depending on <VAR>invoking_key</VAR>.
3097 </DL>
3098
3099 </P>
3100 <P>
3101 <DL>
3102 <DT><U>Function:</U> int <B>rl_possible_completions</B> <I>(int count, int invoking_key))</I>
3103 <DD><A NAME="IDX192"></A>
3104 List the possible completions.  See description of <CODE>rl_complete
3105 ()</CODE>.  This calls <CODE>rl_complete_internal ()</CODE> with an argument of
3106 <SAMP>`?'</SAMP>.
3107 </DL>
3108
3109 </P>
3110 <P>
3111 <DL>
3112 <DT><U>Function:</U> int <B>rl_insert_completions</B> <I>(int count, int invoking_key))</I>
3113 <DD><A NAME="IDX193"></A>
3114 Insert the list of possible completions into the line, deleting the
3115 partially-completed word.  See description of <CODE>rl_complete ()</CODE>.
3116 This calls <CODE>rl_complete_internal ()</CODE> with an argument of <SAMP>`*'</SAMP>.
3117 </DL>
3118
3119 </P>
3120 <P>
3121 <DL>
3122 <DT><U>Function:</U> char ** <B>completion_matches</B> <I>(char *text, CPFunction *entry_func)</I>
3123 <DD><A NAME="IDX194"></A>
3124 Returns an array of <CODE>(char *)</CODE> which is a list of completions for
3125 <VAR>text</VAR>.  If there are no completions, returns <CODE>(char **)NULL</CODE>.
3126 The first entry in the returned array is the substitution for <VAR>text</VAR>.
3127 The remaining entries are the possible completions.  The array is
3128 terminated with a <CODE>NULL</CODE> pointer.
3129
3130 </P>
3131 <P>
3132 <VAR>entry_func</VAR> is a function of two args, and returns a
3133 <CODE>(char *)</CODE>.  The first argument is <VAR>text</VAR>.  The second is a
3134 state argument; it is zero on the first call, and non-zero on subsequent
3135 calls.  <VAR>entry_func</VAR> returns a <CODE>NULL</CODE>  pointer to the caller
3136 when there are no more matches.
3137 </DL>
3138
3139 </P>
3140 <P>
3141 <DL>
3142 <DT><U>Function:</U> char * <B>filename_completion_function</B> <I>(char *text, int state)</I>
3143 <DD><A NAME="IDX195"></A>
3144 A generator function for filename completion in the general case.  Note
3145 that completion in Bash is a little different because of all
3146 the pathnames that must be followed when looking up completions for a
3147 command.  The Bash source is a useful reference for writing custom
3148 completion functions.
3149 </DL>
3150
3151 </P>
3152 <P>
3153 <DL>
3154 <DT><U>Function:</U> char * <B>username_completion_function</B> <I>(char *text, int state)</I>
3155 <DD><A NAME="IDX196"></A>
3156 A completion generator for usernames.  <VAR>text</VAR> contains a partial
3157 username preceded by a random character (usually <SAMP>`~'</SAMP>).  As with all
3158 completion generators, <VAR>state</VAR> is zero on the first call and non-zero
3159 for subsequent calls.
3160 </DL>
3161
3162 </P>
3163
3164
3165 <H3><A NAME="SEC44" HREF="readline.html#TOC44">Completion Variables</A></H3>
3166
3167 <P>
3168 <DL>
3169 <DT><U>Variable:</U> Function * <B>rl_completion_entry_function</B>
3170 <DD><A NAME="IDX197"></A>
3171 A pointer to the generator function for <CODE>completion_matches ()</CODE>.
3172 <CODE>NULL</CODE> means to use <CODE>filename_entry_function ()</CODE>, the default
3173 filename completer.
3174 </DL>
3175
3176 </P>
3177 <P>
3178 <DL>
3179 <DT><U>Variable:</U> CPPFunction * <B>rl_attempted_completion_function</B>
3180 <DD><A NAME="IDX198"></A>
3181 A pointer to an alternative function to create matches.
3182 The function is called with <VAR>text</VAR>, <VAR>start</VAR>, and <VAR>end</VAR>.
3183 <VAR>start</VAR> and <VAR>end</VAR> are indices in <CODE>rl_line_buffer</CODE> saying
3184 what the boundaries of <VAR>text</VAR> are.  If this function exists and
3185 returns <CODE>NULL</CODE>, or if this variable is set to <CODE>NULL</CODE>, then
3186 <CODE>rl_complete ()</CODE> will call the value of
3187 <CODE>rl_completion_entry_function</CODE> to generate matches, otherwise the
3188 array of strings returned will be used.
3189 </DL>
3190
3191 </P>
3192 <P>
3193 <DL>
3194 <DT><U>Variable:</U> CPFunction * <B>rl_filename_quoting_function</B>
3195 <DD><A NAME="IDX199"></A>
3196 A pointer to a function that will quote a filename in an application-
3197 specific fashion.  This is called if filename completion is being
3198 attempted and one of the characters in <CODE>rl_filename_quote_characters</CODE>
3199 appears in a completed filename.  The function is called with
3200 <VAR>text</VAR>, <VAR>match_type</VAR>, and <VAR>quote_pointer</VAR>.  The <VAR>text</VAR>
3201 is the filename to be quoted.  The <VAR>match_type</VAR> is either
3202 <CODE>SINGLE_MATCH</CODE>, if there is only one completion match, or
3203 <CODE>MULT_MATCH</CODE>.  Some functions use this to decide whether or not to
3204 insert a closing quote character.  The <VAR>quote_pointer</VAR> is a pointer
3205 to any opening quote character the user typed.  Some functions choose
3206 to reset this character.
3207 </DL>
3208
3209 </P>
3210 <P>
3211 <DL>
3212 <DT><U>Variable:</U> CPFunction * <B>rl_filename_dequoting_function</B>
3213 <DD><A NAME="IDX200"></A>
3214 A pointer to a function that will remove application-specific quoting
3215 characters from a filename before completion is attempted, so those
3216 characters do not interfere with matching the text against names in
3217 the filesystem.  It is called with <VAR>text</VAR>, the text of the word
3218 to be dequoted, and <VAR>quote_char</VAR>, which is the quoting character
3219 that delimits the filename (usually <SAMP>`''</SAMP> or <SAMP>`"'</SAMP>).  If
3220 <VAR>quote_char</VAR> is zero, the filename was not in an embedded string.
3221 </DL>
3222
3223 </P>
3224 <P>
3225 <DL>
3226 <DT><U>Variable:</U> Function * <B>rl_char_is_quoted_p</B>
3227 <DD><A NAME="IDX201"></A>
3228 A pointer to a function to call that determines whether or not a specific
3229 character in the line buffer is quoted, according to whatever quoting
3230 mechanism the program calling readline uses.  The function is called with
3231 two arguments: <VAR>text</VAR>, the text of the line, and <VAR>index</VAR>, the
3232 index of the character in the line.  It is used to decide whether a
3233 character found in <CODE>rl_completer_word_break_characters</CODE> should be
3234 used to break words for the completer.
3235 </DL>
3236
3237 </P>
3238 <P>
3239 <DL>
3240 <DT><U>Variable:</U> int <B>rl_completion_query_items</B>
3241 <DD><A NAME="IDX202"></A>
3242 Up to this many items will be displayed in response to a
3243 possible-completions call.  After that, we ask the user if she is sure
3244 she wants to see them all.  The default value is 100.
3245 </DL>
3246
3247 </P>
3248 <P>
3249 <DL>
3250 <DT><U>Variable:</U> char * <B>rl_basic_word_break_characters</B>
3251 <DD><A NAME="IDX203"></A>
3252 The basic list of characters that signal a break between words for the
3253 completer routine.  The default value of this variable is the characters
3254 which break words for completion in Bash, i.e.,
3255 <CODE>" \t\n\"\\'`@$&#62;&#60;=;|&#38;{("</CODE>.
3256 </DL>
3257
3258 </P>
3259 <P>
3260 <DL>
3261 <DT><U>Variable:</U> char * <B>rl_basic_quote_characters</B>
3262 <DD><A NAME="IDX204"></A>
3263 List of quote characters which can cause a word break.
3264 </DL>
3265
3266 </P>
3267 <P>
3268 <DL>
3269 <DT><U>Variable:</U> char * <B>rl_completer_word_break_characters</B>
3270 <DD><A NAME="IDX205"></A>
3271 The list of characters that signal a break between words for
3272 <CODE>rl_complete_internal ()</CODE>.  The default list is the value of
3273 <CODE>rl_basic_word_break_characters</CODE>.
3274 </DL>
3275
3276 </P>
3277 <P>
3278 <DL>
3279 <DT><U>Variable:</U> char * <B>rl_completer_quote_characters</B>
3280 <DD><A NAME="IDX206"></A>
3281 List of characters which can be used to quote a substring of the line.
3282 Completion occurs on the entire substring, and within the substring
3283 <CODE>rl_completer_word_break_characters</CODE> are treated as any other character,
3284 unless they also appear within this list.
3285 </DL>
3286
3287 </P>
3288 <P>
3289 <DL>
3290 <DT><U>Variable:</U> char * <B>rl_filename_quote_characters</B>
3291 <DD><A NAME="IDX207"></A>
3292 A list of characters that cause a filename to be quoted by the completer
3293 when they appear in a completed filename.  The default is the null string.
3294 </DL>
3295
3296 </P>
3297 <P>
3298 <DL>
3299 <DT><U>Variable:</U> char * <B>rl_special_prefixes</B>
3300 <DD><A NAME="IDX208"></A>
3301 The list of characters that are word break characters, but should be
3302 left in <VAR>text</VAR> when it is passed to the completion function.
3303 Programs can use this to help determine what kind of completing to do.
3304 For instance, Bash sets this variable to "$@" so that it can complete
3305 shell variables and hostnames.
3306 </DL>
3307
3308 </P>
3309 <P>
3310 <DL>
3311 <DT><U>Variable:</U> int <B>rl_completion_append_character</B>
3312 <DD><A NAME="IDX209"></A>
3313 When a single completion alternative matches at the end of the command
3314 line, this character is appended to the inserted completion text.  The
3315 default is a space character (<SAMP>` '</SAMP>).  Setting this to the null
3316 character (<SAMP>`\0'</SAMP>) prevents anything being appended automatically.
3317 This can be changed in custom completion functions to
3318 provide the "most sensible word separator character" according to
3319 an application-specific command line syntax specification.
3320 </DL>
3321
3322 </P>
3323 <P>
3324 <DL>
3325 <DT><U>Variable:</U> int <B>rl_ignore_completion_duplicates</B>
3326 <DD><A NAME="IDX210"></A>
3327 If non-zero, then disallow duplicates in the matches.  Default is 1.
3328 </DL>
3329
3330 </P>
3331 <P>
3332 <DL>
3333 <DT><U>Variable:</U> int <B>rl_filename_completion_desired</B>
3334 <DD><A NAME="IDX211"></A>
3335 Non-zero means that the results of the matches are to be treated as
3336 filenames.  This is <EM>always</EM> zero on entry, and can only be changed
3337 within a completion entry generator function.  If it is set to a non-zero
3338 value, directory names have a slash appended and Readline attempts to
3339 quote completed filenames if they contain any embedded word break
3340 characters.
3341 </DL>
3342
3343 </P>
3344 <P>
3345 <DL>
3346 <DT><U>Variable:</U> int <B>rl_filename_quoting_desired</B>
3347 <DD><A NAME="IDX212"></A>
3348 Non-zero means that the results of the matches are to be quoted using
3349 double quotes (or an application-specific quoting mechanism) if the
3350 completed filename contains any characters in
3351 <CODE>rl_filename_quote_chars</CODE>.  This is <EM>always</EM> non-zero
3352 on entry, and can only be changed within a completion entry generator
3353 function.  The quoting is effected via a call to the function pointed to
3354 by <CODE>rl_filename_quoting_function</CODE>.
3355 </DL>
3356
3357 </P>
3358 <P>
3359 <DL>
3360 <DT><U>Variable:</U> int <B>rl_inhibit_completion</B>
3361 <DD><A NAME="IDX213"></A>
3362 If this variable is non-zero, completion is inhibit&#60;ed.  The completion
3363 character will be inserted as any other bound to <CODE>self-insert</CODE>.
3364 </DL>
3365
3366 </P>
3367 <P>
3368 <DL>
3369 <DT><U>Variable:</U> Function * <B>rl_ignore_some_completions_function</B>
3370 <DD><A NAME="IDX214"></A>
3371 This function, if defined, is called by the completer when real filename
3372 completion is done, after all the matching names have been generated.
3373 It is passed a <CODE>NULL</CODE> terminated array of matches.
3374 The first element (<CODE>matches[0]</CODE>) is the
3375 maximal substring common to all matches. This function can
3376 re-arrange the list of matches as required, but each element deleted
3377 from the array must be freed.
3378 </DL>
3379
3380 </P>
3381 <P>
3382 <DL>
3383 <DT><U>Variable:</U> Function * <B>rl_directory_completion_hook</B>
3384 <DD><A NAME="IDX215"></A>
3385 This function, if defined, is allowed to modify the directory portion
3386 of filenames Readline completes.  It is called with the address of a
3387 string (the current directory name) as an argument.  It could be used
3388 to expand symbolic links or shell variables in pathnames.
3389 </DL>
3390
3391 </P>
3392 <P>
3393 <DL>
3394 <DT><U>Variable:</U> VFunction * <B>rl_completion_display_matches_hook</B>
3395 <DD><A NAME="IDX216"></A>
3396 If non-zero, then this is the address of a function to call when
3397 completing a word would normally display the list of possible matches.
3398 This function is called in lieu of Readline displaying the list.
3399 It takes three arguments:
3400 (<CODE>char **</CODE><VAR>matches</VAR>, <CODE>int</CODE> <VAR>num_matches</VAR>, <CODE>int</CODE> <VAR>max_length</VAR>)
3401 where <VAR>matches</VAR> is the array of matching strings,
3402 <VAR>num_matches</VAR> is the number of strings in that array, and
3403 <VAR>max_length</VAR> is the length of the longest string in that array.
3404 Readline provides a convenience function, <CODE>rl_display_match_list</CODE>,
3405 that takes care of doing the display to Readline's output stream.  That
3406 function may be called from this hook.
3407 </DL>
3408
3409 </P>
3410
3411
3412 <H3><A NAME="SEC45" HREF="readline.html#TOC45">A Short Completion Example</A></H3>
3413
3414 <P>
3415 Here is a small application demonstrating the use of the GNU Readline
3416 library.  It is called <CODE>fileman</CODE>, and the source code resides in
3417 <TT>`examples/fileman.c'</TT>.  This sample application provides
3418 completion of command names, line editing features, and access to the
3419 history list.
3420
3421 </P>
3422
3423 <PRE>
3424 /* fileman.c -- A tiny application which demonstrates how to use the
3425    GNU Readline library.  This application interactively allows users
3426    to manipulate files and their modes. */
3427
3428 #include &#60;stdio.h&#62;
3429 #include &#60;sys/types.h&#62;
3430 #include &#60;sys/file.h&#62;
3431 #include &#60;sys/stat.h&#62;
3432 #include &#60;sys/errno.h&#62;
3433
3434 #include &#60;readline/readline.h&#62;
3435 #include &#60;readline/history.h&#62;
3436
3437 extern char *getwd ();
3438 extern char *xmalloc ();
3439
3440 /* The names of functions that actually do the manipulation. */
3441 int com_list (), com_view (), com_rename (), com_stat (), com_pwd ();
3442 int com_delete (), com_help (), com_cd (), com_quit ();
3443
3444 /* A structure which contains information on the commands this program
3445    can understand. */
3446
3447 typedef struct {
3448   char *name;                   /* User printable name of the function. */
3449   Function *func;               /* Function to call to do the job. */
3450   char *doc;                    /* Documentation for this function.  */
3451 } COMMAND;
3452
3453 COMMAND commands[] = {
3454   { "cd", com_cd, "Change to directory DIR" },
3455   { "delete", com_delete, "Delete FILE" },
3456   { "help", com_help, "Display this text" },
3457   { "?", com_help, "Synonym for `help'" },
3458   { "list", com_list, "List files in DIR" },
3459   { "ls", com_list, "Synonym for `list'" },
3460   { "pwd", com_pwd, "Print the current working directory" },
3461   { "quit", com_quit, "Quit using Fileman" },
3462   { "rename", com_rename, "Rename FILE to NEWNAME" },
3463   { "stat", com_stat, "Print out statistics on FILE" },
3464   { "view", com_view, "View the contents of FILE" },
3465   { (char *)NULL, (Function *)NULL, (char *)NULL }
3466 };
3467
3468 /* Forward declarations. */
3469 char *stripwhite ();
3470 COMMAND *find_command ();
3471
3472 /* The name of this program, as taken from argv[0]. */
3473 char *progname;
3474
3475 /* When non-zero, this global means the user is done using this program. */
3476 int done;
3477
3478 char *
3479 dupstr (s)
3480      int s;
3481 {
3482   char *r;
3483
3484   r = xmalloc (strlen (s) + 1);
3485   strcpy (r, s);
3486   return (r);
3487 }
3488
3489 main (argc, argv)
3490      int argc;
3491      char **argv;
3492 {
3493   char *line, *s;
3494
3495   progname = argv[0];
3496
3497   initialize_readline ();       /* Bind our completer. */
3498
3499   /* Loop reading and executing lines until the user quits. */
3500   for ( ; done == 0; )
3501     {
3502       line = readline ("FileMan: ");
3503
3504       if (!line)
3505         break;
3506
3507       /* Remove leading and trailing whitespace from the line.
3508          Then, if there is anything left, add it to the history list
3509          and execute it. */
3510       s = stripwhite (line);
3511
3512       if (*s)
3513         {
3514           add_history (s);
3515           execute_line (s);
3516         }
3517
3518       free (line);
3519     }
3520   exit (0);
3521 }
3522
3523 /* Execute a command line. */
3524 int
3525 execute_line (line)
3526      char *line;
3527 {
3528   register int i;
3529   COMMAND *command;
3530   char *word;
3531
3532   /* Isolate the command word. */
3533   i = 0;
3534   while (line[i] &#38;&#38; whitespace (line[i]))
3535     i++;
3536   word = line + i;
3537
3538   while (line[i] &#38;&#38; !whitespace (line[i]))
3539     i++;
3540
3541   if (line[i])
3542     line[i++] = '\0';
3543
3544   command = find_command (word);
3545
3546   if (!command)
3547     {
3548       fprintf (stderr, "%s: No such command for FileMan.\n", word);
3549       return (-1);
3550     }
3551
3552   /* Get argument to command, if any. */
3553   while (whitespace (line[i]))
3554     i++;
3555
3556   word = line + i;
3557
3558   /* Call the function. */
3559   return ((*(command-&#62;func)) (word));
3560 }
3561
3562 /* Look up NAME as the name of a command, and return a pointer to that
3563    command.  Return a NULL pointer if NAME isn't a command name. */
3564 COMMAND *
3565 find_command (name)
3566      char *name;
3567 {
3568   register int i;
3569
3570   for (i = 0; commands[i].name; i++)
3571     if (strcmp (name, commands[i].name) == 0)
3572       return (&#38;commands[i]);
3573
3574   return ((COMMAND *)NULL);
3575 }
3576
3577 /* Strip whitespace from the start and end of STRING.  Return a pointer
3578    into STRING. */
3579 char *
3580 stripwhite (string)
3581      char *string;
3582 {
3583   register char *s, *t;
3584
3585   for (s = string; whitespace (*s); s++)
3586     ;
3587
3588   if (*s == 0)
3589     return (s);
3590
3591   t = s + strlen (s) - 1;
3592   while (t &#62; s &#38;&#38; whitespace (*t))
3593     t--;
3594   *++t = '\0';
3595
3596   return s;
3597 }
3598
3599 /* **************************************************************** */
3600 /*                                                                  */
3601 /*                  Interface to Readline Completion                */
3602 /*                                                                  */
3603 /* **************************************************************** */
3604
3605 char *command_generator ();
3606 char **fileman_completion ();
3607
3608 /* Tell the GNU Readline library how to complete.  We want to try to complete
3609    on command names if this is the first word in the line, or on filenames
3610    if not. */
3611 initialize_readline ()
3612 {
3613   /* Allow conditional parsing of the ~/.inputrc file. */
3614   rl_readline_name = "FileMan";
3615
3616   /* Tell the completer that we want a crack first. */
3617   rl_attempted_completion_function = (CPPFunction *)fileman_completion;
3618 }
3619
3620 /* Attempt to complete on the contents of TEXT.  START and END bound the
3621    region of rl_line_buffer that contains the word to complete.  TEXT is
3622    the word to complete.  We can use the entire contents of rl_line_buffer
3623    in case we want to do some simple parsing.  Return the array of matches,
3624    or NULL if there aren't any. */
3625 char **
3626 fileman_completion (text, start, end)
3627      char *text;
3628      int start, end;
3629 {
3630   char **matches;
3631
3632   matches = (char **)NULL;
3633
3634   /* If this word is at the start of the line, then it is a command
3635      to complete.  Otherwise it is the name of a file in the current
3636      directory. */
3637   if (start == 0)
3638     matches = completion_matches (text, command_generator);
3639
3640   return (matches);
3641 }
3642
3643 /* Generator function for command completion.  STATE lets us know whether
3644    to start from scratch; without any state (i.e. STATE == 0), then we
3645    start at the top of the list. */
3646 char *
3647 command_generator (text, state)
3648      char *text;
3649      int state;
3650 {
3651   static int list_index, len;
3652   char *name;
3653
3654   /* If this is a new word to complete, initialize now.  This includes
3655      saving the length of TEXT for efficiency, and initializing the index
3656      variable to 0. */
3657   if (!state)
3658     {
3659       list_index = 0;
3660       len = strlen (text);
3661     }
3662
3663   /* Return the next name which partially matches from the command list. */
3664   while (name = commands[list_index].name)
3665     {
3666       list_index++;
3667
3668       if (strncmp (name, text, len) == 0)
3669         return (dupstr(name));
3670     }
3671
3672   /* If no names matched, then return NULL. */
3673   return ((char *)NULL);
3674 }
3675
3676 /* **************************************************************** */
3677 /*                                                                  */
3678 /*                       FileMan Commands                           */
3679 /*                                                                  */
3680 /* **************************************************************** */
3681
3682 /* String to pass to system ().  This is for the LIST, VIEW and RENAME
3683    commands. */
3684 static char syscom[1024];
3685
3686 /* List the file(s) named in arg. */
3687 com_list (arg)
3688      char *arg;
3689 {
3690   if (!arg)
3691     arg = "";
3692
3693   sprintf (syscom, "ls -FClg %s", arg);
3694   return (system (syscom));
3695 }
3696
3697 com_view (arg)
3698      char *arg;
3699 {
3700   if (!valid_argument ("view", arg))
3701     return 1;
3702
3703   sprintf (syscom, "more %s", arg);
3704   return (system (syscom));
3705 }
3706
3707 com_rename (arg)
3708      char *arg;
3709 {
3710   too_dangerous ("rename");
3711   return (1);
3712 }
3713
3714 com_stat (arg)
3715      char *arg;
3716 {
3717   struct stat finfo;
3718
3719   if (!valid_argument ("stat", arg))
3720     return (1);
3721
3722   if (stat (arg, &#38;finfo) == -1)
3723     {
3724       perror (arg);
3725       return (1);
3726     }
3727
3728   printf ("Statistics for `%s':\n", arg);
3729
3730   printf ("%s has %d link%s, and is %d byte%s in length.\n", arg,
3731           finfo.st_nlink,
3732           (finfo.st_nlink == 1) ? "" : "s",
3733           finfo.st_size,
3734           (finfo.st_size == 1) ? "" : "s");
3735   printf ("Inode Last Change at: %s", ctime (&#38;finfo.st_ctime));
3736   printf ("      Last access at: %s", ctime (&#38;finfo.st_atime));
3737   printf ("    Last modified at: %s", ctime (&#38;finfo.st_mtime));
3738   return (0);
3739 }
3740
3741 com_delete (arg)
3742      char *arg;
3743 {
3744   too_dangerous ("delete");
3745   return (1);
3746 }
3747
3748 /* Print out help for ARG, or for all of the commands if ARG is
3749    not present. */
3750 com_help (arg)
3751      char *arg;
3752 {
3753   register int i;
3754   int printed = 0;
3755
3756   for (i = 0; commands[i].name; i++)
3757     {
3758       if (!*arg || (strcmp (arg, commands[i].name) == 0))
3759         {
3760           printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
3761           printed++;
3762         }
3763     }
3764
3765   if (!printed)
3766     {
3767       printf ("No commands match `%s'.  Possibilties are:\n", arg);
3768
3769       for (i = 0; commands[i].name; i++)
3770         {
3771           /* Print in six columns. */
3772           if (printed == 6)
3773             {
3774               printed = 0;
3775               printf ("\n");
3776             }
3777
3778           printf ("%s\t", commands[i].name);
3779           printed++;
3780         }
3781
3782       if (printed)
3783         printf ("\n");
3784     }
3785   return (0);
3786 }
3787
3788 /* Change to the directory ARG. */
3789 com_cd (arg)
3790      char *arg;
3791 {
3792   if (chdir (arg) == -1)
3793     {
3794       perror (arg);
3795       return 1;
3796     }
3797
3798   com_pwd ("");
3799   return (0);
3800 }
3801
3802 /* Print out the current working directory. */
3803 com_pwd (ignore)
3804      char *ignore;
3805 {
3806   char dir[1024], *s;
3807
3808   s = getwd (dir);
3809   if (s == 0)
3810     {
3811       printf ("Error getting pwd: %s\n", dir);
3812       return 1;
3813     }
3814
3815   printf ("Current directory is %s\n", dir);
3816   return 0;
3817 }
3818
3819 /* The user wishes to quit using this program.  Just set DONE non-zero. */
3820 com_quit (arg)
3821      char *arg;
3822 {
3823   done = 1;
3824   return (0);
3825 }
3826
3827 /* Function which tells you that you can't do this. */
3828 too_dangerous (caller)
3829      char *caller;
3830 {
3831   fprintf (stderr,
3832            "%s: Too dangerous for me to distribute.  Write it yourself.\n",
3833            caller);
3834 }
3835
3836 /* Return non-zero if ARG is a valid argument for CALLER, else print
3837    an error message and return zero. */
3838 int
3839 valid_argument (caller, arg)
3840      char *caller, *arg;
3841 {
3842   if (!arg || !*arg)
3843     {
3844       fprintf (stderr, "%s: Argument required.\n", caller);
3845       return (0);
3846     }
3847
3848   return (1);
3849 }
3850 </PRE>
3851
3852
3853
3854 <H1><A NAME="SEC46" HREF="readline.html#TOC46">Concept Index</A></H1>
3855 <P>
3856 Jump to:
3857 <A HREF="#c">c</A>
3858 -
3859 <A HREF="#e">e</A>
3860 -
3861 <A HREF="#i">i</A>
3862 -
3863 <A HREF="#k">k</A>
3864 -
3865 <A HREF="#n">n</A>
3866 -
3867 <A HREF="#r">r</A>
3868 -
3869 <A HREF="#y">y</A>
3870 <P>
3871 <H2><A NAME="c">c</A></H2>
3872 <DIR>
3873 <LI><A HREF="readline.html#IDX3">command editing</A>
3874 </DIR>
3875 <H2><A NAME="e">e</A></H2>
3876 <DIR>
3877 <LI><A HREF="readline.html#IDX4">editing command lines</A>
3878 </DIR>
3879 <H2><A NAME="i">i</A></H2>
3880 <DIR>
3881 <LI><A HREF="readline.html#IDX8">initialization file, readline</A>
3882 <LI><A HREF="readline.html#IDX1">interaction, readline</A>
3883 </DIR>
3884 <H2><A NAME="k">k</A></H2>
3885 <DIR>
3886 <LI><A HREF="readline.html#IDX7">kill ring</A>
3887 <LI><A HREF="readline.html#IDX5">killing text</A>
3888 </DIR>
3889 <H2><A NAME="n">n</A></H2>
3890 <DIR>
3891 <LI><A HREF="readline.html#IDX2">notation, readline</A>
3892 </DIR>
3893 <H2><A NAME="r">r</A></H2>
3894 <DIR>
3895 <LI><A HREF="readline.html#IDX98">readline, function</A>
3896 </DIR>
3897 <H2><A NAME="y">y</A></H2>
3898 <DIR>
3899 <LI><A HREF="readline.html#IDX6">yanking text</A>
3900 </DIR>
3901
3902 </P>
3903
3904
3905 <H1><A NAME="SEC47" HREF="readline.html#TOC47">Function and Variable Index</A></H1>
3906 <P>
3907 Jump to:
3908 <A HREF="#(">(</A>
3909 -
3910 <A HREF="#a">a</A>
3911 -
3912 <A HREF="#b">b</A>
3913 -
3914 <A HREF="#c">c</A>
3915 -
3916 <A HREF="#d">d</A>
3917 -
3918 <A HREF="#e">e</A>
3919 -
3920 <A HREF="#f">f</A>
3921 -
3922 <A HREF="#h">h</A>
3923 -
3924 <A HREF="#i">i</A>
3925 -
3926 <A HREF="#k">k</A>
3927 -
3928 <A HREF="#l">l</A>
3929 -
3930 <A HREF="#m">m</A>
3931 -
3932 <A HREF="#n">n</A>
3933 -
3934 <A HREF="#o">o</A>
3935 -
3936 <A HREF="#p">p</A>
3937 -
3938 <A HREF="#q">q</A>
3939 -
3940 <A HREF="#r">r</A>
3941 -
3942 <A HREF="#s">s</A>
3943 -
3944 <A HREF="#t">t</A>
3945 -
3946 <A HREF="#u">u</A>
3947 -
3948 <A HREF="#v">v</A>
3949 -
3950 <A HREF="#y">y</A>
3951 <P>
3952 <H2><A NAME="(">(</A></H2>
3953 <DIR>
3954 <LI><A HREF="readline.html#IDX164">(int</A>
3955 </DIR>
3956 <H2><A NAME="a">a</A></H2>
3957 <DIR>
3958 <LI><A HREF="readline.html#IDX83">abort (C-g)</A>
3959 <LI><A HREF="readline.html#IDX34">accept-line (Newline, Return)</A>
3960 <LI><A HREF="readline.html#IDX167">alphabetic</A>
3961 </DIR>
3962 <H2><A NAME="b">b</A></H2>
3963 <DIR>
3964 <LI><A HREF="readline.html#IDX29">backward-char (C-b)</A>
3965 <LI><A HREF="readline.html#IDX48">backward-delete-char (Rubout)</A>
3966 <LI><A HREF="readline.html#IDX59">backward-kill-line (C-x Rubout)</A>
3967 <LI><A HREF="readline.html#IDX63">backward-kill-word (M-DEL)</A>
3968 <LI><A HREF="readline.html#IDX31">backward-word (M-b)</A>
3969 <LI><A HREF="readline.html#IDX37">beginning-of-history (M-&#38;#60;)</A>
3970 <LI><A HREF="readline.html#IDX26">beginning-of-line (C-a)</A>
3971 <LI><A HREF="readline.html#IDX9">bell-style</A>
3972 </DIR>
3973 <H2><A NAME="c">c</A></H2>
3974 <DIR>
3975 <LI><A HREF="readline.html#IDX81">call-last-kbd-macro (C-x e)</A>
3976 <LI><A HREF="readline.html#IDX57">capitalize-word (M-c)</A>
3977 <LI><A HREF="readline.html#IDX91">character-search (C-])</A>
3978 <LI><A HREF="readline.html#IDX92">character-search-backward (M-C-])</A>
3979 <LI><A HREF="readline.html#IDX32">clear-screen (C-l)</A>
3980 <LI><A HREF="readline.html#IDX10">comment-begin</A>
3981 <LI><A HREF="readline.html#IDX74">complete (TAB)</A>
3982 <LI><A HREF="readline.html#IDX11">completion-query-items</A>
3983 <LI><A HREF="readline.html#IDX194">completion_matches</A>
3984 <LI><A HREF="readline.html#IDX12">convert-meta</A>
3985 <LI><A HREF="readline.html#IDX68">copy-backward-word ()</A>
3986 <LI><A HREF="readline.html#IDX69">copy-forward-word ()</A>
3987 <LI><A HREF="readline.html#IDX67">copy-region-as-kill ()</A>
3988 </DIR>
3989 <H2><A NAME="d">d</A></H2>
3990 <DIR>
3991 <LI><A HREF="readline.html#IDX47">delete-char (C-d)</A>
3992 <LI><A HREF="readline.html#IDX78">delete-char-or-list ()</A>
3993 <LI><A HREF="readline.html#IDX65">delete-horizontal-space ()</A>
3994 <LI><A HREF="readline.html#IDX72">digit-argument (M-0, M-1, ... M--)</A>
3995 <LI><A HREF="readline.html#IDX173">digit_p</A>
3996 <LI><A HREF="readline.html#IDX176">digit_value</A>
3997 <LI><A HREF="readline.html#IDX169">ding</A>
3998 <LI><A HREF="readline.html#IDX13">disable-completion</A>
3999 <LI><A HREF="readline.html#IDX84">do-uppercase-version (M-a, M-b, M-<VAR>x</VAR>, ...)</A>
4000 <LI><A HREF="readline.html#IDX56">downcase-word (M-l)</A>
4001 <LI><A HREF="readline.html#IDX94">dump-functions ()</A>
4002 <LI><A HREF="readline.html#IDX96">dump-macros ()</A>
4003 <LI><A HREF="readline.html#IDX95">dump-variables ()</A>
4004 </DIR>
4005 <H2><A NAME="e">e</A></H2>
4006 <DIR>
4007 <LI><A HREF="readline.html#IDX14">editing-mode</A>
4008 <LI><A HREF="readline.html#IDX15">enable-keypad</A>
4009 <LI><A HREF="readline.html#IDX80">end-kbd-macro (C-x ))</A>
4010 <LI><A HREF="readline.html#IDX38">end-of-history (M-&#38;#62;)</A>
4011 <LI><A HREF="readline.html#IDX27">end-of-line (C-e)</A>
4012 <LI><A HREF="readline.html#IDX90">exchange-point-and-mark (C-x C-x)</A>
4013 <LI><A HREF="readline.html#IDX16">expand-tilde</A>
4014 </DIR>
4015 <H2><A NAME="f">f</A></H2>
4016 <DIR>
4017 <LI><A HREF="readline.html#IDX195">filename_completion_function</A>
4018 <LI><A HREF="readline.html#IDX49">forward-backward-delete-char ()</A>
4019 <LI><A HREF="readline.html#IDX28">forward-char (C-f)</A>
4020 <LI><A HREF="readline.html#IDX40">forward-search-history (C-s)</A>
4021 <LI><A HREF="readline.html#IDX30">forward-word (M-f)</A>
4022 <LI><A HREF="readline.html#IDX146">free_undo_list</A>
4023 </DIR>
4024 <H2><A NAME="h">h</A></H2>
4025 <DIR>
4026 <LI><A HREF="readline.html#IDX44">history-search-backward ()</A>
4027 <LI><A HREF="readline.html#IDX43">history-search-forward ()</A>
4028 <LI><A HREF="readline.html#IDX17">horizontal-scroll-mode</A>
4029 </DIR>
4030 <H2><A NAME="i">i</A></H2>
4031 <DIR>
4032 <LI><A HREF="readline.html#IDX18">input-meta</A>
4033 <LI><A HREF="readline.html#IDX93">insert-comment (M-#)</A>
4034 <LI><A HREF="readline.html#IDX76">insert-completions (M-*)</A>
4035 <LI><A HREF="readline.html#IDX20">isearch-terminators</A>
4036 </DIR>
4037 <H2><A NAME="k">k</A></H2>
4038 <DIR>
4039 <LI><A HREF="readline.html#IDX21">keymap</A>
4040 <LI><A HREF="readline.html#IDX58">kill-line (C-k)</A>
4041 <LI><A HREF="readline.html#IDX66">kill-region ()</A>
4042 <LI><A HREF="readline.html#IDX61">kill-whole-line ()</A>
4043 <LI><A HREF="readline.html#IDX62">kill-word (M-d)</A>
4044 </DIR>
4045 <H2><A NAME="l">l</A></H2>
4046 <DIR>
4047 <LI><A HREF="readline.html#IDX172">lowercase_p</A>
4048 </DIR>
4049 <H2><A NAME="m">m</A></H2>
4050 <DIR>
4051 <LI><A HREF="readline.html#IDX22">mark-modified-lines</A>
4052 <LI><A HREF="readline.html#IDX77">menu-complete ()</A>
4053 <LI><A HREF="readline.html#IDX19">meta-flag</A>
4054 </DIR>
4055 <H2><A NAME="n">n</A></H2>
4056 <DIR>
4057 <LI><A HREF="readline.html#IDX36">next-history (C-n)</A>
4058 <LI><A HREF="readline.html#IDX42">non-incremental-forward-search-history (M-n)</A>
4059 <LI><A HREF="readline.html#IDX41">non-incremental-reverse-search-history (M-p)</A>
4060 <LI><A HREF="readline.html#IDX168">numeric</A>
4061 </DIR>
4062 <H2><A NAME="o">o</A></H2>
4063 <DIR>
4064 <LI><A HREF="readline.html#IDX23">output-meta</A>
4065 </DIR>
4066 <H2><A NAME="p">p</A></H2>
4067 <DIR>
4068 <LI><A HREF="readline.html#IDX75">possible-completions (M-?)</A>
4069 <LI><A HREF="readline.html#IDX85">prefix-meta (ESC)</A>
4070 <LI><A HREF="readline.html#IDX35">previous-history (C-p)</A>
4071 </DIR>
4072 <H2><A NAME="q">q</A></H2>
4073 <DIR>
4074 <LI><A HREF="readline.html#IDX50">quoted-insert (C-q, C-v)</A>
4075 </DIR>
4076 <H2><A NAME="r">r</A></H2>
4077 <DIR>
4078 <LI><A HREF="readline.html#IDX82">re-read-init-file (C-x C-r)</A>
4079 <LI><A HREF="readline.html#IDX97">readline</A>
4080 <LI><A HREF="readline.html#IDX33">redraw-current-line ()</A>
4081 <LI><A HREF="readline.html#IDX39">reverse-search-history (C-r)</A>
4082 <LI><A HREF="readline.html#IDX87">revert-line (M-r)</A>
4083 <LI><A HREF="readline.html#IDX119">rl_add_defun</A>
4084 <LI><A HREF="readline.html#IDX145">rl_add_undo</A>
4085 <LI><A HREF="readline.html#IDX198">rl_attempted_completion_function</A>
4086 <LI><A HREF="readline.html#IDX204">rl_basic_quote_characters</A>
4087 <LI><A HREF="readline.html#IDX203">rl_basic_word_break_characters</A>
4088 <LI><A HREF="readline.html#IDX143">rl_begin_undo_group</A>
4089 <LI><A HREF="readline.html#IDX128">rl_bind_key</A>
4090 <LI><A HREF="readline.html#IDX129">rl_bind_key_in_map</A>
4091 <LI><A HREF="readline.html#IDX118">rl_binding_keymap</A>
4092 <LI><A HREF="readline.html#IDX177">rl_callback_handler_install</A>
4093 <LI><A HREF="readline.html#IDX179">rl_callback_handler_remove</A>
4094 <LI><A HREF="readline.html#IDX178">rl_callback_read_char</A>
4095 <LI><A HREF="readline.html#IDX180">rl_catch_signals</A>
4096 <LI><A HREF="readline.html#IDX181">rl_catch_sigwinch</A>
4097 <LI><A HREF="readline.html#IDX201">rl_char_is_quoted_p</A>
4098 <LI><A HREF="readline.html#IDX182">rl_cleanup_after_signal</A>
4099 <LI><A HREF="readline.html#IDX154">rl_clear_message</A>
4100 <LI><A HREF="readline.html#IDX187">rl_clear_signals</A>
4101 <LI><A HREF="readline.html#IDX188">rl_complete</A>, <A HREF="rlman.html#IDX191">rl_complete</A>
4102 <LI><A HREF="readline.html#IDX190">rl_complete_internal</A>
4103 <LI><A HREF="readline.html#IDX206">rl_completer_quote_characters</A>
4104 <LI><A HREF="readline.html#IDX205">rl_completer_word_break_characters</A>
4105 <LI><A HREF="readline.html#IDX209">rl_completion_append_character</A>
4106 <LI><A HREF="readline.html#IDX216">rl_completion_display_matches_hook</A>
4107 <LI><A HREF="readline.html#IDX189">rl_completion_entry_function</A>, <A HREF="rlman.html#IDX197">rl_completion_entry_function</A>
4108 <LI><A HREF="readline.html#IDX202">rl_completion_query_items</A>
4109 <LI><A HREF="readline.html#IDX121">rl_copy_keymap</A>
4110 <LI><A HREF="readline.html#IDX159">rl_copy_text</A>
4111 <LI><A HREF="readline.html#IDX158">rl_delete_text</A>
4112 <LI><A HREF="readline.html#IDX215">rl_directory_completion_hook</A>
4113 <LI><A HREF="readline.html#IDX123">rl_discard_keymap</A>
4114 <LI><A HREF="readline.html#IDX170">rl_display_match_list</A>
4115 <LI><A HREF="readline.html#IDX147">rl_do_undo</A>
4116 <LI><A HREF="readline.html#IDX103">rl_done</A>
4117 <LI><A HREF="readline.html#IDX101">rl_end</A>
4118 <LI><A HREF="readline.html#IDX144">rl_end_undo_group</A>
4119 <LI><A HREF="readline.html#IDX105">rl_erase_empty_line</A>
4120 <LI><A HREF="readline.html#IDX114">rl_event_hook</A>
4121 <LI><A HREF="readline.html#IDX117">rl_executing_keymap</A>
4122 <LI><A HREF="readline.html#IDX211">rl_filename_completion_desired</A>
4123 <LI><A HREF="readline.html#IDX200">rl_filename_dequoting_function</A>
4124 <LI><A HREF="readline.html#IDX207">rl_filename_quote_characters</A>
4125 <LI><A HREF="readline.html#IDX212">rl_filename_quoting_desired</A>
4126 <LI><A HREF="readline.html#IDX199">rl_filename_quoting_function</A>
4127 <LI><A HREF="readline.html#IDX150">rl_forced_update_display</A>
4128 <LI><A HREF="readline.html#IDX183">rl_free_line_state</A>
4129 <LI><A HREF="readline.html#IDX141">rl_function_dumper</A>
4130 <LI><A HREF="readline.html#IDX138">rl_function_of_keyseq</A>
4131 <LI><A HREF="readline.html#IDX134">rl_generic_bind</A>
4132 <LI><A HREF="readline.html#IDX124">rl_get_keymap</A>
4133 <LI><A HREF="readline.html#IDX126">rl_get_keymap_by_name</A>
4134 <LI><A HREF="readline.html#IDX127">rl_get_keymap_name</A>
4135 <LI><A HREF="readline.html#IDX162">rl_getc</A>
4136 <LI><A HREF="readline.html#IDX115">rl_getc_function</A>
4137 <LI><A HREF="readline.html#IDX210">rl_ignore_completion_duplicates</A>
4138 <LI><A HREF="readline.html#IDX214">rl_ignore_some_completions_function</A>
4139 <LI><A HREF="readline.html#IDX213">rl_inhibit_completion</A>
4140 <LI><A HREF="readline.html#IDX165">rl_initialize</A>
4141 <LI><A HREF="readline.html#IDX193">rl_insert_completions</A>
4142 <LI><A HREF="readline.html#IDX157">rl_insert_text</A>
4143 <LI><A HREF="readline.html#IDX110">rl_instream</A>
4144 <LI><A HREF="readline.html#IDX139">rl_invoking_keyseqs</A>
4145 <LI><A HREF="readline.html#IDX140">rl_invoking_keyseqs_in_map</A>
4146 <LI><A HREF="readline.html#IDX160">rl_kill_text</A>
4147 <LI><A HREF="readline.html#IDX107">rl_library_version</A>
4148 <LI><A HREF="readline.html#IDX99">rl_line_buffer</A>
4149 <LI><A HREF="readline.html#IDX142">rl_list_funmap_names</A>
4150 <LI><A HREF="readline.html#IDX120">rl_make_bare_keymap</A>
4151 <LI><A HREF="readline.html#IDX122">rl_make_keymap</A>
4152 <LI><A HREF="readline.html#IDX102">rl_mark</A>
4153 <LI><A HREF="readline.html#IDX153">rl_message</A>
4154 <LI><A HREF="readline.html#IDX148">rl_modifying</A>
4155 <LI><A HREF="readline.html#IDX137">rl_named_function</A>
4156 <LI><A HREF="readline.html#IDX151">rl_on_new_line</A>
4157 <LI><A HREF="readline.html#IDX111">rl_outstream</A>
4158 <LI><A HREF="readline.html#IDX135">rl_parse_and_bind</A>
4159 <LI><A HREF="readline.html#IDX104">rl_pending_input</A>
4160 <LI><A HREF="readline.html#IDX100">rl_point</A>
4161 <LI><A HREF="readline.html#IDX192">rl_possible_completions</A>
4162 <LI><A HREF="readline.html#IDX113">rl_pre_input_hook</A>
4163 <LI><A HREF="readline.html#IDX106">rl_prompt</A>
4164 <LI><A HREF="readline.html#IDX136">rl_read_init_file</A>
4165 <LI><A HREF="readline.html#IDX161">rl_read_key</A>
4166 <LI><A HREF="readline.html#IDX109">rl_readline_name</A>
4167 <LI><A HREF="readline.html#IDX149">rl_redisplay</A>
4168 <LI><A HREF="readline.html#IDX116">rl_redisplay_function</A>
4169 <LI><A HREF="readline.html#IDX184">rl_reset_after_signal</A>
4170 <LI><A HREF="readline.html#IDX152">rl_reset_line_state</A>
4171 <LI><A HREF="readline.html#IDX166">rl_reset_terminal</A>
4172 <LI><A HREF="readline.html#IDX185">rl_resize_terminal</A>
4173 <LI><A HREF="readline.html#IDX156">rl_restore_prompt</A>
4174 <LI><A HREF="readline.html#IDX155">rl_save_prompt</A>
4175 <LI><A HREF="readline.html#IDX125">rl_set_keymap</A>
4176 <LI><A HREF="readline.html#IDX186">rl_set_signals</A>
4177 <LI><A HREF="readline.html#IDX208">rl_special_prefixes</A>
4178 <LI><A HREF="readline.html#IDX112">rl_startup_hook</A>
4179 <LI><A HREF="readline.html#IDX163">rl_stuff_char</A>
4180 <LI><A HREF="readline.html#IDX108">rl_terminal_name</A>
4181 <LI><A HREF="readline.html#IDX133">rl_unbind_command_in_map</A>
4182 <LI><A HREF="readline.html#IDX132">rl_unbind_function_in_map</A>
4183 <LI><A HREF="readline.html#IDX130">rl_unbind_key</A>
4184 <LI><A HREF="readline.html#IDX131">rl_unbind_key_in_map</A>
4185 </DIR>
4186 <H2><A NAME="s">s</A></H2>
4187 <DIR>
4188 <LI><A HREF="readline.html#IDX52">self-insert (a, b, A, 1, !, ...)</A>
4189 <LI><A HREF="readline.html#IDX89">set-mark (C-@)</A>
4190 <LI><A HREF="readline.html#IDX24">show-all-if-ambiguous</A>
4191 <LI><A HREF="readline.html#IDX79">start-kbd-macro (C-x ()</A>
4192 </DIR>
4193 <H2><A NAME="t">t</A></H2>
4194 <DIR>
4195 <LI><A HREF="readline.html#IDX51">tab-insert (M-TAB)</A>
4196 <LI><A HREF="readline.html#IDX88">tilde-expand (M-~)</A>
4197 <LI><A HREF="readline.html#IDX175">to_lower</A>
4198 <LI><A HREF="readline.html#IDX174">to_upper</A>
4199 <LI><A HREF="readline.html#IDX53">transpose-chars (C-t)</A>
4200 <LI><A HREF="readline.html#IDX54">transpose-words (M-t)</A>
4201 </DIR>
4202 <H2><A NAME="u">u</A></H2>
4203 <DIR>
4204 <LI><A HREF="readline.html#IDX86">undo (C-_, C-x C-u)</A>
4205 <LI><A HREF="readline.html#IDX73">universal-argument ()</A>
4206 <LI><A HREF="readline.html#IDX60">unix-line-discard (C-u)</A>
4207 <LI><A HREF="readline.html#IDX64">unix-word-rubout (C-w)</A>
4208 <LI><A HREF="readline.html#IDX55">upcase-word (M-u)</A>
4209 <LI><A HREF="readline.html#IDX171">uppercase_p</A>
4210 <LI><A HREF="readline.html#IDX196">username_completion_function</A>
4211 </DIR>
4212 <H2><A NAME="v">v</A></H2>
4213 <DIR>
4214 <LI><A HREF="readline.html#IDX25">visible-stats</A>
4215 </DIR>
4216 <H2><A NAME="y">y</A></H2>
4217 <DIR>
4218 <LI><A HREF="readline.html#IDX70">yank (C-y)</A>
4219 <LI><A HREF="readline.html#IDX46">yank-last-arg (M-., M-_)</A>
4220 <LI><A HREF="readline.html#IDX45">yank-nth-arg (M-C-y)</A>
4221 <LI><A HREF="readline.html#IDX71">yank-pop (M-y)</A>
4222 </DIR>
4223
4224 </P>
4225 <P><HR><P>
4226 This document was generated on 31 December 1998 using the
4227 <A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A>
4228 translator version 1.52.</P>
4229 </BODY>
4230 </HTML>