6133 lines
212 KiB
Text
6133 lines
212 KiB
Text
\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
|
||
@subtitle Draft Manual Time-stamp: <2011-12-01 08:37 (cpearls)>
|
||
@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::
|
||
* Building Reports::
|
||
* Reporting Commands::
|
||
* Command-line Syntax::
|
||
* Budgeting and Forecasting::
|
||
* Value Expressions::
|
||
* Format Strings::
|
||
* Journal File Format::
|
||
* 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 commandline 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. If you use
|
||
another GUI accounting program like GNUCash, the vast majority of its
|
||
functionality is geared towards helping you keep a journal.
|
||
|
||
A checkbook journal records debits (subtractions, or withdrawals) and
|
||
credits (additions, or deposits) with reference to a single account:
|
||
the checking account. Where the money comes from, and where it goes
|
||
to, are described in the payee field, where you write the person or
|
||
company's name. The ultimate aim of keeping a checkbook journal is to
|
||
know how much money is available to spend. That's really the aim of
|
||
all journals.
|
||
|
||
@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, transfering money to your checking account. There is
|
||
nothing left over to be accounted for, since the money has simply moved
|
||
from one account to another in both cases. This is the basis of
|
||
double-entry accounting: money never pops in or out of existence; it is
|
||
always a posting from one account to another.
|
||
|
||
Keeping a general journal is the same as keeping two separate journals:
|
||
One for Pacific Bell and one for Checking. In that case, each time a
|
||
payment is written into one, you write a corresponding withdrawal into
|
||
the other. This makes it easier to write in a ``running balance'',
|
||
since you don't have to look back at the last time the account was
|
||
referenced---but it also means having a lot of journal books, if you
|
||
deal with multiple accounts.
|
||
|
||
@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 multiprecision integer library (libgmp), and the
|
||
Perl regular expression library (libpcre). It was developed using GNU
|
||
make and gcc 3.3, on a PowerBook running OS/X.
|
||
|
||
To build and install once you have these libraries on your system,
|
||
enter these commands:
|
||
|
||
@smallexample
|
||
./configure && make install
|
||
@end smallexample
|
||
|
||
@node Getting Help, , Building the Program, Introduction to Ledger
|
||
@section Getting help
|
||
Ledger has a complete online help system based on GNU Info. This manual
|
||
can be searched directly fromthe command line using the following
|
||
options:
|
||
@option{ledger --help} bring up this entire manual in your tty.
|
||
|
||
@option{ledger --help-info} brings up help on how to use the info system.
|
||
|
||
@option{ledger --help-comm concept} search the manual index and bring up pages associated with `concept'.
|
||
|
||
@option{ledger --help-calc} brings up the value expressions chapter of the manual
|
||
|
||
@option{ledger --help-disp} brings up the Format Strings chapter of the manual.
|
||
|
||
If you need help on how to use Ledger, or run into problems,
|
||
you can join the Ledger mailing list at the following Web address:
|
||
|
||
@smallexample
|
||
http://groups.google.com/group/ledger-cli
|
||
@end smallexample
|
||
|
||
You can also find help at the @samp{#ledger} channel on the IRC server
|
||
@samp{irc.freenode.net}.
|
||
|
||
@node Ledger Tutorial , Principles of Accounting, Introduction to Ledger, Top
|
||
@chapter Ledger Tutorial
|
||
|
||
@menu
|
||
* Start a Journal::
|
||
* Run Some Reports::
|
||
* Command Line Quick Reference::
|
||
@end menu
|
||
|
||
@node Start a Journal, Run Some Reports, Ledger Tutorial , Ledger Tutorial
|
||
@section Start a Journal File
|
||
@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
|
||
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
|
||
To show all transactions and a running total:
|
||
@smallexample
|
||
ledger -f drewr3.dat register
|
||
@end smallexample
|
||
|
||
Ledger will generate:
|
||
|
||
@smallexample
|
||
10-Dec-01 Checking balance Assets:Checking $ 1,000.00 $ 1,000.00
|
||
Equity:Opening Balances $ -1,000.00 0
|
||
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50
|
||
Expense:Food:Groceries $ 37.50 $ 75.00
|
||
Expense:Food:Groceries $ 37.50 $ 112.50
|
||
Expense:Food:Groceries $ 37.50 $ 150.00
|
||
Expense:Food:Groceries $ 37.50 $ 187.50
|
||
Expense:Food:Groceries $ 37.50 $ 225.00
|
||
Assets:Checking $ -225.00 0
|
||
10-Dec-28 Acme Mortgage Lia:Mortgage:Principal $ 200.00 $ 200.00
|
||
Expe:Interest:Mortgage $ 500.00 $ 700.00
|
||
Expenses:Escrow $ 300.00 $ 1,000.00
|
||
Assets:Checking $ -1,000.00 0
|
||
11-Jan-02 Grocery Store Expense:Food:Groceries $ 65.00 $ 65.00
|
||
Assets:Checking $ -65.00 0
|
||
11-Jan-05 Employer Assets:Checking $ 2,000.00 $ 2,000.00
|
||
Income:Salary $ -2,000.00 0
|
||
(Liabilities:Tithe) $ -240.00 $ -240.00
|
||
11-Jan-14 Bank Assets:Savings $ 300.00 $ 60.00
|
||
Assets:Checking $ -300.00 $ -240.00
|
||
11-Jan-19 Grocery Store Expense:Food:Groceries $ 44.00 $ -196.00
|
||
Assets:Checking $ -44.00 $ -240.00
|
||
11-Jan-25 Bank Assets:Checking $ 5,500.00 $ 5,260.00
|
||
Assets:Savings $ -5,500.00 $ -240.00
|
||
11-Jan-25 Tom's Used Cars Expenses:Auto $ 5,500.00 $ 5,260.00
|
||
Assets:Checking $ -5,500.00 $ -240.00
|
||
11-Jan-27 Book Store Expenses:Books $ 20.00 $ -220.00
|
||
Liabilities:MasterCard $ -20.00 $ -240.00
|
||
11-Dec-01 Sale Asse:Checking:Business $ 30.00 $ -210.00
|
||
Income:Sales $ -30.00 $ -240.00
|
||
(Liabilities:Tithe) $ -3.60 $ -243.60
|
||
@end smallexample
|
||
|
||
@noindent To limit this to a more useful subset, simply add the accounts you are are interested in seeing transactions for:
|
||
|
||
@smallexample
|
||
$ ledger -f drewr3.dat register Groceries
|
||
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50
|
||
Expense:Food:Groceries $ 37.50 $ 75.00
|
||
Expense:Food:Groceries $ 37.50 $ 112.50
|
||
Expense:Food:Groceries $ 37.50 $ 150.00
|
||
Expense:Food:Groceries $ 37.50 $ 187.50
|
||
Expense:Food:Groceries $ 37.50 $ 225.00
|
||
11-Jan-02 Grocery Store Expense:Food:Groceries $ 65.00 $ 290.00
|
||
11-Jan-19 Grocery Store Expense:Food:Groceries $ 44.00 $ 334.00
|
||
@end smallexample
|
||
|
||
@noindent Which matches the balance reported for the @samp{Groceries} account:
|
||
|
||
@smallexample
|
||
$ ledger -f drewr3.dat balance Groceries
|
||
$ 334.00 Expenses:Food:Groceries
|
||
@end smallexample
|
||
|
||
@noindent If you would like to find transaction to only a certain payee use @samp{payee} or @@:
|
||
@smallexample
|
||
$ ledger -f drewr3.dat register payee "Organic"
|
||
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50
|
||
Expense:Food:Groceries $ 37.50 $ 75.00
|
||
Expense:Food:Groceries $ 37.50 $ 112.50
|
||
Expense:Food:Groceries $ 37.50 $ 150.00
|
||
Expense:Food:Groceries $ 37.50 $ 187.50
|
||
Expense:Food:Groceries $ 37.50 $ 225.00
|
||
Assets:Checking $ -225.00 0
|
||
@end smallexample
|
||
|
||
@node Cleared Report, Using the Windows command line, Register Report, Run Some Reports
|
||
@subsection Cleared Report
|
||
|
||
A very useful report is to show what your obligations are versus what
|
||
expenditures have actually been recorded. It can take several days for
|
||
a check to clear, but you should treat it as money spent. The
|
||
@samp{cleared} report shows just that:
|
||
|
||
@smallexample
|
||
$ ledger -f drewr3.dat cleared
|
||
$ -3,804.00 $ 775.00 Assets
|
||
$ 1,396.00 $ 775.00 10-Dec-20 Checking
|
||
$ 30.00 0 Business
|
||
$ -5,200.00 0 Savings
|
||
$ -1,000.00 $ -1,000.00 10-Dec-01 Equity:Opening Balances
|
||
$ 6,654.00 $ 225.00 Expenses
|
||
$ 5,500.00 0 Auto
|
||
$ 20.00 0 Books
|
||
$ 300.00 0 Escrow
|
||
$ 334.00 $ 225.00 10-Dec-20 Food:Groceries
|
||
$ 500.00 0 Interest:Mortgage
|
||
$ -2,030.00 0 Income
|
||
$ -2,000.00 0 Salary
|
||
$ -30.00 0 Sales
|
||
$ -63.60 0 Liabilities
|
||
$ -20.00 0 MasterCard
|
||
$ 200.00 0 Mortgage:Principal
|
||
$ -243.60 0 Tithe
|
||
---------------- ---------------- ---------
|
||
$ -243.60 0
|
||
@end smallexample
|
||
|
||
@noindent The first column shows the outstanding balance, the second column show the ``cleared'' balance.
|
||
@node Using the Windows command line, , Cleared Report, Run Some Reports
|
||
@subsection Using the Windows Command Line
|
||
|
||
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::
|
||
* Output Customization Quick Reference::
|
||
* Grouping Options::
|
||
* Commodity Reporting Quick Reference::
|
||
@end menu
|
||
|
||
@node Reporting Commands Quick Reference, Basic Options Quick Reference, Command Line Quick Reference, Command Line Quick Reference
|
||
@subsection Reporting Commands
|
||
@multitable @columnfractions .2 .8
|
||
@item @strong{Report} @tab @strong{Description}
|
||
@item @code{balance} @tab Show account balances
|
||
@item @code{register} @tab Show all transactions with running total
|
||
@item @code{print} @tab Print transaction in a ledger readable format
|
||
@item @code{output} @tab Similar to print without included transactions
|
||
@item @code{xml} @tab Produce XML output of the register command
|
||
@item @code{emacs} @tab Produce emacs lisp output
|
||
@item @code{equity} @tab Print account balances as transactions
|
||
@item @code{prices} @tab Print price history for matching commodities
|
||
@item @code{pricedb} @tab Print price history for matching commodities in ledger readable format
|
||
@item @code{xact} @tab Used to generate transactions based on previous postings
|
||
@end multitable
|
||
|
||
@node Basic Options Quick Reference, Report Filtering Quick Reference, Reporting Commands Quick Reference, Command Line Quick Reference
|
||
@subsection Basic Options
|
||
@multitable @columnfractions .1 .25 .65
|
||
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
|
||
@item @code{-h} @tab @code{--help} @tab prints summary of all options
|
||
@item @code{-v} @tab @code{--version} @tab prints version of ledger executable
|
||
@item @code{-f FILE} @tab @code{--file FILE} @tab read @file{FILE} as a ledger file
|
||
@item @code{-o FILE} @tab @code{--output FILE} @tab redirects output to @file{FILE}
|
||
@item @code{-i FILE} @tab @code{--init-file FILE} @tab specify options file
|
||
@item @code{-a NAME} @tab @code{--account NAME} @tab specify default account name for QIF file postings
|
||
@end multitable
|
||
|
||
@node Report Filtering Quick Reference, Output Customization Quick Reference, Basic Options Quick Reference, Command Line Quick Reference
|
||
@subsection Report Filtering
|
||
@multitable @columnfractions .1 .25 .65
|
||
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
|
||
@item @code{-c} @tab @code{--current} @tab Display transaction on or before the current date
|
||
@item @code{-b DATE} @tab @code{--begin DATE} @tab Begin reports on or after @code{DATE}
|
||
@item @code{-e DATE} @tab @code{--end DATE} @tab Limits end date od transactions for report
|
||
@item @code{-p STR} @tab @code{--period} @tab Set report period to STR
|
||
@item @code{ } @tab @code{--period-sort} @tab Sort postings within each period
|
||
@item @code{-C} @tab @code{--cleared} @tab Display only cleared postings
|
||
@item @code{-U} @tab @code{--uncleared} @tab Display only uncleared postings
|
||
@item @code{-R} @tab @code{--real} @tab Display only real postings
|
||
@item @code{-L} @tab @code{--actual} @tab Displays only actual postings, not automated
|
||
@item @code{-r} @tab @code{--related} @tab Display related postings
|
||
@item @code{} @tab @code{--budget} @tab Display how close your postings meet your budget
|
||
@item @code{} @tab @code{--add-budget} @tab Shows unbudgeted postings
|
||
@item @code{} @tab @code{--unbudgeted} @tab Shows only unbudgeted postings
|
||
@item @code{} @tab @code{--forecast} @tab Project balances into the future
|
||
@item @code{-l EXPR} @tab @code{--limit EXPR} @tab Limits postings in calculations
|
||
@item @code{-t EXPR} @tab @code{--amount} @tab Change value expression reported in register report
|
||
@item @code{-T EXPR} @tab @code{--total} @tab Change the value expression used for ``totals'' column in register and balance reports
|
||
@end multitable
|
||
|
||
@node Output Customization Quick Reference, Grouping Options, Report Filtering Quick Reference, Command Line Quick Reference
|
||
@subsection Output Customization
|
||
@multitable @columnfractions .15 .4 .45
|
||
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
|
||
@item @code{-n} @tab @code{--collapse} @tab Collapse transactions with multiple postings
|
||
@item @code{-s} @tab @code{--subtotal} @tab Report register as a single subtotal
|
||
@item @code{-P} @tab @code{--by-payee} @tab Report subtotals by payee
|
||
@item @code{-x} @tab @code{--comm-as-payee} @tab Change the payee of every posting to be the commodity used in that posting
|
||
@item @code{-E} @tab @code{--empty} @tab Include empty accounts in report
|
||
@item @code{-W} @tab @code{--weekly} @tab Report posting totals by week
|
||
@item @code{-Y} @tab @code{--yearly} @tab Report posting totals by year
|
||
@item @code{} @tab @code{--dow} @tab report Posting totals by day of week
|
||
@item @code{-S EXPR} @tab @code{--sort EXPR} @tab Sorts a report using @code{EXPR}
|
||
@item @code{-w} @tab @code{--wide} @tab Assume 132 columns instead of 80
|
||
@item @code{} @tab @code{--head N} @tab Report the first N postings
|
||
@item @code{} @tab @code{--tail N} @tab Report the last N postings
|
||
@item @code{} @tab @code{--pager prog} @tab Direct output @code{prog} pager program
|
||
@item @code{-A} @tab @code{--average} @tab Reports average posting value
|
||
@item @code{-D} @tab @code{--deviation} @tab Reports each posting deviation from the average
|
||
@item @code{-%} @tab @code{--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, usefule for filing bug reports
|
||
@end multitable
|
||
|
||
@node Grouping Options, Commodity Reporting Quick Reference, Output Customization Quick Reference, Command Line Quick Reference
|
||
@subsection Grouping Options
|
||
@multitable @columnfractions .1 .25 .65
|
||
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
|
||
@item @code{-P} @tab @code{--by-payee} @tab Group postings by common payee names
|
||
@item @code{-D} @tab @code{--daily} @tab Group postings by day
|
||
@item @code{-W} @tab @code{--weekly} @tab Group postings by week
|
||
@item @code{-M} @tab @code{--Monthly} @tab Group postings by month
|
||
@item @code{} @tab @code{--quarterly} @tab Group postings by quarter
|
||
@item @code{-Y} @tab @code{--yearly} @tab Group postings by year
|
||
@item @code{-dow} @tab @code{} @tab Group by day of weeks
|
||
@item @code{-s} @tab @code{--subtotal} @tab Group posting together, similar to balance report
|
||
@end multitable
|
||
|
||
@node Commodity Reporting Quick Reference, , Grouping Options, Command Line Quick Reference
|
||
@subsection Commodity Reporting
|
||
|
||
@multitable @columnfractions .1 .25 .65
|
||
@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
|
||
@item @code{} @tab @code{--price-db FILE} @tab Use @file{FILE} for retrieving downloaded commodity prices
|
||
@item @code{-L MINS} @tab @code{--price-exp MINS} @tab Set expected freshness of prices in minutes
|
||
@item @code{-Q} @tab @code{--download} @tab Download quotes using @code{getquote}
|
||
@item @code{-O} @tab @code{--quantity} @tab Report commodity totals without conversion
|
||
@item @code{-B} @tab @code{--basis} @tab Report cost basis
|
||
@item @code{-V} @tab @code{--market} @tab Report last known market value
|
||
@item @code{-G} @tab @code{--gain} @tab Report net gain loss for commodities that have a price history
|
||
@end multitable
|
||
|
||
@node Principles of Accounting, Keeping a Journal, Ledger Tutorial , Top
|
||
@chapter Principles of Accounting with Ledger
|
||
|
||
|
||
@menu
|
||
* Accounting with Ledger::
|
||
* Stating where money goes::
|
||
* Assets and Liabilities::
|
||
* Typical queries::
|
||
* Commodities and Currencies::
|
||
* Accounts and Inventories::
|
||
* Understanding Equity::
|
||
* Dealing with Petty Cash::
|
||
* Working with multiple funds and accounts::
|
||
@end menu
|
||
|
||
|
||
@node Accounting with Ledger, Stating where money goes, Principles of Accounting, Principles of Accounting
|
||
@section Accounting with Ledger
|
||
|
||
Accounting is simply tracking your money. It can range from nothing,
|
||
and just waiting for automatic overdraft protection to kick in, or not,
|
||
to a full blown double entry accounting system. Ledger accomplishes the
|
||
latter. With ledger you can handle your personal finances or you
|
||
businesses. Double-entry accounting scales.
|
||
@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, Typical queries, Stating where money goes, Principles of Accounting
|
||
@section Assets and Liabilities
|
||
|
||
Assets are money that you have, and Liabilities are money that you
|
||
owe. ``Liabilities'' is just a more inclusive name for Debts.
|
||
|
||
An Asset is typically increased by transferring money from an Income
|
||
account, such as when you get paid. Here is a typical transaction:
|
||
|
||
@smallexample
|
||
2004/09/29 My Employer
|
||
Assets:Checking $500.00
|
||
Income:Salary
|
||
@end smallexample
|
||
|
||
Money, here, comes from an Income account belonging to ``My
|
||
Employer'', and is transferred to your checking account. The money is
|
||
now yours, which makes it an Asset.
|
||
|
||
Liabilities track money owed to others. This can happen when you
|
||
borrow money to buy something, or if you owe someone money. Here is
|
||
an example of increasing a MasterCard liability by spending money with
|
||
it:
|
||
|
||
@smallexample
|
||
2004/09/30 Restaurant
|
||
Expenses:Dining $25.00
|
||
Liabilities:MasterCard
|
||
@end smallexample
|
||
|
||
The Dining account balance now shows $25 spent on Dining, and a
|
||
corresponding $25 owed on the MasterCard---and therefore shown as
|
||
$-25.00. The MasterCard liability shows up as negative because it
|
||
offsets the value of your assets.
|
||
|
||
The combined total of your Assets and Liabilities is your net worth.
|
||
So to see your current net worth, use this command:
|
||
|
||
@example
|
||
ledger balance ^assets ^liabilities
|
||
@end example
|
||
|
||
Relatedly, your Income accounts show up negative, because they
|
||
transfer money @emph{from} an account in order to increase your
|
||
assets. Your Expenses show up positive because that is where the
|
||
money went to. The combined total of Income and Expenses is your cash
|
||
flow. A positive cash flow means you are spending more than you make,
|
||
since income is always a negative figure. To see your current cash
|
||
flow, use this command:
|
||
|
||
@example
|
||
ledger balance ^income ^expenses
|
||
@end example
|
||
|
||
Another common question to ask of your expenses is: How much do I
|
||
spend each month on X? Ledger provides a simple way of displaying
|
||
monthly totals for any account. Here is an example that summarizes
|
||
your monthly automobile expenses:
|
||
|
||
@example
|
||
ledger -M register expenses:auto
|
||
@end example
|
||
|
||
This assumes, of course, that you use account names like
|
||
@samp{Expenses:Auto:Gas} and @samp{Expenses:Auto:Repair}.
|
||
|
||
@menu
|
||
* Tracking reimbursable expenses::
|
||
@end menu
|
||
|
||
@node Tracking reimbursable expenses, , Assets and Liabilities, Assets and Liabilities
|
||
@subsection Tracking reimbursable expenses
|
||
|
||
Sometimes you will want to spend money on behalf of someone else,
|
||
which will eventually get repaid. Since the money is still ``yours'',
|
||
it is really an asset. And since the expenditure was for someone
|
||
else, you don't want it contaminating your Expenses reports. You will
|
||
need to keep an account for tracking reimbursements.
|
||
|
||
This is fairly easy to do in ledger. When spending the money, spend
|
||
it @emph{to} your Assets:Reimbursements, using a different account for
|
||
each person or business that you spend money for. For example:
|
||
|
||
@smallexample
|
||
2004/09/29 Circuit City
|
||
Assets:Reimbursements:Company XYZ $100.00
|
||
Liabilities:MasterCard
|
||
@end smallexample
|
||
|
||
This shows $100.00 spent on a MasterCard at Circuit City, with the
|
||
expense was made on behalf of Company XYZ. Later, when Company XYZ
|
||
pays the amount back, the money will transfer from that reimbursement
|
||
account back to a regular asset account:
|
||
|
||
@smallexample
|
||
2004/09/29 Company XYZ
|
||
Assets:Checking $100.00
|
||
Assets:Reimbursements:Company XYZ
|
||
@end smallexample
|
||
|
||
This deposits the money owed from Company XYZ into a checking account,
|
||
presumably because they paid the amount back with a check.
|
||
|
||
But what to do if you run your own business, and you want to keep
|
||
track of expenses made on your own behalf, while still tracking
|
||
everything in a single ledger file? This is more complex, because you
|
||
need to track two separate things: 1) The fact that the money should
|
||
be reimbursed to you, and 2) What the expense account was, so that you
|
||
can later determine where your company is spending its money.
|
||
|
||
This kind of posting is best handled with mirrored postings in
|
||
two different files, one for your personal accounts, and one for your
|
||
company accounts. But keeping them in one file involves the same
|
||
kinds of postings, so those are what is shown here. First, the
|
||
personal transaction, which shows the need for reimbursement:
|
||
|
||
@smallexample
|
||
2004/09/29 Circuit City
|
||
Assets:Reimbursements:Company XYZ $100.00
|
||
Liabilities:MasterCard
|
||
@end smallexample
|
||
|
||
This is the same as above, except that you own Company XYZ, and are
|
||
keeping track of its expenses in the same ledger file. This transaction
|
||
should be immediately followed by an equivalent transaction, which shows the
|
||
kind of expense, and also notes the fact that $100.00 is now payable
|
||
to you:
|
||
|
||
@smallexample
|
||
2004/09/29 Circuit City
|
||
Company XYZ:Expenses:Computer:Software $100.00
|
||
Company XYZ:Accounts Payable:Your Name
|
||
@end smallexample
|
||
|
||
This second transaction shows that Company XYZ has just spent $100.00 on
|
||
software, and that this $100.00 came from Your Name, which must be
|
||
paid back.
|
||
|
||
These two transactions can also be merged, to make things a little clearer.
|
||
Note that all amounts must be specified now:
|
||
|
||
@smallexample
|
||
2004/09/29 Circuit City
|
||
Assets:Reimbursements:Company XYZ $100.00
|
||
Liabilities:MasterCard $-100.00
|
||
Company XYZ:Expenses:Computer:Software $100.00
|
||
Company XYZ:Accounts Payable:Your Name $-100.00
|
||
@end smallexample
|
||
|
||
To ``pay back'' the reimbursement, just reverse the order of
|
||
everything, except this time drawing the money from a company asset,
|
||
paying it to accounts payable, and then drawing it again from the
|
||
reimbursement account, and paying it to your personal asset account.
|
||
It's easier shown than said:
|
||
|
||
@smallexample
|
||
2004/10/15 Company XYZ
|
||
Assets:Checking $100.00
|
||
Assets:Reimbursements:Company XYZ $-100.00
|
||
Company XYZ:Accounts Payable:Your Name $100.00
|
||
Company XYZ:Assets:Checking $-100.00
|
||
@end smallexample
|
||
|
||
And now the reimbursements account is paid off, accounts payable is
|
||
paid off, and $100.00 has been effectively transferred from the
|
||
company's checking account to your personal checking account. The
|
||
money simply ``waited''---in both @samp{Assets:Reimbursements:Company
|
||
XYZ}, and @samp{Company XYZ:Accounts Payable:Your Name}---until such
|
||
time as it could be paid off.
|
||
|
||
The value of tracking expenses from both sides like that is that you
|
||
do not contaminate your personal expense report with expenses made on
|
||
behalf of others, while at the same time making it possible to
|
||
generate accurate reports of your company's expenditures. It is more
|
||
verbose than just paying for things with your personal assets, but it
|
||
gives you a very accurate information trail.
|
||
|
||
The advantage to keep these doubled transactions together is that they
|
||
always stay in sync. The advantage to keeping them apart is that it
|
||
clarifies the transfer's point of view. To keep the postings in
|
||
separate files, just separate the two transactions that were joined above.
|
||
For example, for both the expense and the pay-back shown above, the
|
||
following four transactions would be created. Two in your personal ledger
|
||
file:
|
||
|
||
@smallexample
|
||
2004/09/29 Circuit City
|
||
Assets:Reimbursements:Company XYZ $100.00
|
||
Liabilities:MasterCard $-100.00
|
||
|
||
2004/10/15 Company XYZ
|
||
Assets:Checking $100.00
|
||
Assets:Reimbursements:Company XYZ $-100.00
|
||
@end smallexample
|
||
|
||
And two in your company ledger file:
|
||
|
||
@smallexample
|
||
!account Company XYZ
|
||
|
||
2004/09/29 Circuit City
|
||
Expenses:Computer:Software $100.00
|
||
Accounts Payable:Your Name $-100.00
|
||
|
||
2004/10/15 Company XYZ
|
||
Accounts Payable:Your Name $100.00
|
||
Assets:Checking $-100.00
|
||
|
||
!end
|
||
@end smallexample
|
||
|
||
(Note: The @samp{!account} above means that all accounts mentioned in
|
||
the file are children of that account. In this case it means that all
|
||
activity in the file relates to Company XYZ).
|
||
|
||
After creating these transactions, you will always know that $100.00 was
|
||
spent using your MasterCard on behalf of Company XYZ, and that Company
|
||
XYZ spent the money on computer software and paid it back about two
|
||
weeks later.
|
||
|
||
@node Typical queries, Commodities and Currencies, Assets and Liabilities, Principles of Accounting
|
||
@section Typical queries
|
||
|
||
A query such as the following shows all expenses since last
|
||
October, sorted by total:
|
||
|
||
@example
|
||
ledger -b "last oct" -s -S T bal ^expenses
|
||
@end example
|
||
|
||
From left to right the options mean: Show transactions since October, 2003;
|
||
show all sub-accounts; sort by the absolute value of the total; and
|
||
report the balance for all expenses.
|
||
|
||
@menu
|
||
* Reporting monthly expenses::
|
||
* Visualizing with Gnuplot::
|
||
@end menu
|
||
|
||
@node Reporting monthly expenses, Visualizing with Gnuplot, Typical queries, Typical queries
|
||
@subsection Reporting monthly expenses
|
||
|
||
The following query makes it easy to see monthly expenses, with each
|
||
month's expenses sorted by the amount:
|
||
|
||
@example
|
||
ledger -M --period-sort t reg ^expenses
|
||
@end example
|
||
|
||
Now, you might wonder where the money came from to pay for these
|
||
things. To see that report, add @option{-r}, which shows the
|
||
``related account'' postings:
|
||
|
||
@example
|
||
ledger -M --period-sort t -r reg ^expenses
|
||
@end example
|
||
|
||
But maybe this prints too much information. You might just want to
|
||
see how much you're spending with your MasterCard. That kind of query
|
||
requires the use of a display predicate, since the postings
|
||
calculated must match @samp{^expenses}, while the postings
|
||
displayed must match @samp{mastercard}. The command would be:
|
||
|
||
@example
|
||
ledger -M -r -d /mastercard/ reg ^expenses
|
||
@end example
|
||
|
||
This query says: Report monthly subtotals; report the ``related
|
||
account'' postings; display only related postings whose
|
||
account matches @samp{mastercard}, and base the calculation on
|
||
postings matching @samp{^expenses}.
|
||
|
||
This works just as well for report the overall total, too:
|
||
|
||
@example
|
||
ledger -s -r -d /mastercard/ reg ^expenses
|
||
@end example
|
||
|
||
The @option{-s} option subtotals all postings, just as @option{-M}
|
||
subtotaled by the month. The running total in both cases is off,
|
||
however, since a display expression is being used.
|
||
|
||
@node Visualizing with Gnuplot, , Reporting monthly expenses, Typical queries
|
||
@subsection Visualizing with Gnuplot
|
||
|
||
If you have @command{Gnuplot} installed, you can graph any of the
|
||
above register reports. The script to do this is included in the
|
||
ledger distribution, and is named @file{scripts/report}. Install
|
||
@file{report} anywhere along your @env{PATH}, and then use
|
||
@command{report} instead of @command{ledger} when doing a register
|
||
report. The only thing to keep in mind is that you must specify
|
||
@option{-j} or @option{-J} to indicate whether Gnuplot should plot the
|
||
amount, or the running total. For example, this command plots total
|
||
monthly expenses made on your MasterCard.
|
||
|
||
@example
|
||
report -j -M -r -d /mastercard/ reg ^expenses
|
||
@end example
|
||
|
||
The @command{report} script is a very simple Bourne shell script, that
|
||
passes a set of scripted commands to Gnuplot. Feel free to modify the
|
||
script to your liking, since you may prefer histograms to line plots,
|
||
for example.
|
||
|
||
@menu
|
||
* Typical plots::
|
||
@end menu
|
||
|
||
@node Typical plots, , Visualizing with Gnuplot, Visualizing with Gnuplot
|
||
@subsubsection Typical plots
|
||
|
||
Here are some useful plots:
|
||
|
||
@smallexample
|
||
report -j -M reg ^expenses # monthly expenses
|
||
report -J reg checking # checking account balance
|
||
report -J reg ^income ^expenses # cash flow report
|
||
|
||
# net worth report, ignoring non-$ postings
|
||
|
||
report -J -l "Ua>=@{\$0.01@}" reg ^assets ^liab
|
||
|
||
# net worth report starting last February. the use of a display
|
||
# predicate (-d) is needed, otherwise the balance will start at
|
||
# zero, and thus the y-axis will not reflect the true balance
|
||
|
||
report -J -l "Ua>=@{\$0.01@}" -d "d>=[last feb]" reg ^assets ^liab
|
||
@end smallexample
|
||
|
||
The last report uses both a calculation predicate (@option{-l}) and a
|
||
display predicate (@option{-d}). The calculation predicates limits
|
||
the report to postings whose amount is greater than $1 (which can
|
||
only happen if the posting amount is in dollars). The display
|
||
predicate limits the transactions @emph{displayed} to just those since last
|
||
February, even those transactions from before then will be computed as part
|
||
of the balance.
|
||
|
||
|
||
@node Commodities and Currencies, Accounts and Inventories, Typical queries, Principles of Accounting
|
||
@section Commodities and Currencies
|
||
|
||
Ledger makes no assumptions about the commodities you use; it only
|
||
requires that you specify a commodity. The commodity may be any
|
||
non-numeric string that does not contain a period, comma, forward
|
||
slash or at-sign. It may appear before or after the amount, although
|
||
it is assumed that symbols appearing before the amount refer to
|
||
currencies, while non-joined symbols appearing after the amount refer
|
||
to commodities. Here are some valid currency and commodity
|
||
specifiers:
|
||
|
||
@example
|
||
$20.00 ; currency: twenty US dollars
|
||
40 AAPL ; commodity: 40 shares of Apple stock
|
||
60 DM ; currency: 60 Deutsch Mark
|
||
£50 ; currency: 50 British pounds
|
||
50 EUR ; currency: 50 Euros (or use appropriate symbol)
|
||
@end example
|
||
|
||
Ledger will examine the first use of any commodity to determine how
|
||
that commodity should be printed on reports. It pays attention to
|
||
whether the name of commodity was separated from the amount, whether
|
||
it came before or after, the precision used in specifying the amount,
|
||
whether thousand marks were used, etc. This is done so that printing
|
||
the commodity looks the same as the way you use it.
|
||
|
||
An account may contain multiple commodities, in which case it will
|
||
have separate totals for each. For example, if your brokerage account
|
||
contains both cash, gold, and several stock quantities, the balance
|
||
might look like:
|
||
|
||
@smallexample
|
||
$200.00
|
||
100.00 AU
|
||
AAPL 40
|
||
BORL 100
|
||
FEQTX 50 Assets:Brokerage
|
||
@end smallexample
|
||
|
||
This balance report shows how much of each commodity is in your
|
||
brokerage account.
|
||
|
||
Sometimes, you will want to know the current street value of your
|
||
balance, and not the commodity totals. For this to happen, you must
|
||
specify what the current price is for each commodity. The price can
|
||
be any commodity, in which case the balance will be computed in terms
|
||
of that commodity. The usual way to specify prices is with a price
|
||
history file, which might look like this:
|
||
|
||
@smallexample
|
||
P 2004/06/21 02:18:01 FEQTX $22.49
|
||
P 2004/06/21 02:18:01 BORL $6.20
|
||
P 2004/06/21 02:18:02 AAPL $32.91
|
||
P 2004/06/21 02:18:02 AU $400.00
|
||
@end smallexample
|
||
|
||
Specify the price history to use with the @option{--price-db} option,
|
||
with the @option{-V} option to report in terms of current market
|
||
value:
|
||
|
||
@example
|
||
ledger --price-db prices.db -V balance brokerage
|
||
@end example
|
||
|
||
The balance for your brokerage account will be reported in US dollars,
|
||
since the prices database uses that currency.
|
||
|
||
@smallexample
|
||
$40880.00 Assets:Brokerage
|
||
@end smallexample
|
||
|
||
You can convert from any commodity to any other commodity. Let's say
|
||
you had $5000 in your checking account, and for whatever reason you
|
||
wanted to know many ounces of gold that would buy, in terms of the
|
||
current price of gold:
|
||
|
||
@example
|
||
ledger -T "@{1 AU@}*(O/P@{1 AU@})" balance checking
|
||
@end example
|
||
|
||
Although the total expression appears complex, it is simply saying
|
||
that the reported total should be in multiples of AU units, where the
|
||
quantity is the account total divided by the price of one AU. Without
|
||
the initial multiplication, the reported total would still use the
|
||
dollars commodity, since multiplying or dividing amounts always keeps
|
||
the left value's commodity. The result of this command might be:
|
||
|
||
@smallexample
|
||
14.01 AU Assets:Checking
|
||
@end smallexample
|
||
|
||
@menu
|
||
* Commodity Price Histories::
|
||
* Commodity equivalencies::
|
||
@end menu
|
||
|
||
@node Commodity Price Histories, Commodity equivalencies, Commodities and Currencies, Commodities and Currencies
|
||
@subsection Commodity price histories
|
||
|
||
Whenever a commodity is purchased using a different commodity (such as
|
||
a share of common stock using dollars), it establishes a price for
|
||
that commodity on that day. It is also possible, by recording price
|
||
details in a ledger file, to specify other prices for commodities at
|
||
any given time. Such price transactions might look like those below:
|
||
|
||
@smallexample
|
||
P 2004/06/21 02:17:58 TWCUX $27.76
|
||
P 2004/06/21 02:17:59 AGTHX $25.41
|
||
P 2004/06/21 02:18:00 OPTFX $39.31
|
||
P 2004/06/21 02:18:01 FEQTX $22.49
|
||
P 2004/06/21 02:18:02 AAPL $32.91
|
||
@end smallexample
|
||
|
||
By default, ledger will not consider commodity prices when generating
|
||
its various reports. It will always report balances in terms of the
|
||
commodity total, rather than the current value of those commodities.
|
||
To enable pricing reports, use one of the commodity reporting options.
|
||
|
||
@node Commodity equivalencies, , Commodity Price Histories, Commodities and Currencies
|
||
@subsection Commodity equivalencies
|
||
|
||
Sometimes a commodity has several forms which are all equivalent. An
|
||
example of this is time. Whether tracked in terms of minutes, hours
|
||
or days, it should be possible to convert between the various forms.
|
||
Doing this requires the use of commodity equivalencies.
|
||
|
||
For example, you might have the following two postings, one which
|
||
transfers an hour of time into a @samp{Billable} account, and another
|
||
which decreases the same account by ten minutes. The resulting report
|
||
will indicate that fifty minutes remain:
|
||
|
||
@smallexample
|
||
2005/10/01 Work done for company
|
||
Billable:Client 1h
|
||
Project:XYZ
|
||
|
||
2005/10/02 Return ten minutes to the project
|
||
Project:XYZ 10m
|
||
Billable:Client
|
||
@end smallexample
|
||
|
||
Reporting the balance for this ledger file produces:
|
||
|
||
@smallexample
|
||
50.0m Billable:Client
|
||
-50.0m Project:XYZ
|
||
@end smallexample
|
||
|
||
This example works because ledger already knows how to handle seconds,
|
||
minutes and hours, as part of its time tracking support. Defining
|
||
other equivalencies is simple. The following is an example that
|
||
creates data equivalencies, helpful for tracking bytes, kilobytes,
|
||
megabytes, and more:
|
||
|
||
@smallexample
|
||
C 1.00 Kb = 1024 b
|
||
C 1.00 Mb = 1024 Kb
|
||
C 1.00 Gb = 1024 Mb
|
||
C 1.00 Tb = 1024 Gb
|
||
@end smallexample
|
||
|
||
Each of these definitions correlates a commodity (such as @samp{Kb})
|
||
and a default precision, with a certain quantity of another commodity.
|
||
In the above example, kilobytes are reporetd with two decimal places
|
||
of precision and each kilobyte is equal to 1024 bytes.
|
||
|
||
Equivalency chains can be as long as desired. Whenever a commodity
|
||
would report as a decimal amount (less than @samp{1.00}), the next
|
||
smallest commodity is used. If a commodity could be reported in terms
|
||
of a higher commodity without resulting to a partial fraction, then
|
||
the larger commodity is used.
|
||
|
||
@node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Principles of Accounting
|
||
@section Accounts and Inventories
|
||
|
||
Since Ledger's accounts and commodity system is so flexible, you can
|
||
have accounts that don't really exist, and use commodities that no one
|
||
else recognizes. For example, let's say you are buying and selling
|
||
various items in EverQuest, and want to keep track of them using a
|
||
ledger. Just add items of whatever quantity you wish into your
|
||
EverQuest account:
|
||
|
||
@smallexample
|
||
9/29 Get some stuff at the Inn
|
||
Places:Black's Tavern -3 Apples
|
||
Places:Black's Tavern -5 Steaks
|
||
EverQuest:Inventory
|
||
@end smallexample
|
||
|
||
Now your EverQuest:Inventory has 3 apples and 5 steaks in it. The
|
||
amounts are negative, because you are taking @emph{from} Black's
|
||
Tavern in order to add to your Inventory account. Note that you don't
|
||
have to use @samp{Places:Black's Tavern} as the source account. You
|
||
could use @samp{EverQuest:System} to represent the fact that you
|
||
acquired them online. The only purpose for choosing one kind of
|
||
source account over another is for generate more informative reports
|
||
later on. The more you know, the better analysis you can perform.
|
||
|
||
If you later sell some of these items to another player, the transaction
|
||
would look like:
|
||
|
||
@smallexample
|
||
10/2 Sturm Brightblade
|
||
EverQuest:Inventory -2 Steaks
|
||
EverQuest:Inventory 15 Gold
|
||
@end smallexample
|
||
|
||
Now you've turned 2 steaks into 15 gold, courtesy of your customer,
|
||
Sturm Brightblade.
|
||
|
||
@node Understanding Equity, Dealing with Petty Cash, Accounts and Inventories, Principles of Accounting
|
||
@section Understanding Equity
|
||
|
||
The most confusing transaction in any ledger will be your equity account---
|
||
because starting balances can't come out of nowhere.
|
||
|
||
When you first start your ledger, you will likely already have money
|
||
in some of your accounts. Let's say there's $100 in your checking
|
||
account; then add a transaction to your ledger to reflect this amount.
|
||
Where will money come from? The answer: your equity.
|
||
|
||
@smallexample
|
||
10/2 Opening Balance
|
||
Assets:Checking $100.00
|
||
Equity:Opening Balances
|
||
@end smallexample
|
||
|
||
But what is equity? You may have heard of equity when people talked
|
||
about house mortgages, as ``the part of the house that you own''.
|
||
Basically, equity is like the value of something. If you own a car
|
||
worth $5000, then you have $5000 in equity in that car. In order to
|
||
turn that car (a commodity) into a cash flow, or a credit to your bank
|
||
account, you will have to debit the equity by selling it.
|
||
|
||
When you start a ledger, you are probably already worth something.
|
||
Your net worth is your current equity. By transferring the money in
|
||
the ledger from your equity to your bank accounts, you are crediting
|
||
the ledger account based on your prior equity. That is why, when you
|
||
look at the balance report, you will see a large negative number for
|
||
Equity that never changes: Because that is what you were worth (what
|
||
you debited from yourself in order to start the ledger) before the
|
||
money started moving around. If the total positive value of your
|
||
assets is greater than the absolute value of your starting equity, it
|
||
means you are making money.
|
||
|
||
Clear as mud? Keep thinking about it. Until you figure it out, put
|
||
@samp{-Equity} at the end of your balance command, to remove the
|
||
confusing figure from the total.
|
||
|
||
@node Dealing with Petty Cash, Working with multiple funds and accounts, Understanding Equity, Principles of Accounting
|
||
@section Dealing with Petty Cash
|
||
|
||
Something that stops many people from keeping a ledger at all is the
|
||
insanity of tracking small cash expenses. They rarely generate a
|
||
receipt, and there are often a lot of small postings, rather than
|
||
a few large ones, as with checks.
|
||
|
||
One solution is: don't bother. Move your spending to a debit card,
|
||
but in general ignore cash. Once you withdraw it from the ATM, mark
|
||
it as already spent to an @samp{Expenses:Cash} category:
|
||
|
||
@smallexample
|
||
2004/03/15 ATM
|
||
Expenses:Cash $100.00
|
||
Assets:Checking
|
||
@end smallexample
|
||
|
||
If at some point you make a large cash expense that you want to track,
|
||
just ``move'' the amount of the expense from @samp{Expenses:Cash} into
|
||
the target account:
|
||
|
||
@smallexample
|
||
2004/03/20 Somebody
|
||
Expenses:Food $65.00
|
||
Expenses:Cash
|
||
@end smallexample
|
||
|
||
This way, you can still track large cash expenses, while ignoring all
|
||
of the smaller ones.
|
||
|
||
@node Working with multiple funds and accounts, , Dealing with Petty Cash, Principles of Accounting
|
||
@section Working with multiple funds and accounts
|
||
|
||
There are situations when the accounts you're tracking are different
|
||
between your clients and the financial institutions where money is
|
||
kept. An example of this is working as the treasurer for a religious
|
||
institution. From the secular point of view, you might be working
|
||
with three different accounts:
|
||
|
||
@itemize
|
||
@item Checking
|
||
@item Savings
|
||
@item Credit Card
|
||
@end itemize
|
||
|
||
From a religious point of view, the community expects to divide its
|
||
resources into multiple ``funds'', from which it makes purchases or
|
||
reserves resources for later:
|
||
|
||
@itemize
|
||
@item School fund
|
||
@item Building fund
|
||
@item Community fund
|
||
@end itemize
|
||
|
||
The problem with this kind of setup is that when you spend money, it
|
||
comes from two or more places at once: the account and the fund. And
|
||
yet, the correlation of amounts between funds and accounts is rarely
|
||
one-to-one. What if the school fund has @samp{$500.00}, but
|
||
@samp{$400.00} of that comes from Checking, and @samp{$100.00} from
|
||
Savings?
|
||
|
||
Traditional finance packages require that the money reside in only one
|
||
place. But there are really two ``views'' of the data: from the
|
||
account point of view and from the fund point of view -- yet both sets
|
||
should reflect the same overall expenses and cash flow. It's simply
|
||
where the money resides that differs.
|
||
|
||
This situation can be handled one of two ways. The first is using
|
||
virtual postings to represent the fact that money is moving to and
|
||
from two kind of accounts at the same time:
|
||
|
||
@smallexample
|
||
2004/03/20 Contributions
|
||
Assets:Checking $500.00
|
||
Income:Donations
|
||
|
||
2004/03/25 Distribution of donations
|
||
[Funds:School] $300.00
|
||
[Funds:Building] $200.00
|
||
[Assets:Checking] $-500.00
|
||
@end smallexample
|
||
|
||
The use of square brackets in the second transaction ensures that the
|
||
virtual postings balance to zero. Now money can be spent directly
|
||
from a fund at the same time as money is drawn from a physical
|
||
account:
|
||
|
||
@smallexample
|
||
2004/03/25 Payment for books (paid from Checking)
|
||
Expenses:Books $100.00
|
||
Assets:Checking $-100.00
|
||
(Funds:School) $-100.00
|
||
@end smallexample
|
||
|
||
When reports are generated, by default they'll appear in terms of the
|
||
funds. In this case, you will likely want to mask out your
|
||
@samp{Assets} account, because otherwise the balance won't make much
|
||
sense:
|
||
|
||
@example
|
||
ledger bal -^Assets
|
||
@end example
|
||
|
||
If the @option{--real} option is used, the report will be in terms of
|
||
the real accounts:
|
||
|
||
@example
|
||
ledger --real bal
|
||
@end example
|
||
|
||
If more asset accounts are needed as the source of a posting, just
|
||
list them as you would normally, for example:
|
||
|
||
@smallexample
|
||
2004/03/25 Payment for books (paid from Checking)
|
||
Expenses:Books $100.00
|
||
Assets:Checking $-50.00
|
||
Liabilities:Credit Card $-50.00
|
||
(Funds:School) $-100.00
|
||
@end smallexample
|
||
|
||
The second way of tracking funds is to use transaction codes. In this
|
||
respect the codes become like virtual accounts that embrace the entire
|
||
set of postings. Basically, we are associating a transaction with a
|
||
fund by setting its code. Here are two transactions that desposit money
|
||
into, and spend money from, the @samp{Funds:School} fund:
|
||
|
||
@smallexample
|
||
2004/03/25 (Funds:School) Donations
|
||
Assets:Checking $100.00
|
||
Income:Donations
|
||
|
||
2004/04/25 (Funds:School) Payment for books
|
||
Expenses:Books $50.00
|
||
Assets:Checking
|
||
@end smallexample
|
||
|
||
Note how the accounts now relate only to the real accounts, and any
|
||
balance or registers reports will reflect this. That the transactions
|
||
relate to a particular fund is kept only in the code.
|
||
|
||
How does this become a fund report? By using the
|
||
@option{--code-as-payee} option, you can generate a register report
|
||
where the payee for each posting shows the code. Alone, this is
|
||
not terribly interesting; but when combined with the
|
||
@option{--by-payee} option, you will now see account subtotals for any
|
||
postings related to a specific fund. So, to see the current
|
||
monetary balances of all funds, the command would be:
|
||
|
||
@smallexample
|
||
ledger --code-as-payee -P reg ^Assets
|
||
@end smallexample
|
||
|
||
Or to see a particular funds expenses, the @samp{School} fund in this
|
||
case:
|
||
|
||
@smallexample
|
||
ledger --code-as-payee -P reg ^Expenses -- School
|
||
@end smallexample
|
||
|
||
Both approaches yield different kinds of flexibility, depending on how
|
||
you prefer to think of your funds: as virtual accounts, or as tags
|
||
associated with particular transactions. Your own tastes will decide which
|
||
is best for your situation.
|
||
|
||
|
||
@node Keeping a Journal, Building Reports, 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::
|
||
* Commenting on your journal::
|
||
* Starting up::
|
||
* Currency and Commodities::
|
||
* Structuring Your Accounts::
|
||
* Advanced Transactions::
|
||
* File Format::
|
||
* Archiving Previous Years ::
|
||
* Using emacs::
|
||
@end menu
|
||
|
||
@node Most Basic Entry, Commenting on your journal, 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 not count the transaction and will not
|
||
give an error. There must be at least two spaces, or a tab, between the
|
||
amount and the account. If you do not have adequate separation between
|
||
the amount and the account Ledger will give an error and stop
|
||
calculating}
|
||
|
||
|
||
@menu
|
||
* Comments::
|
||
@end menu
|
||
|
||
@node Commenting on your journal, Starting up, Most Basic Entry, 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
|
||
three 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
|
||
multipl lines
|
||
!end comment
|
||
@end smallexample
|
||
|
||
@node Starting up, Currency and Commodities, Commenting on your journal, Keeping a Journal
|
||
@section Starting up
|
||
|
||
@cindex initial equity
|
||
@cindex beginning ledger
|
||
|
||
Unless you have recntly 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 Currency and Commodities, Structuring Your Accounts, Starting up, 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 labelled using whatever is convenient for you (stock ticker
|
||
symbols are suggested for publicly traded assets).@footnote{you can
|
||
track ANYTHING, even time or distance travelled. As long as it cannot be
|
||
created or destroyed inside your accounting system.}
|
||
|
||
For the rest of this manual, we will only use the word ``commodities''
|
||
when refering to the units on a transaction value.
|
||
|
||
This is fundamentally different than many common accounting packages,
|
||
which assume the same currency throughout all of your accounts. This
|
||
means if you typically operate in Euros, but travel to the US and have
|
||
some expenses, you would have to do the currency conversion BEFORE you
|
||
made the entry into your financial system. With ledger this is not
|
||
required. In the same journal you can have entries in any or all
|
||
commodities you actually hold. You can use the reporting capabilities
|
||
to convert all commodities to a single commodity for reporting purposes
|
||
without ever changing the underlying entry.
|
||
|
||
For example, the following entries reflect transaction made for a
|
||
business trip to Europe from the US:
|
||
|
||
@smallexample
|
||
2011/09/23 Cash in Munich
|
||
Assets:Cash E50.00
|
||
Assets:Checking $-66.00
|
||
|
||
2011/09/24 Dinner in Munich
|
||
Expenses:Business:Travel E35.00
|
||
Assets:Cash
|
||
@end smallexample
|
||
|
||
This says that $66.00 came out of checking and turned into 50 Euros. The
|
||
implied exchange rate was $1.32. Then 35.00 Euros was spent on Dinner
|
||
in Munich.
|
||
|
||
Running a ledger balance report shows:
|
||
@smallexample
|
||
$ ledger -f example.dat bal
|
||
$-66.00
|
||
E15.00 Assets
|
||
E15.00 Cash
|
||
$-66.00 Checking
|
||
E35.00 Expenses:Business:Travel
|
||
--------------------
|
||
$-66.00
|
||
E50.00
|
||
@end smallexample
|
||
|
||
The top two lines show my current assets as $-66.00 in checking (in this
|
||
very short example I didn't establish opening an opening balance for the
|
||
checking account) and E15.00. After spending on dinner i have E15.00 in
|
||
my wallet. The bottom line balances to zero, but is shown in two lines
|
||
since we haven't told ledger to convert commodities.
|
||
|
||
@menu
|
||
* Naming Commodities::
|
||
* Buying and Selling Stock::
|
||
* Fixing Lot Prices::
|
||
@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 whitespace. However,
|
||
if you include whitespace 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 purcase 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
|
||
|
||
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, , Buying and Selling Stock, Currency and Commodities
|
||
@subsection Fixing Lot Prices
|
||
@cindex fixing lot prices
|
||
@cindex consumable commodity pricing
|
||
Commodites 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.29 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
|
||
11 cent difference, which is then balanced by Assets:Checking because
|
||
its amount is null.
|
||
|
||
@node Structuring Your Accounts, Advanced Transactions, Currency and Commodities, 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 moeny comes from
|
||
@item
|
||
Liabilities: money you owe
|
||
@item
|
||
Equity: the real value of your property.
|
||
@end enumerate
|
||
|
||
Starting the structure off this way will make it simpler for you to get
|
||
answers to the questions you really need to ask about your finances.
|
||
|
||
Beneath these top level accounts you can have any level of detail you
|
||
desire. For example, if you want to keep specific track of how much you spend on
|
||
burgers and fries, you could have the following:
|
||
@smallexample
|
||
Expenses:Food:Hamburgers and Fries
|
||
@end smallexample
|
||
|
||
|
||
|
||
|
||
@node Advanced Transactions, File Format, Structuring Your Accounts, Keeping a Journal
|
||
@section Advanced Transactions
|
||
@menu
|
||
* Transaction Notes and Tags::
|
||
* Multiple Account Transactions::
|
||
* Virtual Transactions::
|
||
* Automatic Transactions::
|
||
* Checking Balances and Reconciliations::
|
||
* Effective Dates::
|
||
* Periodic Transactions::
|
||
* Recording Commodity Lot Prices::
|
||
@end menu
|
||
|
||
@node Transaction Notes and Tags, Multiple Account Transactions, Advanced Transactions, Advanced Transactions
|
||
@subsection Transaction Notes and Tags
|
||
|
||
Ledger 3.0 supports entry and transaction ``notes'', which may
|
||
contain new metadata and tag markers. Here's an example:
|
||
@cindex metadata
|
||
@cindex tags
|
||
|
||
@smallexample
|
||
2004/05/27 (100) Credit card company
|
||
; This is an entry note!
|
||
; Sample: Value
|
||
Liabilities:MasterCard $20.00
|
||
; This is a transaction note!
|
||
; Sample: Another Value
|
||
; :MyTag:
|
||
Assets:Bank:Checking
|
||
; :AnotherTag:
|
||
@end smallexample
|
||
|
||
An indented paragraph starting with `;' is parsed as a persistent note
|
||
for its preceding category. These notes will get printed back to you
|
||
with the ``print'' command. They are accessible to value expressions
|
||
using the ``note'' variable.
|
||
|
||
Further, any occurrence of ``:foo:'' in a note will cause a metadata tag
|
||
for "foo" to be registered for that entry. You can then search for
|
||
such transactions using:
|
||
@findex %
|
||
@cindex tags
|
||
@smallexample
|
||
ledger reg %foo
|
||
ledger reg tag foo
|
||
@end smallexample
|
||
|
||
@cindex setting the value of a tag
|
||
@cindex value tags
|
||
|
||
Also, if any word in the note ends (but does not start) with a colon,
|
||
the remainder of that line will be taken to be the metadata value for
|
||
that tag. That is:
|
||
|
||
@smallexample
|
||
; :foo:bar:baz: <-- These are three tags
|
||
; name: value <-- this is a tag with a value
|
||
@end smallexample
|
||
@cindex searching for tags
|
||
@cindex tags, searching for
|
||
Tags with value can be searched for just like tags. In addition, you
|
||
can further limit your tag search by looking for only those tags that
|
||
have specific values:
|
||
|
||
@smallexample
|
||
ledger reg %name=value
|
||
ledger reg tag name=value
|
||
@end smallexample
|
||
@findex --group-by tag
|
||
The group-by and sort functions also support tags:
|
||
@smallexample
|
||
ledger --group-by "tag('foo')" bal
|
||
@end smallexample
|
||
Will produce a balance summary of all transanction with tag `foo' group
|
||
by transactions wiht the same value for `foo'.
|
||
|
||
@smallexample
|
||
ledger reg --sort "tag('foo')" %foo
|
||
@end smallexample
|
||
Produces a register view with the transaction have tag `foo' sorted by
|
||
the tags value.
|
||
|
||
Comments that occur before an entry, or which starts at column zero, are
|
||
always ignored and are neither searched nor printed back.
|
||
|
||
If a posting comment is a date (with brackets), it modifies the date for that posting:
|
||
@smallexample
|
||
2010/02/01 Sample
|
||
Assets:Bank $400.00
|
||
Income:Check $-400.00 ; [2010/01/01]
|
||
@end smallexample
|
||
You can use metadata to override the payee field for individual postings within a transaction: (source)
|
||
@cindex overriding payee using metadata
|
||
@cindex metadata, overiding payee
|
||
@smallexample
|
||
2010/06/17 Sample
|
||
Assets:Bank $400.00
|
||
Income:Check1 $-100.00 ; Payee: Person One
|
||
Income:Check2 $-100.00 ; Payee: Person Two
|
||
Income:Check3 $-100.00 ; Payee: Person Three
|
||
Income:Check4 $-100.00 ; Payee: Person Four
|
||
@end smallexample
|
||
Metadata are normally strings, but you can create metadata of other types:
|
||
|
||
@smallexample
|
||
2010/06/17 Sample
|
||
Assets:Bank $400.00
|
||
Income:Check1 $-100.00
|
||
; Date:: [2010/09/01]
|
||
; Amount:: $100.00
|
||
@end smallexample
|
||
(Note that this Date tag is not the same as the posting date.)
|
||
|
||
@cindex @@tag directive
|
||
@cindex tags, applying to several transactions.
|
||
You apply a tag or tags to a group of transactions by surrounding them with a @code{@@tag ... @@end tag} block.
|
||
For example, if you wanted a
|
||
conceptual ``page'' of transactions relating to business trip to
|
||
Chicago, you could do this:
|
||
|
||
@smallexample
|
||
@@tag Location: Chicago
|
||
@@tag Purpose: Business
|
||
|
||
... transactions go here
|
||
|
||
@@end tag
|
||
@@end tag
|
||
@end smallexample
|
||
It would be as if you'd applied "; Location: Chicago", etc., to every transaction.
|
||
|
||
@node Multiple Account Transactions, Virtual Transactions, Transaction Notes and Tags, Advanced Transactions
|
||
@subsection Multiple Account Transactions
|
||
|
||
Often times a transaction needs to be split across several accounts.
|
||
This is trivially simple in a Ledger journal:
|
||
|
||
@cindex splitting transactions across accounts
|
||
@cindex transactions, splitting across accounts
|
||
@smallexample
|
||
2011/09/15 * Deposit Acme Bytepumps Monthly Paycheck
|
||
Income:Taxable:Acme Bytepumps Inc. $-2500.00
|
||
Assets:Brokerage:Checking $175.00
|
||
Assets:Investments:401K Deferred $250.00
|
||
Expenses:Tax:Medicare $36.25
|
||
Expenses:Tax:Federal Tax $200.00
|
||
Expenses:Tax:State Tax $20.00
|
||
Expenses:Insurance:Life $18.75
|
||
Assets:Credit Union:Joint Checking
|
||
@end smallexample
|
||
|
||
This is an example of a paycheck entry. The money comes @strong{out} of your
|
||
income account, and is spent into several other accounts. The last line
|
||
doesn't require an amount, as ledger will automatically balance the
|
||
transaction (it will be $1800 into the Joint Checking account)
|
||
|
||
|
||
@node Virtual Transactions, Automatic Transactions, Multiple Account Transactions, Advanced Transactions
|
||
@subsection Virtual Transactions
|
||
|
||
|
||
A virtual posting is when you, in your mind, see money as moving
|
||
to a certain place, when in reality that money has not moved at all.
|
||
There are several scenarios in which this type of tracking comes in
|
||
handy, and each of them will be discussed in detail.
|
||
|
||
To enter a virtual posting, surround the account name in
|
||
parentheses. This form of usage does not need to balance. However,
|
||
if you want to ensure the virtual posting balances with other
|
||
virtual postings in the same transaction, use square brackets. For
|
||
example:
|
||
|
||
@smallexample
|
||
10/2 Paycheck
|
||
Assets:Checking $1000.00
|
||
Income:Salary $-1000.00
|
||
(Debt:Alimony) $200.00
|
||
@end smallexample
|
||
|
||
In this example, after receiving a paycheck an alimony debt is
|
||
increased---even though no money has moved around yet.
|
||
|
||
@smallexample
|
||
10/2 Paycheck
|
||
Assets:Checking $1000.00
|
||
Income:Salary $-1000.00
|
||
[Savings:Trip] $200.00
|
||
[Assets:Checking] $-200.00
|
||
@end smallexample
|
||
|
||
In this example, $200 has been deducted from checking toward savings
|
||
for a trip. It will appear as though the money has been moved from
|
||
the account into @samp{Savings:Trip}, although no money has actually
|
||
moved anywhere.
|
||
|
||
When balances are displayed, virtual postings will be factored in.
|
||
To view balances without any virtual balances factored in, using the
|
||
@option{-R} flag, for ``reality''.
|
||
|
||
|
||
@node Automatic Transactions, Checking Balances and Reconciliations, Virtual Transactions, Advanced Transactions
|
||
@subsection Automatic Transactions
|
||
|
||
As a Bahá'í, I need to compute Huqúqu'lláh whenever I acquire assets.
|
||
It is similar to tithing for Jews and Christians, or to Zakát for
|
||
Muslims. The exact details of computing Huqúqu'lláh are somewhat
|
||
complex, but if you have further interest, please consult the Web.
|
||
|
||
Ledger makes this otherwise difficult law very easy. Just set up an
|
||
automated posting at the top of your ledger file:
|
||
|
||
@smallexample
|
||
; This automated transaction will compute Huqúqu'lláh based on this
|
||
; journal's postings. Any that match will affect the
|
||
; Liabilities:Huququ'llah account by 19% of the value of that posting.
|
||
|
||
= /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/
|
||
(Liabilities:Huququ'llah) 0.19
|
||
@end smallexample
|
||
|
||
This automated posting works by looking at each posting in the
|
||
ledger file. If any match the given value expression, 19% of the
|
||
posting's value is applied to the @samp{Liabilities:Huququ'llah}
|
||
account. So, if $1000 is earned from @samp{Income:Salary}, $190 is
|
||
added to @samp{Liabilities:Huqúqu'lláh}; if $1000 is spent on Rent,
|
||
$190 is subtracted. The ultimate balance of Huqúqu'lláh reflects how
|
||
much is owed in order to fulfill one's obligation to Huqúqu'lláh.
|
||
When ready to pay, just write a check to cover the amount shown in
|
||
@samp{Liabilities:Huququ'llah}. That transaction would look like:
|
||
|
||
@smallexample
|
||
2003/01/01 (101) Baha'i Huqúqu'lláh Trust
|
||
Liabilities:Huququ'llah $1,000.00
|
||
Assets:Checking
|
||
@end smallexample
|
||
|
||
That's it. To see how much Huqúq is currently owed based on your
|
||
ledger transactions, use:
|
||
|
||
@smallexample
|
||
ledger balance Liabilities:Huquq
|
||
@end smallexample
|
||
|
||
This works fine, but omits one aspect of the law: that Huquq is only
|
||
due once the liability exceeds the value of 19 mithqáls of gold (which
|
||
is roughly 2.22 ounces). So what we want is for the liability to
|
||
appear in the balance report only when it exceeds the present day
|
||
value of 2.22 ounces of gold. This can be accomplished using the
|
||
command:
|
||
|
||
@smallexample
|
||
ledger -Q -t "/Liab.*Huquq/?(a/P@{2.22 AU@}<=@{-1.0@}&a):a" -s bal liab
|
||
@end smallexample
|
||
|
||
With this command, the current price for gold is downloaded, and the
|
||
Huqúqu'lláh is reported only if its value exceeds that of 2.22 ounces
|
||
of gold. If you wish the liability to be reflected in the parent
|
||
subtotal either way, use this instead:
|
||
|
||
@smallexample
|
||
ledger -Q -T "/Liab.*Huquq/?(O/P@{2.22 AU@}<=@{-1.0@}&O):O" -s bal liab
|
||
@end smallexample
|
||
|
||
In some cases, you may wish to refer to the account of whichever
|
||
posting matched your automated transaction's value expression. To do
|
||
this, use the special account name @samp{$account}:
|
||
|
||
@smallexample
|
||
= /^Some:Long:Account:Name/
|
||
[$account] -0.10
|
||
[Savings] 0.10
|
||
@end smallexample
|
||
|
||
This example causes 10% of the matching account's total to be deferred
|
||
to the @samp{Savings} account---as a balanced virtual posting,
|
||
which may be excluded from reports by using @option{--real}.
|
||
|
||
Automated transactions can use the full range of value expressions in
|
||
their predicate. If you wanted to specify a transaction only occur to
|
||
certain accounts that meet cetain value criteria you could specify:
|
||
|
||
@smallexample
|
||
= /Employees:.*:Payroll$/ and expr (amount >= $1000 and amount < $10000)
|
||
Expenses:Tax 0.27
|
||
@end smallexample
|
||
In this case, @samp{amount} is tied to the amount of the posting being
|
||
tested.
|
||
|
||
But, wait! There's more!
|
||
|
||
@cindex Tax Bracket automation
|
||
@cindex value expressions in automatic transactions
|
||
|
||
In the short example above we calculated the taxes due for income within
|
||
a certain bracket. But in reality this calculation is more difficult.
|
||
There are different rates for different marginal incomes and those taxes
|
||
are not easily descirbed by a simple multiplicative coefficient.
|
||
Automated transactions can use value expressions in their postings to
|
||
determine the ammounts. So to expand the example above for a three tax
|
||
bracket system we could enter:
|
||
|
||
@smallexample
|
||
= /Employees:.*:Payroll$/ and expr (amount < $10000.00)
|
||
(Expenses:Tax) 0.1
|
||
= /Employees:.*:Payroll$/ and expr (amount > $10000.00 and amount < $100000.00 )
|
||
(Expenses:Tax) ($1000.00 + .15 * (amount - $10000.00))
|
||
= /Employees:.*:Payroll$/ and expr (amount > $100000.00)
|
||
(Expenses:Tax) ($13500.00 + .20 * (amount-$100000.00))
|
||
@end smallexample
|
||
|
||
@node Checking Balances and Reconciliations, Effective Dates, Automatic Transactions, Advanced Transactions
|
||
@subsection Forcing balances and Reconciling Accounts
|
||
|
||
|
||
Ledger has a feature for ensuring known past balances. Here's
|
||
an example entry:
|
||
@cindex forcing a balance
|
||
@cindex balance verifications
|
||
@smallexample
|
||
2008/11/26 (Interest) EXTND INS SWEEP ACCT(FDIC-INS)
|
||
* Assets:Brokerage $0.07 = $970.64
|
||
Income:Interest $-0.07
|
||
@end smallexample
|
||
|
||
What this says is that as of 11/26/08 (bank perspective), the
|
||
Assets:Brokerage account was known to equal $970.64. It @strong{must}
|
||
equal this amount at this point in the Ledger file, or there will be a
|
||
balancing error.
|
||
|
||
If you reconcile bank statements you can enter the reconciliation and
|
||
link to a file (if you have it)
|
||
@cindex statement reconciliation
|
||
@cindex reconcile statements
|
||
|
||
@smallexample
|
||
2009/12/01 Foo
|
||
Assets:Checking $10.00
|
||
Equity
|
||
|
||
2009/12/10 Reconciled statement dated 2009/12/08
|
||
; Link: [[file:statements/checking/2009-12.pdf][2009-12.pdf]]
|
||
[Assets:Checking] = $10.00
|
||
@end smallexample
|
||
|
||
@node Effective Dates, Periodic Transactions, Checking Balances and Reconciliations, Advanced 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 that you want to distribute cost for. 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, Recording Commodity Lot Prices, Effective Dates, Advanced Transactions
|
||
@subsection Periodic Transactions
|
||
|
||
A periodic transaction starts with a ~ followed by a period expression.
|
||
Periodic transactions are used for budgeting and forecasting only, they
|
||
have no effect without the @samp{--budget} option specified.
|
||
|
||
See @ref{Budgeting and Forecasting} for examples and details.
|
||
|
||
@node Recording Commodity Lot Prices, , Periodic Transactions, Advanced Transactions
|
||
@subsection Recording Commodity Lot Prices
|
||
|
||
If you are tracking investments it is often necessary to keep track of
|
||
specific purchases of a commodity bought at difference prices. These
|
||
specific purchases are referred to as ``lots''. Tracking lots using ledger
|
||
requires some additional info in the journal as well as additional
|
||
command-line options when generating reports.
|
||
|
||
Say you want to record purchase of two separate lots of ACME, then sell
|
||
some shares. The correct way to do this is:
|
||
|
||
@smallexample
|
||
2010-09-01 * Buy 2 shares of ACME @@ $100
|
||
Assets:Broker 2 ACME @@ $100.00
|
||
Assets:Cash
|
||
|
||
2010-09-10 * Buy 2 share of ACME @@ $110
|
||
Assets:Broker 2 ACME @@ $110.00
|
||
Assets:Cash
|
||
|
||
2011-09-20 * Sell 2 shares of ACME @@ $150
|
||
Assets:Broker -1 ACME @{$100.00@} @@ $150.00
|
||
Assets:Broker -1 ACME @{$200.00@} @@ $150.00
|
||
Assets:Cash
|
||
@end smallexample
|
||
|
||
To report which lots of commodities you hold, use the
|
||
@samp{--lot-prices} option. For example, after buying the 2 shares at
|
||
$100 and 1 at $200 it would show you:
|
||
@smallexample
|
||
$ ledger balance --lot-prices Assets:Broker until 2011-09-15
|
||
2 ACME @{$100.00@}
|
||
1 ACME @{$200.00@} Assets:Broker
|
||
@end smallexample
|
||
@noindent without the @samp{--lot-prices} option you would only see the total number of shares you held:
|
||
@smallexample
|
||
$ ledger balance Assets:Broker until 2011-09-15
|
||
3 ACME Assets:Broker
|
||
@end smallexample
|
||
@noindent and after the sale on @samp{2011-09-20} it would show you:
|
||
@smallexample
|
||
$ ledger balance --lot-prices Assets:Broker
|
||
1 ACME @{$100.00@} Assets:Broker
|
||
@end smallexample
|
||
|
||
|
||
@node File Format, Archiving Previous Years , Advanced Transactions, Keeping a Journal
|
||
@section File Format for Users
|
||
@menu
|
||
* File Format Intro::
|
||
* Transaction and Comments::
|
||
* Command Directives::
|
||
@end menu
|
||
|
||
@node File Format Intro, Transaction and Comments, File Format, File Format
|
||
@subsection Introduction
|
||
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.
|
||
|
||
@node Transaction and Comments, Command Directives, File Format Intro, File 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 whitespace, to denote the
|
||
transaction's account postings. The format of the first line is:
|
||
|
||
@smallexample
|
||
DATE[=EDATE] [*|!] [(CODE)] DESC
|
||
@end smallexample
|
||
|
||
If @samp{*} appears after the date (with optional effective date), it
|
||
indicates the transaction is ``cleared'', which can mean whatever the user
|
||
wants it to mean. If @samp{!} appears after the date, it indicates d
|
||
the transaction is ``pending''; i.e., tentatively cleared from the user's
|
||
point of view, but not yet actually cleared. If a @samp{CODE} appears
|
||
in parentheses, it may be used to indicate a check number, or the type
|
||
of the posting. Following these is the payee, or a description of
|
||
the posting.
|
||
|
||
The format of each following posting is:
|
||
|
||
@smallexample
|
||
ACCOUNT AMOUNT [; NOTE]
|
||
@end smallexample
|
||
|
||
The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual
|
||
posting, or square brackets if it is a virtual posting that
|
||
must balance. The @samp{AMOUNT} can be followed by a per-unit
|
||
posting cost, by specifying @samp{@@ AMOUNT}, or a complete
|
||
posting cost with @samp{@@@@ AMOUNT}. Lastly, the @samp{NOTE} may
|
||
specify an actual and/or effective date for the posting by using
|
||
the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or
|
||
@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}.(See @pxref{Virtual Transactions})
|
||
|
||
@item 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{Automatic Transactions}).
|
||
|
||
@item ~
|
||
A period transaction. A period expression must appear after the tilde.
|
||
|
||
After this initial line there should be a set of one or more
|
||
postings, just as if it were normal transaction.
|
||
|
||
@item ; # % | *
|
||
A line beginning with 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, File Format
|
||
@subsection Command Directives
|
||
|
||
@table @code
|
||
@item ! @@
|
||
A line beginning with an exclamation mark or an @@ sign denotes a
|
||
command directive. It must be immediately followed by a command word.
|
||
The supported commands are:
|
||
|
||
|
||
@item account
|
||
@c instance_t::master_account_directive
|
||
Sets the base for all account 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 adn your business finances. In order to keep them seperate 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
|
||
|
||
@@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 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
|
||
tham.
|
||
@item assert
|
||
@c instance_t::assert_directive
|
||
An assertion can throw an eror 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 ammount 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
|
||
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
|
||
Start a block comment, closed by @code{@@end comment}.
|
||
@item define
|
||
@c instance_t::define_directive
|
||
@item end
|
||
@c instance_t::end_directive
|
||
@item expr
|
||
@c instance_t::expr_directive
|
||
@item fixed
|
||
@c instance_t::fixed_directive
|
||
@item include
|
||
@c instance_t::include_directive
|
||
Include the stated file as if it were part of the current file.
|
||
@item payee
|
||
@c instance_t::payee_mapping_directive
|
||
Directs Ledger to replace any payee matching a regex with the given
|
||
payee. You may download transactions from your bank that you want to be
|
||
shortened or altered. For example, the the payee for the grocery store
|
||
near me is only one character different than the payee if I buy gasoline
|
||
at the grocery story. I can enter payee mappings that make this very clear:
|
||
|
||
@smallexample
|
||
@@payee Supermarket Gas Supermarket 4
|
||
@@payee Supermarket Groceries Supermarket 1
|
||
@end smallexample
|
||
|
||
Ledger will display the mapped payees in @code{print} and
|
||
@code{register} reports.
|
||
@item tag
|
||
@c instance_t::tag_directive
|
||
Allows you to designate a block of transactions and assign the same tag to all. Tags can have values and may be nested.
|
||
@smallexample
|
||
@@tag hastag
|
||
@@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 tag nestedtag
|
||
|
||
2011/12/01 Sale
|
||
Assets:Checking:Business $ 30.00
|
||
Income:Sales
|
||
@@end 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. placeing the
|
||
name of the tag that is being closed is a simple way to keep track.
|
||
|
||
@item test
|
||
@c instance_t::comment_directive
|
||
@item year
|
||
@c instance_t::year_directive
|
||
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, File Format, Keeping a Journal
|
||
@section Archiving Previous Years
|
||
|
||
|
||
After a while, your journal can get to be pretty large. While this will
|
||
not slow down Ledger---it's designed to process journals very
|
||
quickly---things can start to feel ``messy''; and it's a universal
|
||
complaint that when finances feel messy, people avoid them.
|
||
|
||
Thus, archiving the data from previous years into their own files can
|
||
offer a sense of completion, and freedom from the past. But how to best
|
||
accomplish this with the ledger program? There are two commands that
|
||
make it very simple: @command{print}, and @command{equity}.
|
||
|
||
Let's take an example file, with data ranging from year 2000 until 2004.
|
||
We want to archive years 2000 and 2001 to their own file, leaving just
|
||
2003 and 2004 in the current file. So, use @command{print} to output
|
||
all the earlier transactions to a file called @file{ledger-old.dat}:
|
||
|
||
@smallexample
|
||
ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat
|
||
@end smallexample
|
||
|
||
To delete older data from the current ledger file, use @command{print}
|
||
again, this time specifying year 2002 as the starting date:
|
||
|
||
@smallexample
|
||
ledger -f ledger.dat -b 2002 print > x
|
||
mv x ledger.dat
|
||
@end smallexample
|
||
|
||
However, now the current file contains @emph{only} postings from 2002
|
||
onward, which will not yield accurate present-day balances, because the
|
||
net income from previous years is no longer being tallied. To
|
||
compensate for this, we must append an equity report for the old ledger
|
||
at the beginning of the new one:
|
||
|
||
@smallexample
|
||
ledger -f ledger-old.dat equity > equity.dat
|
||
cat equity.dat ledger.dat > x
|
||
mv x ledger.dat
|
||
rm equity.dat
|
||
@end smallexample
|
||
|
||
Now the balances reported from @file{ledger.dat} are identical to what
|
||
they were before the data was split.
|
||
|
||
How often should you split your ledger? You never need to, if you
|
||
don't want to. Even eighty years of data will not slow down ledger
|
||
much---and that's just using present day hardware! Or, you can keep
|
||
the previous and current year in one file, and each year before that
|
||
in its own file. It's really up to you, and how you want to organize
|
||
your finances. For those who also keep an accurate paper trail, it
|
||
might be useful to archive the older years to their own files, then
|
||
burn those files to a CD to keep with the paper records---along with
|
||
any electronic statements received during the year. In the arena of
|
||
organization, just keep in mind this maxim: Do whatever keeps you
|
||
doing it.
|
||
|
||
@node 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 modifed by any text
|
||
editor. A special mode for emacs is included with the source
|
||
distribution.
|
||
|
||
@cindex emacs .emacs file
|
||
To use the emacs mopy, copy the several lisp files from the source lisp
|
||
directory your your @file{site-lisp} directoy 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
|
||
goto 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 autocompletion
|
||
@cindex misspelled accounts treated as new
|
||
|
||
In most financial programs, some sort of autocompletion is avaiable 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 minibuffer 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 minibuffer 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 Building Reports, Reporting Commands, Keeping a Journal, Top
|
||
@chapter Building Reports
|
||
|
||
@menu
|
||
* Introduction::
|
||
* Balance Reports::
|
||
* 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 controlls
|
||
how it is displayed. The combinations are infinite. This chapter will
|
||
show you the basics of combining varous options and commands. In the next
|
||
chapters you will find details about the specific commands and
|
||
options.
|
||
|
||
@node Balance Reports, Advanced Reports, 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 you 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
|
||
morepossibilities.
|
||
|
||
@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 Advanced Reports, , Balance Reports, Building Reports
|
||
@section Advanced Reports
|
||
|
||
@menu
|
||
* Asset Allocation::
|
||
@end menu
|
||
|
||
@node Asset Allocation, , 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
|
||
|
||
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} format their
|
||
ratio as a percentage. The fourth line tells ledger to display the
|
||
current market value of the the line.
|
||
|
||
|
||
|
||
|
||
@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
|
||
* balance::
|
||
* equity::
|
||
* register::
|
||
* print::
|
||
@end menu
|
||
|
||
@node balance, equity, Primary Financial Reports, Primary Financial Reports
|
||
@subsection balance
|
||
|
||
The @command{balance} command reports the current balance of all
|
||
accounts. It accepts a list of optional regexps, which confine the
|
||
balance report to the matching accounts. If an account contains
|
||
multiple types of commodities, each commodity's total is reported
|
||
separately.
|
||
@node equity, register, balance, Primary Financial Reports
|
||
@subsection equity
|
||
|
||
The @command{equity} command prints out accounts balances as if they
|
||
were transactions. This makes it easy to establish the starting balances
|
||
for an account, such as when @ref{Archiving Previous Years}.
|
||
|
||
|
||
@menu
|
||
* register::
|
||
* print::
|
||
@end menu
|
||
|
||
@node register, print, equity, Primary Financial Reports
|
||
@subsection register
|
||
|
||
The @command{register} command displays all the postings occurring
|
||
in a single account, line by line. The account regexp must be
|
||
specified as the only argument to this command. If any regexps occur
|
||
after the required account name, the register will contain only those
|
||
postings that match. Very useful for hunting down a particular
|
||
posting.
|
||
|
||
The output from @command{register} is very close to what a typical
|
||
checkbook, or single-account ledger, would look like. It also shows a
|
||
running balance. The final running balance of any register should
|
||
always be the same as the current balance of that account.
|
||
|
||
If you have Gnuplot installed, you may plot the amount or running
|
||
total of any register by using the script @file{report}, which is
|
||
included in the Ledger distribution. The only requirement is that you
|
||
add either @option{-j} or @option{-J} to your register command, in
|
||
order to plot either the amount or total column, respectively.
|
||
|
||
@node print, , register, Primary Financial Reports
|
||
@subsection print
|
||
|
||
The @command{print} command prints out ledger transactions in a textual
|
||
format that can be parsed by Ledger. They will be properly formatted,
|
||
and output in the most economic form possible. The ``print'' command
|
||
also takes a list of optional regexps, which will cause only those
|
||
postings which match in some way to be printed.
|
||
|
||
The @command{print} command can be a handy way to clean up a ledger
|
||
file whose formatting has gotten out of hand.
|
||
|
||
|
||
@node Reports in other formats, Reports about your Journals, Primary Financial Reports, Reporting Commands
|
||
@section Reports in other formats
|
||
@menu
|
||
* csv::
|
||
* emacs::
|
||
* org::
|
||
* pricemap::
|
||
* xml::
|
||
* prices and pricedb::
|
||
@end menu
|
||
|
||
@node csv, emacs, Reports in other formats, Reports in other formats
|
||
@subsection csv
|
||
|
||
@node emacs, org, csv, Reports in other formats
|
||
@subsection emacs
|
||
|
||
The @command{emacs} command outputs results in a form that can be read
|
||
directly by Emacs Lisp. The format of the sexp is:
|
||
|
||
@smallexample
|
||
((BEG-POS CLEARED DATE CODE PAYEE
|
||
(ACCOUNT AMOUNT)...) ; list of postings
|
||
...) ; list of transactions
|
||
@end smallexample
|
||
|
||
@node org, pricemap, emacs, Reports in other formats
|
||
@subsection org
|
||
The @code{org} command produces a journal file suitable for use in the
|
||
emacs org mode. More details on using org mode can be found at
|
||
@url{http://www.orgmode.org}.
|
||
|
||
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).
|
||
|
||
|
||
@subsubsection Using Ledger for Accounting in 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.
|
||
|
||
@unnumberedsubsubsec Getting Started
|
||
|
||
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.
|
||
|
||
@unnumberedsubsubsec 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
|
||
#+srcname: 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.
|
||
|
||
@unnumberedsubsubsec 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:
|
||
@unnumberedsubsubsec 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
|
||
#+srcname: 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
|
||
@unnumberedsubsubsec 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
|
||
#+srcname: 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
|
||
|
||
@unnumberedsubsubsec 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.
|
||
@unnumberedsubsubsec 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
|
||
#+srcname: 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
|
||
@unnumberedsubsubsec 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
|
||
#+srcname: 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
|
||
#+srcname: 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
|
||
|
||
@unnumberedsubsubsec 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 integrations with a ledger.
|
||
|
||
@node pricemap, xml, org, Reports in other formats
|
||
@subsection pricemap
|
||
|
||
@node xml, prices and pricedb, pricemap, Reports in other formats
|
||
@subsection xml
|
||
|
||
By default, Ledger uses a human-readable data format, and displays its
|
||
reports in a manner meant to be read on screen. For the purpose of
|
||
writing tools which use Ledger, however, it is possible to read and
|
||
display data using XML. This section documents that format.
|
||
|
||
The general format used for Ledger data is:
|
||
|
||
@smallexample
|
||
<?xml version="1.0"?>
|
||
<ledger>
|
||
<xact>...</xact>
|
||
<xact>...</xact>
|
||
<xact>...</xact>...
|
||
</ledger>
|
||
@end smallexample
|
||
|
||
The data stream is enclosed in a @samp{ledger} tag, which contains a
|
||
series of one or more transactions. Each @samp{xact} describes the transaction
|
||
and contains a series of one or more postings:
|
||
|
||
@smallexample
|
||
<xact>
|
||
<en:date>2004/03/01</en:date>
|
||
<en:cleared/>
|
||
<en:code>100</en:code>
|
||
<en:payee>John Wiegley</en:payee>
|
||
<en:postings>
|
||
<posting>...</posting>
|
||
<posting>...</posting>
|
||
<posting>...</posting>...
|
||
</en:postings>
|
||
</xact>
|
||
@end smallexample
|
||
|
||
The date format for @samp{en:date} is always @samp{YYYY/MM/DD}. The
|
||
@samp{en:cleared} tag is optional, and indicates whether the
|
||
posting has been cleared or not. There is also an
|
||
@samp{en:pending} tag, for marking pending postings. The
|
||
@samp{en:code} and @samp{en:payee} tags both contain whatever text the
|
||
user wishes.
|
||
|
||
After the initial transaction data, there must follow a set of postings
|
||
marked with @samp{en:postings}. Typically these postings will
|
||
all balance each other, but if not they will be automatically balanced
|
||
into an account named @samp{<Unknown>}.
|
||
|
||
Within the @samp{en:postings} tag is a series of one or more
|
||
@samp{posting}'s, which have the following form:
|
||
|
||
@smallexample
|
||
<posting>
|
||
<tr:account>Expenses:Computer:Hardware</tr:account>
|
||
<tr:amount>
|
||
<value type="amount">
|
||
<amount>
|
||
<commodity flags="PT">$</commodity>
|
||
<quantity>90.00</quantity>
|
||
</amount>
|
||
</value>
|
||
</tr:amount>
|
||
</posting>
|
||
@end smallexample
|
||
|
||
This is a basic posting. It may also be begin with
|
||
@samp{tr:virtual} and/or @samp{tr:generated} tags, to indicate virtual
|
||
and auto-generated postings. Then follows the @samp{tr:account}
|
||
tag, which contains the full name of the account the posting is
|
||
related to. Colons separate parent from child in an account name.
|
||
|
||
Lastly follows the amount of the posting, indicated by
|
||
@samp{tr:amount}. Within this tag is a @samp{value} tag, of which
|
||
there are four different kinds, each with its own format:
|
||
|
||
@enumerate
|
||
@item boolean
|
||
@item integer
|
||
@item amount
|
||
@item balance
|
||
@end enumerate
|
||
|
||
The format of a boolean value is @samp{true} or @samp{false}
|
||
surrounded by a @samp{boolean} tag, for example:
|
||
|
||
@smallexample
|
||
<boolean>true</boolean>
|
||
@end smallexample
|
||
|
||
The format of an integer value is the numerical value surrounded by an
|
||
@samp{integer} tag, for example:
|
||
|
||
@smallexample
|
||
<integer>12036</integer>
|
||
@end smallexample
|
||
|
||
The format of an amount contains two members, the commodity and the
|
||
quantity. The commodity can have a set of flags that indicate how to
|
||
display it. The meaning of the flags (all of which are optional) are:
|
||
|
||
@table @strong
|
||
@item P
|
||
The commodity is prefixed to the value.
|
||
@item S
|
||
The commodity is separated from the value by a space.
|
||
@item T
|
||
Thousands markers are used to display the amount.
|
||
@item E
|
||
The format of the amount is European, with period used as a thousands
|
||
marker, and comma used as the decimal point.
|
||
@end table
|
||
|
||
The actual quantity for an amount is an integer of arbitrary size.
|
||
Ledger uses the GNU multi-precision math library to handle such
|
||
values. The XML format assumes the reader to be equally capable.
|
||
Here is an example amount:
|
||
|
||
@smallexample
|
||
<value type="amount">
|
||
<amount>
|
||
<commodity flags="PT">$</commodity>
|
||
<quantity>90.00</quantity>
|
||
</amount>
|
||
</value>
|
||
@end smallexample
|
||
|
||
Lastly, a balance value contains a series of amounts, each with a
|
||
different commodity. Unlike the name, such a value does need to
|
||
balance. It is called a balance because it sums several amounts. For
|
||
example:
|
||
|
||
@smallexample
|
||
<value type="balance">
|
||
<balance>
|
||
<amount>
|
||
<commodity flags="PT">$</commodity>
|
||
<quantity>90.00</quantity>
|
||
</amount>
|
||
<amount>
|
||
<commodity flags="TE">DM</commodity>
|
||
<quantity>200.00</quantity>
|
||
</amount>
|
||
</balance>
|
||
</value>
|
||
@end smallexample
|
||
|
||
That is the extent of the XML data format used by Ledger. It will
|
||
output such data if the @command{xml} command is used, and can read
|
||
the same data.
|
||
|
||
|
||
@node prices and pricedb, , xml, Reports in other formats
|
||
@subsection prices and pricedb
|
||
|
||
The @command{prices} command displays the price history for matching
|
||
commodities. The @option{-A} flag is useful with this report, to
|
||
display the running average price, or @option{-D} to show each price's
|
||
deviation from that average.
|
||
|
||
There is also a @command{pricedb} command which outputs the same
|
||
information as @command{prices}, but does in a format that can be parsed
|
||
by Ledger. This is useful for generating and tidying up pricedb
|
||
databasefiles.
|
||
|
||
|
||
@node Reports about your Journals, Developer Commands, Reports in other formats, Reporting Commands
|
||
@section Reports about your Journals
|
||
|
||
@menu
|
||
* accounts::
|
||
* convert::
|
||
* commodities::
|
||
* entry and xact::
|
||
* payees::
|
||
@end menu
|
||
|
||
@node accounts, convert, Reports about your Journals, Reports about your Journals
|
||
@subsection accounts
|
||
|
||
The @command{accounts} reports all of the accounts in the journal.
|
||
Following the command with a regular expression will limit the output to
|
||
accounts matching the regex.
|
||
|
||
|
||
@node convert, commodities, accounts, Reports about your Journals
|
||
@subsection convert
|
||
|
||
@node commodities, entry and xact, convert, Reports about your Journals
|
||
@subsection commodities
|
||
Report all commodities present in the journals under consideration.
|
||
|
||
|
||
@node entry and xact, payees, commodities, Reports about your Journals
|
||
@subsection entry and xact
|
||
|
||
The @code{entry} and @command{xact} commands simplify the creation of
|
||
new transactions. It works on the principle that 80% of all postings
|
||
are variants of earlier postings. Here's how it works:
|
||
|
||
Say you currently have this posting in your ledger file:
|
||
|
||
@smallexample
|
||
2004/03/15 * Viva Italiano
|
||
Expenses:Food $12.45
|
||
Expenses:Tips $2.55
|
||
Liabilities:MasterCard $-15.00
|
||
@end smallexample
|
||
|
||
Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva
|
||
Italiano} again. The exact amounts are different, but the overall
|
||
form is the same. With the @command{xact} command you can type:
|
||
|
||
@smallexample
|
||
ledger entry 2004/4/9 viva food 11 tips 2.50
|
||
@end smallexample
|
||
|
||
This produces the following output:
|
||
|
||
@smallexample
|
||
2004/04/09 Viva Italiano
|
||
Expenses:Food $11.00
|
||
Expenses:Tips $2.50
|
||
Liabilities:MasterCard $-13.50
|
||
@end smallexample
|
||
|
||
It works by finding a past posting matching the regular expression
|
||
@samp{viva}, and assuming that any accounts or amounts specified will
|
||
be similar to that earlier posting. If Ledger does not succeed in
|
||
generating a new transaction, an error is printed and the exit code is set
|
||
to @samp{1}.
|
||
|
||
Here are a few more examples of the @command{xact} command, assuming
|
||
the above journal transaction:
|
||
|
||
@smallexample
|
||
ledger entry 4/9 viva 11.50
|
||
ledger entry 4/9 viva 11.50 checking # (from `checking')
|
||
ledger entry 4/9 viva food 11.50 tips 8
|
||
ledger xact 4/9 viva food 11.50 tips 8 cash
|
||
ledger xact 4/9 viva food $11.50 tips $8 cash
|
||
ledger xact 4/9 viva dining "DM 11.50"
|
||
@end smallexample
|
||
|
||
@command{xact} is identical to @command{entry} and is provide for
|
||
backwards compatibility with Ledger 2.X.
|
||
|
||
@node payees, , entry and xact, Reports about your Journals
|
||
@subsection payees
|
||
The @command{payees} reports all of the unique payees in the journal. To filter the payes displayed you must use the @@ prefix:
|
||
@smallexample
|
||
macbook-2:$ ledger payees '@@Tar.+t'
|
||
El Dorade Restaraunt
|
||
My Big Fat Greek Restaraunt
|
||
Target
|
||
macbook-2:$
|
||
@end smallexample
|
||
|
||
|
||
|
||
|
||
@node Developer Commands, , Reports about your Journals, Reporting Commands
|
||
@section Developer Commands
|
||
@menu
|
||
* echo::
|
||
* reload::
|
||
* source::
|
||
* Pre-commands::
|
||
@end menu
|
||
|
||
@node echo, reload, Developer Commands, Developer Commands
|
||
@subsection echo
|
||
This command simply echos its argument back to the output.
|
||
|
||
|
||
@node reload, source, echo, Developer Commands
|
||
@subsection reload
|
||
Forces ledger to reload any journal files. This function exists to
|
||
support external programs controlling a running ledger process and does
|
||
nothing for a command line user.
|
||
|
||
@node source, Pre-commands, reload, Developer Commands
|
||
@subsection source
|
||
|
||
@node Pre-commands, , source, Developer Commands
|
||
@subsection Pre-Commands
|
||
@table @code
|
||
@item args
|
||
@item eval
|
||
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
|
||
@item query
|
||
@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
|
||
* Scope of Ledger Options::
|
||
* Global Options::
|
||
* Report Options::
|
||
* Session Options::
|
||
* Report Filtering::
|
||
* Search Terms::
|
||
* Output Customization::
|
||
* Commodity Reporting::
|
||
* Environment Variables::
|
||
@end menu
|
||
|
||
@node Scope of Ledger Options, Global Options, Detailed Options Description, Detailed Options Description
|
||
@subsection Scope of Ledger Options
|
||
|
||
Options for Ledger report affec tthree separate scopes of operation:
|
||
Global, Session, and Report. In practice there is very little
|
||
defference 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.
|
||
|
||
@node Global Options, Report Options, Scope of Ledger Options, Detailed Options Description
|
||
@subsection Global Options
|
||
|
||
@option{--args_only} Ignore all environment and init-file settings and
|
||
use only command-line arguments to control Ledger. Usefule for debugs
|
||
or testing small Journal files not assoviated with you main financial
|
||
database.
|
||
|
||
@option{debug "argument"} If Ledger has been built with debug options this will provide extra data during the run. The following are the avilable arguments to debug: @code{
|
||
account.display
|
||
accounts.sorted
|
||
amount.convert
|
||
amount.is_zero
|
||
amount.parse
|
||
amount.price
|
||
amount.truncate
|
||
amount.unround
|
||
amounts.commodities
|
||
amounts.refs
|
||
archive.journal
|
||
auto.columns
|
||
budget.generate
|
||
commodity.annotated.strip
|
||
commodity.annotations
|
||
commodity.compare
|
||
commodity.download
|
||
commodity.prices.add
|
||
commodity.prices.find
|
||
convert.csv
|
||
csv.mappings
|
||
csv.parse
|
||
draft.xact
|
||
expr.calc
|
||
expr.calc.when
|
||
expr.compile
|
||
filters.changed_value
|
||
filters.changed_value.rounding
|
||
filters.collapse
|
||
filters.forecast
|
||
filters.revalued
|
||
format.abbrev
|
||
format.expr
|
||
generate.post
|
||
generate.post.string
|
||
item.meta
|
||
ledger.read
|
||
ledger.validate
|
||
lookup
|
||
lookup.account
|
||
mask.match
|
||
memory.counts
|
||
memory.counts.live
|
||
memory.debug
|
||
op.cons
|
||
op.memory
|
||
option.args
|
||
option.names
|
||
org.next_amount
|
||
org.next_total
|
||
parser.error
|
||
pool.commodities
|
||
post.assign
|
||
python.init
|
||
python.interp
|
||
query.mask
|
||
report.predicate
|
||
scope.symbols
|
||
textual.include
|
||
textual.parse
|
||
timelog
|
||
times.epoch
|
||
times.interval
|
||
times.parse
|
||
value.sort
|
||
value.storage.refcount
|
||
xact.extend
|
||
xact.extend.cleared
|
||
xact.extend.fail
|
||
xact.finalize}
|
||
|
||
@option{full_help}
|
||
Displays the man page for ledger.
|
||
|
||
@option{help_calc}
|
||
Displays the man page for ledger.
|
||
|
||
@option{help_comm}
|
||
Displays the man page for ledger.
|
||
|
||
@option{help_disp}
|
||
Displays the man page for ledger.
|
||
|
||
@option{help}
|
||
Displays the man page for ledger.
|
||
|
||
@option{init_file PATH_TO_INIT_FILE}
|
||
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
|
||
|
||
@option{script PATH_TO_SCRIPT}
|
||
Excute a ledger script.
|
||
|
||
@option{trace INTEGER_TRACE_LEVEL}
|
||
Enable tracing. The integer specifies the level of trace desired: LOG_OFF = 0,
|
||
LOG_CRIT,
|
||
LOG_FATAL,
|
||
LOG_ASSERT,
|
||
LOG_ERROR,
|
||
LOG_VERIFY,
|
||
LOG_WARN,
|
||
LOG_INFO,
|
||
LOG_EXCEPT,
|
||
LOG_DEBUG,
|
||
LOG_TRACE,
|
||
LOG_ALL
|
||
|
||
@option{verbose}
|
||
Print detail information on the execution of Ledger.
|
||
|
||
@option{verify}
|
||
FIX THIS ENTRY
|
||
|
||
@option{version}
|
||
|
||
@node Session Options, Report Filtering, Report Options, Detailed Options Description
|
||
@subsection Session Options
|
||
|
||
@option{cache}
|
||
FIX THIS ENTRY
|
||
|
||
@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 getquote script.
|
||
|
||
@option{file}
|
||
Specify the input file for this invocation.
|
||
|
||
@option{input_date_format}
|
||
Specify the date format for journal entries.
|
||
|
||
@option{master_account}
|
||
FIX THIS ENTRY
|
||
|
||
@option{price_db}
|
||
Specify the price entry data file.
|
||
|
||
@option{price_exp INTEGER_MINUTES} Set the expected freshness of price
|
||
quotes, in min- utes. 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}
|
||
FIX THIS ENTRY
|
||
|
||
@node Report Options, Session Options, Global Options, Detailed Options Description
|
||
@subsection Report Options
|
||
|
||
@option{abbrev_len}
|
||
FIX THIS ENTRY
|
||
|
||
@option{account}
|
||
FIX THIS ENTRY
|
||
|
||
@option{account_width}
|
||
FIX THIS ENTRY
|
||
|
||
@option{actual_dates}
|
||
FIX THIS ENTRY
|
||
|
||
@option{actual}
|
||
FIX THIS ENTRY
|
||
|
||
@option{add_budget}
|
||
FIX THIS ENTRY
|
||
|
||
@option{amount_data}
|
||
FIX THIS ENTRY
|
||
|
||
@option{amount}
|
||
FIX THIS ENTRY
|
||
|
||
@option{amount_width}
|
||
FIX THIS ENTRY
|
||
|
||
@option{anon}
|
||
FIX THIS ENTRY
|
||
|
||
@option{average}
|
||
FIX THIS ENTRY
|
||
|
||
@option{balance_format}
|
||
FIX THIS ENTRY
|
||
|
||
@option{base}
|
||
FIX THIS ENTRY
|
||
|
||
@option{basis}
|
||
FIX THIS ENTRY
|
||
|
||
@option{begin}
|
||
FIX THIS ENTRY
|
||
|
||
@option{bold_if}
|
||
FIX THIS ENTRY
|
||
|
||
@option{budget_format}
|
||
FIX THIS ENTRY
|
||
|
||
@option{budget}
|
||
FIX THIS ENTRY
|
||
|
||
@option{by_payee}
|
||
FIX THIS ENTRY
|
||
|
||
@option{cleared_format}
|
||
FIX THIS ENTRY
|
||
|
||
@option{cleared}
|
||
FIX THIS ENTRY
|
||
|
||
@option{collapse_if_zero}
|
||
FIX THIS ENTRY
|
||
|
||
@option{collapse}
|
||
FIX THIS ENTRY
|
||
|
||
@option{color}
|
||
FIX THIS ENTRY
|
||
|
||
@option{columns}
|
||
FIX THIS ENTRY
|
||
|
||
@option{count}
|
||
FIX THIS ENTRY
|
||
|
||
@option{csv_format}
|
||
FIX THIS ENTRY
|
||
|
||
@option{current}
|
||
FIX THIS ENTRY
|
||
|
||
@option{daily}
|
||
FIX THIS ENTRY
|
||
|
||
@option{date_format}
|
||
FIX THIS ENTRY
|
||
|
||
@option{date}
|
||
FIX THIS ENTRY
|
||
|
||
@option{date_width}
|
||
FIX THIS ENTRY
|
||
|
||
@option{datetime_format}
|
||
FIX THIS ENTRY
|
||
|
||
@option{depth}
|
||
FIX THIS ENTRY
|
||
|
||
@option{deviation}
|
||
FIX THIS ENTRY
|
||
|
||
@option{display_amount}
|
||
FIX THIS ENTRY
|
||
|
||
@option{display}
|
||
FIX THIS ENTRY
|
||
|
||
@option{display_total}
|
||
FIX THIS ENTRY
|
||
|
||
@option{dow}
|
||
FIX THIS ENTRY
|
||
|
||
@option{effective}
|
||
FIX THIS ENTRY
|
||
|
||
@option{empty}
|
||
FIX THIS ENTRY
|
||
|
||
@option{end}
|
||
FIX THIS ENTRY
|
||
|
||
@option{equity}
|
||
FIX THIS ENTRY
|
||
|
||
@option{exact}
|
||
FIX THIS ENTRY
|
||
|
||
@option{exchange}
|
||
FIX THIS ENTRY
|
||
|
||
@option{flat}
|
||
FIX THIS ENTRY
|
||
|
||
@option{force_color}
|
||
FIX THIS ENTRY
|
||
|
||
@option{force_pager}
|
||
FIX THIS ENTRY
|
||
|
||
@option{forecast_while}
|
||
FIX THIS ENTRY
|
||
|
||
@option{forecast_years}
|
||
FIX THIS ENTRY
|
||
|
||
@option{format}
|
||
FIX THIS ENTRY
|
||
|
||
@option{gain}
|
||
FIX THIS ENTRY
|
||
|
||
@option{generated}
|
||
FIX THIS ENTRY
|
||
|
||
@option{group_by}
|
||
FIX THIS ENTRY
|
||
|
||
@option{group_title_format}
|
||
FIX THIS ENTRY
|
||
|
||
@option{head}
|
||
FIX THIS ENTRY
|
||
|
||
@option{inject}
|
||
FIX THIS ENTRY
|
||
|
||
@option{invert}
|
||
FIX THIS ENTRY
|
||
|
||
@option{limit}
|
||
FIX THIS ENTRY
|
||
|
||
@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}
|
||
FIX THIS ENTRY
|
||
|
||
@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}
|
||
FIX THIS ENTRY
|
||
|
||
@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}
|
||
FIX THIS ENTRY
|
||
|
||
@option{register_format}
|
||
FIX THIS ENTRY
|
||
|
||
@option{related_all}
|
||
FIX THIS ENTRY
|
||
|
||
@option{related}
|
||
FIX THIS ENTRY
|
||
|
||
@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}
|
||
FIX THIS ENTRY
|
||
|
||
@option{sort_xacts}
|
||
FIX THIS ENTRY
|
||
|
||
@option{start_of_week}
|
||
FIX THIS ENTRY
|
||
|
||
@option{subtotal}
|
||
FIX THIS ENTRY
|
||
|
||
@option{tail}
|
||
FIX THIS ENTRY
|
||
|
||
@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}
|
||
FIX THIS ENTRY
|
||
|
||
@option{wide}
|
||
FIX THIS ENTRY
|
||
|
||
@option{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, Session 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 asterix to the right of the
|
||
date).
|
||
|
||
@option{--uncleared} (@option{-U}) displays only postings whose
|
||
transaction has not been marked ``cleared'' (i.e., if there is no asterix to
|
||
the right of the date).
|
||
|
||
@option{--real} (@option{-R}) displays only real postings, not virtual.
|
||
(A virtual posting is indicated by surrounding the account name with
|
||
parentheses or brackets; see @ref{Virtual Transactions} for more
|
||
information).
|
||
|
||
@option{--actual} (@option{-L}) displays only actual postings, and
|
||
not those created due to automated postings.
|
||
|
||
@option{--related} (@option{-r}) displays postings that are
|
||
related to whichever postings would otherwise have matched the
|
||
filtering criteria. In the register report, this shows where money
|
||
went to, or the account it came from. In the balance report, it shows
|
||
all the accounts affected by transactions having a related posting.
|
||
For example, if a file had this transaction:
|
||
|
||
@smallexample
|
||
2004/03/20 Safeway
|
||
Expenses:Food $65.00
|
||
Expenses:Cash $20.00
|
||
Assets:Checking $-85.00
|
||
@end smallexample
|
||
|
||
And the register command was:
|
||
|
||
@smallexample
|
||
ledger -r register food
|
||
@end smallexample
|
||
|
||
The following would be output, showing the postings related to the
|
||
posting that matched:
|
||
|
||
@smallexample
|
||
2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00
|
||
Assets:Checking $85.00 $65.00
|
||
@end smallexample
|
||
|
||
@option{--budget} is useful for displaying how close your postings
|
||
meet your budget. @option{--add-budget} also shows unbudgeted
|
||
postings, while @option{--unbudgeted} shows only those.
|
||
@option{--forecast} is a related option that projects your budget into
|
||
the future, showing how it will affect future balances.
|
||
@xref{Budgeting and Forecasting}.
|
||
|
||
@option{--limit EXPR} (@option{-l EXPR}) limits which postings
|
||
take part in the calculations of a report.
|
||
|
||
@option{--amount EXPR} (@option{-t EXPR}) changes the value expression
|
||
used to calculate the ``value'' column in the @command{register}
|
||
report, the amount used to calculate account totals in the
|
||
@command{balance} report, and the values printed in the
|
||
@command{equity} report. @xref{Value Expressions}.
|
||
|
||
@option{--total EXPR} (@option{-T EXPR}) sets the value expression
|
||
used for the ``totals'' column in the @command{register} and
|
||
@command{balance} reports.
|
||
|
||
@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{--comm-as-payee} (@option{-x}) changes the payee of every
|
||
posting to be the commodity used in that posting. This can be
|
||
useful when combined with other options, such as @option{-s}.
|
||
|
||
@option{--empty} (@option{-E}) includes even empty accounts in the
|
||
@command{balance} report.
|
||
|
||
@option{--weekly} (@option{-W}) reports posting totals by the
|
||
week. The week begins on whichever day of the week begins the month
|
||
containing that posting. To set a specific begin date, use a
|
||
period string, such as @samp{weekly from DATE}. @option{--monthly}
|
||
(@option{-M}) reports posting totals by month; @option{--yearly}
|
||
(@option{-Y}) reports posting totals by year. For more complex
|
||
period, using the @option{--period} option described above.
|
||
|
||
@option{--dow} reports postings totals for each day of the week.
|
||
This is an easy way to see if weekend spending is more than on
|
||
weekdays.
|
||
|
||
@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing
|
||
the values determined using the value expression @var{EXPR}. For
|
||
example, using @option{-S -UT} in the balance report will sort account
|
||
balances from greatest to least, using the absolute value of the
|
||
total. For more on how to use value expressions, see @ref{Value
|
||
Expressions}.
|
||
|
||
@option{--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 startup, to
|
||
determine historical prices. Other settings can be placed in this
|
||
file manually, to prevent downloading quotes for a specific, for
|
||
example. This is done by adding a line like the following:
|
||
|
||
@smallexample
|
||
; Don't download quotes for the dollar, or timelog values
|
||
N $
|
||
N h
|
||
@end smallexample
|
||
|
||
@option{--price-exp MINS} (@option{-L MINS}) sets the expected
|
||
freshness of price quotes, in minutes. That is, if the last known
|
||
quote for any commodity is older than this value---and if
|
||
@option{--download} is being used---then the Internet will be
|
||
consulted again for a newer price. Otherwise, the old price is still
|
||
considered to be fresh enough.
|
||
|
||
@option{--download} (@option{-Q}) causes quotes to be automagically
|
||
downloaded, as needed, by running a script named @command{getquote}
|
||
and expecting that script to return a value understood by ledger. A
|
||
sample implementation of a @command{getquote} script, implemented in
|
||
Perl, is provided in the distribution. Downloaded quote price are
|
||
then appended to the price database, usually specified using the
|
||
environment variable @env{LEDGER_PRICE_DB}.
|
||
|
||
There are several different ways that ledger can report the totals it
|
||
displays. The most flexible way to adjust them is by using value
|
||
expressions, and the @option{-t} and @option{-T} options. However,
|
||
there are also several ``default'' reports, which will satisfy most
|
||
users basic reporting needs:
|
||
|
||
@table @code
|
||
@item -O, --quantity
|
||
Reports commodity totals (this is the default)
|
||
|
||
@item -B, --basis
|
||
Reports the cost basis for all postings.
|
||
|
||
@item -V, --market
|
||
Reports the last known market value for all commodities.
|
||
|
||
@item -G --gain
|
||
Reports the net gain/loss for all commodities in the report that have
|
||
a price history.
|
||
@end table
|
||
|
||
|
||
Often you will be more interested in the value of your entire holdings,
|
||
in your preferred currency. It might be nice to know you hold 10,000
|
||
shares of PENNY, but you are more interested in whether or not that is
|
||
worth $1000.00 or $10,000.00. However, the current day value of a
|
||
commodity can mean different things to different people, depending on
|
||
the accounts involved, the commodities, the nature of the transactions,
|
||
etc.
|
||
|
||
When you specify @samp{-V}, or @samp{-X COMM}, you are requesting that
|
||
some or all of the commodities be valuated as of today (or whatever
|
||
@samp{--now} is set to). But what does such a valuation mean? This
|
||
meaning is governed by the presence of a @samp{VALUE} metadata property,
|
||
whose content is an expression used to compute that value.
|
||
|
||
If no VALUE property is specified, each posting is assumed to have a
|
||
default, as if you'd specified a global, automated transaction as
|
||
follows:
|
||
|
||
@smallexample
|
||
= expr true
|
||
; VALUE:: market(amount, date, exchange)
|
||
@end smallexample
|
||
This definition emulates the present day behavior of @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 metadata:
|
||
|
||
@smallexample
|
||
2010-12-26 Example
|
||
Expenses:Food $20
|
||
; Just to be silly, always valuate *these* $20 as 30 DM, no matter what
|
||
; the user asks for with -V or -X
|
||
; VALUE:: 30 DM
|
||
Assets:Cash
|
||
@end smallexample
|
||
|
||
This example demonstrates that your VALUE expression should be as
|
||
symbolic as possible, using terms like 'amount' and 'date', rather than
|
||
specific amounts and dates. Also, you should pass the amount along to
|
||
the function 'market' so it can be further revalued if the user has
|
||
asked for a specific currency.
|
||
|
||
Or, if it better suits your accounting, you can be less symbolic, which
|
||
allows you to report most everything in EUR if you use -X EUR, except
|
||
for certain accounts or postings which should always be valuated in
|
||
another currency. For example:
|
||
|
||
@smallexample
|
||
= /^Assets:Brokerage:CAD$/
|
||
; Always report the value of commodities in this account in
|
||
; terms of present day dollars, despite what was asked for
|
||
; on the command-line VALUE:: market(amount, date, '$')
|
||
@end smallexample
|
||
|
||
@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.
|
||
|
||
|
||
@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 unbudgeted expenses
|
||
using @option{--unbudgeted}:
|
||
|
||
@example
|
||
ledger --unbudgeted --monthly register ^expenses
|
||
@end example
|
||
|
||
You can also use these flags with the @command{balance} command.
|
||
|
||
@node Forecasting, , Budgeting, Budgeting and Forecasting
|
||
@section Forecasting
|
||
|
||
Sometimes it's useful to know what your finances will look like in the
|
||
future, such as determining when an account will reach zero. Ledger
|
||
makes this easy to do, using the same period transactions as are used for
|
||
budgeting. An example forecast report can be generated with:
|
||
|
||
@example
|
||
ledger --forecast "T>@{\$-500.00@}" register ^assets ^liabilities
|
||
@end example
|
||
|
||
This report continues outputting postings until the running total
|
||
is greater than $-500.00. A final posting is always output, to
|
||
show you what the total afterwards would be.
|
||
|
||
Forecasting can also be used with the balance report, but by date
|
||
only, and not against the running total:
|
||
|
||
@example
|
||
ledger --forecast "d<[2010]" bal ^assets ^liabilities
|
||
@end example
|
||
|
||
|
||
@node Value Expressions, Format Strings, Budgeting and Forecasting, Top
|
||
@chapter Value Expressions
|
||
|
||
Value expressions are an expression language used by Ledger to
|
||
calculate values used by the program for many different purposes:
|
||
|
||
@enumerate
|
||
@item
|
||
The values displayed in reports
|
||
@item
|
||
For predicates (where truth is anything non-zero), to determine which
|
||
postings are calculated (@option{-l}) or displayed (@option{-d}).
|
||
@item
|
||
For sorting criteria, to yield the sort key.
|
||
@item
|
||
In the matching criteria used by automated postings.
|
||
@end enumerate
|
||
|
||
Value expressions support most simple math and logic operators, in
|
||
addition to a set of one letter functions and variables. A function's
|
||
argument is whatever follows it. The following is a display predicate
|
||
that I use with the @command{balance} command:
|
||
|
||
@smallexample
|
||
ledger -d /^Liabilities/?T<0:UT>100 balance
|
||
@end smallexample
|
||
|
||
The effect is that account totals are displayed only if: 1) A
|
||
Liabilities account has a total less than zero; or 2) the absolute
|
||
value of the account's total exceeds 100 units of whatever commodity
|
||
contains. If it contains multiple commodities, only one of them must
|
||
exceed 100 units.
|
||
|
||
Display predicates are also very handy with register reports, to
|
||
constrain which transactions are printed. For example, the following
|
||
command shows only transactions from the beginning of the current month,
|
||
while still calculating the running balance based on all transactions:
|
||
|
||
@smallexample
|
||
ledger -d "d>[this month]" register checking
|
||
@end smallexample
|
||
|
||
This advantage to this command's complexity is that it prints the
|
||
running total in terms of all transactions in the register. The following,
|
||
simpler command is similar, but totals only the displayed
|
||
postings:
|
||
|
||
@smallexample
|
||
ledger -b "this month" register checking
|
||
@end smallexample
|
||
|
||
@menu
|
||
* Variables::
|
||
* 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, Journal File Format, Value Expressions, Top
|
||
@chapter Format Strings
|
||
|
||
@menu
|
||
* Basics::
|
||
* Format Expressions::
|
||
* --balance-format::
|
||
* New formatting codes::
|
||
@end menu
|
||
|
||
@node Basics, Format Expressions, Format Strings, Format Strings
|
||
@section Format String Basics
|
||
Format strings may be used to change the output format of reports.
|
||
They are specified by passing a formatting string to the
|
||
@option{--format} (@option{-F}) option. Within that string,
|
||
constructs are allowed which make it possible to display the various
|
||
parts of an account or posting in custom ways.
|
||
|
||
Within a format string, a substitution is specified using a percent
|
||
character (@samp{%}). The basic format of all substitutions is:
|
||
|
||
@smallexample
|
||
%[-][MIN WIDTH][.MAX WIDTH](VALEXPR)
|
||
@end smallexample
|
||
|
||
If the optional minus sign (@samp{-}) follows the percent character,
|
||
whatever is substituted will be left justified. The default is right
|
||
justified. If a minimum width is given next, the substituted text
|
||
will be at least that wide, perhaps wider. If a period and a maximum
|
||
width is given, the substituted text will never be wider than this,
|
||
and will be truncated to fit. Here are some examples:
|
||
|
||
@smallexample
|
||
%-P a transaction's payee, left justified
|
||
%20P The same, right justified, at least 20 chars wide
|
||
%.20P The same, no more than 20 chars wide
|
||
%-.20P Left justified, maximum twenty chars wide
|
||
@end smallexample
|
||
|
||
The expression following the format constraints can be a single
|
||
letter, or an expression enclosed in parentheses or brackets.
|
||
|
||
@node Format Expressions, --balance-format, Basics, Format Strings
|
||
@section Format Expressions
|
||
|
||
The
|
||
allowable expressions are:
|
||
|
||
@table @code
|
||
@item %
|
||
Inserts a percent sign.
|
||
|
||
@item t
|
||
Inserts the results of the value expression specified by @option{-t}.
|
||
If @option{-t} was not specified, the current report style's value
|
||
expression is used.
|
||
|
||
@item T
|
||
Inserts the results of the value expression specified by @option{-T}.
|
||
If @option{-T} was not specified, the current report style's value
|
||
expression is used.
|
||
|
||
@item |
|
||
Inserts a single space. This is useful if a width is specified, for
|
||
inserting a certain number of spaces.
|
||
|
||
@item _
|
||
Inserts a space for each level of an account's depth. That is, if an
|
||
account has two parents, this construct will insert two spaces. If a
|
||
minimum width is specified, that much space is inserted for each level
|
||
of depth. Thus @samp{%5_}, for an account with four parents, will
|
||
insert twenty spaces.
|
||
|
||
@item (EXPR)
|
||
Inserts the amount resulting from the value expression given in
|
||
parentheses. To insert five times the total value of an account, for
|
||
example, one could say @samp{%12(5*O)}. Note: It's important to put
|
||
the five first in that expression, so that the commodity doesn't get
|
||
stripped from the total.
|
||
|
||
@item [DATEFMT]
|
||
Inserts the result of formatting a posting's date with a date
|
||
format string, exactly like those supported by @code{strftime}. For
|
||
example: @samp{%[%Y/%m/%d %H:%M:%S]}.
|
||
|
||
@item S
|
||
Insert the pathname of the file from which the transaction's data was read.
|
||
|
||
@item B
|
||
Inserts the beginning character position of that transaction within the file.
|
||
|
||
@item b
|
||
Inserts the beginning line of that transaction within the file.
|
||
|
||
@item E
|
||
Inserts the ending character position of that transaction within the file.
|
||
|
||
@item e
|
||
Inserts the ending line of that transaction within the file.
|
||
|
||
@item D
|
||
By default, this is the same as @samp{%[%Y/%m%/d]}. The date format
|
||
used can be changed at any time with the @option{-y} flag, however.
|
||
Using @samp{%D} gives the user more control over the way dates are
|
||
output.
|
||
|
||
@item d
|
||
This is the same as the @samp{%D} option, unless the transaction has an
|
||
effective date, in which case it prints
|
||
@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}.
|
||
|
||
@item X
|
||
If a posting has been cleared, this inserts @samp{*} followed by a
|
||
space; otherwise nothing is inserted.
|
||
|
||
@item Y
|
||
This is the same as @samp{%X}, except that it only displays a state
|
||
character if all of the member postings have the same state.
|
||
|
||
@item C
|
||
Inserts the checking number for a transaction, in parentheses, followed by
|
||
a space; if none was specified, nothing is inserted.
|
||
|
||
@item P
|
||
Inserts the payee related to a posting.
|
||
|
||
@item a
|
||
Inserts the optimal short name for an account. This is normally used
|
||
in balance reports. It prints a parent account's name if that name
|
||
has not been printed yet, otherwise it just prints the account's name.
|
||
|
||
@item A
|
||
Inserts the full name of an account.
|
||
|
||
@item W
|
||
This is the same as @samp{%A}, except that it first displays the
|
||
posting's state @emph{if the transaction's posting states are not
|
||
all the same}, followed by the full account name. This is offered as
|
||
a printing optimization, so that combined with @samp{%Y}, only the
|
||
minimum amount of state detail is printed.
|
||
|
||
@item o
|
||
Inserts the ``optimized'' form of a posting's amount. This is
|
||
used by the print report. In some cases, this inserts nothing; in
|
||
others, it inserts the posting amount and its cost. It's use is
|
||
not recommend unless you are modifying the print report.
|
||
|
||
@item n
|
||
Inserts the note associated with a posting, preceded by two spaces
|
||
and a semi-colon, if it exists. Thus, no none becomes an empty
|
||
string, while the note @samp{foo} is substituted as @samp{ ; foo}.
|
||
|
||
@item N
|
||
Inserts the note associated with a posting, if one exists.
|
||
|
||
@item /
|
||
The @samp{%/} construct is special. It separates a format string
|
||
between what is printed for the first posting of a transaction, and
|
||
what is printed for all subsequent postings. If not used, the
|
||
same format string is used for all postings.
|
||
@end table
|
||
|
||
@node --balance-format, New formatting codes, Format Expressions, Format Strings
|
||
@section --balance-format
|
||
|
||
As an example of how flexible the --format strings can be, the default balance format looks like this:
|
||
|
||
@smallexample
|
||
"%(justify(scrub(display_total), 20, -1, true, color))"
|
||
" %(!options.flat ? depth_spacer : \"\")"
|
||
"%-(ansify_if(partial_account(options.flat), blue if color))\n%/"
|
||
"%$1\n%/"
|
||
"--------------------\n"
|
||
@end smallexample
|
||
|
||
@node New formatting codes, , --balance-format, Format Strings
|
||
@section New Formatting Codes
|
||
|
||
@menu
|
||
* Field Widths::
|
||
* Colors::
|
||
* Quantities and Calculations::
|
||
* Dates::
|
||
* Text Formatting::
|
||
* Misc::
|
||
@end menu
|
||
|
||
@node Field Widths, Colors, New formatting codes, New formatting codes
|
||
@subsection Field Widths
|
||
@multitable @columnfractions .3 .2 .5
|
||
@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description}
|
||
@item @code{date_width}
|
||
@item @code{payee_width}
|
||
@item @code{account_width}
|
||
@item @code{amount_width}
|
||
@item @code{total_width}
|
||
@end multitable
|
||
|
||
@node Colors, Quantities and Calculations, Field Widths, New formatting codes
|
||
@subsection Colors
|
||
|
||
The character based formatting ledger can do is limited to the ANSI terminal character colors and font highlight in a normal TTY seesion.
|
||
@multitable @columnfractions .3 .3 .3
|
||
@item @code{red} @tab @code{magenta} @tab @code{bold}
|
||
@item @code{green } @tab @code{cyan} @tab @code{underline}
|
||
@item @code{yellow } @tab @code{white} @tab @code{blink}
|
||
@item @code{blue }
|
||
@end multitable
|
||
|
||
|
||
|
||
@node Quantities and Calculations, Dates, Colors, New formatting codes
|
||
@subsection Quantities and Calcuations
|
||
|
||
|
||
|
||
@multitable @columnfractions .3 .2 .5
|
||
@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description}
|
||
@item @code{amount_expr } @tab @code{} @tab
|
||
@item @code{abs} @tab @code{U} @tab
|
||
@item @code{commodity } @tab @code{} @tab
|
||
@item @code{display_amount } @tab @code{t} @tab
|
||
@item @code{display_total } @tab @code{T} @tab
|
||
@item @code{floor } @tab @code{} @tab
|
||
@item @code{get_at } @tab @code{} @tab
|
||
@item @code{is_seq } @tab @code{} @tab
|
||
@item @code{market } @tab @code{P} @tab
|
||
@item @code{percent } @tab @code{} @tab
|
||
@item @code{price } @tab @code{} @tab
|
||
@item @code{quantity } @tab @code{} @tab
|
||
@item @code{rounded } @tab @code{} @tab
|
||
@item @code{truncated } @tab @code{} @tab
|
||
@item @code{total_expr } @tab @code{} @tab
|
||
@item @code{top_amount } @tab @code{} @tab
|
||
@item @code{to_boolean } @tab @code{} @tab
|
||
@item @code{to_int } @tab @code{} @tab
|
||
@item @code{to_amount } @tab @code{} @tab
|
||
@item @code{to_balance } @tab @code{} @tab
|
||
@item @code{unrounded } @tab @code{} @tab
|
||
@end multitable
|
||
|
||
@node Dates, Text Formatting, Quantities and Calculations, New formatting codes
|
||
@subsection Dates
|
||
|
||
@multitable @columnfractions .3 .2 .5
|
||
@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description}
|
||
@item @code{date } @tab @code{} @tab
|
||
@item @code{format_date } @tab @code{} @tab
|
||
@item @code{now } @tab @code{} @tab --> d m
|
||
@item @code{today } @tab @code{} @tab
|
||
@item @code{to_datetime } @tab @code{} @tab
|
||
@item @code{to_date } @tab @code{} @tab
|
||
@item @code{value_date } @tab @code{} @tab
|
||
@end multitable
|
||
|
||
@node Text Formatting, Misc, Dates, New formatting codes
|
||
@subsection Text Formatting
|
||
@subsubsection Summary
|
||
@multitable @columnfractions .6 .4
|
||
@item @strong{Function} @tab @strong{Description}
|
||
@item @code{ansify_if(str,color) } @tab Colorize the string
|
||
@item @code{justify(str, fwidth, lwidth, right, colorize) } @tab Right or left justify the string.
|
||
@item @code{join(str) } @tab Remove line feeds from the input string. Mainly used internaally for org-mode output
|
||
@item @code{quoted(str) } @tab Returns @code{"<str>"}.
|
||
@item @code{strip } @tab @code{Removes additional annotations from values.}
|
||
@item @code{scrub } @tab @code{S}
|
||
@item @code{should_bold } @tab @code{}
|
||
@end multitable
|
||
@subsubsection Detailed Descriptions
|
||
@table @code
|
||
@item ansify_if(value, color)
|
||
Surrounds the string representing value with ANSI codes to give it @code{color} on an TTY display. Has no effect if directed to a file.
|
||
@item justify(value, first_width, latter_width, right_justify, colorize)
|
||
Right or left justify the string representing @code{value}. The width of the field in the first line is given by @code{first_width}. For subsequent lines the width is given by @code{latterwidth}. If @code{latter_width=-1}, then @code{first_width} is use for all lines. If @code{right_justify=true} then the field is right justify within the width of the field. If it is @code{false}, then the field is left justified and padded to the full width of the field. If @code{colorize} is true then ledger will hone color settings.
|
||
@item join(str)
|
||
Replaces line feeds in str with @code{\n}.
|
||
@item quoted(str)
|
||
Return str surounded by double quotes, @code{"<str>"}.
|
||
@item strip(value)
|
||
Values can have numerous annotations, such as effective dates and lot prices. @code{strip} removes these annotations.
|
||
@end table
|
||
@node Misc, , Text Formatting, New formatting codes
|
||
@subsection Miscellaneous
|
||
@multitable @columnfractions .3 .2 .5
|
||
@item @strong{Function} @tab @strong{Abbrev.} @tab @strong{Description}
|
||
@item @code{amount_expr } @tab @code{} @tab
|
||
@item @code{abs } @tab @code{} @tab --> U
|
||
@item @code{commodity } @tab @code{} @tab
|
||
@item @code{display_amount } @tab @code{} @tab --> t
|
||
@item @code{display_total } @tab @code{} @tab --> T
|
||
@item @code{date } @tab @code{} @tab
|
||
@item @code{format_date } @tab @code{} @tab
|
||
@item @code{format } @tab @code{} @tab
|
||
@item @code{floor } @tab @code{} @tab
|
||
@item @code{get_at } @tab @code{} @tab
|
||
@item @code{is_seq } @tab @code{} @tab
|
||
@item @code{justify } @tab @code{} @tab
|
||
@item @code{join } @tab @code{} @tab
|
||
@item @code{market --> P } @tab @code{} @tab
|
||
@item @code{null } @tab @code{} @tab
|
||
@item @code{now --> d m } @tab @code{} @tab
|
||
@item @code{options } @tab @code{} @tab
|
||
@item @code{post } @tab @code{} @tab
|
||
@item @code{percent } @tab @code{} @tab
|
||
@item @code{price } @tab @code{} @tab
|
||
@item @code{print } @tab @code{} @tab
|
||
@item @code{quoted } @tab @code{} @tab
|
||
@item @code{quantity } @tab @code{} @tab
|
||
@item @code{rounded } @tab @code{} @tab
|
||
@item @code{scrub } @tab @code{} @tab
|
||
@item @code{strip --> S } @tab @code{} @tab
|
||
@item @code{should_bold } @tab @code{} @tab
|
||
@item @code{truncated } @tab @code{} @tab
|
||
@item @code{total_expr } @tab @code{} @tab
|
||
@item @code{today } @tab @code{} @tab
|
||
@item @code{top_amount } @tab @code{} @tab
|
||
@item @code{to_boolean } @tab @code{} @tab
|
||
@item @code{to_int } @tab @code{} @tab
|
||
@item @code{to_datetime } @tab @code{} @tab
|
||
@item @code{to_date } @tab @code{} @tab
|
||
@item @code{to_amount } @tab @code{} @tab
|
||
@item @code{to_balance } @tab @code{} @tab
|
||
@item @code{to_spring } @tab @code{} @tab
|
||
@item @code{to_mask } @tab @code{} @tab
|
||
@item @code{to_sequence } @tab @code{} @tab
|
||
@item @code{unrounded } @tab @code{} @tab
|
||
@item @code{value_date } @tab @code{} @tab
|
||
@end multitable
|
||
|
||
@node Journal File Format, Extending with Python, Format Strings, Top
|
||
@chapter Journal File Format for Developers
|
||
|
||
This chapter offers a complete description of the journal data format,
|
||
suitable for implementors in other languages to follow. For users,
|
||
the chapter on keeping a journal is less extensive, but more typical
|
||
of common usage (@pxref{Keeping a Journal}).
|
||
|
||
Data is collected in the form of @dfn{transactions} which occur in one
|
||
or more @dfn{journal files}. Each transaction, in turn, is made up of
|
||
one or more @dfn{postings}, which describe how @dfn{amounts} flow from
|
||
one @dfn{account} to another. Here is an example of the simplest of
|
||
journal files:
|
||
|
||
@smallexample
|
||
2010/05/31 Just an example
|
||
Expenses:Some:Account $100.00
|
||
Income:Another:Account
|
||
@end smallexample
|
||
|
||
In this example, there is a transaction date, a payee, or description
|
||
of the transaction, and two postings. The postings show movement of
|
||
one hundred dollars from an account within the Income hierarchy, to
|
||
the specified expense account. The name and meaning of these accounts
|
||
in arbitrary, with no preferences implied, although you will find it
|
||
useful to follow standard accounting practice (@pxref{Principles of
|
||
Accounting}).
|
||
|
||
Since an amount is missing from the second posting, it is assumed to
|
||
be the inverse of the first. This guarantee the cardinal rule of
|
||
double-entry accounting: the sum of every transaction must balance to
|
||
zero, or it is in error. Whenever Ledger encounters a @dfn{null
|
||
posting} in a transaction, it uses it to balance the remainder.
|
||
|
||
It is also typical---though not enforced---to think of the first
|
||
posting as the destination, and the final as the source. Thus, the
|
||
amount of the first posting is typically positive. Consider:
|
||
|
||
@smallexample
|
||
2010/05/31 An income transaction
|
||
Assets:Checking $1,000.00
|
||
Income:Salary
|
||
|
||
2010/05/31 An expense transaction
|
||
Expenses:Dining $100.00
|
||
Assets:Checking
|
||
@end smallexample
|
||
|
||
@menu
|
||
* Comments and metadata::
|
||
* Specifying Amounts::
|
||
@end menu
|
||
|
||
@node Comments and metadata, Specifying Amounts, Journal File Format, Journal File Format
|
||
@section Comments and metadata
|
||
@menu
|
||
* Comments::
|
||
* Metadata::
|
||
@end menu
|
||
|
||
@node Comments, Metadata, Comments and metadata, Comments and metadata
|
||
@subsection Comments
|
||
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 Metadata, , Comments, Comments and metadata
|
||
@subsection Metadat
|
||
|
||
@node Specifying Amounts, , Comments and metadata, Journal File Format
|
||
@section 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 and
|
||
commodity designator).
|
||
|
||
@menu
|
||
* Integer Amounts::
|
||
* Commoditized Amounts::
|
||
@end menu
|
||
|
||
@node Integer Amounts, Commoditized Amounts, Specifying Amounts, Specifying Amounts
|
||
@subsection Integer Amounts
|
||
|
||
In the simplest form, bare decimal numbers are accepted:
|
||
|
||
@smallexample
|
||
2010/05/31 An income transaction
|
||
Assets:Checking 1000.00
|
||
Income:Salary
|
||
@end smallexample
|
||
@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 signficant difference: They always display in
|
||
reports with @dfn{full precision}. More on this in a moment. For
|
||
now, a word must be said about how Ledger stores numbers.
|
||
|
||
Every number parsed by Ledger is stored internally as an
|
||
infinite-precision rational value. Floating-point math is never used,
|
||
as it cannot be trusted to maintain precision of values. So, in the
|
||
case of @samp{1000.00} above, the internal value is @samp{100000/100}.
|
||
|
||
While rational numbers are great at not losing precision, the question
|
||
arises: How should they be displayed? A number like @samp{100000/100}
|
||
is no problem, since it represents a clean decimal fraction. But what
|
||
about when the number @samp{1/1} is divided by three? How should one
|
||
print @samp{1/3}, an infinitely repeating decimal?
|
||
|
||
Ledger gets around this problem by rendering rationals into decimal at
|
||
the last possible moment, and only for display. As such, some
|
||
rounding must, at times, occur. If this rounding would affect the
|
||
calculation of a running total, special accommodation postings are
|
||
generated to make you aware it has happened. In practice, it happens
|
||
rarely, but even then it does not reflect adjustment of the
|
||
@emph{internal amount}, only the displayed amount.
|
||
|
||
What has still not been answered is how Ledger rounds values. Should
|
||
@samp{1/3} be printed as @samp{0.33} or @samp{0.33333}? For
|
||
commoditized amounts, the number of decimal places is decided by
|
||
observing how each commodity is used; but in the case of integer
|
||
amounts, an arbitrary factor must be chosen. Initially, this factor
|
||
is six. Thus, @samp{1/3} is printed back as @samp{0.333333}.
|
||
Further, this rounding factor becomes associated with each particular
|
||
value, and is carried through mathematical operations. For example,
|
||
if that particular number were multiplied by itself, the decimal
|
||
precision of the result would be twelve. Addition and subtraction do
|
||
not affect precision.
|
||
|
||
Since each integer amount retains its own display precision, this is
|
||
called @dfn{full precision}, as opposed to commoditized amounts, which
|
||
always look to their commodity to know what precision they should
|
||
round to, and so use @dfn{commodity precision}.
|
||
|
||
@node Commoditized Amounts, , Integer Amounts, Specifying Amounts
|
||
@subsection Commoditized Amounts
|
||
|
||
A @dfn{commoditized amount} is an integer amount which has an
|
||
associated commodity. This commodity can appear before or after the
|
||
amount, and may or may not be separated from it by a space. Most
|
||
characters are allowed in a commodity name, except for the following:
|
||
|
||
@itemize @bullet
|
||
@item Any kind of whitespace
|
||
@item Numerical digits
|
||
@item Punctuation: @samp{.,;:?!}
|
||
@item Mathematical and logical operators: @samp{-+*/^&|=}
|
||
@item Bracketing characters: @samp{<>[]()}@{@}
|
||
@item The at symbol: @samp{@@}
|
||
@end itemize
|
||
|
||
And yet, any of these may appear in a commodity name if it is
|
||
surrounded by double quotes, for example:
|
||
|
||
@smallexample
|
||
100 "EUN+133"
|
||
@end smallexample
|
||
|
||
If a @dfn{quoted commodity} is found, it is displayed in quotes as
|
||
well, to avoid any confusion as to which part is the amount, and which
|
||
part is the commodity.
|
||
|
||
Another feature of commoditized amounts is that they are reported back
|
||
in the same form as parsed. If you specify dollar amounts using
|
||
@samp{$100}, they will print the same; likewise with @samp{100 $} or
|
||
@samp{$100.000}. You may even use decimal commas, such as
|
||
@samp{$100,00}, or thousand-marks, as in @samp{$10,000.00}.
|
||
|
||
These display characteristics become associated with the commodity, with
|
||
the result being that all amounts of the same commodity are reported
|
||
consistently. Where this is most noticeable is the @dfn{display
|
||
precision}, which is determined by the most precise value seen for a
|
||
given commodity---in most cases.
|
||
|
||
Ledger makes a distinction between @dfn{observed amounts} and unobserved
|
||
amounts. An observed amount is critiqued by Ledger to determine how
|
||
amounts using that commodity should be displayed; unobserved amounts are
|
||
significant in their value only---no matter how they are specified, it
|
||
does not change how other amounts in that commodity will be displayed.
|
||
|
||
An example of this is found in cost expressions, covered next.
|
||
|
||
@section Posting costs
|
||
|
||
You have seen how to specify either a commoditized or an integer
|
||
amount for a posting. But what if the amount you paid for something
|
||
was in one commodity, and the amount received was another? There are
|
||
two main ways to express this:
|
||
|
||
@smallexample
|
||
2010/05/31 Farmer's Market
|
||
Assets:My Larder 100 apples
|
||
Assets:Checking $20.00
|
||
@end smallexample
|
||
|
||
In this example, you have paid twenty dollars for one hundred apples.
|
||
The cost to you is twenty cents per apple, and Ledger calculates this
|
||
implied cost for you. You can also make the cost explicit using a
|
||
@dfn{cost amount}:
|
||
|
||
@smallexample
|
||
2010/05/31 Farmer's Market
|
||
Assets:My Larder 100 apples @@ $0.200000
|
||
Assets:Checking
|
||
@end smallexample
|
||
|
||
Here the @dfn{per-unit cost} is given explicitly in the form of a cost
|
||
amount; and since cost amount are @emph{unobserved}, the use of six
|
||
decimal places has no effect on how dollar amounts are displayed in
|
||
the final report. You can also specify the @dfn{total cost}:
|
||
|
||
@smallexample
|
||
2010/05/31 Farmer's Market
|
||
Assets:My Larder 100 apples @@@@ $20
|
||
Assets:Checking
|
||
@end smallexample
|
||
|
||
These three forms have identical meaning. In most cases the first is
|
||
preferred, but the second two are necessary when more than two
|
||
postings are involved:
|
||
|
||
@smallexample
|
||
2010/05/31 Farmer's Market
|
||
Assets:My Larder 100 apples @@ $0.200000
|
||
Assets:My Larder 100 pineapples @@ $0.33
|
||
Assets:My Larder 100 "crab apples" @@ $0.04
|
||
Assets:Checking
|
||
@end smallexample
|
||
|
||
Here the implied cost is @samp{$57.00}, which is entered into the null
|
||
posting automatically so that the transaction balances.
|
||
|
||
@subsection Primary commodities
|
||
|
||
In every transaction involving more than one commodity, there is
|
||
always one which is the @dfn{primary commodity}. This commodity
|
||
should be thought of as the exchange commodity, or the commodity used
|
||
to buy and sells units of the other commodity. In the fruit examples
|
||
above, dollars are the primary commodity. This is decided by Ledger
|
||
on the placement of the commodity in the transaction:
|
||
|
||
@smallexample
|
||
2010/05/31 Sample Transaction
|
||
Expenses 100 secondary
|
||
Assets 50 primary
|
||
|
||
2010/05/31 Sample Transaction
|
||
Expenses 100 secondary @@ 0.5 primary
|
||
Assets
|
||
|
||
2010/05/31 Sample Transaction
|
||
Expenses 100 secondary @@@@ 50 primary
|
||
Assets
|
||
@end smallexample
|
||
|
||
The only case where knowledge of primary versus secondary comes into
|
||
play is in reports that use the @option{-V} or @option{-B} options.
|
||
With these, only primary commodities are shown.
|
||
|
||
If a transaction uses only one commodity, this commodity is also
|
||
considered a primary. In fact, when Ledger goes about ensures that
|
||
all transactions balance to zero, it only ever asks this of primary
|
||
commodities.
|
||
|
||
@node Extending with Python, Major Changes from version 2.6, Journal File Format, Top
|
||
@chapter Extending with Python
|
||
|
||
@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
|