xml

Documentation

Index

• func Deserialize(r io.Reader, api rbxapi.Root) (root *rbxfile.Root, err error)
• func Serialize(w io.Writer, api rbxapi.Root, root *rbxfile.Root) (err error)
• type Attr
• type Decoder
• type Document
  • func (doc *Document) ReadFrom(r io.Reader) (n int64, err error)
  • func (d *Document) WriteTo(w io.Writer) (n int64, err error)
• type Encoder
• type RobloxCodec
  • func (c RobloxCodec) Decode(document *Document) (root *rbxfile.Root, err error)
  • func (c RobloxCodec) DecodeProperties(tags []*Tag, inst *rbxfile.Instance, refs rbxfile.References) (propRefs []rbxfile.PropRef)
  • func (c RobloxCodec) Encode(root *rbxfile.Root) (document *Document, err error)
  • func (c RobloxCodec) EncodeProperties(instance *rbxfile.Instance) (properties []*Tag)
  • func (RobloxCodec) GetCanonType(valueType string) string
• type Serializer
  • func NewSerializer(d Decoder, e Encoder) Serializer
  • func (s Serializer) Deserialize(r io.Reader) (root *rbxfile.Root, err error)
  • func (s Serializer) Serialize(w io.Writer, root *rbxfile.Root) (err error)
• type SyntaxError
  • func (e *SyntaxError) Error() string
• type Tag
  • func NewItem(class, referent string, properties ...*Tag) *Tag
  • func NewProp(valueType, propName, value string) *Tag
  • func NewRoot(items ...*Tag) *Tag
  • func (t Tag) AttrValue(name string) (value string, exists bool)
  • func (t *Tag) SetAttrValue(name, value string)

Functions

func Deserialize

func Deserialize(r io.Reader, api rbxapi.Root) (root *rbxfile.Root, err error)

Deserialize decodes data from r into a Root structure using the default decoder. An optional API can be given to ensure more correct data.

func Serialize

func Serialize(w io.Writer, api rbxapi.Root, root *rbxfile.Root) (err error)

Serialize encodes data from a Root structure to w using the default encoder. An optional API can be given to ensure more correct data.

Types

type Attr

type Attr struct {
	Name  string
	Value string
}

Attr represents an attribute of a tag.

type Decoder

type Decoder interface {
	Decode(document *Document) (root *rbxfile.Root, err error)
}

Decoder decodes a Document to a generic rbxfile.Root structure.

type Document

type Document struct {
	// Prefix is a string that appears at the start of each line in the
	// document.
	//
	// When encoding, the prefix is added after each newline. Newlines are
	// added automatically when either Prefix or Indent is not empty.
	//
	// When decoding, this value is set when indentation is detected in the
	// document. When detected, the value becomes any leading whitespace
	// before the root tag (at the start of the file). This only sets the
	// value; no attempt is made to validate any other prettifying whitespace.
	Prefix string

	// Indent is a string that indicates one level of indentation.
	//
	// When encoding, a sequence of indents appear after the Prefix, an amount
	// equal to the current nesting depth in the markup.
	//
	// When decoding, this value is set when detecting indentation. It is set
	// to the prettifying whitespace that occurs after the first newline and
	// prefix, which occurs between the root tag's CDATA and Text data. This
	// only sets the value; no attempt is made to validate any other
	// prettifying whitespace.
	Indent string

	// Suffix is a string that appears at the very end of the document. When
	// encoding, this string is appended to the end of the file, after the
	// root tag. When decoding, this value becomes any remaining text that
	// appears after the root tag.
	Suffix string

	// ExcludeRoot determines whether the root tag should be encoded. This can
	// be combined with Prefix to write documents in-line.
	ExcludeRoot bool

	// Root is the root tag in the document.
	Root *Tag

	// Warnings is a list of non-fatal problems that have occurred. This will
	// be cleared and populated when calling either ReadFrom and WriteTo.
	// Codecs may also clear and populate this when decoding or encoding.
	Warnings []error
}

Document represents an entire XML document.

func (*Document) ReadFrom

func (doc *Document) ReadFrom(r io.Reader) (n int64, err error)

ReadFrom decode data from r into the Document.

func (*Document) WriteTo

func (d *Document) WriteTo(w io.Writer) (n int64, err error)

WriteTo encodes the Document as bytes to w.

type Encoder

type Encoder interface {
	Encode(root *rbxfile.Root) (document *Document, err error)
}

Encoder encodes a rbxfile.Root structure to a Document.

type RobloxCodec

type RobloxCodec struct {
	// API can be set to yield a more correct encoding or decoding by
	// providing information about each class. If API is nil, the codec will
	// try to use other available information, but may not be fully accurate.
	API rbxapi.Root

	// ExcludeReferent determines whether the "referent" attribute should be
	// added to Item tags when encoding.
	ExcludeReferent bool

	// ExcludeExternal determines whether standard <External> tags should be
	// added to the root tag when encoding.
	ExcludeExternal bool

	// ExcludeInvalidAPI determines whether invalid items are excluded when
	// encoding or decoding. An invalid item is an instance or property that
	// does not exist or has incorrect information, according to a provided
	// rbxapi.API.
	//
	// If true, then warnings will be emitted for invalid items, and the items
	// will not be included in the output. If false, then warnings are still
	// emitted, but invalid items are handled as if they were valid. This
	// applies when decoding from a Document, and when encoding from a
	// rbxfile.Root.
	//
	// Since an API may exclude some items even though they're correct, it is
	// generally preferred to set ExcludeInvalidAPI to false, so that false
	// negatives do not lead to lost data.
	ExcludeInvalidAPI bool

	// ExcludeMetadata determines whether <Meta> tags should be included while
	// encoding.
	ExcludeMetadata bool
}

RobloxCodec implements Decoder and Encoder to emulate Roblox's internal codec as closely as possible.

func (RobloxCodec) Decode

func (c RobloxCodec) Decode(document *Document) (root *rbxfile.Root, err error)

func (RobloxCodec) DecodeProperties

func (c RobloxCodec) DecodeProperties(tags []*Tag, inst *rbxfile.Instance, refs rbxfile.References) (propRefs []rbxfile.PropRef)

DecodeProperties decodes a list of tags as properties to a given instance. Returns a list of unresolved references.

func (RobloxCodec) Encode

func (c RobloxCodec) Encode(root *rbxfile.Root) (document *Document, err error)

func (RobloxCodec) EncodeProperties

func (c RobloxCodec) EncodeProperties(instance *rbxfile.Instance) (properties []*Tag)

func (RobloxCodec) GetCanonType

func (RobloxCodec) GetCanonType(valueType string) string

GetCanonType converts a string (usually from a tag name) to a decodable type.

type Serializer

type Serializer struct {
	Decoder Decoder
	Encoder Encoder
}

Serializer implements functions that decode and encode directly between byte streams and rbxfile Root structures.

func NewSerializer

func NewSerializer(d Decoder, e Encoder) Serializer

NewSerializer returns a new Serializer with a specified decoder and encoder. If either value is nil, the default RobloxCodec will be used in its place.

func (Serializer) Deserialize

func (s Serializer) Deserialize(r io.Reader) (root *rbxfile.Root, err error)

Deserialize decodes data from r into a Root structure using the specified decoder.

func (Serializer) Serialize

func (s Serializer) Serialize(w io.Writer, root *rbxfile.Root) (err error)

Serialize encodes data from a Root structure to w using the specified encoder.

type SyntaxError

type SyntaxError struct {
	Msg  string
	Line int
}

A SyntaxError represents a syntax error in the XML input stream.

func (*SyntaxError) Error

func (e *SyntaxError) Error() string

type Tag

type Tag struct {
	// StartName is the name of the tag in the start tag.
	StartName string

	// EndName is the name of the tag in the end tag. If empty, this is
	// assumed to be equal to StartName.
	EndName string

	// The attributes of the tag.
	Attr []Attr

	// Empty indicates whether the tag has an empty-tag format. When encoding,
	// the tag will be written in the empty-tag format, and any content will
	// be ignored. When decoding, this value will be set if the decoded tag
	// has the empty-tag format.
	Empty bool

	// CData is a sequence of characters in a CDATA section. Only up to one
	// section is allowed, and must be the first element in the tag. A nil
	// array means that the tag does not contain a CDATA section.
	CData []byte

	// Text is the textual content of the tag.
	Text string

	// NoIndent indicates whether the tag contains prettifying whitespace,
	// which occurs between the tag's CData and Text, as well as between each
	// child tag.
	//
	// When decoding, this value is set to true if there is no whitespace of
	// any kind between the CData and Text. It will only be set if the decoder
	// has successfully detected global prefix and indent strings, but note
	// that these do not affect how the whitespace is detected.
	//
	// When encoding, this value determines whether the tag and its
	// descendants will be written with prettifying whitespace.
	NoIndent bool

	// Tags is a list of child tags within the tag.
	Tags []*Tag
}

Tag represents a Roblox XML tag construct. Unlike standard XML, the content of a tag must consist of the following, in order:

1. An optional CData section.
2. A sequence of zero or more whitespace, which is ignored (usually newlines and indentation).
3. A sequence of zero or more characters indicating textual content of the tag.
4. A sequence of zero or more complete tags, with optional whitespace between each.

func NewItem

func NewItem(class, referent string, properties ...*Tag) *Tag

NewItem initializes an "Item" Tag representing a Roblox class.

func NewProp

func NewProp(valueType, propName, value string) *Tag

NewProp initializes a basic property tag representing a property in a Roblox class.

func NewRoot

func NewRoot(items ...*Tag) *Tag

NewRoot initializes a Tag containing values standard to a root tag. Optionally, Item tags can be given as arguments, which will be added to the root as sub-tags.

func (Tag) AttrValue

func (t Tag) AttrValue(name string) (value string, exists bool)

AttrValue returns the value of the first attribute of the given name, and whether or not it exists.

func (*Tag) SetAttrValue

func (t *Tag) SetAttrValue(name, value string)

SetAttrValue sets the value of the first attribute of the given name, if it exists. If value is an empty string, then the attribute will be removed instead. If the attribute does not exist and value is not empty, then the attribute is added.