unit_measurements-rails 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5315caeda4fd8354ecf8f0ee7f50778725827ce96a176f0c5164270a81e08fca
-  data.tar.gz: d5e6ad2b8f041e6fe0a43cd9f2f52b9339a9383cc99ee124155b8ef18c1dcc43
+  metadata.gz: 8df42aea1bd4eeeb476acbf102accaa55c206886b581df3f70e055accae95d41
+  data.tar.gz: 8f1d81756ce2844917278e2c16f49665be362a427c3c1af3c00d8cc834b96f2b
 SHA512:
-  metadata.gz: 4e6a3b59d61493150ff20625a1a800864094e91d2378f7c3a9b12a43fd4319283aadc6d64d893e42566d910095e7bd9b2151b52b14b3f3f9a91c7b011ae60276
-  data.tar.gz: d3e835f26dbaff425180d40e309dadb8d474001829d80e89998d020d847091e985fcde5f16b8e41937ffd4e4ae8caca71c156d04b680bd1cb527a703592e9cfd
+  metadata.gz: e36f8d160d0644c4c66bd5723cdabef25db28ca5cae522dff70cb4299ea59c942d5190d0badc2374456b59db07dca09ac4f7c51bb22f8be261f67c932322cc79
+  data.tar.gz: 8285500f4713be2467e28cb6a2e39605478babf072935a2a93f6de01dfe3338010fed463a094828f425d76a4c8c48124c09b68f1cdbb9ff9f13f3abbad2e5cb7

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [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
+
+- Raise `BaseError` if already measured attribute.
+- Added wrapper for defining `density` measured attributes.
+- Added wrapper for defining `temperature` measured attributes.
+- Added wrapper for defining `time` measured attributes.
+
+-----------
+
 ## [1.2.0](https://github.com/shivam091/unit_measurements-rails/compare/v1.1.0...v1.2.0) - 2023-11-20
 
 ### What's new

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    unit_measurements-rails (1.2.0)
+    unit_measurements-rails (1.4.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.11.0)
+    unit_measurements (5.12.0)
       activesupport (~> 7.0)
     websocket-driver (0.7.6)
       websocket-extensions (>= 0.1.0)

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,6 +61,8 @@ module UnitMeasurements
         options[:unit_group] = unit_group
 
         measured_attrs.map(&:to_s).each do |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"
 
@@ -73,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
       #   {
@@ -109,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]
       #
@@ -123,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.
@@ -148,9 +152,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.
@@ -173,7 +177,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.
       #
@@ -197,7 +201,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.

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

@@ -2,7 +2,10 @@
 # -*- frozen_string_literal: true -*-
 # -*- warn_indent: true -*-
 
+require_relative "area"
+require_relative "density"
 require_relative "length"
-require_relative "weight"
+require_relative "temperature"
+require_relative "time"
 require_relative "volume"
-require_relative "area"
+require_relative "weight"

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

@@ -16,7 +16,7 @@ module UnitMeasurements::Rails::ActiveRecord::Area
   #
   # 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.
+  # names along with their options.
   #
   # @param [Array<String|Symbol>] measured_attrs
   #   An array of the names of area-measured attributes.

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

@@ -0,0 +1,50 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+# The +UnitMeasurements::Rails::ActiveRecord::Density+ module provides a convenient
+# way to define density-measured attributes in +ActiveRecord+ models.
+#
+# It acts as a wrapper for the +measured+ method, simplifying the definition of
+# density-measured attributes without directly invoking the +measured+ method.
+#
+# @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+# @since 1.3.0
+module UnitMeasurements::Rails::ActiveRecord::Density
+  # @!scope class
+  # Defines _density-measured_ attributes in the +ActiveRecord+ model.
+  #
+  # This method serves as a wrapper around the +measured+ method and allows easy
+  # definition of density-measured attributes by accepting an array of attribute
+  # names along with their options.
+  #
+  # @param [Array<String|Symbol>] measured_attrs
+  #   An array of the names of density-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 density-measured attribute:
+  #   class Substance < ActiveRecord::Base
+  #     measured_density :total_density
+  #   end
+  #
+  # @example Define multiple density-measured attributes:
+  #   class Substance < ActiveRecord::Base
+  #     measured_density :internal_density, :external_density
+  #   end
+  #
+  # @return [void]
+  #
+  # @see .measured
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.3.0
+  def measured_density(*measured_attrs, **options)
+    measured(UnitMeasurements::Density, *measured_attrs, **options)
+  end
+end
+
+# ActiveSupport hook to extend ActiveRecord with the `UnitMeasurements::Rails::ActiveRecord::Density` module.
+ActiveSupport.on_load(:active_record) do
+  ::ActiveRecord::Base.send(:extend, UnitMeasurements::Rails::ActiveRecord::Density)
+end

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

@@ -16,7 +16,7 @@ module UnitMeasurements::Rails::ActiveRecord::Length
   #
   # 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.
+  # names along with their options.
   #
   # @param [Array<String|Symbol>] measured_attrs
   #   An array of the names of length-measured attributes.

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

@@ -0,0 +1,50 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+# The +UnitMeasurements::Rails::ActiveRecord::Temperature+ module provides a convenient
+# way to define temperature-measured attributes in +ActiveRecord+ models.
+#
+# It acts as a wrapper for the +measured+ method, simplifying the definition of
+# temperature-measured attributes without directly invoking the +measured+ method.
+#
+# @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+# @since 1.3.0
+module UnitMeasurements::Rails::ActiveRecord::Temperature
+  # @!scope class
+  # Defines _temperature-measured_ attributes in the +ActiveRecord+ model.
+  #
+  # This method serves as a wrapper around the +measured+ method and allows easy
+  # definition of temperature-measured attributes by accepting an array of attribute
+  # names along with their options.
+  #
+  # @param [Array<String|Symbol>] measured_attrs
+  #   An array of the names of temperature-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 temperature-measured attribute:
+  #   class WeatherReport < ActiveRecord::Base
+  #     measured_temperature :average_temperature
+  #   end
+  #
+  # @example Define multiple temperature-measured attributes:
+  #   class WeatherReport < ActiveRecord::Base
+  #     measured_temperature :day_temperature, :night_temperature
+  #   end
+  #
+  # @return [void]
+  #
+  # @see .measured
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.3.0
+  def measured_temperature(*measured_attrs, **options)
+    measured(UnitMeasurements::Temperature, *measured_attrs, **options)
+  end
+end
+
+# ActiveSupport hook to extend ActiveRecord with the `UnitMeasurements::Rails::ActiveRecord::Temperature` module.
+ActiveSupport.on_load(:active_record) do
+  ::ActiveRecord::Base.send(:extend, UnitMeasurements::Rails::ActiveRecord::Temperature)
+end

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

@@ -0,0 +1,50 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+# The +UnitMeasurements::Rails::ActiveRecord::Time+ module provides a convenient
+# way to define time-measured attributes in +ActiveRecord+ models.
+#
+# It acts as a wrapper for the +measured+ method, simplifying the definition of
+# time-measured attributes without directly invoking the +measured+ method.
+#
+# @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+# @since 1.3.0
+module UnitMeasurements::Rails::ActiveRecord::Time
+  # @!scope class
+  # Defines _time-measured_ attributes in the +ActiveRecord+ model.
+  #
+  # This method serves as a wrapper around the +measured+ method and allows easy
+  # definition of time-measured attributes by accepting an array of attribute
+  # names along with their options.
+  #
+  # @param [Array<String|Symbol>] measured_attrs
+  #   An array of the names of time-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 time-measured attribute:
+  #   class ProjectTimeline < ActiveRecord::Base
+  #     measured_time :duration
+  #   end
+  #
+  # @example Define multiple time-measured attributes:
+  #   class ProjectTimeline < ActiveRecord::Base
+  #     measured_time :setup_time, :processing_time
+  #   end
+  #
+  # @return [void]
+  #
+  # @see .measured
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.3.0
+  def measured_time(*measured_attrs, **options)
+    measured(UnitMeasurements::Time, *measured_attrs, **options)
+  end
+end
+
+# ActiveSupport hook to extend ActiveRecord with the `UnitMeasurements::Rails::ActiveRecord::Time` module.
+ActiveSupport.on_load(:active_record) do
+  ::ActiveRecord::Base.send(:extend, UnitMeasurements::Rails::ActiveRecord::Time)
+end

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

@@ -16,7 +16,7 @@ module UnitMeasurements::Rails::ActiveRecord::Volume
   #
   # 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.
+  # names along with their options.
   #
   # @param [Array<String|Symbol>] measured_attrs
   #   An array of the names of volume-measured attributes.

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

@@ -16,7 +16,7 @@ module UnitMeasurements::Rails::ActiveRecord::Weight
   #
   # 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.
+  # names along with their options.
   #
   # @param [Array<String|Symbol>] measured_attrs
   #   An array of the names of weight-measured attributes.

data/lib/unit_measurements/rails/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unit_measurements-rails
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-20 00:00:00.000000000 Z
+date: 2023-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -170,7 +170,10 @@ files:
 - 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/density.rb
 - lib/unit_measurements/rails/unit_groups/length.rb
+- lib/unit_measurements/rails/unit_groups/temperature.rb
+- lib/unit_measurements/rails/unit_groups/time.rb
 - lib/unit_measurements/rails/unit_groups/volume.rb
 - lib/unit_measurements/rails/unit_groups/weight.rb
 - lib/unit_measurements/rails/version.rb