local-lib5/man/man3/WWW::Mechanize.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "WWW::Mechanize 3"
 127 .TH WWW::Mechanize 3 "2009-08-17" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 WWW::Mechanize \- Handy web browsing in a Perl object
 134 .SH "VERSION"
 135 .IX Header "VERSION"
 136 Version 1.60
 137 .SH "SYNOPSIS"
 138 .IX Header "SYNOPSIS"
 139 \&\f(CW\*(C`WWW::Mechanize\*(C'\fR, or Mech for short, helps you automate interaction with
 140 a website. It supports performing a sequence of page fetches including
 141 following links and submitting forms. Each fetched page is parsed and
 142 its links and forms are extracted. A link or a form can be selected, form
 143 fields can be filled and the next page can be fetched. Mech also stores
 144 a history of the URLs you've visited, which can be queried and revisited.
 145 .PP
 146 .Vb 2
 147 \&    use WWW::Mechanize;
 148 \&    my $mech = WWW::Mechanize\->new();
 149 \&
 150 \&    $mech\->get( $url );
 151 \&
 152 \&    $mech\->follow_link( n => 3 );
 153 \&    $mech\->follow_link( text_regex => qr/download this/i );
 154 \&    $mech\->follow_link( url => \*(Aqhttp://host.com/index.html\*(Aq );
 155 \&
 156 \&    $mech\->submit_form(
 157 \&        form_number => 3,
 158 \&        fields      => {
 159 \&            username    => \*(Aqmungo\*(Aq,
 160 \&            password    => \*(Aqlost\-and\-alone\*(Aq,
 161 \&        }
 162 \&    );
 163 \&
 164 \&    $mech\->submit_form(
 165 \&        form_name => \*(Aqsearch\*(Aq,
 166 \&        fields    => { query  => \*(Aqpot of gold\*(Aq, },
 167 \&        button    => \*(AqSearch Now\*(Aq
 168 \&    );
 169 .Ve
 170 .PP
 171 Mech is well suited for use in testing web applications.  If you use
 172 one of the Test::*, like Test::HTML::Lint modules, you can check the
 173 fetched content and use that as input to a test call.
 174 .PP
 175 .Vb 2
 176 \&    use Test::More;
 177 \&    like( $mech\->content(), qr/$expected/, "Got expected content" );
 178 .Ve
 179 .PP
 180 Each page fetch stores its \s-1URL\s0 in a history stack which you can
 181 traverse.
 182 .PP
 183 .Vb 1
 184 \&    $mech\->back();
 185 .Ve
 186 .PP
 187 If you want finer control over your page fetching, you can use
 188 these methods. \f(CW\*(C`follow_link\*(C'\fR and \f(CW\*(C`submit_form\*(C'\fR are just high
 189 level wrappers around them.
 190 .PP
 191 .Vb 7
 192 \&    $mech\->find_link( n => $number );
 193 \&    $mech\->form_number( $number );
 194 \&    $mech\->form_name( $name );
 195 \&    $mech\->field( $name, $value );
 196 \&    $mech\->set_fields( %field_values );
 197 \&    $mech\->set_visible( @criteria );
 198 \&    $mech\->click( $button );
 199 .Ve
 200 .PP
 201 WWW::Mechanize is a proper subclass of LWP::UserAgent and
 202 you can also use any of LWP::UserAgent's methods.
 203 .PP
 204 .Vb 1
 205 \&    $mech\->add_header($name => $value);
 206 .Ve
 207 .PP
 208 Please note that Mech does \s-1NOT\s0 support JavaScript.  Please check the
 209 \&\s-1FAQ\s0 in WWW::Mechanize::FAQ for more.
 210 .SH "IMPORTANT LINKS"
 211 .IX Header "IMPORTANT LINKS"
 212 .IP "\(bu" 4
 213 <http://code.google.com/p/www\-mechanize/issues/list>
 214 .Sp
 215 The queue for bugs & enhancements in WWW::Mechanize and
 216 Test::WWW::Mechanize.  Please note that the queue at <http://rt.cpan.org>
 217 is no longer maintained.
 218 .IP "\(bu" 4
 219 <http://search.cpan.org/dist/WWW\-Mechanize/>
 220 .Sp
 221 The \s-1CPAN\s0 documentation page for Mechanize.
 222 .IP "\(bu" 4
 223 <http://search.cpan.org/dist/WWW\-Mechanize/lib/WWW/Mechanize/FAQ.pod>
 224 .Sp
 225 Frequently asked questions.  Make sure you read here \s-1FIRST\s0.
 226 .SH "CONSTRUCTOR AND STARTUP"
 227 .IX Header "CONSTRUCTOR AND STARTUP"
 228 .SS "\fInew()\fP"
 229 .IX Subsection "new()"
 230 Creates and returns a new WWW::Mechanize object, hereafter referred to as
 231 the \*(L"agent\*(R".
 232 .PP
 233 .Vb 1
 234 \&    my $mech = WWW::Mechanize\->new()
 235 .Ve
 236 .PP
 237 The constructor for WWW::Mechanize overrides two of the parms to the
 238 LWP::UserAgent constructor:
 239 .PP
 240 .Vb 2
 241 \&    agent => \*(AqWWW\-Mechanize/#.##\*(Aq
 242 \&    cookie_jar => {}    # an empty, memory\-only HTTP::Cookies object
 243 .Ve
 244 .PP
 245 You can override these overrides by passing parms to the constructor,
 246 as in:
 247 .PP
 248 .Vb 1
 249 \&    my $mech = WWW::Mechanize\->new( agent => \*(Aqwonderbot 1.01\*(Aq );
 250 .Ve
 251 .PP
 252 If you want none of the overhead of a cookie jar, or don't want your
 253 bot accepting cookies, you have to explicitly disallow it, like so:
 254 .PP
 255 .Vb 1
 256 \&    my $mech = WWW::Mechanize\->new( cookie_jar => undef );
 257 .Ve
 258 .PP
 259 Here are the parms that WWW::Mechanize recognizes.  These do not include
 260 parms that LWP::UserAgent recognizes.
 261 .IP "\(bu" 4
 262 \&\f(CW\*(C`autocheck => [0|1]\*(C'\fR
 263 .Sp
 264 Checks each request made to see if it was successful.  This saves
 265 you the trouble of manually checking yourself.  Any errors found
 266 are errors, not warnings.
 267 .Sp
 268 The default value is \s-1ON\s0, unless it's being subclassed, in which
 269 case it is \s-1OFF\s0.  This means that standalone WWW::Mechanizeinstances
 270 have autocheck turned on, which is protective for the vast majority
 271 of Mech users who don't bother checking the return value of \fIget()\fR
 272 and \fIpost()\fR and can't figure why their code fails. However, if
 273 WWW::Mechanize is subclassed, such as for Test::WWW::Mechanize
 274 or Test::WWW::Mechanize::Catalyst, this may not be an appropriate
 275 default, so it's off.
 276 .IP "\(bu" 4
 277 \&\f(CW\*(C`noproxy => [0|1]\*(C'\fR
 278 .Sp
 279 Turn off the automatic call to the LWP::UserAgent \f(CW\*(C`env_proxy\*(C'\fR function.
 280 .Sp
 281 This needs to be explicitly turned off if you're using Crypt::SSLeay to
 282 access a https site via a proxy server.  Note: you still need to set your
 283 \&\s-1HTTPS_PROXY\s0 environment variable as appropriate.
 284 .IP "\(bu" 4
 285 \&\f(CW\*(C`onwarn => \e&func\*(C'\fR
 286 .Sp
 287 Reference to a \f(CW\*(C`warn\*(C'\fR\-compatible function, such as \f(CW\*(C`L<Carp>::carp\*(C'\fR,
 288 that is called when a warning needs to be shown.
 289 .Sp
 290 If this is set to \f(CW\*(C`undef\*(C'\fR, no warnings will ever be shown.  However,
 291 it's probably better to use the \f(CW\*(C`quiet\*(C'\fR method to control that behavior.
 292 .Sp
 293 If this value is not passed, Mech uses \f(CW\*(C`Carp::carp\*(C'\fR if Carp is
 294 installed, or \f(CW\*(C`CORE::warn\*(C'\fR if not.
 295 .IP "\(bu" 4
 296 \&\f(CW\*(C`onerror => \e&func\*(C'\fR
 297 .Sp
 298 Reference to a \f(CW\*(C`die\*(C'\fR\-compatible function, such as \f(CW\*(C`L<Carp>::croak\*(C'\fR,
 299 that is called when there's a fatal error.
 300 .Sp
 301 If this is set to \f(CW\*(C`undef\*(C'\fR, no errors will ever be shown.
 302 .Sp
 303 If this value is not passed, Mech uses \f(CW\*(C`Carp::croak\*(C'\fR if Carp is
 304 installed, or \f(CW\*(C`CORE::die\*(C'\fR if not.
 305 .IP "\(bu" 4
 306 \&\f(CW\*(C`quiet => [0|1]\*(C'\fR
 307 .Sp
 308 Don't complain on warnings.  Setting \f(CW\*(C`quiet => 1\*(C'\fR is the same as
 309 calling \f(CW\*(C`$mech\->quiet(1)\*(C'\fR.  Default is off.
 310 .IP "\(bu" 4
 311 \&\f(CW\*(C`stack_depth => $value\*(C'\fR
 312 .Sp
 313 Sets the depth of the page stack that keeps track of all the
 314 downloaded pages. Default is effectively infinite stack size.  If
 315 the stack is eating up your memory, then set this to a smaller
 316 number, say 5 or 10.  Setting this to zero means Mech will keep no
 317 history.
 318 .PP
 319 To support forms, WWW::Mechanize's constructor pushes \s-1POST\s0
 320 on to the agent's \f(CW\*(C`requests_redirectable\*(C'\fR list (see also
 321 LWP::UserAgent.)
 322 .ie n .SS "$mech\->agent_alias( $alias )"
 323 .el .SS "\f(CW$mech\fP\->agent_alias( \f(CW$alias\fP )"
 324 .IX Subsection "$mech->agent_alias( $alias )"
 325 Sets the user agent string to the expanded version from a table of actual user strings.
 326 \&\fI\f(CI$alias\fI\fR can be one of the following:
 327 .IP "\(bu" 4
 328 Windows \s-1IE\s0 6
 329 .IP "\(bu" 4
 330 Windows Mozilla
 331 .IP "\(bu" 4
 332 Mac Safari
 333 .IP "\(bu" 4
 334 Mac Mozilla
 335 .IP "\(bu" 4
 336 Linux Mozilla
 337 .IP "\(bu" 4
 338 Linux Konqueror
 339 .PP
 340 then it will be replaced with a more interesting one.  For instance,
 341 .PP
 342 .Vb 1
 343 \&    $mech\->agent_alias( \*(AqWindows IE 6\*(Aq );
 344 .Ve
 345 .PP
 346 sets your User-Agent to
 347 .PP
 348 .Vb 1
 349 \&    Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)
 350 .Ve
 351 .PP
 352 The list of valid aliases can be returned from \f(CW\*(C`known_agent_aliases()\*(C'\fR.  The current list is:
 353 .IP "\(bu" 4
 354 Windows \s-1IE\s0 6
 355 .IP "\(bu" 4
 356 Windows Mozilla
 357 .IP "\(bu" 4
 358 Mac Safari
 359 .IP "\(bu" 4
 360 Mac Mozilla
 361 .IP "\(bu" 4
 362 Linux Mozilla
 363 .IP "\(bu" 4
 364 Linux Konqueror
 365 .SS "\fIknown_agent_aliases()\fP"
 366 .IX Subsection "known_agent_aliases()"
 367 Returns a list of all the agent aliases that Mech knows about.
 368 .SH "PAGE-FETCHING METHODS"
 369 .IX Header "PAGE-FETCHING METHODS"
 370 .ie n .SS "$mech\->get( $uri )"
 371 .el .SS "\f(CW$mech\fP\->get( \f(CW$uri\fP )"
 372 .IX Subsection "$mech->get( $uri )"
 373 Given a \s-1URL/URI\s0, fetches it.  Returns an HTTP::Response object.
 374 \&\fI\f(CI$uri\fI\fR can be a well-formed \s-1URL\s0 string, a \s-1URI\s0 object, or a
 375 WWW::Mechanize::Link object.
 376 .PP
 377 The results are stored internally in the agent object, but you don't
 378 know that.  Just use the accessors listed below.  Poking at the
 379 internals is deprecated and subject to change in the future.
 380 .PP
 381 \&\f(CW\*(C`get()\*(C'\fR is a well-behaved overloaded version of the method in
 382 LWP::UserAgent.  This lets you do things like
 383 .PP
 384 .Vb 1
 385 \&    $mech\->get( $uri, \*(Aq:content_file\*(Aq => $tempfile );
 386 .Ve
 387 .PP
 388 and you can rest assured that the parms will get filtered down
 389 appropriately.
 390 .PP
 391 \&\fB\s-1NOTE:\s0\fR Because \f(CW\*(C`:content_file\*(C'\fR causes the page contents to be
 392 stored in a file instead of the response object, some Mech functions
 393 that expect it to be there won't work as expected. Use with caution.
 394 .ie n .SS "$mech\->put( $uri, content => $content )"
 395 .el .SS "\f(CW$mech\fP\->put( \f(CW$uri\fP, content => \f(CW$content\fP )"
 396 .IX Subsection "$mech->put( $uri, content => $content )"
 397 PUTs \fI\f(CI$content\fI\fR to \f(CW$uri\fR.  Returns an HTTP::Response object.
 398 \&\fI\f(CI$uri\fI\fR can be a well-formed \s-1URI\s0 string, a \s-1URI\s0 object, or a
 399 WWW::Mechanize::Link object.
 400 .ie n .SS "$mech\->\fIreload()\fP"
 401 .el .SS "\f(CW$mech\fP\->\fIreload()\fP"
 402 .IX Subsection "$mech->reload()"
 403 Acts like the reload button in a browser: repeats the current
 404 request. The history (as per the \*(L"back\*(R" method) is not altered.
 405 .PP
 406 Returns the HTTP::Response object from the reload, or \f(CW\*(C`undef\*(C'\fR
 407 if there's no current request.
 408 .ie n .SS "$mech\->\fIback()\fP"
 409 .el .SS "\f(CW$mech\fP\->\fIback()\fP"
 410 .IX Subsection "$mech->back()"
 411 The equivalent of hitting the \*(L"back\*(R" button in a browser.  Returns to
 412 the previous page.  Won't go back past the first page. (Really, what
 413 would it do if it could?)
 414 .PP
 415 Returns true if it could go back, or false if not.
 416 .SH "STATUS METHODS"
 417 .IX Header "STATUS METHODS"
 418 .ie n .SS "$mech\->\fIsuccess()\fP"
 419 .el .SS "\f(CW$mech\fP\->\fIsuccess()\fP"
 420 .IX Subsection "$mech->success()"
 421 Returns a boolean telling whether the last request was successful.
 422 If there hasn't been an operation yet, returns false.
 423 .PP
 424 This is a convenience function that wraps \f(CW\*(C`$mech\->res\->is_success\*(C'\fR.
 425 .ie n .SS "$mech\->\fIuri()\fP"
 426 .el .SS "\f(CW$mech\fP\->\fIuri()\fP"
 427 .IX Subsection "$mech->uri()"
 428 Returns the current \s-1URI\s0 as a \s-1URI\s0 object. This object stringifies
 429 to the \s-1URI\s0 itself.
 430 .ie n .SS "$mech\->\fIresponse()\fP / $mech\->\fIres()\fP"
 431 .el .SS "\f(CW$mech\fP\->\fIresponse()\fP / \f(CW$mech\fP\->\fIres()\fP"
 432 .IX Subsection "$mech->response() / $mech->res()"
 433 Return the current response as an HTTP::Response object.
 434 .PP
 435 Synonym for \f(CW\*(C`$mech\->response()\*(C'\fR
 436 .ie n .SS "$mech\->\fIstatus()\fP"
 437 .el .SS "\f(CW$mech\fP\->\fIstatus()\fP"
 438 .IX Subsection "$mech->status()"
 439 Returns the \s-1HTTP\s0 status code of the response.  This is a 3\-digit
 440 number like 200 for \s-1OK\s0, 404 for not found, and so on.
 441 .ie n .SS "$mech\->\fIct()\fP / $mech\->\fIcontent_type()\fP"
 442 .el .SS "\f(CW$mech\fP\->\fIct()\fP / \f(CW$mech\fP\->\fIcontent_type()\fP"
 443 .IX Subsection "$mech->ct() / $mech->content_type()"
 444 Returns the content type of the response.
 445 .ie n .SS "$mech\->\fIbase()\fP"
 446 .el .SS "\f(CW$mech\fP\->\fIbase()\fP"
 447 .IX Subsection "$mech->base()"
 448 Returns the base \s-1URI\s0 for the current response
 449 .ie n .SS "$mech\->\fIforms()\fP"
 450 .el .SS "\f(CW$mech\fP\->\fIforms()\fP"
 451 .IX Subsection "$mech->forms()"
 452 When called in a list context, returns a list of the forms found in
 453 the last fetched page. In a scalar context, returns a reference to
 454 an array with those forms. The forms returned are all HTML::Form
 455 objects.
 456 .ie n .SS "$mech\->\fIcurrent_form()\fP"
 457 .el .SS "\f(CW$mech\fP\->\fIcurrent_form()\fP"
 458 .IX Subsection "$mech->current_form()"
 459 Returns the current form as an HTML::Form object.
 460 .ie n .SS "$mech\->\fIlinks()\fP"
 461 .el .SS "\f(CW$mech\fP\->\fIlinks()\fP"
 462 .IX Subsection "$mech->links()"
 463 When called in a list context, returns a list of the links found in the
 464 last fetched page.  In a scalar context it returns a reference to an array
 465 with those links.  Each link is a WWW::Mechanize::Link object.
 466 .ie n .SS "$mech\->\fIis_html()\fP"
 467 .el .SS "\f(CW$mech\fP\->\fIis_html()\fP"
 468 .IX Subsection "$mech->is_html()"
 469 Returns true/false on whether our content is \s-1HTML\s0, according to the
 470 \&\s-1HTTP\s0 headers.
 471 .ie n .SS "$mech\->\fItitle()\fP"
 472 .el .SS "\f(CW$mech\fP\->\fItitle()\fP"
 473 .IX Subsection "$mech->title()"
 474 Returns the contents of the \f(CW\*(C`<TITLE>\*(C'\fR tag, as parsed by
 475 HTML::HeadParser.  Returns undef if the content is not \s-1HTML\s0.
 476 .SH "CONTENT-HANDLING METHODS"
 477 .IX Header "CONTENT-HANDLING METHODS"
 478 .ie n .SS "$mech\->content(...)"
 479 .el .SS "\f(CW$mech\fP\->content(...)"
 480 .IX Subsection "$mech->content(...)"
 481 Returns the content that the mech uses internally for the last page
 482 fetched. Ordinarily this is the same as \f(CW$mech\fR\->\fIresponse()\fR\->\fIcontent()\fR,
 483 but this may differ for \s-1HTML\s0 documents if \*(L"update_html\*(R" is
 484 overloaded (in which case the value passed to the base-class
 485 implementation of same will be returned), and/or extra named arguments
 486 are passed to \fI\fIcontent()\fI\fR:
 487 .ie n .IP "\fI\fI$mech\fI\->content( format => 'text' )\fR" 2
 488 .el .IP "\fI\f(CI$mech\fI\->content( format => 'text' )\fR" 2
 489 .IX Item "$mech->content( format => 'text' )"
 490 Returns a text-only version of the page, with all \s-1HTML\s0 markup
 491 stripped. This feature requires \fIHTML::TreeBuilder\fR to be installed,
 492 or a fatal error will be thrown.
 493 .ie n .IP "\fI\fI$mech\fI\->content( base_href => [$base_href|undef] )\fR" 2
 494 .el .IP "\fI\f(CI$mech\fI\->content( base_href => [$base_href|undef] )\fR" 2
 495 .IX Item "$mech->content( base_href => [$base_href|undef] )"
 496 Returns the \s-1HTML\s0 document, modified to contain a
 497 \&\f(CW\*(C`<base href="$base_href">\*(C'\fR mark-up in the header.
 498 \&\fI\f(CI$base_href\fI\fR is \f(CW\*(C`$mech\->base()\*(C'\fR if not specified. This is
 499 handy to pass the \s-1HTML\s0 to e.g. HTML::Display.
 500 .PP
 501 Passing arguments to \f(CW\*(C`content()\*(C'\fR if the current document is not
 502 \&\s-1HTML\s0 has no effect now (i.e. the return value is the same as
 503 \&\f(CW\*(C`$self\->response()\->content()\*(C'\fR. This may change in the future,
 504 but will likely be backwards-compatible when it does.
 505 .SH "LINK METHODS"
 506 .IX Header "LINK METHODS"
 507 .ie n .SS "$mech\->\fIlinks()\fP"
 508 .el .SS "\f(CW$mech\fP\->\fIlinks()\fP"
 509 .IX Subsection "$mech->links()"
 510 Lists all the links on the current page.  Each link is a
 511 WWW::Mechanize::Link object. In list context, returns a list of all
 512 links.  In scalar context, returns an array reference of all links.
 513 .ie n .SS "$mech\->follow_link(...)"
 514 .el .SS "\f(CW$mech\fP\->follow_link(...)"
 515 .IX Subsection "$mech->follow_link(...)"
 516 Follows a specified link on the page.  You specify the match to be
 517 found using the same parms that \f(CW\*(C`find_link()\*(C'\fR uses.
 518 .PP
 519 Here some examples:
 520 .IP "\(bu" 4
 521 3rd link called \*(L"download\*(R"
 522 .Sp
 523 .Vb 1
 524 \&    $mech\->follow_link( text => \*(Aqdownload\*(Aq, n => 3 );
 525 .Ve
 526 .IP "\(bu" 4
 527 first link where the \s-1URL\s0 has \*(L"download\*(R" in it, regardless of case:
 528 .Sp
 529 .Vb 1
 530 \&    $mech\->follow_link( url_regex => qr/download/i );
 531 .Ve
 532 .Sp
 533 or
 534 .Sp
 535 .Vb 1
 536 \&    $mech\->follow_link( url_regex => qr/(?i:download)/ );
 537 .Ve
 538 .IP "\(bu" 4
 539 3rd link on the page
 540 .Sp
 541 .Vb 1
 542 \&    $mech\->follow_link( n => 3 );
 543 .Ve
 544 .PP
 545 Returns the result of the \s-1GET\s0 method (an HTTP::Response object) if
 546 a link was found. If the page has no links, or the specified link
 547 couldn't be found, returns undef.
 548 .ie n .SS "$mech\->find_link( ... )"
 549 .el .SS "\f(CW$mech\fP\->find_link( ... )"
 550 .IX Subsection "$mech->find_link( ... )"
 551 Finds a link in the currently fetched page. It returns a
 552 WWW::Mechanize::Link object which describes the link.  (You'll
 553 probably be most interested in the \f(CW\*(C`url()\*(C'\fR property.)  If it fails
 554 to find a link it returns undef.
 555 .PP
 556 You can take the \s-1URL\s0 part and pass it to the \f(CW\*(C`get()\*(C'\fR method.  If
 557 that's your plan, you might as well use the \f(CW\*(C`follow_link()\*(C'\fR method
 558 directly, since it does the \f(CW\*(C`get()\*(C'\fR for you automatically.
 559 .PP
 560 Note that \f(CW\*(C`<FRAME SRC="...">\*(C'\fR tags are parsed out of the the \s-1HTML\s0
 561 and treated as links so this method works with them.
 562 .PP
 563 You can select which link to find by passing in one or more of these
 564 key/value pairs:
 565 .IP "\(bu" 4
 566 \&\f(CW\*(C`text => \*(Aqstring\*(Aq,\*(C'\fR and \f(CW\*(C`text_regex => qr/regex/,\*(C'\fR
 567 .Sp
 568 \&\f(CW\*(C`text\*(C'\fR matches the text of the link against \fIstring\fR, which must be an
 569 exact match.  To select a link with text that is exactly \*(L"download\*(R", use
 570 .Sp
 571 .Vb 1
 572 \&    $mech\->find_link( text => \*(Aqdownload\*(Aq );
 573 .Ve
 574 .Sp
 575 \&\f(CW\*(C`text_regex\*(C'\fR matches the text of the link against \fIregex\fR.  To select a
 576 link with text that has \*(L"download\*(R" anywhere in it, regardless of case, use
 577 .Sp
 578 .Vb 1
 579 \&    $mech\->find_link( text_regex => qr/download/i );
 580 .Ve
 581 .Sp
 582 Note that the text extracted from the page's links are trimmed.  For
 583 example, \f(CW\*(C`<a> foo </a>\*(C'\fR is stored as 'foo', and searching for
 584 leading or trailing spaces will fail.
 585 .IP "\(bu" 4
 586 \&\f(CW\*(C`url => \*(Aqstring\*(Aq,\*(C'\fR and \f(CW\*(C`url_regex => qr/regex/,\*(C'\fR
 587 .Sp
 588 Matches the \s-1URL\s0 of the link against \fIstring\fR or \fIregex\fR, as appropriate.
 589 The \s-1URL\s0 may be a relative \s-1URL\s0, like \fIfoo/bar.html\fR, depending on how
 590 it's coded on the page.
 591 .IP "\(bu" 4
 592 \&\f(CW\*(C`url_abs => string\*(C'\fR and \f(CW\*(C`url_abs_regex => regex\*(C'\fR
 593 .Sp
 594 Matches the absolute \s-1URL\s0 of the link against \fIstring\fR or \fIregex\fR,
 595 as appropriate.  The \s-1URL\s0 will be an absolute \s-1URL\s0, even if it's relative
 596 in the page.
 597 .IP "\(bu" 4
 598 \&\f(CW\*(C`name => string\*(C'\fR and \f(CW\*(C`name_regex => regex\*(C'\fR
 599 .Sp
 600 Matches the name of the link against \fIstring\fR or \fIregex\fR, as appropriate.
 601 .IP "\(bu" 4
 602 \&\f(CW\*(C`id => string\*(C'\fR and \f(CW\*(C`id_regex => regex\*(C'\fR
 603 .Sp
 604 Matches the attribute 'id' of the link against \fIstring\fR or
 605 \&\fIregex\fR, as appropriate.
 606 .IP "\(bu" 4
 607 \&\f(CW\*(C`class => string\*(C'\fR and \f(CW\*(C`class_regex => regex\*(C'\fR
 608 .Sp
 609 Matches the attribute 'class' of the link against \fIstring\fR or
 610 \&\fIregex\fR, as appropriate.
 611 .IP "\(bu" 4
 612 \&\f(CW\*(C`tag => string\*(C'\fR and \f(CW\*(C`tag_regex => regex\*(C'\fR
 613 .Sp
 614 Matches the tag that the link came from against \fIstring\fR or \fIregex\fR,
 615 as appropriate.  The \f(CW\*(C`tag_regex\*(C'\fR is probably most useful to check for
 616 more than one tag, as in:
 617 .Sp
 618 .Vb 1
 619 \&    $mech\->find_link( tag_regex => qr/^(a|frame)$/ );
 620 .Ve
 621 .Sp
 622 The tags and attributes looked at are defined below, at
 623 \&\*(L"$mech\->\fIfind_link()\fR : link format\*(R".
 624 .PP
 625 If \f(CW\*(C`n\*(C'\fR is not specified, it defaults to 1.  Therefore, if you don't
 626 specify any parms, this method defaults to finding the first link on the
 627 page.
 628 .PP
 629 Note that you can specify multiple text or \s-1URL\s0 parameters, which
 630 will be ANDed together.  For example, to find the first link with
 631 text of \*(L"News\*(R" and with \*(L"cnn.com\*(R" in the \s-1URL\s0, use:
 632 .PP
 633 .Vb 1
 634 \&    $mech\->find_link( text => \*(AqNews\*(Aq, url_regex => qr/cnn\e.com/ );
 635 .Ve
 636 .PP
 637 The return value is a reference to an array containing a
 638 WWW::Mechanize::Link object for every link in \f(CW\*(C`$self\->content\*(C'\fR.
 639 .PP
 640 The links come from the following:
 641 .ie n .IP """<a href=...>""" 4
 642 .el .IP "\f(CW<a href=...>\fR" 4
 643 .IX Item "<a href=...>"
 644 .PD 0
 645 .ie n .IP """<area href=...>""" 4
 646 .el .IP "\f(CW<area href=...>\fR" 4
 647 .IX Item "<area href=...>"
 648 .ie n .IP """<frame src=...>""" 4
 649 .el .IP "\f(CW<frame src=...>\fR" 4
 650 .IX Item "<frame src=...>"
 651 .ie n .IP """<iframe src=...>""" 4
 652 .el .IP "\f(CW<iframe src=...>\fR" 4
 653 .IX Item "<iframe src=...>"
 654 .ie n .IP """<link href=...>""" 4
 655 .el .IP "\f(CW<link href=...>\fR" 4
 656 .IX Item "<link href=...>"
 657 .ie n .IP """<meta content=...>""" 4
 658 .el .IP "\f(CW<meta content=...>\fR" 4
 659 .IX Item "<meta content=...>"
 660 .PD
 661 .ie n .SS "$mech\->find_all_links( ... )"
 662 .el .SS "\f(CW$mech\fP\->find_all_links( ... )"
 663 .IX Subsection "$mech->find_all_links( ... )"
 664 Returns all the links on the current page that match the criteria.  The
 665 method for specifying link criteria is the same as in \f(CW"find_link()"\fR.
 666 Each of the links returned is a WWW::Mechanize::Link object.
 667 .PP
 668 In list context, \f(CW\*(C`find_all_links()\*(C'\fR returns a list of the links.
 669 Otherwise, it returns a reference to the list of links.
 670 .PP
 671 \&\f(CW\*(C`find_all_links()\*(C'\fR with no parameters returns all links in the
 672 page.
 673 .ie n .SS "$mech\->find_all_inputs( ... criteria ... )"
 674 .el .SS "\f(CW$mech\fP\->find_all_inputs( ... criteria ... )"
 675 .IX Subsection "$mech->find_all_inputs( ... criteria ... )"
 676 \&\fIfind_all_inputs()\fR returns an array of all the input controls in the
 677 current form whose properties match all of the regexes passed in.
 678 The controls returned are all descended from HTML::Form::Input.
 679 .PP
 680 If no criteria are passed, all inputs will be returned.
 681 .PP
 682 If there is no current page, there is no form on the current
 683 page, or there are no submit controls in the current form
 684 then the return will be an empty array.
 685 .PP
 686 You may use a regex or a literal string:
 687 .PP
 688 .Vb 5
 689 \&    # get all textarea controls whose names begin with "customer"
 690 \&    my @customer_text_inputs = $mech\->find_all_inputs(
 691 \&        type       => \*(Aqtextarea\*(Aq,
 692 \&        name_regex => qr/^customer/,
 693 \&    );
 694 \&
 695 \&    # get all text or textarea controls called "customer"
 696 \&    my @customer_text_inputs = $mech\->find_all_inputs(
 697 \&        type_regex => qr/^(text|textarea)$/,
 698 \&        name       => \*(Aqcustomer\*(Aq,
 699 \&    );
 700 .Ve
 701 .ie n .SS "$mech\->find_all_submits( ... criteria ... )"
 702 .el .SS "\f(CW$mech\fP\->find_all_submits( ... criteria ... )"
 703 .IX Subsection "$mech->find_all_submits( ... criteria ... )"
 704 \&\f(CW\*(C`find_all_submits()\*(C'\fR does the same thing as \f(CW\*(C`find_all_inputs()\*(C'\fR
 705 except that it only returns controls that are submit controls,
 706 ignoring other types of input controls like text and checkboxes.
 707 .SH "IMAGE METHODS"
 708 .IX Header "IMAGE METHODS"
 709 .ie n .SS "$mech\->images"
 710 .el .SS "\f(CW$mech\fP\->images"
 711 .IX Subsection "$mech->images"
 712 Lists all the images on the current page.  Each image is a
 713 WWW::Mechanize::Image object. In list context, returns a list of all
 714 images.  In scalar context, returns an array reference of all images.
 715 .ie n .SS "$mech\->\fIfind_image()\fP"
 716 .el .SS "\f(CW$mech\fP\->\fIfind_image()\fP"
 717 .IX Subsection "$mech->find_image()"
 718 Finds an image in the current page. It returns a
 719 WWW::Mechanize::Image object which describes the image.  If it fails
 720 to find an image it returns undef.
 721 .PP
 722 You can select which image to find by passing in one or more of these
 723 key/value pairs:
 724 .IP "\(bu" 4
 725 \&\f(CW\*(C`alt => \*(Aqstring\*(Aq\*(C'\fR and \f(CW\*(C`alt_regex => qr/regex/,\*(C'\fR
 726 .Sp
 727 \&\f(CW\*(C`alt\*(C'\fR matches the \s-1ALT\s0 attribute of the image against \fIstring\fR, which must be an
 728 exact match. To select a image with an \s-1ALT\s0 tag that is exactly \*(L"download\*(R", use
 729 .Sp
 730 .Vb 1
 731 \&    $mech\->find_image( alt => \*(Aqdownload\*(Aq );
 732 .Ve
 733 .Sp
 734 \&\f(CW\*(C`alt_regex\*(C'\fR matches the \s-1ALT\s0 attribute of the image  against a regular
 735 expression.  To select an image with an \s-1ALT\s0 attribute that has \*(L"download\*(R"
 736 anywhere in it, regardless of case, use
 737 .Sp
 738 .Vb 1
 739 \&    $mech\->find_image( alt_regex => qr/download/i );
 740 .Ve
 741 .IP "\(bu" 4
 742 \&\f(CW\*(C`url => \*(Aqstring\*(Aq,\*(C'\fR and \f(CW\*(C`url_regex => qr/regex/,\*(C'\fR
 743 .Sp
 744 Matches the \s-1URL\s0 of the image against \fIstring\fR or \fIregex\fR, as appropriate.
 745 The \s-1URL\s0 may be a relative \s-1URL\s0, like \fIfoo/bar.html\fR, depending on how
 746 it's coded on the page.
 747 .IP "\(bu" 4
 748 \&\f(CW\*(C`url_abs => string\*(C'\fR and \f(CW\*(C`url_abs_regex => regex\*(C'\fR
 749 .Sp
 750 Matches the absolute \s-1URL\s0 of the image against \fIstring\fR or \fIregex\fR,
 751 as appropriate.  The \s-1URL\s0 will be an absolute \s-1URL\s0, even if it's relative
 752 in the page.
 753 .IP "\(bu" 4
 754 \&\f(CW\*(C`tag => string\*(C'\fR and \f(CW\*(C`tag_regex => regex\*(C'\fR
 755 .Sp
 756 Matches the tag that the image came from against \fIstring\fR or \fIregex\fR,
 757 as appropriate.  The \f(CW\*(C`tag_regex\*(C'\fR is probably most useful to check for
 758 more than one tag, as in:
 759 .Sp
 760 .Vb 1
 761 \&    $mech\->find_image( tag_regex => qr/^(img|input)$/ );
 762 .Ve
 763 .Sp
 764 The tags supported are \f(CW\*(C`<img>\*(C'\fR and \f(CW\*(C`<input>\*(C'\fR.
 765 .PP
 766 If \f(CW\*(C`n\*(C'\fR is not specified, it defaults to 1.  Therefore, if you don't
 767 specify any parms, this method defaults to finding the first image on the
 768 page.
 769 .PP
 770 Note that you can specify multiple \s-1ALT\s0 or \s-1URL\s0 parameters, which
 771 will be ANDed together.  For example, to find the first image with
 772 \&\s-1ALT\s0 text of \*(L"News\*(R" and with \*(L"cnn.com\*(R" in the \s-1URL\s0, use:
 773 .PP
 774 .Vb 1
 775 \&    $mech\->find_image( image => \*(AqNews\*(Aq, url_regex => qr/cnn\e.com/ );
 776 .Ve
 777 .PP
 778 The return value is a reference to an array containing a
 779 WWW::Mechanize::Image object for every image in \f(CW\*(C`$self\->content\*(C'\fR.
 780 .ie n .SS "$mech\->find_all_images( ... )"
 781 .el .SS "\f(CW$mech\fP\->find_all_images( ... )"
 782 .IX Subsection "$mech->find_all_images( ... )"
 783 Returns all the images on the current page that match the criteria.  The
 784 method for specifying image criteria is the same as in \f(CW"find_image()"\fR.
 785 Each of the images returned is a WWW::Mechanize::Image object.
 786 .PP
 787 In list context, \f(CW\*(C`find_all_images()\*(C'\fR returns a list of the images.
 788 Otherwise, it returns a reference to the list of images.
 789 .PP
 790 \&\f(CW\*(C`find_all_images()\*(C'\fR with no parameters returns all images in the page.
 791 .SH "FORM METHODS"
 792 .IX Header "FORM METHODS"
 793 These methods let you work with the forms on a page.  The idea is
 794 to choose a form that you'll later work with using the field methods
 795 below.
 796 .ie n .SS "$mech\->forms"
 797 .el .SS "\f(CW$mech\fP\->forms"
 798 .IX Subsection "$mech->forms"
 799 Lists all the forms on the current page.  Each form is an HTML::Form
 800 object.  In list context, returns a list of all forms.  In scalar
 801 context, returns an array reference of all forms.
 802 .ie n .SS "$mech\->form_number($number)"
 803 .el .SS "\f(CW$mech\fP\->form_number($number)"
 804 .IX Subsection "$mech->form_number($number)"
 805 Selects the \fInumber\fRth form on the page as the target for subsequent
 806 calls to \f(CW"field()"\fR and \f(CW"click()"\fR.  Also returns the form that was
 807 selected.
 808 .PP
 809 If it is found, the form is returned as an HTML::Form object and set internally
 810 for later use with Mech's form methods such as \f(CW"field()"\fR and \f(CW"click()"\fR.
 811 .PP
 812 Emits a warning and returns undef if no form is found.
 813 .PP
 814 The first form is number 1, not zero.
 815 .ie n .SS "$mech\->form_name( $name )"
 816 .el .SS "\f(CW$mech\fP\->form_name( \f(CW$name\fP )"
 817 .IX Subsection "$mech->form_name( $name )"
 818 Selects a form by name.  If there is more than one form on the page
 819 with that name, then the first one is used, and a warning is
 820 generated.
 821 .PP
 822 If it is found, the form is returned as an HTML::Form object and
 823 set internally for later use with Mech's form methods such as
 824 \&\f(CW"field()"\fR and \f(CW"click()"\fR.
 825 .PP
 826 Returns undef if no form is found.
 827 .ie n .SS "$mech\->form_id( $name )"
 828 .el .SS "\f(CW$mech\fP\->form_id( \f(CW$name\fP )"
 829 .IX Subsection "$mech->form_id( $name )"
 830 Selects a form by \s-1ID\s0.  If there is more than one form on the page
 831 with that \s-1ID\s0, then the first one is used, and a warning is generated.
 832 .PP
 833 If it is found, the form is returned as an HTML::Form object and
 834 set internally for later use with Mech's form methods such as
 835 \&\f(CW"field()"\fR and \f(CW"click()"\fR.
 836 .PP
 837 Returns undef if no form is found.
 838 .ie n .SS "$mech\->form_with_fields( @fields )"
 839 .el .SS "\f(CW$mech\fP\->form_with_fields( \f(CW@fields\fP )"
 840 .IX Subsection "$mech->form_with_fields( @fields )"
 841 Selects a form by passing in a list of field names it must contain.  If there
 842 is more than one form on the page with that matches, then the first one is used,
 843 and a warning is generated.
 844 .PP
 845 If it is found, the form is returned as an HTML::Form object and set internally
 846 for later used with Mech's form methods such as \f(CW"field()"\fR and \f(CW"click()"\fR.
 847 .PP
 848 Returns undef if no form is found.
 849 .PP
 850 Note that this functionality requires libwww-perl 5.69 or higher.
 851 .SH "FIELD METHODS"
 852 .IX Header "FIELD METHODS"
 853 These methods allow you to set the values of fields in a given form.
 854 .ie n .SS "$mech\->field( $name, $value, $number )"
 855 .el .SS "\f(CW$mech\fP\->field( \f(CW$name\fP, \f(CW$value\fP, \f(CW$number\fP )"
 856 .IX Subsection "$mech->field( $name, $value, $number )"
 857 .ie n .SS "$mech\->field( $name, \e@values, $number )"
 858 .el .SS "\f(CW$mech\fP\->field( \f(CW$name\fP, \e@values, \f(CW$number\fP )"
 859 .IX Subsection "$mech->field( $name, @values, $number )"
 860 Given the name of a field, set its value to the value specified.
 861 This applies to the current form (as set by the \*(L"\fIform_name()\fR\*(R" or
 862 \&\*(L"\fIform_number()\fR\*(R" method or defaulting to the first form on the
 863 page).
 864 .PP
 865 The optional \fI\f(CI$number\fI\fR parameter is used to distinguish between two fields
 866 with the same name.  The fields are numbered from 1.
 867 .ie n .SS "$mech\->select($name, $value)"
 868 .el .SS "\f(CW$mech\fP\->select($name, \f(CW$value\fP)"
 869 .IX Subsection "$mech->select($name, $value)"
 870 .ie n .SS "$mech\->select($name, \e@values)"
 871 .el .SS "\f(CW$mech\fP\->select($name, \e@values)"
 872 .IX Subsection "$mech->select($name, @values)"
 873 Given the name of a \f(CW\*(C`select\*(C'\fR field, set its value to the value
 874 specified.  If the field is not \f(CW\*(C`<select multiple>\*(C'\fR and the
 875 \&\f(CW$value\fR is an array, only the \fBfirst\fR value will be set.  [Note:
 876 the documentation previously claimed that only the last value would
 877 be set, but this was incorrect.]  Passing \f(CW$value\fR as a hash with
 878 an \f(CW\*(C`n\*(C'\fR key selects an item by number (e.g.
 879 \&\f(CW\*(C`{n => 3}\*(C'\fR or \f(CW\*(C`{n => [2,4]}\*(C'\fR).
 880 The numbering starts at 1.  This applies to the current form.
 881 .PP
 882 Returns true on successfully setting the value. On failure, returns
 883 false and calls \f(CW\*(C`$self>warn()\*(C'\fR with an error message.
 884 .ie n .SS "$mech\->set_fields( $name => $value ... )"
 885 .el .SS "\f(CW$mech\fP\->set_fields( \f(CW$name\fP => \f(CW$value\fP ... )"
 886 .IX Subsection "$mech->set_fields( $name => $value ... )"
 887 This method sets multiple fields of the current form. It takes a list
 888 of field name and value pairs. If there is more than one field with
 889 the same name, the first one found is set. If you want to select which
 890 of the duplicate field to set, use a value which is an anonymous array
 891 which has the field value and its number as the 2 elements.
 892 .PP
 893 .Vb 2
 894 \&        # set the second foo field
 895 \&        $mech\->set_fields( $name => [ \*(Aqfoo\*(Aq, 2 ] );
 896 .Ve
 897 .PP
 898 The fields are numbered from 1.
 899 .PP
 900 This applies to the current form.
 901 .ie n .SS "$mech\->set_visible( @criteria )"
 902 .el .SS "\f(CW$mech\fP\->set_visible( \f(CW@criteria\fP )"
 903 .IX Subsection "$mech->set_visible( @criteria )"
 904 This method sets fields of the current form without having to know
 905 their names.  So if you have a login screen that wants a username and
 906 password, you do not have to fetch the form and inspect the source (or
 907 use the \fImech-dump\fR utility, installed with WWW::Mechanize) to see
 908 what the field names are; you can just say
 909 .PP
 910 .Vb 1
 911 \&    $mech\->set_visible( $username, $password );
 912 .Ve
 913 .PP
 914 and the first and second fields will be set accordingly.  The method
 915 is called set_\fIvisible\fR because it acts only on visible fields;
 916 hidden form inputs are not considered.  The order of the fields is
 917 the order in which they appear in the \s-1HTML\s0 source which is nearly
 918 always the order anyone viewing the page would think they are in,
 919 but some creative work with tables could change that; caveat user.
 920 .PP
 921 Each element in \f(CW@criteria\fR is either a field value or a field
 922 specifier.  A field value is a scalar.  A field specifier allows
 923 you to specify the \fItype\fR of input field you want to set and is
 924 denoted with an arrayref containing two elements.  So you could
 925 specify the first radio button with
 926 .PP
 927 .Vb 1
 928 \&    $mech\->set_visible( [ radio => \*(AqKCRW\*(Aq ] );
 929 .Ve
 930 .PP
 931 Field values and specifiers can be intermixed, hence
 932 .PP
 933 .Vb 1
 934 \&    $mech\->set_visible( \*(Aqfred\*(Aq, \*(Aqsecret\*(Aq, [ option => \*(AqChecking\*(Aq ] );
 935 .Ve
 936 .PP
 937 would set the first two fields to \*(L"fred\*(R" and \*(L"secret\*(R", and the \fInext\fR
 938 \&\f(CW\*(C`OPTION\*(C'\fR menu field to \*(L"Checking\*(R".
 939 .PP
 940 The possible field specifier types are: \*(L"text\*(R", \*(L"password\*(R", \*(L"hidden\*(R",
 941 \&\*(L"textarea\*(R", \*(L"file\*(R", \*(L"image\*(R", \*(L"submit\*(R", \*(L"radio\*(R", \*(L"checkbox\*(R" and \*(L"option\*(R".
 942 .PP
 943 \&\f(CW\*(C`set_visible\*(C'\fR returns the number of values set.
 944 .ie n .SS "$mech\->tick( $name, $value [, $set] )"
 945 .el .SS "\f(CW$mech\fP\->tick( \f(CW$name\fP, \f(CW$value\fP [, \f(CW$set\fP] )"
 946 .IX Subsection "$mech->tick( $name, $value [, $set] )"
 947 \&\*(L"Ticks\*(R" the first checkbox that has both the name and value associated
 948 with it on the current form.  Dies if there is no named check box for
 949 that value.  Passing in a false value as the third optional argument
 950 will cause the checkbox to be unticked.
 951 .ie n .SS "$mech\->untick($name, $value)"
 952 .el .SS "\f(CW$mech\fP\->untick($name, \f(CW$value\fP)"
 953 .IX Subsection "$mech->untick($name, $value)"
 954 Causes the checkbox to be unticked.  Shorthand for
 955 \&\f(CW\*(C`tick($name,$value,undef)\*(C'\fR
 956 .ie n .SS "$mech\->value( $name [, $number] )"
 957 .el .SS "\f(CW$mech\fP\->value( \f(CW$name\fP [, \f(CW$number\fP] )"
 958 .IX Subsection "$mech->value( $name [, $number] )"
 959 Given the name of a field, return its value. This applies to the current
 960 form.
 961 .PP
 962 The optional \fI\f(CI$number\fI\fR parameter is used to distinguish between two fields
 963 with the same name.  The fields are numbered from 1.
 964 .PP
 965 If the field is of type file (file upload field), the value is always
 966 cleared to prevent remote sites from downloading your local files.
 967 To upload a file, specify its file name explicitly.
 968 .ie n .SS "$mech\->click( $button [, $x, $y] )"
 969 .el .SS "\f(CW$mech\fP\->click( \f(CW$button\fP [, \f(CW$x\fP, \f(CW$y\fP] )"
 970 .IX Subsection "$mech->click( $button [, $x, $y] )"
 971 Has the effect of clicking a button on the current form.  The first
 972 argument is the name of the button to be clicked.  The second and
 973 third arguments (optional) allow you to specify the (x,y) coordinates
 974 of the click.
 975 .PP
 976 If there is only one button on the form, \f(CW\*(C`$mech\->click()\*(C'\fR with
 977 no arguments simply clicks that one button.
 978 .PP
 979 Returns an HTTP::Response object.
 980 .ie n .SS "$mech\->click_button( ... )"
 981 .el .SS "\f(CW$mech\fP\->click_button( ... )"
 982 .IX Subsection "$mech->click_button( ... )"
 983 Has the effect of clicking a button on the current form by specifying
 984 its name, value, or index.  Its arguments are a list of key/value
 985 pairs.  Only one of name, number, input or value must be specified in
 986 the keys.
 987 .IP "\(bu" 4
 988 \&\f(CW\*(C`name => name\*(C'\fR
 989 .Sp
 990 Clicks the button named \fIname\fR in the current form.
 991 .IP "\(bu" 4
 992 \&\f(CW\*(C`number => n\*(C'\fR
 993 .Sp
 994 Clicks the \fIn\fRth button in the current form. Numbering starts at 1.
 995 .IP "\(bu" 4
 996 \&\f(CW\*(C`value => value\*(C'\fR
 997 .Sp
 998 Clicks the button with the value \fIvalue\fR in the current form.
 999 .IP "\(bu" 4
1000 \&\f(CW\*(C`input => $inputobject\*(C'\fR
1001 .Sp
1002 Clicks on the button referenced by \f(CW$inputobject\fR, an instance of
1003 HTML::Form::SubmitInput obtained e.g. from
1004 .Sp
1005 .Vb 1
1006 \&    $mech\->current_form()\->find_input( undef, \*(Aqsubmit\*(Aq )
1007 .Ve
1008 .Sp
1009 \&\f(CW$inputobject\fR must belong to the current form.
1010 .IP "\(bu" 4
1011 \&\f(CW\*(C`x => x\*(C'\fR
1012 .IP "\(bu" 4
1013 \&\f(CW\*(C`y => y\*(C'\fR
1014 .Sp
1015 These arguments (optional) allow you to specify the (x,y) coordinates
1016 of the click.
1017 .ie n .SS "$mech\->\fIsubmit()\fP"
1018 .el .SS "\f(CW$mech\fP\->\fIsubmit()\fP"
1019 .IX Subsection "$mech->submit()"
1020 Submits the page, without specifying a button to click.  Actually,
1021 no button is clicked at all.
1022 .PP
1023 Returns an HTTP::Response object.
1024 .PP
1025 This used to be a synonym for \f(CW\*(C`$mech\->click( \*(Aqsubmit\*(Aq )\*(C'\fR, but is no
1026 longer so.
1027 .ie n .SS "$mech\->submit_form( ... )"
1028 .el .SS "\f(CW$mech\fP\->submit_form( ... )"
1029 .IX Subsection "$mech->submit_form( ... )"
1030 This method lets you select a form from the previously fetched page,
1031 fill in its fields, and submit it. It combines the form_number/form_name,
1032 set_fields and click methods into one higher level call. Its arguments
1033 are a list of key/value pairs, all of which are optional.
1034 .IP "\(bu" 4
1035 \&\f(CW\*(C`fields => \e%fields\*(C'\fR
1036 .Sp
1037 Specifies the fields to be filled in the current form.
1038 .IP "\(bu" 4
1039 \&\f(CW\*(C`with_fields => \e%fields\*(C'\fR
1040 .Sp
1041 Probably all you need for the common case. It combines a smart form selector
1042 and data setting in one operation. It selects the first form that contains all
1043 fields mentioned in \f(CW\*(C`\e%fields\*(C'\fR.  This is nice because you don't need to know
1044 the name or number of the form to do this.
1045 .Sp
1046 (calls \f(CW"form_with_fields()"\fR and \f(CW"set_fields()"\fR).
1047 .Sp
1048 If you choose this, the form_number, form_name, form_id and fields options will be ignored.
1049 .IP "\(bu" 4
1050 \&\f(CW\*(C`form_number => n\*(C'\fR
1051 .Sp
1052 Selects the \fIn\fRth form (calls \f(CW"form_number()"\fR).  If this parm is not
1053 specified, the currently-selected form is used.
1054 .IP "\(bu" 4
1055 \&\f(CW\*(C`form_name => name\*(C'\fR
1056 .Sp
1057 Selects the form named \fIname\fR (calls \f(CW"form_name()"\fR)
1058 .IP "\(bu" 4
1059 \&\f(CW\*(C`form_id => ID\*(C'\fR
1060 .Sp
1061 Selects the form with \s-1ID\s0 \fI\s-1ID\s0\fR (calls \f(CW"form_id()"\fR)
1062 .IP "\(bu" 4
1063 \&\f(CW\*(C`button => button\*(C'\fR
1064 .Sp
1065 Clicks on button \fIbutton\fR (calls \f(CW"click()"\fR)
1066 .IP "\(bu" 4
1067 \&\f(CW\*(C`x => x, y => y\*(C'\fR
1068 .Sp
1069 Sets the x or y values for \f(CW"click()"\fR
1070 .PP
1071 If no form is selected, the first form found is used.
1072 .PP
1073 If \fIbutton\fR is not passed, then the \f(CW"submit()"\fR method is used instead.
1074 .PP
1075 Returns an HTTP::Response object.
1076 .SH "MISCELLANEOUS METHODS"
1077 .IX Header "MISCELLANEOUS METHODS"
1078 .ie n .SS "$mech\->add_header( name => $value [, name => $value... ] )"
1079 .el .SS "\f(CW$mech\fP\->add_header( name => \f(CW$value\fP [, name => \f(CW$value\fP... ] )"
1080 .IX Subsection "$mech->add_header( name => $value [, name => $value... ] )"
1081 Sets \s-1HTTP\s0 headers for the agent to add or remove from the \s-1HTTP\s0 request.
1082 .PP
1083 .Vb 1
1084 \&    $mech\->add_header( Encoding => \*(Aqtext/klingon\*(Aq );
1085 .Ve
1086 .PP
1087 If a \fIvalue\fR is \f(CW\*(C`undef\*(C'\fR, then that header will be removed from any
1088 future requests.  For example, to never send a Referer header:
1089 .PP
1090 .Vb 1
1091 \&    $mech\->add_header( Referer => undef );
1092 .Ve
1093 .PP
1094 If you want to delete a header, use \f(CW\*(C`delete_header\*(C'\fR.
1095 .PP
1096 Returns the number of name/value pairs added.
1097 .PP
1098 \&\fB\s-1NOTE\s0\fR: This method was very different in WWW::Mechanize before 1.00.
1099 Back then, the headers were stored in a package hash, not as a member of
1100 the object instance.  Calling \f(CW\*(C`add_header()\*(C'\fR would modify the headers
1101 for every WWW::Mechanize object, even after your object no longer existed.
1102 .ie n .SS "$mech\->delete_header( name [, name ... ] )"
1103 .el .SS "\f(CW$mech\fP\->delete_header( name [, name ... ] )"
1104 .IX Subsection "$mech->delete_header( name [, name ... ] )"
1105 Removes \s-1HTTP\s0 headers from the agent's list of special headers.  For
1106 instance, you might need to do something like:
1107 .PP
1108 .Vb 2
1109 \&    # Don\*(Aqt send a Referer for this URL
1110 \&    $mech\->add_header( Referer => undef );
1111 \&
1112 \&    # Get the URL
1113 \&    $mech\->get( $url );
1114 \&
1115 \&    # Back to the default behavior
1116 \&    $mech\->delete_header( \*(AqReferer\*(Aq );
1117 .Ve
1118 .ie n .SS "$mech\->quiet(true/false)"
1119 .el .SS "\f(CW$mech\fP\->quiet(true/false)"
1120 .IX Subsection "$mech->quiet(true/false)"
1121 Allows you to suppress warnings to the screen.
1122 .PP
1123 .Vb 3
1124 \&    $mech\->quiet(0); # turns on warnings (the default)
1125 \&    $mech\->quiet(1); # turns off warnings
1126 \&    $mech\->quiet();  # returns the current quietness status
1127 .Ve
1128 .ie n .SS "$mech\->stack_depth( $max_depth )"
1129 .el .SS "\f(CW$mech\fP\->stack_depth( \f(CW$max_depth\fP )"
1130 .IX Subsection "$mech->stack_depth( $max_depth )"
1131 Get or set the page stack depth. Use this if you're doing a lot of page
1132 scraping and running out of memory.
1133 .PP
1134 A value of 0 means \*(L"no history at all.\*(R"  By default, the max stack depth
1135 is humongously large, effectively keeping all history.
1136 .ie n .SS "$mech\->save_content( $filename )"
1137 .el .SS "\f(CW$mech\fP\->save_content( \f(CW$filename\fP )"
1138 .IX Subsection "$mech->save_content( $filename )"
1139 Dumps the contents of \f(CW\*(C`$mech\->content\*(C'\fR into \fI\f(CI$filename\fI\fR.
1140 \&\fI\f(CI$filename\fI\fR will be overwritten.  Dies if there are any errors.
1141 .PP
1142 If the content type does not begin with \*(L"text/\*(R", then the content
1143 is saved in binary mode.
1144 .ie n .SS "$mech\->dump_headers( [$fh] )"
1145 .el .SS "\f(CW$mech\fP\->dump_headers( [$fh] )"
1146 .IX Subsection "$mech->dump_headers( [$fh] )"
1147 Prints a dump of the \s-1HTTP\s0 response headers for the most recent
1148 response.  If \fI\f(CI$fh\fI\fR is not specified or is undef, it dumps to
1149 \&\s-1STDOUT\s0.
1150 .PP
1151 Unlike the rest of the dump_* methods, you cannot specify a filehandle
1152 to print to.
1153 .ie n .SS "$mech\->dump_links( [[$fh], $absolute] )"
1154 .el .SS "\f(CW$mech\fP\->dump_links( [[$fh], \f(CW$absolute\fP] )"
1155 .IX Subsection "$mech->dump_links( [[$fh], $absolute] )"
1156 Prints a dump of the links on the current page to \fI\f(CI$fh\fI\fR.  If \fI\f(CI$fh\fI\fR
1157 is not specified or is undef, it dumps to \s-1STDOUT\s0.
1158 .PP
1159 If \fI\f(CI$absolute\fI\fR is true, links displayed are absolute, not relative.
1160 .ie n .SS "$mech\->dump_images( [[$fh], $absolute] )"
1161 .el .SS "\f(CW$mech\fP\->dump_images( [[$fh], \f(CW$absolute\fP] )"
1162 .IX Subsection "$mech->dump_images( [[$fh], $absolute] )"
1163 Prints a dump of the images on the current page to \fI\f(CI$fh\fI\fR.  If \fI\f(CI$fh\fI\fR
1164 is not specified or is undef, it dumps to \s-1STDOUT\s0.
1165 .PP
1166 If \fI\f(CI$absolute\fI\fR is true, links displayed are absolute, not relative.
1167 .ie n .SS "$mech\->dump_forms( [$fh] )"
1168 .el .SS "\f(CW$mech\fP\->dump_forms( [$fh] )"
1169 .IX Subsection "$mech->dump_forms( [$fh] )"
1170 Prints a dump of the forms on the current page to \fI\f(CI$fh\fI\fR.  If \fI\f(CI$fh\fI\fR
1171 is not specified or is undef, it dumps to \s-1STDOUT\s0.
1172 .ie n .SS "$mech\->dump_all( [[$fh], $absolute] )"
1173 .el .SS "\f(CW$mech\fP\->dump_all( [[$fh], \f(CW$absolute\fP] )"
1174 .IX Subsection "$mech->dump_all( [[$fh], $absolute] )"
1175 Prints a dump of all links, images and forms on the current page to
1176 \&\fI\f(CI$fh\fI\fR.  If \fI\f(CI$fh\fI\fR is not specified or is undef, it dumps to \s-1STDOUT\s0.
1177 .PP
1178 If \fI\f(CI$absolute\fI\fR is true, links displayed are absolute, not relative.
1179 .SH "OVERRIDDEN LWP::UserAgent METHODS"
1180 .IX Header "OVERRIDDEN LWP::UserAgent METHODS"
1181 .ie n .SS "$mech\->\fIclone()\fP"
1182 .el .SS "\f(CW$mech\fP\->\fIclone()\fP"
1183 .IX Subsection "$mech->clone()"
1184 Clone the mech object.  The clone will be using the same cookie jar
1185 as the original mech.
1186 .ie n .SS "$mech\->\fIredirect_ok()\fP"
1187 .el .SS "\f(CW$mech\fP\->\fIredirect_ok()\fP"
1188 .IX Subsection "$mech->redirect_ok()"
1189 An overloaded version of \f(CW\*(C`redirect_ok()\*(C'\fR in LWP::UserAgent.
1190 This method is used to determine whether a redirection in the request
1191 should be followed.
1192 .PP
1193 Note that WWW::Mechanize's constructor pushes \s-1POST\s0 on to the agent's
1194 \&\f(CW\*(C`requests_redirectable\*(C'\fR list.
1195 .ie n .SS "$mech\->request( $request [, $arg [, $size]])"
1196 .el .SS "\f(CW$mech\fP\->request( \f(CW$request\fP [, \f(CW$arg\fP [, \f(CW$size\fP]])"
1197 .IX Subsection "$mech->request( $request [, $arg [, $size]])"
1198 Overloaded version of \f(CW\*(C`request()\*(C'\fR in LWP::UserAgent.  Performs
1199 the actual request.  Normally, if you're using WWW::Mechanize, it's
1200 because you don't want to deal with this level of stuff anyway.
1201 .PP
1202 Note that \f(CW$request\fR will be modified.
1203 .PP
1204 Returns an HTTP::Response object.
1205 .ie n .SS "$mech\->update_html( $html )"
1206 .el .SS "\f(CW$mech\fP\->update_html( \f(CW$html\fP )"
1207 .IX Subsection "$mech->update_html( $html )"
1208 Allows you to replace the \s-1HTML\s0 that the mech has found.  Updates the
1209 forms and links parse-trees that the mech uses internally.
1210 .PP
1211 Say you have a page that you know has malformed output, and you want to
1212 update it so the links come out correctly:
1213 .PP
1214 .Vb 3
1215 \&    my $html = $mech\->content;
1216 \&    $html =~ s[</option>.{0,3}</td>][</option></select></td>]isg;
1217 \&    $mech\->update_html( $html );
1218 .Ve
1219 .PP
1220 This method is also used internally by the mech itself to update its
1221 own \s-1HTML\s0 content when loading a page. This means that if you would
1222 like to \fIsystematically\fR perform the above \s-1HTML\s0 substitution, you
1223 would overload \fIupdate_html\fR in a subclass thusly:
1224 .PP
1225 .Vb 2
1226 \&   package MyMech;
1227 \&   use base \*(AqWWW::Mechanize\*(Aq;
1228 \&
1229 \&   sub update_html {
1230 \&       my ($self, $html) = @_;
1231 \&       $html =~ s[</option>.{0,3}</td>][</option></select></td>]isg;
1232 \&       $self\->WWW::Mechanize::update_html( $html );
1233 \&   }
1234 .Ve
1235 .PP
1236 If you do this, then the mech will use the tidied-up \s-1HTML\s0 instead of
1237 the original both when parsing for its own needs, and for returning to
1238 you through \*(L"content\*(R".
1239 .PP
1240 Overloading this method is also the recommended way of implementing
1241 extra validation steps (e.g. link checkers) for every \s-1HTML\s0 page
1242 received.  \*(L"warn\*(R" and \*(L"die\*(R" would then come in handy to signal
1243 validation errors.
1244 .ie n .SS "$mech\->credentials( $username, $password )"
1245 .el .SS "\f(CW$mech\fP\->credentials( \f(CW$username\fP, \f(CW$password\fP )"
1246 .IX Subsection "$mech->credentials( $username, $password )"
1247 Provide credentials to be used for \s-1HTTP\s0 Basic authentication for
1248 all sites and realms until further notice.
1249 .PP
1250 The four argument form described in LWP::UserAgent is still
1251 supported.
1252 .ie n .SS "$mech\->get_basic_credentials( $realm, $uri, $isproxy )"
1253 .el .SS "\f(CW$mech\fP\->get_basic_credentials( \f(CW$realm\fP, \f(CW$uri\fP, \f(CW$isproxy\fP )"
1254 .IX Subsection "$mech->get_basic_credentials( $realm, $uri, $isproxy )"
1255 Returns the credentials for the realm and \s-1URI\s0.
1256 .ie n .SS "$mech\->\fIclear_credentials()\fP"
1257 .el .SS "\f(CW$mech\fP\->\fIclear_credentials()\fP"
1258 .IX Subsection "$mech->clear_credentials()"
1259 Remove any credentials set up with \f(CW\*(C`credentials()\*(C'\fR.
1260 .SH "INTERNAL-ONLY METHODS"
1261 .IX Header "INTERNAL-ONLY METHODS"
1262 These methods are only used internally.  You probably don't need to
1263 know about them.
1264 .ie n .SS "$mech\->_update_page($request, $response)"
1265 .el .SS "\f(CW$mech\fP\->_update_page($request, \f(CW$response\fP)"
1266 .IX Subsection "$mech->_update_page($request, $response)"
1267 Updates all internal variables in \f(CW$mech\fR as if \f(CW$request\fR was just
1268 performed, and returns \f(CW$response\fR. The page stack is \fBnot\fR altered by
1269 this method, it is up to caller (e.g. \*(L"request\*(R") to do that.
1270 .ie n .SS "$mech\->_modify_request( $req )"
1271 .el .SS "\f(CW$mech\fP\->_modify_request( \f(CW$req\fP )"
1272 .IX Subsection "$mech->_modify_request( $req )"
1273 Modifies a HTTP::Request before the request is sent out,
1274 for both \s-1GET\s0 and \s-1POST\s0 requests.
1275 .PP
1276 We add a \f(CW\*(C`Referer\*(C'\fR header, as well as header to note that we can accept gzip
1277 encoded content, if Compress::Zlib is installed.
1278 .ie n .SS "$mech\->\fI_make_request()\fP"
1279 .el .SS "\f(CW$mech\fP\->\fI_make_request()\fP"
1280 .IX Subsection "$mech->_make_request()"
1281 Convenience method to make it easier for subclasses like
1282 WWW::Mechanize::Cached to intercept the request.
1283 .ie n .SS "$mech\->\fI_reset_page()\fP"
1284 .el .SS "\f(CW$mech\fP\->\fI_reset_page()\fP"
1285 .IX Subsection "$mech->_reset_page()"
1286 Resets the internal fields that track page parsed stuff.
1287 .ie n .SS "$mech\->\fI_extract_links()\fP"
1288 .el .SS "\f(CW$mech\fP\->\fI_extract_links()\fP"
1289 .IX Subsection "$mech->_extract_links()"
1290 Extracts links from the content of a webpage, and populates the \f(CW\*(C`{links}\*(C'\fR
1291 property with WWW::Mechanize::Link objects.
1292 .ie n .SS "$mech\->\fI_push_page_stack()\fP"
1293 .el .SS "\f(CW$mech\fP\->\fI_push_page_stack()\fP"
1294 .IX Subsection "$mech->_push_page_stack()"
1295 The agent keeps a stack of visited pages, which it can pop when it needs
1296 to go \s-1BACK\s0 and so on.
1297 .PP
1298 The current page needs to be pushed onto the stack before we get a new
1299 page, and the stack needs to be popped when \s-1BACK\s0 occurs.
1300 .PP
1301 Neither of these take any arguments, they just operate on the \f(CW$mech\fR
1302 object.
1303 .ie n .SS "warn( @messages )"
1304 .el .SS "warn( \f(CW@messages\fP )"
1305 .IX Subsection "warn( @messages )"
1306 Centralized warning method, for diagnostics and non-fatal problems.
1307 Defaults to calling \f(CW\*(C`CORE::warn\*(C'\fR, but may be overridden by setting
1308 \&\f(CW\*(C`onwarn\*(C'\fR in the constructor.
1309 .ie n .SS "die( @messages )"
1310 .el .SS "die( \f(CW@messages\fP )"
1311 .IX Subsection "die( @messages )"
1312 Centralized error method.  Defaults to calling \f(CW\*(C`CORE::die\*(C'\fR, but
1313 may be overridden by setting \f(CW\*(C`onerror\*(C'\fR in the constructor.
1314 .SH "REQUESTS & BUGS"
1315 .IX Header "REQUESTS & BUGS"
1316 The bug queue for WWW::Mechanize and Test::WWW::Mechanize is at
1317 <http://code.google.com/p/www\-mechanize/issues/list>.  Please do
1318 not add any tickets to the old queue at <http://rt.cpan.org/>.
1319 .SH "WWW::MECHANIZE'S SUBVERSION REPOSITORY"
1320 .IX Header "WWW::MECHANIZE'S SUBVERSION REPOSITORY"
1321 Mech and Test::WWW::Mechanize are both hosted at Google Code:
1322 http://code.google.com/p/www\-mechanize/.  The Subversion repository
1323 is at http://www\-mechanize.googlecode.com/svn/wm/.
1324 .SH "OTHER DOCUMENTATION"
1325 .IX Header "OTHER DOCUMENTATION"
1326 .SS "\fISpidering Hacks\fP, by Kevin Hemenway and Tara Calishain"
1327 .IX Subsection "Spidering Hacks, by Kevin Hemenway and Tara Calishain"
1328 \&\fISpidering Hacks\fR from O'Reilly
1329 (<http://www.oreilly.com/catalog/spiderhks/>) is a great book for anyone
1330 wanting to know more about screen-scraping and spidering.
1331 .PP
1332 There are six hacks that use Mech or a Mech derivative:
1333 .IP "#21 WWW::Mechanize 101" 4
1334 .IX Item "#21 WWW::Mechanize 101"
1335 .PD 0
1336 .IP "#22 Scraping with WWW::Mechanize" 4
1337 .IX Item "#22 Scraping with WWW::Mechanize"
1338 .IP "#36 Downloading Images from Webshots" 4
1339 .IX Item "#36 Downloading Images from Webshots"
1340 .IP "#44 Archiving Yahoo! Groups Messages with WWW::Yahoo::Groups" 4
1341 .IX Item "#44 Archiving Yahoo! Groups Messages with WWW::Yahoo::Groups"
1342 .IP "#64 Super Author Searching" 4
1343 .IX Item "#64 Super Author Searching"
1344 .IP "#73 Scraping \s-1TV\s0 Listings" 4
1345 .IX Item "#73 Scraping TV Listings"
1346 .PD
1347 .PP
1348 The book was also positively reviewed on Slashdot:
1349 <http://books.slashdot.org/article.pl?sid=03/12/11/2126256>
1350 .SH "ONLINE RESOURCES AND SUPPORT"
1351 .IX Header "ONLINE RESOURCES AND SUPPORT"
1352 .IP "\(bu" 4
1353 WWW::Mechanize mailing list
1354 .Sp
1355 The Mech mailing list is at
1356 <http://groups.google.com/group/www\-mechanize\-users> and is specific
1357 to Mechanize, unlike the \s-1LWP\s0 mailing list below.  Although it is a
1358 users list, all development discussion takes place here, too.
1359 .IP "\(bu" 4
1360 \&\s-1LWP\s0 mailing list
1361 .Sp
1362 The \s-1LWP\s0 mailing list is at
1363 <http://lists.perl.org/showlist.cgi?name=libwww>, and is more
1364 user-oriented and well-populated than the WWW::Mechanize list.
1365 .IP "\(bu" 4
1366 Perlmonks
1367 .Sp
1368 <http://perlmonks.org> is an excellent community of support, and
1369 many questions about Mech have already been answered there.
1370 .IP "\(bu" 4
1371 WWW::Mechanize::Examples
1372 .Sp
1373 A random array of examples submitted by users, included with the
1374 Mechanize distribution.
1375 .SH "ARTICLES ABOUT WWW::MECHANIZE"
1376 .IX Header "ARTICLES ABOUT WWW::MECHANIZE"
1377 .IP "\(bu" 4
1378 <http://www\-128.ibm.com/developerworks/linux/library/wa\-perlsecure.html>
1379 .Sp
1380 \&\s-1IBM\s0 article \*(L"Secure Web site access with Perl\*(R"
1381 .IP "\(bu" 4
1382 <http://www.oreilly.com/catalog/googlehks2/chapter/hack84.pdf>
1383 .Sp
1384 Leland Johnson's hack #84 in \fIGoogle Hacks, 2nd Edition\fR is
1385 an example of a production script that uses WWW::Mechanize and
1386 HTML::TableContentParser. It takes in keywords and returns the estimated
1387 price of these keywords on Google's AdWords program.
1388 .IP "\(bu" 4
1389 <http://www.perl.com/pub/a/2004/06/04/recorder.html>
1390 .Sp
1391 Linda Julien writes about using HTTP::Recorder to create WWW::Mechanize
1392 scripts.
1393 .IP "\(bu" 4
1394 <http://www.developer.com/lang/other/article.php/3454041>
1395 .Sp
1396 Jason Gilmore's article on using WWW::Mechanize for scraping sales
1397 information from Amazon and eBay.
1398 .IP "\(bu" 4
1399 <http://www.perl.com/pub/a/2003/01/22/mechanize.html>
1400 .Sp
1401 Chris Ball's article about using WWW::Mechanize for scraping \s-1TV\s0
1402 listings.
1403 .IP "\(bu" 4
1404 <http://www.stonehenge.com/merlyn/LinuxMag/col47.html>
1405 .Sp
1406 Randal Schwartz's article on scraping Yahoo News for images.  It's
1407 already out of date: He manually walks the list of links hunting
1408 for matches, which wouldn't have been necessary if the \f(CW\*(C`find_link()\*(C'\fR
1409 method existed at press time.
1410 .IP "\(bu" 4
1411 <http://www.perladvent.org/2002/16th/>
1412 .Sp
1413 WWW::Mechanize on the Perl Advent Calendar, by Mark Fowler.
1414 .IP "\(bu" 4
1415 <http://www.linux\-magazin.de/Artikel/ausgabe/2004/03/perl/perl.html>
1416 .Sp
1417 Michael Schilli's article on Mech and WWW::Mechanize::Shell for the
1418 German magazine \fILinux Magazin\fR.
1419 .SS "Other modules that use Mechanize"
1420 .IX Subsection "Other modules that use Mechanize"
1421 Here are modules that use or subclass Mechanize.  Let me know of any others:
1422 .IP "\(bu" 4
1423 Finance::Bank::LloydsTSB
1424 .IP "\(bu" 4
1425 HTTP::Recorder
1426 .Sp
1427 Acts as a proxy for web interaction, and then generates WWW::Mechanize scripts.
1428 .IP "\(bu" 4
1429 Win32::IE::Mechanize
1430 .Sp
1431 Just like Mech, but using Microsoft Internet Explorer to do the work.
1432 .IP "\(bu" 4
1433 WWW::Bugzilla
1434 .IP "\(bu" 4
1435 WWW::CheckSite
1436 .IP "\(bu" 4
1437 WWW::Google::Groups
1438 .IP "\(bu" 4
1439 WWW::Hotmail
1440 .IP "\(bu" 4
1441 WWW::Mechanize::Cached
1442 .IP "\(bu" 4
1443 WWW::Mechanize::FormFiller
1444 .IP "\(bu" 4
1445 WWW::Mechanize::Shell
1446 .IP "\(bu" 4
1447 WWW::Mechanize::Sleepy
1448 .IP "\(bu" 4
1449 WWW::Mechanize::SpamCop
1450 .IP "\(bu" 4
1451 WWW::Mechanize::Timed
1452 .IP "\(bu" 4
1453 WWW::SourceForge
1454 .IP "\(bu" 4
1455 WWW::Yahoo::Groups
1456 .SH "ACKNOWLEDGEMENTS"
1457 .IX Header "ACKNOWLEDGEMENTS"
1458 Thanks to the numerous people who have helped out on WWW::Mechanize in
1459 one way or another, including
1460 Kirrily Robert for the original \f(CW\*(C`WWW::Automate\*(C'\fR,
1461 Gisle Aas,
1462 Jeremy Ary,
1463 Hilary Holz,
1464 Rafael Kitover,
1465 Norbert Buchmuller,
1466 Dave Page,
1467 David Sainty,
1468 H.Merijn Brand,
1469 Matt Lawrence,
1470 Michael Schwern,
1471 Adriano Ferreira,
1472 Miyagawa,
1473 Peteris Krumins,
1474 Rafael Kitover,
1475 David Steinbrunner,
1476 Kevin Falcone,
1477 Mike O'Regan,
1478 Mark Stosberg,
1479 Uri Guttman,
1480 Peter Scott,
1481 Phillipe Bruhat,
1482 Ian Langworth,
1483 John Beppu,
1484 Gavin Estey,
1485 Jim Brandt,
1486 Ask Bjoern Hansen,
1487 Greg Davies,
1488 Ed Silva,
1489 Mark-Jason Dominus,
1490 Autrijus Tang,
1491 Mark Fowler,
1492 Stuart Children,
1493 Max Maischein,
1494 Meng Wong,
1495 Prakash Kailasa,
1496 Abigail,
1497 Jan Pazdziora,
1498 Dominique Quatravaux,
1499 Scott Lanning,
1500 Rob Casey,
1501 Leland Johnson,
1502 Joshua Gatcomb,
1503 Julien Beasley,
1504 Abe Timmerman,
1505 Peter Stevens,
1506 Pete Krawczyk,
1507 Tad McClellan,
1508 and the late great Iain Truskett.
1509 .SH "COPYRIGHT"
1510 .IX Header "COPYRIGHT"
1511 Copyright (c) 2005\-2009 Andy Lester. All rights reserved. This program is
1512 free software; you can redistribute it and/or modify it under the same
1513 terms as Perl itself.