RubyGems - rock_books - Versions diffs - 0.1.6 → 0.2.0 - Mend

rock_books 0.1.6 → 0.2.0

Files changed (142) hide show

data/lib/rock_books/documents/index.html.erb ADDED Viewed

@@ -0,0 +1,156 @@
+<!DOCTYPE html>
+<html>
+<head>
+<!--Bootstrap:-->
+<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.2.1/css/bootstrap.min.css" integrity="sha384-GJzZqFGwb1QTTN6wy59ffF1BuGJpLSa9DkKMp0DgiMDm4iYMj70gZWKYbI706tWS" crossorigin="anonymous">
+<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
+<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.2.1/js/bootstrap.min.js" integrity="sha384-B0UglyR+jN6CkvvICOB2joaf5I4l3gm9GU6Hc1og6Ls7i6U/mkkaduKaBhlAXv9k" crossorigin="anonymous"></script>
+  <style>
+    body {
+      padding: 18px;
+      background-color: #e7f7cd;
+      color: darkgreen;
+    }
+    h2 {
+      margin-top: 32px;
+      margin-bottom: 12px;
+    }
+    .this_page_style {
+      background-color: #e7f7cd;
+      color: darkgreen;
+      border: 0px;
+    }
+  </style>
+</head>
+<body>
+<h1><%= chart_of_accounts.entity %></h1>
+<p class="muted">Reports Generated at <%= DateTime.now.strftime('%Y-%m-%d %H:%M:%S') %> by RockBooks version <%=RockBooks::VERSION %></p>
+<h2>Financial Statements</h2>
+<div id="financial-statements">
+<a href='balance_sheet.html' class="btn btn-success">Balance Sheet</a>
+<a href='income_statement.html' class="btn btn-success">Income Statement</a>
+</div>
+<h2>Supporting Documents</h2>
+<div id="supporting-documents" style="display: inline ">
+  <%
+    subdir_link = ->(name, caption) do
+      dir_name = File.expand_path(File.join(Dir.pwd, name))
+      if Dir.exist?(dir_name)
+        %Q{<a href=#{dir_name} class="btn btn-success">#{caption}</a>}
+      end
+    end
+  %>
+  <%= subdir_link.('invoices',   'Invoices')   %>
+  <%= subdir_link.('receipts',   'Receipts')   %>
+  <%= subdir_link.('statements', 'Statements') %>
+  <%= subdir_link.('worksheets', 'Worksheets') %>
+</div>
+<h2>All Transactions Reports</h2>
+<div id="all-transactions">
+<a href="all_txns_by_acct.html" class="btn btn-success">By Account</a>
+<a href="all_txns_by_amount.html" class="btn btn-success">By Amount</a>
+<a href="all_txns_by_date.html" class="btn btn-success">By Date</a>
+</div>
+<% collapsible_heading = ->(caption, href) do
+  %Q{<br /><br />
+  <div class="collapsible-heading">
+    <div class="container-fluid">
+      <div class="row">
+        <div class="col-sm2" style="margin-right: 12px;">
+          <a class="btn btn-success" data-toggle="collapse" href="#{href}" role="button" aria-expanded="false" aria-controls="collapseExample">
+            +/-
+          </a>
+        </div>
+        <div class="col-sm10">
+          <h2 style="margin: 0px;">#{caption}</h2>
+        </div>
+      </div>
+    </div>
+  </div>
+  }
+  end
+%>
+<%= collapsible_heading.('Journal Reports', '#journal-reports') %>
+</div>
+<div class="collapse" id="journal-reports">
+  <div class="card card-body this_page_style">
+    <ul>
+      <% journals.each do |journal|
+        filespec = journal.short_name + '.html'
+        caption = "#{journal.title} -- #{journal.short_name} -- #{journal.account_code}"%>
+        <li><a href="<%= filespec %>" class="this_page_style" target="_blank"><%= caption %></a></li>
+      <% end %>
+    </ul>
+  </div>
+</div>
+<%= collapsible_heading.('Individual Accounts', '#individual-accounts') %>
+<div class="collapse" id="individual-accounts">
+  <div class="card card-body  this_page_style">
+    <ul>
+    <%
+        chart_of_accounts.accounts.each do |account|
+          filespec = File.join('single-account', "acct_#{account.code}.html")
+          caption = "#{account.name} (#{account.code})"
+    %>
+      <li><a href="<%= filespec %>" class="this_page_style"><%= caption %></a></li>
+    <% end %>
+    </ul>
+</div>
+</div>
+</div>
+<%= collapsible_heading.('Other', '#other') %>
+<div class="collapse" id="other">
+  <div class="card card-body this_page_style">
+    <ul>
+      <% if run_options.do_receipts  %>
+        <li><a href="receipts.html" class="this_page_style">Missing and Existing Receipts</a></li>
+      <% end %>
+    </ul>
+  </div>
+</div>
+<%= collapsible_heading.('Reports in PDF and Text Formats', '#other-formats') %>
+<div class="collapse" id="other-formats">
+  <div class="card card-body this_page_style">
+    <ul>
+        <li><a href="../pdf" class="this_page_style" target="_blank">PDF Format</a></li>
+        <li><a href="../txt" class="this_page_style" target="_blank">Text Format</a></li>
+    </ul>
+  </div>
+</div>
+</body>
+</html>

data/lib/rock_books/documents/journal_entry_builder.rb CHANGED Viewed

@@ -136,17 +136,23 @@ class JournalEntryBuilder < Struct.new(:journal_entry_context)
     tokens = line.split
     acct_amount_tokens = tokens[1..-1]
     date_string = journal.date_prefix + tokens[0]
-    raise_error = -> do
-      raise Error.new("In journal '#{journal.short_name}', date string was '#{date_string}'" +
-          " but should be a valid date in the form YYYY-MM-DD.")
+    raise_date_format_error = -> do
+      raise Error.new("Date string was '#{date_string}' but should be a valid date in the form YYYY-MM-DD in " + \
+          "journal '#{journal_entry_context[:journal].title}', line #{journal_entry_context[:linenum]}.")
     end
-    raise_error.() if date_string.length != 10
+    raise_date_format_error.() if date_string.length != 10
     begin
       date = Date.iso8601(date_string)
     rescue ArgumentError
-      raise_error.()
+      raise_date_format_error.()
+    end
+    unless chart_of_accounts.included_in_period?(date)
+      raise DateRangeError.new(date, chart_of_accounts.start_date,
+          chart_of_accounts.end_date, journal_entry_context)
     end
     acct_amounts = build_acct_amount_array(date, acct_amount_tokens)

data/lib/rock_books/documents/receipts.html.erb ADDED Viewed

@@ -0,0 +1,54 @@
+<!DOCTYPE html>
+<html>
+<body>
+<h1><%= chart_of_accounts.entity %> -- Receipts</h1>
+<p>Reports Generated at <%= DateTime.now.strftime('%Y-%m-%d_%H-%M-%S') %> by RockBooks version <%=RockBooks::VERSION %></p>
+<br />
+<% receipts.each  %>
+<h2>Financial Statements</h2>
+<ul>
+  <li><a href='balance_sheet.html'>Balance Sheet</a></li>
+  <li><a href='income_statement.html'>Income Statement</a></li>
+</ul>
+<h2>All Transactions</h2>
+<ul>
+  <li><a href="all_txns_by_acct.html">By Account</a></li>
+  <li><a href="all_txns_by_amount.html">By Amount</a></li>
+  <li><a href="all_txns_by_date.html">By Date</a></li>
+</ul>
+<h2>Journals</h2>
+<ul>
+  <% journals.each do |journal|
+    filespec = journal.short_name + '.html'
+    caption = "#{journal.title} -- #{journal.short_name} -- #{journal.account_code}"
+%>
+    <li><a href="<%= filespec %>"><%= caption %></a></li>
+  <% end %>
+</ul>
+<h2>Individual Accounts</h2>
+<ul>
+  <%
+    chart_of_accounts.accounts.each do |account|
+      filespec = File.join('single-account', "acct_#{account.code}.html")
+      caption = "#{account.name} (#{account.code})"
+  %>
+    <li><a href="<%= filespec %>"><%= caption %></a></li>
+  <% end %>
+</ul>
+  <h2>Receipts</h2>
+  <ul>
+    <% if run_options.do_receipts  %>
+      <li><a href="receipts.html">Missing and Existing Receipts</a></li>
+    <% end %>
+  </ul>
+</body>
+</html>

data/lib/rock_books/errors/date_range_error.rb ADDED Viewed

@@ -0,0 +1,20 @@
+module RockBooks
+  class DateRangeError < RuntimeError
+    attr_reader :date, :start_date, :end_date, :extra_string
+    def initialize(date, start_date, end_date, extra_string = nil)
+      @date = date
+      @start_date = start_date
+      @end_date = end_date
+      @extra_string = extra_string
+    end
+    def to_s
+      s = "#{date} is not within this data set's period of #{start_date} to #{end_date}"
+      s << " (#{extra_string})" if extra_string
+      s << '.'
+      s
+    end
+  end
+end

data/lib/rock_books/reports/balance_sheet.rb CHANGED Viewed

@@ -19,14 +19,14 @@ class BalanceSheet
   def end_date
-    context.end_date || Time.new.to_date
+    context.chart_of_accounts.end_date
   end
   def generate_header
     lines = [banner_line]
     lines << center(context.entity || 'Unspecified Entity')
-    lines << center("Balance Sheet -- #{end_date}")
+    lines << center("Balance Sheet for Period Ending #{end_date}")
     lines << banner_line
     lines << ''
     lines << ''

data/lib/rock_books/reports/income_statement.rb CHANGED Viewed

@@ -17,12 +17,12 @@ module RockBooks
   def start_date
-    context.start_date || Date.new(1900, 1, 1)
+    context.chart_of_accounts.start_date
   end
   def end_date
-    context.end_date || Date.new(2100, 1, 1)
+    context.chart_of_accounts.end_date
   end

data/lib/rock_books/reports/report_context.rb CHANGED Viewed

@@ -3,8 +3,6 @@ module RockBooks
 class ReportContext < Struct.new(
     :chart_of_accounts,
     :journals,
-    :start_date,
-    :end_date,
     :page_width)
   def entity

data/lib/rock_books/version.rb CHANGED Viewed

@@ -1,3 +1,3 @@
 module RockBooks
-  VERSION = "0.1.6"
+  VERSION = "0.2.0"
 end

data/manual.md ADDED Viewed

@@ -0,0 +1,251 @@
+# RockBooks Manual
+| Note: |
+| ---- |
+| See also the [README.md file](README.md) for an overview of high level concepts. |
+### Getting Started
+Install the RockBooks software:
+`gem install rock_books`
+It is recommended that you create a directory structure such as this:
+```.
+├── 2018-xyz-inc
+│   ├── invoices
+│   ├── receipts
+│   ├── references
+│   ├── rockbooks-inputs
+│   ├── rockbooks-reports
+│   ├── statements
+│   └── worksheets
+```
+The top level is a directory containing your data for a given entity for a single reporting period (probably a year).
+Here are the subdirectories:
+* `rockbooks-inputs` - all input documents (chart of accounts, journals)
+* `rockbooks-reports` - all generated reports and web content
+* `receipts`
+* `invoices`
+* `references`
+* `statements`
+* `worksheets`
+The last five can contain your non-RockBooks specific files that you would normally keep anyway. These directories will be offered by the reports home page web interface merely to navigate the filesystem, with links to view the files using the default application for that file type. Receipts are handled specially though -- you can specify a receipt in a journal and it will be checked for existence in the Receipts report. In the future we hope to generate hyperlinks to both receipts and invoices in the journal reports.
+Feel free to organize your files in subdirectories of these directories in whatever way makes sense to you. I have subdirectories of `receipts` for each month (`01`, `02` ... `12`).
+### Version Control
+Tracking this directory tree with version control software such as `git` in a private repository is _highly_ recommended because it provides:
+* free cloud backup with Github, Gitlab, and/or Bitbucket
+* an audit trail with human readable diffs
+* manageable collaboration
+### Chart of Accounts
+You will need a chart of accounts in the `rockbooks-inputs` directory. A sample chart of accounts is provided in the sample data (see [sample_data/minimal/rockbooks-inputs/2018-xyz-chart-of-accounts.txt](sample_data/minimal/rockbooks-inputs/2018-xyz-chart-of-accounts.txt)).
+### Journals
+You will need journals. Usually there would be one journal per external financial institution accounts, such as checking and credit card accounts. Samples have been provided in the sample_data/minimal/rockbooks-inputs directory of the gem:
+* [Checking](sample_data/minimal/rockbooks-inputs/2018-xyz-checking-journal.txt)
+* [Credit Card](sample_data/minimal/rockbooks-inputs/2018-xyz-visa-journal.txt)
+### General Journal
+The general journal is a special journal that is not associated with any particular account. One use of the general journal is for entering the balances of the assets, liabilities, and equity accounts at the beginning of the reporting period (usually a year). A sample general journal is at [sample_data/minimal/rockbooks-inputs/2018-xyz-general-journal.txt](sample_data/minimal/rockbooks-inputs/2018-xyz-general-journal.txt).
+The general journal is a special case of journal because transactions in it do not have an implied account (e.g. the checking account for a checking account journal); both sides of the transaction need to be explicitly specified. This is its strength and purpose; it is intended to be used where a transaction would not fit in a regular journal.
+### Terminology Usage
+* _data file_ - a RockBooks input data file, which is a text file with the extension `.txt`
+* _document_ - a RockBooks logical document such as a chart of accounts, a journal, etc., usually containing information parsed from a data file
+* _input records_ - repeating records appropriate to the document type, i.e. accounts for the chart of accounts and transactions for journals
+* _document properties_ - per document properties such as title, account; property names are preceded by `@` and initialized like this: `@account: ck_abc`.
+### Input Data File Format
+#### Plain Text
+Input data files are plain text files. We recommend using a text editor and _not_ a word processor for them. If you don't already have a favorite text editor, some excellent graphical text editors are [VS Code](https://code.visualstudio.com/), [Atom](https://atom.io/), and [Brackets](http://brackets.io/).
+Fields are space separated; any number of spaces can be used.
+#### Comment Lines
+Lines beginning with `#` will be ignored when the input data is parsed. Comment lines are useful for:
+* explanations of the input itself
+* information that you would like to be available for deeper research or examination but not printed in the reports
+#### Document Properties
+Data lines that contain the value of document properties,
+as opposed to input records, will be expressed as lines beginning with `@`:
+```
+@doc_type: journal
+@title: "ABC Bank Checking Account Disbursements Journal"
+@account: ck_abc
+```
+#### Input Records
+Input records are multiple records for the type appropriate to the document:
+* chart of accounts - each account
+* journals - each transaction
+Input records are, in general, entered into the text files after all properties. One exception is that the `@date_prefix` is often specified in multiple places in the journal, usually with a new month (e.g. `@date_prefix: 2018-11`).
+Data lines will contain fields that an be separated with an arbitrary number of spaces, e.g.:
+```
+2018-05-18   123.45   supplies
+```
+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 and included in reports.
+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 typing.
+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.
+For clarity, it is recommended that all accounts for each of the five account types be grouped together. That is, list all the assets first, then all the liabilities, etc.
+### Journals
+There is no particular restriction on what journals should be used, or which transactions should go in which journal. Do whatever makes the most sense in the context of your entity's financial activities. Each journal is merely an entry point for data into the ultimate list of transactions used to arrive at account balances. You could even (theoretically) have multiple journals for the same bank account, such as one per quarter or month, if that made them more manageable for you.
+Here are some examples of possible journals:
+* a checking account
+* a credit card account
+* a Paypal account
+* sales (all sales, or 1 journal per client)
+* a loan to/from shareholder/owner account
+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) for an account that has more outgoing than incoming transactions, 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
+```