unit_measurements 5.2.0 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30ecc167254df71dd7e6415ea85e4042837d37294041d5fc1791e395711a5774
-  data.tar.gz: c7e5382424fbb305607a312e6fec931e0967c09d402f08ce88343909a7c0a89e
+  metadata.gz: 006027cb5f557c69f5ba083f6624cf9e424fcb00cc794b8f50912907538a3689
+  data.tar.gz: 4db6ec5c12a752191933c5aa6d99837c1e2dc5e8269e5d05339a6e9b631d3e7f
 SHA512:
-  metadata.gz: b50e6cf5076ed8a27b16b81246c864cb0b3dcbeba9e91b400d7e377f91bd9497667312f2ff551cb43abc4a3520ee11d31f4926b20bbf40010f0895d19d0c32e7
-  data.tar.gz: 948c1541e6e57613839a88dee8c5f99e583f0137c2bfc3114fa1e9eb758bce608b6f194adbab2f8e85216768127630ec65c90bb4fd685054cbb69000fa0a9a9e
+  metadata.gz: fe13840ae30879e2068b4a0628e073259d8faab8efc615f0ff6da1b4fc7307b2a4285ebe44425fc4bedf26263e02a5f29e34df6ac792e3c16429f214262dbc31
+  data.tar.gz: d9f28aecb8b8dea511466a8e4f71288581c35407d841b20d65006a9bb8e3dad8d3ec53da4b2f83c0235d9a919a2dccf572371957c1010a8d449c7b11bdf1947f

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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.3.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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unit_measurements
 version: !ruby/object:Gem::Version
-  version: 5.2.0
+  version: 5.3.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-10-22 00:00:00.000000000 Z
+date: 2023-10-24 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