comparison 0.1.100 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b0e8d2bec70b83572712b131b41afae523f0f5bf2a68057ebf0f3ceca471df7
-  data.tar.gz: 60d11ba61eedaca4bce96d1cceddeb7caf5f9ea11cf53cb6519a3380904ea8a6
+  metadata.gz: b1789756840509d6bfc178a7fce308b15e8097b8321362f36d2ceba7970862c0
+  data.tar.gz: cfd348911fee4ae30d3857985017d290dadb3f89af2e826b086b84a0c46c180e
 SHA512:
-  metadata.gz: ec743eb02eafcf845f4676d30f8606b7d3045fe5d98fc00a8dad0795996e483dd6a0c4ad94b25646ef7a9987dbe4dbd7e3561d66415b9fc1e1cfb205fcde2ae6
-  data.tar.gz: c499e868d7dac4693627c7ffad1d7a199cd9921ed6df3c262919ab558442ce7ae6172f13da5f5668a676a87c07d0b659f460827c6de6da32f5f8b46918701ece
+  metadata.gz: ce42dd5c8370367bdca1c66fa40277515b80c352c6db76222b4f0d5a9f8e40581a56d04396075802f86bbd4a41043167c719bb4d9406272e9d0ddd67792e43d9
+  data.tar.gz: f1d697351b7f16e05fc3b5394c5f22c70fac9f5e6db17cf5898cdd4adef82ecb8e4d83b3bbfd5fac113daa2f558f8ce83d3e5417b29c288d8c821cb4da325d70

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,7 +70,7 @@ en:
       positive: 'comparison positive'
       negative: 'comparison negative'
       nochange: 'comparison nochange'
-    style:
+    inline_style:
       positive: 'color: #3c763d; background-color: #dff0d8;'
       negative: 'color: #a94442; background-color: #f2dede;'
       nochange: 'color: #777777;'
@@ -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,30 +173,28 @@ 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
-      if positive?
-        t 'comparison.style.positive',
-          default: [:'comparison.css.positive', '']
-      elsif negative?
-        t 'comparison.style.negative',
-          default: [:'comparison.css.negative', '']
-      else
-        t 'comparison.style.nochange',
-          default: [:'comparison.css.nochange', '']
-      end
+    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
 
     ##
@@ -210,12 +210,6 @@ module Comparison
       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, **options)
@@ -226,5 +220,9 @@ module Comparison
     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.100'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: comparison
 version: !ruby/object:Gem::Version
-  version: 0.1.100
+  version: 0.2.0
 platform: ruby
 authors:
 - John Parker
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-06 00:00:00.000000000 Z
+date: 2022-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -19,7 +19,7 @@ dependencies:
         version: '4.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,7 @@ dependencies:
         version: '4.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: minitest-focus
   requirement: !ruby/object:Gem::Requirement
@@ -44,6 +44,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -101,14 +115,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: []
-rubygems_version: 3.0.2
+rubygems_version: 3.3.12
 signing_key: 
 specification_version: 4
 summary: Helpers for displaying details of comparing two numbers.