by Brad Hanson (bradh@spamcop.net) March 29, 1998 - Release 6
The document describes BBEdit plug-ins (called BBEdit extensions in versions of BBEdit prior to 4.5) that facilitate the use of BBEdit as an external editor for MacPerl. MacPerl is a Macintosh port by Matthias Neeracher of the Perl programming language. Information about MacPerl is available at the MacPerl Home Page and the MacPerl Pages.
The latest versions of these plug-ins are available at my BBEdit plug-ins web page.
The distribution includes a BBEdit plug-in tool named ``Perl Filters'' that displays a floating window containing a list of Perl scripts. A script contained in the floating window can be applied to text selected in a BBEdit window. The Perl Filters plug-in tool is described in a separate document.
The six plug-ins included are: 1) Run MacPerl, 2) Check Perl Syntax, 3) Run MacPerl Front, 4) Run File with MacPerl, 5) Edit MacPerl Script, and 6) Shuck. Each of these plug-ins can be used with either BBEdit or BBEdit Lite, except the Edit MacPerl Script plug-in which only works with BBEdit, not BBEdit Lite. Descriptions of these plug-ins are given in later sections. Also included is a Perl Palette written by Lindsay Davies. The Perl Palette displays a floating palette containing buttons for each of the six BBEdit plug-ins. The Perl Palette only works with BBEdit, not with BBEdit Lite.
These plug-ins are independent of one another and any of them can be installed without the others. To install a plug-in quit BBEdit and put the plug-in in the ``BBEdit Plug-Ins'' folder that is in the same folder as the BBEdit application (or the ``BBEdit Extensions'' folder for versions of BBEdit prior to 4.5). The plug-ins can also be put in any folder within the BBEdit Plug-Ins folder.
To install the Perl Palette move it into the same folder that contains the BBEdit plug-ins for MacPerl. To use the Perl Palette the plug-ins must be contained in the BBEdit Plug-Ins folder, or a folder named ``perl Tools'' within the BBEdit Plug-Ins folder. Installation of the Perl Palette is optional. It is not necessary to install the Perl Palette to use the plug-ins.
The plug-ins are run by selecting them from the BBEdit Tools menu (the Tools menu was named the Extensions menu in versions of BBEdit prior to 4.5). A command key can be assigned to a BBEdit plug-in by selecting the Tools List item from the Tools menu and using the Set Key button in the BBEdit Tools window. To assign a command key to a plug-in in versions of BBEdit prior to 4.5 use the ``Set Keys'' item in the BBEdit Extensions menu. Four of the plug-ins (Run MacPerl, Check Perl Syntax, Run MacPerl Front, and Run File with MacPerl) have preferences that can be changed. Selecting any of these plug-ins from the BBEdit Tools menu with the option key held down will display a preference dialog.
To activate the Perl Palette within BBEdit select ``Perl Palette'' from the Tools menu in BBEdit 4.5 (or the Extensions menu in BBEdit 4.0). The Perl Palette displays a floating palette containing buttons for the six BBEdit plug-ins. Which plug-ins are displayed in the palette and some aspects of the appearance of the palette can be controlled by the pop-up menu in the upper left corner of the palette. A plug-in can be run by clicking on the associated button in the palette.
These plug-ins are 68K BBEdit plug-ins and should work on a 68K or PowerPC Macintosh with MacPerl 4 or 5, and BBEdit (version 3.5 or later) or BBEdit Lite (version 3.0.1 or later). The plug-ins require Macintosh system software version 7.0 or later.
These plug-ins are freeware. If you have any questions or comments, or would like a copy of the source code, please let me know. I thank everyone who has provided feedback to me on the plug-ins. I thank the following people for their assistance in the design and testing of the plug-ins: Matthias Neeracher, Richard Pfeiffer, Nicolas Le Clerc, Peter Sylvan, Scott Prahl, Rich Morin, and Vicki Brown.
Descriptions of the plug-ins are given in the following sections.
Selecting the Run MacPerl plug-in from the BBEdit Tools menu while holding down the option key will display a dialog from which preferences for the plug-in can be chosen. At the top of the dialog is a box with three radio buttons and two check boxes. These items control how output of a script to STDOUT or STDERR is handled. If the ``New window'' radio button is selected then any output of a script to STDOUT or STDERR is written in a new BBEdit window.
If the ``MacPerl file'' radio button is selected then any output to STDOUT or STDERR is written in a window corresponding to a text file named ``MacPerl'' in the same folder as the BBEdit application. The MacPerl file is created and opened if needed. A later section describes how to change the file that is used for STDOUT and STDERR when the ``MacPerl file'' option is chosen.
If the ``File based on script name'' radio button is selected then output to STDOUT or STDERR is written in a window corresponding to a file that has the same name as the file containing the script with '.log' appended, and is in the same folder as the script. If the script is in a new window output to STDOUT or STDERR is written to a new window. For example, if the file containing the script is named 'hello.pl' then output to STDOUT or STDERR would be written in a window corresponding to a file named 'hello.pl.log'. This file is created if it does not exist, and opened in BBEdit if it is not already open. A later section describes how to change the naming convention used to create the output file.
Within the box containing the two ratio buttons at the top of the preferences dialog are two check boxes: ``Clear window before writing'', and ``Save window after writing''. These two check boxes will only be active if the ``MacPerl file'' or ``File based on script name' radio button is selected. If the ''Clear window before writing`` option is selected then any contents in output window are cleared before output from a Perl script is written. If this option is not selected then any output to the output window is appended to the end of the window contents. If the ''Save window after writing`` check box is checked then the output window is automatically saved after output from a Perl script is written to it, otherwise the output window is not saved. The ''Save window after writing`` option is only available when using the plug-in with BBEdit, not BBEdit Lite (this check box is dimmed when using the plug-in with BBEdit Lite).
There are eight check boxes below the box containing the radio buttons. If the ``Use Error Browser'' check box is checked then a BBEdit error browser is created if a script that is run has errors. The browser is not created if the script is contained in a new BBEdit window that has not been saved. The browser is only created if there is more than one error (if there is only a single error an alert is shown indicating the error). The browser contains only the first ten errors. This option is not available in BBEdit Lite (the ``Use Error Browser'' check box will be dimmed when using the plug-in with BBEdit Lite).
If the ``Save active window before running'' check box is checked then the active BBEdit window is saved before the script in the window is sent to MacPerl. This option is only available when using BBEdit, not BBEdit Lite (the check box is inactive when using the plug-in with BBEdit Lite). This option has no effect if the active window is a new window that has not been saved to disk.
If the ``Set working directory to script folder'' check box is checked then the default working directory when a script is run is set to the folder containing the script. If this option is not set the default working directory is the folder containing the MacPerl application. The working directory can be changed within a script by using the chdir function. This option has no effect if the script is in a new BBEdit window that has not been saved to disk (in which case the default working directory will always be the folder containing the MacPerl application), or if the ``Use file of active window for script'' option described below is selected (in which case the default working directory will always be the folder containing the script, unless the script is contained in a new window).
If the ``Switch to MacPerl'' check box is checked then MacPerl is brought to the front and the script is run as though the Run Script command was used in MacPerl (STDOUT and STDERR are send to the output window in the MacPerl application). This option needs to be set if any MacPerl specific functions that put up a window or dialog (such as MacPerl::Choose or MacPerl::Ask) are contained in the script or the script uses STDIN. For cautions on using this option see the description of the Run MacPerl Front plug-in below.
The ``Check syntax'' check box controls whether is script is only checked for syntax errors or is run. If the ``Use debugger'' check box is checked MacPerl is switched to the front when a script is run and the Perl debugger is started. The ``Check syntax'' and ``Use debugger'' check boxes can not both be checked. If one is of these check boxes is checked the other will be dimmed. The syntax of a script can be checked without the ``Check syntax'' option being used by putting ``#!perl -c'' (without the quotes) as the first line of the script.
If the ``Use file of active window for script'' check box is checked then the file corresponding to the document in the active window is sent to MacPerl as the script to be executed rather than the text in the active window. If the text in the active window has been modified and not saved to disk (and the ``Save active window before running'' check box is not checked) then the version of the script as saved on disk rather than the version of the script in the window is used. This option has no effect if the active window is a new window that has not been saved to disk. When this option is used the error browser may not report accurate line numbers if the active window has been changed and not saved to disk.
If the ``Use selected text for script'' check box is checked then only the selected text in the active BBEdit window is sent to MacPerl as the script to be run. If this option is not selected then all the text in the active window is used as the script even if some of the text is selected. If this option is used and there is no text selected in the active BBEdit window then the plug-in behaves the same as if the option were not used. This option takes precedence over the ``Use file of active window for script'' option when both options are used and text is selected in the active BBEdit window.
After the desired options have been set in the preference dialog clicking the OK button will save the options in the BBEdit preference file (in resource 128 of type 'P*r1'). The options saved will be used when a script is run by selecting the plug-in without holding down the option key. Since the preferences are saved in the BBEdit preference file they are retained even after BBEdit is quit and restarted.
run macperl list -- List passed to Perl in @ARGV
[stdout file specification] -- File opened in BBEdit to contain STDOUT and STDERR
[with preferences record] -- Preference record used to run script
Sending the run macperl event to BBEdit is the same as running the Run
MacPerl plug-in from within BBEdit. The script to be run is taken from the
front window in BBEdit. There are three optional parameters to the run
macperl event. The direct parameter is a list that is passed to the Perl
script in @ARGV (the direct parameter is optional). The stdout parameter contains a file that will be created if it does not exist, opened
in BBEdit, and used for STDOUT and STDERR. If the stdout parameter is used this overrides the preferences set for the plug-in as to
where STDOUT and STDERR should be written.
The with preferences parameter can be used to temporarily override any of the plug-in preferences for the event. A record is used with the with preferences parameter to specify the preference settings. The fields of the record are:
output small integer -- STDOUT and STDERR to: 0) new window, 1) MacPerl file, 2) file based on script name clear output boolean -- Clear output window before writing save output boolean -- Save output window after writing save active boolean -- Save active BBEdit window before running working directory boolean -- Set working directory to script folder switch boolean -- Switch to MacPerl check syntax boolean -- Check syntax of script use debugger boolean -- use debugger use file boolean -- Use file of active window for script use selection boolean -- Use selected text for script error browser boolean -- Use error browser
The preferences as currently set for the plug-in are used for any fields not specified in the with preferences parameter.
For following AppleScript is an example of scripting the Run MacPerl plug-in.
on open fileList
tell application "BBEdit 4.5"
activate
run macperl fileList with preferences {error browser:true, use selection:true}
end tell
end open
If this script is saved as an AppleScript application then when files are
dropped on the application the Perl script in the front BBEdit window will
be run with @ARGV containing the files dropped on the
AppleScript application. The 'Use selected text for script' and 'Use error
browser' options will be set even if they are not currently set in the
plug-ins preferences (the preferences are only temporarily changed for the
duration of the run macperl
event).
The procedure for creating special versions of the Run MacPerl plug-in with ResEdit will be illustrated by describing the steps used to create the Check Perl Syntax plug-in.
When the ``MacPerl file'' radio button is selected in the preferences dialog STDOUT and STDERR are written to a file named ``MacPerl'' that is in the same folder as the BBEdit application. The name of this file can be changed from ``MacPerl'' to another name by changing the string stored in 'TEXT' resource 260 of the plug-in from ``MacPerl'' to the desired file name. If the contents of 'TEXT' resource 260 begins with a colon then the string is considered a partial path name relative to the folder containing the BBEdit application. For example, if the contents of 'TEXT' resource 260 is ``:MacPerl folder:output'' then the file used for output will be the file named ``output'' that is in the folder ``MacPerl folder'' in the folder containing the BBEdit application. Partial path names are limited to 255 characters. The contents of 'TEXT' resource 260 can also contain a full path name which fully specifies the location of the file used for output (a full path name can contain any number of characters).
When the ``File based on script name'' radio button is selected STDOUT and STDERR are written to a file whose name is the name of the file containing the script with a '.log' appended that is in the same folder as the script. The text appended to the name of the file containing the script to create the output file is contained in the first string of 'STR#' resource -356. If this string were changed from '.log' to '.out' then, for example, the file used for STDOUT and STDERR for a script contained in a file named 'hello.pl' would be 'hello.pl.out'.
If there is a second string in 'STR#' resource -356 then the first character of that string is used with the first string in 'STR#' resource -356 to create a file name as illustrated in the following example. Assume the first string in 'STR#' resource -356 is 'log' and there is a second string in 'STR#' resource -356 whose first character is a period ('.'). Then the name of the file used for STDOUT and STDERR is the same as the name of the file containing the script with all characters after the last period replaced by 'log'. For example, if the name of the file containing the script was 'hello.pl' then the file used for STDOUT and STDERR would be 'hello.log'.
When a file is created by the plug-in to hold STDOUT and STDERR then 'MPSR' and 'BBST' resources are written in the resource fork of the file which contain BBEdit state information about the file (e.g. the size and position of the window, etc.). The 'MPSR' and 'BBST' resources that are written to created files are contained in the resource file of the plug-in. The 'MPSR' and 'BBST' resources numbered 1005 are used when creating a file when the ``MacPerl file'' option is chosen. The 'MPSR' and 'BBST' resources numbered 1006 are used when creating a file when the ``File based on script name'' option is chosen. If 'MPSR' and 'BBST' resources numbered 1006 do not exist then the 'MPSR' and 'BBST' resources numbered 1005 are used. If no 'MPSR' and 'BBST' resources numbered 1005 or 1006 exist then no state information is written to created files. The state information written for files created by the plug-in can be controlled by replacing the 'MPSR' and 'BBST' resources in the plug-in. An easy way to do that is to create a file in BBEdit with the desired state information and copy the 'MPSR' and 'BBST' resources from that file to the plug-in.
Other applications are not really supposed to be brought to the front when a BBEdit plug-in is running. Because of this there is a potential for problems to occur when using this plug-in, although I have not run across any problems in the examples I have tried.
An alternative to using this plug-in is the following AppleScript script:
tell application "BBEdit 4.5"
set theScript to text of window 1
end tell
tell application "MacPerl"
activate
Do Script theScript
end tell
This script will appear under the Script menu in BBEdit (the script icon in the menu bar on the right of the other BBEdit menus) if it is saved from the Script Editor as a compiled script in the ``BBEdit Scripts'' folder that is in the same folder as the BBEdit application. This AppleScript script will only work with BBEdit 3.5.2 or later, not BBEdit Lite.
This file was created from the Run MacPerl plug-in by setting an option that results in the plug-in putting up a standard file dialog to get the script to run. This option is not visible in the preferences dialog of the Run MacPerl plug-in. The option can be set by changing the 'BPpf' resource in the Run MacPerl plug-in (setting the seventh bit of the 13th two-byte integer to 1).
Holding down the option key while starting the Run File with MacPerl plug-in will display a preference dialog that is identical to the preference dialog displayed for the Run MacPerl plug-in, with the exception that four of the check boxes are not active (``Save active BBEdit window'', ``Use file of active window for script'', ``Set working directory to script folder'', and ``Use selected text for script'').
After the plug-in is started, and a file selected from the standard file dialog, the Perl script contained in the file will be displayed in a BBEdit window. When the BBEdit save command is used a command is sent to MacPerl to replace the script in the file with the modified version in the BBEdit window.
This plug-in functions the same as selecting Edit from the BBEdit menu in MacPerl. The BBEdit menu will appear in MacPerl if BBEdit is set as the editor helper application with Internet Config.
It is possible to use ResEdit to modify the MacPerl application so that the files created by a Perl script will have BBEdit as the creator rather than MPW. Open the MacPerl application with ResEdit and open the resource of type GUSI (where the ``S'' in GUSI is actually a capital sigma). The field named ``Creator of created files'' contains a four character application signature. Change the text of this field to R*ch (the application signature of BBEdit) and save the modified MacPerl application.
Of related interest is the BBEdit Script Extension for MacPerl written by Matthias Neeracher. This allows Perl scripts to be saved as BBEdit plug-ins in MacPerl - allowing BBEdit plug-ins to be written in Perl. There is a Perl interface to BBEdit that allows MacPerl scripts saved as BBEdit plug-ins to use BBEdit plug-in callbacks. The BBEdit Script Extension for MacPerl is available at ftp://err.ethz.ch/pub/neeri/MacPerl/MPBBEdit_01Nov96.sit.bin