Skip to content
Back to top
View this page
Edit this page

# Tutorial: `prompt_toolkit` custom keybindings

Are you really jonesing for some special keybindings? We can help you out with that. The first time is free and so is every other time!

Warning

This tutorial will let you hook directly into the `prompt_toolkit` keybinding manager. It will not stop you from rendering your prompt completely unusable, so tread lightly.

## Overview

The `prompt_toolkit` shell has a registry for handling custom keybindings. You may not like the default keybindings in xonsh, or you may want to add a new key binding.

We’ll walk you though how to do this using `prompt_toolkit` tools to define keybindings and warn you about potential pitfalls.

All of the code below can be entered into your xonshrc

## Control characters

We can’t and won’t stop you from doing what you want, but in the interest of a functioning shell, you probably shouldn’t mess with the following keystrokes. Some of them are ASCII control characters and really shouldn’t be used. The others are used by xonsh and will result in some loss of functionality (in less you take the time to rebind them elsewhere).

Keystroke | ASCII control representation | Default command
--- | --- | ---
`Control J` | `<Enter>` | Run command
`Control I` | `<Tab>` | Indent, autocomplete
`Control R` |  | Backwards history search
`Control Z` |  | SIGSTOP current job
`Control C` |  | SIGINT current job

## Useful imports

There are a few useful `prompt_toolkit` tools that will help us create better bindings:

    from prompt_toolkit.keys import Keys
    from prompt_toolkit.filters import Condition, EmacsInsertMode, ViInsertMode

## Custom keyload function

We need our additional keybindings to load after the shell is initialized, so we define a function that contains all of the custom keybindings and decorate it with the appropriate event, in this case `on_ptk_create`.

We’ll start with a toy example that just inserts the text “hi” into the current line of the prompt:

    @events.on_ptk_create
    def custom_keybindings(bindings, **kw):

        @bindings.add(Keys.ControlW)
        def say_hi(event):
            event.current_buffer.insert_text('hi')

Put that in your xonshrc, restart xonsh and then see if pressing `Ctrl-w` does anything (it should!)

Note

It is also possible to write `Keys.ControlW` like `c-w`.

## What commands can keybindings run?

Pretty much anything! Since we’re defining these commands after xonsh has started up, we can create keybinding events that run subprocess commands with hardly any effort at all. If we wanted to, say, have a command that runs `ls -l` in the current directory:

    @handler(Keys.ControlP)
    def run_ls(event):
        ls -l
        event.cli.renderer.erase()

Note

The `event.cli.renderer.erase()` is required to redraw the prompt after asking for a separate command to send information to `STDOUT`

## Restrict actions with filters

Often we want a key command to only work if certain conditions are met. For instance, the `<TAB>` key in xonsh brings up the completions menu, but then it also cycles through the available completions. We use filters to create this behavior.

A few helpful filters are included with `prompt_toolkit`, like `ViInsertMode` and `EmacsInsertMode`, which return `True` when the respective insert mode is active.

But it’s also easy to create our own filters that take advantage of xonsh’s beautiful strangeness. Suppose we want a filter to restrict a given command to run only when there are fewer than ten files in a given directory. We just need a function that returns a Bool that matches that requirement and then we decorate it! And remember, those functions can be in xonsh-language, not just pure Python:

    @Condition
    def lt_ten_files(cli):
        return len(g`*`) < 10

Note

See the tutorial section on globbing for more globbing options.

Now that the condition is defined, we can pass it as a `filter` keyword to a keybinding definition:

    @handler(Keys.ControlL, filter=lt_ten_files)
    def ls_if_lt_ten(event):
        ls -l
        event.cli.renderer.erase()

With both of those in your `.xonshrc`, pressing `Control L` will list the contents of your current directory if there are fewer than 10 items in it. Useful? Debatable. Powerful? Yes.