view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

Accessing an object as an array will mainly work. For
determining the `length`, it is assumed that the
object has a `.length` method. If the method has
a different name, you will have to access the object
as a hash with the index as the key.

Note that `push` expects the underlying object
to have a `.push()` Javascript method, and `pop`
gets mapped to the `.pop()` Javascript method.

# OBJECT IDENTITY

Object identity is currently implemented by
overloading the `==` operator.
Two objects are considered identical
if the javascript `===` operator
returns true.

    my $obj_a = MozRepl::RemoteObject->expr('window.document');
    print $obj_a->__id(),"\n"; # 42
    my $obj_b = MozRepl::RemoteObject->expr('window.document');
    print $obj_b->__id(), "\n"; #43
    print $obj_a == $obj_b; # true

# CALLING METHODS

Calling methods on a Javascript object is supported.

All arguments will be autoquoted if they contain anything
other than ASCII digits (`[0-9]`). There currently
is no way to specify that you want an all-digit parameter
to be put in between double quotes.

Passing MozRepl::RemoteObject objects as parameters in Perl
passes the proxied Javascript object as parameter to the Javascript method.

As in Javascript, functions are first class objects, the following
two methods of calling a function are equivalent:

    $window->loadURI('http://search.cpan.org/');

    $window->{loadURI}->('http://search.cpan.org/');

# EVENTS / CALLBACKS

This module also implements a rudimentary asynchronous
event dispatch mechanism. Basically, it allows you
to write code like this and it will work:

    $window->addEventListener('load', sub {
         my ($event) = @_;
         print "I got a " . $event->{type} . " event\n";
         print "on " . $event->{originalTarget};
    });
    # do other things...

Note that you cannot block the execution of Javascript that way.
The Javascript code has long continued running when you receive
the event.

Currently, only busy-waiting is implemented and there is no
way yet for Javascript to tell Perl it has something to say.
So in absence of a real mainloop, you have to call

    $repl->poll;

from time to time to look for new events. Note that _any_
call to Javascript will carry all events back to Perl and trigger
the handlers there, so you only need to use poll if no other
activity happens.

In the long run,
a move to [AnyEvent](https://metacpan.org/pod/AnyEvent) would make more sense, but currently,
MozRepl::RemoteObject is still under heavy development on
many fronts so that has been postponed.

# OBJECT METHODS

These methods are considered to be internal. You usually
do not want to call them from your code. They are
documented here for the rare case you might need to use them directly
instead of treating the objects as Perl structures. The
official way to access these functions is by using
[MozRepl::RemoteObject::Methods](https://metacpan.org/pod/MozRepl::RemoteObject::Methods) instead.

## `$obj->__invoke(METHOD, ARGS)`

The `->__invoke()` object method is an alternate way to
invoke Javascript methods. It is normally equivalent to
`$obj->$method(@ARGS)`. This function must be used if the
METHOD name contains characters not valid in a Perl variable name
(like foreign language characters).
To invoke a Javascript objects native `__invoke` method (if such a
thing exists), please use:

    $object->MozRepl::RemoteObject::Methods::invoke::invoke('__invoke', @args);

The same method can be used to call the Javascript functions with the
same name as other convenience methods implemented
by this package:

    __attr
    __setAttr
    __xpath
    __click
    ...

## `$obj->__transform_arguments(@args)`

This method transforms the passed in arguments to their JSON string
representations.

Things that match ` /^(?:[1-9][0-9]*|0+)$/ ` get passed through.

MozRepl::RemoteObject::Instance instances
are transformed into strings that resolve to their
Javascript global variables. Use the `->expr` method
to get an object representing these.

It's also impossible to pass a negative or fractional number
as a number through to Javascript, or to pass digits as a Javascript string.