raml 0.2.0

data/.ruby

@@ -0,0 +1,42 @@
+---
+source:
+- meta
+authors:
+- name: 7rans
+  email: transfire@gmail.com
+copyrights:
+- holder: Rubyworks
+  year: '2010'
+replacements: []
+alternatives: []
+requirements:
+- name: blankslate
+- name: detroit
+  groups:
+  - build
+  development: true
+- name: qed
+  groups:
+  - test
+  development: true
+dependencies: []
+conflicts: []
+repositories: []
+resources:
+  home: http://rubyworks.github.com/raml
+  code: http://github.com/rubyworks/raml
+  docs: http://rubydoc.info/gems/raml/frames
+  mail: http://groups.google.com/group/rubyworks-mailinglist
+  gems: http://rubygems.org/gems/raml
+extra: {}
+load_path:
+- lib
+revision: 0
+created: '2010-09-21'
+summary: Ruby Syntax Data Language
+title: RAML
+version: 0.2.0
+name: raml
+description: RAML is a Ruby-syntax-based data language.
+organization: rubyworks
+date: '2011-10-28'

data/.yardopts

@@ -0,0 +1,8 @@
+--title "RAML"
+--readme README.rdoc
+--protected
+--private
+lib/**/*.rb
+-
+[A-Z]*.*
+

data/COPYING.rdoc

@@ -0,0 +1,31 @@
+= COPYRIGHT NOTICES
+
+== RAML
+
+Copyright:: (c) 2010 Thomas Sawyer, Rubyworks
+License:: BSD-2-Clause
+Website:: http://rubyworks.github.com/raml
+
+    Copyright 2011 Thomas Sawyer. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+
+       1. Redistributions of source code must retain the above copyright notice,
+          this list of conditions and the following disclaimer.
+
+       2. Redistributions in binary form must reproduce the above copyright
+          notice, this list of conditions and the following disclaimer in the
+          documentation and/or other materials provided with the distribution.
+
+    THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+    INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+    AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+    COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR  SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+    OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+    EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/HISTORY.rdoc

@@ -0,0 +1,12 @@
+= RELEASE HISTORY
+
+== 0.1.0 | 2010-09-28
+
+A very early release of RAML, presently only supporting an eval-based parser.
+Ultimately the intent is to provide a true parser, that can restict the format
+to pure data.
+
+Changes:
+
+* Initial implementation.
+

data/QED.rdoc

@@ -0,0 +1,217 @@
+= RAML.eval
+
+The RAML.eval() method parses a RAML document using the Kernel.eval.
+In this way Ruby scripting can still be utilized within the document.
+
+Require the RAML library.
+
+  require 'raml'
+
+Given a RAML document:
+
+  website "http://rubygems.org"
+
+We can load the text via the #load method. (Note above document text has
+been placed in the @text variable.)
+
+  data = RAML.eval(@text)
+
+  data.assert == {:website=>"http://rubygems.org"}
+
+One of the nicer features of RAML derives from Ruby's block notation, allowing
+for nested entries.
+
+Given a RAML document:
+
+  resources do
+    home "http://rubyworks.github.com/raml"
+    docs "http://rubyworks.github.com/raml/docs/api"
+    wiki "http://wiki.rubyworks.github.com/raml"
+  end
+
+We get a two layer hash.
+
+  data = RAML.eval(@text)
+
+  data[:resources][:home].assert == "http://rubyworks.github.com/raml"
+  data[:resources][:docs].assert == "http://rubyworks.github.com/raml/docs/api"
+  data[:resources][:wiki].assert == "http://wiki.rubyworks.github.com/raml"
+
+RAML is also considers the content of a block. If it is a scalar entry,
+such as a String, then that will be assigned to the key.
+
+Given a RAML document:
+
+  description %{
+    This is a description.
+    It can have multiple lines.
+    RAML handles this just fine,
+    because Ruby does too.
+  }
+
+Loading this document, description will contain the text as expected.
+
+  data = RAML.eval(@text)
+
+  text = data[:description].sub(/\s+/, ' ').strip
+
+  text.assert.start_with?("This is")
+  text.assert.end_with?("does too.")
+
+It is only unfortunate that Ruby doesn't have a margin controlled string
+notation (e.g. `%L{ }`) so that post processing with `sub()` would not
+be neccessary.
+
+RAML has some options that makes it more flexible than many other data
+lanaguages. For instance, it can allow for multi-key entries.
+
+Given a RAML document:
+
+  source "http://rubygems.org"
+  gem "facets", "~> 2.8"
+  gem "ansi", "~> 1.1"
+
+We simply need to inform the loader to allow identical keys.
+
+  data = RAML.eval(@text, :multikey=>true)
+
+  data.assert == {
+    :source=>"http://rubygems.org",
+    :gem=>[["facets", "~> 2.8"],["ansi", "~> 1.1"]]
+  }
+
+If we did not turn on the multi-key option, then the last `gem` entry
+would have simply overwritten the former.
+
+  data = RAML.eval(@text)
+
+  data.assert == {
+    :source=>"http://rubygems.org",
+    :gem=>["ansi", "~> 1.1"]
+  }
+
+Not let's show-off the benefit of using RAML.eval instead of RAML.load.
+
+Given a RAML document:
+
+  sum 1 + 1
+
+We will see that the value of `sum` will be evaluated as 2.
+
+  data = RAML.eval(@text)
+
+  data.assert == {:sum=>2}
+
+
+= RAML.read
+
+The RAML.read() method parses a RAML document using Ripper.
+In this way a RAML document is treated purely as data and cannot
+contain any Ruby scripting.
+
+Require the RAML library.
+
+  require 'raml'
+
+Given a RAML document:
+
+  website "http://rubygems.org"
+
+We can load the text via the #read method. (Note above document text has
+been placed in the @text variable.)
+
+  data = RAML.read(@text)
+
+  data.assert == {:website=>"http://rubygems.org"}
+
+One of the nicer features of RAML derives from Ruby's block notation, allowing
+for nested entries.
+
+Given a RAML document:
+
+  resources do
+    home "http://rubyworks.github.com/raml"
+    docs "http://rubyworks.github.com/raml/docs/api"
+    wiki "http://wiki.rubyworks.github.com/raml"
+  end
+
+We get a two layer hash.
+
+  data = RAML.read(@text)
+
+  data[:resources][:home].assert == "http://rubyworks.github.com/raml"
+  data[:resources][:docs].assert == "http://rubyworks.github.com/raml/docs/api"
+  data[:resources][:wiki].assert == "http://wiki.rubyworks.github.com/raml"
+
+RAML is also considers the content of a block. If it is a scalar entry,
+such as a String, then that will be assigned to the key.
+
+Given a RAML document:
+
+  description %{
+    This is a description.
+    It can have multiple lines.
+    RAML handles this just fine,
+    because Ruby does too.
+  }
+
+Loading this document, description will contain the text as expected.
+
+  data = RAML.read(@text)
+
+  text = data[:description].sub(/\s+/, ' ').strip
+
+  text.assert.start_with?("This is")
+  text.assert.end_with?("does too.")
+
+It is only unfortunate that Ruby doesn't have a margin controlled string
+notation (e.g. `%L{ }`) so that post processing with `sub()` would not
+be neccessary.
+
+RAML has some options that makes it more flexible than many other data
+lanaguages. For instance, it can allow for multi-key entries.
+
+Given a RAML document:
+
+  source "http://rubygems.org"
+  gem "facets", "~> 2.8"
+  gem "ansi", "~> 1.1"
+
+We simply need to inform the reader to allow identical keys.
+
+  data = RAML.read(@text, :multikey=>true)
+
+  data.assert == {
+    :source=>"http://rubygems.org",
+    :gem=>[["facets", "~> 2.8"],["ansi", "~> 1.1"]]
+  }
+
+If we did not turn on the multi-key option, then the last `gem` entry
+would have simply overwritten the former.
+
+  data = RAML.read(@text)
+
+  data.assert == {
+    :source=>"http://rubygems.org",
+    :gem=>["ansi", "~> 1.1"]
+  }
+
+Not let's show-off the benefit of using RAML.read instead of RAML.eval.
+
+Given a RAML document:
+
+  sum "word".upcase
+
+We will see that the result of calling `#upcase` CANNOT be evaluated and
+will raise an error.
+
+  expect Exception do
+    data = RAML.read(@text)
+  end if RUBY_VERSION >= '1.9'
+
+Note, this last assertion is only true for Ruby 1.9+, becuase Ripper is
+not supported by older versions of Ruby.
+
+
+
+

data/README.rdoc

@@ -0,0 +1,92 @@
+= 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]
+
+{<img src="http://travis-ci.org/rubyworks/raml.png" />}[http://travis-ci.org/rubyworks/raml]
+
+
+== DESCRIPTION
+
+RAML is a flexable data format suitable for a variety of uses, such
+as configuration files.
+
+Admittedly, "Ruby Ambidextrous Meta-Language" is a funny name. But
+nonetheless fitting, becuase 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 an `:safe` option that is used to set the level evaluation
+Ruby is allowed. If the option is `false`, the default, than evaluation is handled
+with Ruby `$SAFE=0`. If `true` the $SAFE=4.
+
+  RAML.load(raml, :safe=>true)
+
+Safe evaluation is useful when loading untrusted data files. With `$SAFE=4`
+most (though not all) security concerns are mitigated.
+
+For a complete lockdown on evaluation, allowing only data setting and no other
+forms of Ruby evaluation, `RAML.load` supports the `:eval` option. By default
+it is `true`. By setting it to `false` (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 <b>Robert Dober</b> 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.
+

data/lib/raml.rb

@@ -0,0 +1,110 @@
+require 'raml/eval_parser'
+
+if RUBY_VERSION > '1.9'
+  require 'raml/ripper_parser'
+end
+
+module RAML
+
+  # Load a RAML document. Like `eval()` but parses the document
+  # via Ripper, ensuring a pure data format.
+  #
+  # IMPORTANT: Ruby 1.8.x and older does not support Ripper.
+  # In this case RAML falls back to using `eval()` with $SAFE = 4.
+  #
+  # Arguments
+  #
+  #   io - a String, File or any object that responds to #read.
+  #
+  # Options
+  #
+  #   :eval     - false for data-only parser
+  #   :safe     - true sets $SAFE=4
+  #   :keep     - public methods to keep in scope
+  #   :scope    - an object to act as the evaluation context
+  #   :multikey - handle duplicate keys
+  #
+  # Returns [Hash] data parsed from document.
+  def self.load(io, options={})
+    if FalseClass === options[:eval]
+      read(io, options)
+    else
+      eval(io, options)
+    end
+  end
+
+  # Evaluate a RAML document. Like `load()` but parses the  document via #eval.
+  # (same as load with :eval=>true). This can be done a $SAFE level 4 by
+  # setting the :safe option to +true+.
+  #
+  # Arguments
+  #
+  #   io - a String, File or any object that responds to #read.
+  #
+  # Options
+  #
+  #   :safe     - true/false
+  #   :keep     - public methods to keep in scope
+  #   :scope    - an object to act as the evaluation context
+  #   :multikey - handle duplicate keys
+  #
+  # Returns [Hash] data parsed from document.
+  def self.eval(io, options={})
+    code, file = io(io)
+    parser = RAML::EvalParser.new(options)
+    parser.parse(code, file)
+  end
+
+  # Read in a RAML document. Like `load()` but parses the  document via Ripper
+  # (same as load with :eval=>false). This only work in Ruby 1.9+, otherwise it
+  # falls back to the eval parer with `:safe=>true`.
+  #
+  # Arguments
+  #
+  #   io - a String, File or any object that responds to #read.
+  #
+  # Options
+  #
+  #   :keep     - public methods to keep in scope
+  #   :scope    - an object to act as the evaluation context
+  #   :multikey - handle duplicate keys
+  #
+  # Returns [Hash] data parsed from document.
+  def self.read(io, options={})
+    code, file = io(io)
+    if RUBY_VERSION > '1.9'
+      parser = RAML::RipperParser.new(options)
+    else
+      options[:safe] = true
+      parser = RAML::EvalParser.new(options)
+    end
+    parser.parse(code, file)
+  end
+
+  private
+
+  # Take a String, File, IO or any object that respons to #read
+  # and return the string or result of calling #read and the
+  # file name if any and "(eval)" if not.
+  #
+  # Arguments
+  #
+  #   io - a String, File or any object that responds to #read.
+  #
+  # Returns [String, String] text of string or file and file name or "(eval)".
+  def self.io(io)
+    case io
+    when String
+      file = '(eval)'
+      code = io
+    when File
+      file = io.path
+      code = io.read
+    else #IO
+      file = '(eval)'
+      code = io.read
+    end
+    return code, file
+  end
+
+end

data/lib/raml.yml

@@ -0,0 +1,42 @@
+---
+source:
+- meta
+authors:
+- name: 7rans
+  email: transfire@gmail.com
+copyrights:
+- holder: Rubyworks
+  year: '2010'
+replacements: []
+alternatives: []
+requirements:
+- name: blankslate
+- name: detroit
+  groups:
+  - build
+  development: true
+- name: qed
+  groups:
+  - test
+  development: true
+dependencies: []
+conflicts: []
+repositories: []
+resources:
+  home: http://rubyworks.github.com/raml
+  code: http://github.com/rubyworks/raml
+  docs: http://rubydoc.info/gems/raml/frames
+  mail: http://groups.google.com/group/rubyworks-mailinglist
+  gems: http://rubygems.org/gems/raml
+extra: {}
+load_path:
+- lib
+revision: 0
+created: '2010-09-21'
+summary: Ruby Syntax Data Language
+title: RAML
+version: 0.2.0
+name: raml
+description: RAML is a Ruby-syntax-based data language.
+organization: rubyworks
+date: '2011-10-28'

data/lib/raml/core_ext.rb

@@ -0,0 +1,13 @@
+class String
+
+  # Combine with string with a newline between each.
+  #
+  # Examples
+  #
+  #   "foo" ^ "bar"  #=> "foo\nbar"
+  #
+  def ^(string)
+    self + "\n" + string.to_s
+  end
+
+end

data/lib/raml/eval_parser.rb

@@ -0,0 +1,149 @@
+require 'thread'
+require 'raml/multi_value'
+
+unless defined?(::BasicObject)
+  require 'blankslate'
+  BasicObject = BlankSlate
+end
+
+module RAML
+
+  # The EvalParser parses RAML documents using standard Ruby evaluation.
+  # This has some limitations, but also some benefits.
+  #
+  # Unlike the pure data evaluator, the ruby evaluator can be instructed to
+  # keep methods available for access, as well as use a custom scope.
+  #
+  class EvalParser
+
+    #
+    SAFE = 4
+
+    # Need tainted data store.
+    HASH = {}.taint
+
+    #
+    attr :options
+
+    # You can pass in an object to act as the scope. All non-essential public
+    # and private Object methods will be removed from the scope unless a `keep`
+    # string or regex matches the name. Protected methods are also kept intact.
+    def initialize(options={})
+      @options   = options
+
+      self.safe      = options[:safe]
+      #self.file      = options[:file]
+      self.keep      = options[:keep]
+      self.scope     = options[:scope] || BasicObject.new
+      self.multi_key = options[:multikey]
+    end
+
+    #
+    def safe?
+      @safe
+    end
+
+    #
+    def safe=(boolean)
+      @safe = !!boolean
+    end
+
+    # Returns 4 is safe is true, otherwise 0.
+    def safe_level
+      safe? ? 4 : 0
+    end
+
+    # Returns Array<Regexp>.
+    attr_reader :keep
+
+    def keep=(list)
+      @keep = [list].compact.flatten
+    end
+
+    ## Returns [String] file name.
+    #attr_accessor :file
+
+    # Returns [Boolean] true/false.
+    def multi_key?
+      @multi_key
+    end
+
+    #
+    def multi_key=(bool)
+      @multi_key = !!bool
+    end
+
+    # Returns [BasicObject,Object] scope object.
+    attr_reader :scope
+
+    # Sets the scope object while preparing it for use as the evaluation
+    # context.
+    def scope=(object)
+      @scope ||= (
+        #qua_class = (class << object; self; end)
+        #methods = [object.public_methods, Object.private_instance_methods].flatten
+        #methods.each do |m|
+        #  next if /^(__|instance_|singleton_method_|binding$|method_missing$|extend$|initialize$|object_id$|p$)/ =~ m.to_s
+        #  next if keep.any?{ |k| k === m.to_s }
+        #  qua_class.__send__(:undef_method, m)
+        #end
+        parser = self
+        object.instance_eval{ @__parser__ = parser }
+        #object.instance_eval{ extend MethodMissing }
+        MethodMissing.__send__(:extend_object, object)
+        object
+      )
+    end
+
+    #
+    def parse(code=nil, file=nil, &block)
+      data = HASH.dup
+
+      scope.instance_eval{ @__data__ = data}
+
+      result = nil
+
+      thread = Thread.new do
+        $SAFE = safe_level unless $SAFE == safe_level
+        result = if block
+          scope.instance_eval(&block)
+        else
+          scope.instance_eval(code, file)
+        end
+      end
+
+      thread.join
+
+      return result if data.empty?  # good idea?
+      return data
+    end
+
+    #
+    module MethodMissing
+      #
+      def method_missing(name, *args, &block)
+        return @__data__[name] if args.empty? and !block
+        if block
+          val = EvalParser.new(@__parser__.options).parse(&block)
+        else
+          val = args.size == 1 ? args.first : args
+        end
+        if @__parser__.multi_key?
+          if @__data__.key?(name)
+            unless MultiValue === @__data__[name]
+              @__data__[name] = MultiValue.new(@__data__[name])
+            end
+            @__data__[name] << val
+          else
+            @__data__[name] = val
+          end
+        else
+          @__data__[name] = val
+          val
+        end
+      end
+    end
+
+  end
+
+end

data/lib/raml/multi_value.rb

@@ -0,0 +1,12 @@
+module RAML
+
+  # The MultiValue class is simply an Array. It is used to distinguish
+  # an Array value from a multi-key entry.
+  class MultiValue < Array
+    #
+    def initialize(*elements)
+      replace(elements)
+    end
+  end
+
+end

data/lib/raml/ripper_parser.rb

@@ -0,0 +1,151 @@
+require 'ripper'
+require 'pp'
+require 'raml/multi_value'
+
+module RAML
+
+  # RAML document parser utilizoing Ripper.
+  #
+  # NOTE: This code is probably far from robust and is almost certainly not
+  # best the approach to implmentation. But your humble author is no expert
+  # on Ripper or parsers in general.
+  #
+  # FIXME: This class needs work. I currently handles basic cases, but will
+  # incorrectly parse complex cases.
+  #
+  # FIXME: Add non hash block value support.
+  class RipperParser
+
+    def initialize(options={})
+      @options   = options
+
+      self.multi_key = options[:multikey]
+    end
+
+    # Returns [Boolean] true/false.
+    def multi_key?
+      @multi_key
+    end
+
+    # Set multi-key option.
+    def multi_key=(bool)
+      @multi_key = !!bool
+    end
+
+    # Parse the RAML document via Ripper.
+    def parse(code, file=nil)
+      tree = Ripper::SexpBuilder.new(code).parse
+
+      @k, @v = nil, []
+
+      d = clean(tree)
+      set(d)
+
+      return d
+    end
+
+    private
+
+    #
+    def clean(tree, data={})
+      d = data
+
+      tag, *rest = *tree
+
+      #show(tag, rest)
+
+      case tag.to_s
+      when "@ident"
+        set(d)
+        @k = rest.shift
+      when "@kw"
+        case rest.shift
+        when "nil"   then @v << nil
+        when "true"  then @v << true
+        when "false" then @v << false
+        end
+      when "@int"
+        @v << rest.shift.to_i
+      when "@float"
+        @v << rest.shift.to_f
+      when /^@/
+        @v << rest.shift
+      when "do_block"
+        h = [d, @k, @v]
+        @k, @v = nil, []
+        n = {}
+        rest.each do |r|
+          clean(r, n)
+        end
+        set(n)
+        d, @k, @v = *h
+        @v << n
+        set(d)
+      when '.'
+        raise SyntaxError, "evaluations forbidden"
+      else
+        rest.each do |r|
+          clean(r, d)
+        end
+      end
+
+      return d
+    end
+
+    #
+    def set(data)
+      return unless @k
+      if multi_key?
+        set_multi_key(data)
+      else
+        set_key(data)
+      end
+    end
+
+    #
+    def set_key(data)
+      key = @k.to_sym
+      case @v.size
+      when 0
+        data[key] = nil
+      when 1
+        data[key] = @v.first
+      else
+        data[key] = @v
+      end
+      @k, @v = nil, []
+    end
+
+    #
+    def set_multi_key(data)
+      key = @k.to_sym
+
+      if data.key?(key)
+        unless MultiValue === data[key]
+          data[key] = MultiValue.new(data[key])
+        end
+
+        case @v.size
+        when 1
+          data[key] << @v.first
+        else
+          data[key] << @v
+        end
+        @k, @v = nil, []
+      else
+        set_key(data)
+      end
+    end
+
+    # Used for development purposes only. 
+    def show(name, args)
+      if @options[:debug]
+        puts "#{name}:"
+        p args
+        puts
+      end
+    end
+
+  end
+
+end

data/qed/applique/document.rb

@@ -0,0 +1,4 @@
+When "Given a RAML document" do |text|
+  @text = text
+end
+

data/qed/eval.rdoc

@@ -0,0 +1,104 @@
+= RAML.eval
+
+The RAML.eval() method parses a RAML document using the Kernel.eval.
+In this way Ruby scripting can still be utilized within the document.
+
+Require the RAML library.
+
+  require 'raml'
+
+Given a RAML document:
+
+  website "http://rubygems.org"
+
+We can load the text via the #load method. (Note above document text has
+been placed in the @text variable.)
+
+  data = RAML.eval(@text)
+
+  data.assert == {:website=>"http://rubygems.org"}
+
+One of the nicer features of RAML derives from Ruby's block notation, allowing
+for nested entries.
+
+Given a RAML document:
+
+  resources do
+    home "http://rubyworks.github.com/raml"
+    docs "http://rubyworks.github.com/raml/docs/api"
+    wiki "http://wiki.rubyworks.github.com/raml"
+  end
+
+We get a two layer hash.
+
+  data = RAML.eval(@text)
+
+  data[:resources][:home].assert == "http://rubyworks.github.com/raml"
+  data[:resources][:docs].assert == "http://rubyworks.github.com/raml/docs/api"
+  data[:resources][:wiki].assert == "http://wiki.rubyworks.github.com/raml"
+
+RAML is also considers the content of a block. If it is a scalar entry,
+such as a String, then that will be assigned to the key.
+
+Given a RAML document:
+
+  description %{
+    This is a description.
+    It can have multiple lines.
+    RAML handles this just fine,
+    because Ruby does too.
+  }
+
+Loading this document, description will contain the text as expected.
+
+  data = RAML.eval(@text)
+
+  text = data[:description].sub(/\s+/, ' ').strip
+
+  text.assert.start_with?("This is")
+  text.assert.end_with?("does too.")
+
+It is only unfortunate that Ruby doesn't have a margin controlled string
+notation (e.g. `%L{ }`) so that post processing with `sub()` would not
+be neccessary.
+
+RAML has some options that makes it more flexible than many other data
+lanaguages. For instance, it can allow for multi-key entries.
+
+Given a RAML document:
+
+  source "http://rubygems.org"
+  gem "facets", "~> 2.8"
+  gem "ansi", "~> 1.1"
+
+We simply need to inform the loader to allow identical keys.
+
+  data = RAML.eval(@text, :multikey=>true)
+
+  data.assert == {
+    :source=>"http://rubygems.org",
+    :gem=>[["facets", "~> 2.8"],["ansi", "~> 1.1"]]
+  }
+
+If we did not turn on the multi-key option, then the last `gem` entry
+would have simply overwritten the former.
+
+  data = RAML.eval(@text)
+
+  data.assert == {
+    :source=>"http://rubygems.org",
+    :gem=>["ansi", "~> 1.1"]
+  }
+
+Not let's show-off the benefit of using RAML.eval instead of RAML.load.
+
+Given a RAML document:
+
+  sum 1 + 1
+
+We will see that the value of `sum` will be evaluated as 2.
+
+  data = RAML.eval(@text)
+
+  data.assert == {:sum=>2}
+

data/qed/read.rdoc

@@ -0,0 +1,109 @@
+= RAML.read
+
+The RAML.read() method parses a RAML document using Ripper.
+In this way a RAML document is treated purely as data and cannot
+contain any Ruby scripting.
+
+Require the RAML library.
+
+  require 'raml'
+
+Given a RAML document:
+
+  website "http://rubygems.org"
+
+We can load the text via the #read method. (Note above document text has
+been placed in the @text variable.)
+
+  data = RAML.read(@text)
+
+  data.assert == {:website=>"http://rubygems.org"}
+
+One of the nicer features of RAML derives from Ruby's block notation, allowing
+for nested entries.
+
+Given a RAML document:
+
+  resources do
+    home "http://rubyworks.github.com/raml"
+    docs "http://rubyworks.github.com/raml/docs/api"
+    wiki "http://wiki.rubyworks.github.com/raml"
+  end
+
+We get a two layer hash.
+
+  data = RAML.read(@text)
+
+  data[:resources][:home].assert == "http://rubyworks.github.com/raml"
+  data[:resources][:docs].assert == "http://rubyworks.github.com/raml/docs/api"
+  data[:resources][:wiki].assert == "http://wiki.rubyworks.github.com/raml"
+
+RAML is also considers the content of a block. If it is a scalar entry,
+such as a String, then that will be assigned to the key.
+
+Given a RAML document:
+
+  description %{
+    This is a description.
+    It can have multiple lines.
+    RAML handles this just fine,
+    because Ruby does too.
+  }
+
+Loading this document, description will contain the text as expected.
+
+  data = RAML.read(@text)
+
+  text = data[:description].sub(/\s+/, ' ').strip
+
+  text.assert.start_with?("This is")
+  text.assert.end_with?("does too.")
+
+It is only unfortunate that Ruby doesn't have a margin controlled string
+notation (e.g. `%L{ }`) so that post processing with `sub()` would not
+be neccessary.
+
+RAML has some options that makes it more flexible than many other data
+lanaguages. For instance, it can allow for multi-key entries.
+
+Given a RAML document:
+
+  source "http://rubygems.org"
+  gem "facets", "~> 2.8"
+  gem "ansi", "~> 1.1"
+
+We simply need to inform the reader to allow identical keys.
+
+  data = RAML.read(@text, :multikey=>true)
+
+  data.assert == {
+    :source=>"http://rubygems.org",
+    :gem=>[["facets", "~> 2.8"],["ansi", "~> 1.1"]]
+  }
+
+If we did not turn on the multi-key option, then the last `gem` entry
+would have simply overwritten the former.
+
+  data = RAML.read(@text)
+
+  data.assert == {
+    :source=>"http://rubygems.org",
+    :gem=>["ansi", "~> 1.1"]
+  }
+
+Not let's show-off the benefit of using RAML.read instead of RAML.eval.
+
+Given a RAML document:
+
+  sum "word".upcase
+
+We will see that the result of calling `#upcase` CANNOT be evaluated and
+will raise an error.
+
+  expect Exception do
+    data = RAML.read(@text)
+  end if RUBY_VERSION >= '1.9'
+
+Note, this last assertion is only true for Ruby 1.9+, becuase Ripper is
+not supported by older versions of Ruby.
+

data/qed/samples/sample1.rml

@@ -0,0 +1,7 @@
+source "http://rubygems.org"
+example "this", 10, true
+another do
+  name "Tom"
+  age 41
+  weight 229 
+end

data/qed/samples/sample2.rml

@@ -0,0 +1,6 @@
+source "http://rubygems.org"
+
+group "development" do
+  gem "cucumber"
+end
+

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: raml
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+  prerelease: 
+platform: ruby
+authors:
+- 7rans
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: blankslate
+  requirement: &22824260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *22824260
+- !ruby/object:Gem::Dependency
+  name: detroit
+  requirement: &22823580 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *22823580
+- !ruby/object:Gem::Dependency
+  name: qed
+  requirement: &22822940 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *22822940
+description: RAML is a Ruby-syntax-based data language.
+email:
+- transfire@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- HISTORY.rdoc
+- README.rdoc
+- QED.rdoc
+- COPYING.rdoc
+files:
+- .ruby
+- .yardopts
+- lib/raml/core_ext.rb
+- lib/raml/eval_parser.rb
+- lib/raml/multi_value.rb
+- lib/raml/ripper_parser.rb
+- lib/raml.rb
+- lib/raml.yml
+- qed/applique/document.rb
+- qed/eval.rdoc
+- qed/read.rdoc
+- qed/samples/sample1.rml
+- qed/samples/sample2.rml
+- HISTORY.rdoc
+- README.rdoc
+- QED.rdoc
+- COPYING.rdoc
+homepage: http://rubyworks.github.com/raml
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Ruby Syntax Data Language
+test_files: []