package xml
import "encoding/xml"
Package xml 实现了一个简单的 XML 1.0 解析器,
它能理解 XML 命名空间。
Output: Output:Example (CustomMarshalXML)
package main
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 main() {
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])
}
Zoo Census:
* Gophers: 3
* Zebras: 2
* Unknown: 3
Example (TextMarshalXML)
package main
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 main() {
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])
}
Inventory Counts:
* Small: 3
* Large: 2
* Unrecognized: 3
Index
- Constants
- Variables
- func Escape(w io.Writer, s []byte)
- func EscapeText(w io.Writer, s []byte) error
- func Marshal(v any) ([]byte, error)
- func MarshalIndent(v any, prefix, indent string) ([]byte, error)
- func Unmarshal(data []byte, v any) error
- type Attr
- type CharData
- type Comment
-
type Decoder
- func NewDecoder(r io.Reader) *Decoder
- func NewTokenDecoder(t TokenReader) *Decoder
- func (d *Decoder) Decode(v any) error
- func (d *Decoder) DecodeElement(v any, start *StartElement) error
- func (d *Decoder) InputOffset() int64
- func (d *Decoder) InputPos() (line, column int)
- func (d *Decoder) RawToken() (Token, error)
- func (d *Decoder) Skip() error
- func (d *Decoder) Token() (Token, error)
- type Directive
-
type Encoder
- func NewEncoder(w io.Writer) *Encoder
- func (enc *Encoder) Close() error
- func (enc *Encoder) Encode(v any) error
- func (enc *Encoder) EncodeElement(v any, 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
- type StartElement
- type SyntaxError
- type TagPathError
- type Token
- type TokenReader
- type UnmarshalError
- type Unmarshaler
- type UnmarshalerAttr
- type UnsupportedTypeError
Examples
Constants
const ( // Header 是一个通用的 XML 头部,适合与 [Marshal] 的输出一起使用。 // 它不会被自动添加到本包的任何输出中, // 此处只是作为一个便利提供。 Header = `<?xml version="1.0" encoding="UTF-8"?>` + "\n" )
Variables
var HTMLAutoClose []string = htmlAutoClose
HTMLAutoClose 是一组 HTML 元素, 它们应被视为自动关闭。
参见 Decoder.Strict 和 Decoder.Entity 字段的文档。
var HTMLEntity map[string]string = htmlEntity
HTMLEntity 是一个实体映射,包含标准 HTML 实体字符的 翻译。
参见 Decoder.Strict 和 Decoder.Entity 字段的文档。
Functions
func Escape
func Escape(w io.Writer, s []byte)
Escape 类似 EscapeText,但省略错误返回值。 提供它是为了与 Go 1.0 向后兼容。 面向 Go 1.1 及更高版本的代码应使用 EscapeText。
func EscapeText
func EscapeText(w io.Writer, s []byte) error
EscapeText 将纯文本数据 s 的正确转义后的 XML 等价形式 写入 w。
func Marshal
func Marshal(v any) ([]byte, error)
Marshal 返回 v 的 XML 编码。
Marshal 处理数组或切片的方式是封送其中的每个元素。 Marshal 处理指针的方式是封送它所指向的值,或者如果 指针为 nil,则不写入任何内容。Marshal 处理接口值的方式是 封送其中包含的值,或者如果接口值为 nil,则不写入任何内容。 Marshal 处理所有其他数据的方式是写入一个或多个包含该数据的 XML 元素。
XML 元素的名称按优先顺序取自:
- 若数据是结构体,则取自 XMLName 字段上的标签
- 类型为 Name 的 XMLName 字段的值
- 用于获取数据的结构体字段的标签
- 用于获取数据的结构体字段的名称
- 被封送类型的名称
结构体的 XML 元素包含该结构体每个导出字段的封送元素, 但有以下例外:
- 上述的 XMLName 字段会被省略。
- 标签为 "-" 的字段会被省略。
- 标签为 "name,attr" 的字段在 XML 元素中成为具有 给定名称的属性。
- 标签为 ",attr" 的字段在 XML 元素中成为具有 字段名的属性。
- 标签为 ",chardata" 的字段被写为字符数据, 而不是 XML 元素。
- 标签为 ",cdata" 的字段被写为包裹在一个或多个 <![CDATA[ ... ]]> 标签中的字符数据,而不是 XML 元素。
- 标签为 ",innerxml" 的字段被原样写入,不经过 通常的封送过程。
- 标签为 ",comment" 的字段被写为 XML 注释,不经过 通常的封送过程。它内部不得包含 "--" 字符串。
- 标签中包含 "omitempty" 选项的字段,若字段值为空则 被省略。空值包括 false、0、任何 nil 指针或接口值,以及任何长度为零的数组、切片、map 或 字符串。
- 匿名结构体字段的处理方式如同其值的字段是外层结构体的一部分。
- 接口类型的匿名结构体字段被视为以该类型作为其名称, 而不是匿名。
- 实现了 Marshaler 的字段通过调用其 MarshalXML 方法来写入。
- 实现了 encoding.TextMarshaler 的字段通过将其 MarshalText 方法 的结果编码为文本来写入。
如果字段使用标签 "a>b>c",则元素 c 将嵌套在 父元素 a 和 b 中。相邻出现且名称相同的父元素 字段会被包含在同一个 XML 元素中。
如果结构体字段的 XML 名称同时由字段标签和 结构体的 XMLName 字段定义,则名称必须匹配。
示例参见 MarshalIndent。
如果要求 Marshal 封送 channel、函数或 map,它会返回一个错误。
func MarshalIndent
func MarshalIndent(v any, prefix, indent string) ([]byte, error)
MarshalIndent 的工作方式与 Marshal 类似,但每个 XML 元素都从
新的一行开始,该行以 prefix 开头,并根据嵌套深度
后跟一个或多个 indent 的副本。
Output:Example
package main
import (
"encoding/xml"
"fmt"
"os"
)
func main() {
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 any) error
Unmarshal 解析 XML 编码的数据,并将结果存储到 v 指向的值中, v 必须是任意的结构体、切片或字符串。格式良好但不适合放入 v 的 数据会被丢弃。
由于 Unmarshal 使用 reflect 包,它只能赋值给导出(首字母大写)的 字段。Unmarshal 使用区分大小写的比较,将 XML 元素名称与标签值 和结构体字段名进行匹配。
Unmarshal 使用以下规则将 XML 元素映射到结构体。 在这些规则中,字段的标签指的是结构体字段标签中键 'xml' 关联的值(见上方的示例)。
如果结构体有一个类型为 []byte 或 string、标签为 ",innerxml" 的字段,Unmarshal 会把嵌套在该元素内的原始 XML 累积到该字段中。其余规则仍然适用。
如果结构体有一个名为 XMLName、类型为 Name 的字段, 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。如果没有这样的字段,注释会被丢弃。
如果 XML 元素包含一个子元素,其名称与形如 "a" 或 "a>b>c" 的标签 前缀匹配,unmarshal 会深入 XML 结构查找具有给定名称的元素, 并将最内层的元素映射到该结构体字段。以 ">" 开头的标签等价于 以字段名后跟 ">" 开头的标签。
如果 XML 元素包含一个子元素,其名称与某个结构体字段的 XMLName 标签匹配,且该结构体字段没有按照上一条规则显式给出名称标签, unmarshal 会把该子元素映射到该结构体字段。
如果 XML 元素包含一个子元素,其名称与某个没有任何模式标志 (",attr"、",chardata" 等)的字段匹配,Unmarshal 会把该子元素 映射到该结构体字段。
如果 XML 元素包含一个子元素,它未匹配以上任何规则,并且结构体 有一个标签为 ",any" 的字段,unmarshal 会把该子元素映射到该 结构体字段。
匿名结构体字段的处理方式如同其值的字段是外层结构体的一部分。
标签为 "-" 的结构体字段永远不会被反封送。
如果 Unmarshal 遇到实现了 Unmarshaler 接口的字段类型,Unmarshal 会调用 其 UnmarshalXML 方法从 XML 元素生成值。否则,如果该值实现了 encoding.TextUnmarshaler,Unmarshal 会调用该值的 UnmarshalText 方法。
Unmarshal 通过将该元素字符数据的拼接结果保存到 string 或 []byte, 从而将 XML 元素映射到 string 或 []byte。保存的 []byte 永远不会为 nil。
Unmarshal 通过将值保存到 string 或切片中,从而将属性值映射到 string 或 []byte。
Unmarshal 通过将属性(包括其名称)保存到 Attr,从而将属性值映射到 Attr。
Unmarshal 通过扩展切片的长度并将元素或属性映射到新创建的值, 从而将 XML 元素或属性值映射到切片。
Unmarshal 通过将值设为字符串所表示的布尔值,从而将 XML 元素或 属性值映射到 bool。空白会被去除并忽略。
Unmarshal 通过将字段设为按十进制解释字符串值的结果,从而将 XML 元素或 属性值映射到整数或浮点字段。不检查溢出。空白会被去除并忽略。
Unmarshal 通过记录元素名称,从而将 XML 元素映射到 Name。
Unmarshal 通过将指针设为新分配的值、然后将元素映射到该值, 从而将 XML 元素映射到指针。
缺失的元素或空属性值会被反封送为零值。
如果该字段是切片,则会将零值追加到该字段。否则,该字段
会被设为其零值。
This example demonstrates unmarshaling an XML excerpt into a value with
some preset fields. Note that the Phone field isn't modified and that
the XML <Company> element is ignored. Also, the Groups field is assigned
considering the element path provided in its tag.
Output:Example
package main
import (
"encoding/xml"
"fmt"
)
func main() {
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}
Types
type Attr
type Attr struct { Name Name Value string }
Attr 表示 XML 元素中的一个属性(Name=Value)。
type CharData
type CharData []byte
CharData 表示 XML 字符数据(原始文本), 其中的 XML 转义序列已被替换为 它们所代表的字符。
func (CharData) Copy
func (c CharData) Copy() CharData
Copy 创建 CharData 的新副本。
type Comment
type Comment []byte
Comment 表示形如 <!--comment--> 的 XML 注释。 其字节内容不包含 <!-- 和 --> 注释标记。
func (Comment) Copy
func (c Comment) Copy() Comment
Copy 创建 Comment 的新副本。
type Decoder
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 可用于将非标准实体名称映射到字符串替换。 // 无论该 map 的实际内容如何,解析器的行为都如同 // 这些标准映射存在于 map 中: // // "lt": "<", // "gt": ">", // "amp": "&", // "apos": "'", // "quot": `"`, Entity map[string]string // CharsetReader 若为非 nil,则定义一个函数来生成 // 字符集转换读取器,将提供的非 UTF-8 字符集 // 转换为 UTF-8。如果 CharsetReader 为 nil 或 // 返回错误,解析会以错误停止。CharsetReader 的 // 结果值之一必须为非 nil。 CharsetReader func(charset string, input io.Reader) (io.Reader, error) // DefaultSpace 设置用于无修饰标签的默认命名空间, // 就如同整个 XML 流被包裹在一个包含 // 属性 xmlns="DefaultSpace" 的元素中一样。 DefaultSpace string // contains filtered or unexported fields }
Decoder 表示一个读取特定输入流的 XML 解析器。 该解析器假定其输入以 UTF-8 编码。
func NewDecoder
func NewDecoder(r io.Reader) *Decoder
NewDecoder 创建一个从 r 读取的新的 XML 解析器。 如果 r 未实现 io.ByteReader,NewDecoder 将 自行进行缓冲。
func NewTokenDecoder
func NewTokenDecoder(t TokenReader) *Decoder
NewTokenDecoder 使用底层 token 流创建一个新的 XML 解析器。
func (*Decoder) Decode
func (d *Decoder) Decode(v any) error
Decode 的工作方式与 Unmarshal 类似,不同之处在于它读取解码器 流以找到起始元素。
func (*Decoder) DecodeElement
func (d *Decoder) DecodeElement(v any, start *StartElement) error
DecodeElement 的工作方式与 Unmarshal 类似,不同之处在于它接收 一个指向起始 XML 元素的指针,用于解码到 v。 当客户端自己读取了一些原始 XML token,但又希望将某些元素 交由 Unmarshal 处理时,它会很有用。
func (*Decoder) InputOffset
func (d *Decoder) InputOffset() int64
InputOffset 返回当前解码器位置在输入流中的字节偏移量。 该偏移量给出最近返回的 token 的结尾 以及下一个 token 的开头的位置。
func (*Decoder) InputPos
func (d *Decoder) InputPos() (line, column int)
InputPos 返回当前解码器位置所在的行以及该行内从 1 开始的 输入位置。该位置给出最近返回的 token 的结尾位置。
func (*Decoder) RawToken
func (d *Decoder) RawToken() (Token, error)
RawToken 类似 Decoder.Token,但不验证 起始和结束元素是否匹配,也不将 命名空间前缀翻译为它们对应的 URL。
func (*Decoder) Skip
func (d *Decoder) Skip() error
Skip 读取 token,直到它消费了与最近已消费的起始元素相匹配的 结束元素,跳过嵌套结构。 如果它找到与起始元素匹配的结束元素,则返回 nil; 否则返回一个描述问题的错误。
func (*Decoder) Token
func (d *Decoder) Token() (Token, error)
Token 返回输入流中的下一个 XML token。 在输入流末尾,Token 返回 nil、io.EOF。
返回的 token 数据中的字节切片引用解析器的 内部缓冲区,仅在下一次调用 Token 之前有效。 若要获取字节的副本,请调用 CopyToken 或该 token 的 Copy 方法。
Token 会将诸如 <br> 这样的自闭合元素 展开为通过连续调用返回的独立起始和结束元素。
Token 保证它返回的 StartElement 和 EndElement token 正确嵌套且配对:如果 Token 在所有预期的结束元素 之前遇到意外的结束元素或 EOF,它将返回一个错误。
如果调用了 Decoder.CharsetReader 并返回错误, 该错误会被包装并返回。
Token 按 https://www.w3.org/TR/REC-xml-names/ 所述 实现 XML 命名空间。Token 中包含的每个 Name 结构在已知时都会将 Space 设置为标识其命名空间的 URL。 如果 Token 遇到无法识别的命名空间前缀, 它会使用该前缀作为 Space,而不是报告错误。
type Directive
type Directive []byte
Directive 表示形如 <!text> 的 XML 指令。 其字节内容不包含 <! 和 > 标记。
func (Directive) Copy
func (d Directive) Copy() Directive
Copy 创建 Directive 的新副本。
type Encoder
type Encoder struct { // contains filtered or unexported fields }
Encoder 将 XML 数据写入输出流。
Output:Example
package main
import (
"encoding/xml"
"fmt"
"os"
)
func main() {
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) Close
func (enc *Encoder) Close() error
Close 关闭 Encoder,表明不再写入任何数据。它会将 任何已缓冲的 XML 刷新到底层写入器,并在 写入的 XML 无效(例如包含未闭合的元素)时返回错误。
func (*Encoder) Encode
func (enc *Encoder) Encode(v any) error
Encode 将 v 的 XML 编码写入流。
关于 Go 值到 XML 的转换细节,参见 Marshal 的文档。
Encode 在返回前会调用 Encoder.Flush。
func (*Encoder) EncodeElement
func (enc *Encoder) EncodeElement(v any, start StartElement) error
EncodeElement 将 v 的 XML 编码写入流, 使用 start 作为编码中最外层的标签。
关于 Go 值到 XML 的转换细节,参见 Marshal 的文档。
EncodeElement 在返回前会调用 Encoder.Flush。
func (*Encoder) EncodeToken
func (enc *Encoder) EncodeToken(t Token) error
EncodeToken 将给定的 XML token 写入流。 如果 StartElement 和 EndElement token 未正确配对,它会返回一个错误。
EncodeToken 不调用 Encoder.Flush,因为它通常是更大操作的一部分, 例如 Encoder.Encode 或 Encoder.EncodeElement(或在这些操作期间调用的 自定义 Marshaler 的 MarshalXML),这些操作会在完成时调用 Flush。 创建 Encoder 后直接调用 EncodeToken、而不使用 Encode 或 EncodeElement 的调用者,需要在完成时调用 Flush,以确保 XML 被写入底层写入器。
EncodeToken 只允许将 Target 设为 "xml" 的 ProcInst 作为流中的 第一个 token 写入。
func (*Encoder) Flush
func (enc *Encoder) Flush() error
Flush 将任何已缓冲的 XML 刷新到底层写入器。 关于何时需要调用它的细节,参见 Encoder.EncodeToken 文档。
func (*Encoder) Indent
func (enc *Encoder) Indent(prefix, indent string)
Indent 设置编码器生成 XML 时,每个元素都从 新的一行开始,该行以 prefix 开头,并根据嵌套深度 后跟一个或多个 indent 的副本。
type EndElement
type EndElement struct { Name Name }
EndElement 表示一个 XML 结束元素。
type Marshaler
type Marshaler interface { MarshalXML(e *Encoder, start StartElement) error }
Marshaler 是那些能够将自身封送为有效 XML 元素的对象所实现的 接口。
MarshalXML 将接收者编码为零个或多个 XML 元素。 按照惯例,数组或切片通常被编码为一个元素序列, 每个条目对应一个元素。 使用 start 作为元素标签并非必须,但这样做 将使 Unmarshal 能够将 XML 元素匹配到正确的 结构体字段。 一种常见的实现策略是构造一个布局与所需 XML 相对应的独立 值,然后使用 e.EncodeElement 对它进行编码。 另一种常见策略是重复调用 e.EncodeToken 来逐个 token 地生成 XML 输出。 编码后的 token 序列必须构成零个或多个有效的 XML 元素。
type MarshalerAttr
type MarshalerAttr interface { MarshalXMLAttr(name Name) (Attr, error) }
MarshalerAttr 是那些能够将自身封送为有效 XML 属性的对象所实现的 接口。
MarshalXMLAttr 返回一个 XML 属性,其值为接收者的编码值。 使用 name 作为属性名称并非必须,但这样做 将使 Unmarshal 能够将该属性匹配到正确的 结构体字段。 如果 MarshalXMLAttr 返回零值属性 Attr{},则输出中 不会生成任何属性。 MarshalXMLAttr 仅用于字段标签中带有 "attr" 选项的结构体字段。
type Name
type Name struct { Space, Local string }
Name 表示一个 XML 名称(Local), 并标注了命名空间标识符(Space)。 在 Decoder.Token 返回的 token 中,Space 标识符 以规范化 URL 的形式给出,而不是被解析文档中 使用的短前缀。
type ProcInst
type ProcInst struct { Target string Inst []byte }
ProcInst 表示形如 <?target inst?> 的 XML 处理指令。
func (ProcInst) Copy
func (p ProcInst) Copy() ProcInst
Copy 创建 ProcInst 的新副本。
type StartElement
type StartElement struct { Name Name Attr []Attr }
StartElement 表示一个 XML 起始元素。
func (StartElement) Copy
func (e StartElement) Copy() StartElement
Copy 创建 StartElement 的新副本。
func (StartElement) End
func (e StartElement) End() EndElement
End 返回对应的 XML 结束元素。
type SyntaxError
type SyntaxError struct { Msg string Line int }
SyntaxError 表示 XML 输入流中的一个语法错误。
func (*SyntaxError) Error
func (e *SyntaxError) Error() string
type TagPathError
type TagPathError struct { Struct reflect.Type Field1, Tag1 string Field2, Tag2 string }
TagPathError 表示反封送过程中因使用了路径冲突的 字段标签而导致的错误。
func (*TagPathError) Error
func (e *TagPathError) Error() string
type Token
type Token any
Token 是一个接口,持有以下 token 类型之一: StartElement、EndElement、CharData、Comment、ProcInst 或 Directive。
func CopyToken
func CopyToken(t Token) Token
CopyToken 返回 Token 的副本。
type TokenReader
type TokenReader interface { Token() (Token, error) }
TokenReader 是任何能够解码 XML token 流的东西,包括 Decoder。
当 Token 在成功读取一个 token 之后遇到错误或文件结束(EOF)条件时, 它会返回该 token。它既可能在同一次调用中返回(非 nil 的)错误, 也可能在后续调用中返回该错误(以及一个 nil token)。 这种一般情况的一个例子是:在 token 流末尾返回非 nil token 的 TokenReader 可以返回 io.EOF 或 nil 错误。 下一次 Read 应返回 nil、io.EOF。
不建议 Token 的实现返回 nil token 搭配 nil 错误。调用者应将 返回 nil、nil 视为未发生任何事;尤其是它并不表示 EOF。
type UnmarshalError
type UnmarshalError string
UnmarshalError 表示反封送过程中的一个错误。
func (UnmarshalError) Error
func (e UnmarshalError) Error() string
type Unmarshaler
type Unmarshaler interface { UnmarshalXML(d *Decoder, start StartElement) error }
Unmarshaler 是那些能够反封送自身 XML 元素描述的对象所实现的 接口。
UnmarshalXML 解码以给定起始元素开始的单个 XML 元素。 如果它返回错误,对 Unmarshal 的外层调用会停止并 返回该错误。 UnmarshalXML 必须恰好消费一个 XML 元素。 一种常见的实现策略是使用 d.DecodeElement 将其反封送到一个 布局与预期 XML 匹配的独立值中,然后 将该值中的数据复制到接收者中。 另一种常见策略是使用 d.Token 逐个 token 地处理 XML 对象。 UnmarshalXML 不得使用 d.RawToken。
type UnmarshalerAttr
type UnmarshalerAttr interface { UnmarshalXMLAttr(attr Attr) error }
UnmarshalerAttr 是那些能够反封送自身 XML 属性描述的对象所实现的 接口。
UnmarshalXMLAttr 解码单个 XML 属性。 如果它返回错误,对 Unmarshal 的外层调用会停止并 返回该错误。 UnmarshalXMLAttr 仅用于字段标签中带有 "attr" 选项的结构体字段。
type UnsupportedTypeError
type UnsupportedTypeError struct { Type reflect.Type }
当 Marshal 遇到无法转换为 XML 的类型时, 会返回 UnsupportedTypeError。
func (*UnsupportedTypeError) Error
func (e *UnsupportedTypeError) Error() string