On this page:
1.1 Syntax Coloring
1.2 Indentation
1.3 Comments
1.4 Keystrokes
1.5 Filename Extensions
1.6 REPL Submit Predicate
1.7 Show Big “Definitions” and “Interactions” Labels
1.8 Opting Out of Standard Toolbar Buttons
1.9 Opting In to Language-Specific Toolbar Buttons
1.10 Adding New Toolbar Buttons
1.11 Definition Popup-Menu Navigation
1.12 Definitions Text Surrogate

1 Tool support for #lang-based Languages

A variety of tools can use extra information specified by a language. These tools include DrRacket, expeditor, and more.

The simplest and best way to extend tools to support a new language is to implement the language via  #lang (see Defining new #lang Languages for more details). Tools will then use read-language to find code and values that it uses to customize itself to the language.

If the call to read-language raises an error, DrRacket logs the error at the debug level to a logger with the name 'drracket-language (see Logging for more about how to follow specific loggers).

With the exception of the 'definitions-text-surrogate, if there is an error during a use of one of these extensions, DrRacket notices the error and removes all of the extensions for the language. It also shows the error at the bottom of the DrRacket frame (prefixed by #lang). Note that this applies only to errors that occur during the dynamic extent of a use of one of these extensions. If an extension were to, for example, create a new thread that (eventually) caused an error, DrRacket would not notice that error and would not remove the extensions.

When experimenting with changes to these extensions, use the Racket|Reload #lang Extensions menu item to cause DrRacket to remove the extensions and reload the implementations from the files on disk.

DrRacket calls the language’s read-language’s get-info procedure with the following key arguments. Other tools may use only a subset.

1.1 Syntax Coloring

When a language’s get-info procedure responds to 'color-lexer, it is expected to return a procedure suitable to pass as the get-token argument to start-colorer.

The recognized token styles (specified implicitly via start-colorer’s token-sym->style argument) are:

The precise colors for these identifiers are controlled by the preferences dialog in DrRacket, and by other customization mechanisms in other tools.

1.2 Indentation

When a language’s get-info procedure responds to 'drracket:indentation, it is expected to return a function with this contract:

(-> (is-a?/c color-textoid<%>)
    exact-nonnegative-integer?
    (or/c #f exact-nonnegative-integer?))

Although DrRacket might supply a full racket:text<%>, if your language can limit itself to the smaller number of methods in the color-textoid<%> interface then it will work with more tools.

The function is used to indent lines. It is called with the position containing the line to be indented. It is expected to return the number of spaces that should appear at the beginning of the line or #f. If #f is returned, the tool uses the standard s-expression indentation rules.

Added in version 1.3 of package drracket.

When a language’s get-info procedure responds to 'drracket:range-indentation, it is expected to return a function with this contract:

(-> (is-a?/c color-textoid<%>)
    exact-nonnegative-integer?
    exact-nonnegative-integer?
    (or/c #f (listof (list/c exact-nonnegative-integer? string?))))

Although DrRacket might supply a full racket:text<%>, if your language can limit itself to the smaller number of methods in the color-textoid<%> interface then it will work with more tools.

The function is used to indent a range that potentially spans multiple lines. It is called with the start and ending position of the range. The function is expected to return either #f or a list with an item for each line in the range. Returning #f falls back to iterating indentation over every line in the range (using 'drracket:indentation, if available). Returning a list indicates an update for each corresponding line, where a line update takes the form (list delete-amount insert-string): first delete delete-amount items from the start of the line, and then insert insert-string at the start of the line. If the returned list has fewer items then the range of lines to indent, the list is effectively padded with (list 0 "") no-op items. If the list has more items than the range of lines to indent, the extra items are ignored. Note that returning an empty list causes no lines to be updated, as opposed to returning #f to trigger a different indentation mechanism.

When both 'drracket:indentation and 'drracket:range-indentation are available, the function for 'drracket:range-indentation is called first—except in the case of an implicit indentation from creating a newline, in which case only 'drracket:indentation is used.

Added in version 1.10 of package drracket.

When a language’s get-info procedure responds to 'drracket:paren-matches, it is expected to return a list of opening and closing parentheses, matching this contract:
Each element of the outer list corresponds to a pair of parentheses, opening first and closing second.

These are used with the framework library’s color:text<%> object; they are supplied as the pairs argument to the start-colorer method. The default value is

'((|(| |)|)
  (|[| |]|)
  (|{| |}|))

They are also used to introduce keybindings that match the parentheses, via racket:map-pairs-keybinding-functions.

Added in version 1.12 of package drracket.

When a language’s get-info procedure responds to 'drracket:quote-matches, it is expected to return a list of characters that are self-matching, e.g. " in racket, matching this contract:

These characters are used to introduce keybindings via racket:map-pairs-keybinding-functions, where the open and close arguments are both the character.

The default value is (list #\" #\|).

Added in version 1.13 of package drracket.

1.3 Comments

When a language’s get-info procedure responds to 'drracket:comment-delimiters, it is expected to return a value with this contract:

(listof
 (or/c (list/c 'line
               (and/c string? (not/c #rx"[\r\n]"))
               (and/c string? (not/c #rx"[\r\n]")))
       (list/c 'region
               (and/c string? (not/c #rx"[\r\n]"))
               (and/c string? (not/c #rx"[\r\n]"))
               (and/c string? (not/c #rx"[\r\n]"))
               (and/c string? (not/c #rx"[\r\n]")))))

The value is a list of comment styles. Each comment style is expressed as one of:

When not specified by a lang, the default value is suitable for Racket s-expression langs:

'((line ";;" " ")
  (region "#|" "  " "|#" " "))

An intended use for these values is by (un)comment commands, which vary among tools. Some tools (un)comment entire lines, whereas others may handle portions of a line. Generally this is orthogonal to using a lang’s line vs. region style: A tool can wrap entire lines using region comments. A tool can insert line breaks to make it possible to use line comments on a portion of a line. The point of 'drracket:comment-delimiters is to enable a lang to tell a tool about its comment delimiters — not to say exactly how the (un)comment commands could or should work, exactly.

When the list has multiple styles: Some tools may present the styles for the user to pick one. Other tools may default to using the first style in the list (allowing the user to configure another preference by other means). Therefore when a language supports multiple comment styles, it should list the most popular or preferred style first.

Added in version 1.15 of package drracket.

1.4 Keystrokes

When a language’s get-info procedure responds to 'drracket:keystrokes, it is expected to return a list of keybindings and callbacks matching this contract:

(listof (list/c string?
                (-> (is-a?/c text%)
                    (is-a?/c event%)
                    any)))

Each element of the list is a different keybinding, where the string indicates the keystroke (see the documentation for map-function for the precise contents of the string and how it maps to particular keystrokes) and the procedure is called when the user types that keystroke in the definitions window.

The procedure’s first argument will be the definitions text, the second will be the event object supplied from the GUI system and the result of the procedure is ignored.

When a language’s get-info procedure responds to 'drracket:grouping-position, it is expected to return a function that determines where positions relevant to the nesting structure of the program appear. This function is used for a number of motion and selection operations in the editor, as well as determining where to flash to for closing parentheses.

Specifically the result must be a function matching this contract:

(-> (is-a?/c color-textoid<%>)
    natural?
    natural?
    (or/c 'up 'down 'backward 'forward)
    (or/c #f #t natural?))

Although DrRacket might supply a full text%, if your language can limit itself to the smaller number of methods in the color-textoid<%> interface then it will work with more tools.

Consider first the first and third argument. The first argument indicates a position in the editor to start from and the third argument is a direction to look. The result return the position for the corresponding direction, where the nesting structure of the program is viewed as a tree. That is, if the third argument is 'up, the function should return the position that goes up one layer in the tree from the given position to the parent. Similarly 'down should return the position going on layer deeper into that tree, going down to the first child. The 'backward and 'forward arguments correspond to position where we stay at the same level in the tree, moving between siblings. The result should be #f when there is no corresponding position to move to, e.g., when the current position has no children, no parents, or no siblings in the corresponding direction.

The second argument is a limit. Positions smaller than the limit should be ignored, so if the corresponding position appears to be before the limit, return #f.

Finally, return #t to get the default behavior, namely motion in Racket-style s-expressions.

Added in version 1.11 of package drracket.

1.5 Filename Extensions

When a language’s get-info procedure responds to 'drracket:default-filters, it is expected to return (listof (list/c string? string?)).

These results are added as a prefix to finder:default-filters, extending the default that DrRacket normally uses, namely:

`(["Racket Sources" "*.rkt;*.scrbl;*.rktl;*.rktd;*.ss;*.scm"]
  ["Any" "*.*"])

Added in version 1.2 of package drracket.

When a language’s get-info procedure responds to 'drracket:default-extension, it is expected to return (and/c string? (not/c #rx"[.]")); the result is used as the default extension when saving files by setting finder:default-extension.

Added in version 1.2 of package drracket.

1.6 REPL Submit Predicate

When using the language declared in the source, DrRacket queries that language via read-language to determine if an expression in the interactions window is ready to be submitted to the evaluator (when the user types return). The info procedure is passed 'drracket:submit-predicate and should return a function matching this contract:

(-> input-port?
    boolean?
    boolean?)

This function’s first argument is a port that contains the interactions window’s data, starting just after the prompt and continuing to the end of the editor. The second argument is a boolean indicating if the insertion point is followed only by whitespace. The results should be a boolean indicating if the expression should be evaluated.

For backwards compatibility reasons, DrRacket also queries the result of module->language-info for 'drracket:submit-predicate. It does this during the evaluation of the definitions (so the Racket|Reload #lang extensions menu item does not trigger a re-load). If the submit predicate is specified both ways, then the predicate supplied via read-language takes precedence.

Changed in version 1.5 of package drracket: Look for drracket:submit-predicate via read-language.

1.7 Show Big “Definitions” and “Interactions” Labels

If the read-language predicate returns #t for 'drracket:show-big-defs/ints-labels, then DrRacket shows the words “Definitions” and “Interactions” in a large font in the corresponding windows. This is intended as a help for students who are reading instructions about where to type their programs but might not have internalized this particular bit of DrRacket terminology.

1.8 Opting Out of Standard Toolbar Buttons

Some of the built-in buttons in the DrRacket button bar at the top of the window can be disabled on a per-language basis. DrRacket will invoke the get-info proc returned by read-language with 'drracket:opt-out-toolbar-buttons (and 'drscheme:opt-out-toolbar-buttons for backwards compatibility).

If the result is a list of symbols, the listed symbols are opted out. If the result is #f, all buttons are opted out. The default is the empty list, meaning that all opt-out buttons appear.

The Check Syntax button uses the symbol 'drracket:syncheck; the debugger uses the symbol 'debug-tool and the macro stepper uses 'macro-stepper.

Plugins may add more opt-out buttons via drracket:module-language-tools:add-opt-out-toolbar-button.

1.9 Opting In to Language-Specific Toolbar Buttons

Like drracket:opt-out-toolbar-buttons, but for languages to opt in to buttons that are not enabled by default.

Plugins may add more opt-out buttons via drracket:module-language-tools:add-opt-in-toolbar-button.

Added in version 1.6 of package drracket.

1.10 Adding New Toolbar Buttons

DrRacket queries the result of read-language to determine if there are any new toolbar buttons to be used when editing files in this language.

Specifically, DrRacket will pass 'drracket:toolbar-buttons to the function and expect back a value matching this contract:

(or/c (listof (list/c string?
                      (is-a?/c bitmap%)
                      (-> (is-a?/c drracket:unit:frame<%>) any)
                      (or/c real? #f)))
      #f)

which is then used to create new toolbar buttons, one for each element in the result list. The string is the label on the button; the bitmap is the icon (it should be 16x16 pixels); the function is called when the button is clicked; and the number is passed as the #:number argument to register-toolbar-button.

If the result is #f, then no toolbar buttons are created.

To implement functionality similar to the Run button, call the execute-callback method. You may also want to use the drracket:rep:after-expression parameter.

If 'drracket:toolbar-buttons is not recognized, DrRacket will also pass 'drscheme:toolbar-buttons; this is for backwards compatibility and new code should not use it. Similarly, if the fourth element from the list (the argument to #:number) is not present, then it is treated as #f.

1.11 Definition Popup-Menu Navigation

A popup menu in the DrRacket button bar jumps to definitions based on a heuristic search of the program text. DrRacket will invoke the get-info proc returned by read-language with 'drracket:define-popup to obtain a configuration for the menu.

The value must satisfy the contract

(non-empty-listof (or/c (list/c string? string? string?)
                        (list/c string? string? string?
                                (or/c #f
                                      (-> (is-a/c text%)
                                          string?
                                          exact-integer?
                                          (->* ((is-a/c text%)
                                                string?
                                                exact-integer?)
                                               (#:case-sensitive? any/c
                                                #:delimited? any/c)
                                               (or/c exact-integer? #f))
                                          (or/c exact-integer? #f)))
                                (or/c #f
                                      (-> (is-a/c text%)
                                          exact-integer?
                                          (-> (is-a/c text%)
                                              exact-integer?
                                              string?)
                                          string?)))))

where the first string in each nested list is literal text to search for (outside of comments and literal strings), the second string is a label to describe the category of matches, and the third string is a short form of the label. The labels from the first nested list are used for the definition-popup button itself, while all labels are used for the user to select which categories are enabled.

When a nested list contains fourth and fifth elements, they can supply replacements (when not #f) for the default functions that find a prefix and extract the subsequent name:

Plugins can provide a default popup-menu configuration via drracket:language:register-capability using 'drscheme:define-popup.

Added in version 1.14 of package drracket.

1.12 Definitions Text Surrogate

Using a #lang-specific definitions text surrogate is a very powerful way to flexibly control DrRacket’s behavior when a new language is installed. It is also easy to cause DrRacket to completely misbehave with this form of extension. It is here only when one of the other forms of extension listed above are not sufficient for the kind of extension your language requires. And even in that case, it is preferable to add something to this list that is more easily controlled in the case of errors, using the definitions text surrogate only until that more easily controlled extension has been added to DrRacket.

DrRacket calls read-language’s get-info procedure with 'definitions-text-surrogate and expects it to return a value matching the contract (or/c #f module-path?), which is then passed to dynamic-require together with 'surrogate%. The result is expected to be a class implementing the interface racket:text-mode<%> (presumably derived from racket:text-mode%. That mode is installed into the definitions text, where it can change its behavior by changing how is responds to any of the methods in the mode.

One consequence of this power is that errors that happen during the dynamic extent of calls into the mode are not trapped (much as errors that occur on newly created threads are not trapped, as described in the introduction to this section).