Developer Interface¶
This part of the documentation covers all the interfaces of twosheds.
Main Interface¶
All of twoshed’s functionality can be accessed by an instance of the Shell
object.
-
class
twosheds.
Shell
(environ, aliases=None, echo=False, histfile=None, use_suffix=True, exclude=None)¶ A facade encapsulating the high-level logic of a command language interpreter.
Parameters: - aliases – dictionary of aliases
- builtins – dictionary of builtins
- echo – set True to print commands immediately before execution
- environ – a dictionary containing environmental variables. This must include PS1 and PS2, which are used to define the prompts.
- histfile – the location in which to look for a history file. if
unset,
DEFAULT_HISTFILE
is used. histfile is useful when sharing the same home directory between different machines, or when saving separate histories on different terminals. - use_suffix – add a
/
to completed directories and a space to the end of other completed words, to speed typing and provide a visual indicator of successful completion. - exclude – list of regexes to be ignored by completion.
Usage:
>>> import twosheds >>> shell = twosheds.Shell() >>> shell.interact()
-
after_interaction
(f)¶ Register a function to be run after each interaction.
Parameters: f – The function to run after each interaction. This function must not take any parameters.
-
before_interaction
(f)¶ Register a function to be run before each interaction.
Parameters: f – The function to run after each interaction. This function must not take any parameters.
-
completes
(g)¶ Register a generator to extend the capabilities of the completer.
Parameters: g – A generator which, when invoked with a string representing the word the user is trying to complete, should generate strings that the user might find relevant.
-
eval
(text)¶ Respond to text entered by the user.
Parameters: text – the user’s input
-
read
()¶ The shell shall read its input in terms of lines from a file, from a terminal in the case of an interactive shell, or from a string in the case of sh -c or system(). The input lines can be of unlimited length.
-
serve_forever
(banner=None)¶ Interact with the user.
Parameters: banner – (optional) the banner to print before the first interaction. Defaults to None
.
Completion¶
-
class
twosheds.completer.
Completer
(transforms, use_suffix=True, exclude=None, extensions=None)¶ A Completer completes words when given a unique abbreviation.
Type part of a word (for example
ls /usr/lost
) and hit the tab key to run the completer.The shell completes the filename
/usr/lost
to/usr/lost+found/
, replacing the incomplete word with the complete word in the input buffer.Note
Completion adds a
/
to the end of completed directories and a space to the end of other completed words, to speed typing and provide a visual indicator of successful completion. Completer.use_suffix can be setFalse
to prevent this.If no match is found (perhaps
/usr/lost+found
doesn’t exist), then no matches will appear.If the word is already complete (perhaps there is a
/usr/lost
on your system, or perhaps you were thinking too far ahead and typed the whole thing) a/
or space is added to the end if it isn’t already there.The shell will list the remaining choices (if any) below the unfinished command line whenever completion fails, for example:
$ ls /usr/l[tab] lbin/ lib/ local/ lost+found/
Completion will always happen on the shortest possible unique match, even if more typing might result in a longer match. Therefore:
$ ls fodder foo food foonly $ rm fo[tab]
just beeps, because
fo
could expand tofod
orfoo
, but if we type anothero
:$ rm foo[tab] $ rm foo
the completion completes on
foo
, even thoughfood
andfoonly
also match.Note
excludes_patterns
can be set to a list of regular expression patterns to be ignored by completion.Consider that the completer were initialized to ignore
[r'.*~', r'.*.o']
:$ ls Makefile condiments.h~ main.o side.c README main.c meal side.o condiments.h main.c~ $ emacs ma[tab] main.c
Parameters: - use_suffix – add a
/
to completed directories and a space to the end of other completed words, to speed typing and provide a visual indicator of successful completion. Defaults toTrue
. - excludes – a list of regular expression patterns to be ignored by completion.
- extensions – A sequence of generators which can extend the matching capabilities of the completer. Generators must accept a string “word” as the sole argument, representing the word that the user is trying to complete, and use it to generate possible matches.
-
complete
(word, state)¶ Return the next possible completion for
word
.This is called successively with
state == 0, 1, 2, ...
until it returnsNone
.The completion should begin with
word
.Parameters: - word – the word to complete
- state – an int, used to iterate over the choices
-
exclude_matches
(matches)¶ Filter any matches that match an exclude pattern.
Parameters: matches – a list of possible completions
-
gen_filename_completions
(word, filenames)¶ Generate a sequence of filenames that match
word
.Parameters: word – the word to complete
-
gen_matches
(word)¶ Generate a sequence of possible completions for
word
.Parameters: word – the word to complete
-
gen_variable_completions
(word, env)¶ Generate a sequence of possible variable completions for
word
.Parameters: - word – the word to complete
- env – the environment
-
get_matches
(word)¶ Get a list of filenames with match word.
-
inflect
(filename)¶ Inflect a filename to indicate its type.
If the file is a directory, the suffix “/” is appended, otherwise a space is appended.
Parameters: filename – the name of the file to inflect
- use_suffix – add a