xml

package
v1.22.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 15, 2024 License: Apache-2.0 Imports: 9 Imported by: 56

Documentation

Overview

Package xml holds the XMl encoder utility. This utility is written in accordance to our design to delegate to shape serializer function in which a xml.Value will be passed around.

Resources followed: https://smithy.io/2.0/spec/protocol-traits.html#xml-bindings

Member Element

Member element should be used to encode xml shapes into xml elements except for flattened xml shapes. Member element write their own element start tag. These elements should always be closed.

Flattened Element

Flattened element should be used to encode shapes marked with flattened trait into xml elements. Flattened element do not write a start tag, and thus should not be closed.

Simple types encoding

All simple type methods on value such as String(), Long() etc; auto close the associated member element.

Array

Array returns the collection encoder. It has two modes, wrapped and flattened encoding.

Wrapped arrays have two methods Array() and ArrayWithCustomName() which facilitate array member wrapping. By default, a wrapped array members are wrapped with `member` named start element. 

<wrappedArray><member>apple</member><member>tree</member></wrappedArray>

Flattened arrays rely on Value being marked as flattened. If a shape is marked as flattened, Array() will use the shape element name as wrapper for array elements. 

<flattenedAarray>apple</flattenedArray><flattenedArray>tree</flattenedArray>

Map

Map is the map encoder. It has two modes, wrapped and flattened encoding.

Wrapped map has Array() method, which facilitate map member wrapping. By default, a wrapped map members are wrapped with `entry` named start element. 

<wrappedMap><entry><Key>apple</Key><Value>tree</Value></entry><entry><Key>snow</Key><Value>ice</Value></entry></wrappedMap>

Flattened map rely on Value being marked as flattened. If a shape is marked as flattened, Map() will use the shape element name as wrapper for map entry elements. 

<flattenedMap><Key>apple</Key><Value>tree</Value></flattenedMap><flattenedMap><Key>snow</Key><Value>ice</Value></flattenedMap>

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func FetchRootElement 

func FetchRootElement(decoder *xml.Decoder) (startElement xml.StartElement, err error)

FetchRootElement takes in a decoder and returns the first start element within the xml body. This function is useful in fetching the start element of an XML response and ignore the comments and preamble

Types

type Array 

type Array struct {
	// contains filtered or unexported fields
}

Array represents the encoding of a XML array type

func (*Array) Member 

func (a *Array) Member() Value

Member adds a new member to the XML array. It returns a Value encoder.

type Attr 

type Attr struct {
	Name  Name
	Value string
}

An Attr represents an attribute in an XML element (Name=Value).

func NewAttribute 

func NewAttribute(local, value string) Attr

NewAttribute returns a pointer to an attribute. It takes in a local name aka attribute name, and value representing the attribute value.

func NewNamespaceAttribute 

func NewNamespaceAttribute(local, value string) Attr

NewNamespaceAttribute returns a pointer to an attribute. It takes in a local name aka attribute name, and value representing the attribute value.

NewNamespaceAttribute appends `xmlns:` in front of namespace prefix.

For creating a name space attribute representing `xmlns:prefix="http://example.com`, the breakdown would be: local = "prefix" value = "http://example.com"

type Encoder 

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder is an XML encoder that supports construction of XML values using methods. The encoder takes in a writer and maintains a scratch buffer.

Example

ExampleEncoder is the example function on how to use an encoder 

package main

import (
	"bytes"
	"log"

	"github.com/aws/smithy-go/encoding/xml"
)

var root = xml.StartElement{Name: xml.Name{Local: "root"}}

func main() {
	b := bytes.NewBuffer(nil)
	encoder := xml.NewEncoder(b)

	// expected encoded xml document is :
	// `<root><liststr><namedMember><value>abc</value></namedMember><namedMember><value>123</value></namedMember></liststr></root>`
	defer log.Printf("Encoded xml document: %v", encoder.String())

	r := encoder.RootElement(root)
	defer r.Close()

	// Object key `liststr`
	liststr := xml.StartElement{Name: xml.Name{Local: "liststr"}}
	namedMember := xml.StartElement{Name: xml.Name{Local: "namedMember"}}

	// member element
	m := r.MemberElement(liststr)
	defer m.Close()

	// Build array
	a := m.ArrayWithCustomName(namedMember)

	value := xml.StartElement{Name: xml.Name{Local: "value"}}
	m1 := a.Member()
	m1.MemberElement(value).String("abc")
	m1.Close()

	m2 := a.Member()
	m2.MemberElement(value).Integer(123)
	m2.Close()
}

Output:

func NewEncoder 

func NewEncoder(w writer) *Encoder

NewEncoder returns an XML encoder

func (Encoder) Bytes 

func (e Encoder) Bytes() []byte

Bytes returns the []byte slice of the XML encoder

func (Encoder) RootElement 

func (e Encoder) RootElement(element StartElement) Value

RootElement builds a root element encoding It writes it's start element tag. The value should be closed.

func (Encoder) String 

func (e Encoder) String() string

String returns the string output of the XML encoder

type EndElement 

type EndElement struct {
	Name Name
}

An EndElement represents an XML end element.

type ErrorComponents 

type ErrorComponents struct {
	Code    string
	Message string
}

ErrorComponents represents the error response fields that will be deserialized from an xml error response body

func GetErrorResponseComponents 

func GetErrorResponseComponents(r io.Reader, noErrorWrapping bool) (ErrorComponents, error)

GetErrorResponseComponents returns the error fields from an xml error response body

type Map 

type Map struct {
	// contains filtered or unexported fields
}

Map represents the encoding of a XML map type

func (*Map) Entry 

func (m *Map) Entry() Value

Entry returns a Value encoder with map's element. It writes the member wrapper start tag for each entry.

type Name 

type Name struct {
	Space, Local string
}

A Name represents an XML name (Local) annotated with a name space identifier (Space). In tokens returned by Decoder.Token, the Space identifier is given as a canonical URL, not the short prefix used in the document being parsed.

type NodeDecoder 

type NodeDecoder struct {
	Decoder *xml.Decoder
	StartEl xml.StartElement
}

NodeDecoder is a XML decoder wrapper that is responsible to decoding a single XML Node element and it's nested member elements. This wrapper decoder takes in the start element of the top level node being decoded.

func WrapNodeDecoder 

func WrapNodeDecoder(decoder *xml.Decoder, startEl xml.StartElement) NodeDecoder

WrapNodeDecoder returns an initialized XMLNodeDecoder

func (NodeDecoder) GetElement 

func (d NodeDecoder) GetElement(name string) (t xml.StartElement, err error)

GetElement looks for the given tag name at the current level, and returns the element if found, and skipping over non-matching elements. Returns an error if the node is not found, or if an error occurs while walking the document.

func (NodeDecoder) Token 

func (d NodeDecoder) Token() (t xml.StartElement, done bool, err error)

Token on a Node Decoder returns a xml StartElement. It returns a boolean that indicates the a token is the node decoder's end node token; and an error which indicates any error that occurred while retrieving the start element

func (NodeDecoder) Value 

func (d NodeDecoder) Value() (c []byte, err error)

Value provides an abstraction to retrieve char data value within an xml element. The method will return an error if it encounters a nested xml element instead of char data. This method should only be used to retrieve simple type or blob shape values as []byte.

type StartElement 

type StartElement struct {
	Name Name
	Attr []Attr
}

A StartElement represents an XML start element.

func (StartElement) Copy 

func (e StartElement) Copy() StartElement

Copy creates a new copy of StartElement.

func (StartElement) End 

func (e StartElement) End() EndElement

End returns the corresponding XML end element.

type Value 

type Value struct {
	// contains filtered or unexported fields
}

Value represents an XML Value type XML Value types: Object, Array, Map, String, Number, Boolean.

func (Value) Array 

func (xv Value) Array() *Array

Array returns an array encoder. By default, the members of array are wrapped with `<member>` element tag. If value is marked as flattened, the start element is used to wrap the members instead of the `<member>` element.

func (Value) ArrayWithCustomName 

func (xv Value) ArrayWithCustomName(element StartElement) *Array

ArrayWithCustomName returns an array encoder.

It takes named start element as an argument, the named start element will used to wrap xml array entries. for eg, `<someList><customName>entry1</customName></someList>` Here `customName` named start element will be wrapped on each array member.

func (Value) Base64EncodeBytes 

func (xv Value) Base64EncodeBytes(v []byte)

Base64EncodeBytes writes v as a base64 value in XML string. It will auto close the parent xml element tag.

func (Value) BigDecimal 

func (xv Value) BigDecimal(v *big.Float)

BigDecimal encodes v big.Float as XML value. It will auto close the parent xml element tag.

func (Value) BigInteger 

func (xv Value) BigInteger(v *big.Int)

BigInteger encodes v big.Int as XML value. It will auto close the parent xml element tag.

func (Value) Boolean 

func (xv Value) Boolean(v bool)

Boolean encodes v as a XML boolean. It will auto close the parent xml element tag.

func (Value) Byte 

func (xv Value) Byte(v int8)

Byte encodes v as a XML number. It will auto close the parent xml element tag.

func (Value) Close 

func (xv Value) Close()

Close closes the value.

func (Value) Double 

func (xv Value) Double(v float64)

Double encodes v as a XML number. It will auto close the parent xml element tag.

func (Value) FlattenedElement 

func (xv Value) FlattenedElement(element StartElement) Value

FlattenedElement returns flattened element encoding. It returns a Value. This method should be used for flattened shapes.

Unlike MemberElement, flattened element will NOT write element tags directly for the associated start element.

The value returned by the FlattenedElement does not need to be closed.

func (Value) Float 

func (xv Value) Float(v float32)

Float encodes v as a XML number. It will auto close the parent xml element tag.

func (Value) Integer 

func (xv Value) Integer(v int32)

Integer encodes v as a XML number. It will auto close the parent xml element tag.

func (Value) IsFlattened 

func (xv Value) IsFlattened() bool

IsFlattened returns true if value is for flattened shape.

func (Value) Long 

func (xv Value) Long(v int64)

Long encodes v as a XML number. It will auto close the parent xml element tag.

func (Value) Map 

func (xv Value) Map() *Map

Map returns a map encoder. By default, the map entries are wrapped with `<entry>` element tag.

If value is marked as flattened, the start element is used to wrap the entry instead of the `<member>` element.

func (Value) MemberElement 

func (xv Value) MemberElement(element StartElement) Value

MemberElement does member element encoding. It returns a Value. Member Element method should be used for all shapes except flattened shapes.

A call to MemberElement will write nested element tags directly using the provided start element. The value returned by MemberElement should be closed.

func (Value) Short 

func (xv Value) Short(v int16)

Short encodes v as a XML number. It will auto close the parent xml element tag.

func (Value) String 

func (xv Value) String(v string)

String encodes v as a XML string. It will auto close the parent xml element tag.

func (Value) Write 

func (xv Value) Write(v []byte, escapeXMLText bool)

Write writes v directly to the xml document if escapeXMLText is set to true, write will escape text. It will auto close the parent xml element tag.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.