package HTML::Form;

use strict;
use URI;
use Carp ();

use vars qw($VERSION);
$VERSION = "5.817";

my %form_tags = map {$_ => 1} qw(input textarea button select option);

my %type2class = (
 text     => "TextInput",
 password => "TextInput",
 hidden   => "TextInput",
 textarea => "TextInput",

 "reset"  => "IgnoreInput",

 radio    => "ListInput",
 checkbox => "ListInput",
 option   => "ListInput",

 button   => "SubmitInput",
 submit   => "SubmitInput",
 image    => "ImageInput",
 file     => "FileInput",

 keygen   => "KeygenInput",
);

=head1 NAME

HTML::Form - Class that represents an HTML form element

=head1 SYNOPSIS

 use HTML::Form;
 $form = HTML::Form->parse($html, $base_uri);
 $form->value(query => "Perl");

 use LWP::UserAgent;
 $ua = LWP::UserAgent->new;
 $response = $ua->request($form->click);

=head1 DESCRIPTION

Objects of the C<HTML::Form> class represents a single HTML
C<E<lt>formE<gt> ... E<lt>/formE<gt>> instance.  A form consists of a
sequence of inputs that usually have names, and which can take on
various values.  The state of a form can be tweaked and it can then be
asked to provide C<HTTP::Request> objects that can be passed to the
request() method of C<LWP::UserAgent>.

The following methods are available:

=over 4

=item @forms = HTML::Form->parse( $response )

=item @forms = HTML::Form->parse( $html_document, $base )

=item @forms = HTML::Form->parse( $html_document, %opt )

The parse() class method will parse an HTML document and build up
C<HTML::Form> objects for each <form> element found.  If called in scalar
context only returns the first <form>.  Returns an empty list if there
are no forms to be found.

The $base is the URI used to retrieve the $html_document.  It is
needed to resolve relative action URIs.  If the document was retrieved
with LWP then this this parameter is obtained from the
$response->base() method, as shown by the following example:

    my $ua = LWP::UserAgent->new;
    my $response = $ua->get("http://www.example.com/form.html");
    my @forms = HTML::Form->parse($response->decoded_content,
				  $response->base);

The parse() method can parse from an C<HTTP::Response> object
directly, so the example above can be more conveniently written as:

    my $ua = LWP::UserAgent->new;
    my $response = $ua->get("http://www.example.com/form.html");
    my @forms = HTML::Form->parse($response);

Note that any object that implements a decoded_content() and base() method
with similar behaviour as C<HTTP::Response> will do.

Finally options might be passed in to control how the parse method
behaves.  The following options are currently recognized:

=over

=item C<< base => $uri >>

Another way to provide the base URI.

=item C<< verbose => $bool >>