panier 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6d71eb654f6c9e4f3d3812729a1ed98f61fd62de
+  data.tar.gz: 61e6d3d591c2f9f657213b8b64184c749930304d
+SHA512:
+  metadata.gz: f407468ecdcd83e83550a0145d97a69426bb87c821de09ffb74a5881cf07f6700388a2d194bc686b904a078cf9b30ae1907b25bb893bda7cf3d31794b98eaeb7
+  data.tar.gz: daf083bdab9397125c3b7b9bc3df7fe1105d64ded6d0856f3bfc2b9bf751162d6461c9f5d49554229c283a8c4fca97b156117490fbf6aeeabd6e6b67730d0ec7

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Luke Eller
+
+MIT License
+
+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,33 @@
+# Panier
+
+This gem demonstrates the calculation of sales taxes for various kinds of line items on a receipt.
+
+## Documentation
+
+- [Application](docs/application.md)
+- [Domain model](docs/domain_model.md)
+- [Implementation notes](docs/implementation_notes.md)
+- [Examples](docs/examples.md)
+
+## Requirements
+
+* Ruby 2.1.2+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'panier'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install panier
+
+## Usage
+
+TODO: Write usage instructions here
+

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task default: :spec

data/bin/panier

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+if RUBY_VERSION >= '2.1.2'
+  $LOAD_PATH.unshift(File.dirname(File.realpath(__FILE__)) + '/../lib')
+
+  require 'panier'
+
+  cli = Panier::Application::CLI.new
+
+  exit cli.run
+else
+  puts 'Panier supports only Ruby 2.1.2+'
+  exit(-1)
+end

data/docs/application.md

@@ -0,0 +1,9 @@
+# Application
+
+## Sales tax service
+
+This service is the core application service, fulfilling the core requirement of accepting input in the form of a list of products and producing a receipt in CSV format.
+
+## CLI
+
+The command line interface provides an interactive console application, allowing users to enter input data directly and view a receipt.

data/docs/domain_model.md

@@ -0,0 +1,21 @@
+# Domain model
+
+## Receipt
+
+A receipt is a value object describing a payment that has been made by a shopper to a merchant in relation to an order.
+
+## Line item
+
+A line item is a value object representing a single line a receipt. It describes the item represented and contains a reference to it, has a quantity, a unit amount, a tax class and can calculate its total amount and total tax.
+
+## Product
+
+A product is a purchasable item with a price and one or more tax classes that allow taxes to be calculated accurately.
+
+## Tax class
+
+A tax class is a value object that describes a particular type of tax or duty applicable to products sold. It has a name and a rate.
+
+Its association with a product means that the orders made for that product are subject to tax at the rate represented by the tax class.
+
+References to tax classes are held by a line item and used in the calculation of tax for that item. 

data/docs/examples.md

@@ -0,0 +1,45 @@
+# Input
+
+## Input 1
+Quantity, Product, Price
+1, book, 12.49
+1, music CD, 14.99
+1, chocolate bar, 0.85
+
+## Input 2
+Quantity, Product, Price
+1, imported box of chocolates, 10.00
+1, imported bottle of perfume, 47.50
+
+## Input 3
+Quantity, Product, Price
+1, imported bottle of perfume, 27.99
+1, bottle of perfume, 18.99
+1, packet of headache pills, 9.75
+1, box of imported chocolates, 11.25
+
+# Output
+
+## Output 1
+1, book, 12.49
+1, music CD, 16.49
+1, chocolate bar, 0.85
+
+Sales Taxes: 1.50
+Total: 29.83
+
+## Output 2
+1, imported box of chocolates, 10.50
+1, imported bottle of perfume, 54.65
+
+Sales Taxes: 7.65
+Total: 65.15
+
+## Output 3
+1, imported bottle of perfume, 32.19
+1, bottle of perfume, 20.89
+1, packet of headache pills, 9.75
+1, box of imported chocolates, 11.85
+
+Sales Taxes: 6.70
+Total: 74.68

data/docs/implementation_notes.md

@@ -0,0 +1,39 @@
+# Implementation notes
+
+## Style
+
+Because no web interface is necessary to demonstrate the core application code, the application has been implemented as a standalone gem with a command line interface.
+
+## Assumptions
+
+With regard to the given coding exercise, the following assumptions have been made.
+
+* We are interested in calculating tax for the purposes of generating an itemised receipt.
+* We assume a preexisting product catalog, where each product contains one more more tax classes.
+* Products may be selected by the shopper from the preexisting product catalog. This catalog is limited to the items in the test data. Unknown items are ignored.
+* The product name is the same for input and output. Some changes to input data had to be made to allow for discrepancies. TODO: Name the changes.
+* There are some products with the same name and different prices. We can assume that these items are available in various sizes.
+
+## Design considerations
+
+### Input
+
+The input is considered to be a selection of products from a preexisting catalog. The items are looked from the internal product service based on name and price. If neither match, no item is returned.
+
+### Order workflow
+
+In a real world application, the order domain class would have more states. For the purposes of this demonstration, only two states are defined: _awaiting payment_ and _completed_.
+
+### Line items
+
+The line item keeps a reference to the product's price and tax classes so that if the mutable product should change, the line item is unaffected. This is important because once a contract has been established between a merchant and a shopper via an order, the terms of that contract should not be changed.
+
+The tax rounding calculation originally took place within the line item class. It was decided that making the policy of tax rounding more explicit by representing it in a standalone strategy object would be more expressive.
+
+### Product service
+
+This is an in-memory implementation, useful for testing, which contains only the products from the given input data. A real-world implementation would be backed by a database or web service.
+
+### Decorator
+
+The receipt decorator was created to separate the concern of formatting a receipt for display in CSV format from the receipt domain object.

data/lib/panier/application/cli.rb

@@ -0,0 +1,72 @@
+include Panier::Domain
+
+module Panier
+  module Application
+    ##
+    # A class responsible for handling the command line interface input.
+    #
+    class CLI
+      EXIT_SUCCESS = 0
+      EXIT_FAILURE = -1
+
+      def initialize
+        I18n.enforce_available_locales = false
+        @service = SalesTaxService.new
+      end
+
+      ##
+      # The main application loop.
+      #
+      def run
+        begin
+          print_welcome
+          loop do
+            prompt_for_input
+          end
+        rescue SignalException, Interrupt
+          puts "\nExiting..."
+        end
+
+        EXIT_SUCCESS
+      end
+
+      private
+
+      ##
+      # Prints a welcome message and instructions about how to quit.
+      #
+      def print_welcome
+        puts "Welcome to Panier.\n"
+        puts 'Press Ctrl+C to exit.'
+      end
+
+      ##
+      # Asks the user for input and processes it when given.
+      #
+      def prompt_for_input
+        puts 'Enter some sample input, then leave a blank line to proceed.'
+
+        input = []
+        $stdin.each do |line|
+          break if line.nil? || line.chomp.empty?
+          input << line.chomp
+        end
+
+        input = input.join("\n")
+        process_input(input) unless input.empty?
+      end
+
+      ##
+      # Given a complete set of input, prints a receipt.
+      #
+      def process_input(input)
+        begin
+          puts @service.evaluate_input(input)
+        rescue ArgumentError
+          $stderr.puts 'The input was invalid.'
+        end
+        puts
+      end
+    end
+  end
+end

data/lib/panier/application/input_reader.rb

@@ -0,0 +1,41 @@
+require 'csv'
+
+include Panier::Domain
+
+module Panier
+  module Application
+    ##
+    # The InputReader is responsible for parsing raw input data.
+    #
+    class InputReader
+      CELLS_PER_LINE = 3
+      HEADER = /quantity.*?,.*?product.*?,.*?price/i
+
+      def initialize(product_service = nil)
+        @product_service = product_service ||
+            Panier::Domain::ProductService.new
+      end
+
+      def parse_input(input)
+        line_items = input.lines.reject(&:blank?).map do |line|
+          parse_line(line)
+        end
+        line_items.reject(&:nil?)
+      end
+
+      def parse_line(line)
+        return nil if line.match(HEADER)
+        parsed = CSV.parse_line(line)
+        unless parsed.count == CELLS_PER_LINE
+          fail ArgumentError, 'invalid input'
+        end
+        quantity = Integer(parsed[0])
+        name = parsed[1].strip
+        price = Money.new(Float(parsed[2]) * 100)
+
+        product = @product_service.find_by_name_and_price(name, price)
+        product.present? ? LineItem.new(product, quantity) : nil
+      end
+    end
+  end
+end

data/lib/panier/application/sales_tax_service.rb

@@ -0,0 +1,28 @@
+# Encoding: utf-8
+include Panier::Domain
+
+module Panier
+  module Application
+    ##
+    # This is an application layer service responsible for handling the
+    # use-case of taking a list of items and producing a receipt.
+    #
+    class SalesTaxService
+      def initialize(input_reader = nil)
+        @input_reader = input_reader || InputReader.new
+      end
+
+      ##
+      # Accepts a list of products and produces a receipt.
+      #
+      # @param [String] input A list of products in CSV format.
+      # @param [String] A receipt in CSV format.
+      def evaluate_input(input)
+        line_items = @input_reader.parse_input(input)
+        receipt = Receipt.new(line_items)
+        decorator = Panier::Decorators::ReceiptDecorator.new(receipt)
+        decorator.to_csv
+      end
+    end
+  end
+end

data/lib/panier/decorators/decorator.rb

@@ -0,0 +1,25 @@
+# Encoding: utf-8
+
+module Panier
+  module Decorators
+    ##
+    # Defines basic behaviour common to decorators.
+    #
+    module Decorator
+      attr_reader :decorated
+
+      def initialize(decorated)
+        @decorated = decorated
+      end
+
+      def method_missing(symbol, *args, &block)
+        super unless @decorated.respond_to? symbol
+        @decorated.send(symbol, *args, &block)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @decorated.respond_to?(name, include_private) || super
+      end
+    end
+  end
+end

data/lib/panier/decorators/receipt_decorator.rb

@@ -0,0 +1,29 @@
+# Encoding: utf-8
+require 'csv'
+
+module Panier
+  module Decorators
+    ##
+    # Decorates a receipt with presentation-specific methods.
+    #
+    class ReceiptDecorator
+      include Decorator
+
+      ##
+      # Generates CSV string expressing the details of the receipt.
+      #
+      # @return [String] CSV expressing the details of the receipt.
+      def to_csv
+        ::CSV.generate do |csv|
+          decorated.line_items.each do |item|
+            csv << [item.quantity, " #{item.description}",
+                    " #{item.total_amount_inc_tax}"]
+          end
+          csv << []
+          csv << ["Sales Taxes: #{total_tax}"]
+          csv << ["Total: #{total_amount}"]
+        end
+      end
+    end
+  end
+end

data/lib/panier/domain/line_item.rb

@@ -0,0 +1,85 @@
+# Encoding: utf-8
+require 'money'
+
+module Panier
+  module Domain
+    ##
+    # A line item is a value object representing a single line of an order or
+    # receipt.
+    #
+    class LineItem
+      ##
+      # The fractional value to which tax rounding calculations are made.
+      #
+      TAX_ROUNDING_VALUE = 5
+
+      attr_reader :product, :quantity, :unit_amount, :tax_classes, :description
+
+      ##
+      # Initializes the line such that it represents the given quantity of
+      # products.
+      #
+      # @param product [Product] The product represented in the line item.
+      # @param quantity [Integer] The number of products represented.
+      def initialize(product, quantity)
+        @product = product
+        self.quantity = quantity
+        @rounding_strategy = RoundUpRounding.new(TAX_ROUNDING_VALUE)
+        @description = product.name
+        @unit_amount = product.price
+        @tax_classes = product.tax_classes.dup
+      end
+
+      ##
+      # Calculates the total value of the line item.
+      #
+      def total_amount
+        unit_amount * quantity
+      end
+
+      ##
+      # Calculates the total tax included in the line item.
+      #
+      def total_tax
+        unit_tax * quantity
+      end
+
+      ##
+      # Calculates the total value of the line item including tax.
+      #
+      # @return [Money] The total value of the line item including tax.
+      def total_amount_inc_tax
+        unit_amount_inc_tax * quantity
+      end
+
+      ##
+      # Calculates the value of a single unit including tax.
+      #
+      def unit_amount_inc_tax
+        unit_amount + unit_tax
+      end
+
+      ##
+      # Calculates the tax applicable to one unit of the line item.
+      #
+      def unit_tax
+        tax = Money.new(0)
+        tax_classes.each do |tax_class|
+          class_tax = @rounding_strategy.round(tax_class.rate * unit_amount)
+          tax += class_tax
+        end
+        tax
+      end
+
+      private
+
+      def quantity=(quantity)
+        unless quantity.is_a? Integer
+          fail ArgumentError, ':quantity must be a whole number'
+        end
+        fail ArgumentError, ':quantity must be non-negative' if quantity < 0
+        @quantity = quantity
+      end
+    end
+  end
+end

data/lib/panier/domain/product.rb

@@ -0,0 +1,33 @@
+# Encoding: utf-8
+
+module Panier
+  module Domain
+    ##
+    # A product is a purchasable item with a price and one or more tax classes
+    # that allow taxes to be calculated accurately.
+    #
+    class Product
+      attr_accessor :name, :tax_classes
+      attr_reader :price
+
+      ##
+      # Initializes the product using the given name, price and optional tax
+      # classes.
+      #
+      # @param name [String]
+      # @param price [Money]
+      # @param tax_classes [Array]
+      #
+      def initialize(name, price, tax_classes = [])
+        @name = name
+        self.price = price
+        @tax_classes = tax_classes
+      end
+
+      def price=(price)
+        fail ArgumentError, ':price must be non-negative' if price.negative?
+        @price = price
+      end
+    end
+  end
+end

data/lib/panier/domain/product_service.rb

@@ -0,0 +1,47 @@
+require 'money'
+
+module Panier
+  module Domain
+    ##
+    # The product service provides a means of finding and retrieving products
+    # from the product catalog.
+    #
+    # This is an in-memory implementation, useful for testing, which contains
+    # only the products from the given input data. A real-world implementation
+    # would be backed by a database or web service.
+    #
+    class ProductService
+      def initialize
+        @tax = TaxClass.new('Basic sales tax', 0.1)
+        @duty = TaxClass.new('Import duty', 0.05)
+
+        @products = product_data.map do |row|
+          Product.new(*row)
+        end
+      end
+
+      def product_data
+        [['book', Money.new(1249)],
+         ['music CD', Money.new(1499), [@tax]],
+         ['chocolate bar', Money.new(85)],
+         ['imported box of chocolates', Money.new(1000), [@duty]],
+         ['imported bottle of perfume', Money.new(4750), [@tax, @duty]],
+         ['imported bottle of perfume', Money.new(2799), [@tax, @duty]],
+         ['bottle of perfume', Money.new(1899), [@tax]],
+         ['packet of headache pills',   Money.new(975)],
+         ['box of imported chocolates', Money.new(1125), [@duty]]]
+      end
+
+      ##
+      # Finds a product matching the given name and price.
+      #
+      # @param [String] name
+      # @param [Money] price
+      def find_by_name_and_price(name, price)
+        @products.find do |product|
+          product.name == name && product.price == price
+        end
+      end
+    end
+  end
+end

data/lib/panier/domain/receipt.rb

@@ -0,0 +1,40 @@
+# Encoding: utf-8
+
+module Panier
+  module Domain
+    ##
+    # A receipt is a value object describing a payment that has been made by a
+    # shopper to a merchant in relation to an order.
+    #
+    class Receipt
+      attr_reader :line_items
+
+      ##
+      # Initializes the receipt with the given line items.
+      #
+      # @param line_items [Array] The line items to be represented on the
+      #   receipt.
+      def initialize(line_items)
+        @line_items = line_items
+      end
+
+      ##
+      # Calculates the total value of the receipt by adding together the total
+      # values of all line items.
+      #
+      # @return [Money] The total value of the receipt.
+      def total_amount
+        line_items.reduce(Money.zero) { |a, e| a + e.total_amount_inc_tax }
+      end
+
+      ##
+      # Calculates the total tax present on the receipt by adding together the
+      # total tax of all line items.
+      #
+      # @return [Money] The total tax present on the receipt.
+      def total_tax
+        line_items.reduce(Money.zero) { |a, e| a + e.total_tax }
+      end
+    end
+  end
+end

data/lib/panier/domain/round_up_rounding.rb

@@ -0,0 +1,38 @@
+require 'money'
+
+module Panier
+  module Domain
+    ##
+    # A money-rounding strategy that rounds fractional values up to the nearest
+    # increment. For example, $0.21 would be rounded up to $0.25.
+    #
+    class RoundUpRounding
+      ##
+      # @param increment [Integer] The fractional value to which rounding
+      #   calculations are made.
+      #
+      def initialize(increment = 5)
+        self.increment = increment
+      end
+
+      ##
+      # Rounds a monetary value up to the nearest increment.
+      #
+      # @param value [Money] The amount of tax to be rounded.
+      #
+      def round(value)
+        unless value % @increment == Money.zero
+          value += Money.new(@increment) - value % @increment
+        end
+        value
+      end
+
+      private
+
+      def increment=(increment)
+        fail ArgumentError ':increment must be non-negative' if increment < 0
+        @increment = increment
+      end
+    end
+  end
+end