respect 0.1.0

data/lib/respect/boolean_schema.rb

@@ -0,0 +1,32 @@
+module Respect
+  class BooleanSchema < Schema
+    include HasConstraints
+
+    public_class_method :new
+
+    def validate_type(object)
+      case object
+      when String
+        if object == "true"
+          true
+        elsif object == "false"
+          false
+        else
+          raise ValidationError,
+                "malformed boolean value: `#{object}'"
+        end
+      when TrueClass, FalseClass
+        object
+      when NilClass
+        if allow_nil?
+          nil
+        else
+          raise ValidationError, "object is nil but this #{self.class} does not allow nil"
+        end
+      else
+        raise ValidationError, "object is not a boolean but a '#{object.class}'"
+      end
+    end
+
+  end # class BooleanSchema
+end # module Respect

data/lib/respect/composite_schema.rb

@@ -0,0 +1,86 @@
+module Respect
+  # A composite schema is a schema composed of another schema.
+  #
+  # Sub-classing {CompositeSchema} is the easiest way to add a user-defined
+  # schema. Indeed, you just have to overwrite {#schema_definition} and optionally
+  # {#sanitize}. Your schema will be handled properly by all other part
+  # of the library (i.e. mainly dumpers and the DSL).
+  #
+  # Example:
+  #   module Respect
+  #     class PointSchema < CompositeSchema
+  #       def schema_defintion
+  #         HashSchema.define do |s|
+  #           s.numeric "x"
+  #           s.numeric "y"
+  #         end
+  #       end
+  #
+  #       def sanitize(object)
+  #         # Assuming you have defined a Point class.
+  #         Point.new(object[:x], object[:y])
+  #       end
+  #     end
+  #   end
+  #
+  # A "point" method will be available in the DSL so you could use
+  # your schema like that:
+  #
+  # Example:
+  #   HashSchema.define do |s|
+  #     s.point "origin"
+  #   end
+  class CompositeSchema < Schema
+
+    class << self
+      def inherited(subclass)
+        subclass.public_class_method :new
+      end
+    end
+
+    def initialize(options = {})
+      super
+      @schema = self.schema_definition
+    end
+
+    # Returns the schema composing this schema.
+    attr_reader :schema
+
+    # Overloaded methods (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.name} does not allow nil"
+        end
+      end
+      @schema.validate(object)
+      self.sanitized_object = sanitize(@schema.sanitized_object)
+      true
+    rescue ValidationError => e
+      # Reset sanitized object.
+      self.sanitized_object = nil
+      raise e
+    end
+
+    # Returns the schema composing this composite schema.
+    # Overwrite this methods in sub-class.
+    def schema_definition
+      raise NoMethodError, "implement me in sub-class"
+    end
+
+    # Sanitize the given validated +object+. Overwrite this method
+    # in sub-class and returns the object that would be inserted
+    # in the sanitized object. The object passed as argument
+    # is an already sanitized sub-part of the overall object
+    # being validated. By default this method is a no-op. It
+    # returns the given +object+.
+    def sanitize(object)
+      object
+    end
+
+  end # class CompositeSchema
+end # module Respect

data/lib/respect/core_statements.rb

@@ -0,0 +1,206 @@
+module Respect
+  # Core DSL statements definition module.
+  #
+  # This module holds all the basic statements available in the DSL. It is included
+  # in all the DSL context using {Respect.extend_dsl_with}. Thus all basic DSL
+  # contexts provides its feature.
+  #
+  # Most of the statements are available as dynamic methods.
+  # For each "FooSchema" class defined in the {Respect} module (and following certain
+  # condition described at {Respect.schema_for}), there is a statement
+  # "foo" (see {Schema.statement_name}) expecting a name, some options and a block.
+  # This statement defines a new "FooSchema" with the given options and block. This
+  # schema is stored in the current context using the given name. The name may be used
+  # differently depending on the context. In a hash definition context it will be
+  # used as a property name whereas it will be simply ignored in the
+  # context of an array. Context classes including the {DefWithoutName} module ignore
+  # the name argument whereas others do not. The {FakeNameProxy} is in charge of
+  # transparently passing +nil+ for the name in contexts including the {DefWithoutName}
+  # module.
+  #
+  # Example:
+  #   HashSchema.define do |s|
+  #     # method_missing calls:
+  #     #   update_context("i", IntegerSchema.define({greater_than: 42}))
+  #     s.integer "i", greater_than: 42
+  #   end
+  #   ArraySchema.define do |s|
+  #     # method_missing calls:
+  #     #   update_context(nil, IntegerSchema.define({greater_than: 42}))
+  #     s.integer greater_than: 42
+  #   end
+  #
+  # Classes including this module must implement the +update_context+ method
+  # which is supposed to update the schema under definition with the given
+  # name and schema created by the method.
+  #
+  # Do not include your helper module in this module since definition classes
+  # including it won't be affected due to the
+  # {dynamic module include problem}[http://eigenclass.org/hiki/The+double+inclusion+problem].
+  # To extend the DSL use {Respect.extend_dsl_with} instead.
+  #
+  # It is recommended that your macros implementation be based on core statements
+  # because +update_context+ API is *experimental*. If you do so anyway your
+  # macros may not work properly with the {#doc} and {#with_options} statements.
+  module CoreStatements
+
+    # @!method string(name, options = {})
+    #   Define a {StringSchema} with the given +options+ and stores it in the
+    #   current context using +name+ as index.
+    # @!method integer(name, options = {})
+    #   Define a {IntegerSchema} with the given +options+ and stores it in the
+    #   current context using +name+ as index.
+    # @!method float(name, options = {})
+    #   Define a {FloatSchema} with the given +options+ and stores it in the
+    #   current context using +name+ as index.
+    # @!method numeric(name, options = {})
+    #   Define a {NumericSchema} with the given +options+ and stores it in the
+    #   current context using +name+ as index.
+    # @!method any(name, options = {})
+    #   Define a {AnySchema} with the given +options+ and stores it in the
+    #   current context using +name+ as index.
+    # @!method null(name, options = {})
+    #   Define a {NullSchema} with the given +options+ and stores it in the
+    #   current context using +name+ as index.
+    # @!method boolean(name, options = {})
+    #   Define a {BooleanSchema} with the given +options+ and stores it in the
+    #   current context using +name+ as index.
+    # @!method uri(name, options = {})
+    #   Define a {URISchema} with the given +options+ and stores it in the
+    #   current context using +name+ as index.
+    # @!method hash(name, options = {}, &block)
+    #   Define a {HashSchema} with the given +options+ and +block+ stores it
+    #   in the current context using +name+ as index.
+    # @!method array(name, options = {})
+    #   Define a {ArraySchema} with the given +options+ and +block+ stores it
+    #   in the current context using +name+ as index.
+    # @!method datetime(name, options = {})
+    #   Define a {DatetimeSchema} with the given +options+ and stores it in the
+    #   current context using +name+ as index.
+    # @!method ip_addr(name, options = {})
+    #   Define a {IPAddrSchema} with the given +options+ and stores it in the
+    #   current context using +name+ as index.
+    # @!method ipv4_addr(name, options = {})
+    #   Define a {Ipv4AddrSchema} with the given +options+ and stores it in the
+    #   current context using +name+ as index.
+    # @!method ipv6_addr(name, options = {})
+    #   Define a {Ipv6AddrSchema} with the given +options+ and stores it in the
+    #   current context using +name+ as index.
+    # @!method regexp(name, options = {})
+    #   Define a {RegexpSchema} with the given +options+ and stores it in the
+    #   current context using +name+ as index.
+    # @!method utc_time(name, options = {})
+    #   Define a {UTCTimeSchema} with the given +options+ and stores it in the
+    #   current context using +name+ as index.
+    #
+    # Call +update_context+ using the first argument as index and passes the rest
+    # to the {Schema.define} class method of the schema class associated with the method name.
+    # As a consequence any call to missing method +foo+ will define a +FooSchema+
+    # schema using +FooSchema.define+.
+    #
+    # The options are merged with the default options which may include the +:doc+
+    # option if {#doc} has been called before. The current documentation is reset
+    # after this call.
+    #
+    # Note that if you define a new schema named after a method already defined in
+    # a context class such as {GlobalDef} or its sub-classes or in +Object+, the
+    # dynamic dispatch won't work. For instance even if you have defined the
+    # +ClassSchema+ class the following code won't work as expected:
+    #
+    #   Schema.define do |s|
+    #     s.class  # Call Object#class !!!!!
+    #   end
+    #
+    # To prevent this problem you must undefine the method in the DSL by doing
+    # something like that:
+    #
+    #   module Respect
+    #     class GlobalDef
+    #       undef_method :class
+    #     end
+    #   end
+    #
+    # or you can overwrite the +class+ method in the context of your choice:
+    #
+    #   module Respect
+    #     class GlobalDef
+    #       def class(name, options = {}, &block)
+    #         update_context name, ClassSchema.define(options, &block)
+    #       end
+    #     end
+    #   end
+    #
+    # Do not un-define or overwrite 'method' and 'methods' since {FakeNameProxy}
+    # use them.
+    def method_missing(method_name, *args, &block)
+      if respond_to_missing?(method_name, false)
+        size_range = 1..2
+        if size_range.include? args.size
+          name = args.shift
+          default_options = {}
+          default_options.merge!(@options) unless @options.nil?
+          default_options[:doc] = @doc unless @doc.nil?
+          if options = args.shift
+            options = default_options.merge(options)
+          else
+            options = default_options
+          end
+          @doc = nil
+          update_context name, Respect.schema_for(method_name).define(options, &block)
+        else
+          expected_size = args.size > size_range.end ? size_range.end : size_range.begin
+          raise ArgumentError, "wrong number of argument (#{args.size} for #{expected_size})"
+        end
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_all)
+      Respect.schema_defined_for?(method_name)
+    end
+
+    # @!method email(name, options = {})
+    #   Define a string formatted an email (see {FormatValidator#validate_email}).
+    # @!method phone_number(name, options = {})
+    #   Define a string formatted as a phone number (see {FormatValidator#validate_phone_number}).
+    # @!method hostname(name, options = {})
+    #   Define a string formatted as a machine host name (see {FormatValidator#validate_hostname}).
+    [
+      :email,
+      :phone_number,
+      :hostname,
+    ].each do |meth_name|
+      define_method(meth_name) do |name, options = {}|
+        string name, options.dup.merge(format: meth_name)
+      end
+    end
+
+    # Define the current documentation text. It will be used as documentation for the
+    # next defined schema. It can be used once, so it is reset once it has been affected
+    # to a schema.
+    #
+    # Example:
+    #   s = HashSchema.define do |s|
+    #     s.doc "A magic number"
+    #     s.integer "magic"
+    #     s.integer "nodoc"
+    #     s.doc "A parameter..."
+    #     s.string "param"
+    #   end
+    #   s["magic"].doc                  #=> "A magic number"
+    #   s["nodoc"].doc                  #=> nil
+    #   s["param"].doc                  #=> "A parameter..."
+    def doc(text)
+      @doc = text
+    end
+
+    # Use +options+ as the default for all schema created within +block+.
+    def with_options(options, &block)
+      @options = options
+      FakeNameProxy.new(self).eval(&block)
+      @options = nil
+    end
+
+  end # module CoreStatements
+end # module Respect

data/lib/respect/datetime_schema.rb

@@ -0,0 +1,27 @@
+module Respect
+  # Validate a date and time string following RFC 3399.
+  # +DateTime+, +Time+, and +Date+ object are accepted.
+  # If validation succeed the sanitized object is a +DateTime+ object.
+  class DatetimeSchema < StringSchema
+
+    def validate_type(object)
+      case object
+      when NilClass
+        if allow_nil?
+          nil
+        else
+          raise ValidationError, "object is nil but this #{self.class} does not allow nil"
+        end
+      when DateTime
+        object
+      when Time
+        object.to_datetime
+      when Date
+        object.to_date
+      else
+        FormatValidator.new(:datetime).validate(object)
+      end
+    end
+
+  end # class DatetimeSchema
+end # module Respect

data/lib/respect/def_without_name.rb

@@ -0,0 +1,6 @@
+module Respect
+  # Include this module in DSL classes defining methods
+  # not accepting name as first argument.
+  module DefWithoutName
+  end
+end

data/lib/respect/divisible_by_validator.rb

@@ -0,0 +1,20 @@
+module Respect
+  class DivisibleByValidator < Validator
+    def initialize(divider)
+      @divider = divider
+    end
+
+    def validate(value)
+      unless (value % @divider).zero?
+        raise ValidationError, "#{value} is not divisible by #@divider"
+      end
+    end
+
+    private
+
+    def to_h_org3
+      { 'divisibleBy' => @divider }
+    end
+
+  end
+end

data/lib/respect/doc_helper.rb

@@ -0,0 +1,24 @@
+module Respect
+  # Convenient module to ease usage of {DocParser}.
+  #
+  # Include it in classes returning their documentation via a +documentation+ method.
+  # This module provides a {#title} and {#description} methods for extracting
+  # them from the documentation.
+  module DocHelper
+    # Returns the title part of the documentation returned by +documentation+ method
+    # (+nil+ if it does not have any).
+    def title
+      if documentation
+        DocParser.new.parse(documentation.to_s).title
+      end
+    end
+
+    # Returns the description part of the documentation returned by +documentation+ method
+    # (+nil+ if it does not have any).
+    def description
+      if documentation
+        DocParser.new.parse(documentation.to_s).description
+      end
+    end
+  end
+end # module Respect

data/lib/respect/doc_parser.rb

@@ -0,0 +1,37 @@
+module Respect
+  class DocParser
+
+    def initialize
+      @title = nil
+      @description = nil
+    end
+
+    def parse(string)
+      ss = StringScanner.new(string)
+      if ss.scan_until(/\n/)
+        if ss.eos?
+          @title = ss.pre_match
+        else
+          if ss.scan(/\n+/)
+            @title = ss.pre_match.chop
+            unless ss.rest.empty?
+              @description = ss.rest
+            end
+          else
+            if ss.eos?
+              @title = string.chop
+            else
+              @description = string
+            end
+          end
+        end
+      else
+        @title = string
+      end
+      self
+    end
+
+    attr_reader :title, :description
+
+  end # class DocParser
+end # module Respect