Пакет xml
Обзор
Пакет xml реализует простой парсер XML 1.0, понимающий XML-пространства имен.
Пример (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
}
Индекс
Файлы пакета
marshal.go read.go typeinfo.go xml.go
Константы
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"
) Переменные
HTMLAutoClose — набор HTML-элементов, которые должны считаться автоматически закрывающимися.
См. документацию по полям [Decoder.Strict] и [Decoder.Entity].
var HTMLAutoClose []string = htmlAutoClose
HTMLEntity — карта сущностей, содержащая переводы стандартных символов HTML-сущностей.
См. документацию по полям [Decoder.Strict] и [Decoder.Entity].
var HTMLEntity map[string]string = htmlEntity
функция Escape
func Escape(w io.Writer, s []byte)
Escape подобна EscapeText, но опускает возвращаемое значение ошибки. Она предоставляется для обратной совместимости с Go 1.0. Код, нацеленный на Go 1.1 или более поздние версии, должен использовать EscapeText.
функция EscapeText 1.1
func EscapeText(w io.Writer, s []byte) error
EscapeText записывает в w должным образом экранированный XML-эквивалент необработанных данных s.
функция Marshal
func Marshal(v any) ([]byte, error)
Marshal возвращает XML-кодирование v.
Marshal обрабатывает массив или срез, сериализуя каждый из элементов. Marshal обрабатывает указатель, сериализуя значение, на которое он указывает, или, если указатель равен nil, ничего не записывая. Marshal обрабатывает значение интерфейса, сериализуя содержащееся в нём значение или, если значение интерфейса равно nil, ничего не записывая. Marshal обрабатывает все другие данные, записывая один или несколько XML-элементов, содержащих данные.
Имя для XML-элементов берется, в порядке предпочтения:
- тега поля XMLName, если данные являются структурой
- значения поля XMLName типа Name
- тега поля структуры, используемого для получения данных
- имени поля структуры, используемого для получения данных
- имени сериализуемого типа
XML-элемент для структуры содержит сериализованные элементы для каждого экспортированного поля структуры, с этими исключениями:
- поле XMLName, описанное выше, пропускается.
- поле с тегом "-" пропускается.
- поле с тегом "name,attr" становится атрибутом с заданным именем в XML-элементе.
- поле с тегом ",attr" становится атрибутом с именем поля в XML-элементе.
- поле с тегом ",chardata" записывается как текстовые данные, а не как XML-элемент.
- поле с тегом ",cdata" записывается как текстовые данные, заключённые в один или несколько тегов <![CDATA[ ... ]]>, а не как XML-элемент.
- поле с тегом ",innerxml" записывается дословно, не подвергаясь обычной процедуре сериализации.
- поле с тегом ",comment" записывается как XML-комментарий, не подвергаясь обычной процедуре сериализации. Оно не должно содержать строку "--" внутри.
- поле с тегом, включающим опцию "omitempty", пропускается, если значение поля пустое. Пустые значения — false, 0, любой nil указатель или значение интерфейса, а также любой массив, срез, карта или строка длиной ноль.
- анонимное поле структуры обрабатывается так, как если бы поля его значения были частью внешней структуры.
- поле, реализующее Marshaler, записывается путём вызова его метода MarshalXML.
- поле, реализующее encoding.TextMarshaler, записывается путём кодирования результата его метода MarshalText в виде текста.
Если поле использует тег "a>b>c", то элемент c будет вложен внутри родительских элементов a и b. Поля, которые появляются рядом друг с другом и называют один и тот же родительский элемент, будут заключены в один XML-элемент.
Если XML-имя для поля структуры определено как тегом поля, так и полем XMLName структуры, имена должны совпадать.
См. MarshalIndent для примера.
Marshal вернёт ошибку, если попросят сериализовать канал, функцию или карту.
функция MarshalIndent
func MarshalIndent(v any, prefix, indent string) ([]byte, error)
MarshalIndent работает как Marshal, но каждый XML-элемент начинается с новой отступаемой строки, которая начинается с prefix и сопровождается одним или несколькими повторениями 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>
функция Unmarshal
func Unmarshal(data []byte, v any) error
Unmarshal анализирует закодированные в XML данные и сохраняет результат в значении, на которое указывает 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 сопоставляет XML-элемент со строкой или []byte, сохраняя конкатенацию символьных данных этого элемента в строке или []byte. Сохранённый []byte никогда не равен nil.
Unmarshal сопоставляет значение атрибута со строкой или []byte, сохраняя значение в строке или срезе.
Unmarshal сопоставляет значение атрибута с Attr, сохраняя атрибут, включая его имя, в Attr.
Unmarshal сопоставляет значение XML-элемента или атрибута со срезом, увеличивая длину среза и сопоставляя элемент или атрибут с новым созданным значением.
Unmarshal сопоставляет значение XML-элемента или атрибута с bool, установив его в булевое значение, представленное строкой. Пробелы обрезаются и игнорируются.
Unmarshal сопоставляет значение 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}
тип Attr
Attr представляет атрибут в XML-элементе (Name=Value).
type Attr struct {
Name Name
Value string
}
тип CharData
CharData представляет символьные данные XML (необработанный текст), в котором XML-последовательности escape заменены соответствующими символами.
type CharData []byte
функция (CharData) Copy
func (c CharData) Copy() CharData
Copy создаёт новую копию CharData.
тип Comment
Comment представляет XML-комментарий в формате <!--comment-->. Байты не включают маркеры комментария <!-- и -->.
type Comment []byte
функция (Comment) Copy
func (c Comment) Copy() Comment
Copy создаёт новую копию Comment.
тип Decoder
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
}
функция NewDecoder
func NewDecoder(r io.Reader) *Decoder
NewDecoder создаёт новый XML-парсер, читающий из r. Если r не реализует io.ByteReader, NewDecoder будет осуществлять собственное буферирование.
функция NewTokenDecoder 1.10
func NewTokenDecoder(t TokenReader) *Decoder
NewTokenDecoder создаёт новый XML-парсер, используя подчинённый поток маркеров.
функция (*Decoder) Decode
func (d *Decoder) Decode(v any) error
Decode работает как Unmarshal, за исключением того, что он считывает поток декодера, чтобы найти стартовый элемент.
функция (*Decoder) DecodeElement
func (d *Decoder) DecodeElement(v any, start *StartElement) error
DecodeElement работает как Unmarshal, за исключением того, что он принимает указатель на стартовый XML-элемент для распаковки в v. Это полезно, когда клиент читает некоторые исходные XML-маркеры самостоятельно, но также хочет отложить Unmarshal для некоторых элементов.
функция (*Decoder) InputOffset 1.4
func (d *Decoder) InputOffset() int64
InputOffset возвращает смещение байта входного потока текущей позиции декодера. Смещение указывает расположение конца последнего возвращённого маркера и начала следующего маркера.
функция (*Decoder) InputPos 1.19
func (d *Decoder) InputPos() (line, column int)
InputPos возвращает строку текущей позиции декодера и 1-основанное положение в строке. Позиция указывает расположение конца последнего возвращённого маркера.
функция (*Decoder) RawToken
func (d *Decoder) RawToken() (Token, error)
RawToken подобен Decoder.Token, но не проверяет, что стартовые и конечные элементы совпадают, и не преобразует префиксы пространства имён в соответствующие URL-адреса.
функция (*Decoder) Skip
func (d *Decoder) Skip() error
Skip считывает маркеры до тех пор, пока не потребляется конечный элемент, соответствующий последнему прочитанному начальному элементу, пропуская вложенные структуры. Возвращает nil, если находит конечный элемент, соответствующий начальному элементу; в противном случае возвращает ошибку, описывающую проблему.
функция (*Decoder) Token
func (d *Decoder) Token() (Token, error)
Token возвращает следующий XML-маркер в входном потоке. В конце входного потока Token возвращает nil, io.EOF.
Срезы байтов в возвращаемых данных маркера ссылаются на внутренний буфер парсера и остаются допустимыми только до следующего вызова Token. Для получения копии байтов вызовите CopyToken или метод Copy маркера.
Token расширяет самозакрывающиеся элементы, такие как <br>, в отдельные начальные и конечные элементы, возвращаемые последовательными вызовами.
Token гарантирует, что маркеры StartElement и EndElement, которые он возвращает, правильно вложены и сопоставлены: если Token встречает неожиданный конечный элемент или EOF, прежде чем все ожидаемые конечные элементы, он вернёт ошибку.
Если [Decoder.CharsetReader] вызывается и возвращает ошибку, ошибка обертывается и возвращается.
Token реализует XML-пространства имён, как описано в https://www.w3.org/TR/REC-xml-names/. Каждая из структур Name, содержащихся в Token, имеет Space, установленный в URL, идентифицирующий его пространство имён, если оно известно. Если Token встречает нераспознанный префикс пространства имён, он использует префикс как Space вместо сообщения об ошибке.
тип Directive
Directive представляет XML-директиву в формате <!text>. Байты не включают маркеры <! и >.
type Directive []byte
функция (Directive) Copy
func (d Directive) Copy() Directive
Copy создаёт новую копию Directive.
тип Encoder
Encoder записывает XML-данные в выходной поток.
type Encoder struct {
// contains filtered or unexported fields
}
Пример
Код:
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>
функция NewEncoder
func NewEncoder(w io.Writer) *Encoder
NewEncoder возвращает новый кодировщик, который записывает в w.
функция (*Encoder) Close 1.20
func (enc *Encoder) Close() error
Закрывает Encoder, указывая, что больше данных не будет записано. Он сбрасывает любой буферизованный XML в подчинённый writer и возвращает ошибку, если записанный XML некорректен (например, содержит незакрытые элементы).
функция (*Encoder) Encode
func (enc *Encoder) Encode(v any) error
Encode записывает XML-кодирование v в поток.
См. документацию для Marshal для получения подробностей о преобразовании значений Go в XML.
Encode вызывает Encoder.Flush перед возвратом.
функция (*Encoder) EncodeElement 1.2
func (enc *Encoder) EncodeElement(v any, start StartElement) error
EncodeElement записывает XML-кодирование v в поток, используя start в качестве самого внешнего тега при кодировании.
См. документацию для Marshal для получения подробностей о преобразовании значений Go в XML.
EncodeElement вызывает Encoder.Flush перед возвратом.
функция (*Encoder) EncodeToken 1.2
func (enc *Encoder) EncodeToken(t Token) error
EncodeToken записывает данный XML-маркер в поток. Он возвращает ошибку, если маркеры StartElement и EndElement не сопоставлены должным образом.
EncodeToken не вызывает Encoder.Flush, поскольку обычно он является частью более крупной операции, такой как Encoder.Encode или Encoder.EncodeElement (или вызов MarshalXML пользовательского Marshaler во время этих операций), и те вызовут Flush по завершении. Вызывающие функции, которые создают Encoder и затем вызывают EncodeToken напрямую, не используя Encode или EncodeElement, должны вызвать Flush по завершении, чтобы убедиться, что XML записан в подлежащий записывающему элементу.
EncodeToken позволяет записать ProcInst с Target, установленным в «xml», только как первый маркер в потоке.
func (*Encoder) Flush 1.2
func (enc *Encoder) Flush() error
Flush очищает любой буферизованный XML в подлежащем записывающем элементе. См. документацию Encoder.EncodeToken для получения подробностей о необходимости этого.
func (*Encoder) Indent 1.1
func (enc *Encoder) Indent(prefix, indent string)
Indent настраивает кодировщик на генерирование XML, в котором каждый элемент начинается с новой отступаемой строки, которая начинается с префикса и за которым следуют одна или несколько копий отступа в соответствии с глубиной вложенности.
type EndElement
EndElement представляет собой конечный элемент XML.
type EndElement struct {
Name Name
}
type Marshaler 1.2
Marshaler — это интерфейс, реализуемый объектами, которые могут сериализовать сами себя в допустимые XML-элементы.
MarshalXML кодирует получателя как ноль или более XML-элементов. По соглашению, массивы или срезы обычно кодируются как последовательность элементов, по одному на элемент. Использование start в качестве тега элемента необязательно, но это позволит Unmarshal сопоставить XML-элементы с соответствующим полем структуры. Один распространённый подход к реализации — создание отдельной переменной с макетом, соответствующим желаемому 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 сопоставить атрибут с соответствующим полем структуры. Если MarshalXMLAttr возвращает нулевой атрибут Attr{}, атрибут не будет сгенерирован в выводе. MarshalXMLAttr используется только для полей структуры с опцией «attr» в теге поля.
type MarshalerAttr interface {
MarshalXMLAttr(name Name) (Attr, error)
} type Name
Name представляет собой имя XML (Local), снабжённое идентификатором пространства имён (Space). В маркерах, возвращаемых Decoder.Token, идентификатор пространства задаётся как канонический URL, а не короткое префиксное имя, используемое в анализируемом документе.
type Name struct {
Space, Local string
}
type ProcInst
ProcInst представляет собой XML-инструкцию обработки формата <?target inst?>
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 any
func CopyToken
func CopyToken(t Token) Token
CopyToken возвращает копию Token.
type TokenReader 1.10
TokenReader — это всё, что может декодировать поток XML-маркеров, включая Decoder.
Когда Token сталкивается с ошибкой или концом файла после успешной обработки маркера, он возвращает маркер. Он может вернуть ошибку (не null) из того же вызова или вернуть ошибку (и null-маркер) из последующего вызова. Примером общего случая является то, что TokenReader, возвращающий не-null маркер в конце потока маркеров, может вернуть либо io.EOF, либо null-ошибку. Следующий Read должен вернуть null, io.EOF.
Реализация Token не рекомендуется для возвращения null-маркера с null-ошибкой. Вызывающие функции должны интерпретировать возврат null, null как индикацию, что ничего не произошло; в частности, это не означает 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 декодирует один XML-элемент, начиная с заданного начального элемента. Если он возвращает ошибку, внешний вызов Unmarshal прекращается и возвращает эту ошибку. UnmarshalXML должен потреблять ровно один XML-элемент. Один распространённый подход к реализации — распаковать в отдельную переменную с макетом, соответствующим ожидаемому XML, с помощью d.DecodeElement, а затем скопировать данные из этой переменной в получатель. Другой распространённый подход — использовать 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
UnsupportedTypeError возвращается, когда Marshal сталкивается с типом, который нельзя преобразовать в XML.
type UnsupportedTypeError struct {
Type reflect.Type
}
func (*UnsupportedTypeError) Error
func (e *UnsupportedTypeError) Error() string
Ошибки
- ☞
Сопоставление между XML-элементами и структурами данных изначально имеет недостатки: XML-элемент — это зависимая от порядка коллекция анонимных значений, в то время как структура данных — это независимая от порядка коллекция именованных значений. См. encoding/json для текстового представления, более подходящего для структур данных.
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/encoding/xml/
