cashflow 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 576c6d93c4d566d3524dd76bf75aff69239aaa3f
+  data.tar.gz: ffc085bdaf1a9d72824f2bc87528311723dc5449
+SHA512:
+  metadata.gz: 84adc6c6a09b7f9825e46443013e1658ea66f174e2147277445e6dcb80a62236ba790dccba2dc709e7725c641f9ebcf52b50bc56290ea2c81629c1c76a0d6b7b
+  data.tar.gz: cd3096ba3cab1d2bb8ddfe1be8f21c5e5f44ab51ba926c63e09e04a12feab8cfb4a95c7855bd33794ea5326e4768ac81b8ff2267270f1b3015ad0a5e6799f3c3

data/.gitignore

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

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 2.0.0@cashflow --create

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in cashflow.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Mike Fulcher
+
+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,31 @@
+Cashflow
+--------
+
+**Compare your latest income & expenses to your average.**
+
+Cashflow is a simple command-line application written in Ruby using [Thor](https://github.com/wycats/thor). It's purpose is simple: to analyse your bank transactions (collecting only the _date_ and _amount_) in order to build an average if your income and expenses over the last few months and compare these with the income and expenses for the current month.
+
+Only transactions up to the current day of the month are included, so the app gives you good insight into your financial position at this exact point in the month - extremely useful when you have regular monthly transactions such as rent and salary.
+
+By default, only transactions from 4 months prior are factored into the calculations (or as far back as the stored transactions go), but this is configurable.
+
+Usage
+-----
+
+Basic useage is simple: you load a set of transactions (in OFX format), then print a report.
+
+![Useage screenshot](https://raw.github.com/6twenty/cashflow/master/screenshot.png)
+
+Commands
+--------
+
+```
+cashflow help            # Show this help message
+cashflow help [COMMAND]  # Describe available commands or one specific command
+cashflow load PATH       # Loads the OFX file at the specified PATH
+cashflow report          # Analyses the stored transactions and prints a comparison report
+cashflow flush           # Flushes the database, removing all stored transactions
+cashflow version         # Prints the current version number
+```
+
+**`cashflow report`** takes a single optional parameter. You can specify the date range for the transactions to compare against by passing "-s" or "--span" followed by a number repensenting the number of months to use.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/cashflow

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+# Add load path and require the module.
+lib = File.expand_path('../../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cashflow'
+
+# Quick check for shortcuts to the "help"
+# and "version" commands.
+if %w(-v --version).include?(ARGV[0])
+  Cashflow::Cli.new.version
+elsif %w(-h --help).include?(ARGV[0])
+  Cashflow::Cli.new.help
+else
+  Cashflow::Cli.start
+end

data/cashflow.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cashflow/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "cashflow"
+  spec.version       = Cashflow::VERSION
+  spec.authors       = ["Mike Fulcher"]
+  spec.email         = ["mike@drawingablank.me"]
+  spec.description   = %q{Compares your latest income & expense to your average, giving you a quick at-a-glance view of your financial position.}
+  spec.summary       = %q{Compares your latest income & expense to your average.}
+  spec.homepage      = "http://github.com/6twenty/cashflow"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+
+  spec.add_dependency "iconv"
+  spec.add_dependency "sqlite3"
+  spec.add_dependency "thor"
+  spec.add_dependency "ofx"
+end

data/lib/cashflow/cli.rb

@@ -0,0 +1,93 @@
+module Cashflow
+  class Cli < ::Thor
+    include Thor::Actions
+
+    desc "version", "Prints the current version number"
+    def version
+      say("Cashflow v#{Cashflow::VERSION}", :green)
+    end
+
+    desc "load PATH", "Loads the OFX file at the specified PATH"
+    def load(ofx_file_path)
+      map_transactions(OFX(ofx_file_path).account.transactions).each(&:save)
+      say("Successfully loaded the transactions from '#{ofx_file_path}'", :green)
+    end
+
+    # Option to factor only up to the day of the month.
+    desc "report", "Analyses the stored transactions and prints a comparison report"
+    option :span, :type => :numeric, :aliases => "-s", :default => 4
+    def report
+      # Build report.
+      report = Report.new(options)
+      report.build_report
+
+      # Define columns widths.
+      cols = "%-11s %-11s %-11s %-11s\n"
+
+      # Intro.
+      say("\n")
+      say("Using transactions up to and including the #{Date.today.day.ordinalize} of the month")
+      say("Transactions begin #{report.start.strftime('%B')} #{report.start.day.ordinalize}, #{report.start.strftime('%Y')}")
+      say("\n")
+
+      # Table header.
+      printf(cols, "", "Average", "This month", "Difference")
+      
+      # Print the debits & credits comparison.
+      Transaction::TYPES.each do |type|
+        # Calculate comparison.
+        avg = report.send("#{type}_average")
+        current = report.send("#{type}_current_sum")
+        diff = report.send("#{type}_diff")
+        in_or_out = type == :debits ? 'out' : 'in'
+        is_good = diff <= 0
+        colour = is_good ? :green : :red
+
+        # Table row.
+        printf(cols, "Money #{in_or_out}:", currencify(avg), currencify(current), set_color(currencify(diff), colour))
+      end
+
+      # Calculate net position.
+      net_position = report.debits_diff + report.credits_diff
+      is_good = net_position <= 0
+      colour = is_good ? :green : :red
+      position = is_good ? 'improvement' : 'decline'
+
+      # Print the net position.
+      say("\n")
+      say("Comparison: #{set_color(currencify(net_position) + ' ' + position + ' on average', colour)}")
+      say("\n")
+    end
+
+    desc "flush", "Flushes the database, removing all stored transactions"
+    def flush
+      Cashflow.flush
+      say("Successfully flushed database", :green)
+    end
+
+    private
+
+    def currencify(number)
+      is_neg = number < 0
+      number = number / 100.0
+      int, frac = ("%.2f" % number).split('.')
+      int.gsub!(/(\d)(?=(\d\d\d)+(?!\d))/, "\\1,")
+      int = int.slice(1..-1) if is_neg
+      "$" + int + "." + frac
+    end
+
+    # Takes a collection of OFX transactions and maps them to
+    # Transaction instances, which are saved to the database.
+    def map_transactions(transactions)
+      transactions.map do |record|
+        Transaction.new({
+          :id     => record.fit_id.to_s,
+          :type   => record.type,
+          :amount => record.amount_in_pennies,
+          :date   => record.posted_at.to_date
+        })
+      end
+    end
+
+  end
+end

data/lib/cashflow/patches.rb

@@ -0,0 +1,21 @@
+class String
+  def to_date
+    year, month, day = self.split("-").map(&:to_i)
+    Date.strptime("{ #{year}, #{month}, #{day} }", "{ %Y, %m, %d }")
+  end
+end
+
+class Fixnum
+  def ordinalize
+    if (11..13).include?(self % 100)
+      "#{self}th"
+    else
+      case self % 10
+        when 1; "#{self}st"
+        when 2; "#{self}nd"
+        when 3; "#{self}rd"
+        else    "#{self}th"
+      end
+    end
+  end
+end

data/lib/cashflow/report.rb

@@ -0,0 +1,112 @@
+module Cashflow
+  class Report
+    TYPES = Cashflow::Transaction::TYPES
+    attr_accessor *TYPES
+    attr_accessor *TYPES.map { |type| :"#{type}_sums" }
+    attr_accessor *TYPES.map { |type| :"#{type}_current" }
+    attr_accessor *TYPES.map { |type| :"#{type}_current_sum" }
+    attr_accessor *TYPES.map { |type| :"#{type}_average" }
+    attr_accessor *TYPES.map { |type| :"#{type}_diff" }
+    attr_accessor :start
+
+    def initialize(options)
+      date = Date.today << options[:span]
+      @start = Date.new(date.year, date.month, 1)
+    end
+
+    def debits
+      @debits ||= Transaction.merged(Transaction.debits(start))
+    end
+
+    def credits
+      @credits ||= Transaction.merged(Transaction.credits(start))
+    end
+
+    def build_report
+      filter_up_to_day_of_the_month!
+      separate_current_month!
+      group_priors_by_month!
+      sum_all_by_month!
+      calculate_averages!
+      calculate_differences!
+    end
+
+    private
+
+    # Filters the credits and debits to only include the transactions
+    # that occurred up to the current day of the month.
+    def filter_up_to_day_of_the_month!
+      TYPES.each do |type|
+        filtered = send(type).select do |transaction|
+          transaction.date.day <= Date.today.day
+        end
+        send("#{type}=", filtered)
+      end
+    end
+
+    # Divide the credits & debits into those for the current month
+    # and all others prior.
+    def separate_current_month!
+      TYPES.each do |type|
+        this_month = send(type).select do |transaction|
+          transaction.date.year == Date.today.year &&
+          transaction.date.month == Date.today.month
+        end
+        send("#{type}_current=", this_month)
+        send("#{type}=", send(type) - this_month)
+      end
+    end
+
+    # Group all prior transactions into months (as a hash).
+    def group_priors_by_month!
+      TYPES.each do |type|
+        by_month = send(type).inject({}) do |hash, transaction|
+          key = "#{transaction.date.year}-#{transaction.date.month}"
+          hash[key] ||= []
+          hash[key] << transaction
+          hash
+        end
+        send("#{type}=", by_month)
+      end
+    end
+
+    # Sum all transactions by month.
+    def sum_all_by_month!
+      TYPES.each do |type|
+        # Current month:
+        current_sum = send("#{type}_current").inject(0) do |sum, transaction|
+          sum += transaction.amount
+          sum
+        end
+        send("#{type}_current_sum=", current_sum)
+
+        # Prior months:
+        prior_sums = {}
+        send("#{type}").each do |key, transactions|
+          prior_sums[key] = transactions.inject(0) do |sum, transaction|
+            sum += transaction.amount
+            sum
+          end
+        end
+        send("#{type}_sums=", prior_sums)
+      end
+    end
+
+    # Calculate the average debits & credits based on the prior transactions.
+    def calculate_averages!
+      TYPES.each do |type|
+        average = send("#{type}_sums").values.inject(0, :+) / send("#{type}_sums").values.length
+        send("#{type}_average=", average)
+      end
+    end
+
+    # Calculate the difference between the current month totals and the prior averages.
+    def calculate_differences!
+      TYPES.each do |type|
+        diff = send("#{type}_average") - send("#{type}_current_sum")
+        send("#{type}_diff=", diff)
+      end
+    end
+
+  end
+end

data/lib/cashflow/transaction.rb

@@ -0,0 +1,60 @@
+module Cashflow
+  class Transaction
+    attr_accessor :id, :type, :amount, :date
+
+    TYPES = %i(debits credits)
+
+    class << self
+
+      def select_from_sql(sql)
+        Cashflow.db.execute(sql).map do |(id, type, amount, date)|
+          Transaction.new({
+            :id     => id,
+            :type   => type.to_sym,
+            :amount => amount,
+            :date   => date.to_date
+          })
+        end
+      end
+
+      def all(since)
+        select_from_sql("SELECT * FROM #{Cashflow.table_name} WHERE date >= '#{since.to_s}' ORDER BY date ASC")
+      end
+
+      def debits(since)
+        select_from_sql("SELECT * FROM #{Cashflow.table_name} WHERE date >= '#{since.to_s}' AND type = 'debit' ORDER BY date ASC")
+      end
+
+      def credits(since)
+        select_from_sql("SELECT * FROM #{Cashflow.table_name} WHERE date >= '#{since.to_s}' AND type = 'credit' ORDER BY date ASC")
+      end
+
+      def merged(transactions)
+        by_date = {}
+        transactions.each do |transaction|
+          key = "#{transaction.date.to_s}-#{transaction.type.to_s}"
+          # If a transaction already exists for this date and type, combine them.
+          transaction.amount += by_date[key].amount if by_date[key]
+          by_date[key] = transaction
+        end
+        # Return the combined transactions, sorted by date.
+        by_date.values.sort_by { |transaction| transaction.date }
+      end
+    end
+
+    def initialize(attrs)
+      attrs.each do |(attribute, value)|
+        send("#{attribute}=", value)
+      end
+    end
+
+    def save
+      begin
+        Cashflow.db.execute("INSERT INTO activity (id, type, amount, date) VALUES (?, ?, ?, ?)", [ id, type.to_s, amount, date.to_s ])
+        true
+      rescue Exception => e
+        false
+      end
+    end
+  end
+end

data/lib/cashflow/version.rb

@@ -0,0 +1,3 @@
+module Cashflow
+  VERSION = "0.0.1"
+end

data/lib/cashflow.rb

@@ -0,0 +1,49 @@
+# Ruby libs.
+require 'kconv' # For OFX gem fix.
+require 'logger'
+require 'sqlite3'
+require 'thor'
+require 'ofx'
+
+# App modules.
+require 'cashflow/version'
+require 'cashflow/patches'
+require 'cashflow/transaction'
+require 'cashflow/report'
+require 'cashflow/cli'
+
+module Cashflow
+
+  # Define the database table name.
+  def self.table_name
+    "activity"
+  end
+
+  # Define the root directory.
+  def self.root
+    @root ||= File.expand_path(File.join(__FILE__, '../../'))
+  end
+
+  # Set up & retrieve the logger.
+  def self.logger
+    @logger ||= Logger.new(File.join(root, 'log/cashflow.log'))
+  end
+
+  # Initialize & retrieve the database.
+  def self.db
+    @db ||= begin
+      # Initialize the database. Create the table if necessary.
+      db = SQLite3::Database.new(File.join(root, 'db/cashflow.db'))
+      db.execute("CREATE TABLE IF NOT EXISTS #{table_name} (id string primary key, type varchar(6), amount integer, date date);")
+      # Return the database connection.
+      db
+    end
+  end
+
+  # Erase the database.
+  def self.flush
+    db.execute("DROP TABLE IF EXISTS #{table_name};")
+    @db = nil
+  end
+
+end

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification
+name: cashflow
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Mike Fulcher
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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: iconv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ofx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Compares your latest income & expense to your average, giving you a quick
+  at-a-glance view of your financial position.
+email:
+- mike@drawingablank.me
+executables:
+- cashflow
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rvmrc
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/cashflow
+- cashflow.gemspec
+- db/cashflow.db
+- lib/cashflow.rb
+- lib/cashflow/cli.rb
+- lib/cashflow/patches.rb
+- lib/cashflow/report.rb
+- lib/cashflow/transaction.rb
+- lib/cashflow/version.rb
+- log/cashflow.log
+- screenshot.png
+homepage: http://github.com/6twenty/cashflow
+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.0.0
+signing_key: 
+specification_version: 4
+summary: Compares your latest income & expense to your average.
+test_files: []