uuids 0.2.0 → 1.0.0.pre.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5e74d457a60d98ff3a145f6a6a1833f2075983af
-  data.tar.gz: 6ff0c0939c243ef4648edb145a5d6f5b3b9cab3b
+  metadata.gz: 716ef7b1e74c7adf9fd9d29302aa0ad0b2ba6c74
+  data.tar.gz: 6086c3c5ece7db6730ef17aa814373789ea03189
 SHA512:
-  metadata.gz: 8d4b2414ae87ce041c34248cb76c4e382072d2e20f5e1b54c86a884b5cb488bc703acf02220a8012fb8f3bb080dac55801a779147c67cd73567375ee182016fa
-  data.tar.gz: 168e82b3e79766a35e814ccb6660f35d4a82d277a8a9a23030936099faa4aa4c631a748beceadb5f72766dd1293b2c50662f2f9b4729106634faf645aabd8499
+  metadata.gz: bc6c1947993bddd20aae7128f7be6987032bb7018e073a48c841a69ba4208ffdb20b854c2dec71d583a6f95b76ca2b35e944b7567e1050a2210a7946e8cf04af
+  data.tar.gz: 9a663e80d1b08d164eeb9a3ecab76fb5bf3d1051cecb579360bbae7333bf710fa87169d477f829133761012d4694c0665d5bbe555389dec0d9cacc57e3f8e43a

data/.rubocop.yml

@@ -11,6 +11,10 @@ Lint/RescueException:
   Exclude:
     - 'spec/**/*'
 
+Metrics/MethodLength:
+  Exclude:
+    - 'db/**/*'
+
 Style/AccessorMethodName:
   Exclude:
     - 'spec/**/*'
@@ -31,9 +35,8 @@ Style/EmptyLineBetweenDefs:
   Exclude:
     - 'spec/**/*'
 
-Metrics/MethodLength:
-  Exclude:
-    - 'db/**/*'
+Style/PredicateName:
+  Enabled: false
 
 Style/RaiseArgs:
   EnforcedStyle: compact

data/README.rdoc

@@ -9,53 +9,44 @@
 
 == About
 
-Defines a model +Uuid+ to store {UUIDs}[http://en.wikipedia.org/wiki/Universally_Unique_Identifier] assigned to various AR records.
+The gem adds addressing ActiveRecord objects by {UUID}[http://en.wikipedia.org/wiki/Universally_Unique_Identifier]s following the {RFC4122}[http://www.ietf.org/rfc/rfc4122.txt]
+standard.
 
-It is expected any uuid is assigned to one record, but a record can be
-identified by many uuids.
-
-The gem is a {mountable Rails engine}[http://guides.rubyonrails.org/engines.html#generating-an-engine].
-
-The gem provides:
+It provides:
 
 <tt>Uuids::Uuid</tt>:: A model of UUIDs associated with various records.
-<tt>Uuids::Base</tt>:: A module to be included to AR model to provide required +#uuids+ attribute.
+<tt>Uuids::Base</tt>:: A module provides ActiveRecord class helpers +has_uuids+ and +has_many+ (with <tt>uuid: true</tt> option).
+
+The gem is a {mountable Rails engine}[http://guides.rubyonrails.org/engines.html#generating-an-engine].
 
 === Pattern
 
-This model allows refering records by some uuid (not the id).
+This model allows adressing records by some UUID (not the ID).
+It is expected any UUID is assigned to one record, but a record can be
+identified by many UUIDs.
 
 If necessary any referred record can be merged with another one.
-If you reassign all their uuids to merged record then any references remains
-valid without tracking and changing them before merge.
-
-A uuid should be neither deleted, no changed. It can only be reassigned to
-another resource. The records can be deleted 
+All you need is to reassign all UUIDs to merged record and outer associations
+remains valid.
 
-* by merging to another ones;
-* by explicitly marking as deleted without physical removal.
+A **UUID** should be neither deleted, no changed. It can only be reassigned to
+another resource. On ther other hand, the outer record should be merged to
+another one (reassign UUIDs) to prevent existance of UUIDs assigned to nothing.
 
 === Example
 
 Suppose you have models referred to cities. One day you discover
-a duplication among cities: the "New York" and the "NEW YORK".
+a duplication among two cities: the "New York" and the "NEW YORK".
 
 You should:
 
-* reassign both uuids to "New York";
+* reassign both UUIDs to "New York";
 * safely remove the "NEW YORK" record.
 
 You needn't track all records that refer to "NEW YORK". All those references
-will authomatically lead to merged record via old uuid.
-
-=== Standards
+will authomatically lead to merged record via old UUID.
 
-The Uuid is generated authomatically following the
-{RFC4122}[http://www.ietf.org/rfc/rfc4122.txt] standard. The generation uses the
-+sequrerandom+ Ruby library.
-
-This allows keeping all uuids in one model and referring to any record whatever
-type it has.
+Now the model of cities should **know nothing about outer models** that use it.
 
 === Translations
 
@@ -76,90 +67,101 @@ Or install it yourself as:
 
     $ gem install uuids
 
+== Initialization
+
+To initialize the module you need to copy and run uuid's db migrations.
+
 === Rails application
 
 Run from a command line in application root:
 
     $ rake uuids:install
 
-This will copy gem migrations to a `db/migrate` folder and run it.
-
 === Rails mountable engine
 
 Run from a command line in application root:
 
     $ rake app:uuids:install
 
-This will copy gem migrations to a `spec/dummy/db/migrate` folder and run it.
-
 == Usage
 
+=== Adding UUIDs identifiers
+
 Add the assotiation to your AR model:
 
-    class YourModel < ActiveRecord::Base
+    class City < ActiveRecord::Base
+      include Uuids::Base
+      has_uuids
+    end
 
-      # declares the association
-      has_many :uuids, class_name: "Uuids::Uuid", as: :record, validate: false
+This will add methods:
 
-      # auto-generates uuid by default
-      before_create  -> { uuids.present? || uuids.new }
++#uuids+:: List of <tt>Uuids::Uuid</tt> objects referred to the record.
++#uuid+:: main UUID for the record - a value of the first +uuids+ object.
+<tt>.by_uuid</tt>:: A scope for unique records by UUID: <tt>City.by_uuid</tt>
 
-      # prevents the record from being unreferable
-      validates :uuids, presence: true, on: :update
+The first uuid is added by default. It can also be set manually:
+    
+    # UUID is generated by default
+    city = City.new
+    city.save!
 
-      # prevents a record destruction before its uuids reassigned to another one
-      before_destroy -> { uuids.blank? }
-    end
+    # UUID is assigned manually
+    city = City.new
+    city.uuids.new value: "6d9456a9-8f54-4ff7-ba0d-9854f1954417"
+    city.save
 
-Instead of above you can simply include the Uuids::Base module:
+The destruction of object is forbidden if it has a +uuid+. You should reassign
+all object's UUIDs to another object in advance.
 
-    class YourModel < ActiveRecord::Base
-      include Uuids::Base
-    end
+=== Referring model by UUID [TODO]
 
-Now you can refer to your model via uuid:
+Instead of <tt>ActiveRecord::Associations</tt> +belongs_to+, +has_one+ and
++has_many+, you should define custom methods by <tt>ActiveRecord::Relation</tt>
+explicitly.
 
-    class CreateAnotherModelTable < ActiveRecord::Migration
+    class CreateStreetsTable < ActiveRecord::Migration
       def change
-        create_table :another_models do |t|
-          t.string :your_model_uuid, limit: 36
+        create_table :streets do |t|
+          t.string :city_uuid, limit: 36
         end
-        add_index :another_models, :your_model_uuid
+        add_index :streets_table, :city_uuid
       end
     end
 
-    class AnotherModel < ActiveRecord::Base
+    class Street < ActiveRecord::Base
 
-      def your_model
-        @your_model ||= YourModel.join(:uuids)
-          .where(uuids_uuids: { value: your_model_uuid }).first
+      scope :by_city, ->(city) { City.by_uuid(city.uuid) }
+
+      def city
+        @city ||= City.by_uuid(city_uuid)
       end
 
-      def your_model=(record)
-        @your_model_uuid ||= Uuids::Uuid.find_by_record(record).try(:value)
+      def city=(city)
+        read_attribute :city_uuid, city.uuid
       end
     end
 
 == Uninstallation
 
+To uninstall the module you need to:
+
+* rollback and remove uuid's migration;
+* remove all lines containing <tt>include Uuids::Base</tt>, +has_uuids+ and <tt>by_uuid: true</tt> from any model;
+* remove the gem dependencies from application's +Gemfile+ and gemspec.
+
 === Rails app
 
 Run from a command line in application root:
 
     $ rake uuids:uninstall
 
-This will rollback and remove migration from `db/migrate` folder and then
-remove the gem dependencies from application's +Gemfile+ and gemspec.
-
 === Rails mountable engine
 
 Run from a command line in engine root:
 
     $ rake app:uuids:uninstall
 
-This will rollback and remove migration from `spec/dummy/db/migrate` folder and
-then remove the gem dependencies from engine's +Gemfile+ and gemspec.
-
 == Contributing
 
 1. Fork it ( https://github.com/nepalez/uuids/fork )
@@ -168,17 +170,6 @@ then remove the gem dependencies from engine's +Gemfile+ and gemspec.
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
 
-== TODO
-
-Redefine AR::Base class methods +has_one+ and +has_many+ to allow reference
-by uuid:
-
-    class MyModel < ActiveRecord::Base
-      include Uuids::Associations
-
-      has_one :another_model, uuid: true
-    end
-
 == License
 
 The plugin is distributed under {MIT license}[https://github.com/nepalez/uuids/blob/master/LICENSE.rdoc]

data/lib/tasks/uuids_tasks.rake

@@ -14,18 +14,17 @@ namespace :uuids do
 
   def remove_gem
     say "Removing the 'uuids' gem" do
-      remove_from_file "Gemfile", /gem\s+["|']uuids["|']/
-      Dir["*.gemspec"].each do |gemspec|
-        remove_from_file gemspec, /_dependency\s+["|']uuids["|']/
-      end
+      GEMFILE = /gem\s+["|']uuids["|']/
+      GEMSPEC = /_dependency\s+["|']uuids["|']/
+      remove_from_file "Gemfile", GEMFILE
+      Dir["*.gemspec"].each { |file| remove_from_file file, GEMSPEC }
     end
   end
 
   def remove_from_file(name, regex)
     say_with_time name do
-      temp = File.read(name).split("\n")
-        .reject { |line| line[regex] }.join("\n")
-      File.write(name, temp)
+      temp = File.read(name).split("\n").reject { |line| line[regex] }.join "\n"
+      File.write name, temp
     end
   end
 

data/lib/uuids/base.rb

@@ -2,25 +2,61 @@ module Uuids
 
   # Creates required `#uuids` attribute of the ActiveRecord model.
   module Base
+    extend ActiveSupport::Concern
 
+    # Prevents the module usage outside an ActiveRecord model.
+    #
+    #   class Text < String
+    #     include Uuids::Base
+    #   end
+    #   # => raises a TypeError
+    #
     def self.included(klass)
-      fail unless klass.ancestors.include? ActiveRecord::Base
+      unless klass.ancestors.include? ActiveRecord::Base
+        fail TypeError.new("#{ klass.name } isn't an ActiveRecord model.")
+      end
+    end
 
-      klass.has_many :uuids, uuids_params
+    # Methods added to the ActiveRecord model.
+    module ClassMethods
 
-      klass.before_create  :add_default_uuid
-      klass.before_destroy :prevent_destruction
+      private
 
-      klass.validates :uuids, presence: true, on: :update
-    end
+      # Declares:
+      #
+      # * +uuids+ association attribute;
+      # * +uuid+ method (string);
+      # * <tt>uuid</tt> relation scope.
+      #
+      def has_uuids
+        define_uuids
+        define_uuid_getter
+        define_scope
+      end
 
-    private
+      # Defines the +uuids+ association attribute;
+      def define_uuids
+        has_many :uuids, class_name: "Uuids::Uuid", as: :record, validate: false
+        before_create  :add_default_uuid
+        before_destroy :prevent_destruction
+        validates :uuids, presence: true, on: :update
+      end
 
-    # Parameters for uuid associations
-    def self.uuids_params
-      { class_name: "Uuids::Uuid", as: :record, validate: false }
+      # Defines the +uuid+ method
+      def define_uuid_getter
+        class_eval "def uuid; uuids.first.try(:value); end"
+      end
+
+      # Defines the <tt>uuid</tt> relation scope.
+      def define_scope
+        scope :by_uuid, ->(value) {
+          joins(:uuids).where(uuids_uuids: { value: value }).uniq
+        }
+      end
     end
 
+    private
+
     # Creates the uuids by default preventing a record from being ureferrable
     def add_default_uuid
       uuids.present? || uuids.new

data/lib/uuids/version.rb

@@ -2,5 +2,5 @@
 module Uuids
 
   # Current release.
-  VERSION = "0.2.0"
+  VERSION = "1.0.0-rc1"
 end

data/spec/dummy/app/models/city.rb

@@ -0,0 +1,5 @@
+require "uuids"
+
+class City < ActiveRecord::Base
+  include Uuids::Base
+end

data/spec/dummy/db/migrate/20141017081115_create_cities.rb

@@ -0,0 +1,8 @@
+class CreateCities < ActiveRecord::Migration
+  def change
+    create_table :cities do |t|
+
+      t.timestamps
+    end
+  end
+end

data/spec/dummy/db/schema.rb

@@ -13,7 +13,7 @@
 
 ActiveRecord::Schema.define(version: 20141017081115) do
 
-  create_table "items", force: true do |t|
+  create_table "cities", force: true do |t|
     t.datetime "created_at"
     t.datetime "updated_at"
   end