\input texinfo  @c -*-texinfo-*-

@setfilename ledger.info
@settitle Ledger: Command-Line Accounting

@documentencoding iso-8859-1

@iftex
@finalout
@end iftex

@titlepage
@title Ledger: Command-Line Accounting
@author John Wiegley
@end titlepage

@node Top, Introduction, (dir), (dir)
@top Overview

@menu
* Introduction::                
* Running Ledger::              
* Keeping a ledger::            
* Extending with Python::       
@end menu

@node Introduction, Running Ledger, Top, Top
@chapter Introduction

Ledger is an accounting tool with the moxie to exist.  It provides no
bells or whistles, and returns the user to the days before user
interfaces were even a twinkling in their father's CRT.

What it does offer is a double-entry accounting ledger with all the
flexibility and muscle of its modern day cousins, without any of the
fat.  Think of it as the Bran Muffin of accounting tools.

To use it, you need to start keeping a ledger.  This is the basis of
all accounting, and if you haven't started yet, now is the time to
learn.  The little booklet that comes with your checkbook is a ledger,
so we'll describe double-entry accounting in terms of that.

A checkbook ledger records debits (subtractions, or withdrawals) and
credits (additions, or deposits) with reference to a single account:
the checking account.  Where the money comes from, and where it goes
to, are described in the payee field, where you write the person or
company's name.  The ultimate aim of keeping a checkbook ledger is to
know how much money is available to spend.  That's really the aim of
all ledgers.

What computers add is the ability to walk through these transactions,
and tell you things about your spending habits; to let you devise
budgets and get control over your spending; to squirrel away money
into virtual savings account without having to physically move money
around; etc.  As you keep your ledger, you are recording information
about your life and habits, and sometimes that information can start
telling you things you aren't aware of.  Such is the aim of all good
accounting tools.

The next step up from a checkbook ledger, is a ledger that keeps track
of all your accounts, not just checking.  In such a ledger, you record
not only who gets paid---in the case of a debit---but where the
money came from.  In a checkbook ledger, its assumed that all the
money comes from your checking account.  But in a general ledger, you
write transaction two-lines: the source account and target account.
@emph{There must always be a debit from at least one account for every
credit made to another account}.  This is what is meant by
``double-entry'' accounting: the ledger must always balance to zero,
with an equal number of debits and credits.

For example, let's say you have a checking account and a brokerage
account, and you can write checks from both of them.  Rather than keep
two checkbooks, you decide to use one ledger for both.  In this
general ledger you need to record a payment to Pacific Bell for your
monthly phone bill.  The cost is $23.00, let's say, and you want to
pay it from your checking account.  In the general ledger you need to
say where the money came from, in addition to where it's going to.
The entry might look like this:

@example
9/29  BAL  Pacific Bell              $-200.00   $-200.00
           Equity:Opening Balances    $200.00
9/29  BAL  Checking                   $100.00    $100.00
           Equity:Opening Balances   $-100.00
9/29  100  Pacific Bell                $23.00    $223.00
           Checking                   $-23.00     $77.00
@end example

The first line shows a payment to Pacific Bell for $23.00.  Because
there is no ``balance'' in a general ledger---it's always zero---we
write in the total balance of all payments to ``Pacific Bell'', which
now is $223.00 (previously the balance was $200.00).  This is done by
looking at the last entry for ``Pacific Bell'' in the ledger, adding
$23.00 to that amount, and writing the total in the balance column.
And the money came from ``Checking''---a withdrawal of $23.00---which
leaves the ending balance in ``Checking'' at $77.00.  This is a very
manual procedure; but that's where computers come in...

The transaction must balance to $0: $23 went to Pacific Bell, $23 came
from Checking.  There is nothing left over to be accounted for, since
the money has simply moved from one account to another.  This is the
basis of double-entry accounting: that money never pops in or out of
existence; it is always a transaction from one account to another.

Keeping a general ledger is the same as keeping two separate ledgers:
One for Pacific Bell and one for Checking.  In that case, each time a
payment is written into one, you write a corresponding withdrawal into
the other.  This makes it easier to write in a ``running balance'',
since you don't have to look back at the last time the account was
referenced---but it also means having a lot of ledger books, if you
deal with multiple accounts.

Enter the beauty of computerized accounting.  The purpose of the
Ledger program is to make general ledger accounting simple, by keeping
track of the balances for you.  Your only job is to enter the
transactions.  If a transaction does not balance, Ledger will display
an error and indicate which transaction is wrong.@footnote{In some
special cases, it will automatically balance the entry for you.}

In summary, there are two aspects of Ledger use: updating the ledger
data file, and using the Ledger tool to view the summarized result of
your entries.

And just for the sake of example---as a starting point for those who
want to dive in head-first---here are the ledger entries from above,
formatting as the ledger program wishes to see them:

@example
2004/09/29 Pacific Bell
     Payable:Pacific Bell            $-200.00
     Equity:Opening Balances

2004/09/29 Checking
     Accounts:Checking                $100.00
     Equity:Opening Balances

2004/09/29 Pacific Bell
     Payable:Pacific Bell              $23.00
     Accounts:Checking
@end example

The account balances and registers in this file, if saved as
@file{ledger.dat}, could be reported using:

@example
$ ledger -f ledger.dat balance
$ ledger -f ledger.dat register checking
$ ledger -f ledger.dat register bell
@end example

@menu
* Building the program::        
@end menu

@node Building the program,  , Introduction, Introduction
@section Building the program

Ledger is written in ANSI C++, and should compile on any platform.  It
depends on the GNU multiprecision integer library (libgmp), and the
Perl regular expression library (libpcre).  It was developed using GNU
make and gcc 3.3, on a PowerBook running OS/X.

To build and install once you have these libraries on your system,
enter these commands:

@example
./configure && make install
@end example

@node Running Ledger, Keeping a ledger, Introduction, Top
@chapter Running Ledger

Ledger has a very simple command-line interface, named---enticing
enough---@command{ledger}.  It supports a few reporting commands, and
a large number of options for refining the output from those commands.
The basic syntax of any ledger command is:

@example
ledger [OPTIONS...] COMMAND [ARGS...]
@end example

Command options must always precede the command word.  After the
command word there may appear any number of arguments.  For most
commands, these arguments are regular expressions that cause the
output to relate only to transactions matching those regular
expressions.  For the @command{entry} command, the arguments have a
special meaning, described below.

The regular expressions arguments always match the account name that a
transaction refers to.  To match on the payee of the entry instead,
precede the regular expression with @samp{--}.  For example, the
following balance command reports account totals for rent, food and
movies, but only those whose payee matches Freddie:

@example
ledger bal rent food movies -- freddie
@end example

There are many, many command options available with the
@command{ledger} command, and it will take a while to master them.
However, none of them are required to use the basic reporting
commands.

@menu
* Commands::                    
* Options::                     
* Format strings::              
* Value expressions::           
* Interval expressions::        
* Plotting register data::      
* Typical queries::             
* File format::                 
@end menu

@node Commands, Options, Running Ledger, Running Ledger
@section Commands

@subsection balance

The @command{balance} command reports the current balance of all
accounts.  It accepts a list of optional regexps, which confine the
balance report to the matching accounts.  If an account contains
multiple types of commodities, each commodity's total is reported
separately.

@subsection register

The @command{register} command displays all the transactions occurring in
a single account, line by line.  The account regexp must be specified
as the only argument to this command.  If any regexps occur after the
required account name, the register will contain only those
transactions that match.  Very useful for hunting down a particular
transaction.

The output from ``register'' is very close to what a typical checkbook,
or single account ledger, would look like.  It also shows a running
balance.  The final running balance of any register should always be
the same as the current balance of that account.

@subsection print

The @command{print} command prints out ledger entries just as they appear in
the original ledger.  They will be properly formatted, and output in
the most economic form possible.  The ``print'' command also takes a
list of optional regexps, which will cause only those transactions
which match in some way to be printed.

The @command{print} command can be a handy way to clean up a ledger file
whose formatting has gotten out of hand.

@subsection equity

The @command{equity} commands print out accounts balance as if they were
transactions.  This makes it easy to establish the starting balances
for an account, when @ref{Archiving previous years}.

@subsection entry

The @command{entry} commands simplifies the creation of new entries.  It
works on the principle that 80% of all transactions are variants of
earlier transactions.  Here's how it works:

Let's say you have an old transaction of the following form:

@example
2004/03/15 * Viva Italiano
    Expenses:Food                       $12.45
    Expenses:Tips                        $2.55
    Liabilities:MasterCard             $-15.00
@end example

Now it's 2004/4/9, and you've just eating at Viva Italiano again.  The
exact amounts are different, but the overall form is the same.  With
the ``entry'' command you can type:

@example
ledger entry 2004/4/9 viva food 11.00 tips 2.50
@end example

This will produce the following output:

@example
2004/04/09 Viva Italiano
    Expenses:Food                       $11.00
    Expenses:Tips                        $2.50
    Liabilities:MasterCard             $-13.50
@end example

This works by finding a transaction that matches the regexp ``viva'',
and then assuming that any accounts or amounts you specify will be the
same as that earlier transaction.  If Ledger does not succeed in
generating a new entry for you, it will print an error and set the
exit code to 1.

There is a shell script in the distribution called ``entry'', which
simplifies the task of adding a new entry to your ledger, and then
launches @command{vi} to let you confirm that the entry looks
appropriate.

Here are a few more examples of the entry command, assuming the above
journal entry:

@example
# Pay $11.00 to first transaction account (food)
ledger entry 4/9 viva 11.00

# Pay $11.00 to food from checking
ledger entry 4/9 viva 11.00 checking

# Pay DM 11.00 to dining, no matter what the entry said
ledger entry 4/9 viva dining "DM 11.00"
@end example

@node Options, Format strings, Commands, Running Ledger
@section Options

With all of the reports, command-line options are useful for modifying
the output generated.  You will often find yourselves adding option
flags to the command-line to modify those commands.

Command-line options always occur before the command word.  This is
done to distinguish them from exclusive matching expressions, which
also begin with a desh.  The basic form for most commands is:

@example
ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]]
@end example

The @var{OPTIONS} and @var{REGEXPS} expressions are optional.  You
could use just ``ledger balance'' without any options, which would
print the summarized total for all accounts.  But for more specific
reporting, or to change the appearance of the output, options are
needed.

@menu
* Basic options::               
* Report filtering::            
* Output customization::        
* Commodity reporting::         
* Environment variables::       
@end menu

@node Basic options, Report filtering, Options, Options
@subsection Basic options

These are the most basic command options.  Most likely, the user will
want to set them using @ref{Environment variables}, instead of using
actual command-line options:

@option{--help} (@option{-h}) prints a summary of all the options, and
what they are used for.  This can be a handy way to remember which
options do what.  This help screen is also printed if ledger is run
without a command.

@option{--version} (@option{-v}) prints the current version of ledger and
exits.  This is useful for sending bug reports, to let the author know
which version of ledger you are using.

@option{--init FILE} (@option{-i FILE}) causes FILE to be read by ledger before any
other ledger file.  This file may not contain any transactions, but it
may contain option settings.  To specify options in the init file, use
the same syntax as the command-line.  Here's an example init file:

@example
--price-db ~/finance/.pricedb
@end example

Option settings on the command-line or in the environment always take
precedence over settings in the init file.

@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file.  This command
may be used multiple times.  FILE may also be a list of file names
separated by colons.  Typically, the environment variable
@var{LEDGER_FILE} is set, rather than using this command-line option.

@option{--cache FILE} identifies FILE as the default binary cache file.  That
is, if the ledger files to be read are specified using the environment
variable @var{LEDGER_FILE}, then whenever a command is finished a binary
copy will be written to the specified cache, to speed up the loading
time of subsequent queries.  This filename can also be given using the
environment variable @var{LEDGER_CACHE}, or by putting the option into
your init file.

@option{--output FILE} (@option{-o FILE}) redirects output from any command to
@var{FILE}.  By default, all output goes to standard output.

@option{--set-price CONV} (@option{-z CONV}) specifies a forced
commodity conversion.  If a setting like @samp{COMM=$1.20} is used,
the commodity @var{COMM} is reported in terms of the conversion
factor.  This can be useful for performing arbitrary value
substitutions.  For example, to report dollars in terms of the ounces
of gold they would buy, use: @samp{-z "$=0.00280112 AU"} (or whatever
the current exchange rate is).

@option{--account NAME} (@option{-a NAME}) specifies the default
account which QIF file transactions are assumed to relate to.

@node Report filtering, Output customization, Basic options, Options
@subsection Report filtering

These options change which transactions affect the outcome of a
report, in ways other than just using regular expressions:

@option{--begin-date DATE} (@option{-b DATE}) constrains the report to
entries on or after @var{DATE}.  Only entries after that date will be
calculated, which means that the running total in the balance report
will always start at zero with the first matching entry.  (Note: This
is different from using @option{--display} to constrain what is
displayed).

@option{--end-date DATE} (@option{-e DATE}) contrains the report so that
entries on or after @var{DATE} are not considered.  This ending date
is not inclusive, therefore always use a date that is later than the
last entry you want to see.

@option{--current}(@option{-c}) displays only entries occurring on or
before the current date.

@option{--cleared} (@option{-C}) displays only transactions whose entry
has been marked ``cleared'' (by placing an asterix to the right of the
date).

@option{--uncleared} (@option{-U}) displays only transactions whose entry
has not been marked ``cleared'' (i.e., if there is no asterix to the
right of the date).

@option{--real} (@option{-R}) displays only real transactions, not
virtual.  (A virtual transaction is indicated by surrounding the
account name with parentheses or brackets; see the section on using
virtual transactions for more information).

@option{--related} (@option{-r}) displays transactions that are related to
whichever transactions would otherwise have matched the filtering
criteria.  In the register report, this shows where money went to, or
the account it came from.  In the balance report, it shows all the
accounts affected by entries having a related transaction.  For
example, if a file had this entry:

@example
2004/03/20 Safeway
    Expenses:Food                       $65.00
    Expenses:Cash                       $20.00
    Assets:Checking
@end example

And if the register command was:

@example
ledger -r register food
@end example

This would be the output, to show the transactions related to the
transaction that matched.

@example
2004/03/20 Safeway  Expenses:Cash    $-20.00  $-20.00
                    Assets:Checking   $85.00   $65.00
@end example

@node Output customization, Commodity reporting, Report filtering, Options
@subsection Output customization

These options affect only the output, but not which transactions are
used to create it:

@option{--date-format STR} (@option{-y STR}) changes the basic date format
used by reports.  The default uses a date like 2004/08/01, which
represents the default date format of @samp{%Y/%m/%d}.  To change the
way dates are printed in general, the easiest way is to
@option{--date-format FORMAT} to the initialize file @file{~/.ledgerc}
(or the file referred to by @var{LEDGER_INIT}).

@option{--format STR} (@option{-F STR}) sets the reporting format for
whatever report ledger is about to make.  @xref{Format strings}.

You can also set the default format for a given report type, usually
in the initialization file @file{~/.ledgerrc}, by using one of the
following options:

@table @code
@item --balance-format STR
Sets the default format for the @command{balance} report.

@item --equity-format STR
Sets the default format for the @command{equity} report.

@item --register-format STR
Sets the default format for the @command{register} report.

@item --print-format STR
Sets the default format for the @command{print} report.

@item --plot-value-format STR
Sets the default format for the @command{register} report, when @option{-j}
is being used.

@item --plot-total-format STR
Sets the default format for the @command{register} report, when @option{-J}
is being used.
@end table

@option{--empty} (@option{-E}) includes even empty accounts in the
@command{balance} report.

@option{--collapse} (@option{-n}) causes entries in a @command{register}
report with multiple transactions to be collapsed into a single,
subtotaled entry.

@option{--subtotal} (@option{-s}) causes all entries in a
@command{register} report to be collapsed into a single, subtotaled
entry.

@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing the
values determined using the value expression @var{EXPR}.  For example,
using @option{-S -AT} in the balance report will sort account balances
from greatest to least, using the absolute value of the total.  For
more on how to use value expressions, see @ref{Value expressions}.

@option{--interval STR} (@option{-p STR}) sets the reporting interval to
@var{STR}.  This will subtotal all matching entries within each
interval separately, making it easy to see weekly, monthly, quarterly,
etc., transaction totals.  An interval string can even specify the
beginning and end of the report range, using simple terms like ``last
june'' or ``next month''.  For more using interval expressions, see
@ref{Interval expressions}.

@option{--dow} reports transactions totals for each day of the week.
This is an easy way to see if weekend spending is more than on
weekdays.

@option{--weekly} (@option{-W}) reports transaction totals by the week.
The week begins on whichever day a transaction is first found, so to
start each week on a Sunday, specifying a beginning date for the
report that falls on a Sunday.  @option{--monthly} (@option{-M}) reports
transaction totals by month; @option{--yearly} (@option{-Y}) reports
transaction totals by year.  For more complex interval, using the
@option{--interval} option described above.

@option{--limit EXPR} (@option{-l EXPR}) limits which transactions take
part in the calculations of a report.

@option{--display EXPR} (@option{-d EXPR}) limits which transactions or
accounts or actually displayed in a report.  They might still be
calculated, and be part of the running total of a register report, for
example, but they will not be displayed.  This is useful for seeing
last month's checking transactions, against a running balance which
includes all transaction values:

@example
ledger -d "d>=[last month]" reg checking
@end example

The output from this command is very different from the following,
whose running total includes only transactions from the last month
onward:

@example
ledger -p "last month" reg checking
@end example

Which is more useful depends on what you're looking to know: the total
amount for the reporting range (@option{-p}), or simply a display
restricted to the reporting range (using @option{-d}).

@option{--value EXPR} (@option{-t EXPR}) changes the value expression used
to calculate the ``value'' column in the @command{register} report,
and the totals in the @command{equity} report.  @xref{Value
expressions}.

@option{--total EXPR} (@option{-T EXPR}) sets the value expression used by
the ``total'' column in the @command{register} report, and also the
@command{balance} report.

@option{--value-data} (@option{-j}) changes the @command{register} report
so that it output nothing but the date and the value column, and the
latter without commodities.  This is only meaningful if the report
uses a single commodity.  This data can then be fed to other programs,
which could plot the date, analyze it, etc.

@option{--total-data} (@option{-J}) changes the @command{register} report
so that it output nothing but the date and totals column, without
commodities.

@node Commodity reporting, Environment variables, Output customization, Options
@subsection Commodity reporting

These options affect how commodity values are displayed:

@option{--price-db FILE} (@option{-P FILE}) sets the file that is used for
recording downloaded commodity prices.  It is always read on startup,
to determine historical prices.  Other settings can be placed in this
file manually, to prevent downloading quotes for a specific, for
example.  This is done by adding a line like the following:

@example
; Don't download quotes for the dollar, or timelog values
N $
N h
@end example

@option{--download} (@option{-Q}) causes quotes to be automagically
downloaded, as needed, by running a script named @command{getquote}
and expecting that script to return a value understood by ledger.  A
sample implementation of a @command{getquote} script, implemented in
Perl, is provided in the distribution.  Downloaded quote price are
then appended to the price database, usually specified using the
environment variable @var{LEDGER_PRICE_DB}.

@option{--price-exp MINS} (@option{-L MINS}) sets the expected freshness
of price quotes, in minutes.  That is, if the last known quote for any
commodity is older than this value---and if @option{--download} is being
used---then the Internet will be consulted again for a newer price.
Otherwise, the old price is still considered to be fresh enough.

There are several different ways that ledger can report the totals it
displays.  The most flexible way to adjust them is by using value
expressions, and the @option{-t} and @option{-T} options.  However,
there are also several ``default'' reports, which will satisfy most
users basic reporting needs:

@table @code
@item --quantity
(@option{-O}) reports commodity totals (this is the default)

@item --basis
(@option{-B}) reports the cost basis for all transactions.

@item --market
(@option{-V}) reports the last known market value for all commodities.

@item --gain
(@option{-G}) reports the net gain/loss for all commodity with a price
history.

@item --average
(@option{-A}) reports the average transaction value.

@item --deviation
(@option{-D}) reports each transaction's deviation from the average.
This is only meaningful in the @command{register} report.

@item --trend
(@option{-X}) reports the basic trend of all transaction values.  This
can indicate whether spending is on the increase, or decrease, based
on the way the trend values change in the totals column of the
@command{register} report.

@item --weighted-trend
(@option{-Z}) reports the trend, like @option{--trend}, but factors in the
passage of time.  Older transactions do not swing the trend numbers as
much as recent and future transactions.  Thus, recent heavy spending
will indicate a higher trend, than if time were not considered.
@end table

@node Environment variables,  , Commodity reporting, Options
@subsection Environment variables

Every option to ledger may be set using an environment variable.  If
an option has a long name such @option{--this-option}, setting the
environment variable @var{LEDGER_THIS_OPTION} will have the same
affect as specifying that option on the command-line.  Options on the
command-line always take precedence over environment variable
settings, however.

Note that you may also permanently specify option values by placing
option settings in the file @file{~/.ledgerrc}, for example:

@example
--cache /tmp/.mycache
@end example

@node Format strings, Value expressions, Options, Running Ledger
@section Format strings

Format strings can be used to change the output format of reports.
They are specified by passing a formatting string to the
@option{--format} (@option{-F}) option.  Within that string, constructs
are allowed which make it possible to display the various parts of an
account or transaction in custom ways.

Within a format strings, a subtitution is specified using a percent
character (@samp{%}).  The basic format of all substitutions is:

@example
%[-][MIN WIDTH][.MAX WIDTH]EXPR
@end example

If the optional minus sign (@samp{-}) follows the percent character,
whatever is subtituted will be left justified.  The default is right
justified.  If a mininum width is given next, the substituted text
will be at least that wide, perhaps wider.  If a period and a maximum
width is given, the substituted text will never be wider than this,
and will be truncated to fit.  Here are some examples:

@example
%-P     An entry's payee, left justified
%20P    The same, right justified, at least 20 chars wide
%.20P   The same, no more than 20 chars wide
%-.20P  Left justified, maximum twenty chars wide
@end example

The expression following the format constraints can be a single
letter, or an expression enclosed in parentheses or brackets.  The
allowable expressions are:

@table @code
@item %
Inserts a percent sign.

@item t
Inserts the results of the value expression specified by @option{-t}.
If @option{-t} was not specified, the current report style's value
expression is used.

@item T
Inserts the results of the value expression specified by @option{-T}.
If @option{-T} was not specified, the current report style's value
expression is used.

@item |
Inserts a single space.  This is useful if a width is specified, for
inserting a certain number of spaces.

@item _
Inserts a space for each level of an account's depth.  That is, if an
account has two parents, this construct will insert two spaces.  If a
minimum width is specified, that much space is inserted for each level
of depth.  Thus @samp{%5_}, for an account with four parents, will
insert twenty spaces.

@item (EXPR)
Inserts the amount resulting from the value expression given in
parentheses.  To insert five times the total value of an account, for
example, one could say @samp{%12(5*O)}.  Note: It's important to put
the five first in that expression, so that the commodity doesn't get
stripped from the total.

@item [DATEFMT]
Inserts the result of formatting a transaction's date with a date
format string, exactly like those supported by @code{strftime}.  For
example: @samp{%[%Y/%m/%d %H:%M:%S]}.

@item D
By default, this is the same as @samp{%[%Y/%m%/d]}.  The date format
used can be changed at any time with the @option{-y} flag, however.
Using @samp{%D} gives the user more control over the way dates are
output.

@item X
If a transaction has been cleared, this inserts @samp{*} followed by a
space; otherwise nothing is inserted.

@item C
Inserts the checking number for an entry, in parentheses, followed by
a space; if none was specified, nothing is inserted.

@item P
Inserts the payee related to a transaction.

@item n
Inserts the optimal short name for an account.  This is normally used
in balance reports.  It prints a parent account's name if that name
has not been printed yet, oherwise it just prints the account's name.

@item N
Inserts the full name of an account.

@item o
Inserts the ``optimized'' form of a transaction's amount.  This is
used by the print report.  In some cases, this inserts nothing; in
others, it inserts the tranaction amount and its cost.  It's use is
not recommend unless you are modifying the print report.

@item /
The @samp{%/} construct is special.  It separates a format string
between what should be printed for the first transaction in an entry,
and what should be printed for all subsequent transactions.  If not
used, the same format string is applied to all transactions.
@end table

Here are default format strings for the balance and print reports,
just to give an example:

@example
%20T  %2_%-n\n
\n%D %X%C%P\n    %-34N  %12o\n%/    %-34N  %12o\n
@end example

@node Value expressions, Interval expressions, Format strings, Running Ledger
@section Value expressions

A value expression is a language used by ledger wherever a value is
involved.  Some examples are:

@enumerate
@item Values displayed in reports
@item Predicates, or which transactions get calculated/displayed
@item Sorting criteria, or how transactions are sorted
@item Matching criteria used by automated transactions
@end enumerate

Value expressions support most simple math and logic operators, in
addition to a set of one letter functions and variables.  A function's
argument is whatever follows it.  The following is a display predicate
that I use with the @command{balance} command:

@example
ledger -d /^Liabilities/?T<0:AT>100 balance
@end example

The effect is that account totals are displayed only if: 1) A
Liabitilies account has a total less than zero; or 2) the absolute
value of the account's total exceeds 100 units of whatever commodity
contains.  If it contains multiple commodities, only one of them must
exceed 100 units.

Display predicates are also very handy with register reports, to
constrain which entries are printed.  For example, the following
command shows only entries from the beginning of the current month,
while still calculating the running balance based on all entries:

@example
ledger -d "d>[$(date +%Y/%m/01)]" register checking
@end example

This advantage to this command's complexity is that it prints the
running total in terms of all entries in the register.  The following,
simpler command is similar, but totals only the transactions
displayed:

@example
ledger -b "this month" register checking
@end example

@subsection Variables

Below are the one letter variables available in any value expression.
For the register and print commands, these variables relate to
individual transactions, and sometimes the account affected by a
transaction.  For the balance command, these variables relate to
accounts -- often with a subtle difference in meaning.  The use of
each variable for both is specified.

@table @code
@item t
This maps to whatever the user specified with @option{-t}.  In a
register report, @option{-t} changes the value column; in a balance
report, it has no meaning by default.  If @option{-t} was not specified,
the current report style's value expression is used.

@item T
This maps to whatever the user specified with @option{-T}.  In a
register report, @option{-T} changes the totals column; in a balance
report, this is the value given for each account.  If @option{-T} was
not specified, the current report style's value expression is used.

@item m
This is always the present moment/date.
@end table

@subsubsection Transaction/account details

@table @code
@item d
A transaction's date, as the number of seconds past the epoch.  This
is always ``today'' for an account.

@item a
The transaction's amount; the balance of an account, without
considering children.

@item c
The cost of a transaction; the cost of an account, without its
children.

@item v
The market value of a transaction, or an account without its children.

@item g
The net gain (market value minus cost basis), for a transaction or an
account without its children.  It is the same as @samp{v-c}.

@item l
The depth (``level'') of an account.  If an account has one parent,
it's depth is one.

@item n
The index of a transaction, or the count of transactions affecting an
account.

@item X
1, if a transaction's entry has been cleared, 0 otherwise.

@item R
1, if a transaction is not virtual, 0 otherwise.
@end table

@subsubsection Calculated totals

@table @code
@item O
The total of all transactions seen so far, or the total of an account
and all its children.

@item N
The total count of transactions affecting an account and all its
children.

@item C
The total cost of all transactions seen so far; the total cost of an
account and all its children.

@item V
The market value of all transactions seen so far, or of an account and
all its children.

@item G
The total net gain (market value minus cost basis), for a series of
transactions, or an account and its children.  It is the same as
@samp{V-C}.
@end table

@subsection Functions

The available one letter functions are:

@table @code
@item -
Negates the argument.

@item A
The absolute value of the argument.

@item S
Strips the commodity from the argument.

@item M
The median of the argument; @samp{Mx} is the same as @samp{x/n}.

@item D
The deviation of the argument; @samp{Dx} is the same as @samp{x-x/n}.

@item P
The present market value of the argument.  The syntax @samp{P(x,d)} is
supported, which yields the market value at time @samp{d}.
@end table

@subsection Operators

The binary and ternary operators, in order of precedence, are:

@enumerate
@item @samp{* /}
@item @samp{+ -}
@item @samp{! < > =}
@item @samp{& | ?:}
@end enumerate

@subsection Complex expressions

More complicated expressions are possible using:

@table @code
@item NUM
A plain integer represents a commodity-less amount.

@item @{AMOUNT@}
An amount in braces can be any kind of amount supported by ledger,
with or without a commodity.  Use this for decimal values.

@item /REGEXP/
A regular expression that matches against an account's full name.  If
a transaction, this will match against the account affected by the
transaction.

@item //REGEXP/
A regular expression that matches against an entry's payee name.

@item ///REGEXP/
A regular expression that matches against an account's base name.  If
a transaction, this will match against the account affected by the
transaction.

@item (EXPR)
A sub-expression is nested in parenthesis.  This can be useful passing
more complicated arguments to functions, or for overriding the natural
precedence order of operators.

@item [DATE]
Useful specifying a date in plain terms.  For example, you could say
@samp{[2004/06/01]}.
@end table

@node Interval expressions, Plotting register data, Value expressions, Running Ledger
@section Interval expressions

@node Plotting register data, Typical queries, Interval expressions, Running Ledger
@section Plotting register data

@node Typical queries, File format, Plotting register data, Running Ledger
@section Typical queries

Once you have an orderly and well-organized general ledger, the next
step is to generate orderly and well-organized reports.  This is where
the Ledger command-line tool comes in.  With it, you can balance your
checkbook, see where your money is going, tell whether you've made a
profit this year, and compute the present value of your retirement
accounts.  And all with the simplest of interfaces, the command-line.

The most often used command will be the ``balance'' command:

@example
export LEDGER=/home/johnw/doc/ledger.dat
ledger balance
@end example

Here I've set my Ledger environment variable to point to where my
ledger file is hiding.  Thereafter, I needn't specify it again.

The balance command prints out the summarized balances of all my
top-level accounts, excluding sub-accounts.  In order to see the
balances for a specific account, just specify a regular expression
after the balance command:

@example
ledger balance expenses:food
@end example

This will show all the money that's been spent on food, since the
beginning of the ledger.  For food spending just this month
(September), use:

@example
ledger -d sep balance expenses:food
@end example

Or maybe I want to see all of my assets, in which case the -s (show
sub-accounts) option comes in handy:

@example
ledger balance -s
@end example

To exclude a particular account, use a regular expression with a
leading minus sign.  The following will show all expenses, but without
food spending:

@example
ledger balance expenses -food
@end example

If you want to show all accounts but for one account, remember to use
``--'' to separate the exclusion pattern from the options list:

@example
ledger balance -- -equity
@end example

@node File format,  , Typical queries, Running Ledger
@section File format

The ledger file format is quite simple, but also very flexible.  It
supports many options, though typically the user can ignore most of
them.  They are summarized below.

The initial character of each line determines what the line means, and
how it should be interpreted.  Allowable initial characters are:

@table @code
@item NUMBER
A line beginning with a number denotes an entry.  It may be followed
by any number of lines, each beginning with whitespace, to denote the
entry's account transactions.  The format of the first line is:

@example
DATE [*] [(CODE)] DESC
@end example

If @samp{*} appears after the date, it indicates that entry is
``cleared'', meaning it has been seen a bank statement, or otherwise
verified.  If a @samp{CODE} appears in parentheses, it can be used to
indicate a check number, or the type of the transaction.  Following
these is the payee, or a description of the transaction.

@item =
An automated transaction.  A value expression must appear after the
equal sign.

After this initial line there should be a set of one or more
transactions, just as if it were normal entry.  If the amounts of the
transactions have no commodity, they will be applied as modifiers to
whichever real transaction is matched by the value expression.

@item !
A line beginning with an exclamation mark denotes a command directive.
It must be immediately followed by the command word.  The supported
commands are:

@table @strong
@item include
Include the stated ledger file.

@item account
The account name is given is taken to be the parent of all
transactions that follow, until @samp{!end} is seen.

@item end
Ends an account block.

@item python
If Python support is available, all of the lines following
@samp{!python} will be passed to the Python interpretor.  Any
functions defined will be available to later Python blocks, and can be
called from a value expression.  The Python code block must be ended
with @samp{!end}.
@end table

@item ;
A line beginning with a colon indicates a comment, and is ignored.

@item (whitespace)
A line beginning with whitespace, which is not part of a regular or
automated transaction, is also ignored.

@item Y
If a line begins with a capital Y, it denotes the year used for all
subsequent entries that give a date without a year.  The year should
appear immediately after the Y, for example: @samp{Y2004}.  This is
useful at the beginning of a file, to specify the year for that file.
If all entries specify a year, however, this command has no effect.

@item P
Specifies a historical price for a commodity.  These are usually found
in a pricing history file (see the @option{-Q} option).  The syntax
is:
@example
P DATE SYMBOL PRICE
@end example

@item C
Specifies a conversion price for a commodity.  This has no reference
to time, and takes precedence over all historical prices (even the
current prices).  Syntax is:
@example
C SYMBOL PRICE
@end example

@item N SYMBOL
Indicates that pricing information is to be ignored for a given
symbol, nor will quotes ever be downloaded for that symbol.  Useful
with a home currency, such as the dollar ($).  It is recommended that
these pricing options be set in the price database file, which
defaults to @file{~/.pricedb}.  The syntax for this command is:
@example
N SYMBOL
@end example

@item i, o, b, h
These four options relate to timeclock support, which permits ledger
to read timelog files.  See the timeclock's documentation for more
info on the syntax of its timelog files.
@end table

@node Keeping a ledger, Extending with Python, Running Ledger, Top
@chapter Keeping a ledger

The most important part of accounting is keeping a good ledger.  If
you have a good ledger, tools can be written to work whatever
mathematically tricks you need to better understand your spending
patterns.  Without a good ledger, no tool, however smart, can help
you.

The Ledger program aims at making ledger entry as simple as possible.
Since it is a command-line tool, it does not provide a user interface
for keeping a ledger.  If you like, you may use GnuCash to maintain
your ledger, in which case the Ledger program will read GnuCash's data
files directly.  In that case, read the GnuCash manual now, and skip
to the next chapter.

If you are not using GnuCash, but a text editor to maintain your
ledger, read on.  Ledger has been designed to make data entry as
simple as possible, by keeping the ledger format easy, and also by
automagically determining as much information as possible based on the
nature of your entries.

For example, you do not need to tell Ledger about the accounts you
use.  Any time Ledger sees a transaction involving an account it knows
nothing about, it will create it.  If you use a commodity that is new
to Ledger, it will create that commodity, and determine its display
characteristics (placement of the symbol before or after the amount,
display precision, etc) based on how you used the commodity in the
transaction.

Here is the Pacific Bell example from above, given as a Ledger
transaction:

@example
9/29  (100)  Pacific Bell
    Expenses:Utilities:Telephone               $23.00
    Assets:Checking                           $-23.00
@end example

As you can see, it is very similar to what would be written on paper,
minus the computed balance totals, and adding in account names that
work better with Ledger's scheme of things.  In fact, since Ledger is
smart about many things, you don't need to specify the balanced
amount, if it is the same as the first line:

@example
9/29  (100)  Pacific Bell
    Expenses:Utilities:Telephone               $23.00
    Assets:Checking
@end example

For this entry, Ledger will figure out that $-23.00 must come from
``Assets:Checking'' in order to balance the entry.

@menu
* Stating where money goes::    
* Assets and Liabilities::      
* Commodities and Currencies::  
* Accounts and Inventories::    
* Understanding Equity::        
* Dealing with Petty Cash::     
* Archiving previous years::    
* Virtual transactions::        
* Automated transactions::      
* Differences with accounting conventions::  
* Using Emacs to Keep Your Ledger::  
* Using GnuCash to Keep Your Ledger::  
* Using timeclock to record billable time::  
@end menu

@node Stating where money goes, Assets and Liabilities, Keeping a ledger, Keeping a ledger
@section Stating where money goes

Accountants will talk of `credits' and `debits', but their meaning is
often different from the layman's definitions.  To avoid this semantic
overloading, we will refer to subtractions and additions.
@xref{Differences with accounting conventions}, for more on how to
reconcile the two systems.

Recall that every transaction will involve two or more accounts.
Money is transferred from one group of accounts to another group.  To
record the transaction, @emph{subtract} an amount from the source
accounts, and @emph{add} the same amount to the target accounts.

In order to write the Ledger entry correctly, you must determine where
the money comes from, and where it goes to.  For example, when you are
paid, in order to add to your bank account, you must subtract from an
income account:

@example
9/29  My Employer
    Assets:Checking                           $500.00
    Income:Salary                            $-500.00
@end example

But wait, you say, why is the Income a negative figure?  And when you
look at the balance totals for your ledger, you will certainly be
surprised to see Expenses as a positive figure, and Income as a
negative figure.  Isn't that the opposite of how it should look?

It may take getting used to, but to properly use a general ledger you
will need to think in terms of money flows.  Rather than Ledger
``fixing'' the minus signs, let's understand why they are there.

When you earn money, the money has to come from somewhere.  Let's call
that somewhere ``society''.  In order for society to give you an
income, you must take money away (withdraw) from society in order to
put it into (make a payment to) your bank.  When you then spend that
money, it leaves your bank account (a withdrawal) and goes back to
society (a payment).  This is why Income will appear negative---it
reflects the money you have drawn from society---and why Expenses will
be positive---it is the amount you've given back.  These additions and
subtractions will always cancel each other out in the end, because you
don't have the ability to create new money: it must always come from
somewhere, and in the end must always leave.  This is the beginning of
economy, after which the explanation gets terribly difficult.

Based on that explanation, here's another way to look at your balance
report: every negative figure means that that account or person or
place has less money now than when you started your ledger; and every
positive figure means that that account or person or place has more
money now that when you started your ledger.  Make sense?

@node Assets and Liabilities, Commodities and Currencies, Stating where money goes, Keeping a ledger
@section Assets and Liabilities

Assets are money that you have, and Liabilities are money that you
owe.  ``Liabilities'' is just a more inclusive name for Debts.

An Asset is typically increased by transferring money from an Income
account, such as when you get paid.  Here is a typical entry:

@example
2004/09/29  My Employer
    Assets:Checking               $500.00
    Income:Salary
@end example

Money, here, is coming from an Income account belonging to ``My
Employer'', and is being transferred to an account that belongs to you.
The money is now yours, which makes it an asset.

Liability accounts track money you owe to others.  They come into play
whenever you borrow money to buy something, or if you owe someone
money.  The usual way a liability is changed is by expending money,
thus transferring it to an Expenses account.  For example:

@example
2004/09/30  Restaurant
    Expenses:Dining                $25.00
    Liabilities:MasterCard
@end example

Your account balance will now show $25 spent on Dining, and a
corresponding $25 owed on your MasterCard.  The MasterCard liability
will show up as negative, since it offsets the value of your assets.
@emph{The combined total of your Assets and Liabilities is your net
worth}.  To see your current net worth, use this command:

@example
$ ledger balance ^assets ^liabilities
@end example

Relatedly, your Income accounts will show up negative, because they
transfer money @emph{from} an account in order to increase your
assets.  Your Expenses accounts will show up positive, because that is
where the money went.  The combined total your Income and Expenses is
your cash flow.  A negative cash flow means that you are spending more
cash than you make.  To see your current cash flow, use this command:

@example
$ ledger balance ^income ^expenses
@end example

Often, it is only important to view your income and expenses when
asking questions like, ``Where did my money go?  Am I spending too
much on X?  Am I making enough to cover my expenses?''  But most of
the time, you will usually want to ask other questions like, ``Is
there enough money in my checking account to cover my next credit card
bill?''  For these reasons, I recommend creating a script that removes
Income, Expenses, and Equity by default from your basic balance
report.  The provided script ``bal'' does this for you, as well as
making it easier to run the balance command:

@example
$ bal
@end example

To use this script, it must be copied from the @strong{scripts}
directory in the ledger distribution, to a directory along your
@var{PATH}.  Also, you must set the environment variable @var{LEDGER}
to point to your main ledger file.

Another common question to ask of your expenses is: How much do I
spend each month on X?  Ledger provides a simple way of displaying
monthly totals for any account.  Here is an example that summarizes
monthly automobile expenses:

@example
$ ledger -M register expenses:auto
@end example

This assumes, of course, that you use account names like
@samp{Expenses:Auto:Gas} and @samp{Expenses:Auto:Repair}.

@menu
* Tracking reimbursable expenses::  
@end menu

@node Tracking reimbursable expenses,  , Assets and Liabilities, Assets and Liabilities
@subsection Tracking reimbursable expenses

Sometimes you will want to spend money on behalf of someone else,
which will eventually get repaid.  Since the money is still ``yours'',
it is really an asset.  And since the expenditure was for someone
else, you don't want it contaminating your Expenses reports.  You will
need to keep an account for tracking reimbursements.

This is fairly easy to do in ledger.  When spending the money, spend
it @emph{to} your Assets:Reimbursements, using a different account for
each person or business that you spend money for.  For example:

@example
2004/09/29  Circuit City
    Assets:Reimbursements:Company XYZ     $100.00
    Liabilities:MasterCard
@end example

This shows that you spent $100.00 on your MasterCard at Circuit City,
but that the expense was made on behalf of Company XYZ.  Later, when
Company XYZ pays you back, you will transfer the money from your
reimbursement account to a regular asset account:

@example
2004/09/29  Company XYZ
    Assets:Checking                       $100.00
    Assets:Reimbursements:Company XYZ
@end example

This deposits the money owed from Company XYZ into your checking
account, presumably because they paid you back with a check.

But what to do if you run your own business, and you want to keep
track of expenses made on your own behalf, while still tracking
everything in a single ledger file?  This is more complex, because you
need to track two separate things: 1) The fact that the money should
be reimbursed to you, and 2) What the expense account was, so that you
can later determine where your company is spending its money.

This kind of transaction is best handled with mirrored transactions in
two different files, one for your personal accounts, and one for your
company accounts.  But keeping them in one file involves the same
kinds of transactions, so those are what is shown here.  First, the
personal entry, which shows the need for reimbursement:

@example
2004/09/29  Circuit City
    Assets:Reimbursements:Company XYZ     $100.00
    Liabilities:MasterCard
@end example

This is the same as above, except that you own Company XYZ, and are
keeping track of its expenses in the same ledger file.  This entry
should be immediately followed by an equivalent entry, which shows the
kind of expense, and also notes the fact that $100.00 is now payable
to you:

@example
2004/09/29  Circuit City
    Company XYZ:Expenses:Computer:Software      $100.00
    Company XYZ:Accounts Payable:Your Name
@end example

This second entry shows that Company XYZ has just spent $100.00 on
software, and that this $100.00 came from Your Name, which must be
paid back.

These two entries can also be merged, to make things a little clearer.
Note that all amounts must be specified now:

@example
2004/09/29  Circuit City
    Assets:Reimbursements:Company XYZ         $100.00
    Liabilities:MasterCard                   $-100.00
    Company XYZ:Expenses:Computer:Software    $100.00
    Company XYZ:Accounts Payable:Your Name   $-100.00
@end example

To ``pay back'' the reimbursement, just reverse the order of everything,
except this time drawing the money from a company asset, paying it to
accounts payable, and then drawing it again from the reimbursement
account, and paying it to your personal asset account.  It's easier
shown than said:

@example
2004/10/15  Company XYZ
    Assets:Checking                           $100.00
    Assets:Reimbursements:Company XYZ        $-100.00
    Company XYZ:Accounts Payable:Your Name    $100.00
    Company XYZ:Assets:Checking              $-100.00
@end example

And now the reimbursements account is paid off, accounts payable is
paid off, and $100.00 has been effectively transferred from the
company's checking account to your personal checking account.  The
money simply ``waited''---in both @samp{Assets:Reimbursements:Company
XYZ}, and @samp{Company XYZ:Accounts Payable:Your Name}---until such
time as it could be paid off.

The value of tracking expenses from both sides like that is that you
do not contaminate your personal expense report with expenses made on
behalf of others, while at the same time making it possible to
generate accurate reports of your company's expenditures.  It is more
verbose than just paying for things with your personal assets, but it
gives you a very accurate information trail.

The advantage to keep these doubled entries together is that they
always stay in sync.  The advantage to keeping them apart is that it
clarifies the transfer's point of view.  To keep the transactions in
separate files, just separate the two entries that were joined above.
For example, for both the expense and the pay-back shown above, the
following four entries would be created.  Two in your personal ledger
file:

@example
2004/09/29  Circuit City
    Assets:Reimbursements:Company XYZ     $100.00
    Liabilities:MasterCard               $-100.00

2004/10/15  Company XYZ
    Assets:Checking                       $100.00
    Assets:Reimbursements:Company XYZ    $-100.00
@end example

And two in your company ledger file:

@example
!account Company XYZ

2004/09/29  Circuit City
    Expenses:Computer:Software            $100.00
    Accounts Payable:Your Name           $-100.00

2004/10/15  Company XYZ
    Accounts Payable:Your Name            $100.00
    Assets:Checking                      $-100.00

!end
@end example

(Note: The @ above command means that all accounts mentioned in the
file are children of the specified account.  In this case it means
that all activity in file relates to Company XYZ).

After creating these entries, you will always know that $100.00 was
spent using your MasterCard on behalf of Company XYZ, and that Company
XYZ spent the money on computer software and paid it back about two
weeks later.

@node Commodities and Currencies, Accounts and Inventories, Assets and Liabilities, Keeping a ledger
@section Commodities and Currencies

Ledger makes no assumptions about the commodities you use; it only
requires that you specify a commodity.  The commodity may be any
non-numeric string that does not contain a period, comma, forward
slash or at-sign.  It may appear before or after the amount, although
it is assumed that symbols appearing before the amount refer to
currencies, while non-joined symbols appearing after the amount refer
to commodities.  Here are some valid currency and commodity
specifiers:

@example
$20.00         ; currency: twenty US dollars
40 AAPL        ; commodity: 40 shares of Apple stock
60 DM          ; currency: 60 Deutsch Mark
£50            ; currency: 50 British pounds
50e            ; currency: 50 Euros (use appropriate symbol)
@end example

Ledger will examine the first use of any commodity to determine how
that commodity should be printed on reports.  It pays attention to
whether the name of commodity was separated from the amount, whether
it came before or after, the precision used in specifying the amount,
whether thousand marks were used, etc.  This is done so that printing
the commodity looks the same as the way you use it.

An account may contain multiple commodities, in which case it will
have separate totals for each.  For example, if your brokerage account
contains both cash, gold, and several stock quantities, the balance
might look like:

@example
  $200.00
100.00 AU
  AAPL 40
 BORL 100
 FEQTX 50  Assets:Brokerage
@end example

This balance report shows how much of each commodity is in your
brokerage account.

Sometimes, you will want to know the current street value of your
balance, and not the commodity totals.  For this to happen, you must
specify what the current price is for each commodity.  The price can
be in any commodity, in which case the balance will be computed in
terms of that commodity.  The usual way to specify prices is with a
file of price settings, which might look like this:

@example
AU=$357.00
AAPL=$37
BORL=$19
FEQTX=$32
@end example

Specify the prices file using the @option{-p} option:

@example
ledger -p prices.db balance brokerage
@end example

Now the balance for your brokerage account will be given in US
dollars, since the prices database has specified conversion factors
from each commodity into dollars:

@example
$40880.00  Assets:Brokerage
@end example

You can convert from any commodity to any other commodity.  Let's say
you had $5000 in your checking account, and for whatever reason you
wanted to know many ounces of gold that would buy.  If gold is
currently $357 per ounce, then each dollar is worth 1/357 AU:

@example
ledger -p "$=0.00280112 AU" balance checking
@end example

@example
14.01 AU  Assets:Checking
@end example

$5000 would buy 14 ounces of gold, which becomes the new display
commodity since a conversion factor was provided.

Commodities conversions can also be chained, up to a depth of 10.
Here is a sample prices database that uses chaining:

@example
AAPL=$15
$=0.00280112 AU
AU=300 Euro
Euro=MD 0.75
@end example

This is a roundabout way of reporting AAPL shares in their Deutsch
Mark equivalent.

@menu
* Commodity price histories::   
@end menu

@node Commodity price histories,  , Commodities and Currencies, Commodities and Currencies
@subsection Commodity price histories

Whenever a commodity is purchased using a different commodity (such as
a share of common stock using dollars), it establishes a price for
that commodity on that day.  It is also possible, by recording price
details in a ledger file, to specify other prices for commodities at
any given time.  Such price entries might look like those below:

@example
P 2004/06/21 02:17:58 TWCUX $27.76
P 2004/06/21 02:17:59 AGTHX $25.41
P 2004/06/21 02:18:00 OPTFX $39.31
P 2004/06/21 02:18:01 FEQTX $22.49
P 2004/06/21 02:18:02 AAPL $32.91
@end example

By default, ledger will not consider commodity prices when generating
its various reports.  It will always report balances in terms of the
commodity total, rather than the current value of those commodities.
To enable pricing reports, several options are possible:

@table @code
@item @strong{-P FILE}
With this option, or if the environment variable @var{PRICE_HIST} is
set, pricing information obtained from the Internet will be kept in
this file.  Also, this file will be read after all other ledger files
are read, so that full history information is available for reports.

@item @strong{-O}
Report commodity totals only, not their market value or basis cost.

@item @strong{-V}
Report commodity values in terms of their last known market price.

@item @strong{-B}
Report commodities in terms of their ``basis cost'', or what they cost
at time of purchase.  Thus, totals in the register and balance
report reflect the total amount spent.

@item @strong{-G}
Report commodities in terms of their net gain, which is: the market
value minus the cost basis.  A balance report using this option
shows very quickly the performance of investments.

@item @strong{-Q}
When needed (see the @option{-L} option) pricing quotes are obtained by
calling the script @command{getquote} (a sample Perl script is
provided, but the interface is kept simple so replacements may be
made).

@item @strong{-L MINS}
When using the @option{-Q} flag, new quotes are obtained only if current
pricing data is older than MINS minutes.  The default is one day,
or 1440 minutes.

@item @strong{-p ARG}
If a string, such as ``COMM=$1.20'', the commodity COMM will be
reported only in terms of the conversion factor, which supersedes
all other pricing histories for that commodity.  This can be used to
perform arbitrary value substitutions.  For example, to report the
value of your dollars in terms of the ounces of gold they would buy,
use: -p ``$=0.00280112 AU'' (or whatever the current exchange rate
is).

@end table

Note that the @option{-B}, @option{-O}, @option{-V}, and @option{-G} are mutually exclusive.

@node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Keeping a ledger
@section Accounts and Inventories

Since Ledger's accounts and commodity system is so flexible, you can
have accounts that don't really exist, and use commodities that no one
else recognizes.  For example, let's say you are buying and selling
various items in EverQuest, and want to keep track of them using a
ledger.  Just add items of whatever quantity you wish into your
EverQuest account:

@example
9/29  Get some stuff at the Inn
    Places:Black's Tavern                   -3 Apples
    Places:Black's Tavern                   -5 Steaks
    EverQuest:Inventory
@end example

Now your EverQuest:Inventory has 3 apples and 5 steaks in it.  The
amounts are negative, because you are taking @emph{from} Black's Tavern in
order to add to your Inventory account.  Note that you don't have to
use ``Places:Black's Tavern'' as the source account.  You could use
``EverQuest:System'' to represent the fact that you acquired them
online.  The only purpose for choosing one kind of source account over
another is for generate more informative reports later on.  The more
you know, the better analysis you can perform.

If you later sell some of these items to another player, the entry
would look like:

@example
10/2  Strum Brightblade
    EverQuest:Inventory                     -2 Steaks
    EverQuest:Inventory                     15 Gold
@end example

Now you've turned 2 steaks into 15 gold, courtesy of your customer,
Strum Brightblade.

@node Understanding Equity, Dealing with Petty Cash, Accounts and Inventories, Keeping a ledger
@section Understanding Equity

The most confusing entry in any ledger will be your equity account---
because starting balances can't come out of nowhere.

When you first start your ledger, you will likely already have money
in some of your accounts.  Let's say there's $100 in your checking
account; then add an entry to your ledger to reflect this amount.
Where will money come from?  The answer: your equity.

@example
10/2  Opening Balance
    Assets:Checking                         $100.00
    Equity:Opening Balances
@end example

But what is equity?  You may have heard of equity when people talked
about house mortgages, as ``the part of the house that you own''.
Basically, equity is like the value of something.  If you own a car
worth $5000, then you have $5000 in equity in that car.  In order to
turn that car (a commodity) into a cash flow, or a credit to your bank
account, you will have to debit the equity by selling it.

When you start a ledger, you are probably already worth something.
Your net worth is your current equity.  By transferring the money in
the ledger from your equity to your bank accounts, you are crediting
the ledger account based on your prior equity value.  That is why,
when you look at the balance report, you will see a large negative
number for Equity that never changes: Because that is what you were
worth (what you debited from yourself in order to start the ledger)
before the money started moving around.  If the total positive value
of your assets is greater than the absolute value of your starting
equity, it means you are making money.

Clear as mud?  Keep thinking about it.  Until you figure it out, put
``@samp{-- -Equity}'' at the end of your balance command, to remove the
confusing figure from the totals.

@node Dealing with Petty Cash, Archiving previous years, Understanding Equity, Keeping a ledger
@section Dealing with Petty Cash

Something that stops many people from keeping a ledger at all is the
insanity of tracking small cash expenses.  They rarely generate a
receipt, and there are often a lot of small transactions, rather than
a few large ones, as with checks.

One solution is: don't bother.  Move your spending to a debit card,
but in general ignore cash.  Once you withdraw it from the ATM, mark
it as already spent to an ``Expenses:Cash'' category:

@example
2004/03/15 ATM
    Expenses:Cash                      $100.00
    Assets:Checking
@end example

If at some point you make a large cash expense that you want to track,
just ``move'' the amount of the expense from ``Expenses:Cash'' into the
target account:

@example
2004/03/20 Somebody
    Expenses:Food                       $65.00
    Expenses:Cash
@end example

This way, you can still track large cash expenses, while ignoring all
of the smaller ones.

@node Archiving previous years, Virtual transactions, Dealing with Petty Cash, Keeping a ledger
@section Archiving previous years

After a while, your ledger can get to be pretty large.  While this
will not slow down the ledger program much---it's designed to process
ledger files very quickly---things can start to feel ``messy''; and
it's a universal complaint that when finances feel messy, people avoid
them.

Thus, archiving the data from previous years into their own files can
offer a sense of completion, and freedom from the past.  But how to
best accomplish this with the ledger program?  There are two commands
that make it very simple: ``print'', and ``equity''.

Let's take an example file, with data ranging from year 2000 until
2004.  We want to archive years 2000 and 2001 to their own file,
leaving just 2003 and 2004 in the current file.  So, use ``print'' to
output all the earlier entries to a file called @file{ledger-old.dat}.
(Keeping in mind that the ending date is not inclusive, which is why
2002 is mentioned in the following command):

@example
$ ledger -f ledger.dat -b 2000/1/1 -e 2002/1/1 print \
    > ledger-old.dat
@end example

To delete older data from the current ledger file, use ``print'' again,
this time specifying year 2002 as the starting date:

@example
$ ledger -f ledger.dat -b 2002/1/1 print > x
$ mv x ledger.dat
@end example

However, now the current file contains @emph{only} transactions from 2002
onward, which will not yield accurate present-day balances, because
the net income from previous years is no longer being tallied.  To
compensate for this, we must append an equity report for the old
ledger at the beginning of the new one:

@example
$ ledger -f ledger-old.dat equity > equity.dat
$ cat equity.dat ledger.dat > x
$ mv x ledger.dat
$ rm equity.dat
@end example

Now the balances reported from @file{ledger.dat} are identical to what
they were before the data was split.

How often should you split your ledger?  You never need to, if you
don't want to.  Even eighty years of data will not slow down ledger
much---and that's just using present day hardware!  Or, you can keep
the previous and current year in one file, and each year before that
in its own file.  It's really up to you, and how you want to organize
your finances.  For those who also keep an accurate paper trail, it
might be useful to archive the older years to their own files, then
burn those files to a CD to keep with the paper records---along with
any electronic statements received during the year.  In the arena of
organization, just keep in mind this maxim: Do whatever keeps you
doing it.

@node Virtual transactions, Automated transactions, Archiving previous years, Keeping a ledger
@section Virtual transactions

A virtual transaction is when you, in your mind, see money as moving
to a certain place, when in reality that money has not moved at all.
There are several scenarios in which this type of tracking comes in
handy, and each of them will be discussed in detail.

To enter a virtual transaction, surround the account name in
parentheses.  This form of usage does not need to balance.  However,
if you want to ensure the virtual transaction balances with other
virtual transactions in the same entry, use square brackets.  For
example:

@example
10/2  Paycheck
    Assets:Checking                        $1000.00
    Income:Salary                         $-1000.00
    (Debt:Alimony)                          $200.00
@end example

In this example, after receiving a paycheck an alimony debt is
increased---even though no money has moved around yet.

@example
10/2  Paycheck
    Assets:Checking                        $1000.00
    Income:Salary                         $-1000.00
    [Savings:Trip]                          $200.00
    [Assets:Checking]                      $-200.00
@end example

In this example, $200 has been deducted from checking toward savings
for a trip.  It will appear as though the money has been moved from
the account into ``Savings:Trip'', although no money has actually moved
anywhere.

When balances are displayed, virtual transactions will be factored in.
To view balances without any virtual balances factored in, using the
``-R'' flag, for ``Reality''.

Write about: Saving for a Special Occasion; Keeping a Budget; Tracking
Allocated Funds.

@node Automated transactions, Differences with accounting conventions, Virtual transactions, Keeping a ledger
@section Automated transactions

As a Bahá'í, I need to compute Huqúqu'lláh as I acquire assets.  It is
similar to tithing for Jews and Christians, and to Zakát for Muslims.
The exact details of computing Huqúqu'lláh are a bit complex, but if
you have further interest, please consult the Web.

Ledger makes this otherwise difficult calculation quite easy.  Just
set up the following automated transaction at the top of your ledger
file:

@example
; These entries will compute Huqúqu'lláh based on the
; contents of the ledger.

= ^Income:
= ^Expenses:Rent$
= ^Expenses:Furnishings
= ^Expenses:Business
= ^Expenses:Taxes
= ^Expenses:Insurance
  (Liabilities:Huqúqu'lláh)               0.19
@end example

This automated transaction works by looking at each transaction
appearing afterward in the ledger file.  If any match the account
regexps, occurring after the equal signs above, 19% of the value of
that transaction is applied to the ``Liabilities:Huqúqu'lláh''
account.  So if $1000 is earned through Income:Salary, which is seen
as a debit from Income, a debit of $190 is applied to
``Liabilities:Huqúqu'lláh''; if $1000 is spent on Rent---seen as a
credit to the Expense account---a credit of $190 is applied to
Huqúqu'lláh.  The ultimate balance of Huqúqu'lláh reflects how much
must be paid to that account in order to balance it to zero.

When you're ready to pay, just write a check directly to the account
``Liabilities:Huqúqu'lláh'':

@example
2003/01/01 (101) Baha'i Huqúqu'lláh Trust
    Liabilities:Huqúqu'lláh          $1,000.00
    Assets:Checking
@end example

That's it.  To see how much Huqúq is currently owed based on your
ledger entries, use:

@example
ledger balance Liabilities:Huqúq
@end example


@node Differences with accounting conventions, Using Emacs to Keep Your Ledger, Automated transactions, Keeping a ledger
@section Differences with accounting conventions
If you are an accountant, or you are familiar with accounting
terminology, then you might be tearing your hair out after reading the
above.  Please don't!

Ledger is intended to make people comfortable with their finances; to
help them better control the flow of their money.  Contemporary
accounting practices, on the other hand, often seem counter-intuitive
and confusing to the layman.  To make Ledger more accessible, it
avoids the use of standard accounting conventions and terminology.
However, Ledger is flexible enough that you may interpret what is
happening however you wish.

Most probably, the following section will confuse you, and you should
skip it if you've managed to understand everything so far.  However,
if you intend to communicate your accounting practices to a
professional accountant, the following explanations may be useful.

@table @strong
@item The entity
The individual or organisation under consideration: the someone or
something on whose behalf you are accounting.  Probably you.

@item Assets
Future economic benefits controlled by the entity as a result of a
past transaction or event.

@item Liabilities
Future sacrifices of economic benefits that the entity is obliged to
make as a result of a past transaction or event.

@end table

The format of the data files used by Ledger is more akin to a general
journal than a ledger.  In an accounting ledger, transactions are
grouped by account.  In a general journal, transactions are commonly
listed in chronological order.

Often ``cash'' is used to refer to a liquid savings account at a bank,
rather than the physical notes and coins you may withdraw.

In general, an ``addition'' in Ledger is an accounting debit, and a
``subtraction'' in Ledger is an accounting credit.  The following table
shows the ``normal'' balances for the different types of accounts.
Accountants avoid using negative balances where possible, instead
prefering a positive amount in ``credit'' balance.

@multitable @columnfractions 0.2 0.2 0.2 0.2 0.2
@item System @tab Asset @tab Liability @tab Income @tab Expense
@item @strong{Accounting} @tab debit @tab credit @tab credit @tab debit
@item @strong{Ledger} @tab positive @tab negative @tab negative @tab positive
@end multitable

That's correct: accountants call an addition to their cash a debit!
However, from the bank's perspective it is a credit: the accountant's
cash is a liability for the bank.  Consequently, payments to the
account will show up as credits on his bank statement.

@node Using Emacs to Keep Your Ledger, Using GnuCash to Keep Your Ledger, Differences with accounting conventions, Keeping a ledger
@section Using Emacs to Keep Your Ledger

In the Ledger tarball is an Emacs module, @file{ledger.el}.  This module
makes the process of keeping a text ledger much easier for Emacs
users.  I recommend putting this at the top of your ledger file:

@example
; -*-ledger-*-
@end example

And this in your @file{.emacs} file, after copying @file{ledger.el} to your
site-lisp directory:

@example
(load "ledger")
@end example

Now when you edit your ledger file, it will be in @command{ledger-mode}.
@command{ledger-mode} adds the following commands:

@table @strong
@item C-c C-a
For quickly adding new entries based on the form of older ones
(see previous section).

@item C-c C-c
Toggles the ``cleared'' flag of the transaction under point.

@item C-c C-r
Reconciles an account by displaying the transactions in another
buffer, where simply hitting the spacebar will toggle the cleared
flag of the transaction in the ledger.  It also displays the current
cleared balance for the account in the modeline.

@end table

@node Using GnuCash to Keep Your Ledger, Using timeclock to record billable time, Using Emacs to Keep Your Ledger, Keeping a ledger
@section Using GnuCash to Keep Your Ledger

The Ledger tool is fast and simple, but it offers no custom method for
actually editing the ledger.  It assumes you know how to use a text
editor, and like doing so.  Perhaps an Emacs mode will appear someday
soon to make editing Ledger's data files much easier.

Until then, you are free to use GnuCash to maintain your ledger, and
the Ledger program for querying and reporting on the contents
of that ledger.  It takes a little longer to parse the XML data format
that GnuCash uses, but the end result is identical.

Then again, why would anyone use a Gnome-centric, 35 megabyte behemoth
to edit their data, and a 65 kilobyte binary to query it...

@node Using timeclock to record billable time,  , Using GnuCash to Keep Your Ledger, Keeping a ledger
@section Using timeclock to record billable time

The timeclock tool makes it easy to track time events, like clocking
into and out of a particular job.  These events accumulate in a
timelog file.

Each in/out event may have an optional description.  If the ``in''
description is a ledger account name, these in/out pairs may be viewed
as virtual transactions, adding time commodities (hours) to that
account.

For example, the command-line version of the timeclock tool (which is
written in Python) could be used to begin a timelog file like:

@example
$ export TIMELOG=$HOME/.timelog
$ ti ClientOne  category
$ sleep 10
$ to waited for ten seconds
@end example

The @strong{.timelog} file now contains:

@example
i 2004/10/06 15:21:00 ClientOne  category
o 2004/10/06 15:21:10 waited for ten seconds
@end example

Ledger can parse this directly, as if it had seen the following ledger
entry:

@example
2004/10/06 category
    (ClientOne)      0.00277h
@end example

In other words, the timelog event pair is seen as adding 0.00277h (ten
seconds) worth of time to the ClientOne account.  This would be
considered billable time, which later could be invoiced and credited
to accounts receivable:

@example
2004/11/01 (INV#1) ClientOne, Inc.
    Receivable:ClientOne       $0.10
    ClientOne              -0.00277h @@ $35.00
@end example

The above transaction converts the clocked time into an invoice for
the time spent, at an hourly rate of $35.  Once the invoice is paid,
the money is deposited from the receivable account into a checking
account:

@example
2004/12/01 ClientOne, Inc.
    Assets:Checking            $0.10
    Receivable:ClientOne
@end example

And now the time spent has been turned into hard cash in the checking
account.

The advantage to using timeclock and invoicing to bill time is that
you will always know, by looking at the balance report, exactly how
much unbilled and unpaid time you've spent working for any particular
client.

I like to @samp{!include} my timelog at the top of my company's accounting
ledger, with the attached prefix ``Billable'':

@example
; -*-ledger-*-

; This is the ledger file for my company.  But first, include the
; timelog data, entering all of the time events within the umbrella
; account "Billable".

!include /home/johnw/.timelog Billable

; Here follows this fiscal year's transactions for the company.

2004/11/01 (INV#1) ClientOne, Inc.
    Receivable:ClientOne           $0.10
    Billable:ClientOne         -0.00277h @@ $35.00

2004/12/01 ClientOne, Inc.
    Assets:Checking                $0.10
    Receivable:ClientOne
@end example

@node Extending with Python,  , Keeping a ledger, Top
@chapter Extending with Python

Ledger fully supports Python as an extension language.  It may be used
in a few different forms, which fall into three basic categories:

@enumerate
@item
Defining Python functions to use in value expressions
@item
Using the ledger library as a Python module
@item
Setting up custom initialization using Python
@end enumerate

Note that this feature, while functional, is still under development.
It will not be documented until it has been fully proven, probably in
the next version of ledger.  For now, if you wish to make this of this
functionality and are willing to debug problems that come up, pass the
option @samp{--enable-python} to configure, and contact the author via
email.

Below is a quick example of text that could be pasted into a ledger
file to generate a customized amount column in the register report.
It does nothing more than add $100 to each transaction's amount, but
it demonstrates the potential for more complex extensions:

@example
!python
from ledger import *
def foo(d, val):
    return d.xact.amount + val
!end

--amount-expr 'foo'@{$100@}
@end example

@contents
@bye