measured 2.8.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ec3f063994e56291a70f5b2726890e03b43ef00e512894a901bc8ea924ae895
-  data.tar.gz: 442e6cca31eb154cbe318287a64f9379ab987b9ddcd59629a2780960b52ea00d
+  metadata.gz: b794b67ca5a9cc00444ec39526340e3f3710dc0395b7205aeb95f44d8ed698fe
+  data.tar.gz: 2696f28b014ce76cded21150a1e1b4ef4772ef92a358ddf4e99b526081125d2a
 SHA512:
-  metadata.gz: 141a1214a375f0af9ae4d92c1e9c51d77e2a98d2a174321ee9e85eb4387fa72c3c98c49dcc5448d6617f7cc7d6bdf67e9ca4f12772d7446cb00e827329108d4f
-  data.tar.gz: f5a34f7aa0baf05177f216089dd9b4443ca2b04eecda5c0b72bf5899973a9a5a2a462b2e4f11ea7087dffcc8927e35835e9555da211bc628d50f76fadd110c35
+  metadata.gz: 95c82144964349b7111b6a1d372384dc3721b3c5e79870c8b841b7468d6794f60702c2acb1be714fab6c5a858a26d0bc28c340ef987c61a5d94658ffd64eec25
+  data.tar.gz: 49b6f68fd80cce3886824df3298c2d837ec0f257b0e4bb311231558b0d9a81eb9cb744f3746540eeaa740f6ad1f84bb578441fc6914841ac81ae57005638a1c0

data/.github/workflows/ci.yml

@@ -10,14 +10,20 @@ jobs:
     strategy:
       matrix:
         ruby:
-          - '2.6'
-          - '2.7'
           - '3.0'
+          - '3.1'
+          - '3.2'
         gemfile:
           - Gemfile
-          - gemfiles/activesupport-5.2.gemfile
-          - gemfiles/activesupport-6.0.gemfile
-          - gemfiles/activesupport-6.1.gemfile
+          - gemfiles/rails-6.0.gemfile
+          - gemfiles/rails-6.1.gemfile
+          - gemfiles/rails-7.0.gemfile
+          - gemfiles/rails-edge.gemfile
+        exclude:
+          # Rails Edge only supports Ruby >= 3.1
+          - ruby: '3.0'
+            gemfile: gemfiles/rails-edge.gemfile
+
     name: Ruby ${{ matrix.ruby }} ${{ matrix.gemfile }}
     steps:
       - uses: actions/checkout@v1

data/.github/workflows/cla.yml

@@ -0,0 +1,23 @@
+# .github/workflows/cla.yml
+name: Contributor License Agreement (CLA)
+
+on:
+  pull_request_target:
+    types: [opened, synchronize]
+  issue_comment:
+    types: [created]
+
+jobs:
+  cla:
+    runs-on: ubuntu-latest
+    if: |
+      (github.event.issue.pull_request
+        && !github.event.issue.pull_request.merged_at
+        && contains(github.event.comment.body, 'signed')
+      )
+      || (github.event.pull_request && !github.event.pull_request.merged)
+    steps:
+      - uses: Shopify/shopify-cla-action@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          cla-token: ${{ secrets.CLA_TOKEN }}

data/.ruby-version

@@ -0,0 +1 @@
+3.0.2

data/CHANGELOG.md

@@ -3,6 +3,19 @@ Unreleased
 
 
 
+3.0.0
+-----
+
+* Merge functionality of `measured-rails` into this gem. From this version on, this gem is able to automatically integrate with Active Record out of the box. (@paracycle)
+* Add `:gm` and `:gms` as aliases to weight. (@kushagra-03)
+* Adds support for initializing `Measured` objects with a rational value from string. (@dvisockas)
+* Make `Measured` initialization faster by avoiding string substitution in certain cases. (@bitwise-aiden)
+
+2.8.2
+-----
+
+* Add cm3 and mm3 to volume. (@fekadeabdejene)
+
 2.8.1
 -----
 

data/Gemfile

@@ -1,3 +1,5 @@
 source 'https://rubygems.org'
 
 gemspec
+
+gem "activerecord"

data/README.md

@@ -4,7 +4,7 @@ Encapsulates measurements with their units. Provides easy conversion between uni
 
 Lightweight and easily extensible to include other units and conversions. Conversions done with `Rational` for precision.
 
-The adapter to integrate `measured` with Ruby on Rails is in a separate [`measured-rails`](https://github.com/Shopify/measured-rails) gem.
+Since version 3.0.0, the adapter to integrate `measured` with Ruby on Rails is also a part of this gem. If you had been using [`measured-rails`](https://github.com/Shopify/measured-rails) for that functionality, you should now remove `measured-rails` from your gem file.
 
 ## Installation
 
@@ -158,6 +158,116 @@ Measured::Weight.new("3.14", "kg").format(with_conversion_string: false)
 > "3.14 kg"
 ```
 
+### Active Record
+
+This gem also provides an Active Record adapter for persisting and retrieving measurements with their units, and model validations.
+
+Columns are expected to have the `_value` and `_unit` suffix, and be `DECIMAL` and `VARCHAR`, and defaults are accepted. Customizing the column used to hold units is supported, see below for details.
+
+```ruby
+class AddWeightAndLengthToThings < ActiveRecord::Migration
+  def change
+    add_column :things, :minimum_weight_value, :decimal, precision: 10, scale: 2
+    add_column :things, :minimum_weight_unit, :string, limit: 12
+
+    add_column :things, :total_length_value, :decimal, precision: 10, scale: 2, default: 0
+    add_column :things, :total_length_unit, :string, limit: 12, default: "cm"
+  end
+end
+```
+
+A column can be declared as a measurement with its measurement subclass:
+
+```ruby
+class Thing < ActiveRecord::Base
+  measured Measured::Weight, :minimum_weight
+  measured Measured::Length, :total_length
+  measured Measured::Volume, :total_volume
+end
+```
+
+You can optionally customize the model's unit column by specifying it in the `unit_field_name` option, as follows:
+
+```ruby
+class ThingWithCustomUnitAccessor < ActiveRecord::Base
+  measured_length :length, :width, :height,     unit_field_name: :size_unit
+  measured_weight :total_weight, :extra_weight, unit_field_name: :weight_unit
+  measured_volume :total_volume, :extra_volume, unit_field_name: :volume_unit
+end
+```
+
+Similarly, you can optionally customize the model's value column by specifying it in the `value_field_name` option, as follows:
+
+```ruby
+class ThingWithCustomValueAccessor < ActiveRecord::Base
+  measured_length :length, value_field_name: :custom_length
+  measured_weight :total_weight, value_field_name: :custom_weight
+  measured_volume :volume, value_field_name: :custom_volume
+end
+```
+
+There are some simpler methods for predefined types:
+
+```ruby
+class Thing < ActiveRecord::Base
+  measured_weight :minimum_weight
+  measured_length :total_length
+  measured_volume :total_volume
+end
+```
+
+This will allow you to access and assign a measurement object:
+
+```ruby
+thing = Thing.new
+thing.minimum_weight = Measured::Weight.new(10, "g")
+thing.minimum_weight_unit     # "g"
+thing.minimum_weight_value    # 10
+```
+
+Order of assignment does not matter, and each property can be assigned separately and with mass assignment:
+
+```ruby
+params = { total_length_unit: "cm", total_length_value: "3" }
+thing = Thing.new(params)
+thing.total_length.to_s   # 3 cm
+```
+
+### Validations
+
+Validations are available:
+
+```ruby
+class Thing < ActiveRecord::Base
+  measured_length :total_length
+
+  validates :total_length, measured: true
+end
+```
+
+This will validate that the unit is defined on the measurement, and that there is a value.
+
+Rather than `true` the validation can accept a hash with the following options:
+
+* `message`: Override the default "is invalid" message.
+* `units`: A subset of units available for this measurement. Units must be in existing measurement.
+* `greater_than`
+* `greater_than_or_equal_to`
+* `equal_to`
+* `less_than`
+* `less_than_or_equal_to`
+
+All comparison validations require `Measured::Measurable` values, not scalars. Most of these options replace the `numericality` validator which compares the measurement/method name/proc to the column's value. Validations can also be combined with `presence` validator.
+
+**Note:** Validations are strongly recommended since assigning an invalid unit will cause the measurement to return `nil`, even if there is a value:
+
+```ruby
+thing = Thing.new
+thing.total_length_value = 1
+thing.total_length_unit = "invalid"
+thing.total_length  # nil
+```
+
 ## Units and conversions
 
 ### SI units support
@@ -269,7 +379,7 @@ Existing alternatives which were considered:
 * **Cons**
   * Opens up and modifies `Array`, `Date`, `Fixnum`, `Math`, `Numeric`, `String`, `Time`, and `Object`, then depends on those changes internally.
   * Lots of code to solve a relatively simple problem.
-  * No ActiveRecord adapter.
+  * No Active Record adapter.
 
 ### Gem: [quantified](https://github.com/Shopify/quantified)
 * **Pros**
@@ -278,7 +388,7 @@ Existing alternatives which were considered:
   * All math done with floats making it highly lossy.
   * All units assumed to be pluralized, meaning using unit abbreviations is not possible.
   * Not actively maintained.
-  * No ActiveRecord adapter.
+  * No Active Record adapter.
 
 ### Gem: [unitwise](https://github.com/joshwlewis/unitwise)
 * **Pros**
@@ -287,7 +397,7 @@ Existing alternatives which were considered:
 * **Cons**
   * Lots of code. Good code, but lots of it.
   * Many modifications to core types.
-  * ActiveRecord adapter exists but is written and maintained by a different person/org.
+  * Active Record adapter exists but is written and maintained by a different person/org.
   * Not actively maintained.
 
 ## Contributing