penny-fit.7

.TH penny-fit 7
.
.SH NAME
penny-fit - Penny financial institution statements parser
.
.SH SYNOPSIS
.B penny-fit
[global-options] COMMAND [local-options] ARGS
.
.SH DESCRIPTION
.
.B penny-fit
works with data you have downloaded from your financial
institution.
.
It parses statements that you have downloaded and adds
transactions from the statements to your ledger, skipping those that
have already been added.
.
It also helps you reconcile your ledger with
financial institution statements.
.
.P
First you will have to configure and compile a
.B penny-fit
binary.
.
You can use the
.B penny-fit-sample.hs
file in the
.I doc
directory of the
.B penny-bin
package as an example.
.
Alternatively, if you know your way around Haskell, see the Haddock
documentation for the
.I Penny.Brenner
module.
.
The comments in that file should help you get
started.
.
.P
Currently Penny includes a parser for Open Financial
Exchange, or OFX, data.
.
Many banks make information available in this
format, as Quicken and the now-defunct Microsoft Money both support
the format.
.
.SH IMPORTING
.
To use
.BR penny-fit ,
first you will download the appropriate data from your financial
institution and place it in a file.
.
.I penny-fit info
will tell give you a little more information about the place to look
on your institution's web site to download the data, if you have
configured that information in your binary.
.
.P
Then, run
.IR "penny-fit -f ACCOUNT import FILENAME" .
The first time you run this command, you will have to add the
.I --new
option after the
.I import
command, which allows the creation of a new database.
.
Without this
option, if the database is not found,
.B penny-fit
quits with an error message.
.
The ACCOUNT must be a financial
institution account that you configured in your
.B penny-fit
binary (if you configured a default account and you want to use that,
you can omit the
.I -f
option).
.
The FILENAME is the location of the data that you just
downloaded.
.
.P
The
.I import
command will examine the data that you downloaded.
.
Using the unique
identifiers already assigned to each posting by your financial
institution, the
.I import
command determines whether you have already downloaded each particular
posting.
.
If the posting is new,
.I import
assigns a different, unique number to the posting.
.
This is called a
.IR U-number .
The U-number allows you to uniquely identify each posting that you
download.
.
The data from the financial institution, along with the
U-number, is added to a database at the location specified in your
configuration.
.I import
automatically skips postings that have already been processed, so you
do not have to worry about importing duplicate postings.
.
.SH MERGING
.
Next you will want to merge new postings into your ledger.
.
Do this by
running
.I penny-fit -f ACCOUNT merge LEDGER_FILE...
where LEDGER_FILE is one or more filenames for your ledger files.
.
.I merge
examines your ledgers to see if each of the postings in the database
for this financial institution is represented in your ledger.
.
To do
this it looks at the postings in the
.I pennyAcct
specified in your configuration.
.
For each U-number in the database,
.I merge
sees if there is a posting in the
.I pennyAcct
with a tag bearing the U-number (e.g. if the U-number is 5, it looks
for the tag
.IR U5 ).
If a posting has more than one U-number tag, only the first is used;
the others are ignored.
.
If such a posting is found,
.I merge
moves on to the next U-number in the database.
.
If no matching posting is found for a U-number,
.I merge
sees if there is a matching posting that does
.I not
have a U-number tag.
.
If there is a posting in the
.I pennyAcct
that has the same quantity and date as the financial institution
posting,
.I merge
will then examine the debit or credit of the ledger posting.
.
.P
This table describes whether
.I penny-fit
will find a match:
.
.TS
tab(:);
l l l l
- - - -
l l l l.
T{
If the financial institution posting is a
T}:T{
and translator is
T}:T{
and the ledger posting is a
T}:T{
then is there a match?
T}
increase:IncreaseIsDebit:debit:Yes
increase:IncreaseIsDebit:credit:No
increase:IncreaseIsCredit:debit:No
increase:IncreaseIsCredit:credit:Yes
decrease:IncreaseIsDebit:debit:No
decrease:IncreaseIsDebit:credit:Yes
decrease:IncreaseIsCredit:debit:Yes
decrease:IncreaseIsCredit:credit:No
.TE
.
.P
If
.B penny-fit
finds a match for a financial institution posting in this way, then it
will assign a new U-number tag to the posting.
.
If
.B penny-fit
does not find a match, then it will create an entirely new transaction
and append it to the end of your ledger.
.
.P
If it is creating an entirely new transaction,
.B penny-fit
will attempt to give the new transaction the same account and payee
information that you have used for similar transactions in the
past.
.
To do this,
.B penny-fit
will first search through the database to find the most recent
financial institution posting that has the same payee as the one of
the new transaction. If one is found,
.B penny-fit
then searches through the postings in your ledger file to find the one
that has the same U-number and account as the old financial
institution posting.
.
If it is found,
.B penny-fit
will assign the payee name found on the posting in the ledger to the
new posting.
.
Also, if the posting found in the ledger has exactly one
sibling posting,
.B penny-fit
will assign the same account name from that sibling to the new
sibling.
.
You can turn off this automatic assignment of information by using the
.I --no-auto
or 
.I -n
option to the
.I merge
command.
.
.P
The result of
.I merge
is printed to standard output, unless you use the
.I --output FILENAME
or
.I -o FILENAME
option, in which case the output is sent to
.IR FILENAME .
.
You can use multiple
.I -o
options.
.
To explicitly send output to standard output, use
.IR "-o -" .
.
Use
.BR diff (1)
or
.BR penny-diff (1)
to see what changes
.I merge
made.
.
Typically you will need to edit the output somewhat.
.
.SH RECONCILING
.
Next you may wish to reconcile your ledger with your financial
institution data (that is, "balance the checkbook").
.
Typically the
most time-consuming part of this process is finding the postings in
your ledger that match the postings on your bank statement.
.
.B penny-fit clear
will help with this, dramatically speeding up the process.
.
To do
this, download data from your financial institution that corresponds
to the data that is covered within the current statement period.
.
Run
.B penny-fit import
and
.B penny-fit merge
as described above. Then run
.
.P
.EX
penny-fit -f ACCOUNT clear FIT_FILE LEDGER_FILE...
.EE
.
.P
where FIT_FILE is the data file you downloaded from your financial
institution, and LEDGER_FILE contains your ledger data.
.
The
.I clear
command will mark as cleared (that is, assign a
.I C
flag to) all postings in your LEDGER_FILEs that correspond to one of
the postings in the FIT_FILE.
.
It does this by matching the U-number
tags on your postings to the U-numbers in the database.
.
If a posting
has more than one U-number tag, only the first is used; the others are
ignored.
.
.P
As with the 
.I merge
command, the results are printed to standard output unless you use the
.I --output FILENAME
or
.I -o FILENAME
option.
.
Once you have verified that things
are as they should be, you can use
.BR penny-reconcile (1)
to mark the cleared postings as reconciled.
.
.BR penny-basics (7)
has more details on how to use
.B penny
when reconciling a financial institution statement.
.
.SH OTHER COMMANDS
.
The
.I database
command prints the database for a particular financial institution to
standard output in human-readable form (the database unfortunately is
not in plain human-readable text).
.
For instance you might use this to
see what U-number is assigned to a particular financial institution
posting.
.
.P
The
.I print
command parses a downloaded file of financial institution data and
prints the result to standard output.
.
This is useful for seeing the
contents of a financial institution data file, or for testing new
parsers.
.
.P
Every
.B penny-fit
command has a
.I -h
and a
.I --help
option.
.
There is also a global
.I --help
option, as in
.IR "penny-fit --help" .
.
.SH BUGS
To quote another man page: "Bugs?
.
You must be kidding, there are no
bugs in this software.
.
But if we happen to be wrong, send us an email
with as much detail as possible to" omari@smileystation.com.
.
.SH SEE ALSO
.BR penny-suite (7)