.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "WWW::Mechanize::Shell 3pm"
.TH WWW::Mechanize::Shell 3pm "2023-08-21" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
WWW::Mechanize::Shell \- An interactive shell for WWW::Mechanize
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
From the command line as
.PP
.Vb 1
\&  perl \-MWWW::Mechanize::Shell \-eshell
.Ve
.PP
or alternatively as a custom shell program via :
.PP
.Vb 3
\&  #!/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;
\&  };
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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.
.ie n .SS """WWW::Mechanize::Shell\->new %ARGS"""
.el .SS "\f(CWWWW::Mechanize::Shell\->new %ARGS\fP"
.IX Subsection "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.
.PP
By default, a file \f(CW\*(C`.mechanizerc\*(C'\fR (respectively \f(CW\*(C`mechanizerc\*(C'\fR 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 \f(CW\*(C`rcfile\*(C'\fR parameter can be passed to the constructor :
.PP
.Vb 1
\&  rcfile => \*(Aq.myapprc\*(Aq,
.Ve
.IP "\fBagent\fR" 4
.IX Item "agent"
.Vb 3
\&  my $shell = WWW::Mechanize::Shell\->new(
\&      agent => WWW::Mechanize::Chrome\->new(),
\&  );
.Ve
.Sp
Pass in a premade custom user agent. This object must be compatible to
WWW::Mechanize. Use this feature from the command line as
.Sp
.Vb 3
\&  perl \-Ilib \-MWWW::Mechanize::Chrome \e
\&             \-MWWW::Mechanize::Shell \e
\&             \-e"shell(agent => WWW::Mechanize::Chrome\->new())"
.Ve
.ie n .SS """$shell\->release_agent"""
.el .SS "\f(CW$shell\->release_agent\fP"
.IX Subsection "$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.
.ie n .SS """$shell\->source_file FILENAME"""
.el .SS "\f(CW$shell\->source_file FILENAME\fP"
.IX Subsection "$shell->source_file FILENAME"
The \f(CW\*(C`source_file\*(C'\fR method executes the lines of \s-1FILENAME\s0
as if they were typed in.
.PP
.Vb 1
\&  $shell\->source_file( $filename );
.Ve
.ie n .SS """$shell\->display_user_warning"""
.el .SS "\f(CW$shell\->display_user_warning\fP"
.IX Subsection "$shell->display_user_warning"
All user warnings are routed through this routine
so they can be rerouted / disabled easily.
.ie n .SS """$shell\->print_paged LIST"""
.el .SS "\f(CW$shell\->print_paged LIST\fP"
.IX Subsection "$shell->print_paged LIST"
Prints the text in \s-1LIST\s0 using \f(CW$ENV{PAGER}\fR. If \f(CW$ENV{PAGER}\fR
is empty, prints directly to \f(CW\*(C`STDOUT\*(C'\fR. Most of this routine
comes from the \f(CW\*(C`perldoc\*(C'\fR utility.
.ie n .SS """$shell\->link_text LINK"""
.el .SS "\f(CW$shell\->link_text LINK\fP"
.IX Subsection "$shell->link_text LINK"
Returns a meaningful text from a WWW::Mechanize::Link object. This is (in order of
precedence) :
.PP
.Vb 3
\&    $link\->text
\&    $link\->name
\&    $link\->url
.Ve
.ie n .SS """$shell\->history"""
.el .SS "\f(CW$shell\->history\fP"
.IX Subsection "$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.
.PP
.Vb 1
\&  print join "\en", $shell\->history;
.Ve
.ie n .SS """$shell\->script"""
.el .SS "\f(CW$shell\->script\fP"
.IX Subsection "$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.
.PP
.Vb 1
\&  print join "\en", $shell\->script;
.Ve
.ie n .SS """$shell\->status"""
.el .SS "\f(CW$shell\->status\fP"
.IX Subsection "$shell->status"
\&\f(CW\*(C`status\*(C'\fR is called for status updates.
.ie n .SS """$shell\->display FILENAME LINES"""
.el .SS "\f(CW$shell\->display FILENAME LINES\fP"
.IX Subsection "$shell->display FILENAME LINES"
\&\f(CW\*(C`display\*(C'\fR is called to output listings, currently from the
\&\f(CW\*(C`history\*(C'\fR and \f(CW\*(C`script\*(C'\fR 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.
.SH "COMMANDS"
.IX Header "COMMANDS"
The shell implements various commands :
.SS "exit"
.IX Subsection "exit"
Leaves the shell.
.SS "restart"
.IX Subsection "restart"
Restart the shell.
.PP
This is mostly useful when you are modifying the shell itself. It doesn't
work if you use the shell in oneliner mode with \f(CW\*(C`\-e\*(C'\fR.
.SS "get"
.IX Subsection "get"
Download a specific \s-1URL.\s0
.PP
This is used as the entry point in all sessions
.PP
Syntax:
.PP
.Vb 1
\&  get URL
.Ve
.SS "save"
.IX Subsection "save"
Download a link into a file.
.PP
If more than one link matches the \s-1RE,\s0 all matching links are
saved. The filename is taken from the last part of the
\&\s-1URL.\s0 Alternatively, the number of a link may also be given.
.PP
Syntax:
.PP
.Vb 1
\&  save RE
.Ve
.SS "content"
.IX Subsection "content"
Display the content for the current page.
.PP
Syntax: content [\s-1FILENAME\s0]
.PP
If the \s-1FILENAME\s0 argument is provided, save the content to the file.
.PP
A trailing \*(L"\en\*(R" is added to the end of the content when using the
shell, so this might not be ideally suited to save binary files without
manual editing of the produced script.
.SS "title"
.IX Subsection "title"
Display the current page title as found
in the \f(CW\*(C`<TITLE>\*(C'\fR tag.
.SS "headers"
.IX Subsection "headers"
Prints all \f(CW\*(C`<H1>\*(C'\fR through \f(CW\*(C`<H5>\*(C'\fR strings found in the content,
indented accordingly.  With an argument, prints only those
levels; e.g., \f(CW\*(C`headers 145\*(C'\fR prints H1,H4,H5 strings only.
.SS "ua"
.IX Subsection "ua"
Get/set the current user agent
.PP
Syntax:
.PP
.Vb 2
\&  # 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 ""
.Ve
.SS "links"
.IX Subsection "links"
Display all links on a page
.PP
The links numbers displayed can used by \f(CW\*(C`open\*(C'\fR to directly
select a link to follow.
.SS "images"
.IX Subsection "images"
Display images on a page
.SS "parse"
.IX Subsection "parse"
Dump the output of HTML::TokeParser of the current content
.SS "forms"
.IX Subsection "forms"
Display all forms on the current page.
.SS "form"
.IX Subsection "form"
Select the form named \s-1NAME\s0
.PP
If \s-1NAME\s0 matches \f(CW\*(C`/^\ed+$/\*(C'\fR, it is assumed to be the (1\-based) index
of the form to select. There is no way of selecting a numerically
named form by its name.
.SS "dump"
.IX Subsection "dump"
Dump the values of the current form
.SS "value"
.IX Subsection "value"
Set a form value
.PP
Syntax:
.PP
.Vb 1
\&  value NAME [VALUE]
.Ve
.SS "tick"
.IX Subsection "tick"
Set checkbox marks
.PP
Syntax:
.PP
.Vb 1
\&  tick NAME VALUE(s)
.Ve
.PP
If no value is given, all boxes are checked.
.SS "untick"
.IX Subsection "untick"
Remove checkbox marks
.PP
Syntax:
.PP
.Vb 1
\&  untick NAME VALUE(s)
.Ve
.PP
If no value is given, all marks are removed.
.SS "submit"
.IX Subsection "submit"
submits the form without clicking on any button
.SS "click"
.IX Subsection "click"
Clicks on the button named \s-1NAME.\s0
.PP
No regular expression expansion is done on \s-1NAME.\s0
.PP
Syntax:
.PP
.Vb 1
\&  click NAME
.Ve
.PP
If you have a button that has no name (displayed as \s-1NONAME\s0),
use
.PP
.Vb 1
\&  click ""
.Ve
.PP
to click on it.
.SS "open"
.IX Subsection "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
\&\f(CW\*(C`links\*(C'\fR function. It goes directly to the page if a number is used
or if the \s-1RE\s0 has one match. Otherwise, a list of links matching
the regular expression is displayed.
.PP
The regular expression should start and end with \*(L"/\*(R".
.PP
Syntax:
.PP
.Vb 1
\&  open  [ RE | # ]
.Ve
.SS "back"
.IX Subsection "back"
Go back one page in the browser page history.
.SS "reload"
.IX Subsection "reload"
Repeat the last request, thus reloading the current page.
.PP
Note that also \s-1POST\s0 requests are blindly repeated, as this command
is mostly intended to be used when testing server side code.
.SS "browse"
.IX Subsection "browse"
Open the web browser with the current page
.PP
Displays the current page in the browser.
.SS "set"
.IX Subsection "set"
Set a shell option
.PP
Syntax:
.PP
.Vb 1
\&   set OPTION [value]
.Ve
.PP
The command lists all valid options. Here is a short overview over
the different options available :
.PP
.Vb 9
\&    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
\&    dumpresponses \- dump the headers of the responses to STDOUT
\&    verbose       \- print commands to STDERR as they are run,
\&                    when sourcing from a file
.Ve
.SS "history"
.IX Subsection "history"
Display your current session history as the relevant commands.
.PP
Syntax:
.PP
.Vb 1
\&  history [FILENAME]
.Ve
.PP
Commands that have no influence on the browser state are not added
to the history. If a parameter is given to the \f(CW\*(C`history\*(C'\fR command,
the history is saved to that file instead of displayed onscreen.
.SS "script"
.IX Subsection "script"
Display your current session history as a Perl script using WWW::Mechanize.
.PP
Syntax:
.PP
.Vb 1
\&  script [FILENAME]
.Ve
.PP
If a parameter is given to the \f(CW\*(C`script\*(C'\fR command, the script is saved to
that file instead of displayed on the console.
.PP
This command was formerly known as \f(CW\*(C`history\*(C'\fR.
.SS "comment"
.IX Subsection "comment"
Adds a comment to the script and the history. The comment
is prepended with a \en to increase readability.
.SS "fillout"
.IX Subsection "fillout"
Fill out the current form
.PP
Interactively asks the values hat have no preset
value via the autofill command.
.SS "auth"
.IX Subsection "auth"
Set basic authentication credentials.
.PP
Syntax:
.PP
.Vb 1
\&  auth user password
.Ve
.PP
If you know the authority and the realm in advance, you can
presupply the credentials, for example at the start of the script :
.PP
.Vb 4
\&        >auth corion secret
\&        >get http://www.example.com
\&        Retrieving http://www.example.com(200)
\&        http://www.example.com>
.Ve
.SS "table"
.IX Subsection "table"
Display a table described by the columns \s-1COLUMNS.\s0
.PP
Syntax:
.PP
.Vb 1
\&  table COLUMNS
.Ve
.PP
Example:
.PP
.Vb 1
\&  table Product Price Description
.Ve
.PP
If there is a table on the current page that has in its first row the three
columns \f(CW\*(C`Product\*(C'\fR, \f(CW\*(C`Price\*(C'\fR and \f(CW\*(C`Description\*(C'\fR (not necessarily in that order),
the script will display these columns of the whole table.
.PP
The \f(CW\*(C`HTML::TableExtract\*(C'\fR module is needed for this feature.
.SS "tables"
.IX Subsection "tables"
Display a list of tables.
.PP
Syntax:
.PP
.Vb 1
\&  tables
.Ve
.PP
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.
.PP
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.
.PP
HTML::TableExtract is needed for this feature.
.SS "cookies"
.IX Subsection "cookies"
Set the cookie file name
.PP
Syntax:
.PP
.Vb 1
\&  cookies FILENAME
.Ve
.SS "autofill"
.IX Subsection "autofill"
Define an automatic value
.PP
Sets a form value to be filled automatically. The \s-1NAME\s0 parameter is
the WWW::Mechanize::FormFiller::Value subclass you want to use. For
session fields, \f(CW\*(C`Keep\*(C'\fR is a good candidate, for interactive stuff,
\&\f(CW\*(C`Ask\*(C'\fR is a value implemented by the shell.
.PP
A field name starting and ending with a slash (\f(CW\*(C`/\*(C'\fR) is taken to be
a regular expression and will be applied to all fields with their
name matching the expression. A field with a matching name still
takes precedence over the regular expression.
.PP
Syntax:
.PP
.Vb 1
\&  autofill NAME [PARAMETERS]
.Ve
.PP
Examples:
.PP
.Vb 5
\&  autofill login Fixed corion
\&  autofill password Ask
\&  autofill selection Random red green orange
\&  autofill session Keep
\&  autofill "/date$/" Random::Date string "%m/%d/%Y"
.Ve
.SS "eval"
.IX Subsection "eval"
Evaluate Perl code and print the result
.PP
Syntax:
.PP
.Vb 1
\&  eval CODE
.Ve
.PP
For the generated scripts, anything matching the regular expression
\&\f(CW\*(C`/\e$self\->agent\eb/\*(C'\fR is automatically
replaced by \f(CW$agent\fR in your eval code, to do the Right Thing.
.PP
Examples:
.PP
.Vb 2
\&  # Say hello
\&  eval "Hello World"
\&
\&  # And take a look at the current content type
\&  eval $self\->agent\->ct
.Ve
.SS "source"
.IX Subsection "source"
Execute a batch of commands from a file
.PP
Syntax:
.PP
.Vb 1
\&  source FILENAME
.Ve
.SS "versions"
.IX Subsection "versions"
Print the version numbers of important modules
.PP
Syntax:
.PP
.Vb 1
\&  versions
.Ve
.SS "timeout"
.IX Subsection "timeout"
Set new timeout value for the agent. Effects all subsequent
requests. \s-1VALUE\s0 is in seconds.
.PP
Syntax:
.PP
.Vb 1
\&  timeout VALUE
.Ve
.SS "ct"
.IX Subsection "ct"
prints the content type of the most current response.
.PP
Syntax:
.PP
.Vb 1
\&  ct
.Ve
.SS "referrer"
.IX Subsection "referrer"
set the value of the Referer: header
.PP
Syntax:
.PP
.Vb 2
\&  referer URL
\&  referrer URL
.Ve
.SS "referer"
.IX Subsection "referer"
Alias for referrer
.SS "response"
.IX Subsection "response"
display the last server response
.ie n .SS """$shell\->munge_code( CODE )"""
.el .SS "\f(CW$shell\->munge_code( CODE )\fP"
.IX Subsection "$shell->munge_code( CODE )"
Munges a coderef to become code fit for
output independent of WWW::Mechanize::Shell.
.ie n .SS """shell"""
.el .SS "\f(CWshell\fP"
.IX Subsection "shell"
This subroutine is exported by default as a convenience method
so that the following oneliner invocation works:
.PP
.Vb 1
\&    perl \-MWWW::Mechanize::Shell \-eshell
.Ve
.PP
You can pass constructor arguments to this
routine as well. Any scripts given in \f(CW@ARGV\fR
will be run. If \f(CW@ARGV\fR is empty,
an interactive loop will be started.
.SH "SAMPLE SESSIONS"
.IX Header "SAMPLE SESSIONS"
.SS "Entering values"
.IX Subsection "Entering values"
.Vb 7
\&  # 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\*(Aqt)
.Ve
.SS "Retrieving a table"
.IX Subsection "Retrieving a table"
.Vb 6
\&  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.
.Ve
.SS "Uploading a file"
.IX Subsection "Uploading a file"
.Vb 3
\&  get http://aliens:xxxxx/
\&  value f path/to/file
\&  click "upload"
.Ve
.SS "Batch download"
.IX Subsection "Batch download"
.Vb 3
\&  # download prerelease versions of my modules
\&  get http://www.corion.net/perl\-dev
\&  save /.tar.gz$/
.Ve
.SH "REGULAR EXPRESSION SYNTAX"
.IX Header "REGULAR EXPRESSION SYNTAX"
Some commands take regular expressions as parameters. A regular
expression \fBmust\fR be a single parameter matching \f(CW\*(C`^/.*/([isxm]+)?$\*(C'\fR, so
you have to use quotes around it if the expression contains spaces :
.PP
.Vb 2
\&  /link_foo/       # will match as (?\-xims:link_foo)
\&  "/link foo/"     # will match as (?\-xims:link foo)
.Ve
.PP
Slashes do not need to be escaped, as the shell knows that a \s-1RE\s0 starts and
ends with a slash :
.PP
.Vb 2
\&  /link/foo/       # will match as (?\-xims:link/foo)
\&  "/link/ /foo/"   # will match as (?\-xims:link/\es/foo)
.Ve
.PP
The \f(CW\*(C`/i\*(C'\fR modifier works as expected.
If you desire more power over the regular expressions, consider dropping
to Perl or recommend me a good parser module for regular expressions.
.SH "DISPLAYING HTML"
.IX Header "DISPLAYING HTML"
WWW::Mechanize::Shell now uses the module HTML::Display
to display the \s-1HTML\s0 of the current page in your browser.
Have a look at the documentation of HTML::Display how to
make it use your browser of choice in the case it does not
already guess it correctly.
.SH "FILLING FORMS VIA CUSTOM CODE"
.IX Header "FILLING FORMS VIA CUSTOM CODE"
If you want to stay within the confines of the shell, but still
want to fill out forms using custom Perl code, here is a recipe
how to achieve this :
.PP
Code passed to the \f(CW\*(C`eval\*(C'\fR command gets evaluated in the WWW::Mechanize::Shell
namespace. You can inject new subroutines there and these get picked
up by the Callback class of WWW::Mechanize::FormFiller :
.PP
.Vb 4
\&  # Fill in the "date" field with the current date/time as string
\&  eval sub &::custom_today { scalar localtime };
\&  autofill date Callback WWW::Mechanize::Shell::custom_today
\&  fillout
.Ve
.PP
This method can also be used to retrieve data from shell scripts :
.PP
.Vb 5
\&  # Fill in the "date" field with the current date/time as string
\&  # works only if there is a program "date"
\&  eval sub &::custom_today { chomp \`date\` };
\&  autofill date Callback WWW::Mechanize::Shell::custom_today
\&  fillout
.Ve
.PP
As the namespace is different between the shell and the generated
script, make sure you always fully qualify your subroutine names,
either in your own namespace or in the main namespace.
.SH "GENERATED SCRIPTS"
.IX Header "GENERATED SCRIPTS"
The \f(CW\*(C`script\*(C'\fR command outputs a skeleton script that reproduces
your actions as done in the current session. It pulls in
\&\f(CW\*(C`WWW::Mechanize::FormFiller\*(C'\fR, which is possibly not needed. You
should add some error and connection checking afterwards.
.SH "ADDING FIELDS TO HTML"
.IX Header "ADDING FIELDS TO HTML"
If you are automating a JavaScript dependent site, you will encounter
JavaScript like this :
.PP
.Vb 3
\&    <script>
\&      document.write( "<input type=submit name=submit>" );
\&    </script>
.Ve
.PP
HTML::Form will not know about this and will not have provided a
submit button for you (understandably). If you want to create such
a submit button from within your automation script, use the following
code :
.PP
.Vb 1
\&  $agent\->current_form\->push_input( submit => { name => "submit", value =>"submit" } );
.Ve
.PP
This also works for other dynamically generated input fields.
.PP
To fake an input field from within a shell session, use the \f(CW\*(C`eval\*(C'\fR command :
.PP
.Vb 1
\&  eval $self\->agent\->current_form\->push_input(submit=>{name=>"submit",value=>"submit"});
.Ve
.PP
And yes, the generated script should do the Right Thing for this eval as well.
.SH "LOCAL FILES"
.IX Header "LOCAL FILES"
If you want to use the shell on a local file without setting up a \f(CW\*(C`http\*(C'\fR server
to serve the file, you can use the \f(CW\*(C`file:\*(C'\fR \s-1URI\s0 scheme to load it into the \*(L"browser\*(R":
.PP
.Vb 2
\&  get file:local.html
\&  forms
.Ve
.SH "PROXY SUPPORT"
.IX Header "PROXY SUPPORT"
Currently, the proxy support is realized via a call to
the \f(CW\*(C`env_proxy\*(C'\fR method of the WWW::Mechanize object, which
loads the proxies from the environment. There is no provision made
to prevent using proxies (yet). The generated scripts also
load their proxies from the environment.
.SH "ONLINE HELP"
.IX Header "ONLINE HELP"
The online help feature is currently a bit broken in \f(CW\*(C`Term::Shell\*(C'\fR,
but a fix is in the works. Until then, you can re-enable the
dynamic online help by patching \f(CW\*(C`Term::Shell\*(C'\fR :
.PP
Remove the three lines
.PP
.Vb 3
\&      my $smry = exists $o\->{handlers}{$h}{smry}
\&    ? $o\->summary($h)
\&    : "undocumented";
.Ve
.PP
in \f(CW\*(C`sub run_help\*(C'\fR and replace them by
.PP
.Vb 1
\&      my $smry = $o\->summary($h);
.Ve
.PP
The shell works without this patch and the online help is still
available through \f(CW\*(C`perldoc WWW::Mechanize::Shell\*(C'\fR
.SH "BUGS"
.IX Header "BUGS"
Bug reports are very welcome \- please use the \s-1RT\s0 interface at
https://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW\-Mechanize\-Shell or send a
descriptive mail to bug\-WWW\-Mechanize\-Shell@rt.cpan.org . Please
try to include as much (relevant) information as possible \- a test script
that replicates the undesired behaviour is welcome every time!
.IP "\(bu" 4
The two parameter version of the \f(CW\*(C`auth\*(C'\fR command guesses the realm from
the last received response. Currently a \s-1RE\s0 is used to extract the realm,
but this fails with some servers resp. in some cases. Use the four
parameter version of \f(CW\*(C`auth\*(C'\fR, or if not possible, code the extraction
in Perl, either in the final script or through \f(CW\*(C`eval\*(C'\fR commands.
.IP "\(bu" 4
The shell currently detects when you want to follow a JavaScript link and tells you
that this is not supported. It would be nicer if there was some callback mechanism
to (automatically?) extract URLs from JavaScript-infected links.
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
Add XPath expressions (by moving \f(CW\*(C`WWW::Mechanize\*(C'\fR from HTML::Parser to XML::XMLlib
or maybe easier, by tacking Class::XPath onto an \s-1HTML\s0 tree)
.IP "\(bu" 4
Add \f(CW\*(C`head\*(C'\fR as a command ?
.IP "\(bu" 4
Optionally silence the HTML::Parser / HTML::Forms warnings about invalid \s-1HTML.\s0
.SH "EXPORT"
.IX Header "EXPORT"
The routine \f(CW\*(C`shell\*(C'\fR is exported into the importing namespace. This
is mainly for convenience so you can use the following commandline
invocation of the shell like with \s-1CPAN :\s0
.PP
.Vb 1
\&  perl \-MWWW::Mechanize::Shell \-e"shell"
.Ve
.SH "REPOSITORY"
.IX Header "REPOSITORY"
The public repository of this module is
<https://github.com/Corion/WWW\-Mechanize\-Shell>.
.SH "SUPPORT"
.IX Header "SUPPORT"
The public support forum of this module is
<http://perlmonks.org/>.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
.PP
Copyright (C) 2002\-2023 Max Maischein
.SH "AUTHOR"
.IX Header "AUTHOR"
Max Maischein, <corion@cpan.org>
.PP
Please contact me if you find bugs or otherwise improve the module. More tests are also very welcome !
.SH "SEE ALSO"
.IX Header "SEE ALSO"
WWW::Mechanize,WWW::Mechanize::FormFiller,WWW::Mechanize::Firefox