eapi 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 63f4151b5dc72b051cea9b0c448472007841deaa
-  data.tar.gz: a0f4c037e605fd4ca96e6c1d8518accaee6d9509
+  metadata.gz: af49a7ace939612da586885e144e872e26f9bab6
+  data.tar.gz: a55532d8fc6a2eb3350b19768e5ac403f3329b2b
 SHA512:
-  metadata.gz: b06d56359371a02be843a0bc48b11f8fb9c873656e08d7d877427c95840d58b1595ea07d0faa1c9a176a7cfbb2432a2b67e74ace65f113c0836c51bde87d0147
-  data.tar.gz: 24e712cec447d69b9a65202b946d6a73e23aaa35334c0e92b46a9aba15fa119245e6cde824da3c0a34c9daff0dbf3e233e8747f7061dbc44c73aebedba855858
+  metadata.gz: df2402e3c80c6d2ec64291d61a31f3c9e8c50dff4383f29b1f72e56bd801473a40daea2b9e97199f87a16a959ec63670af210fedbd4a343b68c0a5c7cbd34ecb
+  data.tar.gz: 5dd6bcb8988fb8a1add9932e038fd84df732f5c84c494efcfbe00be5ac3f549bc6f70a07cb34506fd23dd1ef30e7e0e274a7b53e1e3bbab281cf03a45ee4d3dc

data/README.md

@@ -1,114 +1,85 @@
 # Eapi (Elastic API)
 
-ruby gem for building complex structures that will end up in hashes (initially devised for ElasticSearch search requests)
-
 [![Gem Version](https://badge.fury.io/rb/eapi.svg)](http://badge.fury.io/rb/eapi)
 [![Build Status](https://travis-ci.org/eturino/eapi.svg?branch=master)](https://travis-ci.org/eturino/eapi)
 [![Code Climate](https://codeclimate.com/github/eturino/eapi.png)](https://codeclimate.com/github/eturino/eapi)
 [![Code Climate Coverage](https://codeclimate.com/github/eturino/eapi/coverage.png)](https://codeclimate.com/github/eturino/eapi)
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'eapi'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install eapi
-
-## Dependencies
-
-### Ruby version
-
-Works with ruby 2.1, tested with MRI 2.1.1 
-
-### Gem dependencies
+Ruby gem for building complex structures that will end up in hashes or arrays
 
-This gem uses ActiveSupport (version 4) and also the ActiveModel Validations (version 4). It also uses fluent_accessors gem.
+Main features:
 
-Extracted from the gemspec:
-```
-spec.add_dependency 'fluent_accessors', '~> 1'
-spec.add_dependency 'activesupport', '~> 4'
-spec.add_dependency 'activemodel', '~> 4'
-```
+* property definition
+* automatic fluent accessors
+* list support
+* validation
+* rendering to `Hash` or `Array`
+* raw `Hash` or `Array` support to skip type check validations
+* omit `nil` values automatically
 
 ## Usage
 
-### including EAPI into your class
+Eapi work by exposing a couple of modules to include in your classes. 
 
-Just include the module `Eapi::Item` into your class.
+* `Eapi::Item` module to create objects with multiple properties that will render into hashes.
+* `Eapi::List` module to create lists that will render into arrays.
 
 ```ruby    
-class MyTestKlass
+# ITEM
+class MyItem
   include Eapi::Item
 
+  # defining some properties
   property :something
+  property :other, type: Fixnum
+  property :third, multiple: true
 end
-```
 
-### Initialize
+i = MyItem.new something: 1
+i.something # => 1
+i.other(2).add_third(3)
+i.render # => {something: 1, other: 2, third: [3]}
+i.to_h # => {something: 1, other: 2, third: [3]}
 
-`Eapi::Common` will add a `initialize` method to your class that will accept a hash. It will recognise the defined properties in that hash and will set them. 
+# LIST
+class MyList
+  include Eapi::List
+  
+  elements required: true
+end
 
-For now any unrecognised property in the hash will be ignored. This may change in the future.
+l = MyList.new
+l.add(1).add(2)
+l.render # => [ 1, 2 ]
+l.to_a # => [ 1, 2 ]
+```
 
-```ruby    
-class MyTestKlass
-  include Eapi::Item
+This will provide:
 
-  property :something
-end
+* a *DSL to define properties* and elements *validations* and *rules*
+* *fluent accessor* methods for each property 
+* a *keyword arguments* enabled `initialize` method
+* a shortcut for object creation sending messages to the `Eapi` module directly with the name of the class.
 
-x = MyTestKlass.new something: 1
-x.something # => 1
-```
+We'll se this in detail.
 
-### Object creation shortcut: calling methods in Eapi
+## `Eapi::Item`: Property based Item objects
 
-Calling a method with the desired class name in `Eapi` module will do the same as `DesiredClass.new(...)`. The name can be the same as the class, or an underscorised version, or a simple underscored one.  
+### `initialize` method
 
-The goal is to use `Eapi.esr_search(name: 'Paco')` as a shortcut to `Esr::Search.new(name: 'Paco')`. We can also use `Eapi.Esr_Search(...)` and other combinations.
+`Eapi::Item` will add a `initialize` method to your class that will accept a hash. It will recognise the defined properties in that hash and will set them. 
 
-To show this feature and all the combinations for method names, we'll use the 2 example classes that are used in the actual test rspec.
+*important*: For now any unrecognised property in the hash will be ignored. This may change in the future.
 
-```ruby
-class MyTestKlassOutside
+```ruby    
+class MyTestKlass
   include Eapi::Item
 
   property :something
 end
 
-module Somewhere
-  class TestKlassInModule
-    include Eapi::Item
-
-    property :something
-  end
-end
-```
-
-As shown by rspec run:
-
-```
-    initialise using method calls to Eapi
-      Eapi.MyTestKlassOutside(...)
-        calls MyTestKlassOutside.new
-      Eapi.my_test_klass_outside(...)
-        calls MyTestKlassOutside.new
-      Eapi.Somewhere__TestKlassInModule(...)
-        calls Somewhere::TestKlassInModule.new
-      Eapi.somewhere__test_klass_in_module(...)
-        calls Somewhere::TestKlassInModule.new
-      Eapi.Somewhere_TestKlassInModule(...)
-        calls Somewhere::TestKlassInModule.new
-      Eapi.somewhere_test_klass_in_module(...)
-        calls Somewhere::TestKlassInModule.new
+x = MyTestKlass.new something: 1
+x.something # => 1
 ```
 
 ### Defining properties
@@ -123,7 +94,7 @@ class MyTestKlass
   property :two
 end
 ```
-#### Setting proeprties on object creation
+#### Setting properties on object creation
 We can then assign the properties on object creation:
 ```ruby
 x = MyTestKlass.new one: 1, two: 2
@@ -180,15 +151,15 @@ All Eapi classes respond to `render` and return a hash (for `Item` classes) or a
 
 Inside, `render` will call `valid?`, raise an error of type `Eapi::Errors::InvalidElementError` if something is not right, and if everything is ok it will call `create_hash`.
 
-The `create_hash` method will create a hash with the properties as keys. Each value will be "converted".
+The `create_hash` method will create a hash with the properties as keys. Each value will be "converted" (see "Values conversion" section).
 
 #### Values conversion
 
 By default, each property will be converted into a simple element (Array, Hash, or simple value).  
 
-If a value is an Array or a Set, `to_a` will be invoked and all values will be "converted" in the same way.
-
-If a value respond to `to_h`, it will be called. That way, if the value of a property (or an element of an Array) is an Eapi object, it will be validated and converted into a simple hash structure.
+1. If a value responds to `render`, it will call that method. That way, Eapi objects that are values of some properties or lists will be validated and rendered (converted) themselves (render / value conversion cascade).
+2. If a value is an Array or a Set, `to_a` will be invoked and all values will be converted in the same way.
+3. If a value respond to `to_h`, it will be called.
 
 important: *any nil value will be omitted* in the final hash.
 
@@ -246,6 +217,24 @@ When defining the property, we can specify some options to specify what values a
 
 It uses `ActiveModel::Validations`. When `to_h` is called in an Eapi object, the `valid?` method will be called and if the object is not valid an `Eapi::Errors::InvalidElementError` error will raise.
 
+#### Validations from `ActiveModel::Validations`
+
+All other ActiveModel::Validations can be used:
+
+```ruby
+class TestKlass
+  include Eapi::Item
+
+  property :something
+  validates :something, numericality: true
+end
+
+eapi = TestKlass.new something: 'something'
+eapi.valid? # => false
+eapi.errors.full_messages # => ["Something is not a number"]
+eapi.errors.messages # => {something: ["must is not a number"]}
+```
+
 #### Mark a property as Required with `required` option
 
 A required property will fail if the value is not present. It will use `ActiveModel::Validations` inside and will effectively do a `validates_presence_of :property_name`. 
@@ -267,7 +256,7 @@ eapi.errors.messages # => {something: ["can't be blank"]}
 
 #### Specify the property's Type with `type` option
 
-If a property is defined to be of a specific type, the value will be validated to meet that criteria. It means that the value must be of the specified type. It will use `value.kind_of?(type)` and if that fails it will use `value.is?(type)` if defined.
+If a property is defined to be of a specific type, the value will be validated to meet that criteria. It means that the value must be of the specified type. It will use `value.kind_of?(type)` (if type represents an actual class), and if that fails it will use `value.is?(type)` if defined.
 
 example:
  
@@ -284,13 +273,164 @@ eapi.errors.full_messages # => ["Something must be a Hash"]
 eapi.errors.messages # => {something: ["must be a Hash"]}
 ```
 
-Also, if a type is specified, then a `init_property_name` method is created that will set a new object of the given type in the property.
+#### Custom validation with `validate_with` option
+
+A more specific validation can be used using `validate_with`, that works the same way as `ActiveModel::Validations`. 
 
+example:
+ 
 ```ruby
 class TestKlass
   include Eapi::Item
 
-  property :something, type: Hash
+  property :something, validate_with: ->(record, attr, value) do
+    record.errors.add(attr, "must pass my custom validation") unless value == :valid_val
+  end
+end
+
+eapi = TestKlass.new something: 1
+eapi.valid? # => false
+eapi.errors.full_messages # => ["Something must pass my custom validation"]
+eapi.errors.messages # => {something: ["must pass my custom validation"]}
+```
+
+
+### List properties
+
+A property can be defined as a multiple property. This will affect the methods defined in the class (it will create a fluent 'adder' method `add_property_name` and a fluent 'clearer' method `clear_property_name`), and also the automatic initialisation.
+
+#### Define property as multiple with `multiple` option
+
+A property marked as `multiple` will be initialised with an empty array. If no `init_class` is specified then it will use Array as a `init_class`, for purposes of the `init_property_name` method.
+
+```ruby
+class TestKlass
+  include Eapi::Item
+
+  property :something, multiple: true
+end
+```
+
+#### Fluent adder method `add_property_name`
+
+For a property marked as multiple, an extra fluent method called `add_property_name` will be created. This work very similar to the fluent setter `set_property_name` but inside it will append the value (using the shovel method `<<`) instead of setting it.
+
+If the property is `nil` when `add_property_name` is called, then it will call `init_property_name` before. 
+
+```ruby
+class TestKlass
+  include Eapi::Item
+
+  property :something, multiple: true
+end
+
+x = TestKlass.new
+x.add_something(1).add_something(2)
+x.something # => [1, 2]
+```
+
+
+#### Fluent clearer method `clear_property_name`
+
+For a property marked as multiple, an extra fluent method called `clear_property_name` will be created. This method will call `clear` into the existing property value if it is present and respond to it. If that is not the case, it will init the property again calling `init_property_name`.
+
+```ruby
+class TestKlass
+  include Eapi::Item
+
+  property :something, multiple: true
+end
+
+x = TestKlass.new
+x.add_something(1).add_something(2)
+x.something # => [1, 2]
+x.clear_something.something # => []
+```
+
+#### Implicit `multiple` depending on `init_class` or `type`
+
+Even without `multiple` option specified, if the `init_class` option is: 
+* `Array`
+* `Set`
+* a class that responds to `is_multiple?` with true
+
+then the property is marked as multiple.
+ 
+It will also work if the `type` option is given with a class or a class name that complies with the above restrictions.
+ 
+example: (all `TestKlass` properties are marked as multiple)
+```ruby
+class MyCustomList
+  def self.is_multiple?
+    true
+  end
+  
+  def <<(val)
+    @list |= []
+    @list << val
+  end
+end
+
+class TestKlass
+  include Eapi::Item
+
+  property :p1, multiple: true
+  property :p2, init_class: Array
+  property :p3, init_class: "Set"
+  property :p4, type: Set
+  property :p5, type: "MyCustomList"
+end
+
+x = TestKlass.new
+x.add_p1(1).add_p2(2).add_p3(3).add_p4(4)
+```
+
+#### Element validation
+
+Same as property validation, but for specific the elements in the list.
+
+We can use `element_type` option in the definition, and it will check the type of each element in the list, same as `type` option does with the type of the property's value.
+
+We can also specify `validate_element_with` option, and it will act the same as `validate_with` but for each element in the list.
+
+```ruby
+class TestKlass
+  include Eapi::Item
+
+  property :something, multiple: true, element_type: Hash
+  property :other, multiple: true, validate_element_with: ->(record, attr, value) do
+    record.errors.add(attr, "element must pass my custom validation") unless value == :valid_val
+  end
+end
+
+eapi = TestKlass.new
+eapi.add_something 1
+
+eapi.valid? # => false
+eapi.errors.full_messages # => ["Something element must be a Hash"]
+eapi.errors.messages # => {something: ["must element be a Hash"]}
+
+eapi.something [{a: :b}]
+eapi.valid? # => true
+
+eapi.add_other 1
+eapi.valid? # => false
+eapi.errors.full_messages # => ["Other element must pass my custom validation"]
+eapi.errors.messages # => {other: ["element must pass my custom validation"]}
+
+eapi.other [:valid_val]
+eapi.valid? # => true
+```
+
+#### Automatic property initialisation with `init_class` option
+
+If a property is marked to be initialised using a specific class, then a `init_property_name` method is created that will set a new object of the given class in the property.
+
+```ruby
+class TestKlass
+  include Eapi::Item
+
+  property :something, init_class: Hash
 end
 
 eapi = TestKlass.new
@@ -299,7 +439,7 @@ eapi.init_something
 eapi.something # => {}
 ```
 
-A symbol or a string can also be specified as class name in `type` option, and it will be loaded on type check. This can be helpful to avoid loading problems. Using the same example as before:
+A symbol or a string can also be specified as class name in `init_class` option, and it will be loaded on type check. This can be helpful to avoid loading problems. Using the same example as before:
 
 ```ruby
 class TestKlass
@@ -316,7 +456,7 @@ eapi.something # => {}
 
 To trigger the error, the value must not be an instance of the given Type, and also must not respond `true` to `value.is?(type)`
 
-#### Skip type validation with 'raw' values with `allow_raw` option
+### Skip type validation with 'raw' values with `allow_raw` option
 
 If we want to check for the type of the elements, but still want the flexibility of using raw `Hash` or `Array` in case we want something specific there, we can specify it with the `allow_raw` option.
 
@@ -397,44 +537,7 @@ TestList.elements_disallow_raw
 TestList.elements_allow_raw? # => false
 ```
 
-#### Custom validation with `validate_with` option
-
-A more specific validation can be used using `validate_with`, that works the same way as `ActiveModel::Validations`. 
-
-example:
- 
-```ruby
-class TestKlass
-  include Eapi::Item
-
-  property :something, validate_with: ->(record, attr, value) do
-    record.errors.add(attr, "must pass my custom validation") unless value == :valid_val
-  end
-end
-
-eapi = TestKlass.new something: 1
-eapi.valid? # => false
-eapi.errors.full_messages # => ["Something must pass my custom validation"]
-eapi.errors.messages # => {something: ["must pass my custom validation"]}
-```
-
-#### Validations from `ActiveModel::Validations`
-
-All other ActiveModel::Validations can be used:
-
-```ruby
-class TestKlass
-  include Eapi::Item
-
-  property :something
-  validates :something, numericality: true
-end
-
-eapi = TestKlass.new something: 'something'
-eapi.valid? # => false
-eapi.errors.full_messages # => ["Something is not a number"]
-eapi.errors.messages # => {something: ["must is not a number"]}
-```
+### Definition
 
 #### Unrecognised property definition options
 
@@ -460,113 +563,7 @@ definition[:type] = Array
 TestKlass.definition_for :something # => { type: Hash, unrecognised_option: 1 }
 ```
 
-### List properties
-
-a property can be defined as a multiple property. This will affect the methods defined in the class (it will create a fluent 'adder' method `add_property_name`), and also the automatic initialisation.
-
-#### Define property as multiple with `multiple` option
-
-A property marked as `multiple` will be initialised with an empty array. If no type is specified then it will use Array as a type, only for purposes of the `init_property_name` method.
-
-```ruby
-class TestKlass
-  include Eapi::Item
-
-  property :something, multiple: true
-end
-```
-
-#### Adder method `add_property_name`
-
-For a property marked as multiple, an extra fluent method called `add_property_name` will be created. This work very similar to the fluent setter `set_property_name` but inside it will append the value (using the shovel method `<<`) instead of setting it.
-
-If the property is `nil` when `add_property_name` is called, then it will call `init_property_name` before. 
-
-```ruby
-class TestKlass
-  include Eapi::Item
-
-  property :something, multiple: true
-end
-
-x = TestKlass.new
-x.add_something(1).add_something(2)
-x.something # => [1, 2]
-```
-
-#### Implicit `multiple` depending on Type
-
-Even without `multiple` option specified, if the `type` option is: 
-* `Array`
-* `Set`
-* a class that responds to `is_multiple?` with true
-
-then the property is marked as multiple.
- 
-example: (all `TestKlass` properties are marked as multiple)
-```ruby
-class MyCustomList
-  def self.is_multiple?
-    true
-  end
-  
-  def <<(val)
-    @list |= []
-    @list << val
-  end
-end
-
-class TestKlass
-  include Eapi::Item
-
-  property :p1, multiple: true
-  property :p2, type: Array
-  property :p3, type: Set
-  property :p4, type: MyCustomList
-end
-
-x = TestKlass.new
-x.add_p1(1).add_p2(2).add_p3(3).add_p4(4)
-```
-
-#### Element validation
-
-Same as property validation, but for specific the elements in the list.
-
-We can use `element_type` option in the definition, and it will check the type of each element in the list, same as `type` option does with the type of the property's value.
-
-We can also specify `validate_element_with` option, and it will act the same as `validate_with` but for each element in the list.
-
-```ruby
-class TestKlass
-  include Eapi::Item
-
-  property :something, multiple: true, element_type: Hash
-  property :other, multiple: true, validate_element_with: ->(record, attr, value) do
-    record.errors.add(attr, "element must pass my custom validation") unless value == :valid_val
-  end
-end
-
-eapi = TestKlass.new
-eapi.add_something 1
-
-eapi.valid? # => false
-eapi.errors.full_messages # => ["Something element must be a Hash"]
-eapi.errors.messages # => {something: ["must element be a Hash"]}
-
-eapi.something [{a: :b}]
-eapi.valid? # => true
-
-eapi.add_other 1
-eapi.valid? # => false
-eapi.errors.full_messages # => ["Other element must pass my custom validation"]
-eapi.errors.messages # => {other: ["element must pass my custom validation"]}
-
-eapi.other [:valid_val]
-eapi.valid? # => true
-```
-
-### `List` classes
+## `Eapi::List`: list based objects
 
 An Eapi `List` is to an Array as an Eapi `Item` is to a Hash. 
 
@@ -574,10 +571,14 @@ It will render itself into an array of elements. It can store a list of elements
 
 It works using an internal list of elements, to whom it delegates most of the behaviour. Its interface is compatible with an Array, including ActiveSupport methods. 
 
-#### accessor to internal element list: `_list`
+*important*: Right now a `List` can also have properties like an `Item`, but this could change for a stable release.
+
+### accessor to internal element list: `_list`
 
 The internal list of elements of an Eapi `List` object can be accessed using the `_list` method, that is always an `Array`.
  
+### Methods
+ 
 #### fluent adder: `add`
 
 Similar to the `set_x` methods for properties, this method will add an element to the internal list and return `self`. 
@@ -593,7 +594,7 @@ The options for that definition is:
 * `element_type` or `type`: it will provoke the list validation to fail if an element does not complies with the given type validation (see type validation on `Item`)
 * `validate_element_with` or `validate_with`: it will execute the given callable object to validate each element, similar to the `validate_element_with` option in the property definition.
 
-#### example
+### example
 
 ```ruby
 class MyListKlass
@@ -620,6 +621,10 @@ l.add(1)
 l.valid? # => false
 ```
 
+## Common to `Item` and `List`
+
+The following features are shared between `List`s and `Item`s.
+
 ### Pose as other types
 
 An Eapi class can poses as other types, for purposes of `type` checking in a property definition. We use the class method `is` for this.
@@ -671,9 +676,51 @@ obj.is_an_one_thing? # => true
 obj.is_a_super_duper_thing? # => false
 ```
 
-### Use in your own library
+### Object creation shortcut: calling methods in Eapi
+
+Calling a method with the desired class name in `Eapi` module will do the same as `DesiredClass.new(...)`. The name can be the same as the class, or an underscorised version, or a simple underscored one.  
+
+The goal is to use `Eapi.esr_search(name: 'Paco')` as a shortcut to `Esr::Search.new(name: 'Paco')`. We can also use `Eapi.Esr_Search(...)` and other combinations.
+
+To show this feature and all the combinations for method names, we'll use the 2 example classes that are used in the actual test rspec.
+
+```ruby
+class MyTestKlassOutside
+  include Eapi::Item
+
+  property :something
+end
+
+module Somewhere
+  class TestKlassInModule
+    include Eapi::Item
+
+    property :something
+  end
+end
+```
+
+As shown by rspec run:
+
+```
+    initialise using method calls to Eapi
+      Eapi.MyTestKlassOutside(...)
+        calls MyTestKlassOutside.new
+      Eapi.my_test_klass_outside(...)
+        calls MyTestKlassOutside.new
+      Eapi.Somewhere__TestKlassInModule(...)
+        calls Somewhere::TestKlassInModule.new
+      Eapi.somewhere__test_klass_in_module(...)
+        calls Somewhere::TestKlassInModule.new
+      Eapi.Somewhere_TestKlassInModule(...)
+        calls Somewhere::TestKlassInModule.new
+      Eapi.somewhere_test_klass_in_module(...)
+        calls Somewhere::TestKlassInModule.new
+```
+
+## Using Eapi in your own library
 
-You can add the functionality of Eapi to your own library module, and use it instead of `Eapi::Common`.
+You can add the functionality of Eapi to your own library module, and use it instead of `Eapi::Item` or `Eapi::List`.
 
 Method-call-initialise shortcut can ignore the base name:
 
@@ -683,7 +730,7 @@ module MyExtension
 end
 
 class TestKlass
-  include MyExtension::Common
+  include MyExtension::Item
   property :something
 end
 
@@ -695,7 +742,7 @@ obj.something # => 1
 
 module MyExtension
   class TestKlassInside
-    include MyExtension::Common
+    include MyExtension::Item
     property :something
   end
 end
@@ -711,9 +758,41 @@ obj.something # => 1
 
 As it works now, the children of your extension will be also children of `Eapi`, so calling `Eapi.your_klass` and `YourExtension.your_klass` will do the same.
 
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'eapi'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install eapi
+
+## Dependencies
+
+### Ruby version
+
+Works with ruby 2.1, tested with MRI 2.1.1 
+
+### Gem dependencies
+
+This gem uses ActiveSupport (version 4) and also the ActiveModel Validations (version 4). It also uses fluent_accessors gem.
+
+Extracted from the gemspec:
+```
+spec.add_dependency 'fluent_accessors', '~> 1'
+spec.add_dependency 'activesupport', '~> 4'
+spec.add_dependency 'activemodel', '~> 4'
+```
+
 ## TODO
 
 1. `type` option in property definition to accept symbol -> if a class can be recognised by that name, it works ok. If not, it still uses that for type validation (using `is?`) but it does not use that in the `init_` method.
+2. `type` option to be divided in `init_type` (must be a class or a class name) and `check_type` (class / class name or type validation using `is?`)
 
 ## Contributing