| <html lang="en"> |
| <head> |
| <title>Readline Init File Syntax - Debugging with GDB</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="Debugging with GDB"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="up" href="Readline-Init-File.html#Readline-Init-File" title="Readline Init File"> |
| <link rel="next" href="Conditional-Init-Constructs.html#Conditional-Init-Constructs" title="Conditional Init Constructs"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 |
| Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Free Software'' and ``Free Software Needs |
| Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' |
| and with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: ``You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom.''--> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| <link rel="stylesheet" type="text/css" href="../cs.css"> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="Readline-Init-File-Syntax"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="Conditional-Init-Constructs.html#Conditional-Init-Constructs">Conditional Init Constructs</a>, |
| Up: <a rel="up" accesskey="u" href="Readline-Init-File.html#Readline-Init-File">Readline Init File</a> |
| <hr> |
| </div> |
| |
| <h4 class="subsection">31.3.1 Readline Init File Syntax</h4> |
| |
| <p>There are only a few basic constructs allowed in the |
| Readline init file. Blank lines are ignored. |
| Lines beginning with a ‘<samp><span class="samp">#</span></samp>’ are comments. |
| Lines beginning with a ‘<samp><span class="samp">$</span></samp>’ indicate conditional |
| constructs (see <a href="Conditional-Init-Constructs.html#Conditional-Init-Constructs">Conditional Init Constructs</a>). Other lines |
| denote variable settings and key bindings. |
| |
| <dl> |
| <dt>Variable Settings<dd>You can modify the run-time behavior of Readline by |
| altering the values of variables in Readline |
| using the <code>set</code> command within the init file. |
| The syntax is simple: |
| |
| <pre class="example"> set <var>variable</var> <var>value</var> |
| </pre> |
| <p class="noindent">Here, for example, is how to |
| change from the default Emacs-like key binding to use |
| <code>vi</code> line editing commands: |
| |
| <pre class="example"> set editing-mode vi |
| </pre> |
| <p>Variable names and values, where appropriate, are recognized without regard |
| to case. Unrecognized variable names are ignored. |
| |
| <p>Boolean variables (those that can be set to on or off) are set to on if |
| the value is null or empty, <var>on</var> (case-insensitive), or 1. Any other |
| value results in the variable being set to off. |
| |
| <p>A great deal of run-time behavior is changeable with the following |
| variables. |
| |
| <p><a name="index-variables_002c-readline-2194"></a> |
| <dl> |
| <dt><code>bell-style</code><dd><a name="index-bell_002dstyle-2195"></a>Controls what happens when Readline wants to ring the terminal bell. |
| If set to ‘<samp><span class="samp">none</span></samp>’, Readline never rings the bell. If set to |
| ‘<samp><span class="samp">visible</span></samp>’, Readline uses a visible bell if one is available. |
| If set to ‘<samp><span class="samp">audible</span></samp>’ (the default), Readline attempts to ring |
| the terminal's bell. |
| |
| <br><dt><code>bind-tty-special-chars</code><dd><a name="index-bind_002dtty_002dspecial_002dchars-2196"></a>If set to ‘<samp><span class="samp">on</span></samp>’, Readline attempts to bind the control characters |
| treated specially by the kernel's terminal driver to their Readline |
| equivalents. |
| |
| <br><dt><code>comment-begin</code><dd><a name="index-comment_002dbegin-2197"></a>The string to insert at the beginning of the line when the |
| <code>insert-comment</code> command is executed. The default value |
| is <code>"#"</code>. |
| |
| <br><dt><code>completion-ignore-case</code><dd>If set to ‘<samp><span class="samp">on</span></samp>’, Readline performs filename matching and completion |
| in a case-insensitive fashion. |
| The default value is ‘<samp><span class="samp">off</span></samp>’. |
| |
| <br><dt><code>completion-query-items</code><dd><a name="index-completion_002dquery_002ditems-2198"></a>The number of possible completions that determines when the user is |
| asked whether the list of possibilities should be displayed. |
| If the number of possible completions is greater than this value, |
| Readline will ask the user whether or not he wishes to view |
| them; otherwise, they are simply listed. |
| This variable must be set to an integer value greater than or equal to 0. |
| A negative value means Readline should never ask. |
| The default limit is <code>100</code>. |
| |
| <br><dt><code>convert-meta</code><dd><a name="index-convert_002dmeta-2199"></a>If set to ‘<samp><span class="samp">on</span></samp>’, Readline will convert characters with the |
| eighth bit set to an <span class="sc">ascii</span> key sequence by stripping the eighth |
| bit and prefixing an <ESC> character, converting them to a |
| meta-prefixed key sequence. The default value is ‘<samp><span class="samp">on</span></samp>’. |
| |
| <br><dt><code>disable-completion</code><dd><a name="index-disable_002dcompletion-2200"></a>If set to ‘<samp><span class="samp">On</span></samp>’, Readline will inhibit word completion. |
| Completion characters will be inserted into the line as if they had |
| been mapped to <code>self-insert</code>. The default is ‘<samp><span class="samp">off</span></samp>’. |
| |
| <br><dt><code>editing-mode</code><dd><a name="index-editing_002dmode-2201"></a>The <code>editing-mode</code> variable controls which default set of |
| key bindings is used. By default, Readline starts up in Emacs editing |
| mode, where the keystrokes are most similar to Emacs. This variable can be |
| set to either ‘<samp><span class="samp">emacs</span></samp>’ or ‘<samp><span class="samp">vi</span></samp>’. |
| |
| <br><dt><code>enable-keypad</code><dd><a name="index-enable_002dkeypad-2202"></a>When set to ‘<samp><span class="samp">on</span></samp>’, Readline will try to enable the application |
| keypad when it is called. Some systems need this to enable the |
| arrow keys. The default is ‘<samp><span class="samp">off</span></samp>’. |
| |
| <br><dt><code>expand-tilde</code><dd><a name="index-expand_002dtilde-2203"></a>If set to ‘<samp><span class="samp">on</span></samp>’, tilde expansion is performed when Readline |
| attempts word completion. The default is ‘<samp><span class="samp">off</span></samp>’. |
| |
| <br><dt><code>history-preserve-point</code><dd><a name="index-history_002dpreserve_002dpoint-2204"></a>If set to ‘<samp><span class="samp">on</span></samp>’, the history code attempts to place point at the |
| same location on each history line retrieved with <code>previous-history</code> |
| or <code>next-history</code>. The default is ‘<samp><span class="samp">off</span></samp>’. |
| |
| <br><dt><code>horizontal-scroll-mode</code><dd><a name="index-horizontal_002dscroll_002dmode-2205"></a>This variable can be set to either ‘<samp><span class="samp">on</span></samp>’ or ‘<samp><span class="samp">off</span></samp>’. Setting it |
| to ‘<samp><span class="samp">on</span></samp>’ means that the text of the lines being edited will scroll |
| horizontally on a single screen line when they are longer than the width |
| of the screen, instead of wrapping onto a new screen line. By default, |
| this variable is set to ‘<samp><span class="samp">off</span></samp>’. |
| |
| <br><dt><code>input-meta</code><dd><a name="index-input_002dmeta-2206"></a><a name="index-meta_002dflag-2207"></a>If set to ‘<samp><span class="samp">on</span></samp>’, Readline will enable eight-bit input (it |
| will not clear the eighth bit in the characters it reads), |
| regardless of what the terminal claims it can support. The |
| default value is ‘<samp><span class="samp">off</span></samp>’. The name <code>meta-flag</code> is a |
| synonym for this variable. |
| |
| <br><dt><code>isearch-terminators</code><dd><a name="index-isearch_002dterminators-2208"></a>The string of characters that should terminate an incremental search without |
| subsequently executing the character as a command (see <a href="Searching.html#Searching">Searching</a>). |
| If this variable has not been given a value, the characters <ESC> and |
| <kbd>C-J</kbd> will terminate an incremental search. |
| |
| <br><dt><code>keymap</code><dd><a name="index-keymap-2209"></a>Sets Readline's idea of the current keymap for key binding commands. |
| Acceptable <code>keymap</code> names are |
| <code>emacs</code>, |
| <code>emacs-standard</code>, |
| <code>emacs-meta</code>, |
| <code>emacs-ctlx</code>, |
| <code>vi</code>, |
| <code>vi-move</code>, |
| <code>vi-command</code>, and |
| <code>vi-insert</code>. |
| <code>vi</code> is equivalent to <code>vi-command</code>; <code>emacs</code> is |
| equivalent to <code>emacs-standard</code>. The default value is <code>emacs</code>. |
| The value of the <code>editing-mode</code> variable also affects the |
| default keymap. |
| |
| <br><dt><code>mark-directories</code><dd>If set to ‘<samp><span class="samp">on</span></samp>’, completed directory names have a slash |
| appended. The default is ‘<samp><span class="samp">on</span></samp>’. |
| |
| <br><dt><code>mark-modified-lines</code><dd><a name="index-mark_002dmodified_002dlines-2210"></a>This variable, when set to ‘<samp><span class="samp">on</span></samp>’, causes Readline to display an |
| asterisk (‘<samp><span class="samp">*</span></samp>’) at the start of history lines which have been modified. |
| This variable is ‘<samp><span class="samp">off</span></samp>’ by default. |
| |
| <br><dt><code>mark-symlinked-directories</code><dd><a name="index-mark_002dsymlinked_002ddirectories-2211"></a>If set to ‘<samp><span class="samp">on</span></samp>’, completed names which are symbolic links |
| to directories have a slash appended (subject to the value of |
| <code>mark-directories</code>). |
| The default is ‘<samp><span class="samp">off</span></samp>’. |
| |
| <br><dt><code>match-hidden-files</code><dd><a name="index-match_002dhidden_002dfiles-2212"></a>This variable, when set to ‘<samp><span class="samp">on</span></samp>’, causes Readline to match files whose |
| names begin with a ‘<samp><span class="samp">.</span></samp>’ (hidden files) when performing filename |
| completion, unless the leading ‘<samp><span class="samp">.</span></samp>’ is |
| supplied by the user in the filename to be completed. |
| This variable is ‘<samp><span class="samp">on</span></samp>’ by default. |
| |
| <br><dt><code>output-meta</code><dd><a name="index-output_002dmeta-2213"></a>If set to ‘<samp><span class="samp">on</span></samp>’, Readline will display characters with the |
| eighth bit set directly rather than as a meta-prefixed escape |
| sequence. The default is ‘<samp><span class="samp">off</span></samp>’. |
| |
| <br><dt><code>page-completions</code><dd><a name="index-page_002dcompletions-2214"></a>If set to ‘<samp><span class="samp">on</span></samp>’, Readline uses an internal <code>more</code>-like pager |
| to display a screenful of possible completions at a time. |
| This variable is ‘<samp><span class="samp">on</span></samp>’ by default. |
| |
| <br><dt><code>print-completions-horizontally</code><dd>If set to ‘<samp><span class="samp">on</span></samp>’, Readline will display completions with matches |
| sorted horizontally in alphabetical order, rather than down the screen. |
| The default is ‘<samp><span class="samp">off</span></samp>’. |
| |
| <br><dt><code>show-all-if-ambiguous</code><dd><a name="index-show_002dall_002dif_002dambiguous-2215"></a>This alters the default behavior of the completion functions. If |
| set to ‘<samp><span class="samp">on</span></samp>’, |
| words which have more than one possible completion cause the |
| matches to be listed immediately instead of ringing the bell. |
| The default value is ‘<samp><span class="samp">off</span></samp>’. |
| |
| <br><dt><code>show-all-if-unmodified</code><dd><a name="index-show_002dall_002dif_002dunmodified-2216"></a>This alters the default behavior of the completion functions in |
| a fashion similar to <var>show-all-if-ambiguous</var>. |
| If set to ‘<samp><span class="samp">on</span></samp>’, |
| words which have more than one possible completion without any |
| possible partial completion (the possible completions don't share |
| a common prefix) cause the matches to be listed immediately instead |
| of ringing the bell. |
| The default value is ‘<samp><span class="samp">off</span></samp>’. |
| |
| <br><dt><code>visible-stats</code><dd><a name="index-visible_002dstats-2217"></a>If set to ‘<samp><span class="samp">on</span></samp>’, a character denoting a file's type |
| is appended to the filename when listing possible |
| completions. The default is ‘<samp><span class="samp">off</span></samp>’. |
| |
| </dl> |
| |
| <br><dt>Key Bindings<dd>The syntax for controlling key bindings in the init file is |
| simple. First you need to find the name of the command that you |
| want to change. The following sections contain tables of the command |
| name, the default keybinding, if any, and a short description of what |
| the command does. |
| |
| <p>Once you know the name of the command, simply place on a line |
| in the init file the name of the key |
| you wish to bind the command to, a colon, and then the name of the |
| command. The name of the key |
| can be expressed in different ways, depending on what you find most |
| comfortable. |
| |
| <p>In addition to command names, readline allows keys to be bound |
| to a string that is inserted when the key is pressed (a <var>macro</var>). |
| |
| <dl> |
| <dt><var>keyname</var>: <var>function-name</var> or <var>macro</var><!-- /@w --><dd><var>keyname</var> is the name of a key spelled out in English. For example: |
| <pre class="example"> Control-u: universal-argument |
| Meta-Rubout: backward-kill-word |
| Control-o: "> output" |
| </pre> |
| <p>In the above example, <kbd>C-u</kbd> is bound to the function |
| <code>universal-argument</code>, |
| <kbd>M-DEL</kbd> is bound to the function <code>backward-kill-word</code>, and |
| <kbd>C-o</kbd> is bound to run the macro |
| expressed on the right hand side (that is, to insert the text |
| ‘<samp><span class="samp">> output</span></samp>’ into the line). |
| |
| <p>A number of symbolic character names are recognized while |
| processing this key binding syntax: |
| <var>DEL</var>, |
| <var>ESC</var>, |
| <var>ESCAPE</var>, |
| <var>LFD</var>, |
| <var>NEWLINE</var>, |
| <var>RET</var>, |
| <var>RETURN</var>, |
| <var>RUBOUT</var>, |
| <var>SPACE</var>, |
| <var>SPC</var>, |
| and |
| <var>TAB</var>. |
| |
| <br><dt>"<var>keyseq</var>": <var>function-name</var> or <var>macro</var><!-- /@w --><dd><var>keyseq</var> differs from <var>keyname</var> above in that strings |
| denoting an entire key sequence can be specified, by placing |
| the key sequence in double quotes. Some <span class="sc">gnu</span> Emacs style key |
| escapes can be used, as in the following example, but the |
| special character names are not recognized. |
| |
| <pre class="example"> "\C-u": universal-argument |
| "\C-x\C-r": re-read-init-file |
| "\e[11~": "Function Key 1" |
| </pre> |
| <p>In the above example, <kbd>C-u</kbd> is again bound to the function |
| <code>universal-argument</code> (just as it was in the first example), |
| ‘<samp><kbd>C-x</kbd> <kbd>C-r</kbd></samp>’ is bound to the function <code>re-read-init-file</code>, |
| and ‘<samp><span class="samp"><ESC> <[> <1> <1> <~></span></samp>’ is bound to insert |
| the text ‘<samp><span class="samp">Function Key 1</span></samp>’. |
| |
| </dl> |
| |
| <p>The following <span class="sc">gnu</span> Emacs style escape sequences are available when |
| specifying key sequences: |
| |
| <dl> |
| <dt><kbd>\C-</kbd><dd>control prefix |
| <br><dt><kbd>\M-</kbd><dd>meta prefix |
| <br><dt><kbd>\e</kbd><dd>an escape character |
| <br><dt><kbd>\\</kbd><dd>backslash |
| <br><dt><kbd>\"</kbd><dd><">, a double quotation mark |
| <br><dt><kbd>\'</kbd><dd><'>, a single quote or apostrophe |
| </dl> |
| |
| <p>In addition to the <span class="sc">gnu</span> Emacs style escape sequences, a second |
| set of backslash escapes is available: |
| |
| <dl> |
| <dt><code>\a</code><dd>alert (bell) |
| <br><dt><code>\b</code><dd>backspace |
| <br><dt><code>\d</code><dd>delete |
| <br><dt><code>\f</code><dd>form feed |
| <br><dt><code>\n</code><dd>newline |
| <br><dt><code>\r</code><dd>carriage return |
| <br><dt><code>\t</code><dd>horizontal tab |
| <br><dt><code>\v</code><dd>vertical tab |
| <br><dt><code>\</code><var>nnn</var><dd>the eight-bit character whose value is the octal value <var>nnn</var> |
| (one to three digits) |
| <br><dt><code>\x</code><var>HH</var><dd>the eight-bit character whose value is the hexadecimal value <var>HH</var> |
| (one or two hex digits) |
| </dl> |
| |
| <p>When entering the text of a macro, single or double quotes must |
| be used to indicate a macro definition. |
| Unquoted text is assumed to be a function name. |
| In the macro body, the backslash escapes described above are expanded. |
| Backslash will quote any other character in the macro text, |
| including ‘<samp><span class="samp">"</span></samp>’ and ‘<samp><span class="samp">'</span></samp>’. |
| For example, the following binding will make ‘<samp><kbd>C-x</kbd><span class="samp"> \</span></samp>’ |
| insert a single ‘<samp><span class="samp">\</span></samp>’ into the line: |
| <pre class="example"> "\C-x\\": "\\" |
| </pre> |
| </dl> |
| |
| </body></html> |
| |
