detailed 0.0.5 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 28e43c195327231d8e2e93365dff966ebdbc98ef
-  data.tar.gz: 53854de1aef853ca8085cabd40afc707b2ff9c13
+  metadata.gz: 08d3b3c0a6e1ab82b95a455566c1e2b6dcb4d9f6
+  data.tar.gz: 37143a1fa1c5c2f3b02fae20311845e39094077f
 SHA512:
-  metadata.gz: 3247784accccc96c5465a21a0241fb46f102cc54f9b1485b332eee0d16fb6d67580a334f2f36b993add05ffdaaba66db0f7ea32e3fdb45f3c7cbf38e0cda11c9
-  data.tar.gz: 4f78a226d723cc07c99b9df0f2f3f8dfa1f46fc75ecac79f94f6b9df1b57616760d92bc2adc9cbd4a4e887f561f45ea2f7dbf1ca59a71ff03febc7bfff143ea3
+  metadata.gz: 907355ad9a27966bac60f4af6cbfe894f40b916fc1226852fb9997b4782a8227e96e95f7045ed8cc65d0b6251066f501aed86b187e92e44964e9724d2cf2f57c
+  data.tar.gz: 26dddeb82242f3a1b3bc791f07e65c2ba4d9f5f8df2c62e9ac42d8b157da9638c637e5efa655483861aba5f4dc7432d595b9f5b5d736f2dda91796d0495067fa

data/COPYING

@@ -0,0 +1,19 @@
+Copyright (c) 2014 Marcin Łabanowski
+
+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,128 @@
+detailed
+========
+
+Compromise between single and multiple table inheritance with ActiveRecord. This gem doesn't
+depend on Rails at all (that's, in fact, how it originated).
+
+With this gem you can have a table hierarchy like this:
+    user (id, type (class), login, password)
+    |- user_client_details (client_id, billing_address, phone_number)
+    |- user_worker_details (worker_id, wage, bank_account)
+    `- user_supplier_details (supplier_id, company_name)
+
+And models hierarchy like this:
+    ActiveRecord::Base
+    |- User
+    |  |- Client
+    |  |- Worker
+    |  `- Supplier
+    |- UserWorkerDetail
+    |- UserClientDetail
+    `- UserSupplierDetail
+
+All detail classes would look like this (nothing more is needed):
+    UserWorkerDetail < ActiveRecord::Base
+      belongs_to :worker
+    end
+
+The main class should be in this form:
+    class User < ActiveRecord::Base
+      # ... your code here ...
+
+      include Detailed
+    end
+
+The subclasses should be in this form:
+    class Client < User
+      request_details
+
+      # ... your code here ...
+    end
+    
+To add this package to your environment, add the following line to your Gemfile:
+    gem "detailed"
+
+This gem started from this post on StackExchange: http://stackoverflow.com/a/1634734/3256901 .
+
+
+Access to detailed properties
+-----------------------------
+With the tableset above, we can access our variables directly, like
+    client = new Client
+    client.login = "teh1234"              # a field of user
+    client.billing_address = "Zgoda 18/2" # a field of user_client_details
+    client.save
+
+Be aware, that you can't issue find/where with extended fields at the current
+time. You need to resort to the regular:
+    Client.find("details_of_client.billing_address" => "Zgoda 18/2")
+
+
+Subclasses' associations
+------------------------
+Your subclasses can have relations directly, without touching the detail models (even
+though their tables will carry the foreign keys).
+
+Let's suppose, that your Worker has one avatar...
+
+    class Worker < User
+      ...
+      request_details
+      has_one :avarar
+      ...
+    end
+
+On the way back, this is a bit more complicated:
+
+    class Avatar < ActiveRecord::Base
+      ...
+      belongs_to :worker, foreign_key: "user_worker_details.avatar_id"
+      ...
+    end
+
+Please be aware, that the "dot notation" of the foreign key is an extension to
+ActiveRecord provided by this gem.
+
+NB.: Other sorts of associations than has_one are currently untested.
+
+
+N+1 query problem
+-----------------
+This is an optimization problem. When you want to list all your users, casting
+them to appropriate models and fetching their details, you can do:
+    
+    User.all
+
+Unfortunately, this method causes you to do N+1 queries (one for all users, and
+each another one for details). This is because ActiveRecord doesn't know a class
+of a given record in advance.
+
+On the other hand, you can instruct ActiveRecord, that all details will be needed
+by issuing this call:
+
+    User.all_with_details
+
+ActiveRecord will now run 1+m queries, where m is the number of subclasses, so
+for our users it will be 4 queries.
+
+
+Subclasses without details
+--------------------------
+Sometimes you are going to subclass the main model without the need for additional
+fields. This is easy, you just do
+
+class BasicUser < User
+end
+
+No further code needed, detailed won't go into your way.
+
+
+Subclasses of subclasses
+------------------------
+This is currently not tested nor supported, though possible with small changes to
+this code. Patches are welcome.
+
+
+License
+-------
+This code is licensed under the MIT license. See file COPYING for details.

data/lib/detailed.rb

@@ -1,3 +1,24 @@
+# detailed.rb
+# Copyright (c) 2014 Marcin Łabanowski 
+
+# 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.
+
 require "active_record/associations/association_scope.rb"
 
 module Detailed
@@ -180,4 +201,4 @@ end
 
 class ActiveRecord::Associations::AssociationScope
   include Detailed::AssociationScope
-end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: detailed
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.1.0
 platform: ruby
 authors:
 - Marcin Łabanowski
@@ -17,6 +17,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- COPYING
+- README.md
 - lib/detailed.rb
 homepage: http://github.com/czaks/detailed
 licenses: