2 Customizing Expeditor

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 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.