# module XML

##
Overview

The XML module allows parsing and generating XML documents.

NOTE To use `XML`, you must explicitly import it with `require "xml"`

###
Parsing

`XML#parse` will parse xml from `String` or `IO` and return xml document as an `XML::Node` which represents all kinds of xml nodes.

Example:

    require "xml"

    xml = <<-XML
     <person id="1">
      <firstname>Jane</firstname>
      <lastname>Doe</lastname>
     </person>
    XML

    document = XML.parse(xml)             # : XML::Node
    person = document.first_element_child # : XML::Node?
    if person
      puts person["id"] # "1" : String?

      puts typeof(person.children)                       # XML::NodeSet
      person.children.select(&.element?).each do |child| # Select only element children
        puts typeof(child)                               # XML::Node
        puts child.name                                  # firstname : String
        puts child.content                               # Jane : String?
      end
    end

##
Generating

Use `XML.build`, which uses an `XML::Builder`:

    require "xml"

    string = XML.build(indent: "  ") do |xml|
      xml.element("person", id: 1) do
        xml.element("firstname") { xml.text "Jane" }
        xml.element("lastname") { xml.text "Doe" }
      end
    end

    string # => "<?xml version=\"1.0\"?>\n<person id=\"1\">\n  <firstname>Jane</firstname>\n  <lastname>Doe</lastname>\n</person>\n"

##
Defined in:

xml.cr
xml/builder.cr

##
Class Method Summary

- .build(version : String | Nil = nil, encoding : String | Nil = nil, indent = nil, quote_char = nil, &)

  Returns the resulting `String` of writing XML to the yielded `XML::Builder`.

- .build(io : IO, version : String | Nil = nil, encoding : String | Nil = nil, indent = nil, quote_char = nil, &) : Nil

  Writes XML document into the given `IO`.

- .build_fragment(io : IO, *, indent = nil, quote_char = nil, &) : Nil

  Writes XML fragment into the given `IO`.

- .build_fragment(*, indent = nil, quote_char = nil, &)

  Returns the resulting `String` of writing XML to the yielded `XML::Builder`.

- .parse(string : String, options : ParserOptions = ParserOptions.default) : Node

  Parses an XML document from string with options into an `XML::Node`.

- .parse(io : IO, options : ParserOptions = ParserOptions.default) : Node

  Parses an XML document from io with options into an `XML::Node`.

- .parse_html(string : String, options : HTMLParserOptions = HTMLParserOptions.default) : Node

  Parses an HTML document from string with options into an `XML::Node`.

- .parse_html(io : IO, options : HTMLParserOptions = HTMLParserOptions.default) : Node

  Parses an HTML document from io with options into an `XML::Node`.

##
Class Method Detail

def self.build(version : String | Nil = nil, encoding : String | Nil = nil, indent = nil, quote_char = nil, &) #

Returns the resulting `String` of writing XML to the yielded `XML::Builder`.

Builds an XML document (see `#document`) including XML declaration (`<?xml?>`).

    require "xml"

    string = XML.build(indent: "  ") do |xml|
      xml.element("person", id: 1) do
        xml.element("firstname") { xml.text "Jane" }
        xml.element("lastname") { xml.text "Doe" }
      end
    end

    string # => "<?xml version=\"1.0\"?>\n<person id=\"1\">\n  <firstname>Jane</firstname>\n  <lastname>Doe</lastname>\n</person>\n"

def self.build(io : IO, version : String | Nil = nil, encoding : String | Nil = nil, indent = nil, quote_char = nil, &) : Nil #

Writes XML document into the given `IO`. An `XML::Builder` is yielded to the block.

Builds an XML document (see `#document`) including XML declaration (`<?xml?>`).

def self.build_fragment(io : IO, *, indent = nil, quote_char = nil, &) : Nil #

Writes XML fragment into the given `IO`. An `XML::Builder` is yielded to the block.

Builds an XML fragment without XML declaration (`<?xml?>`).

def self.build_fragment(*, indent = nil, quote_char = nil, &) #

Returns the resulting `String` of writing XML to the yielded `XML::Builder`.

Builds an XML fragment without XML declaration (`<?xml?>`).

    require "xml"

    string = XML.build_fragment(indent: "  ") do |xml|
      xml.element("person", id: 1) do
        xml.element("firstname") { xml.text "Jane" }
        xml.element("lastname") { xml.text "Doe" }
      end
    end

    string # => "<person id=\"1\">\n  <firstname>Jane</firstname>\n  <lastname>Doe</lastname>\n</person>\n"

def self.parse(string : String, options : ParserOptions = ParserOptions.default) : Node #

Parses an XML document from string with options into an `XML::Node`.

See `ParserOptions.default` for default options.

def self.parse(io : IO, options : ParserOptions = ParserOptions.default) : Node #

Parses an XML document from io with options into an `XML::Node`.

See `ParserOptions.default` for default options.

def self.parse_html(string : String, options : HTMLParserOptions = HTMLParserOptions.default) : Node #

Parses an HTML document from string with options into an `XML::Node`.

See `HTMLParserOptions.default` for default options.

def self.parse_html(io : IO, options : HTMLParserOptions = HTMLParserOptions.default) : Node #

Parses an HTML document from io with options into an `XML::Node`.

See `HTMLParserOptions.default` for default options.