名前¶

HTML::Form - HTML フォーム要素を表現するクラス

概要¶

 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);

説明¶

HTML::Form クラスのオブジェクトは一つの HTML の <form> ... </form> 実体を表現します。 一つのフォームは、普通は名前の付いている、様々な値を取ることができる いくつかの入力で構成されます。 フォームの状態は修正でき、それから LWP::UserAgent の request() メソッドに 渡せる HTTP::Request オブジェクトを取得できます。

以下のメソッドが利用可能です:

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

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

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

The parse() class method will parse an HTML document and build up 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.

parse() クラスメソッドは HTML 文書をパースして、<form> 要素が見つかる毎に HTML::Form オブジェクトを構築します。 スカラコンテキストで呼び出すと、最初の <form> だけが返されます。 フォームが見つからなかった場合は空リストが返されます。

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:

$base は $html_document の取得に使われた URI です。 これは相対アクション URI を解決するのに必要です。 LWP を使って文書が取得されると、以下の例のように、 この引数が $response->base() から取られます:

    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 HTTP::Response object directly, so the example above can be more conveniently written as:

parse() メソッドは HTTP::Response オブジェクトから直接パースすることも できるので、上述の例は以下のようにしてより便利になります:

    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 HTTP::Response will do.

HTTP::Response と同じような振る舞いをする decoded_content() メソッドと base() メソッドが実装されているどのような オブジェクトでも行えることに注意してください。

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

最後に、どのようにパースメソッドが振る舞うかを制御するオプションを 渡せます。 現在以下のオプションを認識します:

base

Another way to provide the base URI.

ベース URI を提供するもう一つの方法です。

verbose

Print messages to STDERR about any bad HTML form constructs found.

悪い HTML フォーム構造を見つけると、STDERR にメッセージを出力します。

$method = $form->method

$form->method( $new_method )

This method is gets/sets the method name used for the HTTP::Request generated. It is a string like "GET" or "POST".

このメソッドは、HTTP::Request が生成されるときに使われる メソッド 名を 取得/設定します。 これは "GET" や "POST" のような文字列です。

$action = $form->action

$form->action( $new_action )

This method gets/sets the URI which we want to apply the request method to.

このメソッドはリクエスト メソッド を適用したい URI を取得/設定します。

$enctype = $form->enctype

$form->enctype( $new_enctype )

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".

このメソッドはフォームデータのエンコーディングタイプを取得/設定します。 これは "application/x-www-form-urlencoded" や "multipart/form-data" のような 文字列です。

$value = $form->attr( $name )

$form->attr( $name, $new_value )

This method give access to the original HTML attributes of the <form> tag. The $name should always be passed in lower case.

このメソッドは元の <form> タグの HTML 属性へのアクセスを提供します。 $name は常に小文字で渡す必要があります。

Example:

例:

   @f = HTML::Form->parse( $html, $foo );
   @f = grep $_->attr("id") eq "foo", @f;
   die "No form named 'foo' found" unless @f;
   $foo = shift @f;

@inputs = $form->inputs

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 "INPUTS" for what methods are available for the input objects returned.

このメソッドはフォームの入力のリストを返します。 スカラコンテキストで呼ばれると、フォームに含まれている入力の数を返します。 返された入力オブジェクトで利用可能なメソッドについては "INPUTS" を参照してください。

$input = $form->find_input( $name )

$input = $form->find_input( $name, $type )

$input = $form->find_input( $name, $type, $index )

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 undef if none match.

このメソッドはフォーム内の特定の入力の位置を知るために使われます。 与えられた引数にマッチングする入力全てが返されます。 スカラコンテキストでは、マッチングしなければ undef を、 マッチングすれば最初のものだけを返します。

If $name is specified, then the input must have the indicated name.

$name が指定された場合、入力は指示された名前を持たなければなりません。

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".

$type が指定された場合、有力は指定された種類でなければなりません。 以下の種類が使われます: "text", "password", "hidden", "textarea", "file", "image", "submit", "radio", "checkbox", "option"

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 nth input with the given name and/or type.

$index はマッチングする入力のシーケンス番号(1 が先頭)です。 $name や $type と組み合わせると、与えられた名前や種類の n 番目が選択されます。

$value = $form->value( $name )

$form->value( $name, $new_value )

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.

value() メソッドは特定の入力の値を取得/設定するために使われます。 指定された名前の入力がない場合、このメソッドは croak します。

If multiple inputs have the same name, only the first one will be affected.

同じ名前の入力が複数ある場合、最初のものだけが影響します。

The call:

以下の呼び出し:

    $form->value('foo')

is a short-hand for:

は以下のものの短縮形です:

    $form->find_input('foo')->value;

@names = $form->param

@values = $form->param( $name )

$form->param( $name, $value, ... )

$form->param( $name, \@values )

Alternative interface to examining and setting the values of the form.

フォームの値の調査と設定を行うためのもう一つのインターフェースです。

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.

引数なしで呼ばれると、フォームの全ての入力の名前を返します。 同じ名前の入力が複数あっても一度しか現れません。 スカラコンテキストでは、異なる名前の数が返されます。

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 undef is returned.

引数一つで呼び出されると、与えられた名前の入力の値を返します。 スカラコンテキストで呼び出されると、最初の値のみが返されます。 与えられた名前の入力がない場合は、undef が返されます。

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.

2 以上の引数で呼び出されると、名前のある入力の値を設定します。 この形式は、もし与えられた名前がなかったり、提供された値が適合しない場合は croak します。 値は配列へのリファレンスででも提供できます。 この形式は与えられた名前の全ての値をクリアすることも出来ます。

This interface resembles that of the param() function of the CGI module.

このインターフェースは CGI モジュールの param() 関数と似ています。

$form->try_others( \&callback )

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.

このメソッドはまだ訪れていない列挙値 (<select>, <radio>, <checkbox>) の 順列に対して反復し、それぞれに対して callback を起動します。 callback は引数として $form が渡されます。 callback からの返り値は無視され、try_others() メソッド自身は何も 返しません。

$request = $form->make_request

Will return an HTTP::Request object that reflects the current setting of the form. You might want to use the click() method instead.

フォームの現在の設定を反映した HTTP::Request を返します。 代わりに click() メソッドを使いたいかも知れません。

$request = $form->click

$request = $form->click( $name )

$request = $form->click( $x, $y )

$request = $form->click( $name, $x, $y )

Will "click" on the first clickable input (which will be of type submit or image). The result of clicking is an HTTP::Request object that can then be passed to LWP::UserAgent if you want to obtain the server response.

クリックできる入力 (型が submit または image のもの) を 「クリック」します。 クリックの結果は、もしサーバレスポンスがほしい場合は後で LWP::UserAgent に 渡せる HTTP::Request オブジェクトです。

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 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.

$name が指定されると、与えられた名前を持つ最初のクリック可能な入力が クリックされ、もし与えられた名前のクリック可能な入力が見付からなかった場合は croak します。 $name が指定 されない 場合は、フォームにクリック可能な入力がなくても 問題ありません。 この場合、click() メソッドは make_request() メソッドと同じリクエストを 返します。

If there are multiple clickable inputs with the same name, then there is no way to get the click() method of the 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.

同じ名前で複数のクリック可能な入力がある場合、最初のもの以外が クリックされたことを HTML::Form の click() メソッドで知る方法は ありません。 これが必要なら、find_input() で入力の位置を探して、得られた入力自身に 対して click() メソッドを起動する必要があります。

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.

クリック座標の組も提供されますが、画像をクリックされたときにのみ 違いがあります。 デフォルトの座標は (1,1) です。 画像の左上の隅は (0,0) ですが、間違ってコーディングされた CGI スクリプトには これを認識しないことが知られています。 従って (1,1) はより安全なデフォルトとして選択されました。

@kw = $form->form

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.

現在の設定をキー/値の組として返します。 キーは繰り返されるかもしれないので、返り値をハッシュに代入すると 値の一部が失われるかもしれないことに注意してください。

In scalar context this method returns the number of key/value pairs generated.

スカラコンテキストではこのメソッドは生成されるキー/値の組の数を返します。

$form->dump

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.

フォームの現在の状態のテキスト表現を返します。 主にデバッグに有用です。 無効コンテキストで呼び出されると、ダンプは STDERR に出力されます。

入力¶

HTML::Form オブジェクトは 入力(input) の組を含みます。 入力へのリファレンスは $form->inputs メソッドや $form->find_input メソッドで 得られます。

入力 オブジェクト と、HTML 文書の <input> 要素 は 1 対 1 で 対応しない ことに注意してください。 入力オブジェクトは基本的に一つの名前/値の組を表現するので、同じ名前/値の 組を提供する複数の HTML 要素は結合されます。

1 対 1 でマッピングされる入力要素は "text", "textarea", "password", "hidden", "file", "image", "submit", "checkbox" です。 "radio" と "option" 入力では話はそれほど簡単ではありません: 同じ名前を持つ全ての <input type="radio"> 要素は同じ入力 radio オブジェクトに提供されます。 radio 入力オブジェクトの数は <input type="radio"> 要素で使われている 異なる名前の数と同じです。 multiple 属性のない <select> 要素の場合、"option" 型の 一つの入力オブジェクトです。 <select multiple> 要素の場合、それぞれに <option> 要素を 含んだ一つの入力オブジェクトです。 これらの option オブジェクトのそれぞれは同じ名前を持ちます。

以下のメソッドが input オブジェクトで利用可能です:

$input->type

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".

この入力の種類を返します。 種類は以下の文字列の一つです: "text", "password", "hidden", "textarea", "file", "image", "submit", "radio", "checkbox", "option"。

$name = $input->name

$input->name( $new_name )

This method can be used to get/set the current name of the input.

このメソッドは入力の現在の名前を取得/設定できます。

$value = $input->value

$input->value( $new_value )

This method can be used to get/set the current value of an input.

このメソッドは入力の現在の値を取得/設定できます。

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.

入力が列挙された値のリストうちの一つだけを取る場合、違う値を 設定しようとすることはエラーであり、そうしようとするとメソッドは croak します。

You will also be able to set the value of read-only inputs, but a warning will be generated if running under perl -w.

また、読み込み専用入力の値を設定することもできますが、 perl -w で実行されている場合は警告が発生します。

$input->possible_values

Returns a list of all values that an input can take. For inputs that do not have discrete values, this returns an empty list.

入力が取ることができる全ての値のリストを返します。 離散値を取る入力でない場合は、空リストを返します。

$input->other_possible_values

Returns a list of all values not tried yet.

まだ試していない全ての値のリストを返します。

$input->value_names

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.

一部の入力では、値に値自身と違う名前を付けられます。 このメソッドで返される名前の数は $input->possible_values で報告される 値の数と一致します。

When setting values using the value() method it is also possible to use the value names in place of the value itself.

value() メソッドを使って値を設定するとき、値自身の代わりに値の名前を 使うことも可能です。

$bool = $input->readonly

$input->readonly( $bool )

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.

このメソッドは読み込み専用(readonly)属性の値を取得/設定するために使います。 読み込み専用の入力の値を変えることもできますが、値を設定すると 警告が有効の時には警告が出力されます。 hidden フィールドは常に読み込み専用で始まります。

$bool = $input->disabled

$input->disabled( $bool )

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.

このメソッドは無効(disabled)属性の値を取得/設定するために使われます。 無効の入力はフォームの値のためにキー/値の組を提供しません。

$input->form_name_value

Returns a (possible empty) list of key/value pairs that should be incorporated in the form value from this input.

この入力からのフォームの値と連携しているキー/値の組のリスト (空かもしれません)を返します。

$input->check

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.

一部の入力はオン/オフできるトグルを表現しています。 これは "checkbox" と "option" を含みます。 このメソッドを呼び出すと、この入力の現在の値を知らなくてもオンになります。 入力が既にオンなら、何も起きません。

This has the same effect as:

これは以下と同じ効果です:

    $input->value($input->possible_values[1]);

The input can be turned off with:

入力は以下のようにしてオフにできます:

    $input->value(undef);

$input->click($form, $x, $y)

Some input types (currently "submit" buttons and "images") can be clicked to submit the form. The click() method returns the corresponding HTTP::Request object.

一部の入力 (現在のところ "submit" ボタンと "images") はフォームを 送信するためにクリックできます。 click() メソッドは対応する HTTP::Request オブジェクトを返します。

入力の種類が file の場合、追加のメソッドがあります:

$input->file

This is just an alias for the value() method. It sets the filename to read data from.

これは単に value() メソッドの別名です。 データを読み込むファイル名を設定します。

$filename = $input->filename

$input->filename( $new_filename )

This get/sets the filename reported to the server during file upload. This attribute defaults to the value reported by the file() method.

これはファイルアップロード中にサーバに報告されるファイル名を設定/取得します。 この属性のデフォルトは file() メソッドで報告される値です。

$content = $input->content

$input->content( $new_content )

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.

これはファイルアップロード中にサーバに提供されるファイルの内容を 取得/設定します。 このメソッドは、実際のファイルから内容を読み込みたくない場合に使えます。

@headers = $input->headers

input->headers($key => $value, .... )

This get/set additional header fields describing the file uploaded. This can for instance be used to set the Content-Type reported for the file.

これはアップロードされたファイルを表現する追加のヘッダフィールドを 取得/設定します。 これは例えばファイルのために報告する Content-Type の設定に使います。

SEE ALSO¶

LWP, LWP::UserAgent, HTML::Parser

コピーライト¶

Copyright 1998-2005 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.