Laurent Orseau <laurent dot orseauREMOVEME at gmail dot com>
The Script Plugin’s purpose is to make it easy to extend DrRacket with small Racket scripts that can be used in the definition (or interaction) window, or interact with the user.
Creating a new script is as easy as a click on a menu item. Each script is automatically added as an item to the Scripts menu, without needing to restart DrRacket. A keyboard shortcut can be assigned to a script (via the menu item). By default, a script takes as input the currently selected text, and outputs the replacement text. There is also direct access to some elements of DrRacket for advanced (though simplified since there is no need to create a dedicated plugin) scripting, like DrRacket’s frame and the definition or interaction editor.
To install, simply evaluate:
Wait for the installation process to finish, and then restart DrRacket. You should now see a new Scripts menu.
Click on the Scripts/New Script menu item, and enter Reverse for the script name. This creates and opens the files reverse.rkt and reverse.rktd in the script directory. Also, a new item automatically appears in the Scripts menu.
Then go to a new tab, type some text, select it, and click on Scripts/Reverse.
There are several other examples in the examples directory.
To use an example, just copy both the .rkt and .rktd files of the same name from the example directory to the user’s script directory. It should then automatically appear in the Scripts menu.
(require racket planet/resolver) (build-path (path-only (resolve-planet-path '(planet orseau/script-plugin/tool))) "examples")
The default location of the user’s scripts is in a sub-folder of (find-system-path 'home-path). The directory of the user scripts can be changed through DrRacket’s preferences (in Edit/Preferences/Scripts). Important: The scripts directory must have write-access for the user (which should be the case for the default settings).
(I will try to simplify this process in the future, I’m just not sure exactly what would be best.)
This DrRacket plugin adds a Script menu to the main window. This menu has several items, followed by the (initially empty) list of active scripts.
a .rkt file, the script itself (with a sample program)
a .rktd file, the metadata of the script with the default values
The script menu is rebuilt each time the user activates it, so that changes are taken into account as soon as possible.
This is the script file. It must provide the item-callback function, as in the sample code. It is meant to be executable by itself, as a normal module, to ease the testing process.
The path to the current file of the definition window, or #f if there is no such file (i.e., unsaved editor).Example:
(define (item-callback str #:file f) (string-append "(in " (if f (path->string f) "no-file") ": " str))
#:definitions : text%
The text% editor of the current definition window.
See text% for more details.
#:interactions : text%
The text% editor of the current interaction window. Similar to #:definitions.
#:editor : text%
The text% current editor, either the definitions or the interactions editor. Similar to #:definitions.
#:frame : drracket:unit:frame<%>
DrRacket’s frame. For advanced scripting.Example:
The name of the function can also be changed, but this requires to change it also in the functions entry of the .rktd file, and the function must be provided.
This is the metadata file. It contains an association list that defines the configuration of the script.
Note: This file being a data file, it should almost never contain quotes. The quotes in the following definitions must thus not appear in the file.
Most options (label, shortcut, shortcut-prefix, help-string) are the same as for the menu-item% constructor. In particular, a keyboard shortcut can be assigned to an item.
Additionally, If the label is 'separator, then a separator is added in the menu.
If a symbol, the name of the function to call (which must be provided), and must follow item-callback’s signature.
If a list, each symbol is the name of a function, and each string is a label for that function. In this case, a sub-menu holding all these functions is created, and the label option is used as the parent menu name.
Note that a sub-menu can be shared among scripts.
Example:The following .rktd file will create a submenu named My Functions (with the letter F for keyboard access), containing 3 items, one for each function and its associated letter-accessor.
((label . "My &Functions") (functions . ((my-function1 "My Function #&1") (my-function2 "My Function #&2") (my-function3 "My Function #&3") )) (output-to . message-box) )And the associated .rkt example file:
Note: The label can also be 'separator.
If 'selection, the output of the transform function replaces the selection in the current tab (or insert at the cursor if there is no selection). If 'new-tab, a new tab is created and the output of the script is written to it. If 'message-box, the output is displayed in a message-box. If #f, no output is generated.
If set to #f, no menu item is generated for this dictionary.
Finally, one .rktd file can contain several such dictionaries (one after the other), which allows for multiple sub-menus and menu items and in a single script. This would have roughly the same effect as splitting such a script into several script, each one with its own .rktd file and its dictionary.
Auto-completion (see the "complete-word.rkt" example)
Code snippets scripts, with keyboard shortcuts, e.g., adding a require line for each planet package you usually use, or a license header
Module template (e.g., the "info.rkt" file)
ASCII frames and styling (upper-case, ASCII art, etc.) for comment titles, sections, etc. (see the "sections.rkt" example)
Automatic comments, e.g. with today’s date, user name, etc. (see the "author-date.rkt" example)
Automatic reformatting and custom indentation (see the "indent-let.rkt" example)
Analyse the current file and display the results in a new tab, or Count the number of words/lines/characters and display it in a message-box
Perform a particular search and replace operation
Open a new tab with a template code
Commit/update files from repositories
Perform various OS tasks, e.g., open the OS’s browser or terminal in the directory of the current file
Turn DrRacket into a very rich text editor with slideshow (see the "test-slideshow.rkt" example)
Note that racket/gui can be used to ask the user for more information and more.
Remark: Code snippets should probably be of rare usage, as one should better take advantage of Racket’s wonderful macro system. In some cases however, snippets might be useful, e.g., to require your common module where all your usual macros and functions are defined, or for automatic comments.
Copyright (c) 2012 by Laurent Orseau <laurent.orseauREMOVEME@gmail.com>.
This package is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You can find a copy of the GNU Lesser General Public License at http://www.gnu.org/licenses/lgpl-3.0.html.