=begin
# $Id: manual.rd.src,v 1.1 2003/01/22 16:41:45 katsu Exp $

= xmlscan version 0.2 リファレンスマニュアル

	en| = xmlscan version 0.2 Reference Manual
	en|
	en| This is a broken English version. If you find lexical or
	en| grammatical mistakes, or strange expressions (including kidding,
	en| unnatural or unclear ones) in this document, please
	en| ((<let me know|URL:mailto:katsu@blue.sky.or.jp>)).

== 概要

	en| == Abstract

xmlscan は Ruby だけで書かれた non-validating XML parser です。

	en| XMLscan is one of non-validating XML parser written in 100%
	en| pure Ruby.

次のような特長があります。

	en| XMLscan's features are as follows:

: 100% pure Ruby
    拡張ライブラリを一切必要としないので、1.6 以上の Ruby インタプリタだけ
    あれば完全に動作します。(標準添付の拡張ライブラリも必要としません。)

	en| : 100% pure Ruby
	en|     XMLscan doesn't require any extension libraries, so
	en|     it completely works only with a Ruby interpreter version
	en|     1.6 or above.
	en|     (It also needs no standard-bundled extension library.)

: 規格への適合性
    xmlscan は、XML 1.0 Specification で述べられている、妥当性を検証しない
    プロセサに求められる全ての条件を満たすことを目標に開発が進められて
    います。

	en| : Compliant to the specification
	en|     XMLscan has been developed to satisfy all conditions,
	en|     described in XML 1.0 Specification and required to a
	en|     non-validating XML processor

: 高速
    xmlscan の解析の速さは、おそらく、現存する Ruby で書かれた
    XML/HTML parser の中で最速です。

	en| : High-speed
	en|     XMLscan is, probably, the fastest parser among all
        en|     existing XML/HTML parsers written in pure Ruby.

: 様々なCESに対応
    xmlscan は少なくとも iso-8859-*, EUC-*, Shift_JIS, UTF-8 で書かれた
    XML文書をそのまま解析できます。ただし UTF-16 は扱えません。

	en| : Support for various CES.
	en|     XMLscan can parse an XML document encoded in at least
	en|     iso-8859-*, EUC-*, Shift_JIS, and UTF-8 as it is.
	en|     UTF-16 is not supported directly, though.

: 解析するだけ
    xmlscan の役割は、ただXML文書を解析することだけです。XML文書を
    簡便に取り扱うための高レベルな機能は提供しません。xmlscan は
    そのような機能を提供するライブラリのコア部分として使われることを
    想定しています。

	en| : Just parsing
	en|     The role of xmlscan is just to parse an XML document.
	en|     XMLscan doesn't provide high-level features to easily
	en|     handle an XML document. XMLscan is assumed to be used as
	en|     a core part of a library providing such features.

: HTML
    オマケで HTML を構文解析する htmlscan が付いています。

	en| : HTML
	en|     XMLscan contains htmlscan, an HTML parser.


== 文字エンコーディングについて

	en| == Character encodings

デフォルトでは、xmlscan がどの CES (Character Encoding Scheme) で
XML文書を解析するかはグローバル変数 $KCODE の値によって決まります。
EUC-*, Shift_JIS, UTF-8 で書かれたXML文書を解析するには $KCODE や
((<XMLScan::XMLScanner#kcode=>)) に適切な値を設定する必要があります。

	en| By default, the value of global variable $KCODE decides
	en| which CES (character encoding scheme) is assumed for xmlscan
	en| to parse an XML document.
	en| You need to set $KCODE or ((<XMLScan::XMLScanner#kcode=>))
	en| an appropriate value to parse an XML document encoded in EUC-*,
	en| Shift_JIS, or UTF-8.

UTF-16 は直接サポートしていません。解析前に一旦 UTF-8 に変換する
必要があります。

	en| UTF-16 is not supported directly. You should convert it into
	en| UTF-8 before parsing.


== XML名前空間について

	en| == XML Namespaces

XML名前空間は xmlscan/namespace.rb で実装されていますが、インターフェースを
大きく変更する予定があるため undocumented とします。

	en| XML Namespaces have been already implemented in
	en| xmlscan/namespace.rb. However, since its interface is going
	en| to be modified, this feature is undocumented now.



== クラスリファレンス
	en| == Class Reference


=== XMLScan::Error

xmlscan に関する全ての例外のスーパークラス。

	en| The superclass for all exceptions related to xmlscan.

これらの例外は、XMLScan::Visitor のインスタンスが、XMLScan::XMLScanner や
XMLScan::XMLParser からエラー報告を受け取ったときに、デフォルトで発生させる
ものです。各パーサが直接これらの例外を投げることはありません。

	en| These exceptions are raised by XMLScan::Visitor
	en| by default when it receives an error report from a parser,
	en| such as XMLScan::XMLScanner or XMLScan::XMLParser.
	en| Each parser never raises these exceptions by itself.

#次の例外は xmlscan/scanner.rb で定義されています。
	en| #The following exceptions are defined in xmlscan/scanner.rb:

: XMLScan::ParseError

    生成規則にマッチしない等、制約違反以外のエラー。

	en| An error except a constraint violation, for example,
	en| an XML document is unmatched with a production.

: XMLScan::NotWellFormedError

    整形式制約に違反している。

	en| Raised when an XML document violates an well-formedness
	en| constraint.

: XMLScan::NotValidError

    妥当性制約に違反している。

	en| Raised when an XML document violates an validity constraint.


=== XMLScan::Visitor

XML文書の解析結果を受け取るための Mix-in です。

	en| Mix-in for receiving the result of parsing an XML document.

xmlscan に含まれる各 parser は、文書の先頭から構文解析を行い、タグ等の
構文要素を見つけるたびに、パーサに与えられた XMLScan::Visitor の
インスタンスの特定のメソッドを呼び出します。この呼び出しは、必ず文書の
先頭から順番に行われます。

	en| Each parser included in xmlscan parses an XML document from
	en| the beginning, and calls each specific method of given instance of
	en| XMLScan::Visitor for each syntactic element, such as a tag.
	en| It is ensured that these calls is in order of the appearance
	en| in the document from the beginning.

==== メソッド:
	en| ==== Methods:

特に記述の無い限り、各メソッドはデフォルトでは何もしません。

	en| Without special notice, the following methods do nothing by
	en| default.

--- XMLScan::Visitor#parse_error(msg)

    生成規則にマッチしない等、制約違反以外のエラーを発見した場合に
    呼び出されます。デフォルトでは ((<XMLScan::ParseError>))例外を
    発生させます。例外処理等の大域脱出を行わずに普通に制御を
    パーサに返すと、パーサはエラーを回復して解析を続けます。

	en| Called when the parser meets an error except a constraint
	en| violation, for example, an XML document is unmatched with
	en| a production. By default, this method raises
	en| ((<XMLScan::ParseError>)) exception. If no exception is
	en| raised and this method returns normally, the parser recovers
	en| the error and continues to parse.

--- XMLScan::Visitor#wellformed_error(msg)

    整形式制約違反を発見した場合に呼び出されます。デフォルトでは
    ((<XMLScan::NotWellFormedError>))例外を発生させます。例外処理等の
    大域脱出を行わずに普通に制御をパーサに返すと、パーサはエラーを
    回復して解析を続けます。

	en| Called when the parser meets an well-formedness constraint
	en| violation. By default, this method raises
        en| ((<XMLScan::NotWellFormedError>)) exception. If no exception
	en| is raised and this method returns normally, the parser recovers
	en| the error and continues to parse.

--- XMLScan::Visitor#valid_error(msg)

    妥当性制約違反を発見した場合に呼び出されます。デフォルトでは
    ((<XMLScan::NotValidError>))例外を発生させます。例外処理等の
    大域脱出を行わずに普通に制御をパーサに返すと、パーサはエラーを
    回復して解析を続けます。

	en| Called when the parser meets validity constraint
	en| violation. By default, this method raises
        en| ((<XMLScan::NotValidError>)) exception. If no exception
	en| is raised and this method returns normally, the parser recovers
	en| the error and continues to parse.

    なお、現在の xmlscan には妥当性を検証するXMLプロセサは
    含まれていません。このメソッドは将来の版のために予約されています。

	en| FYI, current version of xmlscan includes no validating XML
	en| processor. This method is reserved for future versions.

--- XMLScan::Visitor#warning(msg)

    エラーではないが推奨されない事柄や、xmlscan では十分に解析できない
    構文を発見した場合に呼び出されます。

	en| Called when the parser meets a non-error but unrecommended
	en| thing or a syntax which xmlscan is not able to parse.

--- XMLScan::Visitor#on_start_document

    XML文書の解析を始める直前に呼び出されます。このメソッドが呼び出された
    後には必ず、対応する ((<XMLScan::Visitor#on_end_document>)) メソッドが
    呼び出されます。

	en| Called just before the parser starts parsing an XML document.
	en| After this method is called, corresponding
	en| ((<XMLScan::Visitor#on_end_document>)) method is always called.

--- XMLScan::Visitor#on_end_document

    XML文書の終端まで解析し終った後に呼び出されます。

	en| Called after the parser reaches the end of an XML document.

--- XMLScan::Visitor#on_xmldecl
--- XMLScan::Visitor#on_xmldecl_version(str)
--- XMLScan::Visitor#on_xmldecl_encoding(str)
--- XMLScan::Visitor#on_xmldecl_standalone(str)
--- XMLScan::Visitor#on_xmldecl_other(name, value)
--- XMLScan::Visitor#on_xmldecl_end

    XML宣言を発見した場合に呼び出されます。

	en| Called when the parser meets an XML declaration.

        <?xml version="1.0" encoding="euc-jp" standalone="yes" ?>
        ^     ^             ^                 ^                ^
        1     2             3                 4                5

                     method                 argument
                 --------------------------------------
                  1: on_xmldecl
                  2: on_xmldecl_version     ("1.0")
                  3: on_xmldecl_encoding    ("euc-jp")
                  4: on_xmldecl_standalone  ("yes")
                  5: on_xmldecl_end

    XML宣言を発見した場合、on_xmldecl と on_xmldecl_end は必ず
    呼び出されます。他のメソッドは対応する構文がXML宣言中に
    現れなかった場合は呼び出されません。

	en| When an XML declaration is found, both on_xmldecl and
	en| on_xmldecl_end method are always called. Any other methods
	en| are called only when the corresponding syntaxes are found.

    on_xmldecl_other は version, encoding, standalone 以外の宣言が
    XML宣言の中にあった場合に呼び出されます。そのような宣言は構文上
    許されていないため、on_xmldecl_other が呼び出される前には必ず
    ((<XMLScan::Visitor#parse_error>)) メソッドが呼び出されることに
    注意して下さい。

	en| When a declaration except version, encoding, and standalone
	en| is found in an XML declaration, on_xmldecl_other method is
	en| called. Since such a declaration is not permitted, note that
	en| the parser always calls ((<XMLScan::Visitor#parse_error>)) method
	en| before calling on_xmldecl_other method.

--- XMLScan::Visitor#on_doctype(root, pubid, sysid)

    文書型宣言を発見した場合に呼び出されます。

	en| Called when the parser meets a document type declaration.

             document                            argument
        --------------------------------------------------------------
         1: <!DOCTYPE foo>                      ('foo', nil,   nil)
         2: <!DOCTYPE foo SYSTEM "bar">         ('foo', nil,   'bar')
         3: <!DOCTYPE foo PUBLIC "bar">         ('foo', 'bar',  nil )
         4: <!DOCTYPE foo PUBLIC "bar" "baz">   ('foo', 'bar', 'baz')

--- XMLScan::Visitor#on_prolog_space(str)

    前書きの中に空白を発見した場合に呼び出されます。

	en| Called when the parser meets whitespaces in prolog.

--- XMLScan::Visitor#on_comment(str)

    コメントを発見した場合に呼び出されます。

	en| Called when the parser meets a comment.

--- XMLScan::Visitor#on_pi(target, pi)

    処理命令を発見した場合に呼び出されます。

	en| Called when the parser meets a processing instruction.

--- XMLScan::Visitor#on_chardata(str)

    文字データを発見した場合に呼び出されます。

	en| Called when the parser meets character data.

--- XMLScan::Visitor#on_cdata(str)

    CDATAセクションを発見した場合に呼び出されます。

	en| Called when the parser meets a CDATA section.

--- XMLScan::Visitor#on_entityref(ref)

    属性値の中以外の場所で一般実体参照を発見した場合に呼び出されます。

	en| Called when the parser meets a general entity reference
	en| in a place except an attribute value.

--- XMLScan::Visitor#on_charref(code)
--- XMLScan::Visitor#on_charref_hex(code)

    属性値の中以外の場所で文字参照を発見した場合に呼び出されます。
    文字コードが10進数で指定されていた場合は on_charref、16進数で
    指定されていた場合は on_charref_hex が呼び出されます。
    ((|code|))は整数です。

	en| Called when the parser meets a character reference
	en| in a place except an attribute value.
	en| When the character code is represented by decimals,
	en| on_charref is called. When by hexadecimals, on_charref_hex
	en| is called. ((|code|)) is an integer.

--- XMLScan::Visitor#on_stag(name)
--- XMLScan::Visitor#on_attribute(name)
--- XMLScan::Visitor#on_attr_value(str)
--- XMLScan::Visitor#on_attr_entityref(ref)
--- XMLScan::Visitor#on_attr_charref(code)
--- XMLScan::Visitor#on_attr_charref_hex(code)
--- XMLScan::Visitor#on_attribute_end(name)
--- XMLScan::Visitor#on_stag_end_empty(name)
--- XMLScan::Visitor#on_stag_end(name)

    開始タグを発見した場合に呼び出されます。

	en| Called when the parser meets an XML declaration.

        <hoge fuga="foo&bar;&#38;&#x26;baz"  >
        ^     ^     ^  ^    ^    ^     ^  ^  ^
        1     2     3  4    5    6     7  8  9

             method                 argument
         ------------------------------------
          1: on_stag                ('hoge')
          2: on_attribute           ('fuga')
          3: on_attr_value          ('foo')
          4: on_attr_entityref      ('bar')
          5: on_attr_charref        (38)
          6: on_attr_charref_hex    (38)
          7: on_attr_value          ('baz')
          8: on_attribute_end       ('fuga')
          9: on_stag_end            ('hoge')
              or
             on_stag_end_empty      ('hoge')

    開始タグを発見した場合、on_stag と、対応する on_stag_end 又は
    on_stag_end_empty は必ず呼び出されます。他のメソッドは、開始タグの
    中に属性が現れなかった場合は呼び出されません。

	en| When a start tag is found, both on_stag and corresponding
	en| either on_stag_end or on_stag_end_empty method are always
	en| called. Any other methods are called only when at least one
	en| attribute is found in the start tag.

    属性を発見した場合、on_attribute と on_attribute_end は必ず
    呼び出されます。属性値が空 (fuga="") の時は、この2つのメソッドのみが
    呼び出されます。

	en| When an attribute is found, both on_attribute and
	en| on_attribute_end method are always called. If the attribute
	en| value is empty, only these two methods are called.

    on_attr_entityref は属性値の中で一般実体参照を発見した場合に
    呼び出されます。on_charref 及び on_charref_hex は属性値の中で
    文字参照を発見した場合に呼び出されます。

	en| When the parser meets a general entity reference in an
        en| attribute value, it calls on_attr_entityref method.
	en| When the parser meets a character reference in an attribute
	en| value, it calls either on_charref or on_charref_hex method.

    タグが空要素タグだった場合は、on_stag_end メソッドの代わりに
    on_stag_end_empty メソッドが呼び出されます。

	en| If the tag is an empty element tag, on_stag_end_empty method
	en| is called instead of on_stag_end method.

--- XMLScan::Visitor#on_etag(name)

    終了タグを発見した場合に呼び出されます。

	en| Called when the parser meets an end tag.



=== XMLScan::XMLScanner

XML文書を字句解析し、タグ等を認識するスキャナです。

	en| The scanner which tokenizes an XML document and recognize tags,
	en| and so on.

XMLScan::XMLScanner の規格適合性については、他の文書で述べています。

	en| The conformance of XMLScan::XMLScanner to the specification
	en| is described in another document.

==== スーパークラス:
	en| ==== SuperClass:

* Object

==== クラスメソッド:
	en| ==== Class Methods:

--- XMLScan::XMLScanner.new(visitor[, option ...])

    XMLScan::XMLScanner オブジェクトを生成します。((|visitor|))は
    XMLScan::Visitor のインスタンスで、XMLScan::XMLScanner オブジェクトから
    解析結果を受け取ります。

	en| Creates an instance. ((|visitor|)) is a instance of
	en| ((<XMLScan::Visitor>)) and receives the result of parsing
	en| from the XMLScan::Scanner object.

    ((|option|))は文字列又はシンボルで指定します。optionには
    次のものがあります。

	en| You can specify one of more ((|option|)) as a string or symbol.
	en| XMLScan::Scanner's options are as follows:

    : 'strict_char'

        (({require 'xmlscan/xmlchar'})) すると指定できるようになります。
        不正な文字が使われていないかどうかのチェックを行います。
        パフォーマンスが著しく低下します。

		en| This option is enabled after
		en| (({require 'xmlscan/xmlchar'})).
		en| XMLScan::Scanner checks whether an XML document includes
		en| an illegal character. The performance decreases sharply.

==== メソッド:
	en| ==== Methods:

--- XMLScan::XMLScanner#kcode= arg

    CESを指定します。((|arg|))の解釈は、nil を除いて $KCODE と同じです。
    ((|arg|))が nil のときは、どの CES で解析を行うかは $KCODE の値によって
    決まります。

	en| Sets CES. Available values for ((|code|)) are same as $KCODE
	en| except nil. If ((|code|)) is nil, $KCODE decides the CES.

--- XMLScan::XMLScanner#kcode

    どの CES で解析を行うかを Regexp#kcode と同じ形式で返します。
    nilのときは$KCODEに依存することを表します。

	en| Returns CES. The format of the return value is same as
	en| Regexp#kcode. If this method returns nil, it represents that
	en| $KCODE decides the CES.

--- XMLScan::XMLScanner#parse(source)

    ((|source|)) をXML文書として解析します。((|source|)) は文字列か
    文字列の配列、又は IO#gets と同じ振る舞いをする gets メソッドを持つ
    オブジェクトでなければなりません。

	en| Parses ((|source|)) as an XML document. ((|source|)) must be
	en| a string, an array of strings, or an object which responds to
	en| gets method which behaves same as IO#gets does.


=== XMLScan::XMLParser

妥当性を検証しない XML parser です。

	en| The non-validating XML parser.

XMLScan::XMLParser の規格適合性については、他の文書で述べています。

	en| The conformance of XMLScan::XMLParser to the specification
	en| is described in another document.


==== スーパークラス:
	en| ==== SuperClass:

* ((<XMLScan::XMLScanner>))

==== クラスメソッド:
	en| ==== Class Methods:

--- XMLScan::XMLParser.new(visitor[, option ...])

    XMLScan::XMLParser オブジェクトは((|visitor|))の各メソッドについて、
    次のことを保証します。

		en| XMLScan::XMLParser makes sure the following for each
		en| method of ((|visitor|)):

    : ((<XMLScan::Visitor#on_stag>))

        このメソッドを呼び出した後に、対応する ((<XMLScan::Visitor#on_etag>))
        メソッドを必ず呼び出します。

		en| After calling this method, XMLScan::Parser always call
		en| corresponding ((<XMLScan::Visitor#on_etag>)) method.

    加えて、エラー回復を行わなければ、整形式のXML文書では起こり得ない
    メソッド呼び出しは全て抑制されます。

	en| In addition, if you never intend error recovery, method calls
	en| which must not be occurred in a well-formed XML document are
	en| all suppressed.


=== XMLScan::HTMLScanner

((<XMLScan::XMLScanner>)) を元にした HTML パーサです。

	en| An HTML parser based on ((<XMLScan::XMLScanner>)).

XMLScan::HTMLScanner の規格適合性については、他の文書で述べています。

	en| The conformance of XMLScan::HTMLScanner to the specification
	en| is described in another document.

==== スーパークラス:
	en| ==== SuperClass:

* ((<XMLScan::XMLScanner>))

==== クラスメソッド:
	en| ==== Class Methods:

--- XMLScan::HTMLScanner.new(visitor[, option ...])

    XMLScan::HTMLScanner オブジェクトは((|visitor|))の各メソッドについて、
    次のことを保証します。

		en| XMLScan::HTMLScanner makes sure the following for each
		en| method of ((|visitor|)):

    : ((<XMLScan::Visitor#on_xmldecl>))
    : ((<XMLScan::Visitor#on_xmldecl_version>))
    : ((<XMLScan::Visitor#on_xmldecl_encoding>))
    : ((<XMLScan::Visitor#on_xmldecl_standalone>))
    : ((<XMLScan::Visitor#on_xmldecl_end>))

        HTML には XML宣言は存在しないので、これらのメソッドを呼び出すことは
        ありません。

		en| An XML declaration never appears in an HTML document,
		en| so XMLScan::HTMLScanner never calls these methods.

    : ((<XMLScan::Visitor#on_stag_end_empty>))

        HTML には空要素タグは存在しないので、このメソッドを呼び出すことは
        ありません。空要素タグは解析エラーになります。

		en| An empty element tag never appears in an HTML document,
		en| so XMLScan::HTMLScanner never calls this method.
		en| An empty element tag causes a parse error.

    : ((<XMLScan::Visitor#wellformed_error>))

        HTML には整形式制約が存在しないので、このメソッドを呼び出すことは
        ありません。

		en| There is no well-formedness constraint for HTML,
		en| so XMLScan::HTMLScanner never calls this method.

=end
