comparison 0.1.0 → 0.1.99

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: baea273a06f0a0abb98d762a042fa9839ffd1c0e
-  data.tar.gz: 0b801fed057465fd098120a14e9cf931851c9198
+SHA256:
+  metadata.gz: 3a1be3dfdb9956ab89e40615d7e019ac31cefb24596e236acb5a99c4e30ff15a
+  data.tar.gz: b8fce566958ce9801c2ccdab4adce9bbe9739e48b2fd92464763886702f918a6
 SHA512:
-  metadata.gz: 6511bc82b1f7fde3f6c13f4d2ae1ad56622d08f3ec65a15a670c8fa370684996ea395d36455763f4894460ce8ca1920ff2f37ff7db4f473ef9305944e27fc3b7
-  data.tar.gz: ccd9104172486a78800166080e0ba1268008b41bc36ae34524bc491f3576fc30562446110a48b05933b6cffbe051b33f431b47b6be7ba2b8e6dc45ffff950c4b
+  metadata.gz: 5a252e4fd07af9024f0972b5a42b5665fac54f1807cbd7f88affd2236bbd9448ad57ae79bc9c78ba31901c723015a0b50fae6ffd46cf78af0d2e8468c6d83ff0
+  data.tar.gz: f9d8b42bfed576f00e8bb200272b001f64a123f709603445e4a6fe165e7f6d4132f967308b3747cf5364c489d74b1b0647e18ebc1f1b78dd40282ec2ffd51f97

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2016 John Parker
+Copyright 2018 John Parker
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,17 +1,32 @@
+# [![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)
+
 # Comparison
 
-I have often found myself implementing reporting features that compare two
-numbers to each other. For example, a report that compares the outcome for a
-quarter to the outcome of the same quarter in the prior year. Frequently I end
-up displaying both the raw difference between the two numbers, the percentage
-difference, and maybe a simple visual indicator such as an arrow (pointing up
-or down). Sometimes these comparisons require special handling for Infinity and
-NaN when one or both numbers are zero.
+Comparison bundles up into Rails helpers the logic for rendering visually
+informative comparisons of numbers. For example, say you were comparing the
+sales figures from one quarter to the same quarter in a previous year. You
+might want to show the percentage change, accompanied by an arrow or icon and
+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.
 
-I've tackled this task enough times and in enough applications that I felt it
-would simplify my life to extract and package the code for future re-use.
+`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
@@ -53,6 +68,7 @@ change, an empty string).
 
 
 ## Configuration
+
 Comparison uses I18n to configure the output of some of the Presenter methods.
 Default implementations are provided where it makes sense. You can provide your
 own implementations by adding translations to your application.
@@ -60,11 +76,11 @@ own implementations by adding translations to your application.
 ```yml
 en:
   comparison:
-    classes:
+    dom_classes:
       positive: 'comparison positive'
       negative: 'comparison negative'
       nochange: 'comparison nochange'
-    css:
+    style:
       positive_html: 'color: #3c763d; background-color: #dff0d8;'
       negative_html: 'color: #a94442; background-color: #f2dede;'
       nochange_html: 'color: #777777;'
@@ -79,6 +95,7 @@ en:
 ```
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -96,9 +113,11 @@ $ gem install comparison
 ```
 
 ## Contributing
+
 Open an GitHub issue for problems and suggestions. This library is in its
 infancy, so use it at your own risk.
 
 ## License
+
 The gem is available as open source under the terms of the
 [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen-string-literal: true
+
 begin
   require 'bundler/setup'
 rescue LoadError
@@ -14,22 +16,19 @@ RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-
+APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
 
 load 'rails/tasks/statistics.rake'
 
-
-
 require 'bundler/gem_tasks'
 
 require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
   t.libs << 'test'
   t.pattern = 'test/**/*_test.rb'
   t.verbose = false
 end
 
-
 task default: :test

data/app/helpers/comparison/application_helper.rb

@@ -1,13 +1,18 @@
+# frozen-string-literal: true
+
 module Comparison
-  module ApplicationHelper
+  module ApplicationHelper # :nodoc:
     ##
     # Returns a Presenter for a Comparator for +m+ and +n+.
     #
     # 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
       yield comparison if block_given?
       comparison
     end
+    # rubocop:enable Naming/UncommunicativeMethodParamName
   end
 end

data/config/locales/en.yml

@@ -4,14 +4,17 @@ en:
     #   positive: 'comparison positive'
     #   negative: 'comparison negative'
     #   nochange: 'comparison nochange'
-    css:
-      positive_html: ''
-      negative_html: ''
-      nochange_html: ''
+
     # icons:
     #   positive_html: '<span class="glyphicon glyphicon-arrow-up"></span>'
     #   negative_html: '<span class="glyphicon glyphicon-arrow-down"></span>'
     #   nochange_html: '<span class="glyphicon glyphicon-minus"></span>'
+
+    style:
+      positive_html: ''
+      negative_html: ''
+      nochange_html: ''
+
     arrows:
       positive_html: '&uarr;'
       negative_html: '&darr;'

data/lib/comparison.rb

@@ -1,6 +1,8 @@
+# frozen-string-literal: true
+
 require 'comparison/engine'
 require 'comparison/comparator'
 require 'comparison/presenter'
 
-module Comparison
+module Comparison # :nodoc:
 end

data/lib/comparison/comparator.rb

@@ -1,16 +1,26 @@
+# frozen-string-literal: true
+
 require 'bigdecimal'
 require 'forwardable'
 
 module Comparison
+  ##
+  # The Comparator object compares two numbers to each other and exposes the
+  # raw and percentage differences.
   class Comparator
     extend Forwardable
 
     ##
     # Instantiates a new Comparator to compare two numbers, +m+ and +n+.
+    #
+    # 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
     end
+    # rubocop:enable Naming/UncommunicativeMethodParamName
 
     attr_reader :m, :n
 
@@ -22,7 +32,7 @@ module Comparison
       @absolute ||= m - n
     end
 
-    alias_method :difference, :absolute
+    alias difference absolute
 
     ##
     # Returns the percentage difference of +@m+ to +@n+.
@@ -34,6 +44,6 @@ module Comparison
                     end
     end
 
-    alias_method :percentage, :relative
+    alias percentage relative
   end
 end

data/lib/comparison/engine.rb

@@ -1,9 +1,11 @@
+# frozen-string-literal: true
+
 module Comparison
-  class Engine < ::Rails::Engine
+  class Engine < ::Rails::Engine # :nodoc:
     isolate_namespace Comparison
 
     initializer 'comparison.view_helpers' do
-      ActionView::Base.send :include, ApplicationHelper
+      ActionView::Base.send :include, helpers
     end
   end
 end

data/lib/comparison/presenter.rb

@@ -1,19 +1,20 @@
 # frozen-string-literal: true
 
 require 'delegate'
-require 'forwardable'
 
 module Comparison
+  ##
+  # The Presenter object wraps a Comparator with methods that return
+  # view-friendly output.
   class Presenter < DelegateClass(Comparator)
-    extend Forwardable
     include ActionView::Helpers::TranslationHelper
 
-    ARROWS = { up: '&uarr;', down: '&darr;', none: '' }
+    ARROWS = { up: '&uarr;', down: '&darr;', none: '' }.freeze
 
     # TODO: This shouldn't necessarily return a currency representation.
 
     ##
-    # Returns `Comparator#absolute` presented as currency.
+    # Returns Comparator#absolute presented as currency.
     def difference(**options)
       if positive?
         number_to_currency absolute, format: '+%u%n', **options
@@ -23,33 +24,26 @@ module Comparison
     end
 
     ##
-    # Returns `Comparator#relative` formatted as a percentage.
+    # Returns Comparator#relative formatted as a percentage.
     #
     # If the relative percentage evaluates to Infinity or -Infinity, +nil+ is
     # returned. If it evaluates to NaN, 0 is returned.
-    def percentage(delimiter: ',', precision: 0, **options)
-      case
-      when nan? || zero?
-        number_to_percentage 0, precision: precision, **options
-      when infinite?
+    def percentage(**options)
+      if nan? || zero?
+        number_to_percentage 0, **options
+      elsif infinite?
         # TODO: Return nil, or lookup an optional representation in I18n?
         nil
-      when positive?
-        number_to_percentage relative, delimiter: delimiter,
-          precision: precision, format: '+%n%', **options
+      elsif positive?
+        number_to_percentage relative, format: '+%n%', **options
       else
-        number_to_percentage relative, delimiter: delimiter,
-          precision: precision, **options
+        number_to_percentage relative, **options
       end
     end
 
-    alias_method :change, :percentage
-    deprecate :change
-
-    delegate %i[number_to_currency number_to_percentage] => :'ActiveSupport::NumberHelper'
-
+    # rubocop:disable Metrics/LineLength
     ##
-    # Returns the I18n translation for `comparison.icons`. (See also `#arrow`.)
+    # Returns the I18n translation for `comparison.icons`. (See also #arrow.)
     #
     # This method is intended to display a graphical representation of the
     # comparison. Typically this would be an arrow pointing up or down.
@@ -61,17 +55,18 @@ module Comparison
     # with Bootstrap, you could add the following translations to your
     # application:
     #
-    # en:
-    #   comparison:
-    #     icons:
-    #       positive_html: '<span class="glyphicon glyphicon-arrow-up"></span>'
-    #       negative_html: '<span class="glyphicon glyphicon-arrow-down"></span>'
-    #       nochange_html: '<span class="glyphicon glyphicon-minus"></span>'
+    #     en:
+    #       comparison:
+    #         icons:
+    #           positive_html: '<span class="glyphicon glyphicon-arrow-up"></span>'
+    #           negative_html: '<span class="glyphicon glyphicon-arrow-down"></span>'
+    #           nochange_html: '<span class="glyphicon glyphicon-minus"></span>'
+    #
+    # rubocop:enable Metrics/LineLength
     def icon
-      case
-      when positive?
+      if positive?
         t 'comparison.icons.positive_html'
-      when negative?
+      elsif negative?
         t 'comparison.icons.negative_html'
       else
         t 'comparison.icons.nochange_html'
@@ -79,40 +74,39 @@ module Comparison
     end
 
     ##
-    # Returns the I18n translation for `comparison.icons`. (See also `#icon`.)
+    # Returns the I18n translation for `comparison.icons`. (See also #icon.)
     #
     # This method is intended to display a graphical representation of the
     # comparison. Typically this would be an arrow pointing up or down.
     #
     # The default implementation is as follows:
     #
-    # en:
-    #   comparison:
-    #     arrows:
-    #       positive_html: '&uarr;'
-    #       negative_html: '&darr;'
-    #       nochange_html: ''
+    #     en:
+    #       comparison:
+    #         arrows:
+    #           positive_html: '&uarr;'
+    #           negative_html: '&darr;'
+    #           nochange_html: ''
     #
     # For example, to generate up and down arrows using Glyphicons included
     # with Bootstrap, you could add the following translations to your
     # application:
     #
-    # `#arrows` and its sister method `#icon` perform roughly identical tasks
-    # with roughly identical intentions. The difference between the two methods
-    # is in the context in which they are intended to be used.
+    # #arrows and its sister method #icon perform roughly identical tasks with
+    # roughly identical intentions. The difference between the two methods is
+    # in the context in which they are intended to be used.
     #
-    # `#arrows` is meant to be used from view contexts with limited
-    # functionality such as an HTML email. As such, the translations you
-    # specify should be simple enough, like HTML character entities, to work
-    # within said view context.
+    # #arrows is meant to be used from view contexts with limited functionality
+    # such as an HTML email. As such, the translations you specify should be
+    # simple enough, like HTML character entities, to work within said view
+    # context.
     #
-    # `#icons` is meant to be used from full-featured view contexts. As such,
-    # `#icons` is the one to use to generate HTML tags.
+    # #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
-      case
-      when positive?
+      if positive?
         t 'comparison.arrows.positive_html', default: ARROWS[:up]
-      when negative?
+      elsif negative?
         t 'comparison.arrows.negative_html', default: ARROWS[:down]
       else
         t 'comparison.arrows.nochange_html', default: ARROWS[:none]
@@ -120,72 +114,106 @@ module Comparison
     end
 
     ##
-    # Returns the I18n translation for `comparison.classes`. (See also `#css`.)
+    # Returns the I18n translation for `comparison.dom_classes`.
     #
     # Use these translations to specify CSS classes for tags that contain
     # comparison data. For example:
     #
-    # en:
-    #   comparison:
-    #     classes:
-    #       positive: 'comparison positive'
-    #       negative: 'comparison negative'
-    #       nochange: 'comparison nochange'
-    #
-    # .comparison.positive {
-    #   color: #3c763d;
-    #   background-color: #dff0d8;
-    # }
-    # .comparison.negative {
-    #   color: #a94442;
-    #   background-color: #f2dede;
-    # }
-    # .comparison.nochange {
-    #   color: #777777;
-    # }
-    #
-    # content_tag cmp.difference, class: cmp.classes
-    def classes
-      case
-      when positive?
-        t 'comparison.classes.positive'
-      when negative?
-        t 'comparison.classes.negative'
+    #     en:
+    #       comparison:
+    #         dom_classes:
+    #           positive: 'comparison positive'
+    #           negative: 'comparison negative'
+    #           nochange: 'comparison nochange'
+    #
+    #     .comparison.positive {
+    #       color: #3c763d;
+    #       background-color: #dff0d8;
+    #     }
+    #     .comparison.negative {
+    #       color: #a94442;
+    #       background-color: #f2dede;
+    #     }
+    #     .comparison.nochange {
+    #       color: #777777;
+    #     }
+    #
+    #     content_tag :span, cmp.difference, class: cmp.dom_classes
+    #     # => "<span class=\"comparison positive\">+10%</span>"
+    #
+    # If you need to work with inline styles instead of CSS classes, see the
+    # `#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.classes.nochange'
+        t 'comparison.dom_classes.nochange',
+          default: %i[comparison.classes.nochange]
       end
     end
 
+    def classes
+      Kernel.warn '[DEPRECATION WARNING] #classes is deprecated: ' \
+        "use #dom_classes instead: #{caller(3..3).first}"
+      dom_classes
+    end
+
+    # rubocop:disable Metrics/LineLength
     ##
-    # Returns the I18n translation for `comparison.css`. (See also `#classes`.)
+    # Returns the I18n translation for `comparison.style`.
     #
-    # Use these translations to specify raw CSS style rules to be used when
+    # Use these translations to specify inline CSS style rules to be used when
     # formatting comparison data. For example:
     #
-    # en:
-    #   comparison:
-    #     css:
-    #       positive: 'color: #3c763d; background-color: #dff0d8;'
-    #       negative: 'color: #a94442; background-color: #f2dede;'
-    #       nochange: 'color: #777777;'
+    #     en:
+    #       comparison:
+    #         style:
+    #           positive: 'color: #3c763d; background-color: #dff0d8;'
+    #           negative: 'color: #a94442; background-color: #f2dede;'
+    #           nochange: 'color: #777777;'
     #
-    # content_tag cmp.difference, style: cmp.css
+    #     content_tag :span, cmp.difference, style: cmp.style
+    #     # => "<span style=\"color: #3c763d; background-color: #dff0d8;\">+10%</span>"
     #
-    # `#css` and its sister method `#classes` perform very similar tasks. Use
-    # `#css` when you need to embed the CSS style rules in an HTML tag using
-    # the style attribute. Use `#classes` when you want have the CSS style
-    # rules defined in a class and want to add that class to the HTML tag.
-    def css
-      case
-      when positive?
-        t 'comparison.css.positive', default: ''
-      when negative?
-        t 'comparison.css.negative', default: ''
+    # 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.css.nochange', default: ''
+        t 'comparison.style.nochange',
+          default: [:'comparison.css.nochange', '']
       end
     end
 
-    alias_method :style, :css
+    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
+    end
+
+    def number_to_currency(*args)
+      ActiveSupport::NumberHelper.number_to_currency(*args)
+    end
   end
 end

data/lib/comparison/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: comparison
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.99
 platform: ruby
 authors:
 - John Parker
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-28 00:00:00.000000000 Z
+date: 2018-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -45,7 +45,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: pry-rails
+  name: pry
+  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: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -75,7 +89,6 @@ files:
 - lib/comparison/engine.rb
 - lib/comparison/presenter.rb
 - lib/comparison/version.rb
-- lib/tasks/comparison_tasks.rake
 homepage: https://github.com/jparker/comparison
 licenses:
 - MIT
@@ -88,7 +101,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -96,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.6
+rubygems_version: 2.7.7
 signing_key: 
 specification_version: 4
 summary: Helpers for displaying details of comparing two numbers.

data/lib/tasks/comparison_tasks.rake

@@ -1,4 +0,0 @@
-# desc "Explaining what the task does"
-# task :comparison do
-#   # Task goes here
-# end