unit_measurements 5.2.0 → 5.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30ecc167254df71dd7e6415ea85e4042837d37294041d5fc1791e395711a5774
-  data.tar.gz: c7e5382424fbb305607a312e6fec931e0967c09d402f08ce88343909a7c0a89e
+  metadata.gz: e3db321077ce62eba3bf98f77fc58980cdfdef88789fba2a219a71655bb8a9af
+  data.tar.gz: 3c5b51f6d643d8cce56f67452fdd76643ae385f2d325b479151e1ce3686caeb3
 SHA512:
-  metadata.gz: b50e6cf5076ed8a27b16b81246c864cb0b3dcbeba9e91b400d7e377f91bd9497667312f2ff551cb43abc4a3520ee11d31f4926b20bbf40010f0895d19d0c32e7
-  data.tar.gz: 948c1541e6e57613839a88dee8c5f99e583f0137c2bfc3114fa1e9eb758bce608b6f194adbab2f8e85216768127630ec65c90bb4fd685054cbb69000fa0a9a9e
+  metadata.gz: 193497aecf9153a9098fb6cc496f7f72ed82cff90d6045a60a7567eed3bb3c07af9a03e62d0c49ce479ac517a59d45501336cceb66c12edaed3986811e9f12aa
+  data.tar.gz: 5a8d0f77ae6b7f9455f05e122db97f3ad4ddaf448c0bf45b9c0d086b7363b6fd7e65ad3d12288d0b1e5541d413270b8ac7a3bc7d3a4377ce7ea40c9bcbef366e

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [5.4.0](https://github.com/shivam091/unit_measurements/compare/v5.3.0...v5.4.0) - 2023-10-27
+
+### What's new
+
+- Added new units `Å`, `lnk`, `lea`, `hh`, `nl`, and `sft` in length.
+- Added new units `N`, `s`, `drt`, and `lbt` in weight.
+
+----------
+
+## [5.3.0](https://github.com/shivam091/unit_measurements/compare/v5.2.0...v5.3.0) - 2023-10-24
+
+### What's new
+
+- Added ability set globally configurable options for **`unit_measurements`**.
+
+### What's improved
+
+- Code coverage improvements.
+
+----------
+
 ## [5.2.0](https://github.com/shivam091/unit_measurements/compare/v5.1.1...v5.2.0) - 2023-10-22
 
 ### What's new

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    unit_measurements (5.2.0)
+    unit_measurements (5.4.0)
       activesupport (~> 7.0)
 
 GEM

data/README.md

@@ -22,14 +22,16 @@ to numerous errors.
 
 The `unit_measurements` gem is designed to simplify the handling of units for scientific calculations.
 
-## Features
-
-1. Provides easy conversion between units.
-2. Lightweight and easily extensible to include other units and conversions.
-3. Built in support for various [unit groups](https://github.com/shivam091/unit_measurements/blob/main/units.md).
-4. Ability to parse strings representing complex, fractional, mixed fractional, scientific numbers, and ratios.
-5. Well organized and descriptive documentation published [here](https://shivam091.github.io/unit_measurements).
-6. Supports caching of conversion factors between different units of the unit group.
+## Key Features
+1. **Simplified Measurement Conversion:** Easily convert measurements between compatible units, reducing the likelihood of errors in scientific calculations.
+2. **Extensible Unit Groups:** Effortlessly build own unit groups with specific units and conversions tailored to your needs.
+3. **Built-in Unit Groups:** Comes bundled with a wide range of standard [unit groups](https://github.com/shivam091/unit_measurements/blob/main/units.md),
+  covering various units.
+4. **String Parsing Capabilities:** Effortlessly parse strings representing complex, fractional, mixed fractional, scientific numbers, and ratios directly
+  saving you the hassle of manually extracting and converting them.
+5. **Comprehensive Documentation:** Well-organized and descriptive [documentation](https://shivam091.github.io/unit_measurements) for quick reference and implementation guidance.
+6. **Configurable Options:** Fine-tune behavior with configurable options, including caching for enhanced performance.
+7. **Error Handling:** Robust error handling ensures stability and reliability during conversions.
 
 ## Disclaimer
 
@@ -57,6 +59,23 @@ Or otherwise simply install it yourself as:
 
 `$ gem install unit_measurements`
 
+## Configuration
+
+`unit_measurements` is designed to work out of the box, but you can customize its behavior by placing
+the configuration block in an initializer file before requiring the library files:
+
+```ruby
+UnitMeasurements.configure do |config|
+  config.use_cache = false
+end
+```
+
+The current available configurable options are:
+
+| Option | Default value | Description |
+| ------ | ------------- | ----------- |
+| **use_cache** | false | Set to `true` to enable caching during conversions. |
+
 ## Usage
 
 The **`UnitMeasurements::Measurement`** class is responsible for conversion of quantity to various compatible units
@@ -400,10 +419,9 @@ gem "unit_measurements", require: ["unit_measurements/base", "unit_measurements/
 
 ### Building new unit groups
 
-This library provides a simpler way to define your own unit groups. Use the
-`UnitMeasurements.build` method to define units within it. You can also group
-units by the unit system using the `system` method and set the primitive unit for
- each unit group using the `primitive` method.
+This library provides a simpler way to define your own unit groups. Use the `UnitMeasurements.build` method to define
+units within it. You can group units by the unit system using the `system` method and set the primitive unit for the
+unit group using the `primitive` method. You can specify cache file name in unit group definition using the `cache` method.
 
 ```ruby
 UnitMeasurements::Time = UnitMeasurements.build do

data/lib/unit_measurements/base.rb

@@ -7,6 +7,13 @@ require "unit_measurements/version"
 
 module UnitMeasurements
   class << self
+    # Allows setting an instance of +Configuration+ containing values of desired
+    # configurable options.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.3.0
+    attr_writer :configuration
+
     # Creates a new unit group based on the provided +block+ of instructions.
     #
     # The +build+ method allows you to define and create a custom unit group with
@@ -40,10 +47,6 @@ module UnitMeasurements
     #     cache "length.json"
     #   end
     #
-    # @param block
-    #   A block of instructions for defining units and their conversions within
-    #   the unit group.
-    #
     # @yield [builder]
     #   A block that defines the units to be added to the unit group.
     #   The block takes a {UnitGroupBuilder} instance as a parameter.
@@ -76,10 +79,58 @@ module UnitMeasurements
         @unit_group = builder.build
       end
     end
+
+    # Returns an instance of +Configuration+ with the values of desired configurable
+    # options of +*unit_measurements*+. If instance is not present, it initializes
+    # a new instance of {Configuration}.
+    #
+    # @return [Configuration] An instance of +Configuration+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.3.0
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Reset the configuration to its default state.
+    #
+    # @example
+    #   UnitMeasurements.reset
+    #
+    # @return [Configuration] A new +Configuration+ object.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.3.0
+    def reset
+      @configuration = Configuration.new
+    end
+
+    # Configures options of the +*UnitMeasurements*+ module using a block. It
+    # yields the current +Configuration+ instance for updating default values of
+    # options by new values specified within a block.
+    #
+    # @example
+    #   UnitMeasurements.configure do |config|
+    #     config.use_cache = false
+    #   end
+    #
+    # @yield [configuration] The current +Configuration+ instance.
+    #
+    # @yieldparam [Configuration] configuration
+    #   An instance of +Configuration+ with the new values of options.
+    #
+    # @yieldreturn [Configuration] The updated +Configuration+ instance.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.3.0
+    def configure
+      yield configuration
+    end
   end
 end
 
 # The following requires load various components of the unit measurements library.
+require "unit_measurements/configuration"
 require "unit_measurements/cache"
 require "unit_measurements/unit_group_builder"
 require "unit_measurements/unit"

data/lib/unit_measurements/configuration.rb

@@ -0,0 +1,64 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_stringing_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # The +UnitMeasurements::Configuration+ class maintains and manages the globally
+  # configurable options of +*unit_measurements*+.
+  #
+  # @note
+  #   This class is responsible for configuring globally configurable options of
+  #   +*unit_measurements*+.
+  #
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 5.3.0
+  class Configuration
+    # Get the current value of the +use_cache+ option.
+    #
+    # @note
+    #   This option controls whether caching is enabled for converting measurements.
+    #   Defaults to +false+.
+    #
+    # @return [TrueClass|FalseClass]
+    #   Returns +true+ if caching is enabled, otherwise +false+.
+    #
+    # @see Cache
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.3.0
+    attr_reader :use_cache
+
+    # Initializes a new +Configuration+ instance with default values of configurable
+    # options.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.3.0
+    def initialize
+      self.use_cache = false
+    end
+
+    # Sets a value for the +use_cache+ option.
+    #
+    # It controls whether caching is enabled for converting measurements. When
+    # caching is enabled, previously computed conversion factors are stored for
+    # future use, improving conversion performance.
+    #
+    # @param [TrueClass|FalseClass] use_cache
+    #   +true+ if caching should be used while converting the measurement otherwise
+    #   +false+.
+    #
+    # @return [TrueClass|FalseClass] The updated value of +use_cache+.
+    #
+    # @raise [BaseError] if +use_cache+ is not a boolean value.
+    #
+    # @see Cache
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.3.0
+    def use_cache=(use_cache)
+      unless [true, false].include?(use_cache)
+        raise BaseError, "Configuration#use_cache= only accepts true or false, but received #{use_cache}"
+      end
+
+      @use_cache = use_cache
+    end
+  end
+end

data/lib/unit_measurements/measurement.rb

@@ -462,6 +462,8 @@ module UnitMeasurements
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 5.2.0
     def calculate_conversion_factor(target_unit, use_cache)
+      use_cache = (UnitMeasurements.configuration.use_cache || use_cache)
+
       if use_cache && (cached_factor = self.class.cached.get(unit.name, target_unit.name))
         cached_factor
       else

data/lib/unit_measurements/unit_groups/length.rb

@@ -7,19 +7,31 @@ UnitMeasurements::Length = UnitMeasurements.build do
 
   system :metric do
     si_unit "m", aliases: ["meter", "metre", "meters", "metres"]
+
+    unit "Å", value: "1e-10 m", aliases: ["angstrom", "angstroms", "ångström"]
   end
 
   system :imperial do
+    unit "h", value: "4 in", aliases: ["hh", "hand", "hands"]
+
     unit "in", value: "25.4 mm", aliases: ['"', "inch", "inches"]
     unit "ft", value: "12 in", aliases: ["'", "foot", "feet"]
     unit "yd", value: "3 ft", aliases: ["yard", "yards"]
-    unit "mi", value: "1760 yd", aliases: ["mile", "miles", "statute mile", "international mile"]
+    unit "mi", value: "5280 ft", aliases: ["mile", "miles", "statute mile", "international mile"]
     unit "ch", value: "22 yd", aliases: ["chain", "chains"]
-    unit "th", value: "1/1000 in", aliases: ["thou", "thousandth of an inch"]
+    unit "th", value: "1/1000 in", aliases: ["thou", "thousandth of an inch", "mil", "mils"]
+    unit "nl", value: "3 nmi", aliases: ["NL", "nleague", "nleagues", "nautical league", "nautical leagues"]
+
     unit "ftm", value: "6 ft", aliases: ["fathom", "fathoms"]
     unit "fur", value: "220 yd", aliases: ["furlong", "furlongs"]
     unit "nmi", value: "1852 m", aliases: ["NMI", "M", "NM", "nautical mile", "nautical miles"]
     unit "rod", value: "16 1/2 ft", aliases: ["rods", "perch", "pole", "lug"]
+    unit "lnk", value: "33/50 ft", aliases: ["l", "li", "link", "links"]
+    unit "lea", value: "3 mi", aliases: ["league", "leagues"]
+  end
+
+  system :us_customary do
+    unit "sft", value: "1200/3937 m", aliases: ["sfoot", "sfeet", "survey-foot", "survey-feet"]
   end
 
   system :astronomical do

data/lib/unit_measurements/unit_groups/weight.rb

@@ -10,27 +10,28 @@ UnitMeasurements::Weight = UnitMeasurements.build do
 
     unit "q", value: "100 kg", aliases: ["quintal", "quintals"]
     unit "t", value: "1000 kg", aliases: ["tonne", "tonnes", "metric tonne", "metric tonnes"]
+    unit "N", value: "0.10197162129779283 kg", aliases: ["newton", "newtons"]
+
     unit "ct", value: "200 mg", aliases: ["carat", "carats"]
     unit "Da", value: "1.660538921e-27 kg", aliases: ["dalton", "daltons"]
   end
 
   system :imperial do
-    unit "lb", value: [Rational(45_359_237, 1e+8), "kg"], aliases: ["lbs", "lbm", "pound-mass", "pound", "pounds", "#"]
+    unit "s", value: "20 gr", aliases: ["scruple", "scruples"]
+
+    unit "lb", value: "0.45359237 kg", aliases: ["lbs", "lbm", "pound-mass", "pound", "pounds", "#"]
     unit "st", value: "14 lb", aliases: ["stone", "stones"]
-    unit "oz", value: [Rational(1, 16), "lb"], aliases: ["ounce", "ounces"]
-  end
+    unit "oz", value: "1/16 lb", aliases: ["ounce", "ounces"]
+    unit "dr", value: "1/16 oz", aliases: ["dram", "drams"]
+    unit "gr", value: "1/7000 lb", aliases: ["grain", "grains"]
 
-  system :troy_weight do
-    unit "gr", value: [Rational(1, 7000), "lb"], aliases: ["grain", "grains"]
+    unit "drt", value: "60 gr", aliases: ["troy dram", "troy drams"]
     unit "ozt", value: "480 gr", aliases: ["troy ounce", "troy ounces"]
-    unit "dwt", value: [Rational(1, 20), "ozt"], aliases: ["pennyweight", "pennyweights"]
-  end
-
-  system :avoirdupois do
-    unit "dr", value: [Rational(1, 16), "oz"], aliases: ["dram", "drams"]
+    unit "lbt", value: "5760 gr", aliases: ["troy pound", "troy pounds"]
+    unit "dwt", value: "1/20 ozt", aliases: ["pwt", "pennyweight", "pennyweights"]
   end
 
   system :foot_pound_second do
-    unit "slug", value: "32.1740 lb", aliases: ["slugs"]
+    unit "slug", value: "32.17404856 lb", aliases: ["slugs"]
   end
 end

data/lib/unit_measurements/version.rb

@@ -4,5 +4,5 @@
 
 module UnitMeasurements
   # Current stable version.
-  VERSION = "5.2.0"
+  VERSION = "5.4.0"
 end

data/units.md

@@ -9,27 +9,33 @@ check below list of bundled units before converting your measurements.
 in addition to [Decimal SI prefixes](README.md#decimal-si-prefixes).
 3. Primitive unit of the unit group is in _emphasised typeface_.
 
-## 1. Length/Distance
+## 1. Length or distance
 
 These units are defined in `UnitMeasurements::Length`.
 
 | # | Name | Aliases |
 |:--|:--|:--|
 | _1_ | _m*_ | _meter, metre, meters, metres_ |
-| 2 | in | ", inch, inches |
-| 3 | ft | ', foot, feet |
-| 4 | yd | yard, yards |
-| 5 | mi | mile, miles, statute mile, international mile |
-| 6 | ch | chain, chains |
-| 7 | th | thou, thousandth of an inch |
-| 8 | au | astronomical unit, astronomical units |
-| 9 | pc | parsec, parsecs |
-| 10 | ftm | fathom, fathoms |
-| 11 | fur | furlong, furlongs |
-| 12 | nmi | NMI, M, NM, nautical mile, nautical miles |
-| 13 | rod | rods, perch, pole, lug |
-
-## 2. Weight/Mass
+| 2 | Å | angstrom, angstroms, ångström |
+| 3 | h | hh, hand, hands |
+| 4 | in | ", inch, inches |
+| 5 | ft | ', foot, feet |
+| 6 | yd | yard, yards |
+| 7 | mi | mile, miles, statute mile, international mile |
+| 8 | ch | chain, chains |
+| 9 | th | thou, thousandth of an inch, mil, mils |
+| 10 | au | astronomical unit, astronomical units |
+| 11 | pc | parsec, parsecs |
+| 12 | nl | NL, nleague, nleagues, nautical league, nautical leagues |
+| 13 | ftm | fm, fathom, fathoms |
+| 14 | fur | furlong, furlongs |
+| 15 | nmi | NMI, M, NM, nautical mile, nautical miles |
+| 16 | rod | rods, perch, pole, lug |
+| 17 | lnk | l, li, link, links |
+| 18 | lea | league, leagues |
+| 19 | sft | sfoot, sfeet, survey-foot, survey-feet |
+
+## 2. Weight or mass
 
 These units are defined in `UnitMeasurements::Weight`.
 
@@ -38,16 +44,20 @@ These units are defined in `UnitMeasurements::Weight`.
 | _1_ | _g*_ | _gram, grams, gramme, grammes_ |
 | 2 | q | quintal, quintals |
 | 3 | t | tonne, tonnes, metric tonne, metric tonnes |
-| 4 | ct | carat, carats |
-| 5 | Da | dalton, daltons |
-| 6 | st | stone, stones |
-| 7 | dr | dram, drams |
-| 8 | dwt | pennyweight, pennyweights |
-| 9 | ozt | troy ounce, troy ounces |
-| 10 | slug | slugs |
-| 11 | lb | lbs, lbm, pound-mass, pound, pounds, \# |
-| 12 | oz | ounce, ounces |
-| 13 | gr | grain, grains |
+| 4 | N | newton, newtons |
+| 5 | s | scruple, scruples |
+| 6 | ct | carat, carats |
+| 7 | Da | dalton, daltons |
+| 8 | st | stone, stones |
+| 9 | dr | dram, drams |
+| 10 | lb | lbs, lbm, pound-mass, pound, pounds, \# |
+| 11 | oz | ounce, ounces |
+| 12 | gr | grain, grains |
+| 13 | dwt | pennyweight, pennyweights |
+| 14 | ozt | troy ounce, troy ounces |
+| 15 | lbt | troy pound, troy pounds |
+| 16 | drt | troy dram, troy drams |
+| 17 | slug | slugs |
 
 ## 3. Time
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unit_measurements
 version: !ruby/object:Gem::Version
-  version: 5.2.0
+  version: 5.4.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-10-22 00:00:00.000000000 Z
+date: 2023-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -109,6 +109,7 @@ files:
 - lib/unit_measurements/base.rb
 - lib/unit_measurements/cache.rb
 - lib/unit_measurements/comparison.rb
+- lib/unit_measurements/configuration.rb
 - lib/unit_measurements/conversion.rb
 - lib/unit_measurements/errors/parse_error.rb
 - lib/unit_measurements/errors/primitive_unit_already_set_error.rb