saphyr 0.4.0.beta

data/lib/saphyr/validator.rb

@@ -0,0 +1,129 @@
+require 'json'
+
+module Saphyr
+
+  # Base class used to define a validator.
+  class Validator
+
+    class << self
+      attr_accessor :cache_config, :proc_idx
+
+      def config()
+        self.cache_config ||= Saphyr::Schema.new
+      end
+
+      # ----- Proxy all following method calls to Saphyr::Schema instance
+      def strict(value)
+        config.strict value
+      end
+
+      def root(value)
+        config.root value
+      end
+
+      def field(name, type, **opts)
+        if config.root_array? and name != :_root_
+          raise Saphyr::Error.new "Can only define ':_root_' field when root is ':array'"
+        end
+        if name == :_root_ and type != :array
+          raise Saphyr::Error.new "Field ':_root_' must be of type ':array'"
+        end
+        config.field name, type, **opts
+      end
+
+      def schema(name, &block)
+        config.schema name, &block
+      end
+
+      def conditional(cond, &block)
+        #
+        # TODO: 'cond' must be a method Symbol or a proc / lambda
+        #
+        method = cond
+        if cond.is_a? Proc
+          m = "_proc_#{self.internal_proc_index}".to_sym
+          self.send :define_method, m, cond
+          method = m
+          self.proc_idx += 1
+        end
+        config.conditional method, &block
+      end
+
+      def cast(field, method)
+        if method.is_a? Proc
+          m = "_proc_#{self.internal_proc_index}".to_sym
+          self.send :define_method, m, method
+          method = m
+          self.proc_idx += 1
+        end
+        config.cast field, method
+      end
+      # ----- / Proxy
+
+      private 
+
+        def internal_proc_index()
+          self.proc_idx ||= 0
+        end
+    end
+
+    def initialize()
+      @proc_idx = 0
+      @ctx = nil
+    end
+
+    # Get the validator configuration (ie: the attached schema)
+    # @return [Saphyr::Schema]
+    def get_config()
+      self.class.config
+    end
+
+    # Find a local schema
+    # @param name [Symbol] The schema name.
+    # @return [Saphyr::Schema]
+    def find_schema(name)
+      self.class.config.find_schema name
+    end
+
+    # Get the parsed JSON data.
+    # @return [Hash]
+    def data()
+      return nil if @ctx.nil?
+      @ctx.data
+    end
+
+    # -----
+
+    # Validate an already parsed JSON document.
+    # @param [Hash | Array] The data to validate.
+    # @return [Boolean] Wheter the validation was successful or failed.
+    def validate(data)
+      @ctx = Saphyr::Engine::Context.new [self], get_config, data, nil, '//'
+      engine = Saphyr::Engine.new @ctx
+      engine.validate
+      @ctx.errors.size == 0
+    end
+
+    # Parse and validate a JSON document.
+    # @param json [String] The JSON document.
+    # @return [Boolean] Wheter the validation was successful or failed.
+    def parse_and_validate(json)
+      validate JSON.parse(json)
+    end
+
+    # Get the validation errors
+    # @return [Array] An array of errors.
+    def errors()
+      return [] if @ctx.nil?
+      @ctx.errors
+    end
+
+    # Get a field from the data to validate.
+    # @param [String | Symbol] The field name
+    # @return The field value
+    def get(field)
+      data = @ctx.data_to_validate
+      data[field.to_s]
+    end
+  end
+end

data/lib/saphyr/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Saphyr
+  VERSION = "0.4.0.beta"
+end

data/lib/saphyr.rb

@@ -0,0 +1,160 @@
+#efrozen_string_literal: true
+
+require_relative "saphyr/version"
+
+# Saphyr is a libray used to validate JSON data using a schema defined with a DSL.
+#
+# == Usage example :
+#
+# Say you have a JSON literal string or already parsed 'data' like that :
+#
+#     json = '{"id": 3465, "name": "Bob"}'
+# 
+#     data = {
+#       "id" => 3465,
+#       "name" => "Bob",
+#     }
+#
+# Define a Validator with a specific schema :
+#
+#     class ItemValidator < Saphyr::Validator
+#       schema do
+#         field :id, :integer, gte: 1, lt: 32000
+#         field :name, :string, min: 2, max: 50
+#       end
+#     end
+#
+# Validate data :
+#
+#     v = ItemValidator.new
+#     if v.validate data
+#       puts "Validation : SUCCESS", "\n"
+#     else
+#       puts "Validation : FAILED", "\n"
+#       Saphyr::Helpers::Format.errors_to_text v.errors
+#     end
+#
+# Or :
+#
+#     v = ItemValidator.new
+#     if v.parse_and_validate json
+#       puts "Validation : SUCCESS", "\n"
+#       data = v.data                      # Get back the parsed json data
+#     else
+#       puts "Validation : FAILED", "\n"
+#       Saphyr::Helpers::Format.errors_to_text v.errors
+#     end
+#
+module Saphyr
+  class Error < StandardError; end
+
+  class << self
+    # The global configuration.
+    # @return [Saphyr::Config]
+    attr_accessor :config
+
+    # This method is part of the DSL used to register global field type or schema.
+    # @param block [Block] This block must use the followingDSL methods:
+    # 'field_type' and 'schema'
+    # @api public
+    def register(&block)
+      self.config ||= Config.new
+      self.config.instance_eval &block
+    end
+
+    # Get a specific global schema.
+    # @param name [Symbol] The name of the schema
+    # @return [Saphyr::Schema]
+    # @raise [Saphyr::Error] If schema does not exists.
+    # @api public
+    def global_schema(name)
+      self.config.get_schema name
+    end
+  end
+
+
+  # This class is used to encapsulate global settings (field types, schema).
+  # @api private
+  class Config
+    attr_reader :field_types, :schemas
+
+    def initialize()
+      @schemas = {}
+      @field_types = {
+        array: Saphyr::Fields::ArrayField,
+        schema: Saphyr::Fields::SchemaField,
+      }
+    end
+
+    # ---------------------------------------------------- DSL
+
+    # This method is part of the DSL and used to register global field type
+    # and global schemas.
+    #
+    # @param name [String, Symbol] The field type name
+    # @param klass [Class] The class used to handle the field type
+    def field_type(name, klass)
+      raise Saphyr::Error.new "Cannot overwrite ':array' field" if name == :array
+      raise Saphyr::Error.new "Cannot overwrite ':schema' field" if name == :schema
+      @field_types[name] = klass
+    end
+
+    # This method is part of the DSL used to configure global settings.
+    # Register a new global schema.
+    #
+    # == Parameters:
+    # name::
+    #   The name of the schema
+    #   can be `Symbol` or `String`.
+    # &block::
+    #   The block evaluated by the DSL.
+    def schema(name, &block)
+      schema = Saphyr::Schema.new
+      schema.instance_eval &block
+      @schemas[name] = schema
+    end
+
+    # -------------------------------------------------- / DSL
+
+    # Instanciate a registered field type.
+    # @param type [Symbol] The type name use to register the field type
+    # @param opts [Hash] A hash of options to pass to the field type instance.
+    # @return [Field Type Object] An instance of the field type.
+    def instanciate_field_type(type, opts={})
+      klass = @field_types[type]
+      raise Saphyr::Error.new "Unknown field : #{type}" if klass.nil?
+      Object.const_get(klass.name).new opts
+    end
+
+    # Get a specific global schema given his name.
+    # @param name [Symbol] The schema name
+    # @return [Saphyr::Schema]
+    # @raise [Saphyr::Error] If schema does not exists.
+    def get_schema(name)
+      raise Saphyr::Error.new "Unknown schema : #{name}" unless @schemas.key? name
+      @schemas[name]
+    end
+  end
+end
+
+
+#
+# Required files
+#
+require_relative './saphyr/asserts'
+require_relative './saphyr/fields'
+require_relative './saphyr/schema'
+require_relative './saphyr/validator'
+require_relative './saphyr/engine'
+require_relative './saphyr/helpers'
+
+
+#
+# Register default field types.
+#
+Saphyr.register do
+  field_type :string, Saphyr::Fields::StringField
+  field_type :integer, Saphyr::Fields::IntegerField
+  field_type :float, Saphyr::Fields::FloatField
+  field_type :boolean, Saphyr::Fields::BooleanField
+end

data/rdoc/01_Define_Schema.md

@@ -0,0 +1,133 @@
+# How To Define a Schema
+
+A validation schema is basicly a class inheriting
+from `Saphyr::Validator` and using the DSL to describe the schema.
+
+```ruby
+data = {
+  "name" => 'my item',
+}
+
+class ItemValidator < Saphyr::Validator
+  # Declaring the 'name' field into the validation schema:
+
+  field :name,  :string,   min: 5, max: 50
+  #       |        |       |-------------|
+  #       |        |               |
+  #      name     type           options (depending on the type)
+
+  # The field name can be a Sring or Symbol:
+  field 'name',  :string,   min: 5, max: 50
+end
+```
+
+By default the `Saphyr` library provide many field types, like: `:integer`,
+`:float`, `:string`, `:array` ...
+
+_(You can also define your own custom field type, we'll see that later)_
+
+Example of some types:
+
+```ruby
+data = {
+  "id"     => 721,            # Integer: > 0
+  "type"   => 2,              # Integer: possible value 1, 2 or 3
+  "price"  => 27.60,          # Float: > 0
+  "name"   => 'my item',      # String: 5 >= len <= 50
+  "active" => true,           # Boolean
+}
+
+class ItemValidator < Saphyr::Validator
+  field :id,      :integer,  gt: 0
+  field :type,    :integer,  in: [1, 2, 3]
+  field :price,   :float,    gt: 0
+  field :name,    :string,   min: 5, max: 50
+  field :active,  :boolean
+end
+```
+
+Each `Validator` can embed local schemas used to describe the structure of data:
+
+```ruby
+data = {
+  "id"    => 721,
+  "name"  => 'my item',
+  "timestamps" => {
+    "created_at"   => 1669215446,           # Unix timestamp
+    "modified_at"  => 1670943462,
+  }
+}
+
+class ItemValidator < Saphyr::Validator
+  schema :timestamp do
+    field :created_at,   :integer,  gt: 0
+    field :modified_at,  :integer,  gt: 0
+  end
+
+  field :id,          :integer,  gt: 0
+  field :name,        :string,   min: 5, max: 50
+  field :timestamps,  :schema,   name: :timestamp
+end
+```
+
+The `:timestamp` schema is local to the validator and cannot be accessed by other
+validators.
+
+If you need to share a schema between many validators then you can declare it globally:
+
+```ruby
+Saphyr.register do
+  schema :timestamp do
+    field :created_at,   :integer,  gt: 0
+    field :modified_at,  :integer,  gt: 0
+  end
+end
+
+class ItemValidator < Saphyr::Validator
+  # ....
+  field :timestamps,  :schema,  name: :timestamp
+end
+
+class PostValidator < Saphyr::Validator
+  # ....
+  field :timestamps,  :schema,  name: :timestamp
+end
+```
+
+## When root is an array
+
+By default validator root are set to `:object`, but this can be customized.
+
+In this case, only one virtual field must be defined : `:_root_` and it must be of type `:array`
+
+Example with `:of_type` :
+
+```ruby
+data = ['fr', 'en', 'es']
+
+class ItemValidator < Saphyr::Validator
+  root :array
+
+  field :_root_,  :array,  min: 2,  max: 5,  of_type: :string,  opts: {len: 2}
+end
+```
+
+Example with `:of_schema` :
+
+```ruby
+data = [
+  { "id" => 12, "label" => "tag1" },
+  { "id" => 15, "label" => "tag2" },
+]
+
+class ItemValidator < Saphyr::Validator
+  root :array
+
+  schema :tag do
+    field :id,     :integer,  gt: 0
+    field :label,  :string,   min: 2,  max: 30
+  end
+
+  field :_root_,  :array,  min: 2,  max: 4,  of_schema: :tag
+end
+```

data/rdoc/02_Field_Types.md

@@ -0,0 +1,210 @@
+# An Overview of Library Field Types
+
+By default the `Saphyr` library is including many field types.
+
+## Common options
+
+All field type have the common `:required`, `:nullable`.
+
+## String
+
+Authorized options for the `:string` type: `[:eq, :len, :min, :max, :in, :regexp]`
+
+Here is an example with all possible options for `:string` type:
+
+```ruby
+class MyValidator < Saphyr::Validator
+  field :name,      :string
+  field :name,      :string,  eq: 'v1.1'
+  field :name,      :string,  min: 5, max: 50
+  field :name,      :string,  max: 50
+  field :name,      :string,  len: 15
+  field :name,      :string,  len: 15, regexp: /^[a-f0-9]+$/
+  field :name,      :string,  regexp: /^[A-Z0-9]{15}$/
+  field :name,      :string,  in: ['jpg', 'png', 'gif']
+
+
+  field :location,  :string,  required: false, min: 10
+  field :info,      :string,  nullable: true, max: 1024
+end
+```
+
+- If you use `:eq` option then you cannot use any of the other options
+- If you use `:len` option then you cannot use `:min` and `:max` options
+- If you use `:in` option then you cannot use any of the other options
+
+
+## Integer
+
+Authorized options for the `:integer` type: `[:eq, :gt, :gte, :lt, :lte, :in]`
+
+Here is an example with all possible options for `:integer` type:
+
+```ruby
+class MyValidator < Saphyr::Validator
+  field :count,  :integer
+  field :count,  :integer,  eq: 'v1.1'
+  field :count,  :integer,  gt: 0
+  field :count,  :integer,  lt: 50
+  field :count,  :integer,  gte: 5, lte: 50
+  field :count,  :integer,  in: ['jpg', 'png', 'gif']
+
+  field :count,  :integer,  required: false, gte: 10
+  field :count,  :integer,  nullable: true, lte: 1024
+end
+```
+
+- If you use `:eq` option then you cannot use any of the other options
+- If you use `:in` option then you cannot use any of the other options
+
+## Float
+
+Authorized options for the `:float` type: `[:eq, :gt, :gte, :lt, :lte, :in]`
+
+Here is an example with all possible options for `:float` type:
+
+```ruby
+class MyValidator < Saphyr::Validator
+  field :price,  :float
+  field :price,  :float,  eq: 15.1
+  field :price,  :float,  gt: 0
+  field :price,  :float,  lt: 50
+  field :price,  :float,  gte: 5, lte: 50
+  field :price,  :float,  in: ['jpg', 'png', 'gif']
+
+  field :price,  :float,  required: false, gte: 10
+  field :price,  :float,  nullable: true, lte: 1024
+end
+```
+
+- If you use `:eq` option then you cannot use any of the other options
+- If you use `:in` option then you cannot use any of the other options
+
+## Boolean
+
+Authorized options for the `:boolean` type: `[:eq]`
+
+Here is an example with all possible options for `:boolean` type:
+
+```ruby
+class MyValidator < Saphyr::Validator
+  field :active,  :boolean
+  field :active,  :boolean,  eq: true
+  field :active,  :boolean,  eq: false
+
+  field :active,  :boolean,  required: false
+  field :active,  :boolean,  nullable: true
+end
+```
+
+## Array
+
+Authorized options for the `:array` type: `[:len, :min, :max, :of_type, :of_schema, :opts]`
+
+The `:array` type is little bit different than the other types.
+
+The following options `[:len, :min, :max]` are for the array size then you must define
+the type of the array element, this is where `:of_type` and `:of_schema` options
+take place.
+
+- One of this option is required: `:of_type` and `:of_schema`
+- If you use `:len` option then you cannot use `:min`, `:max` options
+
+### Example with `of_type`:
+
+```ruby
+data = {
+  'tags' => ['code', 'ruby', 'json']
+}
+
+class MyValidator < Saphyr::Validator
+  field :tags,  :array,  of_type: :string, opts: {max: 50}
+end
+
+class MyValidator < Saphyr::Validator
+  field :tags,  :array,  min: 1, max: 10, of_type: :string, opts: {max: 50}
+  #                      |-------------|                    |-------------|
+  #                             |                                  |
+  # Size of array must be: 1 >= s <= 10                            |
+  #                                                                |
+  #               This 'opts' are for the element of array, ie: 'string'
+end
+```
+
+### Example with `of_schema`:
+
+- When using `:of_schema` then `:opts` cannot be used
+
+```ruby
+data = {
+  'code' => 'AGF30',
+  'tags' => [
+    {'id' => 234, 'label' => 'ruby'},
+    {'id' => 567, 'label' => 'elixir'}
+  ]
+}
+
+class MyValidator < Saphyr::Validator
+  schema :tag do
+    field :id,     :integer,  gt: 0
+    field :label,  :string,   min: 5, max: 30
+  end
+
+  field :code,  :string,  min: 5,  max: 10
+  field :tags,  :array,   of_schema: :tag
+end
+```
+
+## Schema
+
+The schema field type does not have any option.
+
+It is used to describe the structure hierarchy of the document. The referenced schema
+can local to the validator or global to `Saphyr` library.
+
+To find the schema, we first search it in the validator, if there isn't the named schema in
+the validtor then you search it in the global `Saphyr` registry.  
+_(and if not found an exception is raised)_
+
+Using a local validator schema:
+
+```ruby
+data = {
+  # ....
+  "timestamps": {
+    "created_at": 1669215446,           # Unix timestamp
+    "modified_at": 1670943462
+  }
+}
+
+class ItemValidator < Saphyr::Validator
+  schema :timestamp do
+    field :created_at,   :integer,  gt: 0
+    field :modified_at,  :integer,  gt: 0
+  end
+
+  # ....
+  field :timestamps,  :schema,  name: :timestamp
+end
+```
+
+Using a global schema:
+
+```ruby
+Saphyr.register do
+  schema :timestamp do
+    field :created_at,   :integer,  gt: 0
+    field :modified_at,  :integer,  gt: 0
+  end
+end
+
+class ItemValidator < Saphyr::Validator
+  # ....
+  field :timestamps,  :schema,  name: :timestamp
+end
+
+class PostValidator < Saphyr::Validator
+  # ....
+  field :timestamps,  :schema,  name: :timestamp
+end
+```

data/rdoc/03_Strict_Mode.md

@@ -0,0 +1,80 @@
+# How to Use Strict Mode
+
+By default the library is setup as strict mode, this mean that all fields from schema or
+data must be described.
+
+```ruby
+data = {
+  "name" => 'my item',
+  "info" => 'Lipsum',                             # Not defined in schema
+}
+
+class ItemValidator < Saphyr::Validator
+  field :id,    :integer,  gt: 0                  # Not existing in data
+  field :name,  :string,   min: 5, max: 50
+end
+```
+
+when trying to validate the data, we will get 2 errors:
+
+```ruby
+v = ItemValidator.new
+v.validate data
+puts "Validation : FAILED", "\n"
+Saphyr::Helpers::Format.errors_to_text validator.errors
+```
+
+Output:
+
+```
+Validation : FAILED
+
+path: //id
+  - type: strict_mode:missing_in_data
+  - data: {:field=>"id"}
+  - msg: Missing fields in data
+
+path: //info
+  - type: strict_mode:missing_in_schema
+  - data: {:field=>"info"}
+  - msg: Missing fields in schema
+```
+
+### Disabling the strict mode
+
+```ruby
+class ItemValidator < Saphyr::Validator
+  strict false
+
+  field :id,    :integer,  gt: 0
+  field :name,  :string,   min: 5, max: 50
+end
+```
+
+In this case the validation wil succeed.
+
+### Combining the ':required' option with strict mode
+
+```ruby
+
+class ItemValidator < Saphyr::Validator
+  field :id,    :integer,  gt: 0
+  field :name,  :string,   min: 5, max: 50
+  field :info,  :string,   min: 5, max: 50, required: false
+end
+```
+
+This will ensure that the following data example are both valid:
+
+```ruby
+data1 = {
+  "id" => 235,
+  "name" => 'my item',
+}
+
+data2 = {
+  "id" => 235,
+  "name" => 'my item',
+  "info" => 'Lipsum ...',
+}
+```