Пакет 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
func Escape
func Escape(w io.Writer, s []byte)
Escape похожа на EscapeText, но не возвращает значение ошибки. Она предоставлена для обратной совместимости с Go 1.0. В коде, предназначенном для Go 1.1 и новее, следует использовать EscapeText.
func EscapeText 1.1
func EscapeText(w io.Writer, s []byte) error
EscapeText записывает в w корректно экранированное XML-представление обычных текстовых данных s.
func 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-указатель или nil-значение интерфейсного типа, а также массив, срез, карта или строка нулевой длины.
- анонимное поле структуры обрабатывается так, как если бы поля его значения входили во внешнюю структуру.
- анонимное поле структуры интерфейсного типа обрабатывается так, как если бы именем поля был этот тип, а не как анонимное поле.
- поле, реализующее Marshaler, записывается вызовом его метода MarshalXML.
- поле, реализующее encoding.TextMarshaler, записывается путем кодирования результата его метода MarshalText как текста.
Если в поле используется тег "a>b>c", элемент c будет вложен в родительские элементы a и b. Соседние поля, указывающие на одного и того же родителя, будут заключены в один XML-элемент.
Если имя XML для поля структуры задано и тегом поля, и полем XMLName структуры, эти имена должны совпадать.
Пример см. в разделе MarshalIndent.
Marshal вернет ошибку, если ей передать канал, функцию или карту.
func 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>
func 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}
type Attr
Attr представляет атрибут XML-элемента (Name=Value).
type Attr struct {
Name Name
Value string
}
type CharData
CharData представляет символьные данные XML (обычный текст), в которых XML-последовательности экранирования заменены символами, которые они обозначают.
type CharData []byte
func (CharData) Copy
func (c CharData) Copy() CharData
Copy создает копию CharData.
type Comment
Comment представляет XML-комментарий вида <!--comment-->. Байты не включают маркеры комментария <!-- и -->.
type Comment []byte
func (Comment) Copy
func (c Comment) Copy() Comment
Copy создает копию Comment.
type 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
}
func NewDecoder
func NewDecoder(r io.Reader) *Decoder
NewDecoder создает новый XML-парсер, считывающий данные из r. Если r не реализует io.ByteReader, NewDecoder будет выполнять буферизацию самостоятельно.
func NewTokenDecoder 1.10
func NewTokenDecoder(t TokenReader) *Decoder
NewTokenDecoder создает новый 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-токены, но для обработки некоторых элементов хочет использовать Unmarshal.
func (*Decoder) InputOffset 1.4
func (d *Decoder) InputOffset() int64
InputOffset возвращает смещение в байтах во входном потоке для текущей позиции декодера. Смещение указывает на конец последнего возвращенного токена и начало следующего токена.
func (*Decoder) InputPos 1.19
func (d *Decoder) InputPos() (line, column int)
InputPos возвращает номер строки для текущей позиции декодера и позицию во входной строке, отсчитываемую от 1. Позиция указывает на конец последнего возвращенного токена.
func (*Decoder) RawToken
func (d *Decoder) RawToken() (Token, error)
RawToken похож на Decoder.Token, но не проверяет соответствие начальных и конечных элементов и не преобразует префиксы пространств имен в соответствующие URL.
func (*Decoder) Skip
func (d *Decoder) Skip() error
Skip считывает токены, пока не встретит конечный элемент, соответствующий последнему уже считанному начальному элементу, пропуская вложенные структуры. Метод возвращает nil, если находит конечный элемент, соответствующий начальному; в противном случае он возвращает ошибку с описанием проблемы.
func (*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, а не сообщает об ошибке.
type Directive
Directive представляет директиву XML вида <!text>. Байты не включают маркеры <! и >.
type Directive []byte
func (Directive) Copy
func (d Directive) Copy() Directive
Copy создает копию Directive.
type 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>
func NewEncoder
func NewEncoder(w io.Writer) *Encoder
NewEncoder возвращает новый кодировщик, который записывает данные в w.
func (*Encoder) Close 1.20
func (enc *Encoder) Close() error
Close закрывает Encoder, указывая, что больше данные записываться не будут. Метод сбрасывает все буферизованные данные XML в базовый поток записи и возвращает ошибку, если записанный XML некорректен (например, содержит незакрытые элементы).
func (*Encoder) Encode
func (enc *Encoder) Encode(v any) error
Encode записывает XML-кодирование значения v в поток.
Подробные сведения о преобразовании значений Go в XML см. в документации к Marshal.
Перед возвратом Encode вызывает Encoder.Flush.
func (*Encoder) EncodeElement 1.2
func (enc *Encoder) EncodeElement(v any, start StartElement) error
EncodeElement записывает XML-кодирование значения v в поток, используя start в качестве внешнего тега кодирования.
Подробные сведения о преобразовании значений Go в XML см. в документации к Marshal.
Перед возвратом EncodeElement вызывает Encoder.Flush.
func (*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 начинался с новой строки с отступом: сначала записывается prefix, затем одна или несколько копий indent в соответствии с глубиной вложенности.
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, идентификатор Space задается в виде канонического 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 обнаруживает ошибку или конец файла после успешного считывания токена, он возвращает этот токен. Ошибка, не равная nil, может быть возвращена в том же вызове или в последующем вызове вместе с nil-токеном. Пример такого общего случая: TokenReader, возвращающий токен, не равный nil, в конце потока токенов, может вернуть io.EOF или ошибку nil. Следующий вызов Read должен вернуть nil, io.EOF.
Реализациям Token не рекомендуется возвращать nil-токен вместе с ошибкой 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 декодирует один 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/
