About the MacPerl FAQ

Version and Date information:

Changes since prior release:

• 11/11 - comment RE: Faq-o-matic
• 7/30 - comments RE: Net::SMTP and 68000 support
• 7/29 - comments from Paul Schinder:
  name of comp.lang.perl.moderated, ftp site for Alpha, 68000 systems, Perl 4 vs 5 information...
• 7/28 - posted update
• 7/26 - Updated from version 2.5 (March 1997) - many changes

The MacPerl FAQ is currently being edited and maintained by Vicki Brown, Rich Morin, and other members of the MacPerl community at www.ptf.com/macperl/depts/fom.html.

The MacPerl FAQ-o-matic is being kept on the MacPerl Pages at http://www.cfcl.com/macperl/depts/fom.html. The FAQ-o-matic is maintained entirely by your contributions.

The initial version of the MacPerl FAQ was prepared by Hal Wine. The current outline and a lot of the useful words in this edition were prepared by Hal, as well. Later versions of the FAQ were edited and maintained by Bob Dalgleish and Bob Wilkinson.

This FAQ is intended as a supplement to the main Perl FAQ, and does not replace it.

Where to get the most recent MacPerl release:

• Use FTP to get the site registry and find the repository site nearest you. Save this information for later use when you want to get files. It saves wear and tear on the 'net and administrators everywhere.

• Use a Web browser to search for the file to download. This URL will find a (relatively local) mirror site to get your file. This URL uses a magic process to refer you to a nearby FTP site. There is also a form that will identify the most recent versions of released files and give you the URL without the search.

Where to get the most recent FAQ:

What the FAQ covers:

The MacPerl FAQ also contains information on some unique applications of MacPerl. However, pointers to other information are more likely for these topics.

Finally, the MacPerl FAQ contains information useful in porting Perl scripts to and from the Unix environment.

What the FAQ doesn't cover:

The MacPerl FAQ is also not a tutorial. Nor is it a 100% correct authority on anything! If you think something is missing, we welcome you to add it to the MacPerl FAQ-O-Matic

How the FAQ is organized:

Both Perl version 4 and 5 have been ported to the Mac. Much of the information in this FAQ is not unique to the Perl version being used. The major emphasis of the FAQ is on MacPerl 5.

Table of Contents

• 1) General Questions

  • 1.1) What's the most recent version of MacPerl?
    • 1.1.1) Perl 5
    • 1.1.2) Perl 4
    • 1.1.3) Differences between Perl 4 and Perl 5

  • 1.2) How do I install MacPerl?
    • 1.2.1) Transferring the files:
    • 1.2.2) How do I unpack the stuff I got?
    • 1.2.3) Setting Preferences

  • 1.3) What Macs does MacPerl run on?

  • 1.4) Other MacPerl resources:
    • 1.4.1) Is there a mailing list for MacPerl?
    • 1.4.2) Newsgroups which cover Perl (not specifically MacPerl)
    • 1.4.3) Are there any books on MacPerl?

  • 1.5) Perl Resources
    • 1.5.1 What are the recommended books about Perl?
    • 1.5.2 Where do I look for more Perl books and documentation?
    • 1.5.3 Are there any book reviews online?

• 2) Differences between MacPerl and Perl on other platforms

  • 2.1) Differences in functions on MacPerl, compared with Perl under Unix.

  • 2.2) Compatability with Perl under Unix.
    • 2.2.1) Why does source preprocessing (-P) not work?
    • 2.2.2) How do I open a pipe both to and from a command?
    • 2.2.3) Why do %ENV changes not pass to processes that I start?
    • 2.2.4) Why don't backticks work as they do on Unix?

  • 2.3) MacOS file system issues
    • 2.3.1) How do I request an input or output file under MacPerl?
    • 2.3.1.1) How do I request a folder under MacPerl?
    • 2.3.2) Why can't I detect aliases in my script?
    • 2.3.3) How do I pass environment variables to my script?
    • 2.3.4) How do I perform globbing in MacPerl?

  • 2.4) Application additions
    • 2.4.1) MacPerl package
    • 2.4.2) Macintosh Toolbox interfaces

  • 2.5) How can I compare two date strings?

  • 2.6) How do I get MacPerl to recognize the Mac character set?

  • 2.7) How do I access Mac Resources from MacPerl?

• 3) MacPerl Application

  • 3.1) How do I package my Perl scripts?
    • 3.1.1) Droplets:
    • 3.1.2) Standalone applications/Runtimes:
    • 3.1.3) What about other files to go with the package?

  • 3.2) Devices (printer, screen, apple event)
    • 3.2.1) How can I get MacPerl to dial my modem?
    • 3.2.2) How can I keep local data files in my droplet/runtime?
    • 3.2.3) How can I output to another window?
    • 3.2.4) How can I get/set AppleEvent data?

  • 3.3) How do I develop scripts?
    • 3.3.1) Alternate Text Editors
    • 3.3.2) Alpha Text Editor:
    • 3.3.3) BBEdit Text Editor:

• 4) MacPerl MPW tool

  • 4.1) Installation of MPW MacPerl

  • 4.2) Specific differences between the MPW tool and Perl under Unix

• 5) Special Application Areas

  • 5.1) How can I extend the capabilities of MacPerl?
    • 5.1.1) Perl Modules
    • 5.1.2) Perl Extension System (XS) and dynamic loading of extensions.

  • 5.2) How do I program for the Web?
    • 5.2.1) How do I serve Web information (CGI)?
    • 5.2.2) How do I mail the contents of a filled in form?
    • 5.2.3) How do I create or parse HTML documents?

  • 5.3) Portability tricks and techniques
    • 5.3.1) How do I know that this script is running under MacPerl?
    • 5.3.2) How do I get input from the user of the script?
    • 5.3.3) How do I pass parameters to the script?

  • 5.4) How do I know what directory the current script is in?

• 6) Common Problems

  • 6.1) Why does my here document not get read properly?

  • 6.2) Why does MacPerl not work with Netscape?

  • 6.3) When I try to read a particular file, why does MacPerl complain that it is "out of memory"?

  • 6.4) I can't get my droplet to run when I drop files on it?

1) General Questions

1.1) What's the most recent version of MacPerl?

Unless you already have MPW, and know its environment, you want the standalone version, hereafter called the MacPerl Application.

Perl5 introduced several powerful new technologies, including object-oriented programming, to Perl. This allowed modules to be much more self-sufficient, yet extensible, as well as allowing system extensions. These extensions will be capitalized upon in further releases of MacPerl.

Where possible, the users of MacPerl should upgrade to MacPerl5, since its extensibility and generality are very much enhanced. Perl4 scripts should run almost unchanged under Perl5, but you can easily check for problems by setting the -wswitch to flag common errors. The reference file pod:perltrap.html in the release describes common problems.

1.1.1) Perl 5

Mac_Perl_tool.bin

for the MacPerl tool

Mac_Perl_appl.bin

for the MacPerl application

The source code for these versions is also available in the same directory. Consult the file Mac_Perl.info for details on which sources are needed for which version.

1.1.2) Perl 4

Mac_Perl_tool.bin

for the MacPerl tool

Mac_Perl_appl.bin

for the MacPerl application

1.1.3) Differences from Perl 4 to Perl 5

One noticeable difference is how package qualifications are made. In Perl4, a variable in a package was entered as $Package'variable. In Perl5, it is entered as $Package::variable, although the old form is still permitted.

Other differences include:

• some old keywords are gone
• some new keywords have been added
• new quoting constructs have been added
• Perl 5 has object oriented features
• Perl 5 has modules
• myis recommended instead of local
• more diagnostics are possible
• certain coding habits that should not have been permitted now generate appropriate complaints ;-)

If you have been using Perl 4 and are moving to Perl 5, consult the Perl 4 to Perl 5 Traps list or perltrap.pod in the release help files, for guidance. If you are just now learning Perl, be sure to start with the latest version. Be sure that any books you refer to document Perl version 5!

1.2) How do I install MacPerl?

1.2.1) Transferring the files:

After decompressing the archive, be sure to read all the text files in the top leveldirectory. (Or just review them if you're upgrading.)

1.2.2) How do I unpack the stuff I got?

All MacPerl distribution files are StuffIt formatted archives, encapsulated in MacBinary. Use StuffIt Expander, available from Aladdin Systems, or a similar utility, to decompress the files. See the comp.sys.mac.comm FAQ for a more complete list

1.2.3) Setting Preferences

Preferences are set for the MacPerl tool by pulling down the "Edit" menu, and selecting "Preferences". This permits the user to

• Choose the path along which libraries are searched

• Determine whether MacPerl defaults to opening files for editing, or tries to run them. The decision whether to check for a line starting with the string "#!" can be toggled.

• The decision whether to check for inline input can be toggled

• "Internet config" can be launched, which enables various parameters to be set

Preferences for the MPW tool are set as described in section 4.1.1.

1.3) What Macs does MacPerl run on?

1.4) Other MacPerl resources:

1.4.1) Is there a mailing list for MacPerl?

Or use the web-based subscription form on The MacPerl pages

A searchable archive of the mailing list is available.

The mailing list is presently unavailable in digest form.

1.4.2) Newsgroups which cover Perl (not specifically MacPerl)

• comp.lang.perl.announce
• comp.lang.perl.misc
• comp.lang.perl.moderated
• comp.lang.perl.modules
• comp.lang.perl.tk

1.4.3) Are there any books on MacPerl?

MacPerl: Power and Ease
by Vicki Brown and Chris Nandor
published May, 1998, by Prime Time Freeware
ISBN 1-881957-32-2

1.5) Perl Resources

1.5.1 What are the recommended books about Perl?

Programming Perl
by Larry Wall, Tom Christiansen, & Randal L. Schwartz
Second Edition
published Sept., 1996, by O'Reilly & Associates
ISBN 1-56592-149-6

Note - not all examples in the typical Perl books will run unmodified under MacPerl! Most Perl books were written for Unix Perl (or perhaps Perl for Windows NT). See the section on differences for more details.

1.5.2 Where do I look for more Perl books and documentation?

You can also search the online bookstores. Try Computer Literacy or Amazon.com.

1.5.3 Are there any book reviews online?

Amazon.com asks readers to post reviews of books they have purchased and read.

2) Differences between MacPerl and Perl on other platforms

2.1) Differences in functions on MacPerl, compared with Perl under Unix.

2.2) Compatability with Perl under Unix.

2.2.1) Why does source preprocessing (-P) not work?

Language processors on Unix have traditionally allowed arbitrary front end preprocessing for their input. The Mac has not.

Perl5 has significantly extended the syntax and the preparation so that most preprocessing is not needed. The usual use of preprocessing is to provide manifest constants. Subroutines can be made into "bare-words", which allow what-look-to-be constant values, likeENOFILE, to be used in Perl code.

2.2.2) How do I open a pipe both to and from a command?

2.2.3) Why do %ENV changes not pass to processes that I start?

2.2.4) Why don't backticks work as they do on Unix?

Matthias has hardcoded some strings to be processed by MacPerl itself.

pwd

Current working directory.

Directory

Current working directory.

hostname

Hostname as returned by MacTCP or OpenTransport.

stty -raw

Allow single character input from the keyboard.

stty -cooked

Allow normal character input (line-oriented) from the keyboard.

For greater portability, there is a module called Cwd.pm which sets the environment variable PWD. For instance,

    use Cwd;
	    chdir_init;
	    $p = $ENV{'PWD'};
	    ...
	    chdir $newdir;
	    $p = $ENV{'PWD'};
	

2.3) MacOS file system issues

2.3.1) How do I request an input or output file under MacPerl?

       use Mac::StandardFile;
       $file = StandardGetFile('', 'TEXT');
       if ($file->sfGood()) {
           push(@ARGV, $file->sfFile());
       } else {
           exit(1);
       }
 	
	

2.3.1.1) How do I request a folder under MacPerl?

require 'GUSI.ph';
	
	$chosen_folder = MacPerl::Choose(&GUSI::AF_FILE(), 0, "Which folder?",
                     "", &GUSI::CHOOSE_DIR);

	

2.3.2) Why can't I detect aliases in my script?

The same is true for the results of standard file calls.

This has been fixed in MacPerl5r2.

2.3.3) How do I pass environment variables to my script?

	property env : {"HOME", "Boot", "TEMP", "Boot:Temporary Items"}
	property perlScript : "Boot:Scripting:MacPerl:called_by_as_test.pl"
	property opts : {"-n", "-x", "Boot:Scripting"}
	
	tell application "MacPerl"
	   try
	      Do Script ({perlScript} & opts) mode batch environment env
	      without extract
	   on error errorMessage number errorNumber
	      return errorNumber
	   end try
	end tell
	

2.3.4) How do I perform globbing in MacPerl?

        @files = <*.error>;
	

    opendir( DIR, ':' ) || die( "Can't open ':': $!\n" );
	    @files = grep( /\.error$/, readdir( DIR ) );
	    closedir( DIR );
	

2.4) Application additions

2.4.1) MacPerl package

2.4.2) Macintosh Toolbox interfaces

2.5) How can I compare two date strings?

2.6) How do I get MacPerl to recognize the Mac character set?

The top 128 characters which can be stored in a byte are the extended characters. However, which character is represented by which bit-pattern is font-dependent, and especially machine-dependent. Some machines do share the same extended character set e.g. Unix and MS-Windows both use the ISO-lat1 (Latin-1) character set; this is not the same as that generally used on a Macintosh.

In regular expressions, \w can be used to match against an alphanumeric character, where this set of characters is [A-Za-z0-9_]. This will not match against å, é, ü, è or any other accented characters which are found in the extended characters of the Macintosh character set (or any other extended characters for this matter). However, locale settings can influence the characters matched by \w.

Portability of code (from platform to platform, and on the Macintosh from font to font) would be compromised, if the extended characters were used within the \w, \W matches. A set of characters may be constructed on an ad hoc basis by encoding the characters as their hex values e.g. \xa9.

The library function, I18N:Collate may be used to order objects according to the national character set used.

2.7) How do I access Mac Resources from MacPerl?

Recently, Matthias has released Perl extensions that allow access to the Macintosh toolbox for Memory, Resources, and Apple Events. Currently, this is PowerMac-compatible only.

3) MacPerl Application

3.1) How do I package my Perl scripts?

First, let's look at what you have to distribute in order to share a perl script with a friend e.g. your wiz bang lotto number picker script.

Two methods of distributing clickable run-time applications are supported, Droplets and Runtimes.

3.1.1) Droplets:

To make a droplet, simply open your script in MacPerl, then choose "Save As". One of the "Type" options is "Droplet". The droplet is actually an application program that contains the text of your script, plus some code (about 8KB). When launched, the droplet uses Apple Events to launch MacPerl (if it isn't already running), and then sends it the script to execute.

You can reopen and change the script of droplets from within MacPerl. Subsequent "Saves" will retain the droplet file type.

If the user launches a droplet by dragging and dropping some files onto the droplet's icon in the Finder, those file names will appear as arguments to the script (i.e. they will be in @ARGV). This is one of the simplest ways to access the command line from outside of MPW.

The only downside to droplets is that users must have a complete installation of MacPerl, including any libraries that are called by your script. This means that the first application you distribute this way take over 800K. However, future droplets only take up 8K over the size of the script.

3.1.2) Standalone applications/Runtimes:

If having your users install a version of MacPerl is too onerous (required for droplets), then you can save them as a runtime application. However, not all features are supported in the runtime applications. Also, runtime versions take over 500KB per script!

Note: runtime versions do not execute any quicker. Perl is always interpreted every time the script is run, period.

3.1.3) What about other files to go with the package?

The Macintosh way is to package everything that is needed into a single file using (named) resources to differentiate components. In support of this, MacPerl allows you to include CODE resources (of type XCMD or XFCN), as well as TEXT resources containing source modules, into the droplet or runtime. To get access to the CODE resource, you need to use theMacPerl::LoadExternals() function. To get access to the source modules, therequire function searches the TEXT resources of the droplet for the module name. (See Extending Perl .)

3.2) Devices (printer, screen, apple event)

3.2.1) How can I get MacPerl to dial my modem?

   ATDT 1-900-MACPERL
	

3.2.2) How can I keep local data files in my droplet/runtime?

3.2.3) How can I output to another window?

open(CON2, ">Dev:Console:Another Window");
	

3.2.4) How can I get/set AppleEvent data?

3.3) How do I develop scripts?

3.3.1) Alternate Text Editors

The shareware editor, Alpha, and the commercial editor, BBEdit, (as well as the freeware version, BBEdit Lite), contain many useful features designed to make it easier to write (and run) Perl scripts (as well as many other programming languages). These features include line numbering, real tabs, the ability to edit files larger than 32K in size, language-sensitive syntax coloring, search/replace capability, subroutine indexing, and much more.

3.3.2) Alpha Text Editor:

3.3.3) BBEdit Text Editor:

4) MacPerl MPW tool

4.1) Installation of MPW MacPerl

To complete the installation proces, launch MPW and run the Install.MPW_Perl script (this was part of the tool package you just installed). Follow the instructions. This MPW script will create configuration file which you must edit and execute to complete the installation process.

4.2) Specific differences between the MPW tool and Perl under Unix

5) Special Application Areas

5.1) How can I extend the capabilities of MacPerl?

The code modules (XCMD/XFCN) developed for HyperCard may often be used in MacPerl. While there is no external documentation for which HyperCard callbacks are not implemented,most widely available code module libraries offer safe packages. See themacperl.html file in the pod directory of MacPerl for how to useMacPerl::LoadExternal().

5.1.1) Perl Modules

5.1.2) Perl Extension System (XS) and dynamic loading of extensions.

Starting with MacPerl5r2, the extension system has gotten a lot easier, and Matthias has written a number of modules that give access to the MacOS functions. These extension modules are still in beta testing, but will be made available for general release.

5.2) How do I program for the Web?

5.2.1) How do I serve Web information (CGI)?

Then, get the CGIglue

Next, get some documentation from Using Perl With MacHTTP and MacUser April 1997.

Other links which may be of use are MacWorld, Mac WWW: Network Questions, and MacHTTP web site.

5.2.2) How do I mail the contents of a filled in form?

5.2.3) How do I create or parse HTML documents?

If you want to do smaller versions of these tasks, then try Tom Christiansen's hacks for useful scripts.

5.3) Portability tricks and techniques

5.3.1) How do I know that this script is running under MacPerl?

    print "Running under MacPerl\n" if $MacPerl::Version;
	

    use Config;
	    if ( $Config{'osname'} =~ /^macos/i ) {
	        print "Running under MacPerl\n";
	    }
	 

Accessing file names is different between Unix and MacOS. However, Unix, MacOS and MSDOS all use hierarchical file naming, and some of the commonality has been gathered together into Perl modules for Perl5. Learn to use the portability-oriented modules, such as File::Basename.pm, and File::Path.pm.

5.3.2) How do I get input from the user of the script?

5.3.3) How do I pass parameters to the script?

#!perl -pi.BAK
	

In the MPW version, the command line is supplied in the same manner as on Unix. For the application, there are two choices, depending on whether or not you need just file names or also options.

If you also want to give the user a chance to enter command line options, you can use the following code fragment:

   if( $MacPerl::Version =~ /Application$/ ) {
	        # we're running from the app
	        my( $cmdLine, @args );
	        $cmdLine = &MacPerl::Ask( "Enter command line options:" );
	        require "shellwords.pl";
	        @args = &shellwords( $cmdLine );
	        unshift( @ARGV, @args );
	    }
	

If your script just needs to know file names, then you can save the script as a droplet and start it by dropping the desired files onto the droplet's icon from the Finder.

If the parameters you need to supply are mostly fixed, you can also put them after the script itself, in the data portion of the script. For instance,

	# Get the default parameters
	 {
	   my @parms = <DATA>;
	    chomp(@parms);
	    unshift(@ARGV, @parms);
	}
	...
	 __END__
	parm1
	parm2
	...
	

5.4) How do I know what directory the current script is in?

    $dirSep = '/';  # assume Unix
	    $dirSep = ':' if $MacPerl::Version;  # change to Mac
	    ($path, $app) = $0 =~ /^(.*$dirSep)?([^$dirSep]+)$/;
	

    use File::Basename;
	    ($app, $path) = fileparse($0);
	

6) Common Problems

6.1) Why does my here document not get read properly?

1. there isn't a carriage return after the final HEREIS or
2. there is a bunch of white space after the final HEREIS

	print "HEREIS\n";
	

6.2) Why does MacPerl not work with Netscape?

Note that MacOS 8 does not require a separate ObjectSupportLib; this functionality is built into the System.

6.3) When I try to read a particular file, why does MacPerl complain that it is "out of memory"?

Set the record separator character to "\012" using any of

	
$/ = "\012";
	
use English; $INPUT_RECORD_SEPARATOR = "\012";
	
use English; $RS = "\012";
	
	

Alternatively, translate the file using an editor or file conversion program. Or, convert it using Perl! For example:

	$/="\012";$\="\010";while(<>){chop;print}
	

	$/ = "\012";
	$^I = ".orig";

	while (<>) {
    	s/\012/\015/g;
    	print;
	}
         

6.4) I can't get my droplet to run when I drop files on it?