.TH penny 1
.SH NAME
penny - report on postings in financial ledger
.SH SYNOPSIS
penny [posting filter expression] report name [report options] FILE...
.SH DESCRIPTION
The
.B penny
program prepares reports based upon the
.B postings
in your ledger file. Each transaction has at least two postings. After
.B penny
verifies that your ledger file is
.I balanced
(that is, every transaction has debits and credits that are equal)
.B penny
splits each transaction into its component postings. After this point,
.B penny
for the most part deals only with postings, not with transactions.
You may specify a
.I filter expression
that determines which postings are ultimately used for the report. The
filter expression may also contain additional options that perform
tasks other than filtering. For example, you may specify how to
perform text matching (for instance, you may want to use regular
expressions) or you may specify that you want to sort the postings (by
default, they are not sorted and are left in the order in which they
were found in the input ledger).
Next you must specify a
.IR report .
Currently there are two reports:
.BR postings ,
which shows information about each posting, like a checkbook register, and
.BR balance ,
which shows you information about the balance of each account. The
report is based only upon the postings that the filter expression
returned.
You may then specify options pertaining to the report. The
.BR postings
report takes many options that format its output and that specify
which postings are shown in the report; however, postings that the
filter expression returned that are not shown in the report still
affect the running balance. This can be useful if, for example, you
want to see the total balance in your bank account and how some
transactions affect it but you do not want to see all transactions
since the beginning of time. The
.BR balance
report takes many fewer options.
Finally you may specify one or more files from which to draw the
data. If you do not specify a file, standard input is used.
The report is always printed to standard output. By default,
.BR penny
sees whether its standard output is a terminal. If so,
.BR penny 's
output is sized to fit the width of the
.BR COLUMNS
environment variable (if it is set) and is printed in color. If
standard output is not a terminal, by default the output is not in
color and will be 80 characters wide. This behavior can be overridden
on the command line.
Entering the data into the ledger files is your responsibility;
.B penny
will never modify this data. To see how to enter data into the file,
see the file
.BR samplePennyFile ,
which is included inside the package for
.BR penny-bin .
.SH COMPARERS
Many options perform comparisons; for example, the
.B --date
option compares postings to a date you specify to determine
which postings to keep and which to reject. Where
.I comparer
appears below, you must supply one of the following strings.
You will need to quote many of them, because many of these
characters will have special meaning for your shell.
.TS
tab(:);
l l l
- - -
lB lB l.
Primary form:Alternate form:Comparison performed
<::Less than
<=::Less than or equal to
==:T{
=
T}:Equals
>::Greater than
>=::Greater than or equal to
/=:!=:Not equal to
.TE
.SH POSTING FILTERS
.SS Dates
.TP
.BI "--date | -d " "comparer timespec"
The date of the posting must be within the time frame given.
.BR date
is the same format as dates in the
.B penny
file and
is either a date alone, such as
.BR 2012-04-25 ,
or a date and a time, such as
.BR "2012-04-25 14:25 -0400" .
.TP
.B --current
Same as
.BI "--date <= " "right now"
.SS Serials
These perform matching based on serials. For more on serials,
see the section
.B SERIALS
below. Each option takes the form
.IR "option comparer number" .
.TP
.B --globalTransaction
.TQ
.B --revGlobalTransaction
.TQ
.B --globalPosting
.TQ
.B --revGlobalPosting
.TQ
.B --fileTransaction
.TQ
.B --revFileTransaction
.TQ
.B --filePosting
.TQ
.B --revFilePosting
.SS Pattern matching
These options allow you to filter postings by specifying a pattern
that must match a particular component of the posting. By default the simple
.I within
matcher is used, and matches are case-insensitive.
.TP
.BI "--account | -a " pattern
The sub-accounts of the account are separated with colons, and the
match succeeds if the pattern matches this entire colon-separated
name.
.TP
.BI "--account-level " "number pattern"
The account is separated into sub-accounts, which are numbered
beginning at zero. The match succeeds if the posting has a sub-account
numbered at the given level, and if that sub account matches the given
pattern.
.TP
.BI --account-any " pattern"
The account is separated into sub-accounts. The match succeeds if the
pattern matches any of a posting's sub-accounts.
.TP
.BI "--payee | -p " pattern
Succeeds if the pattern matches the posting's payee. If the posting
has no payee, the payee of the parent transaction is used (if there is
one).
.TP
.BI "--tag | -t " pattern
Succeeds if any one of the posting's tags matches the given pattern.
.TP
.BI --number " pattern"
Succeeds if the posting's number matches the given pattern. (This is
the number that you specify in parentheses in your ledger file, not
the line number or any of the serial numbers.) If the posting has no
number, the number of the parent transaction is used (if there is
one).
.TP
.BI --flag " pattern"
Succeeds if the posting's flag matches the given pattern. If the
posting has no number, the flag of the parent transaction is used
(if there is one).
.TP
.BI --commodity " pattern"
The commodity is separated into colon-separated sub-commodities, and
the test succeeds if the pattern matches the full colon-separated
commodity name.
.TP
.BI "--commodity-level " "number pattern"
The commodity is separated into sub-commodities, which are numbered
beginning at zero. The match succeeds if the posting has a sub-commodity
numbered at the given level, and if that sub-commodity matches the given
pattern.
.TP
.BI "--commodity-any " pattern
The commodity is separated into sub-commodities. The match succeeds if
the pattern matches any of a posting's sub-commodities.
.TP
.BI "--posting-memo " pattern
The posting memo must match the given pattern.
.TP
.BI "--transaction-memo " pattern
The transaction memo must match the given pattern.
.SS Other posting characteristics
.B --debit
The entry must be a debit.
.B --credit
The entry must be a credit.
.BI --qty " comparer number"
The entry's quantity must fall within the given range.
.SS Operators
Each of the options above is a single operand. If you have multiple
operands, you must join them together using operators. These
operators are specified below, from highest to lowest precedence. All
operators are left associative.
.TP
.BI "--open " expr " --close"
Force precedence using parentheses. Enclose a complete expression
between the
.B --open
and
.B --close
options.
.TP
.BI "--not " expr
True if
.I expr
is false.
.TP
.IB expr1 " --and " expr2
True if
.I expr1
and
.I expr2
are both true.
.TP
.IB expr1 " --or " expr2
True if
.I expr1
or
.I expr2
is true.
.SS Options affecting patterns
These options affect how patterns are interpreted. The order of the
.B penny
command line is significant; each of these options only affects
patterns that appear after it on the command line.
.TP
.B "-i | --case-insensitive"
Patterns are case insensitive (default)
.TP
.B "-I | --case-sensitive"
Patterns are case sensitive
.TP
.B --within
Use the "within" matcher (default), which matches if the pattern given
appears anywhere within the target text. This is a simple
letter-for-letter match, not a regular expression, though its case
sensitivity is affected by the
.B --case-insensitive
and
.B --case-sensitive
options.
.TP
.B --pcre
Use the "pcre" matcher, which uses Perl-compatible regular expressions (see
.BR pcresyntax "(1) and " pcrepattern (1))
.TP
.B --posix
Use the "posix" matcher, which uses POSIX regular expressions (see
.BR regex (7))
.TP
.B --exact
Use the "exact" matcher, which matches if the given pattern is a
letter-for-letter match of the target text, with case sensitivity
determined by the
.B --case-insensitive
and
.B --case-sensitive
options.
.SH Removing postings after sorting and filtering
.TP
.BI "--head " n
Keep only the first
.I n
postings.
.TP
.BI "--tail " n
Keep only the last
.I n
postings.
.SH Sorting
.TP
.BI "--sort | -s " key
Sorts postings according to a key. Use multiple
.B --sort
options to sort by more than one key. Valid keys are: payee, date,
flag, number, account, drCr, qty, commodity, postingMemo,
transactionMemo.
The postings are sorted in ascending order if the first letter of the
key is lowercase; descending order if the first letter of the key is
uppercase.
.SH POSTINGS REPORT
The
.B postings
report, or
.B pos
for short, shows postings in order with a running balance. This report
takes all the options shown above in the categories from "Posting
filters" to "Removing postings after sorting and filtering." These
options affect which postings are shown in the report. Postings that
are not shown in the report but which were not filtered out in the
filtering stage still affect the report's running balance.
Additional options for the
.B postings
report:
.SS Additional serial filtering options
These options affect which postings are shown. Postings that were not
filtered in the filtering stage but that are not shown still affect
the running balance. In addition to using the same options that are
used for filtering, these additional options are available that are
based on some additional serials. They take the form
.IR "option comparer number " .
For more information on serials, see the
.B SERIALS
section below.
.TP
.B --filtered
filtered serial, forward component
.TQ
.B --revFiltered
filtered serial, reverse component
.TQ
.B --sorted
sorted serial, forward component
.TQ
.B --revSorted
sorted serial, reverse component
.SS Other additional options for the balance report
.TP
.BR --color " yes|no|auto|256"
Controls which colors are shown.
.B yes
always shows 8 colors.
.B no
never shows colors.
.B auto
first examines whether standard output is a terminal. If standard output is not a terminal,
.B penny
does not show any colors. If standard output is a terminal, examines
the value of the TERM environment variable. If TERM is
"xterm-256color", uses 256 colors. If TERM is any other value, or if
TERM is not set, uses 8 colors.
.TP
.BR --background " light|dark"
Pick a color scheme for a light or dark terminal background (by
default, a dark color scheme is used.)
.TP
.BI --width " num"
Gives a hint for roughly how wide the report should be, in
columns. Sometimes the report will be narrower than the specified
width; however, it will never be wider than the specified width.
.TP
.BI "--show" " field"
.TQ
.BI "--hide" " field"
Show or hide fields from the displayed report. Fields are displayed in
a fixed order, which is the same as the order that the table below is
in. Fields with an asterisk are shown by default.
.\" Do not precede the empty fields in the table with any spaces. This
.\" will cause GNU tbl to segfault.
.\" See
.\" http://lists.gnu.org/archive/html/groff/2010-11/msg00014.html
.\" Apparently the bug has been fixed but who knows how long that will
.\" take to propogate.
.TS
tab(:);
lB lB l.
:globalTransaction:globalTransaction serial, forward component
:revGlobalTransaction:globalTransaction serial, reverse component
:globalPosting:globalPosting serial, forward component
:revGlobalPosting:globalPosting serial, reverse component
:fileTransaction:fileTransaction serial, forward component
:revFileTransaction:fileTransaction serial, reverse component
:filePosting:filePosting serial, forward component
:revFilePosting:filePosting serial, reverse component
:filtered:filtered serial, forward component
:revFiltered:revFiltered serial, reverse component
:sorted:sorted serial, forward component
:revSorted:sorted serial, reverse component
:visible:visible serial, forward component
:revVisible:visible serial, reverse component
:lineNum:line number (starting from 1)
*:date:transaction's date
:flag:posting or transaction flag
:number:posting or transaction's number
*:payee:posting or transaction's payee
*:account:posting's account
*:postingDrCr:whether the posting is a debit or credit
*:postingCmdty:posting's commodity
*:postingQty:posting's quantity
*:totalDrCr:whether the running total is a debit or credit
*:totalCommodity:commodity of the running total
*:totalQty:quantity of the running total
:tags:posting's tags
:memo:the posting and transaction memo
:filename:filename where the posting came from
.TE
.TP
.B --show-all
Show all fields
.TP
.B --hide-all
Hide all fields
.TP
.B --show-zero-balances
Shows the balance of all commodities in the
.IR totalDrCr ", " totalCommodity ", and " totalQty
fields, even if that balance is zero.
.TP
.B --hide-zero-balances
Hides the balance of commodities in the
.IR totalDrCr ", " totalCommodity ", and " totalQty
fields if they are zero (default)
.SH BALANCE REPORT
The
.B balance
report summarizes the balances in each account that is represented in
the postings that remain after the filtering specifications are
carried out. You can use sorting specifications with the balance
report, but they will have no effect. The accounts are shown
hierarchically. This report is also useful for converting from one
commodity to another.
The
.B balance
report accepts the following options:
.TP
.BI --color " yes|no|auto|256"
Controls how many colors to display:
.TS
tab(:);
lB l.
yes:always show 8 colors
no:never show any colors
auto:T{
show 8 or 256 colors, but only if standard output is a terminal.
If standard output is a terminal, shows 256 colors if the value
of the TERM environment variable is \fIxterm-256color\fR;
otherwise, shows 8 colors.
T}
256:always show 256 colors
.TE
.TP
.BI --background " light|dark"
Use appropriate color scheme for the given terminal background
.TP
.BI --convert " commodity dateTime"
Convert all commodities to the given commodity using their price as of
the given date and, optionally, time.
.IR commodity " and " dateTime
follow the same format as the respective items in a ledger file. If
any commodity does not have a matching price,
.B penny
will fail and give you an error message.
.TP
.BI -c " commodity"
Same as
.BI "--convert " "commodity [right now]"
.SH SERIALS
Each posting is assigned several
.IR serials ,
each of which is a pair of ordinal numbers. The first number in the
pair, or
.IR "forward component" ,
is assigned by numbering the transactions or postings from
beginning to end beginning at zero, while the second number in the
pair, or
.IR "reverse component" ,
is assigned by numbering the transactions or postings from end to
beginning, beginning at zero. Here are all the serials that are
assigned to each posting.
.TP
.B globalTransaction
All transactions are numbered in order, beginning with those in the
first file specified on the command line and ending with the last
file. Occurs before the transactions are split into postings.
.TP
.B fileTransaction
Like
.IR globalTransaction ,
but numbering restarts with each new file.
.TP
.B globalPosting
All postings are numbered in order, beginning with those in the first
file specified on the command line and ending with the last file.
.TP
.B filePosting
Like
.IR globalPosting ,
but numbering restarts with each new file.
.TP
.B filtered
Postings are numbered after first removing the postings as specified
by the filtering options specified on the command line.
.TP
.B sorted
Postings are numbered in order after the sorting options have been
applied, which occurs after the filtering options have been applied.
.TP
.B visible
Postings are numbered in order after removing the postings as
specified by the options to the
.I postings
report. (Does not apply to the
.I balance
report.)
.SH SEE ALSO
The file
.B samplePennyFile
in the tarball for the
.B penny-bin
package shows you how to write a ledger file.