PDQ Ledger 1.6: A Finance Application

PDQ Ledger is a Financial application that has been written entirely in Tcl/Tk . It is distributed for free use under the Open Source Artistic License . Ledger uses double-entry accounting internally, and treats categories the same as accounts. Ledger sports features such as split transactions, scheduled transactions, account reconciliation, and transaction reports . Data entry is designed to be fast and simple using features such as auto filling transactions and auto completing fields as you type . There is also support for importing QIF , CBB and Qhacc transaction files.

Ledger was developed using Tk version 8.3 on Linux, but it should run and work anywhere that Tk does, including under Windows (and possibly the Mac). It's user interface uses the Tk text widget in interesting ways, and it stores data in plain text TDB format: as a Tcl array of lists. Ledger is reasonably fast, and has been load tested to the tune of 13K*2 transaction.

Downloading

Ledger is actually part of a collection of software called PDQ Interfaces. It can be downloaded from the PDQI site. There is nothing to compile, but you do need to have Tcl/Tk installed. Tcl/Tk is available from http://www.tcl.tk/ and a Windows installable binary may be found here. After unzipping pdqi, just run it with pdqi/lib/ledger.tcl or wish83 pdqi/lib/ledger.tcl under windows.

Getting Started

A good first step is to create a few accounts. Note that by default, accounts are of type category, so remember to uncheck that option. Next, since all transactions must go to a category/account, you should create some categories. A quick way to do this is to use the menu entry Account/Setup/Categories to create the default categories. You are no ready to start entering transactions. Note: Send any bug reports to Peter MacDonald at peter@pdqi.com

GUI Layout

Ledger employs a simplified interface that uses a single Amount field in place of the traditional Deposit/Withdraw pair. Negative amounts are treated as a withdrawal, positive amounts as a deposit. Also, Ledger does not auto-save, so you will need to manually save every so often. Not to worry though, you will be warned if you try to quit without saving any changes.

Ledger divides the screen into two half's. The left half is the list of accounts, while the right side lists the transactions in the current account. You can resize these by placing the cursor between the two half's to change the cursor into a double arrow. Pressing the left mouse button , and drag in either direction and release. Conversely, column are resized using right mouse button-move with the cursor over the column headers.

Sort values in columns is easy. Just click the left mouse button on the column header. A second click reverses the order of the sort. Se below for Keyboard Mappings keyboard shortcuts for transaction creation. Common ones are: Alt-n to open a New Transaction , and Alt-e will Edit A Transaction .

Importing Transactions

Ledger can import QIF, CBB or QHACC transactions. CBB or QIF files of transactions can be imported into specific accounts. First select the destination account as the current account. Then do the import (Account/Import). Missing destination category-accounts will be created as the import proceeds, and they will be considered category-accounts so you will want to manually change those that are real accounts afterwords. Note that as ledger stores all transactions in a single file, the user should import all accounts of transactions in one session, without quiting. This will automatically eliminate duplicate transactions from preceding imports. Refer to import.log for messages and warnings resulting from imports. Also, any transaction not having a destination account/category, will go to the account Unspecified .

The Qhacc import is different since Qhacc stores all of it's transactions in a single transaction file (just as Ledger does). Therefore Ledger can use qhacc/khacc input data files on startup, if you have never done a save yet (ie, no *.tld files). Just copy the files "account" and "transactions" into your blank ~/ledger directory and start Ledger . At startup ledger.tcl will load these files from to the ~/ledger directory. Or you can change the directory with the -dir option to use a different location.

Scheduled Transactions

Ledger supports basic scheduled transactions. These are transactions on a per/account basis. For example, to schedule a transaction for say every second Friday, select the starting date to be the first such Friday, and then set the period to 14. Similarly for quarterly transactions select monthly and set periods to 3.

Keyboard Mappings

Following are the main keyboard mappings.


  Alt-s    : Save.
  Alt-q    : Quit.
  Alt-n    : New transaction.
  Alt-e    : Edit transaction.
  Return   : Edit transaction.
  Alt-m    : Move transaction.
  Del      : Delete transaction.
  Down     : Next transaction.
  Up       : Previous transaction.
  PageDn   : Next page of transactions.
  PageUp   : Previous page of transactions.
  Home     : Begin of transactions.
  End      : End of transactions.
  Alt-Dn   : Next account.
  Alt-Up   : Previous account.
  Alt-b    : Toggle display of menu.

Inside entry inputs within dialogs, the following bindings apply:


  Alt-p    : Invoke the associated buttons (such as Split, Calculator...).
  Up       : For date fields, increase day by 1.
  Down     : For date fields, decrease day by 1.
  Left     : For date fields, increase month by 1.
  Right    : For date fields, decrease month by 1.
  PageUp   : For date fields, increase year by 1.
  PageDown : For date fields, decrease year by 1.

These are of course, in addition to the regular Tk key bindings.

Options

The following are the major options for Ledger , the default values are in braces: eg. (0). Refer to the ~/ledger/preference.tcl file for the complete list. All options require a value argument. Options generally may be provided either on the command-line or in the preferences.tcl file (except -dir). Preferences are saved to disk when the data is saved. Preferences used on the command line become permanent if a save occurs.


  -abspos         : Window placement uses geom absolute positioning.
  -aclist:fldmap  : Account view headers.
  -aclist:sort    : Name of field to sort by in accounts view. (aname)
  -aclist:sortdir : Direction of sort in accounts view. (increasing)
  -alt            : Set to Control to use control instead of alt keys. (Alt)
  -bg             : Background color. (lightblue)
  -catlower       : Categories are lower cased. (1)
  -cvtaccts       : Internal use.  See the code. (0)
  -datefmt        : Format to use for date. (%Y-%m-%d)
  -datefmts       : List of all possible date formats.
  -dir            : Directory to use for data.  Command line only.
  -fg             : Foreground color.
  -font           : Font to use.
  -geom           : Startup geometry.
  -hasmenu        : Enable menubar. (1)
  -hasstatus      : Enable status bar. (1)
  -hastoolbar     : Enable toolbar. (0)
  -maxsplits      : Max number of split transactions. (10)
  -lang           : Set language: default is English. (en)
  -langtrace      : If 1 trace unknown lang lookups to ~/ledger/langtrace.msg. (0)
  -nosched        : Do not apply scheduled transactions. (0)
  -showcat        : Show categories in accounts view. (1)
  -trace          : Set to 1 to trace proc calls.  Requires Tcl8.4. (0)
  -update         : Update only visible part of transaction view. (1)
  -usecvs         : Do a CVS commit at each save.  See above for setup.
  -usercs         : RCS commit each file at each save.
  -xaction:fldmap : Transaction view headers.
  -xaction:sortdir: Direction of sort in transaction view. (increasing)
  -xaction:sort   : Name of field to sort by in transaction view. (tdate)

Note that editing the -aclist:fldmap and -xaction:fldmap options in the preferences file is the only way to change the order columns appear in views. There is currently no way to modify these via the GUI. Refer to aclist:fields and xaction:fields at the top of ledger .tcl for the full list of field names. Similarly, the field labels are stored in the preferences file where they can be edit (for English only).

Archiving

There are three archiving functions provided in Ledger These are:

Backup All - Make a backup copy the whole data directory.
Archive Transactions - Save data from a date range.
Unarchive Transactions - Load back in saved data.

The first is self explanatory. The second will backup transactions and optionally accounts. Transactions may be limited by date and/or account. If the Save Accounts Also box is checked, the user is prompted for a directory to save the files to, else the name of a file to store transactions in is requested.

The last option, Unarchive, will prompt you for the name of a transactions file to import. If the file name is transactions.tld and there is an accounts.tld in the same directory, you will be further prompted if you wish to have it imported as well.

RCS and CVS

As the data entry to an accounting system can be an onerous task to have to redo, having a reliable backup is paramount. Ledger has built-in backup options. Using RCS and/or CVS it can incrementally archive changes each time a save occurs. This should work automatically under UNIX, or on any system that has ci or cvs installed. RCS can be utilized just by checking the appropriate box in the Options menu. This will do an RCS check-in at each save.

CVS supports off-host backup, but is more complex to setup. Here is a sample setup sequence under Unix:


 export CVSROOT=~/CVSROOT;    # Set CVSROOT, if required.
 mkdir $CVSROOT
 pdqi/lib/ledger.tcl;         # Then do a Alt-s save and exit.
 cd ~/ledger
 cvs import ledger Ledger add start
 cd ~/
 mv ledger ledger.old
 cvs checkout ledger

After this, just start ledger and check the CVS option in ledger. Obviously, in the case a recovery, it will be required to learn the cvs and ci commands. But one interesting scenarios is using both CVS and RCS at the same time, particularly when the CVS server is remote.

Language Options

Currently, a template lang/fr.msg file is provided with just enough of fields filled in to demonstrate language support. Volunteer translators are welcome. Note that the en.msg file can and is used to translate certain display fields like date strings.

Here is a screen-shot.