transactions 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d1fb2dde0117abbbd982a133959573444cb4b0fd
+  data.tar.gz: 27fbf80ef838f35511f3a9337ac7746c159b811f
+SHA512:
+  metadata.gz: dfc5cc11724b32935bfb1b63936404109f9d384a3936dd28ab899e32ac0e11d55e51ef58491dfe9312d83ba62fcf6eb921bbd2f4d7091655e83c4e2d8b80d33c
+  data.tar.gz: e7d1c09de955ccde03a27024783c3eb9e5bd3ea7e6e4a875712da422ad03cd9ef30724ae6aa934d8b2437318762e242d326b9aa39b832ebb55b809c03c3298dc

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+## version 0.1.0 (2013-06-27)
+---
+* Initial Release
+* Added additional unit tests
+* Authored README.md
+
+
+## version 0.0.0 (2013-06-26)
+---
+* Happy Birthday!
+

data/LICENSE.md

@@ -0,0 +1,21 @@
+Copyright (c) 2013 Randy Schneck
+
+The MIT License (MIT)
+
+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,245 @@
+# [transactions](http://computercrayons.com/transactions)
+
+## Description
+
+transactions is a command line application for managing your finances using a
+plain text format (yaml or json). All transactions are written to a text file
+by hand similar to a checkbook register. This text file is your ledger and it
+can handle most financial bookkeeping needs.
+
+
+## Installation
+
+### Requirements
+
+Before you can get started with *transaction*, the following must be installed
+on your system. Note that RubyGems is included with Ruby since version 1.9.
+
+* [Ruby](http://www.ruby-lang.org/en/downloads/)
+* [RubyGems](http://rubygems.org/pages/download)
+
+The best way to install transactions is via RubyGems. At the terminal prompt, run
+the following command:
+
+`gem install transactions`
+
+
+## Additional Information
+
+### Using the program
+
+1. create a ledger file
+    * you can copy and paste the example ledger below into a text file named
+      "ledger.yaml" if you just want to try out the program. If this is your
+      style of bookkeeping, then just edit the file with your own info using
+      your favorite text editor.
+    * run this command `transactions bal` and see the output.
+    * by default, "transactions" looks in the current directory for a file
+      named "ledger.yaml".
+    * you can use the -f option to specify a different file (eg. `transactions
+      -f example.yaml bal`)
+2. run `transactions reg`
+    * this is a register for all transactions
+    * notice that every transaction prints multiple times
+        * this happens because each transaction affects multiple accounts
+3. to make the register more useful try `transactions reg assets:checking`
+    * this will limit the register to assets:checking (case is ignored)
+    * this would be equivalent to printing a checkbook register from
+      "ledger.yaml"
+    * more than one account can be included eg. assets:checking expenses:food
+    * this limit by string of text also works with the balance command.
+4. see keeping a ledger below for information about general accounting
+   principles to help you with your own ledger.
+
+
+### Sample Ledger File
+
+    # This is a sample ledger file
+    # this line and the one above are comments that will be ignored
+    # during processing! Comments can also be placed at the end of
+    # a line (see below for examples).
+
+    - date:                             2013/01/01
+      transaction:                      Opening Balances
+      Assets:Checking:                  251.0
+      Assets:Savings:                   5005.3
+      Assets:IRA:                       22510.92
+      Liabilities:CreditCard:           -931.32
+      Liabilities:Salliemae:            -10189.05
+      Equity:OpeningBalances:           -16646.85
+
+    - date:                             2013/01/07
+      transaction:                      Trader Joe's
+      Expenses:Food:Groceries:          58.77
+      Assets:Checking:                  -58.77
+
+    - date:                             2013/01/09
+      transaction:                      Student Loan Payment
+      Liabilities:Salliemae:            103.3
+      Expenses:Interest:StudentLoan:    15.04
+      Assets:Checking:                  -118.34
+
+    - date:                             2013/02/11
+      transaction:                      Deposit Paycheck
+      Assets:Checking:                  1242.87
+      Income:JobName:                   -1242.87
+
+    - date:                             2013/02/11
+      transaction:                      Visa Payment
+      Expenses:Interest:CreditCard:     10.0
+      Liabilities:CreditCard:           130.0
+      Assets:Checking:                  -140.0
+
+    - date:                             2013/02/25
+      transaction:                      PG&E
+      Expenses:Utilities:Electric:      75
+      Assets:Checking:                  -75
+
+    - date:                             2013/02/25
+      transaction:                      Verizon  # Switch to Virgin Mobile
+      Expenses:Phone:                   55.72
+      Assets:Checking:                  -55.72
+
+    - date:                             2013/02/26
+      transaction:                      Ike's Lair  # good sandwich
+      Expenses:Food:Dining:             22.31
+      Assets:Checking:                  -22.31
+
+    # a transaction requires only one space as a separator but can also be
+    # aligned as above. The choice is yours!
+
+    - date: 2013/02/26
+      transaction: Money Transfer
+      Assets:Savings: 494.7
+      Assets:Checking: -494.7
+
+
+
+### Keeping a Ledger
+
+Although the program doesn't limit you on naming your accounts, it is highly
+recommended to use some standard conventions in order to facilitate easier
+understanding of your finances by your accountant. The five base accounts that
+you should use are:
+
++ Assets
+    * what you own
+    * a debit or withdrawal will be a negative number
+    * a deposit will be a positive number
++ Liabilities
+    * what you owe
+    * a payment towards a liability will be a positive number
+    * borrowing on a liability will be a negative number
++ Equity
+    * what you have accumulated over time
+    * Equity = Assets - Liabilities
++ Income
+    * your earnings from society
+    * this will always be a negative number (seems weird but you'll get used to
+      it)
+    * think of Income as a withdrawal from society and that is why it is
+      negative
++ Expenses
+    * things you spent your assets on or incurred liabilities for
+    * a purchase or expense will be a positive number
+    * a return or refund will be a negative number
+
+Everything falls under one of these five categories but also belongs in a
+sub-account. Sub-accounts are created by appending a colon and the name of the
+sub-account after one of the main accounts.  Some examples for account names
+could then be `Assets:Savings`, `Income:My Job`, `Expenses:Food:Groceries`,
+`Expenses:Food:Dining`, `Liabilities:Credit Card`.
+
+See the example ledger above for the complete syntax.
+
+
+### Start your own ledger
+
+1. Create an empty text file named "ledger.yaml"
+2. Enter your opening balances as the first transaction using the Equity
+   account (see example ledger above)
+    * The accounting equation that makes this work is `Equity = Assets -
+      Liabilities`
+    * Your Assets are positive numbers (unless your checking account is in the
+      negative == BAD!)
+    * Your Liabilities are negative since they bring down your net worth
+    * The difference of your Assets and Liabilities is balanced to zero with
+      the equity account.
+    * A negative equity in our ledger means a positive net worth (your assets
+      are greater than your liabilities).
+    * A positive equity in our ledger means a negative net worth (your
+      liabilities are greater than your assets).
+3. Enter transactions (be consistent with your account naming).
+4. The best way to be consistent is to run `transactions bal` to see all your
+   accounts before creating your new entry.
+5. Transaction names can be whatever you want to help remind you of the
+   transaction.
+6. The date is formatted as `YYYY/MM/DD` (this is important for the date
+   limiting options to function)
+
+
+### Some (hopefully) Helpful Notes
+
+* Assets, Liabilities, and Equity accounts are called "Real" accounts since
+  their balances are not zeroed out at the end of an accounting period.
+    * While this is unfortunate in the case of your Liabilities, it is
+      beneficial to your Assets.
+* Income and Expense accounts are called "Nominal" accounts since they begin at
+  zero at the start of a new accounting period.
+    * Income is used for expenses, to pay liabilities, or put into an asset
+      account as it comes in from society and thus starts at zero every
+      accounting period
+    * Expenses start over every accounting period (you can't claim already
+      claimed Expenses
+
+
+### Examples
+
+Trial Balance - list of all accounts in the ledger and their balances
+
+    transactions balance
+
+Balance Sheet - What you own and owe
+
+    transactions balance assets liabilities
+
+Income Statement - measures cash flow / profitability (income vs expenses)
+
+    transactions balance income expenses
+
+Limit by date
+
+    transactions -b 2013/01/01 -e 2013/12/31 balance
+
+* this will show the entire year of 2013 inclusive of the dates used as
+  arguments.
+* the date limits work for balance, register, and print commands.
+* the totals for income and expenses will be accurate with date limits since
+  they are nominal accounts that reset at the beginning of a new accounting
+  period.
+* the totals for assets and liabilities are the amounts that the accounts
+  changed during the accounting period. To see the totals that you actually
+  have in your assets or liabilities the date limits must be left out.
+
+
+## Contributing
+
+How to get your work merged into the project?
+
+* Fork the project.
+* Clone your fork ( git clone git@github.com:<username>/transactions.git ).
+* Create a topic branch for your change ( git checkout -b my_new_feature ).
+* Hack away, add tests. Not necessarily in that order.
+* Make sure everything still passes by running rake.
+* If necessary, rebase your commits into logical chunks, without errors.
+* Push the branch up ( git push origin my_new_feature ).
+* Create a pull request against randyschneck/transactions and describe what
+  your change does and the why you think it should be merged.
+
+
+## Credits
+
+Written by Randy A. Schneck (rasch@computercrayons.com)
+
+see [LICENSE.md](https://github.com/randyschneck/transactions/blob/master/LICENSE.md)
+

data/bin/transactions

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")  # For use/testing when not installed
+
+require 'transactions'
+
+t = Transaction::Parser.new
+
+if ARGV[0]
+  command = ARGV[0]
+  unless %w(balance bal register reg print).include? command
+    puts "That's not an option. Type 'transactions --help' for more info."
+  end
+  t.send(:parse, "balance") if %w(balance bal).include? command
+  t.send(:parse, "register") if %w(register reg).include? command
+  t.send(:parse, "print") if 'print' == command
+else
+  puts "At least one command is required. Type 'transactions --help' for more info."
+end
+

data/lib/transactions.rb

@@ -0,0 +1,12 @@
+$:.unshift File.dirname(__FILE__) # For use/testing when not installed
+
+# stdlib
+require 'yaml'
+require 'optparse'
+
+# internal requires
+require 'transactions/version'
+require 'transactions/options'
+require 'transactions/main'
+require 'transactions/parser'
+

data/lib/transactions/main.rb

@@ -0,0 +1,32 @@
+module Transaction
+
+  class Parser
+
+    def initialize
+      @options = Options.new.options
+      @default_ledger = 'ledger.yaml'
+      if @options[:file]
+        ledger = File.read @options[:file]
+      else
+        if File.exists? File.expand_path(@default_ledger)
+          ledger = File.read(File.expand_path(@default_ledger))
+        else
+          abort "There is no 'ledger.yaml' file in the current directory."
+        end
+      end
+      @ledger = YAML::load ledger if ledger != ""
+      @ledger = [] if ledger == ""
+      @date = Time.now.strftime "%Y/%m/%d"
+      if @options[:sort] == 'tran'  # sort by transaction
+        @ledger.sort_by! { |h| h['transaction'] }
+      elsif @options[:sort] == 'date'  # sort by date
+        @ledger.sort_by! { |h| h['date'] }
+      end
+    end
+
+    include Transaction
+
+  end
+
+end
+

data/lib/transactions/options.rb

@@ -0,0 +1,89 @@
+module Transaction
+
+  class Options
+
+    def initialize
+      @options = {}
+    end
+
+    def options
+      OptionParser.new do |opts|
+
+        opts.banner = "Usage: transactions [options] COMMAND [ARGS] ..."
+
+        opts.on("-f", "--file PATH", "PATH to yaml file to parse") do |x|
+          @options[:file] = x
+        end
+
+        opts.on("-c", "--current",
+                "don't include entries with future dates") do |x|
+          @options[:current] = x
+        end
+
+        opts.on("-b", "--begin DATE", "set begin date, DATE: YYYY/MM/DD") do |x|
+          @options[:begin] = x
+        end
+
+        opts.on("-e", "--end DATE", "set end date, DATE: YYYY/MM/DD") do |x|
+          @options[:end] = x
+        end
+
+        opts.on("-s", "--subtotal", "show sub-totals for balance") do |x|
+          @options[:subtotal] = x
+        end
+
+        opts.on("-E", "--empty", "show accounts with zero balance") do |x|
+          @options[:empty] = x
+        end
+
+        opts.on("-S", "--sort ARG", "sort by field, ARG can be date or tran") do |x|
+          @options[:sort] = x
+        end
+
+        opts.on("-w", "--wide", "print 132 columns wide for register") do |x|
+          @options[:wide] = x
+        end
+
+        #opts.on("-C", "--cleared", "only include cleared transactions") do |x|
+        #  @options[:cleared] = x
+        #end
+
+        #opts.on("-U", "--uncleared", "only include uncleared transactions") do |x|
+        #  @options[:uncleared] = x
+        #end
+
+        opts.on_tail("-h", "--help", "show this help message") do
+          puts opts
+          abort self.commands_help
+        end
+
+        opts.on_tail("-v", "--version", "show version") do
+          abort "#{Transaction::VERSION}"
+        end
+
+      end.parse!
+
+      @options
+
+    end
+
+
+    def commands_help
+      <<-COMMANDHELP
+
+      COMMANDS
+      --------
+      balance [ACCOUNT]..   Prints account balances, limited to ACCOUNTS.
+                            'bal' can be used as a shortcut.
+      register [ACCOUNT]..  Prints account register, limited to ACCOUNTS.
+                            'reg' can be used as a shortcut.
+      print                 Prints transactions formatted for export to ledger.
+                            Can be limited by date but not ACCOUNT.
+      COMMANDHELP
+    end
+
+
+  end
+
+end
+

data/lib/transactions/parser.rb

@@ -0,0 +1,162 @@
+module Transaction
+
+  def parse(cmd)
+
+    @accounts = {}
+    @running_total = 0
+
+    def transaction_print(x)
+      puts "#{x['date']} #{x['transaction']}"
+      x.each do |k, v |
+        puts sprintf("    %-30.30s % .2f", k, v) if v.is_a? Numeric
+      end
+      puts ""
+    end
+
+    def transaction_balance(k, v)
+      @accounts[k] += v if v.is_a? Numeric
+    end
+
+    def transaction_register(x, k, v, running_total)
+      if v.is_a? Numeric
+        if @options[:wide]  # for printing 132 columns wide
+          t = "%10s %-44s %-44s %15.2f %15.2f"
+          puts sprintf(t, x['date'], x['transaction'][0..42],
+                       k[0..42], v, running_total)
+        else  # for printing 78 columns wide (default)
+          t = "%10s %-20s %-24s %10.2f %10.2f"
+          puts sprintf(t, x['date'], x['transaction'][0..18],
+                       k[0..22], v, running_total)
+        end
+      end
+    end
+
+    def transaction_command(cmd, x, k, v)
+      ARGV.map! { |z| z.downcase }
+      if ARGV[1..-1].any? { |arg| k.downcase.include? arg }
+        @running_total += v if v.is_a? Numeric
+        if cmd == 'print'
+          transaction_print(x)
+        elsif cmd == 'balance'
+          transaction_balance(k, v)
+        elsif cmd == 'register'
+          transaction_register(x, k, v, @running_total)
+        end
+      elsif !ARGV[1]
+        @running_total += v if v.is_a? Numeric
+        if cmd == 'print'
+          transaction_print(x)
+        elsif cmd == 'balance'
+          transaction_balance(k, v)
+        elsif cmd == 'register'
+          transaction_register(x, k, v, @running_total)
+        end
+      end
+    end
+
+    @ledger.each do |x|
+      total = 0
+      x.each do |k, v|
+        total += v if v.is_a? Numeric
+        @accounts[k] ||= 0 if v.is_a? Numeric
+
+        if @options[:current]
+          if @options[:begin]
+            if x['date'] <= @date && x['date'] >= @options[:begin]
+              transaction_command(cmd, x, k, v); break if cmd == 'print'
+            end
+          else
+            if x['date'] <= @date
+              transaction_command(cmd, x, k, v); break if cmd == 'print'
+            end
+          end
+        elsif @options[:begin] || @options[:end]
+          if @options[:begin] && @options[:end]
+            if @options[:begin] <= x['date'] and x['date'] <= @options[:end]
+              transaction_command(cmd, x, k, v); break if cmd == 'print'
+            end
+          elsif @options[:begin]
+            if x['date'] >= @options[:begin]
+              transaction_command(cmd, x, k, v); break if cmd == 'print'
+            end
+          elsif @options[:end]
+            if x['date'] <= @options[:end]
+              transaction_command(cmd, x, k, v); break if cmd == 'print'
+            end
+          end
+        else
+          transaction_command(cmd, x, k, v); break if cmd == 'print'
+        end
+      end
+      if total.round(2) != 0
+        abort <<-EOF
+        You have an UNBALANCED Transaction
+        #{x}
+        Your total is off by #{sprintf("%.2f", -total)}
+        EOF
+      end
+    end
+
+
+    if cmd == 'balance'
+      accounts_total = 0
+      main_accounts = {}
+
+      if ARGV[1] && !@options[:subtotal]
+        ARGV[1..-1].each do |arg|
+          @accounts.sort.each do |k, v|
+            if k.downcase.include? arg
+              accounts_total += v
+              v = v.round(2)
+              if @options[:empty]
+                puts sprintf("%16.2f  %s", v, k)
+              else
+                puts sprintf("%16.2f  %s", v, k) if v != 0
+              end
+            end
+          end
+        end
+        puts "#{'-' * 16}"
+        puts sprintf("%16.2f", accounts_total)
+
+      elsif @options[:subtotal]
+        summary_total = 0
+        @accounts.each do |k, v|
+          x = k.split(':')
+          main_accounts[x[0].to_sym] ||= 0
+          main_accounts[x[0].to_sym] += v
+          main_accounts.each do |account, value|
+            main_accounts[account] = value.round(2)
+          end
+        end
+        main_accounts.sort.each do |k, v|
+          if ARGV[1]
+            ARGV.map! { |x| x.downcase }
+            ARGV[1..-1].each do |arg|
+              puts "#{sprintf("%16.2f  %s", v, k)}" if k.to_s.downcase.include? arg
+              summary_total += v if k.to_s.downcase.include? arg
+            end
+          else
+            puts "#{sprintf("%16.2f  %s", v, k)}"
+            summary_total += v
+          end
+        end
+        puts "#{"-" * 16}"
+        puts "#{sprintf("%16.2f", summary_total.round(2))}"
+
+      else
+        @accounts.sort.each do |k, v|
+          v = v.round(2)
+          if @options[:empty]
+            puts sprintf("%16.2f  %s", v, k)
+          else
+            puts sprintf("%16.2f  %s", v, k) if v != 0
+          end
+        end
+      end
+    end
+
+
+  end
+end
+

data/lib/transactions/version.rb

@@ -0,0 +1,4 @@
+module Transaction
+  VERSION = "0.1.0"
+end
+

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: transactions
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Randy Schneck
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-27 00:00:00.000000000 Z
+dependencies: []
+description: |2
+      A small but powerful command line application to help manage finances.
+      Transactions are entered into a text file using yaml and reports are
+      generated by parsing this data.
+email: rasch@computercrayons.com
+executables:
+- transactions
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/transactions
+- lib/transactions/main.rb
+- lib/transactions/options.rb
+- lib/transactions/parser.rb
+- lib/transactions/version.rb
+- lib/transactions.rb
+- LICENSE.md
+- README.md
+- CHANGELOG.md
+homepage: https://github.com/randyschneck/transactions
+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.2
+signing_key: 
+specification_version: 4
+summary: A bookkeeping application to help manage your finances.
+test_files: []