https://github.com/rails/builder

Provide a simple way to create XML markup and data structures.
https://github.com/rails/builder

Keywords from Contributors

activejob activerecord mvc rubygems rack rspec background-jobs rake sinatra feature-flag

Last synced: about 6 hours ago
JSON representation

Repository metadata

Provide a simple way to create XML markup and data structures.

Host: GitHub
URL: https://github.com/rails/builder
Owner: rails
License: mit
Fork: true (jimweirich/builder)
Created: 2017-01-13T17:07:20.000Z (almost 9 years ago)
Default Branch: master
Last Pushed: 2024-07-11T12:28:55.000Z (over 1 year ago)
Last Synced: 2025-11-30T04:07:01.956Z (12 days ago)
Language: Ruby
Homepage: http://builder.rubyforge.org
Size: 234 KB
Stars: 37
Watchers: 4
Forks: 20
Open Issues: 5
Releases: 0

https://github.com/rails/builder/blob/master/

          # Project: Builder

## Goal

Provide a simple way to create XML markup and data structures.

## Classes

Builder::XmlMarkup:: Generate XML markup notation
Builder::XmlEvents:: Generate XML events (i.e. SAX-like)

**Notes:**

* An Builder::XmlTree class to generate XML tree
  (i.e. DOM-like) structures is also planned, but not yet implemented.
  Also, the events builder is currently lagging the markup builder in
  features.

## Usage

```ruby
  require 'rubygems'
  require_gem 'builder', '~> 2.0'

  builder = Builder::XmlMarkup.new
  xml = builder.person { |b| b.name("Jim"); b.phone("555-1234") }
  xml #=> Jim555-1234
```

or

```ruby
  require 'rubygems'
  require_gem 'builder'

  builder = Builder::XmlMarkup.new(:target=>STDOUT, :indent=>2)
  builder.person { |b| b.name("Jim"); b.phone("555-1234") }
  #
  # Prints:
  # 
  #   Jim
  #   555-1234
  # 
```

## Compatibility

### Version 2.0.0 Compatibility Changes

Version 2.0.0 introduces automatically escaped attribute values for
the first time.  Versions prior to 2.0.0 did not insert escape
characters into attribute values in the XML markup.  This allowed
attribute values to explicitly reference entities, which was
occasionally used by a small number of developers.  Since strings
could always be explicitly escaped by hand, this was not a major
restriction in functionality.

However, it did surprise most users of builder.  Since the body text is
normally escaped, everybody expected the attribute values to be
escaped as well.  Escaped attribute values were the number one support
request on the 1.x Builder series.

Starting with Builder version 2.0.0, all attribute values expressed as
strings will be processed and the appropriate characters will be
escaped (e.g. "&" will be translated to "&amp;").  Attribute values
that are expressed as Symbol values will not be processed for escaped
characters and will be unchanged in output. (Yes, this probably counts
as Symbol abuse, but the convention is convenient and flexible).

Example:

```ruby
  xml = Builder::XmlMarkup.new
  xml.sample(:escaped=>"This&That", :unescaped=>:"Here&There")
  xml.target!  =>
    
```

### Version 1.0.0 Compatibility Changes

Version 1.0.0 introduces some changes that are not backwards
compatible with earlier releases of builder.  The main areas of
incompatibility are:

* Keyword based arguments to +new+ (rather than positional based).  It
  was found that a developer would often like to specify indentation
  without providing an explicit target, or specify a target without
  indentation.  Keyword based arguments handle this situation nicely.

* Builder must now be an explicit target for markup tags.  Instead of
  writing

```ruby
    xml_markup = Builder::XmlMarkup.new
    xml_markup.div { strong("text") }
```

  you need to write

```ruby
    xml_markup = Builder::XmlMarkup.new
    xml_markup.div { xml_markup.strong("text") }
```

* The builder object is passed as a parameter to all nested markup
  blocks.  This allows you to create a short alias for the builder
  object that can be used within the block.  For example, the previous
  example can be written as:

```ruby
    xml_markup = Builder::XmlMarkup.new
    xml_markup.div { |xml| xml.strong("text") }
```

* If you have both a pre-1.0 and a post-1.0 gem of builder installed,
  you can choose which version to use through the RubyGems
  +require_gem+ facility.

```ruby
    require_gem 'builder', "~> 0.0"   # Gets the old version
    require_gem 'builder', "~> 1.0"   # Gets the new version
```

## Features

* XML Comments are supported ...

```ruby
    xml_markup.comment! "This is a comment"
      #=>  
```

* XML processing instructions are supported ...

```ruby
    xml_markup.instruct! :xml, :version=>"1.0", :encoding=>"UTF-8"
      #=>  
```

  If the processing instruction is omitted, it defaults to "xml".
  When the processing instruction is "xml", the defaults attributes
  are:

  version: 1.0
  encoding: "UTF-8"

  (NOTE: if the encoding is set to "UTF-8" and $KCODE is set to
  "UTF8", then Builder will emit UTF-8 encoded strings rather than
  encoding non-ASCII characters as entities.)

* XML entity declarations are now supported to a small degree.

```ruby
    xml_markup.declare! :DOCTYPE, :chapter, :SYSTEM, "../dtds/chapter.dtd"
      #=>  
```

  The parameters to a declare! method must be either symbols or
  strings. Symbols are inserted without quotes, and strings are
  inserted with double quotes.  Attribute-like arguments in hashes are
  not allowed.

  If you need to have an argument to declare! be inserted without
  quotes, but the argument does not conform to the typical Ruby
  syntax for symbols, then use the :"string" form to specify a symbol.

  For example:

```ruby
    xml_markup.declare! :ELEMENT, :chapter, :"(title,para+)"
      #=>  
```

  Nested entity declarations are allowed.  For example:

```ruby
    @xml_markup.declare! :DOCTYPE, :chapter do |x|
      x.declare! :ELEMENT, :chapter, :"(title,para+)"
      x.declare! :ELEMENT, :title, :"(#PCDATA)"
      x.declare! :ELEMENT, :para, :"(#PCDATA)"
    end

    #=>

    
      
      
    ]>
```

* Some support for XML namespaces is now available.  If the first
  argument to a tag call is a symbol, it will be joined to the tag to
  produce a namespace:tag combination.  It is easier to show this than
  describe it.

```ruby
   xml.SOAP :Envelope do ... end
```

  Just put a space before the colon in a namespace to produce the
  right form for builder (e.g. "SOAP:Envelope" =>
  "xml.SOAP :Envelope")

* String attribute values are now escaped by default by
  Builder (NOTE: this is _new_ behavior as of version 2.0).

  However, occasionally you need to use entities in attribute values.
  Using a symbol (rather than a string) for an attribute value will
  cause Builder to not run its quoting/escaping algorithm on that
  particular value.

  (Note: The +escape_attrs+ option for builder is now
  obsolete).

  Example:

```ruby
    xml = Builder::XmlMarkup.new
    xml.sample(:escaped=>"This&That", :unescaped=>:"Here&There")
    xml.target!  =>
      
```

* UTF-8 Support

  Builder correctly translates UTF-8 characters into valid XML.  (New
  in version 2.0.0).  Thanks to Sam Ruby for the translation code.

  You can get UTF-8 encoded output by making sure that the XML
  encoding is set to "UTF-8" and that the $KCODE variable is set to
  "UTF8".

```ruby
    $KCODE = 'UTF8'
    xml = Builder::Markup.new
    xml.instruct!(:xml, :encoding => "UTF-8")
    xml.sample("Iñtërnâtiônàl")
    xml.target!  =>
      "Iñtërnâtiônàl"
```

## Links

| Description | Link |
| :----: | :----: |
| Documents           | http://builder.rubyforge.org/ |
| Github Clone        | git://github.com/rails/builder.git |
| Issue / Bug Reports | https://github.com/rails/builder/issues?state=open |

## Contact

| Description | Value                  |
| :----:      | :----:                 |
| Author      | Jim Weirich            |
| Email       | jim.weirich@gmail.com  |
| Home Page   | http://onestepback.org |
| License     | MIT Licence (http://www.opensource.org/licenses/mit-license.html) |

Owner metadata

Name: Ruby on Rails
Login: rails
Email:
Kind: organization
Description:
Website: https://rubyonrails.org/
Location:
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/4223?v=4
Repositories: 116
Last ynced at: 2023-04-09T03:40:20.529Z
Profile URL: https://github.com/rails

GitHub Events

Total

Watch event: 2
Pull request event: 1
Fork event: 2

Last Year

Watch event: 2
Pull request event: 1
Fork event: 2

Committers metadata

Last synced: 3 days ago

Total Commits: 224
Total Committers: 34
Avg Commits per committer: 6.588
Development Distribution Score (DDS): 0.661

Commits in past year: 0
Committers in past year: 0
Avg Commits per committer in past year: 0.0
Development Distribution Score (DDS) in past year: 0.0

Name	Email	Commits
jimweirich	j**h@b**6	76
Jim Weirich	j**h@g**m	67
tom	t**m@b**6	22
htonl	h**l@b**6	8
Aaron Patterson	a**n@g**m	6
Jean Boussier	j**r@g**m	6
Vít Ondruch	v**h@r**m	4
Matthew Rudy Jacobs	m**s@g**m	3
Bart ten Brinke	i**o@r**m	2
Eric Hodel	d**n@s**t	2
Jun Aruga	j**a@r**m	2
Tim Krins	t**s@g**m	2
krisquigley	k**s@k**k	2
Dermot Haughey	h**s@g**m	2
sanemat	o**n@g**m	1
sandstrom	a**r@s**m	1
hadley wickham	h**m@g**m	1
(no author)	(**)@b**6	1
epinault	e**t@o**o	1
gforge	g**e@b**6	1
tcarrico	t**o@b**6	1
benlovell	b**l@g**m	1
Robert	h**b@e**m	1
Pat Allan	p**t@f**m	1
Orien Madgwick	_@o****o	1
Nikita Afanasenko	n**a@a**e	1
Nathan Phillip Brink	b**i@g**g	1
Keenan Brock	k**n@t**t	1
Jeffrey Hulten	j**h@a**m	1
Hosam Aly	h**6@g**m	1
and 4 more...

Committer domains:

Issue and Pull Request metadata

Last synced: about 1 month ago

Total issues: 6
Total pull requests: 20
Average time to close issues: over 2 years
Average time to close pull requests: about 1 year
Total issue authors: 6
Total pull request authors: 14
Average comments per issue: 1.0
Average comments per pull request: 0.4
Merged pull request: 17
Bot issues: 0
Bot pull requests: 0

Past year issues: 0
Past year pull requests: 1
Past year average time to close issues: N/A
Past year average time to close pull requests: N/A
Past year issue authors: 0
Past year pull request authors: 1
Past year average comments per issue: 0
Past year average comments per pull request: 0.0
Past year merged pull request: 0
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/rails/builder

Top Issue Authors

thijsnado (1)
gavingmiller (1)
etdsoft (1)
voxik (1)
rtirkeyDiligent (1)
aks (1)

Top Pull Request Authors

voxik (4)
kbrock (3)
junaruga (2)
okuramasafumi (2)
casperisfine (2)
Earlopain (2)
epinault (1)
timkrins (1)
krisquigley (1)
hosamaly (1)
orien (1)
sandstrom (1)
tiendo1011 (1)
pat (1)

Top Issue Labels

Top Pull Request Labels

Package metadata

Total packages: 2
Total downloads:
- rubygems: 1,652,586,683 total
Total docker downloads: 2,361,115,798
Total dependent packages: 1,270 (may contain duplicates)
Total dependent repositories: 939,517 (may contain duplicates)
Total versions: 50
Total maintainers: 11

gem.coop: builder

Builder provides a number of builder objects that make creating structured data simple to do. Currently the following builder objects are supported: * XML Markup * XML Events

Homepage: https://github.com/rails/builder
Documentation: http://www.rubydoc.info/gems/builder/
Licenses: MIT
Latest release: 3.3.0 (published over 1 year ago)
Last Synced: 2025-12-09T17:01:29.401Z (2 days ago)
Versions: 25
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 826,606,605 Total
Docker Downloads: 1,180,557,899
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Downloads: 0.017%
- Average: 0.022%
- Docker downloads count: 0.07%
Maintainers (11)
- tenderlove
- webster132
- fxn
- cantoniodasilva
- rafaelfranca
- jeremydaer
- matthewd
- eileencodes
- byroot
- jimweirich
- htonl

rubygems.org: builder