5.5 Tool Support

8.18

5.5 Tool Support🔗ℹ

Librraies such as shrubbery/syntax-color and shrubbery/indentation provide tools for working with shrubbery-based programs. They generally follow DrRacket’s protocols, but they are also intended to support other tools where the protocols can be adapted.

5.5.1 Language Configuration🔗ℹ

(require (submod shrubbery reader))

The (submod shrubbery reader) module provides read, read-syntax, and "get-info" functions as normal for a reader submodule, but read and read-syntax accept an extra #:variant argument in the sense of shrubbery/variant. To better cooperate with new languages that are defined with syntax/module-reader, the (submod shrubbery reader) module also provides get-info-proc and make-get-info-proc.

procedure
(get-info-proc key
default
make-default
[ #:variant variant]) → any/c
  key : symbol?
  default : any/c
  make-default : (symbol? any/c . -> . any/c)
  variant : variant? = default-variant

Returns language-configuration results that are suitable for any shrubbery-based languages. The results are based on modules such as shrubbery/syntax-color, shrubbery/indentation, shrubbery/navigation, and shrubbery/keystroke.

procedure
(make-get-info-proc [#:variant variant]) → procedure?
variant : variant? = default-variant

Returns a procedure like get-info-proc, but with variant already supplied as the #:variant argument.

5.5.2 Syntax Coloring🔗ℹ

(require shrubbery/syntax-color)

package: shrubbery-lib

procedure
(shrubbery-lexer in
pos
status
[ #:variant variant])
→
(or/c string? eof-object?)
(or/c symbol?
      (and/c (hash/c symbol? any/c) immutable?))
(or/c symbol? #f)
(or/c number? #f)
(or/c number? #f)
exact-nonnegative-integer?
any/c
  in : input-port?
  pos : exact-nonnegative-integer?
  status : any/c
  variant : variant? = default-variant

A syntax-coloring lexer that follows the start-colorer protocol used by DrRacket, but with an additional optional #:variant argument.

procedure
(shrubbery-text-mode-lexer in
pos
status
[ #:variant variant])
→
(or/c string? eof-object?)
(or/c symbol?
      (and/c (hash/c symbol? any/c) immutable?))
(or/c symbol? #f)
(or/c number? #f)
(or/c number? #f)
exact-nonnegative-integer?
any/c
  in : input-port?
  pos : exact-nonnegative-integer?
  status : any/c
  variant : variant? = default-variant

Like shrubbery-lexer, but starting in “text” mode as if surrounded by an @ form and inside the form’s { and }.

procedure
(make-shrubbery-lexer [#:variant variant]) → procedure?
variant : variant? = default-variant
procedure
(make-shrubbery-text-mode-lexer [#:variant variant]) → procedure?
variant : variant? = default-variant

Returns a procedure like shrubbery-lexer or shrubbery-text-mode-lexer, but where variant is already supplied as the #:variant argument.

5.5.3 Indentation🔗ℹ

(require shrubbery/indentation)

package: shrubbery-lib

procedure
(shrubbery-indentation text
pos
[ #:multi? multi?
#:always? always?
#:reverse? reverse?
#:stop-pos stop-pos
#:variant variant])
→
(or/c #f
      exact-nonnegative-integer?
      (list/c exact-nonnegative-integer? string?)
      (listof (or/c exact-nonnegative-integer?
                    (list/c exact-nonnegative-integer? string?))))
  text : (is-a?/c color-textoid<%>)
  pos : exact-nonnegative-integer?
  multi? : any/c = #f
  always? : any/c = multi?
  reverse? : any/c = #f
  stop-pos : exact-nonnegative-integer? = 0
  variant : variant? = default-variant

Returns a suggested indentation for the line containing pos in text following a protocol used by DrRacket, but with several extra options described below. The result includes an integer and a string only when tab characters force a description of indentation in terms of tab and space characters.

If the current indentation matches a valid indentation but others are possible, the result when multi? is #f corresponds to the next valid indentation in a sequence of possibilities.

multi?: Returns all possible indentations, instead of just the first one.
always?: When #f, returns the line’s current indentation if that indentation is valid, instead of cycling to the next valid indentation. This argument is provided as #f when indenting for a newly created line, for example.
reverse?: When true, causes the a sequence of valid indentations to be used or returned in reverse order. See shrubbery-range-indentation/reverse-choices for more information about the default order.
stop-pos: Indicates a position in text where indentation should stop inspecting, instead of considering the effect of earlier characters.
variant: See shrubbery/variant.

procedure
(shrubbery-range-indentation text
start-pos
end-pos
[ #:reverse? reverse?
#:variant variant])
→
(or/c #f
      (listof (list/c exact-nonnegative-integer? string?)))
  text : (is-a?/c color-textoid<%>)
  start-pos : exact-nonnegative-integer?
  end-pos : exact-nonnegative-integer?
  reverse? : any/c = #f
  variant : variant? = default-variant

Similar to shrubbery-indentation, returns a suggested indentation for multiple lines following a character-range protocol used by DrRacket.

procedure
(shrubbery-range-indentation/reverse-choices
text
start-pos
end-pos
[ #:variant variant])
→
(or/c #f
      (listof (list/c exact-nonnegative-integer? string?)))
  text : (is-a?/c color-textoid<%>)
  start-pos : exact-nonnegative-integer?
  end-pos : exact-nonnegative-integer?
  variant : variant? = default-variant

Like shrubbery-range-indentation with #:reverse? #t.

By default, non-reversed indentation choices cycle left-to-right. If the 'shrubbery:tab-right-to-left preference (in the sense of get-preference) is set to a true value, then non-reversed indentation choices cycle right-to-left.

procedure
(make-shrubbery-indentation [#:variant variant]) → procedure?
  variant : variant? = default-variant
procedure
(make-shrubbery-range-indentation [#:variant variant])
→ procedure?
  variant : variant? = default-variant
procedure
(make-shrubbery-range-indentation/reverse-choices [#:variant variant])
→ procedure?
  variant : variant? = default-variant

Returns a procedure like shrubbery-indentation, shrubbery-range-indentation, or shrubbery-range-indentation/reverse-choices, but with variant already supplied as the #:variant argument.

5.5.4 Term and Group Navigation🔗ℹ

(require shrubbery/navigation)

package: shrubbery-lib

procedure
(shrubbery-grouping-position text
pos
limit-pos
direction
[ #:variant variant])
→ (or/c #f #t natural?)
  text : (is-a?/c color-textoid<%>)
  pos : exact-nonnegative-integer?
  limit-pos : exact-nonnegative-integer?
  direction : (or/c 'up 'down 'backward 'forward)
  variant : variant? = default-variant

Returns navigation guidance starting at pos in text following a protocol used by DrRacket.

procedure
(make-shrubbery-grouping-position [#:variant variant])
→ procedure?
variant : variant? = default-variant

Returns a procedure like shrubbery-grouping-position, but with variant already supplied as the #:variant argument.

5.5.5 Keystrokes🔗ℹ

(require shrubbery/keystroke)

package: shrubbery-lib

value
shrubbery-keystrokes :
(listof (list/c string?
                ((is-a?/c text%)
                 (is-a?/c event%)
                 . -> . any)))

Extra keystrokes suitable for shrubbery forms following a protocol used by DrRacket.

procedure
(make-shrubbery-keystrokes [#:variant variant]) → list?
variant : variant? = default-variant

Returns a list like shrubbery-keystrokes, but suitable for a form of shrubbery notation selected by variant.

1	Quick Overview
2	Shrubbery Specification
3	Parsed Representation
4	Shrubbery Language
5	Shrubbery APIs
6	Design Considerations
7	Editor Support

5.1	Parsing
5.2	Source Locations and Raw-Text Properties
5.3	Reconstructing Shrubbery Notation
5.4	Writing Shrubbery Notation
5.5	Tool Support
5.6	Shrubbery Variants

5.5.1	Language Configuration
5.5.2	Syntax Coloring
5.5.3	Indentation
5.5.4	Term and Group Navigation
5.5.5	Keystrokes