path: root/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


@titlepage
@title Ledger: Command-Line Accounting
@subtitle For Version 3.0 of Ledger
@subtitle Draft Manual Time-stamp: <2011-10-26 15:20 (cpearls)>
@author John Wiegley
@end titlepage

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

@contents

@ifnottex
@node Top, Copying, (dir), (dir)
@top Overview
Ledger is a command line accounting tool that provides double-entry
accounting based on a text journal.  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::      
* Ledger Tutorial ::            
* Principles of Accounting::    
* Keeping a Journal::           
* Command-line Syntax::         
* Reporting Commands::          
* Budgeting and Forecasting::   
* Value Expressions::           
* Format Strings::              
* Journal File Format::         
* Extending with Python::       
* Example Data File::           
* Miscellaneous Notes::         
@end menu

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

@node Introduction to Ledger, Ledger Tutorial , Copying, Top
@chapter Introduction to Ledger
@menu
* Fat-free Accounting::         
* Building the Program::        
* Getting Help::                
@end menu

@node Fat-free Accounting, Building the Program, Introduction to Ledger, Introduction to Ledger
@section Fat-free Accounting
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.  If you use
another GUI accounting program like GNUCash, the vast majority of its
functionality is geared towards helping you keep a journal.

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 an individual 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:

@smallexample
$ ledger -f ledger.dat balance
$ ledger -f ledger.dat register checking
$ ledger -f ledger.dat register Bell
@end smallexample

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.


@node Building the Program, Getting Help, Fat-free Accounting, 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:

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

@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:

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

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

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

@menu
* Start a Journal::             
* Run Some Reports::            
* Command Line Quick Reference::  
@end menu

@node Start a Journal, Run Some Reports, Ledger Tutorial , Ledger Tutorial
@section Start a Journal File

A journal is a record of your financial transactions and will be central
to using Ledger.  For now we just want to get a taste of what Ledger can
do.  An example journal is included with the source code distribution,
called @file{drewr3.dat} (@pxref{Example Data File}).
Copy it someplace convenient and open up a terminal window in that
directory.

If you would rather start with your own journal right away please skip
to @xref{Keeping a Journal}.

@node Run Some Reports, Command Line Quick Reference, Start a Journal, Ledger Tutorial
@section Run a Few Reports

@menu
* Balance Report::              
* Register Report::             
* Cleared Report::              
@end menu

@node Balance Report, Register Report, Run Some Reports, Run Some Reports
@subsection Balance Report

To find the balances of all of your accounts, run this command:

@smallexample
ledger -f drewr3.dat balance
@end smallexample

Ledger will generate:

@smallexample
         $ -3,804.00  Assets
          $ 1,396.00    Checking
             $ 30.00      Business
         $ -5,200.00    Savings
         $ -1,000.00  Equity:Opening Balances
          $ 6,654.00  Expenses
          $ 5,500.00    Auto
             $ 20.00    Books
            $ 300.00    Escrow
            $ 334.00    Food:Groceries
            $ 500.00    Interest:Mortgage
         $ -2,030.00  Income
         $ -2,000.00    Salary
            $ -30.00    Sales
            $ -63.60  Liabilities
            $ -20.00    MasterCard
            $ 200.00    Mortgage:Principal
           $ -243.60    Tithe
--------------------
           $ -243.60
@end smallexample

@noindent Showing you the balance of all accounts.  Options and search terms can pare this down to show only the accounts you want.

A more useful report is to show only your Assets and Liabilities:

@smallexample
$ ledger -f drewr3.dat balance Assets Liabilities
         $ -3,804.00  Assets
          $ 1,396.00    Checking
             $ 30.00      Business
         $ -5,200.00    Savings
            $ -63.60  Liabilities
            $ -20.00    MasterCard
            $ 200.00    Mortgage:Principal
           $ -243.60    Tithe
--------------------
         $ -3,867.60
@end smallexample


@node Register Report, Cleared Report, Balance Report, Run Some Reports
@subsection Register Report

To show all transactions and a running total:
@smallexample
ledger -f drewr3.dat register
@end smallexample

Ledger will generate:

@smallexample
10-Dec-01 Checking balance      Assets:Checking          $ 1,000.00   $ 1,000.00
                                Equity:Opening Balances  $ -1,000.00            0
10-Dec-20 Organic Co-op         Expense:Food:Groceries      $ 37.50      $ 37.50
                                Expense:Food:Groceries      $ 37.50      $ 75.00
                                Expense:Food:Groceries      $ 37.50     $ 112.50
                                Expense:Food:Groceries      $ 37.50     $ 150.00
                                Expense:Food:Groceries      $ 37.50     $ 187.50
                                Expense:Food:Groceries      $ 37.50     $ 225.00
                                Assets:Checking           $ -225.00            0
10-Dec-28 Acme Mortgage         Lia:Mortgage:Principal     $ 200.00     $ 200.00
                                Expe:Interest:Mortgage     $ 500.00     $ 700.00
                                Expenses:Escrow            $ 300.00   $ 1,000.00
                                Assets:Checking         $ -1,000.00            0
11-Jan-02 Grocery Store         Expense:Food:Groceries      $ 65.00      $ 65.00
                                Assets:Checking            $ -65.00            0
11-Jan-05 Employer              Assets:Checking          $ 2,000.00   $ 2,000.00
                                Income:Salary           $ -2,000.00            0
                                (Liabilities:Tithe)       $ -240.00    $ -240.00
11-Jan-14 Bank                  Assets:Savings             $ 300.00      $ 60.00
                                Assets:Checking           $ -300.00    $ -240.00
11-Jan-19 Grocery Store         Expense:Food:Groceries      $ 44.00    $ -196.00
                                Assets:Checking            $ -44.00    $ -240.00
11-Jan-25 Bank                  Assets:Checking          $ 5,500.00   $ 5,260.00
                                Assets:Savings          $ -5,500.00    $ -240.00
11-Jan-25 Tom's Used Cars       Expenses:Auto            $ 5,500.00   $ 5,260.00
                                Assets:Checking         $ -5,500.00    $ -240.00
11-Jan-27 Book Store            Expenses:Books              $ 20.00    $ -220.00
                                Liabilities:MasterCard     $ -20.00    $ -240.00
11-Dec-01 Sale                  Asse:Checking:Business      $ 30.00    $ -210.00
                                Income:Sales               $ -30.00    $ -240.00
                                (Liabilities:Tithe)         $ -3.60    $ -243.60
@end smallexample

@noindent To limit this to a more useful subset, simply add the accounts you are are interested in seeing transactions for:

@smallexample
$ ledger -f drewr3.dat register Groceries
10-Dec-20 Organic Co-op         Expense:Food:Groceries      $ 37.50      $ 37.50
                                Expense:Food:Groceries      $ 37.50      $ 75.00
                                Expense:Food:Groceries      $ 37.50     $ 112.50
                                Expense:Food:Groceries      $ 37.50     $ 150.00
                                Expense:Food:Groceries      $ 37.50     $ 187.50
                                Expense:Food:Groceries      $ 37.50     $ 225.00
11-Jan-02 Grocery Store         Expense:Food:Groceries      $ 65.00     $ 290.00
11-Jan-19 Grocery Store         Expense:Food:Groceries      $ 44.00     $ 334.00
@end smallexample

@noindent Which matches the balance reported for the @samp{Groceries} account:

@smallexample
$ ledger -f drewr3.dat balance Groceries 
            $ 334.00  Expenses:Food:Groceries
@end smallexample

@noindent  If you would like to find transaction to only a certain payee use @samp{payee} or @@:
@smallexample
$ ledger -f drewr3.dat register payee "Organic"
10-Dec-20 Organic Co-op         Expense:Food:Groceries      $ 37.50      $ 37.50
                                Expense:Food:Groceries      $ 37.50      $ 75.00
                                Expense:Food:Groceries      $ 37.50     $ 112.50
                                Expense:Food:Groceries      $ 37.50     $ 150.00
                                Expense:Food:Groceries      $ 37.50     $ 187.50
                                Expense:Food:Groceries      $ 37.50     $ 225.00
                                Assets:Checking           $ -225.00            0
@end smallexample

@node Cleared Report,  , Register Report, Run Some Reports
@subsection Cleared Report

A very useful report is to show what your obligations are versus what
expenditures have actually been recorded.  It can take several days for
a check to clear, but you should treat it as money spent.  The
@samp{cleared} report shows just that:

@smallexample
$ ledger -f drewr3.dat cleared 
     $ -3,804.00            $ 775.00                 Assets
      $ 1,396.00            $ 775.00    10-Dec-20      Checking
         $ 30.00                   0                     Business
     $ -5,200.00                   0                   Savings
     $ -1,000.00         $ -1,000.00    10-Dec-01    Equity:Opening Balances
      $ 6,654.00            $ 225.00                 Expenses
      $ 5,500.00                   0                   Auto
         $ 20.00                   0                   Books
        $ 300.00                   0                   Escrow
        $ 334.00            $ 225.00    10-Dec-20      Food:Groceries
        $ 500.00                   0                   Interest:Mortgage
     $ -2,030.00                   0                 Income
     $ -2,000.00                   0                   Salary
        $ -30.00                   0                   Sales
        $ -63.60                   0                 Liabilities
        $ -20.00                   0                   MasterCard
        $ 200.00                   0                   Mortgage:Principal
       $ -243.60                   0                   Tithe
----------------  ----------------    ---------
       $ -243.60                   0    
@end smallexample

@noindent The first column shows the outstanding balance, the second column show the ``cleared'' balance.

@node Command Line Quick Reference,  , Run Some Reports, Ledger Tutorial
@section Command Line Quick Reference

@menu
* Reporting Commands Quick Reference::  
* Basic Options Quick Reference::  
* Report Filtering Quick Reference::  
* Output Customization Quick Reference::  
* Grouping Options::            
* Commodity Reporting Quick Reference::  
@end menu

@node Reporting Commands Quick Reference, Basic Options Quick Reference, Command Line Quick Reference, Command Line Quick Reference
@subsection Reporting Commands
@multitable @columnfractions .2 .8
@item @strong{Report} @tab @strong{Description}
@item @code{balance} @tab Show account balances
@item @code{register} @tab Show all transactions with running total
@item @code{print} @tab  Print transaction in a ledger readable format
@item @code{output} @tab  Similar to print without included transactions
@item @code{xml} @tab Produce XML output of the register command
@item @code{emacs} @tab Produce emacs lisp output
@item @code{equity} @tab Print account balances as transactions
@item @code{prices} @tab Print price history for matching commodities
@item @code{pricedb} @tab Print price history for matching commodities in ledger readable format
@item @code{xact} @tab  Used to generate transactions based on previous postings
@end multitable

@node Basic Options Quick Reference, Report Filtering Quick Reference, Reporting Commands Quick Reference, Command Line Quick Reference
@subsection Basic Options
@multitable @columnfractions .1 .25 .65
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
@item @code{-h} @tab @code{--help} @tab prints summary of all options
@item @code{-v} @tab @code{--version} @tab prints version of ledger executable
@item @code{-f FILE} @tab @code{--file FILE} @tab read @file{FILE} as a ledger file
@item @code{-o FILE} @tab @code{--output FILE} @tab redirects output to @file{FILE}
@item @code{-i FILE} @tab @code{--init-file FILE} @tab specify options file
@item @tab @code{--cache FILE} @tab specify binary cache file 
@item @code{-a NAME} @tab @code{--account NAME} @tab specify default account name for QIF file postings
@end multitable
 
@node Report Filtering Quick Reference, Output Customization Quick Reference, Basic Options Quick Reference, Command Line Quick Reference
@subsection Report Filtering
@multitable @columnfractions .1 .25 .65
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
@item @code{-c} @tab @code{--current} @tab Display transaction on or before the current date
@item @code{-b DATE} @tab @code{--begin DATE} @tab Begin reports on or after @code{DATE}
@item @code{-e DATE} @tab @code{--end DATE} @tab Limits end date od transactions for report
@item @code{-p STR} @tab @code{--period} @tab Set report period to STR
@item @code{ } @tab @code{--period-sort} @tab Sort postings within each period
@item @code{-C} @tab @code{--cleared} @tab Display only cleared postings
@item @code{-U} @tab @code{--uncleared} @tab Display only uncleared postings
@item @code{-R} @tab @code{--real} @tab Display only real postings
@item @code{-L} @tab @code{--actual} @tab Displays only actual postings, not automated
@item @code{-r} @tab @code{--related} @tab Display related postings
@item @code{} @tab @code{--budget} @tab Display how close your postings meet your budget
@item @code{} @tab @code{--add-budget} @tab Shows unbudgeted postings
@item @code{} @tab @code{--unbedgeted} @tab Shows only unbudgeted postings
@item @code{} @tab @code{--forecast} @tab Project balances into the future
@item @code{-l EXPR} @tab @code{--limit EXPR} @tab Limits postings in calculations
@item @code{-t EXPR} @tab @code{--amount} @tab Change value expression reported in register report
@item @code{-T EXPR} @tab @code{--total} @tab Change the value expression used for ``totals'' column in register and balance reports
@end multitable

@node Output Customization Quick Reference, Grouping Options, Report Filtering Quick Reference, Command Line Quick Reference
@subsection Output Customization
@multitable @columnfractions .15 .4 .45
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
@item @code{-n} @tab @code{--collapse} @tab Collapse transactions with multiple postings
@item @code{-s} @tab @code{--subtotal} @tab Report register as a single subtotal
@item @code{-P} @tab @code{--by-payee} @tab Report subtotals by payee
@item @code{-x} @tab @code{--comm-as-payee} @tab Change the payee of every posting to be the commodity used in that posting
@item @code{-E} @tab @code{--empty} @tab Include empty accounts in report
@item @code{-W} @tab @code{--weekly} @tab Report posting totals by week
@item @code{-Y} @tab @code{--yearly} @tab Report posting totals by year
@item @code{} @tab @code{--dow} @tab report Posting totals by day of week
@item @code{-S EXPR} @tab @code{--sort EXPR} @tab Sorts a report using @code{EXPR}
@item @code{-w} @tab @code{--wide} @tab Assume 132 columns instead of 80
@item @code{} @tab @code{--head N} @tab Report the first N postings
@item @code{} @tab @code{--tail N} @tab Report the last N postings
@item @code{} @tab @code{--pager prog} @tab Direct output @code{prog} pager program
@item @code{-A} @tab @code{--average} @tab Reports average posting value
@item @code{-D} @tab @code{--deviation} @tab Reports each posting deviation from the average
@item @code{-%} @tab @code{--percentage} @tab Show subtotals in the balance report as percentages
@item @code{} @tab @code{--totals} @tab Include running total in the @code{xml} report
@item @code{-j} @tab @code{--amount-data} @tab Show only date and value column
@item @code{-J} @tab @code{--total-data} @tab Show only dates and totals
@item @code{-d EXPR} @tab @code{--display EXPR} @tab Limit only the display of certain postings
@item @code{-y STR} @tab @code{--date-format STR} @tab Change the basic date format used in reports
@item @code{-F STR} @tab @code{--format STR} @tab Set reporting format
@item @code{} @tab @code{--balance-format STR} @tab
@item @code{} @tab @code{--register-format STR} @tab
@item @code{} @tab @code{--print-format STR} @tab
@item @code{-j register} @tab @code{--plot-amount-format STR} @tab
@item @code{-J register} @tab @code{--plot-total-format STR} @tab
@item @code{} @tab @code{--equity-format STR} @tab
@item @code{} @tab @code{--prices-format STR} @tab
@item @code{-w register} @tab @code{--wide-register-format STR} @tab
@item @code{} @tab @code{--anon} @tab  Print the ledger register with anonymized accounts and payees, usefule for filing bug reports
@end multitable

@node Grouping Options, Commodity Reporting Quick Reference, Output Customization Quick Reference, Command Line Quick Reference
@subsection Grouping Options
@multitable @columnfractions .1 .25 .65
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
@item @code{-P} @tab @code{--by-payee} @tab Group postings by common payee names
@item @code{-D} @tab @code{--daily} @tab  Group postings by day
@item @code{-W} @tab @code{--weekly} @tab Group postings by week
@item @code{-M} @tab @code{--Monthly} @tab Group postings by month
@item @code{} @tab @code{--quarterly} @tab  Group postings by quarter
@item @code{-Y} @tab @code{--yearly} @tab  Group postings by year
@item @code{-dow} @tab @code{} @tab  Group by day of weeks
@item @code{-s} @tab @code{--subtotal} @tab Group posting together, similar to balance report
@end multitable

@node Commodity Reporting Quick Reference,  , Grouping Options, Command Line Quick Reference
@subsection Commodity Reporting

@multitable @columnfractions .1 .25 .65
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
@item @code{} @tab @code{--price-db FILE} @tab Use @file{FILE} for retrieving downloaded commodity prices
@item @code{-L MINS} @tab @code{--price-exp MINS} @tab Set expected freshness of prices in minutes
@item @code{-Q} @tab @code{--download} @tab Download quotes using @code{getquote}
@item @code{-O} @tab @code{--quantity} @tab  Report commodity totals without conversion
@item @code{-B} @tab @code{--basis} @tab Report cost basis
@item @code{-V} @tab @code{--market} @tab Report last known market value
@item @code{-G} @tab @code{--gain} @tab  Report net gain loss for commodities that have a price history
@end multitable

@node Principles of Accounting, Keeping a Journal, Ledger Tutorial , Top
@chapter Principles of Accounting with Ledger


@menu
* Accounting with Ledger::      
* Stating where money goes::    
* Assets and Liabilities::      
* Typical queries::             
* Commodities and Currencies::  
* Accounts and Inventories::    
* Understanding Equity::        
* Dealing with Petty Cash::     
* Working with multiple funds and accounts::  
@end menu


@node Accounting with Ledger, Stating where money goes, Principles of Accounting, Principles of Accounting
@section Accounting with Ledger

Accounting is simply tracking your money.  It can range from nothing,
and just waiting for automatic overdraft protection to kick in, or not,
to a full blown double entry accounting system.  Ledger accomplishes the
latter.  With ledger you can handle your personal finances or you
businesses.  Double-entry accounting scales.  


@node Stating where money goes, Assets and Liabilities, Accounting with Ledger, Principles of Accounting
@section Stating where money goes

Accountants will talk of ``credits'' and ``debits'', but the meaning
is often different from the layman's understanding.  To avoid
confusion, Ledger uses only subtractions and additions, although the
underlying intent is the same as standard accounting principles.

Recall that every posting will involve two or more accounts.
Money is transferred from one or more accounts to one or more other
accounts.  To record the posting, an amount is @emph{subtracted}
from the source accounts, and @emph{added} to the target accounts.

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

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

Why is the Income a negative figure?  When you look at the balance
totals for your ledger, you may be surprised to see that Expenses are
a positive figure, and Income is a negative figure.  It may take some
getting used to, but to properly use a general ledger you must think
in terms of how money moves.  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 than when you started your ledger.  Make sense?

@node Assets and Liabilities, Typical queries, Stating where money goes, Principles of Accounting
@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 transaction:

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

Money, here, comes from an Income account belonging to ``My
Employer'', and is transferred to your checking account.  The money is
now yours, which makes it an Asset.

Liabilities track money owed to others.  This can happen when you
borrow money to buy something, or if you owe someone money.  Here is
an example of increasing a MasterCard liability by spending money with
it:

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

The Dining account balance now shows $25 spent on Dining, and a
corresponding $25 owed on the MasterCard---and therefore shown as
$-25.00.  The MasterCard liability shows up as negative because it
offsets the value of your assets.

The combined total of your Assets and Liabilities is your net worth.
So to see your current net worth, use this command:

@example
ledger balance ^assets ^liabilities
@end example

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

@example
ledger balance ^income ^expenses
@end example

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
your 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:

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

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

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

This deposits the money owed from Company XYZ into a checking account,
presumably because they paid the amount 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 posting is best handled with mirrored postings 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 postings, so those are what is shown here.  First, the
personal transaction, which shows the need for reimbursement:

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

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 transaction
should be immediately followed by an equivalent transaction, which shows the
kind of expense, and also notes the fact that $100.00 is now payable
to you:

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

This second transaction 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 transactions can also be merged, to make things a little clearer.
Note that all amounts must be specified now:

@smallexample
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 smallexample

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:

@smallexample
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 smallexample

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 transactions 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 postings in
separate files, just separate the two transactions that were joined above.
For example, for both the expense and the pay-back shown above, the
following four transactions would be created.  Two in your personal ledger
file:

@smallexample
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 smallexample

And two in your company ledger file:

@smallexample
!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 smallexample

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

After creating these transactions, 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 Typical queries, Commodities and Currencies, Assets and Liabilities, Principles of Accounting
@section Typical queries

A query such as the following shows all expenses since last
October, sorted by total:

@example
ledger -b "last oct" -s -S T bal ^expenses
@end example

From left to right the options mean: Show transactions since October, 2003;
show all sub-accounts; sort by the absolute value of the total; and
report the balance for all expenses.

@menu
* Reporting monthly expenses::  
* Visualizing with Gnuplot::    
@end menu

@node Reporting monthly expenses, Visualizing with Gnuplot, Typical queries, Typical queries
@subsection Reporting monthly expenses

The following query makes it easy to see monthly expenses, with each
month's expenses sorted by the amount:

@example
ledger -M --period-sort t reg ^expenses
@end example

Now, you might wonder where the money came from to pay for these
things.  To see that report, add @option{-r}, which shows the
``related account'' postings:

@example
ledger -M --period-sort t -r reg ^expenses
@end example

But maybe this prints too much information.  You might just want to
see how much you're spending with your MasterCard.  That kind of query
requires the use of a display predicate, since the postings
calculated must match @samp{^expenses}, while the postings
displayed must match @samp{mastercard}.  The command would be:

@example
ledger -M -r -d /mastercard/ reg ^expenses
@end example

This query says: Report monthly subtotals; report the ``related
account'' postings; display only related postings whose
account matches @samp{mastercard}, and base the calculation on
postings matching @samp{^expenses}.

This works just as well for report the overall total, too:

@example
ledger -s -r -d /mastercard/ reg ^expenses
@end example

The @option{-s} option subtotals all postings, just as @option{-M}
subtotaled by the month.  The running total in both cases is off,
however, since a display expression is being used.

@node Visualizing with Gnuplot,  , Reporting monthly expenses, Typical queries
@subsection Visualizing with Gnuplot

If you have @command{Gnuplot} installed, you can graph any of the
above register reports.  The script to do this is included in the
ledger distribution, and is named @file{scripts/report}.  Install
@file{report} anywhere along your @env{PATH}, and then use
@command{report} instead of @command{ledger} when doing a register
report.  The only thing to keep in mind is that you must specify
@option{-j} or @option{-J} to indicate whether Gnuplot should plot the
amount, or the running total.  For example, this command plots total
monthly expenses made on your MasterCard.

@example
report -j -M -r -d /mastercard/ reg ^expenses
@end example

The @command{report} script is a very simple Bourne shell script, that
passes a set of scripted commands to Gnuplot.  Feel free to modify the
script to your liking, since you may prefer histograms to line plots,
for example.

@menu
* Typical plots::               
@end menu

@node Typical plots,  , Visualizing with Gnuplot, Visualizing with Gnuplot
@subsubsection Typical plots

Here are some useful plots:

@smallexample
report -j -M reg ^expenses         # monthly expenses
report -J reg checking             # checking account balance
report -J reg ^income ^expenses    # cash flow report

# net worth report, ignoring non-$ postings

report -J -l "Ua>=@{\$0.01@}" reg ^assets ^liab

# net worth report starting last February.  the use of a display
# predicate (-d) is needed, otherwise the balance will start at
# zero, and thus the y-axis will not reflect the true balance

report -J -l "Ua>=@{\$0.01@}" -d "d>=[last feb]" reg ^assets ^liab
@end smallexample

The last report uses both a calculation predicate (@option{-l}) and a
display predicate (@option{-d}).  The calculation predicates limits
the report to postings whose amount is greater than $1 (which can
only happen if the posting amount is in dollars).  The display
predicate limits the transactions @emph{displayed} to just those since last
February, even those transactions from before then will be computed as part
of the balance.


@node Commodities and Currencies, Accounts and Inventories, Typical queries, Principles of Accounting
@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
50 EUR         ; currency: 50 Euros (or 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:

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

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 any commodity, in which case the balance will be computed in terms
of that commodity.  The usual way to specify prices is with a price
history file, which might look like this:

@smallexample
P 2004/06/21 02:18:01 FEQTX $22.49
P 2004/06/21 02:18:01 BORL $6.20
P 2004/06/21 02:18:02 AAPL $32.91
P 2004/06/21 02:18:02 AU $400.00
@end smallexample

Specify the price history to use with the @option{--price-db} option,
with the @option{-V} option to report in terms of current market
value:

@example
ledger --price-db prices.db -V balance brokerage
@end example

The balance for your brokerage account will be reported in US dollars,
since the prices database uses that currency.

@smallexample
$40880.00  Assets:Brokerage
@end smallexample

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, in terms of the
current price of gold:

@example
ledger -T "@{1 AU@}*(O/P@{1 AU@})" balance checking
@end example

Although the total expression appears complex, it is simply saying
that the reported total should be in multiples of AU units, where the
quantity is the account total divided by the price of one AU.  Without
the initial multiplication, the reported total would still use the
dollars commodity, since multiplying or dividing amounts always keeps
the left value's commodity.  The result of this command might be:

@smallexample
14.01 AU  Assets:Checking
@end smallexample

@menu
* Commodity Price Histories::   
* Commodity equivalencies::     
@end menu

@node Commodity Price Histories, Commodity equivalencies, 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 transactions might look like those below:

@smallexample
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 smallexample

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, use one of the commodity reporting options.

@node Commodity equivalencies,  , Commodity Price Histories, Commodities and Currencies
@subsection Commodity equivalencies

Sometimes a commodity has several forms which are all equivalent.  An
example of this is time.  Whether tracked in terms of minutes, hours
or days, it should be possible to convert between the various forms.
Doing this requires the use of commodity equivalencies.

For example, you might have the following two postings, one which
transfers an hour of time into a @samp{Billable} account, and another
which decreases the same account by ten minutes.  The resulting report
will indicate that fifty minutes remain:

@smallexample
2005/10/01 Work done for company
    Billable:Client                 1h
    Project:XYZ
    
2005/10/02 Return ten minutes to the project
    Project:XYZ                    10m
    Billable:Client
@end smallexample

Reporting the balance for this ledger file produces:

@smallexample
       50.0m  Billable:Client
      -50.0m  Project:XYZ
@end smallexample

This example works because ledger already knows how to handle seconds,
minutes and hours, as part of its time tracking support.  Defining
other equivalencies is simple.  The following is an example that
creates data equivalencies, helpful for tracking bytes, kilobytes,
megabytes, and more:

@smallexample
C 1.00 Kb = 1024 b
C 1.00 Mb = 1024 Kb
C 1.00 Gb = 1024 Mb
C 1.00 Tb = 1024 Gb
@end smallexample

Each of these definitions correlates a commodity (such as @samp{Kb})
and a default precision, with a certain quantity of another commodity.
In the above example, kilobytes are reporetd with two decimal places
of precision and each kilobyte is equal to 1024 bytes.

Equivalency chains can be as long as desired.  Whenever a commodity
would report as a decimal amount (less than @samp{1.00}), the next
smallest commodity is used.  If a commodity could be reported in terms
of a higher commodity without resulting to a partial fraction, then
the larger commodity is used.

@node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Principles of Accounting
@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:

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

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 @samp{Places:Black's Tavern} as the source account.  You
could use @samp{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 transaction
would look like:

@smallexample
10/2  Sturm Brightblade
    EverQuest:Inventory                     -2 Steaks
    EverQuest:Inventory                     15 Gold
@end smallexample

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

@node Understanding Equity, Dealing with Petty Cash, Accounts and Inventories, Principles of Accounting
@section Understanding Equity

The most confusing transaction 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 a transaction to your ledger to reflect this amount.
Where will money come from?  The answer: your equity.

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

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

@node Dealing with Petty Cash, Working with multiple funds and accounts, Understanding Equity, Principles of Accounting
@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 postings, 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 @samp{Expenses:Cash} category:

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

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

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

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

@node Working with multiple funds and accounts,  , Dealing with Petty Cash, Principles of Accounting
@section Working with multiple funds and accounts

There are situations when the accounts you're tracking are different
between your clients and the financial institutions where money is
kept.  An example of this is working as the treasurer for a religious
institution.  From the secular point of view, you might be working
with three different accounts:

@itemize
@item Checking
@item Savings
@item Credit Card
@end itemize

From a religious point of view, the community expects to divide its
resources into multiple ``funds'', from which it makes purchases or
reserves resources for later:

@itemize
@item School fund
@item Building fund
@item Community fund
@end itemize

The problem with this kind of setup is that when you spend money, it
comes from two or more places at once: the account and the fund.  And
yet, the correlation of amounts between funds and accounts is rarely
one-to-one.  What if the school fund has @samp{$500.00}, but
@samp{$400.00} of that comes from Checking, and @samp{$100.00} from
Savings?

Traditional finance packages require that the money reside in only one
place.  But there are really two ``views'' of the data: from the
account point of view and from the fund point of view -- yet both sets
should reflect the same overall expenses and cash flow.  It's simply
where the money resides that differs.

This situation can be handled one of two ways.  The first is using
virtual postings to represent the fact that money is moving to and
from two kind of accounts at the same time:

@smallexample
2004/03/20 Contributions
    Assets:Checking                    $500.00
    Income:Donations

2004/03/25 Distribution of donations
    [Funds:School]                     $300.00
    [Funds:Building]                   $200.00
    [Assets:Checking]                 $-500.00
@end smallexample

The use of square brackets in the second transaction ensures that the
virtual postings balance to zero.  Now money can be spent directly
from a fund at the same time as money is drawn from a physical
account:

@smallexample
2004/03/25 Payment for books (paid from Checking)
    Expenses:Books                    $100.00
    Assets:Checking                  $-100.00
    (Funds:School)                   $-100.00
@end smallexample

When reports are generated, by default they'll appear in terms of the
funds.  In this case, you will likely want to mask out your
@samp{Assets} account, because otherwise the balance won't make much
sense:

@example
ledger bal -^Assets
@end example

If the @option{--real} option is used, the report will be in terms of
the real accounts:

@example
ledger --real bal
@end example

If more asset accounts are needed as the source of a posting, just
list them as you would normally, for example:

@smallexample
2004/03/25 Payment for books (paid from Checking)
    Expenses:Books                    $100.00
    Assets:Checking                   $-50.00
    Liabilities:Credit Card           $-50.00
    (Funds:School)                   $-100.00
@end smallexample

The second way of tracking funds is to use transaction codes.  In this
respect the codes become like virtual accounts that embrace the entire
set of postings.  Basically, we are associating a transaction with a
fund by setting its code.  Here are two transactions that desposit money
into, and spend money from, the @samp{Funds:School} fund:

@smallexample
2004/03/25 (Funds:School) Donations
    Assets:Checking                   $100.00
    Income:Donations

2004/04/25 (Funds:School) Payment for books
    Expenses:Books                     $50.00
    Assets:Checking
@end smallexample

Note how the accounts now relate only to the real accounts, and any
balance or registers reports will reflect this.  That the transactions
relate to a particular fund is kept only in the code.

How does this become a fund report?  By using the
@option{--code-as-payee} option, you can generate a register report
where the payee for each posting shows the code.  Alone, this is
not terribly interesting; but when combined with the
@option{--by-payee} option, you will now see account subtotals for any
postings related to a specific fund.  So, to see the current
monetary balances of all funds, the command would be:

@smallexample
ledger --code-as-payee -P reg ^Assets
@end smallexample

Or to see a particular funds expenses, the @samp{School} fund in this
case:

@smallexample
ledger --code-as-payee -P reg ^Expenses -- School
@end smallexample

Both approaches yield different kinds of flexibility, depending on how
you prefer to think of your funds: as virtual accounts, or as tags
associated with particular transactions.  Your own tastes will decide which
is best for your situation.


@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::            
* Currency and Commodities::    
* Structuring Your Accounts::   
* Advanced Transactions::       
* File Format::                 
* Archiving Previous Years ::   
@end menu

@node Most Basic Entry, Currency and 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}).



@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}

@menu
* Checking Balances::           
@end menu

@node Checking Balances,  , Most Basic Entry, Most Basic Entry
@subsection Checking balances


Ledger 3.0 has a new feature for confirming  
known past balances.  Here's an example entry:

@smallexample
   2008/11/26 (Interest) EXTND INS SWEEP ACCT(FDIC-INS)
       * Assets:Brokerage                 $0.07 = $970.64
       Income:Interest                   $-0.07
@end smallexample

What this says is that as of 11/26/08 (bank perspective), the
Assets:Brokerage account was known to equal $970.64.  It @strong{must}
equal this amount at this point in the Ledger file, or there will be a
balancing error.

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

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

For the rest of this manual, we will only use the word ``commodities''
when refering to the units on a transaction value.

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 have
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                               E50.00
    Assets:Checking                          $-66.00

2011/09/24 Dinner in Munich
    Expenses:Business:Travel                  E35.00
    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.00 Euros was spent on Dinner
in Munich.

Running a ledger balance report shows:
@smallexample
$ ledger -f example.dat bal 
             $-66.00
              E15.00  Assets
              E15.00    Cash
             $-66.00    Checking
              E35.00  Expenses:Business:Travel
--------------------
             $-66.00
              E50.00
@end smallexample

The top two lines show my current assets as $-66.00 in checking (in this
very short example I didn't establish opening an opening balance for the
checking account) and E15.00.  After spending on dinner i have E15.00 in
my wallet.  The bottom line balances to zero, but is shown in two lines
since we haven't told ledger to convert commodities.


@node Structuring Your Accounts, Advanced Transactions, Currency and 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:
@enumerate
@item 
Expenses: where money goes
@item 
Assets: where money sits
@item
Income: where moeny comes from
@item
Liabilities: money you owe
@item 
Equity: the real value of your property. 
@end enumerate

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.

Beneath these top level accounts you can have any level of detail you
desire.  For example, if you want to keep specific track of how much you spend on
burgers and fries, you could have the following:
@smallexample
Expenses:Food:Hamburgers and Fries
@end smallexample




@node Advanced Transactions, File Format, Structuring Your Accounts, Keeping a Journal
@section Advanced Transactions
@menu
* Transaction Notes and Tags::  
* Multiple Account Transactions::  
* Virtual Transactions::        
* Automatic Transactions::      
* Periodic Transactions::       
* Recording Commodity Lot Prices::  
* Commodity Pricing Problem::   
@end menu

@node Transaction Notes and Tags, Multiple Account Transactions, Advanced Transactions, Advanced Transactions
@subsection 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
   ledger 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.

If a posting comment is a date (with brackets), it modifies the date for that posting:
@smallexample
2010/02/01 Sample
  Assets:Bank  $400.00
  Income:Check  $-400.00 ; [2010/01/01]
@end smallexample
You can use metadata to override the payee field for individual postings within a transaction: (source)

@smallexample 
2010/06/17 Sample
  Assets:Bank  $400.00
  Income:Check1  $-100.00 ; Payee: Person One
  Income:Check2  $-100.00 ; Payee: Person Two
  Income:Check3  $-100.00 ; Payee: Person Three
  Income:Check4  $-100.00 ; Payee: Person Four
@end smallexample
Metadata are normally strings, but you can create metadata of other types:

@smallexample 
2010/06/17 Sample
  Assets:Bank  $400.00
  Income:Check1  $-100.00
  ; Date:: [2010/09/01]
  ; Amount:: $100.00
@end smallexample
(Note that this Date tag is not the same as the posting date.)

There are now tag/pop directives, to apply metadata to a range of transactions (and their postings). For example, if you wanted a conceptual "page" of transactions relating to business trip to Chicago, you could do this:

@smallexample
 tag Location: Chicago
 tag Purpose: Business

 ... transactions go here

 pop
 pop
@end smallexample
It would be as if you'd applied "; Location: Chicago", etc., to every transaction.

@node Multiple Account Transactions, Virtual Transactions, Transaction Notes and Tags, Advanced Transactions
@subsection Multiple Account Transactions

Often times a transaction needs to be split across several accounts.  This is trivially simple in a Ledger journal:

@smallexample
2011/09/15 * Deposit Acme Bytepumps Monthly Paycheck
    Income:Taxable:Acme Bytepumps Inc.     $-2500.00
    Assets:Brokerage:Checking                $175.00
    Assets:Investments:401K Deferred         $250.00
    Expenses:Tax:Medicare                     $36.25
    Expenses:Tax:Federal Tax                 $200.00
    Expenses:Tax:State Tax                    $20.00
    Expenses:Insurance:Life                   $18.75
    Assets:Credit Union:Joint Checking     
@end smallexample

This is an example of a paycheck entry.  THe money comes OUT of your
income account, and is spent into several other accounts.  The last line
doesn't require an amount, as ledger will automatically balance the
transaction (it will be $1800 into the Joint Checking account)


@node Virtual Transactions, Automatic Transactions, Multiple Account Transactions, Advanced Transactions
@subsection Virtual Transactions


A virtual posting 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 posting, surround the account name in
parentheses.  This form of usage does not need to balance.  However,
if you want to ensure the virtual posting balances with other
virtual postings in the same transaction, use square brackets.  For
example:

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

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

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

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 @samp{Savings:Trip}, although no money has actually
moved anywhere.

When balances are displayed, virtual postings will be factored in.
To view balances without any virtual balances factored in, using the
@option{-R} flag, for ``reality''.


@node Automatic Transactions, Periodic Transactions, Virtual Transactions, Advanced Transactions
@subsection Automatic Transactions

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

Ledger makes this otherwise difficult law very easy.  Just set up an
automated posting at the top of your ledger file:

@smallexample
; This automated transaction will compute Huqúqu'lláh based on this
; journal's postings.  Any that match will affect the
; Liabilities:Huququ'llah account by 19% of the value of that posting.

= /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/
  (Liabilities:Huququ'llah)               0.19
@end smallexample

This automated posting works by looking at each posting in the
ledger file.  If any match the given value expression, 19% of the
posting's value is applied to the @samp{Liabilities:Huququ'llah}
account.  So, if $1000 is earned from @samp{Income:Salary}, $190 is
added to @samp{Liabilities:Huqúqu'lláh}; if $1000 is spent on Rent,
$190 is subtracted.  The ultimate balance of Huqúqu'lláh reflects how
much is owed in order to fulfill one's obligation to Huqúqu'lláh.
When ready to pay, just write a check to cover the amount shown in
@samp{Liabilities:Huququ'llah}.  That transaction would look like:

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

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

@smallexample
ledger balance Liabilities:Huquq
@end smallexample

This works fine, but omits one aspect of the law: that Huquq is only
due once the liability exceeds the value of 19 mithqáls of gold (which
is roughly 2.22 ounces).  So what we want is for the liability to
appear in the balance report only when it exceeds the present day
value of 2.22 ounces of gold.  This can be accomplished using the
command:

@smallexample
ledger -Q -t "/Liab.*Huquq/?(a/P@{2.22 AU@}<=@{-1.0@}&a):a" -s bal liab
@end smallexample

With this command, the current price for gold is downloaded, and the
Huqúqu'lláh is reported only if its value exceeds that of 2.22 ounces
of gold.  If you wish the liability to be reflected in the parent
subtotal either way, use this instead:

@smallexample
ledger -Q -T "/Liab.*Huquq/?(O/P@{2.22 AU@}<=@{-1.0@}&O):O" -s bal liab
@end smallexample

In some cases, you may wish to refer to the account of whichever
posting matched your automated transaction's value expression.  To do
this, use the special account name @samp{$account}:

@smallexample
= /^Some:Long:Account:Name/
  [$account]  -0.10
  [Savings]    0.10
@end smallexample

This example causes 10% of the matching account's total to be deferred
to the @samp{Savings} account---as a balanced virtual posting,
which may be excluded from reports by using @option{--real}.

Automated transactions can use the full range of value expressions in
their predicate.  If you wanted to specify a transaction only occur to
certain accounts that meet cetain value criteria you could specify:

@smallexample
= /Employees:.*:Payroll$/ and expr (amount >= $1000 and amount < $10000)
  Expenses:Tax  0.27
@end smallexample
In this case, @samp{amount} is tied to the amount of the posting being
tested.

But, wait! There's more!

In the short example above we calculated the taxes due for income within
a certain bracket.  But in reality this calculation is more difficult.
There are different rate for difference marginal incomes and those taxes
are not easily descirbe by a simple multiplicative coefficient.
Automated transaction can use value expressions in there posting to
determine the ammounts.  So to expand the example above for a three tax
bracket system we could enter:

@smallexample
= /Employees:.*:Payroll$/ and expr (amount < $10000.00)
  (Expenses:Tax)  0.1
= /Employees:.*:Payroll$/ and expr (amount > $10000.00 and amount < $100000.00 )
  (Expenses:Tax)  ($1000.00 + .15 * (amount - $10000.00))
= /Employees:.*:Payroll$/ and expr (amount > $100000.00)
  (Expenses:Tax)  ($13500.00 + .20 * (amount-$100000.00))
@end smallexample


@node Periodic Transactions, Recording Commodity Lot Prices, Automatic Transactions, Advanced Transactions
@subsection Periodic Transactions

A periodic transaction starts with a ~ followed by a period expression.
Periodic transactions are used for budgeting and forecasting only, they
have no effect withouth the @samp{--budget} option specified.

See @ref{Budgeting and Forecasting} for examples and details.

@node Recording Commodity Lot Prices, Commodity Pricing Problem, Periodic Transactions, Advanced Transactions
@subsection Recording Commodity Lot Prices

If you are tracking investments it is often necessary to keep track of
specific purchases of a commodity bought at difference prices.  These
specific purchases are referred to as ``lots''.  Tracking lots using ledger
requires some additional info in the journal as well as additional
command-line options when generating reports.

Say you want to record purchase of two separate lots of ACME, then sell
some shares.  The correct way to do this is:

@smallexample
2010-09-01 * Buy 2 shares of ACME @@ $100
   Assets:Broker                                  2 ACME @@ $100.00
   Assets:Cash

2010-09-10 * Buy 2 share of ACME @@ $110
   Assets:Broker                                  2 ACME @@ $110.00
   Assets:Cash

2011-09-20 * Sell 2 shares of ACME @@ $150
   Assets:Broker                       -1 ACME @{$100.00@} @@ $150.00
   Assets:Broker                       -1 ACME @{$200.00@} @@ $150.00
   Assets:Cash
@end smallexample

To report which lots of commodities you hold, use the
@samp{--lot-prices} option.  For example, after buying the 2 shares at
$100 and 1 at $200 it would show you:
@smallexample
$ ledger balance --lot-prices Assets:Broker until 2011-09-15
    2 ACME @{$100.00@}
    1 ACME @{$200.00@}  Assets:Broker
@end smallexample
@noindent without the @samp{--lot-prices} option you would only see the total number of shares you held:
@smallexample
$ ledger balance  Assets:Broker until 2011-09-15
    3 ACME  Assets:Broker
@end smallexample
@noindent and after the sale on @samp{2011-09-20} it would show you:
@smallexample
$ ledger balance --lot-prices Assets:Broker
    1 ACME @{$100.00@}  Assets:Broker
@end smallexample

@node Commodity Pricing Problem,  , Recording Commodity Lot Prices, Advanced Transactions
@subsection  Commodity Valuation

[THIS SUBSECTION COULD BELONG IN REPORTING SECTION, OR MAYBE EVEN SPLIT BETWEEN THE TWO]


Often you will be more interested in the value of your entire holdings, in
your preferred currency.  It might be nice to know you hold 10,000 shares
of PENNY, but you are more interested in whether or not that is worth
$1000.00 or $10,000.00.  However, the current day value of a commodity can
mean different things to different people, depending on the accounts
involved, the commodities, the nature of the transactions, etc.

When you specify @samp{-V}, or @samp{-X COMM}, you are requesting that
some or all of the commodities be valuated as of today (or whatever
@samp{--now} is set to).  But what does such a valuation mean?  This
meaning is governed by the presence of a @samp{VALUE} metadata
property, whose content is an expression used to compute that value.

If no VALUE property is specified, each posting is assumed to have a default,
as if you'd specified a global, automated transaction as follows:

@smallexample
  = expr true
    ; VALUE:: market(amount, date, exchange)
@end smallexample
This definition emulates the present day behavior of -V and -X (in the case of
-X, the requested commodity is passed via the string 'exchange' above).

One thing many people have wanted to do is to fixate the valuation of old
European currencies in terms of the Euro after a certain date:

@smallexample
  = expr commodity == "DM"
    ; VALUE:: date < [Jun 2008] ? market(amount, date, exchange) : 1.44 EUR
@end smallexample

This says: If --now is some old date, use market prices as they were at that
time; but if --now is past June 2008, use a fixed price for converting Deutsch
Mark to Euro.

Or how about never re-valuating commodities used in Expenses, since they
cannot have a different future value:

@smallexample
  = /^Expenses:/
    ; VALUE:: market(amount, post.date, exchange)
@end smallexample

This says the future valuation is the same as the valuation at the time of
posting.  post.date equals the posting's date, while just 'date' is the value
of --now (defaults to today).

Or how about valuating miles based on a reimbursement rate during a specific
time period:


@smallexample
  = expr commodity == "miles" and date >= [2007] and date < [2008]
    ; VALUE:: market($1.05, date, exchange)
@end smallexample

In this case, miles driven in 2007 will always be valuated at $1.05 each.  If
you use -X EUR to expressly request all amounts in Euro, Ledger shall convert
$1.05 to Euro by whatever means are appropriate for dollars.

Note that you can have a valuation expression specific to a particular posting
or transaction, by overriding these general defaults using specific metadata:

@smallexample

  2010-12-26 Example
      Expenses:Food                $20
      ; Just to be silly, always valuate *these* $20 as 30 DM, no matter what
      ; the user asks for with -V or -X
      ; VALUE:: 30 DM
      Assets:Cash
@end smallexample

This example demonstrates that your VALUE expression should be as symbolic as
possible, using terms like 'amount' and 'date', rather than specific amounts
and dates.  Also, you should pass the amount along to the function 'market' so
it can be further revalued if the user has asked for a specific currency.

Or, if it better suits your accounting, you can be less symbolic, which allows
you to report most everything in EUR if you use -X EUR, except for certain
accounts or postings which should always be valuated in another currency.  For
example:

@smallexample
  = /^Assets:Brokerage:CAD$/
    ; Always report the value of commodities in this account in 
    ; terms of present day dollars, despite what was asked for 
    ; on the command-line VALUE:: market(amount, date, '$')
@end smallexample

I think this scheme, of using predicated value expressions which can be
generalized in automated transactions, and made specific via transaction and
posting-based metadata, provides sufficient flexibility to express most of the
use cases which have occurred on this topic.


Ledger presently has no way of handling such things as FIFO and LIFO.

If you specify an unadorned commodity name, like AAPL, it will balance
against itself.  If --lots are not being displayed, then it will appear
to balance against any lot of AAPL.

If you specify an adorned commodity, like AAPL @{$10.00@}, it will also
balance against itself, and against any AAPL if --lots is not specified.
But if you do specify --lot-prices, for example, then it will balance
against that specific price for AAPL.

I may, for the sake of reporting *only*, be able to implement some sort
of guessing strategy, based on the order in which transactions appear in
the data file...  But I'll have to think about this a lot more, and it
would be a 3.1 thing.

@smallexample
> b) I don't see how this VALUE property can differentiate between -V
> and -B.  Does this imply that you want to get rid of the -B option and
> simply let users define what VALUE they get with -V?  If so, I think
> this would be a bad idea... I really like the ability to see different
> valuation methods using command line options (i.e. -B for cost basis
> and -V for market value).  (Incidentally, while I initially liked your
> example of using the posting date for Expenses, I later realized that
> I sometimes use -V to see what my expenses (in a foreign currency)
> would have been if I bought everything at today's exchange rate.)
@end smallexample
-V and -B are entirely unrelated.  Perhaps I could support a BASIS
property setting, for customizing -B in the same way VALUE
customizes -V...

@smallexample
> c) I never fully understood what -X does exactly but afaik -X is a
> special version of -V.  However, I believe that -X should _only_ do
> conversion.  This would allow -X to be combined with other options,
> such as -X and -V.  Example: let's say I bought 10 shares for 10.00
> GBP and they are now worth 15.00.  Because my main assets are in EUR,
> I want to see what those shares are worth in EUR.  Since I'm
> conservative I want to see the cost basis, i.e. I want to use -B and
> -X EUR together. (This actually works today but I'm told this is an
> accident and won't work in all cases.)
@end smallexample
-V asks for the present day value of all commodities, and lets Ledger
pick the target commodity based on its own hueristics.  -X is the same
as -V, except that it overrides those hueristics and forces the target
commodity.  (Although, as you've seen, the VALUE property could now
countermand that).

There are reasons why -X can't be applied to any report.  Mainly it has
to do with rounding.  For example, let's say I have 10 postings that
each trade 1 DM, and the value of 1 DM is 0.001 EUR.  If I add all
10 DM and then apply -X, I get 0.01 EUR.  But if I apply -X to each
1 DM and *then* total them, I get 0.00 EUR.

This becomes very important to Ledger because -X is applied to totals,
not just to individual amounts.  I'm going to have to use some magic
internally to avoid this problem with the VALUE property (in most, but
not all, cases).

And so, -X gets applied after, when the posting-origin of the
commodities has been lost -- required information if a basis cost
calculation is to be deferred.

The alternative would involve ever-growing lists of individual amounts,
which would slow many parts of Ledger from O(N) to O(N^2).  Plus, it
still wouldn't solve the rounding problem.


> Ledger presently has no way of handling such things as FIFO and LIFO.

Yeah, I know... but I think it's a feature that ledger should
eventually get (obviously not for 3.0).

@smallexample
> If you specify an adorned commodity, like AAPL @{$10.00@}, it will also
> balance against itself, and against any AAPL if --lots is not specified.
> But if you do specify --lot-prices, for example, then it will balance
> against that specific price for AAPL.
> 
> I may, for the sake of reporting *only*, be able to implement some sort
> of guessing strategy, based on the order in which transactions appear in
> the data file...
@end smallexample
Why for reporting only?  It seems to me that ledger has all the
information to do FIFO and LIFO properly (i.e. to remove the right
commodities from the list).  Let's take this example:

@smallexample

2011-01-01 * Buy AAA
    Assets:Shares                             5 AAA @ 10.00 EUR
    Assets:Cash

2011-01-03 * Buy AAA
    Assets:Shares                             2 AAA @ 10.00 EUR
    Assets:Cash

2011-01-11 * Buy AAA
    Assets:Shares                             5 AAA @ 12.00 EUR
    Assets:Cash

2011-01-21 * Buy AAA
    Assets:Shares                             5 AAA @ 13.00 EUR
    Assets:Cash
@end smallexample

So we end up with (ledger --lots):

@smallexample
5 AAA @{10.00 EUR@} [2011/01/01]
2 AAA @{10.00 EUR@} [2011/01/03]
5 AAA @{12.00 EUR@} [2011/01/11]
5 AAA @{13.00 EUR@} [2011/01/21]  Assets:Shares
@end smallexample

So if I sell 6 shares now, according to FIFO, I would do:

@smallexample
2011-02-01 * Sell AAA
    Assets:Shares                          -5 AAA @{10.00 EUR@} [2011/01/01] @ 
13.50 EUR
    Assets:Shares                          -1 AAA @{10.00 EUR@} [2011/01/03] @ 
13.50 EUR
    Assets:Cash
@end smallexample

ledger --lots:

@smallexample
1 AAA @{10.00 EUR@} [2011/01/03]
5 AAA @{12.00 EUR@} [2011/01/11]
5 AAA @{13.00 EUR@} [2011/01/21]  Assets:Shares
@end smallexample

According to LIFO, I would do this instead:

@smallexample
2011-02-01 * Sell AAA
    Assets:Shares                          -5 AAA @{13.00 EUR@} [2011/01/21] @ 
13.50 EUR
    Assets:Shares                          -1 AAA @{12.00 EUR@} [2011/01/11] @ 
13.50 EUR
    Assets:Cash
@end smallexample

In other words, you can manually do FIFO and LIFO with ledger already.
However, it would be great if ledger would make this easier, e.g. that
you could specify:

@smallexample
 2011-02-01 * Sell AAA
    Assets:Shares                          -6 AAA @{FIFO@} @ 13.50 EUR
    Assets:Cash
@end smallexample

and ledger would iterate through all AAA commodities and take out the
right ones (after all, it knows the date and price).

The only thing I don't think is possible with ledger at the moment is
average cost.  I'm also not sure how --lot-dates should behave for
average cost.

@smallexample
> There are reasons why -X can't be applied to any report.  Mainly it has
> to do with rounding.  For example, let's say I have 10 postings that
> each trade 1 DM, and the value of 1 DM is 0.001 EUR.  If I add all
> 10 DM and then apply -X, I get 0.01 EUR.  But if I apply -X to each
> 1 DM and *then* total them, I get 0.00 EUR.
@end smallexample
Thanks for the explanation... what I was thinking of is that ledger
would just produce a report according to -V or -B or whatever and
*then* convert it with -X.  I use a shell script to do this for now:

@smallexample
GBP2EUR="117/100"

eurgbp=$(ledger -f $FILE -p "until $YEAR-$NEXT_MONTH-01" -B bal "^assets" 
"^liabilities" | egrep " (EUR|GBP)$" | tail -n 2)
eur=$(echo "$eurgbp" | grep "EUR" | sed 's/ EUR//')
gbp=$(echo "$eurgbp" | grep "GBP" | sed 's/ GBP//')
eur=$(echo "$eur" | sed 's/\..*//')
gbp=$(echo "$gbp" | sed 's/\..*//')
gbpineur=$(($gbp*$GBP2EUR))
echo "      " $(($eur + $gbpineur)) "   EUR   Total"
@end smallexample

I'm kinda surprised that you no longer think it's a good idea to split
-X from -V.  Last time I brought this up on IRC, you thought it was a
good idea:

@smallexample
10:44 < johnw> I think having -H, in addition to -X, may make what you want
 to see both natural and simple
10:45 < johnw> you'd use -H for income/expense accounts, and -X for
 assets/liabilities
10:45 < johnw> -H = historical values
10:45 < johnw> -X = current exchange values
10:45 < tbm> so what's the difference between -X and -V again?
10:45 < johnw> -V is an automated version of -X
10:45 < johnw> it tries to figure out what the reported commodity should be
10:45 < johnw> we may then need an automated version of -H, to complete the
 reflection
10:46 < johnw> btw, this is just an inside-out version of my "final"
 feature :)
10:46 < tbm> why not change the meaning of -X to _only do conversion_?  And
 then you could combine -X with -B, -V or -H
10:46 < johnw> instead of having it be syntactic, we're moving the semantic
 difference to a difference in options
10:46 < johnw> oh HMM
10:46 < johnw> -X with -B, -V and -I
10:46 < johnw> (and -O, incidentally)
10:46 < johnw> O = amount, B = cost, V = market value, I = price
10:47 < johnw> that's really an excellent suggestion
10:48 < johnw> i'd still need a flag to mean "historical" vs "current"
10:48 < johnw> as well as "target commodity" (-X)
@end smallexample

@node File Format, Archiving Previous Years , Advanced Transactions, Keeping a Journal
@section File Format for Users

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:

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

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:

@smallexample
  ACCOUNT  AMOUNT  [; NOTE]
@end smallexample

The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual
posting, or square brackets if it is a virtual posting 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]}.(See @pxref{Virtual Transactions})

@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(See @pxref{Automatic Transactions}).

@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:
@smallexample
P DATE SYMBOL PRICE
@end smallexample

@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:
@smallexample
N SYMBOL
@end smallexample

@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:
@smallexample
D $1,000.00
@end smallexample

@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:
@smallexample
C 1.00 Kb = 1024 bytes
@end smallexample

@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 ,  , File Format, Keeping a Journal
@section Archiving Previous Years


After a while, your journal can get to be pretty large.  While this will
not slow down Ledger---it's designed to process journals 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: @command{print}, and @command{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 @command{print} to output
all the earlier transactions to a file called @file{ledger-old.dat}:

@smallexample
ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat
@end smallexample

To delete older data from the current ledger file, use @command{print}
again, this time specifying year 2002 as the starting date:

@smallexample
ledger -f ledger.dat -b 2002 print > x
mv x ledger.dat
@end smallexample

However, now the current file contains @emph{only} postings 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:

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

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 Command-line Syntax, Reporting Commands, Keeping a Journal, Top
@chapter Command-line Syntax


@menu
* Basic Usage::                 
* Detailed Options Description::  
* Period Expressions::          
@end menu

@node Basic Usage, Detailed Options Description, Command-line Syntax, Command-line Syntax
@section Basic Usage

This chapter describes Ledger's features and options. 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:

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

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{payee} or @@.  For example, the
following balance command reports account totals for rent, food and
movies, but only those whose payee matches Freddie:

@smallexample
ledger bal rent food movies payee freddie
@end smallexample
@noindent or
@smallexample
ledger bal rent food movies @@freddie
@end smallexample

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 Detailed Options Description, Period Expressions, Basic Usage, Command-line Syntax
@section Detailed Option Description

With all of the reports, command-line options are useful to modify the
output generated.  The basic form for most commands is:

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

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{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{--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:

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

@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 @ref{Virtual Transactions} 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:

@smallexample
ledger -r register food
@end smallexample

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.

@menu
* Search Terms::                
* Output Customization::        
* Commodity Reporting::         
* Environment Variables::       
@end menu

@node Search Terms, Output Customization, Detailed Options Description, Detailed Options Description
@subsection Search Terms

Valid Ledger invocations look like:
@smallexample
 ledger [OPTIONS] <COMMAND> <SEARCH-TERMS>
@end smallexample

Where @samp{COMMAND} is any command verb (@pxref{Reporting Commands}), @samp{OPTIONS} can occur
anywhere, and @samp{SEARCH-TERM} is one or more of the following:

@smallexample
 word              search for any account containing 'word'
 TERM and TERM     boolean AND between terms
 TERM or TERM      boolean OR between terms
 not TERM          invert the meaning of the term
 payee word        search for any payee containing 'word'
 @@word             shorthand for 'payee word'
 desc word         alternate for 'payee word'
 note word         search for any note containing 'word'
 &word             shorthand for 'note word'
 tag word          search for any metadata tag containing 'word'
 tag word=value    search for any metadata tag containing 'word'
                   whose value contains 'value'
 %word             shorthand for 'tag word'
 %word=value       shorthand for 'tag word=value'
 meta word         alternate for 'tag word'
 meta word=value   alternate for 'tag word=value'
 expr 'EXPR'       apply the given value expression as a predicate
 '=EXPR'           shorthand for 'expr EXPR'
 \( TERMS \)     group terms; useful if using and/or/not
@end smallexample

So, to list all transaction that charged to ``ffod'' but not ``dining'' for any payee other than ``chang'' the following three commands would be equivalent:

@smallexample
 ledger reg food not dining @@chang
 ledger reg food and not dining and not payee chang
 ledger reg food not dining expr 'payee =~ /chang/'
@end smallexample

@node Output Customization, Commodity Reporting, Search Terms, Detailed Options Description
@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:

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

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

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

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

@node Commodity Reporting, Environment Variables, Output Customization, Detailed Options Description
@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:

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

@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

@node Environment Variables,  , Commodity Reporting, Detailed Options Description
@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:

@smallexample
--cache /tmp/.mycache
--pager /bin/cat

@end smallexample

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

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

@smallexample
[INTERVAL] [BEGIN] [END]
@end smallexample

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

@smallexample
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 smallexample

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

@smallexample
from <SPEC>
since <SPEC>
@end smallexample

The end time can be either of:

@smallexample
to <SPEC>
until <SPEC>
@end smallexample

Where @var{SPEC} can be any of:

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

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:

@smallexample
<SPEC>
in <SPEC>
@end smallexample

Here are a few examples of period expressions:

@smallexample
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 smallexample


@node Reporting Commands, Budgeting and Forecasting, Command-line Syntax, Top
@chapter Reporting Commands
@menu
* Primary Financial Reports::   
* Reports in other formats::    
* Reports about your Journals::  
* Developer Commands::          
@end menu

@node Primary Financial Reports, Reports in other formats, Reporting Commands, Reporting Commands
@section Primary Financial Reports

@menu
* balance::                     
* equity::                      
* register::                    
* print::                       
@end menu

@node balance, equity, Primary Financial Reports, Primary Financial Reports
@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.
@node equity, register, balance, Primary Financial Reports
@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}.


@menu
* register::                    
* print::                       
@end menu

@node register, print, equity, Primary Financial Reports
@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.

@node print,  , register, Primary Financial Reports
@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.

@node Reports in other formats, Reports about your Journals, Primary Financial Reports, Reporting Commands
@section Reports in other formats
@menu
* csv::                         
* emacs::                       
* org::                         
* pricemap::                    
* xml::                         
* prices and pricedb::          
@end menu

@node csv, emacs, Reports in other formats, Reports in other formats
@subsection csv

@node emacs, org, csv, Reports in other formats
@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:

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

@node org, pricemap, emacs, Reports in other formats
@subsection org
The @code{org} command produces a journal file suitable for use in the
emacs org mode.  More details on using org mode can be found at
@url{http://www.orgmode.org}.

@node pricemap, xml, org, Reports in other formats
@subsection pricemap

@node xml, prices and pricedb, pricemap, Reports in other formats
@subsection xml

By default, Ledger uses a human-readable data format, and displays its
reports in a manner meant to be read on screen.  For the purpose of
writing tools which use Ledger, however, it is possible to read and
display data using XML.  This section documents that format.

The general format used for Ledger data is:

@smallexample
<?xml version="1.0"?>
<ledger>
  <xact>...</xact>
  <xact>...</xact>
  <xact>...</xact>...
</ledger>
@end smallexample

The data stream is enclosed in a @samp{ledger} tag, which contains a
series of one or more transactions.  Each @samp{xact} describes the transaction
and contains a series of one or more postings:

@smallexample
<xact>
  <en:date>2004/03/01</en:date>
  <en:cleared/>
  <en:code>100</en:code>
  <en:payee>John Wiegley</en:payee>
  <en:postings>
    <posting>...</posting>
    <posting>...</posting>
    <posting>...</posting>...
  </en:postings>
</xact>
@end smallexample

The date format for @samp{en:date} is always @samp{YYYY/MM/DD}.  The
@samp{en:cleared} tag is optional, and indicates whether the
posting has been cleared or not.  There is also an
@samp{en:pending} tag, for marking pending postings.  The
@samp{en:code} and @samp{en:payee} tags both contain whatever text the
user wishes.

After the initial transaction data, there must follow a set of postings
marked with @samp{en:postings}.  Typically these postings will
all balance each other, but if not they will be automatically balanced
into an account named @samp{<Unknown>}.

Within the @samp{en:postings} tag is a series of one or more
@samp{posting}'s, which have the following form:

@smallexample
<posting>
  <tr:account>Expenses:Computer:Hardware</tr:account>
  <tr:amount>
    <value type="amount">
      <amount>
        <commodity flags="PT">$</commodity>
        <quantity>90.00</quantity>
      </amount>
    </value>
  </tr:amount>
</posting>
@end smallexample

This is a basic posting.  It may also be begin with
@samp{tr:virtual} and/or @samp{tr:generated} tags, to indicate virtual
and auto-generated postings.  Then follows the @samp{tr:account}
tag, which contains the full name of the account the posting is
related to.  Colons separate parent from child in an account name.

Lastly follows the amount of the posting, indicated by
@samp{tr:amount}.  Within this tag is a @samp{value} tag, of which
there are four different kinds, each with its own format:

@enumerate
@item boolean
@item integer
@item amount
@item balance
@end enumerate

The format of a boolean value is @samp{true} or @samp{false}
surrounded by a @samp{boolean} tag, for example:

@smallexample
<boolean>true</boolean>
@end smallexample

The format of an integer value is the numerical value surrounded by an
@samp{integer} tag, for example:

@smallexample
<integer>12036</integer>
@end smallexample

The format of an amount contains two members, the commodity and the
quantity.  The commodity can have a set of flags that indicate how to
display it.  The meaning of the flags (all of which are optional) are:

@table @strong
@item P
The commodity is prefixed to the value.
@item S
The commodity is separated from the value by a space.
@item T
Thousands markers are used to display the amount.
@item E
The format of the amount is European, with period used as a thousands
marker, and comma used as the decimal point.
@end table

The actual quantity for an amount is an integer of arbitrary size.
Ledger uses the GNU multi-precision math library to handle such
values.  The XML format assumes the reader to be equally capable.
Here is an example amount:

@smallexample
<value type="amount">
  <amount>
    <commodity flags="PT">$</commodity>
    <quantity>90.00</quantity>
  </amount>
</value>
@end smallexample

Lastly, a balance value contains a series of amounts, each with a
different commodity.  Unlike the name, such a value does need to
balance.  It is called a balance because it sums several amounts.  For
example:

@smallexample
<value type="balance">
  <balance>
    <amount>
      <commodity flags="PT">$</commodity>
      <quantity>90.00</quantity>
    </amount>
    <amount>
      <commodity flags="TE">DM</commodity>
      <quantity>200.00</quantity>
    </amount>
  </balance>
</value>
@end smallexample

That is the extent of the XML data format used by Ledger.  It will
output such data if the @command{xml} command is used, and can read
the same data.


@node prices and pricedb,  , xml, Reports in other formats
@subsection prices and pricedb

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{pricedb} command which outputs the same
information as @command{prices}, but does in a format that can be parsed
by Ledger.  This is useful for generating and tidying up pricedb
databasefiles.


@node Reports about your Journals, Developer Commands, Reports in other formats, Reporting Commands
@section Reports about your Journals

@menu
* accounts::                    
* convert::                     
* commodities::                 
* entry and xact::              
* payees::                      
@end menu

@node accounts, convert, Reports about your Journals, Reports about your Journals
@subsection accounts

The @command{accounts} reports all of the accounts in the journal.
Following the command with a regular expression will limit the output to
accounts matching the regex.


@node convert, commodities, accounts, Reports about your Journals
@subsection convert

@node commodities, entry and xact, convert, Reports about your Journals
@subsection commodities
Report all commodities present in the journals under consideration.


@node entry and xact, payees, commodities, Reports about your Journals
@subsection entry and xact

The @code{entry} and @command{xact} commands simplify 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:

@smallexample
ledger entry 2004/4/9 viva food 11 tips 2.50
@end smallexample

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

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

@smallexample
ledger entry 4/9 viva 11.50
ledger entry 4/9 viva 11.50 checking # (from `checking')
ledger entry 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 smallexample

@command{xact} is identical to @command{entry} and is provide for
backwards compatibility with Ledger 2.X.

@node payees,  , entry and xact, Reports about your Journals
@subsection payees
The @command{payees} reports all of the unique payees in the journal. To filter the payes displayed you must use the @@ prefix:
@smallexample
macbook-2:$ ledger payees '@@Tar.+t'
El Dorade Restaraunt
My Big Fat Greek Restaraunt
Target
macbook-2:$
@end smallexample 




@node Developer Commands,  , Reports about your Journals, Reporting Commands
@section Developer Commands
@menu
* echo::                        
* reload::                      
* source::                      
* Pre-commands::                
@end menu

@node echo, reload, Developer Commands, Developer Commands
@subsection echo
This command simply echos its argument back to the output.


@node reload, source, echo, Developer Commands
@subsection reload
Forces ledger to reload any journal files.  This function exists to
support external programs controlling a running ledger process and does
nothing for a command line user.

@node source, Pre-commands, reload, Developer Commands
@subsection source

@node Pre-commands,  , source, Developer Commands
@subsection Pre-Commands
@table @code
@item args
@item eval
@item expr
@item format
@item generate
@item parse
@item period
@item query
@item template
@end table


@menu
* Budgeting and Forecasting::   
@end menu

@node Budgeting and Forecasting, Value Expressions, Reporting Commands, Top
@chapter Budgeting and Forecasting

@menu
* Budgeting::                   
* Forecasting::                 
@end menu

@node Budgeting, Forecasting, Budgeting and Forecasting, Budgeting and Forecasting
@section Budgeting

Keeping a budget allows you to pay closer attention to your income and
expenses, by reporting how far your actual financial activity is from
your expectations.

To start keeping a budget, put some periodic transactions
(@pxref{Periodic Transactions}) at the top of your ledger file.  A
period transaction is almost identical to a regular transaction, except
that it begins with a tilde and has a period expression in place of a
payee.  For example:

@smallexample
~ Monthly
  Expenses:Rent               $500.00
  Expenses:Food               $450.00
  Expenses:Auto:Gas           $120.00
  Expenses:Insurance          $150.00
  Expenses:Phone              $125.00
  Expenses:Utilities          $100.00
  Expenses:Movies              $50.00
  Expenses                    $200.00  ; all other expenses
  Assets

~ Yearly
  Expenses:Auto:Repair        $500.00
  Assets
@end smallexample

These two period transactions give the usual monthly expenses, as well as
one typical yearly expense.  For help on finding out what your average
monthly expense is for any category, use a command like:

@example
ledger -p "this year" --monthly --average --subtotal balance ^expenses
@end example

The reported totals are the current year's average for each account.

Once these period transactions are defined, creating a budget report is as
easy as adding @option{--budget} to the command-line.  For example, a
typical monthly expense report would be:

@example
ledger --monthly register ^expenses
@end example

To see the same report balanced against your budget, use:

@example
ledger --budget --monthly register ^expenses
@end example

A budget report includes only those accounts that appear in the
budget.  To see all expenses balanced against the budget, use
@option{--add-budget}.  You can even see only the unbudgeted expenses
using @option{--unbudgeted}:

@example
ledger --unbudgeted --monthly register ^expenses
@end example

You can also use these flags with the @command{balance} command.

@node Forecasting,  , Budgeting, Budgeting and Forecasting
@section Forecasting

Sometimes it's useful to know what your finances will look like in the
future, such as determining when an account will reach zero.  Ledger
makes this easy to do, using the same period transactions as are used for
budgeting.  An example forecast report can be generated with:

@example
ledger --forecast "T>@{\$-500.00@}" register ^assets ^liabilities
@end example

This report continues outputting postings until the running total
is greater than $-500.00.  A final posting is always output, to
show you what the total afterwards would be.

Forecasting can also be used with the balance report, but by date
only, and not against the running total:

@example
ledger --forecast "d<[2010]" bal ^assets ^liabilities
@end example


@node Value Expressions, Format Strings, Budgeting and Forecasting, 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:

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

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:

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

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:

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

@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

@menu
* Basics::                      
* Format Expressions::          
* --balance-format::            
* New formatting codes::        
@end menu

@node Basics, Format Expressions, Format Strings, Format Strings
@section Format String Basics
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 string, a substitution is specified using a percent
character (@samp{%}).  The basic format of all substitutions is:

@smallexample
%[-][MIN WIDTH][.MAX WIDTH](VALEXPR)
@end smallexample

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:

@smallexample
%-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 smallexample

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

@node Format Expressions, --balance-format, Basics, Format Strings
@section Format Expressions

 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 --balance-format, New formatting codes, Format Expressions, Format Strings
@section --balance-format

As an example of how flexible the --format strings can be, the default balance format looks like this:

@smallexample
         "%(justify(scrub(display_total), 20, -1, true, color))"
         "  %(!options.flat ? depth_spacer : \"\")"
         "%-(ansify_if(partial_account(options.flat), blue if color))\n%/"
         "%$1\n%/"
         "--------------------\n"
@end smallexample

@node New formatting codes,  , --balance-format, Format Strings
@section New Formatting Codes

@menu
* Field Widths::                
* Colors::                      
* Quantities and Calculations::  
* Dates::                       
* Text Formatting::             
* Misc::                        
@end menu

@node Field Widths, Colors, New formatting codes, New formatting codes
@subsection Field Widths
@multitable @columnfractions .3 .2 .5
@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description}
@item @code{date_width}
@item @code{payee_width}
@item @code{account_width}
@item @code{amount_width}
@item @code{total_width}
@end multitable

@node Colors, Quantities and Calculations, Field Widths, New formatting codes
@subsection Colors

The character based formatting ledger can do is limited to the ANSI terminal character colors and font highlight in a normal TTY seesion.  
@multitable @columnfractions .3 .3 .3
@item @code{red} @tab @code{magenta} @tab @code{bold}
@item @code{green } @tab @code{cyan} @tab @code{underline}
@item @code{yellow } @tab @code{white} @tab @code{blink}
@item @code{blue } 
@end multitable



@node Quantities and Calculations, Dates, Colors, New formatting codes
@subsection Quantities and Calcuations



@multitable @columnfractions .3 .2 .5
@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description}
@item @code{amount_expr } @tab @code{} @tab 
@item @code{abs} @tab @code{U} @tab 
@item @code{commodity } @tab @code{} @tab 
@item @code{display_amount } @tab @code{t} @tab
@item @code{display_total } @tab @code{T} @tab 
@item @code{floor } @tab @code{} @tab 
@item @code{get_at } @tab @code{} @tab 
@item @code{is_seq } @tab @code{} @tab 
@item @code{market } @tab @code{P} @tab 
@item @code{percent } @tab @code{} @tab 
@item @code{price } @tab @code{} @tab 
@item @code{quantity } @tab @code{} @tab 
@item @code{rounded } @tab @code{} @tab 
@item @code{truncated } @tab @code{} @tab 
@item @code{total_expr } @tab @code{} @tab 
@item @code{top_amount } @tab @code{} @tab 
@item @code{to_boolean } @tab @code{} @tab 
@item @code{to_int } @tab @code{} @tab 
@item @code{to_amount } @tab @code{} @tab 
@item @code{to_balance } @tab @code{} @tab 
@item @code{unrounded } @tab @code{} @tab 
@end multitable
      
@node Dates, Text Formatting, Quantities and Calculations, New formatting codes
@subsection Dates

@multitable @columnfractions .3 .2 .5
@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description}
@item @code{date } @tab @code{} @tab 
@item @code{format_date } @tab @code{} @tab 
@item @code{now } @tab @code{} @tab   --> d m
@item @code{today } @tab @code{} @tab 
@item @code{to_datetime } @tab @code{} @tab 
@item @code{to_date } @tab @code{} @tab 
@item @code{value_date } @tab @code{} @tab 
@end multitable

@node Text Formatting, Misc, Dates, New formatting codes
@subsection Text Formatting
@subsubsection Summary
@multitable @columnfractions .6 .4
@item @strong{Function}  @tab @strong{Description}
@item @code{ansify_if(str,color) } @tab Colorize the string
@item @code{justify(str, fwidth, lwidth, right, colorize) }  @tab Right or left justify the string.
@item @code{join(str) } @tab Remove line feeds from the input string.  Mainly used internaally for org-mode output 
@item @code{quoted(str) } @tab Returns @code{"<str>"}. 
@item @code{strip } @tab @code{Removes additional annotations from values.}
@item @code{scrub } @tab @code{S} 
@item @code{should_bold } @tab @code{} 
@end multitable
@subsubsection Detailed Descriptions
@table @code
@item ansify_if(value, color)
Surrounds the string representing value with ANSI codes to give it @code{color} on an TTY display.  Has no effect if directed to a file.
@item justify(value, first_width, latter_width, right_justify, colorize)  
Right or left justify the string representing @code{value}.  The width of the field in the first line is given by @code{first_width}.  For subsequent lines the width is given by @code{latterwidth}.  If @code{latter_width=-1}, then @code{first_width} is use for all lines.  If @code{right_justify=true} then the field is right justify within the width of the field. If it is @code{false}, then the field is left justified and padded to the full width of the field.  If @code{colorize} is true then ledger will hone color settings.
@item join(str)
Replaces line feeds in str with @code{\n}.
@item quoted(str)
Return str surounded by double quotes, @code{"<str>"}.
@item strip(value)
Values can have numerous annotations, such as effective dates and lot prices.  @code{strip} removes these annotations.
@end table
@node Misc,  , Text Formatting, New formatting codes
@subsection Miscellaneous
@multitable @columnfractions .3 .2 .5
@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description}
@item @code{amount_expr } @tab @code{} @tab 
@item @code{abs } @tab @code{} @tab  --> U
@item @code{commodity } @tab @code{} @tab 
@item @code{display_amount } @tab @code{} @tab   --> t
@item @code{display_total } @tab @code{} @tab  --> T
@item @code{date } @tab @code{} @tab 
@item @code{format_date } @tab @code{} @tab 
@item @code{format } @tab @code{} @tab 
@item @code{floor } @tab @code{} @tab 
@item @code{get_at } @tab @code{} @tab 
@item @code{is_seq } @tab @code{} @tab 
@item @code{justify } @tab @code{} @tab 
@item @code{join } @tab @code{} @tab 
@item @code{market --> P } @tab @code{} @tab 
@item @code{null } @tab @code{} @tab 
@item @code{now  --> d m } @tab @code{} @tab 
@item @code{options } @tab @code{} @tab 
@item @code{post } @tab @code{} @tab 
@item @code{percent } @tab @code{} @tab 
@item @code{price } @tab @code{} @tab 
@item @code{print } @tab @code{} @tab 
@item @code{quoted } @tab @code{} @tab 
@item @code{quantity } @tab @code{} @tab 
@item @code{rounded } @tab @code{} @tab 
@item @code{scrub } @tab @code{} @tab 
@item @code{strip --> S } @tab @code{} @tab 
@item @code{should_bold } @tab @code{} @tab 
@item @code{truncated } @tab @code{} @tab 
@item @code{total_expr } @tab @code{} @tab 
@item @code{today } @tab @code{} @tab 
@item @code{top_amount } @tab @code{} @tab 
@item @code{to_boolean } @tab @code{} @tab 
@item @code{to_int } @tab @code{} @tab 
@item @code{to_datetime } @tab @code{} @tab 
@item @code{to_date } @tab @code{} @tab 
@item @code{to_amount } @tab @code{} @tab 
@item @code{to_balance } @tab @code{} @tab 
@item @code{to_spring } @tab @code{} @tab 
@item @code{to_mask } @tab @code{} @tab 
@item @code{to_sequence } @tab @code{} @tab 
@item @code{unrounded } @tab @code{} @tab 
@item @code{value_date } @tab @code{} @tab 
@end multitable

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

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:

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

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:

@smallexample
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 smallexample

@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:

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

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 @bullet
@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:

@smallexample
100 "EUN+133"
@end smallexample

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 between @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:

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

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}:

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

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}:

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

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:

@smallexample
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 smallexample

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:

@smallexample
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 smallexample

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, Example Data File, Journal File Format, Top
@chapter Extending with Python

@node Example Data File, Miscellaneous Notes, Extending with Python, Top
@appendix Example Journal File: drewr.dat
 The following journal file is included with the source distribution of
 ledger.  It is called @file{drewr.dat} and exhibits many ledger
 features, include automatic and virtual transactions, 
@smallexample
; -*- ledger -*-

= /^Income/
  (Liabilities:Tithe)                    0.12

~ Monthly
  Assets:Checking                     $500.00
  Income:Salary

2003/12/01 * Checking balance
  Assets:Checking                   $1,000.00
  Equity:Opening Balances

2003/12/20 Organic Co-op
  Expenses:Food:Groceries             $ 37.50  ; [=2004/01/01]
  Expenses:Food:Groceries             $ 37.50  ; [=2004/02/01]
  Expenses:Food:Groceries             $ 37.50  ; [=2004/03/01]
  Expenses:Food:Groceries             $ 37.50  ; [=2004/04/01]
  Expenses:Food:Groceries             $ 37.50  ; [=2004/05/01]
  Expenses:Food:Groceries             $ 37.50  ; [=2004/06/01]
  Assets:Checking                   $ -225.00

2003/12/28=2004/01/01 Acme Mortgage
  Liabilities:Mortgage:Principal    $  200.00
  Expenses:Interest:Mortgage        $  500.00
  Expenses:Escrow                   $  300.00
  Assets:Checking                  $ -1000.00

2004/01/02 Grocery Store
  Expenses:Food:Groceries             $ 65.00
  Assets:Checking

2004/01/05 Employer
  Assets:Checking                   $ 2000.00
  Income:Salary

2004/01/14 Bank
  ; Regular monthly savings transfer
  Assets:Savings                     $ 300.00
  Assets:Checking

2004/01/19 Grocery Store
  Expenses:Food:Groceries             $ 44.00
  Assets:Checking

2004/01/25 Bank
  ; Transfer to cover car purchase
  Assets:Checking                  $ 5,500.00
  Assets:Savings
  ; :nobudget:

2004/01/25 Tom's Used Cars
  Expenses:Auto                    $ 5,500.00
  ; :nobudget:
  Assets:Checking

2004/01/27 Book Store
  Expenses:Books                       $20.00
  Liabilities:MasterCard

2004/02/01 Sale
  Assets:Checking:Business            $ 30.00
  Income:Sales

@end smallexample

@node Miscellaneous Notes,  , Example Data File, Top
@appendix Miscellaneous Notes

Various notes from the discussion list that I haven't incorporated in to the main body of the documentation.

@menu
* Cookbook::                    
@end menu

@node Cookbook,  , Miscellaneous Notes, Miscellaneous Notes
@section Cookbook

@subsection Invoking Ledger

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

@smallexample
= /^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 smallexample




@bye