Doc/lib/libreadline.tex

   1 \section{\module{readline} ---
   2          GNU readline interface}
   3
   4 \declaremodule{builtin}{readline}
   5   \platform{Unix}
   6 \sectionauthor{Skip Montanaro}{skip@mojam.com}
   7 \modulesynopsis{GNU Readline in Python.}
   8
   9
  10 The \module{readline} module defines a number of functions used either
  11 directly or from the \refmodule{rlcompleter} module to facilitate
  12 completion and history file read and write from the Python
  13 interpreter.
  14
  15 The \module{readline} module defines the following functions:
  16
  17
  18 \begin{funcdesc}{parse_and_bind}{string}
  19 Parse and execute single line of a readline init file.
  20 \end{funcdesc}
  21
  22 \begin{funcdesc}{get_line_buffer}{}
  23 Return the current contents of the line buffer.
  24 \end{funcdesc}
  25
  26 \begin{funcdesc}{insert_text}{string}
  27 Insert text into the command line.
  28 \end{funcdesc}
  29
  30 \begin{funcdesc}{read_init_file}{\optional{filename}}
  31 Parse a readline initialization file.
  32 The default filename is the last filename used.
  33 \end{funcdesc}
  34
  35 \begin{funcdesc}{read_history_file}{\optional{filename}}
  36 Load a readline history file.
  37 The default filename is \file{\~{}/.history}.
  38 \end{funcdesc}
  39
  40 \begin{funcdesc}{write_history_file}{\optional{filename}}
  41 Save a readline history file.
  42 The default filename is \file{\~{}/.history}.
  43 \end{funcdesc}
  44
  45 \begin{funcdesc}{get_history_length}{}
  46 Return the desired length of the history file.  Negative values imply
  47 unlimited history file size.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{set_history_length}{length}
  51 Set the number of lines to save in the history file.
  52 \function{write_history_file()} uses this value to truncate the
  53 history file when saving.  Negative values imply unlimited history
  54 file size.
  55 \end{funcdesc}
  56
  57 \begin{funcdesc}{set_completer}{\optional{function}}
  58 Set or remove the completer function.  The completer function is
  59 called as \code{\var{function}(\var{text}, \var{state})},
  60 \code{for i in [0, 1, 2, ...]} until it returns a non-string.
  61 It should return the next possible completion starting with \var{text}.
  62 \end{funcdesc}
  63
  64 \begin{funcdesc}{get_begidx}{}
  65 Get the beginning index of the readline tab-completion scope.
  66 \end{funcdesc}
  67
  68 \begin{funcdesc}{get_endidx}{}
  69 Get the ending index of the readline tab-completion scope.
  70 \end{funcdesc}
  71
  72 \begin{funcdesc}{set_completer_delims}{string}
  73 Set the readline word delimiters for tab-completion.
  74 \end{funcdesc}
  75
  76 \begin{funcdesc}{get_completer_delims}{}
  77 Get the readline word delimiters for tab-completion.
  78 \end{funcdesc}
  79
  80
  81 \begin{seealso}
  82   \seemodule{rlcompleter}{Completion of Python identifiers at the
  83                           interactive prompt.}
  84 \end{seealso}
  85
  86
  87 \subsection{Example \label{readline-example}}
  88
  89 The following example demonstrates how to use the
  90 \module{readline} module's history reading and writing functions to
  91 automatically load and save a history file named \file{.pyhist} from
  92 the user's home directory.  The code below would normally be executed
  93 automatically during interactive sessions from the user's
  94 \envvar{PYTHONSTARTUP} file.
  95
  96 \begin{verbatim}
  97 import os
  98 histfile = os.path.join(os.environ["HOME"], ".pyhist")
  99 try:
 100     readline.read_history_file(histfile)
 101 except IOError:
 102     pass
 103 import atexit
 104 atexit.register(readline.write_history_file, histfile)
 105 del os, histfile
 106 \end{verbatim}