argra****@users*****
argra****@users*****
2010年 10月 21日 (木) 04:56:20 JST
Index: docs/modules/libwww-perl-5.813/HTML/Form.pod
diff -u /dev/null docs/modules/libwww-perl-5.813/HTML/Form.pod:1.1
--- /dev/null Thu Oct 21 04:56:20 2010
+++ docs/modules/libwww-perl-5.813/HTML/Form.pod Thu Oct 21 04:56:20 2010
@@ -0,0 +1,973 @@
+
+=encoding euc-jp
+
+=head1 NAME
+
+=begin original
+
+HTML::Form - Class that represents an HTML form element
+
+=end original
+
+HTML::Form - HTML フォーム要素を表現するクラス
+
+=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
+
+=begin original
+
+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>.
+
+=end original
+
+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>.
+(TBT)
+
+=begin original
+
+The following methods are available:
+
+=end original
+
+以下のメソッドが利用可能です:
+
+=over 4
+
+=item @forms = HTML::Form->parse( $response )
+
+=item @forms = HTML::Form->parse( $html_document, $base )
+
+=item @forms = HTML::Form->parse( $html_document, %opt )
+
+=begin original
+
+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.
+
+=end original
+
+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.
+(TBT)
+
+=begin original
+
+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:
+
+=end original
+
+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:
+(TBT)
+
+ 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);
+
+=begin original
+
+The parse() method can parse from an C<HTTP::Response> object
+directly, so the example above can be more conveniently written as:
+
+=end original
+
+The parse() method can parse from an C<HTTP::Response> object
+directly, so the example above can be more conveniently written as:
+(TBT)
+
+ my $ua = LWP::UserAgent->new;
+ my $response = $ua->get("http://www.example.com/form.html");
+ my @forms = HTML::Form->parse($response);
+
+=begin original
+
+Note that any object that implements a decoded_content() and base() method
+with similar behaviour as C<HTTP::Response> will do.
+
+=end original
+
+Note that any object that implements a decoded_content() and base() method
+with similar behaviour as C<HTTP::Response> will do.
+(TBT)
+
+=begin original
+
+Finally options might be passed in to control how the parse method
+behaves. The following options are currently recognized:
+
+=end original
+
+Finally options might be passed in to control how the parse method
+behaves. The following options are currently recognized:
+(TBT)
+
+=over
+
+=item C<base>
+
+=begin original
+
+Another way to provide the base URI.
+
+=end original
+
+Another way to provide the base URI.
+(TBT)
+
+=item C<verbose>
+
+=begin original
+
+Print messages to STDERR about any bad HTML form constructs found.
+
+=end original
+
+Print messages to STDERR about any bad HTML form constructs found.
+(TBT)
+
+=back
+
+=item $method = $form->method
+
+=item $form->method( $new_method )
+
+=begin original
+
+This method is gets/sets the I<method> name used for the
+C<HTTP::Request> generated. It is a string like "GET" or "POST".
+
+=end original
+
+This method is gets/sets the I<method> name used for the
+C<HTTP::Request> generated. It is a string like "GET" or "POST".
+(TBT)
+
+=item $action = $form->action
+
+=item $form->action( $new_action )
+
+=begin original
+
+This method gets/sets the URI which we want to apply the request
+I<method> to.
+
+=end original
+
+This method gets/sets the URI which we want to apply the request
+I<method> to.
+(TBT)
+
+=item $enctype = $form->enctype
+
+=item $form->enctype( $new_enctype )
+
+=begin original
+
+This method gets/sets the encoding type for the form data. It is a
+string like "application/x-www-form-urlencoded" or "multipart/form-data".
+
+=end original
+
+This method gets/sets the encoding type for the form data. It is a
+string like "application/x-www-form-urlencoded" or "multipart/form-data".
+(TBT)
+
+=item $value = $form->attr( $name )
+
+=item $form->attr( $name, $new_value )
+
+=begin original
+
+This method give access to the original HTML attributes of the <form> tag.
+The $name should always be passed in lower case.
+
+=end original
+
+This method give access to the original HTML attributes of the <form> tag.
+The $name should always be passed in lower case.
+(TBT)
+
+=begin original
+
+Example:
+
+=end original
+
+Example:
+(TBT)
+
+ @f = HTML::Form->parse( $html, $foo );
+ @f = grep $_->attr("id") eq "foo", @f;
+ die "No form named 'foo' found" unless @f;
+ $foo = shift @f;
+
+=item @inputs = $form->inputs
+
+=begin original
+
+This method returns the list of inputs in the form. If called in
+scalar context it returns the number of inputs contained in the form.
+See L</INPUTS> for what methods are available for the input objects
+returned.
+
+=end original
+
+This method returns the list of inputs in the form. If called in
+scalar context it returns the number of inputs contained in the form.
+See L</INPUTS> for what methods are available for the input objects
+returned.
+(TBT)
+
+=item $input = $form->find_input( $name )
+
+=item $input = $form->find_input( $name, $type )
+
+=item $input = $form->find_input( $name, $type, $index )
+
+=begin original
+
+This method is used to locate specific inputs within the form. All
+inputs that match the arguments given are returned. In scalar context
+only the first is returned, or C<undef> if none match.
+
+=end original
+
+This method is used to locate specific inputs within the form. All
+inputs that match the arguments given are returned. In scalar context
+only the first is returned, or C<undef> if none match.
+(TBT)
+
+=begin original
+
+If $name is specified, then the input must have the indicated name.
+
+=end original
+
+If $name is specified, then the input must have the indicated name.
+(TBT)
+
+=begin original
+
+If $type is specified, then the input must have the specified type.
+The following type names are used: "text", "password", "hidden",
+"textarea", "file", "image", "submit", "radio", "checkbox" and "option".
+
+=end original
+
+If $type is specified, then the input must have the specified type.
+The following type names are used: "text", "password", "hidden",
+"textarea", "file", "image", "submit", "radio", "checkbox" and "option".
+(TBT)
+
+=begin original
+
+The $index is the sequence number of the input matched where 1 is the
+first. If combined with $name and/or $type then it select the I<n>th
+input with the given name and/or type.
+
+=end original
+
+The $index is the sequence number of the input matched where 1 is the
+first. If combined with $name and/or $type then it select the I<n>th
+input with the given name and/or type.
+(TBT)
+
+=item $value = $form->value( $name )
+
+=item $form->value( $name, $new_value )
+
+=begin original
+
+The value() method can be used to get/set the value of some input. If
+no input has the indicated name, then this method will croak.
+
+=end original
+
+The value() method can be used to get/set the value of some input. If
+no input has the indicated name, then this method will croak.
+(TBT)
+
+=begin original
+
+If multiple inputs have the same name, only the first one will be
+affected.
+
+=end original
+
+If multiple inputs have the same name, only the first one will be
+affected.
+(TBT)
+
+=begin original
+
+The call:
+
+=end original
+
+The call:
+(TBT)
+
+ $form->value('foo')
+
+=begin original
+
+is a short-hand for:
+
+=end original
+
+is a short-hand for:
+(TBT)
+
+ $form->find_input('foo')->value;
+
+=item @names = $form->param
+
+=item @values = $form->param( $name )
+
+=item $form->param( $name, $value, ... )
+
+=item $form->param( $name, \@values )
+
+=begin original
+
+Alternative interface to examining and setting the values of the form.
+
+=end original
+
+Alternative interface to examining and setting the values of the form.
+(TBT)
+
+=begin original
+
+If called without arguments then it returns the names of all the
+inputs in the form. The names will not repeat even if multiple inputs
+have the same name. In scalar context the number of different names
+is returned.
+
+=end original
+
+If called without arguments then it returns the names of all the
+inputs in the form. The names will not repeat even if multiple inputs
+have the same name. In scalar context the number of different names
+is returned.
+(TBT)
+
+=begin original
+
+If called with a single argument then it returns the value or values
+of inputs with the given name. If called in scalar context only the
+first value is returned. If no input exists with the given name, then
+C<undef> is returned.
+
+=end original
+
+If called with a single argument then it returns the value or values
+of inputs with the given name. If called in scalar context only the
+first value is returned. If no input exists with the given name, then
+C<undef> is returned.
+(TBT)
+
+=begin original
+
+If called with 2 or more arguments then it will set values of the
+named inputs. This form will croak if no inputs have the given name
+or if any of the values provided does not fit. Values can also be
+provided as a reference to an array. This form will allow unsetting
+all values with the given name as well.
+
+=end original
+
+If called with 2 or more arguments then it will set values of the
+named inputs. This form will croak if no inputs have the given name
+or if any of the values provided does not fit. Values can also be
+provided as a reference to an array. This form will allow unsetting
+all values with the given name as well.
+(TBT)
+
+=begin original
+
+This interface resembles that of the param() function of the CGI
+module.
+
+=end original
+
+This interface resembles that of the param() function of the CGI
+module.
+(TBT)
+
+=item $form->try_others( \&callback )
+
+=begin original
+
+This method will iterate over all permutations of unvisited enumerated
+values (<select>, <radio>, <checkbox>) and invoke the callback for
+each. The callback is passed the $form as argument. The return value
+from the callback is ignored and the try_others() method itself does
+not return anything.
+
+=end original
+
+This method will iterate over all permutations of unvisited enumerated
+values (<select>, <radio>, <checkbox>) and invoke the callback for
+each. The callback is passed the $form as argument. The return value
+from the callback is ignored and the try_others() method itself does
+not return anything.
+(TBT)
+
+=item $request = $form->make_request
+
+=begin original
+
+Will return an C<HTTP::Request> object that reflects the current setting
+of the form. You might want to use the click() method instead.
+
+=end original
+
+Will return an C<HTTP::Request> object that reflects the current setting
+of the form. You might want to use the click() method instead.
+(TBT)
+
+=item $request = $form->click
+
+=item $request = $form->click( $name )
+
+=item $request = $form->click( $x, $y )
+
+=item $request = $form->click( $name, $x, $y )
+
+=begin original
+
+Will "click" on the first clickable input (which will be of type
+C<submit> or C<image>). The result of clicking is an C<HTTP::Request>
+object that can then be passed to C<LWP::UserAgent> if you want to
+obtain the server response.
+
+=end original
+
+Will "click" on the first clickable input (which will be of type
+C<submit> or C<image>). The result of clicking is an C<HTTP::Request>
+object that can then be passed to C<LWP::UserAgent> if you want to
+obtain the server response.
+(TBT)
+
+=begin original
+
+If a $name is specified, we will click on the first clickable input
+with the given name, and the method will croak if no clickable input
+with the given name is found. If $name is I<not> specified, then it
+is ok if the form contains no clickable inputs. In this case the
+click() method returns the same request as the make_request() method
+would do.
+
+=end original
+
+If a $name is specified, we will click on the first clickable input
+with the given name, and the method will croak if no clickable input
+with the given name is found. If $name is I<not> specified, then it
+is ok if the form contains no clickable inputs. In this case the
+click() method returns the same request as the make_request() method
+would do.
+(TBT)
+
+=begin original
+
+If there are multiple clickable inputs with the same name, then there
+is no way to get the click() method of the C<HTML::Form> to click on
+any but the first. If you need this you would have to locate the
+input with find_input() and invoke the click() method on the given
+input yourself.
+
+=end original
+
+If there are multiple clickable inputs with the same name, then there
+is no way to get the click() method of the C<HTML::Form> to click on
+any but the first. If you need this you would have to locate the
+input with find_input() and invoke the click() method on the given
+input yourself.
+(TBT)
+
+=begin original
+
+A click coordinate pair can also be provided, but this only makes a
+difference if you clicked on an image. The default coordinate is
+(1,1). The upper-left corner of the image is (0,0), but some badly
+coded CGI scripts are known to not recognize this. Therefore (1,1) was
+selected as a safer default.
+
+=end original
+
+A click coordinate pair can also be provided, but this only makes a
+difference if you clicked on an image. The default coordinate is
+(1,1). The upper-left corner of the image is (0,0), but some badly
+coded CGI scripts are known to not recognize this. Therefore (1,1) was
+selected as a safer default.
+(TBT)
+
+=item @kw = $form->form
+
+=begin original
+
+Returns the current setting as a sequence of key/value pairs. Note
+that keys might be repeated, which means that some values might be
+lost if the return values are assigned to a hash.
+
+=end original
+
+Returns the current setting as a sequence of key/value pairs. Note
+that keys might be repeated, which means that some values might be
+lost if the return values are assigned to a hash.
+(TBT)
+
+=begin original
+
+In scalar context this method returns the number of key/value pairs
+generated.
+
+=end original
+
+In scalar context this method returns the number of key/value pairs
+generated.
+(TBT)
+
+=item $form->dump
+
+=begin original
+
+Returns a textual representation of current state of the form. Mainly
+useful for debugging. If called in void context, then the dump is
+printed on STDERR.
+
+=end original
+
+Returns a textual representation of current state of the form. Mainly
+useful for debugging. If called in void context, then the dump is
+printed on STDERR.
+(TBT)
+
+=back
+
+=head1 INPUTS
+
+=begin original
+
+An C<HTML::Form> objects contains a sequence of I<inputs>. References to
+the inputs can be obtained with the $form->inputs or $form->find_input
+methods.
+
+=end original
+
+An C<HTML::Form> objects contains a sequence of I<inputs>. References to
+the inputs can be obtained with the $form->inputs or $form->find_input
+methods.
+(TBT)
+
+=begin original
+
+Note that there is I<not> a one-to-one correspondence between input
+I<objects> and E<lt>inputE<gt> I<elements> in the HTML document. An
+input object basically represents a name/value pair, so when multiple
+HTML elements contribute to the same name/value pair in the submitted
+form they are combined.
+
+=end original
+
+Note that there is I<not> a one-to-one correspondence between input
+I<objects> and E<lt>inputE<gt> I<elements> in the HTML document. An
+input object basically represents a name/value pair, so when multiple
+HTML elements contribute to the same name/value pair in the submitted
+form they are combined.
+(TBT)
+
+=begin original
+
+The input elements that are mapped one-to-one are "text", "textarea",
+"password", "hidden", "file", "image", "submit" and "checkbox". For
+the "radio" and "option" inputs the story is not as simple: All
+E<lt>input type="radio"E<gt> elements with the same name will
+contribute to the same input radio object. The number of radio input
+objects will be the same as the number of distinct names used for the
+E<lt>input type="radio"E<gt> elements. For a E<lt>selectE<gt> element
+without the C<multiple> attribute there will be one input object of
+type of "option". For a E<lt>select multipleE<gt> element there will
+be one input object for each contained E<lt>optionE<gt> element. Each
+one of these option objects will have the same name.
+
+=end original
+
+The input elements that are mapped one-to-one are "text", "textarea",
+"password", "hidden", "file", "image", "submit" and "checkbox". For
+the "radio" and "option" inputs the story is not as simple: All
+E<lt>input type="radio"E<gt> elements with the same name will
+contribute to the same input radio object. The number of radio input
+objects will be the same as the number of distinct names used for the
+E<lt>input type="radio"E<gt> elements. For a E<lt>selectE<gt> element
+without the C<multiple> attribute there will be one input object of
+type of "option". For a E<lt>select multipleE<gt> element there will
+be one input object for each contained E<lt>optionE<gt> element. Each
+one of these option objects will have the same name.
+(TBT)
+
+=begin original
+
+The following methods are available for the I<input> objects:
+
+=end original
+
+The following methods are available for the I<input> objects:
+(TBT)
+
+=over 4
+
+=item $input->type
+
+=begin original
+
+Returns the type of this input. The type is one of the following
+strings: "text", "password", "hidden", "textarea", "file", "image", "submit",
+"radio", "checkbox" or "option".
+
+=end original
+
+Returns the type of this input. The type is one of the following
+strings: "text", "password", "hidden", "textarea", "file", "image", "submit",
+"radio", "checkbox" or "option".
+(TBT)
+
+=item $name = $input->name
+
+=item $input->name( $new_name )
+
+=begin original
+
+This method can be used to get/set the current name of the input.
+
+=end original
+
+This method can be used to get/set the current name of the input.
+(TBT)
+
+=item $value = $input->value
+
+=item $input->value( $new_value )
+
+=begin original
+
+This method can be used to get/set the current value of an
+input.
+
+=end original
+
+This method can be used to get/set the current value of an
+input.
+(TBT)
+
+=begin original
+
+If the input only can take an enumerated list of values, then it is an
+error to try to set it to something else and the method will croak if
+you try.
+
+=end original
+
+If the input only can take an enumerated list of values, then it is an
+error to try to set it to something else and the method will croak if
+you try.
+(TBT)
+
+=begin original
+
+You will also be able to set the value of read-only inputs, but a
+warning will be generated if running under C<perl -w>.
+
+=end original
+
+You will also be able to set the value of read-only inputs, but a
+warning will be generated if running under C<perl -w>.
+(TBT)
+
+=item $input->possible_values
+
+=begin original
+
+Returns a list of all values that an input can take. For inputs that
+do not have discrete values, this returns an empty list.
+
+=end original
+
+Returns a list of all values that an input can take. For inputs that
+do not have discrete values, this returns an empty list.
+(TBT)
+
+=item $input->other_possible_values
+
+=begin original
+
+Returns a list of all values not tried yet.
+
+=end original
+
+Returns a list of all values not tried yet.
+(TBT)
+
+=item $input->value_names
+
+=begin original
+
+For some inputs the values can have names that are different from the
+values themselves. The number of names returned by this method will
+match the number of values reported by $input->possible_values.
+
+=end original
+
+For some inputs the values can have names that are different from the
+values themselves. The number of names returned by this method will
+match the number of values reported by $input->possible_values.
+(TBT)
+
+=begin original
+
+When setting values using the value() method it is also possible to
+use the value names in place of the value itself.
+
+=end original
+
+When setting values using the value() method it is also possible to
+use the value names in place of the value itself.
+(TBT)
+
+=item $bool = $input->readonly
+
+=item $input->readonly( $bool )
+
+=begin original
+
+This method is used to get/set the value of the readonly attribute.
+You are allowed to modify the value of readonly inputs, but setting
+the value will generate some noise when warnings are enabled. Hidden
+fields always start out readonly.
+
+=end original
+
+This method is used to get/set the value of the readonly attribute.
+You are allowed to modify the value of readonly inputs, but setting
+the value will generate some noise when warnings are enabled. Hidden
+fields always start out readonly.
+(TBT)
+
+=item $bool = $input->disabled
+
+=item $input->disabled( $bool )
+
+=begin original
+
+This method is used to get/set the value of the disabled attribute.
+Disabled inputs do not contribute any key/value pairs for the form
+value.
+
+=end original
+
+This method is used to get/set the value of the disabled attribute.
+Disabled inputs do not contribute any key/value pairs for the form
+value.
+(TBT)
+
+=item $input->form_name_value
+
+=begin original
+
+Returns a (possible empty) list of key/value pairs that should be
+incorporated in the form value from this input.
+
+=end original
+
+Returns a (possible empty) list of key/value pairs that should be
+incorporated in the form value from this input.
+(TBT)
+
+=item $input->check
+
+=begin original
+
+Some input types represent toggles that can be turned on/off. This
+includes "checkbox" and "option" inputs. Calling this method turns
+this input on without having to know the value name. If the input is
+already on, then nothing happens.
+
+=end original
+
+Some input types represent toggles that can be turned on/off. This
+includes "checkbox" and "option" inputs. Calling this method turns
+this input on without having to know the value name. If the input is
+already on, then nothing happens.
+(TBT)
+
+=begin original
+
+This has the same effect as:
+
+=end original
+
+This has the same effect as:
+(TBT)
+
+ $input->value($input->possible_values[1]);
+
+=begin original
+
+The input can be turned off with:
+
+=end original
+
+The input can be turned off with:
+(TBT)
+
+ $input->value(undef);
+
+=item $input->click($form, $x, $y)
+
+=begin original
+
+Some input types (currently "submit" buttons and "images") can be
+clicked to submit the form. The click() method returns the
+corresponding C<HTTP::Request> object.
+
+=end original
+
+Some input types (currently "submit" buttons and "images") can be
+clicked to submit the form. The click() method returns the
+corresponding C<HTTP::Request> object.
+(TBT)
+
+=back
+
+=begin original
+
+If the input is of type C<file>, then it has these additional methods:
+
+=end original
+
+If the input is of type C<file>, then it has these additional methods:
+(TBT)
+
+=over 4
+
+=item $input->file
+
+=begin original
+
+This is just an alias for the value() method. It sets the filename to
+read data from.
+
+=end original
+
+This is just an alias for the value() method. It sets the filename to
+read data from.
+(TBT)
+
+=item $filename = $input->filename
+
+=item $input->filename( $new_filename )
+
+=begin original
+
+This get/sets the filename reported to the server during file upload.
+This attribute defaults to the value reported by the file() method.
+
+=end original
+
+This get/sets the filename reported to the server during file upload.
+This attribute defaults to the value reported by the file() method.
+(TBT)
+
+=item $content = $input->content
+
+=item $input->content( $new_content )
+
+=begin original
+
+This get/sets the file content provided to the server during file
+upload. This method can be used if you do not want the content to be
+read from an actual file.
+
+=end original
+
+This get/sets the file content provided to the server during file
+upload. This method can be used if you do not want the content to be
+read from an actual file.
+(TBT)
+
+=item @headers = $input->headers
+
+=item input->headers($key => $value, .... )
+
+=begin original
+
+This get/set additional header fields describing the file uploaded.
+This can for instance be used to set the C<Content-Type> reported for
+the file.
+
+=end original
+
+This get/set additional header fields describing the file uploaded.
+This can for instance be used to set the C<Content-Type> reported for
+the file.
+(TBT)
+
+=back
+
+=head1 SEE ALSO
+
+L<LWP>, L<LWP::UserAgent>, L<HTML::Parser>
+
+=head1 COPYRIGHT
+
+Copyright 1998-2005 Gisle Aas.
+
+=begin original
+
+This library is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+=end original
+
+This library is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+(TBT)
+
+=begin meta
+
+Translated: Kentaro SHIRAKATA <argra****@ub32*****> (5.813)
+
+=end meta
+
+=cut
+