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 set False 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 to fod or foo, but if we type another o:

$ rm foo[tab]
$ rm foo

the completion completes on foo, even though food and foonly 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 to True.
  • 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 returns None.

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