3 Keybinding Language Reference

3 Keybinding Language Reference🔗ℹ

3.1 Operations🔗ℹ

This section describes every supported operation by the kb-base language. Every operation returns an kb-expr? that represents an expression interpreted by the kb-base interpreter. Similarly there is an buffer-safe-kb-expr? that represents an expression that doesn’t change the current editor buffer.

procedure
(insert str) → kb-expr?
str : (or/c string? symbol? kb-expr?)

Inserts str into the buffer at the current position.

procedure
(insert-return) → kb-expr?

Inserts a newline at the current position.

procedure
(delete start-expr [end-expr]) → kb-expr?
start-expr : (or/c exact-nonnegative-integer? symbol? kb-expr?)
end-expr : (or/c #f exact-nonnegative-integer? symbol? kb-expr?)
= #f

The first form deletes the text starting at start-expr and ending at end-expr. If end-expr is #f, deletes start-expr characters starting at the current position.

procedure
(seq expr1 ...) → kb-expr?
expr1 : (or/c string? char? number? boolean? symbol? kb-expr?)

Sequences all the expressions passed to it and returns the value of the final one (similar to Racket’s begin).

procedure
(set-position pos-expr) → kb-expr?
pos-expr : (or/c exact-nonnegative-integer? symbol? kb-expr?)

Sets the current position in the editor to the result of pos-expr.

procedure
(get-position) → kb-expr?

Returns end position of the currently selected text or the current position if none is selected.

procedure
(last-position) → kb-expr?

Returns the last position in the editor.

procedure
(move-position code kind) → kb-expr?
   code :
(or/c 'up
      'down
      'left
      'right
      'home
      'end)
   kind :
(or/c 'simple
      'word
      'line
      'page
      'sexp)

Uses the same rules as text%’s move-position to move based on the passed code and kind.

Additionally, takes a kind 'sexp, which works with 'right or 'left.

procedure
(forward-sexp) → kb-expr?

Jumps over the next sexp following the current position.

procedure
(backward-sexp) → kb-expr?

Jumps backwards over the first sexp preceding the current position.

procedure
(down-sexp) → kb-expr?

Moves into the next sexp following the current position.

procedure
(up-sexp) → kb-expr?

Jumps out of the current sexp (the one the current position is in) leaving the current position at the start of that sexp.

procedure
(get-forward-sexp) → kb-expr?

Returns the starting position the next sexp following the current position, or #f if one doesn’t exist.

procedure
(forward-sexp-exists?) → kb-expr?

Returns #t if there is an sexp following the current position, #f otherwise.

procedure
(get-character [pos]) → kb-expr?
pos : (or/c #f exact-nonnegative-integer? symbol? kb-expr?)
= #f

The first form gets the character that immediately follows the current cursor position. If pos is not #f, returns the character after the position pos in the current editor.

procedure
(get-forward-word [pos]) → kb-expr?
pos : (or/c #f exact-nonnegative-integer? symbol? kb-expr?)
= #f

The first form gets the word that immediately follows the current cursor position. If pos is not #f, returns the word after the position pos in the current editor.

procedure
(get-text start-expr end-expr) → kb-expr?
start-expr : (or/c exact-nonnegative-integer? symbol? kb-expr?)
end-expr : (or/c exact-nonnegative-integer? symbol? kb-expr?)

Gets the text between the result of start-expr and end-expr and returns it as a string.

procedure
(do-times iter-count body) → kb-expr?
iter-count : (or/c number? kb-expr?)
body : kb-expr?

Evaluates iter-count which should return a number? and executes body that many times.

procedure
(count-iters condition-expr
step-size-expr
step-type) → kb-expr?
  condition-expr : (or/c boolean? symbol? buffer-safe-kb-expr?)
  step-size-expr : (or/c number? symbol? kb-expr?)
   step-type :
(or/c 'simple
      'word
      'line
      'page
      'sexp)

Returns the number of iterations where each iteration evaluates condition-expr and then does moves in the buffer according to step-size-expr and step-type. condition-expr is special in that it is not allowed to be an expression that modifies the buffer (i.e. non-modify-buffer-kb-expr?). The current cursor position is reset after the number of iterations has been counted.

procedure
(seek-while condition-expr
step-size-expr
step-type) → kb-expr?
  condition-expr : (or/c boolean? symbol? buffer-safe-kb-expr?)
  step-size-expr : (or/c number? symbol? kb-expr?)
   step-type :
(or/c 'simple
      'word
      'line
      'page
      'sexp)

Uses step-size-expr and step-type to seek through the buffer while condition-expr holds true.

syntax
(kb-let (let-clause ...+) body-expr)

let-clause = [id val-expr]

For each let-clause, binds id to the result of val-expr in body-expr.

procedure
(kb-set! id new-val-expr) → kb-expr?
  id : symbol?
   new-val-expr :
(or/c string?
      number?
      char?
      boolean?
      symbol?
      kb-expr?)

First checks to make sure id is bound, then overwrites its current value to the result of new-val-expr.

procedure
(kb-if condition-expr thn-expr else-expr) → kb-expr?
  condition-expr : (or/c boolean? symbol? kb-expr?)
  thn-expr : (or/c string? number? char? boolean? symbol? kb-expr?)
  else-expr : (or/c string? number? char? boolean? symbol? kb-expr?)

Evaluates condition-expr and evaluates thn-expr if the result is anything other than #f, if the result is #f it evaluates else-expr instead.

procedure
(kb-not expr) → kb-expr?
expr : (or/c boolean? symbol? kb-expr?)

Evaluates expr, which should produce a boolean?, and negates the result.

procedure
(kb-equal? expr1 expr2) → kb-expr?
expr1 : (or/c string? number? char? boolean? symbol? kb-expr?)
expr2 : (or/c string? number? char? boolean? symbol? kb-expr?)

Evaluates expr1 and expr2, and then compares their results using equal?.

procedure
(kb-or expr1 expr2) → kb-expr?
expr1 : (or/c boolean? symbol? kb-expr?)
expr2 : (or/c boolean? symbol? kb-expr?)

or’s the result of expr1 with expr2.

procedure
(kb-and expr1 expr2) → kb-expr?
expr1 : (or/c boolean? symbol? kb-expr?)
expr2 : (or/c boolean? symbol? kb-expr?)

and’s the result of expr1 with expr2.

procedure
(kb-gte expr1 expr2) → kb-expr?
expr1 : (or/c number? symbol? kb-expr?)
expr2 : (or/c number? symbol? kb-expr?)

Returns #t if the result of expr1 is >= the result of expr2.

procedure
(kb-lte expr1 expr2) → kb-expr?
expr1 : (or/c number? symbol? kb-expr?)
expr2 : (or/c number? symbol? kb-expr?)

Returns #t if the result of expr1 is <= the result of expr2.

procedure
(kb-gt expr1 expr2) → kb-expr?
expr1 : (or/c number? symbol? kb-expr?)
expr2 : (or/c number? symbol? kb-expr?)

Returns #t if the result of expr1 is > the result of expr2.

procedure
(kb-lt expr1 expr2) → kb-expr?
expr1 : (or/c number? symbol? kb-expr?)
expr2 : (or/c number? symbol? kb-expr?)

Returns #t if the result of expr1 is < the result of expr2.

procedure
(add num-expr1 num-expr2) → kb-expr?
num-expr1 : (or/c number? symbol? kb-expr?)
num-expr2 : (or/c number? symbol? kb-expr?)

Adds the result of num-expr1 and num-expr2.

procedure
(sub num-expr1 num-expr2) → kb-expr?
num-expr1 : (or/c number? symbol? kb-expr?)
num-expr2 : (or/c number? symbol? kb-expr?)

Subtracts the result of num-expr2 from the result of num-expr1.

3.2 Helpers🔗ℹ

This section documents helpers provided by the kb-base language.

The kb-base package also provides a few utilities to make testing easier. Since programs written in this language run in the context of an editor window (specifically a racket:text<%>), these test utilities handle setting that editor up and getting results back from running programs.

procedure
(make-kb stroke
kb-program
name
active-range
stx) → vector?
  stroke : string?
  kb-program : (or/c string? number? char? boolean? symbol? kb-expr?)
  name : string?
   active-range :
(or/c 'local 'global (cons/c exact-nonnegative-integer?
                             exact-nonnegative-integer?))
  stx : syntax?

A nicer way to construct ’keybinding-info properties. Generates a vector using the given information that corresponds to the content of an ’keybinding-info property. The last item in the vector is a srcloc built from the passed stx.

3.3 Testing Utilities🔗ℹ

(require kb-base/test-utils)
	package: drracket-custom-keybindings

procedure
(get-kb-program-result editor kb-program)
→
any/c exact-nonnegative-integer? string?
editor : (is-a?/c racket:text<%>)
kb-program : (or/c string? number? char? boolean? symbol? kb-expr?)

Passes the given editor and kb-program to the kb-base interpreter and returns three results: the value of the operation in kb-program, the current position after running kb-program, and the current text in editor after running kb-program.

procedure
(test-kb-program kb-program
[ test-proc]
#:setup-proc setup-proc) → any/c
  kb-program : (or/c string? number? char? boolean? symbol? kb-expr?)
   test-proc :
(-> any/c
    exact-nonnegative-integer?
    string?
    any/c)
=
(λ (val pos text)
  (values val pos text))
   setup-proc :
(-> (is-a?/c racket:text<%>)
    any/c)

Creates an empty racket:text% object and uses that as the editor for a call to get-kb-program-result with the provided kb-program. If setup-proc is provided, runs setup-proc to set up some initial editor state before calling get-kb-program-result. After get-kb-program-result has returned, passes the resulting three values to test-proc, which by default wraps them in values and returns them. test-proc is useful in combination with rackunit to test properties about the editor after kb-program has run.

1	Getting Started with Keybindings
2	Some Example Keybindings
3	Keybinding Language Reference