method (send a-color:text start-colorer   token-sym->style             get-token             pairs)   →   void?

token-sym->style : (-> symbol? string?)

get-token   :   (or/c (-> input-port?           (values any/c                   symbol?                   (or/c symbol? #f)                   (or/c exact-positive-integer? #f)                   (or/c exact-positive-integer? #f)))       (-> input-port?           exact-nonnegative-integer?           (not/c dont-stop?)           (values any/c                   symbol?                   (or/c symbol? #f)                   (or/c exact-positive-integer? #f)                   (or/c exact-positive-integer? #f)                   exact-nonnegative-integer?                   any/c)))

pairs : (listof (list/c symbol? symbol?))

Starts tokenizing the buffer for coloring and parenthesis matching.

The token-sym->style argument will be passed the first return symbol from get-token, and it should return the style-name that the token should be colored.

The get-token argument’s contract above is just the basic checks it should satisfy; it is also expected to satisfy the lexer/c contract, which attempts to also check the invariants described here.

The arguments to get-token are an input port and optionally an offset and mode value. When it accepts just an input port, get-token should return the next token as 5 values:

• This value is intended to represent the textual component of the token. If the second value returned by get-token is 'symbol and this value is a string then the value is used to differentiate between symbols and keywords for the purpose of coloring and formatting, configurable from DrRacket’s preference’s editing menu.

• A symbol describing the type of the token. This symbol is transformed into a style-name via the token-sym->style argument. The symbols 'white-space and 'comment have special meaning and should always be returned for white space and comment tokens respectively. The symbol 'no-color can be used to indicate that although the token is not white space, it should not be colored. The symbol 'eof must be used to indicate when all the tokens have been consumed.

• A symbol indicating how the token should be treated by the paren matcher or #f. This symbol should be in the pairs argument.

• The starting position of the token (or #f if eof); this number is relative to the third result of port-next-location when applied to the input port that gets passed to get-token.

• The ending position of the token (or #f if eof); this is also relative to the port’s location, just like the previous value.

When get-token accepts an offset and mode value in addition to an input port, it must also return two extra results. The offset given to get-token can be added to the position of the input port to obtain absolute coordinates within a text stream. The extra two results are

• a backup distance; The backup distance returned by get-token indicates the maximum number of characters to back up (counting from the start of the token) and for re-parsing after a change to the editor within the token’s region.

• a new mode; The mode argument allows get-token to communicate information from earlier parsing to later. When get-token is called for the beginning on a stream, the mode argument is #f; thereafter, the mode returned for the previous token is provided to get-token for the next token.

  If the mode result is a dont-stop struct, then the value inside the struct is considered the new mode, and the colorer is guaranteed not to be interrupted until at least the next call to this tokenizing function that does not return a dont-stop struct (unless, of course, it returns an eof token, in which case the new mode result is ignored). This is useful, for example, when a lexer has to read ahead in the buffer to decide on the tokens at this point; then that read-ahead will be inconsistent if an edit happens; returning a dont-stop struct ensures that no changes to the buffer happen.

  The mode should not be a mutable value; if part of the stream is re-tokenized, the mode saved from the immediately preceding token is given again to the get-token function.

The get-token function must obey the following invariants:

• Every position in the buffer must be accounted for in exactly one token, and every token must have a non-zero width. Accordingly, get-token must never refuse to accept certain token streams (e.g., by raising an exception). The idea is that, while a normal parser for the language could signal errors by helpfully raising exceptions, a colorer should instead return a token with the type 'error and possibly continue to color the remainder of the buffer. For example, the racket-lexer identifiers strings that have malformed escape characters inside strings by returning 'error, but then continuing to color the rest of text as normal.

• The token returned by get-token must rely only on the contents of the input port argument plus the mode argument. This constraint means that the tokenization of some part of the input cannot depend on earlier parts of the input except through the mode (and implicitly through the starting positions for tokens).

• A change to the stream must not change the tokenization of the stream prior to the token immediately preceding the change plus the backup distance. In the following example, this invariant does not hold for a zero backup distance: If the buffer contains

  " 1 2 3

  and the tokenizer treats the unmatched " as its own token (a string error token), and separately tokenizes the 1 2 and 3, an edit to make the buffer look like

  " 1 2 3"

  would result in a single string token modifying previous tokens. To handle these situations, get-token can treat the first line as a single token, or it can precisely track backup distances.

The pairs argument is a list of different kinds of matching parens. The second value returned by get-token is compared to this list to see how the paren matcher should treat the token. An example: Suppose pairs is '((|(| |)|) (|[| |]|) (begin end)). This means that there are three kinds of parens. Any token which has 'begin as its second return value will act as an open for matching tokens with 'end. Similarly any token with '|]| will act as a closing match for tokens with '|[|. When trying to correct a mismatched closing parenthesis, each closing symbol in pairs will be converted to a string and tried as a closing parenthesis.

The get-token function is usually be implemented with a lexer using the parser-tools/lex library, but can be implemented directly. For example, here is a lexer that colors alternating characters as if they were symbols and strings:

(λ (port offset mode)

(define-values (line col pos) (port-next-location port))

(define c (read-char port))

(cond

[(eof-object? c)

(values c 'eof #f #f #f 0 mode)]

[else

(values (string c)

(if mode 'symbol 'string)

#f

(+ pos)

(+ pos 1)

0

(not mode))]))

method (send a-color:text stop-colorer [clear-colors?]) → void?

clear-colors? : boolean? = #t

Stops coloring and paren matching the buffer.

If clear-colors? is true all the text in the buffer will have its style set to Standard.

method (send a-color:text force-stop-colorer stop?) → void?

stop? : boolean?

Causes the entire tokenizing/coloring system to become inactive. Intended for debugging purposes only.

stop? determines whether the system is being forced to stop or allowed to wake back up.

method (send a-color:text is-stopped?) → boolean?

Indicates if the colorer for this editor has been stopped, or not.

method (send a-color:text is-frozen?) → boolean?

Indicates if this editor’s colorer is frozen. See also freeze-colorer and thaw-colorer.

method (send a-color:text freeze-colorer) → void?

Keep the text tokenized and paren matched, but stop altering the colors.

freeze-colorer will not return until the coloring/tokenization of the entire text is brought up-to-date. It must not be called on a locked text.

method (send a-color:text thaw-colorer  [ recolor?             retokenize?])   →   void?

recolor? : boolean? = #t

retokenize? : boolean? = #f

Start coloring a frozen buffer again.

If recolor? is #t, the text is re-colored. If it is #f the text is not recolored. When recolor? is #t, retokenize? controls how the text is recolored. #f causes the text to be entirely re-colored before thaw-colorer returns using the existing tokenization. #t causes the entire text to be retokenized and recolored from scratch. This will happen in the background after the call to thaw-colorer returns.

method (send a-color:text reset-region start end) → void?

start : exact-nonnegative-integer?

end : (or/c exact-nonnegative-integer? 'end)

Set the region of the text that is tokenized.

method (send a-color:text reset-regions regions) → void?

regions   :   (listof (list/c exact-nonnegative-integer?                 (or/c exact-nonnegative-integer? 'end)))

Sets the currently active regions to be regions. The numbers in the regions argument must be increasing and only the last number can be replaced with 'end.

Note that editing outside of the active regions violates (unchecked) invariants of this class and edits that move text across region boundaries may also violate (unchecked) invariants. DrRacket uses this method in the interactions window in a way that disallows edits anywhere except the last region and the last region has 'end as its second argument.

method (send a-color:text get-spell-check-strings) → boolean?

Returns #t if the colorer will attempt to spell-check string constants.

method (send a-color:text set-spell-check-strings b?) → void?

b? : boolean?

If called with #t, tell the colorer to spell-check string constants. Otherwise, disable spell-checking of string constants.

method (send a-color:text get-spell-check-text) → boolean?

Returns #t if the colorer will attempt to spell-check text (e.g., the words inside { and } in Scribble documents).

method (send a-color:text set-spell-check-text b?) → void?

b? : boolean?

If called with #t, tell the colorer to spell-check text constants. Otherwise, disable spell-checking of text.

method (send a-color:text set-spell-current-dict dict) → void?

dict : (or/c string? #f)

Sets the current dictionary used with aspell to dict. If dict is #f, then the default dictionary is used.

method (send a-color:text get-spell-current-dict) → (or/c string? #f)

Get the current dictionary used with aspell. If the result is #f, then the default dictionary is used.

method (send a-color:text get-spell-suggestions pos)

→   (or/c #f (list/c exact-nonnegative-integer?                  exact-nonnegative-integer?                  (listof string?)))

pos : exact-nonnegative-integer?

Returns suggested spelling corrections (and the span of the entire word) to replace the word at pos. If the word is spelled correctly or spell checking is disabled, returns #f.

method (send a-color:text get-regions)

→ (listof (list/c exact-nonnegative-integer? (or/c exact-nonnegative-integer? 'end)))

This returns the list of regions that are currently being colored in the editor.

method (send a-color:text get-matching-paren-string   paren-str      [ get-side])

→ (or/c string? #f)

paren-str : string?

get-side : (or/c 'open 'close 'either) = 'either

Returns a string of a paren matching the other side of paren-str as specified by the pairs argument of start-colorer, if one exists on the side indicated by get-side. If there is no match on the corresponding side, including if paren-str contains any characters other than a single paren token (even whitespace), returns #f instead.

method (send a-color:text skip-whitespace   position       direction       comments?)

→ exact-nonnegative-integer?

position : exact-nonnegative-integer?

direction : (or/c 'forward 'backward)

comments? : boolean?

Returns the next non-whitespace character.

Starts from position and skips whitespace in the direction indicated by direction. If comments? is true, comments are skipped as well as whitespace. skip-whitespace determines whitespaces and comments by comparing the token type to 'white-space and 'comment.

Must only be called while the tokenizer is started.

method (send a-color:text backward-match   position       cutoff)

→ (or/c exact-nonnegative-integer? #f)

position : exact-nonnegative-integer?

cutoff : exact-nonnegative-integer?

Skip all consecutive whitespaces and comments (using skip-whitespace) immediately preceding the position. If the token at this position is a close, return the position of the matching open, or #f if there is none. If the token was an open, return #f. For any other token, return the start of that token.

Must only be called while the tokenizer is started.

method (send a-color:text backward-containing-sexp   position       cutoff)

→ (or/c exact-nonnegative-integer? #f)

position : exact-nonnegative-integer?

cutoff : exact-nonnegative-integer?

Return the starting position of the interior of the (non-atomic) s-expression containing position, or #f is there is none.

Must only be called while the tokenizer is started.

method (send a-color:text forward-match   position       cutoff)

→ (or/c exact-nonnegative-integer? #f)

position : exact-nonnegative-integer?

cutoff : exact-nonnegative-integer?

Skip all consecutive whitespaces and comments (using skip-whitespace) immediately following position. If the token at this position is an open, return the position of the matching close, or #f if there is none. For any other token, return the end of that token.

Must only be called while the tokenizer is started.

method (send a-color:text insert-close-paren   position             char             flash?             fixup?            [ smart-skip?])   →   void?

position : exact-nonnegative-integer?

char : char?

flash? : boolean?

fixup? : boolean?

smart-skip? : (or/c #f 'adjacent 'forward) = #f

Inserts a close parentheses, or, under scenarios described further below, skips past a subsequent one. The position is the place to put the parenthesis, or from which to start searching for a subsequent one, and char is the parenthesis to be added (e.g., that the user typed). If fixup? is true, the right kind of closing parenthesis will be chosen from the set previously passed to start-colorer—but only if an inserted char would be colored as a parenthesis (i.e., with the 'parenthesis classification). Otherwise, char will be inserted (or skipped past), even if it is not the right kind. If flash? is true, the matching open parenthesis will be flashed when the insertion or skip is done.

The "smart skipping" behavior of this function is determined by smart-skip?. If smart-skip? is false, no skip will take place. A parenthesis will simply be inserted as described in the paragraph above. When smart-skip? is 'adjacent, if the next token after position, ignoring whitespace and comments (see skip-whitespace), is a properly matched closing parenthesis (which may not necessarily match char if fixup? is true) then simply move the cursor to the position immediately after that already present closing parenthesis. When smart-skip? is 'forward, this function attempts to determine the closest pair of properly balanced parentheses around position. If that exists, then the cursor position skips to the position immediately after the closing parenthesis of that outer pair. If a properly balanced outer pair is not present, then the cursor attempts to skip immediately after the next closing parenthesis that occurs after position, ignoring whitespace, comments, and all other tokens. In both non-false cases of smart-skip?, if there is no subsequent parenthesis, then a parenthesis is simply inserted, as previously described.

method (send a-color:text classify-position position)

→ (or/c symbol? #f)

position : exact-nonnegative-integer?

Return a symbol for the lexer-determined token type for the token that contains the item after position.

Must only be called while the tokenizer is started.

method (send a-color:text get-token-range position)

→   (or/c #f exact-nonnegative-integer?) (or/c #f exact-nonnegative-integer?)

position : exact-nonnegative-integer?

Returns the range of the token surrounding position, if there is a token there.

This method must be called only when the tokenizer is started.

method (send a-color:text on-lexer-valid valid?) → any

valid? : boolean?

Augments <method not found>.

This method is an observer for when the lexer is working. It is called when the lexer’s state changes from valid to invalid (and back). The valid? argument indicates if the lexer has finished running over the editor (or not).

The default method just returns (void?).

method (send a-color:text is-lexer-valid?) → boolean?

Indicates if the lexer is currently valid for this editor.

method (send a-color:text lock) → void?

Overrides lock in editor<%>.

method (send a-color:text on-focus) → void?

Overrides on-focus in editor<%>.

method (send a-color:text after-edit-sequence) → void?

Augments after-edit-sequence in editor<%>.

method (send a-color:text after-set-position) → void?

Augments after-set-position in text%.

method (send a-color:text after-change-style) → void?

Augments after-change-style in text%.

method (send a-color:text on-set-size-constraint) → void?

Augments on-set-size-constraint in text%.

method (send a-color:text after-insert) → void?

Augments after-insert in text%.

method (send a-color:text after-delete) → void?

Augments after-delete in text%.

method (send a-color:text-mode set-get-token get-token) → void?

get-token : procedure?

Sets the get-token function used to color the contents of the editor.

See start-colorer’s get-token argument for the contract on this method’s get-token argument.

constructor (new color:text-mode-mixin        [ [get-token get-token]         [token-sym->style token-sym->style]         [matches matches]])

→ (is-a?/c color:text-mode-mixin)

get-token : lexer = default-lexer

token-sym->style   :   (symbol? . -> . string?)       =   (λ (x) "Standard")

matches : (listof (list/c symbol? symbol?)) = null

The arguments are passed to start-colorer.

method (send a-color:text-mode on-disable-surrogate) → void?

Overrides on-disable-surrogate in mode:surrogate-text<%>.

method (send a-color:text-mode on-enable-surrogate) → void?

Overrides on-enable-surrogate in mode:surrogate-text<%>.

procedure (color:get-parenthesis-colors-table)

→ (listof (list/c symbol? string? (vectorof (is-a?/c color%)) (or/c 'low 'high)))

value color:misspelled-text-color-style-name : string?