penny-bin-0.6.0.0: man/penny.1

.TH penny 1

.SH NAME
penny - report on postings in financial ledger

.SH SYNOPSIS
penny [global options] report name [report options] FILE...

.SH DESCRIPTION

This manual page is a complete reference for the operation of
.BR penny .
To get started, see
.BR penny-getting-started (1).

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
.IR "global options" .
Most global options allow you to create 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).

Other global options control the color scheme of the report and
whether colors are used at all.

Next you must specify a
.IR report .
Currently there are three reports. The
.BR postings
report shows information about each posting, like a checkbook register.
There are two reports that show account balances only: the
.BR balance
report and the
.B convert
report. Each report shows only the postings returned by the posting
filter expression.

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
and
.B convert
reports take 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.

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 examples/starter.pny ,
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 DISPLAY OPTIONS

.TP
.BI "--scheme " SCHEME_NAME
Use the given color scheme. By default, three schemes are available:
.IR dark ,
designed for dark-background terminals,
.IR light ,
for light-background terminals, and
.IR plain ,
which uses the terminal's default colors.
By default the
.I dark
scheme is used.

.TP
.BI "--color-to-file " "no|yes"
Whether to use color when standard output is not a terminal. Default is
.IR no .
If standard output is a terminal, the maximum color capabilities of your terminal are used. (If you do not like color, preface your
.B penny
command with
.IR TERM=dumb
or, alternatively, use
.BR "--scheme plain" ,
which has the same effect.)

.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"
Succeeds if the posting's commodity matches the given pattern.

.TP
.BI "--posting-memo " pattern
The posting memo must match the given pattern. For the purpose of this
option, the line breaks in the posting memo are replaced with spaces.

.TP
.BI "--transaction-memo " pattern
The transaction memo must match the given pattern. For the purpose of
this option, the line breaks in the transaction memo are replaced with
spaces.

.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.

Postings by default are sorted by date in ascending order; however,
any specification of a
.B --sort
option on the command line overrides this. For example,
.B --sort payee
sorts postings by payee from A-Z, while
.B --sort date --sort payee
sorts postings by date from oldest to newest and sorts postings with
the same date in payee order from A to Z.

If you want to leave postings in the order in which they appeared in
your ledger file, use
.BR "--sort none" .


.SH HELP
.TP
.B --help | -h
Show help and exit

.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
.TP
.B --revFiltered
filtered serial, reverse component
.TP
.B --sorted
sorted serial, forward component
.TP
.B --revSorted
sorted serial, reverse component

.SS Other additional options for the postings report

.TP
.BI --width " num"
Gives a hint for roughly how wide the report should be, in
columns. (By default the
.I COLUMNS
environment variable is used.)

.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
.BI "--zero-balances " "show|hide"
Whether to show the balance of all commodities in the
.IR totalDrCr ", " totalCommodity ", and " totalQty
fields, even if that balance is zero. (default: hide)

.TP
.B --help | -h
Show help and exit

.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 in the posting filter
expression, but they will have no effect. The
accounts are shown hierarchically.

The
.B balance
report accepts the following options:

.TP
.BI "--zero-balances " "show|hide"
Whether to show balances that are zero (default: hide)

.TP
.BI "--order " "ascending|descending"
Sort in ascending (default) or descending order by account name

.TP
.B --help | -h
Show help and exit

.SH CONVERT REPORT

The
.B convert
report shows account balances after converting all amounts to a single
commodity. In addition to converting commodities, it also can sort
accounts by their balances.  Accepts ONLY the following report
options:

.TP
.BI "--zero-balances " "show|hide"
Whether to show balances that are zero (default: hide)

.TP
.BI "--commodity | -c " "TARGET-COMMODITY"
Convert all commodities to
.IR TARGET-COMMODITY .
By default, the commodity that appears most often as the target
commodity in your price data is used. If there is a tie, the price
closest to the end of your list of prices is used.

.TP
.BI "--date | -d " "DATE-TIME"
Convert prices as of the date and time given. By default, the current
date and time is used.

.TP
.BI "--sort | -s " "name|qty"
Sort balances by sub-account name (default) or by quantity

.TP
.BI "--order " "ascending|descending"
Sort in ascending (default) or descending order

.TP
.B --help | -h
Show help and exit

.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. (Applies only to the
.I postings
report.)

.SH DEFAULT OPTIONS
This manual page often specifies defaults for various options. These
are the defaults that come "out of the box." You may configure your
own default options (see
.BR penny-custom (7).)
If you do that, the defaults you configure will be reflected in the
output of
.IR "penny -h" .

.SH EXIT STATUS
.B 0
if no errors;
.B 1
if there was a problem.

.SH BUGS
Please report any bugs in the software or documentation to
omari@smileystation.com.

.SH SEE ALSO
.BR penny-suite (7)

The file
.B examples/starter.pny
in the tarball for the
.B penny-bin
package shows you how to write a ledger file.