/ 
WWW-Mechanize-Shell-0.23
River stage one • 1 direct dependent • 1 total dependent
3 ++
/ WWW::Mechanize::Shell

NAME

WWW::Mechanize::Shell - An interactive shell for WWW::Mechanize

SYNOPSIS

From the command line as

  perl -MWWW::Mechanize::Shell -eshell

or alternatively as a custom shell program via :

  #!/usr/bin/perl -w
  use strict;
  use WWW::Mechanize::Shell;

  my $shell = WWW::Mechanize::Shell->new("shell");

  if (@ARGV) {
    $shell->source_file( @ARGV );
  } else {
    $shell->cmdloop;
  };

DESCRIPTION

This module implements a www-like shell above WWW::Mechanize and also has the capability to output crude Perl code that recreates the recorded session. Its main use is as an interactive starting point for automating a session through WWW::Mechanize.

The cookie support is there, but no cookies are read from your existing browser sessions. See HTTP::Cookies on how to implement reading/writing your current browsers cookies.

WWW::Mechanize::Shell->new %ARGS

This is the constructor for a new shell instance. Some of the options can be passed to the constructor as parameters.

By default, a file .mechanizerc (respectively mechanizerc under Windows) in the users home directory is executed before the interactive shell loop is entered. This can be used to set some defaults. If you want to supply a different filename for the rcfile, the rcfile parameter can be passed to the constructor :

  rcfile => '.myapprc',

$shell->release_agent

Since the shell stores a reference back to itself within the WWW::Mechanize instance, it is necessary to break this circular reference. This method does this.

$shell->source_file FILENAME

The source_file method executes the lines of FILENAME as if they were typed in.

  $shell->source_file( $filename );

$shell->display_user_warning

All user warnings are routed through this routine so they can be rerouted / disabled easily.

sub prompt_str { ($_[0]->agent->uri || "") . ">" };

sub request_dumper { print $_[1]->as_string if $_[0]->option("dumprequests"); };

$shell->history

Returns the (relevant) shell history, that is, all commands that were not solely for the information of the user. The lines are returned as a list.

  print join "\n", $shell->history;

$shell->script

Returns the shell history as a Perl program. The lines are returned as a list. The lines do not have a one-by-one correspondence to the lines in the history.

  print join "\n", $shell->script;

$shell->status

status is called for status updates.

$shell->display FILENAME LINES

display is called to output listings, currently from the history and script commands. If the second parameter is defined, it is the name of the file to be written, otherwise the lines are displayed to the user.

COMMANDS

The shell implements various commands :

exit

Leaves the shell.

restart

Restart the shell.

This is mostly useful when you are modifying the shell itself. It dosen't work if you use the shell in oneliner mode with -e.

get

Download a specific URL.

This is used as the entry point in all sessions

Syntax:

  get URL

save

Download a link into a file.

If more than one link matches the RE, all matching links are saved. The filename is taken from the last part of the URL. Alternatively, the number of a link may also be given.

Syntax:

  save RE

content

Display the HTML for the current page

ua

Get/set the current user agent

Syntax:

  # fake Internet Explorer
  ua "Mozilla/4.0 (compatible; MSIE 4.01; Windows 98)"

  # fake QuickTime v5
  ua "QuickTime (qtver=5.0.2;os=Windows NT 5.0Service Pack 2)"

  # fake Mozilla/Gecko based
  ua "Mozilla/5.001 (windows; U; NT4.0; en-us) Gecko/25250101"

  # set empty user agent :
  ua ""

Display all links on a page

The links numbers displayed can used by open to directly select a link to follow.

parse

Dump the output of HTML::TokeParser of the current content

forms

Display all forms on the current page

dump

Dump the values of the current form

value

Set a form value

Syntax:

  value NAME [VALUE]

submit

Clicks on the button labeled "submit"

click

Clicks on the button named NAME.

No regular expression expansion is done on NAME.

Syntax:

  click NAME

open

<open> accepts one argument, which can be a regular expression or the number of a link on the page, starting at zero. These numbers are displayed by the links function. It goes directly to the page if a number is used or if the RE has one match. Otherwise, a list of links matching the regular expression is displayed.

The regular expression should start and end with "/".

Syntax:

  open  [ RE | # ]

back

Go back one page in the browser page history.

reload

Repeat the last request, thus reloading the current page.

Note that also POST requests are blindly repeated, as this command is mostly intended to be used when testing server side code.

browse

Open the web browser with the current page

Displays the current page in the browser.

set

Set a shell option

Syntax:

   set OPTION [value]

The command lists all valid options. Here is a short overview over the different options available :

    autosync     - automatically synchronize the browser window
    autorestart  - restart the shell when any required module changes
                   This does not work with C<-e> oneliners.
    watchfiles   - watch all required modules for changes
    cookiefile   - the file where to store all cookies
    dumprequests - dump all requests to STDOUT

history

Display your current session history as the relevant commands.

Syntax:

  history [FILENAME]

Commands that have no influence on the browser state are not added to the history. If a parameter is given to the history command, the history is saved to that file instead of displayed onscreen.

script

Display your current session history as a Perl script using WWW::Mechanize.

Syntax:

  script [FILENAME]

If a parameter is given to the script command, the script is saved to that file instead of displayed on the console.

This command was formerly known as history.

fillout

Fill out the current form

Interactively asks the values hat have no preset value via the autofill command.

auth

Set basic authentication credentials.

Syntax:

  auth [authority realm] user password

If you get back a 401, you can simply supply the matching user and password, as the authority and realm are already known :

        >get http://www.example.com
        Retrieving http://www.example.com(401)
        http://www.example.com>auth corion secret
        http://www.example.com>get http://www.example.com
        Retrieving http://www.example.com(200)
        http://www.example.com>

If you know the authority and the realm in advance, you can presupply the credentials, for example at the start of the script :

        >auth www.example.com:80 secure_realm corion secret
        >get http://www.example.com
        Retrieving http://www.example.com(200)
        http://www.example.com>

table

Display a table described by the columns COLUMNS.

Syntax:

  table COLUMNS

Example:

  table Product Price Description

If there is a table on the current page that has in its first row the three columns Product, Price and Description (not necessarily in that order), the script will display these columns of the whole table.

The HTML::TableExtract module is needed for this feature.

tables

Display a list of tables.

Syntax:

  tables

This command will display the top row for every table on the current page. This is convenient if you want to find out what the exact spellings for each column are.

The command does not always work nice, for example if a site uses tables for layout, it will be harder to guess what tables are irrelevant and what tables are relevant.

HTML::TableExtract is needed for this feature.

cookies

Set the cookie file name

Syntax:

  cookies FILENAME

autofill

Define an automatic value

Sets a form value to be filled automatically. The NAME parameter is the WWW::Mechanize::FormFiller::Value subclass you want to use. For session fields, Keep is a good candidate, for interactive stuff, Ask is a value implemented by the shell.

Syntax:

  autofill NAME [PARAMETERS]

Examples:

  autofill login Fixed corion
  autofill password Ask
  autofill selection Random red green orange
  autofill session Keep

eval

Evaluate Perl code and print the result

Syntax:

  eval CODE

For the generated scripts, anything matching the regular expression /\$self->agent\b/ is automatically replaced by $agent in your eval code, to do the Right Thing.

Examples:

  # Say hello
  eval "Hello World"

  # And take a look at the current content type
  eval $self->agent->ct

source

Execute a batch of commands from a file

Syntax:

  source FILENAME

versions

Print the version numbers of important modules

Syntax:

  versions

SAMPLE SESSIONS

Entering values

  # Search for a term on Google
  get http://www.google.com
  value q "Corions Homepage"
  click btnG
  script
  # (yes, this is a bad example of automating, as Google
  #  already has a Perl API. But other sites don't)

Retrieving a table

  get http://www.perlmonks.org
  open "/Saints in/"
  table User Experience Level
  script
  # now you have a program that gives you a csv file of
  # that table.

Uploading a file

  get http://aliens:xxxxx/
  value f path/to/file
  click "upload"

Batch download

  # download prerelease versions of my modules
  get http://www.corion.net/perl-dev
  save /.tar.gz$/