/ 
MacPerl-AppleScript-0.02
River stage zero No dependents
/ MacPerl::AppleScript

NAME

MacPerl::AppleScript - Perl extension for easily accessing scriptable Apps

SYNOPSIS

use MacPerl::AppleScript;

#
# create Application Object
#
my $app = MacPerl::AppleScript->new("Application Name");

my $doc1 = $application->new("document 1");
my $doc2 = $application->new("document 2 of $app");

#
# directly execute Script in Application
# (auto-creates a tell "Application Name" block for you
#
$app->execute("some applescript command");
$app->execute(["some applescript command", "..." ... ]);
$app->execute("some applescript command", "..." ... );

#
# alternative way using a hashref
#   script: script to get executed (string or array-ref)
#   object: optional, object to be named in the "tell" block
#   timeout: optional, timeout in seconds
#
$app->execute({
                script => [...],
                object => $doc1,
                timeout => 10,
              });


#
# calling functions
#
$app->open('POSIX path "/path/to/file" as alias');
$app->open($app->convert_path('/path/to/file','alias'));
$doc->close();
$app->close($doc1);

#
# string interpolation to Applescript Object Name
# gets 'application "Application Name"' for $application
# gets 'document 1 of application "Application Name"' for $doc1
#
my $ascript_appname = "$app";
my $ascript_docname = "$doc1";

$app->execute("close $doc1");  # cool :-)

#
# getting/setting properties
#
my $foo_property = $app->{foo};

my $foo_bar_prop = $doc1->{'foo bar'};
my $foo_bar_prop = $doc1->{foo_bar};

$app->{bar} = "any value";

$doc1->{'foo bar'} = [1,2,3,4];
$doc1->{foo_bar} = {a=>1, b=>2};

my %properties = %{$app};

DESCRIPTION

This module is not written for being efficient. In fact it is really inefficient but hopefully easy to use :-)

As AppleScript (and its way of communicating to Applications) usually has some kind of latency. The creation of readable code is the most important goal when writing this Module.

Another reason for some kind of inefficiency results in the technical problem that AppleScript is a strongly typed language. Converting types back to Perl is easy. But the other direction is not always clear, as converting a scalar from Perl to AppleScript needs some guessing :-(

The parts of the code that deal with these problems do some tries with different AppleScript commands wrapped in try-blocks. So usually one of the expression works without errors. The same approach is made with hash keys that can contain spaces or underscores inside the key name.

This module assumes that all strings are correctly encoded in perl internal's coding sheme based on Unicode. During the conversion to AppleScript all characters inside strings that are not ascii-clean are converted to strange looking unicode-string constructing sequences. I tested a lot of character schemes including west- and mid-european languages as well as russian, greek and arabic with some applications without getting problems.

USAGE

use MacPerl::AppleScript;

there are no special options for the usage of this module.

APPLESCRIPT OBJECTS

Internally a MacPerl::AppleScript Object simply is something that knows the name of itself, its parent and the application it belongs to. There is some caching inside. Constructing two objects for the same AppleScript-Object results in the same Perl Object if the names are the same. If the names differ (eg. 'foo id 13' and 'foo 1') but refer to the same AppleScript Object, the MacPerl::AppleScript Objects will be different, as this module only identifies things by their name.

my $app = MacPerl::AppleScript->new('application "MyApp"');
my $app = MacPerl::AppleScript->new('MyApp');

my $doc = MacPerl::AppleScript->new('document 1 of application "MyApp"');
my $doc = MacPerl::AppleScript->new("document 1 of $app");
my $doc = $app->new('document 1');

my $par = MacPerl::AppleScript->new('paragraph 1 of document 1 of application "MyApp"');
my $par = MacPerl::AppleScript->new("paragraph 1 of document 1 of $app");
my $par = MacPerl::AppleScript->new("paragraph 1 of $doc");
my $par = $app->new("paragraph 1 of $doc");
my $par = $doc->new('paragraph 1');

All grouped forms above are equivalent and give exactly the same result. Note that in a string-context an object interpolates to its AppleScript Name known from the moment of its construction.

SIMPLE METHODS

$obj->name()

delivers the name of an object in fully qualified form as used inside AppleScript, e.g. 'application "MyApp"' or 'document 1 of application "MyApp"'.

$obj->app()

gives back the Object of the application this Object belongs to. An application object returns itself.

$obj->parent()

gives back the parent Object of this one. Application objects do not have a parent object. In this case, undef is returned. (We do not reflect the real AppleScript hierarchy hiere where everything is a descendant of 'script "AppleScript"' that magically encloses every code you write.)

SCRIPT EXECUTION

$obj->execute("one line script here");
$obj->execute("first line","second line", ...);
$obj->execute(["first line","second line",...]);

This simple execution format constructs an AppleScript "tell" Block for the object on which the execute is called and puts the line(s) inside the tell block. There is no guarantee that this execute ever returns or that it will not die... Using the timeout feature (below) will prevent the first, using an eval{} around will prevent the second.

If the AppleScript run returns something, it will be returned as a Perl data structure reflecting the AppleScript data returned.

$obj->execute({script => string or array_ref,
               timeout => seconds,
               object => some_object });

Here, a timeout in full seconds may be given, or the object to be named in the "tell" Block can get specified. The script may be a simple string or an array-ref of script-lines.

Another way of getting AppleScript code to execute is by calling the method directly. Internally the functions are resolved by Perl's AUTOLOAD feature. Calling an undefined function of this class triggers the AUTOLOAD function, that converts its caller and the parameters to an AppleScript code sequence.

$obj->someFunction();

makes a "tell" block for $obj and "someFunction" as the AppleScript function to get executed.

$obj->someFunction("argument1", "argument2", ...);

appends the space-separated arguments to the function call. If any argument is an object, a hash or an array, the correct form for AppleScript is used. Scalars are insert as they are. If you need args quoted, you will have to add them on your own.

PROPERTIES AND INTERPOLATION

All AppleScript Objects have some magic features built in.

"$obj"

In String context, an object interpolates to its name inserting exactly the same result as the $obj-name()> function call returns. This allows you to use the object name inside an AppleScript you like to constuct, giving you the meaning of this object in the right context.

An Object may get accessed like a Hash reference.

$obj->{'property name'}
$obj->{property_name}
%properties = %{$obj};

Access a property of the object by either using the AppleScript commands "get ..." or "set ... to" to get the job done.

The key of the property may be written correct or in a simplified form using underscores instead of spaces. Technically, both forms are tried as AppleScript commands. The first successful set/get wins.

Retrieved values are converted to their Perl structures. Referred Objects inside other objects are returned as MacPerl::AppleScript Object (or subclasses hereof) references.

Setting values needs guessing of the right AppleScript datatype. 123 and '123' will both result in an Integer Object inside AppleScript. In doubtful cases, put the entire contents in "" quotes '"123"' in this case.

CLASS METHODS

Working with paths and filenames in AppleScript is a bit nasty as it is not always clear how to use Mac and Unix paths.

$self->convert_path('volume:folder:file')
  returns 'file "volume:folder:file"'

$self->convert_path('volume:folder:file', 'string')
  returns 'file "volume:folder:file" as string'

$self->convert_path('/path/to/file', 'alias')
  returns 'POSIX file "/path/to/file" as alias'

SUBCLASSING

When building new classes based on MacPerl::AppleScript, there is one feature that might help.

Every result that comes back from AppleScript is parsed as a text and then converted to some Perl data structure. During this step all things that look like AppleScript Objects are converted using a call like MacPerl::AppleScript->new('some name');

Usually all objects created like that are objects of the base class. However, if you like to get all 'foo of application "xx"' to be an Object of 'MacPerl::XX::Foo' then you could force that behaviour.

$self->register_class('foo of application "xx"', 'MacPerl::XX::Foo');
  or
$self->register_class('foo of xx', 'MacPerl::XX::Foo');
  or
$self->register_class(['foo','application "xx"'], 'MacPerl::XX::Foo');
  or
$self->register_class(['foo','xx'], 'MacPerl::XX::Foo');

as a step inside your class (maybe inside a BEGIN block) will do that job. The left side is a collection of 'of' separated items or an array reference that act as regular expressions to match the beginning of object names.

If multiple registrations are made like this, they are evaluated in unpredictable order of their definition stopping at the first match. Doing a registration multiple times will not hurt, as internally the registrations are stored in a HoH structure.

$self->get_registered_class(['foo','application "xx"'])
  returns 'MacPerl::XX::Foo'

usually the latter function need never get called by a subclass, as the magic of finding the class name occurs behind the scenes automatically.

EXPORT

None by default.

All defined subroutines are accessed as object-methods or indirectly by overloaded functionality.

SEE ALSO

MacPerl
  this module uses the AppleScript sending routines of MacPerl.

Mac::Glue
  this is an alternative to this module.

Mac::AppleEvents
  for the brave people who want to compose AppleEvents on their own.

Mac::AppleScript
  yet another alternative to executing AppleScript

BUGS

probably many :-(

Please do not shame me too much, as this is my first CPAN module. There are a couple of things that can be improved. Marying two completely different worlds is not an easy task. If you do have any idea on how to improve things, please drop me a short mail.

AUTHOR

Wolfgang Kinkeldei, <wolfgang@kinkeldei.de>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Wolfgang Kinkeldei

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.