名前¶

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( $html_document, $base_uri )

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

@forms = HTML::Form->parse( $response, %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 required arguments is the HTML document to parse ($html_document) and the URI used to retrieve the document ($base_uri). The base URI is needed to resolve relative action URIs. The provided HTML document should be a Unicode string (or US-ASCII).

必要な引数はパースする HTML 文書 ($html_document) と、 文書の取得に使われた URI ($base_uri) です。 ベース URI は相対アクション URI を解決するのに必要です。 指定された HTML 文書は Unicode (または US-ASCII) 文字列である 必要があります。

By default HTML::Form assumes that the original document was UTF-8 encoded and thus encode forms that don't specify an explict accept-charset as UTF-8. The charset assumed can be overridden by providing the charset option to parse(). It's a good idea to be explict about this parameter as well, thus the recommended simplest invocation becomes:

デフォルトでは、HTML::Form は元文書が UTF-8 でエンコードされていることを 仮定するので、明示的な accept-charset が指定されないフォームは UTF-8 としてエンコードします。 仮定した文字集合は parse() の charset オプションを指定することで 上書きできます。 この引数についても明示的にするのは良い考えです; 従って推奨するもっとも単純な起動方法は次のようになります:

    my @forms = HTML::Form->parse(
        Encode::decode($encoding, $html_document_bytes),
        base => $base_uri,
        charset => $encoding,
    );

If the document was retrieved with LWP then the response object provide methods to obtain a proper value for base and charset:

LWP を使って文書が取得されると、レスポンスオブジェクトは base と charset の適切な値を得るためのメソッドを提供します:

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

In fact, 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(), base() and content_charset() method with similar behaviour as HTTP::Response will do.

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

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

どのようにパースメソッドが振る舞うかを制御する追加のオプションを 渡せます。 以下は現在認識するオプションの全てです:

base => $uri

This is the URI used to retrive the original document. This option is not optional ;-)

これは元文書を取得するために使われた URI です。 このオプションはオプションではありません ;-)

charset => $str

Specify what charset the original document was encoded in. This is used as the default for accept_charset. If not provided this defaults to "UTF-8".

元文書がどの文字集合でエンコードされているかを指定します。 これは accept_charset のデフォルトとして使われます。 指定されなかった場合、デフォルトは "UTF-8" です。

verbose => $bool

Warn (print messages to STDERR) about any bad HTML form constructs found. You can trap these with $SIG{__WARN__}.

悪い HTML フォーム構造を見つけると、警告します (STDERR にメッセージを出力します)。 これは $SIG{__WARN__} でトラップできます。

strict => $bool

Initialize any form objects with the given strict attribute.

指定された厳密性属性でフォームオブジェクトを初期化します。

$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" のような 文字列です。

$accept = $form->accept_charset

$form->accept_charset( $new_accept )

This method gets/sets the list of charset encodings that the server processing the form accepts. Current implementation supports only one-element lists. Default value is "UNKNOWN" which we interpret as a request to use document charset as specified by the 'charset' parameter of the parse() method. To encode character strings you should have modern perl with Encode module. On older perls the setting of this attribute has no effect.

このメソッドは、フォームを処理するサーバが受け付ける文字集合エンコーディングの 一覧を取得/設定します。 現在の実装は 1 要素のリストのみに対応しています。 デフォルト値は "UNKNOWN" で、parse() メソッドの 'charset' パラメータによって 指定された文書の文字集合を使うことを要求すると解釈します。 文字単位の文字列をエンコードするには、Encode モジュールのある モダンな perl を使う必要があります。 より古い perl では、この属性を設定しても効果はありません。

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

$bool = $form->strict

$form->strict( $bool )

Gets/sets the strict attribute of a form. If the strict is turned on the methods that change values of the form will croak if you try to set illegal values or modify readonly fields. The default is not to be strict.

フォームの厳密性属性を取得/設定します。 厳密性がオンになっている場合、フォームの値を変更するメソッドは、 不正な値を設定しようとしたり、読み込み専用のフィールドを 変更しようとしたりすると、croak します。 デフォルトは厳密ではありません。

@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( $selector )

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

$input = $form->find_input( $selector, $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 $selector is specified, then the input's name, id, class attribute must match. A selector prefixed with '#' must match the id attribute of the input. A selector prefixed with '.' matches the class attribute. A selector prefixed with '^' or with no prefix matches the name attribute.

$selector が指定された場合、入力の name, id, class 属性は マッチングしなければなりません。 '#' が前置されたセレクタは入力の id 属性にマッチングしなければなりません。 '.' が前置されたセレクタは入力の class 属性にマッチングしなければなりません。 '^' が前置されたセレクタは入力の 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( $selector )

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

The value() method can be used to get/set the value of some input. If strict is enabled and 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 basically 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( $selector )

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

$request = $form->click( $selector, $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 $selector is specified, we will click on the first clickable input matching the selector, and the method will croak if no matching clickable input is found. If $selector 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. See description of the find_input() method above for how the $selector is specified.

$selector が指定されると、選択子にマッチングする最初のクリック可能な入力が クリックされ、もしマッチングするクリック可能な入力が見付からなかった場合は croak します。 $selector が指定 されない 場合は、フォームにクリック可能な入力がなくても 問題ありません。 この場合、click() メソッドは make_request() メソッドと同じリクエストを 返します。 $selector をどのように指定するかについては、 前述の find_input() メソッドの記述を参照してください。

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.

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

$input->id

$input->class

These methods can be used to get/set the current id or class attribute for the input.

これらのメソッドは、入力の現在の id または class 属性を取得/設定するために 使われます。

$input->selected( $selector )

Returns TRUE if the given selector matched the input. See the description of the find_input() method above for a description of the selector syntax.

与えられたセレクタが入力にマッチングしたときに真を返します。 セレクタの文法の記述については、前述の find_input() メソッドの記述を参照してください。

$value = $input->value

$input->value( $new_value )

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

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

If strict is enabled and 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() メソッドの別名です。 データを読み込むファイル名を設定します。

For security reasons this field will never be initialized from the parsing of a form. This prevents the server from triggering stealth uploads of arbitrary files from the client machine.

セキュリティ上の理由により、このフィールドはフォームのパースから 初期化されることはありません。 これは、サーバがクライアントマシンから任意のファイルの内密な アップロードを引き起こすことを防ぎます。

$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-2008 Gisle Aas.

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