unit_measurements-rails 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f1843c7f2b52c98319dc2157d86f1028638fcc375e3104551ea79f2954560a4
-  data.tar.gz: 271f1f7c5103ad50e3eddf357cc1456aba6e7219eebeca8768ab7fc5b9bcae9e
+  metadata.gz: 5315caeda4fd8354ecf8f0ee7f50778725827ce96a176f0c5164270a81e08fca
+  data.tar.gz: d5e6ad2b8f041e6fe0a43cd9f2f52b9339a9383cc99ee124155b8ef18c1dcc43
 SHA512:
-  metadata.gz: c824399cc26f750e0e5981f39f4ea14ef50e2c1cb6d6c8dbfabf402bea3e06248ed4e48a0787ce015b223c9aa8b52949b15c6527db655bbb47c7b0db2da76957
-  data.tar.gz: 236a331b4812c7598f997f27203f5b1bfaadd8f0f8a9ac667d2d1e454a8f5f46395eb9dfb7590f81443b0a1ae0b3fe83ead51d5d838eba9de70203f39ede554f
+  metadata.gz: 4e6a3b59d61493150ff20625a1a800864094e91d2378f7c3a9b12a43fd4319283aadc6d64d893e42566d910095e7bd9b2151b52b14b3f3f9a91c7b011ae60276
+  data.tar.gz: d3e835f26dbaff425180d40e309dadb8d474001829d80e89998d020d847091e985fcde5f16b8e41937ffd4e4ae8caca71c156d04b680bd1cb527a703592e9cfd

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [1.2.0](https://github.com/shivam091/unit_measurements-rails/compare/v1.1.0...v1.2.0) - 2023-11-20
+
+### What's new
+
+- Added method `.measured_fields` to provide ability to maintain measured attribute names and their options.
+
+-----------
+
 ## [1.1.0](https://github.com/shivam091/unit_measurements-rails/compare/v1.0.0...v1.1.0) - 2023-11-16
 
 ### What's new
@@ -14,7 +22,7 @@
 
 ### What's new
 
-- Added method `measured` to store and retrieve measurement object.
+- Added method `.measured` to store and retrieve measurement object.
 - Added RDoc for modules and classes.
 
 -----------

data/Gemfile.lock

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

data/README.md

@@ -41,7 +41,11 @@ Or otherwise simply install it yourself as:
 
 ### ActiveRecord
 
-Attribute names are expected to have the `_quantity` and `_unit` suffix, and be `DECIMAL` and `VARCHAR` types, respectively, and defaults values are accepted.
+Attribute names are expected to have the `_quantity` and `_unit` suffix, and be
+`DECIMAL` and `VARCHAR` types, respectively, and defaults values are accepted.
+
+Customizing the accessors used to hold quantity and unit is supported, see below
+for details.
 
 ```ruby
 class CreateTableCubes < ActiveRecord::Migration[7.0]
@@ -94,6 +98,18 @@ class Land < ActiveRecord::Base
 end
 ```
 
+You can optionally customize the model's quantity and unit accessors by specifying
+them in the `quantity_attribute_name` and `unit_attribute_name` option, respectively,
+as follows:
+
+```ruby
+class CubeWithCustomAccessor < ActiveRecord::Base
+  measured_length :length, unit_attribute_name: :length_uom
+  measured_length :width, quantity_attribute_name: :width_value
+  measured_length :height, quantity_attribute_name: :height_value, unit_attribute_name: :height_uom
+end
+```
+
 There are some simpler methods for predefined types:
 
 ```ruby

data/lib/unit_measurements/rails/active_record.rb

@@ -2,6 +2,15 @@
 # -*- frozen_string_literal: true -*-
 # -*- warn_indent: true -*-
 
+# The +UnitMeasurements+ module provides functionality for handling unit
+# measurements. It includes various classes and modules for persisting and
+# retrieving measurements with their units.
+#
+# The module also offers support for integrating with Rails ActiveRecord models
+# for handling unit measurements conveniently.
+#
+# @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+# @since 1.0.0
 module UnitMeasurements
   module Rails
     # The +UnitMeasurements::Rails::ActiveRecord+ module enhances ActiveRecord
@@ -12,6 +21,7 @@ module UnitMeasurements
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
     module ActiveRecord
+      # @!scope class
       # Defines a _reader_ and _writer_ methods for the measured attributes in
       # the +ActiveRecord+ model.
       #
@@ -29,6 +39,10 @@ module UnitMeasurements
       #   The unit group class or its name as a string.
       # @param [Array<String|Symbol>] measured_attrs
       #   An array of the names of measured attributes.
+      # @param [Hash] options A customizable set of options
+      # @option options [String|Symbol] :quantity_attribute_name The name of the quantity attribute.
+      # @option options [String|Symbol] :unit_attribute_name The name of the unit attribute.
+      #
       # @return [void]
       #
       # @raise [BaseError]
@@ -37,14 +51,19 @@ module UnitMeasurements
       # @see BaseError
       # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
       # @since 1.0.0
-      def measured(unit_group, *measured_attrs)
+      def measured(unit_group, *measured_attrs, **options)
+        validate_unit_group!(unit_group)
+
+        options = options.reverse_merge(quantity_attribute_name: nil, unit_attribute_name: nil)
         unit_group = unit_group.constantize if unit_group.is_a?(String)
 
-        validate_unit_group!(unit_group)
+        options[:unit_group] = unit_group
 
         measured_attrs.map(&:to_s).each do |measured_attr|
-          quantity_attr = "#{measured_attr}_quantity"
-          unit_attr = "#{measured_attr}_unit"
+          quantity_attr = options[:quantity_attribute_name]&.to_s || "#{measured_attr}_quantity"
+          unit_attr = options[:unit_attribute_name]&.to_s || "#{measured_attr}_unit"
+
+          measured_attributes[measured_attr] = options.merge(quantity_attribute_name: quantity_attr, unit_attribute_name: unit_attr)
 
           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)
@@ -53,8 +72,37 @@ module UnitMeasurements
         end
       end
 
+      # @!scope class
+      # Returns a hash containing information about the measured attributes and
+      # their options.
+      #
+      # @return [Hash{String => Hash{Symbol => String|Class}}]
+      #   A hash where keys represent the names of the measured attributes, and
+      #   values are hashes containing the options for each measured attribute.
+      #
+      # @example
+      #   {
+      #     "height" => {
+      #       unit_group: UnitMeasurements::Length,
+      #       quantity_attribute_name: "height_quantity",
+      #       unit_attribute_name: "height_unit"
+      #     },
+      #     "weight" => {
+      #       unit_group: UnitMeasurements::Length,
+      #       quantity_attribute_name: "weight_quantity",
+      #       unit_attribute_name: "weight_unit"
+      #     }
+      #   }
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.2.0
+      def measured_attributes
+        @measured_attributes ||= {}
+      end
+
       private
 
+      # @!scope class
       # @private
       # Validates whether +unit_group+ is a subclass of +UnitMeasurements::Measurement+.
       #
@@ -73,6 +121,7 @@ module UnitMeasurements
         end
       end
 
+      # @!scope class
       # @private
       # Defines the method to read the measured attribute.
       #
@@ -97,6 +146,7 @@ module UnitMeasurements
         end
       end
 
+      # @!scope class
       # @private
       # Defines the method to write the measured attribute.
       #
@@ -121,6 +171,7 @@ module UnitMeasurements
         end
       end
 
+      # @!scope class
       # @private
       # Redefines the writer method to set the quantity attribute.
       #
@@ -133,7 +184,7 @@ module UnitMeasurements
       def redefine_quantity_writer(quantity_attr)
         redefine_method("#{quantity_attr}=") do |quantity|
           quantity = BigDecimal(quantity, Float::DIG) if quantity.is_a?(String)
-          quantity = if quantity
+          if quantity
             db_column_props = self.column_for_attribute(quantity_attr)
             precision, scale = db_column_props.precision, db_column_props.scale
 
@@ -144,6 +195,7 @@ module UnitMeasurements
         end
       end
 
+      # @!scope class
       # @private
       # Redefines the writer method to set the unit attribute.
       #
@@ -156,7 +208,7 @@ module UnitMeasurements
       # @since 1.0.0
       def redefine_unit_writer(unit_attr, unit_group)
         redefine_method("#{unit_attr}=") do |unit|
-          unit_name = unit_group.unit_group.unit_for(unit).try!(:name)
+          unit_name = unit_group.unit_for(unit).try!(:name)
           write_attribute(unit_attr, (unit_name || unit))
         end
       end
@@ -167,5 +219,5 @@ 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
+  ::ActiveRecord::Base.send(:extend, UnitMeasurements::Rails::ActiveRecord)
 end

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

@@ -11,6 +11,7 @@
 # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
 # @since 1.1.0
 module UnitMeasurements::Rails::ActiveRecord::Area
+  # @!scope class
   # Defines _area-measured_ attributes in the +ActiveRecord+ model.
   #
   # This method serves as a wrapper around the +measured+ method and allows easy
@@ -19,6 +20,9 @@ module UnitMeasurements::Rails::ActiveRecord::Area
   #
   # @param [Array<String|Symbol>] measured_attrs
   #   An array of the names of area-measured attributes.
+  # @param [Hash] options A customizable set of options
+  # @option options [String|Symbol] :quantity_attribute_name The name of the quantity attribute.
+  # @option options [String|Symbol] :unit_attribute_name The name of the unit attribute.
   #
   # @example Define single area-measured attribute:
   #   class Land < ActiveRecord::Base
@@ -32,15 +36,15 @@ module UnitMeasurements::Rails::ActiveRecord::Area
   #
   # @return [void]
   #
-  # @see #measured
+  # @see .measured
   # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
   # @since 1.1.0
-  def measured_area(*measured_attrs)
-    measured(UnitMeasurements::Area, *measured_attrs)
+  def measured_area(*measured_attrs, **options)
+    measured(UnitMeasurements::Area, *measured_attrs, **options)
   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
+  ::ActiveRecord::Base.send(:extend, UnitMeasurements::Rails::ActiveRecord::Area)
 end

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

@@ -11,6 +11,7 @@
 # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
 # @since 1.1.0
 module UnitMeasurements::Rails::ActiveRecord::Length
+  # @!scope class
   # Defines _length-measured_ attributes in the +ActiveRecord+ model.
   #
   # This method serves as a wrapper around the +measured+ method and allows easy
@@ -19,6 +20,9 @@ module UnitMeasurements::Rails::ActiveRecord::Length
   #
   # @param [Array<String|Symbol>] measured_attrs
   #   An array of the names of length-measured attributes.
+  # @param [Hash] options A customizable set of options
+  # @option options [String|Symbol] :quantity_attribute_name The name of the quantity attribute.
+  # @option options [String|Symbol] :unit_attribute_name The name of the unit attribute.
   #
   # @example Define single length-measured attribute:
   #   class Cube < ActiveRecord::Base
@@ -32,15 +36,15 @@ module UnitMeasurements::Rails::ActiveRecord::Length
   #
   # @return [void]
   #
-  # @see #measured
+  # @see .measured
   # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
   # @since 1.1.0
-  def measured_length(*measured_attrs)
-    measured(UnitMeasurements::Length, *measured_attrs)
+  def measured_length(*measured_attrs, **options)
+    measured(UnitMeasurements::Length, *measured_attrs, **options)
   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
+  ::ActiveRecord::Base.send(:extend, UnitMeasurements::Rails::ActiveRecord::Length)
 end

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

@@ -11,6 +11,7 @@
 # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
 # @since 1.1.0
 module UnitMeasurements::Rails::ActiveRecord::Volume
+  # @!scope class
   # Defines _volume-measured_ attributes in the +ActiveRecord+ model.
   #
   # This method serves as a wrapper around the +measured+ method and allows easy
@@ -19,6 +20,9 @@ module UnitMeasurements::Rails::ActiveRecord::Volume
   #
   # @param [Array<String|Symbol>] measured_attrs
   #   An array of the names of volume-measured attributes.
+  # @param [Hash] options A customizable set of options
+  # @option options [String|Symbol] :quantity_attribute_name The name of the quantity attribute.
+  # @option options [String|Symbol] :unit_attribute_name The name of the unit attribute.
   #
   # @example Define single volume-measured attribute:
   #   class Container < ActiveRecord::Base
@@ -32,15 +36,15 @@ module UnitMeasurements::Rails::ActiveRecord::Volume
   #
   # @return [void]
   #
-  # @see #measured
+  # @see .measured
   # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
   # @since 1.1.0
-  def measured_volume(*measured_attrs)
-    measured(UnitMeasurements::Volume, *measured_attrs)
+  def measured_volume(*measured_attrs, **options)
+    measured(UnitMeasurements::Volume, *measured_attrs, **options)
   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
+  ::ActiveRecord::Base.send(:extend, UnitMeasurements::Rails::ActiveRecord::Volume)
 end

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

@@ -11,6 +11,7 @@
 # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
 # @since 1.1.0
 module UnitMeasurements::Rails::ActiveRecord::Weight
+  # @!scope class
   # Defines _weight-measured_ attributes in the +ActiveRecord+ model.
   #
   # This method serves as a wrapper around the +measured+ method and allows easy
@@ -19,6 +20,9 @@ module UnitMeasurements::Rails::ActiveRecord::Weight
   #
   # @param [Array<String|Symbol>] measured_attrs
   #   An array of the names of weight-measured attributes.
+  # @param [Hash] options A customizable set of options
+  # @option options [String|Symbol] :quantity_attribute_name The name of the quantity attribute.
+  # @option options [String|Symbol] :unit_attribute_name The name of the unit attribute.
   #
   # @example Define single weight-measured attribute:
   #   class Package < ActiveRecord::Base
@@ -32,15 +36,15 @@ module UnitMeasurements::Rails::ActiveRecord::Weight
   #
   # @return [void]
   #
-  # @see #measured
+  # @see .measured
   # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
   # @since 1.1.0
-  def measured_weight(*measured_attrs)
-    measured(UnitMeasurements::Weight, *measured_attrs)
+  def measured_weight(*measured_attrs, **options)
+    measured(UnitMeasurements::Weight, *measured_attrs, **options)
   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
+  ::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.1.0"
+    VERSION = "1.2.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unit_measurements-rails
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-17 00:00:00.000000000 Z
+date: 2023-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties