...

パッケージ xml

import "encoding/xml"
概要
目次

概要 ▾

xml パッケージは XML 名前空間を理解するシンプルな XML 1.0 パーサを実装します。

例 (CustomMarshalXML)

コード:

package xml_test

import (
    "encoding/xml"
    "fmt"
    "log"
    "strings"
)

type Animal int

const (
    Unknown Animal = iota
    Gopher
    Zebra
)

func (a *Animal) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error {
    var s string
    if err := d.DecodeElement(&s, &start); err != nil {
        return err
    }
    switch strings.ToLower(s) {
    default:
        *a = Unknown
    case "gopher":
        *a = Gopher
    case "zebra":
        *a = Zebra
    }

    return nil
}

func (a Animal) MarshalXML(e *xml.Encoder, start xml.StartElement) error {
    var s string
    switch a {
    default:
        s = "unknown"
    case Gopher:
        s = "gopher"
    case Zebra:
        s = "zebra"
    }
    return e.EncodeElement(s, start)
}

func Example_customMarshalXML() {
    blob := `
    <animals>
        <animal>gopher</animal>
        <animal>armadillo</animal>
        <animal>zebra</animal>
        <animal>unknown</animal>
        <animal>gopher</animal>
        <animal>bee</animal>
        <animal>gopher</animal>
        <animal>zebra</animal>
    </animals>`
    var zoo struct {
        Animals []Animal `xml:"animal"`
    }
    if err := xml.Unmarshal([]byte(blob), &zoo); err != nil {
        log.Fatal(err)
    }

    census := make(map[Animal]int)
    for _, animal := range zoo.Animals {
        census[animal] += 1
    }

    fmt.Printf("Zoo Census:\n* Gophers: %d\n* Zebras:  %d\n* Unknown: %d\n",
        census[Gopher], census[Zebra], census[Unknown])

    // Output:
    // Zoo Census:
    // * Gophers: 3
    // * Zebras:  2
    // * Unknown: 3
}

例 (TextMarshalXML)

コード:

package xml_test

import (
    "encoding/xml"
    "fmt"
    "log"
    "strings"
)

type Size int

const (
    Unrecognized Size = iota
    Small
    Large
)

func (s *Size) UnmarshalText(text []byte) error {
    switch strings.ToLower(string(text)) {
    default:
        *s = Unrecognized
    case "small":
        *s = Small
    case "large":
        *s = Large
    }
    return nil
}

func (s Size) MarshalText() ([]byte, error) {
    var name string
    switch s {
    default:
        name = "unrecognized"
    case Small:
        name = "small"
    case Large:
        name = "large"
    }
    return []byte(name), nil
}

func Example_textMarshalXML() {
    blob := `
    <sizes>
        <size>small</size>
        <size>regular</size>
        <size>large</size>
        <size>unrecognized</size>
        <size>small</size>
        <size>normal</size>
        <size>small</size>
        <size>large</size>
    </sizes>`
    var inventory struct {
        Sizes []Size `xml:"size"`
    }
    if err := xml.Unmarshal([]byte(blob), &inventory); err != nil {
        log.Fatal(err)
    }

    counts := make(map[Size]int)
    for _, size := range inventory.Sizes {
        counts[size] += 1
    }

    fmt.Printf("Inventory Counts:\n* Small:        %d\n* Large:        %d\n* Unrecognized: %d\n",
        counts[Small], counts[Large], counts[Unrecognized])

    // Output:
    // Inventory Counts:
    // * Small:        3
    // * Large:        2
    // * Unrecognized: 3
}

目次 ▾

定数
変数
func Escape(w io.Writer, s []byte)
func EscapeText(w io.Writer, s []byte) error
func Marshal(v interface{}) ([]byte, error)
func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)
func Unmarshal(data []byte, v interface{}) error
type Attr
type CharData
    func (c CharData) Copy() CharData
type Comment
    func (c Comment) Copy() Comment
type Decoder
    func NewDecoder(r io.Reader) *Decoder
    func NewTokenDecoder(t TokenReader) *Decoder
    func (d *Decoder) Decode(v interface{}) error
    func (d *Decoder) DecodeElement(v interface{}, start *StartElement) error
    func (d *Decoder) InputOffset() int64
    func (d *Decoder) RawToken() (Token, error)
    func (d *Decoder) Skip() error
    func (d *Decoder) Token() (Token, error)
type Directive
    func (d Directive) Copy() Directive
type Encoder
    func NewEncoder(w io.Writer) *Encoder
    func (enc *Encoder) Encode(v interface{}) error
    func (enc *Encoder) EncodeElement(v interface{}, start StartElement) error
    func (enc *Encoder) EncodeToken(t Token) error
    func (enc *Encoder) Flush() error
    func (enc *Encoder) Indent(prefix, indent string)
type EndElement
type Marshaler
type MarshalerAttr
type Name
type ProcInst
    func (p ProcInst) Copy() ProcInst
type StartElement
    func (e StartElement) Copy() StartElement
    func (e StartElement) End() EndElement
type SyntaxError
    func (e *SyntaxError) Error() string
type TagPathError
    func (e *TagPathError) Error() string
type Token
    func CopyToken(t Token) Token
type TokenReader
type UnmarshalError
    func (e UnmarshalError) Error() string
type Unmarshaler
type UnmarshalerAttr
type UnsupportedTypeError
    func (e *UnsupportedTypeError) Error() string
Bugs

パッケージファイル

marshal.go read.go typeinfo.go xml.go

定数

const (
    // Header は, Marshal の出力とともに使用するのに適した汎用の XML ヘッダーです。
    // これは,このパッケージのどの出力にも自動的に追加されません。
    // 便宜上提供しています。
    Header = `<?xml version="1.0" encoding="UTF-8"?>` + "\n"
)

変数

HTMLAutoClose は,自動的に閉じると見なされるべき HTML 要素のセットです。

Decoder.Strict および Decoder.Entity フィールドのドキュメントを参照してください。

var HTMLAutoClose []string = htmlAutoClose

HTMLEntity は,標準の HTML エンティティ文字の変換を含むエンティティマップです。

Decoder.Strict および Decoder.Entity フィールドのドキュメントを参照してください。

var HTMLEntity map[string]string = htmlEntity

func Escape

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

Escape は EscapeText に似ていますが,エラー戻り値を省略します。 Go 1.0 との後方互換性のためにあります。 Go 1.1 以降をターゲットとするコードは EscapeText を使用する必要があります。

func EscapeText 1.1

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

EscapeText は,プレーンテキストデータ s に相当する,適切にエスケープされた XML を w に書き込みます。

func Marshal

func Marshal(v interface{}) ([]byte, error)

Marshal は v の XML エンコーディングを返します。

Marshal (整列化,マーシャリング) は,配列またはスライスの場合,各要素を整列化します。 Marshal は,ポインターの場合,ポインターが指す値を整列化します。 ポインターが nil の場合は,何も書き込みません。 Marshal は,インターフェース値の場合,インターフェースに含まれている値を整列化します。 インターフェース値が nil の場合は,何も記述しません。 Marshal は,他のデータの場合,そのデータを含む 1 つ以上の XML 要素を書き込みます。

XML 要素の名前は,優先順に次のものから取得されます。

- データが構造体の場合は XMLName フィールドのタグ
- 型 Name の XMLName フィールドの値
- データ取得に使われる構造体フィールドのタグ
- データ取得に使われる構造体フィールドの名前
- 整列化された型の名前

構造体の XML 要素には,構造体のエクスポートされたフィールドの整列化要素が含まれます。 ただし,次の例外があります。

- 上記の XMLName フィールドは省略されています。
- タグ "-" の付いたフィールドは省略されます。
- タグ "name,attr" を持つフィールドは, XML 要素内で名前 name の属性になります。
- タグ ",attr" を持つフィールドは, XML 要素内でフィールド名を持つ属性になります。
- タグ ",chardata" を持つフィールドは, XML 要素としてではなく,文字データとして書き込まれます。
- タグ ",cdata" を持つフィールドは, XML 要素としてではなく, 1 つ以上の <![CDATA[ ... ]]> タグで囲まれた文字データとして書かれます。
- タグ ",innerxml" を持つフィールドはそのまま書きこまれ,通常の整列化手順の対象ではありません。
- タグ ",comment" を持つフィールドは XML コメントとして書かれ,通常の整列化手順の対象ではありません。
  その中に "-" 文字列を含んではいけません。
- "omitempty" オプションを含むタグ付きフィールドは,フィールド値が空の場合は省略されます。
  空の値は false, 0, nil ポインタまたはインターフェース値,および長さゼロの配列,スライス,マップ,または文字列です。
- 無名構造体フィールドは,その値のフィールドが外側の構造体の一部であるかのように処理されます。
- Marshaler を実装するフィールドは,その MarshalXML メソッドを呼び出すことによって作成されます。
- encoding.TextMarshaler を実装するフィールドは,その MarshalText メソッドの結果をテキストとしてエンコードすることによって作成されます。

フィールドがタグ "a>b>c" を使用する場合,要素 c は親要素 a と b の内側にネストされます。 同じ親を示す,隣同士に表示されるフィールドは, 1 つの XML 要素で囲まれます。

構造体フィールドの XML 名が,フィールドタグと構造体の XMLName フィールドの両方で定義されている場合,名前は一致しなければなりません。

例として MarshalIndent を見てください。

チャンネル,関数,またはマップを整列化するようにリクエストされた場合, Marshal はエラーを返します。

func MarshalIndent

func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)

MarshalIndent は Marshal のように機能しますが,各 XML 要素は prefix で始まり,ネストの深さに応じて 1 つ以上の indent のコピーが続く,新しい行で始まります。

コード:

type Address struct {
    City, State string
}
type Person struct {
    XMLName   xml.Name `xml:"person"`
    Id        int      `xml:"id,attr"`
    FirstName string   `xml:"name>first"`
    LastName  string   `xml:"name>last"`
    Age       int      `xml:"age"`
    Height    float32  `xml:"height,omitempty"`
    Married   bool
    Address
    Comment string `xml:",comment"`
}

v := &Person{Id: 13, FirstName: "John", LastName: "Doe", Age: 42}
v.Comment = " Need more details. "
v.Address = Address{"Hanga Roa", "Easter Island"}

output, err := xml.MarshalIndent(v, "  ", "    ")
if err != nil {
    fmt.Printf("error: %v\n", err)
}

os.Stdout.Write(output)

出力:

  <person id="13">
      <name>
          <first>John</first>
          <last>Doe</last>
      </name>
      <age>42</age>
      <Married>false</Married>
      <City>Hanga Roa</City>
      <State>Easter Island</State>
      <!-- Need more details. -->
  </person>

func Unmarshal

func Unmarshal(data []byte, v interface{}) error

Unmarshal (非整列化) は XML エンコードデータを解析し,結果を v が指す値に格納します。 これは任意の構造体,スライス,または文字列でなければなりません。 v に収まらない整形式のデータは破棄されます。

Unmarshal はリフレクトパッケージを使用するため,エクスポートされた (大文字の) フィールドにしか割り当てることができません。 非整列化では,大文字と小文字を区別する比較を使用して, XML 要素名とタグ値および構造体フィールド名を照合します。

Unmarshal は,次の規則を使用して XML 要素を構造体にマップします。 規則では,フィールドのタグは,構造体フィールドのタグ内のキー 'xml' に関連付けられた値を参照します (上記の例を参照) 。

* 構造体が ",innerxml" タグの付いた []byte 型または文字列型のフィールドを持つ場合,
  Unmarshal はそのフィールドの要素内にネストされた生の XML を蓄積します。
  残りの規則も適用されます。

* 構造体に Name 型の XMLName という名前のフィールドがある場合,
  Unmarshal はそのフィールドに要素名を記録します。

* XMLName フィールドに "name" または "namespace-URL name"
  の形式の関連タグがある場合, XML 要素は指定の名前
  (およびオプションで名前空間) を持つ必要があります。
  そうでない場合, Unmarshal はエラーを返します。

* XML 要素の属性名が ",attr" タグを持つ構造体フィールド名または明示的な名前を含むタグ
  "name,attr" の名前と一致するならば,
  Unmarshal はそのフィールドの属性値を記録します。

* XML 要素が前の規則で扱われていない属性を持ち,
  構造体が ",any,attr" を含む関連タグを持つフィールドを持つ場合,
  Unmarshal はそのような最初のフィールドに属性値を記録します。

* XML 要素に文字データが含まれる場合,そのデータはタグ ",chardata"
  を持つ最初の構造体フィールドに蓄積されます。
  その構造体フィールドは []byte 型または string 型を持つことができます。
  そのようなフィールドがない場合は,文字データは破棄されます。

* XML 要素にコメントが含まれる場合,それらはタグ ",comment"
  を持つ最初の構造体フィールドに蓄積されます。
  構造体フィールドは []byte 型または string 型を持つことができます。
  そのようなフィールドがない場合,コメントは破棄されます。

* "a" または "a>b>c" の形式のタグの接頭辞とXML 要素に含まれているサブ要素の名前が一致する場合,
  Unmarshal は指定された名前の要素を探して XML 構造に降りて,
  その構造体フィールドの最も内側の要素にマッピングします。
  ">" で始まるタグは,フィールド名の後に ">" が続くタグと同じです。

* XML 要素に,構造体フィールドの XMLName タグと名前が一致するサブ要素が含まれていて,
  その構造体フィールドに上記の規則のような明示的な名前タグがない場合は,
  Unmarshal はそのサブ要素をその構造体フィールドにマップします。

* XML 要素に,モードフラグ (",attr", ",chardata" など)
  のないフィールドと名前が一致するサブ要素が含まれる場合,
  Unmarshal はそのサブ要素をその構造体フィールドにマップします。

* XML 要素に上記の規則のいずれにも一致しないサブ要素が含まれ,
  構造体にタグ ",any" を持つフィールドがある場合,
  Unmarshal はサブ要素をその構造体フィールドにマップします。

* 無名構造体フィールドは,その値のフィールドが外側の構造体の一部であるかのように扱われます。

* タグ "-" を持つ構造体フィールドが非整列化されることはありません。

Unmarshal が Unmarshaler インターフェースを実装するフィールド型に遭遇すると, Unmarshal はその UnmarshalXML メソッドを呼び出して XML 要素から値を生成します。 そうではなく,値が encoding.TextUnmarshaler を実装している場合, Unmarshal はその値の UnmarshalText メソッドを呼び出します。

Unmarshal は, XML 要素を文字列または []byte に,その要素の文字データの連結を保存することによってマッピングします。 保存された []byte は決して nil ではありません。

Unmarshal は,値を文字列またはスライスに保存することによって,属性値を文字列または []byte にマップします。

Unmarshal は,名前を含む属性を Attr に保存することによって属性値を Attr にマッピングします。

Unmarshal は,スライスの長さを拡張し,要素または属性を新しく作成された値にマッピングすることによって, XML 要素または属性値をスライスにマッピングします。

Unmarshal は, XML 要素または属性値を,文字列で表されるブール値に設定することによってブール値にマッピングします。 空白は切り捨てられて無視されます。

Unmarshal は,文字列値を 10 進数で解釈した結果にフィールドを設定することによって, XML 要素または属性値を整数フィールドまたは浮動小数点フィールドにマップします。 オーバーフローのチェックはありません。 空白は切り捨てられて無視されます。

Unmarshal は,要素名を記録することによって XML 要素を Name にマッピングします。

Unmarshal ルは,ポインタを新たに割り当てられた値に設定してから要素をその値にマッピングすることによって, XML 要素をポインタにマッピングします。

欠けている要素または空の属性値は,ゼロ値として非整列化されます。 フィールドがスライスの場合,ゼロ値がフィールドに追加されます。 それ以外の場合,フィールドはそのゼロ値に設定されます。

この例では, XML の抜粋をいくつかの事前設定フィールドを持つ値に非整列化する方法を示します。 Phone フィールドは変更されず, XML の <Company> 要素は無視されます。 また, Groups フィールドは,そのタグに指定されている要素パスを考慮して割り当てられます。

コード:

type Email struct {
    Where string `xml:"where,attr"`
    Addr  string
}
type Address struct {
    City, State string
}
type Result struct {
    XMLName xml.Name `xml:"Person"`
    Name    string   `xml:"FullName"`
    Phone   string
    Email   []Email
    Groups  []string `xml:"Group>Value"`
    Address
}
v := Result{Name: "none", Phone: "none"}

data := `
        <Person>
            <FullName>Grace R. Emlin</FullName>
            <Company>Example Inc.</Company>
            <Email where="home">
                <Addr>gre@example.com</Addr>
            </Email>
            <Email where='work'>
                <Addr>gre@work.com</Addr>
            </Email>
            <Group>
                <Value>Friends</Value>
                <Value>Squash</Value>
            </Group>
            <City>Hanga Roa</City>
            <State>Easter Island</State>
        </Person>
    `
err := xml.Unmarshal([]byte(data), &v)
if err != nil {
    fmt.Printf("error: %v", err)
    return
}
fmt.Printf("XMLName: %#v\n", v.XMLName)
fmt.Printf("Name: %q\n", v.Name)
fmt.Printf("Phone: %q\n", v.Phone)
fmt.Printf("Email: %v\n", v.Email)
fmt.Printf("Groups: %v\n", v.Groups)
fmt.Printf("Address: %v\n", v.Address)

出力:

XMLName: xml.Name{Space:"", Local:"Person"}
Name: "Grace R. Emlin"
Phone: "none"
Email: [{home gre@example.com} {work gre@work.com}]
Groups: [Friends Squash]
Address: {Hanga Roa Easter Island}

type Attr

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

type Attr struct {
    Name  Name
    Value string
}

type CharData

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

type CharData []byte

func (CharData) Copy

func (c CharData) Copy() CharData

Copy は CharData の新しいコピーを作成します。

type Comment

Comment は <!--comment--> の形式の XML コメントを表します。 バイトには, <!-- と --> のコメントマーカーは含まれません。

type Comment []byte

func (Comment) Copy

func (c Comment) Copy() Comment

Copy はコメントの新しいコピーを作成します。

type Decoder

Decoder は特定の入力ストリームを読み込む XML パーサを表します。 パーサは,その入力が UTF-8 でエンコードされていると想定します。

type Decoder struct {
    // Strict (厳密) は,デフォルトでは true で, XML 仕様の要件を強制します。
    // false に設定すると,パーサは一般的な間違いを含む入力を許可します。
    //	* 要素に終端タグがない場合,パーサは終端タグを必要に応じて付け足して,
    //	  Token が適切にバランスするようにします。
    //	* 属性値と文字データにおいて,不明な,あるいは間違った文字エンティティ (& で始まるシーケンス)
    //	  はそのままになります。
    //
    // 設定:
    //
    //	d.Strict = false
    //	d.AutoClose = xml.HTMLAutoClose
    //	d.Entity = xml.HTMLEntity
    //
    // は,典型的な HTML を処理できるパーサを作成します。
    //
    // Strict モードでは, XML 名前空間 TR の要件は強制されません。
    // 特に,未定義の接頭辞を使った名前空間タグを拒否することはありません。
    // このようなタグは,名前空間の URL として不明な接頭辞を付けて記録されます。
    Strict bool

    // Strict == false の場合, AutoClose は,終了要素が存在するかどうかにかかわらず,開いた直後に閉じると見なす要素の集合です。
    AutoClose []string

    // Entity は,非標準のエンティティ名を文字列の置き換えにマッピングするために使用できます。
    // 実際のマップの内容に関係なく,パーサは以下の標準マッピングがマップに存在するかのように動作します。
    //
    //	"lt": "<",
    //	"gt": ">",
    //	"amp": "&",
    //	"apos": "'",
    //	"quot": `"`,
    Entity map[string]string

    // CharsetReader が nil 以外の場合は,渡されている非 UTF-8 文字セットから UTF-8 に変換して,文字セット変換リーダーを生成する関数を定義します。
    // CharsetReader が nil であるかエラーを返した場合,解析はエラーで停止します。
    // CharsetReader の結果値の 1 つは, nil 以外でなければなりません。
    CharsetReader func(charset string, input io.Reader) (io.Reader, error)

    // DefaultSpace は, XML ストリーム全体が属性 xmlns="DefaultSpace" を含む要素でラップされている場合と同様に,未分類のタグに使用されるデフォルトの名前空間を設定します。
    DefaultSpace string // Go 1.1
    // エクスポートされていないフィールドがあります
}

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder は, r から読み取る新しい XML パーサを作成します。 r が io.ByteReader を実装していない場合, NewDecoder は独自のバッファリングを行います。

func NewTokenDecoder 1.10

func NewTokenDecoder(t TokenReader) *Decoder

NewTokenDecoder は,内部のトークンストリームを使用して新しい XML パーサを作成します。

func (*Decoder) Decode

func (d *Decoder) Decode(v interface{}) error

Decode は,開始要素を見つけるためにデコーダストリームを読み取ることを除いて,非整列化のように機能します。

func (*Decoder) DecodeElement

func (d *Decoder) DecodeElement(v interface{}, start *StartElement) error

DecodeElement は,開始 XML 要素を指すポインターを使用して v にデコードすることを除けば, Unmarshal と同様に機能します。 クライアントが生の XML トークン自体を読み取るだけでなく,一部の要素について Unmarshal を延期する場合にも役立ちます。

func (*Decoder) InputOffset 1.4

func (d *Decoder) InputOffset() int64

InputOffset は,現在のデコーダ位置の入力ストリームのバイトオフセットを返します。 オフセットは,最後に返されたトークンの終わりと次のトークンの始まりの位置を示します。

func (*Decoder) RawToken

func (d *Decoder) RawToken() (Token, error)

RawToken は Token に似ていますが,開始要素と終了要素が一致していることを確認したり,名前空間プレフィックスを対応する URL に変換したりすることはありません。

func (*Decoder) Skip

func (d *Decoder) Skip() error

Skip は,すでに消費された最新の開始要素と一致する終了要素を消費するまでトークンを読み取ります。 開始要素に遭遇した場合は再帰するので,ネストされた構造をスキップするために使用できます。 開始要素と一致する終了要素が見つかった場合は nil を返します。 それ以外の場合は,問題を説明するエラーを返します。

func (*Decoder) Token

func (d *Decoder) Token() (Token, error)

トークンは,入力ストリーム内の次の XML トークンを返します。 入力ストリームの終わりで, Token は nil, io.EOF を返します。

返されたトークンデータのバイトスライスは,パーサの内部バッファを参照し,次の Token の呼び出しまでのみ有効です。 バイトのコピーを取得するには, CopyToken またはトークンの Copy メソッドを呼び出します。

Token は, <br/> のような自己終了要素を,連続した呼び出しによって返される別々の開始要素と終了要素に拡張します。

Token は,返される StartElement と EndElement トークンが適切にネストされ,一致していることを保証します。 トークンが予期されるすべての終了要素の前に予期しない終了要素または EOF を検出すると,エラーを返します。

Token は https://www.w3.org/TR/REC-xml-names/ で説明されているように XML 名前空間を実装します。 Token に含まれている各 Name 構造体の Space は,既知の場合にそのネームスペースを識別する URL に設定されています。 Token が認識できないネームスペースプレフィックスを検出した場合,エラーを報告するのではなく,プレフィックスを Space として使用します。

type Directive

Directive は, <!text> という形式の XML ディレクティブを表します。 バイトには <! と > は含まれません。

type Directive []byte

func (Directive) Copy

func (d Directive) Copy() Directive

Copy は Directive の新しいコピーを作成します。

type Encoder

Encoder (エンコーダ) は XML データを出力ストリームに書き込みます。

type Encoder struct {
    // エクスポートされていないフィールドがあります
}

コード:

type Address struct {
    City, State string
}
type Person struct {
    XMLName   xml.Name `xml:"person"`
    Id        int      `xml:"id,attr"`
    FirstName string   `xml:"name>first"`
    LastName  string   `xml:"name>last"`
    Age       int      `xml:"age"`
    Height    float32  `xml:"height,omitempty"`
    Married   bool
    Address
    Comment string `xml:",comment"`
}

v := &Person{Id: 13, FirstName: "John", LastName: "Doe", Age: 42}
v.Comment = " Need more details. "
v.Address = Address{"Hanga Roa", "Easter Island"}

enc := xml.NewEncoder(os.Stdout)
enc.Indent("  ", "    ")
if err := enc.Encode(v); err != nil {
    fmt.Printf("error: %v\n", err)
}

出力:

  <person id="13">
      <name>
          <first>John</first>
          <last>Doe</last>
      </name>
      <age>42</age>
      <Married>false</Married>
      <City>Hanga Roa</City>
      <State>Easter Island</State>
      <!-- Need more details. -->
  </person>

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder は, w に書き込む新しいエンコーダを返します。

func (*Encoder) Encode

func (enc *Encoder) Encode(v interface{}) error

Encode は v の XML エンコードをストリームに書き込みます。

Go 値の XML への変換について詳しくは, Marshal のドキュメントを参照してください。

Encode は戻る前に Flush を呼び出します。

func (*Encoder) EncodeElement 1.2

func (enc *Encoder) EncodeElement(v interface{}, start StartElement) error

EncodeElement は, start をエンコーディングの最も外側のタグとして使用して, v の XML エンコーディングをストリームに書き込みます。

Go 値の XML への変換について詳しくは, Marshal のドキュメントを参照してください。

EncodeElement は戻る前に Flush を呼び出します。

func (*Encoder) EncodeToken 1.2

func (enc *Encoder) EncodeToken(t Token) error

EncodeToken は与えられた XML トークンをストリームに書き込みます。 StartElement トークンと EndElement トークンが正しく一致していない場合はエラーを返します。

EncodeToken は Flush を呼び出しません。 通常, Encode や EncodeElement (またはそれらの間に呼び出されるカスタム Marshaler の MarshalXML) などの大規模な操作の一部であり,終了時に Flush を呼び出すためです。 Encoder を作成し, Encode または EncodeElement を使用せずに直接 EncodeToken を呼び出す呼び出し側は, XML が内部の書き込み側に確実に書き込まれるように,終了時に Flush を呼び出す必要があります。

EncodeToken では,ストリームの最初のトークンとしてのみ, Target を "xml" に設定して ProcInst を書き込むことができます。

func (*Encoder) Flush 1.2

func (enc *Encoder) Flush() error

Flush はバッファリングされた XML を内部のライターにフラッシュします。 必要な場合の詳細については, EncodeToken のドキュメントを参照してください。

func (*Encoder) Indent 1.1

func (enc *Encoder) Indent(prefix, indent string)

Indent は,各要素が prefix で始まり,ネストの深さに応じて 1 つ以上の indent のコピーが続く,新しい行で始まる XML を生成するようにエンコーダを設定します。

type EndElement

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

type EndElement struct {
    Name Name
}

type Marshaler 1.2

Marshaler は,有効な XML 要素に自分自身を整列させることができるオブジェクトが実装するインターフェースです。

MarshalXML は,レシーバを 0 個以上の XML 要素としてエンコードします。 慣例により,配列またはスライスは通常,エントリごとに 1 つずつ,一連​​の要素としてエンコードされます。 要素タグとして start を使用することは必須ではありませんが,そうすることで Unmarshal が XML 要素を正しい構造体フィールドと一致させることができます。 一般的な実装方法の 1 つは,目的の XML に対応するレイアウトで個別の値を作成してから, e.EncodeElement でエンコードすることです。 もう 1 つの一般的な方法は, e.EncodeToken を繰り返し呼び出して,一度に 1 トークンずつ XML 出力を生成することです。 エンコードされたトークンのシーケンスは,ゼロ個以上の有効な XML 要素を構成する必要があります。

type Marshaler interface {
    MarshalXML(e *Encoder, start StartElement) error
}

type MarshalerAttr 1.2

MarshalerAttr は,有効な XML 属性に変換できるオブジェクトが実装するインターフェースです。

MarshalXMLAttr は,レシーバ受信側のエンコードされた値がセットされた XML 属性を返します。 属性名として name を使用することは必須ではありませんが,そうすることで Unmarshal が属性を正しい構造体フィールドに一致させることができます。 MarshalXMLAttr がゼロ属性 Attr{} を返す場合,出力には属性は生成されません。 MarshalXMLAttr は,フィールドタグに "attr" オプションがある構造体フィールドに対してのみ使用されます。

type MarshalerAttr interface {
    MarshalXMLAttr(name Name) (Attr, error)
}

type Name

Name は,ネームスペース識別子 (Space) でアノテーションがつけられた XML 名 (Local) を表します。 Decoder.Token によって返されるトークンでは,スペース識別子は解析される文書で使用される短いプレフィックスではなく, 正規の URL として与えられます。

type Name struct {
    Space, Local string
}

type ProcInst

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

type ProcInst struct {
    Target string
    Inst   []byte
}

func (ProcInst) Copy

func (p ProcInst) Copy() ProcInst

Copy は ProcInst の新しいコピーを作成します。

type StartElement

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

type StartElement struct {
    Name Name
    Attr []Attr
}

func (StartElement) Copy

func (e StartElement) Copy() StartElement

Copy は StartElement の新しいコピーを作成します。

func (StartElement) End 1.2

func (e StartElement) End() EndElement

End は対応する XML 終了要素を返します。

type SyntaxError

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

type SyntaxError struct {
    Msg  string
    Line int
}

func (*SyntaxError) Error

func (e *SyntaxError) Error() string

type TagPathError

TagPathError は,競合するパスを持つフィールドタグの使用によって引き起こされた非整列化プロセスでのエラーを表します。

type TagPathError struct {
    Struct       reflect.Type
    Field1, Tag1 string
    Field2, Tag2 string
}

func (*TagPathError) Error

func (e *TagPathError) Error() string

type Token

Token は, StartElement, EndElement, CharData, Comment, ProcInst, または Directive のいずれかのトークン型を保持するインターフェースです。

type Token interface{}

func CopyToken

func CopyToken(t Token) Token

CopyToken はトークンのコピーを返します。

type TokenReader 1.10

TokenReader は, Decoder など, XML トークンのストリームをデコードできるものを表します。

トークンが正常に読み取られた後に, Token でエラー発生またはファイルの終わりとなると,そのトークンを返します。 同じ呼び出しから (nil 以外の) エラーを返すか,後続の呼び出しからエラー (および nil トークン) を返すことがあります。 この一般的例として,トークンストリームの最後に TokenReader が, nil でないトークンとともに io.EOF または nil エラーを返す可能性があります。 次の Read では nil, io.EOF を返すはずです。

Token の実装は nil エラーで nil トークンを返すことを推奨しません。 呼び出し側は,何も起こらなかったことを示すものとして nil, nil の戻りを扱うべきです。 これは, EOF を示すものではありません。

type TokenReader interface {
    Token() (Token, error)
}

type UnmarshalError

UnmarshalError は,非整列化プロセスでのエラーを表します。

type UnmarshalError string

func (UnmarshalError) Error

func (e UnmarshalError) Error() string

type Unmarshaler 1.2

Unmarshaler は,自分自身の XML 要素の記述を非整列化できるオブジェクトが実装するインターフェースです。

UnmarshalXML は,指定された開始要素で始まる 1 つの XML 要素をデコードします。 エラーが返されると, Unmarshal への外部呼び出しは停止してそのエラーを返します。 UnmarshalXML は厳密に 1 つの XML 要素を消費する必要があります。 一般的な実装方法の 1 つは, d.DecodeElement を使用して,予想される XML と一致するレイアウトを使用して別の値にアンマーシャリングし,その値からデータをレシーバにコピーすることです。 もう 1 つの一般的な方法は, d.Token を使用して XML オブジェクトを一度に 1 トークンずつ処理することです。 UnmarshalXML は d.RawToken を使用できません。

type Unmarshaler interface {
    UnmarshalXML(d *Decoder, start StartElement) error
}

type UnmarshalerAttr 1.2

UnmarshalerAttr は,自分自身の XML 属性記述を非整列化できるオブジェクトが実装するインターフェースです。

UnmarshalXMLAttr は 1 つの XML 属性をデコードします。 エラーが返されると, Unmarshal への外部呼び出しは停止してそのエラーを返します。 UnmarshalXMLAttr は,フィールドタグに "attr" オプションがある構造体フィールドに対してのみ使用されます。

type UnmarshalerAttr interface {
    UnmarshalXMLAttr(attr Attr) error
}

type UnsupportedTypeError

UnsupportedTypeError は,Marshal が XML に変換できない型を見つけると返されます。

type UnsupportedTypeError struct {
    Type reflect.Type
}

func (*UnsupportedTypeError) Error

func (e *UnsupportedTypeError) Error() string

Bugs