rock_books 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 42c5b49d705d543e5fbf5cf1f311e7b809a7511b898c83b372ee00b0922a8233
+  data.tar.gz: '0090982673c619217d19858dcad25bf05971e6c44de006fc778ed544a74b46e5'
+SHA512:
+  metadata.gz: 60037d15787e0b3559e38050a4e26538ef111de98dbd24ea04e59869d33468869c279e924e91347f8214c168d3a758a64823b2d58f1bc3af18ac60b2115dfa5b
+  data.tar.gz: e96e3afde04b586a3692c4bed2e6cb854aadea35fcbe1a6a5a09b7b80585c85cdc22fb70dc76aa8ca5c316f640e602426a74d3be50eb6dd16b9f3b73654f3706

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.idea/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.5.1
+before_install: gem install bundler -v 1.16.1

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in rock_books.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Keith Bennett
+
+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,200 @@
+# RockBooks
+
+A super primitive bookkeeping system using text files as input documents and console output
+for reporting.
+
+A supreme goal of this project is to give _you_ control over your data. 
+Want to serialize it to YAML, JSON, CSV, or manipulate it in your custom code?
+No problem! 
+
+It assumes the traditional double entry bookkeeping system, with debits and credits.
+In general, assets and expenses are debit balance accounts, and income, liabilities and equity
+are credit balance accounts.
+
+So, to really have this software make sense to you, you should probably understand
+the double entry bookkeeping paradigm pretty well. 
+
+# Terminology Usage
+
+* document - a RockBooks logical document such as a chart of accounts, a journal, etc.,
+usually containing information parsed from a data file
+
+* data file - a RockBooks data file, which is a text file, which
+ by convention has the extension `.rbt`
+
+
+## Data File Format
+
+Lines beginning with `#` will be ignored.
+
+Data lines that contain the value of document properties,
+as opposed to transactions, etc., will be expressed as lines beginning with `@`:
+
+```
+@doc_type: journal
+@title: "ABC Bank Checking Account Disbursements Journal"
+@account: ck_abc
+```
+
+Repeating data types such as entries in journals, and accounts in the chart of accounts,
+should in general be input after the properties.
+
+Data lines will contain fields that an be separated with an arbitrary number of spaces, e.g.:
+
+```
+2018-05-18  123.45 703
+```
+
+In journals, all entries will begin with dates, and all dates begin with numerals, so the
+presence of a numeral in the first column will be interpreted as the beginning of a new
+transaction (entry). Any lines following it not beginning with a `#` or number will be
+assumed to be the textual description of the transaction, and will be saved along with
+its other data.
+
+In order to make the entry of dates more convenient, many documents will support
+a `@date_prefix` property that will be prepended to dates. For example, if this prefix
+contains `2018-`, then subsequent dates must exclude that prefix since it will be
+automatically prepended. So, for example, a journal might contain the following lines:
+
+```
+@date_prefix: 2018-
+# ...more lines...
+05-29   37.50   ofc.spls
+05-30   22.20   tr.taxi
+```
+
+All date strings must use the format `YYYY-MM-DD`, because that's what will be expected
+by the application when it converts the date strings into numeric dates.
+
+
+
+### Chart of Accounts
+
+Pretty much everything in this application assumes the presence of a chart of accounts
+listing the accounts, including their codes, types, and names.
+
+You'll need to provide a chart of accounts file that includes the following line in the header:
+
+`@document_type: chart_of_accounts`
+
+This file should contain the accounts
+that will be used. Each account should contain the following fields:
+
+| Property Name | Description |
+| ------------- | ------------- |
+| code          | a short string with which to identify an account, e.g. `ret.earn` for retained earnings
+| type          | 'A' for asset, 'L' for liability, 'O' for (owners) equity, 'I' for income, and 'E' for expenses.
+| name          | a longer more descriptive name, used in reports, so no more than 30 or so characters long is recommended
+  
+
+So, the chart of accounts data might include something like this:
+
+```
+ck.xyz       A   XYZ Bank Checking Account
+loan.owner   L   Loan Payable to Owner
+o.equity     O   Owner's Equity
+sls.cons     I   Consulting Sales
+tr.airfare   E   Travel - Air Fare
+```
+
+Although hyphens and underscores are typically used to logically separate string fragments,
+we recommend periods; they're much easier to type, and you'll be doing a lot of that.
+
+There is no maximum length for account codes, and reports will automatically align based
+on the longest account code. However, keep in mind that you will need to type these codes,
+and they will consume space in reports.
+
+### Journals
+
+Journals (also referred to as _documents_ by this application)
+are used to record transactions of, for example:
+
+* cash disbursements (expenditures for a single checking account)
+* cash receipts (funds coming into a single checking account)
+* combined cash disbursements and receipts
+* a credit card account
+* a Paypal account
+* sales
+
+Each journal data file needs to contain:
+
+`@doc_type: journal`
+
+Also, it needs to identify the code of the account the journal is representing.
+So for example, if it is a journal of a PayPal account, and the PayPal 
+account's code is `paypal`, then you'll need a line like this in your journal file:
+
+`@account_code: paypal`
+
+For your convenience, when entering transactions in a journal (but _not_ a _general_ journal),
+you may enter all numbers going in the direction natural for that journal as positive numbers.
+
+For example, a _Cash Disbursements Journal_ (something like a
+check register) may contain a transaction like this:
+
+```
+05-29   37.50   ofc.spls
+```
+
+There may be many transactions in your journal, and it would be cumbersome to have to
+type minus signs in front of all of them if they were credits.
+
+Because of this, the program allows you to configure each journal as to the direction
+(debit or credit) of the transaction. This is done with the `@debit_or_credit` property.
+
+For an asset journal whose numbers will be crediting the main account
+(e.g. a cash disbursements journal whose entries will primarily be crediting
+the cash account), you would set the property to `debit`:
+
+```
+@debit_or_credit: debit
+```
+
+
+#### General Journal
+
+The general journal is a special form of journal that does not have a primary account.
+
+In this journal, debits and credits need to be specified literally as account code/amount
+pairs, where positive numbers will result in debits, and negative numbers will result in credits, e.g.:
+
+```
+03-10   tr.perdiem.mi   495.00   loan.to.sh  -495.00
+Per Diem allowance for conference trip
+```
+
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rock_books'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rock_books
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rock_books.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/RELEASE_NOTES.md

@@ -0,0 +1,4 @@
+## v0.1.0
+
+First release.
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rock_books"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/rock_books

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/rock_books/cmd_line/main'
+
+RockBooks::Main.new.call

data/lib/rock_books/cmd_line/command_line_interface.rb

@@ -0,0 +1,391 @@
+require 'fileutils'
+require 'forwardable'
+require 'ostruct'
+
+require_relative '../../rock_books'
+require_relative '../version'
+require_relative '../reports/reporter'
+require_relative '../helpers/book_set_loader'
+
+module RockBooks
+
+class CommandLineInterface
+
+  # Enable users to type methods of this class more conveniently:
+  include JournalEntryFilters
+  extend Forwardable
+
+  attr_reader :book_set, :interactive_mode, :run_options, :verbose_mode
+
+
+  class Command < Struct.new(:min_string, :max_string, :action); end
+
+
+  class BadCommandError < RuntimeError; end
+
+
+  # Enable use of some BookSet methods in shell with long and short names aaa, ae:
+
+  def_delegator :book_set, :all_acct_amounts
+  def_delegator :book_set, :all_acct_amounts, :aaa
+
+  def_delegator :book_set, :all_entries
+  def_delegator :book_set, :all_entries, :ae
+
+  def_delegator :book_set, :chart_of_accounts
+  def_delegator :book_set, :chart_of_accounts, :chart
+
+  # For conveniently finding the project on Github from the shell
+  PROJECT_URL = 'https://github.com/keithrbennett/rock_books'
+
+  # Help text to be used when requested by 'h' command, in case of unrecognized or nonexistent command, etc.
+  HELP_TEXT = "
+Command Line Switches:                    [rock-books version #{RockBooks::VERSION} at https://github.com/keithrbennett/rock_books]
+
+-i   input directory specification, default: '#{DEFAULT_INPUT_DIR}'
+-o   output (reports) directory specification, default: '#{DEFAULT_OUTPUT_DIR}'
+-r   receipts directory, default: '#{DEFAULT_RECEIPT_DIR}'
+-s   run in shell mode
+
+Commands:
+
+rec[eipts]                - receipts: a/:a all, m/:m missing, e/:e existing
+rep[orts]                 - return an OpenStruct containing all reports (interactive shell mode only)
+d[isplay_reports]         - display all reports on stdout
+w[rite_reports]           - write all reports to the output directory (see -o option)
+c[hart_of_accounts]       - chart of accounts
+h[elp]                    - prints this help
+jo[urnals]                - list of the journals' short names
+rel[oad_data]             - reload data from input files
+q[uit]                    - exits this program (interactive shell mode only) (see also 'x')
+x[it]                     - exits this program (interactive shell mode only) (see also 'q')
+
+When in interactive shell mode:
+* use quotes for string parameters such as method names.
+* for pry commands, use prefix `%`.
+* you can use the global variable $filter to filter reports
+
+"
+
+  def initialize(run_options)
+    @run_options = run_options
+    @interactive_mode = !!(run_options.interactive_mode)
+    @verbose_mode = run_options.verbose
+
+    validate_run_options(run_options)
+    # book_set is set with a lazy initializer
+  end
+
+
+  def validate_run_options(options)
+
+    validate_input_dir = -> do
+      File.directory?(options.input_dir) ? nil : "Input directory '#{options.input_dir}' does not exist. "
+    end
+
+    validate_output_dir = -> do
+      dir = options.output_dir
+      subdir = File.join(dir, SINGLE_ACCT_SUBDIR)
+
+      # We need to create the reports directory and its single-account subdirectory.
+      # We can accomplish both by creating just the subdirectory.
+      FileUtils.mkdir_p(subdir) ? nil : \
+          "Output directory '#{dir}' and/or #{subdir} does not exist and could not be created. "
+    end
+
+    validate_receipts_dir = -> do
+      File.directory?(options.receipt_dir) ? nil : \
+          "Receipts directory '#{options.receipt_dir}' does not exist. " +
+          "If you do not want receipt handling, use the --no-receipts command line option."
+    end
+
+    output = []
+    output << validate_input_dir.()
+    output << validate_output_dir.()
+    if run_options.do_receipts
+      output << validate_receipts_dir.()
+    end
+
+    unless output.empty?
+      message = output.compact.join("\n") << "\n"
+      raise Error.new(message)
+    end
+  end
+
+
+  def print_help
+    puts HELP_TEXT
+  end
+
+
+  def enclose_in_hyphen_lines(string)
+    hyphen_line = "#{'-' * 80}\n"
+    hyphen_line + string + "\n" + hyphen_line
+  end
+
+
+  # Pry will output the content of the method from which it was called.
+  # This small method exists solely to reduce the amount of pry's output
+  # that is not needed here.
+  def run_pry
+    binding.pry
+
+    # the seemingly useless line below is needed to avoid pry's exiting
+    # (see https://github.com/deivid-rodriguez/pry-byebug/issues/45)
+    _a = nil
+  end
+
+
+  # Runs a pry session in the context of this object.
+  # Commands and options specified on the command line can also be specified in the shell.
+  def run_shell
+    begin
+      require 'pry'
+    rescue LoadError
+      message = "The 'pry' gem and/or one of its prerequisites, required for running the shell, was not found." +
+          " Please `gem install pry` or, if necessary, `sudo gem install pry`."
+      raise Error.new(message)
+    end
+
+    print_help
+
+    # Enable the line below if you have any problems with pry configuration being loaded
+    # that is messing up this runtime use of pry:
+    # Pry.config.should_load_rc = false
+
+    # Strangely, this is the only thing I have found that successfully suppresses the
+    # code context output, which is not useful here. Anyway, this will differentiate
+    # a pry command from a DSL command, which _is_ useful here.
+    Pry.config.command_prefix = '%'
+
+    run_pry
+  end
+
+
+  # Look up the command name and, if found, run it. If not, execute the passed block.
+  def attempt_command_action(command, *args, &error_handler_block)
+    no_command_specified = command.nil?
+    command = 'help' if no_command_specified
+
+    action = find_command_action(command)
+    result = nil
+
+    if action
+      result = action.(*args)
+    else
+      error_handler_block.call
+      nil
+    end
+
+    if no_command_specified
+      puts enclose_in_hyphen_lines('! No operations specified !')
+    end
+    result
+  end
+
+
+  # For use by the shell when the user types the DSL commands
+  def method_missing(method_name, *method_args)
+    attempt_command_action(method_name.to_s, *method_args) do
+      puts(%Q{"#{method_name}" is not a valid command or option. } \
+        << 'If you intend for this to be a string literal, ' \
+        << 'use quotes or %q{}/%Q{}.')
+    end
+  end
+
+
+  # Processes the command (ARGV[0]) and any relevant options (ARGV[1..-1]).
+  #
+  # CAUTION! In interactive mode, any strings entered (e.g. a network name) MUST
+  # be in a form that the Ruby interpreter will recognize as a string,
+  # i.e. single or double quotes, %q, %Q, etc.
+  # Otherwise it will assume it's a method name and pass it to method_missing!
+  def process_command_line
+    attempt_command_action(ARGV[0], *ARGV[1..-1]) do
+      print_help
+      raise BadCommandError.new(
+          %Q{! Unrecognized command. Command was #{ARGV.first.inspect} and options were #{ARGV[1..-1].inspect}.})
+    end
+  end
+
+
+  def quit
+    if interactive_mode
+      exit(0)
+    else
+      puts "This command can only be run in shell mode."
+    end
+  end
+
+
+  def cmd_c
+    puts chart_of_accounts.report_string
+  end
+
+
+  def cmd_h
+    print_help
+  end
+
+
+  def cmd_j
+    journal_names = book_set.journals.map(&:short_name)
+    interactive_mode ? journal_names : ap(journal_names)
+  end
+
+
+  def book_set
+    @book_set ||= load_data
+  end
+
+
+  def load_data
+    @book_set = BookSetLoader.load(run_options)
+  end
+  alias_method :reload_data, :load_data
+
+
+  def cmd_rel
+    reload_data
+    nil
+  end
+
+
+  # All reports as Ruby objects; only makes sense in shell mode.
+  def cmd_rep
+    unless run_options.interactive_mode
+      raise Error.new("Option 'all_reports' is only available in shell mode. Try 'display_reports' or 'write_reports'.")
+    end
+
+    os = OpenStruct.new(book_set.all_reports($filter))
+    def os.keys; to_h.keys.map(&:to_s); end  # add hash methods for convenience
+    def os.values; to_h.values; end
+    def os.at(index); self.public_send(keys[index]); end # to access as array, e.g. `a.at(1)`
+    os
+  end
+
+
+  def cmd_d
+    book_set.all_reports($filter).each do |short_name, report_text|
+      puts "#{short_name}:\n\n"
+      puts report_text
+      puts "\n\n\n"
+    end
+    nil
+  end
+
+
+  def cmd_proj
+    `open https://github.com/keithrbennett/rock_books`
+  end
+
+
+  def cmd_rec(options)
+    unless run_options.do_receipts
+      raise Error.new("Receipt processing was requested but has been disabled with --no-receipts.")
+    end
+
+    missing, existing = book_set.missing_and_existing_receipts
+
+    print_missing  = -> { puts "Missing Receipts:"; ap missing }
+    print_existing = -> { puts "Existing Receipts:"; ap existing }
+
+    case options.first.to_s
+      when 'a'  # all
+        if run_options.interactive_mode
+          { missing: missing, existing: existing }
+        else
+           print_missing.(); print_existing.()
+        end
+
+      when 'm'
+        run_options.interactive_mode ? missing : print_missing.()
+
+      when 'e'
+        run_options.interactive_mode ? existing : print_existing.()
+
+    else
+      message = "Invalid option for receipts. Must be 'a' for all, 'm' for missing, or 'e' for existing."
+      if run_options.interactive_mode
+        puts message
+      else
+        raise Error.new(message)
+      end
+    end
+  end
+
+  def cmd_w
+    book_set.all_reports_to_files(run_options.output_dir, $filter)
+    nil
+  end
+
+
+  def cmd_x
+    quit
+  end
+
+
+  def commands
+    @commands_ ||= [
+        Command.new('rec', 'receipts',          -> (*options)  { cmd_rec(options)  }),
+        Command.new('rep', 'reports',           -> (*_options) { cmd_rep           }),
+        Command.new('d',   'display_reports',   -> (*_options) { cmd_d             }),
+        Command.new('w',   'write_reports',     -> (*_options) { cmd_w             }),
+        Command.new('c',   'chart_of_accounts', -> (*_options) { cmd_c             }),
+        Command.new('jo',  'journals',          -> (*_options) { cmd_j             }),
+        Command.new('h',   'help',              -> (*_options) { cmd_h             }),
+        Command.new('proj','project_page',      -> (*_options) { cmd_proj          }),
+        Command.new('q',   'quit',              -> (*_options) { cmd_x             }),
+        Command.new('rel', 'reload_data',       -> (*_options) { cmd_rel           }),
+        Command.new('x',   'xit',               -> (*_options) { cmd_x             })
+    ]
+  end
+
+
+  def find_command_action(command_string)
+    result = commands.detect do |cmd|
+      cmd.max_string.start_with?(command_string) \
+    && \
+    command_string.length >= cmd.min_string.length  # e.g. 'c' by itself should not work
+    end
+    result ? result.action : nil
+  end
+
+
+  # If a post-processor has been configured (e.g. YAML or JSON), use it.
+  def post_process(object)
+    post_processor ? post_processor.(object) : object
+  end
+
+
+  def post_processor
+    run_options.post_processor
+  end
+
+
+  # Convenience Method(s)
+
+  # Easier than remembering and typing Date.iso8601.
+  def td(date_string)
+    Date.iso8601(date_string)
+  end
+
+
+  def call
+    begin
+      # By this time, the Main class has removed the command line options, and all that is left
+      # in ARGV is the commands and their options.
+      if @interactive_mode
+        run_shell
+      else
+        process_command_line
+      end
+
+    rescue BadCommandError => error
+      separator_line = "! #{'-' * 75} !\n"
+      puts '' << separator_line << error.to_s << "\n" << separator_line
+      exit(-1)
+    end
+  end
+end
+end