Simple(3) User Contributed Perl Documentation Simple(3)NAMEMac::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".
NOTE: Examples below show use of $^E. On Mac OS, this will return the
signed Mac OS error number in numeric context, and the Mac OS error
message in string context. But on Mac OS X, $^E support is
unimplemented. $! and $^E will both return the unsigned error number.
You can get the correct error number by adding 0 (such as "$! + 0"),
and you can use Mac::Errors to get the error text (this will also work
under Mac OS):
use Mac::Errors '$MacError';
my $res = FSpOpenResFile($file, 0) or die $MacError;
See Mac::Errors on the CPAN for more information.
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.
call(CLASS, EVENT, ARGS, MODE)
Calls a handler in the script, identified by CLASS and EVENT IDs.
Can be executed more than once.
ARGS can be either a scalar or an arrayref. MODE can be any
combination of modes from Mac::OSA listed under the "Mode flags"
constants.
Here is an example script:
on \xC7event abcd1234E\xC8 (filename)
tell app "Finder"
return [URL of file filename, creator type of file filename]
end
end
"abcd" is the CLASS ID, and "1234" is the EVENT ID. They can be
anything, as long as they don't conflict with something else. The
characters \xC7 and \xC8 can be literal if in the Mac Roman
charset, otherwise just use the values like above.
Parameters are passed to handlers as named values, like
"(filename)". Multiple parameters can be passed as an arrayref in
ARGS, and a list of values is returned:
my $script = load_osa_script($path_to_script);
my($url, $creator) = $script->call(qw[abcd 1234], "my file");
You must pass in the same number of variables in ARGS that are
expected by the handler.
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 or file!
Saves to the data fork instead on Mac OS X, unless an ID is
provided.
The context used to load a script from disk (resource fork vs. data
fork, resource file vs. data file) will be used to save the script
back, if applicable, so the file's format will be preserved.
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.
perl v5.16.2 2005-06-01 Simple(3)
