sfos/ledger
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ledger/doc/ledger3.texi
Craig Earls ecc91c6b95 Corrected a few missing @ symbols per Jeroen
2012-10-04 06:25:18 -07:00

7760 lines
278 KiB
Text
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

\input texinfo @c -*-texinfo-*-
@setfilename ledger3.info
@settitle Ledger: Command-Line Accounting
@dircategory User Applications
@copying
Copyright (c) 2003-2011, 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
@author John Wiegley
@end titlepage
@direntry
* Ledger3: (ledger3). 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::
* Transactions ::
* Building Reports::
* Reporting Commands::
* Command-line Syntax::
* Budgeting and Forecasting::
* Value Expressions::
* Format Strings::
* Ledger for Developers::
* Extending with Python::
* Major Changes from version 2.6::
* Example Data File::
* Miscellaneous Notes::
* Concept Index::
* Command Index::
@end menu
@node Copying, Introduction to Ledger, Top, Top
@chapter Copying
@insertcopying
This license can also be obtained from the command-line by executing
@code{ledger --license}
@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.
@c If you use
@c another GUI accounting program like GNUCash, the vast majority of its
@c 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.
@cindex postings
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, transferring 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.
@cindex account, meaning of
@cindex meaning of account
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 multiple precision arithmetic 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
@findex help
@node Getting Help, , Building the Program, Introduction to Ledger
@section Getting help
Ledger has a complete online help system based on GNU Info. This manual
can be searched directly from the command line using the following
options:
@option{ledger --help} bring up this entire manual in your tty.
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
@noindent You can also find help at the @samp{#ledger} channel on the IRC server
@samp{irc.freenode.net}.
@cindex tutorial
@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
@cindex journals
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::
* Using the Windows command line::
@end menu
@node Balance Report, Register Report, Run Some Reports, Run Some Reports
@subsection Balance Report
@cindex balance report
@findex balance (bal)
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
@cindex register report
@findex register (reg)
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:
@cindex accounts, limiting by
@cindex limiting by accounts
@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, Using the Windows command line, Register Report, Run Some Reports
@subsection Cleared Report
@cindex cleared report
@findex cleared
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 Using the Windows command line, , Cleared Report, Run Some Reports
@subsection Using the Windows Command Line
@cindex windows cmd.exe
@cindex currency symbol display on windows
Using ledger under the windows command shell has one significant
limitation. CMD.exe is limited to standard ASCII characters and as such
cannot display any currency symbols other than dollar signs ($).
@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::
* Error Checking and Calculation Options::
* 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{csv} @tab Show transactions in csv format, for exporting to other programs
@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 @code{-a NAME} @tab @code{--account NAME} @tab specify default account name for QIF file postings
@end multitable
@node Report Filtering Quick Reference, Error Checking and Calculation Options, 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 of 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{} @tab @code{--dc} @tab Display register or balance in debit/credit format
@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 un-budgeted postings
@item @code{} @tab @code{--unbudgeted} @tab Shows only un-budgeted 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 Error Checking and Calculation Options, Output Customization Quick Reference, Report Filtering Quick Reference, Command Line Quick Reference
@subsection Error Checking and Calculation Options
@multitable @columnfractions .1 .25 .65
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
@item @code{} @tab @code{--strict} @tab accounts, tags or commodities not previously declared will cause warnings
@item @code{} @tab @code{--pedantic} @tab accounts, tags or commodities not previously declared will cause errors
@item @code{} @tab @code{--check-payees} @tab enable strict and pedantic checking for payees as well as accounts, commodities and tags.
@item @code{} @tab @code{--immediate} @tab instructs ledger to evaluate calculations immediately rather than lazily
@end multitable
@node Output Customization Quick Reference, Grouping Options, Error Checking and Calculation Options, 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{-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{--percent} @tab Show subtotals in the balance report as percentages
@c @item @code{} @tab @code{--totals} @tab Include running total in the @code{xml} report
@item @code{} @tab @code{--pivot TAG} @tab produce a pivot table of the tag type specified
@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, useful 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{} @tab @code{--dow} @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 stored 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{} @tab @code{--getquote} @tab Sets path to a user defined script to download commodity prices.
@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::
* 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 your
businesses. Double-entry accounting scales.
@cindex double-entry accounting
@node Stating where money goes, Assets and Liabilities, Accounting with Ledger, Principles of Accounting
@section Stating where money goes
@cindex credits and debits
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
@cindex income is negative
@cindex why is income negative
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, Commodities and Currencies, Stating where money goes, Principles of Accounting
@section Assets and Liabilities
@cindex assets and liabilities
@cindex debts are 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
In a similar vein, 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
@cindex reimbursable expense tracking
@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
apply 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 apply account
@end smallexample
(Note: The @samp{apply 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 Commodities and Currencies, Accounts and Inventories, Assets and Liabilities, 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 reported 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 deposit 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, Transactions , 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::
* Starting up::
* Structuring Your Accounts::
* Commenting on your journal::
* Currency and Commodities::
* Keeping it Consistent::
* Journal Format::
* Archiving Previous Years ::
* Using Emacs::
@end menu
@node Most Basic Entry, Starting up, 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}).
@cindex spaces in postings
@cindex posting format details
@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 generate an error. There must be at least two
spaces, or a tab, between the amount and the account. If you do not
have adequate separation between the amount and the account Ledger will
give an error and stop calculating.}
@node Starting up, Structuring Your Accounts, Most Basic Entry, Keeping a Journal
@section Starting up
@cindex initial equity
@cindex beginning ledger
Unless you have recently arrived from another planet, you already have a
financial state. You need to capture that financial state so that
Ledger has a starting point.
At some convenient point in time you new the balances and outstanding
obligation of every financial account you have. Those amounts form the
basis of the opening entry for ledger. For example if you chose the
beginning of 2011 as the date to start tracking finances with ledger,
your opening balance entry could look like this:
@cindex opening balance
@smallexample
2011/01/01 * Opening Balance
Assets:Joint Checking $800.14
Assets:Other Checking $63.44
Assets:Savings $2805.54
Assets:Investments:401K:Deferred 100.0000 VIFSX @ $80.5227
Assets:Investments:401K:Matching 50.0000 VIFSX @ $83.7015
Assets:Investments:IRA 250.0000 VTHRX @ $20.5324
Liabilities:Mortgage $-175634.88
Liabilities:Car Loan $-3494.26
Liabilities:Visa -$1762.44
Equity:Opening Balances
@end smallexample
There is nothing special about the name ``Opening Balances'' as the
payee of the account name, anything convenient that you understand will
work.
@node Structuring Your Accounts, Commenting on your journal, Starting up, Keeping a Journal
@section Structuring your Accounts
@cindex accounts, naming
@cindex naming 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 money 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 Commenting on your journal, Currency and Commodities, Structuring Your Accounts, Keeping a Journal
@section Commenting on your Journal
@cindex comments, characters
Comments are generally started using a ';'. However, in order to
increase compatibility with other text manipulation programs and methods
four additional comment characters are valid if used at the beginning
of a line: @code{#}, @code{|}, and @code{*} and @code{%}.
@cindex block comments
@cindex comments, block
Block comments can be made by use @code{@!comment} ... @code{@!end comment}
@smallexample
; This is a single line comment,
# and this,
% and this,
| and this,
* and this.
!comment
This is a block comment with
multiple lines
!end comment
@end smallexample
There are several forms of comments within a transaction, for example:
@smallexample
; this is a global comment that is not applied to a specific transaction
; it can start with any of the five characters but is not included in the
; output from 'print' or 'output'
2011/12/11 Something Sweet
; German Chocolate Cake
; :Broke Diet:
Expenses:Food $10.00 ; Friends: The gang
Assets:Credit Union:Checking
@end smallexample
@noindent The first comment is global and Ledger will not attach it to any specific
transactions. The comments within the transaction must all start with `;'s and are
preserved as part of the transaction. The `:'s indicate meta-data and tags
(@pxref{Metadata}).
@node Currency and Commodities, Keeping it Consistent, Commenting on your journal, Keeping a Journal
@section Currency and Commodities
@cindex currency
@cindex commodity
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 labeled using whatever is convenient for you (stock ticker
symbols are suggested for publicly traded assets).@footnote{you can
track ANYTHING, even time or distance traveled. 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 referring 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.
@menu
* Naming Commodities::
* Buying and Selling Stock::
* Fixing Lot Prices::
* Complete control over commodity pricing::
@end menu
@node Naming Commodities, Buying and Selling Stock, Currency and Commodities, Currency and Commodities
@subsection Naming Commodities
Commodity names can have any character, including white-space. However,
if you include white-space or numeric characters the commodity name must
be enclosed in double quotes:
@smallexample
1999/06/09 ! Achat
Actif:SG PEE STK 49.957 "Arcancia Equilibre 454"
Actif:SG PEE STK $-234.90
2000/12/08 ! Achat
Actif:SG PEE STK 215.796 "Arcancia Equilibre 455"
Actif:SG PEE STK $-10742.54
@end smallexample
@node Buying and Selling Stock, Fixing Lot Prices, Naming Commodities, Currency and Commodities
@subsection Buying and Selling Stock
@cindex buying stock
Buying stock is a typical example that many will use that involves
multiple commodities in the same transaction. The type of the share
(AAPL for Apple Inc.) and the share purchase price in the currency unit
you made the purchase in ($ for AAPL). Yes, the typical convention is as follows:
@smallexample
2004/05/01 Stock purchase
Assets:Broker 50 AAPL @@ $30.00
Expenses:Broker:Commissions $19.95
Assets:Broker $-1,500.00
@end smallexample
This assumes you have a brokerage account that is capable of managed
both liquid and commodity assets. Now, on the day of the sale:
@smallexample
2005/08/01 Stock sale
Assets:Broker -50 APPL @{$30.00@} @@ $50.00
Expenses:Broker:Commissions $19.95
Income:Capital Gains $-1,000.00
Assets:Broker $2,500.00
@end smallexample
@noindent You can, of course, elide the amount of the last posting. It is there
for clarity's sake.
The @{$30.00@} is a lot price. You can also use a lot date,
[2004/05/01], or both, in case you have several lots of the same
price/date and your taxation model is based on longest-held-first.
@node Fixing Lot Prices, Complete control over commodity pricing, Buying and Selling Stock, Currency and Commodities
@subsection Fixing Lot Prices
@cindex fixing lot prices
@cindex consumable commodity pricing
Commodities that you keep in order to sell them at a later time have a
variable value that fluctuates with the market prices. Commodities that
you consume should not fluctuate in value, but stay at the lot price
they were purchased at. As an extension of ``lot pricing'', you can fix
the per-unit price of a commodity.
For example, say you buy 10 gallons of gas at $1.20. In future
``value'' reports, you don't want these gallons reported in terms of
today's price, but rather the price when you bought it. At the same
time, you also want other kinds of commodities -- like stocks --
reported in terms of today's price.
This is supported as follows:
@smallexample
2009/01/01 Shell
Expenses:Gasoline 11 GAL @{=$2.299@}
Assets:Checking
@end smallexample
This transaction actually introduces a new commodity, ``GAL @{=$2.29@}'',
whose market value disregards any future changes in the price of
gasoline.
If you do not want price fixing, you can specify this same transaction
in one of two ways, both equivalent (note the lack of the equal sing
from the transaction above):
@smallexample
2009/01/01 Shell
Expenses:Gasoline 11 GAL @{$2.299@}
Assets:Checking
2009/01/01 Shell
Expenses:Gasoline 11 GAL @@ $2.299
Assets:Checking
@end smallexample
There is no difference in meaning between these two forms. Why do
both exist, you ask? To support things like this:
@smallexample
2009/01/01 Shell
Expenses:Gasoline 11 GAL @{=$2.299@} @@ $2.30
Assets:Checking
@end smallexample
This transaction says that you bought 11 gallons priced at $2.299 per
gallon at a @strong{cost to you} of $2.30 per gallon. Ledger auto-generates
a balance posting in this case to Equity:Capital Losses to reflect the
1.1 cent difference, which is then balanced by Assets:Checking because
its amount is null.
@node Complete control over commodity pricing, , Fixing Lot Prices, Currency and Commodities
@subsection Complete control over commodity pricing
@node Keeping it Consistent, Journal Format, Currency and Commodities, Keeping a Journal
@section Keeping it Consistent
Sometimes Ledger's flexibility can lead to difficulties. Using a
freeform text editor to enter transactions makes it easy to keep the
data, but also easy to enter accounts or payees inconsistently or with
spelling errors.
In order to combat inconsistency you can define allowable accounts and
or payees. For simplicity, create a separate text file and enter define
accounts a payees like
@smallexample
account Expenses
account Expenses:Utilities
...
@end smallexample
Using the @samp{--strict} option will cause Ledger to complain if any accounts are not previously defined:
@smallexample
15:27:39 ~/ledger (next) > ledger bal --strict
Warning: "FinanceData/Master.dat", line 6: Unknown account 'Liabilities:Tithe Owed'
Warning: "FinanceData/Master.dat", line 8: Unknown account 'Liabilities:Tithe Owed'
Warning: "FinanceData/Master.dat", line 15: Unknown account 'Allocation:Equities:Domestic'
@end smallexample
If you have a large Ledger register already created use the @samp{accounts} command to get started:
@smallexample
ledger accounts >> Accounts.dat
@end smallexample
@noindent You will have to edit this file to add the @samp{account} directive.
@node Journal Format, Archiving Previous Years , Keeping it Consistent, Keeping a Journal
@section Journal Format
The ledger file format is quite simple, but also very flexible. It
supports many options, though typically the user can ignore most of
them. They are summarized below.
@menu
* Transaction and Comments::
* Command Directives::
@end menu
@node Transaction and Comments, Command Directives, Journal Format, Journal Format
@subsection Transactions and Comments
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 white-space, 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 postings})
@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 =
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{Automated 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 a colon, pound, percent, bar or asterisk 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 the reporting and filtering capabilities of
Ledger.
@end table
@node Command Directives, , Transaction and Comments, Journal Format
@subsection Command Directives
@table @code
@item beginning of line
Command directives must occur at the beginning of a line. Use of ! and
@@ is deprecated.
@item account
Pre-declare valid account names. This only has effect if
@samp{--strict} or @samp{--pedantic} is used (see below). The
@samp{account} directive supports several optional sub-directives, if
they immediately follow the account directive and if they begin with
whitespace:
@smallexample
account Expenses:Food
note This account is all about the chicken!
alias food
payee ^(KFC|Popeyes)$
check commodity == "$"
assert commodity == "$"
eval print("Hello!")
default
@end smallexample
The @samp{note} sub-directive associates a textual note with the account. This can
be accessed later using the @samp{note} valexpr function in any account context.
The @samp{alias} sub-directive, which can occur multiple times, allows the alias to
be used in place of the full account name anywhere that account names are
allowed.
The @samp{payee} sub-directive, which can occur multiple times, provides regexps
that identify the account if that payee is encountered and an account within
its transaction ends in the name "Unknown". Example:
@smallexample
2012-02-27 KFC
Expenses:Unknown $10.00 ; Read now as "Expenses:Food"
Assets:Cash
@end smallexample
The @samp{check} and @samp{assert} directives warn or error (respectively) if the given
value expression evaluates to false within the context of any posting.
The @samp{eval} directive evaluates the value expression in the context of the
account at the time of definition. At the moment this has little value.
The @samp{default} directive specifies that this account should be used as the
``balancing account'' for any future transactions that contain only a single
posting.
@item apply account
@c instance_t::master_account_directive
Sets the root for all accounts following the directive. Ledger supports
a hierarchical tree of accounts. It may be convenient to keep two
``root accounts''. For example you may be tracking your personal
finances and your business finances. In order to keep them separate you
could preface all personal accounts with @code{personal:} and all
business account with @code{business:}. You can easily split out large
groups of transaction without manually editing them using the account
directive. For example:
@smallexample
apply account Personal
2011/11/15 Supermarket
Expenses:Groceries
Assets:Checking
@end smallexample
Would result in all postings going into
@code{Personal:Expenses:Groceries} and @code{Personal:Assets:hecking}
until and @code{end apply account} directive was found.
@item alias
@c instance_t::alias_directive
Define an alias for an account name. If you have a deeply nested tree
of accounts, it may be convenient to define an alias, for example:
@smallexample
alias Dining=Expenses:Entertainment:Dining
alias Checking=Assets:Credit Union:Joint Checking Account
2011/11/28 YummyPalace
Dining $10.00
Checking
@end smallexample
The aliases are only in effect for transactions read in after the alias
is defined and are effected by @code{account} directives that precede
them.
@item assert
@c instance_t::assert_directive
An assertion can throw an error if a condition is not met during Ledger's run.
@smallexample
assert <VALUE EXPRESSION BOOLEAN RESULT>
@end smallexample
@item bucket
@c instance_t::default_account_directive
Defines the default account to use for balancing transactions.
Normally, each transaction has at least two postings, which must balance
to zero. Ledger allows you to leave one posting with no amount and
automatically calculate balance the transaction in the posting. The
@code{bucket} allows you to fill in all postings and automatically
generate an additional posting to the bucket account balancing the
transaction. The following example set the @code{Assets:Checking} as
the bucket:
@smallexample
bucket Assets:Checking
2011/01/25 Tom's Used Cars
Expenses:Auto $ 5,500.00
2011/01/27 Book Store
Expenses:Books $20.00
2011/12/01 Sale
Assets:Checking:Business $ 30.00
@end smallexample
@item capture
@c instance_t::account_mapping_directive
Directs Ledger to replace any account matching a regex with the given
account. For example:
@smallexample
capture Expenses:Deductible:Medical Medical
@end smallexample
Would cause any posting with @code{Medical} in it's name to be replaced with
@code{Expenses:Deductible:Medical}.
Ledger will display the mapped payees in @code{print} and
@code{register} reports.
@item check
@c instance_t::check_directive in textual.cc
A check can issue a warning if a condition is not met during Ledger's run.
@smallexample
check <VALUE EXPRESSION BOOLEAN RESULT>
@end smallexample
@item comment
@c instance_t::comment_directive in textual.cc
Start a block comment, closed by @code{end comment}.
@item commodity
Pre-declare commodity names. This only has effect if @samp{--strict} or
@samp{--pedantic} is used (see below).
commodity $
commodity CAD
The @samp{commodity} directive supports several optional sub-directives, if they
immediately follow the commodity directive and if they begin with whitespace:
@smallexample
commodity $
note American Dollars
format $1,000.00
nomarket
default
@end smallexample
The @samp{note} sub-directive associates a textual note with the commodity. At
present this has no value other than documentation.
The @samp{format} directive gives you a way to tell Ledger how to format this
commodity. In future using this directive will disable Ledger's observation
of other ways that commodity is used, and will provide the ``canonical''
representation.
The @samp{nomarket} directive states that the commodity's price should never be
auto-downloaded.
The @samp{default} directive marks this as the ``default'' commodity.
@item define
@c instance_t::define_directive in textual.cc
Allows you to define value expression for future use. For example:
@smallexample
define var_name=$100
2011/12/01 Test
Expenses (var_name*4)
Assets
@end smallexample
The posting will have a cost of $400.
@item end
@c instance_t::end_directive in textual.cc
Closes block commands like @code{tag} or @code{comment}.
@item expr
@c instance_t::expr_directive in textual.cc
@item fixed
@c instance_t::fixed_directive in textual.cc
A fixed block is used to set fixated prices (@pxref{Fixated prices}) for a series of
transactions. It's purely a typing saver, for use when entering many
transactions with fixated prices.
Thus, the following:
@smallexample
fixed CAD $0.90
2012-04-10 Lunch in Canada
Assets:Wallet -15.50 CAD
Expenses:Food 15.50 CAD
2012-04-11 Second day Dinner in Canada
Assets:Wallet -25.75 CAD
Expenses:Food 25.75 CAD
endfixed
@end smallexample
is equivalent to this:
@smallexample
2012-04-10 Lunch in Canada
Assets:Wallet -15.50 CAD @{=$0.90@}
Expenses:Food 15.50 CAD @{=$0.90@}
2012-04-11 Second day Dinner in Canada
Assets:Wallet -25.75 CAD @{=$0.90@}
Expenses:Food 25.75 CAD @{=$0.90@}
@end smallexample
Note that ending a @samp{fixed} is done differently than other
directives, as @samp{fixed} is closed with an @samp{endfixed} (i.e.,
there is @strong{no space} between @samp{end} and @samp{fixed}).
For the moment, users may wish to study
@uref{http://bugs.ledger-cli.org/show_bug.cgi?id=789, Bug Report 789}
before using the @samp{fixed} directive in production.
@item include
@c instance_t::include_directive in textual.cc
Include the stated file as if it were part of the current file.
@item payee
@c instance_t::payee_mapping_directive in textual.cc
The @samp{payee} directive supports one optional sub-directive, if it immediately
follows the payee directive and if it begins with whitespace:
@smallexample
payee KFC
alias KENTUCKY FRIED CHICKEN
@end smallexample
The @samp{alias} directive provides a regexp which, if it matches a parsed payee,
the declared payee name is substituted:
@smallexample
2012-02-27 KENTUCKY FRIED CHICKEN ; will be read as being 'KFC'
...
@end smallexample
Ledger will display the mapped payees in @code{print} and
@code{register} reports.
@item apply tag
@c instance_t::tag_directive in textual.cc
Allows you to designate a block of transactions and assign the same tag to all. Tags can have values and may be nested.
@smallexample
apply tag hastag
apply tag nestedtag: true
2011/01/25 Tom's Used Cars
Expenses:Auto $ 5,500.00
; :nobudget:
Assets:Checking
2011/01/27 Book Store
Expenses:Books $20.00
Liabilities:MasterCard
end apply tag nestedtag
2011/12/01 Sale
Assets:Checking:Business $ 30.00
Income:Sales
end apply tag hastag
@end smallexample
@noindent is the equivalent of
@smallexample
2011/01/25 Tom's Used Cars
:hastag:
nestedtag: true
Expenses:Auto $ 5,500.00
; :nobudget:
Assets:Checking
2011/01/27 Book Store
:hastag:
nestedtag: true
Expenses:Books $20.00
Liabilities:MasterCard
2011/12/01 Sale
:hastag:
Assets:Checking:Business $ 30.00
Income:Sales
@end smallexample
Note that anything following ``@code{end tag}'' is ignored. placing the
name of the tag that is being closed is a simple way to keep track.
@item tag
Pre-declares tag names. This only has effect if @samp{--strict} or
@samp{--pedantic} is used (see below).
@smallexample
tag Receipt
tag CSV
@end smallexample
The 'tag' directive supports two optional sub-directives, if they immediately
follow the tag directive and if they begin with whitespace:
@smallexample
tag Receipt
check value =~ /pattern/
assert value != "foobar"
@end smallexample
The @samp{check} and @samp{assert} directives warn or error (respectively) if the given
value expression evaluates to false within the context of any use of the
related tag. In such a context, ``value'' is bound to the value of the tag
(which may not be a string if typed-metadata is used!). Such checks or
assertions are not called if no value is given.
@item test
@c instance_t::comment_directive in textual.cc
This is a synonym for @code{comment} and must be closed by and @code{end} tag.
@item year
@c instance_t::year_directive in textual.cc
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{year 2004}. 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.
@end table
The following single letter commands may be at the beginning of a line
alone, for backwards compatibility with older Ledger versions.
@table @code
@item A
See @code{bucket}
@item Y
See @code{year}
@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, i, O, 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 , Using Emacs, Journal 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 Using Emacs, , Archiving Previous Years , Keeping a Journal
@section Using Emacs to Maintain Your Journal
@cindex Emacs
@menu
* running ledger-mode::
* Working with entries::
* Reconciling accounts::
* Generating Reports::
@end menu
@node running ledger-mode, Working with entries, Using Emacs, Using Emacs
@subsection Running ledger-mode
Journal files are simple free text files easily modified by any text
editor. A special mode for Emacs is included with the source
distribution.
@cindex Emacs .emacs file
To use the Emacs mode, copy the several lisp files from the source lisp
directory your your @file{site-lisp} directory and add the following line
to your @file{.emacs} (or equivalent, @file{~/Aquamacs/Preferences.el}
for Aquamacs on Mac OS X)
@smallexample
(load "ledger")
@end smallexample
To trigger ledger mode when you visit a journal file, the first line of
each of your journal files should be:
@smallexample
; -*-ledger-*-
@end smallexample
To enter ledger-mode on a new file, type M-x ledger-mode.
Once you have loaded a Journal file into Emacs, you have several
commands available to make entering, clearing and reconciling
transactions and producing reports:
@cindex Emacs commands
@table @code
@item C-i or <TAB>
auto complete entry
@item C-c C-a
add a new entry, based on previous entries
@item C-c C-e
toggle cleared status of an entire entry
@item C-c C-c
toggle cleared status of an individual posting
@item C-c C-y
set default year for entry mode
@item C-c C-m
set default month for entry mode
@item C-c C-r
reconcile uncleared entries related to an account
@item C-c C-d
delete the current entry
@item C-c C-s
sort all entries in the journal by date. Drop comments outside of entries
@item C-c C-o C-r
run a ledger report
@item C-C C-o C-g
go to the ledger report buffer
@item C-c C-o C-e
edit the defined ledger reports
@item C-c C-o C-s
save a report definition based on the current report
@item C-c C-o C-a
rerun a ledger report
@item C-c C-o C-k
kill the ledger report buffer
@end table
@menu
* Working with entries::
* Reconciling accounts::
* Generating Reports::
@end menu
@node Working with entries, Reconciling accounts, running ledger-mode, Using Emacs
@subsection Working with entries
@menu
* Manual Entry Support::
* Automagically Adding new entries::
* Clearing Transactions::
@end menu
@node Manual Entry Support, Automagically Adding new entries, Working with entries, Working with entries
@subsubsection Manual Entry Support
@cindex <TAB> completion
@cindex auto-completion
@cindex misspelled accounts treated as new
In most financial programs, some sort of auto-completion is available to
save typing and improve accuracy. Ledger doesn't leave you hanging,
@code{ledger-mode} provides tab completion on all portions of an entry.
Type a portion of the payee and hit <TAB>, and @code{ledger-mode} will
suggest a completion. When filling in the account type the first few
letters followed by a <TAB> and the account will be filled in. For
example typing @samp{Ex<TAB>Au<TAB>F<TAB>} would yield
@samp{Expenses:Auto:Fuel} if you had previously used that account in
this journal. If there are more than one account with similar starting,
hitting <TAB> multiple times will iterate through them. This is a good
habit to get in to prevent misspellings of accounts. Remember Ledger
does not validate the names of payees or account so a misspelled account
will be interpreted as a new account by ledger.
@node Automagically Adding new entries, Clearing Transactions, Manual Entry Support, Working with entries
@subsubsection Automagically Adding new entries
@cindex new transactions in Emacs
@cindex Emacs, adding new transactions
@code{C-c C-a} will run the @code{ledger entry} command (@pxref{entry
and xact}) from within Emacs. When typed, the mini-buffer will appear
with the current year and month, waiting for you to enter the day and
the payee. Ledger will generate a new entry based on the most recent
entry for that payee, using the amount and accounts from that
transaction. If you have a new amount simply type the amount after the
payee. For example, if your journal contains an entry
@smallexample
2011/11/25 Viva Italiano
Expenses:Food $12.45
Expenses:Tips $2.55
Liabilities:MasterCard $-15.00
@end smallexample
@noindent and you type @samp{C-c C-a}, the mini-buffer will appear showing the
current year and month. If you complete the mini-buffer entry by typing
@smallexample
Entry: 2011/11/28 viva food 34 tip 7 <enter>
@end smallexample
@noindent Emacs will add the following entry to your journal:
@smallexample
2011/11/30 Viva Italiano
Expenses:Food $34.00
Expenses:Tips $7.00
Liabilities:MasterCard
@end smallexample
@noindent Notice that the entry will appear at the correct place in the journal
ordered by date, not necessarily at the bottom of the file.
@node Clearing Transactions, , Automagically Adding new entries, Working with entries
@subsubsection Clearing Transactions and Postings
@cindex clearing transactions in Emacs
@cindex Emacs, clear transaction
@code{C-c C-e} will place an asterisk after the date in the current
transaction. The tells ledger the transaction has been cleared through
your bank (or whatever else you want the concept to mean)
@smallexample
2011/11/25 Viva Italiano
Expenses:Food $12.45
Expenses:Tips $2.55
Liabilities:MasterCard $-15.00
@end smallexample
@noindent becomes
@smallexample
2011/11/25 * Viva Italiano
Expenses:Food $12.45
Expenses:Tips $2.55
Liabilities:MasterCard $-15.00
@end smallexample
If, for some reason you need to clear a specific posting in the
transaction you can type @samp{C-c C-c} and the posting at point will be
toggled.
@node Reconciling accounts, Generating Reports, Working with entries, Using Emacs
@subsection Reconciling accounts
In the reconcile buffer, use SPACE to toggle the cleared status of a
transaction, C-x C-s to save changes (to the ledger file as well).
@node Generating Reports, , Reconciling accounts, Using Emacs
@subsection Generating Reports
The ledger reports command asks the user to select a report to run then
creates a report buffer containing the results of running the associated
command line. Its' behavior is modified by a prefix argument which,
when given, causes the generated command line that will be used to
create the report to be presented for editing before the report is
actually run. Arbitrary unnamed command lines can be run by specifying
an empty name for the report. The command line used can later be named
and saved for future use as a named report from the generated reports
buffer.
In a report buffer, the following keys are available:
@table @code
@item (space)
scroll up
@item e
edit the defined ledger reports
@item s
save a report definition based on the current report
@item q
quit the report (return to ledger buffer)
@item r
redo the report
@item k
kill the report buffer
@end table
@node Transactions , Building Reports, Keeping a Journal, Top
@chapter Transactions
@menu
* Basic format::
* Eliding amounts::
* Auxiliary dates::
* Codes::
* Transaction state::
* Transaction notes::
* Metadata::
* Virtual postings::
* Expression amounts::
* Balance verification::
* Posting cost::
* Explicit posting costs::
* Posting cost expressions::
* Total posting costs::
* Virtual posting costs::
* Commodity prices::
* Prices vs. costs::
* Fixated prices::
* Lot dates::
* Lot notes::
* Lot value expressions::
* Automated transactions::
@end menu
@node Basic format, Eliding amounts, Transactions , Transactions
@section Basic format
The most basic form of transaction is:
@smallexample
2012-03-10 KFC
Expenses:Food $20.00
Assets:Cash $-20.00
@end smallexample
This transaction has a date, a payee or description, a target account (the
first posting), and a source account (the second posting). Each posting
specifies what action is taken related to that account.
A transaction can have any number of postings:
@smallexample
2012-03-10 KFC
Expenses:Food $20.00
Assets:Cash $-10.00
Liabilities:Credit $-10.00
@end smallexample
@node Eliding amounts, Auxiliary dates, Basic format, Transactions
@section Eliding amounts
The first thing you can do to make things easier is elide amounts. That is,
if exactly one posting has no amount specified, Ledger will infer the inverse
of the other postings' amounts:
@smallexample
2012-03-10 KFC
Expenses:Food $20.00
Assets:Cash $-10.00
Liabilities:Credit ; same as specifying $-10
@end smallexample
@noindent If the other postings use multiple commodities, Ledger will copy the empty
posting N times and fill in the negated values of the various commodities:
@smallexample
2012-03-10 KFC
Expenses:Food $20.00
Expenses:Tips $2.00
Assets:Cash EUR -10.00
Assets:Cash GBP -10.00
Liabilities:Credit
@end smallexample
@noindent This transaction is identical to writing:
@smallexample
2012-03-10 KFC
Expenses:Food $20.00
Expenses:Tips $2.00
Assets:Cash EUR -10.00
Assets:Cash GBP -10.00
Liabilities:Credit $-22.00
Liabilities:Credit EUR 10.00
Liabilities:Credit GBP 10.00
@end smallexample
@node Auxiliary dates, Codes, Eliding amounts, Transactions
@section Auxiliary dates
You can associate a second date with a transaction by following the primary
date with an equals sign:
@smallexample
2012-03-10=2012-03-08 KFC
Expenses:Food $20.00
Assets:Cash $-20.00
@end smallexample
What this auxiliary date means is entirely up to you. The only use Ledger has
for it is that if you specify --aux-date, then all reports and calculations
(including pricing) will use the aux date as if it were the primary date.
@node Codes, Transaction state, Auxiliary dates, Transactions
@section Codes
A transaction can have a textual "code". This has no meaning and is only
displayed by the print command. Checking accounts often use codes like DEP,
XFER, etc., as well as check numbers. This is to give you a place to put
those codes:
@smallexample
2012-03-10 (#100) KFC
Expenses:Food $20.00
Assets:Checking
@end smallexample
@node Transaction state, Transaction notes, Codes, Transactions
@section Transaction state
A transaction can have a ``state'': cleared, pending, or uncleared. The default
is uncleared. To mark a transaction cleared, put a * before the payee, and
after date or code:
@smallexample
2012-03-10 * KFC
Expenses:Food $20.00
Assets:Cash
@end smallexample
@noindent To mark it pending, use a !:
@smallexample
2012-03-10 ! KFC
Expenses:Food $20.00
Assets:Cash
@end smallexample
What these mean is entirely up to you. The --cleared option will limits to
reports to only cleared items, while --uncleared shows both uncleared and
pending items, and --pending shows only pending items.
I use cleared to mean that I've reconciled the transaction with my bank
statement, and pending to mean that I'm in the middle of a reconciliation.
When you clear a transaction, that's really just shorthand for clearing all of
its postings. That is:
@smallexample
2012-03-10 * KFC
Expenses:Food $20.00
Assets:Cash
@end smallexample
@noindent Is the same as writing:
@smallexample
2012-03-10 KFC
* Expenses:Food $20.00
* Assets:Cash
@end smallexample
@noindent You can mark individual postings as cleared or pending, in case one "side" of
the transaction has cleared, but the other hasn't yet:
@smallexample
2012-03-10 KFC
Liabilities:Credit $100.00
* Assets:Checking
@end smallexample
@node Transaction notes, Metadata, Transaction state, Transactions
@section Transaction notes
After the payee, and after at least one tab or two spaces (or a space
and a tab, which Ledger calls this a ``hard separator''), you may
introduce a note about the transaction using the ; character:
@smallexample
2012-03-10 * KFC ; yum, chicken...
Expenses:Food $20.00
Assets:Cash
@end smallexample
@noindent Notes can also appear on the next line, so long as that line begins with
whitespace:
@smallexample
2012-03-10 * KFC ; yum, chicken...
; and more notes...
Expenses:Food $20.00
Assets:Cash
2012-03-10 * KFC
; just these notes...
Expenses:Food $20.00
Assets:Cash
@end smallexample
A transaction note is shared by all its postings. This becomes significant
when querying for metadata (see below). To specify that a note belongs only
to one posting, place it after a hard separator after the amount, or on its
own line preceded by whitespace:
@smallexample
2012-03-10 * KFC
Expenses:Food $20.00 ; posting #1 note
Assets:Cash
; posting #2 note, extra indentation is optional
@end smallexample
@node Metadata, Virtual postings, Transaction notes, Transactions
@section Metadata
One of Ledger's more powerful features is the ability to associate typed
metadata with postings and transactions (by which I mean all of a
transaction's postings). This metadata can be queried, displayed, and used in
calculations.
The are two forms of metadata: tags and tag/value pairs.
@menu
* Metadata tags::
* Metadata values::
* Typed metadata::
@end menu
@node Metadata tags, Metadata values, Metadata, Metadata
@subsection Metadata tags
To tag an item, put any word not containing whitespace between two colons:
@smallexample
2012-03-10 * KFC
Expenses:Food $20.00
Assets:Cash
; :TAG:
@end smallexample
You can gang up multiple tags by sharing colons:
@smallexample
2012-03-10 * KFC
Expenses:Food $20.00
Assets:Cash
; :TAG1:TAG2:TAG3:
@end smallexample
@node Metadata values, Typed metadata, Metadata tags, Metadata
@subsection Metadata values
To associate a value with a tag, use the syntax "Key: Value", where the value
can be any string of characters. Whitespace is needed after the colon, and
cannot appear in the Key:
@smallexample
2012-03-10 * KFC
Expenses:Food $20.00
Assets:Cash
; MyTag: This is just a bogus value for MyTag
@end smallexample
@node Typed metadata, , Metadata values, Metadata
@subsection Typed metadata
If a metadata tag ends in ::, it's value will be parsed as a value expression
and stored internally as a value rather than as a string. For example,
although I can specify a date textually like so:
@smallexample
2012-03-10 * KFC
Expenses:Food $20.00
Assets:Cash
; AuxDate: 2012/02/30
@end smallexample
@noindent This date is just a string, and won't be parsed as a date unless its value is
used in a date-context (at which time the string is parsed into a date
automatically every time it is needed as a date). If on the other hand I
write this:
@smallexample
2012-03-10 * KFC
Expenses:Food $20.00
Assets:Cash
; AuxDate:: [2012/02/30]
@end smallexample
@noindent Then it is parsed as a date only once, and during parsing of the journal file,
which would let me know right away that it is an invalid date.
@node Virtual postings, Expression amounts, Metadata, Transactions
@section Virtual postings
Ordinarily, the amounts of all postings in a transaction must balance to zero.
This is non-negotiable. It's what double-entry accounting is all about! But
there are some tricks up Ledger's sleeve...
You can use virtual accounts to transfer amounts to an account on the sly,
bypassing the balancing requirement. The trick is that these postings are not
considered ``real'', and can be removed from all reports using @samp{--real}.
To specify a virtual account, surround the account name with parentheses:
@smallexample
2012-03-10 * KFC
Expenses:Food $20.00
Assets:Cash
(Budget:Food) $-20.00
@end smallexample
If you want, you can state that virtual postings @emph{should} balance against
one or more other virtual postings by using brackets (which look ``harder'')
rather than parentheses:
@smallexample
2012-03-10 * KFC
Expenses:Food $20.00
Assets:Cash
[Budget:Food] $-20.00
[Equity:Budgets] $20.00
@end smallexample
@node Expression amounts, Balance verification, Virtual postings, Transactions
@section Expression amounts
An amount is usually a numerical figure with an (optional) commodity, but it
can also be any value expression. To indicate this, surround the amount
expression with parentheses:
@smallexample
2012-03-10 * KFC
Expenses:Food ($10.00 + $20.00) ; Ledger adds it up for you
Assets:Cash
@end smallexample
@node Balance verification, Posting cost, Expression amounts, Transactions
@section Balance verification
@menu
* Balance assertions::
* Balance assignments::
* Resetting a balance::
* Balancing transactions::
@end menu
If at the end of a posting's amount (and after the cost too, if there is one)
there is an equals sign, then Ledger will verify that the total value for that
account as of that posting matches the amount specified.
There are two forms of this features: balance assertions, and balance
assignments.
@node Balance assertions, Balance assignments, Balance verification, Balance verification
@subsection Balance assertions
A balance assertion has this general form:
@smallexample
2012-03-10 KFC
Expenses:Food $20.00
Assets:Cash $-20.00 = $500.00
@end smallexample
This simply asserts that after subtracting $20.00 from Assets:Cash, that the
resulting total matches $500.00. If not, it is an error.
@node Balance assignments, Resetting a balance, Balance assertions, Balance verification
@subsection Balance assignments
A balance assignment has this form:
@smallexample
2012-03-10 KFC
Expenses:Food $20.00
Assets:Cash = $500.00
@end smallexample
This sets the amount of the second posting to whatever it would need to be for
the total in Assets:Cash to be $500.00 after the posting. If the resulting
amount is not $-20.00 in this case, it is an error.
@node Resetting a balance, Balancing transactions, Balance assignments, Balance verification
@subsection Resetting a balance
Say your book-keeping has gotten a bit out of date, and your Ledger balance no
longer matches your bank balance. You can create an adjustment transaction
using balance assignments:
@smallexample
2012-03-10 Adjustment
Assets:Cash = $500.00
Equity:Adjustments
@end smallexample
Since the second posting is also null, it's value will become the inverse of
whatever amount is generated for the first posting.
This is the only time in ledger when more than one posting's amount may be
empty -- and then only because it's not true empty, it is indirectly provided
by the balance assignment's value.
@node Balancing transactions, , Resetting a balance, Balance verification
@subsection Balancing transactions
As a consequence of all the above, consider the following transaction:
@smallexample
2012-03-10 My Broker
[Assets:Brokerage] = 10 AAPL
@end smallexample
What this says is: set the amount of the posting to whatever value is needed
so that Assets:Brokerage contains 10 AAPL. Then, because this posting must
balance, ensure that its value is zero. This can only be true if
Assets:Brokerage does indeed contain 10 AAPL at that point in the input file.
A balanced virtual transaction is used simply to indicate to Ledger that this
is not a "real" transaction. It won't appear in any reports anyway (unless
you use a register report with --empty).
@node Posting cost, Explicit posting costs, Balance verification, Transactions
@section Posting cost
When you transfer a commodity from one account to another, sometimes it get
transformed during the transaction. This happens when you spend money on gas,
for example, which transforms dollars into gallons of gasoline, or dollars
into stocks in a company.
In those cases, Ledger will remember the "cost" of that transaction for you,
and can use it during reporting in various ways. Here's an example of a stock
purchase:
@smallexample
2012-03-10 My Broker
Assets:Brokerage 10 AAPL
Assets:Brokerage:Cash $-500.00
@end smallexample
This is different from transferring 10 AAPL shares from one account to
another, in this case you are @emph{exchanging} one commodity for another. The
resulting posting cost is $50.00 per share.
@node Explicit posting costs, Posting cost expressions, Posting cost, Transactions
@section Explicit posting costs
You can make any posting's cost explicit using the @ symbol after the amount
or amount expression:
@smallexample
2012-03-10 My Broker
Assets:Brokerage 10 AAPL @ $50.00
Assets:Brokerage:Cash $-500.00
@end smallexample
When you do this, since Ledger can now figure out the balancing amount from
the first posting's cost, you can elide the other amount:
@smallexample
2012-03-10 My Broker
Assets:Brokerage 10 AAPL @ $50.00
Assets:Brokerage:Cash
@end smallexample
@menu
* Primary and secondary commodities::
@end menu
@node Primary and secondary commodities, , Explicit posting costs, Explicit posting costs
@subsection Primary and secondary commodities
It is a general convention within Ledger that the "top" postings in a
transaction contain the target accounts, while the final posting contains the
source account. Whenever a commodity is exchanged like this, the commodity
moved to the target account is considered "secondary", while the commodity
used for purchasing and tracked in the cost is "primary".
Said another way, whenever Ledger sees a posting cost of the form "AMOUNT @@
AMOUNT", the commodity used in the second amount is marked "primary".
The only meaning a primary commodity has is that -V flag will never convert a
primary commodity into any other commodity. -X still will, however.
@node Posting cost expressions, Total posting costs, Explicit posting costs, Transactions
@section Posting cost expressions
Just as you can have amount expressions, you can have posting expressions:
@smallexample
2012-03-10 My Broker
Assets:Brokerage 10 AAPL @@ ($500.00 / 10)
Assets:Brokerage:Cash
@end smallexample
You can even have both:
@smallexample
2012-03-10 My Broker
Assets:Brokerage (5 AAPL * 2) @@ ($500.00 / 10)
Assets:Brokerage:Cash
@end smallexample
@node Total posting costs, Virtual posting costs, Posting cost expressions, Transactions
@section Total posting costs
The cost figure following the @ character specifies the @emph{per-unit} price for
the commodity being transferred. If you'd like to specify the total cost
instead, use @@@@:
@smallexample
2012-03-10 My Broker
Assets:Brokerage 10 AAPL @@ $500.00
Assets:Brokerage:Cash
@end smallexample
Ledger reads this as if you had written:
@smallexample
2012-03-10 My Broker
Assets:Brokerage 10 AAPL @@@@ ($500.00 / 10)
Assets:Brokerage:Cash
@end smallexample
@node Virtual posting costs, Commodity prices, Total posting costs, Transactions
@section Virtual posting costs
Normally whenever a commodity exchange like this happens, the price of the
exchange (such as $50 per share of AAPL, above) is recorded in Ledger's
internal price history database. To prevent this from happening in the case
of an exceptional transaction, surround the @@ or @@@@ with parentheses:
@smallexample
2012-03-10 My Brother
Assets:Brokerage 1000 AAPL (@@) $1
Income:Gifts Received
@end smallexample
@node Commodity prices, Prices vs. costs, Virtual posting costs, Transactions
@section Commodity prices
When a transaction occurs that exchange one commodity for another, Ledger
records that commodity price not only within its internal price database, but
also attached to the commodity itself. Usually this fact remains invisible to
the user, unless you turn on @samp{--lot-prices} to show these hidden price figures.
For example, consider the stock sale given above:
@smallexample
2012-03-10 My Broker
Assets:Brokerage 10 AAPL @@ $50.00
Assets:Brokerage:Cash
@end smallexample
The commodity transferred into Assets:Brokerage is not actually 10 AAPL, but
rather 10 AAPL @{$5.00@}. The figure in braces after the amount is called the
``lot price''. It's Ledger's way of remembering that this commodity was
transferred through an exchange, and that $5.00 was the price of that
exchange.
This becomes significant if you later sell that commodity again. For example,
you might write this:
@smallexample
2012-04-10 My Broker
Assets:Brokerage:Cash
Assets:Brokerage -10 AAPL @@ $75.00
@end smallexample
And that would be perfectly fine, but how do you track the capital gains on
the sale? It could be done with a virtual posting:
@smallexample
2012-04-10 My Broker
Assets:Brokerage:Cash
Assets:Brokerage -10 AAPL @@ $75.00
(Income:Capital Gains) $-250.00
@end smallexample
But this gets messy since capital gains income is very real, and not quite
appropriate for a virtual posting.
Instead, if you reference that same hidden price annotation, Ledger will
figure out that the price of the shares you're selling, and the cost you're
selling them at, don't balance:
@smallexample
2012-04-10 My Broker
Assets:Brokerage:Cash $750.00
Assets:Brokerage -10 AAPL @{$50.00@} @@ $75.00
@end smallexample
This transaction will fail because the $250.00 price difference between the
price you bought those shares at, and the cost you're selling them for, does
not match. The lot price also identifies which shares you purchased on that
prior date.
@menu
* Total commodity prices::
@end menu
@node Total commodity prices, , Commodity prices, Commodity prices
@subsection Total commodity prices
As a shorthand, you can specify the total price instead of the per-share
price in doubled braces. This goes well with total costs, but is not required
to be used with them:
@smallexample
2012-04-10 My Broker
Assets:Brokerage:Cash $750.00
Assets:Brokerage -10 AAPL @{@{$500.00@}@} @@@@ $750.00
Income:Capital Gains $-250.00
@end smallexample
It should be noted that this is a convenience only for cases where you buy and
sell whole lots. The @{@{$500.00@}@} is @emph{not} an attribute of commodity, whereas
@{$5.00@} is. In fact, when you write @{@{$500.00@}@}, Ledger just divides that
value by 10 and sees @{$50.00@}. So if you use the print command to look at
this transaction, you'll see the single form in the output. The double price
form is a shorthand only.
Plus, it comes with dangers. This works fine:
@smallexample
2012-04-10 My Broker
Assets:Brokerage 10 AAPL @ $50.00
Assets:Brokerage:Cash $750.00
2012-04-10 My Broker
Assets:Brokerage:Cash $375.00
Assets:Brokerage -5 AAPL @{$50.00@} @@ $375.00
Income:Capital Gains $-125.00
2012-04-10 My Broker
Assets:Brokerage:Cash $375.00
Assets:Brokerage -5 AAPL @{$50.00@} @@ $375.00
Income:Capital Gains $-125.00
@end smallexample
@noindent But this does not do what you might expect:
@smallexample
2012-04-10 My Broker
Assets:Brokerage 10 AAPL @ $50.00
Assets:Brokerage:Cash $750.00
2012-04-10 My Broker
Assets:Brokerage:Cash $375.00
Assets:Brokerage -5 AAPL @{@{$500.00@}@} @@ $375.00
Income:Capital Gains $-125.00
2012-04-10 My Broker
Assets:Brokerage:Cash $375.00
Assets:Brokerage -5 AAPL @{@{$500.00@}@} @@ $375.00
Income:Capital Gains $-125.00
@end smallexample
And in cases where the amounts do not divide into whole figure and must be
rounded, the capital gains figure could be off by a cent. Use with caution.
@node Prices vs. costs, Fixated prices, Commodity prices, Transactions
@section Prices vs. costs
Because lot pricing provides enough information to infer the cost, the
following two transactions are equivalent:
@smallexample
2012-04-10 My Broker
Assets:Brokerage 10 AAPL @ $50.00
Assets:Brokerage:Cash $750.00
2012-04-10 My Broker
Assets:Brokerage 10 AAPL @{$50.00@}
Assets:Brokerage:Cash $750.00
@end smallexample
However, note that what you see in some reports may differ, for example in the
print report. Functionally, however, there is no difference, and neither the
register nor the balance report are sensitive to this difference.
@node Fixated prices, Lot dates, Prices vs. costs, Transactions
@section Fixated prices
If you buy a stock last year, and ask for its value today, Ledger will consult
its price database to see what the most recent price for that stock is. You
can short-circuit this lookup by ``fixing'' the price at the time of a
transaction. This is done using @{=AMOUNT@}:
@smallexample
2012-04-10 My Broker
Assets:Brokerage 10 AAPL @{=$50.00@}
Assets:Brokerage:Cash $750.00
@end smallexample
These 10 AAPL will now always be reported as being worth $50, no matter what
else happens to the stock in the meantime.
Fixated prices are a special case of using lot valuation expressions (see
below) to fix the value of a commodity lot.
@menu
* Fixated costs::
@end menu
@node Fixated costs, , Fixated prices, Fixated prices
@subsection Fixated costs
Since price annotations are costs are largely interchangeable and a matter of
preference, there is an equivalent syntax for specified fixated prices by way
of the cost:
@smallexample
2012-04-10 My Broker
Assets:Brokerage 10 AAPL @@ =$50.00
Assets:Brokerage:Cash $750.00
@end smallexample
This is the same as the previous transaction, with the same caveats found in
the section ``Prices vs. costs''.
@node Lot dates, Lot notes, Fixated prices, Transactions
@section Lot dates
In addition to lot prices, you can specify lot dates and reveal them with
@samp{--lot-dates}. Other than that, however, they have no special meaning to
Ledger. They are specified after the amount in square brackets (the same way
that dates are parsed in value expressions):
@smallexample
2012-04-10 My Broker
Assets:Brokerage:Cash $375.00
Assets:Brokerage -5 AAPL @{$50.00@} [2012-04-10] @@ $375.00
Income:Capital Gains $-125.00
@end smallexample
@node Lot notes, Lot value expressions, Lot dates, Transactions
@section Lot notes
You can also associate arbitrary notes for your own record keeping in
parentheses, and reveal them with --lot-notes. One caveat is that the note
cannot begin with an @ character, as that would indicate a virtual cost:
@smallexample
2012-04-10 My Broker
Assets:Brokerage:Cash $375.00
Assets:Brokerage -5 AAPL @{$50.00@} [2012-04-10] (Oh my!) @@ $375.00
Income:Capital Gains $-125.00
@end smallexample
You can any combination of lot prices, dates or notes, in any order. They are
all optional.
To show all lot information in a report, use @samp{--lots}.
@node Lot value expressions, Automated transactions, Lot notes, Transactions
@section Lot value expressions
Normally when you ask Ledger to display the values of commodities held, it
uses a value expression called ``market'' to determine the most recent value
from its price database -- even downloading prices from the Internet, if -Q
was specified and a suitable ``getquote'' script is found on your system.
However, you can override this valuation logic by providing a commodity
valuation expression in doubled parentheses. This expression must result in
one of two values: either an amount to always be used as the per-share price
for that commodity; or a function taking three argument which is called to
determine that price.
If you use the functional form, you can either specify a function name, or a
lambda expression. Here's a function that yields the price as $10 in whatever
commodity is being requested:
@smallexample
define ten_dollars(s, date, t) = market($10, date, t)
@end smallexample
I can now use that in a lot value expression as follows:
@smallexample
2012-04-10 My Broker
Assets:Brokerage:Cash $375.00
Assets:Brokerage -5 AAPL @{$50.00@} ((ten_dollars)) @@@@ $375.00
Income:Capital Gains $-125.00
@end smallexample
Alternatively, I could do the same thing without pre-defining a function by
using a lambda expression taking three arguments:
@smallexample
2012-04-10 My Broker
A:B:Cash $375.00
A:B -5 AAPL @{$50.00@} ((s, d, t -> market($10, date, t))) @@@@ $375.00
Income:Capital Gains $-125.00
@end smallexample
The arguments passed to these functions have the following meaning:
@itemize
@item source
The source commodity string, or an amount object. If it is a
string, the return value must be an amount representing the
price of the commodity identified by that string (example: ``$'').
If it is an amount, return the value of that amount as a new
amount (usually calculated as commodity price times source amount).
@item date
The date to use for determining the value. If null, it means no
date was specified, which can mean whatever you want it to mean.
@item target
If not null, a string representing the desired target commodity
that the commodity price, or repriced amount, should be valued
in. Note that this string can be a comma-separated list, and
that some or all of the commodities in that list may be suffixed
with an exclamation mark, to indicate what is being desired.
@end itemize
In most cases, it is simplest to either use explicit amounts in your valuation
expressions, or just pass the arguments down to market after modifying them to
suit your needs.
@node Automated transactions, , Lot value expressions, Transactions
@section Automated transactions
An automated transaction is a special kind of transaction which adds its
postings to other transactions any time one of that other transactions'
postings matches its predicate. The predicate uses the same query syntax as
the Ledger command line.
Consider this posting:
@smallexample
2012-03-10 KFC
Expenses:Food $20.00
Assets:Cash
@end smallexample
If I write this automated transaction before it in the file:
@smallexample
= expr true
Foo $50.00
Bar $-50.00
@end smallexample
Then the first transaction will be modified during parsing as if I'd written
this:
@smallexample
2012-03-10 KFC
Expenses:Food $20.00
Foo $50.00
Bar $-50.00
Assets:Cash $-20.00
Foo $50.00
Bar $-50.00
@end smallexample
Despite this fancy logic, automated transactions themselves follow most of the
same rules as regular transactions: their postings must balance (unless you
use a virtual posting), you can have metadata, etc.
One thing you cannot do, however, is elide amounts in an automated
transaction.
@menu
* Amount multipliers::
* Accessing the matching posting's amount::
* Referring to the matching posting's account::
* Applying metadata to every matched posting::
* Applying metadata to the generated posting::
* State flags::
* Effective Dates::
* Periodic Transactions::
@end menu
@node Amount multipliers, Accessing the matching posting's amount, Automated transactions, Automated transactions
@subsection Amount multipliers
As a special case, if an automated transaction's posting's amount (phew) has
no commodity, it is taken as a multiplier upon the matching posting's cost.
For example:
@smallexample
= expr true
Foo 50.00
Bar -50.00
2012-03-10 KFC
Expenses:Food $20.00
Assets:Cash
@end smallexample
Then the latter transaction turns into this during parsing:
@smallexample
2012-03-10 KFC
Expenses:Food $20.00
Foo $1000.00
Bar $-1000.00
Assets:Cash $-20.00
Foo $1000.00
Bar $-1000.00
@end smallexample
@node Accessing the matching posting's amount, Referring to the matching posting's account, Amount multipliers, Automated transactions
@subsection Accessing the matching posting's amount
If you use an amount expression for an automated transaction's posting, that
expression has access to all the details of the matched posting. For example,
you can refer to that posting's amount using the ``amount'' value expression
variable:
@smallexample
= expr true
(Foo) (amount * 2) ; same as just "2" in this case
2012-03-10 KFC
Expenses:Food $20.00
Assets:Cash
@end smallexample
This becomes:
@smallexample
2012-03-10 KFC
Expenses:Food $20.00
(Foo) $40.00
Assets:Cash $-20.00
(Foo) $-40.00
@end smallexample
@node Referring to the matching posting's account, Applying metadata to every matched posting, Accessing the matching posting's amount, Automated transactions
@subsection Referring to the matching posting's account
Sometimes want to refer to the account that matched in some way within the
automated transaction itself. This is done by using the string $account,
anywhere within the account part of the automated posting:
@smallexample
= food
(Budget:$account) 10
2012-03-10 KFC
Expenses:Food $20.00
Assets:Cash
@end smallexample
Becomes:
@smallexample
2012-03-10 KFC
Expenses:Food $20.00
(Budget:Expenses:Food) $200.00
Assets:Cash $-20.00
@end smallexample
@node Applying metadata to every matched posting, Applying metadata to the generated posting, Referring to the matching posting's account, Automated transactions
@subsection Applying metadata to every matched posting
If the automated transaction has a transaction note, that note is copied
(along with any metadata) to every posting that matches the predicate:
@smallexample
= food
; Foo: Bar
(Budget:$account) 10
2012-03-10 KFC
Expenses:Food $20.00
Assets:Cash
@end smallexample
Becomes:
@smallexample
2012-03-10 KFC
Expenses:Food $20.00
; Foo: Bar
(Budget:Expenses:Food) $200.00
Assets:Cash $-20.00
@end smallexample
@node Applying metadata to the generated posting, State flags, Applying metadata to every matched posting, Automated transactions
@subsection Applying metadata to the generated posting
If the automated transaction's posting has a note, that note is carried to the
generated posting within the matched transaction:
@smallexample
= food
(Budget:$account) 10
; Foo: Bar
2012-03-10 KFC
Expenses:Food $20.00
Assets:Cash
@end smallexample
Becomes:
@smallexample
2012-03-10 KFC
Expenses:Food $20.00
(Budget:Expenses:Food) $200.00
; Foo: Bar
Assets:Cash $-20.00
@end smallexample
This is slightly different from the rules for regular transaction notes, in
that an automated transaction's note does not apply to every posting within
the automated transaction itself, but rather to every posting it matches.
@node State flags, Effective Dates, Applying metadata to the generated posting, Automated transactions
@subsection State flags
Although you cannot mark an automated transaction as a whole as cleared or
pending, you can mark its postings with a * or ! before the account name, and
that state flag gets carried to the generated posting.
@node Effective Dates, Periodic Transactions, State flags, Automated transactions
@subsection Effective Dates
@cindex effective dates
In the real world transactions do not take place instantaneously.
Purchases can take several days to post to a bank account. And you may
pay ahead for something for which you want to distribute costs. With
Ledger you can control every aspect of the timing of a transaction.
Say you're in business. If you bill a customer, you can enter
something like
@cindex effective date of invoice
@smallexample
2008/01/01=2008/01/14 Client invoice ; estimated date you'll be paid
Assets:Accounts Receivable $100.00
Income: Client name
@end smallexample
@noindent Then, when you receive the payment, you change it to
@smallexample
2008/01/01=2008/01/15 Client invoice ; actual date money received
Assets:Accounts Receivable $100.00
Income: Client name
@end smallexample
@noindent and add something like
@smallexample
2008/01/15 Client payment
Assets:Checking $100.00
Assets:Accounts Receivable
@end smallexample
Now
@smallexample
ledger --subtotal --begin 2008/01/01 --end 2008/01/14 bal Income
@end smallexample
@noindent gives you your accrued income in the first two weeks of the year, and
@smallexample
ledger --effective --subtotal --begin 2008/01/01 --end 2008/01/14 bal Income
@end smallexample
@noindent gives you your cash basis income in the same two weeks.
Another use is distributing costs out in time. As an example, suppose
you just prepaid into a local vegetable co-op that sustains you through
the winter. It cost $225 to join the program, so you write a check.
You don't want your October grocery budget to be blown because you bought
food ahead, however. What you really want is for the money to be evenly
distributed over the next six months so that your monthly budgets
gradually take a hit for the vegetables you'll pick up from the co-op,
even though you've already paid for them.
@smallexample
2008/10/16 * (2090) Bountiful Blessings Farm
Expenses:Food:Groceries $ 37.50 ; [=2008/10/01]
Expenses:Food:Groceries $ 37.50 ; [=2008/11/01]
Expenses:Food:Groceries $ 37.50 ; [=2008/12/01]
Expenses:Food:Groceries $ 37.50 ; [=2009/01/01]
Expenses:Food:Groceries $ 37.50 ; [=2009/02/01]
Expenses:Food:Groceries $ 37.50 ; [=2009/03/01]
Assets:Checking
@end smallexample
This entry accomplishes this. Every month until you'll start with an
automatic $37.50 deficit like you should, while your checking account
really knows that it debited $225 this month.
@node Periodic Transactions, , Effective Dates, Automated 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 without the @samp{--budget} option specified.
See @ref{Budgeting and Forecasting} for examples and details.
@node Building Reports, Reporting Commands, Transactions , Top
@chapter Building Reports
@menu
* Introduction::
* Balance Reports::
* Typical queries::
* Advanced Reports::
@end menu
@node Introduction, Balance Reports, Building Reports, Building Reports
@section Introduction
The power of Ledger comes from the incredible flexibility in its
reporting commands, combined with formatting commands. Some options
control what is included in the calculations, and formatting controls
how it is displayed. The combinations are infinite. This chapter will
show you the basics of combining various options and commands. In the next
chapters you will find details about the specific commands and
options.
@node Balance Reports, Typical queries, Introduction, Building Reports
@section Balance Reports
@menu
* Controlling the Accounts and Payees::
* Controlling formatting::
@end menu
@node Controlling the Accounts and Payees, Controlling formatting, Balance Reports, Balance Reports
@subsection Controlling the Accounts and Payees
The balance report is the most commonly used report. The simplest invocation is:
@smallexample
ledger balance -f drewr3.dat
@end smallexample
@noindent which will print the balances of every account in your journal.
@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
Most times this is more than you want. Limiting the results to specific
accounts is as easy as entering the names of the accounts after the
command.
@smallexample
20:37:53 ~/ledger/test/input > ledger balance -f drewr3.dat Auto MasterCard
$ 5,500.00 Expenses:Auto
$ -20.00 Liabilities:MasterCard
--------------------
$ 5,480.00
20:39:21 ~/ledger/test/input >
@end smallexample
@noindent note the implicit logical and between @samp{Auto} and @samp{Mastercard}.
If you want the entire contents of a branch of your account tree, use the
highest common name in the branch:
@smallexample
20:39:21 ~/ledger/test/input > ledger balance -f drewr3.dat Income
$ -2,030.00 Income
$ -2,000.00 Salary
$ -30.00 Sales
--------------------
$ -2,030.00
20:40:28 ~/ledger/test/input >
@end smallexample
You can use general regular expressions in nearly anyplace Ledger needs a string:
@smallexample
20:40:28 ~/ledger/test/input > ledger balance -f drewr3.dat ^Bo
21:13:29 ~/ledger/test/input > ledger balance -f drewr3.dat Bo
$ 20.00 Expenses:Books
@end smallexample
The first example looks for any account starting with ``Bo'', of which
there are none. The second looks for any account with ``Bo'', which is
@samp{Expenses:Books}.
@cindex limit by payees
If you want to know exactly how much you have spent in a particular
account on a particular payee, the following are equivalent:
@smallexample
> ledger balance Auto:Fuel and Chevron
> ledger balance --limit "(account=~/Fuel/) & (payee=~/Chev/)"
@end smallexample
@noindent will show you the amount expended on gasoline at Chevron.
The second example is the first example of the very power expression
language available to shape reports. The first example may be easier to
remember, but learning to use the second will open up far more
possibilities.
If you want to exclude specific accounts from the report, you can
exclude multiple accounts with parentheses:
@smallexample
ledger -s bal Expenses and not \(Expenses:Drinks or Expenses:Candy or Expenses:Gifts\)
@end smallexample
@node Controlling formatting, , Controlling the Accounts and Payees, Balance Reports
@subsection Controlling Formatting
These examples all use the default formatting for the balance
report. Customizing the formatting can easily allowing to see only what
you want, or interface Ledger with other programs.
@node Typical queries, Advanced Reports, Balance Reports, Building Reports
@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 last October;
show all sub-accounts; sort by the absolute value of the total; and
report the balance for all accounts that begin with ``expenses''.
@menu
* Reporting monthly expenses::
@end menu
@node Reporting monthly expenses, , 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 "(amount)" 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 "(amount)" -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 --display "account =~ /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 --display "account =~ /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 Advanced Reports, , Typical queries, Building Reports
@section Advanced Reports
@menu
* Asset Allocation::
* Visualizing with Gnuplot::
@end menu
@node Asset Allocation, Visualizing with Gnuplot, Advanced Reports, Advanced Reports
@subsection Asset Allocation
A very popular method of managing portfolios is to control the
percent allocation of assets by certain categories. The mix of
categories and the weights applied to them vary by investing
philosophy, but most follow a similar pattern. Tracking asset
allocation in ledger is not difficult but does require some additional
effort to describe how the various assets you own contribute to the
asset classes you want to track.
In our simple example we assume you want to apportion you assets into
the general categories of domestic and international equities (stocks)
and a combined category of bonds and cash. For illustrative purposes we
will use several publicly available mutual funds from Vanguard. the
three funds we will track are the Vanguard 500 IDX FD Signal (VIFSX),
the Vanguard Target Retirement 2030 (VTHRX), and the Vanguard Short Term
Federal Fund (VSGBX). Each of these funds allocates assets to different
categories of the investment universe and in different proportions.
When you buy a share of VTHRX, that share is partially invested in
equities, and partially invested in bonds and cash. Below is the asset
allocation for each of the instruments listed above:
@multitable @columnfractions .2 .2 .3 .3
@item @tab Domestic @tab Global @tab
@item Symbol @tab Equity @tab Equity @tab bonds/cash
@item VIFSX @tab 100% @tab @tab
@item VTHRX @tab 24.0% @tab 56.3% @tab 19.7%
@item VSGBX @tab @tab @tab 100%
@end multitable
These numbers are available from the prospectus of any publicly
available mutual fund. Of course a single stock issue is 100% equity
and a single bond issue is 100% bonds.
We track purchases of specific investments using the symbol of that
investment as its commodity. How do we tell Ledger that a share of
VTHRX is 24% Global equity etc.? Enter automatic transactions and
virtual accounts.
At the top of our ledger we enter automatic transactions that describe
these proportions to Ledger. In the same entries we set up virtual
accounts that let us separate these abstract calculations from our
actual balances.
For the three instruments listed above, those automatic transactions
would look like:
@smallexample
;
; automatic calculations for asset allocation tracking
;
= expr ( commodity == 'VIFSX' )
(Allocation:Equities:Domestic) 1.000
= expr ( commodity == 'VTHRX' )
(Allocation:Equities:Global) 0.240
(Allocation:Equities:Domestic) 0.563
(Allocation:Bonds/Cash) 0.197
= expr ( commodity == 'VBMFX')
(Allocation:Bonds/Cash) 1.000
@end smallexample
How do these work? First the `=' sign at the beginning of the line tells
ledger this is an automatic transaction to be applied when the condition
following the `=' is true. After the `=' sign is a value expression
(@pxref{Value Expressions}) that returns true any time a posting
contains the commodity of interest.
The following line gives the proportions (not percentages) of each unit
of commodity that belongs to each asset class. Whenever Ledger sees a
buy or sell of a particular commodity it will credit or debit these
virtual accounts with that proportion of the number of shares moved.
Now that Ledger understands how to distribute the commodities amongst
the various asset classes how do we get a report that tells us our
current allocation? Using the balance command and some tricky formatting!
@smallexample
ledger bal Allocation --current --format "\
%-17((depth_spacer)+(partial_account))\
%10(percent(market(display_total), market(parent.total)))\
%16(market(display_total))\n%/"
@end smallexample
@noindent Which yields:
@smallexample
Allocation 100.00% $100000.00
Bonds/Cash 38.94% $38940.00
Equities 61.06% $61060.00
Domestic 95.31% $58196.29
Global 4.69% $2863.71
@end smallexample
Let's look at the Ledger invocation a bit closer. The command above is
split into lines for clarity. The first line is very vanilla Ledger
asking for the current balances of the account in the ``Allocation''
tree, using a special formatter.
@cindex depth_spacer
@findex depth_spacer
@findex display_total
@findex parent.total
The magic is in the formatter. The second line simply tells Ledger to
print the partial account name indented by its depth in the tree. The
third line is where we calculate and display the percentages. The
@code{display_total} command give the values of the total calculated for
the account in this line. The @code{parent.total} command gives the
total for the next level up in the tree. @code{percent} formats their
ratio as a percentage. The fourth line tells ledger to display the
current market value of the the line. The last two characters ``%/''
tell Ledger what to do for the last line, in this case, nothing.
@cindex plotting
@cindex GNUplot
@node Visualizing with Gnuplot, , Asset Allocation, Advanced Reports
@subsection Visualizing with Gnuplot
@cindex GNUplot script
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{contrib/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 (--amount-data)} or
@option{-J (--total-data)} 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 --display "account =~ /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.
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 Reporting Commands, Command-line Syntax, Building Reports, Top
@chapter Reporting Commands
@menu
* Primary Financial Reports:: Reports in other formats:: Reports about
* 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
* The balance Command::
* The equity Command::
* The register Command::
* The print Command::
@end menu
@node The balance Command, The equity Command, Primary Financial Reports, Primary Financial Reports
@subsection The @code{balance} Command
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 The equity Command, The register Command, The balance Command, Primary Financial Reports
@subsection The @code{equity} Command
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}.
@node The register Command, The print Command, The equity Command, Primary Financial Reports
@subsection The @code{register} Command
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 The print Command, , The register Command, Primary Financial Reports
@subsection The @code{print} Command
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
* Comma Separated Variable files::
* Emacs::
* Emacs org mode::
* The pricemap Command::
* The xml Command::
* prices and pricedb::
@end menu
@node Comma Separated Variable files, Emacs, Reports in other Formats, Reports in other Formats
@subsection Comma Separated Variable files
@menu
* The csv command::
* The convert command::
@end menu
@node The csv command, The convert command, Comma Separated Variable files, Comma Separated Variable files
@subsubsection The @code{csv} command
The csv command will output print out the desired ledger transactions in
a csv format suitable for import into other programs. You can determine
the transaction to print using all the normal limiting and searching
functions.
@cindex csv conversion
@cindex reading csv
@cindex comma separated variable file reading
@node The convert command, , The csv command, Comma Separated Variable files
@subsubsection The @code{convert} command
Convert reads your Ledger journal then parses a comma separated value
(csv) file into Ledger transactions. Many banks offer csv file
downloads. Unfortunately the file formats, aside form the commas, are
all different. The ledger convert command tried to help as much as it
can.
Your banks csv files will have fields in different orders from other
banks, so there must be a way to tell Ledger what to expect. Insert a
line at the beginning of the csv file that describes the fields to Ledger.
For example, this is a portion of a csv file downloaded from a credit
union in the United States:
@smallexample
Account Name: VALUFIRST CHECKING
Account Number: 71
Date Range: 11/13/2011 - 12/13/2011
Transaction Number,Date,Description,Memo,Amount Debit,Amount Credit,Balance,Check Number,Fees
767718,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-8.80,,00001640.04,,
767406,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-1.03,,00001648.84,,
683342,12/13/2011,"Visa Checking","NetFlix Date 12/12/11 000326585896 5968",-21.85,,00001649.87,,
639668,12/13/2011,"Withdrawal","ID: 1741472662 CO: XXAA.COM PAYMNT",-236.65,,00001671.72,,
1113648,12/12/2011,"Withdrawal","Tuscan IT #00037657",-29.73,,00001908.37,,
@end smallexample
Unfortunately, as it stands Ledger cannot read it, but you can. Ledger
expects the first line to contain a description of the fields on each
line of the file. The fields ledger can recognize are called
``@code{date}'' ``@code{posted}'', ``@code{code}'', ``@code{payee} or
@code{desc}'', ``@code{amount}'', ``@code{cost}'', ``@code{total}'', and
``@code{note}''.
Delete the account description lines at the top, and replace the first line in the data above with:
@smallexample
date,payee,note,amount,,,code,
@end smallexample
Then execute ledger like this:
@smallexample
ledger convert download.csv --input-date-format "%m/%d/%Y"
@end smallexample
Where the @code{--input-date-format} option tells ledger how to
interpret the dates.
Importing csv files is a lot of work, and but is very amenable to scripting.
@node Emacs, Emacs org mode, Comma Separated Variable files, 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 @code{sexp} is:
@smallexample
((BEG-POS CLEARED DATE CODE PAYEE
(ACCOUNT AMOUNT)...) ; list of postings
...) ; list of transactions
@end smallexample
@node Emacs org mode, The pricemap Command, Emacs, Reports in other Formats
@subsection Emacs @code{org} Mode
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}.
Org mode has a sub-system known as babel which allows for literate
programming. This allows you to mix text and code within the same
document and automatically execute code which may generate results which
will then appear in the text.
One of the languages supported by org+babel is ledger so that you can
have ledger commands embedded in a text file and have the output of
ledger commands also appear in the text file. The output can be
updated whenever any new ledger entries are added.
For instance, the following org mode text document snippet illustrates a
very naive but still useful of the org+babel system:
@smallexample
* A simple test of ledger in an org file
The following are some entries and I have requested that ledger be run
to generate a balance on the accounts. I could have asked for a
register or, in fact, anything at all the ledger can do through command
line options.
#+begin_src ledger :cmdline -s bal :results value
2010/01/01 * Starting balance
assets:bank:savings £1300.00
income:starting balances
2010/07/22 * Got paid
assets:bank:chequing £1000.00
income:salary
2010/07/23 Rent
expenses:rent £500.00
assets:bank:chequing
#+end_src
#+results:
: £1800.00 assets:bank
: £500.00 chequing
: £1300.00 savings
: £500.00 expenses:rent
: £-2300.00 income
: £-1000.00 salary
: £-1300.00 starting balances
@end smallexample
Typing @command{C-c C-c} anywhere in the ``ledger source code block''
will invoke ledger on the contents of that block and generate a
``results'' block. The results block can appear anywhere in the file
but, by default, will appear immediately below the source code block.
You can combine multiple source code blocks before executing ledger and
do all kinds of other wonderful things with Babel (and org).
@subsection Org-mode with Babel
Using Babel, it is possible to record financial transactions
conveniently in an org file and subsequently generate the financial
reports required.
With a recent version of org (7.01+), Ledger support is provided. To use
it, enable Ledger support. Check the Babel documentation on Worg for
instructions on how to achieve this but I currently do this directly as
follows:
@smallexample
(org-babel-do-load-languages
'org-babel-load-languages
'((ledger . t) ;this is the important one for this tutorial
))
@end smallexample
Once Ledger support in Babel has been enabled, we can use proceed to
include Ledger entries within an org file. There are three ways (at
least) in which these can be included:
@enumerate
@item
place all Ledger entries within one source block and execute
this block with different arguments to generate the appropriate
reports;
@item
place Ledger entries in more than one source block and use the
noweb literary programming approach, supported by babel, to
combine these into one block elsewhere in the file for
processing by Ledger; and,
@item
place Ledger entries in different source blocks and use
tangling to generate a Ledger file which you can subsequently
process using Ledger directly.
@end enumerate
The first two are described in more detail in this short tutorial.
@subsubheading Embedded Ledger example with single source block
The easiest, albeit possibly less useful, way in which to use Ledger
within an org file is to use a single source block to record all Ledger
entries. The following is an example source block:
@smallexample
#+name: allinone
#+begin_src ledger
2010/01/01 * Starting balance
assets:bank:savings £1300.00
income:starting balances
2010/07/22 * Got paid
assets:bank:chequing £1000.00
income:salary
2010/07/23 Rent
expenses:rent £500.00
assets:bank:chequing
2010/07/24 Food
expenses:food £150.00
assets:bank:chequing
2010/07/31 * Interest on bank savings
assets:bank:savings £3.53
income:interest
2010/07/31 * Transfer savings
assets:bank:savings £250.00
assets:bank:chequing
2010/08/01 got paid again
assets:bank:chequing £1000.00
income:salary
#+end_src
@end smallexample
In this example, we have combined both expenses and income into one set
of Ledger entries. We can now generate register and balance reports (as
well as many other types of reports) using babel to invoke Ledger with
specific arguments. The arguments are passed to Ledger using the
:cmdline header argument. In the code block above, there is no such
argument so the system takes the default. For Ledger code blocks, the
default :cmdline argument is bal and the result of evaluating this code
block (@command{C-c C-c}) would be:
@smallexample
#+results: allinone()
: £2653.53 assets
: £650.00 expenses
: £-3303.53 income
@end smallexample
If, instead, you wished to generate a register of all the transactions,
you would change the #+begin_src line for the code block to include the
required command line option:
@smallexample
#+begin_src ledger :cmdline reg
@end smallexample
Evaluating the code block again would generate a different report.
Having to change the actual directive on the code block and re-evaluate
makes it difficult to have more than one view of your transactions and
financial state. Eventually, babel will support passing arguments to
#+call evaluations of code blocks but this support is missing
currently. Instead, we can use the concepts of literary programming, as
implemented by the noweb features of babel, to help us.
@subsubheading Multiple Ledger source blocks with noweb
The noweb feature of babel allows us to expand references to other code
blocks within a code block. For Ledger, this can be used to group
transactions according to type, say, and then bring various sets of
transactions together to generate reports.
Using the same transactions used above, we could consider splitting
these into expenses and income, as follows:
@subsubheading Income Entries
The first set of entries relates to income, either monthly pay or
interest, all typically going into one of my bank accounts. Here, I have
placed several entries, but we could have had each entry in a separate
src block. Note that all code blocks you wish to refer to later must
have the :noweb yes babel header argument specified.
@smallexample
#+name: income
#+begin_src ledger :noweb yes
2010/01/01 * Starting balance
assets:bank:savings £1300.00
income:starting balances
2010/07/22 * Got paid
assets:bank:chequing £1000.00
income:salary
2010/07/31 * Interest on bank savings
assets:bank:savings £3.53
income:interest
2010/07/31 * Transfer savings
assets:bank:savings £250.00
assets:bank:chequing
2010/08/01 got paid again
assets:bank:chequing £1000.00
income:salary
#+end_src
@end smallexample
@subsubheading Expenses
The following entries relate to personal expenses, such as rent and
food. Again, these have all been placed in a single src block but could
have been done individually.
@smallexample
#+name: expenses
#+begin_src ledger :noweb yes
2010/07/23 Rent
expenses:rent £500.00
assets:bank:chequing
2010/07/24 Food
expenses:food £150.00
assets:bank:chequing
#+end_src
@end smallexample
@subsubheading Financial Summaries
Given the ledger entries defined above in the income and expenses code
blocks, we can now refer to these using the noweb expansion directives,
<<name>>. We can now define different code blocks to generate specific
reports for those transactions. Below are two examples, one to generate
a balance report and one to generate a register report of all
transactions.
@subsubheading An overall balance summary
The overall balance of your account and expenditure with a breakdown
according to category is specified by passing the :cmdline bal argument
to Ledger. This code block can now be evaluated (C-c C-c) and the
results generated by incorporating the transactions referred to by the
<<income>> and <<expenses>>= lines.
@smallexample
#+name: balance
#+begin_src ledger :cmdline bal :noweb yes
<<income>>
<<expenses>>
#+end_src
#+results: balance
: £2653.53 assets
: £650.00 expenses
: £-3303.53 income
@end smallexample
If you want a more detailed breakdown of where your money is and where
it has been spent, you can specify the -s flag (i.e. :cmdline -s bal) to
tell Ledger to include sub-accounts in the report.
@smallexample
#+begin_src ledger :cmdline -s bal :noweb yes
<<income>>
<<expenses>>
#+end_src
#+results:
: £2653.53 assets:bank
: £1100.00 chequing
: £1553.53 savings
: £650.00 expenses
: £150.00 food
: £500.00 rent
: £-3303.53 income
: £-3.53 interest
: £-2000.00 salary
: £-1300.00 starting balances
@end smallexample
@subsubheading Generating a monthly register
You can also generate a monthly register (the reg command) by executing
the following src block. This presents a summary of transactions for
each monthly period (the -M argument) with a running total in the final
column (which should be 0 at the end if all the entries are correct).
@smallexample
#+name: monthlyregister
#+begin_src ledger :cmdline -M reg :noweb yes
<<income>>
<<expenses>>
#+end_src
#+results: monthlyregister
:2010/01/01 - 2010/01/31 assets:bank:savings £1300.00 £1300.00
: in:starting balances £-1300.00 0
:2010/07/01 - 2010/07/31 assets:bank:chequing £100.00 £100.00
: assets:bank:savings £253.53 £353.53
: expenses:food £150.00 £503.53
: expenses:rent £500.00 £1003.53
: income:interest £-3.53 £1000.00
: income:salary £-1000.00 0
:2010/08/01 - 2010/08/01 assets:bank:chequing £1000.00 £1000.00
: income:salary £-1000.00 0
@end smallexample
We could also generate a monthly report on our assets showing how these
are increasing (or decreasing!). In this case, the final column will be
the running total of the assets in our ledger.
@smallexample
#+name: monthlyassetsregister
#+begin_src ledger :cmdline -M reg assets :noweb yes
<<income>>
<<expenses>>
#+end_src
#+results: monthlyassetsregister
: 2010/01/01 - 2010/01/31 assets:bank:savings £1300.00 £1300.00
: 2010/07/01 - 2010/07/31 assets:bank:chequing £100.00 £1400.00
: assets:bank:savings £253.53 £1653.53
: 2010/08/01 - 2010/08/01 assets:bank:chequing £1000.00 £2653.53
@end smallexample
@subsubheading Summary
This short tutorial shows how Ledger entries can be embedded in a org
file and manipulated using Babel. However, only simple Ledger features
have been illustrated; please refer to the Ledger documentation for
examples of more complex operations with a ledger.
@node The pricemap Command, The xml Command, Emacs org mode, Reports in other Formats
@subsection The @code{pricemap} Command
@node The xml Command, prices and pricedb, The pricemap Command, Reports in other Formats
@subsection The @code{xml} Command
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 multiple precision arithmetic 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, , The xml Command, 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
database files.
@node Reports about your Journals, Developer Commands, Reports in other Formats, Reporting Commands
@section Reports about your Journals
@menu
* accounts::
* commodities::
* entry and xact::
* payees::
@end menu
@node accounts, commodities, 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 commodities, entry and xact, accounts, 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 payees 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::
* Debug Options::
* 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, Debug Options, reload, Developer Commands
@subsection source
The @code{source} command take a journal file as an argument and parses
it checking for errors, no other reports are generated, and no other
arguments are necessary. Ledger will return success if no errors are
found.
@node Debug Options, Pre-commands, source, Developer Commands
@subsection Debug Options
These options are primarily for Ledger developers, but may be of some
use to a user trying something new.
@option{--args-only} ignore init
files and environment variables for the ledger run.
@option{--verify} enable additional assertions during run-time. This
causes a significant slowdown. When combined with @option{--debug}
ledger will produce memory trace information.
@option{--debug "argument"} If Ledger has been built with debug options
this will provide extra data during the run. The following are the
available arguments to debug:
@multitable @columnfractions .32 .43 .27
@item @code{account.display} @tab @code{expr.calc.when} @tab @code{org.next_amount}
@item @code{accounts.sorted} @tab @code{expr.compile} @tab @code{org.next_total}
@item @code{amount.convert} @tab @code{filters.changed_value} @tab @code{parser.error}
@item @code{amount.is_zero} @tab @code{filters.changed_value.rounding} @tab @code{pool.commodities}
@item @code{amount.parse} @tab @code{filters.collapse} @tab @code{post.assign}
@item @code{amount.price} @tab @code{filters.forecast} @tab @code{python.init}
@item @code{amount.truncate} @tab @code{filters.revalued} @tab @code{python.interp}
@item @code{amount.unround} @tab @code{format.abbrev} @tab @code{query.mask}
@item @code{amounts.commodities} @tab @code{format.expr} @tab @code{report.predicate}
@item @code{amounts.refs} @tab @code{generate.post} @tab @code{scope.symbols}
@item @code{archive.journal} @tab @code{generate.post.string} @tab @code{textual.include}
@item @code{auto.columns} @tab @code{item.meta} @tab @code{textual.parse}
@item @code{budget.generate} @tab @code{ledger.read} @tab @code{timelog}
@item @code{commodity.annotated.strip} @tab @code{ledger.validate} @tab @code{times.epoch}
@item @code{commodity.annotations} @tab @code{lookup} @tab @code{times.interval}
@item @code{commodity.compare} @tab @code{lookup.account} @tab @code{times.parse}
@item @code{commodity.download} @tab @code{mask.match} @tab @code{value.sort}
@item @code{commodity.prices.add} @tab @code{memory.counts} @tab @code{value.storage.refcount}
@item @code{commodity.prices.find} @tab @code{memory.counts.live} @tab @code{xact.extend}
@item @code{convert.csv} @tab @code{memory.debug} @tab @code{xact.extend.cleared}
@item @code{csv.mappings} @tab @code{op.cons} @tab @code{xact.extend.fail}
@item @code{csv.parse} @tab @code{op.memory} @tab @code{xact.finalize}
@item @code{draft.xact} @tab @code{option.args}
@item @code{expr.calc} @tab @code{option.names}
@end multitable
@option{--trace INTEGER_TRACE_LEVEL}
Enable tracing. The integer specifies the level of trace desired:
@multitable @columnfractions .3 .7
@item @code{LOG_OFF} @tab 0
@item @code{LOG_CRIT} @tab 1
@item @code{LOG_FATAL} @tab 2
@item @code{LOG_ASSERT} @tab 3
@item @code{LOG_ERROR} @tab 4
@item @code{LOG_VERIFY} @tab 5
@item @code{LOG_WARN} @tab 6
@item @code{LOG_INFO} @tab 7
@item @code{LOG_EXCEPT} @tab 8
@item @code{LOG_DEBUG} @tab 9
@item @code{LOG_TRACE} @tab 10
@item @code{LOG_ALL} @tab 11
@end multitable
@option{--verbose}
Print detailed information on the execution of Ledger.
@option{--version}
Print version information and exit.
@node Pre-commands, , Debug Options, Developer Commands
@subsection Pre-Commands
Pre-commands are useful when you aren't sure how a command or option
will work.
@table @code
@item args
evaluate the given arguments against the following model transaction:
@smallexample
2004/05/27 Book Store
; This note applies to all postings. :SecondTag:
Expenses:Books 20 BOOK @@ $10
; Metadata: Some Value
; Typed:: $100 + $200
; :ExampleTag:
; Here follows a note describing the posting.
Liabilities:MasterCard $-200.00
@end smallexample
@item eval
evaluate the given value expression against the model transaction
@item expr "LIMIT EXPRESSION"
Print details of how ledger parses the given limit expression and apply
it against a model transaction.
@item format "FORMATTING"
Print details of how ledger uses the given formatting description and
apply it against a model transaction.
@item generate
@item parse <VALUE EXPR>
Print details of how ledger uses the given value expression description
and apply it against a model transaction.
@item period
evaluate the given period and report how Ledger interprets it:
@smallexample
20:22:21 ~/ledger (next)> ledger period "this year"
--- Period expression tokens ---
TOK_THIS: this
TOK_YEAR: year
END_REACHED: <EOF>
--- Before stabilization ---
range: in year 2011
--- After stabilization ---
range: in year 2011
start: 11-Jan-01
finish: 12-Jan-01
--- Sample dates in range (max. 20) ---
1: 11-Jan-01
@end smallexample
@item query
evaluate the given query and report how Ledger interprets it against the
model transaction:
@smallexample
20:25:42 ~/ledger (next)> ledger query "/Book/"
--- Input arguments ---
("/Book/")
--- Context is first posting of the following transaction ---
2004/05/27 Book Store
; This note applies to all postings. :SecondTag:
Expenses:Books 20 BOOK @ $10
; Metadata: Some Value
; Typed:: $100 + $200
; :ExampleTag:
; Here follows a note describing the posting.
Liabilities:MasterCard $-200.00
--- Input expression ---
(account =~ /Book/)
--- Text as parsed ---
(account =~ /Book/)
--- Expression tree ---
0x7fd639c0da40 O_MATCH (1)
0x7fd639c10170 IDENT: account (1)
0x7fd639c10780 VALUE: /Book/ (1)
--- Compiled tree ---
0x7fd639c10520 O_MATCH (1)
0x7fd639c0d6c0 IDENT: account (1)
0x7fd639c0d680 FUNCTION (1)
0x7fd639c10780 VALUE: /Book/ (1)
--- Calculated value ---
true
@end smallexample
@item template
@end table
@node Command-line Syntax, Budgeting and Forecasting, Reporting Commands, 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
@menu
* Global Options::
* Session Options::
* Report Options::
* Report Filtering::
* Search Terms::
* Output Customization::
* Commodity Reporting::
* Environment Variables::
@end menu
@node Global Options, Session Options, Detailed Options Description, Detailed Options Description
@subsection Global Options
Options for Ledger report affect three separate scopes of operation:
Global, Session, and Report. In practice there is very little
difference between these scopes. Ledger 3.0 contains provisions for
GUIs, which would make use of the different scopes by keeping an
instance of Ledger running in the background and running multiple
sessions with multiple reports per session.
@option{--args-only} Ignore all environment and init-file settings and
use only command-line arguments to control Ledger. Useful for debugs
or testing small Journal files not associated with you main financial
database.
@option{--help}
Displays the info page for ledger.
@option{--init-file <PATH>}
Specifies the location of the init file @file{.ledgerrc}
@option{--options} Display the options in effect for this Ledger
invocation, along with their values and the source of those values, for
example:
@smallexample
14:15:02 > ledger --options bal --cleared -f ~/ledger/test/input/drewr3.dat
===============================================================================
[Global scope options]
[Session scope options]
--file = ~/ledger/test/input/drewr3.dat -f
--price-db = ~/FinanceData/PriceDB $price-db
[Report scope options]
--cleared --cleared
--color ?normalize
--date-format = %Y/%m/%d $date-format
--limit = cleared --cleared
--prepend-width = 0 ?normalize
--meta-width = 0 ?normalize
--date-width = 10 ?normalize
--payee-width = 21 ?normalize
--account-width = 21 ?normalize
--amount-width = 12 ?normalize
--total-width = 12 ?normalize
===============================================================================
$ 775.00 Assets:Checking
$ -1,000.00 Equity:Opening Balances
$ 225.00 Expenses:Food:Groceries
--------------------
0
@end smallexample
@noindent For the `source' column, a value starting with a `@code{-}' or
`@code{--}' indicated the source was a command line argument. It the
entry starts with a `@code{$}', the source was an environment
variable. If the source is `@code{?normalize}' the value was set
internally by ledger, in a function called @code{normalize_options}.
@option{--script <PATH>} Execute a ledger script.
@node Session Options, Report Options, Global Options, Detailed Options Description
@subsection Session Options
Options for Ledger report affect three separate scopes of operation:
Global, Session, and Report. In practice there is very little
difference between these scopes. Ledger 3.0 contains provisions for
GUIs, which would make use of the different scopes by keeping an
instance of Ledger running in the background and running multiple
sessions with multiple reports per session.
@option{--decimal-comma} Direct Ledger to parse journals using the
European standard comma as decimal separator, vice a period.
@option{--download} Direct Ledger to download prices using the script
defined in @code{--getquote}.
@option{--file <PATH>}
Specify the input file path for this invocation.
@cindex getquote
@cindex download prices
@option{--getquote <PATH>} Tells ledger where to find the user defined
script to download prices information.
@option{--input-date-format <DATE-FORMAT>} Specify the input date format
for journal entries. For example,
@smallexample
ledger convert Export.csv --input-date-format "%m/%d/%Y"
@end smallexample
Would convert the @file{Export.csv} file to ledger format, assuming the
the dates in the CSV file are like 12/23/2009 (@pxref{Date and Time Format Codes}).
@option{--master-account <ARGUMENT>} Prepends all account names with the
argument.
@smallexample
21:51:39 ~/ledger (next)> ledger -f test/input/drewr3.dat bal --master-account HUMBUG
0 HUMBUG
$ -3,804.00 Assets
$ 1,396.00 Checking
$ 30.00 Business
$ -5,200.00 Savings
$ 20.00 Books
$ -1,000.00 Equity:Opening Balances
$ 6,634.00 Expenses
$ 11,000.00 Auto
$ 20.00 Books
$ 300.00 Escrow
$ 334.00 Food:Groceries
$ 500.00 Interest:Mortgage
$ -5,520.00 ssets:Checking
$ -2,030.00 Income
$ -2,000.00 Salary
$ -30.00 Sales
$ 180.00 Liabilities
$ -20.00 MasterCard
$ 200.00 Mortgage:Principal
@end smallexample
@option{--price-db <PATH>} Specify the location of the price entry data
file.
@option{--price-exp INTEGER_MINUTES} Set 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 ‘--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{--strict} Ledger normally silently accepts any account or
commodity in a posting, even if you have misspelled a common used one.
The option @code{--strict} changes that behavior. While running
@code{--strict}, Ledger interprets all cleared transactions as correct,
and if it finds a new account or commodity (same as a misspelled
commodity or account) it will issue a warning giving you the file and
line number of the problem.
@node Report Options, Report Filtering, Session Options, Detailed Options Description
@subsection Report Options
Options for Ledger report affect three separate scopes of operation:
Global, Session, and Report. In practice there is very little
difference between these scopes. Ledger 3.0 contains provisions for
GUIs, which would make use of the different scopes by keeping an
instance of Ledger running in the background and running multiple
sessions with multiple reports per session.
@option{--abbrev-len <INT>} Sets the minimum
length an account can be abbreviated to if it doesn't fit inside the
@code{account-width}. If @code{abbrev-len} is zero, then the account
name will be truncated on the right. If @code{abbrev-len} is greater
than @code{account-width} then the account will be truncated on the
left, with no shortening of the account names in order to fit into the
desired width.
@option{--account <STR>} Prepend @code{<STR>} to all accounts
reported. That is, the option @code{--account Personal} would tack
@code{Personal:} to the beginning of every account reported in a balance
report or register report.
@option{--account-width <INT>} Set the width of the account column in
the @code{register} report to @code{N} characters.
@option{--actual-dates} Show actual dates of transactions
(@pxref{Effective Dates}). Also @code{-L}.
@option{--actual} Report only real transactions, with no automated or
virtual transactions used.
@option{--add-budget} Show only unbudgeted postings.
@option{--amount-data} On a register report print only the dates and
amount of postings. Useful for graphing and spreadsheet applications.
@option{--amount <EXPR>} Apply the given value expression to the posting
amount (@pxref{Value Expressions}). Using @code{--amount} you can apply
an arbitrary transformation to the postings.
@option{--amount-width <INT>} Set the width in characters of the amount
column in the register report.
@option{--anon} anonymizes registry output, mostly for sending in bug
reports.
@option{--average} Print average values over the number of transactions
instead of running totals.
@option{--balance-format <STR>} specifies the format to use for the
@code{balance} report (@pxref{Format Strings}). The default is:
@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
@option{--base} ASK JOHN
@option{--basis} Report the cost basis on all posting
@option{--begin <DATE>} Specify the start date of all calculations.
Transactions before that date will be ignored.
@option{--bold-if <EXPR>} print the entire line in bold if the given
value expression is true (@pxref{Value Expressions}).
@smallexample
ledger reg Expenses --begin Dec --bold-if "amount > 100"
@end smallexample
@noindent list all transactions since the beginning of December and bold any posting greater than $100
@option{--budget-format <FORMAT_STRING>}
specifies the format to use for the @code{budget} report (@pxref{Format Strings}). The default is:
@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
@option{--budget} only display budgeted items. In a register report this
displays transaction in the budget, in a balance report this displays
accounts in the budget (@pxref{Budgeting and Forecasting}).
@option{--by-payee <REGEXP>}
group the register report by payee.
@option{--cleared-format <FORMAT_STRING>} specifies the format to use
for the @code{cleared} report (@pxref{Format Strings}). The default is:
@smallexample
"%(justify(scrub(get_at(total_expr, 0)), 16, 16 + prepend_width, "
" true, color)) %(justify(scrub(get_at(total_expr, 1)), 18, "
" 36 + prepend_width, true, color))"
" %(latest_cleared ? format_date(latest_cleared) : \" \")"
" %(!options.flat ? depth_spacer : \"\")"
"%-(ansify_if(partial_account(options.flat), blue if color))\n%/"
"%$1 %$2 %$3\n%/"
"%(prepend_width ? \" \" * prepend_width : \"\")"
"---------------- ---------------- ---------\n"
@end smallexample
@option{--cleared} consider only transaction that have been cleared for
display and calculation.
@option{--collapse} By default ledger prints all account in an account
tree. With @code{--collapse} it print only the top level account
specified.
@option{--collapse-if-zero} Collapses the account display only if it has
a zero balance.
@option{--color} use color is the tty supports it.
@option{--columns <INT>} specify the width of the register report in
characters.
@option{--count} Direct ledger to report the number of items when
appended to the commodities, accounts or payees command.
@option{--csv-format} specifies the format to use for the @code{csv}
report (@pxref{Format Strings}). The default is:
@smallexample
"%(quoted(date)),"
"%(quoted(code)),"
"%(quoted(payee)),"
"%(quoted(display_account)),"
"%(quoted(commodity)),"
"%(quoted(quantity(scrub(display_amount)))),"
"%(quoted(cleared ? \"*\" : (pending ? \"!\" : \"\"))),"
"%(quoted(join(note | xact.note)))\n"
@end smallexample
@option{--current}
Shorthand for @code{--limit "date <= today"}
@option{--daily}
Shorthand for @code{--period "daily"}
@option{--date-format <DATE-FORMAT>} specifies format ledger should use
to print dates (@pxref{Date and Time Format Codes}).
@option{--date <EXPR>} transforms the date of the transaction using
@code{EXPR}
@option{--date-width <INT>} specifies the width, in characters, of the
date column in the register report.
@option{--datetime-format}
ASK JOHN
@option{--dc} Display register or balance in debit/credit format
If you use @samp{--dc} with either the register (reg) or balance (bal) commands, you
will now get extra columns. The register goes from this:
@smallexample
12-Mar-10 Employer Assets:Cash $100 $100
Income:Employer $-100 0
12-Mar-10 KFC Expenses:Food $20 $20
Assets:Cash $-20 0
12-Mar-10 KFC - Rebate Assets:Cash $5 $5
Expenses:Food $-5 0
12-Mar-10 KFC - Food & Reb.. Expenses:Food $20 $20
Expenses:Food $-5 $15
Assets:Cash $-15 0
@end smallexample
@noindent To this:
@smallexample
12-Mar-10 Employer Assets:Cash $100 0 $100
In:Employer 0 $100 0
12-Mar-10 KFC Expens:Food $20 0 $20
Assets:Cash 0 $20 0
12-Mar-10 KFC - Rebate Assets:Cash $5 0 $5
Expens:Food 0 $5 0
12-Mar-10 KFC - Food &.. Expens:Food $20 0 $20
Expens:Food 0 $5 $15
Assets:Cash 0 $15 0
@end smallexample
@noindent Where the first column is debits, the second is credits, and the third is the
running total. Only the running total may contain negative values.
For the balance report without @samp{--dc}:
@smallexample
$70 Assets:Cash
$30 Expenses:Food
$-100 Income:Employer
--------------------
0
@end smallexample
@noindent And with @samp{--dc} it becomes this:
@smallexample
$105 $35 $70 Assets:Cash
$40 $10 $30 Expenses:Food
0 $100 $-100 Income:Employer
--------------------------------------------
$145 $145 0
@end smallexample
@option{--depth <INT>} limit the depth of the account tree. In a balance
report, for example, a @code{--depth 2} statement will print balances
only for account with two levels, i.e. @code{Expenses:Entertainment} but
not @code{Expenses:entertainemnt:Dining}. This is a display predicate,
which means it only affects display, not the total calculations.
@option{--deviation} reports each posting’s deviation from the
average. It is only mean- ingful in the register and prices reports.
@option{--display-amount <EXPR>} apply a transform to the
@strong{displayed} amount. This occurs after calculations occur.
@option{--display <BOOLEAN_EXPR>}
display lines that satisfy the expression given.
@option{--display-total <EXPR>} apply a transform to the
@strong{displayed} total. This occurs after calculations occur.
@option{--dow}
group transactions by the day of the week.
@smallexample
ledger reg Expenses --dow --collapse
@end smallexample
@noindent will print all Expenses totalled for each day of the week.
@option{--effective}
use effective dates for all calculations (@pxref{Effective Dates}).
@option{--empty}
include empty accounts in the report.
@option{--end <DATE>}
specify the end date for transaction to be considered in the report.
@option{--equity} related to the @code{equity} command (@pxref{The
equity Command}). Gives current account balances in the form of a
register report.
@option{--exact}
ASK JOHN
@option{--exchange <COMMODITY>} display values in terms of the given
commodity. The latest available price is used.
@option{--flat} force the full names of accounts to be used inthe
balance report. The balance report will not use an indented tree.
@option{--force-color} output tty color codes even if the tty doesn't
support them. Ueful for TTY that don't advertise their capabilities
correctly.
@option{--force-pager}
force Ledger to paginate its output.
@option{forecast-while}
FIX THIS ENTRY
@option{forecast-years}
FIX THIS ENTRY
@option{--format <FORMAT STRING>}
use the given format string to print output.
@option{--gain}
report on gains using the latest available prices .
@option{generated}
ASK JOHN
@option{--group-by <EXPR>} group transaction together in the register
report. EXPR can be anything, although most common would be
@code{"payee"} or @code{"commodity"}. The @code{tags()} function is
also useful here.
@option{--group-title-format} sets the format for the headers that
separate reports section of a grouped report. Only has effect with a
@code{--group-by} register report.
@smallexample
ledger reg Expenses --group-by "payee" --group-title-format "------------------------ %-20(value) ---------------------\n"
------------------------ 7-Eleven ---------------------
2011/08/13 7-Eleven Expenses:Auto:Misc $ 5.80 $ 5.80
------------------------ AAA Dues ---------------------
2011/06/02 AAA Dues Expenses:Auto:Misc $ 215.00 $ 215.00
------------------------ ABC Towing and Wrecking ---------------------
2011/03/17 ABC Towing and Wrec.. Expenses:Auto:Hobbies $ 48.20 $ 48.20
...
@end smallexample
@option{--head <INT>}
Print the first INT entries. Opposite of @code{--tail}.
@option{--inject}
See email from John W.
@option{--invert}
Change the sign of all reported values.
@option{--limit <EXPR>} Only transactions that satisfy the expression
will be considered in the calculation.
@option{--lot-dates}
FIX THIS ENTRY
@option{--lot-prices}
FIX THIS ENTRY
@option{--lot-tags}
FIX THIS ENTRY
@option{--lots-actual}
FIX THIS ENTRY
@option{--lots}
FIX THIS ENTRY
@option{market}
FIX THIS ENTRY
@option{meta}
FIX THIS ENTRY
@option{meta-width}
FIX THIS ENTRY
@option{--monthly}
FIX THIS ENTRY
@option{--no-color}
suppress any color TTY output.
@option{--no-rounding}
FIX THIS ENTRY
@option{--no-titles}
FIX THIS ENTRY
@option{--no-total}
FIX THIS ENTRY
@option{--now}
FIX THIS ENTRY
@option{only}
FIX THIS ENTRY
@option{--output}
FIX THIS ENTRY
@option{--pager}
FIX THIS ENTRY
@option{payee}
FIX THIS ENTRY
@option{payee-width}
FIX THIS ENTRY
@option{--pending}
Use only postings tht are marked pending
@option{percent}
FIX THIS ENTRY
@option{period}
FIX THIS ENTRY
@option{--pivot}
FIX THIS ENTRY
@option{plot-amount-format}
FIX THIS ENTRY
@option{plot-total-format}
FIX THIS ENTRY
@option{prepend-format}
FIX THIS ENTRY
@option{prepend-width}
FIX THIS ENTRY
@option{pricedb-format}
FIX THIS ENTRY
@option{price}
FIX THIS ENTRY
@option{prices-format}
FIX THIS ENTRY
@option{quantity}
FIX THIS ENTRY
@option{--quarterly}
FIX THIS ENTRY
@option{raw}
FIX THIS ENTRY
@option{--real} Account using only real transactions ignoring virtual
and automatic transactions.
@option{register-format}
FIX THIS ENTRY
@option{related-all}
FIX THIS ENTRY
@option{--related}
In a register report show the related account.
@option{--revalued-only}
FIX THIS ENTRY
@option{--revalued-total}
FIX THIS ENTRY
@option{--revalued}
FIX THIS ENTRY
@option{seed}
FIX THIS ENTRY
@option{sort-all}
FIX THIS ENTRY
@option{--sort <VEXPR>}
Sort the register report based on the value expression given to sort
@option{--sort-xacts}
FIX THIS ENTRY
@option{--start-of-week <INT>} Tell ledger to use a particular day of
the week to start its ``weekly'' summary. @code{--start-of-week=1}
specifies Monday as the start of the week.
@option{--subtotal}
FIX THIS ENTRY
@option{--tail <INT>}
report only the last <INT> entries. Only useful ona register report.
@option{total-data}
FIX THIS ENTRY
@option{total}
FIX THIS ENTRY
@option{total-width}
FIX THIS ENTRY
@option{truncate}
FIX THIS ENTRY
@option{unbudgeted}
FIX THIS ENTRY
@option{uncleared}
FIX THIS ENTRY
@option{unrealized-gains}
FIX THIS ENTRY
@option{unrealized-losses}
FIX THIS ENTRY
@option{unrealized}
FIX THIS ENTRY
@option{unround}
FIX THIS ENTRY
@option{--weekly}
synonymn for @code{--period "weekly"}
@option{--wide} lets the register report use 132 columns. Identical to
@code{--columns "132"}
@option{yearly}
synonymn for @code{--period "yearly"}
@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
; ~/.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{--account NAME} (@option{-a NAME}) specifies the default
account which QIF file postings are assumed to relate to.
@node Report Filtering, Search Terms, Report Options, Detailed Options Description
@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 asterisk 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 asterisk 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 postings} for more
information).
@option{--actual} (@option{-L}) displays only actual postings, and
not those created due to automated postings.
@option{--related} (@option{-r}) displays postings that are
related to whichever postings would otherwise have matched the
filtering criteria. In the register report, this shows where money
went to, or the account it came from. In the balance report, it shows
all the accounts affected by transactions having a related posting.
For example, if a file had this transaction:
@smallexample
2004/03/20 Safeway
Expenses:Food $65.00
Expenses:Cash $20.00
Assets:Checking $-85.00
@end smallexample
And the register command was:
@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 un-budgeted
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.
@node Search Terms, Output Customization, Report Filtering, 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 ``food'' 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{--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{--pivot TAG} produces a pivot table around the tag provided.
This requires meta data using valued tags.
@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{--percent} (@option{-%}) shows account subtotals in the
@command{balance} report as percentages of the parent account.
@c @option{--totals} include running total information in the
@c @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 start up, to
determine historical prices. Other settings can be placed in this
file manually, to prevent downloading quotes for a specific commodity, 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
Note: Ledger NEVER write output to files. You are responsible for
updated the price-db file. The best way is to have your price download
script maintain this file.
@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
Use the last known value for commodities to calculate final values.
@item -G --gain
Reports the net gain/loss for all commodities in the report that have
a price history.
@end table
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} meta-data 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 @samp{-V} and @samp{-X} (in the
case of @samp{-X}, the requested commodity is passed via the string 'exchange'
above).
@cindex Euro conversion
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 @samp{--now} is some old date, use market prices as they
were at that time; but if @samp{--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 @samp{--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 @samp{-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 meta-data:
@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
@cindex FIFO/LIFO
@cindex LIFO/FIFO
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 @samp{--lots} are not being displayed, then it will
appear to balance against any lot of AAPL.
@cindex adorned commodity
If you specify an adorned commodity, like AAPL @{$10.00@}, it will also
balance against itself, and against any AAPL if @samp{--lots} is not
specified. But if you do specify @samp{--lot-prices}, for example, then
it will balance against that specific price for AAPL.
Normally when you use @samp{-X <commodity>} to request that amounts be reported in a
specific commodity, Ledger uses these values:
@itemize
@item Register Report
For the register report, use the value of that commodity on the date of
the posting being reported, with a <Revalued> posting added at the end of
today's value is different from the value of the last posting.
@item Balance Report
For the balance report, use the value of that commodity as of today.
@end itemize
You can now specify -H to ask that all valuations for any amount be done
relative to the date that amount was encountered.
You can also now use -X (and -H) in conjunction with -B and -I, to see
valuation reports of just your basis costs or lot prices.
@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
--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 Budgeting and Forecasting, Value Expressions, Command-line Syntax, 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 un-budgeted 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::
* Functions::
* Operators::
* Complex Expressions::
@end menu
@node Variables, Functions, 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
@node Functions, Operators, Variables, Value Expressions
@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
@node Operators, Complex Expressions, Functions, Value Expressions
@section Operators
The binary and ternary operators, in order of precedence, are:
@enumerate
@item @samp{* /}
@item @samp{+ -}
@item @samp{! < > =}
@item @samp{& | ?:}
@end enumerate
@menu
* Unary Operators::
* Binary Operators::
@end menu
@node Unary Operators, Binary Operators, Operators, Operators
@subsection Unary Operators
@code{not}
@code{neg}
@node Binary Operators, , Unary Operators, Operators
@subsection Binary Operators
@code{==}
@code{<}
@code{<=}
@code{>}
@code{>=}
@code{and}
@code{or}
@code{+}
@code{-}
@code{*}
@code{/}
@code{QUERY}
@code{COLON}
@code{CONS}
@code{SEQ}
@code{DEFINE}
@code{LOOKUP}
@code{LAMBDA}
@code{CALL}
@code{MATCH}
@node Complex Expressions, , Operators, Value Expressions
@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, Ledger for Developers, Value Expressions, Top
@chapter Format Strings
@menu
* Basics::
* Format Expressions::
* --balance-format::
* New formatting codes::
* Date and Time Format 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, Date and Time Format Codes, --balance-format, Format Strings
@section New Formatting Codes
@menu
* Field Widths::
* Colors::
* Quantities and Calculations::
* Dates::
* Text Formatting::
* Data File Parsing Information::
* 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 session.
@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 Calculations
@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, Data File Parsing Information, 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 internally 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 honor color settings.
@item join(str)
Replaces line feeds in str with @code{\n}.
@item quoted(str)
Return str surrounded 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 Data File Parsing Information, Misc, Text Formatting, New formatting codes
@subsection Data File Parsing Information
The format strings in the table below provide locational metadata
regarding the coordinates of entries in the source data file(s) that
generated the posting.
@subsubsection Summary
@multitable @columnfractions .3 .2 .5
@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description}
@item @code{filename} @tab S @tab name of ledger data file from whence posting came
@item @code{beg_pos} @tab B @tab character position in @code{filename} where entry for posting begins
@item @code{end_pos} @tab E @tab character position in @code{filename} where entry for posting ends
@item @code{beg_line} @tab b @tab line number in @code{filename} where entry for posting begins
@item @code{end_line} @tab e @tab line number in @code{filename} where posting's entry for posting ends
@end multitable
@node Misc, , Data File Parsing Information, 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{code} @tab @code{} @tab returns the transaction code, the string between the parenthesis after the date.
@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 Date and Time Format Codes, , New formatting codes, Format Strings
@section Date and Time Format Codes
Date and time format are specified as strings of single letter codes
preceded by percent signs. Any separator, or no separator can be
specified.
@subsection Dates
Dates are formed from a combination of day, month and year codes, in
whatever order you prefer:
@option{%Y} is keyword for four digit year
@option{%y} is keyword for two digit year
@option{%m} is keyword for two digit month
@option{%d} is keyword for two digit date
@noindent So @code{"%Y%m%d"} yields @code{20111214} which provides a date that is simple to sort.
@subsection Weekdays
You can have additional weekday information in your date with @code{%A}
as
@option{%m-%d-%Y %A} yields @code{02-10-2010 Wednesday}
@option{%A %m-%d-%Y} yields @code{Wednesday 02-10-2010}
@noindent These are options you can select for weekday
@option{%a} weekday, abbreviated Wed
@option{%A} weekday, full Wednesday
@option{%d} day of the month (dd), zero padded 10
@option{%e} day of the month (dd) 10
@option{%j} day of year, zero padded 000-366
@option{%u} day of week starting with Monday (1), i.e. @code{mtwtfss} 3
@option{%w} day of week starting with Sunday (0), i.e. @code{smtwtfs} 3
@subsection Month
You can have additional month information in your date with @code{%B} as
@option{%m-%d-%Y %B} yields @code{ 02-10-2010 Februrary}
@option{%B %m-%d-%Y} yields @code{February 02-10-2010}
@noindent These are options you can select for month
@option{%m} @code{mm} month as two digits
@option{%b} @code{Mon}, locale’s abbreviated Feb
@option{%B} locale’s full month, variable length February
@subsection Miscellaneous Date Codes
Additional date format parameters which can be used :
@option{%U} week number Sunday as first day of week 01–53
@option{%W} week number Monday as first day of week 01–53
@option{%V} week of the year 01–53
@option{%C} @code{cc} century 00–99
@option{%D} yields @code{mm/dd/yy 02/10/10}
@option{%x} locale’s date representation @code{02/10/2010} for the U.S.
@option{%F} yields @code{%Y-%m-%d 2010-02-10}
@node Ledger for Developers, Extending with Python, Format Strings, Top
@chapter Ledger for Developers
@menu
* Internal Design::
* Journal File Format::
@end menu
@node Internal Design, Journal File Format, Ledger for Developers, Ledger for Developers
@section Internal Design
Ledger is developed as a tiered set of functionality, where lower tiers
know nothing about the higher tiers. In fact, multiple libraries are
built during the development the process, and link unit tests to these
libraries, so that it is a link error for a lower tier to violate this
modularity.
Those tiers are:
@itemize
@item Utility code
There's lots of general utility in Ledger for doing time parsing, using
Boost.Regex, error handling, etc. It's all done in a way that can be
reused in other projects as needed.
@item Commoditized Amounts (amount_t, commodity_t and friends)
An numerical abstraction combining multi-precision rational numbers (via
GMP) with commodities. These structures can be manipulated like regular
numbers in either C++ or Python (as Amount objects).
@item Commodity Pool
Commodities are all owned by a commodity pool, so that future parsing of
amounts can link to the same commodity and established a consistent price
history and record of formatting details.
@item Balances
Adds the concept of multiple amounts with varying commodities. Supports
simple arithmetic, and multiplication and division with non-commoditized
values.
@item Price history
Amounts have prices, and these are kept in a data graph which the amount
code itself is only dimly aware of (there's three points of access so an
amount can query its revalued price on a given date).
@item Values
Often the higher layers in Ledger don't care if something is an amount or a
balance, they just want to add stuff to it or print it. For this, I
created a type-erasure class, value_t/Value, into which many things can be
stuffed and then operated on. They can contain amounts, balances, dates,
strings, etc. If you try to apply an operation between two values that
makes no sense (like dividing an amount by a balance), an error occurs at
runtime, rather than at compile-time (as would happen if you actually tried
to divide an amount_t by a balance_t).
This is the core data type for the value expression language.
@item Value expressions
The next layer up adds functions and operators around the Value concept.
This lets you apply transformations and tests to Values at runtime without
having to bake it into C++. The set of functions available is defined by
each object type in Ledger (posts, accounts, transactions, etc.), though
the core engine knows nothing about these. At its base, it only knows how
to apply operators to values, and how to pass them to and receive them from
functions.
@item Query expressions
Expressions can be onerous to type at the command-line, so there's a
shorthand for reporting called "query expressions". These add no
functionality of there own, but are purely translated from the input string
(cash) down to the corresponding value expression (account =~ /cash/).
This is a convenience layer.
@item Format strings
Format strings let you interpolate value expressions into string, with the
requirement that any interpolated value have a string representation.
Really all this does is calculate the value expression in the current
report context, call the resulting value's "to_string()" method, and stuffs
the result into the output string. It also provides printf-like behavior,
such as min/max width, right/left justification, etc.
@item Journal items
Next is a base type shared by anything that can appear in a journal: an
item_t. It contains details common to all such parsed entities, like what
file and line it was found on, etc.
@item Journal posts
The most numerous object found in a Journal, postings are a type of item
that contain an account, an amount, a cost, and metadata. There are some
other complications, like the account can be marked virtual, the amount
could be an expression, etc.
@item Journal transactions
Postings are owned by transactions, always. This subclass of item_t knows
about the date, the payee, etc. If a date or metadata tag is requested
from a posting and it doesn't have that information, the transaction is
queried to see if it can provide it.
@item Journal accounts
Postings are also shared by accounts, though the actual memory is managed
by the transaction. Each account knows all the postings within it, but
contains relatively little information of its own.
@item The Journal object
Finally, all transactions with their postings, and all accounts, are owned
by a journal_t object. This is the go-to object for querying ad reporting
on your data.
@item Textual journal parser
There is a textual parser, wholly contained in textual.cc, which knows how
to parse text into journal objects, which then get "finalized" and added to
the journal. Finalization is the step that enforces the double-entry
guarantee.
@item Iterators
Every journal object is "iterable", and these iterators are defined in
iterators.h and iterators.cc. This iteration logic is kept out of the
basic journal objects themselves for the sake of modularity.
@item Comparators
Another abstraction isolated to its own layer, this class encapsulating the
comparison of journal objects, based on whatever value expression the user
passed to --sort.
@item Temporaries
Many reports bring pseudo-journal objects into existence, like postings
which report totals in a "<Total>" account. These objects are created and
managed by a temporaries_t object, which gets used in many places by the
reporting filters.
@item Option handling
There is an option handling subsystem used by many of the layers further
down. It makes it relatively easy for me to add new options, and to have
those option settings immediately accessible to value expressions.
@item Session objects
Every journal object is owned by a session, with the session providing
support for that object. In GUI terms, this is the Controller object for
the journal Data object, where every document window would be a separate
session. They are all owned by the global scope.
@item Report objects
Every time you create report output, a report object is created to
determine what you want to see. In the Ledger REPL, a new report object is
created every time a command is executed. In CLI mode, only one report
object ever comes into being, as Ledger immediately exits after displaying
the results.
@item Reporting filters
The way Ledger generates data is this: it asks the session for the current
journal, and then creates an iterator applied to that journal. The kind of
iterator depends on the type of report.
This iterator is then walked, and every object yielded from the iterator is
passed to an "item handler", whose type is directly related to the type of
the iterator.
There are many, many item handlers, which can be chained together. Each
one receives an item (post, account, xact, etc.), performs some action on
it, and then passes it down to the next handler in the chain. There are
filters which compute the running totals; that queue and sort all the input
items before playing them back out in a new order; that filter out items
which fail to match a predicate, etc. Almost every reporting feature in
Ledger is related to one or more filters. Looking at filters.h, I see over
25 of them defined currently.
@item The filter chain
How filters get wired up, and in what order, is a complex process based on
all the various options specified by the user. This is the job of the
chain logic, found entirely in chain.cc. It took a really long time to get
this logic exactly write, which is why I haven't exposed this layer to the
Python bridge yet.
@item Output modules
Although filters are great and all, in the end you want to see stuff. This
is the job of special "leaf" filters call output modules. They are
implemented just like a regular filter, but they don't have a "next" filter
to pass the time on down to. Instead, they are the end of the line and
must do something with the item that results in the user seeing something
on their screen or in a file.
@item Select queries
Select queries know a lot about everything, even though they implement
their logic by implementing the user's query in terms of all the other
features thus presented. Select queries have no functionality of their
own, they are simple a shorthand to provide access to much of Ledger's
functionality via a cleaner, more consistent syntax.
@item The Global Scope
There is a master object which owns every other objects, and this is
Ledger's global scope. It creates the other objects, provides REPL
behavior for the command-line utility, etc. In GUI terms, this is the
Application object.
@item The Main Driver
This creates the global scope object, performs error reporting, and handles
command-line options which must precede even the creation of the global
scope, such as --debug.
@end itemize
And that's Ledger in a nutshell. All the rest are details, such as which
value expressions each journal item exposes, how many filters currently exist,
which options the report and session scopes define, etc.
@node Journal File Format, , Internal Design, Ledger for Developers
@section Journal File Format for Developers
This chapter offers a complete description of the journal data format,
suitable for implementers 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
@menu
* Comments and meta-data::
* Specifying Amounts::
* Posting costs::
* Primary commodities::
@end menu
@node Comments and meta-data, Specifying Amounts, Journal File Format, Journal File Format
@subsection Comments and meta-data
Comments are generally started using a ';'. However, in order to
increase compatibility with other text manipulation programs and methods
three additional comment characters are valid if used at the beginning
of a line: @code{#}, @code{|}, and @code{*}.
@node Specifying Amounts, Posting costs, Comments and meta-data, Journal File Format
@subsection Specifying Amounts
@cindex 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.
@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 a commodity designator).
@menu
* Integer Amounts::
* Commoditized Amounts::
@end menu
@node Integer Amounts, Commoditized Amounts, Specifying Amounts, Specifying Amounts
@subsubsection 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
@cindex uncommoditized amounts
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 significant 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}.
@node Commoditized Amounts, , Integer Amounts, Specifying Amounts
@subsubsection 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 white-space
@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.
@node Posting costs, Primary commodities, Specifying Amounts, Journal File Format
@subsection 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.
@node Primary commodities, , Posting costs, Journal File Format
@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, Major Changes from version 2.6, Ledger for Developers, Top
@chapter Extending with Python
Python can be used to extend your Ledger
experience. But first, a word must be said about Ledger's data model, so that
other things make sense later.
@menu
* Basic data traversal::
* Raw vs. Cooked::
* Queries::
* Embedded Python::
* Amounts::
@end menu
@node Basic data traversal, Raw vs. Cooked, Extending with Python, Extending with Python
@section Basic data traversal
Every interaction with Ledger happens in the context of a Session. Even if
you don't create a session manually, one is created for you by the top-level
interface functions. The Session is where objects live like the Commodity's
that Amount's refer to.
The make a Session useful, you must read a Journal into it, using the function
`@samp{read_journal}`. This reads Ledger data from the given file, populates a
Journal object within the current Session, and returns a reference to that
Journal object.
Within the Journal live all the Transaction's, Posting's, and other objects
related to your data. There are also AutomatedTransaction's and
PeriodicTransaction's, etc.
Here is how you would traverse all the postings in your data file:
@smallexample
import ledger
for xact in ledger.read_journal("sample.dat").xacts:
for post in xact.posts:
print "Transferring %s to/from %s" % (post.amount, post.account)
@end smallexample
@node Raw vs. Cooked, Queries, Basic data traversal, Extending with Python
@section Raw vs. Cooked
Ledger data exists in one of two forms: raw and cooked. Raw objects are what
you get from a traversal like the above, and represent exactly what was seen
in the data file. Consider this journal:
@smallexample
= true
(Assets:Cash) $100
2012-03-01 KFC
Expenses:Food $100
Assets:Credit
@end smallexample
In this case, the @emph{raw} regular transaction in this file is:
@smallexample
2012-03-01 KFC
Expenses:Food $100
Assets:Credit
@end smallexample
While the @emph{cooked} form is:
@smallexample
2012-03-01 KFC
Expenses:Food $100
Assets:Credit $-100
(Assets:Cash) $100
@end smallexample
So the easy way to think about raw vs. cooked is that raw is the unprocessed
data, and cooked has had all considerations applied.
When you traverse a Journal by iterating its transactions, you are generally
looking at raw data. In order to look at cooked data, you must generate a
report of some kind by querying the journal:
@smallexample
for post in ledger.read_journal("sample.dat").query("food"):
print "Transferring %s to/from %s" % (post.amount, post.account)
@end smallexample
The reason why queries iterate over postings instead of transactions is that
queries often return only a ``slice'' of the transactions they apply to. You
can always get at a matching posting's transaction by looking at its "xact"
member:
@smallexample
last_xact = None
for post in ledger.read_journal("sample.dat").query(""):
if post.xact != last_xact:
for post in post.xact.posts:
print "Transferring %s to/from %s" % (post.amount,
post.account)
last_xact = post.xact
@end smallexample
This query ends up reporting every cooked posting in the Journal, but does it
transaction-wise. It relies on the fact that an unsorted report returns
postings in the exact order they were parsed from the journal file.
@node Queries, Embedded Python, Raw vs. Cooked, Extending with Python
@section Queries
The Journal.query() method accepts every argument you can specify on the
command-line, including --options.
Since a query ``cooks'' the journal it applies to, only one query may be active
for that journal at a given time. Once the query object is gone (after the
for loop), then the data reverts back to its raw state.
@node Embedded Python, Amounts, Queries, Extending with Python
@section Embedded Python
Can you embed Python into your data files using the 'python' directive:
@smallexample
python
import so
def check_path(path_value):
print "%s => %s" % (str(path_value), os.path.isfile(str(path_value)))
return os.path.isfile(str(path_value))
tag PATH
assert check_path(value)
2012-02-29 KFC
; PATH: somebogusfile.dat
Expenses:Food $20
Assets:Cash
@end smallexample
Any Python functions you define this way become immediately available as
valexpr functions.
@node Amounts, , Embedded Python, Extending with Python
@section Amounts
When numbers come from Ledger, like post.amount, the type of the value is
Amount. It can be used just like an ordinary number, except that addition
and subtraction are restricted to amounts with the same commodity. If you
need to create sums of multiple commodities, use a Balance. For example:
@smallexample
total = Balance()
for post in ledger.read_journal("sample.dat").query(""):
total += post.amount
print total
@end smallexample
@node Major Changes from version 2.6, Example Data File, Extending with Python, Top
@chapter Major Changes from version 2.6
@node Example Data File, Miscellaneous Notes, Major Changes from version 2.6, 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, Concept Index, 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
@node Concept Index, Command Index, Miscellaneous Notes, Top
@unnumbered Concept Index
@printindex cp
@node Command Index, , Concept Index, Top
@unnumbered Command Index
@printindex fn
@bye
Reference in a new issue View git blame Copy permalink