¶ ↑
Ruby Ambidextrous Meta-LanguageHomepage | Source Code | Mailing List IRC
<img src=“http://travis-ci.org/rubyworks/raml.png” />
¶ ↑
DESCRIPTIONRAML is a flexible data format suitable for a variety of uses, such as configuration files.
Admittedly, “Ruby Ambidextrous Meta-Language” is a funny name. But nonetheless fitting, because unlike YAML, RAML can handle a wider variety of data format design needs, even limited markup formats. Unlike YAML, RAML is not a serialization language.
¶ ↑
SYNOPSISA RAML document is Ruby code operating under a set of open domain language rules. An example RAML document looks like this:
source "http://rubygems.org" example "this", 10, true another do name "Tonto" age 42 weight 229 end
Loading this document in via RAML would produce the following Hash:
{:source=>"http://rubygems.org", :example=>["this", 10, true], :another=>{:name=>"Tonto", :age=>42, :weight=>229}}
Loading is handled by the ‘RAML.load` method. The method can take a string,
RAML.load("name 'Bob'")
Or an IO object,
RAML.load(File.new('foo.rml'))
The method also takes a ‘:safe` option that is used to set the level of evaluation Ruby is allowed.
RAML.load(raml, :safe=>true)
If the option is ‘false`, which is the default, than evaluation is handled with `$SAFE=0`. If `true` then $SAFE=4. Safe evaluation is useful when loading untrusted data files. With `$SAFE=4` most (though not all) security concerns are mitigated.
For a complete lock-down on evaluation, allowing only data settings and no other forms of Ruby evaluation, ‘RAML.load` supports the `:eval` option. By default it is set to `true`. By setting it to `false` (but not `nil`), all code evaluation can be turned off.
RAML.load(raml, :eval=>false)
Under the hood the current implementation has two different parsers, a Ripper based parser and a Kernel.eval based parser. By setting ‘:eval=>false` the Ripper parser is used rather than the regular eval parser.
For additional examples and details on working with RAML files, see the QED demonstrandum.
¶ ↑
IMPORTANT NOTEThe Ripper based parser is not yet robust and is NOT RECOMMENDED FOR PRODUCTION USE, as it will parse invalid RAML documents without complaint. The eval parser on the other hand works well.
¶ ↑
SPECIAL THANKSBig props to Robert Dober for taking the time to help me improve the code.
¶ ↑
COPYRIGHTSCopyright © 2010 Rubyworks
RAML is distributed under the terms of the FreeBSD License. See COPYING.rdoc for details.