unit_measurements-rails 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 5f1843c7f2b52c98319dc2157d86f1028638fcc375e3104551ea79f2954560a4
4
- data.tar.gz: 271f1f7c5103ad50e3eddf357cc1456aba6e7219eebeca8768ab7fc5b9bcae9e
3
+ metadata.gz: 5315caeda4fd8354ecf8f0ee7f50778725827ce96a176f0c5164270a81e08fca
4
+ data.tar.gz: d5e6ad2b8f041e6fe0a43cd9f2f52b9339a9383cc99ee124155b8ef18c1dcc43
5
5
  SHA512:
6
- metadata.gz: c824399cc26f750e0e5981f39f4ea14ef50e2c1cb6d6c8dbfabf402bea3e06248ed4e48a0787ce015b223c9aa8b52949b15c6527db655bbb47c7b0db2da76957
7
- data.tar.gz: 236a331b4812c7598f997f27203f5b1bfaadd8f0f8a9ac667d2d1e454a8f5f46395eb9dfb7590f81443b0a1ae0b3fe83ead51d5d838eba9de70203f39ede554f
6
+ metadata.gz: 4e6a3b59d61493150ff20625a1a800864094e91d2378f7c3a9b12a43fd4319283aadc6d64d893e42566d910095e7bd9b2151b52b14b3f3f9a91c7b011ae60276
7
+ data.tar.gz: d3e835f26dbaff425180d40e309dadb8d474001829d80e89998d020d847091e985fcde5f16b8e41937ffd4e4ae8caca71c156d04b680bd1cb527a703592e9cfd
data/CHANGELOG.md CHANGED
@@ -1,3 +1,11 @@
1
+ ## [1.2.0](https://github.com/shivam091/unit_measurements-rails/compare/v1.1.0...v1.2.0) - 2023-11-20
2
+
3
+ ### What's new
4
+
5
+ - Added method `.measured_fields` to provide ability to maintain measured attribute names and their options.
6
+
7
+ -----------
8
+
1
9
  ## [1.1.0](https://github.com/shivam091/unit_measurements-rails/compare/v1.0.0...v1.1.0) - 2023-11-16
2
10
 
3
11
  ### What's new
@@ -14,7 +22,7 @@
14
22
 
15
23
  ### What's new
16
24
 
17
- - Added method `measured` to store and retrieve measurement object.
25
+ - Added method `.measured` to store and retrieve measurement object.
18
26
  - Added RDoc for modules and classes.
19
27
 
20
28
  -----------
data/Gemfile.lock CHANGED
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- unit_measurements-rails (1.1.0)
4
+ unit_measurements-rails (1.2.0)
5
5
  activemodel (>= 7)
6
6
  activerecord (>= 7)
7
7
  railties (>= 7)
data/README.md CHANGED
@@ -41,7 +41,11 @@ Or otherwise simply install it yourself as:
41
41
 
42
42
  ### ActiveRecord
43
43
 
44
- Attribute names are expected to have the `_quantity` and `_unit` suffix, and be `DECIMAL` and `VARCHAR` types, respectively, and defaults values are accepted.
44
+ Attribute names are expected to have the `_quantity` and `_unit` suffix, and be
45
+ `DECIMAL` and `VARCHAR` types, respectively, and defaults values are accepted.
46
+
47
+ Customizing the accessors used to hold quantity and unit is supported, see below
48
+ for details.
45
49
 
46
50
  ```ruby
47
51
  class CreateTableCubes < ActiveRecord::Migration[7.0]
@@ -94,6 +98,18 @@ class Land < ActiveRecord::Base
94
98
  end
95
99
  ```
96
100
 
101
+ You can optionally customize the model's quantity and unit accessors by specifying
102
+ them in the `quantity_attribute_name` and `unit_attribute_name` option, respectively,
103
+ as follows:
104
+
105
+ ```ruby
106
+ class CubeWithCustomAccessor < ActiveRecord::Base
107
+ measured_length :length, unit_attribute_name: :length_uom
108
+ measured_length :width, quantity_attribute_name: :width_value
109
+ measured_length :height, quantity_attribute_name: :height_value, unit_attribute_name: :height_uom
110
+ end
111
+ ```
112
+
97
113
  There are some simpler methods for predefined types:
98
114
 
99
115
  ```ruby
@@ -2,6 +2,15 @@
2
2
  # -*- frozen_string_literal: true -*-
3
3
  # -*- warn_indent: true -*-
4
4
 
5
+ # The +UnitMeasurements+ module provides functionality for handling unit
6
+ # measurements. It includes various classes and modules for persisting and
7
+ # retrieving measurements with their units.
8
+ #
9
+ # The module also offers support for integrating with Rails ActiveRecord models
10
+ # for handling unit measurements conveniently.
11
+ #
12
+ # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
13
+ # @since 1.0.0
5
14
  module UnitMeasurements
6
15
  module Rails
7
16
  # The +UnitMeasurements::Rails::ActiveRecord+ module enhances ActiveRecord
@@ -12,6 +21,7 @@ module UnitMeasurements
12
21
  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
13
22
  # @since 1.0.0
14
23
  module ActiveRecord
24
+ # @!scope class
15
25
  # Defines a _reader_ and _writer_ methods for the measured attributes in
16
26
  # the +ActiveRecord+ model.
17
27
  #
@@ -29,6 +39,10 @@ module UnitMeasurements
29
39
  # The unit group class or its name as a string.
30
40
  # @param [Array<String|Symbol>] measured_attrs
31
41
  # An array of the names of measured attributes.
42
+ # @param [Hash] options A customizable set of options
43
+ # @option options [String|Symbol] :quantity_attribute_name The name of the quantity attribute.
44
+ # @option options [String|Symbol] :unit_attribute_name The name of the unit attribute.
45
+ #
32
46
  # @return [void]
33
47
  #
34
48
  # @raise [BaseError]
@@ -37,14 +51,19 @@ module UnitMeasurements
37
51
  # @see BaseError
38
52
  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
39
53
  # @since 1.0.0
40
- def measured(unit_group, *measured_attrs)
54
+ def measured(unit_group, *measured_attrs, **options)
55
+ validate_unit_group!(unit_group)
56
+
57
+ options = options.reverse_merge(quantity_attribute_name: nil, unit_attribute_name: nil)
41
58
  unit_group = unit_group.constantize if unit_group.is_a?(String)
42
59
 
43
- validate_unit_group!(unit_group)
60
+ options[:unit_group] = unit_group
44
61
 
45
62
  measured_attrs.map(&:to_s).each do |measured_attr|
46
- quantity_attr = "#{measured_attr}_quantity"
47
- unit_attr = "#{measured_attr}_unit"
63
+ quantity_attr = options[:quantity_attribute_name]&.to_s || "#{measured_attr}_quantity"
64
+ unit_attr = options[:unit_attribute_name]&.to_s || "#{measured_attr}_unit"
65
+
66
+ measured_attributes[measured_attr] = options.merge(quantity_attribute_name: quantity_attr, unit_attribute_name: unit_attr)
48
67
 
49
68
  define_reader_for_measured_attr(measured_attr, quantity_attr, unit_attr, unit_group)
50
69
  define_writer_for_measured_attr(measured_attr, quantity_attr, unit_attr, unit_group)
@@ -53,8 +72,37 @@ module UnitMeasurements
53
72
  end
54
73
  end
55
74
 
75
+ # @!scope class
76
+ # Returns a hash containing information about the measured attributes and
77
+ # their options.
78
+ #
79
+ # @return [Hash{String => Hash{Symbol => String|Class}}]
80
+ # A hash where keys represent the names of the measured attributes, and
81
+ # values are hashes containing the options for each measured attribute.
82
+ #
83
+ # @example
84
+ # {
85
+ # "height" => {
86
+ # unit_group: UnitMeasurements::Length,
87
+ # quantity_attribute_name: "height_quantity",
88
+ # unit_attribute_name: "height_unit"
89
+ # },
90
+ # "weight" => {
91
+ # unit_group: UnitMeasurements::Length,
92
+ # quantity_attribute_name: "weight_quantity",
93
+ # unit_attribute_name: "weight_unit"
94
+ # }
95
+ # }
96
+ #
97
+ # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
98
+ # @since 1.2.0
99
+ def measured_attributes
100
+ @measured_attributes ||= {}
101
+ end
102
+
56
103
  private
57
104
 
105
+ # @!scope class
58
106
  # @private
59
107
  # Validates whether +unit_group+ is a subclass of +UnitMeasurements::Measurement+.
60
108
  #
@@ -73,6 +121,7 @@ module UnitMeasurements
73
121
  end
74
122
  end
75
123
 
124
+ # @!scope class
76
125
  # @private
77
126
  # Defines the method to read the measured attribute.
78
127
  #
@@ -97,6 +146,7 @@ module UnitMeasurements
97
146
  end
98
147
  end
99
148
 
149
+ # @!scope class
100
150
  # @private
101
151
  # Defines the method to write the measured attribute.
102
152
  #
@@ -121,6 +171,7 @@ module UnitMeasurements
121
171
  end
122
172
  end
123
173
 
174
+ # @!scope class
124
175
  # @private
125
176
  # Redefines the writer method to set the quantity attribute.
126
177
  #
@@ -133,7 +184,7 @@ module UnitMeasurements
133
184
  def redefine_quantity_writer(quantity_attr)
134
185
  redefine_method("#{quantity_attr}=") do |quantity|
135
186
  quantity = BigDecimal(quantity, Float::DIG) if quantity.is_a?(String)
136
- quantity = if quantity
187
+ if quantity
137
188
  db_column_props = self.column_for_attribute(quantity_attr)
138
189
  precision, scale = db_column_props.precision, db_column_props.scale
139
190
 
@@ -144,6 +195,7 @@ module UnitMeasurements
144
195
  end
145
196
  end
146
197
 
198
+ # @!scope class
147
199
  # @private
148
200
  # Redefines the writer method to set the unit attribute.
149
201
  #
@@ -156,7 +208,7 @@ module UnitMeasurements
156
208
  # @since 1.0.0
157
209
  def redefine_unit_writer(unit_attr, unit_group)
158
210
  redefine_method("#{unit_attr}=") do |unit|
159
- unit_name = unit_group.unit_group.unit_for(unit).try!(:name)
211
+ unit_name = unit_group.unit_for(unit).try!(:name)
160
212
  write_attribute(unit_attr, (unit_name || unit))
161
213
  end
162
214
  end
@@ -167,5 +219,5 @@ end
167
219
  # ActiveSupport hook to extend ActiveRecord with the `UnitMeasurements::Rails::ActiveRecord`
168
220
  # module.
169
221
  ActiveSupport.on_load(:active_record) do
170
- ::ActiveRecord::Base.send :extend, UnitMeasurements::Rails::ActiveRecord
222
+ ::ActiveRecord::Base.send(:extend, UnitMeasurements::Rails::ActiveRecord)
171
223
  end
@@ -11,6 +11,7 @@
11
11
  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
12
12
  # @since 1.1.0
13
13
  module UnitMeasurements::Rails::ActiveRecord::Area
14
+ # @!scope class
14
15
  # Defines _area-measured_ attributes in the +ActiveRecord+ model.
15
16
  #
16
17
  # This method serves as a wrapper around the +measured+ method and allows easy
@@ -19,6 +20,9 @@ module UnitMeasurements::Rails::ActiveRecord::Area
19
20
  #
20
21
  # @param [Array<String|Symbol>] measured_attrs
21
22
  # An array of the names of area-measured attributes.
23
+ # @param [Hash] options A customizable set of options
24
+ # @option options [String|Symbol] :quantity_attribute_name The name of the quantity attribute.
25
+ # @option options [String|Symbol] :unit_attribute_name The name of the unit attribute.
22
26
  #
23
27
  # @example Define single area-measured attribute:
24
28
  # class Land < ActiveRecord::Base
@@ -32,15 +36,15 @@ module UnitMeasurements::Rails::ActiveRecord::Area
32
36
  #
33
37
  # @return [void]
34
38
  #
35
- # @see #measured
39
+ # @see .measured
36
40
  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
37
41
  # @since 1.1.0
38
- def measured_area(*measured_attrs)
39
- measured(UnitMeasurements::Area, *measured_attrs)
42
+ def measured_area(*measured_attrs, **options)
43
+ measured(UnitMeasurements::Area, *measured_attrs, **options)
40
44
  end
41
45
  end
42
46
 
43
47
  # ActiveSupport hook to extend ActiveRecord with the `UnitMeasurements::Rails::ActiveRecord::Area` module.
44
48
  ActiveSupport.on_load(:active_record) do
45
- ::ActiveRecord::Base.send :extend, UnitMeasurements::Rails::ActiveRecord::Area
49
+ ::ActiveRecord::Base.send(:extend, UnitMeasurements::Rails::ActiveRecord::Area)
46
50
  end
@@ -11,6 +11,7 @@
11
11
  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
12
12
  # @since 1.1.0
13
13
  module UnitMeasurements::Rails::ActiveRecord::Length
14
+ # @!scope class
14
15
  # Defines _length-measured_ attributes in the +ActiveRecord+ model.
15
16
  #
16
17
  # This method serves as a wrapper around the +measured+ method and allows easy
@@ -19,6 +20,9 @@ module UnitMeasurements::Rails::ActiveRecord::Length
19
20
  #
20
21
  # @param [Array<String|Symbol>] measured_attrs
21
22
  # An array of the names of length-measured attributes.
23
+ # @param [Hash] options A customizable set of options
24
+ # @option options [String|Symbol] :quantity_attribute_name The name of the quantity attribute.
25
+ # @option options [String|Symbol] :unit_attribute_name The name of the unit attribute.
22
26
  #
23
27
  # @example Define single length-measured attribute:
24
28
  # class Cube < ActiveRecord::Base
@@ -32,15 +36,15 @@ module UnitMeasurements::Rails::ActiveRecord::Length
32
36
  #
33
37
  # @return [void]
34
38
  #
35
- # @see #measured
39
+ # @see .measured
36
40
  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
37
41
  # @since 1.1.0
38
- def measured_length(*measured_attrs)
39
- measured(UnitMeasurements::Length, *measured_attrs)
42
+ def measured_length(*measured_attrs, **options)
43
+ measured(UnitMeasurements::Length, *measured_attrs, **options)
40
44
  end
41
45
  end
42
46
 
43
47
  # ActiveSupport hook to extend ActiveRecord with the `UnitMeasurements::Rails::ActiveRecord::Length` module.
44
48
  ActiveSupport.on_load(:active_record) do
45
- ::ActiveRecord::Base.send :extend, UnitMeasurements::Rails::ActiveRecord::Length
49
+ ::ActiveRecord::Base.send(:extend, UnitMeasurements::Rails::ActiveRecord::Length)
46
50
  end
@@ -11,6 +11,7 @@
11
11
  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
12
12
  # @since 1.1.0
13
13
  module UnitMeasurements::Rails::ActiveRecord::Volume
14
+ # @!scope class
14
15
  # Defines _volume-measured_ attributes in the +ActiveRecord+ model.
15
16
  #
16
17
  # This method serves as a wrapper around the +measured+ method and allows easy
@@ -19,6 +20,9 @@ module UnitMeasurements::Rails::ActiveRecord::Volume
19
20
  #
20
21
  # @param [Array<String|Symbol>] measured_attrs
21
22
  # An array of the names of volume-measured attributes.
23
+ # @param [Hash] options A customizable set of options
24
+ # @option options [String|Symbol] :quantity_attribute_name The name of the quantity attribute.
25
+ # @option options [String|Symbol] :unit_attribute_name The name of the unit attribute.
22
26
  #
23
27
  # @example Define single volume-measured attribute:
24
28
  # class Container < ActiveRecord::Base
@@ -32,15 +36,15 @@ module UnitMeasurements::Rails::ActiveRecord::Volume
32
36
  #
33
37
  # @return [void]
34
38
  #
35
- # @see #measured
39
+ # @see .measured
36
40
  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
37
41
  # @since 1.1.0
38
- def measured_volume(*measured_attrs)
39
- measured(UnitMeasurements::Volume, *measured_attrs)
42
+ def measured_volume(*measured_attrs, **options)
43
+ measured(UnitMeasurements::Volume, *measured_attrs, **options)
40
44
  end
41
45
  end
42
46
 
43
47
  # ActiveSupport hook to extend ActiveRecord with the `UnitMeasurements::Rails::ActiveRecord::Volume` module.
44
48
  ActiveSupport.on_load(:active_record) do
45
- ::ActiveRecord::Base.send :extend, UnitMeasurements::Rails::ActiveRecord::Volume
49
+ ::ActiveRecord::Base.send(:extend, UnitMeasurements::Rails::ActiveRecord::Volume)
46
50
  end
@@ -11,6 +11,7 @@
11
11
  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
12
12
  # @since 1.1.0
13
13
  module UnitMeasurements::Rails::ActiveRecord::Weight
14
+ # @!scope class
14
15
  # Defines _weight-measured_ attributes in the +ActiveRecord+ model.
15
16
  #
16
17
  # This method serves as a wrapper around the +measured+ method and allows easy
@@ -19,6 +20,9 @@ module UnitMeasurements::Rails::ActiveRecord::Weight
19
20
  #
20
21
  # @param [Array<String|Symbol>] measured_attrs
21
22
  # An array of the names of weight-measured attributes.
23
+ # @param [Hash] options A customizable set of options
24
+ # @option options [String|Symbol] :quantity_attribute_name The name of the quantity attribute.
25
+ # @option options [String|Symbol] :unit_attribute_name The name of the unit attribute.
22
26
  #
23
27
  # @example Define single weight-measured attribute:
24
28
  # class Package < ActiveRecord::Base
@@ -32,15 +36,15 @@ module UnitMeasurements::Rails::ActiveRecord::Weight
32
36
  #
33
37
  # @return [void]
34
38
  #
35
- # @see #measured
39
+ # @see .measured
36
40
  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
37
41
  # @since 1.1.0
38
- def measured_weight(*measured_attrs)
39
- measured(UnitMeasurements::Weight, *measured_attrs)
42
+ def measured_weight(*measured_attrs, **options)
43
+ measured(UnitMeasurements::Weight, *measured_attrs, **options)
40
44
  end
41
45
  end
42
46
 
43
47
  # ActiveSupport hook to extend ActiveRecord with the `UnitMeasurements::Rails::ActiveRecord::Weight` module.
44
48
  ActiveSupport.on_load(:active_record) do
45
- ::ActiveRecord::Base.send :extend, UnitMeasurements::Rails::ActiveRecord::Weight
49
+ ::ActiveRecord::Base.send(:extend, UnitMeasurements::Rails::ActiveRecord::Weight)
46
50
  end
@@ -5,6 +5,6 @@
5
5
  module UnitMeasurements
6
6
  module Rails
7
7
  # Current stable version.
8
- VERSION = "1.1.0"
8
+ VERSION = "1.2.0"
9
9
  end
10
10
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: unit_measurements-rails
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.1.0
4
+ version: 1.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Harshal LADHE
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2023-11-17 00:00:00.000000000 Z
11
+ date: 2023-11-20 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: railties