json-spec 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dd9a98802b2e9d9d82dff4d9fd8b6b174812f195
+  data.tar.gz: 071fdf0b74f43cae45e079b089a14fd0fc2af5fc
+SHA512:
+  metadata.gz: 797adfabb1a8111259da2fdc097d47f68914414a07a8fdc760cd5aaad744e91bdece18dbf735a2e78124361c57779b3d3b127ba5deeaeb51fae5c0e8038248d2
+  data.tar.gz: 59e894989cc21acb4abdc0feb9bcee8cfd4ef892111e6d39195ed0891ae543fbb564b499e57c73cbc1e995c8a4d60e95f31b10d5d1b153e2c5e47650eb6307e9

data/.gitignore

@@ -0,0 +1,3 @@
+Gemfile.lock
+
+coverage

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "cachivache/stuff-library"]
+	path = cachivache/stuff-library
+	url = git@github.com:cabeza-de-termo/stuff-library.git

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in json-spec.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Martin Rubi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,960 @@
+# CabezaDeTermo::JsonSpec
+
+A framework to declare expectations and verify that a json object satisfies those expectations. You can use this expectations to validate jsons you send or receive in your application, or to test your API with unit tests.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'json-spec'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install json-spec
+
+## Usage
+
+If you want to read the supported expressions and expectations by `json-spec`, see the [API documentation](api_documentation.md).
+
+If you want to jump to a running example, see the [full example](examples/example-7-full-example.rb).
+
+Otherwise walk through this tutorial where we will be writting a spec to validate a partial specification of the `composer.json` used by a [dyslexic cousin](https://github.com/cabeza-de-termo/php-json-spec) of this project:
+
+```json
+{
+	"name": "cabeza-de-termo/json-spec",
+	"type": "library",
+	"description": "A framework to declare expectations and verify that a json object complies with those expectations. You can use this json expectations to validate jsons you send or receive in your application, or to test your API with unit tests.",
+	"keywords": ["json", "assertions", "expectations", "validation", "phpunit"],
+	"homepage": "https://github.com/cabeza-de-termo/php-json-spec",
+	"license": "MIT",
+	"authors": [
+		{
+			"name": "Martin Rubi",
+			"email": "martin.rubi@martinrubi.com"
+		}
+	],
+	"require": {
+		"php": ">=5.4.0"
+	},
+	"require-dev": {
+		"phpunit/phpunit": "^4",
+		"phpdocumentor/phpdocumentor": "2.*"
+	},
+	"autoload": {
+		"psr-4": {
+			"CabezaDeTermo\\JsonSpec\\": ["src/"],
+			"CabezaDeTermo\\JsonSpec\\Tests\\": ["tests/"]
+		}
+	}
+}
+```
+
+## Starting with a simple validation
+
+We will declare each expression we expect the `composer.json` to have, and for each expression we will declare expectations on it:
+
+```ruby
+require 'cabeza-de-termo/json-spec/json-spec'
+
+valid_licenses = 
+	['Apache-2.0', 'BSD-2-Clause', 'BSD-3-Clause', 
+	 'BSD-4-Clause' ,'GPL-2.0', 'GPL-2.0+', 'GPL-3.0', 
+	 'GPL-3.0+', 'LGPL-2.1', 'LGPL-2.1+', 'LGPL-3.0',
+	 'LGPL-3.0+', 'MIT']
+
+json_spec = CabezaDeTermo::JsonSpec::JsonSpec.new do
+	expect_an(:object) do
+		expect('name') .to_be_defined .not_blank
+		expect('type') .to_be_defined .not_blank
+		expect('description') .to_be_defined .not_blank
+		expect('keywords') .to_be_a(:list) .can_be_absent .not_empty do
+			each do
+				expect_a(:scalar) .not_blank
+			end
+		end
+		expect('homepage') .to_be_url
+		expect('license') .to_be_defined .to_be_in(valid_licenses)
+		expect('authors') .to_be_a(:list) .to_be_defined .not_empty do
+			each do
+				expect_an(:object) do
+					expect('name') .to_be_defined .not_blank
+					expect('email') .to_be_defined .to_be_email
+				end
+			end
+		end
+		expect('require') .to_be_an(:object) .can_be_absent
+		expect('require-dev') .to_be_an(:object) .can_be_absent
+		expect('autoload') .to_be_an(:object) .to_be_defined do
+			expect('psr-0') .to_be_an(:object) .can_be_absent
+			expect('psr-4') .to_be_an(:object) .can_be_absent
+		end
+	end
+end
+```
+
+That's it. Now we can validate a json string by running:
+
+```ruby
+validator = json_spec.validate_string json_string
+
+puts validator.errors
+puts validator.unexpected_fields
+```
+
+If you want to run this example, see the [first example](examples/example-1-simple.rb) in the `examples/` folder.
+
+## Defining default expectations for each expression
+
+One thing you may have noticed about the previous example is that it includes a lot of repeated `.to_be_defined` expectations on many fields. It would be easier if we could just state that `.to_be_defined` is expected for every field.
+
+We can do that in two different ways.
+
+If we want to declare default expectations at a global scope, i.e., for every expression used in any place, then we can do:
+
+```ruby
+CabezaDeTermo::JsonSpec::ExpectationsLibrary.define do
+	default_expectations do
+		for_every_field do
+			to_be_defined
+			to_be_string
+			not_blank
+			...
+		end
+	end
+end
+```
+
+If we want to declare default expectations for a json_spec only then we can do:
+
+```ruby
+json_spec.define do
+	default_expectations do
+		for_every_field do
+			to_be_defined
+			to_be_string
+			not_blank
+			...
+		end
+	end
+end
+```
+
+We can declare default expectations at any scope for different expressions:
+
+```ruby
+default_expectations do
+	for_every_object do
+		...
+	end
+
+	for_every_list do
+		...
+	end
+
+	for_every_scalar do
+		...
+	end
+
+	for_every_field do
+		...
+	end
+end
+```
+
+If we want to get rid of the current default expressions, in the corresponding scope we declare any of:
+
+```ruby
+default_expectations do
+	drop_all_expectations
+	drop_expectations_for(:objects)
+	drop_expectations_for(:lists)
+	drop_expectations_for(:fields)
+	drop_expectations_for(:scalars)
+end
+```
+
+You can see which default expectations are used by the framework in the [DefaultLibraryInitializer](lib/cabeza-de-termo/json-spec/expectations-library/initializers/default-library-initializer.rb) class.
+
+So, back to our example, now the validation looks like:
+
+```ruby
+CabezaDeTermo::JsonSpec::ExpectationsLibrary.define do
+	default_expectations do
+		for_every_field do
+			to_be_defined
+		end
+	end
+end
+
+valid_licenses = 
+	['Apache-2.0', 'BSD-2-Clause', 'BSD-3-Clause', 
+	 'BSD-4-Clause' ,'GPL-2.0', 'GPL-2.0+', 'GPL-3.0', 
+	 'GPL-3.0+', 'LGPL-2.1', 'LGPL-2.1+', 'LGPL-3.0',
+	 'LGPL-3.0+', 'MIT']
+
+json_spec = CabezaDeTermo::JsonSpec::JsonSpec.new do
+	expect_an(:object) do
+		expect('name') .not_blank
+		expect('type') .not_blank
+		expect('description') .not_blank
+		expect('keywords') .to_be_a(:list) .can_be_absent .not_empty do
+			each do
+				expect(:scalar) .not_blank
+			end
+		end
+		expect('homepage') .to_be_url
+		expect('license') .to_be_in(valid_licenses)
+		expect('authors') .to_be_a(:list) .not_empty do
+			each do
+				expect_an(:object) do
+					expect('name') .not_blank
+					expect('email') .to_be_email
+				end
+			end
+		end
+		expect('require') .to_be_an(:object) .can_be_absent
+		expect('require-dev') .to_be_an(:object) .can_be_absent
+		expect('autoload') .to_be_an(:object) do
+			expect('psr-0') .to_be_an(:object) .can_be_absent
+			expect('psr-4') .to_be_an(:object) .can_be_absent
+		end
+	end
+end
+```
+
+If you want to run this example, see the [second example](examples/example-2-default-expectations.rb) in the `examples/` folder.
+
+## Declaring expectations for fields not known in advance.
+
+If you run the previous example, you may notice that it outputs the folowing:
+
+```
+- Failed expectations: 0
+
+- Unexpected fields: 5
+	Field: '@.require'	 message: "An unexpected 'php' field was found."
+	Field: '@.require-dev'	 message: "An unexpected 'phpunit/phpunit' field was found."
+	Field: '@.require-dev'	 message: "An unexpected 'phpdocumentor/phpdocumentor' field was found."
+	Field: '@.autoload.psr-4'	 message: "An unexpected 'CabezaDeTermoJsonSpec\' field was found."
+	Field: '@.autoload.psr-4'	 message: "An unexpected 'CabezaDeTermo\JsonSpec\Tests\' field was found."
+```
+
+That is because the `composer.json` has the following sections:
+
+```json
+"require": {
+	"php": ">=5.4.0"
+},
+"require-dev": {
+	"phpunit/phpunit": "^4",
+    "phpdocumentor/phpdocumentor": "2.*"
+}
+
+...
+
+	"psr-4": {
+		"CabezaDeTermoJsonSpec\\\\": ["src/"],
+		"CabezaDeTermo\\\\JsonSpec\\\\Tests\\\\": ["tests/"]
+	}
+```
+
+with fields with names that we don't know in advance. They can be anything, as long as they comply with what `composer.json` expects. So we also want to declare expectations on unkown fields.
+
+To do that, we use the `:each_field` expectation:
+
+```ruby
+expect('require') .to_be_an(:object) .can_be_absent do
+	each_field do
+		expect_name .not_blank
+		expect_a(:scalar) .not_blank
+	end
+end
+...
+expect('psr-0') .to_be_an(:object) .can_be_absent do
+	each_field do
+		expect_name
+
+		expect_a(:list) .not_empty do
+			each do
+				expect_a(:scalar) .not_blank
+			end
+		end
+	end
+end
+```
+
+If you want to run this example, see the [third example](examples/example-3-each-field.rb) in the `examples/` folder.
+
+
+## Refactoring the expectations
+
+So by now we have the following expectations:
+
+```ruby
+json_spec = CabezaDeTermo::JsonSpec::JsonSpec.new do
+	expect_an(:object) do
+		expect('name') .not_blank
+		expect('type') .not_blank
+		expect('description') .not_blank
+
+		expect('keywords') .to_be_a(:list) .can_be_absent .not_empty do
+			each do
+				expect_a(:scalar) .not_blank
+			end
+		end
+
+		expect('homepage') .to_be_url
+		expect('license') .to_be_in(valid_licenses)
+
+		expect('authors') .to_be_a(:list) .not_empty do
+			each do
+				expect_an(:object) do
+					expect('name') .not_blank
+					expect('email') .to_be_email
+				end
+			end
+		end
+
+		expect('require') .to_be_an(:object) .can_be_absent do
+			each_field do
+				expect_name .not_blank
+				expect_a(:scalar) .not_blank
+			end
+		end
+
+		expect('require-dev') .to_be_an(:object) .can_be_absent do
+			each_field do
+				expect_name.not_blank
+				expect_a(:scalar) .not_blank
+			end
+		end
+
+		expect('autoload') .to_be_an(:object) do
+			expect('psr-0') .to_be_an(:object) .can_be_absent do
+				each_field do
+					expect_name
+
+					expect_a(:list) .not_empty do
+						each do
+							expect_a(:scalar) .not_blank
+						end
+					end
+				end
+			end
+
+			expect('psr-4') .to_be_an(:object) .can_be_absent do
+				each_field do
+					expect_name
+
+					expect_a(:list) .not_empty do
+						each do
+							expect_a(:scalar) .not_blank
+						end
+					end
+				end
+			end
+
+			expect('classmap') .to_be_a(:list) .can_be_absent
+
+			expect('files') .to_be_a(:list) .can_be_absent
+		end
+	end
+end
+```
+
+This have several problems. One is its extension. The spec just got too long. Second, now it is a structure of expectations on json expressions that lacks of some intention revealing names about the expressions. For instance, this section
+
+```ruby
+expect_an(:object) do
+	expect('name') .not_blank
+	expect('email') .to_be_email
+end
+```
+
+refers to an author, but if we only look at it without its parent expression, we don't know that.
+And third, and worst than the previous reasons, is that we are duplicating expectations for `require` and `require-dev`.
+
+So it would be nice to be able to organize the expectations somehow.
+
+We can put expectations in methods, and then call those methods from within the json_spec. This methods can be in any class, but we are going to create a `ComposerJson` class to keep the `composer.json` expectations in one place.
+So now we have the class
+
+```ruby
+class ComposerJson
+	def spec()
+		CabezaDeTermo::JsonSpec::JsonSpec.new do |json_spec|
+			json_spec.expect_an(:object) do |object|
+				object.expect('name') .not_blank
+				object.expect('type') .not_blank
+				object.expect('description') .not_blank
+				object.expect('keywords') .to_be_as_defined_in(self, :keywords_spec)
+				object.expect('homepage').to_be_url
+				object.expect('license') .to_be_in(self.valid_licenses)
+				object.expect('authors') .to_be_as_defined_in(self, :authors_spec)
+				object.expect('require') .to_be_as_defined_in(self, :require_spec)
+				object.expect('require-dev') .to_be_as_defined_in(self, :require_spec)
+				object.expect('autoload') .to_be_as_defined_in(self, :autoload_spec)
+			end
+		end
+	end
+
+	def keywords_spec(json_spec)
+		json_spec .to_be_a(:list) .can_be_absent .not_empty do
+			each do
+				expect_a(:scalar) .not_blank
+			end
+		end
+	end
+
+	def authors_spec(json_spec)
+		json_spec .to_be_a(:list) .not_empty do |list|
+			list.each do |each|
+				each.to_be_as_defined_in(self, :author_spec)
+			end
+		end
+	end
+
+	def author_spec(json_spec)
+		json_spec .expect_an(:object) do
+			expect('name') .not_blank
+			expect('email') .to_be_email
+		end
+	end
+
+	def require_spec(json)
+		json .to_be_an(:object) .can_be_absent do
+			each_field do
+				expect_name .not_blank
+				expect_a(:scalar) .not_blank
+			end
+		end
+	end
+
+	def autoload_spec(json)
+		json .to_be_an(:object) do |object|
+			object.expect('psr-0') .to_be_as_defined_in(self, :psr_spec)
+			object.expect('psr-4') .to_be_as_defined_in(self, :psr_spec)
+			object.expect('classmap') .to_be_as_defined_in(self, :classmaps_spec)
+			object.expect('files') .to_be_as_defined_in(self, :files_spec)
+		end
+	end
+
+	def psr_spec(json_spec)
+		json_spec .to_be_an(:object) .can_be_absent do
+			each_field do
+				expect_name
+
+				expect_a(:list) .not_empty do
+					each do
+						expect_a(:scalar) .not_blank
+					end
+				end
+			end
+		end
+	end
+
+	def classmaps_spec(json_spec)
+		json_spec .to_be_a(:list) .can_be_absent .not_empty
+	end
+
+	def files_spec(json_spec)
+		json_spec .to_be_a(:list) .can_be_absent .not_empty
+	end
+
+	def valid_licenses()
+		['Apache-2.0', 'BSD-2-Clause', 'BSD-3-Clause', 
+		 'BSD-4-Clause' ,'GPL-2.0', 'GPL-2.0+', 'GPL-3.0', 
+		 'GPL-3.0+', 'LGPL-2.1', 'LGPL-2.1+', 'LGPL-3.0',
+		 'LGPL-3.0+', 'MIT']
+	end
+end
+```
+
+and to run the validation all we have to do is
+
+```ruby
+validator = ComposerJson.new.spec.validate_string(json_string)
+```
+
+If you want to validate a not very complex json, you can get away with it without factorizing the expectations. But as soon as the validation gets more complex, you can refactor the expectations using `:to_be_as_defined_in(some_object, :some_method)`.
+
+One thing to notice in this example is that we declared things like
+
+```ruby
+CabezaDeTermo::JsonSpec::JsonSpec.new do |json_spec|
+	json_spec.expect_an(:object) do |object|
+		...
+	end
+end
+```
+
+instead of
+
+```ruby
+CabezaDeTermo::JsonSpec::JsonSpec.new do
+	json_spec.expect_an(:object) do
+		...
+	end
+end
+```
+
+That is because when we don't pass a parameter to the defintion block, it changes the binding of self, and the we can not declare thinkgs like
+
+```ruby
+.to_be_as_defined_in(self, :keywords_spec)
+```
+
+Changing the binding to self is usually a bad idea, but in the definitions of this framework it will only do that if no parameter is given to the definition block.
+
+If you want to run this example, see the [fourth example](examples/example-4-to-be-as-defined-in.rb) in the `examples/` folder.
+
+## Expecting different structures for the same expression
+
+If we look at the `composer.json` definition, we will notice that sometimes it accepts different structures for the same field. For instance, for `psr-4` values, it can take a list of folder strings or a single folder string.
+
+To expect different structures on the same object, we use `:expect(:any_of)`:
+
+```ruby
+expect('psr-4') .to_be_a(:list) do
+	expect(:any_of) do
+		expect_a(:scalar) .to_be_folder
+	or_also
+		expect_a(:list) .not_empty do
+			each do
+				expect_a(:scalar) .to_be_folder
+			end
+		end
+	end
+end
+```
+
+## Defining custom expectations
+
+So far we only used the expectations defined by the `json-spec` framework. But more likely we will want to define our custom expectations. There are several reasons for that. Different APIs use different formats, or in some contexts we may want to use more intention revealing expectation names, to name a few.
+
+There are many ways to define new expectations, let's go through them:
+
+- Delegate the new expectation to an existing one.
+
+Suppose we want to check if a value is equal to 42. We can achieve that by doing
+
+```ruby
+json_spec .to_be_equal_to(42)
+```
+
+But if we want a more meaningful expectation name, we can add it to the [ExpectationsLibrary](lib/cabeza-de-termo/json-spec/expectations-library/expectations-library.rb).
+
+Here's an example of doing so:
+
+```ruby
+CabezaDeTermo::JsonSpec::ExpectationsLibrary.define do
+	expectations do
+		define :to_be_the_answer_to_life_the_universe_and_everything do
+		  expecting :to_be_equal_to, 42
+		  message "Nop, this is not the answer to life, the universe and everything."
+	 	end
+	end
+end
+```
+
+```ruby
+json_spec .to_be_the_answer_to_life_the_universe_and_everything
+# is now equivalent to:
+json_spec .to_be_equal_to(42)
+```
+
+Here's another interesting example of defining new expectations by delegation:
+
+```ruby
+CabezaDeTermo::JsonSpec::ExpectationsLibrary.define do
+	expectations do
+		define :to_be_date do
+		  expecting :to_match, /^\d\d\d\d-\d\d-\d\d$/
+		  message "Not a valid date format."
+	 	end
+	end
+end
+```
+
+This framework does not include a `to_be_date` expectation because it varies a lot from one API to another, but you can easyly add the one that suits your needs.
+
+Now compare using in your specs:
+
+```ruby
+json_spec .to_match(/^\d\d\d\d-\d\d-\d\d$/)
+# vs
+json_spec .to_be_date
+```
+
+- Negate an existing expectation.
+
+If you want to expect that something is not what another expectation asserts, do:
+
+```ruby
+CabezaDeTermo::JsonSpec::ExpectationsLibrary.define do
+	expectations do
+		define :not_date do
+		  negating :to_be_date
+		  message "Expected an invalid date, got a valid one."
+	 	end
+	end
+end
+```
+
+- Chain several existing expectations:
+
+```ruby
+CabezaDeTermo::JsonSpec::ExpectationsLibrary.define do
+	expectations do
+		define :to_be_defined do
+			expecting_all_of :to_exist
+			and_also :not_null
+
+			message "Failed asserting that the field '<%= field %>' with value = '<%= format value %>' is defined."
+		end
+	end
+end
+```
+
+- Expect one existing expectation among several ones:
+
+```ruby
+CabezaDeTermo::JsonSpec::ExpectationsLibrary.define do
+	expectations do
+		define :to_be_accessor do
+			expecting_any_of :to_be_getter
+			or_also :to_be_setter
+
+			message "The value is not an accessor string."
+		end
+	end
+end
+```
+
+So far we only composed existing expectations. Now we are going to define new ones.
+
+- Define a new expectation with a closure:
+
+```ruby
+CabezaDeTermo::JsonSpec::ExpectationsLibrary.define do
+	expectations do
+		define :to_be_greater_than do
+			with_block { |value_holder, expected_value| expected_value < value_holder.value }
+			message "<%= value %> is not greater than <%= expectation.args[0] %>."
+		end
+	end
+end
+```
+- Or finally, if your expectation is more complex, create a class for it:
+
+```ruby
+require 'cabeza-de-termo/json-spec/expectations/expectation'
+
+class IsSomeComplexStuff <  CabezaDeTermo::JsonSpec::Expectation
+	def is_satisfied_by?(value_holder)
+		# Check stuff and answer true or false.
+		# You can get the inspected value with value_holder.value
+	end
+end
+```
+
+and then define the expectation in the ExpectationsLibrary
+
+```ruby
+CabezaDeTermo::JsonSpec::ExpectationsLibrary.define do
+	expectations do
+		define :to_be_some_complex_stuff do
+			with_class IsSomeComplexStuff
+			message "<%= value %> is not a ComplexStuff."
+		end
+	end
+end
+```
+
+If you want to run this example, see the [fifth example](examples/example-5-custom-expectations.rb) in the `examples/` folder.
+
+## Defining custom messages
+
+We saw how we can define new Expectations with their own validation error message. But it would be nice to be able to change the validation error messages for the existing expectations as well.
+
+We can do that at 2 different scopes, just like when we defined default expectations.
+
+To override the validation messages globally, use
+
+```ruby
+CabezaDeTermo::JsonSpec::ExpectationsLibrary.define do
+	expectations do
+		define :to_be_defined do
+			message "If the question is to be or not to be, this value has chosen not to be. Alas, poor <%= field %>. My ValidationError rises at it."
+		end
+	end
+end
+```
+
+If we want to override the message only for a single `json-spec`, do
+
+```ruby
+json_spec.define do
+	expectations do
+		define :to_be_integer do
+			message "An integer, a integer! My <%= field %> for an integer!"
+		end
+	end
+end
+```
+
+You have to admit that these custom messages, although they are in a slang so boring and outdated that will get you to sleep in, like, 10 minutes, have a lot more of what we might call `poetic flight` than the default ones.
+
+Just like when defining new Expectations, we have several ways to define custom messages. Lets walk through them:
+
+- Using a [ErbMessageFormatter](lib/cabeza-de-termo/json-spec/message-formatters/erb-message-formatter.rb) object
+
+```ruby
+CabezaDeTermo::JsonSpec::ExpectationsLibrary.define do
+	expectations do
+		define :to_be_integer do
+			message "An integer, a integer! My <%= field %> for an integer!"
+		end
+	end
+end
+```
+
+This is the simpliest way, and it should be enough most of the times. You can reference :value_holder, :value, :accessors_chain, :field and :expectation objects from within a erb block: `<%= field %>`.
+
+- Using a [BlockMessageFormatter](lib/cabeza-de-termo/json-spec/message-formatters/block-message-formatter.rb) object
+
+```ruby
+CabezaDeTermo::JsonSpec::ExpectationsLibrary.define do
+	expectations do
+		define :to_be_integer do
+			message_block { |expectation, value_holder| "No a valid integer." }
+		end
+	end
+end
+```
+
+- Using you own [MessageFormatter](lib/cabeza-de-termo/json-spec/message-formatters/message-formatter.rb) subclass
+
+Define a new class with a `:message_on(expectation, value_holder)` method
+
+```ruby
+class MyCustomMessageFormatter
+	def message_on(expectation, value_holder)
+		"Nop!"
+	end
+end
+```
+
+and then override the message
+
+```ruby
+CabezaDeTermo::JsonSpec::ExpectationsLibrary.define do
+	expectations do
+		define :to_be_integer do
+			message_formatter MyCustomMessageFormatter.new
+		end
+	end
+end
+```
+
+If you want to run the custom messages example, see the [sixth example](examples/example-6-custom-messages.rb) in the `examples/` folder.
+
+## Conditional expectations and expression modifiers
+
+So far we only talked about Expectations. However, sometimes expectations are not enough. For instance, sometimes you may want to decide whether to keep running expectations or not, but without failing. An example of that are the `:can_be_something` statements. `:can_be_absent` states that a field may be missing and it's ok, but if it is present we want to keep running expectations on that expression.
+In the `json-spec` framework, each expression does not hold a collection of expectations, but an [ExpectationsRunner](lib/cabeza-de-termo/json-spec/expectations/runner/expectations-runner.rb) instead.
+If you plug your own [AbstractExpectationsRunner](lib/cabeza-de-termo/json-spec/expectations/runner/abstract-expectations-runner.rb) you can alter the execution flow of the expectations for that expression.
+
+And how would you plug an ExpectationsRunner in a json_expression?
+
+With the help of an [ExpressionModifier](lib/cabeza-de-termo/json-spec/modifiers/expression-modifier.rb), which you can add to the [ExpectationsLibrary](lib/cabeza-de-termo/json-spec/expectations-library/expectations-library.rb) using its `:define` method, just like with the custom expectations.
+
+Or perhaps some expectation needs to remove other expectations for an expression to make sense.
+In that case you can also use your own ExpressionModifier.
+
+This sounds more complicated than it actually is. Check the [CanBeNullModifier](lib/cabeza-de-termo/json-spec/modifiers/can-be-null-modifier.rb) to see a real example and see that it's actually quite easy to do weird stuff on the expressions and expectations execution flow.
+
+## Putting it all together
+
+Ok, so we can define default expectations for each expression, add new custom expectations, add new custom modifiers and replace the default expectation messages without the need of subclassing any existing class of the framework. That is really handy for simple validations. But what if we have done a nice and complete set of expectations and messages that we want to keep together to use it in several places?
+
+In that case, it is a good idea to bundle it all together in one place.
+
+That place can be the [LibraryInitializer](lib/cabeza-de-termo/json-spec/expectations-library/initializers/library-initializer.rb).
+
+Create you own class that implements the [LibraryInitializer](lib/cabeza-de-termo/json-spec/expectations-library/initializers/library-initializer.rb) protocol, and there create a new and fully configured [ExpectationsLibrary](lib/cabeza-de-termo/json-spec/expectations-library/expectations-library.rb).
+
+Something like this:
+
+```ruby
+class ComposerLibraryInitializer
+	def new_library()
+		initialize_library CabezaDeTermo::JsonSpec::DefaultLibraryInitializer.new.new_library
+	end
+
+	def initialize_library(library)
+		# add more custom stuff to the library here
+
+		library
+	end
+end
+```
+
+and now plug the initializer into the ExpectationsLibrary at your application bootstrap with
+
+```ruby
+CabezaDeTermo::JsonSpec::ExpectationsLibrary
+	.set_default_library_initializer( ComposerLibraryInitializer.new )
+```
+
+and that's it, now you can use the ExpectationsLibrary with all your custom additions.
+
+To see how all the pieces fitted together, check and run the [seventh example](examples/example-7-full-example.rb) in the `examples/` folder.
+
+## Inspecting the expectations
+
+With the default expectations and expression modifiers, it is quite sure that sooner or later you will want to see what expectations are actually set to each expression in a json_spec.
+If you need to debug the expectations, run
+
+```ruby
+	puts json_spec.explain
+```
+
+and will get something like this
+
+```ruby
+{
+	"name":
+		anything .not_blank()
+	"type":
+		anything .not_blank()
+	"description":
+		anything .not_blank()
+	"keywords":
+		[
+			scalar .not_blank()
+		]
+			if present
+			 .to_be_list(Array) .not_empty()
+	"homepage":
+		anything .to_be_url()
+	"license":
+		anything .to_be_valid_lincense(Apache-2.0, BSD-2-Clause, BSD-3-Clause, BSD-4-Clause, GPL-2.0, GPL-2.0+, GPL-3.0, GPL-3.0+, LGPL-2.1, LGPL-2.1+, LGPL-3.0, LGPL-3.0+, MIT)
+	"authors":
+		[
+			{
+				"name":
+					anything .not_blank()
+				"email":
+					anything .to_be_email()
+			} .to_be_object(Hash)
+		] .to_be_list(Array) .not_empty()
+	"require":
+		{
+			each field
+				name .not_blank()
+				value
+					scalar .to_be_version()
+		}
+			if present
+			 .to_be_object(Hash)
+	"require-dev":
+		{
+			each field
+				name .not_blank()
+				value
+					scalar .to_be_version()
+		}
+			if present
+			 .to_be_object(Hash)
+	"autoload":
+		{
+			"psr-0":
+				{
+					each field
+						name .to_be_string(String)
+						value
+							any of
+								scalar .to_be_folder()
+							or
+								[
+									scalar .to_be_folder()
+								] .to_be_list(Array) .not_empty()
+				}
+					if present
+					 .to_be_object(Hash)
+			"psr-4":
+				{
+					each field
+						name .to_be_psr4_key()
+						value
+							any of
+								scalar .to_be_folder()
+							or
+								[
+									scalar .to_be_folder()
+								] .to_be_list(Array) .not_empty()
+				}
+					if present
+					 .to_be_object(Hash)
+			"classmap":
+				[
+				]
+					if present
+					 .to_be_list(Array) .not_empty()
+			"files":
+				[
+				]
+					if present
+					 .to_be_list(Array) .not_empty()
+		} .to_be_object(Hash)
+} .to_be_object(Hash)
+```
+
+## Development environment
+
+So, you are too lazy to setup the development environment for this project. Yeah, I feel you. I am too.
+
+Anyways, you can use the Vagrant configuration for that. To do so:
+
+* Install [VirtualBox](https://www.virtualbox.org/)
+* Install [Vagrant](https://www.vagrantup.com/)
+* `git clone --recursive git@github.com:mrubi/ruby-json-spec.git`
+* `cd ruby-json-spec/cachivache`
+* `vagrant up`
+
+and that will install all the necessary things to run the tests and examples in this project.
+
+Then to start playing around with the code, do
+
+* `vagrant ssh`
+* `cd src/json-spec`
+
+and that's it. You have a fully prepared, ready to use development environment.
+
+# Running the tests
+
+* `rake test`
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/json-spec.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+