NAME

EV::WebKit::Client - drive an EV::WebKit browser running in another process

SYNOPSIS

Blocking, which is what you want from a shell or a one-off script:

use v5.10;                 # for say(), as the eg/ scripts do
use EV::WebKit::Client;

my $c = EV::WebKit::Client->connect("$ENV{XDG_RUNTIME_DIR}/evwk.sock");
say 'attached to: ', $c->hello->{uri} // '(nothing loaded)';

$c->go('https://example.com');
say $c->title;

my $el = $c->find('h1');
say $el->text;

Or EV-native, which is what you want inside an event loop:

use v5.10;                 # for say(), as above
use EV;                    # the blocking form above does not need this
use EV::WebKit::Client;

my $c = EV::WebKit::Client->connect($path, ev => 1, on_event => sub {
    my ($ev, $data) = @_;
    say "the browser navigated to $data->{uri}" if $ev eq 'navigate';
});

$c->go('https://example.com', sub {
    my (undef, $err) = @_;
    # ev mode delivers errors here; a die would only reach $EV::DIED
    if ($err) { warn "navigation failed: $err\n"; return EV::break }
    $c->title(sub { say $_[0] });
});

EV::run;

DESCRIPTION

The other half of EV::WebKit::Control. The EV::WebKit methods listed under "METHODS" are here, with the same name and the same arguments. That is the page-driving surface, not the whole class: whatever configures an instance locally -- the user script and style methods, the on_* handler accessors, the fingerprint accessors -- stays with the process that owns the browser, since those either take a Perl callback or describe how that instance was built.

Blocking mode (the default)

A method with no callback blocks and returns the result. Errors are croaked, carrying the browser's own error string: synchronous code has no callback to hand an error to, and croaking is how it reports one.

my $title = eval { $c->title };
warn "the browser is gone: $@" if $@;

Blocking mode is plain socket I/O -- deliberately not a nested EV::run. A nested loop inside a callback is how EV::Glib gets wedged, and a client has no business running somebody else's event loop.

A trailing callback in this mode croaks. Blocking calls return their result, so a callback there is a caller who meant ev => 1, and running it is not an option this mode has -- saying nothing would silently skip every continuation while the calls appeared to succeed.

Events that arrive while you are waiting are collected. Drain them with events, or hand connect an on_event callback. That applies to both modes: an ev-mode client built without on_event buffers them exactly as a blocking one does.

What is buffered is bounded. A page produces console output at its own pace, so a client that never drains would otherwise grow without limit inside your process: at most 10,000 undelivered events are kept, oldest discarded first. An on_event handler never loses one, since nothing is buffered for it. The browser side is bounded the same way and for the same reason -- see "SECURITY" in EV::WebKit::Control.

EV mode

my $c = EV::WebKit::Client->connect($path, ev => 1);

Every method now takes a trailing callback and returns immediately; the callback gets ($result, $err), exactly as EV::WebKit does -- so code moves between a local browser and a remote one without being rewritten. Calling a method without a callback in this mode croaks: it cannot block, because you own the loop.

If the browser goes away, every request still in flight is answered with an error rather than dropped. A dropped callback is a hung caller.

METHODS

connect, hello (the greeting frame: where the browser already was when you attached), events, path (the socket this client is attached to), disconnect, plus every EV::WebKit method: go, load_html, back, forward, reload, stop, can_go_back, can_go_forward, uri, title, is_loading, status, html, script, script_async, find, find_all, find_js, find_all_js, wait_for, wait_for_js, wait_for_navigation, press, scroll, screenshot, pdf, download, frames, resize, zoom, settings, set_user_agent, user_agent, set_proxy, show_devtools, set_cookie, cookies, clear_cookies, save_cookies, load_cookies, quit.

mock_scheme is not available remotely: its argument is a Perl callback that WebKit invokes inside the browser process, and there is nothing to send.

SEE ALSO

EV::WebKit::Control, EV::WebKit, EV::WebKit::Client::Element.