Perl Mode Help

Name:	Perl Mode
Version:	3.7
Last update:	2019-11-27 14:13:03

Introduction
Installation
Perl Mode
Perl Menu
Running Scripts
Text Filters
- Applying a Text Filter
- Perl Scripts Menus
Version History
Known problems
License and Disclaimer

Introduction

The Perl mode provides facilities for editing Perl language scripts. When it is active, a new menu represented by a camel icon is inserted in the menu bar. The Perl menu is written to allow Alpha to act as a front end for the perl command line and to make it possible to attach Perl scripts to Alpha. It provides a number of features designed to make the use and development of Perl scripts on the Mac more convenient. These are detailed in the rest of this document, but here's a quick overview:
Editing Perl scripts...

Perl keywords and special variables are colorized in Perl mode.
Keyword completion is supported.
The Perl 5 man pages are available as an on-line reference.
The man pages can be referenced by shift-command-double-clicking a highlighted Perl keyword or special variable in your Perl script.
Source files mentioned in require statements can be opened by shift-command-double-clicking as well.

Running Perl Scripts...

Perl scripts can be run directly from Alpha - a script can be a text window in Alpha, a highlighted selection from a window, or a disk file.
Perl scripts (referred to as filters) that read from standard input and write to standard output may be used to process text in Alpha's text windows.
When a script fails, the error messages are displayed and the script is brought up with the line that caused the error highlighted.

For more general information about Perl, go to https://www.perl.com/.

Installation

No special installation procedure is required before using this package. However, there are a couple of things that you may want to do to configure preferences for your particular machine.

Perl application and library

Alpha needs to know where to find your local perl command line in order to execute the scripts, and will automatically prompt you to locate it if it doesn't find it. You can always check and/or change the path that Alpha uses by selecting the menu item Alpha ↣ Global Setup ↣ Helper Applications and then find the execPerl service. Note that this service will appear only if the Perl mode has already been loaded (this happens the first time you open a Perl script).
When opening required source files via the Shift-Command-Double-Click mechanism, Alpha will always look in the lib folder in the local Perl application directory. To have Alpha look for library files elsewhere, you can specify an additional personal library folder, using the Perl Lib Folder preference in Mode Setup dialog.
You can also specify Perl mode search paths. For Search Paths to be available, you must first enable the Include Perl Path Menu preference. See the section on Text Filters below.

Text Filters Setup

The Perl menu contains a hierarchical submenu of preattached scripts to be used as text filters. A sample collection of such scripts is distributed with Alpha. You can specify your own folder of scripts using Perl Lib Folder preference in the Mode Setup dialog.
If you want to use Perl scripts to process Alpha document windows (see the Text Filters section), you'll need to arrange that the Perl menu is a global feature. Use the Alpha ↣ Global Setup ↣ Menus dialog to do so. Or, you could make the Perl menu a mode specific feature for Text (or any other) mode. Click here to open the Menus Preferences dialog.

Perl Preferences

There are a handful of flags you can set to modify the way Alpha and your local Perl application interact while running Perl scripts. These can be set from either the Perl menu or the Mode Setup dialog. They're described in more detail below in the Perl Menu section.
Click here to open the Perl Mode Preferences.

Perl Mode

Perl mode is entered automatically whenever you open a file with a .pl, .ph or .pm suffix; you can also invoke it explicitly using the Modes popup in the toolbar of the document windows. A Perl Example syntax file is available for exploring some of the mode's features and the Perl menu.
Perl mode offers a number of features supporting the editing and execution of Perl scripts. They are described in the next sections.

Basic language support

Perl keywords and special variables appear in blue in Perl mode.
A single line or a selected block of lines may be commented out by using the Comment Line command under the Text menu. Lines are uncommented using Uncomment Line, which appears in the Text menu when the option key is held down.
Alpha will create an index of all subroutines in your Perl script when you select Mark File from the Marks popup (📖) of the document window.
When you open a Perl script that hasn't already been marked, an index is automatically created if the Auto Mark preference is set.

Shift-Command-Double-Clicking

A simple form of hypertext help is invoked by Double-Clicking on certain pieces of text while pressing the Command (⌘) modifier:

The online man page can be referenced by Shift-Command-Double-Clicking a highlighted Perl keyword or special variable in your Perl script.
Most of the clickable keywords and variables will be colored blue. Special variables containing alphabetic characters, .e.g. @ARGV, are also clickable.
After you have clicked on a recognized keyword, Alpha displays the relevant manual page. If the Click Searches On-line preference is set, then a manual page url will be sent to your local browser instead.
Shift-Command-double-clicking on the name of the source file in a require statement will cause that file to be opened by Alpha.
Alpha will look for the file in the current script's folder, in your local library folder, in the local Perl application's lib folder, and in any folder set as a Perl mode search path (in that order). The local lib folder may be specified interactively by the user using the Mode Setup dialog (see the section on Installation above).

Mode Preferences

A more complete set of Perl option flags are also settable through the menu item Alpha ↣ Mode Setup ↣ Mode Preferences… menu item (while you're in Perl mode). Most of these are explained below in the Perl Mode Options section.
The Perl Cmdline Args preference contains the last command-line options supplied. Note that this is only passed to scripts when the Prompt for Args option is active.

Perl Menu

Alpha's Perl menu allows a number of actions that include interaction with a local Perl command line, or aids to write Perl scripts. These include ...

Running Perl Scripts

Run The Buffer: Execute the current text window as a Perl script.
Save And Run: Save the current window and run the saved file as a Perl script.
Run The Selection: Execute the selected text as a Perl script.
Run A File: Run a selected disk file as a Perl script.
Collect Identifiers: Searches the current window to find any string starting with $, @, % or *, and any string embedded in <>. Results are put into the OS clipboard.
This is useful when you want to check for spelling mistakes in identifiers. Also, provides a handy way to make all the identifiers available to another file so you can use the completion / expansion routines. Just paste them in whatever file you like.

Applying Text Filter Scripts

Select File As Filter: Select a file to use as the text filter script.
Select Buffer As Filter: Select one of the open text windows to use as the text filter script.
Repeat Last Filter: Run again the last filter that was used. If the contents of the file or buffer has changed, the new script is run.
Perl Text Filters: This is a hierarchical menu of preattached scripts to use as text filters. When a script is selected from this menu, it is immediately applied to the current text window.

The menu is built from the contents of a user-selected folder. The folder is chosen using the Perl Text Filters Folder preference in the Alpha ↣ Mode Setup ↣ Mode Preferences… dialog. The default location is a set of filters included with the AlphaTcl library.
Additional submenus containing scripts in user-defined folders can also be added to the main Perl menu. See the section on Text Filters below for more information.

Perl Filter Options

Flags controlling the behavior of text filters mechanism.

Apply To Buffer: Apply the filter to the entire current text window; 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.
Run Without Confirmation: By default, you will be prompted to continue whenever you select a script to be run. To bypass this dialog, check this preference.
Include Local Lib Menu: Include an additional Perl Filters submenu, based upon scripts found in the folder specified by the Perl Lib Folder preference. See the section below on Text Filters for more information.
Include Perl Path Menu: Include an additional Perl Filters submenu, based upon scripts found in the folders specified by the Perl Search Paths preference. Selecting this menu item will add additional Filter Options menu items for manipulating Perl mode search paths. See the section below on Text Filters for more information.
Last Filter Used: Displays the name of the last Text Filter applied.
Rebuild Filter Menu: Reconstruct the Perl Filters menu(s) based upon the various preferences. Shouldn't be necessary, since changing the preferences will usually automatically rebuild these menus.

Perl Mode Options

This menu allows you to change the values of various flag preferences that control Alpha's behavior when executing ordinary Perl scripts (not text filters).

Prompt For Args

Have Alpha prompt you for command-line arguments to be passed to the script.

Retrieve Output

Automatically retrieve any output written by the Perl command line and display it in a new window under Alpha. If the mode variable Recycle Output is set, the previous output window is overwritten.

Structural Marks

To recognize strings embedded in

#### some text ####

as section dividers, turn this preference on. Note that if 'some text' is just a string of dashes, as in

#### ---- ####

an actual divider will be placed in the Marks popup menu. If this preference is not turned on, then all marks will be presented alphabetically, similar to using the 'Functions' popup.

Click Searches On-line

When shift-command-double-clicking, try to open an on-line manual page for a command if one exists.

Perl Insertions

This submenu contains a few useful items for editing Perl scripts.

Add Remove @

Either adds @ to or removes @ from the beginning of the word in which the cursor currently resides.

Add Remove $

Either adds $ to or removes $ from the beginning of the word in which the cursor currently resides.

Insert Divider

Adds this text:

##### | #####

at the beginning of the current line. This string is recognized as a special type of file mark.

New Comment

Inserts a 'paragraph-style' comment at the beginning of the current command, as determined by indentation.

Edit Comment

Allows the comment inserted by the 'New Comment' menu item to be customized. Simply type a template for a new comment, highlight, and then select this menu item. To enter • template stops (known as bullets), press Option-# -- be sure to include TWO bullets for every stop.

Perl Navigation

Navigation in Perl mode is determined by indentation. The start of any command is indicated by a non-comment character in column 1 of any row. The command continues until the next non-comment character appears in col 1.

Next Command: Advance the cursor to the next command. If any text is highlighted, the selection will be extended to the next command. Also bound to the arrow keys when 'control' and 'shift' are pressed at the same time.
Prev Command: Back up the cursor to the previous command. If any text is highlighted, the selection will be extended to the start of the previous command. Also bound to the arrow keys when 'control' and 'shift' are pressed at the same time.
Select Command: Highlight the entire command in which the cursor currently resides.
Reformat Command: Select the entire command (if there is no current selection), and properly indent it. At the end of this procedure the cursor is advanced to the next command.

Perl Help

Perl Home Page: Sends the Perl Home Page url preference to your local browser.
Perl Mode Help: Opens this file.
Perl 5 Manual - local: Opens a Perl manual page. The command displays a listpick dialog in which you can select the topic you are insterested in.
Perl 5 Manual - www: Sends the Perl Help url preference to your local browser.
Local Command Help: Opens a dialog asking for a command for which you would like a local manual page.
WWW Command Help: Opens a dialog asking for a command for which you would like a manual page found on the Web. If an on-line manual page exists, the url for it will be sent to your local browser.

Running Scripts

Running scripts using the Perl menu is pretty straightforward. You can send the current selection, the entire current buffer, or a disk file to Perl for execution; the result will be the same as if you ran the script from the perl command line in a Terminal window. Here are listed some important points to remember when running Perl scripts using the Perl menu.

Input and Output

To get the output from your script, select the Retrieve Output flag under Perl Mode Options, this will cause Alpha to copy any output from perl into Alpha after your script has completed.

Command-line Args

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 Perl Cmdline Args, and become the default arguments the next time the script is executed and the dialog is invoked.

Error Messages

If the script fails for some reason, Alpha will read the error messages returned by Perl and write them back into a new text window, called * Perl Errors *.

Text Filters

Perl is, among other things, a powerful tool for extracting and rewriting 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.
The Perl 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 document window in Alpha 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 yet another Alpha text window.

Applying a Text Filter

The procedure for using Perl text filters in Alpha is simple:

Bring the text window you want to operate on to the front and select (highlight) the text that will be the input to the script.
- If the Apply To Buffer option is selected, then the entire text window will be used as input and any text selection is ignored.
- Only complete lines are used as input. The text used will be extended to include all of the lines on which the selected text lies.
Select a Perl script using one of the commands, Select Buffer As Filter, Select File As Filter or Repeat Last Filter from the Perl menu, or by choosing one of the scripts listed in the Text Filters submenu.
- You can see the name of the last script used by examining the variable Perl Last Filter in the Mode Setup dialog. See also the menu item Last Filter Used in the Perl Filter Options submenu. This is the script that will be used if you use Repeat Last Filter.
- If the Prompt For Args option has been selected, you'll be given a dialog box to type in the command-line arguments for the script.
The output of the script is written back out, either in the place of the input text (if the Overwrite Selection option is selected) or into a new text window.
- 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 halts on an error, the filter operation is aborted and any error messages are displayed in a new window.

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: for instance, 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. See also Alpha's global Filters Menu package for this kind of operations (Filters Menu Help).

Perl Scripts Menus

Frequently used text filter scripts can be conveniently accessed in one of several ways, each of which has a Perl Filters/Scripts menu associated with it. When the Perl menu is first created, it looks in various folders and builds a hierarchical submenu from the names of the scripts that it finds. If the Run Without Prompting preference is set, selecting any of these scripts will IMMEDIATELY run them, without any explicit prompting, so please use the items with care if you are not familiar with the script being called.
Tip: holding down any modifier key while selecting the menu item will open the script in Alpha for previewing or editing.

Perl Text Filters

The first collection is a sampling of very useful : Perl scripts distributed with Alpha. If the Perl Text Filters Path preference has not been modified, the Perl Text Filters submenu contains all of these scripts -- selecting any of them will automatically run the script.
The Text Munging scripts in this collection (shuffle, sort lines, travesty, and wordcount) were taken from the Camel book (Programming Perl).
The s2p script is Tom Pollard's 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 one would typically care about (From:, Date:, etc..).
CC To BibTeX is a script Tom uses that takes listings from the online Current Contents database and rewrites them as BibTeX database entries. To try it out, copy the sample Current Contents citation below in a document window, select (highlight) it 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.

Perl Lib Scripts

The second collection is associated with the preference named Perl Lib Folder. Use the Mode Setup dialog to set or change this preference. To include this menu, you must check the Include Lib Filters Menu preference, available as a toggleable item in the Perl Filters Options menu. Unlike the Perl Text Filters menu, only files with the Perl mode file extensions (as determined by Alpha's suffixMappings) will be included in the menu.

Perl Path Scripts

The third location for scripts can contain multiple folders associated with Perl mode using the package searchPaths. Note that it is not necessary to activate the Search Paths feature in order to create such a menu, simply check the Include Path Filters Menu preference, available as a toggleable item in the Perl Filters Options menu.
Once the menu has been included, use the Perl Filter Options > Paths menu items to view, add, or remove Perl mode search paths. Note that the frontmost window must be in Perl mode in order to set these paths. Unlike the Perl Text Filters menu, only files with the Perl mode file extensions (as determined by Alpha's suffixMappings) will be included in the menu.

Version History

See the perlVersionHistory.tcl file for the latest changes.
This document has been placed in the public domain.

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.
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 us know and we'll see what we can do.

License and Disclaimer

Original Author: Tom Pollard.
Co-Authors: Dan Herron, David Schooley, Vince Darley, Martijn Koster, Rob Calhoun, Craig Barton Upright, Bernard Desgraupes.
Copyright (c) 1994-2019, the Alpha Community.
All rights reserved.
The Perl Mode package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the Alpha Community nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE ALPHA COMMUNITY BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.