https://github.com/rubyworks/raml
Ruby Ambidextrous Metadata Language
https://github.com/rubyworks/raml
Last synced: 8 months ago
JSON representation
Ruby Ambidextrous Metadata Language
- Host: GitHub
- URL: https://github.com/rubyworks/raml
- Owner: rubyworks
- License: other
- Created: 2010-09-22T23:03:44.000Z (over 15 years ago)
- Default Branch: master
- Last Pushed: 2012-05-27T19:54:53.000Z (over 13 years ago)
- Last Synced: 2024-04-23T13:26:46.077Z (almost 2 years ago)
- Language: Ruby
- Homepage: http://rubyworks.github.com/raml
- Size: 199 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.rdoc
- Changelog: HISTORY.rdoc
- License: COPYING.rdoc
Awesome Lists containing this project
README
= Ruby Ambidextrous Meta-Language
{Homepage}[http://rubyworks.github.com/raml] |
{Source Code}[http://github.com/rubyworks/raml] |
{Mailing List}[http://googlegroups.com/group/rubyworks-mailinglist]
{IRC}[irc://chat.us.freenode.net/rubyworks]
{
}[http://travis-ci.org/rubyworks/raml]
== 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 (c) 2010 Rubyworks
RAML is distributed under the terms of the *FreeBSD* License.
See COPYING.rdoc for details.