hstore_accessor 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f427874b1399b9aadd39910014acf1374ed8665f
-  data.tar.gz: 6801a29b56e216ffb63de7ce1484ee76c20ba7b3
+  metadata.gz: a479c49a994305a373abfb2bef072aa39eadd1d4
+  data.tar.gz: 6a213cac35074d7b5e8e1d3b760c7e3dcdb5c40e
 SHA512:
-  metadata.gz: 8702aed6b3f57de15f2175da5e50cbfabe60373b41492ff034196224f08494dc6763ac96d9cca7d21c51d6a1e56a2580d5e96803d675a6f10d59ce2f938bc3b4
-  data.tar.gz: 977817e66627297cb37f84f901644db7a2a2d5ecb995864eb68da7d24ebeba8d7fb6db6c87b0309936538eb2ed1ca92f84b5785474fc216dff8b63b4096bcbd8
+  metadata.gz: 264c327667ef20d85443754756deb911e5f4e2cd434f98d19c60f12c8394bf4a5ff7a3f55361bc59df701be9b3788670f97710ddc7fb09de11298b158f538483
+  data.tar.gz: e2c11dbf7feaf586543b4bb7a6a746ab99d1fa207a10ad80aa008da787f95916cc0659188e3809e45fca8d0a367942b3f53632a7e190b9070b6d87aaf7277c82

data/README.md

@@ -22,17 +22,131 @@ Or install it yourself as:
 
 ## Usage
 
+### Setup
+
+The `hstore_accessor` method accepts the name of the hstore column you'd
+like to use and a hash with keys representing fields and values
+indicating the type to be stored in that field.  The available types
+are: `string`, `integer`, `float`, `array`, and `hash`.
+
 ```ruby
 class Product < ActiveRecord::Base
 
   hstore_accessor :options,
     color: :string,
     weight: :integer,
-    
+    price: :float,
+    tags: :array,
+    ratings: :hash
+
+end
+```
+
+Now you can interact with the fields stored in the hstore directly.
+
+```ruby
+p = Product.new
+p.color = "green"
+p.weight = 34
+p.price = 99.95
+p.tags = ["housewares", "kitchen"]
+p.ratings = { user_a: 3, user_b: 4 }
+```
+
+Reading these fields works as well.
+
+```ruby
+p.color #=> "green
+p.tags #=> ["housewares", "kitchen"] 
+```
+
+### Scopes
+
+The `hstore_accessor` macro also creates scopes for `string`, `integer`,
+`float`, and `array` fields.
+
+For `string` types, a `with_<key>` scope is created which checks for
+equality.
+
+```ruby
+Product.with_color("green")
+```
+
+For `integer` and `float` types five scopes are created:
+
+```ruby
+Product.price_lt(240.00)    # price less than
+Product.price_lte(240.00)   # price less than or equal to
+Product.price_eq(240.00)    # price equal to
+Product.price_gte(240.00)   # price greater than or equal to
+Product.price_gt(240.00)    # price greater than
+```
+
+For `array` types, two scopes are created:
+
+```ruby
+Product.tags_eq(["housewares", "kitchen"])        # tags equaling
+Product.tags_contains("kitchen")                  # tags containing a single value
+Product.tags_contains(["housewares", "kitchen"])  # tags containing a number of values
+```
 
+### Single-table Inheritance
+
+One of the big issues with `ActiveRecord` single-table inheritance (STI)
+is sparse columns.  Essentially, as sub-types of the original table
+diverge further from their parent more columns are left empty in a given
+table.  Postgres' `hstore` type provides part of the solution in that
+the values in an `hstore` column does not impose a structure - different
+rows can have different values.
+
+We set up our table with an hstore field:
+
+```ruby
+# db/migration/<timestamp>_create_players_table.rb
+class CreateVehiclesTable < ActiveRecord::Migration
+  def change
+    create_table :vehicles do |t|
+      t.string :make
+      t.string :model
+      t.integer :model_year
+      t.string :type
+      t.hstore :data
+    end
+  end
 end
 ```
 
+And for our models:
+
+```ruby
+# app/models/vehicle.rb
+class Player < ActiveRecord::Base
+end
+
+# app/models/vehicles/automobile.rb
+class Automobile < Vehicle
+  hstore_accessor :data,
+    axle_count: :integer,
+    weight: :float,
+    engine_details: :hash
+end
+
+# app/models/vehicles/airplane.rb
+class Airplane < Vehicle
+  hstore_accessor :data,
+    engine_type: :string,
+    safety_rating: :integer,
+    features: :hash
+end
+```
+
+From here any attributes specific to any sub-class can be stored in the
+`hstore` column avoiding sparse data.  Indices can also be created on
+individual fields in an `hstore` column.
+
+This approach was originally concieved by Joe Hirn in [this blog
+post](http://www.devmynd.com/blog/2013-3-single-table-inheritance-hstore-lovely-combination).
+
 ## Contributing
 
 1. Fork it

data/lib/hstore_accessor/version.rb

@@ -1,3 +1,3 @@
 module HstoreAccessor
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hstore_accessor
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Joe Hirn
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-08 00:00:00.000000000 Z
+date: 2013-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg