bouch 1.1.0

data/README.md

@@ -0,0 +1,142 @@
+# Bouch
+[![pipeline status](https://gitlab.com/ssofos/bouch/badges/master/pipeline.svg)](https://gitlab.com/ssofos/bouch/commits/master) [![coverage report](https://gitlab.com/ssofos/bouch/badges/master/coverage.svg)](https://gitlab.com/ssofos/bouch/commits/master)
+
+`Bouch` is the budget pouch. A simple tool to calculate and project your annual personal budget based on fiscal quarter expenditures, income, assets, and debts.
+
+Use it to help establish an annual financial plan, set monetary goals, and gain perspective on your financial health.
+
+## Install
+
+To install bouch via RubyGems simple execute this command from a command-line interface:
+
+```
+gem install bouch
+```
+
+To use bouch as part of your Ruby Project add this line to your Gemfile:
+
+```
+gem 'bouch'
+```
+
+## Usage
+
+Bouch takes a simple YAML file as its primary data input. This will be referred to as a budget pouch file.
+
+There is an example budget pouch file called **pouch.example.yml**.
+
+Use this budget pouch file and execute the following command on your favorite terminal emulator's CLI:
+
+```
+bouch pouch.example.yml
+```
+
+You should see the example budget summary output:
+
+```
+----------------------
+Quarter 1:                     3025.00
+Quarter 2:                     3025.00
+Quarter 3:                     3025.00
+Quarter 4:                     3025.00
+----------------------
+Budget Annual Total:           12100.00
+Budget Annual Income:          28808.00
+Budget Income Percent:         42.00%
+----------------------
+Assets Total:                  1000.00
+----------------------
+Debt Total:                    420.00
+Debt Ratio:                    0.4200
+Debt Ratio Percent:            42.00%
+----------------------
+```
+
+### Pouch Schema
+
+To use bouch to calculate your own budget you must create a customized budget pouch file.
+
+Budget pouch files are written in Ruby friendly YAML and currently use the following schema:
+
+* Deeply nested mappings, also know as hashes
+* Think of hashes as simple groupings of keys and values
+* Primary hash keys:
+  * **Budget**
+  * **Salary**
+  * **Assets**
+  * **Debts**
+* **Budget** nested keys and values:
+    * **Q1**
+        * foo
+            * Value: Integer or Float
+            * Equals a budget item's quarterly cost
+        * bar
+            * **cost**
+                * Value: Integer or Float
+                * Equals the monthly cost of any repeated payment
+            * **repeat**
+                * Value: true
+                * Enables quarterly auto-calculation of the repeat payment
+  * **Q2**
+      * Same nested schema as Q1
+  * **Q3**
+      * Same nested schema as Q1
+  * **Q4**
+      * Same nested schema as Q1
+* **Salary** nested keys and values:
+  * **quantity**
+      * Value: Float or Integer
+      * Equals amount of after-tax money per salary pay period
+  * **frequency**
+      * Value: Integer
+      * Equals number of weeks for each salary pay period
+* **Assets** nested keys and values:
+  * foo
+      * Value: Integer or Float
+      * Equals an asset's total valued amount
+* **Debts** nested keys and values:
+  * bar
+      * Value: Integer or Float
+      * Equals a debt's total valued amount
+* All non-primary nested keys are case insensitive
+
+Here is an simple example of of budget pouch file:
+
+```
+---
+Budget:
+  Q1:
+    Rent:
+      cost: 1000
+      repeat: true
+    foo: 20
+    bar: 5
+  Q2:
+    Rent:
+      cost: 1000
+      repeat: true
+    fizz: 20
+    buzz: 5
+  Q3:
+    Rent:
+      cost: 1000
+      repeat: true
+    bubble: 20
+    sort: 5
+  Q4:
+    Rent:
+      cost: 1000
+      repeat: true
+    baz: 20
+    qax: 5
+Salary:
+  quantity: 1108.00
+  frequency: 2
+Assets:
+  foo: 500
+  bar: 500
+Debts:
+  baz: 120
+  qax: 300
+...
+```

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/bouch

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+require 'bouch/cli'
+
+Bouch::CLI.new(ARGV[0].freeze).start

data/bouch.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('lib', __dir__)
+require 'bouch/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'bouch'
+  s.date        = '2018-06-09'
+  s.version     = Bouch::VERSION
+  s.authors     = ['Shane R. Sofos']
+  s.email       = ['ssofos@gmail.com']
+  s.homepage    = 'https://gitlab.com/ssofos/bouch'
+  s.license     = 'GPL-3.0'
+  s.description = 'The Budget Pouch. Fast annual budget projections.'
+  s.summary     =
+    'A simple tool to calculate and project your ' +
+    'annual personal budget based on fiscal quarters ' +
+    'expenditures, income, assets, and debts.'
+
+  s.files         = %x(git ls-files).split($INPUT_RECORD_SEPARATOR)
+  s.bindir        = ['bin']
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths = ['lib']
+
+  s.add_development_dependency 'bundler'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'rubocop', '<=0.56.0'
+  s.add_development_dependency 'simplecov'
+
+  s.required_ruby_version = '>= 2.4.0'
+end

data/lib/bouch.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'bouch/calc'
+
+# Calculate and create simple financial budgets
+# by parsing a single YAML file as input
+class Bouch
+  attr_accessor :assets, :debts, :pouch, :quarters
+  include BouchCalculate
+
+  def initialize(file)
+    @assets = Array.new
+    @debts = Array.new
+    @pouch = YAML.safe_load(IO.read(file))
+    @quarters = Hash.new
+  end
+
+  # Summarize and show aggregate asset totals
+  def show_assets_total
+    calc_assets(@pouch['Assets']) if @assets.empty?
+    puts '----------------------'
+    puts format('%-30s %.2f', 'Assets Total:', @assets.sum)
+  end
+
+  # Summarize and show aggregate liabilities totals
+  def show_debts_total
+    calc_debts(@pouch['Debts']) if @debts.empty?
+    puts '----------------------'
+    puts format('%-30s %.2f', 'Debt Total:', @debts.sum)
+  end
+
+  # Summarize and show debt ratio
+  def show_debt_ratio
+    calc_assets(@pouch['Assets']) if @assets.empty?
+    calc_debts(@pouch['Debts']) if @debts.empty?
+    puts format('%-30s %.4f', 'Debt Ratio:', calc_debt_ratio(@debts.sum, @assets.sum))
+    puts format('%-30s %.2f%s', 'Debt Ratio Percent:',
+                calc_debt_ratio_percent(calc_debt_ratio(@debts.sum, @assets.sum)),
+                '%')
+    puts '----------------------'
+  end
+
+  # Summarize and show all financial quarter budgets
+  def show_quarters
+    calc_quarters_raw(@pouch['Budget']) if @quarters.empty?
+    puts '----------------------'
+    4.times do |n|
+      puts format('%-30s %.2f', 'Quarter ' + (n + 1).to_s + ':', @quarters[n.to_s].sum)
+    end
+    puts '----------------------'
+  end
+
+  # Summarize and show the aggregate annual budget totals
+  def show_annual_total
+    calc_quarters_raw(@pouch['Budget']) if @quarters.empty?
+    puts format('%-30s %.2f', 'Budget Annual Total:', calc_quarters_raw_total.to_s)
+  end
+
+  # Summarize and show the aggregate annual budget as a percentage of income
+  def show_budget_percentage
+    calc_quarters_raw(@pouch['Budget']) if @quarters.empty?
+    puts format('%-30s %.2f%s',
+                'Budget Income Percent:',
+                calc_budget_percentage(
+                  calc_quarters_raw_total,
+                  calc_salary(@pouch['Salary']['quantity'], @pouch['Salary']['frequency'])
+                ),
+                '%')
+  end
+
+  # Summarize and show annual income
+  def show_annual_income
+    puts format('%-30s %.2f',
+                'Budget Annual Income:',
+                calc_salary(@pouch['Salary']['quantity'], @pouch['Salary']['frequency']))
+  end
+
+  # Summarize and show all aggregate components of the quarterly, annual budgets, assets
+  def show_budget
+    show_quarters
+    show_annual_total
+    show_annual_income
+    show_budget_percentage
+    show_assets_total
+    show_debts_total
+    show_debt_ratio
+  end
+end

data/lib/bouch/calc.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Financial budget calculation and operations for Bouch
+module BouchCalculate
+  # Calculate asset value aggregate amount
+  def calc_assets(assets)
+    assets.each_value do |value|
+      @assets.push(value)
+    end
+  end
+
+  # Calculate the percentage of budget of a salary/income
+  def calc_budget_percentage(total, salary)
+    ((total.to_f / salary.to_f) * 100).round(2)
+  end
+
+  # Calculate debt/liability aggregate amount
+  def calc_debts(debts)
+    debts.each_value do |value|
+      @debts.push(value)
+    end
+  end
+
+  # Calculate a debt ratio: total debts divided by total assets
+  def calc_debt_ratio(debts, assets)
+    (debts.to_f / assets.to_f).round(4)
+  end
+
+  # Calculate a debt ratio percentage
+  def calc_debt_ratio_percent(debt_ratio)
+    (debt_ratio.to_f * 100).round(2)
+  end
+
+  # Calculate a quarterly repeating budget item amount
+  def calc_repeating(item)
+    (item.to_f * 3).round(2)
+  end
+
+  # Calculate an annual income based on a weekly frequency salary
+  def calc_salary(amount, freq)
+    (amount.to_f * (52 / freq)).round(2)
+  end
+
+  # Calculate each financial quarters budget items, including repeating ones
+  def calc_quarters_raw(budget)
+    budget.each_value do |items|
+      @quarters[@quarters.length.to_s] = Array.new
+      items.each_value do |value|
+        case value
+        when Hash
+          if value.key?('repeat')
+            @quarters[(@quarters.length - 1).to_s].push(calc_repeating(value['cost']))
+          end
+        else
+          @quarters[(@quarters.length - 1).to_s].push(value)
+        end
+      end
+    end
+  end
+
+  # Calculate all financial quarter budget into an aggregate annual budget
+  def calc_quarters_raw_total
+    @quarters['0'].sum + @quarters['1'].sum + @quarters['2'].sum + @quarters['3'].sum
+  end
+end

data/lib/bouch/cli.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'bouch'
+require 'bouch/version'
+
+class Bouch
+  # Parse the command line
+  class CLI
+    attr_accessor :yaml_file
+
+    def initialize(file)
+      @yaml_file = file
+    end
+
+    def start
+      if @yaml_file.eql?(nil)
+        puts 'Please supply budget pouch YAML file path and rerun bouch.'
+        usage
+      elsif File.exist?(@yaml_file)
+        budget = Bouch.new(@yaml_file)
+        budget.show_budget
+      else
+        puts "Whoops. The budget pouch file specified: #{@yaml_file} ; does not exist!"
+        usage
+      end
+    end
+
+    def usage
+      puts "<<bouch #{Bouch::VERSION}>>\nUsage: #{File.basename($PROGRAM_NAME)} [YAML_FILE]"
+    end
+  end
+end

data/lib/bouch/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Bouch
+  VERSION = '1.1.0'
+end

data/pouch.example.yml

@@ -0,0 +1,36 @@
+---
+Budget:
+  Q1:
+    Rent:
+      cost: 1000
+      repeat: true
+    foo: 20
+    bar: 5
+  Q2:
+    Rent:
+      cost: 1000
+      repeat: true
+    fizz: 20
+    buzz: 5
+  Q3:
+    Rent:
+      cost: 1000
+      repeat: true
+    bubble: 20
+    sort: 5
+  Q4:
+    Rent:
+      cost: 1000
+      repeat: true
+    baz: 20
+    qax: 5
+Salary:
+  quantity: 1108.00
+  frequency: 2
+Assets:
+  foo: 500
+  bar: 500
+Debts:
+  baz: 120
+  qax: 300
+...

data/spec/bouch_calc_spec.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'bouch'
+require 'bouch/calc'
+
+describe BouchCalculate do
+  before :all do
+    @yaml = File.realdirpath('pouch.example.yml')
+    @bouch = Bouch.new(@yaml)
+  end
+
+  describe '.calc_assets' do
+    it 'pushes asset values to an Array and returns a Hash' do
+      expect(@bouch.calc_assets(@bouch.pouch['Assets'])).to be_a_kind_of(Hash)
+    end
+    it 'creates array of assets greater than zero' do
+      # Uncomment line below for Debug
+      # puts @bouch.assets.inspect
+      expect(@bouch.assets.length).to be > 0
+    end
+  end
+
+  describe '.calc_budget_percentage' do
+    context 'given a budget total and salary income total' do
+      it 'returns a percentage of budget of a salary income' do
+        expect(@bouch.calc_budget_percentage(12100.00, 28808.00)).to eq(42.00)
+      end
+    end
+  end
+
+  describe '.calc_debts' do
+    it 'pushes debt values to an Array and returns a Hash' do
+      expect(@bouch.calc_debts(@bouch.pouch['Debts'])).to be_a_kind_of(Hash)
+    end
+    it 'creates an array of debts greater than zero' do
+      # Uncomment line below for Debug
+      # puts @bouch.debts.inspect
+      expect(@bouch.debts.length).to be > 0
+    end
+  end
+
+  describe '.calc_debt_ratio' do
+    context 'given a sum of debts and assets' do
+      it 'returns a Float number' do
+        expect(@bouch.calc_debt_ratio(420.00, 1000.00)).to be_a_kind_of(Float)
+      end
+      it 'returns a debt ratio' do
+        expect(@bouch.calc_debt_ratio(420.00, 1000.00)).to eq(0.42)
+      end
+    end
+  end
+
+  describe '.calc_debt_ratio_percent' do
+    context 'given a debt ratio' do
+      it 'returns a Float number' do
+        debt_ratio = @bouch.calc_debt_ratio(420.00, 1000.00)
+        # Uncomment line below for Debug
+        # puts debt_ratio
+        expect(@bouch.calc_debt_ratio_percent(debt_ratio)).to be_a_kind_of(Float)
+      end
+      it 'returns a debt ratio percentage' do
+        debt_ratio = @bouch.calc_debt_ratio(420.00, 1000.00)
+        # Uncomment line below for Debug
+        # puts debt_ratio
+        expect(@bouch.calc_debt_ratio_percent(debt_ratio)).to eq(42.00)
+      end
+    end
+  end
+
+  describe '.calc_repeating' do
+    context 'given a numerical cost amount' do
+      it 'returns a Float number' do
+        expect(@bouch.calc_repeating(1000)).to be_a_kind_of(Float)
+      end
+      it 'returns a number three times that amount' do
+        expect(@bouch.calc_repeating(1000)).to eq(3000.00)
+      end
+    end
+  end
+
+  describe '.calc_salary' do
+    context 'given a salary amount and weekly frequency' do
+      it 'returns a Float number' do
+        expect(@bouch.calc_salary(1108.00, 2)).to be_a_kind_of(Float)
+      end
+      it 'returns an annual income total' do
+        expect(@bouch.calc_salary(1108.00, 2)).to eq(28808.00)
+      end
+    end
+  end
+
+  describe '.calc_quarters_raw' do
+    context 'given a quarterly budget' do
+      it 'pushes quarterly budget items to a collection of Arrays and returns a Hash' do
+        expect(@bouch.calc_quarters_raw(@bouch.pouch['Budget'])).to be_a_kind_of(Hash)
+      end
+      it 'creates an array of financial quarter one budget items greater than zero' do
+        # Uncomment line below for Debug
+        # puts @bouch.quarters['0'].inspect
+        expect(@bouch.quarters['0'].length).to be > 0
+      end
+      it 'creates an array of financial quarter two budget items greater than zero' do
+        # Uncomment line below for Debug
+        # puts @bouch.quarters['1'].inspect
+        expect(@bouch.quarters['1'].length).to be > 0
+      end
+      it 'creates an array of financial quarter three budget items greater than zero' do
+        # Uncomment line below for Debug
+        # puts @bouch.quarters['2'].inspect
+        expect(@bouch.quarters['2'].length).to be > 0
+      end
+      it 'creates an array of financial quarter four budget items greater than zero' do
+        # Uncomment line below for Debug
+        # puts @bouch.quarters['3'].inspect
+        expect(@bouch.quarters['3'].length).to be > 0
+      end
+    end
+  end
+
+  describe '.calc_quarters_raw_total' do
+    context 'given arrays of quarterly budget items' do
+      it 'returns a Float number' do
+        expect(@bouch.calc_quarters_raw_total).to be_a_kind_of(Float)
+      end
+
+      it 'returns a financial quarter aggregate sum' do
+        expect(@bouch.calc_quarters_raw_total).to eq(12100.00)
+      end
+    end
+  end
+end