schemacop 1.0.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 05947ea28e58709d2fbdbb5407b1783fae64ddc8
-  data.tar.gz: f33a9bacaf59ad149f29e809ff3417c86a2fc3c8
+  metadata.gz: 57fd66ee6db934d9c0c2026d2d9dab992d777b01
+  data.tar.gz: 27cda8b63a0962684c0f815145aa5e3fba9f3f6c
 SHA512:
-  metadata.gz: 1a23f0191e0b8954cb9b0debe38067a3fb33921b52023c76b2d68b854d2447db13619f36e3184e705e951ac90a02cfcac71f2d50090a284ffd060ef04228d109
-  data.tar.gz: 5698d5dac2965b9f453715bb66a584cabeff4875b707c1cb3ca4f675cc4f33f5059c3c9fb163c2fb0f6c0833dc7a9e5d7e01862272283fda995aae96609e682f
+  metadata.gz: 9fe380ead2ad62aa1d12171a49e1ca7d3ff3019d3c4839448818e724892e2d611702146cea0f12a5671a04db2ad98345a252da60d5aa8e9412e551112a2eb635
+  data.tar.gz: 3deefe749765e7e662f5878175ec9f1cb3aaebbd892c5d45ba0dd9b044bb6fd12baafd2ee22c13a5dc13e18d226ccd51d214b3830d96d2c15d0efe581c0a40ef

data/.gitignore

@@ -13,4 +13,5 @@ tmtags
 /spec/reports
 /.yardoc
 .idea
-/*.gem
+/*.gem
+tags

data/.rubocop.yml

@@ -1,15 +1,43 @@
 AllCops:
+  TargetRubyVersion: 2.3
+
   Exclude:
     - 'local/**/*'
     - 'vendor/**/*'
     - 'tmp/**/*'
-    - '*.gemspec'
+    - 'target/**/*'
+    - 'log/**/*'
+    - 'db/schema.rb'
+    - 'locale/translations.rb'
+    - 'lib/scratch.rb'
 
   DisplayCopNames: true
 
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/SignalException:
+  EnforcedStyle: only_fail
+
+Style/ConditionalAssignment:
+  Enabled: false
+
+Style/IndentArray:
+  EnforcedStyle: consistent
+
 Metrics/MethodLength:
   Enabled: false
 
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Max: 5
+  CountKeywordArgs: false
+
 Metrics/AbcSize:
   Enabled: False
 
@@ -22,6 +50,12 @@ Metrics/PerceivedComplexity:
 Metrics/LineLength:
   Max: 160
 
+Metrics/BlockNesting:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
 Style/IfUnlessModifier:
   Enabled: false
 
@@ -31,6 +65,9 @@ Style/Documentation:
 Style/RedundantReturn:
   Enabled: false
 
+Style/AsciiComments:
+  Enabled: false
+
 Style/GuardClause:
   Enabled: false
 
@@ -40,3 +77,24 @@ Style/ClassAndModuleChildren:
   SupportedStyles:
     - nested
     - compact
+  # Checks the style of children definitions at classes and modules.
+  #
+  # Basically there are two different styles:
+  #
+  # `nested` - have each child on a separate line
+  #   class Foo
+  #     class Bar
+  #     end
+  #   end
+  #
+  # `compact` - combine definitions as much as possible
+  #   class Foo::Bar
+  #   end
+  #
+  # The compact style is only forced, for classes / modules with one child.
+
+Style/NumericPredicate:
+  Enabled: false
+
+Style/FormatString:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,6 @@
 # Change log
 
+<!--
 ## master (unreleased)
 
 ### New features
@@ -7,6 +8,15 @@
 ### Bug fixes
 
 ### Changes
+-->
+
+## 2.0.0 (2017-05-15)
+
+### Changes
+
+* Completely rewritten the schema specification, breaking backwards
+  compatibility with version 1.x
+* Added tons of unit tests
 
 ## 1.0.1 (2016-06-07)
 

data/README.md

@@ -1,29 +1,49 @@
 [![Build Status](https://travis-ci.org/sitrox/schemacop.svg?branch=master)](https://travis-ci.org/sitrox/schemacop)
 [![Gem Version](https://badge.fury.io/rb/schemacop.svg)](https://badge.fury.io/rb/schemacop)
 
-
 # Schemacop
 
+This is the README for Schemacop version 2, which **breaks backwards
+compatibility** with version 1.
+
 Schemacop validates ruby structures consisting of nested hashes and arrays
-against simple schema definitions.
+against schema definitions described by a simple DSL.
+
+Examples:
 
-Example:
+```ruby
+schema = Schema.new do
+  req :naming, :hash do
+    opt :first_name, :string
+    req :last_name, :string
+  end
+  opt! :age, :integer, min: 18
+  req? :password do
+    type :string, check: proc { |pw| pw.include?('*') }
+    type :integer
+  end
+end
+
+schema.validate!(
+  naming: { first_name: 'John',
+            last_name: 'Doe' },
+  age: 34,
+  password: 'my*pass'
+)
+```
 
 ```ruby
-schema = {
-  type: :hash,
-  hash: {
-    first_name: :string,
-    last_name: :string
-  }
-}
-
-data = {
-  first_name: 'John',
-  last_name: 'Doe'
-}
-
-Schemacop.validate!(schema, data)
+schema2 = Schema.new do
+  req :description,
+      :string,
+      if: proc { |str| str.start_with?('Abstract: ') },
+      max: 35,
+      check: proc { |str| !str.end_with?('.') }
+  req :description, :string, min: 35
+end
+
+schema2.validate!(description: 'Abstract: a short description')
+schema2.validate!(description: 'Since this is no abstract, we expect it to be longer.')
 ```
 
 ## Installation
@@ -34,289 +54,459 @@ To install the **Schemacop** gem:
 $ gem install schemacop
 ```
 
-To install it using `bundler` (recommended for any application), add it
-to your `Gemfile`:
+To install it using `bundler` (recommended for any application), add it to your
+`Gemfile`:
 
 ```ruby
 gem 'schemacop'
 ```
 
-## Basic usage
+## Basics
 
-Schemacop's interface is very simple:
+Since there is no explicit typing in Ruby, it can be hard to make sure that a
+method is recieving exactly the right kind of data it needs. The idea of this
+gem is to define a schema at boot time that will validate the data being passed
+around at runtime. Those two steps look as follows:
+
+At boot time:
 
 ```ruby
-Schemacop.validate!(schema, data)
+my_schema = Schema.new do
+  # Your specification goes here
+end
 ```
 
-It will throw an exception if either the schema is wrong or the given data does
-not comply with the schema. See section *Exceptions* for more information.
+At runtime:
+
+```ruby
+my_shema.validate!(
+  # Your data goes here
+)
+```
 
-## Defining schemas
+`validate!` will fail if the data given to it does not match what was specified
+in the schema.
 
-Schemacop can validate recursive structures of arrays nested into hashes and
-vice-versa. 'Leaf-nodes' can be of any data type, but their internal structure
-is not validated.
+### Type lines vs. Field lines
 
-Schema definitions are always a hash, even if they specify an array. Each level
-of a definition hash has to define a type.
+Schemacop uses a DSL (domain-specific language) to let you describe your
+schemas. We distinguish between two kinds of identifiers:
 
-You can specify any type, but only the types `:hash` and `:array` allow you to
-specify a sub structure.
+- Field Lines: We call a key-value pair (like the contents of a hash) a *field*.
+  A field line typically starts with the keyword `req` (for a required field) or
+  `opt` (for an optional field).
 
-### Defining hashes
+- Type Lines: Those start with the keyword `type` and specify the data type to
+  be accepted with a corresponding symbol (e.g. `:integer` or `:boolean`). You
+  can have multiple Type Lines for a Field Line in order to indicate that the
+  field's value can be of one of the specified types.
 
-Once a level is defined as a hash (`type: :hash`), you can provide the key
-`hash` which in turn specifies the keys contained in that hash:
+If you don't use any short forms, a schema definition would be something like
+this:
 
 ```ruby
-{
-  type: :hash,
-  hash: {
-    first_name: { type: :string },
-    last_name: { type: :string }
-  }
-}
+s = Schema.new do
+  type :integer
+  type :hash do
+    req 'name' do
+      type :boolean
+    end
+  end
+end
 ```
 
-If you don't provide the `:hash` key, the hash won't be validated (other than
-the verification that it really is a hash):
+The above schema would accept either an integer or a hash with exactly one field
+with key 'present' of type String and value of type Boolean (either TrueClass or
+FalseClass).
 
-```ruby
-{ type: :hash }
-```
+We will see Type and Field lines in more detail below.
+
+### `validate` vs `validate!` vs `valid?`
+
+The method `validate` will return a `Collector` object that contains all
+validation errors (if any), whereas `validate!` will accumulate all violations
+and finally throw an exception describing them.
+
+For simply querying the validity of some data, use the methods `valid?` or
+`invalid?`.
+
+## Schemacop's DSL
+
+In this section, we will ignore [short forms](#short-forms) and explicitly
+write out everything.
+
+Inside the block given at the schema instantiation (`Schema.new do ... end`),
+the following kinds of method calls are allowed (where the outermost must be a
+Type Line):
 
-Hash definitions can be nested deeply:
+### Type Line
+
+A Type Line always starts with the identifier `type` and specifies a possible
+data type for a given field (if inside a Field Line) or the given data structure
+(if directly below the schema instantiation).
+
+Type Lines are generally of the form
 
 ```ruby
-{
-  type: :hash,
-  hash: {
-    name: {
-      type: :hash,
-      hash: {
-        first_name: { type: :string },
-        last_name: { type: :string }
-      }
-    }
-  }
-}
+type :my_type, option_1: value_1, ..., option_n: value_n
 ```
 
-### Defining arrays
+where `:my_type` is a supported symbol (see section [Types](#types) below for
+supported types).
+
+#### General options
+
+Some types support specific options that allow additional checks on the nature
+of the data (such as the `min` option for type `:number`). The following options
+are supported by all types:
+
+##### Option `if`
+
+This option takes a proc (or a lambda) as value. The proc will be called when
+checking whether or not the data being analyzed fits a certain type. The data is
+given to the proc, which has to return either true or false. If it returns true,
+the type of the given data is considered correct and the data will be validated
+if further options are given.
+
+Note that the proc in `if` will only get called if the type (`:my_type` from
+above) fits the data already. You can use the option `if` in order to say: "Even
+if the data is of type `:my_type`, I consider it having the wrong type if my
+proc returns false."
+
+Consider a scenario in which you want to have the following rule set:
+
+- Only integers may be given
+- Odd integers must be no larger than 15
+- No limitations for even integers
 
-When you define a level as an array (`type: :array`), you can provide further
-specification of the array's contents uby supplying the key `:array`:
+The corresponding schema would look as follows:
 
 ```ruby
-{
-  type: :array,
-  array: {
-    type: :string
-  }
-}
+Schma.new do
+  type :integer, if: proc { |data| data.odd? }, max: 15
+  type :integer
+end
 ```
 
-This example would define an array of strings.
+Here, the first type line will only accept odd numbers and the option `max: 15`
+provided by the `:integer` validator will discard numbers higher than 15.
 
-Arrays can nest hashes and vice-versa:
+Since the first line only accepts odd numbers, it doesn't apply for even numbers
+(due to the proc given to `if` they are considered to be of the wrong type) and
+control falls through to the second type line accepting any integer.
+
+##### Option `check`
+
+This option allows you to perform arbitrary custom checks for a given data type.
+Just like `if`, `check` takes a proc or lambda as a value, but it runs *after*
+the type checking, meaning that it only gets executed if the data has the right
+type and the proc in `if` (if any) has returned true.
+
+The proc passed to the `check` option is given the data being analyzed. It is to
+return true if the data passes the custom check. If it returns false, Schemacop
+considers the data to be invalid.
+
+The following example illustrates the use of the option `check`: Consider a
+scenario in which you want the following rule set:
+
+- Data must be of type String
+- The string must be longer than 5 characters
+- The second character must be an 'r'
+
+The corresponding schema would look as follows:
 
 ```ruby
-{
-  type: :array,
-  array: {
-    type: :string
-  }
-}
+Schema.new do
+  type :string, min: 5, check: proc { |data| data[1] == 'r'}
+end
 ```
 
-If you don't provide the `:array` key, the array contents won't be validated:
+The above Type Line has type `:string` and two options (`min` and `check`). The
+option `min` is supported by the `:string` validator (covered later).
+
+### Field Line
+
+Inside a Type Line of type `:hash` or `Hash`, you may specify an arbitrary
+number of field lines (one for each key-value pair you want to be in the hash).
+
+Field Lines start with one of the following six identifiers: `req`, `req?`,
+`req!`, `opt`, `opt?` or `opt!`:
+
+- The suffix `-!` means that the field must not be nil.
+
+- The suffix `-?` means that the field may be nil.
+
+- The prefix `req-` denotes a required field (validation fails if the given data
+  hash doesn't define it). `req` is a shorthand notation for `req!` (meaning
+  that by default, a required field cannot be nil).
+
+- The prefix `opt-` denotes an optional field. `opt` is a shorthand notation for
+  `opt?` (meaning that by default, an optional field may be nil).
+
+To summarize:
+
+- `req` or `req!`: required and non-nil
+- `req?`: required but may be nil
+- `opt` or `opt?`: optional and may be nil
+- `opt!`: optional but non-nil
+
+You then pass a block with a single or multiple Type Lines to the field.
+
+Example: The following schema defines a hash that has a required non-nil field
+of type String under the key `:name` (of type Symbol) and an optional but
+non-nil field of type Integer or Date under the key `:age`.
 
 ```ruby
-{ type: :array }
+Schema.new do
+  type :hash do
+    req :name do
+      type :string
+    end
+    opt! :age do
+      type :integer
+      type :object, classes: Date
+    end
+  end
+end
 ```
 
+You might find the notation cumbersome, and you'd be right to say so. Luckily
+there are plenty of short forms available which we will see below.
+
 ## Types
 
-For each level in your schema, you can specify the type in one of the following
-manors:
+The following types are supported by Schemacop:
+<!-- TODO: Test the following statement: (you can easily extend them by writing
+another `your_validator.rb` class under `validator/`): -->
+
+* `:boolean` accepts a Ruby TrueClass or FalseClass instance.
+
+* `:integer` accepts a Ruby Integer.
+
+  - supported options: `min`, `max` (lower / upper bound)
+
+* `:float` accepts a Ruby Float.
+
+  - supported options: `min`, `max` (lower / upper bound)
+
+* `:number` accepts a Ruby Integer or Float.
+
+  - supported options: `min`, `max` (lower / upper bound)
 
-- A ruby class:
+* `:string` accepts a Ruby String.
 
-  ```ruby
-  { type: String }
-  ```
+  - supported options: `min`, `max` (bounds for string length)
 
-- A type alias (see {Schemacop::Validator::TYPE_ALIASES} for a full list of
-  available type aliasses):
+* `:object` accepts an arbitrary Ruby object (any object if no option is given).
 
-  ```ruby
-  { type: :boolean }
-  ```
+  - supported option: `classes`: Ruby class (or an array of them) that will be
+    the only recognized filters. Unlike other options, this one affects not the
+    validation but the type recognition, meaning that you can have multiple Type
+    Lines with different `classes` option for the same field, each having its
+    own validation (e.g. through the option `check`).
 
-- A list of ruby classes or type aliases:
+* `:array` accepts a Ruby Array.
 
-  ```ruby
-  { type: [String, :integer] }
-  ```
+  - supported options: `min`, `max` (bounds for array size) and `nil`: TODO
 
-  When specifying more than one type, it is validated that the given data
-  structure matches *one* of the given types.
+  - accepts a block with an arbitrary number of Type Lines.
 
-  If you specify both `:array` and `:hash` in such a type array, you can provide
-  a specification for both `array` and `hash` types:
+  - TODO no lookahead for different arrays, see
+    validator_array_test#test_multiple_arrays
 
-  ```ruby
-  {
-    type: [:array, :hash],
-    array: {
-      type: :string
-    },
-    hash: {
-      first_name: :string
-    }
-  }
-  ```
+* `:hash` accepts a Ruby Hash.
 
-  It will then determine which specification to use based on the actual data.
+  - accepts a block with an arbitrary number of Field Lines.
 
-## Null and required
+* `:nil`: accepts a Ruby NilClass instance. If you want to allow `nil` as a
+  value in a field, see above for the usage of the suffixes `-!` and `-?` for
+  Field Lines.
 
-Using the optional parameters `required` and `null`, you can control whether a
-specific substructure must be provided (`required`) and if it can be `nil`
-(`null`).
+All types support the options `if` and `check` (see the section about Type Lines
+above).
 
-These two parameters can be combined in any way.
+## Short forms
 
-### Required validation
+For convenience, the following short forms may be used (and combined if
+possible).
 
-When validating with `required = false`, it means that the whole key can be
-omitted. As an example:
+### Passing a type to a Field Line or schema
+
+Instead of adding a Type Line in the block of a Field Line, you can omit `do
+type ... end` and directly write the type after the key of the field.
+
+Note that when using this short form, you may not give a block to the Field
+Line.
 
 ```ruby
-# Successfully validates data hash: {}
-{
-  type: :hash,
-  hash: {
-    first_name: { type: :string, required: false }
-  }
-}
+# Long form
+req :name do
+  type :string, min: 2, max: 5
+end
+
+# Short form
+req :name, :string, min: 2, max: 5
 ```
 
-### Null validation
+This means that the value under the key `:name` of type Symbol must be a String
+containing 2 to 5 characters.
 
-When validating with `null = true`, the key must still be present, but it can
-also be `nil`.
+The short form also works in the schema instantiation:
 
 ```ruby
-# Successfully validates data hash: { first_name: nil }
-{
-  type: :hash,
-  hash: {
-    first_name: { type: :string, null: false }
-  }
-}
+# Long form
+Schema.new do
+  type :string, min: 2, max: 5
+end
+
+# Short form
+Schema.new(:string, min: 2, max: 5)
 ```
 
-## Allowed values
+This means that the data given to the schema must be a String that is between 2
+and 5 characters long.
+
+### Passing multiple types at once
 
-For any level, you can optionally specify an array of values that are allowed.
+You can specify several types at once by putting them in an array.
 
-For example:
+Note that when using this short form, you may not give any options.
 
 ```ruby
-{
-  type: :hash,
-  hash: {
-    category: { type: :integer, allowed_values: [1, 2, 3] }
-  }
-}
+# Long form
+opt! :age do
+  type :string
+  type :integer
+  type :boolean
+end
+
+# Short form
+opt! :age do
+  type [:string, :integer, :boolean]
+end
 ```
 
-## Shortcuts
+Combined with previous short form:
 
-### Type shortcut
+```ruby
+opt! :age, [:string, :integer, :boolean]
+```
 
-If you'd just like to define a type for a level but don't need to supply any
-additional information, you can just skip passing an extra hash and just pass
-the type instead.
+This also works in the schema instantiation:
 
-For example, the following
+```ruby
+Schema.new([:string, :integer, :boolean])
+```
+
+This means that the schema will validate any data of type String, Integer,
+TrueClass or FalseClass.
+
+### Omitting the Type Line in a Field Line
+
+If you don't specify the type of a field, it will default to `:object` with no
+options, meaning that the field will accept any kind of data:
 
 ```ruby
-{
-  type: :array,
-  array: {
-    type: :string
-  }
-}
+# Long form
+req? :child do
+  type :object
+end
+
+# Short form
+req? :child
 ```
 
-can also be written as:
+### Omitting the Type Line in schema instantiation
+
+If you don't give a Type Line to a schema, it will accept data of type Hash.
+Therefore, if you validate Hashes only, you can omit the Type Line and directly
+write Field Lines in the schema instantiation:
 
 ```ruby
-{
-  type: :array,
-  array: :string
-}
+# Long form
+Schema.new do
+  type :hash do
+    req :name do
+      # ...
+    end
+  end
+end
+
+# Short form
+Schema.new do
+  req :name do
+    # ...
+  end
+end
 ```
 
-### Quick hash and array
+### Shortform for subtypes
 
-When specifying a level as hash or array and you're further specifying the
-hashe's fields or the array's content types, you can omit the `type` key.
+In case of nested arrays, you can group all Type Lines to a single one.
 
-For example, the following
+Note that any options or block passed to the grouped Type Line will be given to
+the innermost (last) type.
 
 ```ruby
-{
-  type: :array,
-  array: {
-    type: :string
-  }
-}
+# Long form
+type :array do
+  type :integer, min: 3
+end
+
+# Short form
+type :array, :integer, min: 3
 ```
 
-can also be written as:
+A more complex example:
+
+Long form:
 
 ```ruby
-{
-  array: :string
-}
+Schema.new do
+  type :hash do
+    req 'nutrition' do
+      type :array do
+        type :array do
+          type :hash, check: proc { |h| h.member?(:food) || h.member?(:drink) } do
+            opt! :food do
+              type :object
+            end
+            opt! :drink do
+              type :object
+            end
+          end
+        end
+      end
+    end
+  end
+end
 ```
 
-## Example schema
+Short form (with this short form others from above):
 
 ```ruby
-{
-  hash: {
-    id: [Integer, String],
-    name: :string,
-    meta: {
-      hash: {
-        groups: { array: :integer },
-        birthday: Date,
-        comment: {
-          type: :string,
-          required: false,
-          null: true
-        },
-        ar_object: User
-      }
-    }
-  },
-}
+Schema.new do
+  req 'nutrition', :array, :array, :hash, check: proc { |h| h.member?(:food) || h.member?(:drink) } do
+    opt! :food
+    opt! :drink
+  end
+end
 ```
 
+This example accepts a hash with exactly one String key 'nutrition' with value
+of type Array with children of type Array with children of type Hash in which at
+least one of the Symbol keys `:food` and `:drink` (with any non-nil value type)
+is present.
+
 ## Exceptions
 
 Schemacop will throw one of the following checked exceptions:
 
-* {Schemacop::Exceptions::InvalidSchema}
+* {Schemacop::Exceptions::InvalidSchemaError}
 
   This exception is thrown when the given schema definition format is invalid.
 
-* {Schemacop::Exceptions::Validation}
+* {Schemacop::Exceptions::ValidationError}
 
   This exception is thrown when the given data does not comply with the given
   schema definition.
@@ -336,9 +526,9 @@ Schemacop will throw one of the following checked exceptions:
 ## Contributors
 
 Thanks to [Rubocop](https://github.com/bbatsov/rubocop) for great inspiration
-concerning their name and the structure of their README file. And special thanks to
-[SubGit](http://www.subgit.com/) for their great open source licensing.
+concerning their name and the structure of their README file. And special thanks
+to [SubGit](http://www.subgit.com/) for their great open source licensing.
 
 ## Copyright
 
-Copyright (c) 2016 Sitrox. See `LICENSE` for further details.
+Copyright (c) 2017 Sitrox. See `LICENSE` for further details.