README.md in ratatouille-1.2.6 vs README.md in ratatouille-1.3.0
- old
+ new
@@ -3,10 +3,11 @@
DSL for validation of complex Hashes
## Travis CI Status:
[](http://travis-ci.org/CITguy/ratatouille)
+
## Installation
Add this line to your application's Gemfile:
gem 'ratatouille'
@@ -19,10 +20,15 @@
$ gem install ratatouille
+## Information
+
+Specific uses and syntax can be found in the documentation of each module. The information defined
+here is common information amongst the entirety of the ratatouille gem.
+
## Blocks
All of the given methods accept a block for validation and will not progress into the block if the core method logic does not validate.
However, some methods may be used without a block and validation will progress whether or not the method logic validates.
@@ -33,231 +39,80 @@
This will change when using *given\_key*.
### name
-Within a block, the name method provides the name of the scope. This can be used in your custom validation messages.
+Within a block, the **name** method provides the name of the scope.
+This can be used in your custom validation messages and is already prepended to the beginning
+of every validation error.
-## Usage
+## Custom Validation
-All of the following methods perform validation on the *ratifiable\_object* defined in scope of the block.
+**Return to this section after reading the remaining sections.**
+Custom validation can take place using the following methods to generate custom validation logic that cannot be satisfied with the existing methods.
-### is\_a?
+You should use the **validation\_error** method to add your own errors to the Ratifier object.
-Method to check if ratifiable\_object matches given class. Will not validate without a given class.
+### validation\_error
-### given\_key
+Used to insert validation error message into the Ratifier object.
-This method is used to scope its given block to the key value. Useful to reduce the need to explicitly namespace nested keys in *ratifiable\_object*.
+* Scope name prepended to every validation error
-* **This method doesn't perform any validation and must be used with a block to get any use out of it.**
-* Changes *ratifiable\_object* to *key value* (original scope will return on block exit)
-
#### Syntax
-```ruby
- given_key(:foo) do
- # validation for ratifiable_object[:foo]
- end
-```
+It is also possible to set the context of an error by passing in a second argument.
+However, it defaults to the root of the current ratifiable\_object ('/').
-#### Example
-
-See **choice\_of** for an example.
-
-
-### choice\_of
-
-Meant to be used to validate that X number of given key choices exist in the Hash.
-
-* Number of Choices must be less than size of key choice array
-* Can be used without a block
-* Works well with **given\_key()**.
-
-
-#### Syntax
-
```ruby
- choice_of(number_of_choices, key_choice_array) do
- # Validation provided number of choices is satisfied
- end
+ validation_error("This is an error")
+ validation_error("This is an error", "current_context")
```
-#### Example
-```ruby
- r = ratify({:foo => "bar", :bar => "biz"}) do
- choice_of(1, :foo, :bar) do
- # Validation, provided :foo OR :bar exists
- end
- end
- r.valid? #=> false (:foo OR :bar must be defined, NOT BOTH)
+## Universal Options
- r = ratify({:foo => "bar", :bar => "biz"}) do
- choice_of(2, :foo, :bar, :biz) do
- # Validation, provided 2 of the following exist: :foo, :bar, :biz
+### :unwrap\_block
- given_key(:foo) do
- # in context of ratifiable_object[:foo]
- end
+This optional key, when set to true, will skip the wrapped validation provided in the called
+method and run the validations contained in its given block (if any). This is useful
+if previous validation results dictate further validation logic.
- given_key(:bar) do
- # in context of ratifiable_object[:bar]
- end
- end
- end
- r.valid? #=> true (a choice of 2 items from [:foo, :bar, :biz] is satisfied)
-
- r = ratify({:foo => "bar", :bar => "biz"}) do
- choice_of(2, :foo, :bar) do
- # Validation ...
- end
- end
- r.valid? #=> false (you might as well use required_keys)
-```
-
-
-### required\_keys
-
-Used to ensure that the list of keys exist in the Hash.
-
-* Block is optional
-
-
-#### Syntax
-
-```ruby
- # Validate that the keys exist and perform validation if they do
- required_keys(:foo, :bar) do
- # Validation provided that :foo and :bar exist
- end
-
- # Validate that the keys exist
- required_keys(:foo, :bar)
-```
-
-
#### Example
-```ruby
- r = ratify({:foo => "bar", :bar => "biz"}) do
- required_keys(:foo, :bar)
- end
- r.valid? #=> true
+*A choice of :bar or :biz is required only if :foo is 'green',
+otherwise :bar and :biz should be validated if they are present.*
- r = ratify({:foo => "bar"}) do
- required_keys(:foo, :bar)
- end
- r.valid? #=> false
-```
-
-
-
-### required\_key
-
-Used to ensure given key exists in the Hash.
-
-* Eliminates the need to perform "given\_key" methods within a "required\_keys" block.
-* Evaluates an optional block in context of key value (same as given\_key)
-
-
-#### Syntax
-
```ruby
- # Validate that the keys exist and perform validation if they do
+ ratify({:foo => "red"}) do
required_key(:foo) do
- # Validation provided that :foo exists in Hash
+ unwrap_choice = true
+ unwrap_choice = false if ratifiable_object == 'green'
end
- # Validate that the keys exist
- required_key(:foo)
-```
-
-
-
-### is\_empty
-
-* Self-explanatory
-* Block is optional
-
-```ruby
- r = ratify({:foo => "bar"}) do
- is_empty # validation continues
- is_empty do
- # validation in block is never performed
+ # Because :foo is 'red', choice_of logic will be ignored and the block will be entered.
+ choice_of(:key_list => [:bar, :biz], :unwrap_block => unwrap_choice) do
+ given_key(:bar) do
+ # :bar validation
end
- end
- r.valid? #=> false
-
- r = ratify({}) do
- is_empty # validation continues even if not empty
- is_empty do
- # validation continues only if ratifiable_object is empty
+ given_key(:biz) do
+ # :biz validation
end
end
- r.valid? #=> true
-```
-
-### is\_not\_empty
-
-* Self-explanatory
-* Block is optional
-
-```ruby
- r = ratify({:foo => "bar"}) do
- is_not_empty # validation continues even if empty
- is_not_empty do
- # validation continues unless ratifiable_object is empty
- end
- end
- r.valid? #=> true
-
- r = ratify({}) do
- is_not_empty # validation continues
- is_not_empty do
- # validation in block is never performed
- end
- end
- r.valid? #=> false
+ # If :foo were 'green', choice_of logic would be performed before entering the block.
+ end
```
-## Custom Validation
-
-**Return to this section after reading the remaining sections.**
-
-Custom validation can take place using the following methods to generate custom validation logic that cannot be satisfied with the existing methods.
-
-You should use the **validation\_error** method to add your own errors to the Ratifier object.
-
-
-### validation\_error
-
-Used to insert validation error message into the Ratifier object.
-
-* Scope name prepended to every validation error
-
-
-#### Syntax
-
-It is also possible to set the context of an error by passing in a second argument. However, it defaults to the root of the current ratifiable\_object ('/').
-
-```ruby
- validation_error("This is an error")
- validation_error("This is an error", "current_context")
-```
-
-
-
## Advanced Example
```ruby
include Ratatouille
r = ratify({:foo => {:bar => {:biz => "bang"}}}) do
@@ -274,9 +129,11 @@
end
end
end
r.valid? # => false
```
+
+
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)