unit_measurements-rails 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf20e075bf5db7bd8a33f60eb2e14493aa4ed985defd4a3f49b020498a66ec6b
-  data.tar.gz: df3f2e54ed849cab6b0b6e7221e57bc74c11480053136aba222f6f91b3c43410
+  metadata.gz: 8df42aea1bd4eeeb476acbf102accaa55c206886b581df3f70e055accae95d41
+  data.tar.gz: 8f1d81756ce2844917278e2c16f49665be362a427c3c1af3c00d8cc834b96f2b
 SHA512:
-  metadata.gz: 4a59d3f2cd7a3d7f716aa68ba88ff3c19ae29aade038c6aa1258a5eeef77c6fc44634e3c66167b8e9e499865c51b15861f0122e3cb6b226d1414daa8cb18af14
-  data.tar.gz: 3c722fab2b67d36ae090aef75a01222e5bbecf937c9a2322c03832a4960e0304975d9a347eef5178ea94cc5ae184f5055f97436e37a5702a1ded9b5cbebd5cc2
+  metadata.gz: e36f8d160d0644c4c66bd5723cdabef25db28ca5cae522dff70cb4299ea59c942d5190d0badc2374456b59db07dca09ac4f7c51bb22f8be261f67c932322cc79
+  data.tar.gz: 8285500f4713be2467e28cb6a2e39605478babf072935a2a93f6de01dfe3338010fed463a094828f425d76a4c8c48124c09b68f1cdbb9ff9f13f3abbad2e5cb7

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [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.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,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.
@@ -150,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.
@@ -175,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.
       #
@@ -199,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/version.rb

@@ -5,6 +5,6 @@
 module UnitMeasurements
   module Rails
     # Current stable version.
-    VERSION = "1.3.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.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-22 00:00:00.000000000 Z
+date: 2023-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties