1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
|
# Gyoku
Gyoku translates Ruby Hashes to XML.
``` ruby
Gyoku.xml(:find_user => { :id => 123, "v1:Key" => "api" })
# => "<findUser><id>123</id><v1:Key>api</v1:Key></findUser>"
```
[![Build Status](https://secure.travis-ci.org/savonrb/gyoku.png?branch=master)](http://travis-ci.org/savonrb/gyoku)
[![Gem Version](https://badge.fury.io/rb/gyoku.png)](http://badge.fury.io/rb/gyoku)
[![Code Climate](https://codeclimate.com/github/savonrb/gyoku.png)](https://codeclimate.com/github/savonrb/gyoku)
[![Coverage Status](https://coveralls.io/repos/savonrb/gyoku/badge.png?branch=master)](https://coveralls.io/r/savonrb/gyoku)
## Installation
Gyoku is available through [Rubygems](http://rubygems.org/gems/gyoku) and can be installed via:
``` bash
$ gem install gyoku
```
or add it to your Gemfile like this:
``` ruby
gem 'gyoku', '~> 1.0'
```
## Hash keys
Hash key Symbols are converted to lowerCamelCase Strings.
``` ruby
Gyoku.xml(:lower_camel_case => "key")
# => "<lowerCamelCase>key</lowerCamelCase>"
```
You can change the default conversion formula to `:camelcase`, `:upcase` or `:none`.
Note that options are passed as a second Hash to the `.xml` method.
``` ruby
Gyoku.xml({ :camel_case => "key" }, { :key_converter => :camelcase })
# => "<CamelCase>key</CamelCase>"
```
Hash key Strings are not converted and may contain namespaces.
``` ruby
Gyoku.xml("XML" => "key")
# => "<XML>key</XML>"
```
## Hash values
* DateTime objects are converted to xs:dateTime Strings
* Objects responding to :to_datetime (except Strings) are converted to xs:dateTime Strings
* TrueClass and FalseClass objects are converted to "true" and "false" Strings
* NilClass objects are converted to xsi:nil tags
* These conventions are also applied to the return value of objects responding to :call
* All other objects are converted to Strings using :to_s
## Special characters
Gyoku escapes special characters unless the Hash key ends with an exclamation mark.
``` ruby
Gyoku.xml(:escaped => "<tag />", :not_escaped! => "<tag />")
# => "<escaped><tag /></escaped><notEscaped><tag /></notEscaped>"
```
## Self-closing tags
Hash Keys ending with a forward slash create self-closing tags.
``` ruby
Gyoku.xml(:"self_closing/" => "", "selfClosing/" => nil)
# => "<selfClosing/><selfClosing/>"
```
## Sort XML tags
In case you need the XML tags to be in a specific order, you can specify the order
through an additional Array stored under the `:order!` key.
``` ruby
Gyoku.xml(:name => "Eve", :id => 1, :order! => [:id, :name])
# => "<id>1</id><name>Eve</name>"
```
## XML attributes
Adding XML attributes is rather ugly, but it can be done by specifying an additional
Hash stored under the`:attributes!` key.
``` ruby
Gyoku.xml(:person => "Eve", :attributes! => { :person => { :id => 1 } })
# => "<person id=\"1\">Eve</person>"
```
## Explicit XML Attributes
In addition to using the `:attributes!` key, you may also specify attributes through keys beginning with an "@" sign.
Since you'll need to set the attribute within the hash containing the node's contents, a `:content!` key can be used
to explicity set the content of the node. The `:content!` value may be a String, Hash, or Array.
This is particularly useful for self-closing tags.
**Using :attributes!**
``` ruby
Gyoku.xml(
"foo/" => "",
:attributes! => {
"foo/" => {
"bar" => "1",
"biz" => "2",
"baz" => "3"
}
}
)
# => "<foo baz=\"3\" bar=\"1\" biz=\"2\"/>"
```
**Using "@" keys and ":content!"**
``` ruby
Gyoku.xml(
"foo/" => {
:@bar => "1",
:@biz => "2",
:@baz => "3",
:content! => ""
})
# => "<foo baz=\"3\" bar=\"1\" biz=\"2\"/>"
```
**Example using "@" to get Array of parent tags each with @attributes & :content!**
``` ruby
Gyoku.xml(
"foo" => [
{:@name => "bar", :content! => 'gyoku'}
{:@name => "baz", :@some => "attr", :content! => 'rocks!'}
])
# => "<foo name=\"bar\">gyoku</foo><foo name=\"baz\" some=\"attr\">rocks!</foo>"
```
Naturally, it would ignore :content! if tag is self-closing:
``` ruby
Gyoku.xml(
"foo/" => [
{:@name => "bar", :content! => 'gyoku'}
{:@name => "baz", :@some => "attr", :content! => 'rocks!'}
])
# => "<foo name=\"bar\"/><foo name=\"baz\" some=\"attr\"/>"
```
This seems a bit more explicit with the attributes rather than having to maintain a hash of attributes.
For backward compatibility, `:attributes!` will still work. However, "@" keys will override `:attributes!` keys
if there is a conflict.
``` ruby
Gyoku.xml(:person => {:content! => "Adam", :@id! => 0})
# => "<person id=\"0\">Adam</person>"
```
**Example with ":content!", :attributes! and "@" keys**
``` ruby
Gyoku.xml({
:subtitle => {
:@lang => "en",
:content! => "It's Godzilla!"
},
:attributes! => { :subtitle => { "lang" => "jp" } }
}
# => "<subtitle lang=\"en\">It's Godzilla!</subtitle>"
```
The example above shows an example of how you can use all three at the same time.
Notice that we have the attribute "lang" defined twice.
The `@lang` value takes precedence over the `:attribute![:subtitle]["lang"]` value.
|