2 Customizing Expeditor

▼ |  | Expeditor: Terminal Expression Editor

1 | Default Key Bindings
2 | Customizing Expeditor
3 | Expeditor API

► | 2 | Customizing Expeditor

2.1 | Key-Handling Functions
2.2 | Colors
2.3 | History Navigation

On this page:

2.1 Key-Handling Functions
expeditor-bind-key!
ee-insert-self/ paren
ee-insert-self
make-ee-insert-string
ee-newline/ accept
ee-accept
ee-newline
ee-open-line
ee-indent
ee-indent-all
ee-id-completion/ indent
ee-id-completion/ indent/ reverse
ee-id-completion
ee-next-id-completion
ee-backward-char
ee-forward-char
ee-next-line
ee-previous-line
ee-forward-word
ee-forward-exp
ee-backward-word
ee-backward-exp
ee-upward-exp
ee-downward-exp
ee-backward-page
ee-forward-page
ee-beginning-of-line
ee-end-of-line
ee-beginning-of-entry
ee-end-of-entry
ee-goto-matching-delimiter
ee-flash-matching-delimiter
ee-transpose-char
ee-transpose-word
ee-transpose-exp
ee-set-mark
ee-exchange-point-and-mark
ee-delete-char
ee-backward-delete-char
ee-delete-line
ee-delete-to-eol
ee-delete-between-point-and-mark-or-backward
ee-delete-entry
ee-reset-entry/ break
ee-reset-entry
ee-delete-word
ee-delete-exp
ee-backward-delete-exp
ee-yank-selection
ee-yank-kill-buffer
ee-eof/ delete-char
ee-eof
ee-redisplay
ee-history-bwd
ee-history-fwd
ee-history-bwd-prefix
ee-history-bwd-contains
ee-history-fwd-prefix
ee-history-fwd-contains
ee-command-repeat
ee-suspend-process
eestate?
entry?
2.2 Colors
expeditor-set-syntax-color!
2.3 History Navigation
current-ee-backward-history-point
current-ee-forward-history-point

top contents ← prev up next →

## 2 Customizing Expeditor🔗ℹ

(require (submod expeditor configure))

When expeditor-configure is called—such as when xrepl initializes the expeditor, which is the default behavior when running racket at the command line—it dynamically requires the module file reported by (expeditor-init-file-path), if that file exists. The module file can import (submod expeditor configure) to configure key bindings and colors.

For example, the following module as (expeditor-init-file-path) changes the behavior of Ctl-J and changes the color of literals from green to magenta:

> #lang racket/base
> (require (submod expeditor configure))
> (expeditor-bind-key! "^J" ee-newline)
> (expeditor-set-syntax-color! 'literal 'magenta)

### 2.1 Key-Handling Functions🔗ℹ

A key-handling function accepts three values: a representation of the terminal state, a representation of the current editor region, and a character. The result is a representation of the editor region (usually the one passed in) or #f to indicate that the current editor region should be accepted as input.

> procedure (expeditor-bind-key! key handler) → void?
> key : string?
> handler : (eestate? entry? char . -> . (or/c #f entry?))

Binds the action of key to handler, where handler is typically one of the ee- functions described below.

The key string encodes either a single key or a sequence of keys:

- The sequence \e (so, in a literal string as "\\e") is treated as Escape, which at the start of a sequence is normally the way terminals report “Meta-” key combinations.

- A ^ prefix on a character implies a “Ctl-” combination, like "^a" for Ctl-A.

- The sequence \\ is a backslash (so, in a literal string as "\\\\").

- The sequence \^ is the character character.

- Anything else stands for itself.

The result of a key binding is a potentially updated entry, where only predefined functions can update an entry, or #f to indicate that the current entry should be accepted as an expeditor-read result.

As examples, here are a few bindings from the default set:

> (expeditor-bind-key! "^B" ee-backward-char) ; Ctl-B
> (expeditor-bind-key! "\\ef" ee-forward-word) ; Esc-f
> (expeditor-bind-key! "\\e[C" ee-forward-char) ; Right
> (expeditor-bind-key! "\\e[1;5C" ee-forward-word) ; Ctl-Right

The Right and Ctl-Right bindings are derived from a typical sequence that a terminal generates for those key combinations. In your terminal, the od program may be helpful in figuring how key presses turn into program input.

> procedure (ee-insert-self/paren ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

This function is the default operation for unmapped keys.

Like ee-insert-self, but if c is a “parenthesis” character, flashes its match like ee-flash-matching-delimiter. Furthermore, if c is a closing “parenthesis”, it may be corrected automatically based on its apparently intended match.

> procedure (ee-insert-self ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Inserts c, as long as it is not a control character.

> procedure ((make-ee-insert-string s) ee entry c) → entry?
> s : string?
> ee : eestate?
> entry : entry?
> c : char?

Creates a key-handling function that inserts s.

> procedure (ee-newline/accept ee entry c) → (or/c entry? #f)
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Return. Note that the return value is #f in the case that the input should be accepted.

> procedure (ee-accept ee entry c) → (or/c #f entry?)
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-Ctl-J. Note that the return value is #f in the case that the input should be accepted.

> procedure (ee-newline ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-Return.

> procedure (ee-open-line ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-O.

> procedure (ee-indent ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-Tab.

> procedure (ee-indent-all ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-q.

> procedure (ee-id-completion/indent ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Tab.

> procedure (ee-id-completion/indent/reverse ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Shift-Tab.

Added in version 1.2.

> procedure (ee-id-completion ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Like ee-id-completion, but always attempts completion instead of tabbing.

> procedure (ee-next-id-completion ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-R.

> procedure (ee-backward-char ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Left.

> procedure (ee-forward-char ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Right.

> procedure (ee-next-line ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Down.

> procedure (ee-previous-line ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Up.

> procedure (ee-forward-word ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-Right.

> procedure (ee-forward-exp ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-Ctl-Right.

> procedure (ee-backward-word ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-Left.

> procedure (ee-backward-exp ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-Ctl-Left.

> procedure (ee-upward-exp ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-Ctl-U.

> procedure (ee-downward-exp ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-Ctl-D.

> procedure (ee-backward-page ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for PageUp.

> procedure (ee-forward-page ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for PageDown.

> procedure (ee-beginning-of-line ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Home.

> procedure (ee-end-of-line ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for End.

> procedure (ee-beginning-of-entry ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-<.

> procedure (ee-end-of-entry ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta->.

> procedure (ee-goto-matching-delimiter ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-].

> procedure (ee-flash-matching-delimiter ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-].

> procedure (ee-transpose-char ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-T.

> procedure (ee-transpose-word ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-t.

> procedure (ee-transpose-exp ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-Ctl-T.

> procedure (ee-set-mark ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-@.

> procedure (ee-exchange-point-and-mark ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-X Ctl-X.

> procedure (ee-delete-char ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Delete.

> procedure (ee-backward-delete-char ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Backspace.

> procedure (ee-delete-line ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-U.

> procedure (ee-delete-to-eol ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-K.

> > procedure
> > (ee-delete-between-point-and-mark-or-backward |  | ee |  |  |  |
> > |  | entry |  |  |  |
> > |  | c) |  | → |  | entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-W.

> procedure (ee-delete-entry ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-G.

> procedure (ee-reset-entry/break ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-C.

> procedure (ee-reset-entry ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Like ee-reset-entry/break, but never sends a break signal.

> procedure (ee-delete-word ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-d.

> procedure (ee-delete-exp ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-Delete.

> procedure (ee-backward-delete-exp ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-Backspace.

> procedure (ee-yank-selection ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-V.

> procedure (ee-yank-kill-buffer ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-Y.

> procedure (ee-eof/delete-char ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-D.

> procedure (ee-eof ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Like ee-eof/delete-char, but always return an end-of-file.

> procedure (ee-redisplay ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-L.

> procedure (ee-history-bwd ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-Up. See also current-ee-backward-history-point.

> procedure (ee-history-fwd ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-Down. See also current-ee-forward-history-point.

> procedure (ee-history-bwd-prefix ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-p. See also current-ee-backward-history-point.

> procedure (ee-history-bwd-contains ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-P. See also current-ee-backward-history-point.

> procedure (ee-history-fwd-prefix ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-n. See also current-ee-forward-history-point.

> procedure (ee-history-fwd-contains ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Meta-N. See also current-ee-forward-history-point.

> procedure (ee-command-repeat ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Accumulates c into a repeat count if it is a digit. Otherwise, performs the command associated with c the number of times set up for repeating.

> procedure (ee-suspend-process ee entry c) → entry?
> ee : eestate?
> entry : entry?
> c : char?

Implements the behavior described for Ctl-Z.

> procedure (eestate? v) → boolean?
> v : any/c

Returns #t if v is a representation of the terminal state, #f otherwise.

> procedure (entry? v) → boolean?
> v : any/c

Returns #t if v is a representation of the current editor region, #f otherwise.

### 2.2 Colors🔗ℹ

> > procedure
> > (expeditor-set-syntax-color! |  | category |  |  |  |
> > |  | color) |  | → |  | void?
> | category |  | : |  |
> (or/c 'error
> 'paren
> 'literal
> 'identifier
> 'comment)
> | color |  | : |  |
> (or/c 'default
> 'black
> 'white
> 'red
> 'green
> 'blue
> 'yellow
> 'cyan
> 'magenta
> 'dark-gray
> 'light-gray
> 'light-red
> 'light-green
> 'light-blue
> 'light-yellow
> 'light-cyan
> 'light-magenta)

Sets the color used for a syntactic category when coloring is enabled. The 'error color is used by expeditor-error-display in addition to being used for invalid tokens.

### 2.3 History Navigation🔗ℹ

> parameter (current-ee-backward-history-point)
> → (or/c 'start 'top 'bottom 'end)
> (current-ee-backward-history-point start-at) → void?
> start-at : (or/c 'start 'top 'bottom 'end)

A parameter that determines where the cursor starts when the editor content is changed to an earlier entry in the history via ee-history-bwd and similar functions:

- 'start — at the start of the entry

- 'top — at the end of the first line of the entry

- 'bottom or 'end — at the end of the last line of the entry

The default is 'top.

> parameter (current-ee-forward-history-point)
> → (or/c 'start 'top 'bottom 'end)
> (current-ee-forward-history-point start-at) → void?
> start-at : (or/c 'start 'top 'bottom 'end)

Like current-ee-backward-history-point, but used when the editor content is changed to a later entry in the history via ee-history-fwd and similar functions.

The default is 'bottom.

top contents ← prev up next →