Ruby Ambidextrous Meta-Language¶ ↑

Homepage | Source Code | Mailing List IRC

<img src=“http://travis-ci.org/rubyworks/raml.png” />

DESCRIPTION¶ ↑

RAML 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.

SYNOPSIS¶ ↑

A 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 NOTE¶ ↑

The 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 THANKS¶ ↑

Big props to Robert Dober for taking the time to help me improve the code.

COPYRIGHTS¶ ↑

Copyright © 2010 Rubyworks

RAML is distributed under the terms of the FreeBSD License. See COPYING.rdoc for details.