xmlstream

Documentation

Overview

Package xmlstream provides a namespace-aware streaming XML reader built on xmltext. It exposes zero-copy event slices with explicit lifetimes and helper APIs for subtree copying and streaming unmarshaling.

Index

• Constants
• Variables
• func JoinOptions(opts ...Option) xmltext.Options
• type Attr
• type ElementID
• type Event
  • func (e Event) Attr(namespace, local string) ([]byte, bool)
  • func (e Event) AttrLocal(local string) ([]byte, bool)
• type EventKind
  • func (k EventKind) String() string
• type NameID
• type NamespaceDecl
• type Option
• type QName
• type RawAttr
• type RawEvent
  • func (e RawEvent) Attr(prefix, local []byte) ([]byte, bool)
  • func (e RawEvent) AttrLocal(local []byte) ([]byte, bool)
• type RawName
  • func (n RawName) HasLocal(local []byte) bool
• type Reader
  • func NewReader(r io.Reader, opts ...Option) (*Reader, error)
  • func (r *Reader) CurrentNamespaceDeclsSeq() iter.Seq[NamespaceDecl]
  • func (r *Reader) CurrentPos() (line, column int)
  • func (r *Reader) Decode(v Unmarshaler) error
  • func (r *Reader) DecodeElement(v Unmarshaler, start Event) error
  • func (r *Reader) InputOffset() int64
  • func (r *Reader) LookupNamespace(prefix string) (string, bool)
  • func (r *Reader) LookupNamespaceAt(prefix string, depth int) (string, bool)
  • func (r *Reader) LookupNamespaceBytes(prefix []byte) (string, bool)
  • func (r *Reader) LookupNamespaceBytesAt(prefix []byte, depth int) (string, bool)
  • func (r *Reader) NamespaceDecls(depth int) []NamespaceDecl
  • func (r *Reader) NamespaceDeclsSeq(depth int) iter.Seq[NamespaceDecl]
  • func (r *Reader) Next() (Event, error)
  • func (r *Reader) NextRaw() (RawEvent, error)
  • func (r *Reader) NextResolved() (ResolvedEvent, error)
  • func (r *Reader) ReadSubtreeTo(w io.Writer) (int64, error)
  • func (r *Reader) Reset(src io.Reader, opts ...Option) error
  • func (r *Reader) SkipSubtree() error
• type ResolvedAttr
• type ResolvedEvent
• type Unmarshaler

Constants

const (
	XMLNamespace   = xmlnames.XMLNamespace
	XMLNSNamespace = xmlnames.XMLNSNamespace
	XSINamespace   = xmlnames.XSINamespace
	XSDNamespace   = "http://www.w3.org/2001/XMLSchema"
)

Common XML namespaces.

Variables

var ErrUnboundPrefix = errUnboundPrefix

ErrUnboundPrefix reports usage of an undeclared namespace prefix.

Functions

func JoinOptions

func JoinOptions(opts ...Option) xmltext.Options

JoinOptions merges xmlstream options into a single xmltext options struct.

Types

type Attr

type Attr struct {
	Name  QName
	Value []byte
}

Attr holds a namespace-qualified attribute.

type ElementID

type ElementID uint64

ElementID is a monotonic identifier assigned per document.

type Event

type Event struct {
	Name       QName
	Attrs      []Attr
	Text       []byte
	Kind       EventKind
	Line       int
	Column     int
	ID         ElementID
	ScopeDepth int
}

Event represents a single streaming XML token. Text and Attr.Value are valid until the next Next call.

func (Event) Attr

func (e Event) Attr(namespace, local string) ([]byte, bool)

Attr returns the attribute value by namespace and local name.

func (Event) AttrLocal

func (e Event) AttrLocal(local string) ([]byte, bool)

AttrLocal returns the attribute value by local name, ignoring namespace.

type EventKind

type EventKind int

EventKind identifies the kind of streaming XML event.

const (
	EventStartElement EventKind = iota
	EventEndElement
	EventCharData
	EventComment
	EventPI
	EventDirective
)

func (EventKind) String

func (k EventKind) String() string

String returns a readable name for the event kind.

type NameID

type NameID uint32

NameID is a monotonic identifier assigned per document for expanded names.

type NamespaceDecl

type NamespaceDecl struct {
	Prefix string
	URI    string
}

NamespaceDecl reports a namespace declaration on the current element.

type Option

type Option = xmltext.Options

Option configures the xmlstream reader. Construct options via helpers in pkg/xmltext.

type QName

type QName = qname.QName

QName represents a namespace-qualified name.

type RawAttr

type RawAttr struct {
	Name  RawName
	Value []byte
}

RawAttr holds a raw attribute name and value. The byte slices are valid until the next Next or NextRaw call.

type RawEvent

type RawEvent struct {
	Name       RawName
	Attrs      []RawAttr
	Text       []byte
	Kind       EventKind
	Line       int
	Column     int
	ID         ElementID
	ScopeDepth int
}

RawEvent represents a streaming XML token with raw names. The byte slices are valid until the next Next or NextRaw call.

func (RawEvent) Attr

func (e RawEvent) Attr(prefix, local []byte) ([]byte, bool)

Attr returns the raw attribute value by local name and optional prefix.

func (RawEvent) AttrLocal

func (e RawEvent) AttrLocal(local []byte) ([]byte, bool)

AttrLocal returns the raw attribute value by local name, ignoring prefix.

type RawName

type RawName struct {
	Full   []byte
	Prefix []byte
	Local  []byte
}

RawName holds a raw QName split into prefix and local parts. The byte slices are valid until the next Next or NextRaw call.

func (RawName) HasLocal

func (n RawName) HasLocal(local []byte) bool

HasLocal reports whether the local name matches.

type Reader

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

Reader provides a streaming XML event interface with namespace tracking.

func NewReader

func NewReader(r io.Reader, opts ...Option) (*Reader, error)

NewReader creates a new streaming reader for r.

func (*Reader) CurrentNamespaceDeclsSeq

func (r *Reader) CurrentNamespaceDeclsSeq() iter.Seq[NamespaceDecl]

CurrentNamespaceDeclsSeq yields namespace declarations in the current scope.

func (*Reader) CurrentPos

func (r *Reader) CurrentPos() (line, column int)

CurrentPos returns the line and column of the most recent token.

func (*Reader) Decode

func (r *Reader) Decode(v Unmarshaler) error

Decode unmarshals the current element subtree into v.

func (*Reader) DecodeElement

func (r *Reader) DecodeElement(v Unmarshaler, start Event) error

DecodeElement unmarshals using the provided start event.

func (*Reader) InputOffset

func (r *Reader) InputOffset() int64

InputOffset returns the current byte position in the input stream.

func (*Reader) LookupNamespace

func (r *Reader) LookupNamespace(prefix string) (string, bool)

LookupNamespace resolves a prefix in the current scope.

func (*Reader) LookupNamespaceAt

func (r *Reader) LookupNamespaceAt(prefix string, depth int) (string, bool)

LookupNamespaceAt resolves a prefix at the given scope depth.

func (*Reader) LookupNamespaceBytes

func (r *Reader) LookupNamespaceBytes(prefix []byte) (string, bool)

LookupNamespaceBytes resolves a prefix in the current scope without allocation.

func (*Reader) LookupNamespaceBytesAt

func (r *Reader) LookupNamespaceBytesAt(prefix []byte, depth int) (string, bool)

LookupNamespaceBytesAt resolves a prefix at the given scope depth without allocation.

func (*Reader) NamespaceDecls

func (r *Reader) NamespaceDecls(depth int) []NamespaceDecl

NamespaceDecls returns namespace declarations at the given scope depth. The returned slice aliases reader-owned storage and is valid until the next read.

func (*Reader) NamespaceDeclsSeq

func (r *Reader) NamespaceDeclsSeq(depth int) iter.Seq[NamespaceDecl]

NamespaceDeclsSeq yields namespace declarations at the given scope depth.

func (*Reader) Next

func (r *Reader) Next() (Event, error)

Next returns the next XML event.

func (*Reader) NextRaw

func (r *Reader) NextRaw() (RawEvent, error)

NextRaw returns the next XML event with raw names. Raw name and value slices are valid until the next Next or NextRaw call.

func (*Reader) NextResolved

func (r *Reader) NextResolved() (ResolvedEvent, error)

NextResolved returns the next XML event with namespace-resolved byte slices.

func (*Reader) ReadSubtreeTo

func (r *Reader) ReadSubtreeTo(w io.Writer) (int64, error)

ReadSubtreeTo streams the current element subtree to w.

func (*Reader) Reset

func (r *Reader) Reset(src io.Reader, opts ...Option) error

Reset prepares the reader for a new input stream.

func (*Reader) SkipSubtree

func (r *Reader) SkipSubtree() error

SkipSubtree skips the current element subtree after a StartElement event.

type ResolvedAttr

type ResolvedAttr struct {
	NS     []byte
	Local  []byte
	Value  []byte
	NameID NameID
}

ResolvedAttr holds a namespace-resolved attribute.

type ResolvedEvent

type ResolvedEvent struct {
	NS         []byte
	Local      []byte
	Attrs      []ResolvedAttr
	Text       []byte
	Kind       EventKind
	Line       int
	Column     int
	ID         ElementID
	ScopeDepth int
	NameID     NameID
}

ResolvedEvent represents a streaming XML token with namespace-resolved bytes. NS/Local/Attr slices are valid until the next NextResolved or Next call.

type Unmarshaler

type Unmarshaler interface {
	UnmarshalXMLStream(r *Reader, start Event) error
}

Unmarshaler is implemented by types that can unmarshal themselves from XML.