respect 0.1.0

data/lib/respect.rb

@@ -0,0 +1,231 @@
+require 'active_support/dependencies/autoload'
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/integer/inflections'
+require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/core_ext/string/strip'
+
+# Setup inflection rules for our acronyms
+ActiveSupport::Inflector.inflections do |inflect|
+  inflect.acronym "URI"
+  inflect.acronym "UTC"
+  inflect.acronym "IP"
+  inflect.acronym "JSON"
+end
+
+# Provide methods and classes to define, validate, sanitize and dump object schema.
+#
+# Classes in this module are split in 5 groups:
+# * The _schema_ classes are the core of this module since they support the validation
+#   process and are the internal representation of schema specification (see {Schema}).
+# * The _definition_ classes (aka _def_ classes) are the front-end of this module since
+#   they implement the schema definition DSL (see {GlobalDef}).
+# * The _validator_ classes implement validation routine you can attach to your schema.
+#   accessible via the schema's options (see {Validator}).
+# * The _dumper_ classes are the back-end of this module since they implement the
+#   convertion of the internal schema representation to different formats.
+# * The _miscellaneous_ classes provides various support for the other categories.
+#
+# You can extend this library in many ways:
+#
+# 1. If you want to add your own schema class, you can sub-class the {CompositeSchema}
+#    class. Sub-classing of the {Schema} class is not well supported yet as it may have
+#    some issues with the current dumpers (see {DslDumper} and {Org3Dumper}). Fortunately,
+#    most of the cases can be handled by {CompositeSchema}.
+# 1. If you want to simply add new statements to the schema definition DSL, you can just
+#    bundle them in a module and call {Respect.extend_dsl_with} (see {CoreStatements} for
+#    further information).
+#
+# Extension of the _validator_ and _dumper_ classes is still experimental. Also, creating
+# custom _definition_ classes is not recommended yet.
+module Respect
+  extend ActiveSupport::Autoload
+
+  # Schema classes
+  autoload :Schema
+  autoload :HashSchema
+  autoload :IntegerSchema
+  autoload :FloatSchema
+  autoload :NumericSchema
+  autoload :StringSchema
+  autoload :ArraySchema
+  autoload :AnySchema
+  autoload :BooleanSchema
+  autoload :NullSchema
+  autoload :URISchema
+  autoload :RegexpSchema
+  autoload :DatetimeSchema
+  autoload :IPAddrSchema
+  autoload :Ipv4AddrSchema
+  autoload :Ipv6AddrSchema
+  autoload :UTCTimeSchema
+  autoload :HasConstraints
+  autoload :CompositeSchema
+  # Validator classes
+  autoload :Validator
+  autoload :EqualToValidator
+  autoload :GreaterThanValidator
+  autoload :GreaterThanOrEqualToValidator
+  autoload :LessThanValidator
+  autoload :LessThanOrEqualToValidator
+  autoload :DivisibleByValidator
+  autoload :MultipleOfValidator
+  autoload :InValidator
+  autoload :MatchValidator
+  autoload :MinLengthValidator
+  autoload :MaxLengthValidator
+  autoload :FormatValidator
+  # DSL classes
+  autoload :SchemaDef
+  autoload :ArrayDef
+  autoload :HashDef
+  autoload :GlobalDef
+  autoload :ItemsDef
+  autoload :CoreStatements
+  autoload :DefWithoutName
+  autoload :FakeNameProxy
+  # Dumper classes
+  autoload :DslDumper
+  autoload :Org3Dumper
+  # Miscellaneous classes
+  autoload :DocParser
+  autoload :DocHelper
+  autoload :JSONSchemaHTMLFormatter
+
+  # Base error of all errors raised by this module.
+  class RespectError < StandardError
+  end
+
+  # Raised when the validation process has failed.
+  class ValidationError < RespectError
+    def initialize(message)
+      super
+      @context = [ message ]
+    end
+
+    # An array of error messages to help you track where
+    # the error happened. Use it as a back-trace but in
+    # your validated object instead of your code.
+    attr_reader :context
+  end
+
+  # Raised when you did an illegal operation while defining
+  # a schema. See it as an ArgumentError but more specific.
+  class InvalidSchemaError < RespectError
+  end
+
+  class << self
+
+    # Extend the schema definition DSL with the statements defined in the given
+    # module +mod+. Its methods would be available to each definition class
+    # calling {GlobalDef.include_core_statements}.
+    def extend_dsl_with(mod)
+      raise ArugmentError, "cannot extend DSL with CoreStatements" if mod == CoreStatements
+      CoreStatements.send(:include, mod)
+      # We must "refresh" all the classes include "CoreStatements" by re-including it to
+      # work around the
+      # {dynamic module include problem}[http://eigenclass.org/hiki/The+double+inclusion+problem]
+      GlobalDef.core_contexts.each{|c| c.send(:include, CoreStatements) }
+    end
+
+    STATEMENT_NAME_REGEXP = /^[a-z_][a-z_0-9]*$/
+
+    # Build a schema class name from the given +statement_name+.
+    def schema_name_for(statement_name)
+      unless statement_name =~ STATEMENT_NAME_REGEXP
+        raise ArgumentError, "statement '#{statement_name}' name must match #{STATEMENT_NAME_REGEXP.inspect}"
+      end
+      const_name = statement_name.to_s
+      if const_name == "schema"
+        "#{self.name}::Schema"
+      else
+        "#{self.name}::#{const_name.camelize}Schema"
+      end
+    end
+
+    # Return the schema class associated to the given +statement_name+.
+    #
+    # A "valid" schema class must verify the following properties:
+    # * Named like +StatementNameSchema+ in {Respect} module.
+    # * Be a sub-class of {Schema}.
+    # * Be concrete (i.e. have a public method +new+)
+    def schema_for(statement_name)
+      klass = Respect.schema_name_for(statement_name).safe_constantize
+      if klass && klass < Schema && klass.public_methods.include?(:new)
+        klass
+      else
+        nil
+      end
+    end
+
+    # Test whether a schema is defined for the given +statement_name+.
+    def schema_defined_for?(statement_name)
+      !!schema_for(statement_name)
+    end
+
+    # Turn the given string (assuming it is a constraint name) into a
+    # validator class name string.
+    def validator_name_for(constraint_name)
+      "#{self.name}::#{constraint_name.to_s.camelize}Validator"
+    end
+
+    # Turn the given +constraint_name+ into a validator class symbol.
+    # Return nil if the validator class does not exist.
+    def validator_for(constraint_name)
+      validator_name_for(constraint_name).safe_constantize
+    end
+
+    # Test whether a validator is defined for the given +constraint_name+.
+    def validator_defined_for?(constraint_name)
+      !!validator_for(constraint_name)
+    end
+
+    # Sanitize the given +object+ *in-place* according to the given +sanitized_object+.
+    # A sanitized object contains value with more specific data type. Like a URI
+    # object instead of a plain string.
+    #
+    # Non-sanitized value are not touch (i.e. values present in +object+ but not in
+    # +sanitized_object+). However, +object["key"]+ and +object[:key]+ are considered as
+    # referring to the same value, but they original key would be preserved.
+    #
+    # Example:
+    #   object = { "int" => "42" }
+    #   Respect.sanitize_object!(object, { "int" => 42 }
+    #   object                                     #=> { "int" => 42 }
+    #   object = { :int => "42" }
+    #   Respect.sanitize_object!(object, { "int" => 42 }
+    #   object                                     #=> { :int => 42 }
+    #
+    # The sanitized object is accessible via the {Schema#sanitized_object} method after a
+    # successful validation.
+    def sanitize_object!(object, sanitized_object)
+      case object
+      when Hash
+        if sanitized_object.is_a? Hash
+          sanitized_object.each do |name, value|
+            if object.has_key?(name)
+              object[name] = sanitize_object!(object[name], value)
+            else
+              object[name.to_sym] = sanitize_object!(object[name.to_sym], value)
+            end
+          end
+          object
+        else
+          sanitized_object
+        end
+      when Array
+        if sanitized_object.is_a? Array
+          sanitized_object.each_with_index do |value, index|
+            object[index] = sanitize_object!(object[index], value)
+          end
+          object
+        else
+          sanitized_object
+        end
+      else
+        sanitized_object
+      end
+    end
+
+  end
+
+end

data/lib/respect/any_schema.rb

@@ -0,0 +1,22 @@
+module Respect
+  class AnySchema < Schema
+
+    public_class_method :new
+
+    def validate(object)
+      case object
+      when Hash, Array, TrueClass, FalseClass, Numeric, NilClass, String
+        self.sanitized_object = object
+        true
+      else
+        raise ValidationError,
+              "object is not of a valid type but a #{object.class}"
+      end
+    rescue ValidationError => e
+      # Reset sanitized object.
+      self.sanitized_object = nil
+      raise e
+    end
+
+  end # class AnySchema
+end # module Respect

data/lib/respect/array_def.rb

@@ -0,0 +1,28 @@
+module Respect
+  class ArrayDef < GlobalDef
+    include_core_statements
+    include DefWithoutName
+
+    def initialize(options = {})
+      @array_schema = ArraySchema.new(options)
+    end
+
+    def items(&block)
+      @array_schema.items = ItemsDef.eval(&block)
+    end
+
+    def extra_items(&block)
+      @array_schema.extra_items = ItemsDef.eval(&block)
+    end
+
+    private
+
+    def evaluation_result
+      @array_schema
+    end
+
+    def update_context(name, schema)
+      @array_schema.item = schema
+    end
+  end
+end

data/lib/respect/array_schema.rb

@@ -0,0 +1,203 @@
+module Respect
+  # A schema to specify the structure of an array.
+  #
+  # They are two approaches to specify the structure of an array.
+  #
+  # If the items of your array have all the same structure then you
+  # should use the {#item=} method to set their schema.
+  #
+  # Example:
+  #   # An array where all items are integer greater than 42.
+  #   s = ArraySchema.define do |s|
+  #     s.item do |s|
+  #       s.integer greater_than: 42
+  #     end
+  #   end
+  #   s.validate?([])              #=> true
+  #   s.validate?([ 43 ])          #=> true
+  #   s.validate?([ 43, 44 ])      #=> true
+  #   s.validate?([ 43, 44, 30 ])  #=> false
+  #
+  # Otherwise, you should use the {#items=} and {#extra_items=}. This is called
+  # "tuple" typing.
+  #
+  # Example:
+  #   # An array where first item is an integer and the second one
+  #   # is a string.
+  #   ArraySchema.define do |s|
+  #     s.items do |s|
+  #       s.integer
+  #       s.string
+  #     end
+  #   end
+  #   s.validate?([])              #=> false
+  #   s.validate?([ 43 ])          #=> false
+  #   s.validate?([ 43, "foo" ])   #=> true
+  #   s.validate?([ 43, 44 ])      #=> false
+  #
+  # You cannot mix tuple typing and single item typing.
+  #
+  # You can pass several options when creating an {ArraySchema}:
+  # uniq::     if +true+, duplicated items are forbidden (+false+ by default).
+  # min_size:: if set the array must have at least the given number of items
+  #            (+nil+ by default). This option apply only in non-tuple typing.
+  # max_size:: if set the array must have at most the given number of items
+  #            (+nil+ by default). This option apply only in non-tuple typing.
+  class ArraySchema < Schema
+
+    public_class_method :new
+
+    class << self
+      # Overwritten method. See {Schema.default_options}
+      def default_options
+        super().merge({
+            uniq: false,
+          }).freeze
+      end
+    end
+
+    def initialize(options = {})
+      super(self.class.default_options.merge(options))
+    end
+
+    def initialize_copy(other)
+      super
+      @items = other.items.dup unless other.items.nil?
+      @extra_items = other.extra_items.dup unless other.extra_items.nil?
+    end
+
+    # Set the schema that all items in the array must validate.
+    def item=(item)
+      if @items
+        raise InvalidSchemaError,
+              "cannot mix single item and multiple items validation"
+      end
+      @item = item
+    end
+
+    # Get the schema that all items in the array must validate.
+    attr_reader :item
+
+    # Set the array of schema that the corresponding items must validate.
+    def items=(items)
+      if @item
+        raise InvalidSchemaError,
+              "cannot mix single item and multiple items validation"
+      end
+      @items = items
+    end
+
+    # Get the array of schema that the corresponding items must validate.
+    attr_reader :items
+
+    # Set extra schema items. These are optional. If they are not in the
+    # object the validation pass anyway.
+    def extra_items=(extra_items)
+      return @extra_items unless extra_items
+      if @item
+        raise InvalidSchemaError,
+              "cannot mix single item and extra items validation"
+      end
+      @items = [] if @items.nil?
+      @extra_items = extra_items
+    end
+
+    # Get the extra schema items.
+    attr_reader :extra_items
+
+    # Overwritten method. See {Schema#validate}
+    def validate(object)
+      # Handle nil case.
+      if object.nil?
+        if allow_nil?
+          self.sanitized_object = nil
+          return true
+        else
+          raise ValidationError, "object is nil but this #{self.class} does not allow nil"
+        end
+      end
+      # Validate type.
+      unless object.is_a?(Array)
+        raise ValidationError, "object is not an array but a #{object.class}"
+      end
+      # At this point we are sure @item and (@items or @extra_items) cannot be
+      # defined both. (see the setters).
+      sanitized_object = []
+      # Validate expected item.
+      if @item
+        if options[:min_size] && object.size < options[:min_size]
+          raise ValidationError,
+                "expected at least #{options[:min_size]} item(s) but got #{object.size}"
+        end
+        if options[:max_size] && object.size > options[:max_size]
+          raise ValidationError,
+                "expected at most #{options[:min_size]} item(s) but got #{object.size}"
+        end
+        object.each_with_index do |item, i|
+          validate_item(i, @item, object, sanitized_object)
+        end
+      end
+      # Validate object items count.
+      if @items || @extra_items
+        if @extra_items
+          min_size = @items ? @items.size : 0
+          unless min_size <= object.size
+            raise ValidationError,
+                  "array size should be at least #{min_size} but is #{object.size}"
+          end
+        else
+          if @items.size != object.size
+            raise ValidationError,
+                  "array size should be #{@items.size} but is #{object.size}"
+          end
+        end
+      end
+      # Validate expected multiple items.
+      if @items
+        @items.each_with_index do |schema, i|
+          validate_item(i, schema, object, sanitized_object)
+        end
+      end
+      # Validate extra items.
+      if @extra_items
+        @extra_items.each_with_index do |schema, i|
+          if @items.size + i < object.size
+            validate_item(@items.size + i, schema, object, sanitized_object)
+          end
+        end
+      end
+      # Validate all items are unique.
+      if options[:uniq]
+        s = Set.new
+        object.each_with_index do |e, i|
+          if s.add?(e).nil?
+            raise ValidationError,
+                  "duplicated item number #{i}"
+          end
+        end
+      end
+      self.sanitized_object = sanitized_object
+      true
+    rescue ValidationError => e
+      # Reset sanitized object.
+      self.sanitized_object = nil
+      raise e
+    end
+
+    def ==(other)
+      super && @item == other.item && @items == other.items && @extra_items == other.extra_items
+    end
+
+    private
+
+    def validate_item(index, schema, object, sanitized_object)
+      begin
+        schema.validate(object[index])
+        sanitized_object << schema.sanitized_object
+      rescue ValidationError => e
+        e.context << "in array #{index.ordinalize} item"
+        raise e
+      end
+    end
+  end
+end