modulepackage
0.0.0-20230525083848-85336ec334fa
Repository: https://github.com/shabbyrobe/xmlwriter.git
Documentation: pkg.go.dev
# README
xmlwriter
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.
# 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.