rock_books 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80a8729354ab4814e6703e459d4a95ef1d2ce537cd71ab3d87c976ed45ec4b8c
-  data.tar.gz: aa7ac7d7ddbf5cc913631085c769e212460e5e317f884e4e847577a057c9ecc4
+  metadata.gz: 9e4e92f78b312267260f444d6650180bea2a9b248177b91d28cbb12db63e97b6
+  data.tar.gz: ed88d2eda1870d85d972e8e0e56ae141aa4cdef67b7a09e254af812c1435b7c1
 SHA512:
-  metadata.gz: b1d621b011fc393ce025cdd0729674eb52dcb09b8e106407a35547115a44a8af21453e1159c921b9604785d27e174af84bbf6819e3b61896db0821d89e7fbe87
-  data.tar.gz: b73f51018ef14b8db92d2e96d72ee5d08419ec119d9da753cd91861b7df827acfd922b70930f02a2fa51e3287b1c025935dc5605c2997f65ae1b9c6ea812b7ac
+  metadata.gz: 1c08cce1a4ed26f2dd2caeda2857e0443cfbb31c83952d172819c134b9d5ff6c7457dbac258142052f19baef55b19f352cf05988921e23f0c008b30895db48f8
+  data.tar.gz: 0665fe1fa4ccadb3fe420174c2cd13efc4e3c18f676f96f86877dc5eea30d59d3315e02b492ef0e2ffad0d8c80f56fed79ad14ec1e4345c53d581e846cca19d8

data/.gitignore

@@ -7,6 +7,7 @@
 /spec/reports/
 /tmp/
 /.idea/
+.DS_Store
 
 # rspec failure tracking
 .rspec_status

data/README.md

@@ -1,183 +1,101 @@
 # RockBooks
 
-A super primitive bookkeeping system using text files as input documents and console output
-for reporting.
+| Note: |
+| ---- |
+| The [manual.md file](manual.md) has more detailed information about RockBooks usage. |
 
-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! 
+**A simple but useful accounting software application for very small entities.**
 
-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.
+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! 
 
-So, to really have this software make sense to you, you should probably understand
-the double entry bookkeeping paradigm pretty well. 
+After entering the data in input files, there is a processing step (a single command) that is done to validate the input and generate the reports and home page. (This could be automated using `guard`, etc.) An `index.html` is generated that links to the reports, input documents, receipts, invoices, statements, worksheets, etc., in a unified interface. This `index.html` can be opened locally using a `file:///` URL but the directory tree can easily be copied to a web server for shared and/or remote access.
 
-# Terminology Usage
+#### How RockBooks Is Different
 
-* document - a RockBooks logical document such as a chart of accounts, a journal, etc.,
-usually containing information parsed from a data file
+Mainstream accounting packages like QuickBooks have lots of bells and whistles, but are opinionated and not customizable; if you want to use your data _your_ way, or do something differently, you're out of luck.
 
-* data file - a RockBooks data file, which is a text file with the extension `.txt`
+RockBooks is different in many ways.
 
+The software is in the form of Ruby classes and objects that can be incorporated into your own code for your own customizations. The data is available to programmers as Ruby objects (and therefore JSON, YAML, etc.) In addition, RockBooks could be used as an engine with alternate pluggable UI's. Feel free to write a web app for inputting the data!
 
-## Data File Format
+Rather than hiding accounting concepts from the user, RockBooks embraces and exposes them. There is no attempt to hide the traditional double entry bookkeeping system, with debits and credits. Accounting terminology is used throughout (e.g. "chart of accounts", "journals"). Some understanding of accounting or bookkeeping principles is helpful but not absolutely necessary.
 
-Lines beginning with `#` will be ignored.
+To simplify its implementation, RockBooks assumes some conventions:
 
-Data lines that contain the value of document properties,
-as opposed to transactions, etc., will be expressed as lines beginning with `@`:
+* Input documents (chart of accounts, journals) are assumed to be in the `rockbooks-inputs` directory.
 
-```
-@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.
+* The following directories are assumed to contain the appropriate content, or nothing at all. They are simply presented on the reports web page as directories in the filesystem, so you can feel free to organize files in subdirectories as you see fit:
 
-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
+  * `receipts` - receipts documenting expenses & other transactions
+  * `invoices` - sales/services invoices
+  * `statements` - statements from banks, etc.
+  * `worksheets` - spreadsheets, etc., e.g. mileage and per diem calculations
   
+  
+#### Text Files as Input
 
-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.
+Instead of a web interface, data input is done in plain text files. This isn't as fancy but has the following advantages:
 
-### Journals
+* Data can be tracked in git or other version control software, offering a readable and easily accessible audit trail, manageable collaboration, with free cloud backup including history with Github, Gitlab, Bitbucket, etc.
 
-Journals (also referred to as _documents_ by this application)
-are used to record transactions of, for example:
+* Text notes of arbitrary length can be included in input files, and included or excluded in reports. This can be useful, for example, in explaining the context of a transaction more thoroughly than could be done in a conventional accounting application. This can be helpful to accountants, auditors, etc., saving the time, and you money, and can demonstrate your helpfulness and transparency.
 
-* 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
+* Data will be longer lived, as it is readable and printable without any special software.
 
-Each journal data file needs to contain:
+* Users can use their favorite text editors.
 
-`@doc_type: journal`
+* All data entry can be done without moving the hands away from the keyboard.
 
-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`
+#### The Accounting Period
 
-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.
+There is no handling of end of year closings or the like; the entire set of data in the input files is considered included in the reporting period when generating the reports. Therefore, the best approach is to create a new data set for each year. The chart of accounts and journal files can be copied and modified as necessary.
 
-For example, a _Cash Disbursements Journal_ (something like a
-check register) may contain a transaction like this:
+#### RockBooks Help Text
 
 ```
-05-29   37.50   ofc.spls
+Command Line Switches:                    [rock-books version 0.2.0 at https://github.com/keithrbennett/rock_books]
+
+-i   input directory specification, default: './rockbooks-inputs'
+-o   output (reports) directory specification, default: './rockbooks-reports'
+-r   receipts directory, default: './receipts'
+-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
+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')
+
+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
 ```
 
-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.
+## What RockBooks Is Not
 
-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
-```
+As a product written by a single developer in his spare time, RockBooks lacks some conveniences of traditional accounting software programs, such as:
 
+* Import of data from financial institutions
+* On the fly data validation
+* Data entry conveniences such as drop down selection lists for data such as accounts
+* Fancy reporting and graphing -- however, RockBooks' bringing links to all the entity's documentation and output into a single web page may well be more useful
+* At this time, RockBooks is only tested on Macs. The input files are plain text files and could be created on any OS, but the validation and report generation might not work. Get in touch with me if you are using a different OS and want to use RockBooks, and are willing and available to test my changes. Linux in particular should be an easy port.
 
 
 ## 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
 
 ## Contributing

data/RELEASE_NOTES.md

@@ -1,3 +1,11 @@
+## v0.2.0
+
+* Add instruction manual, modify readme.
+* Overhaul generated index.html.
+* Add accounting period start and end date to configuration and reports.
+* Add validation of transaction dates to ensure within configured date range.
+* Make report hash / OpenStruct keys consistently symbols.
+
 ## v0.1.6
 
 * Fixed PDF output; PDF files were corrupt because cupsfilter starting sending

data/lib/rock_books/cmd_line/command_line_interface.rb

@@ -80,7 +80,14 @@ When in interactive shell mode:
 
   def validate_run_options(options)
 
-    return if options.suppress_command_line_validation
+    if [
+        # the command requested was to show the project page
+        find_command_action(ARGV[0]) == find_command_action('proj'),
+
+        options.suppress_command_line_validation,
+    ].any?
+      return  # do not validate
+    end
 
     validate_input_dir = -> do
       File.directory?(options.input_dir) ? nil : "Input directory '#{options.input_dir}' does not exist. "
@@ -280,7 +287,7 @@ When in interactive shell mode:
     os = OpenStruct.new(book_set.all_reports($filter))
 
     # add hash methods for convenience
-    def os.keys; to_h.keys.map(&:to_s); end
+    def os.keys; to_h.keys; end
     def os.values; to_h.values; end
 
     # to access as array, e.g. `a.at(1)`
@@ -368,6 +375,8 @@ When in interactive shell mode:
 
 
   def find_command_action(command_string)
+    return nil if command_string.nil?
+
     result = commands.detect do |cmd|
       cmd.max_string.start_with?(command_string) \
     && \

data/lib/rock_books/documents/book_set.rb

@@ -13,6 +13,7 @@ require_relative '../reports/transaction_report'
 require_relative '../reports/tx_by_account'
 require_relative '../reports/tx_one_account'
 
+require 'erb'
 require 'open3'
 
 module RockBooks
@@ -28,27 +29,31 @@ module RockBooks
 
 
     def report_context
-      @report_context ||= ReportContext.new(chart_of_accounts, journals, nil, nil, 80)
+      @report_context ||= ReportContext.new(chart_of_accounts, journals, 80)
     end
 
 
     def all_reports(filter = nil)
+
+      periods_to_underscores = ->(string) { string.gsub('.', '_') }
+
       context = report_context
       report_hash = context.journals.each_with_object({}) do |journal, report_hash|
-        report_hash[journal.short_name] = TransactionReport.new(journal, context).call(filter)
+        key = periods_to_underscores.(journal.short_name).to_sym
+        report_hash[key] = TransactionReport.new(journal, context).call(filter)
       end
-      report_hash['all_txns_by_date'] = MultidocTransactionReport.new(context).call(filter)
-      report_hash['all_txns_by_amount'] = MultidocTransactionReport.new(context).call(filter, :amount)
-      report_hash['all_txns_by_acct'] = TxByAccount.new(context).call
-      report_hash['balance_sheet'] = BalanceSheet.new(context).call
-      report_hash['income_statement'] = IncomeStatement.new(context).call
+      report_hash[:all_txns_by_date] = MultidocTransactionReport.new(context).call(filter)
+      report_hash[:all_txns_by_amount] = MultidocTransactionReport.new(context).call(filter, :amount)
+      report_hash[:all_txns_by_acct] = TxByAccount.new(context).call
+      report_hash[:balance_sheet] = BalanceSheet.new(context).call
+      report_hash[:income_statement] = IncomeStatement.new(context).call
 
       if run_options.do_receipts
-        report_hash['receipts'] = ReceiptsReport.new(context, *missing_and_existing_receipts).call
+        report_hash[:receipts] = ReceiptsReport.new(context, *missing_and_existing_receipts).call
       end
 
       chart_of_accounts.accounts.each do |account|
-        key = 'acct_' + account.code
+        key = ('acct_' + periods_to_underscores.(account.code)).to_sym
         report = TxOneAccount.new(context, account.code).call
         report_hash[key] = report
       end
@@ -74,8 +79,15 @@ module RockBooks
     def all_reports_to_files(directory = '.', filter = nil)
       reports = all_reports(filter)
 
+      create_directories = -> do
+        %w(txt pdf html).each do |format|
+          dir = File.join(directory, format, SINGLE_ACCT_SUBDIR)
+          FileUtils.mkdir_p(dir)
+        end
+      end
+
       # "./pdf/short_name.pdf" or "./pdf/single_account/short_name.pdf"
-      build_filespec = ->(short_name, file_format) do
+      build_filespec = ->(directory, short_name, file_format) do
         fragments = [directory, file_format, "#{short_name}.#{file_format}"]
         is_acct_report =  /^acct_/.match(short_name)
         if is_acct_report
@@ -84,20 +96,31 @@ module RockBooks
         File.join(*fragments)
       end
 
-      reports.each do |short_name, report_text|
-        txt_filespec  = build_filespec.(short_name, 'txt')
-        html_filespec = build_filespec.(short_name, 'html')
-        pdf_filespec  = build_filespec.(short_name, 'pdf')
+      create_index_html = -> do
+        filespec = build_filespec.(directory, 'index', 'html')
+        File.write(filespec, index_html_content)
+        puts "Created index.html"
+      end
 
-        FileUtils.mkdir_p(File.dirname(txt_filespec))
-        FileUtils.mkdir_p(File.dirname(html_filespec))
-        FileUtils.mkdir_p(File.dirname(pdf_filespec))
+      write_reports = ->do
 
-        File.write(txt_filespec, report_text)
-        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"
+        reports.each do |short_name, report_text|
+          txt_filespec  = build_filespec.(directory, short_name, 'txt')
+          html_filespec = build_filespec.(directory, short_name, 'html')
+          pdf_filespec  = build_filespec.(directory, short_name, 'pdf')
+
+          File.write(txt_filespec, report_text)
+          # Use smaller size for the PDF but larger size for the web pages:
+          run_command("textutil -convert html -font 'Courier New Bold' -fontsize 11 #{txt_filespec} -output #{html_filespec}")
+          run_command("cupsfilter #{html_filespec} > #{pdf_filespec}")
+          run_command("textutil -convert html -font 'Courier New Bold' -fontsize 14 #{txt_filespec} -output #{html_filespec}")
+          puts "Created reports in txt, html, and pdf for #{"%-20s" % short_name} at #{File.dirname(txt_filespec)}.\n\n\n"
+        end
       end
+
+      create_directories.()
+      create_index_html.()
+      write_reports.()
     end
 
 
@@ -134,5 +157,14 @@ module RockBooks
       end
       [missing, existing]
     end
+
+    def index_html_content
+      erb_filespec = File.join(File.dirname(__FILE__), 'index.html.erb')
+      erb = ERB.new(File.read(erb_filespec))
+      erb.result_with_hash(
+          journals: journals,
+          chart_of_accounts: chart_of_accounts,
+          run_options: run_options)
+    end
   end
 end

data/lib/rock_books/documents/chart_of_accounts.rb

@@ -1,11 +1,12 @@
 require_relative '../types/account'
 require_relative '../types/account_type'
 require_relative '../errors/error'
+require_relative '../errors/date_range_error'
 
 module RockBooks
 class ChartOfAccounts
 
-  attr_reader :doc_type, :title, :accounts, :entity
+  attr_reader :doc_type, :title, :accounts, :entity, :start_date, :end_date
 
 
   def self.from_file(file)
@@ -21,9 +22,19 @@ class ChartOfAccounts
   def initialize(input_lines)
     @accounts = []
     input_lines.each { |line| parse_line(line) }
+    # TODO: Add validation for required fields.
   end
 
 
+  def parse_date(date_string)
+    # TODO: Add better handling for this error.
+    # begin
+      date = Date.iso8601(date_string)
+    # rescue ArgumentError
+    #  ..
+    # end
+  end
+
   def parse_line(line)
     case line.strip
     when /^@doc_type:/
@@ -32,6 +43,10 @@ class ChartOfAccounts
       @entity ||= line.split('@entity:').last.strip
     when /^@title:/
       @title = line.split('@title:').last.strip
+    when /^@start_date:/
+      @start_date = parse_date(line.split('@start_date:').last.strip)
+    when /^@end_date:/
+      @end_date = parse_date(line.split('@end_date:').last.strip)
     when /^$/
       # ignore empty line
     when /^#/
@@ -69,6 +84,11 @@ class ChartOfAccounts
   end
 
 
+  def included_in_period?(date)
+    (start_date..end_date).include?(date)
+  end
+
+
   def report_string
     result = ''
 
@@ -119,10 +139,12 @@ class ChartOfAccounts
 
 
   def ==(other)
-    doc_type == other.doc_type   && \
-    title    == other.title      && \
-    accounts == other.accounts   && \
-    entity   == other.entity
+    doc_type   == other.doc_type   && \
+    title      == other.title      && \
+    accounts   == other.accounts   && \
+    entity     == other.entity     && \
+    start_date == other.start_date && \
+    end_date   == other.end_date
   end
 end
 end