%XML.TextReader の使用

全体構造

メソッドは以下の操作の一部またはすべてを実行する必要があります。

1. 以下のメソッドのいずれかの最初の引数を使用して、ドキュメント・ソースを指定します。

   メソッド	最初の引数
   ParseFile()	完全なパスを含むファイル名ファイル名およびパスは ASCII 文字のみを含む必要があります。
   ParseStream()	ストリーム
   ParseString()	文字列
   ParseURL()	URL

   どのような場合でも、ソース・ドキュメントは、適格な XML ドキュメント、つまり、XML 構文の基本的な規約に従ったドキュメントである必要があります。これらのメソッドはそれぞれ、結果が成功だったかどうかを示すステータス ($$$OK または失敗コード) を返します。通常のメカニズムでステータスをテストできます。特に、$System.Status.DisplayError(status) を使用して、エラー・メッセージのテキストを表示できます。

   メソッドは $$$OK を返す場合、これらのメソッドのそれぞれに対し、参照 (2 番目の引数) によって、XML ドキュメント内の情報を含むテキスト・リーダ・オブジェクトを返します。

   引数をさらに追加すると、エンティティの解析、検証、検出された項目などを制御できます。これらは、この章の後半の “解析メソッドの引数リスト” で説明しています。

2. 解析メソッドで返されたステータスを確認し、必要に応じて実行を中止します。

   解析メソッドが $$$OK を返した場合、テキスト・リーダ・オブジェクトはソース XML ドキュメントに対応しています。このオブジェクトはナビゲートできます。

   ドキュメントには多くの場合、"element"、"endelement"、"startprefixmapping" などのノードが含まれています。ノード・タイプは、この章で後述する “ノード・タイプ” にリストが記載されています。

   Important:

   どのような検証エラーが発生した場合でも、ドキュメントには "error" ノードまたは "warning" ノードが含まれています。そのようなノードがないか、コードで確認する必要があります。“検証の実行” を参照してください。

3. 以下のインスタンス・メソッドのいずれかを使用して、ドキュメントの読み取りを開始します。

   • ドキュメントの最初のノードへ移動するには、Read() を使用します。

   • 特定のタイプの最初の要素へ移動するには、ReadStartElement() を使用します。

   • "chars" の最初のノードへ移動するには、MoveToContent() を使用します。

   この章内で後述の “ドキュメントのナビゲート” を参照してください。

4. このノードで関係するプロパティの値があれば、それを取得します。利用可能なプロパティには、Name、Value、Depth などがあります。この章内で後述の “ノード・プロパティ” を参照してください。

5. 必要に応じてドキュメントのナビゲートおよびプロパティ値の取得を続けます。

   現在のノードが要素の場合、MoveToAttributeIndex() または MoveToAttributeName() メソッドを使用して、要素の属性にフォーカスを移動できます。要素に戻るには、該当する場合は MoveToElement() を使用します。

6. 必要に応じて、Rewind() メソッドを使用して、ドキュメントの最初 (最初のノードの前) に戻ります。これは、ソース内を後退できる唯一のメソッドです。

メソッドの実行後、テキスト・リーダは消滅し、関連する一時格納場所もすべてクリーンアップされます。

例 1

ここでは、任意の XML ファイルを読み取り、各ノードのシーケンス番号、タイプ、名前、および値を表示する単純なメソッドを示します。

ClassMethod WriteNodes(myfile As %String)
{
    set status=##class(%XML.TextReader).ParseFile(myfile,.textreader)
    //check status
    if $$$ISERR(status) {do $System.Status.DisplayError(status) quit}
    //iterate through document, node by node
    while textreader.Read()
    {
        Write !, "Node ", textreader.seq, " is a(n) "
        Write textreader.NodeType," "
        If textreader.Name'=""
        {
            Write "named: ", textreader.Name
            }
            Else
            {
                Write "and has no name"
                }
        Write !, "    path: ",textreader.Path
        If textreader.Value'="" 
        {
            Write !, "    value: ", textreader.Value
            }
        }
}

この例は、以下を実行します。

1. ParseFile() クラス・メソッドを呼び出します。このメソッドはソース・ファイルを読み取り、テキスト・リーダ・オブジェクトを生成して、変数 doc 内でそのオブジェクトを参照によって返します。

2. ParseFile() が成功した場合、このメソッドは Read() メソッドを実行して、ドキュメント内で次のノードをそれぞれ検索します。

3. 各ノードについて、このメソッドは、そのノードのシーケンス番号、ノード・タイプ、ノード名 (存在する場合)、ノード・パス、およびノード値 (存在する場合) が含まれた出力行を記述します。現在のデバイスに出力されます。

以下の例のソース・ドキュメントを考えてみます。

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/css" href="mystyles.css"?>
<Root>
   <s01:Person xmlns:s01="http://www.root.org">
      <Name attr="xyz">Willeke,Clint B.</Name>
      <DOB>1925-10-01</DOB>
   </s01:Person>
</Root>

このソース・ドキュメントについては、前述のメソッドで以下の出力が生成されます。

Node 1 is a(n) processinginstruction named: xml-stylesheet
    path:
    value: type="text/css" href="mystyles.css"
Node 2 is a(n) element named: Root
    path: /Root
Node 3 is a(n) startprefixmapping named: s01
    path: /Root
    value: s01 http://www.root.org
Node 4 is a(n) element named: s01:Person
    path: /Root/s01:Person
Node 5 is a(n) element named: Name
    path: /Root/s01:Person/Name
Node 6 is a(n) chars and has no name
    path: /Root/s01:Person/Name
    value: Willeke,Clint B.
Node 7 is a(n) endelement named: Name
    path: /Root/s01:Person/Name
Node 8 is a(n) element named: DOB
    path: /Root/s01:Person/DOB
Node 9 is a(n) chars and has no name
    path: /Root/s01:Person/DOB
    value: 1925-10-01
Node 10 is a(n) endelement named: DOB
    path: /Root/s01:Person/DOB
Node 11 is a(n) endelement named: s01:Person
    path: /Root/s01:Person
Node 12 is a(n) endprefixmapping named: s01
    path: /Root
    value: s01
Node 13 is a(n) endelement named: Root
    path: /Root

コメントが無視されていることに注意してください。既定では、%XML.TextReaderOpens in a new tab クラスはコメントを無視します。この変更の詳細は、この章で後述する“解析メソッドの引数リスト” で説明します。

例 2

以下の例では、XML ファイルを読み取り、その中の各要素をリスト表示します。

ClassMethod ShowElements(myfile As %String)
{
    set status = ##class(%XML.TextReader).ParseFile(myfile,.textreader)
    //check status
    if $$$ISERR(status) {do $System.Status.DisplayError(status) quit}
    //iterate through document, node by node
    while textreader.Read()
    {
        if (textreader.NodeType = "element") 
        {
            write textreader.Name,!
            }
        }
}

このメソッドは、NodeType プロパティを使用して、各ノードのタイプをチェックします。そのノードが要素の場合、メソッドはその名前を現在のデバイスに出力します。前述の XML ソース・ドキュメントについては、このメソッドで以下の出力が生成されます。

Root
s01:Person
Name
DOB

次のノードへの移動

ドキュメント内の次のノードに進むには、Read() メソッドを使用します。Read() メソッドは、前方のノードが存在しなくなるまで (つまり、ドキュメントの末尾に達するまで)、True の値を返します。前述の例では、このメソッドを以下のようなループで使用しました。

 While (textreader.Read()) {

...

 }

特定の要素の最初の出現箇所への移動

ドキュメント内の特定の要素の、最初の出現箇所に移動できます。この操作には、ReadStartElement() メソッドを使用します。このメソッドは、要素が検出されなくなるまで True の値を返します。要素が検出されない場合、メソッドはファイルの末尾に達しています。

ReadStartElement() メソッドは、要素名および (オプションで) ネームスペース URI の 2 つの引数をとります。%XML.TextReaderOpens in a new tab クラスはネームスペースの接頭語を処理しないことに注意してください。これにより、ReadStartElement() メソッドでは以下の 2 つの要素の名前が異なると見なします。

<Person>Smith,Ellen W. xmlns="http://www.person.org"</Person>

<s01:Person>Smith,Ellen W. xmlns:s01="http://www.person.org"</s01:Person>

属性への移動

要素に移動すると、その要素に属性がある場合は、以下の 2 つの方法のいずれかでその属性に移動できます。

• MoveToAttributeIndex() メソッドを使用して、インデックス (要素内の属性の通常の位置) により特定の属性に移動します。このメソッドの引数は、属性のインデックス番号のみです。AttributeCount プロパティを使用して、指定された要素内の属性の数を知ることができます。すべてのプロパティのリストについては、この章で後述する “ノード・プロパティ” を参照してください。

• MoveToAttributeName() メソッドを使用して、名前により特定の属性に移動します。このメソッドは、属性名および (オプションで) ネームスペース URI の 2 つの引数をとります。%XML.TextReaderOpens in a new tab クラスはネームスペースの接頭語を処理しないことに注意してください。属性に接頭語がある場合、その接頭語は属性名の一部と見なされます。

現在の要素に対する属性を終了したら、Read() などの検索メソッドを実行することで、ドキュメント内の次の要素に移動できます。また、MoveToElement() メソッドを実行して、現在の属性を含む要素に戻ることもできます。

例えば、以下のコードは、インデックス番号によって、現在のノードに対するすべての属性をリストにします。

 If (textreader.NodeType = "element") {
     // list attributes for this node
     For a = 1:1:textreader.AttributeCount {
         Do textreader.MoveToAttributeIndex(a)
         Write textreader.LocalName," = ",textreader.Value,!
     }
 }

以下のコードは、現在のノードに対する color 属性の値を検索します。

 If (textreader.NodeType = "element") {
     // find color attribute for this node
     If (textreader.MoveToAttributeName("color")) {
         Write "color = ",textreader.Value,!
     }
 }

コンテンツを含む次のノードへの移動

MoveToContent() メソッドはコンテンツの検出に役立ちます。具体的には以下のとおりです。

• ノードのタイプが "chars" 以外の場合、このメソッドは "chars" タイプの次のノードに進みます。

• ノードのタイプが "chars" の場合、このメソッドはファイル内で先に進みません。

巻き戻し

ここで説明するメソッドは、Rewind() メソッドを除き、すべてドキュメント内を前進します。Rewind() メソッドは、ドキュメントの最初に移動し、すべてのプロパティをリセットします。