comparison 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: baea273a06f0a0abb98d762a042fa9839ffd1c0e
+  data.tar.gz: 0b801fed057465fd098120a14e9cf931851c9198
+SHA512:
+  metadata.gz: 6511bc82b1f7fde3f6c13f4d2ae1ad56622d08f3ec65a15a670c8fa370684996ea395d36455763f4894460ce8ca1920ff2f37ff7db4f473ef9305944e27fc3b7
+  data.tar.gz: ccd9104172486a78800166080e0ba1268008b41bc36ae34524bc491f3576fc30562446110a48b05933b6cffbe051b33f431b47b6be7ba2b8e6dc45ffff950c4b

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2016 John Parker
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,104 @@
+# 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.
+
+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.
+
+## 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
+view.
+
+`#compare` helper takes the two numbers to be compared and yields the
+Comparison presenter to a block.
+
+`#difference` provides the absolute difference between the two numbers,
+literally `m - n`.
+
+`#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.
+
+`#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>
+  <td>
+    <%= cmp.arrow %>
+    <%= cmp.percentage precision: 1 %>
+  </td>
+<% end %>
+```
+
+| Period  | Outcome | LY      | Diff     | Pct           |
+| ------- | ------: | ------: | -------: | ------------: |
+| Q4 2016 | $200.00 |  $50.00 | +$150.00 | &uarr;+300.0% |
+| Q3 2016 | $125.00 | $100.00 |  +$25.00 |  &uarr;+25.0% |
+| Q2 2016 | $100.00 | $125.00 |  -$25.00 |  &darr;-20.0% |
+| Q1 2016 | $100.00 |   $0.00 | +$100.00 |        &uarr; |
+| Q4 2015 | $75.00  |  $75.00 |    $0.00 |          0.0% |
+| Q3 2015 | $0.00   |   $0.00 |    $0.00 |          0.0% |
+
+
+## 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.
+
+```yml
+en:
+  comparison:
+    classes:
+      positive: 'comparison positive'
+      negative: 'comparison negative'
+      nochange: 'comparison nochange'
+    css:
+      positive_html: 'color: #3c763d; background-color: #dff0d8;'
+      negative_html: 'color: #a94442; background-color: #f2dede;'
+      nochange_html: 'color: #777777;'
+    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>'
+    arrows:
+      positive_html: '&uarr;'
+      negative_html: '&darr;'
+      nochange_html: ''
+```
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'comparison'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ 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

@@ -0,0 +1,35 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Comparison'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+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

@@ -0,0 +1,13 @@
+module Comparison
+  module ApplicationHelper
+    ##
+    # Returns a Presenter for a Comparator for +m+ and +n+.
+    #
+    # If a block is given, the Presenter is yielded to the block.
+    def compare(m, n)
+      comparison = Presenter.new Comparator.new m, n
+      yield comparison if block_given?
+      comparison
+    end
+  end
+end

data/config/locales/en.yml

@@ -0,0 +1,18 @@
+en:
+  comparison:
+    # classes:
+    #   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>'
+    arrows:
+      positive_html: '&uarr;'
+      negative_html: '&darr;'
+      nochange_html: ''

data/lib/comparison.rb

@@ -0,0 +1,6 @@
+require 'comparison/engine'
+require 'comparison/comparator'
+require 'comparison/presenter'
+
+module Comparison
+end

data/lib/comparison/comparator.rb

@@ -0,0 +1,39 @@
+require 'bigdecimal'
+require 'forwardable'
+
+module Comparison
+  class Comparator
+    extend Forwardable
+
+    ##
+    # Instantiates a new Comparator to compare two numbers, +m+ and +n+.
+    def initialize(m, n)
+      @m = m.to_d
+      @n = n.to_d
+    end
+
+    attr_reader :m, :n
+
+    delegate %i[infinite? nan? negative? positive? zero?] => :relative
+
+    ##
+    # Returns the difference between +@m+ and +@n+.
+    def absolute
+      @absolute ||= m - n
+    end
+
+    alias_method :difference, :absolute
+
+    ##
+    # Returns the percentage difference of +@m+ to +@n+.
+    def relative
+      @relative ||= if n.negative?
+                      (1 - m / n) * 100
+                    else
+                      (m / n - 1) * 100
+                    end
+    end
+
+    alias_method :percentage, :relative
+  end
+end

data/lib/comparison/engine.rb

@@ -0,0 +1,9 @@
+module Comparison
+  class Engine < ::Rails::Engine
+    isolate_namespace Comparison
+
+    initializer 'comparison.view_helpers' do
+      ActionView::Base.send :include, ApplicationHelper
+    end
+  end
+end

data/lib/comparison/presenter.rb

@@ -0,0 +1,191 @@
+# frozen-string-literal: true
+
+require 'delegate'
+require 'forwardable'
+
+module Comparison
+  class Presenter < DelegateClass(Comparator)
+    extend Forwardable
+    include ActionView::Helpers::TranslationHelper
+
+    ARROWS = { up: '&uarr;', down: '&darr;', none: '' }
+
+    # TODO: This shouldn't necessarily return a currency representation.
+
+    ##
+    # Returns `Comparator#absolute` presented as currency.
+    def difference(**options)
+      if positive?
+        number_to_currency absolute, format: '+%u%n', **options
+      else
+        number_to_currency absolute, **options
+      end
+    end
+
+    ##
+    # 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?
+        # TODO: Return nil, or lookup an optional representation in I18n?
+        nil
+      when positive?
+        number_to_percentage relative, delimiter: delimiter,
+          precision: precision, format: '+%n%', **options
+      else
+        number_to_percentage relative, delimiter: delimiter,
+          precision: precision, **options
+      end
+    end
+
+    alias_method :change, :percentage
+    deprecate :change
+
+    delegate %i[number_to_currency number_to_percentage] => :'ActiveSupport::NumberHelper'
+
+    ##
+    # 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.
+    #
+    # No default implementation is included. You must provide the translations
+    # yourself or you will get missing translations.
+    #
+    # For example, to generate up and down arrows using Glyphicons included
+    # 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>'
+    def icon
+      case
+      when positive?
+        t 'comparison.icons.positive_html'
+      when negative?
+        t 'comparison.icons.negative_html'
+      else
+        t 'comparison.icons.nochange_html'
+      end
+    end
+
+    ##
+    # 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: ''
+    #
+    # 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` 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.
+    def arrow
+      case
+      when positive?
+        t 'comparison.arrows.positive_html', default: ARROWS[:up]
+      when negative?
+        t 'comparison.arrows.negative_html', default: ARROWS[:down]
+      else
+        t 'comparison.arrows.nochange_html', default: ARROWS[:none]
+      end
+    end
+
+    ##
+    # Returns the I18n translation for `comparison.classes`. (See also `#css`.)
+    #
+    # 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'
+      else
+        t 'comparison.classes.nochange'
+      end
+    end
+
+    ##
+    # Returns the I18n translation for `comparison.css`. (See also `#classes`.)
+    #
+    # Use these translations to specify raw 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;'
+    #
+    # content_tag cmp.difference, style: cmp.css
+    #
+    # `#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: ''
+      else
+        t 'comparison.css.nochange', default: ''
+      end
+    end
+
+    alias_method :style, :css
+  end
+end

data/lib/comparison/version.rb

@@ -0,0 +1,3 @@
+module Comparison
+  VERSION = '0.1.0'
+end

data/lib/tasks/comparison_tasks.rake

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

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: comparison
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- John Parker
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-09-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-focus
+  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-rails
+  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'
+description: Helpers for displaying details of comparing two numbers.
+email:
+- jparker@urgetopunt.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/helpers/comparison/application_helper.rb
+- config/locales/en.yml
+- lib/comparison.rb
+- lib/comparison/comparator.rb
+- 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
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.6
+signing_key: 
+specification_version: 4
+summary: Helpers for displaying details of comparing two numbers.
+test_files: []