README.md in ine-places-0.1.3 vs README.md in ine-places-0.1.4

- old
+ new

@@ -163,9 +163,43 @@ ```ruby INE::Places::Place.find_by_slug('burjassot') => #<INE::Places::Place id="46078", name="Burjassot", slug="burjassot", province_id="46", lon="-0.4135963", lat="39.5096699", province=#<INE::Places::Province id="46", name="Valencia/València", slug="valencia", autonomous_region_id="10", lon="-0.3762881", lat="39.4699075", autonomous_region=#<INE::Places::AutonomousRegion id="10", name="Comunidad Valenciana", slug="comunidad-valenciana", lon="-0.7532808999999999", lat="39.4840108">>> ``` +## Hydratating models with data (experimental feature) + +It's quite common to work with data related with the entities provided by this gem. For example, to know the debt of a place, the amount of schools, the number of inhabitants, and so on. This data lives in external sources, such a CSV or a JSON file, or an API endpoint but can be co-related with the entities using an ID column. + +Hydratation feature helps you with this issue. For the moment it's very experimental but allows you to add basics sets of data from a local CSV file. + +For example, given a CSV file with a single row: + +```csv +municipio,value +28079,33 +``` + +You could hydratate the model `INE::Places::Place` using the `.hydrate` function: + +```ruby +INE::Places.hydratate INE::Places::Place, 'spec/fixtures/happiness.csv', id_column: 'municipio', + as: :happiness, + value_column: 'value' +``` + +You just need to provide: + +- id column, to match the IDs +- the `as` column, with the name of the new method +- the value column, to know exactly where the value is + +After hydratating a class, every object of the class has the new method in the `.data` property: + +```ruby +place.data.happiness +#> 100 +``` + ## Development After checking out the repository, run `bin/setup` to install dependencies. Then, run `rake spec` 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).