/Doc/library/readline.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 238 lines · 138 code · 100 blank · 0 comment · 0 complexity · 06fd9a5936c18d94ca3fa29534ddd471 MD5 · raw file

  1. :mod:`readline` --- GNU readline interface
  2. ==========================================
  3. .. module:: readline
  4. :platform: Unix
  5. :synopsis: GNU readline support for Python.
  6. .. sectionauthor:: Skip Montanaro <skip@pobox.com>
  7. The :mod:`readline` module defines a number of functions to facilitate
  8. completion and reading/writing of history files from the Python interpreter.
  9. This module can be used directly or via the :mod:`rlcompleter` module. Settings
  10. made using this module affect the behaviour of both the interpreter's
  11. interactive prompt and the prompts offered by the :func:`raw_input` and
  12. :func:`input` built-in functions.
  13. The :mod:`readline` module defines the following functions:
  14. .. function:: parse_and_bind(string)
  15. Parse and execute single line of a readline init file.
  16. .. function:: get_line_buffer()
  17. Return the current contents of the line buffer.
  18. .. function:: insert_text(string)
  19. Insert text into the command line.
  20. .. function:: read_init_file([filename])
  21. Parse a readline initialization file. The default filename is the last filename
  22. used.
  23. .. function:: read_history_file([filename])
  24. Load a readline history file. The default filename is :file:`~/.history`.
  25. .. function:: write_history_file([filename])
  26. Save a readline history file. The default filename is :file:`~/.history`.
  27. .. function:: clear_history()
  28. Clear the current history. (Note: this function is not available if the
  29. installed version of GNU readline doesn't support it.)
  30. .. versionadded:: 2.4
  31. .. function:: get_history_length()
  32. Return the desired length of the history file. Negative values imply unlimited
  33. history file size.
  34. .. function:: set_history_length(length)
  35. Set the number of lines to save in the history file. :func:`write_history_file`
  36. uses this value to truncate the history file when saving. Negative values imply
  37. unlimited history file size.
  38. .. function:: get_current_history_length()
  39. Return the number of lines currently in the history. (This is different from
  40. :func:`get_history_length`, which returns the maximum number of lines that will
  41. be written to a history file.)
  42. .. versionadded:: 2.3
  43. .. function:: get_history_item(index)
  44. Return the current contents of history item at *index*.
  45. .. versionadded:: 2.3
  46. .. function:: remove_history_item(pos)
  47. Remove history item specified by its position from the history.
  48. .. versionadded:: 2.4
  49. .. function:: replace_history_item(pos, line)
  50. Replace history item specified by its position with the given line.
  51. .. versionadded:: 2.4
  52. .. function:: redisplay()
  53. Change what's displayed on the screen to reflect the current contents of the
  54. line buffer.
  55. .. versionadded:: 2.3
  56. .. function:: set_startup_hook([function])
  57. Set or remove the startup_hook function. If *function* is specified, it will be
  58. used as the new startup_hook function; if omitted or ``None``, any hook function
  59. already installed is removed. The startup_hook function is called with no
  60. arguments just before readline prints the first prompt.
  61. .. function:: set_pre_input_hook([function])
  62. Set or remove the pre_input_hook function. If *function* is specified, it will
  63. be used as the new pre_input_hook function; if omitted or ``None``, any hook
  64. function already installed is removed. The pre_input_hook function is called
  65. with no arguments after the first prompt has been printed and just before
  66. readline starts reading input characters.
  67. .. function:: set_completer([function])
  68. Set or remove the completer function. If *function* is specified, it will be
  69. used as the new completer function; if omitted or ``None``, any completer
  70. function already installed is removed. The completer function is called as
  71. ``function(text, state)``, for *state* in ``0``, ``1``, ``2``, ..., until it
  72. returns a non-string value. It should return the next possible completion
  73. starting with *text*.
  74. .. function:: get_completer()
  75. Get the completer function, or ``None`` if no completer function has been set.
  76. .. versionadded:: 2.3
  77. .. function:: get_completion_type()
  78. Get the type of completion being attempted.
  79. .. versionadded:: 2.6
  80. .. function:: get_begidx()
  81. Get the beginning index of the readline tab-completion scope.
  82. .. function:: get_endidx()
  83. Get the ending index of the readline tab-completion scope.
  84. .. function:: set_completer_delims(string)
  85. Set the readline word delimiters for tab-completion.
  86. .. function:: get_completer_delims()
  87. Get the readline word delimiters for tab-completion.
  88. .. function:: set_completion_display_matches_hook([function])
  89. Set or remove the completion display function. If *function* is
  90. specified, it will be used as the new completion display function;
  91. if omitted or ``None``, any completion display function already
  92. installed is removed. The completion display function is called as
  93. ``function(substitution, [matches], longest_match_length)`` once
  94. each time matches need to be displayed.
  95. .. versionadded:: 2.6
  96. .. function:: add_history(line)
  97. Append a line to the history buffer, as if it was the last line typed.
  98. .. seealso::
  99. Module :mod:`rlcompleter`
  100. Completion of Python identifiers at the interactive prompt.
  101. .. _readline-example:
  102. Example
  103. -------
  104. The following example demonstrates how to use the :mod:`readline` module's
  105. history reading and writing functions to automatically load and save a history
  106. file named :file:`.pyhist` from the user's home directory. The code below would
  107. normally be executed automatically during interactive sessions from the user's
  108. :envvar:`PYTHONSTARTUP` file. ::
  109. import os
  110. histfile = os.path.join(os.environ["HOME"], ".pyhist")
  111. try:
  112. readline.read_history_file(histfile)
  113. except IOError:
  114. pass
  115. import atexit
  116. atexit.register(readline.write_history_file, histfile)
  117. del os, histfile
  118. The following example extends the :class:`code.InteractiveConsole` class to
  119. support history save/restore. ::
  120. import code
  121. import readline
  122. import atexit
  123. import os
  124. class HistoryConsole(code.InteractiveConsole):
  125. def __init__(self, locals=None, filename="<console>",
  126. histfile=os.path.expanduser("~/.console-history")):
  127. code.InteractiveConsole.__init__(self)
  128. self.init_history(histfile)
  129. def init_history(self, histfile):
  130. readline.parse_and_bind("tab: complete")
  131. if hasattr(readline, "read_history_file"):
  132. try:
  133. readline.read_history_file(histfile)
  134. except IOError:
  135. pass
  136. atexit.register(self.save_history, histfile)
  137. def save_history(self, histfile):
  138. readline.write_history_file(histfile)