MacFormat 1995 January

home *** CD-ROM | disk | FTP | other *** search

/ MacFormat 1995 January / macformat-020.iso / Shareware City / Applications / Alpha.5.96 folder / Help / MacPerl Help < prev next >

Wrap

Text File | 1994-09-19 | 17.9 KB | 406 lines | [TEXT/ALFA]

------------------------- MacPerl Support in Alpha ------------------------- This document describes the MacPerl menu in Alpha. The MacPerl menu was written to allow Alpha to act as a front end for the Matthias Neeracher's standalone MacPerl application and to provide a way to use Perl scripts to process text buffers in Alpha. If you aren't familiar with the Perl language, a descriptive introduction is provided in the help file "Perl Commands"; that file also contains a reasonably complete language reference. Instructions for obtaining the MacPerl application are given further below. Installation ------------ To use Perl mode and the MacPerl menu, they must first be installed by selecting "MacPerl" from "Utils:Install" menu. Once installed, Perl mode can used to edit Perl script files, and the MacPerl menu will become active whenever you enter Perl mode. During installation, you'll be prompted to locate your copy of the MacPerl application. Also, you'll be asked whether you want to install a sample collection of Perl text-filter scripts in the MacPerl application folder. Unless you already have a "Text Filters" folder there, you should probably choose to install the sample files, since they provide a good demonstration of how the text filter mechanism can be used. Finally, you'll be asked whether to make the MacPerl menu active in Text mode. You should say "yes" if you intend to use the text filter mechanism, since text filter scripts are typically most useful when you're editting ordinary text files. Perl Mode --------- Perl mode is entered when you open a file with a ".pl" suffix or when it is explicitly chosen from the modes menu on the sidebar. The prefix character (used by the "Convert:Strings" menu commands) is then set to the Perl comment character ("#") and keyword colorization is turned on for the Perl operators and predefined names. Also, choosing "Mark File" from the marks menu on the sidebar will create index markers for any Perl subroutines found in the current file. MacPerl Menu ------------ Alpha's MacPerl menu allows the following actions: MacPerl actions • You can switch over to the MacPerl application, launching it if necessary. • The current window in Alpha can be opened under MacPerl. The file may first be saved, if desired. • The contents of the MacPerl output window can be retrieved and written into a new window under Alpha. • You can quit the MacPerl application remotely from Alpha. Executing Perl Scripts from Alpha • Selected text (or the entire buffer) may be executed as a Perl script by the MacPerl application. • A selected Perl script file (on disk) may be executed. Scripts run in the aforementioned ways will run as though they were executed from within the MacPerl application, itself. That is, standard input is taken from an interactive window created automatically under MacPerl, and standard output is written to the MacPerl output window. • Flags controlling Alpha's behavior when executing ordinary scripts may be set: Retrieve Output When checked, any output written to the MacPerl output window is captured and written into a new window under Alpha. Auto Switch When checked, MacPerl is made the frontmost application when the script is executed. Otherwise, Alpha remains frontmost while waiting for the script to complete. Prompt For Args When checked, Alpha will prompt you for command-line arguments to be passed to the script. Applying Text Filter Scripts • Perl scripts that read from standard input and write to standard output may be used as text filters within Alpha. The script can be chosen from a set of "pre-attached" scripts in the "Text Filters" folder, from a file, or from another text buffer in Alpha. This is all explained in more detail below. • The last text filter used (from any source) may be run again. It's the source that's reused, actually. If you change the script in between uses, the new script will always be used. • Flags controlling the behavior of the text filter mechanism may be set. There are only two at present: Apply To Buffer When checked, the entire current text window is used as "standard" input for the text filter script; otherwise, only the selected text is used. Overwrite Selection When checked, the output from the text filter script will replace the input text in the original window. Otherwise, the output is written into a new window. • The temporary i/o files used by the text filter mechanism (STDIN, STDOUT, and SCRIPT) may be opened for debugging purposes. Other • The MacPerl menu may be rebuilt. This is useful when files are added to or removed from the "Text Filters" folder after Alpha has started up. Running Scripts --------------- Running scripts using the MacPerl menu is pretty straightforward. You can send the current selection, the entire current buffer, or a disk file to MacPerl for execution as a Perl script; the result will be the same as if you ran the script from MacPerl itself. Unless you explicitly arrange otherwise, this means that standard input is taken from the keyboard (under the MacPerl application) and standard output goes to MacPerl's output window. If the menu flag "Prompt For Args" is checked, then the user is prompted for command-line arguments at the time the script is run. These will be available inside the script through the @ARGV array, as usual. They are also saved in the Perl-mode variable "perlCmdlineArgs", and become the default arguments the next time the script is executed. By default, Alpha will switch over to the MacPerl application while the script is running, and then switch back to Alpha when it's done. This allows you interact with the script, if required, and see terminal output as it appears. This is necessary if you want to run your script under the Perl debugger, for instance. You may also prefer not to switch over to the MacPerl application while the script is running; this results in much less distracting window-swapping, etc., and is probably a bit faster. If you uncheck the flag "Auto Switch", then Alpha will _not_ switch to MacPerl while the script runs. Alpha, in either case, will wait until the script has completed before doing anything else. When the script has completed, any output to MacPerl's standard output window is captured by Alpha and written into a new window. You can suppress this by unchecking the "Retrieve Output" flag on the MacPerl menu. If for some reason the output _isn't_ retrieved when you wanted it, you can always grab it directly using the "Get Output Window" menu command. If the script failed for some reason, Alpha will read the error messages from the MacPerl output window and copy them back into a new window for you to examine. The script that generated the error is brought up and the first line specifically referenced in an error message is highlighted. Note that error-trapping remains active whether "Retrieve Output" is set or not. Sometimes you may find that a script hangs. For instance, if MacPerl is configured to check for "#!" lines in scripts and yours doesn't have one, it will put up a dialog asking whether or not to procede. If you didn't switch over to MacPerl when the script was run, you have know way of knowing this, and so you and Alpha may end up just sitting there waiting. While annoying, a hung script is usually not fatal. You can always tell Alpha to stop waiting for a script to finish by hitting "Cmd-.". You may still have to switch over to MacPerl to terminate the script there, as well. Text Filters ------------ Perl is, among other things, a powerful tool for rewriting and extracting data from text files. On a Unix system, one would typically write text-processing scripts to read from "standard input" and write to "standard output", taking advantage of command-line i/o redirection to specify the actual input and output files used at any given time. On the Mac, the general absence of a command-line interface makes it harder to use this elegant method. The MacPerl menu in Alpha makes it possible to use scripts that read from standard input and write to standard output to process text buffers in Alpha directly. Any text window can be used as standard input, and standard output can either be directed back to that same window or to a newly created one. The script used may either be a disk file or an Alpha text window; it is selected interactively using the "Text Filters" and "Other Text Filters" submenus of the MacPerl menu. Note that Alpha will remember the last filter script you use (from any source) and let you run it again using the menu command "repeatLastFilter". You can see the name of this script by examining the variable "perlLastFilter" under the flags menu in Perl mode. The input for a filter script is always taken from the text window that's current when you call the script. Whether the entire buffer or just the selected text is used is controlled by the menu flag "ApplyToBuffer". If this flag is checked, then the entire text window is used as standard input, otherwise only the selected (highlighted) text is used. The output from the filter script either replaces the input text or else is written into a new text window. The choice is controlled by the other menu flag, "OverwriteSelection". If the flag is checked, then the input text is deleted from its buffer and the Perl output is inserted in its place; otherwise a new window is created to hold the output text. As always, Alpha's unlimited undo capability let's you recover if you accidently overwrite the input text when you didn't want to. If the script triggers an error, then the filter operation is aborted. Any error messages are retrieved from MacPerl's output window and displayed in Alpha, as described above. The ability to take the script itself from a text window allows simple one-time scripts to be created and applied on the fly. This can be very useful because, even with the overhead to start up MacPerl, large-scale global search-and-replace operations (hundreds of replaces) can be substantially faster in MacPerl than in Alpha. Also, you might find it easier to apply a series of regular expression substitutions using a single, short Perl script, rather than a number of separate "Find" and "Replace All" commands in Alpha. Preattached Scripts ------------------- Frequently used text filter scripts can be conveniently accessed by placing them in a folder called "Text Filters" within the MacPerl application folder. When the MacPerl menu is first created, it looks in this folder and builds a hierarchical submenu from the names of the scripts that it finds. Note that it will also create a "Text Filters" folder if one doesn't already exist. As mentioned above, a sampling of useful :-) Perl scripts is distributed with Alpha in the folder ":Tcl:UserCode:Text Filters". When the MacPerl menu is installed, you have the option of copying this folder to your MacPerl folder to get yourself started; if you already have a "Text Filters" folder there, you might not want to do this, since files with the same names as the sample files would be overwritten. Of the scripts in the sample collection, the "Text Munging" scripts ("shuffle", "sort lines", "travesty", and "wordcount") were taken from the Camel book ("Programming Perl"). The "s2p" script is my adaptation of the standard code that converts Unix "sed" scripts to Perl (it was modified to work without using the C preprocessor.) "Strip Mail Headers" takes e-mail files and edits out any header lines but the few that I typically care about ("From:, "Date:", etc..). "CC To BibTeX" is a script I use that takes listings from the online "Current Contents" database and rewrites them as BibTeX database entries. To try it out, select (highlight) the sample Current Contents citation below and choose "CC To BibTeX" from the "Text Filters" submenu (make sure that "Apply To Buffer" is _not_ checked before you do!) 288. VOS MH; LAMBRY JC; ROBLES SJ; YOUVAN DC; and others. FEMTOSECOND SPECTRAL EVOLUTION OF THE EXCITED STATE OF BACTERIAL REACTION CENTERS AT 10-K. PROCEEDINGS OF THE NATIONAL ACADEMY OF SCIENCES OF THE UNITED STATES OF AMERICA, 1992 JAN 15, V89 N2:613-617. Technical Details ----------------- In case something doesn't work the way you expect it to, it may be useful to know exactly what's going on behind the scenes when you run a text filter from the MacPerl menu. The "magic" that allows a script written as a Unix command-line filter to be used in Alpha is achieved by rewriting that script on the fly before passing it on to MacPerl. Basically, the script is modified to take standard input from a file called STDIN, created in the MacPerl folder, and send standard output to another file called STDOUT. This just involves adding a handful of lines at the beginning of the script, to open and select those files, and a few more lines at the end to close them. If there's a #! line in the script, then the new commands are added after that line; if there was no #! line in the first place, one is added anyway in case your MacPerl preferences are set up to require it. So, when you call a text filter, the input text is first copied to the STDIN file. Then, the script you selected is read in by Alpha, modified, and written to another file, SCRIPT, also in the MacPerl folder. Next, MacPerl is sent a "DoScript" AppleEvent directing it to run the script in the SCRIPT file. When it's finished, the output text in the STDOUT file is read back in by Alpha and written out appropriately (in place of the input text or into a new window.) You should never have to worry about the STDIN, STDOUT, and SCRIPT files. However, if something funny happens, you can see exactly what input text was used and what the modified script looked like by examining the STDIN and SCRIPT files. These, together with the STDOUT file, can be opened using the "Open Special" submenu of the MacPerl menu. Also, note that if you get an error message from MacPerl, the line numbers refered to are those of the SCRIPT file, and not of the original script. Bugs, etc. ---------- Comments and suggestions regarding this package are always welcome. If there's something that bothers you, or some additional capability that you'd like to see, let me know and I'll see what I can do. Bug reports and any other comments should be directed to Tom Pollard e-mail: pollard@chem.columbia.edu snail-mail: 544 W 114th St #2R New York, NY 10025 USA Version History --------------- This package was written by Tom Pollard <pollard@chem.columbia.edu> and Martijn Koster <m.koster@nexor.co.uk> 1.5 9/94 - MacPerl menu rearranged somewhat. Explicit "Get Output Window" command added to menu. Reading "#!" line for args is incompatible w/ standard, so it's been dropped. Only scan the first 40 output lines for error messages (faster) "wrapFilterScript" no longer opens STDIN Text filters may now use command-line args STDIN for text filters passed as explicit cmd-line arg 1.4 9/94 - The "#!" line of every script is read for command-line args. "PromptForArgs" menu flag added. "perlCmdlineArgs" modeVar holds default command-line args. Scripts are sent using custom "perlDoScript2" proc. 1.3 9/94 - When any script generates a compilation error, the file containing the script is brought up with the offending line highlighted; all error output is also written to a "Perl Error Messages" window. 'repeatLastFilter' runs again the last text-filter script used. 'perlLastFilter' modeVar holds pathname of last filter. Menu flags now mirrored as modeVars, so they can be saved and restored between sessions. Minor bug fixes. 1.2 8/94 - 'retrieveOutput' and 'autoSwitch' flags added. 'openInMacperl' added. MacPerl output window now closed before new scripts are sent. Filters now abort if there are compilation errors, and MacPerl diagnostic output retrieved and displayed. 1.1 8/94 - 'quitMacperl' added. perl-mode file-marking updated for Alpha 5.90 Simplified installation via 'loadMacperl'(Pete Keleher). 1.0 7/94 - perl-mode setup updated for Alpha 5.85: keyword colorization supported custom file-marking added #! lines in filter scripts now handled correctly Workarounds installed for AppleEvent problem in MacPerl 4.1.3 0.9 3/94 - perl-mode stuff added, and highlighted 'Perl commands' file (man page) prepared minor bug fixes, too 0.8 3/94 - flags are now check-marked 0.7 3/94 - nested Text Filters folder now supported menu format modified somewhat 0.6 3/94 - 'applyToBuffer' flag added scripts in Alpha buffers can now be used as filters 0.5 2/94 - 'filters', 'open special' submenu added 'overwrite' flag added 0.2 1/94 - menu support added (MK) 'execute selection', 'execute buffer' commands added 0.1 9/93 - text filter functionality created (WTP) MacPerl application ------------------- If you don't already have MacPerl, it's available by anonymous ftp from the umich archive site, mac.archive.umich.edu [141.211.165.34] mac/development/languages and its mirrors. Also, MacPerl's home site is ftp.switch.ch [130.59.1.40] software/mac/src/mpw_c MacPerl was written (ported to the Mac) by Matthias Neeracher <neeri@iis.ee.ethz.ch> , and Tim Endres <time@ice.com>. ---------------------------------------------------------------------------