[Date Prev][Date Next][Thread Prev][Thread Next] [Search] [Date Index] [Thread Index]
[MacPerl] Missing file macperl.pod

To: mac-perl@iis.ee.ethz.ch
Subject: [MacPerl] Missing file macperl.pod
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Date: Sat, 26 Oct 1996 00:41:28 +0200
A few of you have pointed out that macperl.pod is missing from the 
distribution. Here it is appended. Just copy it into the pod folder
as "macperl.pod".

"Oha Laetz", for those who have encountered the message, is Swiss German
for "oops, something's wrong".

Matthias

-----
Matthias Neeracher   <neeri@iis.ee.ethz.ch>   http://www.iis.ee.ethz.ch/~neeri
              "Es muess der Moensch, so isch er g'arted
               En Arbet haa wo uf ne wartet
               Und wo-n-aer gniesserisch nit macht."
                          -- Mani Matter, _Lob vor Fuulheit_

=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
Prev by Date: [MacPerl] ressource.t : crash
Next by Date: [MacPerl] Installing Problems - MacPerl 5.1.0r2
Prev by thread: Re: [MacPerl] Installing Problems - MacPerl 5.1.0r2
Next by thread: [MacPerl] ressource.t : crash
Navigation: Date Index | Thread Index | Search | Other lists at bumppo.net