unit_measurements-rails 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf20e075bf5db7bd8a33f60eb2e14493aa4ed985defd4a3f49b020498a66ec6b
-  data.tar.gz: df3f2e54ed849cab6b0b6e7221e57bc74c11480053136aba222f6f91b3c43410
+  metadata.gz: 88cfa69f2d7ec7ba60a19ac6a4519f38d928ae4cff9df64d72035e76b21cc975
+  data.tar.gz: 3bad903fa5c6fbc6f0404be8b85dc96a369ff3bb49a29229c8d57c4927835010
 SHA512:
-  metadata.gz: 4a59d3f2cd7a3d7f716aa68ba88ff3c19ae29aade038c6aa1258a5eeef77c6fc44634e3c66167b8e9e499865c51b15861f0122e3cb6b226d1414daa8cb18af14
-  data.tar.gz: 3c722fab2b67d36ae090aef75a01222e5bbecf937c9a2322c03832a4960e0304975d9a347eef5178ea94cc5ae184f5055f97436e37a5702a1ded9b5cbebd5cc2
+  metadata.gz: c8bdc95a6136ee7d39ea0eb55c2ba3420632e7be2511c15eb7fca96b1083687005c2c08359bb0ee2bc5508070239b0dd60f1e5c588f150efd6b224ab40f1f260
+  data.tar.gz: 409dc3a9e99814361e1d97953118dfae1b4971da9c16da5bac8d77c81e4cd907a9d303aa883a22b040bb19f799291df5ef74644c9f21987c9c997599bc9e0f0e

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [1.5.0](https://github.com/shivam091/unit_measurements-rails/compare/v1.4.0...v1.5.0) - 2023-11-27
+
+### What's new
+
+- Raise error when columns for measurement attribute don't exist in DB.
+
+-----------
+
+## [1.4.0](https://github.com/shivam091/unit_measurements-rails/compare/v1.3.0...v1.4.0) - 2023-11-25
+
+### What's updated
+
+- Updated RDoc and rearranged files.
+
+-----------
+
 ## [1.3.0](https://github.com/shivam091/unit_measurements-rails/compare/v1.2.0...v1.3.0) - 2023-11-22
 
 ### What's new

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    unit_measurements-rails (1.3.0)
+    unit_measurements-rails (1.5.0)
       activemodel (>= 7)
       activerecord (>= 7)
       railties (>= 7)
@@ -163,12 +163,12 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
-    sqlite3 (1.6.8-x86_64-linux)
+    sqlite3 (1.6.9-x86_64-linux)
     thor (1.3.0)
     timeout (0.4.1)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unit_measurements (5.11.0)
+    unit_measurements (5.12.0)
       activesupport (~> 7.0)
     websocket-driver (0.7.6)
       websocket-extensions (>= 0.1.0)
@@ -184,7 +184,7 @@ DEPENDENCIES
   rake (~> 13.0)
   rspec (~> 3.0)
   simplecov (~> 0.21, >= 0.21.2)
-  sqlite3 (~> 1.6)
+  sqlite3 (~> 1.6.9)
   unit_measurements-rails!
 
 BUNDLED WITH

data/README.md

@@ -13,17 +13,18 @@ A Rails adaptor that encapsulate measurements and their units in Ruby on Rails.
 
 ## Introduction
 
-This gem is the Rails integration for the [unit_measurements](https://github.com/shivam091/unit_measurements) gem.
-It provides ActiveRecord adapter for persisting and retrieving measurements with their units.
+This gem is designed as a Rails integration for the [unit_measurements](https://github.com/shivam091/unit_measurements) gem.
+It provides an `ActiveRecord` adapter for persisting and retrieving measurements along with their units, simplifying complex
+measurement handling within your Rails applications.
 
 ## Minimum Requirements
 
-* Ruby 3.2+ (https://www.ruby-lang.org/en/downloads/branches/)
-* Rails 7.0.0+ (https://rubygems.org/gems/rails/versions)
+* Ruby 3.2+ ([Download Ruby](https://www.ruby-lang.org/en/downloads/branches/))
+* Rails 7.0.0+ ([RubyGems - Rails Versions](https://rubygems.org/gems/rails/versions))
 
 ## Installation
 
-If using bundler, first add this line to your application's Gemfile:
+To use `unit_measurements-rails` in your Rails application, add the following line to your Gemfile:
 
 ```ruby
 gem "unit_measurements-rails"
@@ -41,102 +42,82 @@ 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.
-
-Customizing the accessors used to hold quantity and unit is supported, see below
-for details.
+This gem provides an ActiveRecord integration allowing you to declare measurement attributes with their
+corresponding units in your database schema:
 
 ```ruby
-class CreateTableCubes < ActiveRecord::Migration[7.0]
+class CreateCubes < 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:
+Next, declare an atribute as measurement using `measured` with its associated unit
+group class:
 
 ```ruby
 class Cube < ActiveRecord::Base
-  measured UnitMeasurements::Length, :height
+  measured UnitMeasurements::Length, :length
 end
 ```
 
-This will allow you to access and assign a measured attribute:
+This setup allows you to access and assign measurement attributes conveniently:
 
 ```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
+cube.length = UnitMeasurements::Length.new(5, "ft")
+cube.length_quantity   #=> 0.5e1
+cube.length_unit       #=> "ft"
+cube.length            #=> 5.0 ft
 ```
 
-Order of assignment does not matter, and each attribute can be assigned separately
-and with mass assignment:
+You can specify multiple measurement attributes simultaneously:
 
 ```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
+class Cube < ActiveRecord::Base
+  measured UnitMeasurements::Length, :length, :width
 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:
+Attribute names are expected to have the `_quantity` and `_unit` suffix, and be
+`DECIMAL` and `VARCHAR` types, respectively, and defaults values are accepted.
+
+You can customize the model's quantity and unit accessors by specifying them in the
+`quantity_attribute_name` and `unit_attribute_name` options, respectively.
 
 ```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:
+For a more streamlined approach, predefined methods are available for commonly used
+types like `length`, `weight`, `area`, `volume`, etc.:
 
 ```ruby
 class Package < ActiveRecord::Base
   measured_length :size
-  measured_weight :item_weight, :package_weight
   measured_area :carpet_area
   measured_volume :total_volume
+  measured_weight :item_weight, :package_weight
 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
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
+Contributions to this project are welcomed! To contribute:
+
+1. Fork this repository
+2. Create a new branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am "Add some feature"`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+4. Push the changes to your branch (`git push origin my-new-feature`)
+5. Create new **Pull Request**
 
 ## License
 

data/lib/unit_measurements/rails/active_record.rb

@@ -15,22 +15,22 @@ 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
+    # facilitates defining measurement attributes in models with specific unit
     # group support.
     #
     # @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
+      # Defines a _reader_ and _writer_ methods for the measurement attributes in
       # the +ActiveRecord+ model.
       #
-      # @example Defining single measured attribute:
+      # @example Defining single measurement attribute:
       #   class Cube < ActiveRecord::Base
       #     measured UnitMeasurements::Length, :height
       #   end
       #
-      # @example Defining multiple measured attributes:
+      # @example Defining multiple measurement attributes:
       #   class Package < ActiveRecord::Base
       #     measured UnitMeasurements::Weight, :item_weight, :total_weight
       #   end
@@ -38,7 +38,7 @@ module UnitMeasurements
       # @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.
+      #   An array of the names of measurement 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.
@@ -46,7 +46,8 @@ module UnitMeasurements
       # @return [void]
       #
       # @raise [BaseError]
-      #   If +unit_group+ is not a subclass of +UnitMeasurements::Measurement+.
+      #   If +unit_group+ is not a subclass of +UnitMeasurements::Measurement+ or
+      #   the attribute has already been measured.
       #
       # @see BaseError
       # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
@@ -60,7 +61,7 @@ module UnitMeasurements
         options[:unit_group] = unit_group
 
         measured_attrs.map(&:to_s).each do |measured_attr|
-          raise BaseError, "The field '#{measured_attr}' has already been measured." if measured_attributes.key?(measured_attr)
+          raise BaseError, "The attribute '#{measured_attr}' has already been measured." if measured_attributes.key?(measured_attr)
 
           quantity_attr = options[:quantity_attribute_name]&.to_s || "#{measured_attr}_quantity"
           unit_attr = options[:unit_attribute_name]&.to_s || "#{measured_attr}_unit"
@@ -75,12 +76,13 @@ module UnitMeasurements
       end
 
       # @!scope class
-      # Returns a hash containing information about the measured attributes and
-      # their options.
+      # Returns a hash containing information about the measurement 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.
+      #   A hash where keys represent the names of the measurement attributes,
+      #   and values are hashes containing the options for each measurement
+      #   attribute.
       #
       # @example
       #   {
@@ -111,7 +113,7 @@ module UnitMeasurements
       # @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]
       #
@@ -125,9 +127,9 @@ module UnitMeasurements
 
       # @!scope class
       # @private
-      # Defines the method to read the measured attribute.
+      # Defines the method to _read_ the measurement attribute.
       #
-      # @param [String] measured_attr The name of the measured attribute.
+      # @param [String] measured_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.
@@ -138,6 +140,8 @@ module UnitMeasurements
       # @since 1.0.0
       def define_reader_for_measured_attr(measured_attr, quantity_attr, unit_attr, unit_group)
         define_method(measured_attr) do
+          column_exists?(quantity_attr) && column_exists?(unit_attr)
+
           quantity, unit = public_send(quantity_attr), public_send(unit_attr)
 
           begin
@@ -150,9 +154,9 @@ module UnitMeasurements
 
       # @!scope class
       # @private
-      # Defines the method to write the measured attribute.
+      # Defines the method to _write_ the measurement attribute.
       #
-      # @param [String] measured_attr The name of the measured attribute.
+      # @param [String] measured_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.
@@ -163,6 +167,8 @@ module UnitMeasurements
       # @since 1.0.0
       def define_writer_for_measured_attr(measured_attr, quantity_attr, unit_attr, unit_group)
         define_method("#{measured_attr}=") do |measurement|
+          column_exists?(quantity_attr) && column_exists?(unit_attr)
+
           if measurement.is_a?(unit_group)
             public_send("#{quantity_attr}=", measurement.quantity)
             public_send("#{unit_attr}=", measurement.unit.name)
@@ -175,7 +181,7 @@ module UnitMeasurements
 
       # @!scope class
       # @private
-      # Redefines the writer method to set the quantity attribute.
+      # Redefines the _writer_ method to set the quantity attribute.
       #
       # @param quantity_attr [String] The name of the quantity attribute.
       #
@@ -185,6 +191,8 @@ module UnitMeasurements
       # @since 1.0.0
       def redefine_quantity_writer(quantity_attr)
         redefine_method("#{quantity_attr}=") do |quantity|
+          column_exists?(quantity_attr)
+
           quantity = BigDecimal(quantity, Float::DIG) if quantity.is_a?(String)
           if quantity
             db_column_props = self.column_for_attribute(quantity_attr)
@@ -199,7 +207,7 @@ module UnitMeasurements
 
       # @!scope class
       # @private
-      # Redefines the writer method to set the unit attribute.
+      # 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.
@@ -210,6 +218,8 @@ module UnitMeasurements
       # @since 1.0.0
       def redefine_unit_writer(unit_attr, unit_group)
         redefine_method("#{unit_attr}=") do |unit|
+          column_exists?(unit_attr)
+
           unit_name = unit_group.unit_for(unit).try!(:name)
           write_attribute(unit_attr, (unit_name || unit))
         end

data/lib/unit_measurements/rails/base.rb

@@ -33,6 +33,7 @@ module UnitMeasurements
   end
 end
 
+require "unit_measurements/rails/helpers"
 require "unit_measurements/rails/active_record"
 
 require "unit_measurements/rails/railtie" if defined?(Rails)

data/lib/unit_measurements/rails/helpers.rb

@@ -0,0 +1,41 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  module Rails
+    # The +UnitMeasurements::Rails::Helpers+ module provides helper methods for
+    # handling +ActiveRecord+ models in the context of unit measurements.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.5.0
+    module Helpers
+      # Checks the existence of a +column_name+ within the database table
+      # associated with the +ActiveRecord+ model.
+      #
+      # @param [String] column_name The name of the column to check for existence.
+      #
+      # @raise [ArgumentError]
+      #   If the specified column does not exist in the database table.
+      #
+      # @example Check if the +height_quantity+ column exists in the database table:
+      #   column_exists?("height_quantity")
+      #
+      # @return [void]
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.5.0
+      def column_exists?(column_name)
+        unless self.class.column_names.include?(column_name)
+          raise ArgumentError, "Column '#{column_name}' does not exist in the database for table '#{self.class.table_name}'."
+        end
+      end
+    end
+  end
+end
+
+# ActiveSupport hook to include ActiveRecord with the `UnitMeasurements::Rails::Helpers`
+# module.
+ActiveSupport.on_load(:active_record) do
+  ::ActiveRecord::Base.send(:include, UnitMeasurements::Rails::Helpers)
+end

data/lib/unit_measurements/rails/version.rb

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

data/unit_measurements-rails.gemspec

@@ -43,7 +43,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "simplecov", "~> 0.21", ">= 0.21.2"
   spec.add_development_dependency "byebug", "~> 11"
-  spec.add_development_dependency "sqlite3", "~> 1.6"
+  spec.add_development_dependency "sqlite3", "~> 1.6.9"
 
   spec.required_ruby_version = ">= 3.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unit_measurements-rails
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-22 00:00:00.000000000 Z
+date: 2023-11-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -134,14 +134,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: 1.6.9
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: 1.6.9
 description: A Rails adaptor that encapsulate measurements and their units in Ruby
   on Rails.
 email:
@@ -167,6 +167,7 @@ files:
 - lib/unit_measurements-rails.rb
 - lib/unit_measurements/rails/active_record.rb
 - lib/unit_measurements/rails/base.rb
+- lib/unit_measurements/rails/helpers.rb
 - lib/unit_measurements/rails/railtie.rb
 - lib/unit_measurements/rails/unit_groups/all.rb
 - lib/unit_measurements/rails/unit_groups/area.rb