The documentation of “xml” header file package

xmlヘッダファイルパッケージマニュアル

(The documentation of xml header file package)

Last Update: 2022/11/11

xmlヘッダファイルパッケージには Extensible Markup Language (XML)形式のデータに対して様々な処理を行うヘッダファイルをまとめてある。
Header files to perform various operations for data in Extensible Markup Language (XML) format are included in xml header file package.

このヘッダファイルの作成にあたっては Extensible Markup Language (XML) 1.0 (Fifth Edition) — W3C Recommendation 26 November 2008 を参照した。但し、世の中のあらゆるXMLファイルを取り扱えるコードを開発するのではなく (これには時間がかかる)、著者の研究で使用する特定のXMLファイルを取り扱えるコードを短期間で開発することを目的とした。そのためこのヘッダファイルで取り扱えるのは下記の仕様を満たすXMLファイルのみとなる。
Extensible Markup Language (XML) 1.0 (Fifth Edition) — W3C Recommendation 26 November 2008 was refered in developing this header file. However, instead of developing a code that can treat all existing XML files, which takes a long time, I aimed to rapidly develop a code to treat specific XML files that are used in my research. Therefore, only the XML files that satisfy the specifications below can be treated by this header file.

読み込むXMLデータは単一のテキストファイル内で完結していること。
The XML data to read must be complete within a single text file.
<?xmlと ?> で囲まれた要素(XML宣言)で開始すること。なおymaeda_opentoolsではXML宣言の中身は読み飛ばされる。
The file must begin with an element bounded by <?xml and ?> (an XML declaration). Note that the content of the XML declaration is ignored in ymaeda_opentools.
ファイル内の任意の場所に  で囲まれた文字列を挿入することができ、その文字列はコメントとして無視される。
Texts bounded by  can be inserted at arbitrary locations of the file, which are ignored as comments.
ファイル内の任意の場所に <![CDATA[と ]]> で囲まれた文字列(CDATA区間) を挿入することができる。但しymaeda_opentoolsではCDATA区間はコメントと同様に読み飛ばされる。
Texts bounded by <![CDATA[ and ]]> (CDATA sections) can be inserted at arbitrary locations of the file; however, they are ignored like comments in ymaeda_opentools.
ファイルからXML宣言、コメント、CDATA区間を除いた残りの部分はすべて下記のいずれかの形式を持つ要素のみで構成されなければならない。
All remaining parts of the file, i.e., parts other than the XML declaration, comments, and CDATA sections, must consist of only the elements, each of which must have one of the following formats.
- 開始タグ (<タグ名>)で始まり 終了タグ (</タグ名>)で終わる。
  The element starts with a start-tag (<tag name>) and ends with an end-tag (</tag name>).
- 空要素タグ (<タグ名/>) で表現される。
  The element is expressed by an empty-element tag (<tag name/>).
タグ名は自由であり、重複も許容される。
Arbitrary tag names can be used. The tag names can duplicate.
要素内に他の要素を自由に入れ子にすることができる。 XMLデータは全体として 1つの親要素の中に任意の個数の小要素が入った木構造となる。木を構成する大元の親要素(root要素)は 1つでなければならない。
The elements can arbitrary be nested. As a whole, the XML data is a tree structure such that each parent element consists of an arbitrary number of child elements. Only one tree of the nested elements, starting from a single root element, is allowed in an XML file.
XML宣言、各要素の開始タグおよび空要素タグには属性を与えることができる。属性は属性名="値"の形式とし、これらをタグ名の後ろにスペースで区切って任意の個数並べることができる。
The XML declaration, the start-tag, and the empty-element tag of each element can have an arbitrary number of attributes, which are written after the tag name and separated by spaces. Each attribute is given in name of attribute="value of attribute" format.

以下がこのヘッダファイルでサポートするXMLファイルの例である。
An example below shows an XML file supported by this header file.

<?xml version="1.0" encoding="UTF-8"?>
<data>
   <subdata id="earlier" range="A-N">
      <alphabets1>ABC</alphabets1>
      <alphabets2>DEFG</alphabets2>
      <alphabets3>HIJK</alphabets3>
      <alphabets4>LMN</alphabets4>
   </subdata>
   <subdata id="later" range="O-Z">
      <alphabets1>OPQR</alphabets1>
      <alphabets2>STU</alphabets2>
      <alphabets3>VWXYZ</alphabets3>
      <message content="that's all"/>
   </subdata>
</data>

このようなデータを取り扱うため、 xmlヘッダファイルパッケージでは以下の2種類の構造体を定義している。
To cope with this data, the following two structures are defined in xml header file package.

struct XMLdata型構造体 (struct XMLdata-type structure)
1つのXMLファイルの中身全体を表現する構造体である。この構造体の中では全てのXML要素を階層や親子関係に関わらず並列に書き並べる。
A structure to express the entire content of an XML file. In this structure, all XML elements are listed in parallel, regardless of their hierarchy levels and parent-child relations.
struct XMLelement型構造体 (struct XMLelement-type structure)
1つのXML要素の中身を表現する構造体である。他のXML要素との親子関係はこの構造体内で記述される。
A structure to express the content of an XML element. Its parent-child relations to other XML elements are described in this structure.

struxt XMLdata型構造体の1メンバとして struxt XMLelement型構造体を並べた配列が存在し、 XML要素間の親子関係はその配列要素番号を用いて記述されることになる。前出のXMLファイルの例について表現方法を模式的に図示すると以下のようになる。
An array of struct XMLelement-type structures is used as a member of a struct XMLdata-type structure, and the parent-child relations of XML elements are described using the corresponding array indices. This method of representation, for the sample XML file shown earlier, is schematically illustrated below.

XMLファイルの中身(struct XMLdata型構造体)
Content of an XML file (a struct XMLdata-type structure)

XML要素の総数 Total number of XML elements	Nelements	11
XML要素を並べた配列 An array composed of XML elements	elements[0]	<data>	親要素: 無し Parent element: none	子要素: 1, 6 Child elements: 1, 6
	elements[1]	<subdata id="earlier" range="A-N">	親要素: 0 Parent element: 0	子要素: 2, 3, 4, 5 Child elements: 2, 3, 4, 5
	elements[2]	<alphabets1> ABC	親要素: 1 Parent element: 1	子要素: 無し Child elements: none
	elements[3]	<alphabets2> DEFG	親要素: 1 Parent element: 1	子要素: 無し Child elements: none
	elements[4]	<alphabets3> HIJK	親要素: 1 Parent element: 1	子要素: 無し Child elements: none
	elements[5]	<alphabets1> LMN	親要素: 1 Parent element: 1	子要素: 無し Child elements: none
	elements[6]	<subdata id="later" range="O-Z">	親要素: 0 Parent element: 0	子要素: 7, 8, 9, 10 Child elements: 7, 8, 9, 10
	elements[7]	<alphabets1> OPQR	親要素: 6 Parent element: 6	子要素: 無し Child elements: none
	elements[8]	<alphabets2> STU	親要素: 6 Parent element: 6	子要素: 無し Child elements: none
	elements[9]	<alphabets3> VWXYZ	親要素: 6 Parent element: 6	子要素: 無し Child elements: none
	elements[10]	<message content="that's all"/>	親要素: 6 Parent element: 6	子要素: 無し Child elements: none

この例が示すように、struct XMLdata型構造体においては XML要素は並列に並んでいるだけである。 elements[0]-elements[10]がstruct XMLelement型構造体になっており、その中で親要素、子要素の参照が配列要素番号ベースで行われている。例えば<data>要素は elements[0]に格納されている。この要素の子要素は <subdata id="earlier" range="A-N"> と <subdata id="later" range="O-Z"> であるが、これらはそれぞれ elements[1], elements[6] に格納されているのでその配列要素番号の 1と 6が elements[0]の中で子要素の番号として参照されている。
As this example shows, XML elements are simply listed in parallel in a struct XMLdata-type structure. Members elements[0]-elements[10] are struct XMLelement-type structures, in which parent and child elements are referred based on array indices. For example, <data> element is stored in elements[0]. The child elements of this element are <subdata id="earlier" range="A-N"> and <subdata id="later" range="O-Z">, which are stored in elements[1] and elements[6], respectively. The corresponding array indices, 1 and 6, are referred as the child element indices of elements[0].

xmlヘッダファイルパッケージ内のヘッダファイルを以下に示す。各ヘッダファイルの詳細はリンクをクリックして参照のこと。
Header files in xml header file package are listed below. For details of individual header files, click the links.

◆特殊なヘッダファイル (Special header files)

ヘッダファイル名 Header file name	機能・用途 Purpose
xml/index.h	xmlヘッダファイルパッケージ内の他のヘッダファイル一式をインクルードするためのヘッダファイル。 A header file to include all the other header files in xml header file package.
xml/structure.h	xmlヘッダファイルパッケージ用の構造体の定義。 Definitions of structures for xml header file package.
xml/prototype.h	xmlヘッダファイルパッケージ内の関数のプロトタイプ。 Prototypes of functions in xml header file package.

◆通常のヘッダファイル (Normal header files)

ヘッダファイル名 Header file name	機能・用途 Purpose
xml/check.h	XMLデータの処理における各種のチェックを行う関数。 Functions to perform checks in various processings of XML data.
xml/info.h	XMLデータから情報を取り出す関数。 Functions to extract information from XML data.
xml/parent_child.h	XMLタグの親子関係を同定する関数。 Functions to identify parent-child relations among XML tags.
xml/readwrite.h	XMLファイルの入出力を行う関数。 Functions to read and write an XML file.
xml/reformat.h	XMLデータを整形する関数。 Functions to reformat XML data.
xml/tag.h	XMLタグを処理する関数。 Functions to process XML tags.

xmlヘッダファイルパッケージ マニュアル

◆特殊なヘッダファイル (Special header files)

◆通常のヘッダファイル (Normal header files)

xmlヘッダファイルパッケージマニュアル