raml_ruby 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d5b2c3c690054638bb3cdf5dd0ea4fe0cf6e5763
+  data.tar.gz: 913d89301e7cb20ff0e6c73deb7b5104b93b4e47
+SHA512:
+  metadata.gz: a2c78f5010254baab46d008805a257e78a0793486f0e339607a514d2622685c6d991550f53b463ed91b1ff03aead6ff3d5ee5077ba44880dc2c2483900b3d033
+  data.tar.gz: 1206b2996083539351d5ece371ee8451658c7994b7c9630ae99db5019b30bdd42933f673722ad28092dbc3be34da5aad19c5e63c681317d61747267db80d82ee

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.rvmrc
+*.sublime*
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - "1.9.3"
+  - "2.1.2"
+  - jruby-19mode
+script: bundle exec rspec test

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in raml_ruby.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014-2015 kgorin
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,71 @@
+# RAML ruby
+
+[![Build Status](https://travis-ci.org/eliaslevy/raml_ruby.svg?branch=master)](https://travis-ci.org/eliaslevy/raml_ruby)
+
+Implementation of a RAML parser in Ruby. It uses the stdlib YAML parser
+(Psych). It can also generate HTML documentation.
+
+
+<!---
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'raml_ruby'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install raml_ruby
+-->
+
+## Usage
+
+Clone this repository:
+
+    git clone git@github.com:coub/raml_ruby.git
+
+Require:
+
+    require 'lib/raml'
+
+or
+
+    pry -r ./lib/raml.rb
+
+To parse the file:
+
+    Raml.parse_file("path/to/your/file.raml")
+
+To generate HTML documentation:
+
+    # write to file
+    Raml.document("/path/to/your/file.raml", "path/to/output/file.html")
+
+    # or just on screen
+    Raml.document("/path/to/your/file.raml")
+
+## To Do
+
+- Align mergin strategy of conflicting properties of resource types and traits with official Javascript and Java parsers.
+- Security schemes
+- Publish to Rubygems
+
+More a more detailed analysis of the spec requirements and which ones are finishes see the [RAML requirements document](raml_spec_reqs.md).
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+See [LICENSE](https://github.com/coub/raml_ruby/blob/master/LICENSE.txt).
+
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/fixtures/include_1.raml

@@ -0,0 +1,7 @@
+#%RAML 0.8
+baseUri: https://api.example.com
+title: Filesystem API
+version: 0.1
+schemas:
+  - !include schemas/canonicalSchemas.raml
+  - File:       !include schemas/filesystem/file.json

data/fixtures/schemas/canonicalSchemas.raml

@@ -0,0 +1,3 @@
+FileUpdate: !include filesystem/fileupdate.json
+Files:      !include filesystem/files.json
+Test:       !include filesystem/relative/test.json

data/fixtures/schemas/filesystem/file.json

@@ -0,0 +1 @@
+file_schema

data/fixtures/schemas/filesystem/files.json

@@ -0,0 +1 @@
+files_schema

data/fixtures/schemas/filesystem/fileupdate.json

@@ -0,0 +1 @@
+file_update_schema

data/fixtures/schemas/filesystem/relative/test.json

@@ -0,0 +1 @@
+test_schema

data/lib/raml.rb

@@ -0,0 +1,104 @@
+require_relative 'raml/version'
+
+require_relative 'raml/patch/module'
+require_relative 'raml/patch/hash'
+
+require_relative 'raml/exceptions'
+
+require_relative 'raml/parser'
+require_relative 'raml/parser/include'
+
+require_relative 'raml/mixin/bodies'
+require_relative 'raml/mixin/documentable'
+require_relative 'raml/mixin/global'
+require_relative 'raml/mixin/headers'
+require_relative 'raml/mixin/merge'
+require_relative 'raml/mixin/parent'
+require_relative 'raml/mixin/validation'
+
+require_relative 'raml/node'
+require_relative 'raml/node/reference'
+require_relative 'raml/node/parametized_reference'
+
+require_relative 'raml/node/parameter/abstract_parameter'
+require_relative 'raml/node/parameter/form_parameter'
+require_relative 'raml/node/parameter/query_parameter'
+require_relative 'raml/node/parameter/uri_parameter'
+require_relative 'raml/node/parameter/base_uri_parameter'
+
+require_relative 'raml/node/schema'
+require_relative 'raml/node/schema_reference'
+
+require_relative 'raml/node/header'
+require_relative 'raml/node/body'
+require_relative 'raml/node/response'
+
+require_relative 'raml/node/trait_reference'
+require_relative 'raml/node/resource_type_reference'
+
+require_relative 'raml/node/template'
+
+require_relative 'raml/node/abstract_method'
+require_relative 'raml/node/trait'
+require_relative 'raml/node/method'
+
+require_relative 'raml/node/abstract_resource'
+require_relative 'raml/node/resource_type'
+require_relative 'raml/node/resource'
+require_relative 'raml/node/abstract_resource_circular'
+
+require_relative 'raml/node/documentation'
+
+require_relative 'raml/node/root'
+
+module Raml
+  # Parses RAML from a string.
+  #
+  # @param raml [String] the string containing RAML.
+  # @return [Raml::Root] the RAML root node.
+  # @raise [RamlError] if the RAML is invalid.
+  def self.parse(raml)
+    Raml::Parser.parse raml
+  end
+
+  # Parses RAML from a file.
+  #
+  # @param filepath [String] the file path of the file containing RAML.
+  # @return [Raml::Root] the RAML root node.
+  # @raise [Errno::ENOENT] if the file can't be found.
+  # @raise [Errno::EACCES] if the file can't be read.
+  # @raise [RamlError] if the RAML is invalid.
+  def self.parse_file(filepath)
+    file = File.new filepath
+    raise UnsupportedRamlVersion unless file.readline =~ /\A#%RAML 0.8\s*\z/
+    
+    path = File.dirname filepath
+    path = nil if path == ''
+    
+    Raml::Parser.parse file.read, path
+  end
+
+  # Parses RAML from a file and generates API documentation in HTML.  If no
+  # output filename argument is given, the HTML is returned as a string. If
+  # an output filename argument is given, the HTML is stored to a file at
+  # that location.
+  #
+  # @param filepath [String] the file path of the file containing RAML.
+  # @param out_file [String] the file path of the file to write the documentation to. Defaults to nil.
+  # @return [String] the HTML documentation, if out_file is nil.
+  # @raise [Errno::ENOENT] if the file can't be found.
+  # @raise [Errno::EACCES] if the files can't be read or written.
+  # @raise [RamlError] if the RAML is invalid.
+  def self.document(filepath, out_file=nil)
+    root = parse_file filepath
+    root.expand
+
+    if out_file
+      File.open(out_file, 'w') do |file|
+        file.write root.document
+      end
+    else
+      root.document
+    end
+  end
+end

data/lib/raml/exceptions.rb

@@ -0,0 +1,27 @@
+module Raml
+  class RamlError < StandardError; end
+  
+  class UnsupportedRamlVersion          < RamlError; end
+  class CantIncludeFile                 < RamlError; end
+  
+  class RequiredPropertyMissing         < RamlError; end
+  class InvalidProperty                 < RamlError; end
+  class UnknownProperty                 < RamlError; end
+  
+  class InvalidParent                   < RamlError; end
+  class InvalidSchema                   < RamlError; end
+
+  class InvalidMethod                   < RamlError; end
+
+  class InvalidParameterType            < RamlError; end
+  class InapplicableParameterAttribute  < RamlError; end
+  class InvalidParameterAttribute       < RamlError; end
+  
+  class InvalidMediaType                < RamlError; end
+
+  class UnknownTraitReference           < RamlError; end
+  class UnknownResourceTypeReference    < RamlError; end
+  class MergeError                      < RamlError; end
+  class UnknownTypeOrTraitParameter     < RamlError; end
+  class UnknownTypeOrTraitParamFunction < RamlError; end
+end

data/lib/raml/mixin/bodies.rb

@@ -0,0 +1,32 @@
+module Raml
+  module Bodies
+    # @!attribute [r] bodies
+    #   @return [Hash<String, Raml::Body>] the bodies, keyed by their media type.
+
+    # XXX - need this line here to trigger Yard to generate docs for the above attribute.
+
+    private
+
+    def self.included(base)
+      base.instance_eval do
+		    non_scalar_property :body
+		    children_by :bodies, :media_type , Body
+      end
+    end
+    
+    def parse_body(value)
+      if value.is_a? Hash and value.keys.all? {|k| k.is_a? String and k =~ /.+\/.+/ }
+        # If all keys looks like media types, its not a default media type body.
+        validate_hash 'body', value, String, Hash
+        value.map { |b_name, b_data| Body.new b_name, b_data, self }
+
+      else
+        # Its a default media type body.
+        validate_hash 'body', value, String
+        media_type = default_media_type
+        raise InvalidMediaType, 'Body with no media type, but default media type has not been declared.' unless media_type
+        Body.new media_type, value, self
+      end
+    end
+  end
+end

data/lib/raml/mixin/documentable.rb

@@ -0,0 +1,32 @@
+require 'kramdown'
+
+module Raml
+  module Documentable
+    # @!attribute [rw] display_name
+    #   @return [String, nil] the node's display name.
+
+    # @!attribute [rw] description
+    #   @return [String, nil] the node's description.
+
+    # @private
+    def html_description
+      Kramdown::Document.new(description, input: :GFM).to_html
+    end
+
+    private
+
+    def self.included(base)
+      base.instance_eval do
+        scalar_property :display_name, :description
+      end
+    end
+
+    def validate_display_name
+      raise InvalidProperty, "displayName property mus be a string." unless display_name.is_a? String 
+    end
+
+    def validate_description
+      raise InvalidProperty, "description property mus be a string." unless description.is_a? String 
+    end
+  end
+end

data/lib/raml/mixin/global.rb

@@ -0,0 +1,20 @@
+module Raml
+  # @private
+  module Global
+    def default_media_type
+      @parent.default_media_type
+    end
+
+  	def trait_declarations
+  		@parent.trait_declarations
+  	end
+
+  	def resource_type_declarations
+  		@parent.resource_type_declarations
+  	end
+
+  	def schema_declarations
+  		@parent.schema_declarations
+  	end
+  end
+end

data/lib/raml/mixin/headers.rb

@@ -0,0 +1,22 @@
+module Raml
+  module Headers
+    # @!attribute [r] headers
+    #   @return [Hash<String, Raml::Header>] the headers, keyed by the header name.
+
+    # XXX - need this line here to trigger Yard to generate docs for the above attribute.
+
+    private
+
+    def self.included(base)
+      base.instance_eval do
+		    non_scalar_property :headers
+        children_by :headers, :name, Header
+      end
+    end
+
+    def parse_headers(value)
+      validate_hash 'headers', value, String, Hash
+      value.map { |h_name, h_data| Header.new h_name, h_data, self }
+    end
+  end
+end

data/lib/raml/mixin/merge.rb

@@ -0,0 +1,24 @@
+module Raml
+  # @private
+  module Merge
+    def merge(other)
+      other.scalar_properties.each do |prop|
+        prop_var  = "@#{prop}"
+        prop_val = other.instance_variable_get prop_var
+        instance_variable_set prop_var, prop_val unless prop_val.nil?
+      end
+    end
+
+    def merge_properties(other, type)
+    	match, no_match = other.send(type).values.partition { |param| self.send(type).has_key? param.name }
+
+    	match.each { |param| self.send(type)[param.name].merge param }
+
+      # if its an optional property, and there is no match in self, don't merge it.
+      no_match.reject! { |node| node.optional      }
+      no_match.map!    { |node| node.clone         }
+      no_match.each    { |node| node.parent = self }
+    	@children += no_match
+    end
+  end
+end

data/lib/raml/mixin/parent.rb

@@ -0,0 +1,54 @@
+module Raml
+  module Parent
+    # @!attribute [rw] children
+    #   @return [Array<Raml::Node>] children nodes.
+    attr_accessor :children
+
+    private
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # @private
+    module ClassMethods
+      def child_of(name, type)
+        type = [ type ] unless type.is_a? Array
+
+        self.instance_eval do
+          define_method name do
+            @children.select { |child| type.include? child.class }.first
+          end
+        end
+      end
+
+      def children_of(name, type)
+        type = [ type ] unless type.is_a? Array
+
+        self.instance_eval do
+          define_method name do
+            @children.select { |child| type.include? child.class }
+          end
+        end
+      end
+
+      def children_by(name, key, type, merge_parents=false)
+        self.instance_eval do
+          define_method name do
+            result = Hash[
+              @children.
+                select { |child| child.is_a? type }.
+                map    { |child| [ child.send(key.to_sym), child ] }
+            ]
+
+            if merge_parents and parent and parent.respond_to? name
+              result = parent.send(name).merge result
+            end
+
+            result
+          end
+        end
+      end
+    end
+  end
+end