Package xml

import "encoding/xml"
Overview
Index
Examples

Overview ▾

包xml实现了一个简单的XML 1.0解析器,该解析器可以理解XML名称空间.

示例(CustomMarshalXML)

Zoo Census:
* Gophers: 3
* Zebras:  2
* Unknown: 3

示例(TextMarshalXML)

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 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

Package files

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

Constants

const (
    // Header is a generic XML header suitable for use with the output of Marshal.
    // This is not automatically added to any output of this package,
    // it is provided as a convenience.
    Header = `<?xml version="1.0" encoding="UTF-8"?>` + "\n"
)

Variables

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)

转义类似于EscapeText,但是省略了错误返回值. 提供它是为了与Go 1.0向后兼容. 定位到Go 1.1或更高版本的代码应使用EscapeText.

func EscapeText 1.1

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

EscapeText向w写入等效于纯文本数据的XML.

func Marshal

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

元帅返回v的XML编码.

元帅通过封送每个元素来处理数组或切片. 元帅通过整理指针所指向的值来处理指针,如果指针为nil,则不编写任何内容. 元帅通过封送它包含的值来处理接口值,或者如果接口值为nil,则不写任何东西来处理它. 元帅通过编写一个或多个包含数据的XML元素来处理所有其他数据.

XML元素的名称按照优先顺序从中获取:

- the tag on the XMLName field, if the data is a struct
- the value of the XMLName field of type Name
- the tag of the struct field used to obtain the data
- the name of the struct field used to obtain the data
- the name of the marshaled type

结构的XML元素包含该结构的每个导出字段的编组元素,但以下情况除外:

- the XMLName field, described above, is omitted.
- a field with tag "-" is omitted.
- a field with tag "name,attr" becomes an attribute with
  the given name in the XML element.
- a field with tag ",attr" becomes an attribute with the
  field name in the XML element.
- a field with tag ",chardata" is written as character data,
  not as an XML element.
- a field with tag ",cdata" is written as character data
  wrapped in one or more <![CDATA[ ... ]]> tags, not as an XML element.
- a field with tag ",innerxml" is written verbatim, not subject
  to the usual marshaling procedure.
- a field with tag ",comment" is written as an XML comment, not
  subject to the usual marshaling procedure. It must not contain
  the "--" string within it.
- a field with a tag including the "omitempty" option is omitted
  if the field value is empty. The empty values are false, 0, any
  nil pointer or interface value, and any array, slice, map, or
  string of length zero.
- an anonymous struct field is handled as if the fields of its
  value were part of the outer struct.
- a field implementing Marshaler is written by calling its MarshalXML
  method.
- a field implementing encoding.TextMarshaler is written by encoding the
  result of its MarshalText method as text.

如果字段使用标签" a> b> c",则元素c将嵌套在父元素a和b中. 彼此相邻且名称相同的父级的字段将包含在一个XML元素中.

如果struct字段的XML名称同时由field标签和struct的XMLName字段定义,则名称必须匹配.

有关示例,请参见MarshalIndent.

如果要求封送通道,函数或地图,则封送将返回错误.

func MarshalIndent

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

MarshalIndent的工作方式与Marshal相似,但是每个XML元素都从一个新的缩进行开始,该行以前缀开头,并根据嵌套深度紧跟一个或多个缩进副本.

Example

  <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使用了反射包,所以它只能分配给导出的(大写)字段. Unmarshal使用区分大小写的比较来将XML元素名称与标记值和结构字段名称进行匹配.

Unmarshal使用以下规则将XML元素映射到结构. 在规则中,字段的标记是指与struct字段的标记中的键" xml"关联的值(请参见上面的示例).

* If the struct has a field of type []byte or string with tag
   ",innerxml", Unmarshal accumulates the raw XML nested inside the
   element in that field. The rest of the rules still apply.

* If the struct has a field named XMLName of type Name,
   Unmarshal records the element name in that field.

* If the XMLName field has an associated tag of the form
   "name" or "namespace-URL name", the XML element must have
   the given name (and, optionally, name space) or else Unmarshal
   returns an error.

* If the XML element has an attribute whose name matches a
   struct field name with an associated tag containing ",attr" or
   the explicit name in a struct field tag of the form "name,attr",
   Unmarshal records the attribute value in that field.

* If the XML element has an attribute not handled by the previous
   rule and the struct has a field with an associated tag containing
   ",any,attr", Unmarshal records the attribute value in the first
   such field.

* If the XML element contains character data, that data is
   accumulated in the first struct field that has tag ",chardata".
   The struct field may have type []byte or string.
   If there is no such field, the character data is discarded.

* If the XML element contains comments, they are accumulated in
   the first struct field that has tag ",comment".  The struct
   field may have type []byte or string. If there is no such
   field, the comments are discarded.

* If the XML element contains a sub-element whose name matches
   the prefix of a tag formatted as "a" or "a>b>c", unmarshal
   will descend into the XML structure looking for elements with the
   given names, and will map the innermost elements to that struct
   field. A tag starting with ">" is equivalent to one starting
   with the field name followed by ">".

* If the XML element contains a sub-element whose name matches
   a struct field's XMLName tag and the struct field has no
   explicit name tag as per the previous rule, unmarshal maps
   the sub-element to that struct field.

* If the XML element contains a sub-element whose name matches a
   field without any mode flags (",attr", ",chardata", etc), Unmarshal
   maps the sub-element to that struct field.

* If the XML element contains a sub-element that hasn't matched any
   of the above rules and the struct has a field with tag ",any",
   unmarshal maps the sub-element to that struct field.

* An anonymous struct field is handled as if the fields of its
   value were part of the outer struct.

* A struct field with tag "-" is never unmarshaled into.

如果Unmarshal遇到实现Unmarshaler接口的字段类型,则Unmarshal调用其UnmarshalXML方法以从XML元素生成值. 否则,如果该值实现encoding.TextUnmarshaler,则Unmarshal调用该值的UnmarshalText方法.

通过将XML元素的字符数据的串联保存在字符串或[] byte中,Unmarshal将XML元素映射到字符串或[] byte. 保存的[] byte永远不会为零.

通过将属性值保存在字符串或切片中,Unmarshal将属性值映射到字符串或[] byte.

通过将属性(包括名称)保存在Attr中,Unmarshal将属性值映射到Attr.

通过扩展切片的长度并将元素或属性映射到新创建的值,Unmarshal将XML元素或属性值映射到切片.

通过将XML元素或属性值设置为由字符串表示的布尔值,Unmarshal将XML元素或属性值映射为bool. 空格被修剪并被忽略.

通过将字段设置为以十进制解释字符串值的结果,Unmarshal将XML元素或属性值映射到整数或浮点字段. 没有检查溢出. 空格被修剪并被忽略.

Unmarshal通过记录元素名称将XML元素映射到Name.

通过将指针设置为新分配的值,然后将元素映射到该值,Unmarshal将XML元素映射到指针.

缺少的元素或空的属性值将被取消编组为零值. 如果该字段是切片,则将零值附加到该字段. 否则,该字段将设置为零值.

Example

此示例演示了如何将XML摘录编组为具有某些预设字段的值. 请注意,"电话"字段未修改,并且XML <Company>元素被忽略. 同样,考虑到在其标签中提供的元素路径来分配"组"字段.

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元素(名称=值)中的属性.

type Attr struct {
    Name  Name
    Value string
}

type CharData

CharData表示XML字符数据(原始文本),其中XML转义序列已由它们表示的字符替换.

type CharData []byte

func (CharData) Copy

func (c CharData) Copy() CharData

复制将创建CharData的新副本.

type Comment

A Comment represents an XML comment of the form <!--comment-->. The bytes do not include the <!-- and --> comment markers.

type Comment []byte

func (Comment) Copy

func (c Comment) Copy() Comment

复制将创建新的注释副本.

type Decoder

解码器表示读取特定输入流的XML解析器. 解析器假定其输入以UTF-8编码.

type Decoder 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:
    //
    //	d.Strict = false
    //	d.AutoClose = xml.HTMLAutoClose
    //	d.Entity = xml.HTMLEntity
    //
    // creates a parser that can handle typical HTML.
    //
    // Strict mode does not enforce the requirements of the XML name spaces TR.
    // In particular it does not reject name space tags using undefined prefixes.
    // Such tags are recorded with the unknown prefix as the name space URL.
    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

    // CharsetReader, if non-nil, defines a function to generate
    // charset-conversion readers, converting from the provided
    // non-UTF-8 charset into UTF-8. If CharsetReader is nil or
    // returns an error, parsing stops with an error. One of the
    // CharsetReader's result values must be non-nil.
    CharsetReader func(charset string, input io.Reader) (io.Reader, error)

    // DefaultSpace sets the default name space used for unadorned tags,
    // as if the entire XML stream were wrapped in an element containing
    // the attribute xmlns="DefaultSpace".
    DefaultSpace string // Go 1.1
    // contains filtered or unexported fields
}

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

解码的工作方式与Unmarshal相似,只是它读取解码器流以查找开始元素.

func (*Decoder) DecodeElement

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

DecodeElement的工作方式与Unmarshal相似,不同之处在于它需要指向起始XML元素的指针才能解码为v.这在客户端读取一些原始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;否则返回null. 否则返回描述问题的错误.

func (*Decoder) Token

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

令牌返回输入流中的下一个XML令牌. 在输入流的末尾,Token返回nil,即io.EOF.

返回的令牌数据中的字节片引用解析器的内部缓冲区,并且仅在下一次调用Token之前保持有效. 要获取字节的副本,请调用CopyToken或令牌的Copy方法.

令牌将诸如<br/>之类的自闭合元素扩展为连续调用返回的单独的开始和结束元素.

令牌保证返回的StartElement和EndElement令牌正确嵌套和匹配:如果Token在所有预期的结束元素之前遇到意外的结束元素或EOF,它将返回错误.

令牌实现了https://www.w3.org/TR/REC-xml-names/中描述的XML名称空间. 令牌中包含的每个名称结构都将空格设置为URL,以便在知道时标识其名称空间. 如果Token遇到无法识别的名称空间前缀,它将使用该前缀作为空格,而不是报告错误.

type Directive

指令表示形式为<!text>的XML指令. 字节不包含<! 和>标记.

type Directive []byte

func (Directive) Copy

func (d Directive) Copy() Directive

复制会创建指令的新副本.

type Encoder

编码器将XML数据写入输出流.

type Encoder struct {
    // contains filtered or unexported fields
}

Example

  <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 returns a new encoder that writes to w.

func (*Encoder) Encode

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

编码将v的XML编码写入流中.

有关将Go值转换为XML的详细信息,请参见Marshal的文档.

返回之前对调用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然后直接调用EncodeToken(而不使用Encode或EncodeElement)的调用者在完成后需要调用Flush,以确保将XML写入基础编写器.

EncodeToken允许仅将Target设置为" xml"的ProcInst写入流中,作为第一个令牌.

func (*Encoder) Flush 1.2

func (enc *Encoder) Flush() error

刷新将所有缓冲的XML刷新到基础编写器. 有关何时需要的详细信息,请参见EncodeToken文档.

func (*Encoder) Indent 1.1

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

Indent sets the encoder to generate XML in which each element begins on a new indented line that starts with prefix and is followed by one or more copies of indent according to the nesting depth.

type EndElement

EndElement表示XML结束元素.

type EndElement struct {
    Name Name
}

type Marshaler 1.2

Marshaler是由对象实现的接口,这些对象可以将自己编组为有效的XML元素.

MarshalXML将接收方编码为零个或多个XML元素. 按照约定,数组或切片通常被编码为一系列元素,每个条目一个. 不需要将start用作element标记,但这将使Unmarshal能够将XML元素匹配到正确的struct字段. 一种常见的实现策略是使用与所需XML相对应的布局构造一个单独的值,然后使用e.EncodeElement对其进行编码. 另一种常见的策略是使用对e.EncodeToken的重复调用来一次生成XML输出一个令牌. 编码令牌的序列必须组成零个或多个有效XML元素.

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

type MarshalerAttr 1.2

MarshalerAttr是由对象实现的接口,可以将自己编组为有效的XML属性.

MarshalXMLAttr返回带有接收者编码值的XML属性. 不需要使用name作为属性名称,但是这样做可以使Unmarshal将属性与正确的struct字段匹配. 如果MarshalXMLAttr返回零属性Attr {},则在输出中将不生成任何属性. MarshalXMLAttr仅用于在字段标记中带有" attr"选项的结构字段.

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

type Name

名称表示带有名称空间标识符(空格)的XML名称(本地). 在由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

复制将创建ProcInst的新副本.

type StartElement

StartElement表示XML起始元素.

type StartElement struct {
    Name Name
    Attr []Attr
}

func (StartElement) Copy

func (e StartElement) Copy() StartElement

复制将创建StartElement的新副本.

func (StartElement) End 1.2

func (e StartElement) End() EndElement

End返回相应的XML end元素.

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

令牌是持有令牌类型之一的接口:StartElement,EndElement,CharData,Comment,ProcInst或Directive.

type Token interface{}

func CopyToken

func CopyToken(t Token) Token

CopyToken返回令牌的副本.

type TokenReader 1.10

TokenReader是可以解码XML令牌流的任何东西,包括Decoder.

当令牌成功读取令牌后遇到错误或文件结束条件时,它将返回令牌. 它可能从同一调用返回(非nil)错误,或者从后续调用返回错误(和nil令牌). 这种一般情况的一个实例是,在令牌流的末尾返回非nil令牌的TokenReader可能返回io.EOF或nil错误. 下次读取应返回nio EOF.

不鼓励Token的实现返回带有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解码以给定start元素开头的单个XML元素. 如果返回错误,则对Unmarshal的外部调用将停止并返回该错误. UnmarshalXML必须只使用一个XML元素. 一种常见的实现策略是使用d.DecodeElement将具有与所需XML匹配的布局的封送解编为单独的值,然后将数据从该值复制到接收器中. 另一种常见的策略是使用d.Token一次处理XML对象一个令牌. UnmarshalXML可能不使用d.RawToken.

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

type UnmarshalerAttr 1.2

UnmarshalerAttr是由对象实现的接口,这些对象可以解组自己的XML属性描述.

UnmarshalXMLAttr解码单个XML属性. 如果返回错误,则对Unmarshal的外部调用将停止并返回该错误. UnmarshalXMLAttr仅用于在字段标记中带有" attr"选项的结构字段.

type UnmarshalerAttr interface {
    UnmarshalXMLAttr(attr Attr) error
}

type UnsupportedTypeError

当元帅遇到无法转换为XML的类型时,将返回UnsupportedTypeError.

type UnsupportedTypeError struct {
    Type reflect.Type
}

func (*UnsupportedTypeError) Error

func (e *UnsupportedTypeError) Error() string

Bugs

by  ICOPY.SITE