ledger/doc/Ledger3.texi

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

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

@dircategory User Applications
@copying
Copyright (c) 2003-2010, John Wiegley.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

- Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

- Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.

- Neither the name of New Artisans LLC nor the names of its
  contributors may be used to endorse or promote products derived from
  this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@end copying

@documentencoding UTF-8

@iftex
@finalout
@end iftex

@macro ledgerprog
  @sc{ledger}
@end macro


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

@direntry
* Ledger: (ledger).           Command-Line Accounting
@end direntry

@contents

@ifnottex
@node Top, Copying, (dir), (dir)
@top Overview
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.
@c @insertcopying
@end ifnottex

@menu
* Copying::                     
* Introduction to Ledger::      
* Principles of Accounting::    
* Keeping a Journal::           
* Command-line Syntax::         
* Basic Reporting Commands::    
* Value Expressions::           
* Format Strings::              
* Journal File Format::         
* Extending with Python::       
@end menu

@node Copying, Introduction to Ledger, Top, Top
@chapter Copying
@insertcopying

@node Introduction to Ledger, Principles of Accounting, Copying, Top
@chapter Introduction to Ledger

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 journal 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 journal.  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 journal,
so we'll describe double-entry accounting in terms of that.

A checkbook journal 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 journal is to
know how much money is available to spend.  That's really the aim of
all journals.

What computers add is the ability to walk through these postings,
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 journal, 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 journal, is a journal that keeps track
of all your accounts, not just checking.  In such a journal, you record
not only who gets paid---in the case of a debit---but where the money
came from.  In a checkbook journal, its assumed that all the money
comes from your checking account.  But in a general journal, you write
posting 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 journal 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 journal for both.  In this general
journal you need to record a payment to Pacific Bell for your monthly
phone bill, and a transfer (via check) from your brokerage account to
your checking account.  The Pacific Bell bill is $23.00, let's say, and
you want to pay it from your checking account.  In the general journal
you need to say where the money came from, in addition to where it's
going to.  These transactions might look like this:

@smallexample
9/29        Pacific Bell                $23.00     $23.00
            Checking                   $-23.00          0
9/30        Checking                   $100.00    $100.00
      (123) Brokerage                 $-100.00          0
@end smallexample

The posting must balance to $0: $23 went to Pacific Bell, $23 came from
Checking.  The next entry shows check number 123 written against your
brokerage account, transfering money to your checking account.  There is
nothing left over to be accounted for, since the money has simply moved
from one account to another in both cases.  This is the basis of
double-entry accounting: money never pops in or out of existence; it is
always a posting from one account to another.

Keeping a general journal is the same as keeping two separate journals:
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 journal books, if you
deal with multiple accounts.

Here is a good place for an aside on the use of the word `account'.
Most private people consider an account to be something that holds money
at an institution for them.  LEDGER uses a more general definition
of the word.  An account is anywhere money can go.  Other finance
programs use ``categories'', LEDGER uses accounts. So, for
example, if you buy some groceries at Trader Joe's then more groceries
at Whole Foods Markets you might assign the transactions like this
@smallexample
2011/03/15   Trader Joe's
      Expenses:Groceries   $100.00
      Assets:Checking
2011/03/15   Whole Food Market
      Expenses:Groceries   $75.00
      Assets:Checking
@end smallexample
In both cases the money goes to the ``Groceries'' account, even though
the payees were different.  You can set up your accounts in any way you
choose.

Enter the beauty of computerized accounting.  The purpose of the
LEDGER program is to make general journal accounting simple, by keeping
track of the balances for you.  Your only job is to enter the
postings.  If a posting does not balance, LEDGER displays an
error and indicates the incorrect posting.@footnote{In some
special cases, it automatically balances this transaction for you.}

In summary, there are two aspects of LEDGER use: updating the journal
data file, and using the LEDGER tool to view the summarized result of
your transactions.

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

@smallexample
2004/09/29 Pacific Bell
     Expenses:Pacific Bell              $23.00
     Assets:Checking
@end smallexample

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

An important difference between LEDGER and other finance packages is
that journal will never alter your input file.  You can create and edit
that file in any way you prefer, but journal is only for analyzing the
data, not for altering it.

@section More introduction

@menu
* Building the Program::        
* Getting Help::                
@end menu

@node Building the Program, Getting Help, Introduction to Ledger, Introduction to Ledger
@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 Getting Help,  , Building the Program, Introduction to Ledger
@section Getting help

If you need help on how to use LEDGER, or run into problems, you can
join the LEDGER mailing list at the following Web address:

@example
http://groups.google.com/group/ledger-cli
@end example

You can also find help at the @samp{#ledger} channel on the IRC server
@samp{irc.freenode.net}.


@node Principles of Accounting, Keeping a Journal, Introduction to Ledger, Top
@chapter Principles of Accounting

@node Keeping a Journal, Command-line Syntax, Principles of Accounting, Top
@chapter Keeping a Journal

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

The LEDGER program aims at making journal transactions as simple as
possible.  Since it is a command-line tool, it does not provide a user
interface for keeping a journal.  If you like, you may use GnuCash to
maintain your journal, in which case LEDGER 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
journal, read on.  LEDGER has been designed to make data transactions as
simple as possible, by keeping the journal format easy, and also by
automagically determining as much information as possible based on the
nature of your transactions.

For example, you do not need to tell LEDGER about the accounts you
use.  Any time LEDGER sees a posting involving an account it knows
nothing about, it will create it@footnote{This also means if you
misspell an account it will end up getting counted separately from what
you intended.  The provided Emacs major mode provides for automatically
filling in account names.}.  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
posting.

@menu
* Most Basic Entry::            
* Commodities::                 
* Structuring Your Accounts::   
* Transaction Notes and Tags::  
* File Format::                 
* Archiving Previous Years ::   
* Ledger Tutorial ::            
@end menu

@node Most Basic Entry, Commodities, Keeping a Journal, Keeping a Journal
@section The Most Basic Entry

Here is the Pacific Bell example from above, given as a LEDGER
posting, with the additional of a check number:

@smallexample
9/29 (1023) Pacific Bell
    Expenses:Utilities:Phone                   $23.00
    Assets:Checking                           $-23.00
@end smallexample

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:

@smallexample
9/29 (1023) Pacific Bell
    Expenses:Utilities:Phone                   $23.00
    Assets:Checking
@end smallexample

For this transaction, LEDGER will figure out that $-23.00 must come from
@samp{Assets:Checking} in order to balance the transaction.

Also note the structure of the account entries.  There is an implied
hierarchy established by separating with colons.  See
(@pxref{Structuring Your Accounts}) for details and suggestions regarding
your accounts.



@strong{The format is very flexible and it isn't necessary that you
indent and space out things exactly as shown. The only requirements are
that the start of the transaction (the date typically) is at the
beginning of the first line of the transaction, and the accounts are
indented by at least one space.  If you omit the leading spaces in the
account lines LEDGER will not count the transaction and will not
give an error.  There must be at least two spaces, or a tab, between the
amount and the account.  If you do not have adequate separation between
the amount and the account LEDGER will give an error and stop
calculating}

@node Commodities, Structuring Your Accounts, Most Basic Entry, Keeping a Journal
@section Commodities

LEDGER is agnostic when it comes to how you value your accounts.
Dollars, Euros, Pounds, Francs, etc. are just ``commodities''.  Holdings
in stocks, bonds, mutual funds and other financial instrument can be
label using whatever is convenient for you (stock ticker symbols are
suggested for publicly traded assets).@footnote{you can track ANYTHING,
even time. As long as it cannot be created or destroyed inside your
accounting system.}

This is fundamentally different than many common accounting packages,
which assume the same currency throughout all of your accounts.  This
means if you typically operate in Euros, but travel to the US and has
some expenses, you would have to do the currency conversion BEFORE you
made the entry into your financial system.  With ledger this is not
required.  In the same journal you can have entries in any or all
commodities you actually hold.  You can use the reporting capabilities
to convert all commodities to a single commodity for reporting purposes
without ever changing the underlying entry.

For example, the following entries reflect transaction made for a
business trip to Europe from the US:

@smallexample
2011/09/23   Cash in Munich
    Assets:Cash  50.00 Euros
    Assets:Checking  $-66.00

2011/09/24  Dinner in Munich
    Expenses:Business:Travel  35.00 Euro
    Assets:Cash
@end smallexample

This says that $66.00 came out of checking and turned into 50 Euros. The
implied exchange rate was $1.32.  Then 35 Euros was spent on Dinner in Munich.


@node Structuring Your Accounts, Transaction Notes and Tags, Commodities, Keeping a Journal
@section Structuring your Accounts

There really are no requirements for how you do this, but to preserve
your sanity we suggest some very basic structure to your accounting
system.

At the highest level you have five sorts of accounts: Expenses, Assets,
Income, Liabilities and Equity.  Briefly, you can think of these as places money goes,
places money sits, places money comes from and money you owe.

Starting the structure off this way will make it simpler for you to get
answers to the questions you really need to ask about your finances.

@node Transaction Notes and Tags, File Format, Structuring Your Accounts, Keeping a Journal
@section Transaction Notes and Tags
LEDGER 3.0 supports entry and transaction ``notes'', which may  
contain new metadata and tag markers.  Here's an example:

@smallexample
   2004/05/27 (100) Credit card company
       ; This is an entry note!
       ; Sample: Value
       Liabilities:MasterCard         $20.00
       ; This is a transaction note!
       ; Sample: Another Value
       ; :MyTag:
       Assets:Bank:Checking
       ; :AnotherTag:
@end smallexample

An indented paragraph starting with `;' is parsed as a persistent note  
for its preceding category.  These notes will get printed back to you  
with the ``print'' command.  They are accessible to value expressions  
using the ``note'' variable.

Further, any occurrence of ``:foo:'' in a note will cause a metadata tag  
for "foo" to be registered for that entry.  You can then search for  
such transactions using:

@smallexample
   ledger reg %foo
   ldeger reg tag foo
@end smallexample

Also, if any word in the note ends (but does not start) with a colon,  
the remainder of that line will be taken to be the metadata value for  
that tag.  That is:

@smallexample
   ; :foo:bar:baz:  <-- These are three tags
   ; name: value    <-- this is a tag with a value
@end smallexample

Tags with value can be searched for just like tags.  In addition, you  
can further limit your tag search by looking for only those tags that  
have specific values:

@smallexample
   ledger reg %name=value
   ledger reg tag name=value
@end smallexample

The group-by and sort functions also support tags:
@smallexample
ledger --group-by "tag('foo')" bal 
@end smallexample
Will produce a balance summary of all transanction with tag `foo' group by transactions wiht the same value for `foo'.

@smallexample
ledger reg --sort "tag('foo')" %foo
@end smallexample
Produces a register view with the transaction have tag `foo' sorted by the tags value.

Comments that occur before an entry, or which starts at column  
zero, are always ignored and are neither searched nor printed back.



@node File Format, Archiving Previous Years , Transaction Notes and Tags, Keeping a Journal
@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 a transaction.  It may be followed
by any number of lines, each beginning with whitespace, to denote the
transaction's account postings.  The format of the first line is:

@example
DATE[=EDATE] [*|!] [(CODE)] DESC
@end example

If @samp{*} appears after the date (with optional effective date), it
indicates the transaction is ``cleared'', which can mean whatever the user
wants it to mean.  If @samp{!} appears after the date, it indicates d
the transaction is ``pending''; i.e., tentatively cleared from the user's
point of view, but not yet actually cleared.  If a @samp{CODE} appears
in parentheses, it may be used to indicate a check number, or the type
of the posting.  Following these is the payee, or a description of
the posting.

The format of each following posting is:

@example
  ACCOUNT  AMOUNT  [; NOTE]
@end example

The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual
postings, or square brackets if it is a virtual postings that
must balance.  The @samp{AMOUNT} can be followed by a per-unit
posting cost, by specifying @samp{@@ AMOUNT}, or a complete
posting cost with @samp{@@@@ AMOUNT}.  Lastly, the @samp{NOTE} may
specify an actual and/or effective date for the posting by using
the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or
@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}.

@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
postings, just as if it were normal transaction.  If the amounts of the
postings have no commodity, they will be applied as modifiers to
whichever real posting is matched by the value expression.

@item ~
A period transaction.  A period expression must appear after the tilde.

After this initial line there should be a set of one or more
postings, just as if it were normal transaction.

@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 @samp
@item !include
Include the stated journal file.

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

@item !end
Ends an account block.
@end table

@item ;
A line beginning with a colon indicates a comment, and is
ignored. Comments will not be returned in a ``print'' response.
@item indented ; 
If the semi colon is indented and occurs inside a transaction, it is
parsed as a persistent note for its preceding category.  These notes or
tags can be used to augment to reporting and filtering capabilities of
LEDGER.
@item Y
If a line begins with a capital Y, it denotes the year used for all
subsequent transactions 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 transactions 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 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 D AMOUNT
Specifies the default commodity to use, by specifying an amount in the
expected format.  The @command{transaction} command will use this commodity
as the default when none other can be determined.  This command may be
used multiple times, to set the default flags for different
commodities; whichever is seen last is used as the default commodity.
For example, to set US dollars as the default commodity, while also
setting the thousands flag and decimal flag for that commodity, use:
@example
D $1,000.00
@end example

@item C AMOUNT1 = AMOUNT2
Specifies a commodity conversion, where the first amount is given to
be equivalent to the second amount.  The first amount should use the
decimal precision desired during reporting:
@example
C 1.00 Kb = 1024 bytes
@end example

@item i, o, b, h
These four 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 Archiving Previous Years , Ledger Tutorial , File Format, Keeping a Journal
@section Archiving Previous Years

@node Ledger Tutorial ,  , Archiving Previous Years , Keeping a Journal
@section Ledger Tutorial


@node Command-line Syntax, Basic Reporting Commands, Keeping a Journal, Top
@chapter Command-line Syntax


@menu
* Cookbook::                    
* Quick Reference::             
* Commands::                    
* Options::                     
* Period Expressions::          
@end menu

@node Cookbook, Quick Reference, Command-line Syntax, Command-line Syntax
@section Cookbook

@subsection Invoking Ledger

@example
ledger --group-by "tag('trip')" bal
legder reg --sort "tag('foo')" %foo
ledger cleared VWCU NFCU Tithe Misentry
ledger register Joint --uncleared
ledger register NFCUChecking  --sort d  -d 'd>[2011/04/01]' until 2011/05/25
@end example
@subsection Ledger Files

@example
= /^Income:Taxable/ 
  (Liabilities:Tithe Owed)    -0.1
= /Noah/ 
  (Liabilities:Tithe Owed)    -0.1
= /Jonah/ 
  (Liabilities:Tithe Owed)    -0.1
= /Tithe/
  (Liabilities:Tithe Owed)    -1.0
@end example

@node Quick Reference, Commands, Cookbook, Command-line Syntax
@section Quick Reference

This chapter describes LEDGER's features and serves as a quick
reference. You may wish to survey this to get an overview before diving
in to the @ref{Ledger Tutorial} and more detailed examples that follow.

LEDGER has a very simple command-line interface, named---enticingly
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 postings matching those regular
expressions.  For the @command{transaction} command, the arguments have a
special meaning, described below.

The regular expressions arguments always match the account name that a
posting refers to.  To match on the payee of the transaction 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 takes a while to master them.
However, none of them are required to use the basic reporting
commands.


@node Commands, Options, Quick Reference, Command-line Syntax
@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 postings 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
postings that match.  Very useful for hunting down a particular
posting.

The output from @command{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.

If you have Gnuplot installed, you may plot the amount or running
total of any register by using the script @file{report}, which is
included in the LEDGER distribution.  The only requirement is that you
add either @option{-j} or @option{-J} to your register command, in
order to plot either the amount or total column, respectively.

@subsection print

The @command{print} command prints out ledger transactions in a textual
format that can be parsed by 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
postings 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 output

The @command{output} command is very similar to the @command{print}
command, except that it attempts to replicate the specified ledger
file exactly.  The format of the command is:

@example
ledger -f FILENAME output FILENAME
@end example

Where @file{FILENAME} is the name of the ledger file to output.  The
reason for specifying this command is that only transactions contained
within that file will be output, and not an included transactions (as can
happen with the @command{print} command).

@subsection xml

The @command{xml} command outputs results similar to what
@command{print} and @command{register} display, but as an XML form.
This data can then be read in and processed.  Use the
@option{--totals} option to include the running total with each
posting.

@subsection emacs

The @command{emacs} command outputs results in a form that can be read
directly by Emacs Lisp.  The format of the sexp is:

@example
((BEG-POS CLEARED DATE CODE PAYEE
  (ACCOUNT AMOUNT)...)  ; list of postings
 ...)                   ; list of transactions
@end example

@subsection equity

The @command{equity} command prints out accounts balances as if they
were transactions.  This makes it easy to establish the starting balances
for an account, such as when @ref{Archiving Previous Years}.

@subsection prices

The @command{prices} command displays the price history for matching
commodities.  The @option{-A} flag is useful with this report, to
display the running average price, or @option{-D} to show each price's
deviation from that average.

There is also a @command{pricesdb} command which outputs the same
information as @command{prices}, but does in a format that can be
parsed by LEDGER.

@subsection xact

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

Say you currently have this posting in your ledger file:

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

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

@example
ledger xact 2004/4/9 viva food 11 tips 2.50
@end example

This produces the following output:

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

It works by finding a past posting matching the regular expression
@samp{viva}, and assuming that any accounts or amounts specified will
be similar to that earlier posting.  If LEDGER does not succeed in
generating a new transaction, an error is printed and the exit code is set
to @samp{1}.

There is a shell script in the distribution's @file{scripts} directory
called @file{xact}, which simplifies the task of adding a new transaction
to your ledger.  It launches @command{vi} to confirm that the transaction
looks appropriate.

Here are a few more examples of the @command{xact} command, assuming
the above journal transaction:

@example
ledger xact 4/9 viva 11.50
ledger xact 4/9 viva 11.50 checking # (from `checking')
ledger xact 4/9 viva food 11.50 tips 8
ledger xact 4/9 viva food 11.50 tips 8 cash
ledger xact 4/9 viva food $11.50 tips $8 cash
ledger xact 4/9 viva dining "DM 11.50"
@end example

@node Options, Period Expressions, Commands, Command-line Syntax
@section Options

With all of the reports, command-line options are useful to modify the
output generated.  These command-line options always occur before the
command word.  This is done to distinguish options from exclusive
regular expressions, which also begin with a dash.  The basic form for
most commands is:

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

The @var{OPTIONS} and @var{REGEXPS} expressions are both optional.
You could just use @samp{ledger balance}, without any options---which
prints a summary of all accounts.  But for more specific reporting, or
to change the appearance of the output, options are needed.

@subsection Basic options

These are the most basic command options.  Most likely, the user will
want to set them using environment variables (see @ref{Options}),
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{--file FILE} (@option{-f FILE}) reads FILE as a ledger file.
This command may be used multiple times.
Typically, the environment variable
@env{LEDGER_FILE} is set, rather than using this command-line option.

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

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

@smallexample
--price-db ~/finance/.pricedb
--cache /tmp/ledger-cache

; ~/.ledgerrc ends here
@end smallexample

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

@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 @env{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 @env{LEDGER_CACHE}, or by
putting the option into your init file.  The @option{--no-cache}
option causes LEDGER to always ignore the binary cache.

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

@subsection Report filtering

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

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

@option{--begin DATE} (@option{-b DATE}) constrains the report to
transactions on or after @var{DATE}.  Only transactions 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 transaction.  (Note: This
is different from using @option{--display} to constrain what is
displayed).

@option{--end DATE} (@option{-e DATE}) constrains the report so that
transactions on or after @var{DATE} are not considered.  The ending date
is inclusive.

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

@option{--period-sort EXPR} sorts the postings within each
reporting period using the value expression @var{EXPR}.  This is most
often useful when reporting monthly expenses, in order to view the
highest expense categories at the top of each month:

@example
ledger -M --period-sort -At reg ^Expenses
@end example

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

@option{--uncleared} (@option{-U}) displays only postings whose
transaction 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 postings, not
virtual.  (A virtual posting is indicated by surrounding the
account name with parentheses or brackets; see the section on using
virtual postings for more information).

@option{--actual} (@option{-L}) displays only actual postings, and
not those created due to automated postings.

@option{--related} (@option{-r}) displays postings that are
related to whichever postings 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 transactions having a related posting.
For example, if a file had this transaction:

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

And the register command was:

@example
ledger -r register food
@end example

The following would be output, showing the postings related to the
posting that matched:

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

@option{--budget} is useful for displaying how close your postings
meet your budget.  @option{--add-budget} also shows unbudgeted
postings, while @option{--unbudgeted} shows only those.
@option{--forecast} is a related option that projects your budget into
the future, showing how it will affect future balances.
@xref{Budgeting and Forecasting}.

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

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

@option{--total EXPR} (@option{-T EXPR}) sets the value expression
used for the ``totals'' column in the @command{register} and
@command{balance} reports.

@subsection Output customization

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

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

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

@option{--by-payee} (@option{-P}) reports subtotals by payee.

@option{--comm-as-payee} (@option{-x}) changes the payee of every
posting to be the commodity used in that posting.  This can be
useful when combined with other options, such as @option{-s}.

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

@option{--weekly} (@option{-W}) reports posting totals by the
week.  The week begins on whichever day of the week begins the month
containing that posting.  To set a specific begin date, use a
period string, such as @samp{weekly from DATE}.  @option{--monthly}
(@option{-M}) reports posting totals by month; @option{--yearly}
(@option{-Y}) reports posting totals by year.  For more complex
period, using the @option{--period} option described above.

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

@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 -UT} 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{--wide} (@option{-w}) causes the default @command{register}
report to assume 132 columns instead of 80.

@option{--head} causes only the first N transactions to be printed.  This
is different from using the command-line utility @command{head}, which
would limit to the first N postings.  @option{--tail} outputs only
the last N transactions.  Both options may be used simultaneously.  If a
negative amount is given, it will invert the meaning of the flag
(instead of the first five transactions being printed, for example, it
would print all but the first five).

@option{--pager} tells LEDGER to pass its output to the given pager
program---very useful when the output is especially long.  This
behavior can be made the default by setting the @env{LEDGER_PAGER}
environment variable.

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

@option{--deviation} (@option{-D}) reports each posting's
deviation from the average.  It is only meaningful in the
@command{register} and @command{prices} reports.

@option{--percentage} (@option{-%}) shows account subtotals in the
@command{balance} report as percentages of the parent account.

@option{--totals} include running total information in the
@command{xml} report.

@option{--amount-data} (@option{-j}) changes the @command{register}
report so that it outputs 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 outputs nothing but the date and totals column,
without commodities.

@option{--display EXPR} (@option{-d EXPR}) limits which postings
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 postings, against a running balance which
includes all posting 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 postings 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{--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 put
@option{--date-format FORMAT} in the LEDGER initialization file
@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}).

@option{--format STR} (@option{-F STR}) sets the reporting format for
whatever report ledger is about to make.  @xref{Format Strings}.
There are also specific format commands for each report type:

@itemize
@item @option{--balance-format STR}
@item @option{--register-format STR}
@item @option{--print-format STR}
@item @option{--plot-amount-format STR} (-j @command{register})
@item @option{--plot-total-format STR} (-J @command{register})
@item @option{--equity-format STR}
@item @option{--prices-format STR}
@item @option{--wide-register-format STR} (-w @command{register})
@end itemize

@subsection Commodity reporting

These options affect how commodity values are displayed:

@option{--price-db 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{--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.

@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 @env{LEDGER_PRICE_DB}.

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 -O, --quantity
Reports commodity totals (this is the default)

@item -B, --basis
Reports the cost basis for all postings.

@item -V, --market
Reports the last known market value for all commodities.

@item -G --gain
Reports the net gain/loss for all commodities in the report that have
a price history.
@end table

@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 @env{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
--pager /bin/cat

@end example

@node Period Expressions,  , Options, Command-line Syntax
@section Period Expressions

A period expression indicates a span of time, or a reporting interval,
or both.  The full syntax is:

@example
[INTERVAL] [BEGIN] [END]
@end example

The optional @var{INTERVAL} part may be any one of:

@example
every day
every week
every monthly
every quarter
every year
every N days     # N is any integer
every N weeks
every N months
every N quarters
every N years
daily
weekly
biweekly
monthly
bimonthly
quarterly
yearly
@end example

After the interval, a begin time, end time, both or neither may be
specified.  As for the begin time, it can be either of:

@example
from <SPEC>
since <SPEC>
@end example

The end time can be either of:

@example
to <SPEC>
until <SPEC>
@end example

Where @var{SPEC} can be any of:

@example
2004
2004/10
2004/10/1
10/1
october
oct
this week  # or day, month, quarter, year
next week
last week
@end example

The beginning and ending can be given at the same time, if it spans a
single period.  In that case, just use @var{SPEC} by itself.  In that
case, the period @samp{oct}, for example, will cover all the days in
october.  The possible forms are:

@example
<SPEC>
in <SPEC>
@end example

Here are a few examples of period expressions:

@example
monthly
monthly in 2004
weekly from oct
weekly from last month
from sep to oct
from 10/1 to 10/5
monthly until 2005
from apr
until nov
last oct
weekly last august
@end example


@node Basic Reporting Commands, Value Expressions, Command-line Syntax, Top
@chapter Basic Reporting Commands

@menu
* Budgeting and Forecasting::   
@end menu

@node Budgeting and Forecasting,  , Basic Reporting Commands, Basic Reporting Commands
@section Budgeting and Forecasting


@node Value Expressions, Format Strings, Basic Reporting Commands, Top
@chapter Value Expressions

Value expressions are an expression language used by LEDGER to
calculate values used by the program for many different purposes:

@enumerate
@item
The values displayed in reports
@item
For predicates (where truth is anything non-zero), to determine which
postings are calculated (@option{-l}) or displayed (@option{-d}).
@item
For sorting criteria, to yield the sort key.
@item
In the matching criteria used by automated postings.
@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:UT>100 balance
@end example

The effect is that account totals are displayed only if: 1) A
Liabilities 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 transactions are printed.  For example, the following
command shows only transactions from the beginning of the current month,
while still calculating the running balance based on all transactions:

@example
ledger -d "d>[this month]" register checking
@end example

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

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

@menu
* Variables::                   
@end menu

@node Variables,  , Value Expressions, Value Expressions
@section Variables

Below are the one letter variables available in any value expression.
For the register and print commands, these variables relate to
individual postings, and sometimes the account affected by a
posting.  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

@subsection Posting/account details

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

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

@item b
The cost of a posting; the cost of an account, without its
children.

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

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

@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 posting, or the count of postings affecting an
account.

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

@item R
1 if a posting is not virtual, 0 otherwise.

@item Z
1 if a posting is not automated, 0 otherwise.
@end table

@subsection Calculated totals

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

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

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

@item V
The market value of all postings 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
postings, or an account and its children.  It is the same as
@samp{V-B}.
@end table

@section Functions

The available one letter functions are:

@table @code
@item -
Negates the argument.

@item U
The absolute (unsigned) value of the argument.

@item S
Strips the commodity from the argument.

@item A
The arithmetic mean of the argument; @samp{Ax} is the same as
@samp{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}.  If no date
is given, then the current moment is used.
@end table

@section Operators

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

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

@section 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/
@item W/REGEXP/
A regular expression that matches against an account's full name.  If
a posting, this will match against the account affected by the
posting.

@item //REGEXP/
@item p/REGEXP/
A regular expression that matches against a transaction's payee name.

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

@item c/REGEXP/
A regular expression that matches against the transaction code (the text
that occurs between parentheses before the payee name).

@item e/REGEXP/
A regular expression that matches against a posting's note, or
comment field.

@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 Format Strings, Journal File Format, Value Expressions, Top
@chapter Format Strings

Format strings may 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 posting in custom ways.

Within a format strings, a substitution 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 substituted will be left justified.  The default is right
justified.  If a minimum 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     a transaction'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 posting's date with a date
format string, exactly like those supported by @code{strftime}.  For
example: @samp{%[%Y/%m/%d %H:%M:%S]}.

@item S
Insert the pathname of the file from which the transaction's data was read.

@item B
Inserts the beginning character position of that transaction within the file.

@item b
Inserts the beginning line of that transaction within the file.

@item E
Inserts the ending character position of that transaction within the file.

@item e
Inserts the ending line of that transaction within the file.

@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 d
This is the same as the @samp{%D} option, unless the transaction has an
effective date, in which case it prints
@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}.

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

@item Y
This is the same as @samp{%X}, except that it only displays a state
character if all of the member postings have the same state.

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

@item P
Inserts the payee related to a posting.

@item a
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, otherwise it just prints the account's name.

@item A
Inserts the full name of an account.

@item W
This is the same as @samp{%A}, except that it first displays the
posting's state @emph{if the transaction's posting states are not
all the same}, followed by the full account name.  This is offered as
a printing optimization, so that combined with @samp{%Y}, only the
minimum amount of state detail is printed.

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

@item n
Inserts the note associated with a posting, preceded by two spaces
and a semi-colon, if it exists.  Thus, no none becomes an empty
string, while the note @samp{foo} is substituted as @samp{ ; foo}.

@item N
Inserts the note associated with a posting, if one exists.

@item /
The @samp{%/} construct is special.  It separates a format string
between what is printed for the first posting of a transaction, and
what is printed for all subsequent postings.  If not used, the
same format string is used for all postings.
@end table


@node Journal File Format, Extending with Python, Format Strings, Top
@chapter LEDGER Journal File Format

This chapter offers a complete description of the journal data format,
suitable for implementors in other languages to follow.  For users,
the chapter on keeping a journal is less extensive, but more typical
of common usage (@pxref{Keeping a Journal}).

Data is collected in the form of @dfn{transactions} which occur in one
or more @dfn{journal files}.  Each transaction, in turn, is made up of
one or more @dfn{postings}, which describe how @dfn{amounts} flow from
one @dfn{account} to another.  Here is an example of the simplest of
journal files:

@example
2010/05/31 Just an example
    Expenses:Some:Account                $100.00
    Income:Another:Account
@end example

In this example, there is a transaction date, a payee, or description
of the transaction, and two postings.  The postings show movement of
one hundred dollars from an account within the Income hierarchy, to
the specified expense account.  The name and meaning of these accounts
in arbitrary, with no preferences implied, although you will find it
useful to follow standard accounting practice (@pxref{Principles of
Accounting}).

Since an amount is missing from the second posting, it is assumed to
be the inverse of the first.  This guarantee the cardinal rule of
double-entry accounting: the sum of every transaction must balance to
zero, or it is in error.  Whenever Ledger encounters a @dfn{null
posting} in a transaction, it uses it to balance the remainder.

It is also typical---though not enforced---to think of the first
posting as the destination, and the final as the source.  Thus, the
amount of the first posting is typically positive.  Consider:

@example
2010/05/31 An income transaction
    Assets:Checking       $1,000.00
    Income:Salary

2010/05/31 An expense transaction
    Expenses:Dining         $100.00
    Assets:Checking
@end example

@emph{Note:} It is important to note that there must be at least two spaces between
the end of the post and the beginning of the amount (including and
commdity designator).

@section Specifying amounts

The heart of a journal is the amounts it records, and this fact is
reflected in the diversity of amount expressions allowed.  All of them
are covered here, though it must be said that sometimes, there are
multiple ways to achieve a desired result.

@subsection Integer amounts

In the simplest form, bare decimal numbers are accepted:

@example
2010/05/31 An income transaction
    Assets:Checking        1000.00
    Income:Salary
@end example

Such amounts may only use an optional period for a decimal point.
These are referred to as @dfn{integer amounts} or @dfn{uncommoditized
amounts}.  In most ways they are similar to @dfn{commoditized
amounts}, but for one signficant difference: They always display in
reports with @dfn{full precision}.  More on this in a moment.  For
now, a word must be said about how Ledger stores numbers.

Every number parsed by Ledger is stored internally as an
infinite-precision rational value.  Floating-point math is never used,
as it cannot be trusted to maintain precision of values.  So, in the
case of @samp{1000.00} above, the internal value is @samp{100000/100}.

While rational numbers are great at not losing precision, the question
arises: How should they be displayed?  A number like @samp{100000/100}
is no problem, since it represents a clean decimal fraction.  But what
about when the number @samp{1/1} is divided by three?  How should one
print @samp{1/3}, an infinitely repeating decimal?

Ledger gets around this problem by rendering rationals into decimal at
the last possible moment, and only for display.  As such, some
rounding must, at times, occur.  If this rounding would affect the
calculation of a running total, special accommodation postings are
generated to make you aware it has happened.  In practice, it happens
rarely, but even then it does not reflect adjustment of the
@emph{internal amount}, only the displayed amount.

What has still not been answered is how Ledger rounds values.  Should
@samp{1/3} be printed as @samp{0.33} or @samp{0.33333}?  For
commoditized amounts, the number of decimal places is decided by
observing how each commodity is used; but in the case of integer
amounts, an arbitrary factor must be chosen.  Initially, this factor
is six.  Thus, @samp{1/3} is printed back as @samp{0.333333}.
Further, this rounding factor becomes associated with each particular
value, and is carried through mathematical operations.  For example,
if that particular number were multiplied by itself, the decimal
precision of the result would be twelve.  Addition and subtraction do
not affect precision.

Since each integer amount retains its own display precision, this is
called @dfn{full precision}, as opposed to commoditized amounts, which
always look to their commodity to know what precision they should
round to, and so use @dfn{commodity precision}.

@subsection Commoditized amounts

A @dfn{commoditized amount} is an integer amount which has an
associated commodity.  This commodity can appear before or after the
amount, and may or may not be separated from it by a space.  Most
characters are allowed in a commodity name, except for the following:

@itemize
@item Any kind of whitespace
@item Numerical digits
@item Punctuation: @samp{.,;:?!}
@item Mathematical and logical operators: @samp{-+*/^&|=}
@item Bracketing characters: @samp{<>[]()}@{@}
@item The at symbol: @samp{@@}
@end itemize

And yet, any of these may appear in a commodity name if it is
surrounded by double quotes, for example:

@example
100 "EUN+133"
@end example

If a @dfn{quoted commodity} is found, it is displayed in quotes as
well, to avoid any confusion as to which part is the amount, and which
part is the commodity.

Another feature of commoditized amounts is that they are reported back
in the same form as parsed.  If you specify dollar amounts using
@samp{$100}, they will print the same; likewise with @samp{100 $} or
@samp{$100.000}.  You may even use decimal commas, such as
@samp{$100,00}, or thousand-marks, as in @samp{$10,000.00}.

These display characteristics become associated with the commodity,
with the result being that all amounts of the same commodity are
reported consistently.  Where this is most noticeable is the
@dfn{display precision}, which is determined by the most precise value
seen for a given commodity.  In most cases.

Ledger makes a distinction by @dfn{observed amounts} and unobserved
amounts.  An observed amount is critiqued by Ledger to determine how
amounts using that commodity should be displayed; unobserved amounts
are significant in their value only---no matter how they are
specified, it does not change how other amounts in that commodity will
be displayed.

An example of this is found in cost expressions, covered next.

@section Posting costs

You have seen how to specify either a commoditized or an integer
amount for a posting.  But what if the amount you paid for something
was in one commodity, and the amount received was another?  There are
two main ways to express this:

@example
2010/05/31 Farmer's Market
    Assets:My Larder           100 apples
    Assets:Checking                $20.00
@end example

In this example, you have paid twenty dollars for one hundred apples.
The cost to you is twenty cents per apple, and Ledger calculates this
implied cost for you.  You can also make the cost explicit using a
@dfn{cost amount}:

@example
2010/05/31 Farmer's Market
    Assets:My Larder           100 apples @@ $0.200000
    Assets:Checking
@end example

Here the @dfn{per-unit cost} is given explicitly in the form of a cost
amount; and since cost amount are @emph{unobserved}, the use of six
decimal places has no effect on how dollar amounts are displayed in
the final report.  You can also specify the @dfn{total cost}:

@example
2010/05/31 Farmer's Market
    Assets:My Larder           100 apples @@@@ $20
    Assets:Checking
@end example

These three forms have identical meaning.  In most cases the first is
preferred, but the second two are necessary when more than two
postings are involved:

@example
2010/05/31 Farmer's Market
    Assets:My Larder           100 apples        @@ $0.200000
    Assets:My Larder           100 pineapples    @@ $0.33
    Assets:My Larder           100 "crab apples" @@ $0.04
    Assets:Checking
@end example

Here the implied cost is @samp{$57.00}, which is entered into the null
posting automatically so that the transaction balances.

@subsection Primary commodities

In every transaction involving more than one commodity, there is
always one which is the @dfn{primary commodity}.  This commodity
should be thought of as the exchange commodity, or the commodity used
to buy and sells units of the other commodity.  In the fruit examples
above, dollars are the primary commodity.  This is decided by Ledger
on the placement of the commodity in the transaction:

@example
2010/05/31 Sample Transaction
    Expenses               100 secondary
    Assets                  50 primary

2010/05/31 Sample Transaction
    Expenses               100 secondary @@ 0.5 primary
    Assets

2010/05/31 Sample Transaction
    Expenses               100 secondary @@@@ 50 primary
    Assets
@end example

The only case where knowledge of primary versus secondary comes into
play is in reports that use the @option{-V} or @option{-B} options.
With these, only primary commodities are shown.

If a transaction uses only one commodity, this commodity is also
considered a primary.  In fact, when Ledger goes about ensures that
all transactions balance to zero, it only ever asks this of primary
commodities.

@node Extending with Python,  , Journal File Format, Top
@chapter Extending with Python

@bye