kharon 1.1.0 → 1.1.1

data/doc/top-level-namespace.html

@@ -103,7 +103,7 @@
 </div>
 
     <div id="footer">
-  Generated on Tue May 17 11:54:24 2016 by
+  Generated on Thu Jun  2 16:20:54 2016 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.7.6 (ruby-1.9.3).
 </div>

data/kharon.gemspec

@@ -2,6 +2,7 @@
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'kharon/version'
+require 'date'
 
 Gem::Specification.new do |specification|
   specification.name        = "kharon"
@@ -13,12 +14,12 @@ Gem::Specification.new do |specification|
   specification.email       = "courtois.vincent@outlook.com"
   specification.files       = `git ls-files`.split($/)
   specification.homepage    = "https://rubygems.org/gems/kharon"
-  specification.license     = "Apache License 2"
+  specification.license     = "Apache-2.0"
   specification.test_files  = ["spec/spec_helper.rb", "spec/lib/kharon/validator_spec.rb"]
 
   specification.required_ruby_version = ">= 1.9.3"
 
-  specification.add_runtime_dependency "bson", "~> 2.2", ">= 2.2.2"
+  specification.add_runtime_dependency "bson", ">= 4.2.1", "< 5.0.0"
 
   specification.add_development_dependency "yard", "~> 0.8"
   specification.add_development_dependency "redcarpet", "3.3.1"
@@ -26,4 +27,5 @@ Gem::Specification.new do |specification|
   specification.add_development_dependency "rake", "~> 10.0"
   specification.add_development_dependency "rack-test", "~> 0.6.2"
   specification.add_development_dependency "rspec", "~> 3.0", ">= 3.0.0"
+  specification.add_development_dependency "pry"
 end

data/lib/kharon.rb

@@ -2,10 +2,10 @@
 # @author Vincent Courtois <courtois.vincent@outlook.com>
 module Kharon
 
-  [:Validator, :Version, :Errors, :Handlers, :Helpers, :Validate].each { |classname| autoload(classname, "kharon/#{classname.downcase}") }
-
   @@use_exceptions = true
 
+  @@processors = {}
+
   # Configuration method used to tell the module if it uses exceptions or stores error messages.
   # @param [Boolean] use TRUE if you want to use exceptions, FALSE else.
   def self.use_exceptions(use = true)
@@ -17,4 +17,34 @@ module Kharon
   def self.errors_handler
     @@use_exceptions ? Kharon::Handlers::Exceptions.instance : Kharon::Handlers::Messages.new
   end
+
+  # Adds a processor class to the list of processors.
+  # @param [Symbol] name the name of the stored processor to retrieve it after. It will be the method you call to process a data with that processor.
+  # @param [Class] classname the class object for the processor to be instanciated later.
+  def self.add_processor(name, classname)
+    @@processors[name] = classname if classname.ancestors.include? Kharon::Processor
+  end
+
+  # Removes a processor from the list of available processors.
+  # @param [Symbol] name the name (key) of the processor to delete.
+  def self.remove_processor(name)
+    @@processors.delete(name) if self.has_processor?(name)
+  end
+
+  # Getter for the list of processors.
+  # @return [Hash] the list of processors currently available.
+  def self.processors
+    @@processors
+  end
+
+  # Checks if a processor currently exists in the system.
+  # @param [String] name the name of the processor to check the existence.
+  # @return [Boolean] TRUE if the processor exists, FALSE if not.
+  def self.has_processor?(name)
+    @@processors.keys.include?(name)
+  end
+
+  [:Processor, :Validator, :Version, :Errors, :Handlers, :Helpers, :Validate].each { |classname| autoload(classname, "kharon/#{classname.downcase}") }
+
+  Dir[File.join(File.dirname(__FILE__), "kharon/processors/*.rb")].each { |filename| require filename}
 end

data/lib/kharon/processor.rb

@@ -0,0 +1,162 @@
+module Kharon
+  # A basic processor used to be subclassed by all different processors.
+  # It provides basic informations to process a hash key validation.
+  # @author Vincent Courtois <courtois.vincent@outlook.com>
+  class Processor
+
+    Kharon.add_processor(:any, Kharon::Processor)
+
+    attr_accessor :validator
+
+    def initialize(validator)
+      @validator = validator
+    end
+
+    # Default processing method, simply storing the validated key in the filtered hash.
+    # @param [Object] key the key associated with the value currently filteres in the filtered datas.
+    # @param [Hash]   options the options applied to the initial value.
+    def process(key, options = {})
+      store(key, ->(item){item}, options)
+    end
+
+    protected
+
+    # This method is executed before any call to a public method.
+    # @param [Object] key the key associated with the value currently filteres in the filtered datas.
+    # @param [Hash]   options the options applied to the initial value.
+    def before_all(key, options)
+      required(key) if (options.has_key?(:required) and options[:required] == true)
+      if options.has_key?(:dependencies)
+        dependencies(key, options[:dependencies])
+      elsif options.has_key?(:dependency)
+        dependency(key, options[:dependency])
+      end
+    end
+
+    # Tries to store the associated key in the filtered key, transforming it with the given process.
+    # @param [Object] key the key associated with the value to store in the filtered datas.
+    # @param [Proc]   process a process (lambda) to execute on the initial value. Must contain strictly one argument.
+    # @param [Hash]   options the options applied to the initial value.
+    def store(key, process, options = {})
+      unless (options.has_key?(:extract) and options[:extract] == false)
+        if validator.datas.has_key?(key)
+          value = ((options.has_key?(:cast) and options[:cast] == false) ? validator.datas[key] : process.call(validator.datas[key]))
+          if(options.has_key?(:in))
+            in_array?(key, options[:in])
+          elsif(options.has_key?(:equals))
+            equals_to?(key, options[:equals])
+          elsif(options.has_key?(:equals_key))
+            equals_key?(key, options[:equals_key])
+          end
+          options.has_key?(:rename) ? (validator.filtered[options[:rename]] = value) : (validator.filtered[key] = value)
+        end
+      end
+    end
+
+    # Raises a type error with a generic message.
+    # @param [Object] key the key associated from the value triggering the error.
+    # @param [Class]  type the expected type, not respected by the initial value.
+    # @raise [ArgumentError] the chosen type error.
+    def raise_type_error(key, type)
+      raise_error(type: "type", key: key, supposed: type, found: key.class)
+    end
+
+    # Raises an error giving a message to display.
+    # @param [String] message the the message to display with the exception.
+    # @raise ArgumentError an error to stop the execution when this method is invoked.
+    def raise_error(message)
+      validator.handler.report_error(message)
+    end
+
+    # Accessor for the errors, use only if the handler is a Kharon::Handlers::Messages.
+    # @return [Array] the errors encountered during validation or an empty array if the handler was a Kharon::Handlers::Exceptions.
+    def errors
+      validator.handler.respond_to?(:errors) ? validator.handler.errors : []
+    end
+
+    # Checks if a required key is present in provided datas.
+    # @param [Object] key the key of which check the presence.
+    # @raise [ArgumentError] if the key is not present.
+    def required(key)
+      raise_error(type: "required", key: key) unless validator.datas.has_key?(key)
+    end
+
+    # Syntaxic sugar used to chack several dependencies at once.
+    # @param [Object] key the key needing another key to properly work.
+    # @param [Object] dependencies the keys needed by another key for it to properly work.
+    # @raise [ArgumentError] if the required dependencies are not present.
+    # @see self#check_dependency the associated singular method.
+    def dependencies(key, dependencies)
+      dependencies.each { |dependency| dependency(key, dependency) }
+    end
+
+    # Checks if a dependency is respected. A dependency is a key openly needed by another key.
+    # @param [Object] key the key needing another key to properly work.
+    # @param [Object] dependency the key needed by another key for it to properly work.
+    # @raise [ArgumentError] if the required dependency is not present.
+    def dependency(key, dependency)
+      raise_error(type: "dependency", key: "key", needed: dependency) unless validator.datas.has_key?(dependency)
+    end
+
+    # Check if the value associated with the given key is typed with the given type, or with a type inheriting from it.
+    # @param [Object]   key the key of the value to check the type from.
+    # @param [Class]    type the type with which check the initial value.
+    # @return [Boolean] true if the initial value is from the right type, false if not.
+    def is_typed?(key, type)
+      return (!validator.datas.has_key?(key) or validator.datas[key].kind_of?(type))
+    end
+
+    # Checks if the value associated with the given key is included in the given array of values.
+    # @param [Object] key the key associated with the value to check.
+    # @param [Array]  values the values in which the initial value should be contained.
+    # @raise [ArgumentError] if the initial value is not included in the given possible values.
+    def in_array?(key, values)
+      raise_error(type: "array.in", key: key, supposed: values, value: validator.datas[key]) unless (values.empty? or values.include?(validator.datas[key]))
+    end
+
+    # Checks if the value associated with the given key is equal to the given value.
+    # @param [Object] key the key associated with the value to check.
+    # @param [Object] value the values with which the initial value should be compared.
+    # @raise [ArgumentError] if the initial value is not equal to the given value.
+    def equals_to?(key, value)
+      raise_error(type: "equals", key: key, supposed: value, found: validator.datas[key]) unless validator.datas[key] == value
+    end
+
+    # Checks if the value associated with the given key is equal to the given key.
+    # @param [Object] key the key associated with the value to check.
+    # @param [Object] value the key to compare the currently validated key with.
+    # @raise [ArgumentError] if the initial value is not equal to the given value.
+    def equals_key?(key, value)
+      raise_error(type: "equals", key: key, supposed: validator.datas[value], found: validator.datas[key]) unless validator.datas[key] == validator.datas[value]
+    end
+
+    # Check if the value associated with the given key matches the given regular expression.
+    # @param [Object]   key the key of the value to compare with the given regexp.
+    # @param [Regexp]   regex the regex with which match the initial value.
+    # @return [Boolean] true if the initial value matches the regex, false if not.
+    def match?(key, regex)
+      return (!validator.datas.has_key?(key) or validator.datas[key].to_s.match(regex))
+    end
+
+    def match_regex?(key, value, regex)
+      regex = Regexp.new(regex) if regex.kind_of?(String)
+      raise_error(type: "regex", regex: regex, value: value, key: key) unless regex.match(value)
+    end
+
+    # Checks if the value associated with the given key has the given required values.
+    # @param [Object] key the key associated with the value to check.
+    # @param [Array]  required_values the values that the initial Enumerable typed value should contain.
+    # @raise [ArgumentError] if the initial value has not each and every one of the given values.
+    def contains?(key, values, required_values)
+      raise_error(type: "contains.values", required: required_values, key: key) if (values & required_values) != required_values
+    end
+
+    # Checks if the value associated with the given key has the given required keys.
+    # @param [Object] key the key associated with the value to check.
+    # @param [Array]  required_keys the keys that the initial Hash typed value should contain.
+    # @raise [ArgumentError] if the initial value has not each and every one of the given keys.
+    def has_keys?(key, required_keys)
+      raise_error(type: "contains.keys", required: required_keys, key: key) if (validator.datas[key].keys & required_keys) != required_keys
+    end
+  end
+end

data/lib/kharon/processors.rb

@@ -0,0 +1,6 @@
+module Kharon
+  # Module containing all the processors used to process and validate datas.
+  # @author Vincent Courtois <courtois.vincent@outlook.com>
+  module Processors
+  end
+end

data/lib/kharon/processors/array_processor.rb

@@ -0,0 +1,30 @@
+module Kharon
+  module Processors
+    
+    # Processor to validate arrays. It has the :contains option plus the default ones.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    class ArrayProcessor < Kharon::Processor
+
+      Kharon.add_processor(:array, Kharon::Processors::ArrayProcessor)
+
+      # Checks if the given key is a datetime or not.
+      # @param [Object] key the key about which verify the type.
+      # @param [Hash]   options a hash of options passed to this method (see documentation to know which options pass).
+      # @example Validates a key so it has to be a datetime, and depends on two other keys.
+      #   @validator.datetime(:a_datetime, dependencies: [:another_key, :a_third_key])
+      def process(key, options = {})
+        before_all(key, options)
+        is_typed?(key, Array) ? store(key, ->(item){item.to_a}, options) : raise_type_error(key, "Array")
+      end
+
+      # Stores an array after verifying that it contains the values given in the contains? option.
+      # @param [Object] key the key associated with the value to store in the filtered datas.
+      # @param [Proc]   process a process (lambda) to execute on the initial value. Must contain strictly one argument.
+      # @param [Hash]   options the options applied to the initial value.
+      def store(key, process, options)
+        contains?(key, validator.datas[key], options[:contains]) if(options.has_key?(:contains))
+        super(key, process, options)
+      end
+    end
+  end
+end

data/lib/kharon/processors/boolean_processor.rb

@@ -0,0 +1,31 @@
+module Kharon
+  module Processors
+
+    # Processor to validate booleans. It only has the default options.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    class BooleanProcessor < Kharon::Processor
+
+      Kharon.add_processor(:boolean, Kharon::Processors::BooleanProcessor)
+
+      # Checks if the given key is a boolean or not.
+      # @param [Object] key the key about which verify the type.
+      # @param [Hash]   options a hash of options passed to this method (see documentation to know which options pass).
+      # @example Validates a key so it has to be a boolean.
+      #   @validator.boolean(:a_boolean)
+      def process(key, options = {})
+        before_all(key, options)
+        match?(key, /(true)|(false)/) ? store(key, ->(item){to_boolean(item)}, options) : raise_type_error(key, "Numeric")
+      end
+
+      private
+
+      # Transforms a given value in a boolean.
+      # @param [Object] value the value to transform into a boolean.
+      # @return [Boolean] true if the value was true, 1 or yes, false if not.
+      def to_boolean(value)
+        ["true", "1", "yes"].include?(value.to_s) ? true : false
+      end
+
+    end
+  end
+end

data/lib/kharon/processors/box_processor.rb

@@ -0,0 +1,63 @@
+module Kharon
+  module Processors
+
+    # Processor to validate boxes. It has the :at_most and :at_least with the default ones.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    class BoxProcessor < Kharon::Processor
+
+      Kharon.add_processor(:box, Kharon::Processors::BoxProcessor)
+
+      # Checks if the given key is a box (geofences) or not. A box is composed of four numbers (positive or negative, decimal or not) separed by commas.
+      # @param [Object] key the key about which verify the type.
+      # @param [Hash]   options a hash of options passed to this method (see documentation to know which options pass).
+      # @example Validates a key so it has to be a box.
+      #   @validator.box(:a_box)
+      def process(key, options = {})
+        before_all(key, options)
+        match?(key, /^(?:[+-]?\d{1,3}(?:\.\d{1,7})?,?){4}$/) ? store(key, nil, options) : raise_type_error(key, "Box")
+      end
+
+      # Tries to store the associated key in the filtered key, transforming it with the given process.
+      # @param [Object] key the key associated with the value to store in the filtered datas.
+      # @param [Proc]   process a process (lambda) to execute on the initial value. Must contain strictly one argument.
+      # @param [Hash]   options the options applied to the initial value.
+      def store(key, process, options)
+        if(options.has_key?(:at_least))
+          box_contains?(key, validator.datas[key], options[:at_least])
+        end
+        if(options.has_key?(:at_most))
+          box_contains?(key, options[:at_most], validator.datas[key])
+        end
+        super(key, ->(item){parse_box(key, validator.datas[key])}, options)
+      end
+
+      private
+
+      # Verify if a box contains another box.
+      # @param [Object] container any object that can be treated as a box, container of the other box
+      # @param [Object] contained any object that can be treated as a box, contained in the other box
+      # @return [Boolean] TRUE if the box is contained in the other one, FALSE if not.
+      def box_contains?(key, container, contained)
+        container = parse_box(key, container)
+        contained = parse_box(key, contained)
+        result = ((container[0][0] <= contained[0][0]) and (container[0][1] <= container[0][1]) and (container[1][0] >= container[1][0]) and (container[1][1] >= container[1][1]))
+        raise_error(type: "box.containment", contained: contained, container: container, key: key) unless result
+      end
+
+      # Parses a box given as a string of four numbers separated by commas.
+      # @param [String] box the string representing the box.
+      # @return [Array] an array of size 2, containing two arrays of size 2 (the first being the coordinates of the top-left corner, the second the ones of the bottom-right corner)
+      def parse_box(key, box)
+        if box.kind_of?(String)
+          begin
+            raw_box = box.split(",").map(&:to_f)
+            box = [[raw_box[0], raw_box[1]], [raw_box[2], raw_box[3]]]
+          rescue
+            raise_error(type: "box.format", key: "key", value: box)
+          end
+        end
+        return box
+      end
+    end
+  end
+end

data/lib/kharon/processors/date_processor.rb

@@ -0,0 +1,21 @@
+module Kharon
+  module Processors
+
+    # Processor to validate dates. It only has the default options.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    class DateProcessor < Kharon::Processor
+
+      Kharon.add_processor(:date, Kharon::Processors::DateProcessor)
+
+      # Checks if the given key is a datetime or not.
+      # @param [Object] key the key about which verify the type.
+      # @param [Hash]   options a hash of options passed to this method (see documentation to know which options pass).
+      # @example Validates a key so it has to be a datetime, and depends on two other keys.
+      #   @validator.datetime(:a_datetime, dependencies: [:another_key, :a_third_key])
+      def process(key, options = {})
+        before_all(key, options)
+        begin; store(key, ->(item){Date.parse(item.to_s)}, options); rescue; raise_type_error(key, "Date"); end
+      end
+    end
+  end
+end

data/lib/kharon/processors/datetime_processor.rb

@@ -0,0 +1,21 @@
+module Kharon
+  module Processors
+
+    # Processor to validate datetimes. It only has the default options.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    class DatetimeProcessor < Kharon::Processor
+
+      Kharon.add_processor(:datetime, Kharon::Processors::DatetimeProcessor)
+
+      # Checks if the given key is a datetime or not.
+      # @param [Object] key the key about which verify the type.
+      # @param [Hash]   options a hash of options passed to this method (see documentation to know which options pass).
+      # @example Validates a key so it has to be a datetime, and depends on two other keys.
+      #   @validator.datetime(:a_datetime, dependencies: [:another_key, :a_third_key])
+      def process(key, options = {})
+        before_all(key, options)
+        begin; store(key, ->(item){DateTime.parse(item.to_s)} , options); rescue; raise_type_error(key, "DateTime"); end
+      end
+    end
+  end
+end

data/lib/kharon/processors/email_processor.rb

@@ -0,0 +1,21 @@
+module Kharon
+  module Processors
+
+    # Processor to validate emails. It only has the default options.
+    # @author Vincent Courtois <courtois.vincent@outlook.com>
+    class EmailProcessor < Kharon::Processor
+
+      Kharon.add_processor(:email, Kharon::Processors::EmailProcessor)
+
+      # Checks if the given key is a not-empty string or not.
+      # @param [Object] key the key about which verify the type.
+      # @param [Hash]   options a hash of options passed to this method (see documentation to know which options pass).
+      # @example Validates a key so it has to be a string, and seems like and email address (not sure of the regular expression though).
+      #   @validator.text(:an_email, regex: "[a-zA-Z]+@[a-zA-Z]+\.[a-zA-Z]{2-4}")
+      def process(key, options = {})
+        before_all(key, options)
+        match?(key, /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}$/) ? store(key, ->(item){item}, options) : raise_type_error(key, "Email")
+      end
+    end
+  end
+end