311

Chapter 22:

• What Is MPW?
• Using Perl With MPW
• Install The MPW Tool
• Examine The Folder
• Complete The Installation
• Try Out The MPW Tool
• Special Features Of The MPW Tool

MPW Perl

Even workhouses have their aristocracy

- English proverb

This chapter describes the installation of the MacPerl MPW tool, then pro-
vides a brief "get acquainted" walkthrough. It also describes any peculiar-
ities of using Perl under MPW which are not present in the MacPerl stand-
alone application. If you already have a working copy of MPW Perl on your
disk, you may want to skip this chapter. Or, you may wish to read the sec-
tion on features and differences, in case you might see something new.

What Is MPW?

MPW, the Macintosh Programmer's Workshop, is Apple's command line
interpreter for the Macintosh. It has been popular with Macintosh devel-
opers for years, but has only recently become available to the general pub-
lic. The MPW program is referred to as the MPW shell.

MPW includes a built-in text editor with (its own interpretation of) regular
expression processing, a procedure for writing scripts in the MPW command
language, environment variables, and a set of MPW "tools" (specialized
commands, written in languages such as C). MPW Perl is one such tool.

MPW uses windows, known as worksheets, which are always mapped to
files; writing to any open worksheet is treated exactly as writing to a TEXT
file. Unlike other shell-based environments, such as Unix, the MPW shell
isthe editor; the MPW editor is the shell. Commands are executed by
selecting the text to be executed in any open worksheet and pressing ENTER
on the keyboard.

Note that ENTERand RETURNare distinct in MPW. MPW treats RETURN
the same way any text editor or word processor would; it's just a way to get
to the next line. In fact, each MPW Worksheet is simply a text editor win-
dow. That is, until you select one or more lines of text and press ENTER.
Then, voila!, MPW is also a command line processor (a shell).¹For those
who don't like to reach so far (or don't have an ENTER key), cmd-RETURN
is synonymous with ENTER.

MPW's interaction mode, which draws heavily from both Smalltalk and
Unix, can be a little disconcerting at first. You'll soon get used to the power
and flexibility of the MPW editor, however. Let's say that you're typing
along, editing a Perl script, and you can't remember the exact name of a file
you want to open. Simply execute (with ENTER) the filescommand (right
there in the middle of your editor session), then select and delete the extra-
neous filenames, leaving only the name you wanted. The filenames are even
pre-quoted by MPW, as necessary, to protect spaces!

When MPW is acting like an editor, you will see the words MPW Shellin a
little box in the upper left corner of the window's toolbar. When MPW is
executing a program, the contents of this box will change to display the
name of the active program (e.g., Perl). If the current Worksheet window
ever seems to be ignoring you, check the contents of this "current process"
box; chances are, the MPW shell is busy running a program.

The MPW editor is programmer oriented, with provisions for highlighting
reserved words for various languages (Perl included), automatic indenting
after a return, and selection of blocked code by double clicking on a delim-
iter. If you select the text of a filename, an item in the File menu reads
"open selection" and will open that file. You can even add menu items to
execute your own scripts!

Until recently, MPW was available only to Apple's registered developers,
but Apple has now made MPW freely available to anyone. It may be down-
loaded from Apple's Developer World site, devworld.apple.com (under
Developer Tools), or by direct FTP from ftp://ftp.apple.com by follow-
ing the path:

/devworld/Tool_Chest/Core_Mac_OS_Tools/MPW_etc.

1_{If you're only executing one line, you don't actually have to select it. Just make sure}
that the text insertion character, |, is positioned on the appropriate line.

Using Perl With MPW

When you use MPW with Perl, you'll be using the MPW perltool, not the
MacPerl standalone application. MPW tools are binary executables which
work only from the MPW command line. If you try to double-click an MPW
tool in the Finder, you will simply launch MPW. MPW tools have the type
MPSTand the creator 'MPS '(note the trailing space!).

Tools are invoked with an MPW command which starts with the name of
the tool (e.g., perl). The name of the tool may be specified as a full path-
name, a relative pathname, or simply by the tool's name, in which case
MPW will search for the tool in the directories listed in the global vari-
able {Commands}. The command line can also include additional arguments
which are separated by spaces.

Note:Because Macintosh filenames may also contain spaces, some quot-
ing may be needed. Macintosh filenames may also contain quote charac-
ters, so the quoting can get fancy.

A file which contains MPW commands is called a script. Scripts are always
of type TEXT. A script can be executed by giving its filename on the MPW
command line. Arguments can be passed and the script can contain looping
commands, including recursive invocations of itself.

You can create scripts using the MPW editor or create them with another
editor and run them under MPW. MPW Perl scripts may contain only Perl
code, or a combination of other MPW shell commands and Perl code (in
which case they are shell scripts, not Perl scripts). In the latter case, the
scripts can only be executed by MPW, not by the standalone MacPerl app.

If you write an MPW Perl script, it is likely that you will also write an
MPW script to invoke it. In many cases, you may find that an MPW script
can handle system-level tasks more directly than can a MacPerl script.
Doing the top-level script in Perl or in MPW is a personal preference.

Perl scripts must be saved as text and run from the MPW command line using
the perltool. You can't save them as droplets or Runtime programs, and
you can't pass arguments from the MPW command line to standalone
MacPerl droplets or Runtime versions.

Features

MPW provides a very good code editor. The editor displays Perl reserved
words in a highlighted color (reserved words in a comment are also high-
lighted; sigh). Double-clicking on a variety of bracketing characters (e.g.,
}{][)() selects the text all the way down (or up) to the matching bracket.

MPW handles file name generation quite well. Unfortunately, MPW's file-
name generation and regular expressions use yet another new set of symbols.
The "option" characters of the Macintosh keyboard are used for characters
such as the escape character, , and the "wild card" character, . It can be a
challenge to keep the regular expressions for Perl and MPW separate.

The MPW commando interface for formatting an MPW command or the call
to a tool is pretty good. It would be possible to create a commando resource
for Perl, but not so easy for a finished Perl script.

The SET and EXPORT commands in MPW allow variable use. Values are
taken to be text, except that simple arithmetic is allowed in looping con-
structs. Several variables are assigned by MPW itself. The {}construct is
used in command lines to identify environment variables. {Worksheet}is
the full pathname of the current worksheet window, which is always open.
{Active}is the name of the active window.

When MPW is started up, several variables are set in a script named MPW:
Startup. You can and should set up your own variables (e.g., to point to reg-
ularly used MacPerl items). Depending on your MPW version (see the main
Startup script), you may be able to create files named UserStartup*xxx, or
place items in the Startup Itemsfolder for execution.

Note:Exported variables only apply to the MPW environment and will
disappear when MPW is quit. If you're familiar with accessing CGI
variables as exported environment variables in Unix, this won't work
on the Macintosh!

Install The MPW Tool

If you have downloaded a recent copy of the MPW tool from an Internet FTP
or WWW site, it will generally be compressed and encoded (e.g., with
StuffIt(from Aladdin Systems) and BinHex). In this case, you will need to
decode and uncompress the archive before continuing. StuffIt Expander, an

expansion utility, is available on our CD-ROM, from many Macintosh
archive sites, or from Aladdin Systems at www.aladdinsys.com.

The MPW tool on the enclosed CD-ROM has already been uncompressed
and decoded into a double-clickable Installer application. As when
installing the standalone application, you will need to launch the Installer
and review the notes for any important last-minute notes, then choose the
installation location.

Note: Be sure to install the MPW tool on the same disk as the MacPerl
application.The Installation process for the MPW tool has two parts.
In Part 1, you will run the Installer application. The Installer will
install the MPW tool, along with an MPW-based configuration script
which you must then run (as Part 2) to complete the installation.

If you have previously installed MPW and the MacPerl MPW tool, be
sure to look these scripts over carefully before you execute them, to
ensure that nothing they do will conflict with any startup scripts or
configurations you have already put in place.

Steps to Install the MPW tool (Part 1)

1. Double-click the Installer application to start the installation. Be sure
   to review the instructions in the initial screen for any important last-
   minute notes. Print or save these notes, then click Continue.

2. Choose the same volume and folder where you installed the MacPerl
   app, then click Install. (The Read Me...button will take you back to the
   notes you reviewed in step 1.)

3. The Installer will install the MacPerl MPW tool along with an MPW-
   based configuration and install script which you must run to complete
   the installation.

4. When the Installer completes successfully, choose Quit. You do not need
   to restart your Macintosh.

Examine The Folder

The MPW tool Installer places some new (MPW-specific) files into the
MacPerl ƒfolder (created previously by the MacPerl app installation).
Open the folder, if need be, and examine the contents again. (Scroll to the
bottom if you don't see the new files right away).

Before you continue, take a look at the files that were installed:

• The perl tool is what you will be using when you run Perl under MPW.

• The README files, README.MAC and README, are identical to
  those installed with the same version of the MacPerl app. They con-
  tain release notes, information on known problems, special comments
  about the current release, etc. If you have not already done so, be sure to
  look at the README files. The Perl Artistic License is also duplicated
  here in the file Artistic.

• The x2p folder contains two related MPW programs that you may find
  useful when using MacPerl. find2perl is an MPW script that will con-
  vert an MPW findcommand to equivalent Perl code. a2p is an MPW
  tool for converting programs written in Awk to Perl.

• Install.MPW_Perl is an MPW script which we will use in a few
  moments to complete the installation process.

• Uninstall.MPW_Perl is an MPW script which you may run later, if
  you ever decide to uninstall the MacPerl MPW tool.

Complete The Installation

In order to complete the MPW tool installation, you will need to launch
MPW, then run the Install.MPW_Perlscript. The script will create a config-
uration file, which you may edit as needed. Run the script a second time,
processing the configuration file and completing the installation process.

If you have not previously installed MPW, you must do so now before you
can continue with the installation of the MacPerl tool. Also, if you do not
yet know how to launch and run MPW, take some time to work with MPW
before completing the installation of the MacPerl tool. Come back to this
part of the chapter after you have learned more abut MPW.

Steps to Install the MacPerl MPW tool

1. Launch MPW.

2. Change the directory to the MacPerl ƒ folder. Use the directory
   command or the Set Directory...menu item.

3. Execute the Install.MPW_Perl command. This will create and open a
   configuration file named Config.MPW_Perl.

4. Examine the configuration file and make any changes you require. Be
   sure to read the comments at the top of the file before making any modi-
   fications. The configuration file sets a number of useful variables. In
   most cases, the defalts should be acceptible. Save any changes.

5. Execute Install.MPW_Perl again. A set of commands will be printed
   in the MPW Shell worksheet window.

6. To complete the configuration step, select and execute (i.e., enter) the
   commands which are written to the worksheet window. These com-
   mands are set up as two parts. The first part installs the appropriate
   tools and scripts. The second part creates a startup file for Perl. If you
   have your own startup file, you may merge the contents of this part into
   it instead. You will probably want to execute this startup file, or quit
   and relaunch MPW, to make sure all the settings are in effect.

Try Out The MPW Tool

Locate the file, myscript, that you created with the MacPerl app. You
may have to use the Set Directory ... menu item to navigate to the folder
containing the script. If you no longer have this file, create and save a new
MPW worksheet named myscript, containing the statement:

print 'hello';

Then, in your MPW shell window, enter the command:

perl myscript

You should see the result:

hello

Because we configured MPW in the previous step, MPW is able to find and
run the perltool.

Options, switches, and flags

Like many MPW tools, Perl may be run with any of several options (known
also as switchesor flags). Options begin with a dash, -, and usually consist
of a single letter or a letter followed by a word, such as the name of a direc-

tory. Use the -hoption to list all available options as well as an abbrevi-
ated usage statement for Perl.

perl -h
Usage: perl [switches] [--] [programfile] [arguments]
-0[octal] specify record separator ...
-aautosplit mode with -n or -p ...

One-liners

In your MPW shell window, enter the following command:

perl -e 'print "hello";'

You should see the same result printed to the window. The -eoption tells
perlto execute the following string as Perl code. The -emust immediately
precede the string containing Perl commands; there may be no other Perl
switches in between.

You can also use -eto execute a series of lines, i.e. a multi-line script, from
the command line.

perl -e '
print("hello\n");
print("goodbye");
'

Be sure to include the escape character before the return on each line in
the script or it will fail to execute. Also, be sure to select allof the lines
before pressing ENTER.

Making your script executable

To make your script executable directly (i.e., allowing you to enter the
command, myscript, rather than the command, perl myscript), add
the following line of code just above your Perl code:

Perl -Sx "{0}" {"Parameters"}; Exit

Actually, oher MPW statements may come before or after the Perl -
Sx "{0}"statement. Just make sure that there is an MPW Exitjust before

the perl code begins and that the first line of the perl portion is a #!perl
statement.²

Special Features Of The MPW Tool

Because MPW is "command-line" oriented, MPW can pass command line
switches (options) and values as well as filenames.

perl -lw myscript

In contrast, the standalone MacPerl application must have any command
line switches specified inside the script, as:

#!perl -lw

Various shell variables can also be defined and will be expanded by MPW
before passing a command line to Perl.

MPW scripts can be passed to ToolServerfor execution in background or on a
networked machine. In addition, the presence of ToolServerallows the
system()function and backquoted commands to work under MacPerl.³

The MPW shell understands the concept of a working directory better than
the Finder does. Using MPW, it's easy to set the current directory, then run
a MacPerl script, instead of encoding the directory path into the script.

The MPW shell also understands about standard input, standard output,
and standard error. These default to the MPW worksheet from which a
command is entered but they can be changed by providing a filename, pre-
ceded by the appropriate redirectioncharacter, on the command line.

>myfile
>>myfile
<myfile
myfile
myfile

output replaces contents ofmyfile
output is appended tomyfile
input is taken frommyfile
error output replaces contents ofmyfile
error output is appended tomyfile

2_{Or #!/usr/local/bin/perlor whatever pathname is required if you intend to also}
run the script under Unix.
3_{If ToolServeris present, system()and backquotes will work under the standalone}
MacPerl app as well as the MacPerl MPW tool. However, you will still need MPW in
order for ToolServerto have any (MPW) tools to serve!

The command line

The MacPerl tool has its own arguments so the command line is somewhat
unusual:

"{perlpath}" [perl switches] "{script}" arg0 arg1 ...

where:

• {perlpath}is the path to the Perl tool; you may have set this up in
  your MPW:Startup file. The path may need to be quoted if there is any
  possibility of an intermediate directory name containing a space. If the
  tool has been installed in a folder on your standard path, you will only
  need to use the name perl.

• [perl switches]are optional command line flags such as -e, -w, or
  -l. Each must begin with a dash, -. If -eis used, it must be followed by
  a string containing Perl code to be executed.

• {script}is the path to your Perl source code. This name must not begin
  with a dash, even though -is otherwise legal in a filename. If you use
  the -eswitch, the code may be placed "in line" within a quoted string.

• arg0 arg1 ...are the arguments to your Perl script after it starts
  executing. These could be filenames or variables which have been SET
  in preceding lines of an MPW script.

Note that the normal MPW, and Unix, convention is not followed for count-
ing arguments. Arg[0]is the first argument, not the pathname of the Perl
script, as you might expect. Consistent with other counting in Perl, the argu-
ment count is the cardinal of the last argument passed (one less than the
number of arguments).

Reading Perl Help Files

The Mac port of Shuck is small and easily coexists with MPW (even on
small Macs without virtual memory). A standalone Macintosh application
can be launched from MPW by simply giving its path on the command line.
The MPW installation script defines the variable {MacPerl}as the path
to the MacPerl ƒfolder (the location of the Shuckapplication). Argu-
ments on the command line specify files to be opened.

"{MacPerl}"Shuck "{MACPERL}"lib:Mac:Files.pm

The above command will execute the Shuck application and present the
help information for Files.pm. Alternatively, you could type and select the
text Mac::Files, then select the Perl Helpitem from the Findmenu.⁴

If you prefer not to specify "{MacPerl}" every time (or if you did not run
the installation script :-), you may place a copy (duplicate)of the Shuck
application into your MPW Tools folder (or another location on your com-
mand path, e.g.:⁵

directory "{MPW}User Commands"
Duplicate -y "HD:MacPerl ƒ:Shuck" :Shuck

Or, just use the Finder to make an alias to Shuckin an appropriate folder. If
you set the creator ID (signature) of all *.pm modules to that of Shuck, you
will be able to invoke Shuck by double clicking any of them in the Finder.

directory "HD:MacPerl ƒ:lib:"
setfile .pm -c uck

ToolServer and system()

ToolServerallows large processing jobs (e.g., compilations) to be split up
among several networked Macs. A running instance of MPW can send an
AppleEvent (i.e, the filename of an MPW script to be executed) to a Tool-
Serverapplication running on a remote machine. ToolServerthen operates
in background, returning an AppleEvent when it is finished.

With ToolServerinstalled, you can use Perl's system()function, as well as
the command input (i.e., backtick) operator, to run MPW tools from inside
MacPerl. For example, the following lines of MacPerl code will print a
count of the lines and characters in the MPW Startupfile .⁶

$file = '{MPW}Startup';
system("Count $file");

4_{This menu item is added by the perl startup file which was created when we did the}
configuration. It may not appear if you did not execute the startup file (or relaunch
MPW) following the configuration step.
5_{Be sure to replace the name of the disk volume, e.g. HD, in these examples with the}
correct name for your system!
6_{This is not the most efficient way to do this particular exercise, of course; an MPW}
script would be much faster. The Perl code does, however, provide proof of concept.

ToolServerhas its own startup script, which should be modified to define
any aliases and environment variables that Perl will need. ToolServeralso
has its own unique creator ID, MPSX, which can be assigned to a script. Then,
when a script is double clicked under the Finder, it will be sent to the Tool-
Serverapplication. The functionality is somewhat similar to a standalone
MacPerl droplet.

A Framework for a "Combination" Script

The following example illustrates how a perlscript can be embedded
within a "regular" MPW shell script. Although the example itself doesn't
do much of interest (although it does run), it provides a framework for a
"combination" MPW shell and MacPerl script. Note that the perlportion
of this example returns a non-zero exit status, which is caught and dealt
with by the MPW shell portion.

set oExit
set exit 0

"{exit}"

# save the exit value
# set to 0 so script won't
# abort after perl call

echo "# Do the pre-perl stuff here"

Perl -Sx "{0}"
set myStat "{Status}"

# call the perl portion
# save off the status

if ( "{myStat}" )
echo "# Do the non-zero status stuff here"
Else
echo "# Do the zero status stuff here"
End

set exit "{oExit}"# restore the exit value
Exit {myStat}# MPW shouldn't attempt to
# process past this point
-- it's perl from here on out

#!perl
print( "Start the perl script\n" );
print( "Do my perl processing\n" );
print( "Exit the script\n" );
exit 1;

Accessing Command Line Arguments

Internally, the arguments for a Perl script are provided in the array @ARGV.
The variable $#ARGVprovides the argument count (that is, the cardinal
number assigned to the last argument). The contents of @ARGVmay depend
on whether you used perlto run your command or made a directly execut-
able script. That is, arguments to the scriptbecome part of @ARGV, while
arguments to perldo not.

The following example illustrates this behavior. Suppose you have a
script, myscript, which contains the following loop:

foreach $arg (@ARGV) { print "$arg\n"; }

If you execute the script using perlas follows

perl -w myscript hello

it will print

hello

However, if you make the script directly executable by adding

Perl -Sx "{0}" {"Parameters"}; Exit

at the top, then execute it directly as

myscript -w hello

it will print

-w
hello

Returning a Value to MPW

An MPW script sometimes needs a result from a tool to indicate successful
completion. The {Status}variable is normally set to zero to indicate a
good result and to non-zero (perhaps a specific error code) to indicate fail-
ure.⁷Your MPW script can examine {Status}and cause itself to exit(if a
non-zero value is detected) before it does something regrettable.

7_{This is the opposite of the way return values work within Perl, but is consistent with}
other shells and programs such as those found under Unix.

If an error occurs during compilation, Perl will return non-zero in {Status}.
On normal completion of a script, {Status}will contain the value returned
by exit(). If the script did not call exit(), the return value is assumed to
be 0. Calling exit()with a string also results in {Status}being set to 0.

You may want to set the MPW variable, Exit, to 0within any MPW script
that calls or contains an embedded Perl script. This will prevent the MPW
script from quitting if the Perl script returns a non-zero status.

Accessing MPW environment variables from within Perl

The special Perl hash %ENVstores environment variables.⁸This hash is
filled from all existing environment variables in MPW at the time of execu-
tion of the Perl script. Thus, for instance, $ENV{Worksheet}is the full
pathname of the MPW worksheet. Environment variable names are not case
sensitive in MPW perl. Try:

perl -e 'foreach $key (keys(%ENV)) { ð
print("$key\t$ENV{$key}\n"); ð
}'

MacPerl::FAccess

When called from the MPW perltool, the MacPerl::FAccessfunction
manipulates various file characteristics. To get the command constants, it's
convenient to require "FAccess.ph". For details on MacPerl::FAccess, see
the online help under Macintosh specific features.

8_{The MPW SETcommand can be used to set or (with no arguments) list these variables}
from the MPW command line.