unit_measurements-rails 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 248b4aa4b1db413cbd85b1625a3f074eaa19f6c36d1c3f85496b3b2192a61f22
-  data.tar.gz: d5038145522b4dc4041306c9a8b48191febd110aa039bb94e6da9a13f1e4315f
+  metadata.gz: cddde8ae9d387f5c1710542cc3152c2621aae6b2f6c2622a0f0b993ebe315e55
+  data.tar.gz: d68ebeb0acb2dc387fec180d750626f27c345f21a6e65b8181e2de23d946a2af
 SHA512:
-  metadata.gz: d1a7a08872179ea42aa5bc681910dc829b89c22d0a2981ed8888ce8b89a7ac5a239cb6ba78fa057e0566fd1b21b7d487d27eaa5a2d11af7a9ffb349019624f4c
-  data.tar.gz: 16058395f0b28050dc01d773938af2188594f386d650e8a3ce856aec9b1d723bfc8c5efe09093d3482d8d38ece676243a01c7eac4fc790dd976ff0451e4f1e4e
+  metadata.gz: 872c3102f9608149bc7d7983a67684bcbcaac6387a32efdefb1aeeb2214510f25ab00c617e97e2d99675c861d4f29abca2ee88e85f77f5d72abc941064e7c298
+  data.tar.gz: 04b8d2bdd7122990917ffdea05355d2fa7a23e57a91925ddc2b3088745d4a4b5af9042ed45f714d27558894ded5a43196e071f2ca373f5a563e791c97abe45d8

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [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.0.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,50 @@ 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 AddHeightToThings < ActiveRecord::Migration[7.0]
+  def change
+    add_column :things, :height_quantity, :decimal, precision: 10, scale: 2
+    add_column :things, :height_unit, :string, limit: 12
+  end
+end
+```
+
+A column can be declared as a measurement with its unit group class:
+
+```ruby
+class Thing < ActiveRecord::Base
+  measured UnitMeasurements::Length, :height
+end
+```
+
+This will allow you to access and assign a measurement object:
+
+```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
+```
+
+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
+```
 
 ## Contributing
 

data/lib/unit_measurements/rails/active_record.rb

@@ -0,0 +1,159 @@
+# -*- 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 allows
+    # you to define measurement attributes in your models with support for
+    # specific unit groups.
+    #
+    # @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.
+      #
+      # @example Defining measured attributes:
+      #   class Thing < ActiveRecord::Base
+      #     measured UnitMeasurements::Length, :height
+      #   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.
+      # @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, measurement_attr)
+        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"
+
+        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)
+      end
+
+      private
+
+      # Validates whether the +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
+
+      # Defines the method to read measurement attribute.
+      #
+      # @param [String|Symbol] measurement_attr The name of the measurement 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_measurement_reader(measurement_attr, quantity_attr, unit_attr, unit_group)
+        define_method(measurement_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
+
+      # Defines the method to write measurement attribute.
+      #
+      # @param [String|Symbol] measurement_attr The name of the measurement 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_measurement_writer(measurement_attr, quantity_attr, unit_attr, unit_group)
+        define_method("#{measurement_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
+
+      # Redefines the writer method to set 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
+
+          write_attribute(quantity_attr, quantity)
+        end
+      end
+
+      # Redefines the writer method to set 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.on_load(:active_record) do
+  ::ActiveRecord::Base.send :extend, UnitMeasurements::Rails::ActiveRecord
+end

data/lib/unit_measurements/rails/base.rb

@@ -10,10 +10,34 @@ 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.
+  #
+  # It includes 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 is the base class for custom errors in 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,17 @@
 
 module UnitMeasurements
   module Rails
+    # The +Railtie+ class for integrating +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.
+    #
+    # @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,3 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-

data/lib/unit_measurements/rails/version.rb

@@ -5,6 +5,6 @@
 module UnitMeasurements
   module Rails
     # Current stable version.
-    VERSION = "0.2.0"
+    VERSION = "1.0.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.0.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-12 00:00:00.000000000 Z
+date: 2023-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -165,8 +165,10 @@ 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/version.rb
 - unit_measurements-rails.gemspec
 homepage: https://github.com/shivam091/unit_measurements-rails