raml_ruby 0.1.1

data/lib/raml/mixin/validation.rb

@@ -0,0 +1,49 @@
+module Raml
+  # @private
+	module Validation
+    def validate_property(name, value, classes)
+      classes = [ classes ] unless classes.is_a? Array
+      raise InvalidProperty, "#{camel_case name} property must be an #{classes_to_s classes}" unless classes.include? value.class
+    end
+
+		def validate_string(name, string)
+			validate_property name, string, String
+      raise InvalidProperty, "#{camel_case name} property must be a non-empty string." if     string.empty?
+		end
+
+		def validate_array(name, array, element_classes=nil)
+      raise InvalidProperty, "#{camel_case name} property must be an array" unless
+      	array.is_a? Array
+
+      if element_classes
+      	element_classes = [ element_classes ] unless element_classes.is_a? Array
+	      raise InvalidProperty, "#{camel_case name} property must be an array of #{classes_to_s element_classes}" unless
+	        array.all? { |element| element_classes.include? element.class }
+      end
+		end
+
+		def validate_hash(name, hash, key_class=nil, value_class=nil)
+      raise InvalidProperty, "#{camel_case name} property must be a map" unless 
+        hash.is_a? Hash
+
+      if key_class
+				if key_class.is_a? Array
+		      raise InvalidProperty, "#{camel_case name} property must be a map with #{key_class} keys" unless
+		        hash.keys.all?  {|key| key_class.any? { |kc| key.is_a? kc } }
+				else
+		      raise InvalidProperty, "#{camel_case name} property must be a map with #{key_class} keys" unless
+		        hash.keys.all?  {|key| key.is_a? key_class }
+ 				end
+      end
+
+      if value_class
+	      raise InvalidProperty, "#{camel_case name} property must be a map with map values: #{hash}" unless
+	      	hash.values.all?  {|value| value.is_a? Hash }
+      end
+		end
+
+		def classes_to_s(classes)
+			classes.join(', ').gsub(/, (\w)\z/, ' or \1')
+		end
+	end
+end

data/lib/raml/node.rb

@@ -0,0 +1,219 @@
+require 'active_support'
+require 'active_support/core_ext/class/attribute'
+require 'rouge'
+require 'slim'
+
+module Raml
+  class Node
+    class_attribute :doc_template, :doc_template_compiled
+
+    class << self
+      # @private
+      def relative_path(file)
+        File.join(
+          *File.dirname(__FILE__).
+            split(File::SEPARATOR).
+            reverse.
+            drop_while { |p| p != 'lib' }.
+            drop(1).
+            reverse,
+          'templates',
+          file
+        )
+      end
+    end
+
+    # @!attribute [r] name
+    #   @return [String,Integer] the node name (e.g. resource path, header name, etc). Usually a 
+    #     String.  Can be an Integer for methods.
+    attr_reader   :name
+    # @!attribute [rw] parent
+    #   @return [Raml::Node] the node's parent. 
+    attr_accessor :parent
+
+    def initialize(name, parent)
+      @name   = name
+      @parent = parent
+    end
+
+    # Returns HTML documenting the node and child nodes.
+    # @return [String] HTML documentation.
+    def document
+      if doc_template
+        self.doc_template_compiled ||= Slim::Template.new(doc_template, format: :html5, pretty: true)
+        doc_template_compiled.render self
+      else
+        nil
+      end
+    end
+
+    private
+
+    def underscore(camel_cased_word)
+      camel_cased_word.to_s.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        tr("-", "_").
+        downcase
+    end
+
+    def camel_case(underscored_word)
+      w = underscored_word.to_s.split('_')
+      (w[0...1] + w[1..-1].map(&:capitalize)).join
+    end
+
+    def collapse(level, title, display_name=nil, &block)
+      @@cid ||= 0
+      @@cid  += 1
+
+      @@context_class ||= Struct.new(:cid, :title, :level, :display_name, :content) do
+        def highlight_url_params(url)
+          url.gsub(/({[^}]+})/, '<span class="url_param">\1</span>')
+        end 
+      end
+
+      context = @@context_class.new @@cid, title, level, display_name, yield
+
+      @@collapse ||= Slim::Template.new(self.class.relative_path('collapse.slim'), format: :html5, pretty: true)
+      @@collapse.render context
+    end
+
+    def highlight_url_params(url)
+      url.gsub(/({[^}]+})/, '<span class="url_param">\1</span>')
+    end 
+
+    def highlight(source, mimetype=nil)
+      opts = { source: source }
+      opts[:mimetype] = mimetype if mimetype
+
+      formatter = Rouge::Formatters::HTML.new css_class: 'highlight'
+      lexer = Rouge::Lexer.guess(opts).new
+      formatter.format lexer.lex source
+    end
+  end
+
+  class ValueNode < Node
+    attr_accessor :value
+
+    def initialize(name, value, parent)
+      super name, parent
+      @value  = value
+
+      validate_value if respond_to? :validate_value, true
+    end
+  end
+
+  class PropertiesNode < Node
+    class_attribute  :scalar_properties, :non_scalar_properties, :_regexp_property
+    self.scalar_properties     = []
+    self.non_scalar_properties = []
+    self._regexp_property      = nil
+
+    class << self
+      private
+      def inherit_class_attributes
+        self.scalar_properties     = self.scalar_properties.dup
+        self.non_scalar_properties = self.non_scalar_properties.dup
+      end
+
+      def scalar_property(*properties)
+        attr_accessor(*properties.map(&:to_sym))
+        _property(scalar_properties, *properties)
+      end
+
+      def non_scalar_property(*properties)
+        _property(non_scalar_properties, *properties)
+      end
+
+      def _property(type, *properties)
+        properties.map(&:to_s).each { |prop| type << prop unless type.include? prop }
+      end
+
+      def regexp_property(regexp, parse)
+        self._regexp_property = [ regexp, parse ]
+      end
+    end
+
+    # @private
+    def scalar_properties    ; self.class.scalar_properties    ; end
+    # @private
+    def non_scalar_properties; self.class.non_scalar_properties; end
+    # @private
+    def _regexp_property     ; self.class._regexp_property     ; end 
+
+    # @!attribute [rw] optional
+    #   @return [Boolean] whether the property is optional. Only valid
+    #     for decendant nodes a {Trait::Instance} or {ResourceType::Instance}.
+    #     Indicated by a trailing "?" on the property name in the RAML source.
+    attr_accessor :optional
+    
+    def initialize(name, properties, parent)
+      if name.is_a? String and name.end_with? '?'
+        allow_optional? parent
+        name = name.dup.chomp! '?'
+        @optional = true
+      else
+        @optional = false
+      end
+
+      super name, parent
+
+      @children ||= []
+      parse_and_validate_props properties
+    end
+
+    private
+
+    def allow_optional?(parent)
+      until parent == parent.parent or parent.is_a? Root
+        return if parent.is_a? Trait::Instance or parent.is_a? ResourceType::Instance
+        parent = parent.parent
+      end
+      raise InvalidProperty, 'Optional properties are only allowed within a trait or resource type specification.'
+    end
+
+    def parse_and_validate_props(properties)
+      maybe_exec :validate_name
+      maybe_exec :validate_parent
+
+      properties.each do |prop_name, prop_value|
+        prop_name       = prop_name.to_s
+        under_prop_name = underscore prop_name
+
+        if scalar_properties.include? under_prop_name
+          send "#{under_prop_name}=", prop_value
+          maybe_exec "validate_#{under_prop_name}"
+
+        elsif non_scalar_properties.include? under_prop_name
+          parsed = send "parse_#{under_prop_name}", prop_value
+          parsed = [ parsed ] unless parsed.is_a? Array
+          @children += parsed
+
+        elsif _regexp_property and _regexp_property[0].match prop_name
+          parsed = self.instance_exec(prop_name, prop_value, &_regexp_property[1])
+          parsed = [ parsed ] unless parsed.is_a? Array
+          @children += parsed
+
+        else
+          raise UnknownProperty, "#{prop_name} is an unknown property with value of #{prop_value}."
+        end
+      end
+
+      validate if respond_to? :validate, true
+    end
+
+    def maybe_exec(method, *args)
+      send(method,*args) if respond_to? method, true
+    end
+
+    def initialize_clone(other)
+      super
+      @children = @children.clone
+      @children.map! do |child|
+        child = child.clone
+        child.parent = self
+        child
+      end
+    end
+  end
+end

data/lib/raml/node/abstract_method.rb

@@ -0,0 +1,61 @@
+module Raml
+  class AbstractMethod < PropertiesNode
+    inherit_class_attributes
+    
+    include Documentable
+    include Global
+    include Merge
+    include Parent
+    include Validation
+    include Bodies
+    include Headers
+
+    # @!attribute [rw] protocols
+    #   @return [Array<String>, nil] the supported protocols. Nil or an array of up to two string
+    #     elements from the set "HTTP" and "HTTPS".
+
+    # @!attribute [r] query_parameters
+    #   @return [Hash<String, Raml::Parameter::QueryParameter>] the method query parameters, keyed
+    #     by the parameter name. 
+
+    # @!attribute [r] responses
+    #   @return [Hash<Integer, Raml::Response>] the method responses, keyed by the HTTP status code.
+
+    scalar_property     :protocols
+    non_scalar_property :query_parameters, :responses, :secured_by
+
+    attr_reader_default :protocols, []
+
+    children_by :query_parameters , :name       , Parameter::QueryParameter
+    children_by :responses        , :name       , Response
+    
+    private
+        
+    def validate_protocols
+      if @protocols
+        validate_array :protocols, @protocols, String
+        
+        @protocols.map!(&:upcase)
+        
+        raise InvalidProperty, 'protocols property elements must be HTTP or HTTPS' unless 
+          @protocols.all? { |p| [ 'HTTP', 'HTTPS'].include? p }
+      end
+    end
+
+    def parse_query_parameters(value)
+      validate_hash 'queryParameters', value, String, Hash
+      value.map { |p_name, p_data| Parameter::QueryParameter.new p_name, p_data, self }
+    end
+
+    def parse_responses(value)
+      validate_hash 'responses', value, [Integer, String], Hash
+      value.map { |r_name, r_data| Response.new r_name, r_data, self }
+    end
+
+    def parse_secured_by(data)
+      # XXX ignored for now
+      []
+    end
+
+  end
+end

data/lib/raml/node/abstract_resource.rb

@@ -0,0 +1,165 @@
+module Raml
+  class AbstractResource < PropertiesNode
+    inherit_class_attributes
+
+    include Documentable
+    include Global
+    include Merge
+    include Parent
+    include Validation
+
+    # @!attribute [r] base_uri_parameters
+    #   @return [Hash<String, Raml::Parameter::BaseUriParameter>] the base URI parameters, keyed
+    #     by the parameter name. 
+
+    # @!attribute [r] uri_parameters
+    #   @return [Hash<String, Raml::Parameter::UriParameter>] the URI parameters, keyed
+    #     by the parameter name. 
+
+    # @!attribute [r] methods
+    #   @return [Hash<String, Raml::Method>] the methods, keyed by the method name.
+
+    # @!attribute [r] traits
+    #   @return [Array<Raml::Trait, Raml::TraitReference>] the traits and trait references.
+
+    non_scalar_property :uri_parameters, :base_uri_parameters, :is, :type, :secured_by,
+      *Raml::Method::NAMES, *Raml::Method::NAMES.map { |m| "#{m}?" }
+
+    children_by :methods            , :name, Raml::Method
+    children_by :base_uri_parameters, :name, Parameter::BaseUriParameter, true
+    children_by :uri_parameters     , :name, Parameter::UriParameter    , true
+
+    children_of :traits, [ Raml::Trait, Raml::TraitReference ]
+
+    # @private
+    def apply_resource_type
+      if type
+        # We clone the resource as it currently is; apply the resource type to the
+        # resource, so that optional properties are correctly evaluated; then we
+        # apply the cloned resource with the initial state, so that scalar properties
+        # in the resource override the ones in the resource type.
+        cloned_self = self.clone
+        merge instantiate_resource_type
+        merge cloned_self
+      end
+    end
+
+    # @private
+    def merge(other)
+      raise MergeError, "Trying to merge #{other.class} into Resource." unless other.is_a? ResourceType::Instance or other.is_a? Resource
+
+      super
+
+      merge_properties other, :methods
+      merge_properties other, :base_uri_parameters
+      merge_properties other, :uri_parameters
+
+      # merge traits. insert the non-matching ones in the front, so they have the least priority.
+      match, no_match = other.traits.partition do |other_trait|
+        if other_trait.is_a? Trait
+          false
+        else # TraitReference
+          self.traits.any? do |self_trait|
+            self_trait.is_a?(TraitReference)                && 
+            self_trait.name       == other_trait.name       && 
+            self_trait.parameters == other_trait.parameters
+          end
+        end
+      end
+      @children.unshift(*no_match)
+
+      self
+    end
+
+    # Returns the resource's full path.
+    # @return [String] the resource's full path.
+    def resource_path
+      @parent.resource_path + self.name
+    end
+
+    private
+    
+    def validate_parent
+      raise InvalidParent, "Parent of resource cannot be nil." if @parent.nil?
+    end
+
+    def parse_uri_parameters(value)
+      validate_hash :uri_parameters, value, String, Hash
+      value.map { |uname, udata| Parameter::UriParameter.new uname, udata, self }
+    end
+
+    def parse_base_uri_parameters(value)
+      validate_hash :base_uri_parameters, value, String, Hash
+      
+      raise InvalidProperty, 'baseUriParameters property can\'t contain reserved "version" parameter' if
+        value.include? 'version'
+
+      value.map { |bname, bdata| Parameter::BaseUriParameter.new bname, bdata, self }
+    end
+
+    def parse_is(value)
+      validate_array :is, value, [String, Hash]
+
+      value.map do |trait|
+        if trait.is_a? Hash
+          if trait.keys.size == 1 and trait_declarations.include? trait.keys.first
+            raise InvalidProperty, 'is property with map of trait name but params are not a map' unless 
+              trait.values[0].is_a? Hash
+            TraitReference.new( *trait.first, self )
+          else
+            Trait.new '_', trait, self
+          end
+        else
+          raise UnknownTraitReference, "#{trait} referenced in resource but not found in traits declaration." unless
+            trait_declarations.include? trait
+          TraitReference.new trait, self
+        end
+      end
+    end
+
+    Raml::Method::NAMES.each do |method|
+      define_method("parse_#{method}") do |value|
+        Method.new method, value, self
+      end
+
+      define_method("parse_#{method}?") do |value|
+        Method.new "#{method}?", value, self
+      end
+    end
+
+    def parse_type(value)
+      validate_property :type, value, [ Hash, String ]
+
+      if value.is_a? Hash
+        if value.keys.size == 1 and resource_type_declarations.include? value.keys.first
+          raise InvalidProperty, 'type property with map of resource type name but params are not a map' unless 
+            value.values[0].is_a? Hash
+          ResourceTypeReference.new( *value.first, self )
+        else
+          ResourceType.new '_', value, self
+        end
+      else
+        raise UnknownResourceTypeReference, "#{value} referenced in resource but not found in resource types declaration." unless
+          resource_type_declarations.include? value
+        ResourceTypeReference.new value, self
+      end
+    end
+
+    def parse_secured_by(data)
+      # XXX ignored for now
+      []
+    end
+
+    def instantiate_resource_type
+      reserved_params = {
+        'resourcePath'     => resource_path,
+        'resourcePathName' => resource_path.split('/')[-1]
+      }
+      if ResourceTypeReference === type
+        resource_type_declarations[type.name].instantiate type.parameters.merge reserved_params
+      else
+        type.instantiate reserved_params
+      end
+    end
+  end
+end