anchormodel 0.1.0 → 0.1.2

data/doc/index.html

@@ -89,7 +89,14 @@
 
 <p>This is why Anchormodel is strictly relying on String keys corresponding to the entries of an Anchormodel.</p>
 
-<h1 id="label-Example">Example</h1>
+<h1 id="label-Installation">Installation</h1>
+<ol><li>
+<p>Add gem to Gemfile: <code>gem &#39;anchormodel&#39;</code></p>
+</li><li>
+<p>In <code>application_record.rb</code>, add in the class body: <code>include Anchormodel::ModelMixin</code></p>
+</li></ol>
+
+<h1 id="label-Basic+example">Basic example</h1>
 
 <p><code>app/anchormodels/role.rb</code>:</p>
 
@@ -116,7 +123,11 @@
 
 <pre class="code ruby"><code class="ruby"><span class='comment'># The DB table `users` must have a String column `users.role`
 </span><span class='kw'>class</span> <span class='const'>User</span> <span class='op'>&lt;</span> <span class='const'>ApplicationRecord</span>
-  <span class='id identifier rubyid_belongs_to_anchormodel'>belongs_to_anchormodel</span> <span class='symbol'>:role</span>
+  <span class='comment'># If `users.role` has an `NOT NULL` constraint, use:
+</span>  <span class='id identifier rubyid_belongs_to_anchormodel'>belongs_to_anchormodel</span> <span class='symbol'>:role</span>
+
+  <span class='comment'># If `users.role` can be `NULL`, use the following instead:
+</span>  <span class='id identifier rubyid_belongs_to_anchormodel'>belongs_to_anchormodel</span> <span class='symbol'>:role</span><span class='comma'>,</span> <span class='label'>optional:</span> <span class='kw'>true</span>
 <span class='kw'>end</span>
 </code></pre>
 
@@ -135,18 +146,89 @@
 
 <span class='comment'># Pretty print a user&#39;s role, e.g. using the Rails FastGettext gem:
 </span><span class='id identifier rubyid_puts'>puts</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>User </span><span class='embexpr_beg'>#{</span><span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_name'>name</span><span class='embexpr_end'>}</span><span class='tstring_content'> has role </span><span class='embexpr_beg'>#{</span><span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_role'>role</span><span class='period'>.</span><span class='id identifier rubyid_label'>label</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
-</code></pre>
 
-<h1 id="label-Installation">Installation</h1>
-<ol><li>
-<p>Add gem to Gemfile: <code>gem &#39;anchormodel&#39;</code></p>
+<span class='comment'># Check whether @user has role admin
+</span><span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_role'>role</span><span class='period'>.</span><span class='id identifier rubyid_admin?'>admin?</span> <span class='comment'># true if and only if the role is admin (false otherwise)
+</span></code></pre>
+
+<h1 id="label-Rails+Enum+style+model+methods">Rails Enum style model methods</h1>
+
+<p>By default, Anchormodel adds three kinds of methods for each key to the model:</p>
+<ul><li>
+<p>a reader (getter)</p>
 </li><li>
-<p>In <code>application_record.rb</code>, add in the class body: <code>include Anchormodel::ModelMixin</code></p>
-</li></ol>
+<p>a writer (setter)</p>
+</li><li>
+<p>a Rails scope</p>
+</li></ul>
+
+<p>For instance:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>User</span> <span class='op'>&lt;</span> <span class='const'>ApplicationRecord</span>
+  <span class='id identifier rubyid_belongs_to_anchormodel'>belongs_to_anchormodel</span> <span class='symbol'>:role</span> <span class='comment'># where Role has keys :guest, :manager and :admin
+</span>  <span class='id identifier rubyid_belongs_to_anchormodel'>belongs_to_anchormodel</span> <span class='symbol'>:shape</span> <span class='comment'># where Shape has keys :circle and :rectangle
+</span><span class='kw'>end</span>
+
+<span class='comment'># User now implements the following methods, given that @user is retrieved as follows:
+</span><span class='ivar'>@user</span> <span class='op'>=</span> <span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span> <span class='comment'># for example
+</span>
+<span class='comment'># Readers
+</span><span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_guest?'>guest?</span> <span class='comment'># same as @user.role.guest?
+</span><span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_manager?'>manager?</span>
+<span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_admin?'>admin?</span>
+<span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_rectangle?'>rectangle?</span> <span class='comment'># same as @user.shape.rectangle?
+</span><span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_circle?'>circle?</span>
+<span class='comment'># Writers
+</span><span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_guest!'>guest!</span> <span class='comment'># same as @user.role = Role.find(:guest)
+</span><span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_manager!'>manager!</span>
+<span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_admin!'>admin!</span>
+<span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_rectangle!'>rectangle!</span> <span class='comment'># same as @user.shape = Shape.find(:rectangle)
+</span><span class='ivar'>@user</span><span class='period'>.</span><span class='id identifier rubyid_circle!'>circle!</span>
+<span class='comment'># Scopes
+</span><span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_guest'>guest</span> <span class='comment'># same as User.where(role: &#39;guest&#39;)
+</span><span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_manager'>manager</span>
+<span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_admin'>admin</span>
+<span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_rectangle'>rectangle</span> <span class='comment'># same as User.where(shape: &#39;rectangle&#39;)
+</span><span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_circle'>circle</span>
+</code></pre>
+
+<p>This behavior is similar as the one from Rails Enums. If you want to disable it, use:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>User</span> <span class='op'>&lt;</span> <span class='const'>ApplicationRecord</span>
+  <span class='id identifier rubyid_belongs_to_anchormodel'>belongs_to_anchormodel</span> <span class='symbol'>:role</span><span class='comma'>,</span> <span class='label'>model_readers:</span> <span class='kw'>false</span><span class='comma'>,</span> <span class='label'>model_writers:</span> <span class='kw'>false</span><span class='comma'>,</span> <span class='label'>model_scopes:</span> <span class='kw'>false</span>
+  <span class='comment'># or, equivalent, to disable all at once:
+</span>  <span class='id identifier rubyid_belongs_to_anchormodel'>belongs_to_anchormodel</span> <span class='symbol'>:role</span><span class='comma'>,</span> <span class='label'>model_methods:</span> <span class='kw'>false</span>
+<span class='kw'>end</span>
+</code></pre>
+
+<h1 id="label-Calling+a+column+differently+than+the+Anchormodel">Calling a column differently than the Anchormodel</h1>
+
+<p>If your column name (and the model’s attribute) is called differently than the Anchormodel, you may give the Anchormodel’s class as the second argument. For example:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='comment'># app/anchormodels/color.rb
+</span><span class='kw'>class</span> <span class='const'>Color</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Anchormodel.html" title="Anchormodel (class)">Anchormodel</a></span></span>
+  <span class='id identifier rubyid_new'>new</span> <span class='symbol'>:green</span>
+  <span class='id identifier rubyid_new'>new</span> <span class='symbol'>:red</span>
+<span class='kw'>end</span>
+
+<span class='comment'># app/models/user.rb
+</span><span class='kw'>class</span> <span class='const'>User</span> <span class='op'>&lt;</span> <span class='const'>ApplicationRecord</span>
+  <span class='id identifier rubyid_belongs_to_anchormodel'>belongs_to_anchormodel</span> <span class='symbol'>:favorite_color</span><span class='comma'>,</span> <span class='const'>Color</span>
+<span class='kw'>end</span>
+</code></pre>
+
+<h2 id="label-Having+multiple+attributes+to+the+same+Anchormodel">Having multiple attributes to the same Anchormodel</h2>
+
+<p>If you want to have multiple attributes in the same model pointing to the same Anchormodel, you need to disable <code>model_methods</code> for at least one of them (otherwise the model methods will clash in your model class):</p>
+
+<pre class="code ruby"><code class="ruby"><span class='comment'># app/models/user.rb
+</span>  <span class='id identifier rubyid_belongs_to_anchormodel'>belongs_to_anchormodel</span> <span class='symbol'>:role</span>
+  <span class='id identifier rubyid_belongs_to_anchormodel'>belongs_to_anchormodel</span> <span class='symbol'>:secondary_role</span><span class='comma'>,</span> <span class='const'>Role</span><span class='comma'>,</span> <span class='label'>model_methods:</span> <span class='kw'>false</span>
+</code></pre>
 </div></div>
 
       <div id="footer">
-  Generated on Wed Jan 18 11:24:43 2023 by
+  Generated on Wed Jan 25 12:36:39 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.28 (ruby-3.1.3).
 </div>

data/doc/method_list.html

@@ -62,7 +62,7 @@
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Anchormodel/Attribute.html#anchor_class-instance_method" title="Anchormodel::Attribute#anchor_class (method)">#anchor_class</a></span>
+      <span class='object_link'><a href="Anchormodel/Attribute.html#anchormodel_class-instance_method" title="Anchormodel::Attribute#anchormodel_class (method)">#anchormodel_class</a></span>
       <small>Anchormodel::Attribute</small>
     </div>
   </li>

data/doc/top-level-namespace.html

@@ -100,7 +100,7 @@
 </div>
 
       <div id="footer">
-  Generated on Wed Jan 18 11:24:43 2023 by
+  Generated on Wed Jan 25 12:36:39 2023 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.28 (ruby-3.1.3).
 </div>

data/lib/anchormodel/active_model_type_value.rb

@@ -11,13 +11,14 @@ class Anchormodel::ActiveModelTypeValue < ActiveModel::Type::Value
 
   # Implementing this instead of cast to force key validation in any case
   def serialize(value)
+    value = value.presence
     return case value
            when Symbol, String
-             unless @attribute.anchor_class.valid_keys.include?(value.to_sym)
+             unless @attribute.anchormodel_class.valid_keys.include?(value.to_sym)
                fail("Attempt to set #{@attribute.attribute_name} to unsupported key #{value.inspect}.")
              end
              value.to_s
-           when @attribute.anchor_class
+           when @attribute.anchormodel_class
              value.key.to_s
            when nil
              nil
@@ -27,8 +28,9 @@ class Anchormodel::ActiveModelTypeValue < ActiveModel::Type::Value
   end
 
   def deserialize(value)
-    return value if value.is_a?(@attribute.anchor_class)
-    return @attribute.anchor_class.find(value)
+    value = value.presence
+    return value if value.is_a?(@attribute.anchormodel_class)
+    return @attribute.anchormodel_class.find(value)
   end
 
   def changed?(old_value, new_value, _new_value_before_type_cast)

data/lib/anchormodel/attribute.rb

@@ -3,22 +3,17 @@
 # It is instanciated when {Anchormodel::ModelMixin#belongs_to_anchormodel} is used.
 class Anchormodel::Attribute
   attr_reader :attribute_name
+  attr_reader :anchormodel_class
   attr_reader :optional
 
   # @param model_class [ActiveRecord::Base] The Rails model where {Anchormodel::ModelMixin#belongs_to_anchormodel} is used
   # @param attribute_name [String,Symbol] The name and database column of the attribute
-  # @param anchor_class_name [String] Name of the Anchormodel class (omit if attribute `:foo_bar` holds an `FooBar`)
+  # @param anchormodel_class [Class] Class of the Anchormodel (omit if attribute `:foo_bar` holds an `FooBar`)
   # @param optional [Boolean] If true, a presence validation is added to the model.
-  def initialize(model_class, attribute_name, anchor_class_name = nil, optional = false)
+  def initialize(model_class, attribute_name, anchormodel_class = nil, optional = false)
     @model_class = model_class
     @attribute_name = attribute_name.to_sym
-    @anchor_class_name = anchor_class_name || attribute_name.to_s.classify
+    @anchormodel_class = anchormodel_class
     @optional = optional
   end
-
-  # Getter for the Anchormodel class based on the name passed to the initializer.
-  # We are loading the anchor class lazily, because the model mixin instanciates this statically -> avoid premature anchor class loading
-  def anchor_class
-    @anchor_class ||= @anchor_class_name.constantize
-  end
 end

data/lib/anchormodel/model_mixin.rb

@@ -11,11 +11,24 @@ module Anchormodel::ModelMixin
     # Creates an attribute linking to an Anchormodel. The attribute should be
     # present in the DB and the column should be named the same as `attribute_name.`
     # @param attribute_name [String,Symbol] The name and database column of the attribute
-    # @param anchor_class_name [String] Name of the Anchormodel class (omit if attribute `:foo_bar` holds a `FooBar`)
+    # @param anchormodel_class [Class] Class of the Anchormodel (omit if attribute `:foo_bar` holds a `FooBar`)
     # @param optional [Boolean] If true, a presence validation is added to the model.
-    def belongs_to_anchormodel(attribute_name, anchor_class_name = nil, optional: false)
+    # @param model_readers [Boolean] If true, the model is given an ActiveRecord::Enum style method `my_model.my_key?` reader for each key in the anchormodel
+    # @param model_writers [Boolean] If true, the model is given an ActiveRecord::Enum style method `my_model.my_key!` writer for each key in the anchormodel
+    # @param model_scopes [Boolean] If true, the model is given an ActiveRecord::Enum style scope `MyModel.mykey` for each key in the anchormodel
+    # @param model_methods [Boolean, NilClass] If non-nil, this mass-assigns and overrides `model_readers`, `model_writers` and `model_scopes`
+    def belongs_to_anchormodel(attribute_name, anchormodel_class = nil, optional: false, model_readers: true,
+                               model_writers: true, model_scopes: true, model_methods: nil)
+      anchormodel_class ||= attribute_name.to_s.classify.constantize
       attribute_name = attribute_name.to_sym
-      attribute = Anchormodel::Attribute.new(self, attribute_name, anchor_class_name, optional)
+      attribute = Anchormodel::Attribute.new(self, attribute_name, anchormodel_class, optional)
+
+      # Mass configurations if model_methods was specfied
+      unless model_methods.nil?
+        model_readers = model_methods
+        model_writers = model_methods
+        model_scopes = model_methods
+      end
 
       # Register attribute
       self.anchormodel_attributes = anchormodel_attributes.merge({ attribute_name => attribute }).freeze
@@ -41,6 +54,43 @@ module Anchormodel::ModelMixin
 
       # Supply serializer and deserializer
       attribute attribute_name, active_model_type_value
+
+      # Create ActiveRecord::Enum style reader directly in the model if asked to do so
+      # For a model User with anchormodel Role with keys :admin and :guest, this creates user.admin? and user.guest? (returning true iff role is admin/guest)
+      if model_readers
+        anchormodel_class.all.each do |entry|
+          if respond_to?(:"#{entry.key}?")
+            fail("Anchormodel reader #{entry.key}? already defined for #{self}, add `model_readers: false` to `belongs_to_anchormodel :#{attribute_name}`.")
+          end
+          define_method(:"#{entry.key}?") do
+            public_send(attribute_name.to_s) == entry
+          end
+        end
+      end
+
+      # Create ActiveRecord::Enum style writer directly in the model if asked to do so
+      # For a model User with anchormodel Role with keys :admin and :guest, this creates user.admin! and user.guest! (setting the role to admin/guest)
+      if model_writers
+        anchormodel_class.all.each do |entry|
+          if respond_to?(:"#{entry.key}!")
+            fail("Anchormodel writer #{entry.key}! already defined for #{self}, add `model_writers: false` to `belongs_to_anchormodel :#{attribute_name}`.")
+          end
+          define_method(:"#{entry.key}!") do
+            public_send(:"#{attribute_name}=", entry)
+          end
+        end
+      end
+
+      # Create ActiveRecord::Enum style scope directly in the model class if asked to do so
+      # For a model User with anchormodel Role with keys :admin and :guest, this creates user.admin! and user.guest! (setting the role to admin/guest)
+      if model_scopes
+        anchormodel_class.all.each do |entry|
+          if respond_to?(entry.key)
+            fail("Anchormodel scope #{entry.key} already defined for #{self}, add `model_scopes: false` to `belongs_to_anchormodel :#{attribute_name}`.")
+          end
+          scope(entry.key, -> { where(attribute_name => entry.key) })
+        end
+      end
     end
   end
 end

data/lib/anchormodel/version.rb

@@ -2,7 +2,7 @@ class Anchormodel
   module Version
     MAJOR = 0
     MINOR = 1
-    PATCH = 0
+    PATCH = 2
 
     EDGE = false
 

data/lib/anchormodel.rb

@@ -52,6 +52,11 @@ class Anchormodel
 
     # Register valid keys
     valid_keys << key
+
+    # Define boolean reader
+    self.class.define_method(:"#{key}?") do
+      @key == key
+    end
   end
 
   def ==(other)

data/test/active_record_model/user_test.rb

@@ -1,6 +1,10 @@
 class UserTest < Minitest::Test
   def setup; end
 
+  def teardown
+    User.destroy_all
+  end
+
   def test_retrieval
     assert_equal Role.find(:guest), Role.find('guest')
   end
@@ -17,7 +21,11 @@ class UserTest < Minitest::Test
     )
   end
 
-  def test_setters_and_getters
+  def test_missing_key
+    assert_raises { Role.find(:does_not_exist) }
+  end
+
+  def test_basic_setters_and_getters
     u = User.create!(role: 'guest', locale: 'de') # String assignment
     assert_equal Role.find(:guest), u.role
     assert_equal Locale.find(:de), u.locale
@@ -45,7 +53,69 @@ class UserTest < Minitest::Test
   def test_custom_comparison
     assert_equal(-1, Role.find(:moderator) <=> Role.find(:admin))
     assert_equal(1, Role.find(:moderator) <=> Role.find(:guest))
-    assert_equal(0, Role.find(:moderator) <=> Role.find(:moderator))
+    assert_equal(0, Role.find(:moderator) <=> Role.find('moderator'))
     assert Role.find(:moderator) < Role.find(:admin)
   end
+
+  def test_presence_validation
+    valentine = User.new
+    assert_raises(ActiveRecord::RecordInvalid) { valentine.save! }
+  end
+
+  def test_alternative_column_name
+    ben = User.create!(
+      role:           Role.find(:moderator),
+      secondary_role: Role.find(:admin),
+      locale:         Locale.find(:de)
+    )
+    assert_equal(Role.find(:moderator), ben.role)
+    assert_equal(Role.find(:admin), ben.secondary_role)
+    assert_equal(Locale.find(:de), ben.locale)
+  end
+
+  def test_optional_attribute
+    jenny = User.create!(role: :admin, locale: :en)
+    assert_nil jenny.secondary_role
+  end
+
+  def test_model_readers_and_writers
+    pia = User.new
+    pia.admin!
+    assert_equal true, pia.admin?
+    assert_equal false, pia.guest?
+    assert_equal Role.find(:admin), pia.role
+  end
+
+  def test_model_scopes
+    User.create!(role: :admin, locale: :en)
+    User.create!(role: :admin, locale: :en)
+    User.create!(role: :moderator, locale: :en)
+    assert_equal 2, User.admin.count
+    assert_equal 1, User.moderator.count
+    assert_equal 0, User.guest.count
+  end
+
+  def test_model_readers_writers_with_different_class_name
+    pia = User.new(locale: :en)
+    pia.de!
+    assert_equal true, pia.de?
+    assert_equal false, pia.fr?
+    assert_equal Locale.find(:de), pia.preferred_locale
+    assert_equal Locale.find(:en), pia.locale
+  end
+
+  def test_model_scopes_with_different_class_name
+    User.create!(role: :admin, locale: :en, preferred_locale: :de)
+    User.create!(role: :admin, locale: :en, preferred_locale: :de)
+    User.create!(role: :admin, locale: :en, preferred_locale: :fr)
+    assert_equal 2, User.de.count
+    assert_equal 1, User.fr.count
+    assert_equal 0, User.en.count
+  end
+
+  def test_rails_blank_assignment
+    u = User.new(role: :admin, secondary_role: :admin, locale: :en, preferred_locale: :en)
+    u.secondary_role = ''
+    assert_nil u.secondary_role
+  end
 end

data/test/dummy/app/models/user.rb

@@ -1,4 +1,6 @@
 class User < ApplicationRecord
   belongs_to_anchormodel :role
-  belongs_to_anchormodel :locale
+  belongs_to_anchormodel :secondary_role, Role, optional: true, model_readers: false, model_writers: false, model_scopes: false
+  belongs_to_anchormodel :locale, model_methods: false
+  belongs_to_anchormodel :preferred_locale, Locale
 end

data/test/dummy/db/migrate/20230107173151_create_users.rb

@@ -2,7 +2,9 @@ class CreateUsers < ActiveRecord::Migration[7.0]
   def change
     create_table :users do |t|
       t.string :role
+      t.string :secondary_role
       t.string :locale
+      t.string :preferred_locale, null: false, default: :en
 
       t.timestamps
     end

data/test/dummy/db/schema.rb

@@ -10,12 +10,13 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[7.0].define(version: 2023_01_07_173151) do
-  create_table "users", force: :cascade do |t|
-    t.string "role"
-    t.string "locale"
-    t.datetime "created_at", null: false
-    t.datetime "updated_at", null: false
+ActiveRecord::Schema[7.0].define(version: 20_230_124_084_241) do
+  create_table 'users', force: :cascade do |t|
+    t.string 'role'
+    t.string 'locale'
+    t.datetime 'created_at', null: false
+    t.datetime 'updated_at', null: false
+    t.string 'secondary_role'
+    t.string 'preferred_locale', default: 'en', null: false
   end
-
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: anchormodel
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Sandro Kalbermatter
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-18 00:00:00.000000000 Z
+date: 2023-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -166,6 +166,7 @@ files:
 - README.md
 - Rakefile
 - anchormodel.gemspec
+- bin/rails
 - doc/Anchormodel.html
 - doc/Anchormodel/ActiveModelTypeValue.html
 - doc/Anchormodel/Attribute.html