# 1 `HTMLParser` -- HTML および XHTML のシンプルなパーザ

バージョン 2.2 で 新たに追加 された仕様です。

このモジュールでは `HTMLParser` クラスを定義します。 このクラスは HTML (ハイパーテキスト記述言語、 HyperText Mark-up Language) および XHTML で書式化されているテキストファイルを解釈するための基礎と なります。`htmllib` にあるパーザと違って、このパーザ は `sgmllib` の SGML パーザに基づいてはいません。

クラス `HTMLParser`( | )

  `HTMLParser` クラスは引数なしでインスタンス化します。

  HTMLParser インスタンスに HTML データが入力されると、 タグが開始したとき、及び終了したときに関数を呼び出します。 `HTMLParser` クラスは、ユーザが行いたい動作を提供する ために上書きできるようになっています。

  `htmllib` のパーザと違い、このパーザは終了タグが開始タグと 一致しているか調べたり、外側のタグ要素が閉じるときに内側で明示的 に閉じられていないタグ要素のタグ終了ハンドラを呼び出したりはしません。

例外も定義されています:

exception `HTMLParseError`
  パーズ中にエラーに遭遇した場合に`HTMLParser` クラスが送出する例外です。 この例外は三つの属性を提供しています: `msg` はエラーの内容を 説明する簡単なメッセージ、`lineno` は壊れたマークアップ構造 を検出した場所の行番号、`offset` は問題のマークアップ構造の 行内での開始位置を示す文字数です。

`HTMLParser` インスタンスは以下のメソッドを提供します:

`reset`( | )

  インスタンスをリセットします。未処理のデータは全て失われます。 インスタンス化の際に非明示的に呼び出されます。

`feed`( | data)

  パーザにテキストを入力します。入力が完全なタグ要素で構成されている 場合に限り処理が行われます; 不完全なデータであった場合、新たに データが入力されるか、`close()` が呼び出されるまでバッファ されます。

`close`( | )

  全てのバッファされているデータについて、その後にファイル終了マーク が続いているとみなして強制的に処理を行います。このメソッドは 入力データの終端で行うべき追加処理を定義するために導出クラスで 上書きすることができますが、再定義を行ったクラスでは常に、 `HTMLParser` 基底クラスのメソッド `close()` を 呼び出さなくてはなりません。

`getpos`( | )

  現在の行番号およびオフセット値を返します。

`get_starttag_text`( | )

  最も最近開かれた開始タグのテキスト部分を返します。このテキストは 必ずしも元データを構造化する上で必須ではありませんが、 ``広く知られている (as deployed)'' HTML を扱ったり、入力を 最小限の変更で再生成 (属性間の空白をそのままにする、など) したり する場合に便利なことがあります。

`handle_starttag`( | tag, attrs)

  このメソッドはタグの開始部分を処理するために呼び出されます。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

  tag 引数はタグの名前で、小文字に変換されています。 attrs 引数は `(name, value)` のペアからなる リストで、タグの `<>` 括弧内にある属性が収められています。 name は小文字に変換され、value 内のエンティティ参照 は変換されます。二重引用符やバックスラッシュは変換しません。例えば、 タグ `<A HREF="http://www.cwi.nl/">` を処理する場合、このメソッドは "`handle_starttag('a', [('href', 'http://www.cwi.nl/')])`"として呼び出されます。

`handle_startendtag`( | tag, attrs)

  `handle_starttag()` と似ていますが、パーザが XHTML 形式の 空タグ (`<a .../>`) に遭遇した場合に呼び出されます。 この特定の語彙情報 (lexical information) が必要な場合、 このメソッドをサブクラスで上書きすることができます; 標準の実装 では、単に `handle_starttag()` および `handle_endtag()` を呼ぶだけです。

`handle_endtag`( | tag)

  このメソッドはあるタグ要素の終了タグを処理するために呼び出されます。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。tag 引数はタグの名前で、小文字に変換されています。

`handle_data`( | data)

  このメソッドは、他のメソッドに当てはまらない任意のデータを処理するために 呼び出されます。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

`handle_charref`( | ref)

  このメソッドはタグ外の "`&#ref;`" 形式の文字参照 (character reference) を処理するために呼び出されます。 ref には、先頭の"`&#`" および末尾の"`;`" は 含まれません。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

`handle_entityref`( | name)

  このメソッドはタグ外の "`&name;`" 形式の一般のエンティティ参照 (entity reference) name を処理するために呼び出されます。 name には、先頭の"`&`" および末尾の"`;`" は 含まれません。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

`handle_comment`( | data)

  このメソッドはコメントに遭遇した場合に呼び出されます。comment 引数は文字列で、"`--`" および "`--`" デリミタ間の、 デリミタ自体を除いたテキストが収められています。例えば、コメント "`<!--text-->`" があると、このメソッドは引数`'text'` で 呼び出されます。導出クラスで上書きするためのメソッドです; 基底クラスの実装では何も行いません。

`handle_decl`( | decl)

  パーザが SGML 宣言を読み出した際に呼び出されるメソッドです。 decl パラメタは `<!`...`>` 記述内の宣言内容 全体になります。 導出クラスで上書きするためのメソッドです; 基底クラスの実装では 何も行いません。

`handle_pi`( | data)

  処理指令に遭遇した場合に呼び出されます。dataには、処理指令 全体が含まれ、例えば`<?proc color='red'>`という処理指令の場合、 `handle_pi("proc color='red'")`のように呼び出されます。 このメソッドは導出クラスで上書きするためのメソッドです; 基底クラスの 実装では何も行いません。

  注意: The `HTMLParser`クラスでは、処理指令にSGMLの構文を使用します。 末尾に"`?`"がXHTMLの処理指令では、"`?`"がdataに 含まれます。

exception `HTMLParseError`
  HTML の構文に沿わないパターンを発見したときに送出される例外です。 HTML 構文法上の全てのエラーを発見できるわけではないので注意してください。