by Brad Hanson (bradh@spamcop.net) March 29, 1998 - Version 1.1.4
This document describes a BBEdit tool that works with MacPerl to allow Perl scripts to act as text filters on text selected in a BBEdit window. A BBEdit tool is a special type of BBEdit plug-in that has a floating window as an interface (BBEdit plug-ins were called extensions in versions of BBEdit prior to 4.5). The floating window contains a list of Perl scripts. A script contained in the floating window can be applied to text selected in a BBEdit window. MacPerl is a Macintosh port by Matthias Neeracher of the Perl programming language. Information about MacPerl is available at MacPerl Home Page and the MacPerl Pages.
The latest version of this tool is available at my BBEdit plug-ins web page.
This tool is also available in the Info-Mac archives in the text/bbe directory.
This tool is a 68K BBEdit tool and should work on a 68K or PowerPC Macintosh with MacPerl 4 or 5, and BBEdit version 3.5.2 or later. BBEdit tools cannot be used with BBEdit Lite. The tool requires Macintosh system software version 7.0 or later.
This tool is freeware. If you have any questions or comments, or would like a copy of the source code, please let me know.
The tool is started by selecting ``Perl Filters'' from the BBEdit Tools menu. A command key can be assigned to the Perl Filters tool 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 the Perl Filters tool in versions of BBEdit prior to 4.5 use the ``Set Keys'' item in the BBEdit Extensions menu.
After the tool is started a floating window (named ``Perl Filters'') is displayed containing a list of file names. There are two buttons at the top of the Perl Filters window - a ``Run'' button, and an ``Options'' button. The files listed in the tool window are those contained in a folder named ``Perl Filters'' in the same folder as the BBEdit application (a later section describes how to modify which folder is used by the tool). Double-clicking on a file name in the list will open the file (or file group) in a BBEdit window.
Selecting a text file and clicking on the Run button will run the Perl
script contained in the file. The text selected in the active BBEdit window
will be written to a temporary file and the full path name of this file
will be passed to the script as the first element in the @ARGV
array. If a range of text is not selected in the active BBEdit window then
all the text in the window will be selected and used. Any output of the
script written to STDOUT will replace the selected text in the active
BBEdit window. If the script writes to STDERR (e.g., an error occurs when
compiling or running the script) then a BBEdit window is opened and the
STDERR and STDOUT text is written in the window (STDERR text is written
first followed by any STDOUT text). In this case the text selected in the
active BBEdit window when the script was started is left unchanged.
The Run command uses the selected script as saved on disk. Consequently, when a script contained in the Perl Filters window is opened in BBEdit and modified, the script must be saved in order for the modified script to be used when run by the tool.
The memory allocation given to BBEdit will need to be increased if a large amount of text (in STDOUT or STDERR) is returned to BBEdit (greater than about 400,000 bytes for the standard BBEdit memory partition). If more text is returned than BBEdit can handle with the memory partition it is given BBEdit may quit or freeze.
Clicking on the Options button will display a dialog from which preferences for the tool can be chosen. At the top of the dialog are two radio buttons: ``STDERR to new window'' and ``STDERR to MacPerl window''. If the ``STDERR to new window'' radio button is selected then any output of a script to STDERR is written in a new BBEdit window. If the ``STDERR to MacPerl window'' button is selected then any output to STDERR is written in a window corresponding to a file named ``MacPerl'' in the same folder as the BBEdit application. The MacPerl file is opened if needed. If the file does not exist it is created. A later section describes how to change the file used for MacPerl output when the ``STDERR to MacPerl window'' option is chosen.
Within the box containing the two ratio buttons at the top of the preferences dialog are two check boxes: ``Clear MacPerl window before writing'', and ``Save MacPerl window after writing''. These two check boxes will only be active if the ``STDERR to MacPerl window'' radio button is selected. If the ``Clear MacPerl window before writing'' option is selected then any contents of the MacPerl window are cleared before output from a Perl script is written to it. If this option is not selected then any output to the MacPerl window is appended to the end of the window contents. If the ``Save MacPerl window after writing'' check box is checked then the MacPerl window is automatically saved after output from a Perl script is written to it, otherwise the MacPerl window is not saved.
There are two check boxes below the box containing the radio buttons. If the ``STDOUT to window used for STDERR'' check box is checked then any output of a script written to STDOUT is put in the window used for STDERR instead of replacing the text selected in the active window.
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 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.
After the desired options have been set in the preference dialog clicking the OK button will save the options in the BBEdit preferences file (in resource 128 of type 'P*rT'). The options saved will be used when a script is run using the tool.
Since the text selected in the active BBEdit window is passed to the script
as a temporary file whose name is put in @ARGV, the line input (angle)
operator with a null filehandle (<>) can be used to read through the lines of the selected text. The -p and -n switches can also be used to create an implicit while(<>){} loop around the script. The -p switch causes a print statement to be executed after each iteration of the
loop (each line is automatically printed). With the -n switch lines are not automatically printed. For example:
#!perl -p
# Remove spaces at beginning and end of each line
# and change any other sequence of spaces to
# a tab character.
s/^ +//;
s/ +$//;
s/ +/\t/g;
If the file containing this script is selected in the Perl Filter window
and the Run button is pressed then the three statements in the script are
applied to each line of the text selected in the active BBEdit window. The
transformed lines replace the selected text. The -p switch causes an implicit while(<>){} loop to be put around
the statements and an implicit print; to occur, so the script functions
identically to the following script
#!perl
while(<>)
{
s/^ +//;
s/ +$//;
s/ +/\t/g;
print;
}
Another example:
#!perl -an
# Keep specified columns in each line of the selection.
# Columns are separated by white space. On output
# columns are separated by a single tab character.
# First line of selection contains column numbers of
# of columns to keep (zero offset)
BEGIN { $_ = <>; @columns = split; }
$last = chomp;
print join("\t", @F[@columns]);
print "\n" if $last == 1;
This example uses the -a switch in addition to the -n switch. The -a
switch results in an implicit split command to the @F array.
The BEGIN block is executed before the implicit while(<>){} loop around the other statements. BEGIN and END blocks can be used
with the -n and -p switches to execute statements before or after the implicit loop. If the
selected text in the active BBEdit window is
0 2 3
1 2 3 4
5 6 7 8
1 2 3 4
5 6 7 8
then clicking on the Run button in the Perl Filters window with the file containing the above script selected would result in the selected text in the active BBEdit window being changed to
1 3 4
5 7 8
1 3 4
5 7 8
The two examples presented used the -n and -p switches which are often convenient to use for simple text filters. As
shown for the first example, the scripts could have been written without
these switches by using an explicit while(<>){} loop. The Perl
Filter tool comes with an example Perl Filters folder that contains some
other example scripts.
Actions of the Perl Filter tool are undoable, so the action performed on the selected text by a script can be undone by selecting ``Undo Tool'' from the Edit menu. It is possible that the action of a script may not be undoable if there was not enough memory available when the script was run to make the action undoable.
Files added to the Perl Filters folder while the tool is active will not appear in the Perl Filters window until after the window is closed and the tool restarted. Similarly, files that are deleted from the Perl Filters folder while the tool is active will not be removed from the Perl Filters window. An error indicating the file could not be found will be displayed when trying to open or run a file in the tool window that is no longer in the Perl Filters folder.
Additional text files can be added to the list of files displayed by dragging and dropping files on the Perl Filters window. This requires that the Macintosh Drag Manager is available (the Drag Manager is included in Mac OS System 7.5 and later). An easy way to add a file to the window is to open the file in BBEdit and drag the document icon in the BBEdit status bar at the top of the window (the icon just to the left of the text ``Last Saved'' in the BBEdit status bar) to the Perl Filters window (this is only possible for a document that has been saved, not a new document). The file name is added to the end of the list of file names in the Perl Filters window.
A file can also be dragged and dropped from a Finder window to the Perl Filters window. This requires BBEdit to be active when the drag is initiated because the Perl Filters window is a floating window that is hidden when BBEdit is not the active application. Thus, in order to drag and drop a file from the Finder to the Perl Filters window the file must be visible in a Finder window when BBEdit is active, and the Finder is in the background. The file can then be selected and dragged to the Perl Filters window.
Files added to the Perl Filters window by dragging and dropping are not added to the Perl Filters folder. They are only displayed in the Perl Filter window until the window is closed. When the Perl Filters tool is restarted any files added to the window the last time it was open will not appear. For files to appear in the Perl Filters window every time the tool is started they must be moved to the Perl Filters folder.
BBEdit file groups listed in the Perl Filters window can be opened and files listed in the file group window can then be dragged and dropped on the Perl Filters window to temporarily add them to the list of files. File groups are useful for maintaining access to groups of files that may be occasionally used as Perl filters, but do not need to appear in the Perl Filters window every time it is opened.
The folder name is contained in 'TEXT' resource 257. This resource initially contains the text ``Perl Filters''. If this text is changed, for example, to ``Perl Text Filters'' then when the tool is started it will look for a folder named ``Perl Text Filters'' in the same folder as the BBEdit application from which to read the file names that will be displayed in the tool window.
If the contents of 'TEXT' resource 257 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 257 were ``:MacPerl folder:Perl Filters'' then the files to be displayed in the tool window would be assumed to be contained in a folder named ``Perl Filters'' 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 257 can also contain a full path name which fully specifies the location of the folder used (a full path name can contain any number of characters). If a full path name is given the folder does not have to be contained in the folder containing the BBEdit application.
If 'TEXT' resource 257 is set to a null string (there are no characters in the string) then when the tool is started it will prompt the user to select a folder to be used. All text files in the folder chosen will be displayed in the Perl Filters window. If the resource is set to a null string a dialog to select a folder name is presented every time the tool is run (in this case the tool does not remember the folder chosen from one time it is run to the next).
If the tool cannot find the folder specified in TEXT resource 257 then an empty Perl Filters window is displayed (files can be added to the window as described in the previous section).
The following steps can be used to create a copy of the tool using ResEdit: