unit_measurements-rails 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cddde8ae9d387f5c1710542cc3152c2621aae6b2f6c2622a0f0b993ebe315e55
-  data.tar.gz: d68ebeb0acb2dc387fec180d750626f27c345f21a6e65b8181e2de23d946a2af
+  metadata.gz: 5f1843c7f2b52c98319dc2157d86f1028638fcc375e3104551ea79f2954560a4
+  data.tar.gz: 271f1f7c5103ad50e3eddf357cc1456aba6e7219eebeca8768ab7fc5b9bcae9e
 SHA512:
-  metadata.gz: 872c3102f9608149bc7d7983a67684bcbcaac6387a32efdefb1aeeb2214510f25ab00c617e97e2d99675c861d4f29abca2ee88e85f77f5d72abc941064e7c298
-  data.tar.gz: 04b8d2bdd7122990917ffdea05355d2fa7a23e57a91925ddc2b3088745d4a4b5af9042ed45f714d27558894ded5a43196e071f2ca373f5a563e791c97abe45d8
+  metadata.gz: c824399cc26f750e0e5981f39f4ea14ef50e2c1cb6d6c8dbfabf402bea3e06248ed4e48a0787ce015b223c9aa8b52949b15c6527db655bbb47c7b0db2da76957
+  data.tar.gz: 236a331b4812c7598f997f27203f5b1bfaadd8f0f8a9ac667d2d1e454a8f5f46395eb9dfb7590f81443b0a1ae0b3fe83ead51d5d838eba9de70203f39ede554f

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [1.1.0](https://github.com/shivam091/unit_measurements-rails/compare/v1.0.0...v1.1.0) - 2023-11-16
+
+### What's new
+
+- Added ability to define _multiple_ measured attributes at a time.
+- Added wrapper for defining `length` measured attributes.
+- Added wrapper for defining `weight` measured attributes.
+- Added wrapper for defining `volume` measured attributes.
+- Added wrapper for defining `area` measured attributes.
+
+-----------
+
 ## [1.0.0](https://github.com/shivam091/unit_measurements-rails/compare/v0.2.0...v1.0.0) - 2023-11-14
 
 ### What's new

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    unit_measurements-rails (1.0.0)
+    unit_measurements-rails (1.1.0)
       activemodel (>= 7)
       activerecord (>= 7)
       railties (>= 7)

data/README.md

@@ -44,42 +44,74 @@ Or otherwise simply install it yourself as:
 Attribute names are expected to have the `_quantity` and `_unit` suffix, and be `DECIMAL` and `VARCHAR` types, respectively, and defaults values are accepted.
 
 ```ruby
-class AddHeightToThings < ActiveRecord::Migration[7.0]
+class CreateTableCubes < ActiveRecord::Migration[7.0]
   def change
-    add_column :things, :height_quantity, :decimal, precision: 10, scale: 2
-    add_column :things, :height_unit, :string, limit: 12
+    create_table :cubes do |t|
+      t.decimal :length_quantity, precision: 10, scale: 2
+      t.string :length_unit, limit: 12
+      t.decimal :width_quantity, precision: 10, scale: 2
+      t.string :width_unit, limit: 12
+      t.decimal :height_quantity, precision: 10, scale: 2
+      t.string :height_unit, limit: 12
+      t.timestamps
+    end
   end
 end
 ```
 
-A column can be declared as a measurement with its unit group class:
+A column can be declared as a measured with its unit group class:
 
 ```ruby
-class Thing < ActiveRecord::Base
+class Cube < ActiveRecord::Base
   measured UnitMeasurements::Length, :height
 end
 ```
 
-This will allow you to access and assign a measurement object:
+This will allow you to access and assign a measured attribute:
 
 ```ruby
-thing = Thing.new
-thing.height = UnitMeasurements::Length.new(5, "ft")
-thing.height_quantity
-#=> 0.5e1
-thing.height_unit     
-#=> "ft"
-thing.height
-#=> 5.0 ft
+cube = Cube.new
+cube.height = UnitMeasurements::Length.new(5, "ft")
+cube.height_quantity   #=> 0.5e1
+cube.height_unit       #=> "ft"
+cube.height            #=> 5.0 ft
 ```
 
-Order of assignment does not matter, and each attribute can be assigned separately and with mass assignment:
+Order of assignment does not matter, and each attribute can be assigned separately
+and with mass assignment:
 
 ```ruby
 params = {height_quantity: "3", height_unit: "ft"}
-thing = Thing.new(params)
-thing.height
-#=> 3.0 ft
+cube = Cube.new(params)
+cube.height            #=> 3.0 ft
+```
+
+You can specify multiple measured attributes at a time:
+
+```ruby
+class Land < ActiveRecord::Base
+  measured UnitMeasurements::Area, :carpet_area, :buildup_area
+end
+```
+
+There are some simpler methods for predefined types:
+
+```ruby
+class Package < ActiveRecord::Base
+  measured_length :size
+  measured_weight :item_weight, :package_weight
+  measured_area :carpet_area
+  measured_volume :total_volume
+end
+```
+
+This will allow you to access and assign a measurement object:
+
+```ruby
+package = Package.new
+package.item_weight = UnitMeasurements::Weight.new(10, "g")
+package.item_weight_unit       #=> "g"
+package.item_weight_value      #=> 10
 ```
 
 ## Contributing

data/lib/unit_measurements/rails/active_record.rb

@@ -5,55 +5,63 @@
 module UnitMeasurements
   module Rails
     # The +UnitMeasurements::Rails::ActiveRecord+ module enhances ActiveRecord
-    # models by providing a convenient way to handle unit measurements. It allows
-    # you to define measurement attributes in your models with support for
-    # specific unit groups.
+    # models by providing a convenient way to handle unit measurements. It
+    # facilitates defining measurable attributes in models with specific unit
+    # group support.
     #
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
     module ActiveRecord
-      # Defines a reader and writer methods for the measurement attribute in the
-      # +ActiveRecord+ model.
+      # Defines a _reader_ and _writer_ methods for the measured attributes in
+      # the +ActiveRecord+ model.
       #
-      # @example Defining measured attributes:
-      #   class Thing < ActiveRecord::Base
+      # @example Defining single measured attribute:
+      #   class Cube < ActiveRecord::Base
       #     measured UnitMeasurements::Length, :height
       #   end
       #
+      # @example Defining multiple measured attributes:
+      #   class Package < ActiveRecord::Base
+      #     measured UnitMeasurements::Weight, :item_weight, :total_weight
+      #   end
+      #
       # @param [Class|String] unit_group
       #   The unit group class or its name as a string.
-      # @param [String|Symbol] measurement_attr
-      #   The name of the measurement attribute.
+      # @param [Array<String|Symbol>] measured_attrs
+      #   An array of the names of measured attributes.
       # @return [void]
       #
       # @raise [BaseError]
-      #   if unit_group is not a subclass of UnitMeasurements::Measurement.
+      #   If +unit_group+ is not a subclass of +UnitMeasurements::Measurement+.
       #
       # @see BaseError
       # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
       # @since 1.0.0
-      def measured(unit_group, measurement_attr)
+      def measured(unit_group, *measured_attrs)
         unit_group = unit_group.constantize if unit_group.is_a?(String)
 
         validate_unit_group!(unit_group)
 
-        quantity_attr = "#{measurement_attr}_quantity"
-        unit_attr = "#{measurement_attr}_unit"
+        measured_attrs.map(&:to_s).each do |measured_attr|
+          quantity_attr = "#{measured_attr}_quantity"
+          unit_attr = "#{measured_attr}_unit"
 
-        define_measurement_reader(measurement_attr, quantity_attr, unit_attr, unit_group)
-        define_measurement_writer(measurement_attr, quantity_attr, unit_attr, unit_group)
-        redefine_quantity_writer(quantity_attr)
-        redefine_unit_writer(unit_attr, unit_group)
+          define_reader_for_measured_attr(measured_attr, quantity_attr, unit_attr, unit_group)
+          define_writer_for_measured_attr(measured_attr, quantity_attr, unit_attr, unit_group)
+          redefine_quantity_writer(quantity_attr)
+          redefine_unit_writer(unit_attr, unit_group)
+        end
       end
 
       private
 
-      # Validates whether the +unit_group+ is a subclass of +UnitMeasurements::Measurement+.
+      # @private
+      # Validates whether +unit_group+ is a subclass of +UnitMeasurements::Measurement+.
       #
       # @param [Class] unit_group The unit group class to be validated.
       #
       # @raise [BaseError]
-      #   if unit_group is not a subclass of UnitMeasurements::Measurement.
+      #   if +unit_group+ is not a subclass of +UnitMeasurements::Measurement+.
       #
       # @return [void]
       #
@@ -65,9 +73,10 @@ module UnitMeasurements
         end
       end
 
-      # Defines the method to read measurement attribute.
+      # @private
+      # Defines the method to read the measured attribute.
       #
-      # @param [String|Symbol] measurement_attr The name of the measurement attribute.
+      # @param [String] measured_attr The name of the measured attribute.
       # @param [String] quantity_attr The name of the quantity attribute.
       # @param [String] unit_attr The name of the unit attribute.
       # @param [Class] unit_group The unit group class for the measurement.
@@ -76,8 +85,8 @@ module UnitMeasurements
       #
       # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
       # @since 1.0.0
-      def define_measurement_reader(measurement_attr, quantity_attr, unit_attr, unit_group)
-        define_method(measurement_attr) do
+      def define_reader_for_measured_attr(measured_attr, quantity_attr, unit_attr, unit_group)
+        define_method(measured_attr) do
           quantity, unit = public_send(quantity_attr), public_send(unit_attr)
 
           begin
@@ -88,9 +97,10 @@ module UnitMeasurements
         end
       end
 
-      # Defines the method to write measurement attribute.
+      # @private
+      # Defines the method to write the measured attribute.
       #
-      # @param [String|Symbol] measurement_attr The name of the measurement attribute.
+      # @param [String] measured_attr The name of the measured attribute.
       # @param [String] quantity_attr The name of the quantity attribute.
       # @param [String] unit_attr The name of the unit attribute.
       # @param [Class] unit_group The unit group class for the measurement.
@@ -99,8 +109,8 @@ module UnitMeasurements
       #
       # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
       # @since 1.0.0
-      def define_measurement_writer(measurement_attr, quantity_attr, unit_attr, unit_group)
-        define_method("#{measurement_attr}=") do |measurement|
+      def define_writer_for_measured_attr(measured_attr, quantity_attr, unit_attr, unit_group)
+        define_method("#{measured_attr}=") do |measurement|
           if measurement.is_a?(unit_group)
             public_send("#{quantity_attr}=", measurement.quantity)
             public_send("#{unit_attr}=", measurement.unit.name)
@@ -111,7 +121,8 @@ module UnitMeasurements
         end
       end
 
-      # Redefines the writer method to set quantity attribute.
+      # @private
+      # Redefines the writer method to set the quantity attribute.
       #
       # @param quantity_attr [String] The name of the quantity attribute.
       #
@@ -129,13 +140,12 @@ module UnitMeasurements
             quantity.round(scale)
           else
             nil
-          end
-
-          write_attribute(quantity_attr, quantity)
+          end.tap { |value| write_attribute(quantity_attr, value) }
         end
       end
 
-      # Redefines the writer method to set unit attribute.
+      # @private
+      # Redefines the writer method to set the unit attribute.
       #
       # @param unit_attr [String] The name of the unit attribute.
       # @param unit_group [Class] The unit group class for the measurement.
@@ -154,6 +164,8 @@ module UnitMeasurements
   end
 end
 
+# ActiveSupport hook to extend ActiveRecord with the `UnitMeasurements::Rails::ActiveRecord`
+# module.
 ActiveSupport.on_load(:active_record) do
   ::ActiveRecord::Base.send :extend, UnitMeasurements::Rails::ActiveRecord
 end

data/lib/unit_measurements/rails/base.rb

@@ -10,18 +10,13 @@ require "active_record"
 require "active_model"
 require "active_model/validations"
 
-# The +UnitMeasurements::Rails+ module provides functionality related to handling
-# unit measurements within the Rails framework.
-#
-# @author {Harshal V. Ladhe}[https://shivam091.github.io/]
-# @since 0.1.0
 module UnitMeasurements
-  # The +Rails+ module within +UnitMeasurements+ is dedicated to integrating
-  # {unit_measurements}[https://github.com/shivam091/unit_measurements] into
-  # Ruby on Rails applications.
+  # The +UnitMeasurements::Rails+ integrates the
+  # {unit_measurements}[https://github.com/shivam091/unit_measurements]
+  # gem into Ruby on Rails applications.
   #
-  # It includes modules and classes for ActiveRecord support, Railties, and custom
-  # errors.
+  # It integrates +unit_measurements+ into Ruby on Rails applications, encompassing
+  # modules and classes for ActiveRecord support, Railties, and custom errors.
   #
   # @see ActiveRecord
   # @see Railtie
@@ -29,7 +24,7 @@ module UnitMeasurements
   # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
   # @since 0.2.0
   module Rails
-    # This is the base class for custom errors in the +UnitMeasurements::Rails+
+    # This class serves as the base for custom errors within the +UnitMeasurements::Rails+
     # module.
     #
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]

data/lib/unit_measurements/rails/railtie.rb

@@ -4,12 +4,11 @@
 
 module UnitMeasurements
   module Rails
-    # The +Railtie+ class for integrating +unit_measurements+ with the +Rails+
-    # framework.
+    # The +Railtie+ class integrates +unit_measurements+ with the Rails framework.
     #
     # This Railtie is designed to be automatically loaded by Rails when the
-    # application starts. It can be used to configure and customize the behavior
-    # of +unit_measurements+ in a Rails application.
+    # application starts. It facilitates configuration and customization of the
+    # behavior of +unit_measurements+ within a Rails application.
     #
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 0.1.0

data/lib/unit_measurements/rails/unit_groups/all.rb

@@ -1,3 +1,8 @@
 # -*- encoding: utf-8 -*-
 # -*- frozen_string_literal: true -*-
 # -*- warn_indent: true -*-
+
+require_relative "length"
+require_relative "weight"
+require_relative "volume"
+require_relative "area"

data/lib/unit_measurements/rails/unit_groups/area.rb

@@ -0,0 +1,46 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+# The +UnitMeasurements::Rails::ActiveRecord::Area+ module provides a convenient
+# way to define area-measured attributes in +ActiveRecord+ models.
+#
+# It acts as a wrapper for the +measured+ method, simplifying the definition of
+# area-measured attributes without directly invoking the +measured+ method.
+#
+# @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+# @since 1.1.0
+module UnitMeasurements::Rails::ActiveRecord::Area
+  # Defines _area-measured_ attributes in the +ActiveRecord+ model.
+  #
+  # This method serves as a wrapper around the +measured+ method and allows easy
+  # definition of area-measured attributes by accepting an array of attribute
+  # names.
+  #
+  # @param [Array<String|Symbol>] measured_attrs
+  #   An array of the names of area-measured attributes.
+  #
+  # @example Define single area-measured attribute:
+  #   class Land < ActiveRecord::Base
+  #     measured_area :total_area
+  #   end
+  #
+  # @example Define multiple area-measured attributes:
+  #   class Land < ActiveRecord::Base
+  #     measured_area :carpet_area, :buildup_area
+  #   end
+  #
+  # @return [void]
+  #
+  # @see #measured
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.1.0
+  def measured_area(*measured_attrs)
+    measured(UnitMeasurements::Area, *measured_attrs)
+  end
+end
+
+# ActiveSupport hook to extend ActiveRecord with the `UnitMeasurements::Rails::ActiveRecord::Area` module.
+ActiveSupport.on_load(:active_record) do
+  ::ActiveRecord::Base.send :extend, UnitMeasurements::Rails::ActiveRecord::Area
+end

data/lib/unit_measurements/rails/unit_groups/length.rb

@@ -0,0 +1,46 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+# The +UnitMeasurements::Rails::ActiveRecord::Length+ module provides a convenient
+# way to define length-measured attributes in +ActiveRecord+ models.
+#
+# It acts as a wrapper for the +measured+ method, simplifying the definition of
+# length-measured attributes without directly invoking the +measured+ method.
+#
+# @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+# @since 1.1.0
+module UnitMeasurements::Rails::ActiveRecord::Length
+  # Defines _length-measured_ attributes in the +ActiveRecord+ model.
+  #
+  # This method serves as a wrapper around the +measured+ method and allows easy
+  # definition of length-measured attributes by accepting an array of attribute
+  # names.
+  #
+  # @param [Array<String|Symbol>] measured_attrs
+  #   An array of the names of length-measured attributes.
+  #
+  # @example Define single length-measured attribute:
+  #   class Cube < ActiveRecord::Base
+  #     measured_length :length
+  #   end
+  #
+  # @example Define multiple length-measured attributes:
+  #   class Cube < ActiveRecord::Base
+  #     measured_length :height, :width
+  #   end
+  #
+  # @return [void]
+  #
+  # @see #measured
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.1.0
+  def measured_length(*measured_attrs)
+    measured(UnitMeasurements::Length, *measured_attrs)
+  end
+end
+
+# ActiveSupport hook to extend ActiveRecord with the `UnitMeasurements::Rails::ActiveRecord::Length` module.
+ActiveSupport.on_load(:active_record) do
+  ::ActiveRecord::Base.send :extend, UnitMeasurements::Rails::ActiveRecord::Length
+end

data/lib/unit_measurements/rails/unit_groups/volume.rb

@@ -0,0 +1,46 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+# The +UnitMeasurements::Rails::ActiveRecord::Volume+ module provides a convenient
+# way to define volume-measured attributes in +ActiveRecord+ models.
+#
+# It acts as a wrapper for the +measured+ method, simplifying the definition of
+# volume-measured attributes without directly invoking the +measured+ method.
+#
+# @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+# @since 1.1.0
+module UnitMeasurements::Rails::ActiveRecord::Volume
+  # Defines _volume-measured_ attributes in the +ActiveRecord+ model.
+  #
+  # This method serves as a wrapper around the +measured+ method and allows easy
+  # definition of volume-measured attributes by accepting an array of attribute
+  # names.
+  #
+  # @param [Array<String|Symbol>] measured_attrs
+  #   An array of the names of volume-measured attributes.
+  #
+  # @example Define single volume-measured attribute:
+  #   class Container < ActiveRecord::Base
+  #     measured_volume :total_volume
+  #   end
+  #
+  # @example Define multiple volume-measured attributes:
+  #   class Container < ActiveRecord::Base
+  #     measured_volume :internal_volume, :external_volume
+  #   end
+  #
+  # @return [void]
+  #
+  # @see #measured
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.1.0
+  def measured_volume(*measured_attrs)
+    measured(UnitMeasurements::Volume, *measured_attrs)
+  end
+end
+
+# ActiveSupport hook to extend ActiveRecord with the `UnitMeasurements::Rails::ActiveRecord::Volume` module.
+ActiveSupport.on_load(:active_record) do
+  ::ActiveRecord::Base.send :extend, UnitMeasurements::Rails::ActiveRecord::Volume
+end

data/lib/unit_measurements/rails/unit_groups/weight.rb

@@ -0,0 +1,46 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+# The +UnitMeasurements::Rails::ActiveRecord::Weight+ module provides a convenient
+# way to define weight-measured attributes in +ActiveRecord+ models.
+#
+# It acts as a wrapper for the +measured+ method, simplifying the definition of
+# weight-measured attributes without directly invoking the +measured+ method.
+#
+# @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+# @since 1.1.0
+module UnitMeasurements::Rails::ActiveRecord::Weight
+  # Defines _weight-measured_ attributes in the +ActiveRecord+ model.
+  #
+  # This method serves as a wrapper around the +measured+ method and allows easy
+  # definition of weight-measured attributes by accepting an array of attribute
+  # names.
+  #
+  # @param [Array<String|Symbol>] measured_attrs
+  #   An array of the names of weight-measured attributes.
+  #
+  # @example Define single weight-measured attribute:
+  #   class Package < ActiveRecord::Base
+  #     measured_weight :total_weight
+  #   end
+  #
+  # @example Define multiple weight-measured attributes:
+  #   class Package < ActiveRecord::Base
+  #     measured_weight :item_weight, :package_weight
+  #   end
+  #
+  # @return [void]
+  #
+  # @see #measured
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.1.0
+  def measured_weight(*measured_attrs)
+    measured(UnitMeasurements::Weight, *measured_attrs)
+  end
+end
+
+# ActiveSupport hook to extend ActiveRecord with the `UnitMeasurements::Rails::ActiveRecord::Weight` module.
+ActiveSupport.on_load(:active_record) do
+  ::ActiveRecord::Base.send :extend, UnitMeasurements::Rails::ActiveRecord::Weight
+end

data/lib/unit_measurements/rails/version.rb

@@ -5,6 +5,6 @@
 module UnitMeasurements
   module Rails
     # Current stable version.
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unit_measurements-rails
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-14 00:00:00.000000000 Z
+date: 2023-11-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -169,6 +169,10 @@ files:
 - lib/unit_measurements/rails/base.rb
 - lib/unit_measurements/rails/railtie.rb
 - lib/unit_measurements/rails/unit_groups/all.rb
+- lib/unit_measurements/rails/unit_groups/area.rb
+- lib/unit_measurements/rails/unit_groups/length.rb
+- lib/unit_measurements/rails/unit_groups/volume.rb
+- lib/unit_measurements/rails/unit_groups/weight.rb
 - lib/unit_measurements/rails/version.rb
 - unit_measurements-rails.gemspec
 homepage: https://github.com/shivam091/unit_measurements-rails