schemacop 2.1.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: bb096c541a2c7681a8e46331b266f0e6d93e8946
-  data.tar.gz: 2aead692c31d0eea58cc0bcc5f239cb03edcf322
+SHA256:
+  metadata.gz: e82135ea68e1aa89e4fa729d481bcb6097705e01ba339b9692f7a69d2260f334
+  data.tar.gz: 26358b8124dfd17505830b7e5fb1446c37d34eb9d09533cc3b5f216d9fcccba3
 SHA512:
-  metadata.gz: 156d68d30297a571819a9bc9c4e2ca2fe7e10bfcbe01c79d13393de506a4b27e4e6d1faf07021cda33a05ebcf7b8cefb046efcbf325e3fd248ad272271d5ce6a
-  data.tar.gz: 7057102772faed1465753810c013b3a8ea29f0c78d03128af0f6920dce56492de7835571716ba083a4bb48c9edece13ef0f3e364b25575753937855c2209e6b1
+  metadata.gz: ba3a66136b5a4a756f08bf2f377621bbb047574f68e2e97f9a0d21680040330c44510e8c05b18f39da93d34a96d86a4342495d8bdcb2a0522336743a9cb19d9d
+  data.tar.gz: 8f0901419e3e22952ee289d47cc911f7304d5fa848456e1840255e2a5964a374ce48284927e804c530b22eb61408eb4b516dcbce8da46e969e16e504084469ef

data/CHANGELOG.md

@@ -10,6 +10,64 @@
 ### Changes
 -->
 
+## 2.4.0 (2019-10-28)
+
+### New features
+
+* Add support for default values
+
+* Add support for type casting
+
+### Bug fixes
+
+* Change order of built-in validators so that `Integer` and `String` come
+  *before* `Number` which matches both.
+
+### Changes
+
+## 2.3.2 (2019-09-26)
+
+### New features
+
+* Add ability to return custom error messages from `:check` blocks
+
+## 2.3.1 (2019-08-19)
+
+### Changes
+
+* Make compatible with Rails 6
+
+## 2.3.0 (2017-05-18)
+
+### New features
+
+* Option `strict` for the Type `:object`
+
+  This option, which defaults to true, ensures that instance classes are checked
+  strictly. If set to false, instances of derived classes are also allowed.
+
+### Bug fixes
+
+* Removed '/root' from the paths in the error messages
+
+### Changes
+
+* Added tests for the Collector paths to ensure correct behavior
+* Added symbol Type to the short forms test
+
+## 2.2.0 (2017-05-17)
+
+### Changes
+
+* Handle `ActiveSupport::HashWithIndifferentAccess` objects gracefully when
+  performing the validation. This allows the user to specify the schema using
+  a mixture of symbols and strings, but during the validation of a
+  `HashWithIndifferentAccess` it transparently converts the keys, both in the
+  schema and in the hash, to symbols.
+
+  In the event that a key is defined both in the string and symbol version,
+  Schemacop expects a Ruby hash and will throw a ValidationError otherwise.
+
 ## 2.1.0 (2017-05-16)
 
 ### New features

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Sitrox
+Copyright (c) 2019 Sitrox
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -79,7 +79,7 @@ end
 At runtime:
 
 ```ruby
-my_shema.validate!(
+my_schema.validate!(
   # Your data goes here
 )
 ```
@@ -108,7 +108,7 @@ this:
 s = Schema.new do
   type :integer
   type :hash do
-    req 'name' do
+    req 'present' do
       type :boolean
     end
   end
@@ -124,12 +124,40 @@ 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.
+validation errors (if any) as well as a deep copy of your data with applied
+defaults and castings, whereas `validate!` will accumulate all violations
+and finally throw an exception describing them or, if the validation was
+successful, a deep-copy of your supplied data with defaults and castings
+applied.
 
 For simply querying the validity of some data, use the methods `valid?` or
 `invalid?`.
 
+Examples:
+
+```ruby
+# validate! returns your modified data or throws a validation error
+s = Schema.new do
+  req :foo, default: 42
+end
+s.validate!({}) # => { foo: 42 }
+
+# validate returns a collector
+s = Schema.new do
+  req :foo, default: 42
+end
+
+collector = s.validate({}) 
+collector.valid? # true
+collector.data   # => { foo: 42 }
+
+collector = s.validate({ foo: 'invalid' }) 
+collector.valid?     # false
+collector.data       # => nil
+collector.exceptions # => Validation error
+```
+
+
 ## Schemacop's DSL
 
 In this section, we will ignore [short forms](#short-forms) and explicitly
@@ -182,7 +210,7 @@ Consider a scenario in which you want to have the following rule set:
 The corresponding schema would look as follows:
 
 ```ruby
-Schma.new do
+Schema.new do
   type :integer, if: proc { |data| data.odd? }, max: 15
   type :integer
 end
@@ -203,8 +231,8 @@ 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.
+return true if the data passes the custom check. If it returns false or an error
+message as a string, 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:
@@ -224,10 +252,21 @@ end
 The above Type Line has type `:string` and two options (`min` and `check`). The
 option `min` is supported by the `:string` validator (covered later).
 
+You can also specify a custom error message by returning a string:
+
+
+```ruby
+Schema.new do
+  type :integer, check: proc { |i| i.even? ? true : 'Custom error' }
+end
+```
+
+This will include `Custom error` in the validation error message.
+
 ### 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).
+Inside a Type Line of type `: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!`:
@@ -273,6 +312,36 @@ 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.
 
+#### Handling hashes with indifferent access
+
+Schemacop has special handling for objects of the class
+`ActiveSupport::HashWithIndifferentAccess`: You may specify the keys as symbols
+or strings, and Schemacop will handle the conversion necessary for proper
+validation internally. Note that if you define the same key as string and
+symbol, it will throw a `ValidationError` [exception](#exceptions) when asked to
+validate a hash with indifferent access.
+
+Thus, the following two schema definitions are equivalent when validating a hash
+with indifferent access:
+
+```ruby
+Schema.new do
+  type :hash do
+    req :name do
+      type :string
+    end
+  end
+end
+
+Schema.new do
+  type :hash do
+    req 'name' do
+      type :string
+    end
+  end
+end
+```
+
 ## Types
 
 Types are defined via their validators, which is a class under `validator/`.
@@ -302,11 +371,16 @@ The following types are supported by Schemacop by default:
 
 * `:object` accepts an arbitrary Ruby object (any object if no option is given).
 
-  - 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`).
+  Supported options:
+
+  - `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`).
+
+  - `strict`: Boolean option, defaults to true. If set to false, the validator
+    also allows derived classes of those specified with `classes`.
 
 * `:array` accepts a Ruby Array.
 
@@ -317,7 +391,7 @@ The following types are supported by Schemacop by default:
   - TODO no lookahead for different arrays, see
     validator_array_test#test_multiple_arrays
 
-* `:hash` accepts a Ruby Hash.
+* `:hash` accepts a Ruby Hash or an `ActiveSupport::HashWithIndifferentAccess`.
 
   - accepts a block with an arbitrary number of Field Lines.
 
@@ -443,6 +517,10 @@ Schema.new do
 end
 ```
 
+Note that this does not allow you to specify any options for the hash itself.
+You still need to specify `:hash` as a type if you want to pass any options to
+the hash (i.e. a `default`).
+
 ### Shortform for subtypes
 
 In case of nested arrays, you can group all Type Lines to a single one.
@@ -501,6 +579,149 @@ 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.
 
+## Defaults
+
+Starting from version 2.4.0, Schemacop allows you to define default values at
+any point in your schema. If the validated data contains a nil value, it will be
+substituted by the given default value.
+
+Note that Schemacop never modifies the data you pass to it. If you want to
+benefit from Schemacop-applied defaults, you need to access the cloned, modified
+data returned by `validate` or `validate!`.
+
+Applying defaults is done before validating the substructure and before any type
+casting. The provided default will be validated same as user-supplied data, so
+if your given default does not validate properly, a validation error is thrown.
+Make sure your default values always match the underlying schema.
+
+Defaults can be specified at any point:
+
+
+```ruby
+# Basic usage
+Schema.new do
+  type :string, default: 'Hello World'
+end
+
+# The default given for the first type will match
+Schema.new do
+  type :string, default: 'Hello World' # This will always be applied of no value is supplied
+  type :integer, default: 42
+end
+
+# You can also pass entire hashes or arrays to your defaults
+Schema.new do
+  req :foo, :hash, default: { foo: :bar } do
+    req :foo, :symbol
+  end
+  req :bar, :array, :integer, default: [1, 2, 3]
+end
+
+# Defaults must match the given schema. The following will fail.
+Schema.new do
+  req :foo, default: { bar: :baz } do
+    req :foo
+  end
+end
+```
+
+### Required data points
+
+Note that any *required* validation is done before applying the defaults. If you
+specify a `req` field, it must always be given, no matter if you have specified
+a default or not. Therefore, specifying `req` fields do not make sense in
+conjunction with defaults, as the default is always ignored.
+
+## Type casting
+
+Starting from version 2.4.0, Schemacop allows you to specify type castings that
+can alter the validated data. Consider the following:
+
+```ruby
+s = Schema.new do
+  req :id, :integer, cast: [String]
+end
+
+data = s.validate!(id: '42')
+data # => { id: 42 }
+```
+
+Note that Schemacop never modifies the data you pass to it. If you want to
+benefit from Schemacop-applied castings, you need to access the cloned, modified
+data returned by `validate` or `validate!`.
+
+### Specifying type castings
+
+Type castings can be specified using two forms: Either as a hash or as an array.
+While using an array only allows you to specify the supported source types to be
+casted, using a hash allows you to specify custom casting logic as blocks.
+
+For hashes, the key must be a class and the value must be either `:default` for
+using a built-in caster or a callable object (proc or lambda) that receives the
+value and is supposed to cast it. If the value can't be casted, the proc must
+fail with an exception. The exception message will then be contained in the
+collected validation errors.
+
+Example:
+
+```ruby
+Schema.new do
+  # Pass array to `cast`. This enables casting from String or Float to Integer
+  # using the built-in casters.
+  req: id_1, :integer, cast: [String, Float]
+
+  # Pass hash to `cast`. This enables casting from Float to Integer using the
+  # built-in caster and from String to Integer using a custom callback.
+  req :id_2, :integer, cast: { Float => :default, String => proc { |s| Integer(s) }
+end
+```
+
+### Built-in casters
+
+Schemacop comes with the following casters:
+
+- `String` to `Integer` and `Float`
+- `Float` to `Integer`
+- `Integer` to `Float`
+
+Note that all built-in casters are precise, so the string `foo` will fail with
+an error if casted to an Integer. When casting float values and strings
+containing float values to integers, the decimal places will be discarded
+however.
+
+### Execution order
+
+The casting is done *before* the options `if` and `check` are evaluated.
+Example:
+
+```ruby
+s = Schema.new do
+  type :integer, if: proc { |i| i == 42 }    # 1
+  type :integer, check: proc { |i| i < 3 }   # 2
+  type :string
+end
+
+s.validate!('42')  # 1 will match
+s.validate!('2')   # 2 will match
+s.validate!('234') # 3 will match
+s.validate!(5)     # Will fail, as nothing matches
+```
+
+### Caveats
+
+Casting only works with type definitions that only include one type. For
+instance, the `Numeric` validator includes both `Integer` and `Float`, which
+would made it unclear what to cast a string into:
+
+```ruby
+# This does not work, as it is unclear whether to cast the String into an
+# Integer or a Float.
+type :number, cast: [String]
+```
+
+The same also applies to booleans, as they compound both `TrueClass` and
+`FalseClass`. This may be tackled in future releases.
+
 ## Exceptions
 
 Schemacop will throw one of the following checked exceptions:
@@ -526,6 +747,19 @@ Schemacop will throw one of the following checked exceptions:
 
 * Schemacop does not yet support string regex matching.
 
+## Development
+
+To run tests:
+
+* Check out the source
+
+* Run `bundle install`
+
+* Run `bundle exec rake test` to run all tests
+
+* Run `bundle exec rake test TEST=test/unit/some/file.rb` to run a single test
+  file
+
 ## Contributors
 
 Thanks to [Rubocop](https://github.com/bbatsov/rubocop) for great inspiration
@@ -534,4 +768,4 @@ to [SubGit](http://www.subgit.com/) for their great open source licensing.
 
 ## Copyright
 
-Copyright (c) 2017 Sitrox. See `LICENSE` for further details.
+Copyright (c) 2019 Sitrox. See `LICENSE` for further details.

data/RUBY_VERSION

@@ -1 +1 @@
-ruby-2.3.1-p112
+ruby-2.6.2-p47

data/Rakefile

@@ -14,15 +14,20 @@ task :gemspec do
     spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
     spec.require_paths = ['lib']
 
+    # This lower bound for ActiveSupport is not necessarily true. Schemacop
+    # needs access to ActiveSupport::HashWithIndifferentAccess and expects
+    # behavior of that as in version 5 of ActiveSupport.
+    spec.add_dependency 'activesupport', '>= 4.0'
     spec.add_development_dependency 'bundler', '~> 1.3'
     spec.add_development_dependency 'rake'
     spec.add_development_dependency 'ci_reporter', '~> 2.0'
     spec.add_development_dependency 'ci_reporter_minitest'
-    spec.add_development_dependency 'activesupport'
     spec.add_development_dependency 'haml'
+    spec.add_development_dependency 'colorize'
     spec.add_development_dependency 'yard'
     spec.add_development_dependency 'rubocop', '0.35.1'
     spec.add_development_dependency 'redcarpet'
+    spec.add_development_dependency 'pry'
   end
 
   File.open('schemacop.gemspec', 'w') { |f| f.write(gemspec.to_ruby.strip) }