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 +