salestax 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a0fd7c247bcbb8a37acc5defcc9a57b095a9f0b4
-  data.tar.gz: c2741cf4cbaa3dffbe9f1f2367aa5ce1fe45fe40
+  metadata.gz: c8b0453465806dd4fc525a7f0488247d479005b6
+  data.tar.gz: d2749e2f79a6b87b351ffd412a14f4894218b710
 SHA512:
-  metadata.gz: 6bb6e03211201492c8f448b7e9094e5c50e1863f5dacfb30c2e06294bc961d22a4364c9e6d7f432d6ecb22e0317a0e7171ec8a44208580b84ab11b81bc3b00b6
-  data.tar.gz: 11346abbfd2b1a2127ea88e70cb928802ee7aeabaa1ce64c4b50826cdef649efdd54447cc8f89a7f017d690efd442e22960ba78863fb040099a9ef094cb23b40
+  metadata.gz: e4b6272bbc957e80a9695ad788bf30b6471e44140c258bea00a4fd782d82f4ae1b85423e4ea75382d933f0b159f7fa0cf6a43fd61672300df95f61a20035699d
+  data.tar.gz: afb0ea18e520db5e7e92565f0849b71aea83d5f5d93ef42d998b58a1804595c31b078a0707c4a444e39d54c62657644e0e84b5a9c6f2500f3fba578ea266e681

data/.gitignore

@@ -0,0 +1 @@
+.gem

data/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+## How to contribute
+
+Fork, then clone the repo:
+
+    git clone git@github.com:your-username/sales-tax.git
+
+Check you ruby and development dependencies versions:
+
+    $ ruby -v
+
+    $ gem list
+
+Make sure the tests pass:
+
+    rspec
+
+Make your change. Add tests for your change. Make the tests pass:
+
+    rspec
+
+Push to your fork and submit a pull request. Some things that are equal parts necessary/epic:
+
+ * Write tests.
+
+ * Follow a sensible style guide. My pick is [this one](https://github.com/bbatsov/ruby-style-guide).
+
+ * Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).

data/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <http://unlicense.org>

data/README.md

@@ -3,15 +3,135 @@ Sales Tax
 
 A basic sales tax calculator.
 
-## Description
+## Installation
 
-Basic sales tax is applicable at a rate of 10% on all goods, except books, food, and medical products that are exempt. Import duty is an additional sales tax applicable on all imported goods at a rate of 5%, with no exemptions.
+via RubyGems:
+
+    $ gem install salestax
+
+
+## Usage
+
+Pipe in a file with items:
+
+    $ salestax < path/to/file
+
+An example file with items:
+
+    1, book, 12.49
+    1, music CD, 14.99
+    1, chocolate bar, 0.85
+
+To which the calculator will print:
+
+    1, book, 12.49
+    1, music CD, 16.49
+    1, chocolate bar, 0.85
+
+    Sales Taxes: 1.50
+    Total: 29.83
+
+More example files can be found at `data/`
+
+## Dependencies
+
+    ruby version ~> 2.1.0p0
+
+To check your version run:
+
+    $ ruby -v
+
+To learn how to install ruby visit [ruby-lang.org/en/installation/](https://www.ruby-lang.org/en/installation/)
+
+
+## Troubleshooting
+
+### Development environment
+
+ * OSX 10.8.5, ruby 2.1.2p95
+
+Development dependencies:
+
+    rspec ~> 3.1
+
+To install them along the gem:
+
+    $ gem install --dev salestax
+
+### Compatible environments
+
+* Ubuntu 12.04 x32, ruby 2.1.0p0
+
+### Incompatible environments
+
+* ruby < 2.1.0
+
+### Tests
+
+To run the specs:
+
+    $ rspec
+
+To run just the integration tests:
+
+    $ rspec spec/features
+
+## Overview
+
+The application is designed to read items from `$stdin` and print the receipt to `$stdout`.
+
+### Input Format
+
+Items feed into the program are expected to be comma-separated values with the following format:
+
+    <quantity>, <description>, <unit_price>
+
+Example:
+
+    1, book, 12.49
+
+Please note the blank space between the commas and `<description>` / `<unit_price>`, since it is required.
+
+Each row in the input represents a line item of the receipt.
+
+#### Quantity
+
+Quantity is expected to be a whole value, thus only digits are allowed.
+
+#### Description
+
+Anything but a comma character is allowed in the description. They must contain at least one word character (letter, number, underscore).
+
+* Imported items should contain 'imported' in the description.
+
+* Food items should contain 'chocolate' in the description.
+
+* Medicine items should contain 'headache' in the description.
+
+* Book items should contain 'book' in the description.
 
-When I purchase items I receive a receipt that lists the name of all the items and their price (including tax), finishing with the total cost of the items, and the total amounts of sales taxes paid. The rounding rules for sales tax are that for a tax rate of n%, a shelf price of p contains (np/100 rounded up to the nearest 0.05) amount of sales tax.
+#### Unit price
 
-Write an application that prints out the receipt details for these shopping carts; this application should be written in Ruby [1] and use Rspec [2] to test inputs and the expected outputs. The output should be to standard out or CSV.
+Unit price is expected to be a decimal value, though it can be a whole one as well. A '.' is expected as the fractional separator.
 
-Proper object orientated design is important. Each row in the input represents a line item of the receipt.
+### Output Format
+
+A receipt will be printed that lists the name of all the items and their price (including tax), finishing with the total cost of the items, and the total amounts of sales taxes paid.
+
+Example:
+
+    1, book, 12.49
+    1, music CD, 16.49
+    1, chocolate bar, 0.85
+
+    Sales Taxes: 1.50
+    Total: 29.83
+
+### Taxing rules
+
+Basic sales tax is applicable at a rate of 10% on all goods, except books, food, and medical products that are exempt. Import duty is an additional sales tax applicable on all imported goods at a rate of 5%, with no exemptions.
+
+The rounding rules for sales tax are that for a tax rate of n%, a shelf price of p, it contains np/100 (rounded up to the nearest 0.05) amount of sales tax.
 
 ### Examples
 
@@ -65,3 +185,150 @@ Output:
 
     Sales Taxes: 6.70
     Total: 74.68
+
+## Design
+
+The application flows in the following way:
+
+#### 1 Launch
+
+    $ salestax < path/to/file
+
+##### 1.1 bin/salestax
+
+The `salestax` in the command is a ruby executable in your load path. This executable contains the following lines:
+
+```ruby
+require 'sales_tax'
+SalesTax::Application.new.run
+```
+
+The first line requires the file `./lib/sales_tax.rb` which loads the library. The second line creates and instance of the application.
+
+##### 1.2 lib/sales_tax/application.rb
+
+The `#run` method reads in items from the input source (defaults to `$stdin`) and passes them to the parser. The parser returns (might) a structured item which is added to the receipt.
+
+```ruby
+def run
+  loop do
+    raw_input = input.gets
+    break unless raw_input
+    raw_input.chomp!
+    line_item = parser.parse(raw_input)
+    receipt.add_item(line_item) if line_item
+  end
+  puts receipt.print
+end
+```
+
+##### 1.2.1 lib/sales_tax/line_item/parser.rb
+
+`parser.parse()` first calls a `@input_validator` function which checks the formating of the input. It the pre-process the input into a basic hash composed of the quantity, description and price of the item. It finally delegates the heavy lifting to the augmenter function which is in charge of extending the hash with actual taxing info.
+
+```ruby
+def parse(_in)
+  @input_validator.call(_in)
+  @augmenter.call(@pre_processor.call(_in))
+end
+```
+
+The `@augmenter` function delegates the actual augmenting feature to the augmenters, which in this case are hard-coded. The augmenters need to respond to the `#augment` message and either return the augmented hash or `nil` if they do not understand it.
+
+```ruby
+@augmenter = lambda do |_in|
+  augmented = nil
+  [LineItem::Book, LineItem::Medicine, LineItem::Food].each do |augmenter|
+    augmented = augmenter.augment(_in)
+    break if augmented
+  end
+  augmented || LineItem::Base.augment(_in)
+end
+```
+
+This function will return the first augmented hash it encounters or whatever `LineItem::Base.augment(_in)` returns.
+
+##### 1.2.1.1 lib/sales_tax/line_item/base.rb
+
+```ruby
+def self.augment(attributes)
+  new(attributes).to_hash if attributes[:description] =~ description_matcher
+end
+```
+
+This is the base method which `LineItem::(Food/Book/Medicine)` inherit. It tries to recognize the description in the hash, and if successful it will augment it.
+
+Augmenting it will actually involve a long series of messages, which I will not cover here. All of them are contained within `lib/sales_tax/line_item/base.rb` and `lib/sales_tax/accountable.rb`
+
+#### 1.2.2 lib/sales_tax/receipt.rb
+
+Next line in `Application#run` is:
+
+```ruby
+receipt.add_item(line_item) if line_item
+```
+
+This simply adds the `line_item`, which is actually a hash, to a @items array in the receipt.
+
+```ruby
+def add_item(item)
+  items << item
+end
+```
+
+This will be done for every line item. After all items have been added, the application prints the receipt:
+
+```ruby
+puts receipt.print
+```
+
+Printing will return a string with all the items printed out, as well as totals and sales tax totals.
+
+```ruby
+def print
+  _print = ''
+  _print << print_items
+  _print << "\n"
+  _print << print_totals
+  _print
+end
+```
+
+#### 2 Exit
+
+After the receipt is printed, the application exits.
+
+
+## Discussion
+
+My main design decisions / concerns in no specific order are:
+
+* `Accountable` depends on a `Taxable` role which only has a private interface. This is weird. A object should not depend on a private interface. The alternative here is to make that interface public (`#category`, `#imported?`, `#unit_price_str`), but that would make the `LineItem::Base` class to expose much more than I like. Another possible solution would be to make `Accountable` a class instead of a module, so that these messages can be passed as arguments. I liked the module approach better, which ended up bitting.
+
+* There is a pending test for `LineItem::Parser.parse` which should test that the method delegates the augmentation part of it. This behavior is only covered by the integration test. Implementing this test would mean having the dependencies injected into the parser, which is better and that is why the pending test is left there.
+
+*  `Receipt#print` loops two times through the `@items` array. One for printing the items, the second for calculating the totals. I found this to be more readable since it allowed me to break the method into sub-routines.
+
+* The quantity property of items is ignored since there is not enough information in the spec to decide what should be done with it. There is a [issue hosted on github](https://github.com/matiasanaya/sales-tax/issues/1) for this.
+
+* I found input inconsistencies which I did not know how to manage. The decision was to re-format the input and open [another issue](https://github.com/matiasanaya/sales-tax/issues/2)
+
+### Subtleties
+
+In `spec/shared_examples_for_line_item_base.rb` the following line:
+
+```
+it { expect(described_class).to respond_to :augment }
+```
+prints:
+
+    SalesTax::LineItem::Base
+      behaves like a line item
+        the public interface
+          should respond to #augment
+
+This should read `should respond to .augment` since it is a method on the class.
+
+## Contributing
+
+View [CONTRIBUTING.md](https://github.com/matiasanaya/sales-tax/blob/master/CONTRIBUTING.md)

data/bin/salestax

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
 
-require_relative '../lib/sales_tax'
+require 'sales_tax'
 
 SalesTax::Application.new.run

data/salestax.gemspec

@@ -0,0 +1,19 @@
+Gem::Specification.new do |spec|
+  spec.name          = 'salestax'
+  spec.version       = '0.0.2'
+  spec.authors       = ['Matias Anaya']
+  spec.email         = ['matiasanaya@gmail.com']
+  spec.summary       = %q{A basic sales tax calculator}
+  spec.description   = %q{A basic sales tax calculator utility, that accepts a list of items and prints a receipt with taxes.}
+  spec.homepage      = 'https://github.com/matiasanaya/sales-tax'
+  spec.license       = 'UNLICENSE'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = ['salestax']
+  spec.test_files    = spec.files.grep(%r{^(spec)/})
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '~> 2.1'
+
+  spec.add_development_dependency 'rspec', '~> 3.1'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: salestax
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Matias Anaya
@@ -34,6 +34,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- CONTRIBUTING.md
+- LICENSE
 - README.md
 - bin/salestax
 - data/example_input_a.txt
@@ -48,6 +50,7 @@ files:
 - lib/sales_tax/line_item/medicine.rb
 - lib/sales_tax/line_item/parser.rb
 - lib/sales_tax/receipt.rb
+- salestax.gemspec
 - spec/accountable_spec.rb
 - spec/features/sales_tax_spec.rb
 - spec/line_item_base_spec.rb