Completion Support¶
Readline completion support.
Completer Interface¶
- class rl.Completer¶
Interface to the readline completer. Used to configure the completion aspects of readline.
This class is not intended for instantiation beyond the one
completer
object in this module. Typically, applications will import thecompleter
object and use its properties and methods to configure readline:from rl import completer completer.quote_characters = '"\'' completer.query_items = 100 completer.parse_and_bind('TAB: complete')
Settings made through the
completer
object are global and permanent. If you want them restored you have to take care of it yourself.
- Completer.quote_characters¶
Characters that may be used in pairs to quote substrings of the line.
- Completer.word_break_characters¶
Characters that define word boundaries (a.k.a. delimiters).
- Completer.special_prefixes¶
Characters that are word break characters but should be left in the word passed to the completion entry function.
- Completer.filename_quote_characters¶
Characters that must be quoted when they occur in filenames.
- Completer.inhibit_completion¶
If True, completion is disabled and the completion character is inserted as any other character. Defaults to False.
- Completer.query_items¶
Threshold above which the user is prompted if they really want to see all matches. Defaults to 100. A negative value means never prompt.
- Completer.completer¶
The completion entry function. The function is called as
function(text, state)
forstate
in 0, 1, 2, … until it returns None. It should return the next possible completion fortext
. See thegenerator()
factory for a simple way to support this protocol.
- Completer.startup_hook¶
The startup hook function. The function is called with no arguments just before readline prints the first prompt.
- Completer.pre_input_hook¶
The pre-input hook function. The function is called with no arguments after the first prompt has been printed and just before readline starts reading input characters.
- Completer.word_break_hook¶
The word break hook function. The function is called as
function(begidx, endidx)
once per completion and should return a string of word break characters for the current completion or None to indicate no change. The passed-inbegidx
andendidx
are what readline would use if the hook did not exist.
- Completer.char_is_quoted_function¶
The char-is-quoted function. The function is called as
function(text, index)
and should return True if the character atindex
is quoted, False otherwise.
- Completer.filename_quoting_function¶
The filename quoting function. The function is called as
function(text, single_match, quote_char)
and should return a quoted version oftext
or None to indicate no change. Thesingle_match
argument is True if the completion has generated only one match.
- Completer.filename_dequoting_function¶
The filename dequoting function. The function is called as
function(text, quote_char)
and should return a dequoted version oftext
or None to indicate no change.
- Completer.directory_completion_hook¶
The directory completion hook function. This function is allowed to modify the directory portion of filenames readline completes. The function is called as
function(dirname)
and should return a new directory name or None to indicate no change. At the least, the function must perform all necessary dequoting.
- Completer.ignore_some_completions_function¶
The filename filter function. The function is called as
function(substitution, matches)
after all filenames have been generated and should return a filtered subset ofmatches
or None to indicate no change.
- Completer.display_matches_hook¶
The display matches hook function. The function is called as
function(substitution, matches, longest_match_length)
once each time matches need to be displayed. It typically callsdisplay_match_list()
to do the actual work. Note thatlongest_match_length
is not a character count but the “printed length” of the longest string inmatches
.
- Completer.read_init_file(filename=None)¶
Parse a readline initialization file. The default filename is the last filename used.
- Completer.parse_and_bind(line)¶
Parse one line of a readline initialization file.
Additional hooks for when the filesystem representation differs from the representation in the terminal¶
- Completer.directory_rewrite_hook¶
The directory rewrite hook function. This hook is used to prepare the directory name passed to
opendir()
during filename completion. The function is called asfunction(dirname)
and should return a new directory name or None to indicate no change. At the least, the function must perform all necessary dequoting. New in readline 6.2.Under Python 3 this hook returns filesystem encoding to readline.
- Completer.filename_rewrite_hook¶
The filename rewrite hook function. This hook is called for every filename before it is compared against the completion word. The function is called as
function(filename)
and should return a new filename or None to indicate no change. New in readline 6.1.Under Python 3 this hook returns preferred encoding to readline.
- Completer.filename_stat_hook¶
The filename stat hook function. This hook is used to prepare the filename passed to
stat()
during match display. The function is called asfunction(filename)
and should return a new filename or None to indicate no change. New in readline 6.3.Under Python 3 this hook returns filesystem encoding to readline.
Note
If directory_rewrite_hook
and/or
filename_stat_hook
are set,
the directory_completion_hook
must be None,
and vice versa.
Completion Interface¶
- class rl.Completion¶
Interface to the active readline completion. Used to interact with readline when a completion is in progress.
This class is not intended for instantiation beyond the one
completion
object in this module. Typically, applications will import thecompletion
object and use its properties and methods when implementing custom completions:from rl import completion def complete(text): completion.append_character = '@' return completion.complete_username(text)
Settings made through the
completion
object are only valid for the duration of the current completion. They are reset to their defaults when a new completion starts.
- Completion.line_buffer¶
The line buffer readline uses. This property may be assigned to to change the contents of the line.
- Completion.completion_type¶
The type of completion readline performs.
- Completion.begidx¶
The start index of the word in the line.
- Completion.endidx¶
The end index of the word in the line.
- Completion.found_quote¶
True if the word contains or is delimited by any quote character, including backslashes.
- Completion.quote_character¶
The quote character found (not including backslashes).
- Completion.suppress_quote¶
Do not append a matching quote character when completing a quoted string. Defaults to False.
- Completion.append_character¶
The character appended when the completion returns a single match. Defaults to the space character.
- Completion.suppress_append¶
Suppress the append character for this completion. Defaults to False.
- Completion.filename_completion_desired¶
Treat matches as filenames. Directory names will have a slash appended, for example. Defaults to False. Set to True by
complete_filename()
.
- Completion.filename_quoting_desired¶
If matches are filenames, quote them. Defaults to True. Has no effect if
filename_completion_desired
is False.
- Completion.complete_filename(text)¶
Built-in filename completion. May be called from a completion entry function to initiate readline’s filename completion. Returns a list of matches.
- Completion.complete_username(text)¶
Built-in username completion. May be called from a completion entry function to initiate readline’s username completion. Returns a list of matches.
- Completion.expand_tilde(text)¶
Built-in tilde expansion. May be called from anywhere to tilde-expand a filename.
- Completion.display_match_list(substitution, matches, longest_match_length)¶
Built-in matches display. May be called from a custom
display_matches_hook
to perform the default action: columnar display of matches.
- Completion.redisplay(force=False)¶
Update the screen to reflect the current contents of
line_buffer
. Ifforce
is True, readline redisplays the prompt area as well as the line.
Functions¶
- rl.generator(func)¶
Generator function factory.
Takes a function returning a list of matches and returns an object implementing the generator protocol readline requires. The function is called as
function(text)
and should return an iterable of matches fortext
.
- rl.print_exc(func)¶
Decorator printing exceptions to stderr.
Useful when debugging completions and hooks, as exceptions occurring there are usually swallowed by the in-between C code.