# package xml
`import "encoding/xml"`
Package xml implements a simple XML 1.0 parser that understands XML name spaces.
## Index
* [Constants](#pkg-constants)
* [Variables](#pkg-variables)
* [type SyntaxError](#SyntaxError)
* [func (e \*SyntaxError) Error() string](#SyntaxError.Error)
* [type TagPathError](#TagPathError)
* [func (e \*TagPathError) Error() string](#TagPathError.Error)
* [type UnsupportedTypeError](#UnsupportedTypeError)
* [func (e \*UnsupportedTypeError) Error() string](#UnsupportedTypeError.Error)
* [type UnmarshalError](#UnmarshalError)
* [func (e UnmarshalError) Error() string](#UnmarshalError.Error)
* [type CharData](#CharData)
* [func (c CharData) Copy() CharData](#CharData.Copy)
* [type Comment](#Comment)
* [func (c Comment) Copy() Comment](#Comment.Copy)
* [type Directive](#Directive)
* [func (d Directive) Copy() Directive](#Directive.Copy)
* [type ProcInst](#ProcInst)
* [func (p ProcInst) Copy() ProcInst](#ProcInst.Copy)
* [type Name](#Name)
* [type Attr](#Attr)
* [type StartElement](#StartElement)
* [func (e StartElement) Copy() StartElement](#StartElement.Copy)
* [func (e StartElement) End() EndElement](#StartElement.End)
* [type EndElement](#EndElement)
* [type Token](#Token)
* [func CopyToken(t Token) Token](#CopyToken)
* [type Marshaler](#Marshaler)
* [type Unmarshaler](#Unmarshaler)
* [type MarshalerAttr](#MarshalerAttr)
* [type UnmarshalerAttr](#UnmarshalerAttr)
* [func Escape(w io.Writer, s []byte)](#Escape)
* [func EscapeText(w io.Writer, s []byte) error](#EscapeText)
* [func Marshal(v interface{}) ([]byte, error)](#Marshal)
* [func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)](#MarshalIndent)
* [func Unmarshal(data []byte, v interface{}) error](#Unmarshal)
* [type Decoder](#Decoder)
* [func NewDecoder(r io.Reader) \*Decoder](#NewDecoder)
* [func (d \*Decoder) Decode(v interface{}) error](#Decoder.Decode)
* [func (d \*Decoder) DecodeElement(v interface{}, start \*StartElement) error](#Decoder.DecodeElement)
* [func (d \*Decoder) Token() (t Token, err error)](#Decoder.Token)
* [func (d \*Decoder) RawToken() (Token, error)](#Decoder.RawToken)
* [func (d \*Decoder) Skip() error](#Decoder.Skip)
* [type Encoder](#Encoder)
* [func NewEncoder(w io.Writer) \*Encoder](#NewEncoder)
* [func (enc \*Encoder) Encode(v interface{}) error](#Encoder.Encode)
* [func (enc \*Encoder) EncodeElement(v interface{}, start StartElement) error](#Encoder.EncodeElement)
* [func (enc \*Encoder) EncodeToken(t Token) error](#Encoder.EncodeToken)
* [func (enc \*Encoder) Flush() error](#Encoder.Flush)
* [func (enc \*Encoder) Indent(prefix, indent string)](#Encoder.Indent)
### Examples
* [Encoder](#example-Encoder)
* [MarshalIndent](#example-MarshalIndent)
* [Unmarshal](#example-Unmarshal)
## Constants
```
const (
// 適用于本包Marshal輸出的一般性XML header
// 本常數并不會自動添加到本包的輸出里,這里提供主要是出于便利的目的
Header = `<?xml version="1.0" encoding="UTF-8"?>` + "\n"
)
```
## Variables
```
var HTMLAutoClose = htmlAutoClose
```
HTMLAutoClose是應當考慮到自動關閉的HTML元素的集合。
```
var HTMLEntity = htmlEntity
```
HTMLEntity是標準HTML entity字符到其翻譯的映射。
## type [SyntaxError](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L29 "View Source")
```
type SyntaxError struct {
Msg string
Line int
}
```
SyntaxError代表XML輸入流的格式錯誤。
### func (\*SyntaxError) [Error](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L34 "View Source")
```
func (e *SyntaxError) Error() string
```
## type [TagPathError](https://github.com/golang/go/blob/master/src/encoding/xml/typeinfo.go#L336 "View Source")
```
type TagPathError struct {
Struct reflect.Type
Field1, Tag1 string
Field2, Tag2 string
}
```
反序列化時,如果字段標簽的路徑有沖突,就會返回TagPathError。
### func (\*TagPathError) [Error](https://github.com/golang/go/blob/master/src/encoding/xml/typeinfo.go#L342 "View Source")
```
func (e *TagPathError) Error() string
```
## type [UnsupportedTypeError](https://github.com/golang/go/blob/master/src/encoding/xml/marshal.go#L914 "View Source")
```
type UnsupportedTypeError struct {
Type reflect.Type
}
```
當序列化時,如果遇到不能轉化為XML的類型,就會返回UnsupportedTypeError。
### func (\*UnsupportedTypeError) [Error](https://github.com/golang/go/blob/master/src/encoding/xml/marshal.go#L918 "View Source")
```
func (e *UnsupportedTypeError) Error() string
```
## type [UnmarshalError](https://github.com/golang/go/blob/master/src/encoding/xml/read.go#L137 "View Source")
```
type UnmarshalError string
```
UnmarshalError代表反序列化時出現的錯誤。
### func (UnmarshalError) [Error](https://github.com/golang/go/blob/master/src/encoding/xml/read.go#L139 "View Source")
```
func (e UnmarshalError) Error() string
```
## type [CharData](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L83 "View Source")
```
type CharData []byte
```
CharData類型代表XML字符數據(原始文本),其中XML轉義序列已經被它們所代表的字符取代。
### func (CharData) [Copy](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L91 "View Source")
```
func (c CharData) Copy() CharData
```
## type [Comment](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L95 "View Source")
```
type Comment []byte
```
Comment代表XML注釋,格式為<!--comment-->,切片中不包含注釋標記<!—和-->。
### func (Comment) [Copy](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L97 "View Source")
```
func (c Comment) Copy() Comment
```
## type [Directive](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L112 "View Source")
```
type Directive []byte
```
Directive代表XML指示,格式為<!directive>,切片中不包含標記<!和>。
### func (Directive) [Copy](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L114 "View Source")
```
func (d Directive) Copy() Directive
```
## type [ProcInst](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L100 "View Source")
```
type ProcInst struct {
Target string
Inst []byte
}
```
ProcInst代表XML處理指令,格式為<?target inst?>。
### func (ProcInst) [Copy](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L105 "View Source")
```
func (p ProcInst) Copy() ProcInst
```
## type [Name](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L43 "View Source")
```
type Name struct {
Space, Local string
}
```
Name代表一個XML名稱(Local字段),并指定名字空間(Space)。Decoder.Token方法返回的Token中,Space標識符是典型的URL而不是被解析的文檔里的短前綴。
## type [Attr](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L48 "View Source")
```
type Attr struct {
Name Name
Value string
}
```
Attr代表一個XML元素的一條屬性(Name=Value)
## type [StartElement](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L58 "View Source")
```
type StartElement struct {
Name Name
Attr []Attr
}
```
StartElement代表一個XML起始元素。
### func (StartElement) [Copy](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L63 "View Source")
```
func (e StartElement) Copy() StartElement
```
### func (StartElement) [End](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L71 "View Source")
```
func (e StartElement) End() EndElement
```
返回e對應的XML結束元素。
## type [EndElement](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L76 "View Source")
```
type EndElement struct {
Name Name
}
```
EndElement代表一個XML結束元素。
## type [Token](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L55 "View Source")
```
type Token interface{}
```
Token接口用于保存token類型(CharData、Comment、Directive、ProcInst、StartElement、EndElement)的值。
### func [CopyToken](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L117 "View Source")
```
func CopyToken(t Token) Token
```
CopyToken返回一個Token的拷貝。
## type [Marshaler](https://github.com/golang/go/blob/master/src/encoding/xml/marshal.go#L94 "View Source")
```
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 [Unmarshaler](https://github.com/golang/go/blob/master/src/encoding/xml/read.go#L156 "View Source")
```
type Unmarshaler interface {
UnmarshalXML(d *Decoder, start StartElement) error
}
```
實現了Unmarshaler接口的類型可以根據自身的XML元素描述反序列化自身。
UnmarshalXML方法解碼以start起始單個XML元素。如果它返回了錯誤,外層Unmarshal的調用將停止執行并返回該錯誤。UnmarshalXML方法必須正好“消費”一個XML元素。一個常用的策略是使用d.DecodeElement?將XML分別解碼到各獨立值,然后再將這些值寫入UnmarshalXML的調用者。另一個常用的策略是使用d.Token一次一個token的處理XML對象。UnmarshalXML通常不使用d.RawToken。
## type [MarshalerAttr](https://github.com/golang/go/blob/master/src/encoding/xml/marshal.go#L109 "View Source")
```
type MarshalerAttr interface {
MarshalXMLAttr(name Name) (Attr, error)
}
```
實現了MarshalerAttr接口的類型可以將自身序列化為合法的XML屬性。
MarshalXMLAttr返回一個值為方法調用者編碼后的值的XML屬性。使用name作為屬性的name并非必須的,但這么做可以幫助Unmarshal方法正確的匹配屬性和結構體字段。如果MarshalXMLAttr返回一個零值屬性Attr{},將不會生成屬性輸出。MarshalXMLAttr只用于有標簽且標簽有"attr"選項的結構體字段。
## type [UnmarshalerAttr](https://github.com/golang/go/blob/master/src/encoding/xml/read.go#L168 "View Source")
```
type UnmarshalerAttr interface {
UnmarshalXMLAttr(attr Attr) error
}
```
實現了UnmarshalerAttr接口的類型可以根據自身的XML屬性形式的描述反序列化自身。
UnmarshalXMLAttr解碼單個的XML屬性。如果它返回一個錯誤,外層的Umarshal調用會停止執行并返回該錯誤。UnmarshalXMLAttr只有在結構體字段的標簽有"attr"選項時才被使用。
## func [Escape](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L1910 "View Source")
```
func Escape(w io.Writer, s []byte)
```
Escape類似EscapeText函數但會忽略返回的錯誤。本函數是用于保證和Go 1.0的向后兼容。應用于Go 1.1及以后版本的代碼請使用EscapeText。
## func [EscapeText](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L1824 "View Source")
```
func EscapeText(w io.Writer, s []byte) error
```
EscapeText向w中寫入經過適當轉義的、有明文s具有相同意義的XML文本。
## func [Marshal](https://github.com/golang/go/blob/master/src/encoding/xml/marshal.go#L70 "View Source")
```
func Marshal(v interface{}) ([]byte, error)
```
Marshal函數返回v的XML編碼。
Marshal處理數組或者切片時會序列化每一個元素。Marshal處理指針時,會序列化其指向的值;如果指針為nil,則啥也不輸出。Marshal處理接口時,會序列化其內包含的具體類型值,如果接口值為nil,也是不輸出。Marshal處理其余類型數據時,會輸出一或多個包含數據的XML元素。
XML元素的名字按如下優先順序獲取:
```
- 如果數據是結構體,其XMLName字段的標簽
- 類型為xml.Name的XMLName字段的值
- 數據是某結構體的字段,其標簽
- 數據是某結構體的字段,其字段名
- 被序列化的類型的名字
```
一個結構體的XML元素包含該結構體所有導出字段序列化后的元素,有如下例外:
```
- XMLName字段,如上所述,會省略
- 具有標簽"-"的字段會省略
- 具有標簽"name,attr"的字段會成為該XML元素的名為name的屬性
- 具有標簽",attr"的字段會成為該XML元素的名為字段名的屬性
- 具有標簽",chardata"的字段會作為字符數據寫入,而非XML元素
- 具有標簽",innerxml"的字段會原樣寫入,而不會經過正常的序列化過程
- 具有標簽",comment"的字段作為XML注釋寫入,而不經過正常的序列化過程,該字段內不能有"--"字符串
- 標簽中包含"omitempty"選項的字段如果為空值會省略
空值為false、0、nil指針、nil接口、長度為0的數組、切片、映射
- 匿名字段(其標簽無效)會被處理為其字段是外層結構體的字段
```
如果一個字段的標簽為"a>b>c",則元素c將會嵌套進其上層元素a和b中。如果該字段相鄰的字段標簽指定了同樣的上層元素,則會放在同一個XML元素里。
參見MarshalIndent的例子。如果要求Marshal序列化通道、函數或者映射會返回錯誤。
## func [MarshalIndent](https://github.com/golang/go/blob/master/src/encoding/xml/marshal.go#L116 "View Source")
```
func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)
```
MarshalIndent功能類似Marshal。但每個XML元素會另起一行并縮進,該行以prefix起始,后跟一或多個indent的拷貝(根據嵌套層數)。
Example
```
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)
```
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](https://github.com/golang/go/blob/master/src/encoding/xml/read.go#L114 "View Source")
```
func Unmarshal(data []byte, v interface{}) error
```
Unmarshal解析XML編碼的數據并將結果存入v指向的值。v只能指向結構體、切片或者和字符串。良好格式化的數據如果不能存入v,會被丟棄。
因為Unmarshal使用reflect包,它只能填寫導出字段。本函數好似用大小寫敏感的比較來匹配XML元素名和結構體的字段名/標簽鍵名。
Unmarshal函數使用如下規則將XML元素映射到結構體字段上。這些規則中,字段標簽指的是結構體字段的標簽鍵'xml'對應的值(參見上面的例子):
```
* 如果結構體字段的類型為字符串或者[]byte,且標簽為",innerxml",
Unmarshal函數直接將對應原始XML文本寫入該字段,其余規則仍適用。
* 如果結構體字段類型為xml.Name且名為XMLName,Unmarshal會將元素名寫入該字段
* 如果字段XMLName的標簽的格式為"name"或"namespace-URL name",
XML元素必須有給定的名字(以及可選的名字空間),否則Unmarshal會返回錯誤。
* 如果XML元素的屬性的名字匹配某個標簽",attr"為字段的字段名,或者匹配某個標簽為"name,attr"
的字段的標簽名,Unmarshal會將該屬性的值寫入該字段。
* 如果XML元素包含字符數據,該數據會存入結構體中第一個具有標簽",chardata"的字段中,
該字段可以是字符串類型或者[]byte類型。如果沒有這樣的字段,字符數據會丟棄。
* 如果XML元素包含注釋,該數據會存入結構體中第一個具有標簽",comment"的字段中,
該字段可以是字符串類型或者[]byte類型。如果沒有這樣的字段,字符數據會丟棄。
* 如果XML元素包含一個子元素,其名稱匹配格式為"a"或"a>b>c"的標簽的前綴,反序列化會深入
XML結構中尋找具有指定名稱的元素,并將最后端的元素映射到該標簽所在的結構體字段。
以">"開始的標簽等價于以字段名開始并緊跟著">" 的標簽。
* 如果XML元素包含一個子元素,其名稱匹配某個結構體類型字段的XMLName字段的標簽名,
且該結構體字段本身沒有顯式指定標簽名,Unmarshal會將該元素映射到該字段。
* 如果XML元素的包含一個子元素,其名稱匹配夠格結構體字段的字段名,且該字段沒有任何模式選項
(",attr"、",chardata"等),Unmarshal會將該元素映射到該字段。
* 如果XML元素包含的某個子元素不匹配以上任一條,而存在某個字段其標簽為",any",
Unmarshal會將該元素映射到該字段。
* 匿名字段被處理為其字段好像位于外層結構體中一樣。
* 標簽為"-"的結構體字段永不會被反序列化填寫。
```
Unmarshal函數將XML元素寫入string或[]byte時,會將該元素的字符數據串聯起來作為值,目標[]byte不能是nil。
Unmarshal函數將屬性寫入string或[]byte時,會將屬性的值以字符串/切片形式寫入。
Unmarshal函數將XML元素寫入切片時,會將切片擴展并將XML元素的子元素映射入新建的值里。
Unmarshal函數將XML元素/屬性寫入bool值時,會將對應的字符串轉化為布爾值。
Unmarshal函數將XML元素/屬性寫入整數或浮點數類型時,會將對應的字符串解釋為十進制數字。不會檢查溢出。
Unmarshal函數將XML元素寫入xml.Name類型時,會記錄元素的名稱。
Unmarshal函數將XML元素寫入指針時,會申請一個新值并將XML元素映射入該值。
Example
```
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)
```
Output:
```
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 [Decoder](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L135 "View Source")
```
type Decoder struct {
// Strict默認設為true,強制要求符合XML規范
// 如果設為false,則解析器允許輸入中包含常見的錯誤:
// * 如果元素缺少結束標簽,解析器會虛構一個結束標簽以保證返回值來自良好平衡的Token
// * 屬性值和字符數據中,未知或畸形的字符entity(以&開始的序列)會丟在一邊
//
// 設置:
//
// d.Strict = false
// d.AutoClose = HTMLAutoClose
// d.Entity = HTMLEntity
//
// 可以創建一個能處理標準HTML的解析器。
//
// Strict模式不會強制要求XML名稱空間TR,特別注意它不會拒絕使用未定義前綴的名字空間標簽
// 這些標簽會將未知前綴作為名字空間URL來記錄
Strict bool
// 當Strict == false時,AutoClose指定一個元素的集合:
// 這些元素在開啟后就立刻結束,不管有沒有對應關閉標簽存在
AutoClose []string
// Entity字段用于將非標準的實體名映射到替換的字符串
// parser的行為就好像標準實體映射存在于本字段,即使實際上本字段沒有:
//
// "lt": "<",
// "gt": ">",
// "amp": "&",
// "apos": "'",
// "quot": `"`,
Entity map[string]string
// CharsetReader字段如果非nil,會定義一個函數來生成轉換字符集的io.Reader,
// 將給定的非utf-8字符集轉換為utf-8字符集。如果CharsetReader字段為nil
// 或者返回一個錯誤,解析將會停止并發揮該錯誤。CharsetReader的返回值不能都是nil
CharsetReader func(charset string, input io.Reader) (io.Reader, error)
// DefaultSpace設置未修飾標簽的默認名字空間,就好像整個XML流都包裝進有個具有屬性
// xmlns="DefaultSpace"的元素內
DefaultSpace string
// 內含隱藏或非導出字段
}
```
Decoder代表一個XML解析器,可以讀取輸入流的部分數據,該解析器假定輸入是utf-8編碼的。
### func [NewDecoder](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L205 "View Source")
```
func NewDecoder(r io.Reader) *Decoder
```
創建一個從r讀取XML數據的解析器。如果r未實現io.ByteReader接口,NewDecoder會為其添加緩存。
### func (\*Decoder) [Decode](https://github.com/golang/go/blob/master/src/encoding/xml/read.go#L120 "View Source")
```
func (d *Decoder) Decode(v interface{}) error
```
Decode方法功能類似xml.Unmarshal函數,但會從底層讀取XML數據并查找StartElement。
### func (\*Decoder) [DecodeElement](https://github.com/golang/go/blob/master/src/encoding/xml/read.go#L128 "View Source")
```
func (d *Decoder) DecodeElement(v interface{}, start *StartElement) error
```
DecodeElement方法的功能類似xml.Unmarshal函數,但它會啟出一個指向XML起始標簽后將解析結果寫入v。當客戶端自己讀取了一些原始XML token但仍想defer調用Unmarshal處理一些元素時很有用。
### func (\*Decoder) [Token](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L238 "View Source")
```
func (d *Decoder) Token() (t Token, err error)
```
Token返回輸入流里的下一個XML token。在輸入流的結尾處,會返回(nil, io.EOF)
返回的token數據里的[]byte數據引用自解析器內部的緩存,只在下一次調用Token之前有效。如要獲取切片的拷貝,調用CopyToken函數或者token的Copy方法。
成功調用的Token方法會將自我閉合的元素(如<br/>)擴展為分離的起始和結束標簽。
Token方法會保證它返回的StartElement和EndElement兩種token正確的嵌套和匹配:如果本方法遇到了不正確的結束標簽,會返回一個錯誤。
Token方法實現了XML名字空間,細節參見[http://www.w3.org/TR/REC-xml-names/](http://www.w3.org/TR/REC-xml-names/)。每一個包含在Token里的Name結構體,都會將Space字段設為URL標識(如果可知的話)。如果Token遇到未知的名字空間前綴,它會使用該前綴作為名字空間,而不是報錯。
### func (\*Decoder) [RawToken](https://github.com/golang/go/blob/master/src/encoding/xml/xml.go#L492 "View Source")
```
func (d *Decoder) RawToken() (Token, error)
```
RawToken方法Token方法,但不會驗證起始和結束標簽,也不將名字空間前綴翻譯為它們相應的URL。
### func (\*Decoder) [Skip](https://github.com/golang/go/blob/master/src/encoding/xml/read.go#L677 "View Source")
```
func (d *Decoder) Skip() error
```
Skip從底層讀取token,直到讀取到最近一次讀取到的起始標簽對應的結束標簽。如果讀取中遇到別的起始標簽會進行迭代,因此可以跳過嵌套結構。如果本方法找到了對應起始標簽的結束標簽,會返回nil;否則返回一個描述該問題的錯誤。
## type [Encoder](https://github.com/golang/go/blob/master/src/encoding/xml/marshal.go#L127 "View Source")
```
type Encoder struct {
// 內含隱藏或非導出字段
}
```
Encoder向輸出流中寫入XML數據。
Example
```
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)
}
```
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 [NewEncoder](https://github.com/golang/go/blob/master/src/encoding/xml/marshal.go#L132 "View Source")
```
func NewEncoder(w io.Writer) *Encoder
```
NewEncoder創建一個寫入w的\*Encoder。
### func (\*Encoder) [Encode](https://github.com/golang/go/blob/master/src/encoding/xml/marshal.go#L152 "View Source")
```
func (enc *Encoder) Encode(v interface{}) error
```
Encode將v編碼為XML后寫入底層。參見Marshal函數獲取go到XML轉換的細節。在返回前enc會調用Flush。
### func (\*Encoder) [EncodeElement](https://github.com/golang/go/blob/master/src/encoding/xml/marshal.go#L167 "View Source")
```
func (enc *Encoder) EncodeElement(v interface{}, start StartElement) error
```
EncodeElement將v的XML編碼寫入底層,?并使用start作為編碼的最外層。參見Marshal函數獲取go到XML轉換的細節。在返回前enc會調用Flush方法。
### func (\*Encoder) [EncodeToken](https://github.com/golang/go/blob/master/src/encoding/xml/marshal.go#L193 "View Source")
```
func (enc *Encoder) EncodeToken(t Token) error
```
EncodeToken向底層寫入一個token。如果StartElement和EndElement的匹配不正確,本方法會返回錯誤。
EncodeToken?方法不會調用Flush,因為它通常是更大型操作如Encode或EncodeElement方法的一部分(或者用戶自定義的Marshaler接口MarshalXML?方法里調用本方法),這些方法會在結束前Flush。調用者創建一個Encoder并直接使用本方法而不使用Encode或EncodeElement方法的話,必須在結束時調用Flush以保證XML數據寫入底層的io.Writer接口。
EncodeToken寫入ProcInst類型Token時,只允許在底層流最開始寫入目標是"xml"的ProcInst。
### func (\*Encoder) [Flush](https://github.com/golang/go/blob/master/src/encoding/xml/marshal.go#L246 "View Source")
```
func (enc *Encoder) Flush() error
```
Flush方法會將緩存中的XML數據寫入底層。參見EncodeToken函數獲取細節信息。
### func (\*Encoder) [Indent](https://github.com/golang/go/blob/master/src/encoding/xml/marshal.go#L141 "View Source")
```
func (enc *Encoder) Indent(prefix, indent string)
```
Indent函數設定編碼器生成XML數據時的格式化縮進信息。細節請參見MarshalIndent函數。
## Bugs
[?](https://github.com/golang/go/blob/master/src/encoding/xml/read.go#L17 "View Source") XML元素和數據結構體的映射有天生的缺陷:XML元素是依賴順序的匿名值的集合,而結構體是不依賴順序的命名值的集合。參見json包獲取更適用于數據結構體的文本表示。
- 庫
- package achive
- package tar
- package zip
- package bufio
- package builtin
- package bytes
- package compress
- package bzip2
- package flate
- package gzip
- package lzw
- package zlib
- package container
- package heap
- package list
- package ring
- package crypto
- package aes
- package cipher
- package des
- package dsa
- package ecdsa
- package elliptic
- package hmac
- package md5
- package rand
- package rc4
- package rsa
- package sha1
- package sha256
- package sha512
- package subtle
- package tls
- package x509
- package pkix
- package database
- package sql
- package driver
- package encoding
- package ascii85
- package asn1
- package base32
- package base64
- package binary
- package csv
- package gob
- package hex
- package json
- package pem
- package xml
- package errors
- package expvar
- package flag
- package fmt
- package go
- package doc
- package format
- package parser
- package printer
- package hash
- package adler32
- package crc32
- package crc64
- package fnv
- package html
- package template
- package image
- package color
- package palette
- package draw
- package gif
- package jpeg
- package png
- package index
- package suffixarray
- package io
- package ioutil
- package log
- package syslog
- package math
- package big
- package cmplx
- package rand
- package mime
- package multipart
- package net
- package http
- package cgi
- package cookiejar
- package fcgi
- package httptest
- package httputil
- package pprof
- package mail
- package rpc
- package jsonrpc
- package smtp
- package textproto
- package url
- package os
- package exec
- package signal
- package user
- package path
- package filepath
- package reflect
- package regexp
- package runtime
- package cgo
- package debug
- package pprof
- package race
- package sort
- package strconv
- package strings
- package sync
- package atomic
- package text
- package scanner
- package tabwriter
- package template
- package time
- package unicode
- package utf16
- package utf8
- package unsafe