import "xml"

xmlパッケージは、XML名前空間を解釈するXML 1.0の簡単なパーサーを実装しています。

パッケージファイル

read.go xml.go

変数

HTMLAutoCloseは、自動的に閉じられるべきであるHTML要素の集合です。

var HTMLAutoClose = htmlAutoClose

HTMLEntityは、エンティティのマップです。標準的なHTMLエンティティ文字の変換を行います。

var HTMLEntity = htmlEntity

Escape関数

func Escape(w io.Writer, s []byte)

Escapeは、プレーンテキストデータsを適切にエスケープし、wへ書き込みます。

Unmarshal関数

func Unmarshal(r io.Reader, val interface{}) os.Error

Unmarshalは、rから読み込み、XML要素を解析し、reflectライブラリを使用して、valが示す構造体、スライス、文字列へ埋め込みます。形式は合っていてもvalに適合しないデータは破棄されます。

まず、例文のために、いくつか定義を行います。

type Email struct {
	Where string "attr"
	Addr  string
}

type Result struct {
	XMLName xml.Name "result"
	Name	string
	Phone	string
	Email	[]Email
}

result := Result{Name: "name", Phone: "phone", Email: nil}

Unmarshal対象のXMLです。

<result>
	<email where="home">
		<addr>gre@example.com</addr>

	</email>
	<email where='work'>
		<addr>gre@work.com</addr>
	</email>
	<name>Grace R. Emlin</name>

	<address>123 Main Street</address>
</result>

Unmarshal(r, &result)の結果は、次の代入に等しいです。

r = Result{xml.Name{"", "result"},
	"Grace R. Emlin", // name
	"phone",	  // no phone given
	[]Email{
		Email{"home", "gre@example.com"},
		Email{"work", "gre@work.com"},
	},
}

r.Phoneフィールドは変更されないこと、XML要素<address>が破棄されることに注意してください。

Unmarshalはreflectパッケージを使用しているので、代入できるのは大文字で始まるフィールドだけです。またXMLの要素名と構造体のフィールド名の比較の際は、大文字と小文字を区別しません。

Unmarshalは、XML要素を以下のルールに従って構造体にマッピングします:

* この構造体が、[]byte型か、もしくは「innerxml」タグを持った文字列型のフィールドを持つとき、
  この要素内のXMLをそのまま、そのフィールドに格納します。その他のルールも合わせて適用されます。

* この構造体が、xml.Name型のXMLNameという名のフィールドを持つとき、そのフィールドに要素名を
  セットします。

* XMLNameフィールドが「タグ」、「名前空間-URL タグ」形式のタグを持つとき、XML要素はそのタグ
  (および、オプションの名前空間)を持っていなければいけません。持っていないときはエラーを
  返します。

* XML要素が属性を持っており、構造体のフィールドで「attr」タグを持つ文字列型フィールドと名前が
  一致するとき、そのフィールドへ属性値をセットします。

* XML要素に文字データが含まれている場合、タグ「chardata」を持つ最初の構造体フィールドへセット
  されます。そのフィールドは[]byte型、または文字列型です。これに該当するフィールドが存在しない
  ときは、この文字データは破棄されます。

* XML要素が子要素を持ち、フィールド名と一致はするが、そのフィールドのタグが「attr」でも
  「chardata」でもないときは、その子要素をフィールドにマッピングします。もしくは、Anyという
  名前のフィールドがあれば、そこに子要素をマッピングします。

XML要素を文字列または[]byteにマッピングするときは、その要素内の文字データを結合してセットします。
XML要素をスライスにマッピングするときは、そのスライスの長さを拡張し、新しく作成した値に要素をマッピングします。
XML要素をboolにマッピングするときは、その文字列が表す論理値をセットします。
XML要素を整数または浮動小数点フィールドにマッピングするときは、文字列を数値として解釈した値をフィールドにセットします。このときオーバフローのチェックは行いません。
XML要素をxml.Nameにマッピングするときは、要素の名前をセットします。
XML要素をポインタにマッピングするときは、ポインタを再割付し、そのポインタが示す値に要素をマッピングします。

Attr型

Attrは、XML要素の属性(Name=Value)を表します。

type Attr struct {
    Name  Name
    Value string
}

CharData型

CharDataは、XML文字データ(生テキスト)を表します。文字がXMLのエスケープシーケンスに置き換えられているときは、そのまま格納されます。

type CharData []byte

(CharData) Copy関数

func (c CharData) Copy() CharData

Comment型

Commentは、<!–comment–>形式のXMLコメントを表します。コメント内にバイトデータを含めることはできません。

type Comment []byte

(Comment) Copy関数

func (c Comment) Copy() Comment

Directive型

Directiveは、<!text>形式のXMLディレクティブを表します。ディレクティブ内にバイトデータを含めることはできません。

type Directive []byte

(Directive) Copy関数

func (d Directive) Copy() Directive

EndElement型

EndElementは、XMLの終了要素を表します。

type EndElement struct {
    Name Name
}

Name型

Nameは、名前空間識別子(Space)を伴なうXML名(Local)を表します。Parser.Tokenから返されるトークンのSpace識別子は正規化されたURLであり、解析したXMLドキュメント内で使われている短いプレフィックスではありません。

type Name struct {
    Space, Local string
}

Parser型

Parserは、特定の入力ストリームから読み込みを行うXMLパーサーを表します。入力ストリームはUTF-8エンコードされているとみなして処理します。

type Parser struct {
    // Strict defaults to true, enforcing the requirements
    // of the XML specification.
    // If set to false, the parser allows input containing common
    // mistakes:
    //	* If an element is missing an end tag, the parser invents
    //	  end tags as necessary to keep the return values from Token
    //	  properly balanced.
    //	* In attribute values and character data, unknown or malformed
    //	  character entities (sequences beginning with &) are left alone.
    //
    // Setting:
    //
    //	p.Strict = false;
    //	p.AutoClose = HTMLAutoClose;
    //	p.Entity = HTMLEntity
    //
    // creates a parser that can handle typical HTML.
    Strict bool

    // When Strict == false, AutoClose indicates a set of elements to
    // consider closed immediately after they are opened, regardless
    // of whether an end element is present.
    AutoClose []string

    // Entity can be used to map non-standard entity names to string replacements.
    // The parser behaves as if these standard mappings are present in the map,
    // regardless of the actual map content:
    //
    //	"lt": "<",
    //	"gt": ">",
    //	"amp": "&",
    //	"apos": "'",
    //	"quot": `"`,
    
    Entity map[string]string
    // contains unexported fields
}

NewParser関数

func NewParser(r io.Reader) *Parser

NewParserは、rからデータを読み込む新しいXMLパーサーを作成します。

(*Parser) RawToken関数

func (p *Parser) RawToken() (Token, os.Error)

RawTokenはTokenとほぼ同じですが、開始・終了要素が一致していることを確認せず、また名前空間プレフィックスを対応するURLに変換しません。

(*Parser) Skip関数

func (p *Parser) Skip() os.Error

開始要素をすでに読み込んでいるときに、終了要素を見つけるまでトークンを読み込みます。内部で呼び出しているToken関数では、読み込んだ開始要素と一致する終了要素がかならず見つかるように配慮して処理しています。

(*Parser) Token関数

func (p *Parser) Token() (t Token, err os.Error)

Tokenは、入力ストリーム内の次のXMLトークンを返します。入力ストリームの終わりに達すると、nil, os.EOFを返します。

トークンデータ内のバイトスライスは、パーサーの内部バッファを参照しており、これは次のTokenを呼び出すまでの間しか有効ではありません。バイトデータのコピーを取得するには、CopyTokenまたはトークンのCopyメソッドを呼び出してください。

Tokenは、<br/>のような空要素タグを開始要素と終了要素に分割し、一連の呼び出しで返します。

Tokenでは、StartElementトークンとEndElementトークンが正しくネストされ、かつ一致することが保証されます。予期しない終了要素が現れたときは、エラーを返します。

Tokenでは、http://www.w3.org/TR/REC-xml-names/で定義されているXML名前空間を実装しています。Token内のName構造体は、それぞれSpaceフィールドを持っており、そこに名前空間を識別するURLがセットされます。不明な名前空間のプレフィックスがあったときは、エラーを返すのではなく、代わりにそのプレフィックスをSpaceにセットします。

(*Parser) Unmarshal関数

func (p *Parser) Unmarshal(val interface{}, start *StartElement) os.Error

このパーサーのUnmarshalメソッドは、xml.Unmarshalとほぼ同じですが、先頭となる開始要素のポインタを渡す点が異なります。これは、クライアントが生のXMLトークンを読み込んだときに役立ちます。それ以外については、Unmarshalと同じです。開始要素にnilを指定したときは、トークンストリームから最初の要素を見つけ出します。

ProcInst型

ProcInstは、<?target inst?>形式のXML処理命令を表します。

type ProcInst struct {
    Target string
    Inst   []byte
}

(ProcInst) Copy関数

func (p ProcInst) Copy() ProcInst

StartElement型

StartElementは、XMLの開始要素を表します。

type StartElement struct {
    Name Name
    Attr []Attr
}

(StartElement) Copy関数

func (e StartElement) Copy() StartElement

SyntaxError型

SyntaxErrorは、XMLの入力ストリーム内の文法エラーを表します。

type SyntaxError struct {
    Msg  string
    Line int
}

(*SyntaxError) String関数

func (e *SyntaxError) String() string

Token型

Tokenは、次のいずれかのトークン型を格納するインタフェースです。StartElement、EndElement、CharData、Comment、ProcInst、Directive

type Token interface{}

CopyToken関数

func CopyToken(t Token) Token

CopyTokenは、トークンの複製を返します。

UnmarshalError型

UnmarshalErrorは、Unmarshal実行中のエラーを表します。

type UnmarshalError string

(UnmarshalError) String関数

func (e UnmarshalError) String() string

バグ

XML要素とデータ構造間のマッピングには、本質的な欠陥があります。XML要素は、匿名の値のコレクションであり、順序に意味があります。一方、データ構造は、名前を持つ値のコレクションであり、順序とは無関係です。これについては、データ構造で元データをより適切に扱っているjsonパッケージを参照ください。