/ 
Mac-OSA-Simple-1.02
River stage zero No dependents
/ Mac::OSA::Simple

NAME

Mac::OSA::Simple - Simple access to Mac::OSA

SYNOPSIS

#!perl -wl
use Mac::OSA::Simple;
osa_script('LAND', <<'EOS');
  dialog.getInt ("Duration?",@examples.duration);
  dialog.getInt ("Amplitude?",@examples.amplitude);
  dialog.getInt ("Frequency?",@examples.frequency);
  speaker.sound (examples.duration, examples.amplitude,
      examples.frequency)
EOS

print frontier('clock.now()');

applescript('beep 3');

DESCRIPTION

You can access scripting components via the tied hash %ScriptComponents which is automatically exported. Components are only opened if they have not been already, and are closed when the program exits. It is normally not necessary to use this hash, as it is accessed internally when needed.

Also usually not necessary, but possibly useful, are all the functions and constants from Mac::OSA, available with the EXPORT_TAG "all".

Functions

The following functions are automatically exported.

osa_script(SCRIPTCOMPONENT, SCRIPTTEXT)

Compiles and executes SCRIPTTEXT, using four-char SCRIPTCOMPONENT. Component is opened and closed behind the scenes, and SCRIPTTEXT is compiled, executed, and disposed of behind the scenes. If the script returns data, the function returns the data, else it returns 1 or undef on failure.

applescript(SCRIPTTEXT)
frontier(SCRIPTTEXT)

Same thing as osa_script with SCRIPTCOMPONENT already set ('ascr' for AppleScript, 'LAND' for Frontier).

compile_osa_script(SCRIPTCOMPONENT, SCRIPTTEXT)

Compiles script as osa_script above, but does not execute it. Returns Mac::OSA::Simple object. See "Methods" for more information.

compile_applescript(SCRIPTTEXT)
compile_frontier(SCRIPTTEXT)

Same thing as compile_osa_script with SCRIPTCOMPONENT already set.

load_osa_script(HANDLE)
load_osa_script(FILE [, RESOURCEID])

In the first form, load compiled OSA script using data in Handle (same data as returned by compiled method; see Mac::Memory). In the second form, gets script from FILE using RESOURCEID (which is 128 by default). Returns Mac::OSA::Simple object.

NOTE: Because of a change in the parameters for this function, a RESOURCEID value of 1 will not be recognized as a resource ID (the old parameter list had a value of 1 mean "load from file"). If you need to use a resource ID of 1, pass it in as both the second and third parameter. Sorry. Why would you use 1 for a resource ID, anyway??

Example:

use Mac::OSA::Simple qw(:all);
use Mac::Resources;
$res = FSpOpenResFile($file, 0) or die $^E;
$scpt = Get1Resource(kOSAScriptResourceType, 128)
    or die $^E;
$osa = load_osa_script($scpt);
$osa->execute;
CloseResFile($res);

Same thing:

use Mac::OSA::Simple;
$osa = load_osa_script($file);
$osa->execute;

Another example:

use Mac::OSA::Simple;
$osa1 = compile_applescript('return "foo"');
print $osa1->execute;

# make copy of script in $osa1 and execute it
$osa2 = load_osa_script($osa1->compiled);
print $osa2->execute;

See "Methods" for more information.

Methods

This section describes methods for use on objects returned by compile_osa_script and its related functions and load_osa_script.

compiled

Returns a Handle containing the raw compiled form of the script (see Mac::Memory).

dispose

Disposes of OSA script. Done automatically if not called explicitly.

execute

Executes script. Can be executed more than once.

save(FILE [, ID [, NAME]])

Saves script in FILE with ID and NAME. ID defaults to 128, NAME defaults to "MacPerl Script". DANGEROUS! Will overwrite existing resource!

source

Returns text of script source, if available.

Script Context

Scripts compiled by this module now compile scripts as script contexts, which, in part, means they can maintain state information. For example:

use Mac::OSA::Simple;
my $script = compile_applescript(<<'SCRIPT') or die $^E;
property foo: 20
set foo to foo + 1
SCRIPT
print $script->execute, "\n" for 0..2;

Returns: 21 22 23

Whereas in previous versions of this module, it would have returned: 21 21 21

For a script that on disk, to maintain state information in the saved version, remember to call $script-save(LIST)>.

TODO

Work on error handling. We don't want to die when a toolbox function fails. We'd rather return undef and have the user check $^E.

Should frontier and/or osa_script('LAND', $script) launch Frontier if it is not running?

Add run_osa_script, which could take script data in a Handle or a path to a script (as with load_osa_script.

Should save have optional parameter for overwriting resource?

Should run_osa_script and execute take arguments? If so, how?

AUTHOR

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

Copyright (c) 1998-2003 Chris Nandor. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

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

VERSION

v1.02, Thursday, March 12, 2003