mirror of
https://github.com/golang/go
synced 2024-09-18 15:32:18 +00:00
encoding/xml, encoding/json: docs and examples using custom marshalers
Both the encoding/xml and encoding/json packages support custom marshalers for JSON and XML, as well as the basic encoding.TextMarshaler and encoding.TextUnmarshaler interfaces, but the docs and examples for these are missing. There are docs for how to use encoding.TextMarshaler and encoding.TextUnmarshaler in encoding/json, but not encoding/xml. There are no examples for how to use them with either json or xml. This commit includes docs for encoding/xml and examples for both encoding/json and encoding/xml. There is an example using custom marshalers MarshalJSON and UnmarshalJSON in encoding/json, but not MarshalXML and UnmarshalXML in encoding/json. These docs are more so necessary for encoding/xml because the complexities of XML documents is significantly greater than JSON documents which more often leads to the need for custom marshaling. The encoding/json package includes an example of how to write a custom marshaler, and this commit includes the same example for the xml package. All examples are mirrored off the existing custom marshaler example in encoding/json. Fixes #6859 Change-Id: Ic93abc27c0b4d5e48dea6ede4e20b1bedca4ab39 Reviewed-on: https://go-review.googlesource.com/c/76350 Run-TryBot: Ian Lance Taylor <iant@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Ian Lance Taylor <iant@golang.org>
This commit is contained in:
parent
321a3d6e85
commit
d70b0ece2f
67
src/encoding/json/example_text_marshaling_test.go
Normal file
67
src/encoding/json/example_text_marshaling_test.go
Normal file
|
@ -0,0 +1,67 @@
|
||||||
|
// Copyright 2018 The Go Authors. All rights reserved.
|
||||||
|
// Use of this source code is governed by a BSD-style
|
||||||
|
// license that can be found in the LICENSE file.
|
||||||
|
|
||||||
|
package json_test
|
||||||
|
|
||||||
|
import (
|
||||||
|
"encoding/json"
|
||||||
|
"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_textMarshalJSON() {
|
||||||
|
blob := `["small","regular","large","unrecognized","small","normal","small","large"]`
|
||||||
|
var inventory []Size
|
||||||
|
if err := json.Unmarshal([]byte(blob), &inventory); err != nil {
|
||||||
|
log.Fatal(err)
|
||||||
|
}
|
||||||
|
|
||||||
|
counts := make(map[Size]int)
|
||||||
|
for _, size := range inventory {
|
||||||
|
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
|
||||||
|
}
|
84
src/encoding/xml/example_marshaling_test.go
Normal file
84
src/encoding/xml/example_marshaling_test.go
Normal file
|
@ -0,0 +1,84 @@
|
||||||
|
// Copyright 2018 The Go Authors. All rights reserved.
|
||||||
|
// Use of this source code is governed by a BSD-style
|
||||||
|
// license that can be found in the LICENSE file.
|
||||||
|
|
||||||
|
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
|
||||||
|
}
|
79
src/encoding/xml/example_text_marshaling_test.go
Normal file
79
src/encoding/xml/example_text_marshaling_test.go
Normal file
|
@ -0,0 +1,79 @@
|
||||||
|
// Copyright 2018 The Go Authors. All rights reserved.
|
||||||
|
// Use of this source code is governed by a BSD-style
|
||||||
|
// license that can be found in the LICENSE file.
|
||||||
|
|
||||||
|
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
|
||||||
|
}
|
|
@ -61,6 +61,10 @@ const (
|
||||||
// string of length zero.
|
// string of length zero.
|
||||||
// - an anonymous struct field is handled as if the fields of its
|
// - an anonymous struct field is handled as if the fields of its
|
||||||
// value were part of the outer struct.
|
// value were part of the outer struct.
|
||||||
|
// - a field implementing Marshaler is written by calling its MarshalXML
|
||||||
|
// method.
|
||||||
|
// - a field implementing encoding.TextMarshaler is written by encoding the
|
||||||
|
// result of its MarshalText method as text.
|
||||||
//
|
//
|
||||||
// If a field uses a tag "a>b>c", then the element c will be nested inside
|
// If a field uses a tag "a>b>c", then the element c will be nested inside
|
||||||
// parent elements a and b. Fields that appear next to each other that name
|
// parent elements a and b. Fields that appear next to each other that name
|
||||||
|
|
|
@ -92,6 +92,11 @@ import (
|
||||||
//
|
//
|
||||||
// * A struct field with tag "-" is never unmarshaled into.
|
// * A struct field with tag "-" is never unmarshaled into.
|
||||||
//
|
//
|
||||||
|
// If Unmarshal encounters a field type that implements the Unmarshaler
|
||||||
|
// interface, Unmarshal calls its UnmarshalXML method to produce the value from
|
||||||
|
// the XML element. Otherwise, if the value implements
|
||||||
|
// encoding.TextUnmarshaler, Unmarshal calls that value's UnmarshalText method.
|
||||||
|
//
|
||||||
// Unmarshal maps an XML element to a string or []byte by saving the
|
// Unmarshal maps an XML element to a string or []byte by saving the
|
||||||
// concatenation of that element's character data in the string or
|
// concatenation of that element's character data in the string or
|
||||||
// []byte. The saved []byte is never nil.
|
// []byte. The saved []byte is never nil.
|
||||||
|
|
Loading…
Reference in a new issue