instance method REXML::Parsers::SAX2Parser#listen

listen(sym, ary) { ... } -> ()[permalink][rdoc]
listen(sym) { ... } -> ()
listen(ary, listener) -> ()
listen(ary) { ... } -> ()
listen(listener) -> ()

コールバックをパーサに登録します。

引数の種類やブロックの有無でどのような場合に何がコールバックされかが変わります。

ブロックを指定した場合はそのブロックがコールバックされます。ブロックを指定しない場合は REXML::SAX2Listener を include したクラスのオブジェクトを指定します。

sym は以下のシンボルが指定でき、どの場合にコールバックが呼び出されるかを指定します。どのような場合にどのような引数でコールバックが呼び出されるかについては、 REXML::SAX2Listener の対応するメソッドで詳しく説明されていますのでそちらを参照してください。

ary には配列を指定し、要素名によるコールバック呼び出し条件を指定します。配列の要素としては、文字列か正規表現が指定できます。 start_element, end_element に関しては、指定した名前を持つ要素の開始時と終了時にのみコールバックが呼び出されるようになります。 start_prefix_mapping, end_prefix_mapping では、その名前空間が導入された要素の要素名、つまり xmlns:foo="bar" という属性を持つ要素の名前でフィルタリングされるようになります。それ以外(character, cdataなど)では、指定した名前を要素として持つ要素の直下のみコールバックが呼び出されます。フィルタリングに使われる名前は QName、つまり prefix を含む文字列です。

[PARAM] sym:
イベント名(シンボル)
[PARAM] ary:
要素名によるコールバック呼び出し条件の指定(文字列もしくは正規表現の配列)
[PARAM] listener:
コールバックオブジェクト

例

# CDATAセクションに出会った場合にブロックが呼び出される。
parser.listen(:cdata){|data| ... }

# h1, h2 という要素名を持つ要素が開始した場合にブロックが呼び出される
parser.listen(:start_element, ["h1", "h2"]){|uri, localname, qname, attrs|
  ...
}

# /\Ah[1234]\z/ という正規表現にマッチする要素(h1, .. h4)の直下の
# 文字データに出会った場合に呼び出される
parser.listen(:characters, [/\Ah[1234]\z/]){|data|
  ...
}