2x faster API-compatible Builder implementation using libxml.
Ruby
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.gitignore
.travis.yml
Gemfile
README.rdoc
Rakefile
xbuilder.gemspec

README.rdoc

Xbuilder Dependency Status

Xbuilder is an API-compatible Builder implementation using libxml. Also it's almost 2 times faster than Builder and Nokogiri (see test/performance.rb output for details).

Feel free to open an issue on any incompatibility with Builder API. The list of known incompatibilities is given below.

Usage

Xbuilder supports almost all of the Builder's features. Here is a small example:

xml = Xbuilder.new(indent: 2)
xml.node attr: 1 do |xml|     #=> <node attr="1">
  xml.ns :child, attr: 2      #=>   <ns:child attr="2"/>
end                           #=> </node>

With Rails

# some.xml.xbuilder
xml.node do |xml|
  # The first argument is your partial name, the second is a hash of locals.
  xml.partial!("partial", value: 1)
end

# _partial.xml.xbuilder
xml.child(value)

will render:

<?xml version="1.0" encoding="UTF-8"?>
<node><child>1</child></node>

Notes

  • Child blocks with 0 arguments are not supported. So, instead of:

    xml.node do
      xml.node
    end

    write:

    xml.node do |xml|
      xml.node
    end
  • XML instruction will be added automatically.

    xml = Xbuilder.new(encoding: "ISO-8859-1")
    xml.node "test"
    puts xml.target!

    will print:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <node>test</node>
  • libxml-ruby gem has an issue (#46) with node content encoding:

    xml.esc "escaped & text"
    #=> without fix: <esc>escaped </esc>
    #=> with fix: <esc>escaped &amp; text</esc>

    For now I've used temporary workaround (see Xbuilder#__escape).

Incompatibilities With Builder

  • Builder-like unescaped symbol attributes are not supported. It's currently a restriction of libxml (see xmlAttrSerializeContent implementation).

    xml.node(attr: :"&esc") #=> <node attr="&amp;esc"/>
  • Custom XML processing instructions are not supported yet. Instruction will be auto-generated depending on encoding and version provided.

  • XML entity declarations are not yet supported.

Contributing to Xbuilder

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.

  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.

  • Fork the project.

  • Start a feature/bugfix branch.

  • Commit and push until you are happy with your contribution.

  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.

  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Authors

Builder gem was created by Jim Weirich.

Xbuilder gem was created by Nikita Afanasenko. The project is hosted on Github: github.com/nikitug/xbuilder.

Copyright © 2012 Nikita Afanasenko, released under the MIT license.