NAME

Mac::Safari::JavaScript - Run JavaScript in Safari on Mac OS X

SYNOPSIS

  use Mac::Safari::JavaScript qw(safari_js);

  # do an alert
  safari_js 'alert("Hello Safari User")';

  # return some value
  var $arrayref = safari_js 'return [1,2,3]';

  # multiple lines are okay
  safari_js <<'JAVASCRIPT';
    var fred = "bob";
    return fred;
  JAVASCRIPT
  
  # You can set variables to pass in
  safari_js 'return document.getElementById(id).href', id => "mainlink";

DESCRIPTION

This module allows you to execute JavaScript code in the Safari web browser on Mac OS X.

The current implementation wraps the JavaScript in Applescript, compiles it, and executes it in order to control Safari.

FUNCTIONS

Functions are exported on request, or may be called fully qualified.

safari_js($javascript, @named_parameters)

Runs the JavaScript in the first tab of the front window of the currently running Safari.

The script

This script may safely contain newlines, unicode characters, comments etc. Any line numbers in error messages should match up with error messages

Return value

safari_js will do a passable job of mapping whatever you returned from your JavaScript (using the return keyword) into a Perl data structure it will return. If you do not return a value from JavaScript (i.e. the return keyword is not executed) then safari_js will return the empty list. If you return nothing (i.e. use return; in your script), safari_js will return undef.

Whatever you return from your JavaScript will be encoded into JSON with Safari's native JSON.stringify function and decoded on the Perl side using the JSON::XS module.

JavaScript data structures are mapped as you might expect: Objects to hashrefs, Arrays to arrayrefs, strings and numbers to their normal scalar representation, and null, true and false to undef, JSON::XS::true (which you can treat like the scalar 1) and JSON::XS::false (which you can treat like the scalar 0) respectivly. Please see JSON::XS for more information.

You cannot return anything from JavaScript that has a ciruclar reference in it (as this cannot be represented by JSON.)

Passing Parameters

You may pass in named parameters by passing them as name/value pairs

  safari_js $js_code_to_run, name1 => $value1, name2 => $value2, ...

The parameters are simply availble as variables in your code.

Internally parameters are converted from Perl data structures into JavaScript using JSON::XS using the reverse mapping described above. You may not pass in circular data structures. Again, see JSON::XS for more infomation.

Exception Handling

If what you pass causes an uncaught exception within the Safari web browser (including exceptions during by parsing your script) then a Mac::Safari::JavaScript::Exception exception object will be raised by safari_js. This will stringify to the exception you normally would see in your browser and can be integated for extra info such as the line number, etc.

AUTHOR

Written by Mark Fowler <mark@twoshortplanks.com>

Copryright Mark Fowler 2011. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

BUGS

Bugs should be reported to me via the CPAN RT system. http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Mac::Safari::JavaScript

Some pages (e.g. http://developer.apple.com/) cause array stringifcation to break. I haven't worked out why yet.

SEE ALSO

Mac::AppleScript, Mac::Safari::JavaScript::Exception