3 Expeditor API

▼ |  | Expeditor: Terminal Expression Editor

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

On this page:

expeditor-open
expeditor-close
expeditor-read
call-with-expeditor
expeditor-configure
expeditor-init-file-path
current-expeditor-reader
current-expeditor-post-skipper
current-expeditor-lexer
current-expeditor-ready-checker
current-expeditor-parentheses
current-expeditor-grouper
current-expeditor-indenter
current-expeditor-color-enabled
current-expeditor-history
current-expeditor-history-whitespace-trim-enabled
expeditor-error-display

Racket
top contents ← prev up next →

## 3 Expeditor API🔗ℹ

> procedure (expeditor-open history) → (or/c eestate? #f)
> history : (listof string?)

Attempts to start the expeditor. On success, which requires that (current-input-port) and (current-output-port) are terminal ports and the terminal configuration is recognized, the result is a representation of the terminal state. The result is #f if the expeditor cannot be initialized.

The history argument provides the initial list of history entries, which is navigated by functions like ee-history-bwd. This history is updated as input is accepted during expeditor-read, and expeditor-close reports an updated history. The amount of preserved history is limited.

> procedure (expeditor-close ee) → (listof string?)
> ee : estate?

Closes the expeditor, relinquishing terminal configuration and resources, if any. The result is the expeditor’s history as initialized by expeditor-open and updated by expeditor-read calls.

> procedure (expeditor-read ee [#:prompt prompt-str]) → any/c
> ee : estate?
> prompt-str : string? = ">"

Reads input from the terminal. The ee argument holds terminal state as well as history that is updated during expeditor-read. The prompt-str is used as a prompt; a space is added between prompt-str and input, unless prompt-str is "".

Changed in version 1.1 of package expeditor-lib: Added the #:prompt argument.

> > procedure
> > (call-with-expeditor |  | proc |  |  |  |
> > | [ | #:prompt prompt-str]) |  | → |  | any
> proc : ((->* () (#:prompt string?) any/c) -> any)
> prompt-str : string? = ">"

Combines expeditor-open, a call to proc, and expeditor-close, where the reading procedure passed to proc can be called any number of times to read input. The prompt-str argument is used in the same way as for expeditor-read, the reading procedure can also receive an optional string to update the prompt-str.

Expeditor history is initialized from current-expeditor-history on open, and the value of current-expeditor-history is updated with the new history on close.

Changed in version 1.1 of package expeditor-lib: Added the #:prompt argument.

> procedure (expeditor-configure) → void?

Sets expeditor parameters based on current-interaction-info, the user’s preferences file, and (expeditor-init-file-path).

The current-expeditor-reader parameter is first set to use current-read-interaction.

then, expeditor-configure checks for information via current-interaction-info, currently checking for the following keys:

- 'color-lexer — Sets current-expeditor-lexer. If 'color-lexer is not provided and syntax-color/racket-lexer is available, then the Racket lexer is installed.

- 'drracket:submit-predicate — Sets current-expeditor-ready-checker.

- 'drracket:paren-matches — Sets current-expeditor-parentheses.

- 'drracket:grouping-position — Sets current-expeditor-grouper.

- 'drracket:indentation, 'drracket:range-indentation, and 'drracket:range-indentation/reverse-choices — Sets current-expeditor-indenter based on a combination of both values.

The 'expeditor-color-enabled preference (via get-preference) determines current-expeditor-color-enabled.

Finally, if the file named by (expeditor-init-file-path), it is dynamic-required.

> procedure (expeditor-init-file-path) → path?

Returns a path that is used by expeditor-configure.

If (find-system-path 'init-dir) produces a different result than (find-system-path 'home-dir), then the result is (build-path (find-system-path 'init-dir) "expeditor.rkt"). Otherwise, the result is (build-path (find-system-path 'home-dir) ".expeditor.rkt").

> parameter (current-expeditor-reader) → (input-port? . -> . any/c)
> (current-expeditor-reader proc) → void?
> proc : (input-port? . -> . any/c)

A parameter that determines the reader used to parse input when an entry is accepted. The default function uses read.

> parameter (current-expeditor-post-skipper) → (input-port? . -> . any/c)
> (current-expeditor-post-skipper proc) → void?
> proc : (input-port? . -> . any/c)

A parameter that determines a function used to consume extra whitespace after a reader consumes from an accepted entry. The default function consumes whitespace.

> parameter (current-expeditor-lexer) → procedure?
> (current-expeditor-lexer proc) → void?
> proc : procedure?

A parameter that determines the lexer used for syntax coloring and parenthesis matching. See the DrRacket manual for more information. The default function simply recognizes common parenthesis-like characters.

> parameter (current-expeditor-ready-checker) → procedure?
> (current-expeditor-ready-checker proc) → void?
> proc : procedure?

A parameter that determines how expeditor entry is treated as ready to accept or not. See the DrRacket manual for more information. The default function attempts to read all input, returning #f only if exn:fail:read:eof is raised.

> parameter (current-expeditor-parentheses)
> → (listof (list/c symbol? symbol?))
> (current-expeditor-parentheses pairs) → void?
> pairs : (listof (list/c symbol? symbol?))

A parameter that determines character sequences that are considered matching opener and closer pairs. See the DrRacket manual for more information. The default is '((|(| |)|) (|[| |]|) (|{| |}|)).

> parameter (current-expeditor-grouper) → procedure?
> (current-expeditor-grouper proc) → void?
> proc : procedure?

A parameter that determines how expression-based navigation operators work. See the DrRacket manual for more information.

> parameter (current-expeditor-indenter) → procedure?
> (current-expeditor-indenter proc) → void?
> proc : procedure?

A parameter that determines how automatic indentation works. It expects either three or four arguments: a representation of the editor, a position in the editor, a boolean indicating whether the indentation request is automatic due to starting a new line, and an optional boolean indicating whether to cycle through indentation choices in reverse order. The protocol for results is the same as an indentation function for DrRacket. See the DrRacket manual for more information.

Changed in version 1.2 of package expeditor-lib: Added support for an optional fourth argument.

> parameter (current-expeditor-color-enabled) → boolean?
> (current-expeditor-color-enabled on?) → void?
> on? : boolean?

A parameter that determines whether syntax and error coloring are enabled.

> parameter (current-expeditor-history) → (listof string?)
> (current-expeditor-history strs) → void?
> strs : (listof string?)

Expeditor history as consumed and produced by call-with-expeditor.

> parameter (current-expeditor-history-whitespace-trim-enabled) → boolean?
> (current-expeditor-history-whitespace-trim-enabled on?) → void?
> on? : any/c

A parameter that determines whether tailing whitespace is trimmed from input before recording it as history. The default is #t.

> procedure (expeditor-error-display s) → void?
> s : string?

Similar to display of s, but when color is enabled, the string is printed in the error color.
top contents ← prev up next →