19.3. "htmllib" --- HTML 文書の解析器
*************************************

バージョン 2.6 で非推奨: "htmllib" モジュールは Python 3 で削除されま
した。Python 2 では代わりに "HTMLParser" を使ってください。なお、
"HTMLParser" は Python 3 では "html.parser" に移動しています。

このモジュールでは、ハイパーテキストマークアップ言語 (HTML, HyperText
Mark-up Language) 形式でフォーマットされたテキストファイルを解析するた
めの基盤として役立つクラスを定義しています。このクラスは I/O と直接的
には接続されません --- このクラスにはメソッドを介して文字列形式の入力
を提供する必要があり、出力を生成するには "フォーマッタ (formatter)" オ
ブジェクトのメソッドを何度か呼び出さなくてはなりません。"HTMLParser"
クラスは、機能を追加するために他のクラスの基底クラスとして利用するよう
に設計されており、ほとんどのメソッドが拡張したり上書きしたりできるよう
になっています。さらにこのクラスは "sgmllib" モジュールで定義されてい
る "SGMLParser" クラスから派生しており、その機能を拡張しています。
"HTMLParser" の実装は、 **RFC 1866** で解説されている HTML 2.0 記述言
語をサポートします。 "formatter" では 2 つのフォーマッタオブジェクト実
装が提供されています; フォーマッタのインタフェースについての情報は
"formatter" モジュールのドキュメントを参照してください。

以下は "sgmllib.SGMLParser" で定義されているインタフェースの概要です:

* インスタンスにデータを与えるためのインタフェースは "feed()" メソッ
  ド で、このメソッドは文字列を引数に取ります。このメソッドに一度に与
  える テキストは必要に応じて多くも少なくもできます; というのは
  "p.feed(a); p.feed(b)" は "p.feed(a+b)" と同じ効果を持つからです。与
  えられたデー タが完全な HTML マークアップ文を含む場合、それらの文は
  即座に処理され ます; 不完全なマークアップ構造はバッファに保存されま
  す。全ての未処理 データを強制的に処理させるには、 "close()" メソッド
  を呼び出します。

  例えば、ファイルの全内容を解析するには:

     parser.feed(open('myfile.html').read())
     parser.close()

* HTML タグに対して意味付けを定義するためのインタフェースはとても単
  純 です: サブクラスを派生して、 "start_tag()" 、 "end_tag()" 、ある
  いは "do_tag()" といったメソッドを定義するだけです。パーザはこれらの
  メソ ッドを適切なタイミングで呼び出します: "start_tag()" や
  "do_tag()" は "<tag ...>" の形式の開始タグに遭遇した時に呼び出されま
  す; "end_tag()" は "<tag>" の形式の終了タグに遭遇した時に呼び出され
  ます 。 "<H1>" ... "</H1>" のように開始タグが終了タグと対応している
  必要が ある場合、クラス中で "start_tag()" が定義されていなければなり
  ません; "<P>" のように終了タグが必要ない場合、クラス中では
  "do_tag()" を定義 しなければなりません。

このモジュールではパーザクラスと例外を一つづつ定義しています:

class htmllib.HTMLParser(formatter)

   基底となる HTML パーザクラスです。XHTML 1.0 仕様
   (https://www.w3.org/TR/xhtml1) 勧告で要求されている全てのエンティテ
   ィ名をサポートしています。また、全ての HTML 2.0 の要素および HTML
   3.0、3.2 の多くの要素のハンドラを定義しています。

exception htmllib.HTMLParseError

   "HTMLParser" クラスがパーズ処理中にエラーに遭遇した場合に送出する例
   外です。

   バージョン 2.4 で追加.

参考:

  "formatter" モジュール
     抽象化された書式イベントの流れを writer オブジェクト上の特定の出
     力イベントに変換するためのインターフェース。

  "HTMLParser" モジュール
     HTML パーザのひとつです。やや低いレベルでしか入力を扱えませんが、
     XHTML を扱うことができるように設計されています。"広く知られている
     HTML (HTML as deployed)" では使われておらずかつ XHTML では正しく
     ないとされる SGML 構文のいくつかは実装されていません。

  "htmlentitydefs" モジュール
     XHTML 1.0 エンティティに対する置換テキストの定義。

  "sgmllib" モジュール
     "HTMLParser" の基底クラス。


19.3.1. HTMLParser オブジェクト
===============================

タグメソッドに加えて、 "HTMLParser" クラスではタグメソッドで利用するた
めのいくつかのメソッドとインスタンス変数を提供しています。

HTMLParser.formatter

   パーザに関連付けられているフォーマッタインスタンスです。

HTMLParser.nofill

   ブール値のフラグで、空白文字を縮約したくないときには真、縮約すると
   きには偽にします。一般的には、この値を真にするのは、 "<PRE>" 要素の
   中のテキストのように、文字列データが "書式化済みの (preformatted)"
   場合だけです。標準の値は偽です。この値は "handle_data()" および
   "save_end()" の操作に影響します。

HTMLParser.anchor_bgn(href, name, type)

   このメソッドはアンカー領域の先頭で呼び出されます。引数は "<A>" タグ
   の属性で同じ名前を持つものに対応します。標準の実装では、ドキュメン
   ト内のハイパーリンク ("<A>" タグの "HREF" 属性) を列挙したリストを
   維持しています。ハイパーリンクのリストはデータ属性 "anchorlist" で
   手に入れることができます。

HTMLParser.anchor_end()

   このメソッドはアンカー領域の末尾で呼び出されます。標準の実装では、
   テキストの脚注マーカを追加します。マーカは "anchor_bgn()" で作られ
   たハイパーリンクリストのインデクス値です。

HTMLParser.handle_image(source, alt[, ismap[, align[, width[, height]]]])

   このメソッドは画像を扱うために呼び出されます。標準の実装では、単に
   "handle_data()" に *alt* の値を渡すだけです。

HTMLParser.save_bgn()

   文字列データをフォーマッタオブジェクトに送らずにバッファに保存する
   操作を開始します。保存されたデータは "save_end()" で取得してくださ
   い。 "save_bgn()" / "save_end()" のペアを入れ子構造にすることはでき
   ません。

HTMLParser.save_end()

   文字列データのバッファリングを終了し、以前 "save_bgn()" を呼び出し
   た時点から保存されている全てのデータを返します。 "nofill" フラグが
   偽の場合、空白文字は全てスペース文字一文字に置き換えられます。予め
   "save_bgn()" を呼ばないでこのメソッドを呼び出すと "TypeError" 例外
   が送出されます。


19.4. "htmlentitydefs" --- HTML 一般エンティティの定義
******************************************************

注釈: Python 3 で "htmlentitydefs" モジュールは "html.entities" と改
  名され ました。ソースを 3 用に変換する際には *2to3* ツールが自動的に
  import を直してくれます。

**ソースコード:** Lib/htmlentitydefs.py

======================================================================

このモジュールでは "name2codepoint" 、 "codepoint2name" 、
"entitydefs" の三つの辞書を定義しています。 "entitydefs" は "htmllib"
モジュールで "HTMLParser" クラスの "entitydefs" メンバを定義するために
使われます。このモジュールでは XHTML 1.0 で定義された全てのエンティテ
ィを提供しており、 Latin-1 文字集合 (ISO-8859-1) の簡単なテキスト置換
を行う事ができます。

htmlentitydefs.entitydefs

   各 XHTML 1.0 実体定義と ISO Latin-1 における置換テキストとを対応付
   ける辞書です。

htmlentitydefs.name2codepoint

   HTML 実体名と Unicode コードポイントとを対応付ける辞書です。

   バージョン 2.3 で追加.

htmlentitydefs.codepoint2name

   Unicode コードポイントと HTML 実体名とを対応付ける辞書です。

   バージョン 2.3 で追加.
