Tuesday, November 2, 1999

This archive can always be obtained from:

    http://www.perl.com/CPAN/authors/id/CNANDOR/
    http://www.perl.com/CPAN/modules/by-module/Mac/

The file is a tarred, gzipped file.  Use Stuffit Expander or a
similar program (like my untargzipme) to get at the archive.

Please let me know how well it does(n't) work, and any changes you'd 
like to see.

#============================================================================

NAME
    Mac::AppleEvents::Simple - MacPerl module to do Apple Events more
    simply

SYNOPSIS
        #!perl -w
        use Mac::AppleEvents::Simple;
        use Mac::Files;  # for NewAliasMinimal
        $alias = NewAliasMinimal(scalar MacPerl::Volumes);
        do_event(qw/aevt odoc MACS/, "'----':alis(\@\@)", $alias);

        # [...]
        use Mac::AppleEvents;  # for kAENoReply
        $evt = build_event(qw/aevt odoc MACS/, "'----':alis(\@\@)", $alias);
        die "There was a problem: $^E" if $^E;
        $evt->send_event(kAENoReply);
        die "There was a problem: $^E" if $^E;

DESCRIPTION
    **NOTE** You should have the Mac::AppleEvents and Mac::Memory
    distributions from the cpan-mac distribution. See
    http://pudge.net/macperl/ for more info.

    This is just a simple way to do Apple Events. The example above was
    previously done as:

        #!perl -w
        use Mac::AppleEvents;
        use Mac::Files;
        $alias = NewAliasMinimal(scalar MacPerl::Volumes);
        $evt = AEBuildAppleEvent(qw/aevt odoc sign MACS 0 0/,
            "'----':alis(\@\@)", $alias) or die $^E;
        $rep = AESend($evt, kAEWaitReply) or die $^E;
        AEDisposeDesc($rep);
        AEDisposeDesc($evt);

    The building, sending, and disposing is done automatically. The
    function returns an object containing the parameters, including the
    `AEPrint' results of `AEBuildAppleEvent' `($event->{EVENT})' and
    `AESend' `($event->{REPLY})'.

    The raw AEDesc forms are in `($event->{EVT})' and `($event->{REP})'.
    So if I also `use''d the Mac::AppleEvents module (or got the symbols
    via `use Mac::AppleEvents::Simple ':all''), I could extract the direct
    object from the reply like this:

        $dobj = AEPrint(AEGetParamDesc($event->{REP}, keyDirectObject));

    An easier way to get the direct object data, though, is with the `get'
    method, described below.

    The sending of the event uses as its defaults (`kAEWaitReply',
    `kAENormalPriority', `kNoTimeout'). To use different parameters, use
    `build_event' with `send_event'.

    Setting `$Mac::AppleEvents::Simple::SWITCH = 1' forces the target app
    to go to the front on sending an event to it.

    Sending an event with `send_event' or `do_event' will check for errors
    automatically, and if there is an error and
    `$Mac::AppleEvents::Simple::WARN' is true, a warning will be sent to
    `STDERR'. You can also check `$^E' after each call, or check the
    values of `$event->{ERRNO}' and `$event->{ERROR}'.

    If the event reply itself contains a `errn' or `errs' parameter, these
    will also be placed in `$event->{ERRNO}' and `$event->{ERROR}' and
    `$^E' as appropriate.

    You may decide to roll your own error catching system, too. In this
    example, the error is returned in the direct object parameter.

        my $event = do_event( ... );
        die $^E if $^E;  # catch execution errors
        my_warn_for_this_app($event);  # catch AE reply errors

        sub my_warn_for_this_app {
            my $event = shift;
            my $error = AEGetParamDesc($event->{REP}, keyDirectObject);
            if ($error) {
                my $err = $error->get;
                if ($err =~ /^-\d+$/ && $^W) {
                    warn "Application error: $err";
                }
                AEDisposeDesc($error);
            }
        }

REQUIREMENTS
    MacPerl 5.2.0r4 or better, and Mac::Apps::Launch 1.70.

FUNCTIONS
    [$EVENT =] do_event(CLASSID, EVENTID, TARGET, FORMAT, PARAMETERS ...)
        The first three parameters are required. The FORMAT and PARAMETERS
        are documented elsewhere; see the Mac::AppleEvents manpage and the
        macperlcat manpage.

        TARGET may be a four-character app ID or a hashref containing
        ADDRESSTYPE and ADDRESS. For type TARGET, a PPC record can be
        packed with `pack_ppc'.

    $EVENT = build_event(CLASSID, EVENTID, TARGET, FORMAT, PARAMETERS ...)
        This is for delayed execution of the event, or to build an event
        that will be sent specially with `send_event'. Build it with
        `build_event', and then send it with `send_event' method. The
        parameters are the same as `do_event'.

    $EVENT->send_event([GETREPLY, PRIORITY, TIMEOUT]);
            ***NOTE***
            Previously, you could set $object->{REPLY}.  But REPLY was already
            taken.  Whoops.  You now need to set $object->{GETREPLY}.

        For sending events differently than the defaults, which are
        `kAEWaitReply', `kAENormalPriority', and `kNoTimeout', or for re-
        sending an event. The parameters are sticky for a given event, so:

            $evt->send_event(kAENoReply);
            $evt->send_event;  # kAENoReply is still used

    $EVENT->data([KEY])
    $EVENT->get([KEY])
    data(DESC[, KEY])
    get(DESC[, KEY])
        Similar to `get' and `data' from the Mac::AppleEvents module. Get
        data from a Mac::AppleEvents::Simple object for a given key
        (`keyDirectObject' is the default). Can also be called as a
        function, where an AEDesc object is passed as the first parameter.

        For `data', if the descriptor in KEY is an AE list, then a list of
        the descriptors in the list will be returned. In scalar context,
        only the first element will be returned.

        On the other hand, `get' will return a nested data structure,
        where all nested AE lists will be converted to perl array
        references, and all nested AE records will be converted to perl
        hash references. In scalar context, only the first element of the
        base list will be returned for AE lists.

        Also, `get' will attempt to convert other data into a more usable
        form (such as resolving aliases into paths).

    pack_ppc(ID, NAME, SERVER[, ZONE])
        Packs a PPC record suitable for using in `build_event' and
        `do_event'. Accepts the 4-character ID of the target app, the name
        of the app as it may appear in the PPC Chooser, and the server and
        zone it is on. If not supplied, zone is assumed to be '*'.

    pack_eppc(ID, NAME, HOST)
        Packs an EPPC record suitable for using in `build_event' and
        `do_event'. Accepts the 4-character ID of the target app, the name
        of the app as it may appear in the PPC Chooser, and the hostname
        of the machine it is on. Requires Mac OS 9.

    pack_psn(PSN)
        Simply packs a PSN into a double long.

EXPORT
    Exports functions `do_event', `build_event'.

HISTORY
    v0.81, Tuesday, November 2, 1999
        Added requirement for Mac::AppleEvents version 1.22 (included in
        distribution).

        Added `type' method.

        Added EPPC addressing (Apple events over TCP/IP). Seems to work as
        well as the PPC addressing. Requires Mac OS 9. Added `pack_eppc'.

    v0.80, Friday, September 10, 1999
        Added PPC port addressing. Still experimental, as I am working
        largely off empirical observation, rather than specs. Added
        `pack_ppc'. (Cameron Ashby <cameron@evolution.com>)

        Added `pack_psn' to simply get a PSN into a long double.

    v0.72, Wednesday, September 1, 1999
        Fixed bug in `_event_error' that did not return proper value, or
        clear `$^E' properly. (Francis Clarke <F.Clarke@swansea.ac.uk>)

    v0.71, Tuesday, June 8, 1999
        Added `$DEBUG' global. Will be used more.

        Added some coercions so certain types will be returned as typeChar
        from the `get' method.

    v0.70, Friday, June 4, 1999
        Removed deprecated `ae_send' function. Use `send_event' instead.

        Removed deprecated `get_text' function. Not needed anymore, use
        `get' method instead.

        Cleaned up stuff.

        Improved error handling. Will return on first error. See docs
        above for more information.

        Made `$Mac::AppleEvents::Simple::SWITCH' `0' by default instead of
        `1'.

        Added global `%DESCS' to save AEDescs for disposal later.

    v0.65, May 30, 1999
        No longer return entire desc from `get' if direct object not
        supplied.

        Error number put in `$^E' if supplied.

        Added a bunch of stuff to `%AE_GET'.

        `get' method now automatically unpacks nested AE records and AE
        lists into perl hash and array references.

    v0.61, May 1, 1999
        Made default timeout `kNoTimeOut'.

        Changed use of `REPLY' for parameter to `AESend' to `GETREPLY'.
        `REPLY' was already in use, D'oh!

    v0.60, January 28, 1999
        Added `get' and `data' methods.

    v0.52, September 30, 1998
        Re-upload, sigh.

    v0.51, September 29, 1998
        Fixed problems accepting parameters in `send_event'. Sped up
        switching routine significantly.

    v0.50, September 16, 1998
        Only `LaunchApps' when sending event now if $SWITCH is nonzero or
        app is not already running.

        Added warnings for event errors if present and if `$^W' is
        nonzero. Only works if event errors use standard keywords `errs'
        or `errn'.

    v0.10, June 2, 1998
        Changed `new' to `build_event', and `ae_send' to `send_event'.

        Made default `AESend' parameters overridable via `send_event'.

    v0.03, June 1, 1998
        Added `$SWITCH' global var to override making target app go to
        front.

    v0.02, May 19, 1998
        Here goes ...

AUTHOR
    Chris Nandor <pudge@pobox.com>, http://pudge.net/

    Copyright (c) 1999 Chris Nandor. All rights reserved. This program is
    free software; you can redistribute it and/or modify it under the
    terms of the Artistic License, distributed with Perl.

SEE ALSO
    Mac::AppleEvents, Mac::OSA, Mac::OSA::Simple, macperlcat.

VERSION
    v0.81, Tuesday, November 2, 1999

#============================================================================

-- 
Chris Nandor          mailto:pudge@pobox.com         http://pudge.net/
%PGPKey = ('B76E72AD', [1024, '0824090B CE73CA10  1FF77F13 8180B6B6'])
