NAME

Mozilla::Mechanize - Like WWW::Mechanize but using Gtk2::MozEmbed

SYNOPSIS

use Mozilla::Mechanize;

my $moz = Mozilla::Mechanize->new();

$moz->get( $url );

$moz->follow_link( text => $link_txt );

$moz->form_name( $form_name );
$moz->set_fields(
    username => 'yourname',
    password => 'dummy'
);
$moz->click( $btn_name );

# Or all in one go:
$moz->submit_form(
    form_name => $form_name,
    fields    => {
        username => 'yourname',
        password => 'dummy',
    },
    button    => $btn_name,
);

DESCRIPTION

This module tries to be a sort of drop-in replacement for WWW::Mechanize. It uses Mozilla's Gecko HTML-rendering engine via the modules Mozilla::DOM and Gtk2::MozEmbed.

Don't expect it to be like WWW::Mechanize in that the class is not derived from the user-agent class (like LWP).

WARNING: this was quickly ported from Win32::IE::Mechanize. The docs are incomplete and may still refer to the Win32 module. Some methods are unimplemented.

Comment from Abe, which I echo: Thank you Andy Lester for WWW::Mechanize. I ported a lot of that code and nicked most of your documentation!

Ditto from me regarding Abe Timmerman's Win32::IE::Mechanize.

CONSTRUCTION AND PROPERTIES

Mozilla::Mechanize->new( [%options] )

This initializes a new browser window and sets all the properties that are passed via the %options hash(ref). Currently supported options are: quiet, onwarn, onerror.

XXX: most `set_property' %options aren't currently supported. Currently supported Browser options are: height, width, visible, fullscreen. See set_property().

$moz->set_property( %opt )

XXX: this method is currently not supported. You can only set certain options through `new' (which see).

Allows you to set these supported properties:

visible: Set the visibility of the Browser window. Setting this to 0 iconifies the window, while setting it to 1 deiconifies it. I'd be very happy if it wasn't necessary to even create a window, but I don't believe it's possible because of the way Mozilla is implemented (layout and DOM are apparently tightly coupled).
height: Set the height of the Browser window.
width: Set the width of the Browser window.
addressbar (NOT SUPPORTED): Set the visibility of the addressbar
fullscreen: Set the Browser window to fullscreen. Setting it false unfullscreens.
resizable (NOT SUPPORTED): Set the resize-ability
statusbar (NOT SUPPORTED): Set the visibility of the statusbar
toolbar (NOT SUPPORTED): Set the visibility of the toolbar
left (NOT SUPPORTED): Set the left coordinate of the Browser window
top (NOT SUPPORTED): Set the top-coordinate of the Browser window

$moz->close

Close the Browser.

$moz->agent

Return a reference to the Browser object.

PAGE-FETCHING METHODS

$moz->get( $url )

Fetch $url.

$moz->reload()

Reload the page.

$moz->back()

Go back a page in the browser history.

STATUS METHODS

$moz->success

XXX: I don't know how to implement this yet. So this always returns true for now. In fact, if a URL doesn't exist, it'll pop up a dialog. :/

$moz->uri

Return the URI of this document (as a URI object). Note: whenever you do a submit, Mozilla appends a question mark followed by any form input (name=value pairs separated by ampersands).

$moz->ct

Fetch the content-type of the document.

$moz->current_form

Returns the current form as a Mozilla::Mechanize::Form object.

$moz->is_html

Return true if this is an HTML Document.

$moz->title

Fetch the title from the document.

CONTENT-HANDLING METHODS

$moz->content

Fetch the HTML of the document. This won't exactly match the HTML that's sent by the server... (The DOCTYPE/DTD will not be there, the <html> element is kind of generated so its attributes might be rearranged, and some linebreaks might be missing.)

LINK METHODS

$moz->links

When called in a list context, returns a list of the links found in the last fetched page. In a scalar context it returns a reference to an array with those links. The links returned are all Mozilla::Mechanize::Link objects.

$moz->follow_link( %opt )

Uses the $self->find_link() interface to locate a link and $self->get() it.

$moz->find_link( [%options] )

This method finds a link in the currently fetched page. It returns a Mozilla::Mechanize::Link object which describes the link. (You'll probably be most interested in the url() property.) If it fails to find a link it returns undef.

You can take the URL part and pass it to the get() method. If that's your plan, you might as well use the follow_link() method directly, since it does the get() for you automatically.

Note that <FRAME SRC="..."> tags are parsed out of the the HTML and treated as links so this method works with them.

You can select which link to find by passing in one or more of these key/value pairs:

text => 'string', and text_regex => qr/regex/,

text matches the text of the link against string, which must be an exact match. To select a link with text that is exactly "download", use
```
$mech->find_link( text => "download" );
```
text_regex matches the text of the link against regex. To select a link with text that has "download" anywhere in it, regardless of case, use
```
$mech->find_link( text_regex => qr/download/i );
```
Note that the text extracted from the page's links are trimmed. For example, <a> foo </a> is stored as 'foo', and searching for leading or trailing spaces will fail.
url => 'string', and url_regex => qr/regex/,

Matches the URL of the link against string or regex, as appropriate. The URL may be a relative URL, like foo/bar.html, depending on how it's coded on the page.
url_abs => string and url_abs_regex => regex

Matches the absolute URL of the link against string or regex, as appropriate. The URL will be an absolute URL, even if it's relative in the page.
name => string and name_regex => regex

Matches the name of the link against string or regex, as appropriate.
tag => string and tag_regex => regex

Matches the tag that the link came from against string or regex, as appropriate. The tag_regex is probably most useful to check for more than one tag, as in:
```
$mech->find_link( tag_regex => qr/^(a|frame)$/ );
```
The tags and attributes looked at are defined below, at $mech-find_link() : link format>.
n => number

The n parms can be combined with the text* or url* parms as a numeric modifier. For example, text => "download", n => 3 finds the 3rd link which has the exact text "download".

If n is not specified, it defaults to 1. Therefore, if you don't specify any parms, this method defaults to finding the first link on the page.

Note that you can specify multiple text or URL parameters, which will be ANDed together. For example, to find the first link with text of "News" and with "cnn.com" in the URL, use:

$moz->find_link( text => "News", url_regex => qr/cnn\.com/ );

$moz->find_all_links( %opt )

Returns all the links on the current page that match the criteria. The method for specifying link criteria is the same as in find_link(). Each of the links returned is in the same format as in find_link().

In list context, find_all_links() returns a list of the links. Otherwise, it returns a reference to the list of links.

find_all_links() with no parameters returns all links in the page.

IMAGE METHODS

$moz->images

Lists all the images on the current page. Each image is a Mozilla::Mechanize::Image object. In list context, returns a list of all images. In scalar context, returns an array reference of all images.

NOTE: Although WWW::Mechanize explicitly only supports <INPUT type=submit src="..."> constructs, this is not supported by IE, it must be: <INPUT type=image src="..."> for IE to behave as expected. (XXX: not sure if this is true for Mozilla::Mechanize)

$moz->find_image()

Finds an image in the current page. It returns a Mozilla::Mechanize::Image object which describes the image. If it fails to find an image it returns undef.

You can select which link to find by passing in one or more of these key/value pairs:

alt => 'string' and alt_regex => qr/regex/,

alt matches the ALT attribute of the image against string, which must be a n exact match. To select a image with an ALT tag that is exactly "download", use
```
$moz->find_image( alt  => "download" );
```
alt_regex matches the ALT attribute of the image against a regular expression. To select an image with an ALT attribute that has "download" anywhere in it, regardless of case, use
```
$moz->find_image( alt_regex => qr/download/i );
```
url => 'string', and url_regex => qr/regex/,

Matches the URL of the image against string or regex, as appropriate. The URL may be a relative URL, like foo/bar.html, depending on how it's coded on the page.
url_abs => string and url_abs_regex => regex

Matches the absolute URL of the image against string or regex, as appropriate. The URL will be an absolute URL, even if it's relative in the page.
tag => string and tag_regex => regex

Matches the tag that the image came from against string or regex, as appropriate. The tag_regex is probably most useful to check for more than one tag, as in:
```
$moz->find_image( tag_regex => qr/^(img|input)$/ );
```
The tags supported are <img> and <input>.

If n is not specified, it defaults to 1. Therefore, if you don't specify any parms, this method defaults to finding the first image on the page.

Note that you can specify multiple ALT or URL parameters, which will be ANDed together. For example, to find the first image with ALT text of "News" and with "cnn.com" in the URL, use:

$moz->find_image( image => "News", url_regex => qr/cnn\.com/ );

The return value is a reference to an array containing a Mozilla::Mechanize::Image object for every image in $self->content.

$moz->find_all_images( ... )

Returns all the images on the current page that match the criteria. The method for specifying image criteria is the same as in find_image(). Each of the images returned is a Mozilla::Mechanize::Image object.

In list context, find_all_images() returns a list of the images. Otherwise, it returns a reference to the list of images.

find_all_images() with no parameters returns all images in the page.

FORM METHODS

$moz->forms

Lists all the forms on the current page. Each form is an Mozilla::Mechanize::Form object. In list context, returns a list of all forms. In scalar context, returns an array reference of all forms.

$moz->form_number( $number )

Selects the numberth form on the page as the target for subsequent calls to field() and click(). Also returns the form that was selected. Emits a warning and returns undef if there is no such form. Forms are indexed from 1, so the first form is number 1, not zero.

$moz->form_name( $name )

Selects a form by name. If there is more than one form on the page with that name, then the first one is used, and a warning is generated. Also returns the form itself, or undef if it is not found.

$moz->field( $name[, $value[, $index]] )

$moz->field( $name, \@values[, $number ] )

Given the name of a field, set its value to the value specified. This applies to the current form (as set by the form_name() or form_number() method or defaulting to the first form on the page).

The optional $number parameter is used to distinguish between two fields with the same name. The fields are numbered from 1.

$moz->select( $name, $value )

$moz->select( $name, \@values )

Given the name of a select field, set its value to the value specified. If the field is not <select multiple> and the $value is an array, only the first value will be set. Passing $value as a hash with an n key selects an item by number (e.g. {n = 3> or {n = [2,4]}>). The numbering starts at 1. This applies to the current form (as set by the form() method or defaulting to the first form on the page).

Returns 1 on successfully setting the value. On failure, returns undef and calls $self-warn()> with an error message.

$moz->set_fields( %arguments )

This method sets multiple fields of a form. It takes a list of field name and value pairs. If there is more than one field with the same name, the first one found is set. If you want to select which of the duplicate field to set, use a value which is an anonymous array which has the field value and its number as the 2 elements.

# set the second foo field
$moz->set_fields( $name => [ 'foo', 2 ] ) ;

The fields are numbered from 1.

This applies to the current form (as set by the form_name() or form_number() method or defaulting to the first form on the page).

$moz->set_visible( @criteria )

This method sets fields of a form without having to know their names. So if you have a login screen that wants a username and password, you do not have to fetch the form and inspect the source to see what the field names are; you can just say

$moz->set_visible( $username, $password ) ;

and the first and second fields will be set accordingly. The method is called set_visible because it acts only on visible fields; hidden form inputs are not considered. The order of the fields is the order in which they appear in the HTML source which is nearly always the order anyone viewing the page would think they are in, but some creative work with tables could change that; caveat user.

Each element in @criteria is either a field value or a field specifier. A field value is a scalar. A field specifier allows you to specify the type of input field you want to set and is denoted with an arrayref containing two elements. So you could specify the first radio button with

$moz->set_visible( [ radio => "KCRW" ] ) ;

Field values and specifiers can be intermixed, hence

$moz->set_visible( "fred", "secret", [ select => "Checking" ] ) ;

would set the first two fields to "fred" and "secret", and the next OPTION menu field to "Checking".

The possible field specifier types are: "text", "password", "hidden", "textarea", "file", "image", "submit", "radio", "checkbox" and "select".

This method was ported from WWW::Mechanize.

$moz->tick( $name, $value[, $set] )

'Ticks' the first checkbox that has both the name and value assoicated with it on the current form. Dies if there is no named check box for that value. Passing in a false value as the third optional argument will cause the checkbox to be unticked.

$moz->untick( $name, $value )

Causes the checkbox to be unticked. Shorthand for tick( $name, $value, undef)

$mech->value( $name, $number )

Given the name of a field, return its value. This applies to the current form (as set by the form() method or defaulting to the first form on the page).

The option $number parameter is used to distinguish between two fields with the same name. The fields are numbered from 1.

If the field is of type file (file upload field), the value is always cleared to prevent remote sites from downloading your local files. To upload a file, specify its file name explicitly.

$moz->click( $button )

Call the click method on an INPUT object with the name $button. Has the effect of clicking a button on a form. The first argument is the name of the button to be clicked. I have not found a way to set the (x,y) coordinates of the click.

Note: inputs are searched in the order: buttons, images, submits.

$moz->click_button( %args )

Has the effect of clicking a button on a form by specifying its name, value, or index. Its arguments are a list of key/value pairs. Only one of name, number, or value must be specified.

name => name

Clicks the button named name.
number => n

Clicks the nth button in the form. XXX: this isn't currently working. It will select the Nth button if you assume they're gotten in the order: button, image, submit. This will presumably get fixed sometime, so I'd advise not relying on it.
value => value

Clicks the button with the value value.

NOTE: Unlike WWW::Mechanize, Mozilla::Mechanize takes all buttonish types of <INPUT type=> into account: button, image, and submit.

$moz->submit( )

Submits the page, without specifying a button to click. Actually, no button is clicked at all.

This will call the Submit() method of the currently selected form.

NOTE: It looks like this method does not call the onSubmit handler specified in the <FORM>-tag, that only seems to work if you call the click_button() method with submit button.

$moz->submit_form( %opt )

This method lets you select a form from the previously fetched page, fill in its fields, and submit it. It combines the form_number/form_name, set_fields and click methods into one higher level call. Its arguments are a list of key/value pairs, all of which are optional.

form_number => n

Selects the nth form (calls form_number()). If this parm is not specified, the currently-selected form is used.
form_name => name

Selects the form named name (calls form_name())
fields => fields

Sets the field values from the fields hashref (calls set_fields())
button => button

Clicks on button button (calls click())
button => { value => value }

When you specify a hash_ref for button it calls click_button()

If no form is selected, the first form found is used.

If button is not passed, then the submit() method is used instead.

Returns true on success.

MISCELANEOUS METHODS

XXX: don't know how to add headers, so this is unsupported

$moz->add_header( name => $value [, name => $value... ] )

Sets HTTP headers for the agent to add or remove from the HTTP request.

$moz->add_header( Encoding => 'text/klingon' );

If a value is undef, then that header will be removed from any future requests. For example, to never send a Referer header:

$moz->add_header( Referer => undef );

Returns the number of name/value pairs added.

$moz->delete_header( name [, name ... ] )

XXX: don't know how to add headers, so this is unsupported

Removes HTTP headers from the agent's list of special headers.

NOTE: This might not work like it does with WWW::Mechanize

$moz->quiet( [$state] )

Allows you to suppress warnings to the screen.

$a->quiet(0); # turns on warnings (the default)
$a->quiet(1); # turns off warnings
$a->quiet();  # returns the current quietness status

$moz->find_frame( $frame_name )

Returns the URL to the source of the frame with name eq $frame_name

$moz->load_frame( $frame_name )

$self->get( $self->find_frame( $frame_name ))

DOM CONVENIENCE METHODS

$moz->get_window;

Convenience method to get the Window (Mozilla::DOM::Window). (This is the `window' browser object in JavaScript.)

$moz->get_document;

Convenience method to get the Document (Mozilla::DOM::Document). (This is the `document' browser object in JavaScript.)

$moz->get_document_element;

Convenience method to get the document element (Mozilla::DOM::Element). (Actually this is a Mozilla::DOM::HTMLHtmlElement, i.e. <html>, if you want to QueryInterface to it). This is useful for calling GetElementsByTagName.

LWP COMPATABILITY METHODS

$moz->credentials( $netloc, $realm, $uid, $pass )

XXX: don't know how to add headers, so this is unsupported

Set the user name and password to be used for a realm.

$netloc looks like hostname:port.

$moz->get_basic_credentials( $realm, $uri )

XXX: don't know how to add headers, so this is unsupported

This is called by _extra_headers to retrieve credentials for documents protected by Basic Authentication. The arguments passed in are the $realm and the $uri requested.

The method should return a username and password. It should return an empty list to abort the authentication resolution attempt.

The base implementation simply checks a set of pre-stored member variables, set up with the credentials() method.

$moz->set_realm( $netloc, $realm );

XXX: don't know how to add headers, so this is unsupported

Sets the authentication realm to $realm for $netloc. An empty value unsets the realm for $netloc.

$netloc looks like hostname:port.

As I have not found a way to access response-headers, I cannot find out the authentication realm (if any) and automagically set the right headers. You will have to do some bookkeeping for now.

INTERNAL-ONLY METHODS

DESTROY

Close the browser.

$moz->_extract_forms()

Return a list of forms. All forms are mapped onto the Mozilla::Mechanize::Form interface that mimics HTML::Form.

$self->_extract_links()

The links come from the following:

"<A HREF=...>"
"<AREA HREF=...>"
"<FRAME SRC=...>": Note: only works within a <frameset>
"<IFRAME SRC=...>": Note: this must be like <iframe ...></iframe>

$moz->_extract_images()

Return a list of images. All images are mapped onto the Mozilla::Mechanize::Image interface that mimics WWW::Mechanize::Image.

$self->_wait_while_busy()

This adds a "single-shot" idle callback that does Gtk2->main_quit, then does Gtk2->main. The result is that whenever the UI becomes idle it will exit the main loop. Thanks to muppet for the idea. This is repeated until the net_stop event fires, indicating that the new page has finished loading. (Note therefore that you can only call this when you expect a new page to load.)

warn( @messages )

Centralized warning method, for diagnostics and non-fatal problems. Defaults to calling CORE::warn, but may be overridden by setting onwarn in the construcotr.

die( @messages )

Centralized error method. Defaults to calling CORE::die, but may be overridden by setting onerror in the constructor.

$self->_extra_headers( )

(XXX: Not implemented.) For the moment we only support basic authentication.

INTERNAL ONLY NON-METHODS

__prop_value( $key[, $value] )

Check to see if we support the property $key and return a validated value or the default value from %moz_properties.

__authorization_basic( $user, $pass )

(XXX: Not implemented.) Return a HTTP "Authorization: Basic xxx" header.

BUGS

Send bugs directly to me or use http://rt.cpan.org/NoAuth/Bugs.html?Dist=Mozilla-Mechanize.

CREDITS

See Credits. In particular, I acknowledge having copied a lot of the code from Win32::IE::Mechanize, by Abe Timmerman.

COPYRIGHT AND LICENSE

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

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

To install Mozilla::Mechanize, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Mozilla::Mechanize

CPAN shell

perl -MCPAN -e shell
install Mozilla::Mechanize

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

CONSTRUCTION AND PROPERTIES

Mozilla::Mechanize->new( [%options] )

$moz->set_property( %opt )

$moz->close

$moz->agent

PAGE-FETCHING METHODS

$moz->get( $url )

$moz->reload()

$moz->back()

STATUS METHODS

$moz->success

$moz->uri

$moz->ct

$moz->current_form

$moz->is_html

$moz->title

CONTENT-HANDLING METHODS

$moz->content

LINK METHODS

$moz->links

$moz->follow_link( %opt )

$moz->find_link( [%options] )

$moz->find_all_links( %opt )

IMAGE METHODS

$moz->images

$moz->find_image()

$moz->find_all_images( ... )

FORM METHODS

$moz->forms

$moz->form_number( $number )

$moz->form_name( $name )

$moz->field( $name[, $value[, $index]] )

$moz->field( $name, \@values[, $number ] )

$moz->select( $name, $value )

$moz->select( $name, \@values )

$moz->set_fields( %arguments )

$moz->set_visible( @criteria )

$moz->tick( $name, $value[, $set] )

$moz->untick( $name, $value )

$mech->value( $name, $number )

$moz->click( $button )

$moz->click_button( %args )

$moz->submit( )

$moz->submit_form( %opt )

MISCELANEOUS METHODS

$moz->add_header( name => $value [, name => $value... ] )

$moz->delete_header( name [, name ... ] )

$moz->quiet( [$state] )

$moz->find_frame( $frame_name )

$moz->load_frame( $frame_name )

DOM CONVENIENCE METHODS

$moz->get_window;

$moz->get_document;

$moz->get_document_element;

LWP COMPATABILITY METHODS

$moz->credentials( $netloc, $realm, $uid, $pass )

$moz->get_basic_credentials( $realm, $uri )

$moz->set_realm( $netloc, $realm );

INTERNAL-ONLY METHODS

DESTROY

$moz->_extract_forms()

$self->_extract_links()

$moz->_extract_images()

$self->_wait_while_busy()

warn( @messages )

die( @messages )

$self->_extra_headers( )

INTERNAL ONLY NON-METHODS

__prop_value( $key[, $value] )

__authorization_basic( $user, $pass )

BUGS

SEE ALSO

CREDITS

COPYRIGHT AND LICENSE

Module Install Instructions