?
本文檔使用 php中文網(wǎng)手冊 發(fā)布
import "encoding/xml"
Overview
Index
Examples
概觀
Package xml實現(xiàn)了一個理解XML名稱空間的簡單XML 1.0分析器。
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 (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 UnmarshalError
func (e UnmarshalError) Error() string
type Unmarshaler
type UnmarshalerAttr
type UnsupportedTypeError
func (e *UnsupportedTypeError) Error() string
Bugs
例子
Encoder MarshalIndent Unmarshal
包文件
marshal.go read.go typeinfo.go xml.go
常量
const ( // 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")
變量
HTMLAutoClose是應被視為自動關閉的一組HTML元素。
var HTMLAutoClose = htmlAutoClose
HTMLEntity是包含標準HTML實體字符翻譯的實體映射。
var HTMLEntity = htmlEntity
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寫入正確轉義的純文本數(shù)據(jù)的XML等價物。
func Marshal
func Marshal(v interface{}) ([]byte, error)Marshal返回v的XML編碼。
Marshal通過封送每個元素來處理數(shù)組或片段。Marshal通過編組指向的值處理指針，如果指針為零，則不寫任何內容。Marshal通過封送其包含的值來處理接口值，或者如果接口值為零，則不寫任何內容。Marshal通過編寫一個或多個包含數(shù)據(jù)的XML元素來處理所有其他數(shù)據(jù)。
XML元素的名稱取自優(yōu)先順序：
- 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> b> c”，那么元素c將嵌套在父元素a和b中。名稱相同的父對象旁邊出現(xiàn)的字段將被包含在一個XML元素中。
以MarshalIndent為例。
如果要求編組頻道，功能或地圖，元帥將返回錯誤。
func MarshalIndent
func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)MarshalIndent的工作方式與Marshal相同，但每個XML元素都以一個新的縮進行開始，該行以前綴開頭，后跟一個或多個根據(jù)嵌套深度縮進的縮進副本。
例
package mainimport ("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)}func Unmarshal
func Unmarshal(data []byte, v interface{}) errorUnmarshal解析XML編碼的數(shù)據(jù)并將結果存儲在v指向的值中，該值必須是任意的結構體，切片或字符串。丟棄不適合v的格式良好的數(shù)據(jù)。
由于Unmarshal使用反射包，因此它只能分配給導出（大寫）字段。Unmarshal使用區(qū)分大小寫的比較來將XML元素名稱與標記值和結構字段名稱進行匹配。
Unmarshal使用以下規(guī)則將XML元素映射到結構。在規(guī)則中，字段的標記引用與struct字段標記中的鍵'xml'關聯(lián)的值（請參見上面的示例）。
* 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將XML元素映射到字符串或[]字節(jié)，方法是將該元素的字符數(shù)據(jù)串聯(lián)在字符串或[]字節(jié)中。保存的[]字節(jié)永遠不會為零。
Unmarshal通過將值保存在字符串或切片中將屬性值映射到字符串或[]字節(jié)。
Unmarshal通過將屬性（包括其名稱）保存在Attr中將屬性值映射到Attr。
Unmarshal通過擴展切片的長度并將元素或屬性映射到新創(chuàng)建的值來將XML元素或屬性值映射到切片。
Unmarshal通過將XML元素或屬性值設置為由字符串表示的布爾值來映射XML元素或屬性值。
Unmarshal通過將字段設置為以十進制解釋字符串值的結果將XML元素或屬性值映射到整數(shù)或浮點字段。沒有檢查溢出。
Unmarshal通過記錄元素名稱將XML元素映射到名稱。
Unmarshal通過將指針設置為新分配的值，然后將該元素映射到該值，將XML元素映射到指針。
缺少的元素或空屬性值將被解組為零值。如果該字段是切片，則會將零值附加到該字段。否則，該字段將被設置為其零值。
例
本示例演示了將XML摘錄解編到具有某些預設字段的值中。請注意，Phone字段未被修改，并且XML <Company>元素被忽略。此外，Groups字段是考慮到其標簽中提供的元素路徑分配的。
package mainimport ("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)}type Attr
Attr表示XML元素中的屬性（Name = Value）。
type Attr struct {
Name Name
Value string}type CharData
A CharData represents XML character data (raw text), in which XML escape sequences have been replaced by the characters they represent.
type CharData []byte
func (CharData) Copy
func (c CharData) Copy() CharData
type Comment
評論表示形式為<!--comment-->的XML注釋。這些字節(jié)不包括<!-- and -->注釋標記。
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 = HTMLAutoClose; // d.Entity = 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 // 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 // contains filtered or unexported fields}func NewDecoder
func NewDecoder(r io.Reader) *Decoder
NewDecoder從r中創(chuàng)建一個新的XML分析器。如果r沒有實現(xiàn)io.ByteReader，NewDecoder會自行緩沖。
func (*Decoder) Decode
func (d *Decoder) Decode(v interface{}) error解碼像Unmarshal一樣工作，除了它讀取解碼器流以查找開始元素。
func (*Decoder) DecodeElement
func (d *Decoder) DecodeElement(v interface{}, start *StartElement) errorDecodeElement的工作方式與Unmarshal類似，只不過它需要一個指向開始XML元素的指針來解碼為v。當客戶端讀取一些原始XML令牌本身時，它也很有用，但也希望延遲Unmarshal的某些元素。
func (*Decoder) InputOffset
func (d *Decoder) InputOffset() int64
InputOffset返回當前解碼器位置的輸入流字節(jié)偏移量。偏移量給出了最近返回的標記的結束位置和下一個標記的開始位置。
func (*Decoder) RawToken
func (d *Decoder) RawToken() (Token, error)
RawToken與Token類似，但不驗證開始和結束元素是否匹配，也不會將名稱空間前綴轉換為相應的URL。
func (*Decoder) Skip
func (d *Decoder) Skip() error
跳過讀取標記，直到它消耗了與已經(jīng)消耗的最近開始元素相匹配的結束元素。如果它遇到一個開始元素，它會重新出現(xiàn)，所以它可以用來跳過嵌套結構。如果找到匹配start元素的結束元素，則返回nil; 否則會返回描述問題的錯誤。
func (*Decoder) Token
func (d *Decoder) Token() (Token, error)
令牌返回輸入流中的下一個XML令牌。在輸入流結束時，令牌返回nil，io.EOF。
返回的標記數(shù)據(jù)中的字節(jié)片段指的是解析器的內部緩沖區(qū)，并且僅在下一次調用Token之前保持有效。要獲取字節(jié)的副本，請調用CopyToken或標記的Copy方法。
令牌將自閉元素擴展為由連續(xù)調用返回的獨立開始和結束元素。
令牌保證它返回的StartElement和EndElement令牌被正確嵌套和匹配：如果令牌在所有預期的結束元素之前遇到意外的結束元素或EOF，它將返回一個錯誤。
Token按照http://www.w3.org/TR/REC-xml-names/所述實現(xiàn)XML名稱空間。Token中包含的每個Name結構都將空間設置為識別其名稱空間的URL。如果令牌遇到無法識別的名稱空間前綴，它將使用前綴作為空格，而不是報告錯誤。
type Directive
指令表示<！text>格式的XML指令。字節(jié)不包含<！和>標記。
type Directive []byte
func (Directive) Copy
func (d Directive) Copy() Directive
type Encoder
編碼器將XML數(shù)據(jù)寫入輸出流。
type Encoder struct { // contains filtered or unexported fields}例
package mainimport ("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)}}func NewEncoder
func NewEncoder(w io.Writer) *Encoder
NewEncoder返回一個寫入w的新編碼器。
func (*Encoder) Encode
func (enc *Encoder) Encode(v interface{}) error編碼將v的XML編碼寫入流。
有關將Go值轉換為XML的詳細信息，請參閱Marshal的文檔。
在返回之前編碼呼叫刷新。
func (*Encoder) EncodeElement
func (enc *Encoder) EncodeElement(v interface{}, start StartElement) errorEncodeElement將v的XML編碼寫入流，使用start作為編碼中最外層的標記。
有關將Go值轉換為XML的詳細信息，請參閱Marshal的文檔。
EncodeElement在返回之前調用Flush。
func (*Encoder) EncodeToken
func (enc *Encoder) EncodeToken(t Token) error
EncodeToken將給定的XML令牌寫入流中。如果StartElement和EndElement標記沒有正確匹配，它將返回一個錯誤。
EncodeToken不會調用Flush，因為它通常是Encode或EncodeElement（或在這些操作期間調用的自定義Marshaler的MarshalXML）的較大操作的一部分，并且在完成時會調用Flush。創(chuàng)建編碼器然后直接調用EncodeToken而不使用Encode或EncodeElement的調用者在完成后需要調用Flush，以確保將XML寫入底層編寫器。
EncodeToken只允許將Target設置為“xml”的ProcInst作為流中的第一個標記。
func (*Encoder) Flush
func (enc *Encoder) Flush() error
刷新將任何緩沖的XML刷新到底層寫入器。有關何時需要的詳細信息，請參閱EncodeToken文檔。
func (*Encoder) Indent
func (enc *Encoder) Indent(prefix, indent string)
縮進將編碼器設置為生成XML，其中每個元素都以新的縮進行開頭，縮進行以前綴開頭，后跟縮進的一個或多個副本（根據(jù)嵌套深度）。
type EndElement
EndElement表示一個XML結束元素。
type EndElement struct {
Name Name}type Marshaler
Marshaler是由對象實現(xiàn)的接口，可以將自己編組為有效的XML元素。
MarshalXML將接收器編碼為零個或多個XML元素。按照慣例，數(shù)組或片通常被編碼為一系列元素，每個條目一個。不需要使用start作為元素標記，但這樣做可以使Unmarshal將XML元素與正確的struct字段進行匹配。一種常見的實現(xiàn)策略是使用與所需XML相對應的布局構造一個單獨的值，然后使用e.EncodeElement對其進行編碼。另一種常見策略是對e.EncodeToken使用重復調用來一次生成一個令牌的XML輸出。編碼令牌的序列必須組成零個或多個有效的XML元素。
type Marshaler interface { MarshalXML(e *Encoder, start StartElement) error}type MarshalerAttr
MarshalerAttr是由對象實現(xiàn)的接口，可以將自己編組為有效的XML屬性。
MarshalXMLAttr返回一個XML屬性和接收者的編碼值。使用name作為屬性名稱不是必需的，但這樣做將使Unmarshal能夠將該屬性與正確的struct字段進行匹配。如果MarshalXMLAttr返回零屬性Attr {}，則不會在輸出中生成任何屬性。MarshalXMLAttr僅用于字段標簽中具有“attr”選項的結構字段。
type MarshalerAttr interface { MarshalXMLAttr(name Name) (Attr, error)}type Name
名稱表示用名稱空間標識符（空格）注釋的XML名稱（本地）。在由Decoder.Token返回的令牌中，空間標識符是作為規(guī)范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
type StartElement
StartElement表示XML起始元素。
type StartElement struct {
Name Name
Attr []Attr}func (StartElement) Copy
func (e StartElement) Copy() StartElement
func (StartElement) End
func (e StartElement) End() EndElement
End返回相應的XML結束元素。
type SyntaxError
A SyntaxError represents a syntax error in the XML input stream.
type SyntaxError struct {
Msg string
Line int}func (*SyntaxError) Error
func (e *SyntaxError) Error() string
type TagPathError
TagPathError表示由于使用帶有沖突路徑的字段標記而導致解組過程中出現(xiàn)錯誤。
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 UnmarshalError
UnmarshalError表示解組過程中的錯誤。
type UnmarshalError string
func (UnmarshalError) Error
func (e UnmarshalError) Error() string
type Unmarshaler
Unmarshaler是可以解組自己的XML元素描述的對象實現(xiàn)的接口。
UnmarshalXML解碼從給定的開始元素開始的單個XML元素。如果它返回一個錯誤，對Unmarshal的外部調用將停止并返回該錯誤。UnmarshalXML必須使用一個XML元素。一種常見的實現(xiàn)策略是使用d.DecodeElement解組為一個單獨的值，其布局與預期的XML匹配，然后將該值中的數(shù)據(jù)復制到接收器中。另一個常用策略是使用d.Token一次處理XML對象的一個令牌。UnmarshalXML不能使用d.RawToken。
type Unmarshaler interface { UnmarshalXML(d *Decoder, start StartElement) error}type UnmarshalerAttr
UnmarshalerAttr是由可以解組自己的XML屬性描述的對象實現(xiàn)的接口。
UnmarshalXMLAttr解碼單個XML屬性。如果它返回一個錯誤，對Unmarshal的外部調用將停止并返回該錯誤。UnmarshalXMLAttr僅用于字段標簽中具有“attr”選項的結構字段。
type UnmarshalerAttr interface { UnmarshalXMLAttr(attr Attr) error}type UnsupportedTypeError
MarshalXMLError在Marshal遇到無法轉換為XML的類型時返回。
type UnsupportedTypeError struct {
Type reflect.Type}func (*UnsupportedTypeError) Error
func (e *UnsupportedTypeError) Error() string
錯誤
?XML 元素和數(shù)據(jù)結構之間的映射本質上是有缺陷的：XML元素是匿名值的依賴于順序的集合，而數(shù)據(jù)結構是與命令值無關的順序無關集合。查看包json以獲得更適合數(shù)據(jù)結構的文本表示。