rock_books 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb5e28caf47f966b9793cef3f45eafde78895029034d25256864c1035f16e3a5
-  data.tar.gz: 3c5c3d288454789332a4395c57ee362d933e5d141294a22951ef38401556606a
+  metadata.gz: 748869c04031f76ba911a05c45f954290f0d364c5cb4cd08c725238398542075
+  data.tar.gz: a926e2ec2498a2312b5e765ac8511f8f62ffbbcafc016c03752b4c1934cf4eb8
 SHA512:
-  metadata.gz: f8e890585583e9331567371567cd483ea9ac4d8a11999bfaf443094fd896e04343ef2cbbdddf26a1a823cf98301254d9c1a66338a53abab8fd3a4c322066919d
-  data.tar.gz: 39d6ed81e515fc38db7f8b116388cb8e0cf5025e8f2d9adcc307cb0fb03e4bdc6dc40b0477d6adab6857753c7418dcf9c32967dc1fac63d541ae4a92157b602f
+  metadata.gz: 40f17cf379eddd8a675c2aa427f4faf32471e6d95252a5f77a12727f0949efc5e46947cc9e11a08e0d7d00d4cbb1a42f6219d0b4a880c0fcdba53eccf736d47c
+  data.tar.gz: 47eaf0e7d59c26efe53718a965cd09bfd00ba72385e634a3928d096a6909be67354a474e1cb927aa4b57fe1f7f77a0f82794682b755c30f073c7dc7d8f1b4f66

data/.gitattributes

@@ -0,0 +1 @@
+sample_data/minimal/rockbooks-reports/*  linguist-vendored

data/README.md

@@ -19,8 +19,7 @@ the double entry bookkeeping paradigm pretty well.
 * 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 - a RockBooks data file, which is a text file with the extension `.txt`
 
 
 ## Data File Format
@@ -181,19 +180,10 @@ 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.
+Bug reports and pull requests are welcome on GitHub at [https://github.com/keithrbennett/rock_books](https://github.com/keithrbennett/rock_books).
+
 
 ## License
 

data/RELEASE_NOTES.md

@@ -1,6 +1,20 @@
+## v0.1.3
+
+* Report output now goes to separate txt, html, and pdf subdirectories.
+* Add vendor.yml to exclude generated report files from language reporting.
+* Use .gitattributes instead of vendor.yml to specify vendored code.
+* Add == methods to ChartOfAccounts and Journal classes.
+* Rename input files from .rbt to .txt.
+* Convert sample input files to DOS line endings.
+* Add validation that transaction is balanced.
+* Fix so that requesting help shows correct help text, and that passing no args on cmd line triggers help.
+* Implement more helpful error messages, with document short name, line number, and line text.
+* Add JournalEntryContext and TransactionNotBalancedError classes.
+* Add 'from_string' methods to Journal and ChartOfAccounts.
+
 ## v0.1.2
 
-Improve error emssage when the needed directories do not exist. 
+* Improve error message when the needed directories do not exist. 
 
 ## v0.1.1
 

data/lib/rock_books/cmd_line/command_line_interface.rb

@@ -24,7 +24,7 @@ class CommandLineInterface
   class BadCommandError < RuntimeError; end
 
 
-  # Enable use of some BookSet methods in shell with long and short names aaa, ae:
+  # Enable use of some BookSet methods in shell with long and short aliases:
 
   def_delegator :book_set, :all_acct_amounts
   def_delegator :book_set, :all_acct_amounts, :aaa
@@ -56,6 +56,7 @@ w[rite_reports]           - write all reports to the output directory (see -o op
 c[hart_of_accounts]       - chart of accounts
 h[elp]                    - prints this help
 jo[urnals]                - list of the journals' short names
+proj[ect_page]            - open the RockBooks Github project page in a browser
 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')
@@ -79,18 +80,22 @@ When in interactive shell mode:
 
   def validate_run_options(options)
 
+    return if options.suppress_command_line_validation
+
     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. "
+      # We need to create the reports directory if it does not already exist.
+      # mkdir_p silently returns if the directory already exists.
+      begin
+        FileUtils.mkdir_p(options.output_dir)
+        nil
+      rescue Errno::EACCES => error
+        "Output directory '#{options.output_dir}' does not exist and could not be created. "
+      end
     end
 
     validate_receipts_dir = -> do
@@ -273,9 +278,14 @@ When in interactive shell mode:
     end
 
     os = OpenStruct.new(book_set.all_reports($filter))
-    def os.keys; to_h.keys.map(&:to_s); end  # add hash methods for convenience
+
+    # add hash methods for convenience
+    def os.keys; to_h.keys.map(&:to_s); end
     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)`
+
+    # to access as array, e.g. `a.at(1)`
+    def os.at(index); self.public_send(keys[index]); end
+
     os
   end
 

data/lib/rock_books/cmd_line/main.rb

@@ -39,6 +39,11 @@ class Main
 
     OptionParser.new do |parser|
 
+      parser.on("-h", "--help", "Show help") do |_help_requested|
+        ARGV << 'h' # pass on the request to the command processor
+        options.suppress_command_line_validation = true
+      end
+
       parser.on('-i', '--input_dir DIR',
           "Input directory containing source data files, default: '#{DEFAULT_INPUT_DIR}'") do |v|
         options.input_dir = File.expand_path(v)
@@ -80,10 +85,9 @@ class Main
   end
 
 
-  # Arg is a directory containing 'chart_of_accounts.rbd' and '*journal*.rbd' for input,
-  # and reports (*.rpt) will be output to this directory as well.
   def call
     begin
+      ARGV << '-h' if ARGV.empty?
       run_options = parse_command_line
       CommandLineInterface.new(run_options).call
     rescue => error
@@ -91,7 +95,10 @@ class Main
       <<~HEREDOC
       #{error.backtrace.join("\n")}
 
+      #{'-' * 79}
       #{error}
+      #{'-' * 79}
+
       HEREDOC
 
       if run_options.say

data/lib/rock_books/documents/book_set.rb

@@ -63,13 +63,28 @@ module RockBooks
 
     def all_reports_to_files(directory = '.', filter = nil)
       reports = all_reports(filter)
+
+      # "./pdf/short_name.pdf" or "./pdf/single_account/short_name.pdf"
+      build_filespec = ->(short_name, file_format) do
+        fragments = [directory, file_format, "#{short_name}.#{file_format}"]
+        is_acct_report =  /^acct_/.match(short_name)
+        if is_acct_report
+          fragments.insert(2, SINGLE_ACCT_SUBDIR)
+        end
+        File.join(*fragments)
+      end
+
       reports.each do |short_name, report_text|
-        report_directory = /^acct_/.match(short_name) ? File.join(directory, SINGLE_ACCT_SUBDIR) : directory
-        txt_filespec  = File.join(report_directory, "#{short_name}.txt")
-        html_filespec = File.join(report_directory, "#{short_name}.html")
-        pdf_filespec  = File.join(report_directory, "#{short_name}.pdf")
+        txt_filespec  = build_filespec.(short_name, 'txt')
+        html_filespec = build_filespec.(short_name, 'html')
+        pdf_filespec  = build_filespec.(short_name, 'pdf')
+
+        FileUtils.mkdir_p(File.dirname(txt_filespec))
+        FileUtils.mkdir_p(File.dirname(html_filespec))
+        FileUtils.mkdir_p(File.dirname(pdf_filespec))
+
         File.write(txt_filespec, report_text)
-        run_command("textutil -convert html -font 'Menlo Regular' #{txt_filespec} -output #{html_filespec}")
+        run_command("textutil -convert html -font 'Menlo Regular' -fontsize 10 #{txt_filespec} -output #{html_filespec}")
         run_command("cupsfilter #{html_filespec} > #{pdf_filespec}")
         puts "Created reports in txt, html, and pdf for #{"%-20s" % short_name} at #{File.dirname(txt_filespec)}.\n\n\n"
       end

data/lib/rock_books/documents/chart_of_accounts.rb

@@ -9,14 +9,18 @@ class ChartOfAccounts
 
 
   def self.from_file(file)
-    self.new(File.read(file))
+    self.new(File.readlines(file).map(&:chomp))
   end
 
 
-  def initialize(input_string)
+  def self.from_string(string)
+    self.new(string.split("\n"))
+  end
+
+
+  def initialize(input_lines)
     @accounts = []
-    lines = input_string.split("\n")
-    lines.each { |line| parse_line(line) }
+    input_lines.each { |line| parse_line(line) }
   end
 
 
@@ -49,10 +53,12 @@ class ChartOfAccounts
     end
   end
 
+
   def accounts_of_type(type)
     accounts.select { |account| account.type == type }
   end
 
+
   def account_codes_of_type(type)
     accounts_of_type(type).map(&:code)
   end
@@ -88,6 +94,7 @@ class ChartOfAccounts
     found ? found.type : nil
   end
 
+
   def name_for_code(code)
     found = account_for_code(code)
     found ? found.name : nil
@@ -109,5 +116,13 @@ class ChartOfAccounts
       raise "Unexpected type #{type} for code #{code}."
     end
   end
+
+
+  def ==(other)
+    doc_type == other.doc_type   && \
+    title    == other.title      && \
+    accounts == other.accounts   && \
+    entity   == other.entity
+  end
 end
 end

data/lib/rock_books/documents/journal.rb

@@ -4,6 +4,7 @@ require 'yaml'
 
 require_relative '../errors/account_not_found_error'
 require_relative '../types/acct_amount'
+require_relative '../types/journal_entry_context'
 require_relative 'journal_entry'
 require_relative 'journal_entry_builder'
 require_relative '../reports/reporter'
@@ -18,7 +19,12 @@ module RockBooks
 class Journal
 
   def self.from_file(chart_of_accounts, file)
-    self.new(chart_of_accounts, File.read(file))
+    self.new(chart_of_accounts, File.readlines(file).map(&:chomp))
+  end
+
+
+  def self.from_string(chart_of_accounts, string)
+    self.new(chart_of_accounts, string.split("\n"))
   end
 
 
@@ -61,18 +67,21 @@ class Journal
   attr_reader :short_name, :account_code, :chart_of_accounts, :date_prefix, :debit_or_credit, :doc_type, :title, :entries
 
   # short_name is a name that will appear on reports identifying the journal from which a transaction comes
-  def initialize(chart_of_accounts, input_string, short_name = nil)
+  def initialize(chart_of_accounts, input_lines, short_name = nil)
     @chart_of_accounts = chart_of_accounts
     @short_name = short_name
     @entries = []
     @date_prefix = ''
     @title = ''
-    lines = input_string.split("\n")
-    lines.each { |line| parse_line(line) }
+    input_lines.each_with_index do |line, linenum|
+      context = JournalEntryContext.new(self, linenum + 1, line)
+      parse_line(context)
+    end
   end
 
 
-  def parse_line(line)
+  def parse_line(journal_entry_context)
+    line = journal_entry_context.line
     case line.strip
     when /^@doc_type:/
       @doc_type = line.split(/^@doc_type:/).last.strip
@@ -80,7 +89,7 @@ class Journal
       @account_code = line.split(/^@account_code:/).last.strip
 
       unless chart_of_accounts.include?(@account_code)
-        raise AccountNotFoundError.new(@account_code)
+        raise AccountNotFoundError.new(@account_code, journal_entry_context)
       end
 
       # if debit or credit has not yet been specified, inherit the setting from the account:
@@ -102,7 +111,7 @@ class Journal
     when /^#/
       # ignore comment line
     when /^\d/  # a date/acct/amount line starting with a number
-      entries << JournalEntryBuilder.new(line, self).build
+      entries << JournalEntryBuilder.new(journal_entry_context).build
     else # Text line(s) to be attached to the most recently parsed transaction
       unless entries.last
         raise Error.new("Entry for this description cannot be found: #{line}")
@@ -157,5 +166,18 @@ class Journal
 
   def to_json; to_h.to_json; end
   def to_yaml; to_h.to_yaml; end
+
+
+  def ==(other)
+    # excluding date_prefix from this test intentionally because it does not
+    # affect the parsed data.
+    short_name        == other.short_name          && \
+    account_code      == other.account_code        && \
+    chart_of_accounts == other.chart_of_accounts   && \
+    debit_or_credit   == other.debit_or_credit     && \
+    doc_type          == other.doc_type            && \
+    title             == other.title               && \
+    entries           == other.entries
+  end
 end
 end

data/lib/rock_books/documents/journal_entry_builder.rb

@@ -1,23 +1,24 @@
+require_relative '../errors/incorrect_sequence_error'
+require_relative '../errors/transaction_not_balanced_error'
 require_relative '../types/acct_amount'
+require_relative '../types/journal_entry_context'
 require_relative 'chart_of_accounts'
 require_relative 'journal'
 
 module RockBooks
-class JournalEntryBuilder < Struct.new(:line, :journal)
+class JournalEntryBuilder < Struct.new(:journal_entry_context)
 
-  def acct_amounts_from_tokens(tokens, date, chart_of_accounts)
+  def journal;           journal_entry_context.journal;            end
+  def linenum;           journal_entry_context.linenum;            end
+  def line;              journal_entry_context.line;               end
+  def chart_of_accounts; journal_entry_context.chart_of_accounts;  end
+
+
+  def acct_amounts_from_tokens(tokens, date)
     acct_amounts = []
 
     tokens[0..-1].each_slice(2).each do |(account_code, amount)|
-      begin
-        acct_amount = AcctAmount.create_with_chart_validation(date, account_code, amount, chart_of_accounts)
-      rescue AccountNotFoundError => error
-        error.document_name = journal.short_name
-        error.line = line
-        raise
-      end
-
-      acct_amounts << acct_amount
+      acct_amounts <<  AcctAmount.create_with_chart_validation(date, account_code, amount, journal_entry_context)
     end
 
     acct_amounts
@@ -26,7 +27,7 @@ class JournalEntryBuilder < Struct.new(:line, :journal)
 
   def validate_acct_amount_token_array_size(tokens)
     if tokens.size.odd?
-      raise Error.new("Incorrect sequence of account codes and amounts: #{tokens}")
+      raise IncorrectSequenceError.new(tokens, journal_entry_context)
     end
   end
 
@@ -118,7 +119,15 @@ class JournalEntryBuilder < Struct.new(:line, :journal)
       convert_signs_for_debit_credit(tokens)
     end
 
-    acct_amounts_from_tokens(tokens, date, journal.chart_of_accounts)
+    acct_amounts_from_tokens(tokens, date)
+  end
+
+
+  def validate_transaction_is_balanced(acct_amounts)
+    sum = acct_amounts.map(&:amount).sum.round(4)
+    unless sum == 0.0
+      raise TransactionNotBalancedError.new(sum, journal_entry_context)
+    end
   end
 
 
@@ -141,8 +150,8 @@ class JournalEntryBuilder < Struct.new(:line, :journal)
     end
 
     acct_amounts = build_acct_amount_array(date, acct_amount_tokens)
+    validate_transaction_is_balanced(acct_amounts)
     JournalEntry.new(date, acct_amounts, journal.short_name)
   end
-
 end
 end

data/lib/rock_books/errors/account_not_found_error.rb

@@ -1,20 +1,21 @@
+require_relative '../types/journal_entry_context'
+
+
 module RockBooks
 class AccountNotFoundError < RuntimeError
 
-  attr_accessor :bad_account_code, :document_name, :line
+  attr_accessor :code, :journal_entry_context
 
-  def initialize(bad_account_code, document_name = nil, line = nil)
-    self.bad_account_code = bad_account_code
+  def initialize(code, journal_entry_context)
+    self.code = code
+    self.journal_entry_context = journal_entry_context
     super(to_s)
   end
 
 
   def to_s
-    s = "Account code not found in chart of accounts: #{bad_account_code}"
-    if document_name && line
-      s << ", document: #{document_name}, line: #{line}"
-    end
-    s
+    ctx = journal_entry_context
+    "Account code '#{code}' in journal '#{ctx.journal.short_name}', line ##{ctx.linenum} not found in chart of accounts. Line: '#{ctx.line}'"
   end
 end
 end

data/lib/rock_books/errors/incorrect_sequence_error.rb

@@ -0,0 +1,21 @@
+require_relative '../types/journal_entry_context'
+
+
+module RockBooks
+  class IncorrectSequenceError < RuntimeError
+
+    attr_accessor :tokens, :journal_entry_context
+
+    def initialize(tokens, journal_entry_context)
+      self.tokens = tokens
+      self.journal_entry_context = journal_entry_context
+      super(to_s)
+    end
+
+
+    def to_s
+      ctx = journal_entry_context
+      "Incorrect token sequence in journal '#{ctx.journal.short_name}', line ##{ctx.linenum}: #{tokens.inspect}"
+    end
+  end
+end

data/lib/rock_books/errors/transaction_not_balanced_error.rb

@@ -0,0 +1,21 @@
+require_relative '../errors/transaction_not_balanced_error'
+
+module RockBooks
+
+class TransactionNotBalancedError < RuntimeError
+
+    attr_reader :discrepancy, :journal_entry_context
+
+    def initialize(discrepancy, journal_entry_context)
+      @discrepancy = discrepancy
+      @journal_entry_context = journal_entry_context
+      super(to_s)
+    end
+
+    def to_s
+      amount_string = "%0.2f" % discrepancy
+      "Transaction not balanced; discrepancy is #{amount_string}. Context: #{journal_entry_context}"
+    end
+end
+
+end

data/lib/rock_books/filters/journal_entry_filters.rb

@@ -6,6 +6,11 @@ module JournalEntryFilters
   module_function
 
 
+  def filter(entries, entry_filter)
+    entries.select { |entry| entry_filter.(entry) }
+  end
+
+
   # Dates can be provided as a Ruby Date object, or as a string that will be converted to date (yyyy-mm-dd).
   def to_date(string_or_date_object)
     if string_or_date_object.is_a?(String)
@@ -40,7 +45,7 @@ module JournalEntryFilters
   end
 
 
-  def account_code_filter(account_code)
+  def account_code(account_code)
     ->(entry) do
       entry.acct_amounts.map(&:code).detect { |code| code == account_code }
     end

data/lib/rock_books/helpers/book_set_loader.rb

@@ -8,7 +8,7 @@ module RockBooks
     module_function
 
     def get_files_with_types(directory)
-      files = Dir[File.join(directory, '*.rbt')]
+      files = Dir[File.join(directory, '*.txt')]
       files.each_with_object({}) do |filespec, files_with_types|
         files_with_types[filespec] = ParseHelper.find_document_type_in_file(filespec)
       end
@@ -40,7 +40,7 @@ module RockBooks
     end
 
 
-    # Uses all *.rbt files in the specified directory; uses @doc_type to determine which
+    # Uses all *.txt files in the specified directory; uses @doc_type to determine which
     # is the chart of accounts and which are journals.
     # To exclude a file, make the extension other than .rdt.
     def load(run_options)

data/lib/rock_books/helpers/parse_helper.rb

@@ -16,7 +16,7 @@ module RockBooks
 
 
     def find_document_type_in_file(filespec)
-      find_document_type(File.readlines(filespec))
+      find_document_type(File.readlines(filespec).map(&:chomp))
     end
   end
 end

data/lib/rock_books/reports/tx_by_account.rb

@@ -31,7 +31,7 @@ class TxByAccount
 
   def account_header(account, account_total)
     total_string = "%.2f" % account_total
-    title =  "Total: #{total_string} -- #{account_code_name_type_string(account)})"
+    title =  "Total: #{total_string} -- #{account_code_name_type_string(account)}"
 
     <<~HEREDOC
     #{banner_line}

data/lib/rock_books/reports/tx_one_account.rb

@@ -41,7 +41,7 @@ module RockBooks
 
 
     def generate_report
-      entries = Journal.entries_in_documents(context.journals, JournalEntryFilters.account_code_filter(account_code))
+      entries = Journal.entries_in_documents(context.journals, JournalEntryFilters.account_code(account_code))
       account_total = JournalEntry.total_for_code(entries, account_code)
       output = generate_header(account_total)
 

data/lib/rock_books/types/acct_amount.rb

@@ -2,13 +2,13 @@ module RockBooks
 
 # This class represents an account code and an amount.
 # Journal entries will have multiple instances of these.
-class AcctAmount < Struct.new(:date, :code, :amount)
+class AcctAmount < Struct.new(:date, :code, :amount, :journal_entry_context)
 
 
   # Same as constructor except it raises an error if the account code is not in the chart of accounts.
-  def self.create_with_chart_validation(date, code, amount, chart_of_accounts)
-    unless chart_of_accounts.include?(code)
-      raise AccountNotFoundError.new(code)
+  def self.create_with_chart_validation(date, code, amount, journal_entry_context)
+    unless journal_entry_context.chart_of_accounts.include?(code)
+      raise AccountNotFoundError.new(code, journal_entry_context)
     end
     self.new(date, code, amount)
   end

data/lib/rock_books/types/journal_entry_context.rb

@@ -0,0 +1,14 @@
+module RockBooks
+
+class JournalEntryContext < Struct.new(:journal, :linenum, :line)
+
+  def chart_of_accounts
+    journal.chart_of_accounts
+  end
+
+  def to_s
+    "Journal '#{journal.short_name}', line ##{linenum}, text: #{line}"
+  end
+end
+
+end

data/lib/rock_books/version.rb

@@ -1,3 +1,3 @@
 module RockBooks
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end