Figure 1: General Key Bindings.
Curtis L. Olson
curt@sledge.mn.org
September 28, 1996
Copyright © 1994, 1995, 1996 by Curtis L. Olson.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
CBB is a personal check book balancing utility for Unix/X. It is written entirely in Perl and Tcl/Tk so it is very portable and very extendable. It is a program for anyone who would like to balance their checkbook and manage their money using free software under Unix and X.
CBB is intended to be an open, extensible program. It utilizes a simple, easily understood data file format and is written entirely in scripts. In addition, it provides a simple interface for users to add their own reports and graphs without modifying any of the CBB source. In the future, I plan to create a simple interface to other external modules with the intent that others will provide modules to increase CBB's functionality.
CBB stands for the Check Book Balancer. This name was ``discovered'' late one afternoon in a fit of extreme creativeness. Every once in a while I try to think of something better, but as of yet, nothing has come to mind.
CBB is to be used as an application for balancing one's check book. Any other use (such as ammunition for a mail bomb or lining a cat's litter box) is not supported or recommended. CBB is currently nearing the end of its alpha/prototype stage. Version 0.60a represents a fairly substantial reworking/reorganization of version 0.53a--although this may not always be immediately visible on the surface. Version 0.62a represents a substantial amount of rework to better support tk4.0.
I sincerely hope you can find CBB useful in your day to day and year to year money management. I am always working to improve this program so please send in your comments, suggestions, and complaints.
If you would like to contact me, you may send email to curt@sledge.mn.org. I will do my best to respond in a timely manner and address your issue or concern.
The current version of CBB is always available via anonymous ftp from:
ftp.me.umn.edu:/pub/finance/cbb-[version].tar.gz
CBB is written in Perl and Tcl/Tk. These need to be installed on your
system before you can can continue. Note, CBB now requires tk4.0 or
higher and perl4 or higher. If you notice any problems or
incompatibilities please let me know.
Tcl and Tk are available via anonymous ftp from:
ftp://ftp.smli.com/pub/tcl/
Note, the Tcl FAQ has a list of mirror sites. You can read the FAQ online at:
http://www.cis.ohio-state.edu/hypertext/faq/usenet/tcl-faq/top.html
Perl is available via anonymous ftp from:
prep.ai.mit.edu:/pub/gnu/perl-5.***.tar.gz
ftp.cs.umn.edu:/pub/gnu/perl-5.***.tar.gz
Untar the distribution file and cd to the newly created directory.
Type make install.
Specify the location of perl and wish4.0 and specify where
you would like the executables and associated files installed.
If you are upgrading from a pre-0.60a version, you will need to upgrade your data files as well.
The initial versions of CBB saved its data in an ASCII text file with the fields delimited by the `:' character. However, not too far into this CBB project (at version 0.50a I believe) I switched my thinking and decided to take advantage of perl's dbm support. This has one primary advantage. Any changes made to the data file are immediately saved. This also has some disadvantages. It tends to close off the data file so it can only be manipulated from within CBB. This is good from a ``data encapsulation'' stand point, but it suddenly becomes a problem if the data file needs to be manipulated in a way which CBB doesn't support. Another point to note is that because perl is so good at slurping in text files, and because of certain constraints imposed by the Tk front end, using the dbm format did not provide any speed advantage. In fact, for certain operations I noted a speed decrease.
With the above observations in mind, I decided to come full circle and return to saving CBB data files in an open ASCII format by default. The astute among you may observe that ASCII files have one major disadvantage. They are only saved at the user's request. So, one hapless user working all day without saving + one unexpected power outage, one press of the reset button, or one of any other creative ways people invent to destroy their data = trouble. To counter this problem, I created an auto save feature. At regular intervals, if the current data file has been modified, it is saved to a temporary file. This greatly reduces the risk of data loss stupidity or acts of God--or acts of God in response to our stupidity.
For those of you who have grown to love the dbm format, do not despair. In the spirit of openness I have decide to support dbm data files as well--although in a slightly modified form.
The new ASCII data file format is defined to be one record per line with the fields delimited by the <tab> character. The new dbm data file format is of the form <key> <record> where CBB assigns each record a unique key. The dbm record is identical to the ASCII record: a single line of text with the fields delimited by the <tab> character.
(Hopefully this doesn't give any one a migrain.)
I have provided a perl script to automate the data file migration, migrate-to-0.60a.pl. It is located in the contrib subdirectory of the distribution-dir directory.
The migrate script will perform the following tasks:
When the script has finished, your data files should be all set for your new version of CBB. Start up CBB and poke around your files a bit. If you notice any problems, let me know immediately--and be glad you backed up all your data like I suggested earlier.
The following is a quick run down of some of the more notable recent additions to CBB.
I have been maintaining an informal list of people who are especially interested in this program. I try to keep this group up to date on the current happenings of CBB. If you would like to be included on this list, simply send me a note and ask to be place on the list. My email address is curt@sledge.mn.org
So, you want to go for a little test drive? Want to see how or if this thing works? Want to send me a 21inch monitor or the DOS drivers for my ancient Sony PAS16-SCSI cdrom drive? Well, read on ...
The following procedure will lead you through the process of creating a new account, importing some data, editing transactions, and balancing your account.
First, here is the ``one-paragraph'' version of this manual. To use CBB, first make a directory where you would like to keep your group of accounts. Then, go to this directory, run cbb, and make your account(s). Optionally you could choose to import the default categories, but this can be done at any time. Next, load the desired account (if it is not already loaded) and create, delete, and edit transactions to your hearts content. When your statement arrives in the mail, balance your account. Mean while, you have been printing some reports, viewing some graphs, maybe setting up some recurring transactions, and hopefully managing your money better than before you started using CBB!
Ok, so you've just installed CBB. What now? Well, if you are like me, you will have already run it a few times before you cracked open the manual and read all the way down to here. So go ahead and lauch CBB again. The first thing you need to do is create an account.
Now that you have created an account it is time to enter a few transactions. If you like, you can import some sample data to save your fingers from the brutalities of typing. Otherwise, feel free to skip this section and enter your own transactions. The CBB distribution comes with some sample data just for this tutorial!
Now, that you have some data to play with, try editing a transaction. Then try creating new transactions. Try playing around with ``splits'' to specify more than one category for a transaction. Play around with things until you get the hang of it. You can refer to Section 4.2 for a more detailed description of transaction editing.
Now, lets pretend you just received your bank statement in the mail and you want to reconcile your new account. Lets also pretend that you didn't mess thing up too bad back in Section 3.4.
When your next statement arrives and you run the balance routine again, you will only be presented with ``uncleared'' transactions to select. This is a good way to spot old checks that never were cashed ...such as your mortgage payment that got ``lost in the mail.'' Note: by balancing your checkbook in this manner, two good things happen. The first is, when your brother finally cashes that check for $100.00 - many months after you wrote it - your bank balance doesn't suddenly drop -$100.00 from where you think it should be. That transaction had always been entered and subtracted out of your bank balance. The second good thing is that it is easy to spot these sorts of situations so that you can call up your brother and pester him to cash the check.
Now that you have entered a bit of data, you may want to ``understand'' your data at a deeper level. CBB comes with several reports and graphs which can help you get a better idea of where and how your money is being spent. Feel free to look at a few reports and graphs at this point.
Wow! You've been slaving away for the last 10 minutes perfecting your demo account. Great job! That is about all there is to it. CBB isn't rocket science. It's just boils down ``plus and minus''. Since this is not real data, you probably don't care to save it. However, if this had been an actual account, you most definitely would want to save your hard work. CBB stores all your changes in memory, so you must save the account before you quit. If your forget to save your work before you quit, CBB will remind you to do this. If you do something awful, like reboot your machine or log out without saving, you are not completely out of luck. CBB periodically saves a backup copy of your account with a file name of #account.cbb#. Just rename this file to account.cbb and you will be back on track.
To create a new account from scratch, choose Make New Account ... from the File menu. Enter the account name without any extension. (CBB will automatically add a .cbb to the name you provide.) This account name will become a category of the form [acct-name] description for use in transfers between accounts. Section 4.4 explains how transfers work. Next enter a description for this account. When you satisfied with your name and description, click on the Create Account button and your new empty account will be created and loaded.
To create a new account based on exported Quicken data, create a new account from scratch as described in the previous subsection. Once the account has been created, Quicken data can be imported into it. Importing data from Quicken is explained in Section 4.10.1.
Setting an initial balance for an account is as simple as creating a first transaction with a credit amount equal to the initial balance.
At all times in CBB (except for those times when you are doing other things) you are either creating new transactions, or editing existing transactions. Other operations such as balancing may temporarily suspend the entry, but when the chosen function is completed, you are returned to your current edit or insert operation.
At any time you can abort the current edit or insert operation by initiating a new edit or insert.
When you are satisfied with the current contents of the edit area, hit Return and the transaction will be updated. If you are creating a new transaction, it will be inserted. If if you are editing an existing transaction, it will be updated.
Tk4.0 provides several standard key bindings to facilitate data entry. These tend to mimic emacs key bindings. Figure 1 shows a list of some of the more useful of these key bindings. For those hackers among us: look in $(TK_LIB_DIR)/entry.tcl for a complete list of key/mouse bindings.
Figure 1: General Key Bindings.
When the focus is in the check number field you can use the + and - keys to increment and decrement the number. CBB remembers the last check number you used, so when you are creating a new transaction, pressing + will insert the next check number. Figure 2 shows a list of these key bindings.
Figure 2: Check Number Field Bindings.
The + and - keys work as you expect when the focus is in the date field. They will increment or decrement the date. CBB does not try to keep track of things like leap year or even the number of days in a specific month. So, if the date is 2/28/95 and you press +, you will see 2/29/95 and 30 and 31. Hopefully this is not a major annoyance. Figure 3 shows a list of these key bindings.
Figure 3: Date Field Bindings.
The Splits function allows you to ``split'' the value of a transaction among several different categories. Caution: Even though you may click Dismiss in the Splits window, the transaction will not be updated. You need to hit Return again once the splits window is closed. Note also: The maximum number of splits can be set in your .cbbrc.tcl file.
CBB keeps a list of transactions sorted and indexed by description. When entering a typical transaction you would normally first specify the check number, then specify the date, then specify the description. If you have entered a similar transaction in the past, then you only need to type the first few characters of the description, hit Tab and the rest of the transaction is filled in for you. At this point you should make any necessary changes. Finally, you can update the transaction by hitting Return.
If you don't want your transaction completed (i.e. your transaction is being completed in an undesired fashion) you can type Control-Tab in the description field to avoid the completion feature.
The transaction is auto-completed only once per transaction. In other words, your changes won't keep getting overwritten each time you tab through the description field. Also, this feature is only activated by Tabbing from the description field. Shift-Tabbing or pressing Return have the same effect as they do in any other field.
Note: You can turn this feature on and off from the File -> Preferences menu.
Categories are used to give each transaction a ``type.'' This is useful for reporting, since the report can be organized by category.
Adding categories currently can be accomplished by simply using them in a transaction. When the transaction is updated, and the category is unknown, you will be asked if you wish to insert the new category into the list. Simply fill in the category description and check the Tax Related box (if it is tax related.) Once you are satisfied, click on the Add button.
Alternatively you can manually edit the categories file. CBB stores the category file in the same subdirectory as the associated account file. Note, the fields are delimited by tabs. Have fun and be careful!
Categories can be viewed by selecting Categories -> Category List ... from the Functions menu. This brings up a list of categories. When the category list is open, double clicking on an category will paste it into the current entry. Alternatively, you can select a category and click on the Paste button.
Once the category list window has been opened (see Section 4.3.2) simply select a category and click on the Delete button and the category will be deleted.
When an account is created, a category of the form [acct-name] is also created. To create a transfer to another account, use the destination account name (enclosed in [ and ]) to specify the account being transfered to. When the transaction is inserted into the current account a corresponding transaction will be inserted in destination account. WARNING: currently when a transfer transaction is edited or deleted, its corresponding transaction will not be altered. This must be done manually. CBB will remind you of this whenever you edit or delete a transfer transaction.
Clicking on the Balance button will bring up a list of all ``uncleared'' transactions in a window. CBB already knows your statement beginning balance. It is simply the sum of all the cleared transactions. Verify your statement's beginning balance then enter your ending balance. At this point you can go through and check off all the transactions that are listed on your statement. CBB will keep a running total of the beginning balance + the transactions. When you are all done, this should equal the ending balance. If it doesn't, there is a discrepancy someplace ...which will hopefully be not too hard to track down. When everything matches, click on the Update button. This will ``clear'' all the selected transactions. When you balance your checkbook next month, only the ``uncleared'' transactions will be presented to you.
This technique makes it easy to spot and handle situations when some
idiot
doesn't
cash your check for 3 months ...it is still in the system and easy
to spot. This way your idea of your balance stays in sync with the
bank's idea of your balance. And since it is entered into CBB and
subtracted from your running balance, you won't get burned when they
finally do cash it.
As of version 0.60a of CBB, I have completely reworked the reporting mechanism. Each report is actually a stand-alone, self-sufficient, executable perl script (although there is nothing magical about the use of perl.)
When you select a Reports ... you are presented with a dialog box. In this dialog box you can select the report you would like to print, the files you would like to include in the report, a date range, and report destination. If you wish to include all transactions up to a certain date, leave the Starting Date field blank. If you wish to include all transactions from a certain date on, leave the Ending Date field blank. To include all transactions leave both fields blank. Dates should be in the following format: mm/dd/[[yy]yy]. Valid dates are 5/19, 5/19/95, and 5/19/2095.
Reports can be printed to a variety of destinations. If you select Send to Screen the report will be displayed in a window. If you select Save to File or Pipe, enter a file name in the appropriate field and the report will saved to that file. If you specify a file name of the form | command, CBB will pipe the output of the report through the specified command. For instance, if you wanted to send the report to a printer, you could enter something like | nenscript -2Gr | lpr -d hp4L.
The first report is simply a list of all transactions. It looks remarkably like the contents of the transaction list box.
The next report displays all transactions sorted and subtotaled by category. It properly handles splits.
This report is similar to the Transaction List By Category report except it omits the individual transactions and only displays the sum of the transactions for each category. It also properly handles splits.
This report will scan through all the transactions of the selected accounts and find any breaks in the sequence. It will also flag any duplicate check numbers.
Also new to version 0.60a is graphing. Graphing is very similar to reporting. Each graph is actually a stand-alone, self-sufficient, executable perl script which creates a plot file and calls gnuplot. In order for graphing to work, you must have gnuplot installed in your path.
When you select a graph you are presented with a dialog box similar to the one presented for report printing. You can select a graph, group of input files, and a date range. If you wish to include all transactions up to a certain date, leave the Starting Date field blank. If you wish to include all transactions from a certain date on, leave the Ending Date field blank. To include all transactions leave both fields blank. Dates should be in the following format: mm/dd/[[yy]yy]. Valid dates are 5/19, 5/19/95, and 5/19/2095.
This graph is relatively lame. It is very simple minded and is intended only as an example of how to create graphs from within CBB. As time permits or as other contribute, you will see more graphs.
Currently, preferences need much work ...However, you can set a few things including fonts in your .cbbrc.tcl file.
All changes must be saved--or how could they be called changes--they are not really changes at all until they are saved--they are only proposed changes.
CBB is similar to vi or emacs in that all your changes are made in RAM. So, just like you must save your work in vi or emacs, you must save your work in CBB. To do this, click on the Save button or select Save Account or Save Account As ... from the file menu.
New to version 0.60a is an ``auto save'' feature. Your proposed changes are saved to a temporary file at regular intervals. (This interval defaults to 3 minutes and can be set in your .cbbrc.tcl file.)
As always, save early and save often!
CBB is capable of importing Quicken export files. These files are of the form <name>.qif. The transfer process is relatively simple.
CBB is also capable of generating Quicken export files. These files can be imported into Quicken. This process is also relatively simple.
This section describes several scripts that are beyond the original scope of CBB, yet may be useful in managing your money. These scripts are installed in: $CBB_LIB_DIR/contrib
The script fetch-latest.pl will automatically fetch the latest version of CBB from ftp.me.umn.edu. It will then untar and gunzip it. Finally it will run the standard install procedure to install it.
You can run this script from within CBB by selecting Fetch & Install Latest CBB from the External menu. Then, answer the standard install questions when prompted. Don't forget to quit and restart CBB once the install has completed successfully.
The script invest.pl is a simple hack to help me keep track of my investments. It accepts a simply formatted text file from stdin and writes a simple report to stdout. A sample input file could look like the following. Note: each field is separated by one or more tabs.
# Date Description Shares Unit Price #----- ----------- ------ ---------- 19960101 Beginning of 1996 10.000 25.00 19960201 Updated value 0.000 26.56 19960301 Purchase more shares 10.00 25.87 19960401 Updated value 0.000 26.04 19961216 St Cap Gain Reinvest 1.157 26.43 19961216 Lt Cap Gain Reinvest 1.220 26.43 19961216 Service Fee -0.568 26.43
Executing the command: cat sample.inv | invest.pl would produce the following output:
Price Total
New per Shares Total Total
Date Description Shares Share Owned Invstd Value
-------- ---------------------- ------ ------ ------ ------ ------
19960101 Beginning of 1996 10.000 25.00 10.000 250.00 250.00
19960201 Updated value 0.000 26.56 10.000 250.00 265.60
19960301 Purchase more shares 10.000 25.87 20.000 508.70 517.40
19960401 Updated value 0.000 26.04 20.000 508.70 520.80
19961216 St Cap Gain Reinvest 1.157 26.43 21.157 539.28 559.18
19961216 Lt Cap Gain Reinvest 1.220 26.43 22.377 571.52 591.42
19961216 Service Fee -0.568 26.43 21.809 556.51 576.41
Please see section 2.5, page 
for
an explanation of this script and its use.
Wouldn't you like your mortgage payment to entered automatically every month? Would you like to have some idea of how much money you will have in a month, six months, or a year? Then read on. This might be just what you need.
Recurring transactions which have been automatically inserted are denoted by placing a ``?'' in the ``cleared'' field. This is changed to a ``!'' when the transaction date has passed. (Note: this code is changed to a ``x'' when the transaction is cleared.)
The recur.pl script has two main sections.
The config (<account>.rcr) file is reminiscent of a crontab file. The format is slightly different, but the idea is generally the same. Specify the days, months, and years that the transaction will take place, then specify the transaction. One thing to note is that all fields must be separated by one <Tab> character. The script will then insert that transaction on those days.
For instance, the following entry will cause an auto loan payment to be inserted on the fifth of every month. Once the transaction has been entered, you can make any changes you like to it, such as adding
# Days Months Years Description Debit Credit Comment Category # ---- ------ ----- ----------- ----- ------ ------- -------- 5 * * Loan's R Us 100.00 0.00 Auto-Loan
Another variation would be the following entry which will insert a transaction every fourth of July.
4 7 * Fireworks 35.00 0.00 Bang Entertainment
The next entry will insert a transaction on the 15th and last day of every month.
15,last * * Salary 0.00 3.14 Peanuts Salary Income
This entry will insert a transaction on the 1st day of January, April, July, and October.
* 1,4,7,10 * Auto Insurance 200.00 0.00 Approx. Insurance
REMEMBER, separate each field by a <Tab> character and
not spaces.
Finally, a slightly different entry format will allow you to enter transactions based on a regular interval such as every other week. The first field specifies the start date of the interval. This can be any date, but recur.pl will never enter past recurring transactions. The transactions will kick in after the current date. Then next field is the interval in days. So 14 would specify an interval of every other week. The third field is ignored and not used. The last five fields are identical to the previous types of entries.
# Start Date Intrvl Not Used Description Debit Credit Comment Category # ---------- ------ -------- ----------- ----- ------ ------- -------- 19960119 14 * Salary 0.00 2.78 Peanuts Salary
The script yearend.pl simply moves all uncleared transactions from the specified account to a new account. This helps keep file sizes smaller. Usage: yearend.pl <account>.cbb <new-account>.cbb
CBB stores the values of a few standard variables in the
.cbbrc.tcl file. Whenever CBB starts, it first sources this
file. This file is regenerated based on the current value of the
relevant variables whenever an account is created, loaded, or saved.
Any additions/deletions will be lost. However, changes to the values
of the variables will be maintained. Figure 4 on
page shows a sample .cbbrc.tcl file.
Figure 4: Sample .cbbrc.tcl File
CBB has a user configurable menu entitled External. The file extern.conf controls the contents of this menu. An example of an extern.conf file is:
Reports ... <Tab> conf-reports -report -t %t -a %a
Graphs ... <Tab> conf-reports -graph -t %t -a %a
-
Calculator <Tab> xcalc
Calendar <Tab> xcalendar
-
Fetch & Install Latest CBB <Tab> xterm -sb -e \
$lib_path/contrib/fetch-latest.pl
The first field (everything before the <tab>) is the name to appear on the External menu. The second field (everything after the <tab> is the command line of the program to execute. Before launching the external program, CBB will save the current contents of the buffer to a temporary file. This allows the external program to have access to any changes that have been made, but not yet saved. The %t is replaced with the full path name of this temporary file. The %a is replaced with the full name of the current account file.
CBB has a ``simple'' well defined interface for installing new reports. Each report is a stand alone ``program'' which understands a predefined set of command line options and displays its output to stdout.
When the Configure Reports program is launched, it looks for the file, .../lib/cbb/reports/reports.conf. This file consists of entries like the following:
Transaction List rep-txn-list.pl Txn List by Category rep-by-cat.pl Short List by Category rep-by-cat-shrt.pl
Each line contains two fields. The report name which will appear in the dialog box, and the executable name of the report. CBB scans this file when it starts up in order to create the Reports menu.
CBB assumes that all report executables will also be located in the .../lib/cbb/reports/ directory. Each report must accept the following options where date if of the form mm/dd/[yy[yy]] and account-list is a list of a CBB (ASCII) format account files:
Usage: report [ -from date ] [ -to date] account-list
The report executable will read the entries in the specified account files, ignore any entries outside the specified date range, and print its output to stdout. The last thing the report should print is a single line containing the text none.
When a report is selected from the Reports menu, CBB displays the Report Configuration dialog box. When the user clicks on Generate Report, CBB saves the current contents of its ``buffer'' to a temporary file. It then looks up the corresponding report executable, and launches it with the above options. CBB reads the output of the executable (stopping when it receives a line containing only the text none) and routes it according what the user specified in the Report Configuration dialog box.
The procedure for creating and installing new graphs is analogous to the reports procedure. One thing to note, the graph executable should wait for a carriage return from stdin before exiting. This is CBB's way of letting the graph executable know that the user is done looking at the graph.
When CBB is invoked with the -devel option, a Devel menu is added to the menu bar. This menu will allow you to re-``source'' the various Tk pieces of CBB. With this option enabled you can reload various pieces of the code after modifying them without quiting and restarting CBB. This can greatly speed up the development process in some situtations.
This works by executing the Tk source command on the selected file. To use this feature effectively, you need to be aware of the contents of a particular Tk file. Effectively, you are re-running that code at the time you are sourcing it. Therefore, old procedure definitions will be replaced if they were changed. The thing to watch out for is code that is executed outside of procedure calls. This code will be executed when you re-source the file. This may or may not cause a problem if this code is intended to be run only once on startup.
Activating and using this menu is something you only need to be concerned about if you are actively developing code.
The FAQ tends to resist emacs TeX mode. This is most annoying.
Because of this I have placed the FAQ in its own separate file called
...Ta da!!! ...``FAQ''. The FAQ is also available on the CBB
web page at: http://www.menet.umn.edu/~clolson/cbb/
CBB
Check Book Balancer - X Version
This document was generated using the LaTeX2HTML translator Version 96.1 (Feb 5, 1996) Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
The command line arguments were:
latex2html -split 0 -show_section_numbers cbb-man.tex.
The translation was initiated by Curtis L. Olson on Fri Oct 4 17:18:47 CDT 1996