class

Mica::XML::Builder

Inherits Reference < Object

Writes XML to an IO, escaping text and attribute values and checking names and characters so the output is always well-formed. The API mirrors stdlib XML::Builder.

string = Mica::XML.build(indent: 2) do |xml|
  xml.element("feed", lang: "en") do
    xml.element("title") { xml.text "Tom & Jerry" }
  end
end
string # => "<?xml version=\"1.0\"?>\n<feed lang=\"en\">\n  <title>Tom &amp; Jerry</title>\n</feed>\n"

Misuse (an attribute after content, an end without a start, an invalid name or character) raises Mica::XML::BuilderError.

Constants

MAX_INDENT_LEVELS = 64

Indentation stops growing past this depth, so indented output stays linear in the number of nodes.

Constructors

new(io : IO)
Source

Instance methods

attribute(prefix : String | Nil, name : String, namespace_uri : String | Nil, value) : Nil

Writes attribute prefix:name in namespace_uri.

Source
attribute(name : String, value) : Nil

Writes attribute name with value on the open start tag.

Source
attributes(attributes : Hash | NamedTuple) : Nil

Writes each pair of attributes.

Source
attributes

Writes each pair of attributes.

Source
cdata

Writes a CDATA section around the block's text.

Source
cdata(text : String) : Nil

Writes text as a CDATA section (a ]]> inside is split).

Source
comment

Writes a comment around the block's text.

Source
comment(text : String) : Nil

Writes text as a comment. Raises when it contains -- or ends with -.

Source
document(version : String | Nil = nil, encoding : String | Nil = nil, &) : Nil

Writes a whole document: the declaration, the block's content and the final newline.

Source
dtd(name : String, pubid : String | Nil, sysid : String | Nil, subset : String | Nil = nil) : Nil

Writes a DOCTYPE declaration with an optional raw internal subset.

The subset is parsed first under the default work budget. Raises BuilderError when it is malformed, and Mica::LimitExceededError (including Mica::WorkBudgetExceededError) when checking it exceeds a limit.

Source
dtd(name : String, pubid : String | Nil, sysid : String | Nil, &) : Nil

Writes a DOCTYPE declaration around the block.

Source
element(__prefix__ : String | Nil, __name__ : String, __namespace_uri__ : String | Nil, **attributes, &)

Writes element prefix:name in namespace_uri around the block.

Source
element(__name__ : String, attributes : Hash | NamedTuple, &)

Writes element name with attributes around the block's content.

Source
element(__name__ : String, **attributes, &)

Writes element name with attributes around the block's content.

Source
element(prefix : String | Nil, name : String, namespace_uri : String | Nil, **attributes) : Nil

Writes an empty element prefix:name in namespace_uri.

Source
element(name : String, attributes : Hash | NamedTuple) : Nil

Writes an empty element name with attributes.

Source
element(__name__ : String, **attributes) : Nil

Writes an empty element name with attributes.

Source
end_attribute

Ends the open attribute.

Source
end_cdata

Closes the CDATA section.

Source
end_comment

Closes the comment.

Source
end_document

Closes every open element and ends the document with a newline.

Source
end_dtd

Closes the DOCTYPE declaration.

Source
end_element

Closes the innermost open element.

Source
flush

Flushes the underlying IO.

Source
indent=(text : String) : String

Sets the indentation string; empty disables indentation.

Source
indent=(level : Int) : Int

Sets indentation to level spaces.

Source
namespace(prefix : String | Nil, uri : String) : Nil

Declares namespace uri for prefix (nil for the default namespace) on the open start tag.

Source
quote_char=(char : Char) : Char

Sets the quote used around attribute values ('"' or '\'').

Source
start_attribute(name : String) : Nil

Opens attribute name; write its value with text, then call end_attribute.

Source
start_cdata

Opens a CDATA section.

Source
start_comment

Opens a comment.

Source
start_document(version : String | Nil = nil, encoding : String | Nil = nil) : Nil

Writes the XML declaration.

Source
start_dtd(name : String, pubid : String | Nil, sysid : String | Nil) : Nil

Opens a DOCTYPE declaration.

Source
start_element(prefix : String | Nil, name : String, namespace_uri : String | Nil) : Nil

Opens element prefix:name, declaring namespace_uri for the prefix when it is not already in scope.

Source
start_element(name : String) : Nil

Opens element name.

Source
text(content : String) : Nil

Writes escaped character data. Inside start_attribute, start_cdata or start_comment it writes to that construct instead.

Source