README.md in hungryform-0.0.1 vs README.md in hungryform-0.0.2

@@ -1,25 +1,128 @@
 # HungryForm
 
-TODO: Write a gem description
+HungryForm is a gem for managing multiple page forms. The main purpose of this gem is to give developers an easy DSL to build complex forms.
 
-## Installation
+## Usage
 
-Add this line to your application's Gemfile:
+```ruby
+require 'hungryform'
 
-    gem 'hungryform'
+form = HungryForm.new do
+  page :first do
+    text_field :first_name
+    text_field :last_name
+  end
+  page :second, do 
+    text_field :address
+  end
+  page :third do 
+    text_field :occupation
+    
+    # Show this group only when the occupation field is not empty
+    group :employment_history, visible: false, dependency: '{"SET": "third_occupation"}' do
+      html :before, value: "Employment history over the last 5 years"
+      text_field :history, value: "Default value"
+    end
+  end 
+end
+```
 
-And then execute:
+To assign values to the form elements pass them as a hash on form initialization. The params hash must consist of elements names and their values. Please note, that the elements names must contain the full path to the element, starting from the page name.
 
-    $ bundle
+```ruby
+params = {
+  "first_first_name" => "John",
+  "first_last_name" => "Doe",
+  "second_address" => "John's address",
+  "third_occupation" => "Software engineer",
+  "third_employment_history_history" => "John's employment hisotory"
+}
 
-Or install it yourself as:
+form = HungryForm.new :params => params do
+...
+end
 
-    $ gem install hungryform
+```
 
-## Usage
+You can assign default value to a form element:
 
-TODO: Write usage instructions here
+```ruby
+text_field :email, value: "[e-mail]"
+```
+## Dependencies
+
+Each element of HungryForm, including pages and groups, can have a dependency parameter. This parameter must be a json string with an expression, that resolves to a boolean result. Within this expression you can use and combine the following operators, creating complex dependencies that can involve multiple elements:
+
+```json
+# val1 == val2
+{"EQ": ["val1", "val2"]}
+
+# val1 > val2
+{"GT": ["val1", "val2"]}
+
+# val1 < val2
+{"LT": ["val1", "val2"]}
+
+# val1 is not empty
+{"SET": "val1"}
+
+# Get the opposite result of the expression
+{"NOT": {"EQ": ["1", "1"]}}
+
+# Check if all the expressions are true
+{"AND": [
+  {"EQ": ["1", "1"]},
+  {"EQ": ["2", "2"]}
+]}
+
+# Check if any of the expressions is true
+{"OR": [
+  {"NOT": {"EQ": ["1", "1"]}},
+  {"EQ": ["2", "2"]}
+]}
+```
+
+If the dependency is resolved positively it makes the element visible. Otherwise the element will be hidden and not required. It is allowed to use element names or params keys as parameters inside expressions.
+
+```ruby
+HungryForm.new do
+  page :about do
+    text_field :age
+    text_field :favourite_alcohol, required: true, dependency: '{"GT": ["about_age", "18"]}'
+  end
+end
+    
+```
+
+## Validation
+
+Each active element of a form can be assigned with validation rules.
+
+- required - accepts boolean or proc
+- validation - accepts proc
+
+```ruby
+text_field :name, required: true
+text_field :email, validation: ->(el) { "is unexpected email" unless el.value == "[e-mail]"  }
+```
+
+You can extend the list of validation rules by opening the HungryForm::Validator singleton class and creating your own validation methods:
+
+```ruby
+class HungryForm
+  class Validator
+    class << self
+      def my_validation_method(element, rule)
+        "is not #{rule}" unless element.value == rule
+      end
+    end
+  end
+end
+  
+  
+text_field :vegetable, value: "tomato", my_validation_method: "potato" # => is not potato
+```
 
 ## Contributing
 
 1. Fork it ( https://github.com/andrba/hungryform/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)