Categorygithub.com/shabbyrobe/xmlwriter
modulepackage
0.0.0-20230525083848-85336ec334fa
Repository: https://github.com/shabbyrobe/xmlwriter.git
Documentation: pkg.go.dev

# README

xmlwriter

GoDoc Go

xmlwriter is a pure-Go library providing a procedural XML generation API based on libxml2's xmlwriter module. The package is extensively documented at GoDoc.

Quick example:

func main() {
    b := &bytes.Buffer{}
    w := xmlwriter.Open(b)
    ec := &xmlwriter.ErrCollector{}
    defer ec.Panic()

    ec.Do(
        w.StartDoc(xmlwriter.Doc{})
        w.StartElem(xmlwriter.Elem{Name: "foo"})
        w.WriteAttr(xmlwriter.Attr{Name: "a1", Value: "val1"})
        w.WriteAttr(xmlwriter.Attr{Name: "a2", Value: "val2"})
        w.WriteComment(xmlwriter.Comment{"hello"})
        w.StartElem(xmlwriter.Elem{Name: "bar"})
        w.WriteAttr(xmlwriter.Attr{Name: "a1", Value: "val1"})
        w.WriteAttr(xmlwriter.Attr{Name: "a2", Value: "val2"})
        w.StartElem(xmlwriter.Elem{Name: "baz"})
        w.EndAllFlush()
    )
    fmt.Println(b.String())
}

xmlwriter is about twice as quick as using the stdlib's encoding/xml and offers total control of the output. If you don't require that level of control, it's probably better to stick with encoding/xml

BenchmarkWriterHuge-8     	     165	   7189290 ns/op	    4944 B/op	       4 allocs/op
BenchmarkWriterSmall-8    	  299679	      4035 ns/op	    4944 B/op	       4 allocs/op
BenchmarkGolangHuge-8      	      52	  21770422 ns/op	 4324496 B/op	   60008 allocs/op
BenchmarkGolangSmall-8    	  139767	      8828 ns/op	    5936 B/op	      28 allocs/op

xmlwriter is exhaustively tested using a fairly insane mess of C scripts you can find in the tester/ directory.

License

xmlwriter uses the Apache License 2.0. I pulled in about 60 lines of code from the xml/encoding package in the Go sources and retained the copyright. Not sure the exact implications, IANAL. Please file an issue if I've done something wrong.

# Packages

No description provided by the author
No description provided by the author

# Functions

CheckChars ensures a string contains characters which are valid in a Text{} node: https://www.w3.org/TR/xml/#NT-Char The 'strict' argument (which xmlwriter should activate by default) ensures that unicode characters referenced in the note are also excluded.
CheckEncoding validates the characters in a Doc{} node's encoding="..." attribute based on the following production rule: [A-Za-z] ([A-Za-z0-9._] | '-')*.
CheckName ensures a string satisfies the following production rules: https://www.w3.org/TR/xml/#NT-NameStartChar, with the exception that it does not return an error on an empty string.
CheckPubID validates a string according to the following production rule: https://www.w3.org/TR/xml/#NT-PubidLiteral.
NewStandardIndenter creates a StandardIndenter.
Open opens the Writer using the UTF-8 encoding.
OpenEncoding opens the Writer using the supplied encoding.
WithIndent sets the Writer up to indent XML elements to make them easier to read using the StandardIndenter: w := xmlwriter.Open(b, xmlwriter.WithIndent()).
WithIndentString configures the Writer with a StandardIndenter using a specific indent string: w := xmlwriter.Open(b, xmlwriter.WithIndentString(" ")).

# Constants

Range of allowed NodeKind values.
Range of allowed NodeKind values.
Range of allowed NodeKind values.
Range of allowed NodeKind values.
Range of allowed NodeKind values.
Range of allowed NodeKind values.
Range of allowed NodeKind values.
DTDAttr.Value represents the default for this attribute.
No description provided by the author
No description provided by the author
The #FIXED keyword states that the attribute MUST always have the default value.
No description provided by the author
No description provided by the author
No description provided by the author
No default value is provided.
If Value is empty, this attribute is DTDAttrImplied, otherwise it will be a standard DTDAttrDefault value (without #FIXED).
No description provided by the author
No description provided by the author
Range of allowed NodeKind values.
The attribute MUST always be provided.
No description provided by the author
DTDElemAny is a DTDElem Decl used when the element can contain any element.
DTDElemEmpty is a DTDElem Decl used when the element is empty.
Range of allowed NodeKind values.
DTDElemPCData is a DTDElem Decl used when the element can contain parsed character data.
Range of allowed NodeKind values.
Range of allowed NodeKind values.
Range of allowed NodeKind values.
Range of allowed NodeKind values.
Range of allowed NodeKind values.
Range of allowed NodeKind values.
Range of allowed NodeKind values.
StateEnded indicates the node's end, e.g.
StateOpen indicates the node is open but not opened, e.g.
StateOpened indicates the node is fully opened, e.g.
Range of allowed NodeKind values.

# Structs

Attr represents an XML attribute to be written by the Writer.
CData represents an XML CData section which can be written or started by the Writer.
Comment represents an XML comment section which can be written or started by the Writer.
Doc represents an XML document which can be started by the writer.
DTD represents a Document Type Definition to be written by the Writer.
DTDAttList represents a DTD attribute list to be written by the Writer.
DTDAttr represents a DTD attribute to be written by the Writer.
DTDElem represents a DTD element definition to be written by the Writer.
DTDEntity represents a DTD entity definition to be written by the Writer.
Elem represents an XML element to be written by the writer.
ErrCollector allows you to defer raising or accumulating an error until after a series of procedural calls.
Event is raised when a node changes state in the writer.
Notation represents an XML notation declaration to be written by the Writer.
PI represents an XML processing instruction to be written by the Writer.
StandardIndenter implements a primitive Indenter strategy for pretty printing the Writer's XML output.
Writer writes XML to an io.Writer.

# Interfaces

Indenter allows custom indenting strategies to be written for pretty printing the resultant XML.
Node represents an item which the Writer can Start and/or Write.
Startable is a node which can be passed to xmlwriter.Start() - any node which can have children is Startable.
Writable is a node which can be passed to xmlwriter.Write().

# Type aliases

CDataContent represents a text portion of an XML CData section which can be written after a CData is Started.
CommentContent represents a text portion of an XML comment which can be written after a Comment is Started.
DTDAttrDefaultType represents the possible values from the DefaultDecl production in the DTD spec: https://www.w3.org/TR/REC-xml/#NT-DefaultDecl.
DTDAttrType constrains the valid values for the Type property of the DTDAttr struct.
NodeKind is the kind of the node.
NodeState is the state of the node being written.
Option is an option to the Writer.
Raw represents a raw string to be written by the Writer.
Text represents an XML text section to be written by the Writer.