=head1 NAME

macperl - MacPerl specific features

=head1 DESCRIPTION

This file describes differences between MacPerl and a typical Unix perl
implementation. 

=head2 VARIA

All time related functions measure time in seconds from 1904, not 1970 as in
Unix.

"\n" on a Mac means ASCII 13, as opposed to Unix, where it means ASCII 10. If 
you want ASCII 10, write "\012".

Pathnames are specified as:

	volume:folder:file              for absolute pathnames
	:folder:file                    for relative pathnames
	:file                           for relative pathnames
	file                            for relative pathnames

MacPerl has a limited capability to handle constructs like `command` or
C<open(F, "|command")>, if you are the lucky owner of ToolServer. Additionally, 
whether you have toolserver or not, a few commands are implemented:

=over 5

=item *

`pwd` and `Directory` (case is significant) always return the current directory, 
followed by a newline.

=item *

`hostname` returns the name of the current Mac if MacTCP is running.

=item * 

`glob xxx` expands the glob pattern xxx and returns a list of expanded file
names. Only "*" and "?" are supported, with Option-x as an (MPW-style) 
alternative to "*".

=item *

`stty raw` or `stty -sane` in the MacPerl application switch the console window
to "raw" mode, i.e. turn off eching to the window and editing. `stty sane` or
`stty -raw` restores normal mode.

=back

=head2 SOCKETS

MacPerl has more Socket families than Unix Perl. Additionally, there is a call
choose() to allow the user to interactively specify addresses or file names. As
there are lots of rather complicated data types, there is a library header "GUSI.ph"
which defines packing/unpacking procedures.

Choose() is called as follows:

=over 8

=item MacPerl::Choose DOMAIN, TYPE, PROMPT, CONSTRAINT, FLAGS, DEFAULT

=item MacPerl::Choose DOMAIN, TYPE, PROMPT, CONSTRAINT, FLAGS

=item MacPerl::Choose DOMAIN, TYPE, PROMPT, CONSTRAINT

=item MacPerl::Choose DOMAIN, TYPE, PROMPT

Puts up a modal dialog prompting the user to choose an address. DOMAIN specifies 
the communication domain, like for socket(). TYPE may be used by future 
communication domains to further differentiate within a domain, but is ignored by 
current domains. PROMPT is a message that will appear in the dialog. CONSTRAINT 
may be set to a suitable packed value to restrict the types of acceptable addresses.

Examples:

     require "GUSI.ph";

     $file = 
        MacPerl::Choose(
           GUSI::AF_FILE, 0, "", 
           GUSI::pack_sa_constr_file("OBJ ", "TEXT"));

Return the full pathname of an existing text
or MPW object file.

     $dir = MacPerl::Choose(GUSI::AF_FILE, 0, "", "", GUSI::CHOOSE_DIR);

Return the full pathname of an existing directory.

     $file = 
        MacPerl::Choose(
           GUSI::AF_FILE, 0, "", "", 
           GUSI::CHOOSE_NEW + GUSI::CHOOSE_DEFAULT, "yo");

Return the pathname of a new file to be created.

=back 

Socket families are:

=over 8

=item Internet

Packing an address:

    GUSI::pack_sockaddr_in(GUSI::AF_INET, address, port);

Unpacking an address:

    (family, address, port) = GUSI::unpack_sockaddr_in(addr);

Choose is not available.

=item Unix

Packing an address:

    GUSI'pack_sockaddr_un(GUSI::AF_UNIX, path)

Unpacking an address:

    (family, path) = GUSI::unpack_sockaddr_un(addr);

Choose: looking up an existing address:

    MacPerl::Choose(GUSI::AF_UNIX, 0, "", "", 0, "");

Creating a new address (No constraints may be specified):

    MacPerl::Choose(GUSI::AF_UNIX, 0, "Yes ?", "", 
           GUSI::CHOOSE_NEW + GUSI::CHOOSE_DEFAULT, "yo");

=item Appletalk (ADSP)

Packing an address (numerical):

    GUSI::pack_sockaddr_atlk(GUSI::AF_APPLETALK, net, node, socket) 

Packing an address (symbolic):

    GUSI::pack_sockaddr_atlk_sym(GUSI::ATALK_SYMADDR, obj, type, zone)

Unpacking an address:

    (family, net, node, socket) = GUSI::unpack_sockaddr_atlk(addr)
    (family, obj, type, zone)   = GUSI::unpack_sockaddr_atlk_sym(addr)

Choose: look up an existing address:

    MacPerl::Choose(GUSI::AF_APPLETALK, 0, "Eh ?", 
           GUSI::pack_sa_constr_atlk("LaserWriter", "GorillaWriter"),
           0, "");

New addresses may not currently be created with choose.

=item PPC Toolbox

Packing an address:

    GUSI'pack_sockaddr_ppc(GUSI::AF_PPC, type, name, porttype)

Unpacking addresses not available.

Choose: look up an existing address:

    MacPerl::Choose(GUSI::AF_PPC, 0, "Eh ?", 
        GUSI::pack_sa_constr_ppc("Gonkulator"),
        0, "");

New addresses may not currently be created with choose.

=back

=head2 ADDITIONAL FUNCTIONS AVAILABLE IN MACPERL

=over 8

=item MacPerl::Answer(PROMPT)
=item MacPerl::Answer(PROMPT,BUTTON1)
=item MacPerl::Answer(PROMPT,BUTTON1,BUTTON2)
=item MacPerl::Answer(PROMPT,BUTTON1,BUTTON2,BUTTON3)

Presents to the user a dialog with 1, 2, or 3 buttons. 

Examples:

    MacPerl::Answer("Nunc et in hora mortis nostrae", "Amen");

always returns 0.

    MacPerl::Answer("I refuse");

is equivalent to C<&MacPerl'Answer("I refuse", "OK");>

    MacPerl::Answer("Delete hard disk ?", "OK", "Cancel");

returns 1 for OK, 0 for Cancel

    MacPerl::Answer("Overwrite existig file", "Overwrite", "Skip", "Cancel");

returns 2 for Overwrite, 1 for Skip, 0 for Cancel

=item MacPerl::Ask(PROMPT, DEFAULT)
=item MacPerl::Ask(PROMPT)

Asks the user for a string. A default value may be given. Returns
undef if the dialog is cancelled.

Example:

    $phone = MacPerl::Ask("Enter your phone number:");
    $name  = MacPerl::Ask("Enter your first name", "Bruce");

Useful for Australian database applications

=item MacPerl::Pick(PROMPT, VALUES)

Asks the user to pick a choice from a list. VALUES is a list of choices. 
Returns undef if the dialog is cancelled.

Examples:

    $color = MacPerl::Pick("What's your favorite color baby ?", "Red", "Green", "Gold");

=item MacPerl::SetFileInfo(CREATOR,TYPE,FILE...)

Changes the file types and creators of the file(s).

Examples:

    MacPerl::SetFileInfo("MPS ", "TEXT", yin, yang);

Turn yin and yang into MPW text files

=item MacPerl::GetFileInfo(FILE)

In scalar context, returns the file type. In array context, returns (creator,type).

Examples:

    MacPerl::GetFileInfo(yin);

Returns "TEXT" or ("MPS ", "TEXT").

=item MacPerl::DoAppleScript(SCRIPT)

Execute an AppleScript script.

Example:

    MacPerl::DoAppleScript(<<END_SCRIPT);
    tell application "MacPerl"
        make new Window
        copy "Inserting text the hard way." to character 1 of front Window
    end tell
    END_SCRIPT

=item MacPerl::Reply(ANSWER)

Reply to current DoScript request. Useful if you are calling Perl 
scripts from other applications.

=item MacPerl::Quit(LEVEL)

If LEVEL is 0, don't quit after ending the script. If 1, quit if 
running under a runtime version, if 2, always quit. If LEVEL is 3,
quit if this was the first script to be run since starting MacPerl.

=item MacPerl::LoadExternals(LIBFILE)

Load XCMD and XFCN extensions contained in file LIBFILE, which is searched
along the same path as it would be for a require. The extensions are made
accessible in the current package, unless they containing an explicit package
name.

=item MacPerl::DebugExternals(DEBUGLEVEL)

If DEBUGLEVEL is 0, don't print any debug information for XCMDs and XFCNs. 
If 1, print information for unimplemented callbacks. If 2, print 
informations for all callbacks.

=item MacPerl::FAccess(FILE, CMD, ARGS)

When called from the tool, manipulate various information of files. To 
get the command constants, it's convenient to require "FAccess.ph".

=over 8

=item $TAB = MacPerl::FAccess(FILE, F_GTABINFO)

=item MacPerl::FAccess(FILE, F_STABINFO, TAB)

Manipulate tabulator setting (in spaces per tab).

=item ($FONTNAME, $FONTSIZE) = MacPerl::FAccess(FILE, F_GFONTINFO)

=item $FONTNUM = MacPerl::FAccess(FILE, F_GFONTINFO)

=item MacPerl::FAccess(FILE, F_SFONTINFO, FONT [, SIZE])

Manipulate font and size information. Both font names and font numbers
are accepted for F_SFONTINFO; F_GFONTINFO returns a font name in an
array context, a font number in a scalar context.

=item ($STARTSEL, $ENDSEL, $DISPLAYTOP) = MacPerl::FAccess(FILE, F_GSELINFO)

=item $STARTSEL = MacPerl::FAccess(FILE, F_GSELINFO)

=item MacPerl::FAccess(FILE, F_SSELINFO, $STARTSEL, $ENDSEL [, $DISPLAYTOP])

Manipulate the MPW selection of a file.

=item ($LEFT, $TOP, $RIGHT, $BOTTOM) = MacPerl::FAccess(FILE, F_GWININFO)
=item $TOP = MacPerl::FAccess(FILE, F_GWININFO)
=item MacPerl::FAccess(FILE, F_SWININFO, LEFT, TOP [, RIGHT, BOTTOM])

Manipulate the window position.

=back

=item MacPerl::MakeFSSpec(PATH)

This command encodes a path name into an encoding (volume #, directory #,
File name) which is guaranteed to be unique for every file. Don't store
this encoding between runs of MacPerl!

=item MacPerl::MakePath(FSSPEC)

The inverse of MacPerl::MakeFSSpec(): turn an encoding into a path name.

=item MacPerl::Volumes()

In scalar context, return the FSSPEC of the startup volume. In list context, 
return FSSPECs of all volumes.

=back

=head2 MACPERL SPECIFIC LIBRARIES

=over 8

=item StandardFile.pl   

Calls for standard file dialogs. A very convenient front end for MacPerl::Choose()

=item FindFolder.pl     

Returns the path names of special folders (System, Preferences).

=item CommConnect.pl   

Library for accessing the serial port.

=item GUSI.ph           

Definitions for socket related calls.

=item FAccess.ph        

Definitions for MacPerl::FAccess() (MPW tool only).

=back