modules/HTML-TokeParser-Simple-2.1/Simple.pod


=encoding euc-jp

=head1 NAME

HTML::TokeParser::Simple - HTML::TokeParser のインターフェースを簡単に使う

=head1 SYNOPSIS

 use HTML::TokeParser::Simple;
 my $p = HTML::TokeParser::Simple->new( $somefile );

 while ( my $token = $p->get_token ) {
     # This prints all text in an HTML doc (i.e., it strips the HTML)
     next unless $token->is_text;
     print $token->as_is;
 }


=head1 DESCRIPTION

C<HTML::TokeParser> is a fairly common method of parsing HTML.  However, the
tokens returned are not exactly intuitive to parse:

C<HTML::TokeParser>は、HTMLを解析するのに、適切な、一般的なメソッドです。
ですが、返って来るトークンは、あまり直観的には解析できません:

 ["S",  $tag, $attr, $attrseq, $text]
 ["E",  $tag, $text]
 ["T",  $text, $is_data]
 ["C",  $text]
 ["D",  $text]
 ["PI", $token0, $text]

To simplify this, C<HTML::TokeParser::Simple> allows the user ask more
intuitive (read: more self-documenting) questions about the tokens returned.
Specifically, there are 7 C<is_foo> type methods and 5 C<return_bar> type
methods.  The C<is_> methods allow you to determine the token type and the
C<return_> methods get the data that you need.

これを簡単にするために、C<HTML::TokeParser::Simple>では、
返って来るトークンについて、ユーザがより直観的な(より自己ドキュメントな)質問を尋ねることができるようにします。
具体的には、7つのC<is_foo>タイプのメソッドと 5つのC<return_bar>タイプのメソッドがあります。
C<is_>メソッドはトークンのタイプを判断できるようにして、C<return_>メソッドは、必要とするデータを得られるようにします。

You can also rebuild some tags on the fly.  Frequently, the attributes
associated with start tags need to be altered, added to, or deleted.  This
functionality is built in.

オンザフライにいくつかのタグを再構築することもできます。
よくあるのは、開始タグに関連した属性が変えられるか、加えられるか、
削除されるといったことをしなければなりません。この機能性は組み込まれています。

Since this is a subclass of C<HTML::TokeParser>, all C<HTML::TokeParser>
methods are available.  To truly appreciate the power of this module, please
read the documentation for C<HTML::TokeParser> and C<HTML::Parser>.

HTML::TokeParser::Simpleは、C<HTML::TokeParser>のサブクラスであり、
すべてのC<HTML::TokeParser>メソッドが利用できます。
このモジュールの真価をわかるには、C<HTML::TokeParser>と、C<HTML::Parser>の
ドキュメントを読んでください。

The following will be brief descriptions of the available methods followed by
examples.

以下では、利用できるメソッドを、例とともに簡潔に説明します。

=head1 C<is_> メソッド

=over 4

=item * C<is_start_tag([$tag])>

Use this to determine if you have a start tag.  An optional "tag type" may be
passed.  This will allow you to match if it's a I<particular> start tag.  The
supplied tag is case-insensitive.

開始タグがあるかどうかを判断するのに使ってください。
オプションとして、"タグタイプ"を渡すこともできます。
I<特定の>開始タグかどうかにマッチさせることができます。
渡されるタグは大文字と小文字を区別しません。

 if ( $token->is_start_tag( 'font' ) ) { ... }

Optionally, you may pass a regular expression as an argument.  To match all
header (h1, h2, ... h6) tags:

オプションとして、正規表現を引数に渡せます。
全てのヘッダタグ(h1, h2 ... h6)にマッチさせるためには、以下のようにします:

 if ( $token->is_start_tag( qr/^h[123456]$/ ) ) { ... }

=item * C<is_end_tag([$tag])>

Use this to determine if you have an end tag.  An optional "tag type" may be
passed.  This will allow you to match if it's a I<particular> end tag.  The
supplied tag is case-insensitive.

終了タグがあるかどうかを判断するのに使います。
オプションとして、"タグタイプ"を渡すことが出来ます。
I<特定の>終了タグかどうかにマッチさせることができます。
渡されるタグは大文字と小文字を区別しません。

When testing for an end tag, the forward slash on the tag is optional.

終了タグのテストをするときには、タグの前のスラッシュはオプションです。

 while ( $token = $p->get_token ) {
   if ( $token->is_end_tag( 'form' ) ) { ... }
 }

または:

 while ( $token = $p->get_token ) {
   if ( $token->is_end_tag( '/form' ) ) { ... }
 }

Optionally, you may pass a regular expression as an argument.

オプションとして、正規表現を引数に渡せます。

=item * C<is_tag([$tag])>

Use this to determine if you have any tag.  An optional "tag type" may be
passed.  This will allow you to match if it's a I<particular> tag.  The
supplied tag is case-insensitive.

どんなタグを持っているか判断するのに使います。
オプションとして、"タグタイプ"を渡せます。
I<特定の>タグかどうかにマッチさせることができます。
渡されるタグは大文字と小文字を区別しません。

 if ( $token->is_tag ) { ... }

Optionally, you may pass a regular expression as an argument.

オプションとして、正規表現を引数に渡せます。

=item * C<is_text()>

Use this to determine if you have text.  Note that this is I<not> to be
confused with the C<return_text> (I<deprecated>) method described below!
C<is_text> will identify text that the user typically sees display in the Web
browser.

テキストを持っているかどうかを判断するのに使います。
下で説明するC<return_text>(I<軽視されている>)メソッドと混乱させるためにあるのではI<ありません>！
C<is_text>は、ユーザが典型的に見ているWebブラウザで表示されるテキストと一致するでしょう。

=item * C<is_comment()>

Are you still reading this?  Nobody reads POD.  Don't you know you're supposed
to go to CLPM, ask a question that's answered in the POD and get flamed?  It's
a rite of passage.

まだこれを読んでいます？ 誰もPODを読みません。
CLPMにに行くとすると、PODの中で答えられる質問を尋ねて、
フレイムになるのを知らない？ それは通過儀礼です。

Really.

本当です。

C<is_comment> is used to identify comments.  See the HTML::Parser documentation
for more information about comments.  There's more than you might think.

C<is_comment>は、コメントに一致させるのに使います。
コメントについて、より詳しい情報は、HTML::Parser のドキュメントを見てください。
あなたが思っている以上のことがあります。

=item * C<is_declaration()>

This will match the DTD at the top of your HTML. (You I<do> use DTD's, don't
you?)

HTMLのトップにあるDTDにマッチします。(DTDをI<使ってますか>、使ってないでしょ？)

=item * C<is_process_instruction()>

Process Instructions are from XML.  This is very handy if you need to parse out
PHP and similar things with a parser.

プロセスインストラクションはXML出身です。
PHPと類似のものをパーサで解析しなければならないなら、とても手軽です。

=back

=head1 The C<return_> メソッド

=head2 注意:

In case it's not blindingly obvious (I've been bitten by this myself when
writing the tests), you should generally test what type of token you have
B<before> you call some C<return_> methods.  For example, if you have an end
tag, there is no point in calling the C<return_attrseq> method.  Calling an
innapropriate method will return an empty string.

万一に備えて、めがくらむようにはっきりとしていません(自分自身、テストを書くときに、これを理解しています)。
C<return_>メソッドを呼ぶB<前に>、何のタイプのトークンを持っているかをテストすべきです。
たとえば、終了タグがあれば、C<retrun_attrseq>メソッドの呼び出しに何の意義もありません。
不適当なメソッドの呼び出しのために、空の文字列が返されるでしょう。

As noted for the C<is_> methods, these methods are case-insensitive after the
C<return_> part.

C<is_>メソッドのために注意としては、これらのメソッドはC<return_>部分の後は、大文字小文字を区別しません。

=over 4

=item * C<return_tag()>

Do you have a start tag or end tag?  This will return the type (lower case).

開始タグか終了タグがありますか？ そのタイプを返します(小文字)。

=item * C<return_attr()>

If you have a start tag, this will return a hash ref with the attribute names
as keys and the values as the values.

開始タグがあれば、キーに属性の名前、値に属性の値の、ハッシュリファレンスを返します。

=item * C<return_attrseq()>

For a start tag, this is an array reference with the sequence of the
attributes, if any.

開始タグに、もしあれば、連続した属性の配列リファレンスを返します。

=item * C<return_text()>

This method has been deprecated in favor of C<as_is>.  Programmers were getting
confused over the difference between C<is_text>, C<return_text>, and some
parser methods such as C<HTML::TokeParser::get_text> and friends.  This
confusion stems from the fact that your author is a blithering idiot when it
comes to choosing methods names :)

このメソッドは、C<as_is>のために、非難されています。プログラマは、
C<is_text>と、C<return_text>と、C<HTML::TokeParser::get_text>とその仲間を混乱しています。
この混乱は、メソッドの名前を選ぶことに関して、著者がひどくまぬけであるという事実に起因します :)

Using this method still succeeds, but will now carp.

このメソッドの使用はまだ成功します。ですが、現在は警告がでます。

=item * C<as_is()>

This is the exact text of whatever the token is representing.

トークンが表されているものはなんでも、正確なテキストです。

=item * C<return_token0()>

For processing instructions, this will return the token found immediately after
the opening tag.  Example:  For <?php, "php" will be the start of the returned
string.

プロセッシングインストラクションで、開きタグのすぐ後に見つけられるトークンを返します。
例えば: <?php なら、 "php"  が返される文字列の始まりになります。

=back

=head1 タグマンジングメソッド

The C<delete_attr()> and C<set_attr()> methods allow the programmer to rewrite
tag attributes on the fly.  It should be noted that bad HTML will be
"corrected" by this.  Specifically, the new tag will have all attributes
lower-cased with the values properly quoted.

C<delete_attr()>とC<set_attr()>メソッドで、プログラマはタグ属性をオンザフライに
書き直すことができます。悪いHTMLがこれによって"訂正される"ことに気が付くべきです。
特に、新しいタグは全ての属性が小文字になり、その値は適切にクォートされます。

Self-closing tags (e.g. E<lt>hr /E<gt>) are also handled correctly.  Some older
browsers require a space prior to the final slash in a self-closed tag.  If
such a space is detected in the original HTML, it will be preserved.

自動で閉じるタグ(例えば、E<lt>hr /E<gt>)も、正確にあつかわれます。
より古いブラウザには、自動で閉じられるタグには、最後のスラッシュより前に空白を必要とするものがあります。
そのようなスペースが、元のHTMLで見付かると、それはそのままになります。

=over 4

=item * C<delete_attr($name)>

This method attempts to delete the attribute specified.  It will C<croak> if
called on anything other than a start tag.  The argument is case-insensitive,
but must otherwise be an exact match of the attribute you are attempting to
delete.  If the attribute is not found, the method will return without changing
the tag.

このメソッドは特定の属性を消そうとします。このメソッドが開始タグ以外の何かで呼ばれると、
C<croak>します。引数は大文字と小文字を区別しません。
ですが、別な方法で、消そうとしている属性に正確にマッチさせる必要があります。
もし、属性が見付からなければ、メソッドはタグを変更せずに返します。

 # <body bgcolor="#FFFFFF">
 $token->delete_attr('bgcolor');
 print $token->as_is;
 # <body>
 
After this method is called, if successful, the C<as_is()>, C<return_attr()>
and C<return_attrseq()> methods will all return updated results.

このメソッドが呼ばれた後は、成功すれば、C<as_id()>と、C<return_attr()>と
C<return_attrseq()>メソッドは更新された結果を返します。
 
=item * C<set_attr($name,$value)>

This method will set the value of an attribute.  If the attribute is not found,
then C<return_attrseq()> will have the new attribute listed at the end.  Two
arguments

このメソッドは、属性の値をセットします。属性が見付からなければ、
C<return_attrseq()>に、最後にリストされる新しい属性があります。
2つの引数です。

 # <p>
 $token->set_attr('class','some_class');
 print $token->as_is;
 # <p class="some_class">

 # <body bgcolor="#FFFFFF">
 $token->set_attr('bgcolor','red');
 print $token->as_is;
 # <body bgcolor="red">

After this method is called, if successful, the C<as_is()>, C<return_attr()>
and C<return_attrseq()> methods will all return updated results.

このメソッドが呼ばれた後は、C<as_is()>、C<return_attr()>、C<return_attrseq>メソッドは、
全て、更新された結果を返します。

=item * C<rewrite_tag()>

This method rewrites the tag.  The tag name and the name of all attributes will
be lower-cased.  Values that are not quoted with double quotes will be.  This
may be called on both start or end tags.  Note that both C<set_attr()> and
C<delete_attr()> call this method prior to returning.

このメソッドは、タグを書き直します。タグの名前と全ての属性の名前は、小文字になります。
ダブルクォートでクォートされていない値は、クォートされます。開始タグと終了タグの両方で呼ばれます。
C<set_attr()>とC<delete_attr()>の両方がこのメソッドを値を返す前に呼ぶことに気を付けてください。

If called on a token that is not a tag, it simply returns.  Regardless of how
it is called, it returns the token.

タグでないトークンで呼ばれると、単純に返ります。どのようにメソッドが呼ばれたかを無視し、
トークンを返します。

 # <body alink=#0000ff BGCOLOR=#ffffff class='none'>
 $token->rewrite_tag;
 print $token->as_is;
 # <body alink="#0000ff" bgcolor="#ffffff" class="none">

A quick cleanup of sloppy HTML is now the following:

いい加減なHTMLを素早く綺麗にするには、次のようにします:

 my $parser = HTML::TokeParser::Simple->new( $ugly_html );
 while (my $token = $parser->get_token) {
     $token->rewrite_tag;
     print $token->as_is;
 }

=back

=head1 重要事項:

Some people get confused and try to call parser methods on tokens and token
methods (those described above) on methods.  To prevent this,
C<HTML::TokeParser::Simple> versions 1.4 and above now bless all tokens into a
new class which inherits nothing.  Please keep this in mind while using this
module (and many thanks to PodMaster
L<http://www.perlmonks.org/index.pl?node_id=107642> for pointing out this issue
to me.

人々には混乱する人がいて、パーサーメソッドをトークンで呼ぼうとし、トークンメソッド(上で説明しました)を、
メソッドで呼ぼうとします。
これを防ぐために、C<HTML::TokeParser::Simple>のバージョン 1.4以上では、現在、
何も継承しない新しいクラスに全てのトークンを bless しています。
このモジュールを使う間、心にとめておいてください(そして、この問題を私に指摘した PodMaster
L<http://www.perlmonks.org/index.pl?node_id=107642>にとても感謝します。

=head1 例

=head2 コメントを見つける

For some strange reason, your Pointy-Haired Boss (PHB) is convinced that the
graphics department is making fun of him by embedding rude things about him in
HTML comments.  You need to get all HTML comments from the HTML.

ある変わった理由のために、とんがった髪型のボス(PHB)は、
グラフィック部が、HTMLのコメントに彼に対して失礼なことを埋め込んで、
彼をからかっていると確信しています。HTMLから全てのコメントを得る必要があります。

 use strict;
 use HTML::TokeParser::Simple;

 my @html_docs = glob( "*.html" );

 open PHB, "> phbreport.txt" or die "Cannot open phbreport for writing: $!";

 foreach my $doc ( @html_docs ) {
     print "Processing $doc\n";
     my $p = HTML::TokeParser::Simple->new( $doc );
     while ( my $token = $p->get_token ) {
         next unless $token->is_comment;
         print PHB $token->as_is, "\n";
     }
 }

 close PHB;

=head2 コメントをはぎ取る

Uh oh.  Turns out that your PHB was right for a change.  Many of the comments
in the HTML weren't very polite.  Since your entire graphics department was
just fired, it falls on you need to strip those comments from the HTML.

うーあー。PHBには変更する権利があります。HTMLのコメントのほとんどが、
あまり行儀良くありませんでした。グラフィック部の全てが、すぐにクビになりました。
おかげで、HTMLからそれらのコメントをはぎ取らなければならなくなりました。

 use strict;
 use HTML::TokeParser::Simple;

 my $new_folder = 'no_comment/';
 my @html_docs  = glob( "*.html" );

 foreach my $doc ( @html_docs ) {
     print "Processing $doc\n";
     my $new_file = "$new_folder$doc";

     open PHB, "> $new_file" or die "Cannot open $new_file for writing: $!";

     my $p = HTML::TokeParser::Simple->new( $doc );
     while ( my $token = $p->get_token ) {
         next if $token->is_comment;
         print PHB $token->as_is;
     }
     close PHB;
 }

=head2 フォームタグを変更する

Your company was foo.com and now is bar.com.  Unfortunately, whoever wrote your
HTML decided to hardcode "http://www.foo.com/" into the C<action> attribute of
the form tags.  You need to change it to "http://www.bar.com/".

会社は foo.com でしたが、たった今 bar.com になります。不幸なことに、
誰もが、フォームタグのC<action>属性に"http://www.foo.com/"をハードコードすると決めてHTMLを書いていました。
"http://www.bar.com" にそれを変えなければなりません。


 use strict;
 use HTML::TokeParser::Simple;

 my $new_folder = 'new_html/';
 my @html_docs  = glob( "*.html" );

 foreach my $doc ( @html_docs ) {
     print "Processing $doc\n";
     my $new_file = "$new_folder$doc";

     open FILE, "> $new_file" or die "Cannot open $new_file for writing: $!";

     my $p = HTML::TokeParser::Simple->new( $doc );
     while ( my $token = $p->get_token ) {
         if ( $token->is_start_tag('form') ) {
             my $action = $token->return_attr->{action};
             $action =~ s/www\.foo\.com/www.bar.com/;
             $token->set_attr('action', $action);
         }
         print FILE $token->as_is;
     }
     close FILE;
 }

=head1 著作権

(原文まま)

Copyright (c) 2001 Curtis "Ovid" Poe.  All rights reserved.  This program is
free software; you may redistribute it and/or modify it under the same terms as
Perl itself

=head1 著者

(原文まま)

Curtis "Ovid" Poe L<poec@yahoo.com>

=head1 バグ

Use of C<$HTML::Parser::VERSION> which is less than 3.25 may result in
incorrect behavior as older versions do not always handle XHTML correctly.  It
is the programmer's responsibility to verify that the behavior of this code
matches the programmer's needs.

C<$HTML::Parser::VERSION>が3.25より古いものを使うと、結果として、不正確な動きをします。
古いバージョンでは、XHTMLを常には正しく取り扱わないからです。
このコードの動きががプログラマの必要に合っていることを確かめるのは、プログラマの責任です。

Note that C<HTML::Parser> processes text in 512 byte chunks.  This sometimes
will cause strange behavior and cause text to be broken into more than one
token.  You can suppress this behavior with the following command:

C<HTML::Parser>は、512バイトの固まりでテキストを処理することに、気を付けてください。
このことが原因で、おかしな動きを引き起こしたり、テキストが壊れて、2つ以上のトークンになったりします。
この動きを下のコマンドで、抑えることができます:

 $p->unbroken_text( [$bool] );

See the C<HTML::Parser> documentation and
http://www.perlmonks.org/index.pl?node_id=230667 for more information.

C<HTM::Parser>ドキュメントとhttp://www.perlmonks.org/index.pl?node_id=230667 に
より情報があるので、見てください。

Address bug reports and comments to: L<poec@yahoo.com>.  When sending bug
reports, please provide the version of C<HTML::Parser>, C<HTML::TokeParser>,
C<HTML::TokeParser::Simple>, the version of Perl, and the version of the
operating system you are using.

バグレポートとコメントは次のアドレスに: L<poec@yahoo.com>。
バグレポートを送るときには、C<HTML::Parser>と、C<HTML::TokeParser>と、C<HTML::TokeParser::Simple>と、
Perlのバージョンと、使っているOSのバージョンを提供してください。

=head1 翻訳について

翻訳者：加藤敦 (ktat.is@gmail.com)

Perlドキュメント日本語訳 Project にて、
Perlモジュール、ドキュメントの翻訳を行っております。

 http://perldocjp.sourceforge.jp
 http://sourceforge.jp/projects/perldocjp/
 http://www.freeml.com/ctrl/html/MLInfoForm/perldocjp@freeml.com
 http://www.perldoc.jp