unit_measurements-rails 0.2.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 248b4aa4b1db413cbd85b1625a3f074eaa19f6c36d1c3f85496b3b2192a61f22
-  data.tar.gz: d5038145522b4dc4041306c9a8b48191febd110aa039bb94e6da9a13f1e4315f
+  metadata.gz: 5f1843c7f2b52c98319dc2157d86f1028638fcc375e3104551ea79f2954560a4
+  data.tar.gz: 271f1f7c5103ad50e3eddf357cc1456aba6e7219eebeca8768ab7fc5b9bcae9e
 SHA512:
-  metadata.gz: d1a7a08872179ea42aa5bc681910dc829b89c22d0a2981ed8888ce8b89a7ac5a239cb6ba78fa057e0566fd1b21b7d487d27eaa5a2d11af7a9ffb349019624f4c
-  data.tar.gz: 16058395f0b28050dc01d773938af2188594f386d650e8a3ce856aec9b1d723bfc8c5efe09093d3482d8d38ece676243a01c7eac4fc790dd976ff0451e4f1e4e
+  metadata.gz: c824399cc26f750e0e5981f39f4ea14ef50e2c1cb6d6c8dbfabf402bea3e06248ed4e48a0787ce015b223c9aa8b52949b15c6527db655bbb47c7b0db2da76957
+  data.tar.gz: 236a331b4812c7598f997f27203f5b1bfaadd8f0f8a9ac667d2d1e454a8f5f46395eb9dfb7590f81443b0a1ae0b3fe83ead51d5d838eba9de70203f39ede554f

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [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
+
+- Added method `measured` to store and retrieve measurement object.
+- Added RDoc for modules and classes.
+
+-----------
+
 ## [0.2.0](https://github.com/shivam091/unit_measurements-rails/compare/v0.1.0...v0.2.0) - 2023-11-12
 
 ### What's new

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    unit_measurements-rails (0.2.0)
+    unit_measurements-rails (1.1.0)
       activemodel (>= 7)
       activerecord (>= 7)
       railties (>= 7)
@@ -168,7 +168,7 @@ GEM
     timeout (0.4.1)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unit_measurements (5.8.0)
+    unit_measurements (5.11.0)
       activesupport (~> 7.0)
     websocket-driver (0.7.6)
       websocket-extensions (>= 0.1.0)

data/README.md

@@ -37,6 +37,82 @@ Or otherwise simply install it yourself as:
 
 `$ gem install unit_measurements-rails`
 
+## Usage
+
+### ActiveRecord
+
+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 CreateTableCubes < ActiveRecord::Migration[7.0]
+  def change
+    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 measured with its unit group class:
+
+```ruby
+class Cube < ActiveRecord::Base
+  measured UnitMeasurements::Length, :height
+end
+```
+
+This will allow you to access and assign a measured attribute:
+
+```ruby
+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:
+
+```ruby
+params = {height_quantity: "3", height_unit: "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

@@ -0,0 +1,171 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  module Rails
+    # The +UnitMeasurements::Rails::ActiveRecord+ module enhances ActiveRecord
+    # 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 measured attributes in
+      # the +ActiveRecord+ model.
+      #
+      # @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 [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+.
+      #
+      # @see BaseError
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
+      def measured(unit_group, *measured_attrs)
+        unit_group = unit_group.constantize if unit_group.is_a?(String)
+
+        validate_unit_group!(unit_group)
+
+        measured_attrs.map(&:to_s).each do |measured_attr|
+          quantity_attr = "#{measured_attr}_quantity"
+          unit_attr = "#{measured_attr}_unit"
+
+          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
+
+      # @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+.
+      #
+      # @return [void]
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
+      def validate_unit_group!(unit_group)
+        unless unit_group.is_a?(Class) && unit_group.ancestors.include?(Measurement)
+          raise BaseError, "Expecting `#{unit_group}` to be a subclass of UnitMeasurements::Measurement"
+        end
+      end
+
+      # @private
+      # Defines the method to read the measured 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.
+      #
+      # @return [void]
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
+      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
+            unit_group.new(quantity, unit)
+          rescue BlankQuantityError, BlankUnitError, ParseError, UnitError
+            nil
+          end
+        end
+      end
+
+      # @private
+      # Defines the method to write the measured 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.
+      #
+      # @return [void]
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
+      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)
+          else
+            public_send("#{quantity_attr}=", nil)
+            public_send("#{unit_attr}=", nil)
+          end
+        end
+      end
+
+      # @private
+      # Redefines the writer method to set the quantity attribute.
+      #
+      # @param quantity_attr [String] The name of the quantity attribute.
+      #
+      # @return [void]
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
+      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
+            db_column_props = self.column_for_attribute(quantity_attr)
+            precision, scale = db_column_props.precision, db_column_props.scale
+
+            quantity.round(scale)
+          else
+            nil
+          end.tap { |value| write_attribute(quantity_attr, value) }
+        end
+      end
+
+      # @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.
+      #
+      # @return [void]
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @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)
+          write_attribute(unit_attr, (unit_name || unit))
+        end
+      end
+    end
+  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

@@ -11,9 +11,28 @@ require "active_model"
 require "active_model/validations"
 
 module UnitMeasurements
+  # The +UnitMeasurements::Rails+ integrates the
+  # {unit_measurements}[https://github.com/shivam091/unit_measurements]
+  # gem into Ruby on Rails applications.
+  #
+  # It integrates +unit_measurements+ into Ruby on Rails applications, encompassing
+  # modules and classes for ActiveRecord support, Railties, and custom errors.
+  #
+  # @see ActiveRecord
+  # @see Railtie
+  # @see BaseError
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 0.2.0
   module Rails
+    # This class serves as the base for custom errors within the +UnitMeasurements::Rails+
+    # module.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 0.2.0
     class BaseError < StandardError; end
   end
 end
 
+require "unit_measurements/rails/active_record"
+
 require "unit_measurements/rails/railtie" if defined?(Rails)

data/lib/unit_measurements/rails/railtie.rb

@@ -4,7 +4,16 @@
 
 module UnitMeasurements
   module Rails
+    # 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 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
     class Railtie < ::Rails::Railtie
+      # (optional: add custom configuration, initialization, or other hooks)
     end
   end
 end

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

@@ -0,0 +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 = "0.2.0"
+    VERSION = "1.1.0"
   end
 end

data/lib/unit_measurements-rails.rb

@@ -3,3 +3,5 @@
 # -*- warn_indent: true -*-
 
 require "unit_measurements/rails/base"
+
+require "unit_measurements/rails/unit_groups/all"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unit_measurements-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-12 00:00:00.000000000 Z
+date: 2023-11-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -165,8 +165,14 @@ files:
 - gemfiles/rails-7.1.gemfile
 - gemfiles/rails-edge.gemfile
 - lib/unit_measurements-rails.rb
+- lib/unit_measurements/rails/active_record.rb
 - 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