comparison 0.1.99 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a1be3dfdb9956ab89e40615d7e019ac31cefb24596e236acb5a99c4e30ff15a
-  data.tar.gz: b8fce566958ce9801c2ccdab4adce9bbe9739e48b2fd92464763886702f918a6
+  metadata.gz: a0a0717dffff6def29846aef2510a3d20a3e5666fe30b5b581b3979172fafc46
+  data.tar.gz: 98b3eda0230973ff1c07fa81632be94550dba11930ef58f73adc4193891bbb64
 SHA512:
-  metadata.gz: 5a252e4fd07af9024f0972b5a42b5665fac54f1807cbd7f88affd2236bbd9448ad57ae79bc9c78ba31901c723015a0b50fae6ffd46cf78af0d2e8468c6d83ff0
-  data.tar.gz: f9d8b42bfed576f00e8bb200272b001f64a123f709603445e4a6fe165e7f6d4132f967308b3747cf5364c489d74b1b0647e18ebc1f1b78dd40282ec2ffd51f97
+  metadata.gz: dbe04c79ff6e8c17fa0eb0d38ebd60e5a2d7e138b8b807a9b76a606e1abfcbcd6f9af0cf79030a8a50b58e3a2f27f9bd24c990966d2fbdb63532e4f818abceb7
+  data.tar.gz: 2d4c10c029538936cfc61b13ac0d79777497fad1d1695c9862808a5421ef1bcc4b06d229fac076c0509ca341ead7dfb034176f27bea641e9934bee661d00c02b

data/README.md

@@ -1,4 +1,4 @@
-# [![Gem Version](https://badge.fury.io/rb/comparison.svg)](https://badge.fury.io/rb/comparison) [![Build Status](https://travis-ci.org/jparker/comparison.svg?branch=master)](https://travis-ci.org/jparker/comparison)
+# [![Gem Version](https://badge.fury.io/rb/comparison.svg)](https://badge.fury.io/rb/comparison)
 
 # Comparison
 
@@ -10,46 +10,36 @@ color-coded to indicate positive or negative growth. This plugin provides
 helpers that abstract the logic of deciding what to show into a handful of
 simple methods and leveraging I18n.
 
-## Upgrade Notes
-
-This gem has been getting a facelift, and this has resulted in some changes
-from the old behavior.
-
-`Comparison::Presenter#classes` has been renamed to
-`Comparison::Presenter#dom_classes`, and `Comparison::Presenter#css` has been
-renamed to `Comparison::Presenter#style`. The old method names continue to
-work, but they will emit deprecation warnings.
-
-The I18n keys used by the above methods have been similarly renamed, but the
-methods will continue to fall back on the old keys. Going forward, use
-`comparison.dom_classes` instead of `comparison.classes` and `comparison.style`
-instead of `comparison.css`.
-
 ## Usage
 
-The library has three components: the Comparison class for performing the
-actual math, the Presenter class for decorating the Comparison with
-view-friendly output, and a helper module for using the Presenter with the
+The library has three components: the `Comparator` class for performing the
+actual math, the `Presenter` class for decorating the comparator with
+view-friendly output, and a helper module for using the presenter with the
 view.
 
-`#compare` helper takes the two numbers to be compared and yields the
-Comparison presenter to a block.
+The `#compare` helper takes the two numbers to be compared and yields the
+presenter to a block.
 
-`#difference` provides the absolute difference between the two numbers,
-literally `m - n`.
+`#difference_as_currency` provides the difference between the two numbers,
+literally `value - other`, formatted as currency. Formatting is handled by
+`ActiveSupport::NumberHelper#number_to_currency`.
 
 `#percentage` provides the percentage difference between the two numbers. Under
-the hood it uses `ActionView::Helpers::NumberHelper#number_to_percentage` to
-format the percentage. Options are passed through to that method.
+the hood it uses `ActiveSupport#NumberHelper#number_to_percentage` to format
+the percentage. Options are passed through to that method.
+
+`#unsigned_percentage` returns the absolute value of the percentage. Use this
+if you prefer to use other cues, such as colors or icons, to indicate positive
+or negative changes.
 
 `#arrow` returns an HTML character entity for an arrow (up, down, or, for no
 change, an empty string).
 
 ```erb
-<%= compare m, n do |cmp| %>
-  <td><%= number_to_currency m %></td>
-  <td><%= number_to_currency n %></td>
-  <td><%= cmp.difference %></td>
+<%= compare value, other do |cmp| %>
+  <td><%= number_to_currency value %></td>
+  <td><%= number_to_currency other %></td>
+  <td><%= cmp.difference_as_currency %></td>
   <td>
     <%= cmp.arrow %>
     <%= cmp.percentage precision: 1 %>
@@ -80,10 +70,10 @@ en:
       positive: 'comparison positive'
       negative: 'comparison negative'
       nochange: 'comparison nochange'
-    style:
-      positive_html: 'color: #3c763d; background-color: #dff0d8;'
-      negative_html: 'color: #a94442; background-color: #f2dede;'
-      nochange_html: 'color: #777777;'
+    inline_style:
+      positive: 'color: #3c763d; background-color: #dff0d8;'
+      negative: 'color: #a94442; background-color: #f2dede;'
+      nochange: 'color: #777777;'
     icons:
       positive_html: '<span class="glyphicon glyphicon-arrow-up"></span>'
       negative_html: '<span class="glyphicon glyphicon-arrow-down"></span>'
@@ -92,8 +82,14 @@ en:
       positive_html: '&uarr;'
       negative_html: '&darr;'
       nochange_html: ''
+    infinity_html: '&infin;'
 ```
 
+If the `dom_classes` keys are not present, translation falls back on `classes`.
+If the `inline_style` keys are not present, translation falls back on `style`
+and `css`. In both cases, those fallback keys are deprecated. Expect support
+for those keys to eventually be dropped.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -107,9 +103,14 @@ And then execute:
 $ bundle
 ```
 
-Or install it yourself as:
-```bash
-$ gem install comparison
+Include the Comparison helpers by adding the following to your
+application\_helper.rb:
+
+```ruby
+# app/helpers/application_helper.rb
+module ApplicationHelper
+  include Comparison::ApplicationHelper
+end
 ```
 
 ## Contributing

data/app/helpers/comparison/application_helper.rb

@@ -3,16 +3,13 @@
 module Comparison
   module ApplicationHelper # :nodoc:
     ##
-    # Returns a Presenter for a Comparator for +m+ and +n+.
+    # Returns a Presenter for a Comparator for +value+ and +other+.
     #
     # If a block is given, the Presenter is yielded to the block.
-    #
-    # rubocop:disable Naming/UncommunicativeMethodParamName
-    def compare(m, n)
-      comparison = Presenter.new Comparator.new m, n
+    def compare(value, other)
+      comparison = Presenter.new Comparator.new value, other
       yield comparison if block_given?
       comparison
     end
-    # rubocop:enable Naming/UncommunicativeMethodParamName
   end
 end

data/config/locales/en.yml

@@ -1,6 +1,6 @@
 en:
   comparison:
-    # classes:
+    # dom_classes:
     #   positive: 'comparison positive'
     #   negative: 'comparison negative'
     #   nochange: 'comparison nochange'
@@ -10,10 +10,10 @@ en:
     #   negative_html: '<span class="glyphicon glyphicon-arrow-down"></span>'
     #   nochange_html: '<span class="glyphicon glyphicon-minus"></span>'
 
-    style:
-      positive_html: ''
-      negative_html: ''
-      nochange_html: ''
+    inline_style:
+      positive: ''
+      negative: ''
+      nochange: ''
 
     arrows:
       positive_html: '&uarr;'

data/lib/comparison/comparator.rb

@@ -10,40 +10,56 @@ module Comparison
   class Comparator
     extend Forwardable
 
+    attr_reader :value, :other
+
     ##
-    # Instantiates a new Comparator to compare two numbers, +m+ and +n+.
+    # Instantiates a new Comparator to compare two numbers, +value+ and +other+.
     #
     # Both numbers will be converted to instances of `BigDecimal`.
-    #
-    # rubocop:disable Naming/UncommunicativeMethodParamName
-    def initialize(m, n)
-      @m = m.to_d
-      @n = n.to_d
+    def initialize(value, other)
+      @value = value.to_d
+      @other = other.to_d
     end
-    # rubocop:enable Naming/UncommunicativeMethodParamName
-
-    attr_reader :m, :n
 
-    delegate %i[infinite? nan? negative? positive? zero?] => :relative
+    delegate %i[negative? positive? zero? nonzero?] => :difference
+    delegate %i[infinite? nan?] => :change
 
     ##
-    # Returns the difference between +@m+ and +@n+.
+    # Returns the difference between +@value+ and +@other+.
+    def difference
+      value - other
+    end
+
     def absolute
-      @absolute ||= m - n
+      Kernel.warn "DEPRECATION WARNING: use #difference instead of #absolute (called from #{caller(1..1).first})"
+      difference
     end
 
-    alias difference absolute
+    ##
+    # Returns the relative change of +@value+ from +@other+.
+    def change
+      difference / other.abs
+    end
 
     ##
-    # Returns the percentage difference of +@m+ to +@n+.
+    # Returns the relative change of +@value+ from +@other+ as a percentage.
+    def percentage
+      change * 100
+    end
+
     def relative
-      @relative ||= if n.negative?
-                      (1 - m / n) * 100
-                    else
-                      (m / n - 1) * 100
-                    end
+      Kernel.warn "DEPRECATION WARNING: use #percentage instead of #relative (called from #{caller(1..1).first})"
+      change
     end
 
-    alias percentage relative
+    def m
+      Kernel.warn "DEPRECATION WARNING: use #value instead of #m (called from #{caller(1..1).first})"
+      value
+    end
+
+    def n
+      Kernel.warn "DEPRECATION WARNING: use #other instead of #n (called from #{caller(1..1).first})"
+      other
+    end
   end
 end

data/lib/comparison/engine.rb

@@ -3,9 +3,5 @@
 module Comparison
   class Engine < ::Rails::Engine # :nodoc:
     isolate_namespace Comparison
-
-    initializer 'comparison.view_helpers' do
-      ActionView::Base.send :include, helpers
-    end
   end
 end

data/lib/comparison/presenter.rb

@@ -9,39 +9,62 @@ module Comparison
   class Presenter < DelegateClass(Comparator)
     include ActionView::Helpers::TranslationHelper
 
-    ARROWS = { up: '&uarr;', down: '&darr;', none: '' }.freeze
-
-    # TODO: This shouldn't necessarily return a currency representation.
+    ARROWS = { positive: '&uarr;', negative: '&darr;', nochange: '' }.freeze
 
     ##
-    # Returns Comparator#absolute presented as currency.
-    def difference(**options)
+    # Returns Comparator#difference formatted as currency.
+    def difference_as_currency(**options)
       if positive?
-        number_to_currency absolute, format: '+%u%n', **options
+        number_to_currency __getobj__.difference, format: '+%u%n', **options
       else
-        number_to_currency absolute, **options
+        number_to_currency __getobj__.difference, **options
       end
     end
 
     ##
-    # Returns Comparator#relative formatted as a percentage.
+    # Deprecated alias for `#difference_as_currency`.
+    #
+    # In a future release, this method will be changed to delegate directly
+    # `Comparator#difference`.
+    def difference(...)
+      Kernel.warn 'DEPRECATION WARNING: use #difference_as_currency instead of #difference' \
+                  " (called from #{caller(3..3).first})"
+      difference_as_currency(...)
+    end
+
+    ##
+    # Returns Comparator#change formatted as a percentage.
+    #
+    # If the change evaluates to Infinity or -Infinity, the I18n translaation
+    # for infinity is returned. If no translation is defined, `nil` is
+    # returned.
     #
-    # If the relative percentage evaluates to Infinity or -Infinity, +nil+ is
-    # returned. If it evaluates to NaN, 0 is returned.
+    # If the change evaluates to NaN, it is returned as 0.
     def percentage(**options)
       if nan? || zero?
         number_to_percentage 0, **options
       elsif infinite?
-        # TODO: Return nil, or lookup an optional representation in I18n?
-        nil
+        t 'comparison.infinity_html', default: nil
       elsif positive?
-        number_to_percentage relative, format: '+%n%', **options
+        number_to_percentage __getobj__.percentage, format: '+%n%', **options
       else
-        number_to_percentage relative, **options
+        number_to_percentage __getobj__.percentage, **options
       end
     end
 
-    # rubocop:disable Metrics/LineLength
+    ##
+    # Returns the absolute value of Comparator#change formatted as a percentage.
+    #
+    # See `#percentage` for additional information on special return scenarios.
+    #
+    # Use this if you are relying on other cues (colors and/or icons) to
+    # indicate positive or negative values.
+    def unsigned_percentage(**options)
+      return percentage(**options) if nan? || infinite?
+
+      number_to_percentage __getobj__.percentage.abs, **options
+    end
+
     ##
     # Returns the I18n translation for `comparison.icons`. (See also #arrow.)
     #
@@ -62,15 +85,9 @@ module Comparison
     #           negative_html: '<span class="glyphicon glyphicon-arrow-down"></span>'
     #           nochange_html: '<span class="glyphicon glyphicon-minus"></span>'
     #
-    # rubocop:enable Metrics/LineLength
     def icon
-      if positive?
-        t 'comparison.icons.positive_html'
-      elsif negative?
-        t 'comparison.icons.negative_html'
-      else
-        t 'comparison.icons.nochange_html'
-      end
+      key, = expand_i18n_keys 'icons', suffix: '_html'
+      t key
     end
 
     ##
@@ -104,13 +121,8 @@ module Comparison
     # #icons is meant to be used from full-featured view contexts. As such,
     # #icons is the one to use to generate HTML tags.
     def arrow
-      if positive?
-        t 'comparison.arrows.positive_html', default: ARROWS[:up]
-      elsif negative?
-        t 'comparison.arrows.negative_html', default: ARROWS[:down]
-      else
-        t 'comparison.arrows.nochange_html', default: ARROWS[:none]
-      end
+      key, = expand_i18n_keys 'arrows', suffix: '_html'
+      t key, default: ARROWS[description.to_sym]
     end
 
     ##
@@ -142,27 +154,17 @@ module Comparison
     #     # => "<span class=\"comparison positive\">+10%</span>"
     #
     # If you need to work with inline styles instead of CSS classes, see the
-    # `#style` method.
+    # `#inline_style` method.
     def dom_classes
-      if positive?
-        t 'comparison.dom_classes.positive',
-          default: %i[comparison.classes.positive]
-      elsif negative?
-        t 'comparison.dom_classes.negative',
-          default: %i[comparison.classes.negative]
-      else
-        t 'comparison.dom_classes.nochange',
-          default: %i[comparison.classes.nochange]
-      end
+      key, *deprecated_keys = expand_i18n_keys(%w[dom_classes classes])
+      t key, default: deprecated_keys
     end
 
     def classes
-      Kernel.warn '[DEPRECATION WARNING] #classes is deprecated: ' \
-        "use #dom_classes instead: #{caller(3..3).first}"
+      Kernel.warn "DEPRECATION WARNING: use #dom_classes instead of #classes (called from #{caller(3..3).first})"
       dom_classes
     end
 
-    # rubocop:disable Metrics/LineLength
     ##
     # Returns the I18n translation for `comparison.style`.
     #
@@ -171,49 +173,56 @@ module Comparison
     #
     #     en:
     #       comparison:
-    #         style:
+    #         inline_style:
     #           positive: 'color: #3c763d; background-color: #dff0d8;'
     #           negative: 'color: #a94442; background-color: #f2dede;'
     #           nochange: 'color: #777777;'
     #
-    #     content_tag :span, cmp.difference, style: cmp.style
+    #     content_tag :span, cmp.difference, style: cmp.inline_style
     #     # => "<span style=\"color: #3c763d; background-color: #dff0d8;\">+10%</span>"
     #
     # In general, it's probably preferable to use `#dom_classes` in conjunction
     # with CSS style rules defined separate CSS files, but this isn't always
     # possible.
     #
-    # rubocop:enable Metrics/LineLength
-    def style
+    def inline_style
+      key, *deprecated_keys = expand_i18n_keys(%w[inline_style style css])
+      t key, default: [*deprecated_keys, '']
+    end
+
+    alias style inline_style
+
+    def css
+      Kernel.warn "DEPRECATION WARNING: use #inline_style instead of #css (called from #{caller(3..3).first})"
+      inline_style
+    end
+
+    ##
+    # Returns a string description of the direction of change. Possible
+    # descriptions are "positive", "negative", and "nochange".
+    def description
       if positive?
-        t 'comparison.style.positive',
-          default: [:'comparison.css.positive', '']
+        'positive'
       elsif negative?
-        t 'comparison.style.negative',
-          default: [:'comparison.css.negative', '']
+        'negative'
       else
-        t 'comparison.style.nochange',
-          default: [:'comparison.css.nochange', '']
+        'nochange'
       end
     end
 
-    def css
-      Kernel.warn '[DEPRECATION WARNING] #css is deprecated: ' \
-        "use #style instead: #{caller(3..3).first}"
-      style
-    end
-
     private
 
-    def number_to_percentage(value, delimiter: ',', precision: 0, **options)
-      ActiveSupport::NumberHelper.number_to_percentage value,
-        delimiter: delimiter,
-        precision: precision,
-        **options
+    def number_to_percentage(value, **options)
+      options = { delimiter: ',', precision: 0, **options }
+      ActiveSupport::NumberHelper.number_to_percentage value, options
     end
 
     def number_to_currency(*args)
       ActiveSupport::NumberHelper.number_to_currency(*args)
     end
+
+    def expand_i18n_keys(names, suffix: nil)
+      Array(names).map { |name| :"comparison.#{name}.#{description}#{suffix}" }
+    end
   end
 end

data/lib/comparison/version.rb

@@ -1,5 +1,5 @@
 # frozen-string-literal: true
 
 module Comparison
-  VERSION = '0.1.99'
+  VERSION = '0.2.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: comparison
 version: !ruby/object:Gem::Version
-  version: 0.1.99
+  version: 0.2.1
 platform: ruby
 authors:
 - John Parker
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-10-30 00:00:00.000000000 Z
+date: 2022-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,22 +16,22 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '5.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '5.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
-  name: minitest-focus
+  name: mocha
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -101,15 +101,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.3'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 3.3.12
 signing_key: 
 specification_version: 4
 summary: Helpers for displaying details of comparing two numbers.