▼Plugins: Extending Dr Scheme
  top← prev  up  next → 

1 Implementing DrScheme Tools

Tools are designed for major extensions in DrScheme’s functionality. To extend the appearance or the functionality the DrScheme window (say, to annotate programs in certain ways, to add buttons to the DrScheme frame or to add additional languages to DrScheme) use a tool. The Macro Stepper, the Syntax Checker, the Stepper, and the teaching languages are all implemented as tools.

When DrScheme starts up, it looks for tools by reading fields in the info.ss file of each collection and the newest version of each PLaneT package installed on the system. (Technically, DrScheme looks in a cache of the info.ss files contents created by setup-plt. Be sure to re-run setup-plt if you change the contents of the info.ss files). DrScheme checks for these fields:

  • tools: (listof (listof string [subcollection-name]))

  • tool-names: (listof (union #f string))

  • tool-icons:
      (listof (union #f
                     string[relative-pathname]
                     (cons string[filename]
                           (listof string[collection-name]))))

  • tool-urls: (listof (union #f string [url]))

The tools field names a list of tools in this collection. Each tool is specified as a collection path, relative to the collection where the info.ss file resides. As an example, if there is only one tool named tool.ss, this suffices:
  (define tools (list (list "tool.ss")))
If the tool-icons or tool-names fields are present, they must be the same length as tools. The tool-icons specifies the path to an icon for each tool and the name of each tool. If it is #f, no tool is shown. If it is a relative pathname, it must refer to a bitmap and if it is a list of strings, it is treated the same as the arguments to lib, inside require.

This bitmap and the name show up in the about box, Help Desk’s bug report form, and the splash screen as the tool is loaded at DrScheme’s startup.

Each of tools files must contain a module that provides tool@, which must be bound to a unit. The unit must import the drscheme:tool^ signature, which is provided by the tool.ss library in the drscheme collection. The drscheme:tool^ signature contains all of the names listed in this manual. The unit must export the drscheme:tool-exports^ signature.

The drscheme:tool-exports^ signature contains two names: phase1 and phase2. These names must be bound to thunks. After all of the tools are loaded, all of the phase1 functions are called and then all of the phase2 functions are called. Certain primitives can only be called during the dynamic extent of those calls.

This mechanism is designed to support DrScheme’s drscheme:language:language<%> extension capabilities. That is, this mechanism enables two tools to cooperate via new capabilities of languages. The first phase is used for adding functionality that each language must support and the second is used for creating instances of languages. As an example, a tool may require certain specialized language-specific information. It uses phase1 to extend the drscheme:language:language<%> interface and supply a default implementation of the interface extension. Then, other languages that are aware of the extension can supply non-default implementations of the additional functionality.

Phase 1 functions:

Phase 2 functions:

If the tool raises an error as it is loaded, invoked, or as the phase1 or phase2 thunks are called, DrScheme catches the error and displays a message box. Then, DrScheme continues to start up, without the tool.

For example, if the info.ss file in a collection contains:
  #lang setup/infotab
  (define name "Tool Name")
  (define tools (list (list "tool.ss")))
then the same collection would be expected to contain a tool.ss file. It might contain something like this:
  #lang scheme/gui
  (require drscheme/tool)
  
  (provide tool@)
  
  (define tool@
    (unit
      (import drscheme:tool^)
      (export drscheme:tool-exports^)
      (define (phase1) (message-box "tool example" "phase1"))
      (define (phase2) (message-box "tool example" "phase2"))
      (message-box "tool example" "unit invoked")))
This tool just opens a few windows to indicate that it has been loaded and that the phase1 and phase2 functions have been called.

  top← prev  up  next →