raml_ruby 0.1.1

data/lib/raml/node/abstract_resource_circular.rb

@@ -0,0 +1,5 @@
+class Raml::AbstractResource < Raml::PropertiesNode
+  # @!attribute [r] type
+  #   @return [Raml::ResourceType, Raml::ResourceTypeReference>] the resource type or resource type references, if any.
+  child_of :type, [ Raml::ResourceType, Raml::ResourceTypeReference ]
+end

data/lib/raml/node/body.rb

@@ -0,0 +1,94 @@
+module Raml
+  class Body < PropertiesNode
+    inherit_class_attributes
+    
+    include Global
+    include Merge
+    include Parent
+    include Validation
+
+    # @private
+    MEDIA_TYPE_RE = %r{[a-z\d][-\w.+!#$&^]{0,63}/[a-z\d][-\w.+!#$&^]{0,63}(;.*)?}oi
+
+    # @!attribute [rw] example
+    #   @return [String, nil] an example of a valid body.
+
+    # @!attribute [r] form_parameters
+    #   @return [Hash<String, Raml::Parameter::FormParameter>] the form parameters, keyed
+    #     by the parameter name. Only valid for "application/x-www-form-urlencoded" and
+    #     "multipart/form-data" media types.
+
+    # @!attribute [r] schema
+    #   @return [Raml::Schema, nil] the body's schema.  Only valid if the media type
+    #     is not one of "application/x-www-form-urlencoded" or "multipart/form-data".
+
+    # @!attribute [r] media\_type
+    #   @return [String] media type of the of body.  An alias for #name.
+
+    scalar_property     :example 
+    non_scalar_property :form_parameters, :schema
+
+    alias_method :media_type, :name
+    
+    self.doc_template = relative_path 'body.slim'
+    
+    children_by :form_parameters, :name, Parameter::FormParameter
+    
+    child_of :schema, [ Schema, SchemaReference ]
+
+    # Returns whether the body is a web form.  Returns true for "application/x-www-form-urlencoded" and
+    # "multipart/form-data" media types.
+    # @return [Boolean] true if the body is a web form, false otherwise.
+    def web_form?
+      [ 'application/x-www-form-urlencoded', 'multipart/form-data' ].include? media_type
+    end
+    
+    # @private
+    def merge(other)
+      raise MergeError, "Media types don't match." if media_type != other.media_type
+      
+      super
+
+      merge_properties other, :form_parameters
+
+      if other.schema
+        @children.delete_if { |c| [ Schema, SchemaReference ].include? c.class } if schema
+        @children << other.schema
+      end
+
+      self
+    end
+
+    private
+    
+    def validate_name
+      raise InvalidMediaType, 'body media type is invalid' unless media_type =~ Body::MEDIA_TYPE_RE
+    end
+
+    def parse_form_parameters(value)
+      validate_hash 'formParameters', value, String, Hash
+
+      value.map do |name, form_parameter_data|
+        Parameter::FormParameter.new name, form_parameter_data, self
+      end
+    end
+
+    def parse_schema(value)
+      validate_string :schema, value
+
+      if schema_declarations.include? value
+        SchemaReference.new value, self
+      else
+        Schema.new '_', value, self
+      end
+    end
+
+    def validate
+      if web_form?
+        raise InvalidProperty, 'schema property can\'t be defined for web forms.' if schema
+        raise RequiredPropertyMissing, 'formParameters property must be specified for web forms.' if
+          form_parameters.empty?
+      end
+    end
+  end
+end

data/lib/raml/node/documentation.rb

@@ -0,0 +1,28 @@
+require 'kramdown'
+
+module Raml
+  class Documentation < PropertiesNode
+
+    # @!attribute [rw] content
+    #   @return [String] the documentation content.
+
+    # @!attribute [rw] title
+    #   @return [String] the documentation title.  An alias for #name.
+
+    scalar_property :content
+    alias_method :title, :name
+
+    self.doc_template = relative_path 'documentation.slim'
+
+    private
+
+    def validate
+      raise InvalidProperty, 'document title cannot be empty.'   if title.nil?   or title.empty?
+      raise InvalidProperty, 'document content cannot be empty.' if content.nil? or content.empty?
+    end
+
+    def html_content
+      Kramdown::Document.new(content, input: :GFM).to_html
+    end
+  end
+end

data/lib/raml/node/header.rb

@@ -0,0 +1,4 @@
+module Raml
+  class Header < Parameter::AbstractParameter
+  end
+end

data/lib/raml/node/method.rb

@@ -0,0 +1,106 @@
+module Raml
+  class Method < AbstractMethod
+    inherit_class_attributes
+    
+    NAMES = %w(options get head post put delete trace connect patch)
+
+    # @!attribute [r] traits
+    #   @return [Array<Raml::Trait, Raml::TraitReference>] the traits and trait references.
+
+    non_scalar_property :is
+
+    children_of :traits, [ Trait, TraitReference ]
+
+    self.doc_template = relative_path 'method.slim'
+
+    # @private
+    def apply_traits
+      # We apply resource traits before method traits, and apply traits at each level in
+      # the other they are listed (first to last, left to righ).  Later traits scalar
+      # properties overwrite earlier ones.  We end by merging a copy of the method, so
+      # that scalar properties in the method hierarchy overwrite those in the traits.
+      # We must apply the traits against the method first, as they may contain optional
+      # properties that depend on the method hiearchy.
+      cloned_self = self.clone
+
+      (@parent.traits + traits).
+        map  { |trait| instantiate_trait trait }.
+        each { |trait| merge trait }
+
+      merge cloned_self
+    end
+
+    # @private
+    def merge(other)
+      super
+
+      merge_properties other, :headers
+      merge_properties other, :query_parameters
+      merge_properties other, :bodies
+      merge_properties other, :responses
+
+      # We may be applying a resource type, which will result in the merging of a method that may have
+      # traits, instead of a trait that can't have no traits.
+      if other.is_a? Method
+        # 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)
+      end
+
+      self
+    end
+
+    private
+
+    def validate_name
+      raise InvalidMethod, "#{@name} is an unsupported HTTP method" unless NAMES.include? @name
+    end
+
+    def validate_parent
+      raise InvalidParent, "Parent of method cannot be nil." if @parent.nil?
+    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 method but not found in traits declaration." unless
+            trait_declarations.include? trait
+          TraitReference.new trait, self
+        end
+      end
+    end
+
+    def instantiate_trait(trait)
+      reserved_params = {
+        'resourcePath'     => @parent.resource_path,
+        'resourcePathName' => @parent.resource_path.split('/')[-1],
+        'methodName'       => self.name
+      }
+      if TraitReference === trait
+        trait_declarations[trait.name].instantiate trait.parameters.merge reserved_params
+      else
+        trait.instantiate reserved_params
+      end
+    end
+  end
+end

data/lib/raml/node/parameter/abstract_parameter.rb

@@ -0,0 +1,251 @@
+module Raml
+  module Parameter
+    class AbstractParameter < PropertiesNode
+      inherit_class_attributes
+
+      include Documentable
+      include Merge
+      include Parent
+
+      VALID_TYPES = %w(string number integer date boolean file)
+
+      # @!attribute [rw] type
+      #   @return [String] the value type. One of: "string", "number", "integer", "date",
+      #     "boolean", or "file".
+
+      # @!attribute [rw] enum
+      #   @return [Array<String>,nil] the possible values. Only valid for parameters of type "string".
+
+      # @!attribute [rw] pattern
+      #   @return [Regexp,nil] a regular expression the value must match. Only valid for
+      #     parameters of type "string".
+
+      # @!attribute [rw] min_length
+      #   @return [Integer,nil] the minimum value length. Only valid for parameters of type "string".
+
+      # @!attribute [rw] max_length
+      #   @return [Integer,nil] the maximum value length. Only valid for parameters of type "string".
+
+      # @!attribute [rw] minimum
+      #   @return [Numeric,nil] the minimum value length. Only valid for parameters of type "number" or "integer".
+
+      # @!attribute [rw] maximum
+      #   @return [Numeric,nil] the maximum value length. Only valid for parameters of type "number" or "integer".
+
+      # @!attribute [rw] example
+      #   @return [String,Numeric,Boolean,nil] an example of the value.
+
+      # @!attribute [rw] default
+      #   @return [String,Numeric,Boolean,nil] the default value.
+
+      # @!attribute [rw] required
+      #   @return [Boolean] whether the parameter is required.
+
+      # @!attribute [rw] repeat
+      #   @return [Boolean] whether the parameter can be repeated.
+
+      # @!attribute [r] types
+      #   @return [Hash<String, Raml::Parameter::AbstractParameter>] if the parameter supports multiple types,
+      #     the type alternatives, keyed by the type.
+
+      scalar_property :type       , :enum     , :pattern  , :min_length , 
+                      :max_length , :minimum  , :maximum  , :example    , 
+                      :repeat     , :required , :default
+
+      attr_reader_default :type    , 'string'
+      attr_reader_default :repeat  , false
+      attr_reader_default :required, false
+
+      children_by :types, :type, AbstractParameter
+
+      self.doc_template = relative_path 'abstract_parameter.slim'
+
+      # @param name [String] the parameter name.
+      # @param parameter_data [Hash, Array<Hash>] the parameter data. If the parameter supports multiple types,
+      #  it should be an array of hashes, one hash each for each type.
+      # @param parent [Raml::Node] the parameter's parent node.
+      def initialize(name, parameter_data, parent)
+        if parameter_data.is_a? Array
+          @name       = name
+          @children ||= []
+          parameter_data.each do |parameter|
+            @children << self.class.new(name, parameter, self)
+          end
+        elsif parameter_data.is_a? Hash
+          super
+        end
+      end
+
+      # @return [Boolean] true if the parameter supports multiple type alternatives, false otherwise.
+      def has_multiple_types?
+        not children.empty?
+      end
+      
+      # @private
+      def merge(other)
+        raise MergeError, "#{self.class} names don't match." if name != other.name
+
+        case [ has_multiple_types?, other.has_multiple_types? ]
+        when [ true , true  ]
+          match, no_match = other.types.values.partition { |param| types.include? param.type }
+
+          # Merge parameters with the same type.
+          match = Hash[ match.map { |param| [ param.type, param ] } ]
+          types.each { |type, param| param.merge match[type] if match[type] }
+
+          # Add parameters with no matching type.
+          @children.concat no_match
+
+        when [ true , false ]
+          if types[other.type]
+            types[other.type].merge other
+          else
+            @children << other
+          end
+
+        when [ false, true  ]
+          if other.types[self.type]
+            self.merge other.types[self.type]
+            @children << self.clone
+            @children.concat other.types.values.reject { |type| self.type == type.type }
+            reset
+
+          else
+            @children << self.clone
+            @children.concat other.types.values
+            reset
+          end
+
+        when [ false, false ]
+          super
+        end
+
+        self
+      end
+
+      private
+      
+      def validate_type
+        raise InvalidParameterType unless VALID_TYPES.include? type
+      end
+
+      def validate_enum
+        if enum
+          if type == 'string'
+            raise InvalidParameterAttribute, "enum attribute must be an array of strings: #{enum} (#{enum.class})" unless
+              enum.is_a?(Array) && enum.all? { |val| val.is_a? String }
+          else
+            raise InapplicableParameterAttribute, 'enum attribute is only applicable to string parameters.'
+          end
+        end
+      end
+      
+      def validate_pattern
+        if pattern
+          if type == 'string'
+            raise InvalidParameterAttribute, 'pattern attribute must be a string' unless pattern.is_a? String
+            pattern.gsub!(/\\*\^/u) { |m| m.size.odd? ? "#{m.chop}\\A" : m }
+            pattern.gsub!(/\\*\$/u) { |m| m.size.odd? ? "#{m.chop}\\z" : m }
+            begin
+              @pattern = Regexp.new pattern
+            rescue RegexpError
+              raise InvalidParameterAttribute, 'pattern attribute must be a valid regexp'
+            end
+          else
+            raise InapplicableParameterAttribute, 'pattern attribute is only applicable to string parameters.'
+          end          
+        end
+      end
+      
+      def validate_min_length
+        if min_length
+          if type != 'string'
+            raise InapplicableParameterAttribute, 'minLength attributes are applicable only to string parameters.'
+          else
+            raise InvalidParameterAttribute, 'minLength attributes must be an integer' unless min_length.is_a? Integer
+          end
+        end
+      end
+      
+      def validate_max_length
+        if max_length
+          if type != 'string'
+            raise InapplicableParameterAttribute, 'maxLength attributes are applicable only to string parameters.'
+          else
+            raise InvalidParameterAttribute, 'maxLength attributes must be an integer' unless max_length.is_a? Integer
+          end
+        end
+      end
+      
+      def validate_minimum
+        if minimum
+          if %w(integer number).include? type
+            raise InvalidParameterAttribute, 'minimum attribute must be numeric' unless minimum.is_a? Numeric
+          else
+            raise InapplicableParameterAttribute, 
+              'minimum attribute applicable only to number or integer parameters.'
+          end
+        end
+      end
+      
+      def validate_maximum
+        if maximum
+          if %w(integer number).include? type
+            raise InvalidParameterAttribute, 'maximum attribute must be numeric' unless maximum.is_a? Numeric
+          else
+            raise InapplicableParameterAttribute, 
+              'maximum attribute applicable only to number or integer parameters.'
+          end
+        end
+      end
+      
+      def validate_example
+        validate_value :example
+      end
+      
+      def validate_repeat
+        unless [true, false].include?(repeat)
+          raise InvalidParameterAttribute, 'repeat attribute must be true or false.'
+        end
+      end
+      
+      def validate_required
+        unless [true, false].include?(required)
+          raise InvalidParameterAttribute, "required attribute must be true or false: #{required} (#{required.class})"
+        end
+      end
+      
+      def validate_default
+        validate_value :default
+      end
+      
+      def validate_value(which)
+        val = send which
+        if val
+          err_msg = "#{which} attribute for a %s parameter must be a %s: #{val} (#{val.class})"
+          case type
+          when 'string'
+            raise InvalidParameterAttribute, 
+              ( err_msg % [ 'string' , 'string'  ] ) unless val.is_a? String
+          when 'number'
+            raise InvalidParameterAttribute, 
+              ( err_msg % [ 'number' , 'number'  ] ) unless val.is_a? Numeric
+          when 'integer'
+            raise InvalidParameterAttribute, 
+              ( err_msg % [ 'integer', 'integer' ] ) unless val.is_a? Integer
+          when 'date'
+            raise InvalidParameterAttribute, 
+              ( err_msg % [ 'date'   , 'string'  ] ) unless val.is_a? String
+          when 'boolean'
+            raise InvalidParameterAttribute, 
+              ( err_msg % [ 'boolean', 'boolean' ] ) unless [TrueClass, FalseClass].include? val.class
+          end
+        end
+      end
+
+      def reset
+        scalar_properties.each { |prop| instance_variable_set "@#{prop}", nil }
+      end
+    end
+  end
+end