summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--README.md2
-rwxr-xr-xacprep49
-rw-r--r--contrib/ledger-completion.bash91
-rw-r--r--doc/ledger-mode.texi6
-rw-r--r--doc/ledger3.texi6566
-rw-r--r--lisp/ldg-commodities.el134
-rw-r--r--lisp/ldg-complete.el132
-rw-r--r--lisp/ldg-fonts.el32
-rw-r--r--lisp/ldg-mode.el24
-rw-r--r--lisp/ldg-occur.el5
-rw-r--r--lisp/ldg-post.el2
-rw-r--r--lisp/ldg-reconcile.el374
-rw-r--r--lisp/ldg-regex.el42
-rw-r--r--lisp/ldg-report.el36
-rw-r--r--lisp/ldg-sort.el75
15 files changed, 4179 insertions, 3391 deletions
diff --git a/README.md b/README.md
index 45f9de90..61f24703 100644
--- a/README.md
+++ b/README.md
@@ -101,7 +101,7 @@ following packages (current as of Ubuntu 12.04):
python-dev gettext libgmp3-dev libmpfr-dev libboost-dev
libboost-regex-dev libboost-date-time-dev
libboost-filesystem-dev libboost-python-dev texinfo lcov
- sloccount
+ sloccount libboost-iostreams-dev libboost-test-dev
Or, for Ubuntu Karmic:
diff --git a/acprep b/acprep
index 5cfd6710..be81790e 100755
--- a/acprep
+++ b/acprep
@@ -206,7 +206,7 @@ class CommandLineApp(object):
except KeyboardInterrupt:
exit_code = self.handleInterrupt()
- except SystemExit, msg:
+ except SystemExit as msg:
exit_code = msg.args[0]
except Exception:
@@ -244,7 +244,7 @@ class PrepareBuild(CommandLineApp):
}
for varname in self.envvars.keys():
- if os.environ.has_key(varname):
+ if varname in os.environ:
self.envvars[varname] = os.environ[varname]
if varname.endswith('FLAGS'):
@@ -327,7 +327,7 @@ class PrepareBuild(CommandLineApp):
if args:
cmd = args[0]
- if not PrepareBuild.__dict__.has_key('phase_' + cmd):
+ if 'phase_' + cmd not in PrepareBuild.__dict__:
self.log.error("Unknown build phase: " + cmd + "\n")
sys.exit(1)
else:
@@ -344,22 +344,22 @@ class PrepareBuild(CommandLineApp):
def execute(self, *args):
try:
- self.log.debug('Executing command: ' + string.join(args, ' '))
+ self.log.debug('Executing command: ' + ' '.join(args))
retcode = call(args, shell=False)
if retcode < 0:
self.log.error("Child was terminated by signal", -retcode)
sys.exit(1)
elif retcode != 0:
- self.log.error("Execution failed: " + string.join(args, ' '))
+ self.log.error("Execution failed: " + ' '.join(args))
sys.exit(1)
- except OSError, e:
- self.log.error("Execution failed:", e)
+ except OSError as e:
+ self.log.error("Execution failed: " + e)
sys.exit(1)
def get_stdout(self, *args):
try:
- self.log.debug('Executing command: ' + string.join(args, ' '))
+ self.log.debug('Executing command: ' + ' '.join(args))
proc = Popen(args, shell=False, stdout=PIPE)
stdout = proc.stdout.read()
@@ -369,11 +369,11 @@ class PrepareBuild(CommandLineApp):
-retcode)
sys.exit(1)
elif retcode != 0:
- self.log.error("Execution failed: " + string.join(args, ' '))
+ self.log.error("Execution failed: " + ' '.join(args))
sys.exit(1)
return stdout[:-1]
- except OSError, e:
- self.log.error("Execution failed:", e)
+ except OSError as e:
+ self.log.error("Execution failed:" + e)
sys.exit(1)
def isnewer(self, file1, file2):
@@ -445,14 +445,14 @@ class PrepareBuild(CommandLineApp):
if match:
date = match.group(1)
break
- self.current_ver = "%s.%s.%s%s" % (major, minor, patch,
+ self.current_ver = "%s.%s.%s%s" % (major, minor, patch,
"-%s" % date if date else "")
version_m4.close()
return self.current_ver
def phase_products(self, *args):
self.log.info('Executing phase: products')
- print self.products_directory()
+ print(self.products_directory())
def phase_info(self, *args):
self.log.info('Executing phase: info')
@@ -527,7 +527,7 @@ class PrepareBuild(CommandLineApp):
'texlive-xetex', 'doxygen', 'graphviz', 'texinfo',
'lcov', 'sloccount'
] + BoostInfo.dependencies('darwin')
- self.log.info('Executing: ' + string.join(packages, ' '))
+ self.log.info('Executing: ' + ' '.join(packages))
self.execute(*packages)
elif exists('/sw/bin/fink'):
self.log.info('Looks like you are using Fink on OS X')
@@ -616,7 +616,7 @@ class PrepareBuild(CommandLineApp):
self.log.info('I do not recognize your version of Ubuntu!')
packages = None
if packages:
- self.log.info('Executing: ' + string.join(packages, ' '))
+ self.log.info('Executing: ' + ' '.join(packages))
self.execute(*packages)
if exists('/etc/redhat-release'):
@@ -646,7 +646,7 @@ class PrepareBuild(CommandLineApp):
#'lcov',
#'sloccount'
]
- self.log.info('Executing: ' + string.join(packages, ' '))
+ self.log.info('Executing: ' + ' '.join(packages))
self.execute(*packages)
#########################################################################
@@ -678,7 +678,7 @@ class PrepareBuild(CommandLineApp):
self.configure_args.append(self.source_dir)
def setup_for_system(self):
- system = self.get_stdout('uname', '-s')
+ system = str(self.get_stdout('uname', '-s'))
self.log.info('System type is => ' + system)
if self.options.enable_doxygen:
@@ -695,8 +695,7 @@ class PrepareBuild(CommandLineApp):
def setup_flavor(self):
self.setup_for_system()
- if not PrepareBuild.__dict__.has_key('setup_flavor_' +
- self.current_flavor):
+ if 'setup_flavor_' + self.current_flavor not in PrepareBuild.__dict__:
self.log.error('Unknown build flavor "%s"' % self.current_flavor)
sys.exit(1)
@@ -725,7 +724,7 @@ class PrepareBuild(CommandLineApp):
self.log.debug('Final value of %s: %s' %
(var, self.envvars[var]))
- elif self.envvars.has_key(var):
+ elif var in self.envvars:
del self.envvars[var]
#########################################################################
@@ -795,8 +794,8 @@ class PrepareBuild(CommandLineApp):
sys.exit(1)
for var in ('CXX', 'CXXFLAGS', 'LDFLAGS'):
- if self.envvars.has_key(var) and self.envvars[var] and \
- (var.endswith('FLAGS') or exists(self.envvars[var])):
+ if self.envvars.get(var) and (var.endswith('FLAGS')
+ or exists(self.envvars[var])):
if var == 'CXX':
conf_args.append('-DCMAKE_CXX_COMPILER=%s' %
self.envvars[var])
@@ -848,7 +847,7 @@ class PrepareBuild(CommandLineApp):
self.log.error("Child was terminated by signal", -retcode)
sys.exit(1)
elif retcode != 0:
- self.log.error("Execution failed: " + string.join(conf_args, ' '))
+ self.log.error("Execution failed: " + ' '.join(conf_args))
sys.exit(1)
else:
self.log.debug('configure does not need to be run')
@@ -1031,7 +1030,7 @@ class PrepareBuild(CommandLineApp):
def phase_help(self, *args):
self.option_parser.print_help()
- print """
+ print("""
Of the optional ARGS, the first is an optional build FLAVOR, with the default
being 'debug':
@@ -1077,7 +1076,7 @@ Here are some real-world examples:
./acprep
./acprep --python
./acprep opt make
- ./acprep make doc -- -DBUILD_WEB_DOCS=1"""
+ ./acprep make doc -- -DBUILD_WEB_DOCS=1""")
sys.exit(0)
PrepareBuild().run()
diff --git a/contrib/ledger-completion.bash b/contrib/ledger-completion.bash
new file mode 100644
index 00000000..8f3e16af
--- /dev/null
+++ b/contrib/ledger-completion.bash
@@ -0,0 +1,91 @@
+### Assumption
+#
+# bash-completion package is installed and enabled
+#
+### Just want to try it?
+#
+# $ source ledger-completion.bash
+#
+### How to install?
+#
+#### For local user
+#
+# $ cat <<EOF >>~/.bash_completion
+# . ~/.bash_completion.d/ledger
+# EOF
+#
+# $ cp ledger-completion.bash ~/.bash_completion.d/ledger
+#
+#### For all users
+#
+# $ sudo cp ledger-completion.bash /etc/bash_completion.d/ledger
+#
+
+_ledger()
+{
+ local cur prev command options
+ COMPREPLY=()
+ cur="${COMP_WORDS[COMP_CWORD]}"
+ prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+ # COMMANDS
+ #
+ # Commands are found in source code:
+ # report.cc::lookup "case symbol_t::COMMAND"
+ # report.cc::lookupcase "case symbol_t::PRECOMMAND" : these are debug commands and they have been filtered out here
+ #
+ commands="accounts balance budget cleared commodities convert csv draft echo emacs entry equity lisp org payees pricemap prices pricesdb print register reload select source stats tags xact xml"
+
+ # OPTIONS
+ #
+ # Options are found in source code:
+ # global.cc::lookup_option
+ # report.cc::lookup_option
+ # session.cc::lookup_option
+ #
+ options="--abbrev-len= --account-width= --account= --actual --actual-dates --add-budget --amount-data --amount-width= --amount= --anon --ansi --args-only --auto-match --aux-date --average --balance-format= --base --basis --begin= --bold-if= --budget --budget-format= --by-payee --cache= --change --check-payees --cleared --cleared-format= --collapse --collapse-if-zero --color --columns= --cost --count --csv-format= --current --daily --date-format= --date-width= --date= --datetime-format= --day-break --days-of-week --dc --debug= --decimal-comma --depth= --detail --deviation --display-amount= --display-total= --display= --dow --download --effective --empty --end= --equity --exact --exchange= --explicit --file= --first= --flat --force-color --force-pager --forecast-years= --forecast= --format= --full-help --gain --generated --group-by= --group-title-format= --head= --help --help-calc --help-comm --help-disp --historical --immediate --init-file= --inject= --input-date-format= --invert --last= --leeway= --limit= --lot-dates --lot-notes --lot-prices --lot-tags --lots --lots-actual --market --master-account= --meta-width= --meta= --monthly --no-color --no-rounding --no-titles --no-total --now= --only= --options --output= --pager= --payee-width= --payee= --pedantic --pending --percent --period-sort= --period= --permissive --pivot= --plot-amount-format= --plot-total-format= --prepend-format= --prepend-width= --price --price-db= --price-exp= --pricedb-format= --prices-format= --primary-date --quantity --quarterly --raw --real --register-format= --related --related-all --revalued --revalued-only --revalued-total= --rich-data --script= --seed= --sort-all= --sort-xacts= --sort= --start-of-week= --strict --subtotal --tail= --time-colon --time-report --total-data --total-width= --total= --trace= --truncate= --unbudgeted --uncleared --unrealized --unrealized-gains= --unrealized-losses= --unround --value --value-expr= --values --verbose --verify --verify-memory --version --weekly --wide --yearly"
+
+ # Bash FAQ E13 http://tiswww.case.edu/php/chet/bash/FAQ
+ #
+ COMP_WORDBREAKS=${COMP_WORDBREAKS//:}
+
+ # ACCOUNTS
+ #
+ # Accounts are generated with bash command:
+ # $ ledger accounts>/tmp/accounts; for i in {1..5}; do cut -d : -f $i- /tmp/accounts;cut -d : -f -$i /tmp/accounts; done|sort -u|xargs
+ #
+ # Warning: this is working badly if there are spaces in account names
+ #
+ accounts="Assets Liabilities Equity Revenue Expenses"
+
+ case $prev in
+ --@(cache|file|init-file|output|pager|price-db|script))
+ _filedir
+ return 0
+ ;;
+ @(balance|equity|print|register))
+ COMPREPLY=( $(compgen -W "${accounts}" -- ${cur}) )
+ return 0
+ ;;
+
+ esac
+
+ if [[ ${cur} == -* ]] ; then
+ COMPREPLY=( $(compgen -W "${options}" -- ${cur}) )
+# elif [[ ${cur} == [A-Z]* ]] ; then
+# COMPREPLY=( $(compgen -W "${accounts}" -- ${cur}) )
+ else
+ COMPREPLY=( $(compgen -W "${commands}" -- ${cur}) )
+ fi
+
+ return 0
+}
+complete -F _ledger ledger
+
+# Local variables:
+# mode: shell-script
+# sh-basic-offset: 4
+# sh-indent-comment: t
+# indent-tabs-mode: nil
+# End:
+# ex: ts=4 sw=4 et filetype=sh
diff --git a/doc/ledger-mode.texi b/doc/ledger-mode.texi
index d7144112..151876a9 100644
--- a/doc/ledger-mode.texi
+++ b/doc/ledger-mode.texi
@@ -233,7 +233,11 @@ automatically place any amounts such that their last digit is aligned to
the column specified by @code{ledger-post-amount-alignment-column},
which defaults to 52. @xref{Ledger Post Customization Group}.
-@node Quick Balance Display
+@menu
+* Quick Balance Display::
+@end menu
+
+@node Quick Balance Display, , Adding Transactions, Adding Transactions
@subsection Quick Balance Display
You will often want to quickly check the balance of an account. The
easiest way it to position point on the account you are interested in,
diff --git a/doc/ledger3.texi b/doc/ledger3.texi
index 3f099d93..cd1b59a8 100644
--- a/doc/ledger3.texi
+++ b/doc/ledger3.texi
@@ -1,11 +1,15 @@
-\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*-texinfo-*-
@setfilename ledger3.info
@settitle Ledger: Command-Line Accounting
+@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with
+@c a prefix arg). This updates the node pointers, which texinfmt.el
+@c needs.
+
@dircategory User Applications
@copying
-Copyright (c) 2003-2011, John Wiegley. All rights reserved.
+Copyright (c) 2003-2013, 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
@@ -23,7 +27,7 @@ met:
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
+``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,
@@ -41,7 +45,6 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@finalout
@end iftex
-
@titlepage
@title Ledger: Command-Line Accounting
@subtitle For Version 3.0 of Ledger
@@ -55,6 +58,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@contents
@ifnottex
+
@node Top, Copying, (dir), (dir)
@top Overview
Ledger is a command line accounting tool that provides double-entry
@@ -65,45 +69,48 @@ twinkling in their father's CRT.
@end ifnottex
@menu
-* Copying::
-* Introduction to Ledger::
-* Ledger Tutorial ::
-* Principles of Accounting::
-* Keeping a Journal::
-* Transactions ::
-* Building Reports::
-* Reporting Commands::
-* Command-line Syntax::
-* Budgeting and Forecasting::
-* Time Keeping::
-* Value Expressions::
-* Format Strings::
-* Extending with Python::
-* Ledger for Developers::
-* Major Changes from version 2.6::
-* Example Data File::
-* Miscellaneous Notes::
-* Concept Index::
-* Command Index::
+* Copying::
+* Introduction to Ledger::
+* Ledger Tutorial::
+* Principles of Accounting::
+* Keeping a Journal::
+* Transactions::
+* Building Reports::
+* Reporting Commands::
+* Command-line Syntax::
+* Budgeting and Forecasting::
+* Time Keeping::
+* Value Expressions::
+* Format Strings::
+* Extending with Python::
+* Ledger for Developers::
+* Major Changes from version 2.6::
+* Example Data File::
+* Miscellaneous Notes::
+* Concept Index::
+* Command Index::
@end menu
@node Copying, Introduction to Ledger, Top, Top
@chapter Copying
+
@insertcopying
This license can also be obtained from the command-line by executing
@code{ledger --license}
-@node Introduction to Ledger, Ledger Tutorial , Copying, Top
+@node Introduction to Ledger, Ledger Tutorial, Copying, Top
@chapter Introduction to Ledger
+
@menu
-* Fat-free Accounting::
-* Building the Program::
-* Getting Help::
+* 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.
@@ -115,11 +122,11 @@ 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.
+so we'll describe double-entry accounting in terms of that.
-@c If you use
-@c another GUI accounting program like GNUCash, the vast majority of its
-@c functionality is geared towards helping you keep a journal.
+@c If you use another GUI accounting program like GnuCash, the vast
+@c majority of its functionality is geared towards helping you keep
+@c a journal.
A checkbook journal records debits (subtractions, or withdrawals) and
credits (additions, or deposits) with reference to a single account:
@@ -139,27 +146,26 @@ 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.
+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:
+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
@@ -168,62 +174,64 @@ going to. These transactions might look like this:
(123) Brokerage $-100.00 0
@end smallexample
-The posting must balance to $0: $23 went to Pacific Bell, $23 came from
-Checking. The next entry shows check number 123 written against your
-brokerage account, transferring money to your checking account. There is
-nothing left over to be accounted for, since the money has simply moved
-from one account to another in both cases. This is the basis of
-double-entry accounting: money never pops in or out of existence; it is
-always a posting from one account to another.
+The posting must balance to $0: $23 went to Pacific Bell, $23 came
+from Checking. The next entry shows check number 123 written against
+your brokerage account, transferring money to your checking account.
+There is nothing left over to be accounted for, since the money has
+simply moved from one account to another in both cases. This is the
+basis of double-entry accounting: money never pops in or out of
+existence; it is always a posting from one account to another.
-Keeping a general journal is the same as keeping two separate journals:
-One for Pacific Bell and one for Checking. In that case, each time a
-payment is written into one, you write a corresponding withdrawal into
-the other. This makes it easier to write in a ``running balance'',
-since you don't have to look back at the last time the account was
-referenced---but it also means having a lot of journal books, if you
-deal with multiple accounts.
+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
+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
+ Expenses:Groceries $100.00
+ Assets:Checking
2011/03/15 Whole Food Market
- Expenses:Groceries $75.00
- Assets:Checking
+ 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.}
+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:
+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
+ Expenses:Pacific Bell $23.00
+ Assets:Checking
@end smallexample
The account balances and registers in this file, if saved as
@@ -240,89 +248,90 @@ that Ledger will never alter your input file. You can create and edit
that file in any way you prefer, but Ledger is only for analyzing the
data, not for altering it.
-
@node Building the Program, Getting Help, Fat-free Accounting, Introduction to Ledger
@section Building the program
Ledger is written in ANSI C++, and should compile on any platform. It
-depends on the GNU multiple precision arithmetic library (libgmp), and the
-Perl regular expression library (libpcre). It was developed using GNU
-make and gcc 3.3, on a PowerBook running OS/X.
+depends on the GNU multiple precision arithmetic library (libgmp), and
+the Perl regular expression library (libpcre). It was developed using
+GNU make and gcc 3.3, on a PowerBook running OS/X.
To build and install once you have these libraries on your system,
enter these commands:
@smallexample
-./configure && make install
+$ ./configure && make install
@end smallexample
-@findex help
@node Getting Help, , Building the Program, Introduction to Ledger
@section Getting help
-Ledger has a complete online help system based on GNU Info. This manual
-can be searched directly from the command line using the following
-options:
-@code{ledger --help} bring up this entire manual in your tty.
+@findex help
-If you need help on how to use Ledger, or run into problems, you can
-join the Ledger mailing list at the following Web address:
+Ledger has a complete online help system based on GNU Info. This
+manual can be searched directly from the command line using the
+following options: @code{ledger --help} bring up this entire manual in
+your tty.
-@smallexample
-http://groups.google.com/group/ledger-cli
-@end smallexample
+If you need help on how to use Ledger, or run into problems, you can
+join the Ledger mailing list at
+@url{http://groups.google.com/group/ledger-cli}.
-@noindent You can also find help at the @code{#ledger} channel on the IRC server
+You can also find help at the @code{#ledger} channel on the IRC server
@code{irc.freenode.net}.
-@cindex tutorial
-@node Ledger Tutorial , Principles of Accounting, Introduction to Ledger, Top
+@node Ledger Tutorial, Principles of Accounting, Introduction to Ledger, Top
@chapter Ledger Tutorial
+@cindex tutorial
@menu
-* Start a Journal::
-* Run Some Reports::
+* Start a Journal::
+* Run Some Reports::
@end menu
-@node Start a Journal, Run Some Reports, Ledger Tutorial , Ledger Tutorial
+@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}).
+
+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 see @ref{Keeping a Journal}.
+If you would rather start with your own journal right away please
+@pxref{Keeping a Journal}.
@node Run Some Reports, , Start a Journal, Ledger Tutorial
@section Run a Few Reports
@menu
-* Balance Report::
-* Register Report::
-* Cleared Report::
-* Using the Windows command line::
+* Balance Report::
+* Register Report::
+* Cleared Report::
+* Using the Windows command line::
@end menu
Please note that as a command line program, Ledger is controlled from
-your shell. There are several different command shells that all behave
-slightly differently with repsect to some special characters. In
-particular, the BaSH shell will interpret $ signs differently than
-ledger and they must be escaped to reach the actual program. Another
-example is zsh, which will interpret ^ differently than ledger expects.
-In all cases that follow you should take that into account when entering
-the commandline arguments given. There are too many variations between
-shells to give concrete examples for each.
+your shell. There are several different command shells that all
+behave slightly differently with respect to some special characters.
+In particular, the BASH shell will interpret @samp{$} signs
+differently than ledger and they must be escaped to reach the actual
+program. Another example is zsh, which will interpret @samp{^}
+differently than ledger expects. In all cases that follow you should
+take that into account when entering the command line arguments given.
+There are too many variations between shells to give concrete examples
+for each.
@node Balance Report, Register Report, Run Some Reports, Run Some Reports
@subsection Balance Report
@cindex balance report
-@findex balance (bal)
+@findex balance
+
To find the balances of all of your accounts, run this command:
@smallexample
-ledger -f drewr3.dat balance
+$ ledger -f drewr3.dat balance
@end smallexample
Ledger will generate:
@@ -350,8 +359,9 @@ Ledger will generate:
$ -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.
+@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:
@@ -369,17 +379,19 @@ $ ledger -f drewr3.dat balance Assets Liabilities
$ -3,867.60
@end smallexample
-
@node Register Report, Cleared Report, Balance Report, Run Some Reports
@subsection Register Report
@cindex register report
-@findex register (reg)
+@findex register
+
To show all transactions and a running total:
+
@smallexample
-ledger -f drewr3.dat register
+$ ledger -f drewr3.dat register
@end smallexample
-@noindent Ledger will generate:
+@noindent
+Ledger will generate:
@smallexample
10-Dec-01 Checking balance Assets:Checking $ 1,000.00 $ 1,000.00
@@ -415,9 +427,12 @@ ledger -f drewr3.dat register
(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:
+@noindent
+To limit this to a more useful subset, simply add the accounts you are
+interested in seeing transactions for:
@cindex accounts, limiting by
@cindex limiting by accounts
+
@smallexample
$ ledger -f drewr3.dat register Groceries
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50
@@ -430,14 +445,18 @@ $ ledger -f drewr3.dat register Groceries
11-Jan-19 Grocery Store Expense:Food:Groceries $ 44.00 $ 334.00
@end smallexample
-@noindent Which matches the balance reported for the @code{Groceries} account:
+@noindent
+Which matches the balance reported for the @code{Groceries} account:
@smallexample
-$ ledger -f drewr3.dat balance Groceries
+$ 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 @code{payee} or @@:
+@noindent
+If you would like to find transaction to only a certain payee use
+@samp{payee} or @samp{@@}:
+
@smallexample
$ ledger -f drewr3.dat register payee "Organic"
10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50
@@ -453,14 +472,16 @@ $ ledger -f drewr3.dat register payee "Organic"
@subsection Cleared Report
@cindex cleared report
@findex cleared
+
A very useful report is to show what your obligations are versus what
-expenditures have actually been recorded. It can take several days for
-a check to clear, but you should treat it as money spent. The
-@code{cleared} report shows just that (note that the cleared report will
-not format correctly for accounts that contain multiple commodities):
+expenditures have actually been recorded. It can take several days
+for a check to clear, but you should treat it as money spent. The
+@code{cleared} report shows just that (note that the cleared report
+will not format correctly for accounts that contain multiple
+commodities):
@smallexample
-$ ledger -f drewr3.dat cleared
+$ ledger -f drewr3.dat cleared
$ -3,804.00 $ 775.00 Assets
$ 1,396.00 $ 775.00 10-Dec-20 Checking
$ 30.00 0 Business
@@ -480,48 +501,51 @@ $ ledger -f drewr3.dat cleared
$ 200.00 0 Mortgage:Principal
$ -243.60 0 Tithe
---------------- ---------------- ---------
- $ -243.60 0
+ $ -243.60 0
@end smallexample
-@noindent The first column shows the outstanding balance, the second column shows the ``cleared'' balance.
+@noindent
+The first column shows the outstanding balance, the second column
+shows the ``cleared'' balance.
+
@node Using the Windows command line, , Cleared Report, Run Some Reports
@subsection Using the Windows Command Line
@cindex windows cmd.exe
@cindex currency symbol display on windows
-Using ledger under the windows command shell has one significant
-limitation. CMD.exe is limited to standard ASCII characters and as such
-cannot display any currency symbols other than dollar signs ($).
+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
+@samp{$}.
-@node Principles of Accounting, Keeping a Journal, Ledger Tutorial , Top
+@node Principles of Accounting, Keeping a Journal, Ledger Tutorial, Top
@chapter Principles of Accounting with Ledger
@menu
-* Accounting with Ledger::
-* Stating where money goes::
-* Assets and Liabilities::
-* Commodities and Currencies::
-* Accounts and Inventories::
-* Understanding Equity::
-* Dealing with Petty Cash::
-* Working with multiple funds and accounts::
+* Accounting with Ledger::
+* Stating where money goes::
+* Assets and Liabilities::
+* Commodities and Currencies::
+* Accounts and Inventories::
+* Understanding Equity::
+* Dealing with Petty Cash::
+* Working with multiple funds and accounts::
@end menu
-
@node Accounting with Ledger, Stating where money goes, Principles of Accounting, Principles of Accounting
@section Accounting with Ledger
Accounting is simply tracking your money. It can range from nothing,
-and just waiting for automatic overdraft protection to kick in, or not,
-to a full blown double entry accounting system. Ledger accomplishes the
-latter. With ledger you can handle your personal finances or your
-businesses. Double-entry accounting scales.
+and just waiting for automatic overdraft protection to kick in, or
+not, to a full blown double entry accounting system. Ledger
+accomplishes the latter. With ledger you can handle your personal
+finances or your businesses. Double-entry accounting scales.
@cindex double-entry accounting
@node Stating where money goes, Assets and Liabilities, Accounting with Ledger, Principles of Accounting
@section Stating where money goes
-
@cindex credits and debits
+
Accountants will talk of ``credits'' and ``debits'', but the meaning
is often different from the layman's understanding. To avoid
confusion, Ledger uses only subtractions and additions, although the
@@ -532,10 +556,10 @@ 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:
+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
@@ -576,6 +600,7 @@ money now than when you started your ledger. Make sense?
@section Assets and Liabilities
@cindex assets and liabilities
@cindex debts are liabilities
+
Assets are money that you have, and Liabilities are money that you
owe. ``Liabilities'' is just a more inclusive name for Debts.
@@ -603,17 +628,17 @@ it:
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
+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
+@smallexample
+$ ledger balance ^assets ^liabilities
+@end smallexample
In a similar vein, your Income accounts show up negative, because they
transfer money @emph{from} an account in order to increase your
@@ -623,28 +648,29 @@ 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
+@smallexample
+$ ledger balance ^income ^expenses
+@end smallexample
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
+@smallexample
+$ ledger -M register expenses:auto
+@end smallexample
This assumes, of course, that you use account names like
@code{Expenses:Auto:Gas} and @code{Expenses:Auto:Repair}.
@menu
-* Tracking reimbursable expenses::
+* Tracking reimbursable expenses::
@end menu
-@cindex reimbursable expense tracking
+
@node Tracking reimbursable expenses, , Assets and Liabilities, Assets and Liabilities
@subsection Tracking reimbursable expenses
+@cindex reimbursable expense tracking
Sometimes you will want to spend money on behalf of someone else,
which will eventually get repaid. Since the money is still ``yours'',
@@ -696,10 +722,10 @@ personal transaction, which shows the need for reimbursement:
@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:
+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
@@ -707,12 +733,12 @@ to you:
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
+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:
+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
@@ -753,10 +779,10 @@ 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:
+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
@@ -784,14 +810,14 @@ apply account Company XYZ
end apply account
@end smallexample
-(Note: The @code{apply account} above means that all accounts mentioned in
-the file are children of that account. In this case it means that all
-activity in the file relates to Company XYZ).
+(Note: The @code{apply account} above means that all accounts
+mentioned in the file are children of that account. In this case it
+means that all activity in the file relates to Company XYZ).
-After creating these transactions, you will always know that $100.00 was
-spent using your MasterCard on behalf of Company XYZ, and that Company
-XYZ spent the money on computer software and paid it back about two
-weeks later.
+After creating these transactions, you will always know that $100.00
+was spent using your MasterCard on behalf of Company XYZ, and that
+Company XYZ spent the money on computer software and paid it back
+about two weeks later.
@node Commodities and Currencies, Accounts and Inventories, Assets and Liabilities, Principles of Accounting
@section Commodities and Currencies
@@ -805,13 +831,13 @@ currencies, while non-joined symbols appearing after the amount refer
to commodities. Here are some valid currency and commodity
specifiers:
-@example
+@smallexample
$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
+@end smallexample
Ledger will examine the first use of any commodity to determine how
that commodity should be printed on reports. It pays attention to
@@ -850,13 +876,15 @@ P 2004/06/21 02:18:02 AAPL $32.91
P 2004/06/21 02:18:02 AU $400.00
@end smallexample
+@findex --price-db @var{FILE}
+@findex --market
Specify the price history to use with the @code{--price-db} option,
-with the @code{-V} option to report in terms of current market
-value:
+with the @code{-V (--market)} option to report in terms of current
+market value:
-@example
-ledger --price-db prices.db -V balance brokerage
-@end example
+@smallexample
+$ ledger --price-db prices.db -V balance brokerage
+@end smallexample
The balance for your brokerage account will be reported in US dollars,
since the prices database uses that currency.
@@ -870,9 +898,9 @@ 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
+@smallexample
+$ ledger -T "@{1 AU@}*(O/P@{1 AU@})" balance checking
+@end smallexample
Although the total expression appears complex, it is simply saying
that the reported total should be in multiples of AU units, where the
@@ -886,8 +914,8 @@ the left value's commodity. The result of this command might be:
@end smallexample
@menu
-* Commodity Price Histories::
-* Commodity equivalencies::
+* Commodity Price Histories::
+* Commodity equivalencies::
@end menu
@node Commodity Price Histories, Commodity equivalencies, Commodities and Currencies, Commodities and Currencies
@@ -929,7 +957,7 @@ will indicate that fifty minutes remain:
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
@@ -955,7 +983,7 @@ C 1.00 Gb = 1024 Mb
C 1.00 Tb = 1024 Gb
@end smallexample
-Each of these definitions correlates a commodity (such as @code{Kb})
+Each of these definitions correlates a commodity (such as @samp{Kb})
and a default precision, with a certain quantity of another commodity.
In the above example, kilobytes are reported with two decimal places
of precision and each kilobyte is equal to 1024 bytes.
@@ -992,8 +1020,8 @@ 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:
+If you later sell some of these items to another player, the
+transaction would look like:
@smallexample
10/2 Sturm Brightblade
@@ -1007,8 +1035,8 @@ 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.
+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
@@ -1108,7 +1136,7 @@ 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
+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.
@@ -1144,16 +1172,17 @@ funds. In this case, you will likely want to mask out your
@code{Assets} account, because otherwise the balance won't make much
sense:
-@example
-ledger bal -^Assets
-@end example
+@smallexample
+$ ledger bal -^Assets
+@end smallexample
+@findex --real
If the @code{--real} option is used, the report will be in terms of
the real accounts:
-@example
-ledger --real bal
-@end example
+@smallexample
+$ ledger --real bal
+@end smallexample
If more asset accounts are needed as the source of a posting, just
list them as you would normally, for example:
@@ -1186,6 +1215,8 @@ 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.
+@findex --code-as-payee
+@findex --by-payee
How does this become a fund report? By using the
@code{--code-as-payee} option, you can generate a register report
where the payee for each posting shows the code. Alone, this is
@@ -1195,29 +1226,29 @@ 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
+$ ledger --code-as-payee -P reg ^Assets
@end smallexample
Or to see a particular funds expenses, the @code{School} fund in this
case:
@smallexample
-ledger --code-as-payee -P reg ^Expenses @@School
+$ 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.
-
+associated with particular transactions. Your own tastes will decide
+which is best for your situation.
-@node Keeping a Journal, Transactions , Principles of Accounting, Top
+@node Keeping a Journal, Transactions, Principles of Accounting, Top
@chapter Keeping a Journal
-The most important part of accounting is keeping a good journal. If you
-have a good journal, tools can be written to work whatever mathematical
-tricks you need to better understand your spending patterns. Without a
-good journal, no tool, however smart, can help you.
+The 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
@@ -1227,8 +1258,8 @@ 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
+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.
@@ -1240,19 +1271,19 @@ 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
+display precision, etc.) based on how you used the commodity in the
posting.
@menu
-* Most Basic Entry::
-* Starting up::
-* Structuring Your Accounts::
-* Commenting on your journal::
-* Currency and Commodities::
-* Keeping it Consistent::
-* Journal Format::
-* Converting from other formats::
-* Archiving Previous Years ::
+* Most Basic Entry::
+* Starting up::
+* Structuring Your Accounts::
+* Commenting on your journal::
+* Currency and Commodities::
+* Keeping it Consistent::
+* Journal Format::
+* Converting from other formats::
+* Archiving Previous Years::
@end menu
@node Most Basic Entry, Starting up, Keeping a Journal, Keeping a Journal
@@ -1268,10 +1299,10 @@ posting, with the additional of a check number:
@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:
+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
@@ -1279,109 +1310,103 @@ balanced amount, if it is the same as the first line:
Assets:Checking
@end smallexample
-For this transaction, Ledger will figure out that $-23.00 must come from
-@code{Assets:Checking} in order to balance the transaction.
+For this transaction, Ledger will figure out that $-23.00 must come
+from @code{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
+hierarchy established by separating with colons (@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
+indent and space out things exactly as shown. The only requirements
+are that the start of the transaction (the date typically) is at the
beginning of the first line of the transaction, and the accounts are
indented by at least one space. If you omit the leading spaces in the
-account lines Ledger will generate an error. There must be at least two
-spaces, or a tab, between the amount and the account. If you do not
-have adequate separation between the amount and the account Ledger will
-give an error and stop calculating.}
-
+account lines Ledger will generate an error. There must be at least
+two spaces, or a tab, between the amount and the account. If you do
+not have adequate separation between the amount and the account Ledger
+will give an error and stop calculating.}
@node Starting up, Structuring Your Accounts, Most Basic Entry, Keeping a Journal
@section Starting up
-
@cindex initial equity
@cindex beginning ledger
+@cindex opening balance
-Unless you have recently arrived from another planet, you already have a
-financial state. You need to capture that financial state so that
+Unless you have recently arrived from another planet, you already have
+a financial state. You need to capture that financial state so that
Ledger has a starting point.
-At some convenient point in time you new the balances and outstanding
+At some convenient point in time you knew 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
+ 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.
+work.
@node Structuring Your Accounts, Commenting on your journal, Starting up, Keeping a Journal
@section Structuring your Accounts
-
@cindex accounts, naming
@cindex naming accounts
+
There really are no requirements for how you do this, but to preserve
your sanity we suggest some very basic structure to your accounting
system.
At the highest level you have five sorts of accounts:
+
@enumerate
-@item
-Expenses: where money goes
-@item
-Assets: where money sits
-@item
-Income: where money comes from
-@item
-Liabilities: money you owe
-@item
-Equity: the real value of your property.
+@item Expenses: where money goes
+@item Assets: where money sits
+@item Income: where money comes from
+@item Liabilities: money you owe
+@item Equity: the real value of your property.
@end enumerate
Starting the structure off this way will make it simpler for you to get
answers to the questions you really need to ask about your finances.
Beneath these top level accounts you can have any level of detail you
-desire. For example, if you want to keep specific track of how much you spend on
-burgers and fries, you could have the following:
+desire. For example, if you want to keep specific track of how much
+you spend on burgers and fries, you could have the following:
+
@smallexample
Expenses:Food:Hamburgers and Fries
@end smallexample
-
@node Commenting on your journal, Currency and Commodities, Structuring Your Accounts, Keeping a Journal
@section Commenting on your Journal
@cindex comments, characters
-Comments are generally started using a ';'. However, in order to
-increase compatibility with other text manipulation programs and methods
-four additional comment characters are valid if used at the beginning
-of a line: @code{#}, @code{|}, and @code{*} and @code{%}.
+
+Comments are generally started using a @samp{;}. However, in order to
+increase compatibility with other text manipulation programs and
+methods four additional comment characters are valid if used at the
+beginning of a line: @samp{#}, @samp{|}, and @samp{*} and @samp{%}.
@cindex block comments
@cindex comments, block
-Block comments can be made by use @code{@!comment} ... @code{@!end comment}
+Block comments can be made by use @code{@!comment} ... @code{@!end
+comment}
@smallexample
-
; This is a single line comment,
# and this,
% and this,
@@ -1395,36 +1420,37 @@ Block comments can be made by use @code{@!comment} ... @code{@!end comment}
@end smallexample
There are several forms of comments within a transaction, for example:
-@smallexample
+@smallexample
; this is a global comment that is not applied to a specific transaction
-; it can start with any of the five characters but is not included in the
+; it can start with any of the five characters but is not included in the
; output from 'print' or 'output'
2011/12/11 Something Sweet
- ; German Chocolate Cake
- ; :Broke Diet:
- Expenses:Food $10.00 ; Friends: The gang
- Assets:Credit Union:Checking
+ ; German Chocolate Cake
+ ; :Broke Diet:
+ Expenses:Food $10.00 ; Friends: The gang
+ Assets:Credit Union:Checking
@end smallexample
-@noindent The first comment is global and Ledger will not attach it to any specific
-transactions. The comments within the transaction must all start with `;'s and are
-preserved as part of the transaction. The `:'s indicate meta-data and tags
-(@pxref{Metadata}).
+@noindent
+The first comment is global and Ledger will not attach it to any
+specific transactions. The comments within the transaction must all
+start with @samp{;} and are preserved as part of the transaction. The
+@samp{:} indicates meta-data and tags (@pxref{Metadata}).
@node Currency and Commodities, Keeping it Consistent, Commenting on your journal, Keeping a Journal
@section Currency and Commodities
-
@cindex currency
@cindex commodity
+
Ledger is agnostic when it comes to how you value your accounts.
Dollars, Euros, Pounds, Francs, Shares etc. are just ``commodities''.
-Holdings in stocks, bonds, mutual funds and other financial instruments
-can be labeled using whatever is convenient for you (stock ticker
-symbols are suggested for publicly traded assets).@footnote{you can
-track ANYTHING, even time or distance traveled. As long as it cannot be
-created or destroyed inside your accounting system.}
+Holdings in stocks, bonds, mutual funds and other financial
+instruments can be labeled using whatever is convenient for you (stock
+ticker symbols are suggested for publicly traded assets).@footnote{You
+can track @emph{anything}, even time or distance traveled. As long as
+it cannot be created or destroyed inside your accounting system.}
For the rest of this manual, we will only use the word ``commodities''
when referring to the units on a transaction value.
@@ -1432,12 +1458,13 @@ when referring to the units on a transaction value.
This is fundamentally different than many common accounting packages,
which assume the same currency throughout all of your accounts. This
means if you typically operate in Euros, but travel to the US and have
-some expenses, you would have to do the currency conversion BEFORE you
-made the entry into your financial system. With ledger this is not
-required. In the same journal you can have entries in any or all
-commodities you actually hold. You can use the reporting capabilities
-to convert all commodities to a single commodity for reporting purposes
-without ever changing the underlying entry.
+some expenses, you would have to do the currency conversion
+@emph{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:
@@ -1452,13 +1479,14 @@ business trip to Europe from the US:
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.
+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
+$ ledger -f example.dat bal
$-66.00
E15.00 Assets
E15.00 Cash
@@ -1469,35 +1497,35 @@ $ ledger -f example.dat bal
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.
+The top two lines show my current assets as $-66.00 in checking (in
+this very short example I didn't establish opening an opening balance
+for the checking account) and E15.00. After spending on dinner I have
+E15.00 in my wallet. The bottom line balances to zero, but is shown
+in two lines since we haven't told ledger to convert commodities.
@menu
-* Naming Commodities::
-* Buying and Selling Stock::
-* Fixing Lot Prices::
-* Complete control over commodity pricing::
+* Naming Commodities::
+* Buying and Selling Stock::
+* Fixing Lot Prices::
+* Complete control over commodity pricing::
@end menu
@node Naming Commodities, Buying and Selling Stock, Currency and Commodities, Currency and Commodities
@subsection Naming Commodities
-Commodity names can have any character, including white-space. However,
-if you include white-space or numeric characters the commodity name must
-be enclosed in double quotes:
-@smallexample
-1999/06/09 ! Achat
- Actif:SG PEE STK 49.957 "Arcancia Equilibre 454"
- Actif:SG PEE STK $-234.90
-
-2000/12/08 ! Achat
- Actif:SG PEE STK 215.796 "Arcancia Equilibre 455"
- Actif:SG PEE STK $-10742.54
-@end smallexample
+Commodity names can have any character, including white-space.
+However, if you include white-space or numeric characters the
+commodity name must be enclosed in double quotes @samp{"}:
+@smallexample
+1999/06/09 ! Achat
+ Actif:SG PEE STK 49.957 "Arcancia Équilibre 454"
+ Actif:SG PEE STK $-234.90
+
+2000/12/08 ! Achat
+ Actif:SG PEE STK 215.796 "Arcancia Équilibre 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
@@ -1505,132 +1533,149 @@ be enclosed in double quotes:
Buying stock is a typical example that many will use that involves
multiple commodities in the same transaction. The type of the share
-(AAPL for Apple Inc.) and the share purchase price in the currency unit
-you made the purchase in ($ for AAPL). Yes, the typical convention is as follows:
+(AAPL for Apple Inc.) and the share purchase price in the currency
+unit you made the purchase in ($ for AAPL). Yes, the typical
+convention is as follows:
@smallexample
- 2004/05/01 Stock purchase
- Assets:Broker 50 AAPL @@ $30.00
- Expenses:Broker:Commissions $19.95
- Assets:Broker $-1,500.00
+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
+
+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
+2005/08/01 Stock sale
+ Assets:Broker -50 APPL @{$30.00@} @@ $50.00
+ Expenses:Broker:Commissions $19.95
+ Income:Capital Gains $-1,000.00
+ Assets:Broker $2,500.00
@end smallexample
-@noindent You can, of course, elide the amount of the last posting. It is there
+@noindent
+You can, of course, elide the amount of the last posting. It is there
for clarity's sake.
-The @{$30.00@} is a lot price. You can also use a lot date,
-[2004/05/01], or both, in case you have several lots of the same
-price/date and your taxation model is based on longest-held-first.
+The @samp{@{$30.00@}} is a lot price. You can also use a lot date,
+@samp{[2004/05/01]}, or both, in case you have several lots of the
+same price/date and your taxation model is based on
+longest-held-first.
@node Fixing Lot Prices, Complete control over commodity pricing, Buying and Selling Stock, Currency and Commodities
@subsection Fixing Lot Prices
@cindex fixing lot prices
@cindex consumable commodity pricing
-Commodities that you keep in order to sell them at a later time have a
-variable value that fluctuates with the market prices. Commodities that
-you consume should not fluctuate in value, but stay at the lot price
-they were purchased at. As an extension of ``lot pricing'', you can fix
-the per-unit price of a commodity.
+
+Commodities that you keep in order to sell them at a later time have
+a variable value that fluctuates with the market prices. Commodities
+that you consume should not fluctuate in value, but stay at the lot
+price they were purchased at. As an extension of ``lot pricing'', you
+can fix the per-unit price of a commodity.
For example, say you buy 10 gallons of gas at $1.20. In future
``value'' reports, you don't want these gallons reported in terms of
today's price, but rather the price when you bought it. At the same
-time, you also want other kinds of commodities -- like stocks --
+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
+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.
+This transaction actually introduces a new commodity, @samp{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 sign
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
- 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
+
+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
+2009/01/01 Shell
+ Expenses:Gasoline 11 GAL @{=$2.299@} @@ $2.30
+ Assets:Checking
@end smallexample
-This transaction says that you bought 11 gallons priced at $2.299 per
-gallon at a @strong{cost to you} of $2.30 per gallon. Ledger auto-generates
-a balance posting in this case to Equity:Capital Losses to reflect the
-1.1 cent difference, which is then balanced by Assets:Checking because
-its amount is null.
+This transaction says that you bought 11 gallons priced at $2.299 per
+gallon at a @emph{cost to you} of $2.30 per gallon. Ledger
+auto-generates a balance posting in this case to Equity:Capital Losses
+to reflect the 1.1 cent difference, which is then balanced by
+Assets:Checking because its amount is null.
@node Complete control over commodity pricing, , Fixing Lot Prices, Currency and Commodities
@subsection Complete control over commodity pricing
+@findex --market
+@findex --exchange @var{COMMODITY}
Ledger allows you to have very detailed control over how your
commodities are valued. You can fine tune the results given using the
-@code{--market} or @code{--exchange} options. There are now several
-points of interception, you can specify the valuation method:
+@code{--market} or @code{--exchange @var{COMMODITY}} options. There
+are now several points of interception, you can specify the valuation
+method:
+
@enumerate
- @item on a commodity itself
- @item on a posting, via metadata (affect is largely the same as #1)
- @item on an xact, which then applies to all postings in that xact
- @item on any posting via an automated transaction
- @item on a per-account basis
- @item on a per-commodity basis
- @item by changing the journal default of @code{market}
+@item on a commodity itself
+@item on a posting, via metadata (affect is largely the same as #1)
+@item on an xact, which then applies to all postings in that xact
+@item on any posting via an automated transaction
+@item on a per-account basis
+@item on a per-commodity basis
+@item by changing the journal default of @code{market}
@end enumerate
-Fixated pricing (such as @code{@{=$20@})} still plays a role in this scheme. As far as
-valuation goes, it's shorthand for writing @code{((s,d,t -> market($20,d,t)))}.
-
+Fixated pricing (such as @samp{@{=$20@}}) still plays a role in this
+scheme. As far as valuation goes, it's shorthand for writing
+@samp{((s,d,t -> market($20,d,t)))}.
A valuation function receives three arguments:
@table @code
@item source
- A string identifying the commodity whose price is being asked for
- (example: "EUR")
+A string identifying the commodity whose price is being asked for
+(example: @samp{EUR})
+
@item date
- The reference date the price should be relative.
-@item target
+The reference date the price should be relative.
+
+@item target
A string identifying the ``target'' commodity, or the commodity the
- returned price should be in. This argument is null if @code{--market}
- was used instead of @code{--exchange}.
+returned price should be in. This argument is null if @code{--market}
+was used instead of @code{--exchange @var{COMMODITY}}.
@end table
-The valuation function should return an amount. If you've written your
-function in Python, you can return something like @code{Amount("$100")}. If the
-function returns an explicit value, that value is always used, regardless
-of the commodity, the date, or the desired target commodity. For example,
+The valuation function should return an amount. If you've written
+your function in Python, you can return something like
+@samp{Amount("$100")}. If the function returns an explicit value,
+that value is always used, regardless of the commodity, the date, or
+the desired target commodity. For example,
@smallexample
define myfunc_seven(s, d, t) = 7 EUR
@end smallexample
-In order to specify a fixed price, but still valuate that price into the
-target commodity, use something like this:
+In order to specify a fixed price, but still valuate that price into
+the target commodity, use something like this:
+
@smallexample
define myfunc_five(s, d, t) = market(5 EUR, d, t)
@end smallexample
@@ -1638,12 +1683,14 @@ define myfunc_five(s, d, t) = market(5 EUR, d, t)
The @code{value} directive sets the valuation used for all commodities
used in the rest of the data stream. This is the fallback, if nothing
more specific is found.
+
@smallexample
value myfunc_seven
@end smallexample
You can set a specific valuation function on a per-commodity basis.
Instead of defining a function, you can also pass a lambda.
+
@smallexample
commodity $
value s, d, t -> 6 EUR
@@ -1657,8 +1704,8 @@ account Expenses:Food5
value myfunc_five
@end smallexample
-The metadata field @code{Value}, if found, overrides the valuation function
-on a transaction-wide or per-posting basis.
+The metadata field @code{Value}, if found, overrides the valuation
+function on a transaction-wide or per-posting basis.
@smallexample
= @@XACT and Food
@@ -1671,7 +1718,7 @@ on a transaction-wide or per-posting basis.
@end smallexample
Lastly, you can specify the valuation function/value for any specific
-amount using the @code{(( ))} commodity annotation.
+amount using the @samp{(( ))} commodity annotation.
@smallexample
2012-03-02 KFC
@@ -1709,7 +1756,6 @@ amount using the @code{(( ))} commodity annotation.
Assets:Cash9
@end smallexample
-
@smallexample
ledger reg -V food
12-Mar-02 KFC Expenses:Food2 2 EUR 2 EUR
@@ -1726,9 +1772,9 @@ ledger reg -V food
12-Mar-09 POST (Expenses:Food9) 9 EUR 34 EUR
@end smallexample
-
@node Keeping it Consistent, Journal Format, Currency and Commodities, Keeping a Journal
@section Keeping it Consistent
+@findex --strict
Sometimes Ledger's flexibility can lead to difficulties. Using a
freeform text editor to enter transactions makes it easy to keep the
@@ -1736,27 +1782,34 @@ data, but also easy to enter accounts or payees inconsistently or with
spelling errors.
In order to combat inconsistency you can define allowable accounts and
-or payees. For simplicity, create a separate text file and enter define
-accounts a payees like
+or payees. For simplicity, create a separate text file and enter
+define accounts a payees like
+
@smallexample
account Expenses
account Expenses:Utilities
...
@end smallexample
-Using the @code{--strict} option will cause Ledger to complain if any accounts are not previously defined:
+
+Using the @option{--strict} option will cause Ledger to complain if any
+accounts are not previously defined:
+
@smallexample
-15:27:39 ~/ledger (next) > ledger bal --strict
+$ ledger bal --strict
Warning: "FinanceData/Master.dat", line 6: Unknown account 'Liabilities:Tithe Owed'
Warning: "FinanceData/Master.dat", line 8: Unknown account 'Liabilities:Tithe Owed'
Warning: "FinanceData/Master.dat", line 15: Unknown account 'Allocation:Equities:Domestic'
@end smallexample
-If you have a large Ledger register already created use the @code{accounts} command to get started:
+If you have a large Ledger register already created use the
+@code{accounts} command to get started:
+
@smallexample
-ledger accounts >> Accounts.dat
+$ ledger accounts >> Accounts.dat
@end smallexample
-@noindent You will have to edit this file to add the @code{account} directive.
+@noindent
+You will have to edit this file to add the @code{account} directive.
@node Journal Format, Converting from other formats, Keeping it Consistent, Keeping a Journal
@section Journal Format
@@ -1766,38 +1819,40 @@ supports many options, though typically the user can ignore most of
them. They are summarized below.
@menu
-* Transaction and Comments::
-* Command Directives::
+* Transaction and Comments::
+* Command Directives::
@end menu
@node Transaction and Comments, Command Directives, Journal Format, Journal Format
@subsection Transactions and Comments
+
The initial character of each line determines what the line means, and
how it should be interpreted. Allowable initial characters are:
@table @code
@item NUMBER
-A line beginning with a number denotes a transaction. It may be followed
-by any number of lines, each beginning with white-space, to denote the
-transaction's account postings. The format of the first line is:
+A line beginning with a number denotes a transaction. It may be
+followed by any number of lines, each beginning with white-space, to
+denote the transaction's account postings. The format of the first
+line is:
@smallexample
DATE[=EDATE] [*|!] [(CODE)] DESC
@end smallexample
-If @code{*} 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 @code{!} 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 @code{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.
+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 the transaction is ``pending''; i.e., tentatively cleared
+from the user's point of view, but not yet actually cleared. If
+a @code{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]
+ACCOUNT AMOUNT [; NOTE]
@end smallexample
The @code{ACCOUNT} may be surrounded by parentheses if it is a virtual
@@ -1807,24 +1862,26 @@ posting cost, by specifying @code{@@ AMOUNT}, or a complete
posting cost with @code{@@@@ AMOUNT}. Lastly, the @code{NOTE} may
specify an actual and/or effective date for the posting by using
the syntax @code{[ACTUAL_DATE]} or @code{[=EFFECTIVE_DATE]} or
-@code{[ACTUAL_DATE=EFFECTIVE_DATE]}.(See @pxref{Virtual postings})
+@code{[ACTUAL_DATE=EFFECTIVE_DATE]} (@pxref{Virtual postings}).
@item P
Specifies a historical price for a commodity. These are usually found
in a pricing history file (see the @code{-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.
+An automated transaction. A value expression must appear after the
+equal sign.
-After this initial line there should be a set of one or more
-postings, just as if it were normal transaction. If the amounts of the
-postings have no commodity, they will be applied as modifiers to
-whichever real posting is matched by the value expression(See @pxref{Automated Transactions}).
+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 (@pxref{Automated
+Transactions}).
@item ~
A period transaction. A period expression must appear after the tilde.
@@ -1833,10 +1890,11 @@ 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 ;
+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
@@ -1845,14 +1903,15 @@ Ledger.
@node Command Directives, , Transaction and Comments, Journal Format
@subsection Command Directives
+@findex --strict
+@findex --pedantic
@table @code
@item beginning of line
-Command directives must occur at the beginning of a line. Use of ! and
-@@ is deprecated.
+Command directives must occur at the beginning of a line. Use of
+@samp{!} and @samp{@@} is deprecated.
@item account
-
Pre-declare valid account names. This only has effect if
@code{--strict} or @code{--pedantic} is used (see below). The
@code{account} directive supports several optional sub-directives, if
@@ -1860,53 +1919,57 @@ they immediately follow the account directive and if they begin with
whitespace:
@smallexample
- account Expenses:Food
- note This account is all about the chicken!
- alias food
- payee ^(KFC|Popeyes)$
- check commodity == "$"
- assert commodity == "$"
- eval print("Hello!")
- default
+account Expenses:Food
+ note This account is all about the chicken!
+ alias food
+ payee ^(KFC|Popeyes)$
+ check commodity == "$"
+ assert commodity == "$"
+ eval print("Hello!")
+ default
@end smallexample
-The @code{note} sub-directive associates a textual note with the account. This can
-be accessed later using the @code{note} valexpr function in any account context.
+The @code{note} sub-directive associates a textual note with the
+account. This can be accessed later using the @code{note} valexpr
+function in any account context.
-The @code{alias} sub-directive, which can occur multiple times, allows the alias to
-be used in place of the full account name anywhere that account names are
-allowed.
+The @code{alias} sub-directive, which can occur multiple times, allows
+the alias to be used in place of the full account name anywhere that
+account names are allowed.
-The @code{payee} sub-directive, which can occur multiple times, provides regexps
-that identify the account if that payee is encountered and an account within
-its transaction ends in the name "Unknown". Example:
+The @code{payee} sub-directive, which can occur multiple times,
+provides regexps that identify the account if that payee is
+encountered and an account within its transaction ends in the name
+"Unknown". Example:
@smallexample
- 2012-02-27 KFC
- Expenses:Unknown $10.00 ; Read now as "Expenses:Food"
- Assets:Cash
+2012-02-27 KFC
+ Expenses:Unknown $10.00 ; Read now as "Expenses:Food"
+ Assets:Cash
@end smallexample
-The @code{check} and @code{assert} directives warn or error (respectively) if the given
-value expression evaluates to false within the context of any posting.
+The @code{check} and @code{assert} directives warn or error
+(respectively) if the given value expression evaluates to false within
+the context of any posting.
-The @code{eval} directive evaluates the value expression in the context of the
-account at the time of definition. At the moment this has little value.
+The @code{eval} directive evaluates the value expression in the
+context of the account at the time of definition. At the moment this
+has little value.
-The @code{default} directive specifies that this account should be used as the
-``balancing account'' for any future transactions that contain only a single
-posting.
+The @code{default} directive specifies that this account should be
+used as the ``balancing account'' for any future transactions that
+contain only a single posting.
@item apply account
@c instance_t::master_account_directive
-Sets the root for all accounts following the directive. Ledger supports
-a hierarchical tree of accounts. It may be convenient to keep two
-``root accounts''. For example you may be tracking your personal
-finances and your business finances. In order to keep them separate you
-could preface all personal accounts with @code{personal:} and all
-business account with @code{business:}. You can easily split out large
-groups of transaction without manually editing them using the account
-directive. For example:
+Sets the root for all accounts following the directive. Ledger
+supports a hierarchical tree of accounts. It may be convenient to
+keep two ``root accounts''. For example you may be tracking your
+personal finances and your business finances. In order to keep them
+separate you could preface all personal accounts with @code{personal:}
+and all business account with @code{business:}. You can easily split
+out large groups of transaction without manually editing them using
+the account directive. For example:
@smallexample
apply account Personal
@@ -1916,59 +1979,58 @@ apply account Personal
@end smallexample
Would result in all postings going into
-@code{Personal:Expenses:Groceries} and @code{Personal:Assets:hecking}
-until and @code{end apply account} directive was found.
+@code{Personal:Expenses:Groceries} and @code{Personal:Assets:Checking}
+until and @code{end apply account} directive was found.
@item alias
@c instance_t::alias_directive
Define an alias for an account name. If you have a deeply nested tree
of accounts, it may be convenient to define an alias, for example:
-@smallexample
+@smallexample
alias Dining=Expenses:Entertainment:Dining
alias Checking=Assets:Credit Union:Joint Checking Account
-2011/11/28 YummyPalace
- Dining $10.00
- Checking
+2011/11/28 YummyPalace
+ Dining $10.00
+ Checking
@end smallexample
The aliases are only in effect for transactions read in after the alias
is defined and are effected by @code{account} directives that precede
them.
+
@item assert
@c instance_t::assert_directive
-An assertion can throw an error if a condition is not met during Ledger's run.
+An assertion can throw an error if a condition is not met during
+Ledger's run.
@smallexample
-
assert <VALUE EXPRESSION BOOLEAN RESULT>
-
@end smallexample
-
@item bucket
@c instance_t::default_account_directive
Defines the default account to use for balancing transactions.
-Normally, each transaction has at least two postings, which must balance
-to zero. Ledger allows you to leave one posting with no amount and
-automatically calculate balance the transaction in the posting. The
-@code{bucket} allows you to fill in all postings and automatically
-generate an additional posting to the bucket account balancing the
-transaction. The following example set the @code{Assets:Checking} as
-the bucket:
-@smallexample
+Normally, each transaction has at least two postings, which must
+balance to zero. Ledger allows you to leave one posting with no
+amount and automatically calculate balance the transaction in the
+posting. The @code{bucket} allows you to fill in all postings and
+automatically generate an additional posting to the bucket account
+balancing the transaction. The following example set the
+@code{Assets:Checking} as the bucket:
+@smallexample
bucket Assets:Checking
2011/01/25 Tom's Used Cars
- Expenses:Auto $ 5,500.00
+ Expenses:Auto $ 5,500.00
2011/01/27 Book Store
- Expenses:Books $20.00
+ Expenses:Books $20.00
2011/12/01 Sale
- Assets:Checking:Business $ 30.00
+ Assets:Checking:Business $ 30.00
@end smallexample
@@ -1981,83 +2043,87 @@ account. For example:
capture Expenses:Deductible:Medical Medical
@end smallexample
-Would cause any posting with @code{Medical} in its name to be replaced with
-@code{Expenses:Deductible:Medical}.
-
+Would cause any posting with @code{Medical} in its name to be replaced
+with @code{Expenses:Deductible:Medical}.
Ledger will display the mapped payees in @code{print} and
@code{register} reports.
@item check
@c instance_t::check_directive in textual.cc
-A check can issue a warning if a condition is not met during Ledger's run.
+A check can issue a warning if a condition is not met during Ledger's
+run.
@smallexample
-
check <VALUE EXPRESSION BOOLEAN RESULT>
-
@end smallexample
+
@item comment
@c instance_t::comment_directive in textual.cc
Start a block comment, closed by @code{end comment}.
@item commodity
-Pre-declare commodity names. This only has effect if @code{--strict} or
-@code{--pedantic} is used (see below).
+Pre-declare commodity names. This only has effect if @code{--strict}
+or @code{--pedantic} is used (see below).
commodity $
commodity CAD
-The @code{commodity} directive supports several optional sub-directives, if they
-immediately follow the commodity directive and if they begin with whitespace:
+The @code{commodity} directive supports several optional
+sub-directives, if they immediately follow the commodity directive and
+if they begin with whitespace:
@smallexample
- commodity $
+commodity $
note American Dollars
format $1,000.00
nomarket
default
@end smallexample
-The @code{note} sub-directive associates a textual note with the commodity. At
-present this has no value other than documentation.
+The @code{note} sub-directive associates a textual note with the
+commodity. At present this has no value other than documentation.
-The @code{format} directive gives you a way to tell Ledger how to format this
-commodity. In future using this directive will disable Ledger's observation
-of other ways that commodity is used, and will provide the ``canonical''
-representation.
+The @code{format} directive gives you a way to tell Ledger how to
+format this commodity. In future using this directive will disable
+Ledger's observation of other ways that commodity is used, and will
+provide the ``canonical'' representation.
-The @code{nomarket} directive states that the commodity's price should never be
-auto-downloaded.
+The @code{nomarket} directive states that the commodity's price should
+never be auto-downloaded.
The @code{default} directive marks this as the ``default'' commodity.
@item define
@c instance_t::define_directive in textual.cc
Allows you to define value expression for future use. For example:
+
@smallexample
define var_name=$100
2011/12/01 Test
- Expenses (var_name*4)
- Assets
+ Expenses (var_name*4)
+ Assets
@end smallexample
The posting will have a cost of $400.
+
@item end
@c instance_t::end_directive in textual.cc
Closes block commands like @code{tag} or @code{comment}.
+
@item expr
@c instance_t::expr_directive in textual.cc
@item fixed
@c instance_t::fixed_directive in textual.cc
-A fixed block is used to set fixated prices (@pxref{Fixated prices}) for a series of
-transactions. It's purely a typing saver, for use when entering many
-transactions with fixated prices.
+A fixed block is used to set fixated prices (@pxref{Fixated prices})
+for a series of transactions. It's purely a typing saver, for use
+when entering many transactions with fixated prices.
Thus, the following:
+
@smallexample
fixed CAD $0.90
2012-04-10 Lunch in Canada
@@ -2069,20 +2135,22 @@ fixed CAD $0.90
Expenses:Food 25.75 CAD
endfixed
@end smallexample
+
is equivalent to this:
+
@smallexample
- 2012-04-10 Lunch in Canada
- Assets:Wallet -15.50 CAD @{=$0.90@}
- Expenses:Food 15.50 CAD @{=$0.90@}
+2012-04-10 Lunch in Canada
+ Assets:Wallet -15.50 CAD @{=$0.90@}
+ Expenses:Food 15.50 CAD @{=$0.90@}
- 2012-04-11 Second day Dinner in Canada
- Assets:Wallet -25.75 CAD @{=$0.90@}
- Expenses:Food 25.75 CAD @{=$0.90@}
+2012-04-11 Second day Dinner in Canada
+ Assets:Wallet -25.75 CAD @{=$0.90@}
+ Expenses:Food 25.75 CAD @{=$0.90@}
@end smallexample
Note that ending a @code{fixed} is done differently than other
directives, as @code{fixed} is closed with an @code{endfixed} (i.e.,
-there is @strong{no space} between @code{end} and @code{fixed}).
+there is @emph{no space} between @code{end} and @code{fixed}).
For the moment, users may wish to study
@uref{http://bugs.ledger-cli.org/show_bug.cgi?id=789, Bug Report 789}
@@ -2094,20 +2162,21 @@ Include the stated file as if it were part of the current file.
@item payee
@c instance_t::payee_mapping_directive in textual.cc
-The @code{payee} directive supports one optional sub-directive, if it immediately
-follows the payee directive and if it begins with whitespace:
+The @code{payee} directive supports one optional sub-directive, if it
+immediately follows the payee directive and if it begins with
+whitespace:
@smallexample
- payee KFC
- alias KENTUCKY FRIED CHICKEN
+payee KFC
+ alias KENTUCKY FRIED CHICKEN
@end smallexample
-The @code{alias} directive provides a regexp which, if it matches a parsed payee,
-the declared payee name is substituted:
+The @code{alias} directive provides a regexp which, if it matches
+a parsed payee, the declared payee name is substituted:
@smallexample
- 2012-02-27 KENTUCKY FRIED CHICKEN ; will be read as being 'KFC'
- ...
+2012-02-27 KENTUCKY FRIED CHICKEN ; will be read as being 'KFC'
+...
@end smallexample
Ledger will display the mapped payees in @code{print} and
@@ -2115,119 +2184,130 @@ Ledger will display the mapped payees in @code{print} and
@item apply tag
@c instance_t::tag_directive in textual.cc
-Allows you to designate a block of transactions and assign the same tag to all. Tags can have values and may be nested.
+Allows you to designate a block of transactions and assign the same
+tag to all. Tags can have values and may be nested.
+
@smallexample
apply tag hastag
apply tag nestedtag: true
+
2011/01/25 Tom's Used Cars
- Expenses:Auto $ 5,500.00
- ; :nobudget:
- Assets:Checking
+ Expenses:Auto $ 5,500.00
+ ; :nobudget:
+ Assets:Checking
2011/01/27 Book Store
- Expenses:Books $20.00
- Liabilities:MasterCard
+ Expenses:Books $20.00
+ Liabilities:MasterCard
end apply tag nestedtag
2011/12/01 Sale
- Assets:Checking:Business $ 30.00
- Income:Sales
+ Assets:Checking:Business $ 30.00
+ Income:Sales
+
end apply tag hastag
@end smallexample
-@noindent is the equivalent of
+@noindent
+is the equivalent of
@smallexample
2011/01/25 Tom's Used Cars
- :hastag:
- nestedtag: true
- Expenses:Auto $ 5,500.00
- ; :nobudget:
- Assets:Checking
+ :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
+ :hastag:
+ nestedtag: true
+ Expenses:Books $20.00
+ Liabilities:MasterCard
2011/12/01 Sale
- :hastag:
- Assets:Checking:Business $ 30.00
- Income:Sales
+ :hastag:
+ Assets:Checking:Business $ 30.00
+ Income:Sales
@end smallexample
-Note that anything following ``@code{end tag}'' is ignored. placing the
-name of the tag that is being closed is a simple way to keep track.
+Note that anything following ``@code{end tag}'' is ignored. placing
+the name of the tag that is being closed is a simple way to keep
+track.
@item tag
Pre-declares tag names. This only has effect if @code{--strict} or
@code{--pedantic} is used (see below).
@smallexample
- tag Receipt
- tag CSV
+tag Receipt
+tag CSV
@end smallexample
-The 'tag' directive supports two optional sub-directives, if they immediately
-follow the tag directive and if they begin with whitespace:
+The @code{tag} directive supports two optional sub-directives, if they
+immediately follow the tag directive and if they begin with
+whitespace:
@smallexample
- tag Receipt
- check value =~ /pattern/
- assert value != "foobar"
+tag Receipt
+ check value =~ /pattern/
+ assert value != "foobar"
@end smallexample
-The @code{check} and @code{assert} directives warn or error (respectively) if the given
-value expression evaluates to false within the context of any use of the
-related tag. In such a context, ``value'' is bound to the value of the tag
-(which may not be a string if typed-metadata is used!). Such checks or
-assertions are not called if no value is given.
+The @code{check} and @code{assert} directives warn or error
+(respectively) if the given value expression evaluates to false within
+the context of any use of the related tag. In such a context,
+``value'' is bound to the value of the tag (which may not be a string
+if typed-metadata is used!). Such checks or assertions are not called
+if no value is given.
@item test
@c instance_t::comment_directive in textual.cc
-This is a synonym for @code{comment} and must be closed by an @code{end} tag.
+This is a synonym for @code{comment} and must be closed by an
+@code{end} tag.
@item year
@c instance_t::year_directive in textual.cc
Denotes the year used for all subsequent transactions that give a date
-without a year. The year should appear immediately after the directive, for
-example: @code{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.
+without a year. The year should appear immediately after the
+directive, for example: @code{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 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
+with a home currency, such as the dollar @samp{$}. 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:
+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
@@ -2236,6 +2316,7 @@ D $1,000.00
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
@@ -2246,49 +2327,53 @@ timelog files. See the timeclock's documentation for more info on the
syntax of its timelog files.
@end table
-@node Converting from other formats, Archiving Previous Years , Journal Format, Keeping a Journal
+@node Converting from other formats, Archiving Previous Years, Journal Format, Keeping a Journal
@section Converting from other formats
+
There are numerous tools to help convert various formats to a Ledger
file. Most banks will generate a commas separated value file that can
-easily be parsed into Ledger format using one of those tools. Some of the more popular tools are:
+easily be parsed into Ledger format using one of those tools. Some of
+the more popular tools are:
+
@itemize
@item @code{icsv2ledger}
@item @code{csvToLedger}
@item @code{CSV2Ledger}
@end itemize
-@noindent Directly pulling information from banks is outside the scope of Ledger's
-function.
+@noindent
+Directly pulling information from banks is outside the scope of
+Ledger's function.
-@node Archiving Previous Years , , Converting from other formats, Keeping a Journal
+@node Archiving Previous Years, , Converting from other formats, 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
+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}.
+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}:
+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
+$ 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
+$ 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
@@ -2298,10 +2383,10 @@ 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
+$ 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
@@ -2319,180 +2404,192 @@ 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 Transactions , Building Reports, Keeping a Journal, Top
-@chapter Transactions
+@node Transactions, Building Reports, Keeping a Journal, Top
+@chapter Transactions
+
@menu
-* Basic format::
-* Eliding amounts::
-* Auxiliary dates::
-* Codes::
-* Transaction state::
-* Transaction notes::
-* Metadata::
-* Virtual postings::
-* Expression amounts::
-* Balance verification::
-* Posting cost::
-* Explicit posting costs::
-* Posting cost expressions::
-* Total posting costs::
-* Virtual posting costs::
-* Commodity prices::
-* Prices vs. costs::
-* Fixated prices::
-* Lot dates::
-* Lot notes::
-* Lot value expressions::
-* Automated Transactions::
+* Basic format::
+* Eliding amounts::
+* Auxiliary dates::
+* Codes::
+* Transaction state::
+* Transaction notes::
+* Metadata::
+* Virtual postings::
+* Expression amounts::
+* Balance verification::
+* Posting cost::
+* Explicit posting costs::
+* Posting cost expressions::
+* Total posting costs::
+* Virtual posting costs::
+* Commodity prices::
+* Prices vs. costs::
+* Fixated prices::
+* Lot dates::
+* Lot notes::
+* Lot value expressions::
+* Automated Transactions::
@end menu
-@node Basic format, Eliding amounts, Transactions , Transactions
+@node Basic format, Eliding amounts, Transactions, Transactions
@section Basic format
-
The most basic form of transaction is:
@smallexample
- 2012-03-10 KFC
- Expenses:Food $20.00
- Assets:Cash $-20.00
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Assets:Cash $-20.00
@end smallexample
-This transaction has a date, a payee or description, a target account (the
-first posting), and a source account (the second posting). Each posting
-specifies what action is taken related to that account.
+This transaction has a date, a payee or description, a target account
+(the first posting), and a source account (the second posting). Each
+posting specifies what action is taken related to that account.
A transaction can have any number of postings:
@smallexample
- 2012-03-10 KFC
- Expenses:Food $20.00
- Assets:Cash $-10.00
- Liabilities:Credit $-10.00
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Assets:Cash $-10.00
+ Liabilities:Credit $-10.00
@end smallexample
@node Eliding amounts, Auxiliary dates, Basic format, Transactions
-@section Eliding amounts
+@section Eliding amounts
-The first thing you can do to make things easier is elide amounts. That is,
-if exactly one posting has no amount specified, Ledger will infer the inverse
-of the other postings' amounts:
+The first thing you can do to make things easier is elide amounts.
+That is, if exactly one posting has no amount specified, Ledger will
+infer the inverse of the other postings' amounts:
@smallexample
- 2012-03-10 KFC
- Expenses:Food $20.00
- Assets:Cash $-10.00
- Liabilities:Credit ; same as specifying $-10
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Assets:Cash $-10.00
+ Liabilities:Credit ; same as specifying $-10
@end smallexample
-@noindent If the other postings use multiple commodities, Ledger will copy the empty
-posting N times and fill in the negated values of the various commodities:
+@noindent
+If the other postings use multiple commodities, Ledger will copy the
+empty posting N times and fill in the negated values of the various
+commodities:
@smallexample
- 2012-03-10 KFC
- Expenses:Food $20.00
- Expenses:Tips $2.00
- Assets:Cash EUR -10.00
- Assets:Cash GBP -10.00
- Liabilities:Credit
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Expenses:Tips $2.00
+ Assets:Cash EUR -10.00
+ Assets:Cash GBP -10.00
+ Liabilities:Credit
@end smallexample
-@noindent This transaction is identical to writing:
+@noindent
+This transaction is identical to writing:
@smallexample
- 2012-03-10 KFC
- Expenses:Food $20.00
- Expenses:Tips $2.00
- Assets:Cash EUR -10.00
- Assets:Cash GBP -10.00
- Liabilities:Credit $-22.00
- Liabilities:Credit EUR 10.00
- Liabilities:Credit GBP 10.00
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Expenses:Tips $2.00
+ Assets:Cash EUR -10.00
+ Assets:Cash GBP -10.00
+ Liabilities:Credit $-22.00
+ Liabilities:Credit EUR 10.00
+ Liabilities:Credit GBP 10.00
@end smallexample
@node Auxiliary dates, Codes, Eliding amounts, Transactions
@section Auxiliary dates
+@findex --aux-date
-You can associate a second date with a transaction by following the primary
-date with an equals sign:
+You can associate a second date with a transaction by following the
+primary date with an equals sign:
@smallexample
- 2012-03-10=2012-03-08 KFC
- Expenses:Food $20.00
- Assets:Cash $-20.00
+2012-03-10=2012-03-08 KFC
+ Expenses:Food $20.00
+ Assets:Cash $-20.00
@end smallexample
-What this auxiliary date means is entirely up to you. The only use Ledger has
-for it is that if you specify --aux-date, then all reports and calculations
-(including pricing) will use the aux date as if it were the primary date.
+What this auxiliary date means is entirely up to you. The only use
+Ledger has for it is that if you specify @code{--aux-date}, then all
+reports and calculations (including pricing) will use the aux date as
+if it were the primary date.
@node Codes, Transaction state, Auxiliary dates, Transactions
@section Codes
-A transaction can have a textual "code". This has no meaning and is only
-displayed by the print command. Checking accounts often use codes like DEP,
-XFER, etc., as well as check numbers. This is to give you a place to put
-those codes:
+A transaction can have a textual ``code''. This has no meaning and is
+only displayed by the print command. Checking accounts often use
+codes like DEP, XFER, etc., as well as check numbers. This is to give
+you a place to put those codes:
@smallexample
- 2012-03-10 (#100) KFC
- Expenses:Food $20.00
- Assets:Checking
+2012-03-10 (#100) KFC
+ Expenses:Food $20.00
+ Assets:Checking
@end smallexample
@node Transaction state, Transaction notes, Codes, Transactions
@section Transaction state
+@findex --cleared
+@findex --uncleared
+@findex --pending
-A transaction can have a ``state'': cleared, pending, or uncleared. The default
-is uncleared. To mark a transaction cleared, put a * before the payee, and
-after date or code:
+A transaction can have a ``state'': cleared, pending, or uncleared.
+The default is uncleared. To mark a transaction cleared, put a *
+before the payee, and after date or code:
@smallexample
- 2012-03-10 * KFC
- Expenses:Food $20.00
- Assets:Cash
+2012-03-10 * KFC
+ Expenses:Food $20.00
+ Assets:Cash
@end smallexample
-@noindent To mark it pending, use a !:
+@noindent
+To mark it pending, use a !:
@smallexample
- 2012-03-10 ! KFC
- Expenses:Food $20.00
- Assets:Cash
+2012-03-10 ! KFC
+ Expenses:Food $20.00
+ Assets:Cash
@end smallexample
-What these mean is entirely up to you. The --cleared option will limits to
-reports to only cleared items, while --uncleared shows both uncleared and
-pending items, and --pending shows only pending items.
+What these mean is entirely up to you. The @code{--cleared} option
+will limits to reports to only cleared items, while @code{--uncleared}
+shows both uncleared and pending items, and @code{--pending} shows
+only pending items.
-I use cleared to mean that I've reconciled the transaction with my bank
-statement, and pending to mean that I'm in the middle of a reconciliation.
+I use cleared to mean that I've reconciled the transaction with my
+bank statement, and pending to mean that I'm in the middle of
+a reconciliation.
-
-When you clear a transaction, that's really just shorthand for clearing all of
-its postings. That is:
+When you clear a transaction, that's really just shorthand for
+clearing all of its postings. That is:
@smallexample
- 2012-03-10 * KFC
- Expenses:Food $20.00
- Assets:Cash
+2012-03-10 * KFC
+ Expenses:Food $20.00
+ Assets:Cash
@end smallexample
-@noindent Is the same as writing:
+@noindent
+Is the same as writing:
@smallexample
- 2012-03-10 KFC
- * Expenses:Food $20.00
- * Assets:Cash
+2012-03-10 KFC
+ * Expenses:Food $20.00
+ * Assets:Cash
@end smallexample
-@noindent You can mark individual postings as cleared or pending, in case one "side" of
-the transaction has cleared, but the other hasn't yet:
+@noindent
+You can mark individual postings as cleared or pending, in case one
+``side'' of the transaction has cleared, but the other hasn't yet:
@smallexample
- 2012-03-10 KFC
- Liabilities:Credit $100.00
- * Assets:Checking
+2012-03-10 KFC
+ Liabilities:Credit $100.00
+ * Assets:Checking
@end smallexample
@node Transaction notes, Metadata, Transaction state, Transactions
@@ -2500,91 +2597,92 @@ the transaction has cleared, but the other hasn't yet:
After the payee, and after at least one tab or two spaces (or a space
and a tab, which Ledger calls this a ``hard separator''), you may
-introduce a note about the transaction using the ; character:
+introduce a note about the transaction using the @samp{;} character:
@smallexample
- 2012-03-10 * KFC ; yum, chicken...
- Expenses:Food $20.00
- Assets:Cash
+2012-03-10 * KFC ; yum, chicken...
+ Expenses:Food $20.00
+ Assets:Cash
@end smallexample
-@noindent Notes can also appear on the next line, so long as that line begins with
-whitespace:
+@noindent
+Notes can also appear on the next line, so long as that line begins
+with whitespace:
@smallexample
- 2012-03-10 * KFC ; yum, chicken...
- ; and more notes...
- Expenses:Food $20.00
- Assets:Cash
+2012-03-10 * KFC ; yum, chicken...
+ ; and more notes...
+ Expenses:Food $20.00
+ Assets:Cash
- 2012-03-10 * KFC
- ; just these notes...
- Expenses:Food $20.00
- Assets:Cash
+2012-03-10 * KFC
+ ; just these notes...
+ Expenses:Food $20.00
+ Assets:Cash
@end smallexample
-
-A transaction note is shared by all its postings. This becomes significant
-when querying for metadata (see below). To specify that a note belongs only
-to one posting, place it after a hard separator after the amount, or on its
-own line preceded by whitespace:
+A transaction note is shared by all its postings. This becomes
+significant when querying for metadata (see below). To specify that
+a note belongs only to one posting, place it after a hard separator
+after the amount, or on its own line preceded by whitespace:
@smallexample
- 2012-03-10 * KFC
- Expenses:Food $20.00 ; posting #1 note
- Assets:Cash
- ; posting #2 note, extra indentation is optional
+2012-03-10 * KFC
+ Expenses:Food $20.00 ; posting #1 note
+ Assets:Cash
+ ; posting #2 note, extra indentation is optional
@end smallexample
@node Metadata, Virtual postings, Transaction notes, Transactions
@section Metadata
-One of Ledger's more powerful features is the ability to associate typed
-metadata with postings and transactions (by which I mean all of a
-transaction's postings). This metadata can be queried, displayed, and used in
-calculations.
+One of Ledger's more powerful features is the ability to associate
+typed metadata with postings and transactions (by which I mean all of
+a transaction's postings). This metadata can be queried, displayed,
+and used in calculations.
The are two forms of metadata: tags and tag/value pairs.
@menu
-* Metadata tags::
-* Metadata values::
-* Typed metadata::
+* Metadata tags::
+* Metadata values::
+* Typed metadata::
@end menu
@node Metadata tags, Metadata values, Metadata, Metadata
@subsection Metadata tags
-To tag an item, put any word not containing whitespace between two colons:
+To tag an item, put any word not containing whitespace between two
+colons:
@smallexample
- 2012-03-10 * KFC
- Expenses:Food $20.00
- Assets:Cash
- ; :TAG:
+2012-03-10 * KFC
+ Expenses:Food $20.00
+ Assets:Cash
+ ; :TAG:
@end smallexample
You can gang up multiple tags by sharing colons:
@smallexample
- 2012-03-10 * KFC
- Expenses:Food $20.00
- Assets:Cash
- ; :TAG1:TAG2:TAG3:
+2012-03-10 * KFC
+ Expenses:Food $20.00
+ Assets:Cash
+ ; :TAG1:TAG2:TAG3:
@end smallexample
@node Metadata values, Typed metadata, Metadata tags, Metadata
@subsection Metadata values
-To associate a value with a tag, use the syntax "Key: Value", where the value
-can be any string of characters. Whitespace is needed after the colon, and
-cannot appear in the Key:
+To associate a value with a tag, use the syntax "Key: Value", where
+the value can be any string of characters. Whitespace is needed after
+the colon, and cannot appear in the Key:
@smallexample
- 2012-03-10 * KFC
- Expenses:Food $20.00
- Assets:Cash
- ; MyTag: This is just a bogus value for MyTag
+2012-03-10 * KFC
+ Expenses:Food $20.00
+ Assets:Cash
+ ; MyTag: This is just a bogus value for MyTag
@end smallexample
@node Typed metadata, , Metadata values, Metadata
@@ -2595,103 +2693,109 @@ expression and stored internally as a value rather than as a string.
For example, although I can specify a date textually like so:
@smallexample
- 2012-03-10 * KFC
- Expenses:Food $20.00
- Assets:Cash
- ; AuxDate: 2012/02/30
+2012-03-10 * KFC
+ Expenses:Food $20.00
+ Assets:Cash
+ ; AuxDate: 2012/02/30
@end smallexample
-@noindent This date is just a string, and won't be parsed as a date
-unless its value is used in a date-context (at which time the string
-is parsed into a date automatically every time it is needed as a
-date). If on the other hand I write this:
+@noindent
+This date is just a string, and won't be parsed as a date unless its
+value is used in a date-context (at which time the string is parsed
+into a date automatically every time it is needed as a date). If on
+the other hand I write this:
@smallexample
- 2012-03-10 * KFC
- Expenses:Food $20.00
- Assets:Cash
- ; AuxDate:: [2012/02/30]
+2012-03-10 * KFC
+ Expenses:Food $20.00
+ Assets:Cash
+ ; AuxDate:: [2012/02/30]
@end smallexample
-@noindent Then it is parsed as a date only once, and during parsing
-of the journal file, which would let me know right away that it is an
-invalid date.
+@noindent
+Then it is parsed as a date only once, and during parsing of the
+journal file, which would let me know right away that it is an invalid
+date.
@node Virtual postings, Expression amounts, Metadata, Transactions
-@section Virtual postings
+@section Virtual postings
+@findex --real
-Ordinarily, the amounts of all postings in a transaction must balance to zero.
-This is non-negotiable. It's what double-entry accounting is all about! But
-there are some tricks up Ledger's sleeve...
+Ordinarily, the amounts of all postings in a transaction must balance
+to zero. This is non-negotiable. It's what double-entry accounting
+is all about! But there are some tricks up Ledger's sleeve...
-You can use virtual accounts to transfer amounts to an account on the sly,
-bypassing the balancing requirement. The trick is that these postings are not
-considered ``real'', and can be removed from all reports using @code{--real}.
+You can use virtual accounts to transfer amounts to an account on the
+sly, bypassing the balancing requirement. The trick is that these
+postings are not considered ``real'', and can be removed from all
+reports using @code{--real}.
-To specify a virtual account, surround the account name with parentheses:
+To specify a virtual account, surround the account name with
+parentheses:
@smallexample
- 2012-03-10 * KFC
- Expenses:Food $20.00
- Assets:Cash
- (Budget:Food) $-20.00
+2012-03-10 * KFC
+ Expenses:Food $20.00
+ Assets:Cash
+ (Budget:Food) $-20.00
@end smallexample
-If you want, you can state that virtual postings @emph{should} balance against
-one or more other virtual postings by using brackets (which look ``harder'')
-rather than parentheses:
+If you want, you can state that virtual postings @emph{should} balance
+against one or more other virtual postings by using brackets (which
+look ``harder'') rather than parentheses:
@smallexample
- 2012-03-10 * KFC
- Expenses:Food $20.00
- Assets:Cash
- [Budget:Food] $-20.00
- [Equity:Budgets] $20.00
+2012-03-10 * KFC
+ Expenses:Food $20.00
+ Assets:Cash
+ [Budget:Food] $-20.00
+ [Equity:Budgets] $20.00
@end smallexample
@node Expression amounts, Balance verification, Virtual postings, Transactions
@section Expression amounts
-An amount is usually a numerical figure with an (optional) commodity, but it
-can also be any value expression. To indicate this, surround the amount
-expression with parentheses:
+An amount is usually a numerical figure with an (optional) commodity,
+but it can also be any value expression. To indicate this, surround
+the amount expression with parentheses:
@smallexample
- 2012-03-10 * KFC
- Expenses:Food ($10.00 + $20.00) ; Ledger adds it up for you
- Assets:Cash
+2012-03-10 * KFC
+ Expenses:Food ($10.00 + $20.00) ; Ledger adds it up for you
+ Assets:Cash
@end smallexample
@node Balance verification, Posting cost, Expression amounts, Transactions
@section Balance verification
+
@menu
-* Balance assertions::
-* Balance assignments::
-* Resetting a balance::
-* Balancing transactions::
+* Balance assertions::
+* Balance assignments::
+* Resetting a balance::
+* Balancing transactions::
@end menu
-If at the end of a posting's amount (and after the cost too, if there is one)
-there is an equals sign, then Ledger will verify that the total value for that
-account as of that posting matches the amount specified.
+If at the end of a posting's amount (and after the cost too, if there
+is one) there is an equals sign, then Ledger will verify that the
+total value for that account as of that posting matches the amount
+specified.
There are two forms of this features: balance assertions, and balance
assignments.
-
@node Balance assertions, Balance assignments, Balance verification, Balance verification
@subsection Balance assertions
A balance assertion has this general form:
@smallexample
- 2012-03-10 KFC
- Expenses:Food $20.00
- Assets:Cash $-20.00 = $500.00
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Assets:Cash $-20.00 = $500.00
@end smallexample
-This simply asserts that after subtracting $20.00 from Assets:Cash, that the
-resulting total matches $500.00. If not, it is an error.
+This simply asserts that after subtracting $20.00 from Assets:Cash,
+that the resulting total matches $500.00. If not, it is an error.
@node Balance assignments, Resetting a balance, Balance assertions, Balance verification
@subsection Balance assignments
@@ -2699,292 +2803,303 @@ resulting total matches $500.00. If not, it is an error.
A balance assignment has this form:
@smallexample
- 2012-03-10 KFC
- Expenses:Food $20.00
- Assets:Cash = $500.00
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Assets:Cash = $500.00
@end smallexample
-This sets the amount of the second posting to whatever it would need to be for
-the total in Assets:Cash to be $500.00 after the posting. If the resulting
-amount is not $-20.00 in this case, it is an error.
+This sets the amount of the second posting to whatever it would need
+to be for the total in Assets:Cash to be $500.00 after the posting.
+If the resulting amount is not $-20.00 in this case, it is an error.
@node Resetting a balance, Balancing transactions, Balance assignments, Balance verification
-@subsection Resetting a balance
+@subsection Resetting a balance
-Say your book-keeping has gotten a bit out of date, and your Ledger balance no
-longer matches your bank balance. You can create an adjustment transaction
-using balance assignments:
+Say your book-keeping has gotten a bit out of date, and your Ledger
+balance no longer matches your bank balance. You can create an
+adjustment transaction using balance assignments:
@smallexample
- 2012-03-10 Adjustment
- Assets:Cash = $500.00
- Equity:Adjustments
+2012-03-10 Adjustment
+ Assets:Cash = $500.00
+ Equity:Adjustments
@end smallexample
-Since the second posting is also null, it's value will become the inverse of
-whatever amount is generated for the first posting.
+Since the second posting is also null, it's value will become the
+inverse of whatever amount is generated for the first posting.
-This is the only time in ledger when more than one posting's amount may be
-empty -- and then only because it's not true empty, it is indirectly provided
-by the balance assignment's value.
+This is the only time in ledger when more than one posting's amount
+may be empty---and then only because it's not true empty, it is
+indirectly provided by the balance assignment's value.
@node Balancing transactions, , Resetting a balance, Balance verification
-@subsection Balancing transactions
+@subsection Balancing transactions
As a consequence of all the above, consider the following transaction:
@smallexample
- 2012-03-10 My Broker
- [Assets:Brokerage] = 10 AAPL
+2012-03-10 My Broker
+ [Assets:Brokerage] = 10 AAPL
@end smallexample
-What this says is: set the amount of the posting to whatever value is needed
-so that Assets:Brokerage contains 10 AAPL. Then, because this posting must
-balance, ensure that its value is zero. This can only be true if
-Assets:Brokerage does indeed contain 10 AAPL at that point in the input file.
+What this says is: set the amount of the posting to whatever value is
+needed so that Assets:Brokerage contains 10 AAPL. Then, because this
+posting must balance, ensure that its value is zero. This can only be
+true if Assets:Brokerage does indeed contain 10 AAPL at that point in
+the input file.
-A balanced virtual transaction is used simply to indicate to Ledger that this
-is not a "real" transaction. It won't appear in any reports anyway (unless
-you use a register report with --empty).
+A balanced virtual transaction is used simply to indicate to Ledger
+that this is not a ``real'' transaction. It won't appear in any
+reports anyway (unless you use a register report with @code{--empty}).
@node Posting cost, Explicit posting costs, Balance verification, Transactions
@section Posting cost
-When you transfer a commodity from one account to another, sometimes it get
-transformed during the transaction. This happens when you spend money on gas,
-for example, which transforms dollars into gallons of gasoline, or dollars
-into stocks in a company.
+When you transfer a commodity from one account to another, sometimes
+it get transformed during the transaction. This happens when you
+spend money on gas, for example, which transforms dollars into gallons
+of gasoline, or dollars into stocks in a company.
-In those cases, Ledger will remember the "cost" of that transaction for you,
-and can use it during reporting in various ways. Here's an example of a stock
-purchase:
+In those cases, Ledger will remember the ``cost'' of that transaction
+for you, and can use it during reporting in various ways. Here's an
+example of a stock purchase:
@smallexample
- 2012-03-10 My Broker
- Assets:Brokerage 10 AAPL
- Assets:Brokerage:Cash $-500.00
+2012-03-10 My Broker
+ Assets:Brokerage 10 AAPL
+ Assets:Brokerage:Cash $-500.00
@end smallexample
This is different from transferring 10 AAPL shares from one account to
-another, in this case you are @emph{exchanging} one commodity for another. The
-resulting posting cost is $50.00 per share.
+another, in this case you are @emph{exchanging} one commodity for
+another. The resulting posting cost is $50.00 per share.
@node Explicit posting costs, Posting cost expressions, Posting cost, Transactions
@section Explicit posting costs
-You can make any posting's cost explicit using the @@ symbol after the amount
-or amount expression:
+You can make any posting's cost explicit using the @samp{@@} symbol
+after the amount or amount expression:
@smallexample
- 2012-03-10 My Broker
- Assets:Brokerage 10 AAPL @@ $50.00
- Assets:Brokerage:Cash $-500.00
+2012-03-10 My Broker
+ Assets:Brokerage 10 AAPL @@ $50.00
+ Assets:Brokerage:Cash $-500.00
@end smallexample
-When you do this, since Ledger can now figure out the balancing amount from
-the first posting's cost, you can elide the other amount:
+When you do this, since Ledger can now figure out the balancing amount
+from the first posting's cost, you can elide the otheramount:
@smallexample
- 2012-03-10 My Broker
- Assets:Brokerage 10 AAPL @@ $50.00
- Assets:Brokerage:Cash
+2012-03-10 My Broker
+ Assets:Brokerage 10 AAPL @@ $50.00
+ Assets:Brokerage:Cash
@end smallexample
@menu
-* Primary and secondary commodities::
+* Primary and secondary commodities::
@end menu
@node Primary and secondary commodities, , Explicit posting costs, Explicit posting costs
@subsection Primary and secondary commodities
-It is a general convention within Ledger that the "top" postings in a
-transaction contain the target accounts, while the final posting contains the
-source account. Whenever a commodity is exchanged like this, the commodity
-moved to the target account is considered "secondary", while the commodity
-used for purchasing and tracked in the cost is "primary".
+It is a general convention within Ledger that the ``top'' postings in
+a transaction contain the target accounts, while the final posting
+contains the source account. Whenever a commodity is exchanged like
+this, the commodity moved to the target account is considered
+``secondary'', while the commodity used for purchasing and tracked in
+the cost is ``primary''.
-Said another way, whenever Ledger sees a posting cost of the form "AMOUNT @@
-AMOUNT", the commodity used in the second amount is marked "primary".
+Said another way, whenever Ledger sees a posting cost of the form
+"AMOUNT @@ AMOUNT", the commodity used in the second amount is marked
+``primary''.
-The only meaning a primary commodity has is that -V flag will never convert a
-primary commodity into any other commodity. -X still will, however.
+The only meaning a primary commodity has is that @code{-V} flag will
+never convert a primary commodity into any other commodity. @code{-X
+@var{COMMODITY}} still will, however.
@node Posting cost expressions, Total posting costs, Explicit posting costs, Transactions
@section Posting cost expressions
-Just as you can have amount expressions, you can have posting expressions:
+Just as you can have amount expressions, you can have posting
+expressions:
@smallexample
- 2012-03-10 My Broker
- Assets:Brokerage 10 AAPL @@ ($500.00 / 10)
- Assets:Brokerage:Cash
+2012-03-10 My Broker
+ Assets:Brokerage 10 AAPL @@ ($500.00 / 10)
+ Assets:Brokerage:Cash
@end smallexample
You can even have both:
@smallexample
- 2012-03-10 My Broker
- Assets:Brokerage (5 AAPL * 2) @@ ($500.00 / 10)
- Assets:Brokerage:Cash
+2012-03-10 My Broker
+ Assets:Brokerage (5 AAPL * 2) @@ ($500.00 / 10)
+ Assets:Brokerage:Cash
@end smallexample
@node Total posting costs, Virtual posting costs, Posting cost expressions, Transactions
@section Total posting costs
-The cost figure following the @@ character specifies the @emph{per-unit} price for
-the commodity being transferred. If you'd like to specify the total cost
-instead, use @@@@:
+The cost figure following the @samp{@@} character specifies the
+@emph{per-unit} price for the commodity being transferred. If you'd
+like to specify the total cost instead, use @samp{@@@@}:
@smallexample
- 2012-03-10 My Broker
- Assets:Brokerage 10 AAPL @@ $500.00
- Assets:Brokerage:Cash
+2012-03-10 My Broker
+ Assets:Brokerage 10 AAPL @@@@ $500.00
+ Assets:Brokerage:Cash
@end smallexample
Ledger reads this as if you had written:
@smallexample
- 2012-03-10 My Broker
- Assets:Brokerage 10 AAPL @@@@ ($500.00 / 10)
- Assets:Brokerage:Cash
+2012-03-10 My Broker
+ Assets:Brokerage 10 AAPL @@ ($500.00 / 10)
+ Assets:Brokerage:Cash
@end smallexample
@node Virtual posting costs, Commodity prices, Total posting costs, Transactions
@section Virtual posting costs
-Normally whenever a commodity exchange like this happens, the price of the
-exchange (such as $50 per share of AAPL, above) is recorded in Ledger's
-internal price history database. To prevent this from happening in the case
-of an exceptional transaction, surround the @@ or @@@@ with parentheses:
+Normally whenever a commodity exchange like this happens, the price of
+the exchange (such as $50 per share of AAPL, above) is recorded in
+Ledger's internal price history database. To prevent this from
+happening in the case of an exceptional transaction, surround the
+@samp{@@} or @samp{@@@@} with parentheses:
@smallexample
- 2012-03-10 My Brother
- Assets:Brokerage 1000 AAPL (@@) $1
- Income:Gifts Received
+2012-03-10 My Brother
+ Assets:Brokerage 1000 AAPL (@@) $1
+ Income:Gifts Received
@end smallexample
@node Commodity prices, Prices vs. costs, Virtual posting costs, Transactions
@section Commodity prices
+@findex --lot-prices
-When a transaction occurs that exchange one commodity for another, Ledger
-records that commodity price not only within its internal price database, but
-also attached to the commodity itself. Usually this fact remains invisible to
-the user, unless you turn on @code{--lot-prices} to show these hidden price figures.
+When a transaction occurs that exchange one commodity for another,
+Ledger records that commodity price not only within its internal price
+database, but also attached to the commodity itself. Usually this
+fact remains invisible to the user, unless you turn on
+@code{--lot-prices} to show these hidden price figures.
For example, consider the stock sale given above:
@smallexample
- 2012-03-10 My Broker
- Assets:Brokerage 10 AAPL @@ $50.00
- Assets:Brokerage:Cash
+2012-03-10 My Broker
+ Assets:Brokerage 10 AAPL @@ $50.00
+ Assets:Brokerage:Cash
@end smallexample
-The commodity transferred into Assets:Brokerage is not actually 10 AAPL, but
-rather 10 AAPL @{$5.00@}. The figure in braces after the amount is called the
-``lot price''. It's Ledger's way of remembering that this commodity was
-transferred through an exchange, and that $5.00 was the price of that
-exchange.
+The commodity transferred into Assets:Brokerage is not actually 10
+AAPL, but rather 10 AAPL @{$5.00@}. The figure in braces after the
+amount is called the ``lot price''. It's Ledger's way of remembering
+that this commodity was transferred through an exchange, and that
+$5.00 was the price of that exchange.
-This becomes significant if you later sell that commodity again. For example,
-you might write this:
+This becomes significant if you later sell that commodity again. For
+example, you might write this:
@smallexample
- 2012-04-10 My Broker
- Assets:Brokerage:Cash
- Assets:Brokerage -10 AAPL @@ $75.00
+2012-04-10 My Broker
+ Assets:Brokerage:Cash
+ Assets:Brokerage -10 AAPL @@ $75.00
@end smallexample
-And that would be perfectly fine, but how do you track the capital gains on
-the sale? It could be done with a virtual posting:
+And that would be perfectly fine, but how do you track the capital
+gains on the sale? It could be done with a virtual posting:
@smallexample
- 2012-04-10 My Broker
- Assets:Brokerage:Cash
- Assets:Brokerage -10 AAPL @@ $75.00
- (Income:Capital Gains) $-250.00
+2012-04-10 My Broker
+ Assets:Brokerage:Cash
+ Assets:Brokerage -10 AAPL @@ $75.00
+ (Income:Capital Gains) $-250.00
@end smallexample
-But this gets messy since capital gains income is very real, and not quite
-appropriate for a virtual posting.
+But this gets messy since capital gains income is very real, and not
+quite appropriate for a virtual posting.
-Instead, if you reference that same hidden price annotation, Ledger will
-figure out that the price of the shares you're selling, and the cost you're
-selling them at, don't balance:
+Instead, if you reference that same hidden price annotation, Ledger
+will figure out that the price of the shares you're selling, and the
+cost you're selling them at, don't balance:
@smallexample
- 2012-04-10 My Broker
- Assets:Brokerage:Cash $750.00
- Assets:Brokerage -10 AAPL @{$50.00@} @@ $75.00
+2012-04-10 My Broker
+ Assets:Brokerage:Cash $750.00
+ Assets:Brokerage -10 AAPL @{$50.00@} @@ $75.00
@end smallexample
-This transaction will fail because the $250.00 price difference between the
-price you bought those shares at, and the cost you're selling them for, does
-not match. The lot price also identifies which shares you purchased on that
-prior date.
+This transaction will fail because the $250.00 price difference
+between the price you bought those shares at, and the cost you're
+selling them for, does not match. The lot price also identifies which
+shares you purchased on that prior date.
@menu
-* Total commodity prices::
+* Total commodity prices::
@end menu
@node Total commodity prices, , Commodity prices, Commodity prices
@subsection Total commodity prices
-As a shorthand, you can specify the total price instead of the per-share
-price in doubled braces. This goes well with total costs, but is not required
-to be used with them:
+As a shorthand, you can specify the total price instead of the
+per-share price in doubled braces. This goes well with total costs,
+but is not required to be used with them:
@smallexample
- 2012-04-10 My Broker
- Assets:Brokerage:Cash $750.00
- Assets:Brokerage -10 AAPL @{@{$500.00@}@} @@@@ $750.00
- Income:Capital Gains $-250.00
+2012-04-10 My Broker
+ Assets:Brokerage:Cash $750.00
+ Assets:Brokerage -10 AAPL @{@{$500.00@}@} @@@@ $750.00
+ Income:Capital Gains $-250.00
@end smallexample
-It should be noted that this is a convenience only for cases where you buy and
-sell whole lots. The @{@{$500.00@}@} is @emph{not} an attribute of commodity, whereas
-@{$5.00@} is. In fact, when you write @{@{$500.00@}@}, Ledger just divides that
-value by 10 and sees @{$50.00@}. So if you use the print command to look at
-this transaction, you'll see the single form in the output. The double price
-form is a shorthand only.
+It should be noted that this is a convenience only for cases where you
+buy and sell whole lots. The @{@{$500.00@}@} is @emph{not} an
+attribute of commodity, whereas @{$5.00@} is. In fact, when you write
+@{@{$500.00@}@}, Ledger just divides that value by 10 and sees
+@{$50.00@}. So if you use the print command to look at this
+transaction, you'll see the single form in the output. The double
+price form is a shorthand only.
Plus, it comes with dangers. This works fine:
@smallexample
- 2012-04-10 My Broker
- Assets:Brokerage 10 AAPL @@ $50.00
- Assets:Brokerage:Cash $750.00
+2012-04-10 My Broker
+ Assets:Brokerage 10 AAPL @@ $50.00
+ Assets:Brokerage:Cash $750.00
- 2012-04-10 My Broker
- Assets:Brokerage:Cash $375.00
- Assets:Brokerage -5 AAPL @{$50.00@} @@ $375.00
- Income:Capital Gains $-125.00
+2012-04-10 My Broker
+ Assets:Brokerage:Cash $375.00
+ Assets:Brokerage -5 AAPL @{$50.00@} @@ $375.00
+ Income:Capital Gains $-125.00
- 2012-04-10 My Broker
- Assets:Brokerage:Cash $375.00
- Assets:Brokerage -5 AAPL @{$50.00@} @@ $375.00
- Income:Capital Gains $-125.00
+2012-04-10 My Broker
+ Assets:Brokerage:Cash $375.00
+ Assets:Brokerage -5 AAPL @{$50.00@} @@ $375.00
+ Income:Capital Gains $-125.00
@end smallexample
-@noindent But this does not do what you might expect:
+@noindent
+But this does not do what you might expect:
@smallexample
- 2012-04-10 My Broker
- Assets:Brokerage 10 AAPL @@ $50.00
- Assets:Brokerage:Cash $750.00
+2012-04-10 My Broker
+ Assets:Brokerage 10 AAPL @@ $50.00
+ Assets:Brokerage:Cash $750.00
- 2012-04-10 My Broker
- Assets:Brokerage:Cash $375.00
- Assets:Brokerage -5 AAPL @{@{$500.00@}@} @@ $375.00
- Income:Capital Gains $-125.00
+2012-04-10 My Broker
+ Assets:Brokerage:Cash $375.00
+ Assets:Brokerage -5 AAPL @{@{$500.00@}@} @@ $375.00
+ Income:Capital Gains $-125.00
- 2012-04-10 My Broker
- Assets:Brokerage:Cash $375.00
- Assets:Brokerage -5 AAPL @{@{$500.00@}@} @@ $375.00
- Income:Capital Gains $-125.00
+2012-04-10 My Broker
+ Assets:Brokerage:Cash $375.00
+ Assets:Brokerage -5 AAPL @{@{$500.00@}@} @@ $375.00
+ Income:Capital Gains $-125.00
@end smallexample
-And in cases where the amounts do not divide into whole figure and must be
-rounded, the capital gains figure could be off by a cent. Use with caution.
+And in cases where the amounts do not divide into whole figure and
+must be rounded, the capital gains figure could be off by a cent. Use
+with caution.
@node Prices vs. costs, Fixated prices, Commodity prices, Transactions
@section Prices vs. costs
@@ -2993,356 +3108,372 @@ Because lot pricing provides enough information to infer the cost, the
following two transactions are equivalent:
@smallexample
- 2012-04-10 My Broker
- Assets:Brokerage 10 AAPL @@ $50.00
- Assets:Brokerage:Cash $750.00
+2012-04-10 My Broker
+ Assets:Brokerage 10 AAPL @@ $50.00
+ Assets:Brokerage:Cash $750.00
- 2012-04-10 My Broker
- Assets:Brokerage 10 AAPL @{$50.00@}
- Assets:Brokerage:Cash $750.00
+2012-04-10 My Broker
+ Assets:Brokerage 10 AAPL @{$50.00@}
+ Assets:Brokerage:Cash $750.00
@end smallexample
-However, note that what you see in some reports may differ, for example in the
-print report. Functionally, however, there is no difference, and neither the
-register nor the balance report are sensitive to this difference.
+However, note that what you see in some reports may differ, for
+example in the print report. Functionally, however, there is no
+difference, and neither the register nor the balance report are
+sensitive to this difference.
@node Fixated prices, Lot dates, Prices vs. costs, Transactions
@section Fixated prices and costs
-If you buy a stock last year, and ask for its value today, Ledger will consult
-its price database to see what the most recent price for that stock is. You
-can short-circuit this lookup by ``fixing'' the price at the time of a
-transaction. This is done using @{=AMOUNT@}:
+If you buy a stock last year, and ask for its value today, Ledger will
+consult its price database to see what the most recent price for that
+stock is. You can short-circuit this lookup by ``fixing'' the price
+at the time of a transaction. This is done using @{=AMOUNT@}:
@smallexample
- 2012-04-10 My Broker
- Assets:Brokerage 10 AAPL @{=$50.00@}
- Assets:Brokerage:Cash $750.00
+2012-04-10 My Broker
+ Assets:Brokerage 10 AAPL @{=$50.00@}
+ Assets:Brokerage:Cash $750.00
@end smallexample
-These 10 AAPL will now always be reported as being worth $50, no matter what
-else happens to the stock in the meantime.
+These 10 AAPL will now always be reported as being worth $50, no
+matter what else happens to the stock in the meantime.
-Fixated prices are a special case of using lot valuation expressions (see
-below) to fix the value of a commodity lot.
+Fixated prices are a special case of using lot valuation expressions
+(see below) to fix the value of a commodity lot.
-Since price annotations and costs are largely interchangeable and a matter of
-preference, there is an equivalent syntax for specified fixated prices by way
-of the cost:
+Since price annotations and costs are largely interchangeable and
+a matter of preference, there is an equivalent syntax for specified
+fixated prices by way of the cost:
@smallexample
- 2012-04-10 My Broker
- Assets:Brokerage 10 AAPL @@ =$50.00
- Assets:Brokerage:Cash $750.00
+2012-04-10 My Broker
+ Assets:Brokerage 10 AAPL @@ =$50.00
+ Assets:Brokerage:Cash $750.00
@end smallexample
-This is the same as the previous transaction, with the same caveats found in
-@ref{Prices vs. costs}.
+This is the same as the previous transaction, with the same caveats
+found in @ref{Prices vs. costs}.
@node Lot dates, Lot notes, Fixated prices, Transactions
@section Lot dates
+@findex --lot-dates
-In addition to lot prices, you can specify lot dates and reveal them with
-@code{--lot-dates}. Other than that, however, they have no special meaning to
-Ledger. They are specified after the amount in square brackets (the same way
-that dates are parsed in value expressions):
+In addition to lot prices, you can specify lot dates and reveal them
+with @code{--lot-dates}. Other than that, however, they have no
+special meaning to Ledger. They are specified after the amount in
+square brackets (the same way that dates are parsed in value
+expressions):
@smallexample
- 2012-04-10 My Broker
- Assets:Brokerage:Cash $375.00
- Assets:Brokerage -5 AAPL @{$50.00@} [2012-04-10] @@ $375.00
- Income:Capital Gains $-125.00
+2012-04-10 My Broker
+ Assets:Brokerage:Cash $375.00
+ Assets:Brokerage -5 AAPL @{$50.00@} [2012-04-10] @@ $375.00
+ Income:Capital Gains $-125.00
@end smallexample
@node Lot notes, Lot value expressions, Lot dates, Transactions
@section Lot notes
+@findex --lot-notes
+@findex --lots
You can also associate arbitrary notes for your own record keeping in
-parentheses, and reveal them with --lot-notes. One caveat is that the note
-cannot begin with an @@ character, as that would indicate a virtual cost:
+parentheses, and reveal them with @code{--lot-notes}. One caveat is
+that the note cannot begin with an @samp{@@} character, as that would
+indicate a virtual cost:
@smallexample
- 2012-04-10 My Broker
- Assets:Brokerage:Cash $375.00
- Assets:Brokerage -5 AAPL @{$50.00@} [2012-04-10] (Oh my!) @@ $375.00
- Income:Capital Gains $-125.00
+2012-04-10 My Broker
+ Assets:Brokerage:Cash $375.00
+ Assets:Brokerage -5 AAPL @{$50.00@} [2012-04-10] (Oh my!) @@ $375.00
+ Income:Capital Gains $-125.00
@end smallexample
-You can any combination of lot prices, dates or notes, in any order. They are
-all optional.
+You can any combination of lot prices, dates or notes, in any order.
+They are all optional.
To show all lot information in a report, use @code{--lots}.
@node Lot value expressions, Automated Transactions, Lot notes, Transactions
@section Lot value expressions
-Normally when you ask Ledger to display the values of commodities held, it
-uses a value expression called ``market'' to determine the most recent value
-from its price database -- even downloading prices from the Internet, if -Q
-was specified and a suitable ``getquote'' script is found on your system.
+Normally when you ask Ledger to display the values of commodities
+held, it uses a value expression called ``market'' to determine the
+most recent value from its price database---even downloading prices
+from the Internet, if @code{-Q} was specified and a suitable
+``getquote'' script is found on your system.
-However, you can override this valuation logic by providing a commodity
-valuation expression in doubled parentheses. This expression must result in
-one of two values: either an amount to always be used as the per-share price
-for that commodity; or a function taking three argument which is called to
-determine that price.
+However, you can override this valuation logic by providing
+a commodity valuation expression in doubled parentheses. This
+expression must result in one of two values: either an amount to
+always be used as the per-share price for that commodity; or
+a function taking three argument which is called to determine that
+price.
-If you use the functional form, you can either specify a function name, or a
-lambda expression. Here's a function that yields the price as $10 in whatever
-commodity is being requested:
+If you use the functional form, you can either specify a function
+name, or a lambda expression. Here's a function that yields the price
+as $10 in whatever commodity is being requested:
@smallexample
- define ten_dollars(s, date, t) = market($10, date, t)
+define ten_dollars(s, date, t) = market($10, date, t)
@end smallexample
I can now use that in a lot value expression as follows:
@smallexample
- 2012-04-10 My Broker
- Assets:Brokerage:Cash $375.00
- Assets:Brokerage -5 AAPL @{$50.00@} ((ten_dollars)) @@@@ $375.00
- Income:Capital Gains $-125.00
+2012-04-10 My Broker
+ Assets:Brokerage:Cash $375.00
+ Assets:Brokerage -5 AAPL @{$50.00@} ((ten_dollars)) @@@@ $375.00
+ Income:Capital Gains $-125.00
@end smallexample
-Alternatively, I could do the same thing without pre-defining a function by
-using a lambda expression taking three arguments:
+Alternatively, I could do the same thing without pre-defining
+a function by using a lambda expression taking three arguments:
@smallexample
- 2012-04-10 My Broker
- A:B:Cash $375.00
- A:B -5 AAPL @{$50.00@} ((s, d, t -> market($10, date, t))) @@@@ $375.00
- Income:Capital Gains $-125.00
+2012-04-10 My Broker
+ A:B:Cash $375.00
+ A:B -5 AAPL @{$50.00@} ((s, d, t -> market($10, date, t))) @@@@ $375.00
+ Income:Capital Gains $-125.00
@end smallexample
The arguments passed to these functions have the following meaning:
@itemize
-@item source
- The source commodity string, or an amount object. If it is a
- string, the return value must be an amount representing the
- price of the commodity identified by that string (example: ``$'').
- If it is an amount, return the value of that amount as a new
- amount (usually calculated as commodity price times source amount).
-
-@item date
- The date to use for determining the value. If null, it means no
- date was specified, which can mean whatever you want it to mean.
-
-@item target
- If not null, a string representing the desired target commodity
- that the commodity price, or repriced amount, should be valued
- in. Note that this string can be a comma-separated list, and
- that some or all of the commodities in that list may be suffixed
- with an exclamation mark, to indicate what is being desired.
+@item source
+ The source commodity string, or an amount object. If it is
+ a string, the return value must be an amount representing the
+ price of the commodity identified by that string (example:
+ @samp{$}). If it is an amount, return the value of that
+ amount as a new amount (usually calculated as commodity price
+ times source amount).
+
+@item date
+ The date to use for determining the value. If null, it means
+ no date was specified, which can mean whatever you want it to
+ mean.
+
+@item target
+ If not null, a string representing the desired target
+ commodity that the commodity price, or repriced amount, should
+ be valued in. Note that this string can be a comma-separated
+ list, and that some or all of the commodities in that list may
+ be suffixed with an exclamation mark, to indicate what is
+ being desired.
@end itemize
-In most cases, it is simplest to either use explicit amounts in your valuation
-expressions, or just pass the arguments down to market after modifying them to
-suit your needs.
+In most cases, it is simplest to either use explicit amounts in your
+valuation expressions, or just pass the arguments down to market after
+modifying them to suit your needs.
@node Automated Transactions, , Lot value expressions, Transactions
@section Automated Transactions
-An automated transaction is a special kind of transaction which adds its
-postings to other transactions any time one of that other transactions'
-postings matches its predicate. The predicate uses the same query syntax as
-the Ledger command line.
+An automated transaction is a special kind of transaction which adds
+its postings to other transactions any time one of that other
+transactions' postings matches its predicate. The predicate uses the
+same query syntax as the Ledger command line.
Consider this posting:
@smallexample
- 2012-03-10 KFC
- Expenses:Food $20.00
- Assets:Cash
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Assets:Cash
@end smallexample
If I write this automated transaction before it in the file:
@smallexample
- = expr true
- Foo $50.00
- Bar $-50.00
+= expr true
+ Foo $50.00
+ Bar $-50.00
@end smallexample
-Then the first transaction will be modified during parsing as if I'd written
-this:
+Then the first transaction will be modified during parsing as if I'd
+written this:
@smallexample
- 2012-03-10 KFC
- Expenses:Food $20.00
- Foo $50.00
- Bar $-50.00
- Assets:Cash $-20.00
- Foo $50.00
- Bar $-50.00
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Foo $50.00
+ Bar $-50.00
+ Assets:Cash $-20.00
+ Foo $50.00
+ Bar $-50.00
@end smallexample
-Despite this fancy logic, automated transactions themselves follow most of the
-same rules as regular transactions: their postings must balance (unless you
-use a virtual posting), you can have metadata, etc.
+Despite this fancy logic, automated transactions themselves follow
+most of the same rules as regular transactions: their postings must
+balance (unless you use a virtual posting), you can have metadata,
+etc.
One thing you cannot do, however, is elide amounts in an automated
transaction.
@menu
-* Amount multipliers::
-* Accessing the matching posting's amount::
-* Referring to the matching posting's account::
-* Applying metadata to every matched posting::
-* Applying metadata to the generated posting::
-* State flags::
-* Effective Dates::
-* Periodic Transactions::
-* Concrete Example of Automated Transactions::
+* Amount multipliers::
+* Accessing the matching posting's amount::
+* Referring to the matching posting's account::
+* Applying metadata to every matched posting::
+* Applying metadata to the generated posting::
+* State flags::
+* Effective Dates::
+* Periodic Transactions::
+* Concrete Example of Automated Transactions::
@end menu
@node Amount multipliers, Accessing the matching posting's amount, Automated Transactions, Automated Transactions
@subsection Amount multipliers
-As a special case, if an automated transaction's posting's amount (phew) has
-no commodity, it is taken as a multiplier upon the matching posting's cost.
-For example:
+As a special case, if an automated transaction's posting's amount
+(phew) has no commodity, it is taken as a multiplier upon the matching
+posting's cost. For example:
@smallexample
- = expr true
- Foo 50.00
- Bar -50.00
+= expr true
+ Foo 50.00
+ Bar -50.00
- 2012-03-10 KFC
- Expenses:Food $20.00
- Assets:Cash
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Assets:Cash
@end smallexample
Then the latter transaction turns into this during parsing:
@smallexample
- 2012-03-10 KFC
- Expenses:Food $20.00
- Foo $1000.00
- Bar $-1000.00
- Assets:Cash $-20.00
- Foo $1000.00
- Bar $-1000.00
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Foo $1000.00
+ Bar $-1000.00
+ Assets:Cash $-20.00
+ Foo $1000.00
+ Bar $-1000.00
@end smallexample
@node Accessing the matching posting's amount, Referring to the matching posting's account, Amount multipliers, Automated Transactions
@subsection Accessing the matching posting's amount
-If you use an amount expression for an automated transaction's posting, that
-expression has access to all the details of the matched posting. For example,
-you can refer to that posting's amount using the ``amount'' value expression
-variable:
+If you use an amount expression for an automated transaction's
+posting, that expression has access to all the details of the matched
+posting. For example, you can refer to that posting's amount using
+the ``amount'' value expression variable:
@smallexample
- = expr true
- (Foo) (amount * 2) ; same as just "2" in this case
+= expr true
+ (Foo) (amount * 2) ; same as just "2" in this case
- 2012-03-10 KFC
- Expenses:Food $20.00
- Assets:Cash
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Assets:Cash
@end smallexample
This becomes:
@smallexample
- 2012-03-10 KFC
- Expenses:Food $20.00
- (Foo) $40.00
- Assets:Cash $-20.00
- (Foo) $-40.00
+2012-03-10 KFC
+ Expenses:Food $20.00
+ (Foo) $40.00
+ Assets:Cash $-20.00
+ (Foo) $-40.00
@end smallexample
@node Referring to the matching posting's account, Applying metadata to every matched posting, Accessing the matching posting's amount, Automated Transactions
@subsection Referring to the matching posting's account
-Sometimes want to refer to the account that matched in some way within the
-automated transaction itself. This is done by using the string $account,
-anywhere within the account part of the automated posting:
+Sometimes want to refer to the account that matched in some way within
+the automated transaction itself. This is done by using the string
+$account, anywhere within the account part of the automated posting:
@smallexample
- = food
- (Budget:$account) 10
+= food
+ (Budget:$account) 10
- 2012-03-10 KFC
- Expenses:Food $20.00
- Assets:Cash
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Assets:Cash
@end smallexample
Becomes:
@smallexample
- 2012-03-10 KFC
- Expenses:Food $20.00
- (Budget:Expenses:Food) $200.00
- Assets:Cash $-20.00
+2012-03-10 KFC
+ Expenses:Food $20.00
+ (Budget:Expenses:Food) $200.00
+ Assets:Cash $-20.00
@end smallexample
@node Applying metadata to every matched posting, Applying metadata to the generated posting, Referring to the matching posting's account, Automated Transactions
@subsection Applying metadata to every matched posting
-If the automated transaction has a transaction note, that note is copied
-(along with any metadata) to every posting that matches the predicate:
+If the automated transaction has a transaction note, that note is
+copied (along with any metadata) to every posting that matches the
+predicate:
@smallexample
- = food
- ; Foo: Bar
- (Budget:$account) 10
+= food
+ ; Foo: Bar
+ (Budget:$account) 10
- 2012-03-10 KFC
- Expenses:Food $20.00
- Assets:Cash
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Assets:Cash
@end smallexample
Becomes:
@smallexample
- 2012-03-10 KFC
- Expenses:Food $20.00
- ; Foo: Bar
- (Budget:Expenses:Food) $200.00
- Assets:Cash $-20.00
+2012-03-10 KFC
+ Expenses:Food $20.00
+ ; Foo: Bar
+ (Budget:Expenses:Food) $200.00
+ Assets:Cash $-20.00
@end smallexample
@node Applying metadata to the generated posting, State flags, Applying metadata to every matched posting, Automated Transactions
@subsection Applying metadata to the generated posting
-If the automated transaction's posting has a note, that note is carried to the
-generated posting within the matched transaction:
+If the automated transaction's posting has a note, that note is
+carried to the generated posting within the matched transaction:
@smallexample
- = food
- (Budget:$account) 10
- ; Foo: Bar
+= food
+ (Budget:$account) 10
+ ; Foo: Bar
- 2012-03-10 KFC
- Expenses:Food $20.00
- Assets:Cash
+2012-03-10 KFC
+ Expenses:Food $20.00
+ Assets:Cash
@end smallexample
Becomes:
@smallexample
- 2012-03-10 KFC
- Expenses:Food $20.00
- (Budget:Expenses:Food) $200.00
- ; Foo: Bar
- Assets:Cash $-20.00
+2012-03-10 KFC
+ Expenses:Food $20.00
+ (Budget:Expenses:Food) $200.00
+ ; Foo: Bar
+ Assets:Cash $-20.00
@end smallexample
-This is slightly different from the rules for regular transaction notes, in
-that an automated transaction's note does not apply to every posting within
-the automated transaction itself, but rather to every posting it matches.
+This is slightly different from the rules for regular transaction
+notes, in that an automated transaction's note does not apply to every
+posting within the automated transaction itself, but rather to every
+posting it matches.
@node State flags, Effective Dates, Applying metadata to the generated posting, Automated Transactions
@subsection State flags
-Although you cannot mark an automated transaction as a whole as cleared or
-pending, you can mark its postings with a * or ! before the account name, and
-that state flag gets carried to the generated posting.
+Although you cannot mark an automated transaction as a whole as
+cleared or pending, you can mark its postings with a @samp{*} or
+@samp{!} before the account name, and that state flag gets carried to
+the generated posting.
@node Effective Dates, Periodic Transactions, State flags, Automated Transactions
@subsection Effective Dates
@cindex effective dates
+@findex --effective
In the real world transactions do not take place instantaneously.
Purchases can take several days to post to a bank account. And you may
@@ -3352,44 +3483,54 @@ 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
+ Assets:Accounts Receivable $100.00
+ Income: Client name
@end smallexample
-@noindent Then, when you receive the payment, you change it to
+
+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
+ Assets:Accounts Receivable $100.00
+ Income: Client name
@end smallexample
-@noindent and add something like
+
+@noindent
+and add something like
@smallexample
2008/01/15 Client payment
- Assets:Checking $100.00
- Assets:Accounts Receivable
+ Assets:Checking $100.00
+ Assets:Accounts Receivable
@end smallexample
+
Now
@smallexample
- ledger --subtotal --begin 2008/01/01 --end 2008/01/14 bal Income
+$ 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
+
+@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
+$ 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.
+
+@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.
+you just prepaid into a local vegetable co-op that sustains you
+through the winter. It costs $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
@@ -3399,28 +3540,26 @@ even though you've already paid for them.
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
+ 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, Concrete Example of Automated Transactions, Effective Dates, Automated Transactions
@subsection Periodic Transactions
+@findex --budget
-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 @code{--budget} option specified.
-
-See @ref{Budgeting and Forecasting} for examples and details.
-
+A periodic transaction starts with a @samp{~} followed by a period
+expression. Periodic transactions are used for budgeting and
+forecasting only, they have no effect without the @code{--budget}
+option specified. @xref{Budgeting and Forecasting} for examples and
+details.
@node Concrete Example of Automated Transactions, , Periodic Transactions, Automated Transactions
@subsection Concrete Example of Automated 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
@@ -3458,7 +3597,7 @@ That's it. To see how much Huqúq is currently owed based on your
ledger transactions, use:
@smallexample
-ledger balance Liabilities:Huquq
+$ ledger balance Liabilities:Huquq
@end smallexample
This works fine, but omits one aspect of the law: that Huquq is only
@@ -3469,7 +3608,7 @@ 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
+$ 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
@@ -3478,7 +3617,7 @@ 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
+$ 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
@@ -3487,51 +3626,55 @@ this, use the special account name @samp{$account}:
@smallexample
= /^Some:Long:Account:Name/
- [$account] -0.10
- [Savings] 0.10
+ [$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}.
-
-
+to the @samp{Savings} account---as a balanced virtual posting, which
+may be excluded from reports by using @option{--real}.
-@node Building Reports, Reporting Commands, Transactions , Top
+@node Building Reports, Reporting Commands, Transactions, Top
@chapter Building Reports
@menu
-* Introduction::
-* Balance Reports::
-* Typical queries::
-* Advanced Reports::
+* Introduction::
+* Balance Reports::
+* Typical queries::
+* Advanced Reports::
@end menu
@node Introduction, Balance Reports, Building Reports, Building Reports
@section Introduction
+
The power of Ledger comes from the incredible flexibility in its
reporting commands, combined with formatting commands. Some options
control what is included in the calculations, and formatting controls
how it is displayed. The combinations are infinite. This chapter will
-show you the basics of combining various options and commands. In the next
-chapters you will find details about the specific commands and
+show you the basics of combining various options and commands. In the
+next chapters you will find details about the specific commands and
options.
@node Balance Reports, Typical queries, Introduction, Building Reports
@section Balance Reports
+
@menu
-* Controlling the Accounts and Payees::
-* Controlling formatting::
+* 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:
+The balance report is the most commonly used report. The simplest
+invocation is:
+
@smallexample
-ledger balance -f drewr3.dat
+$ ledger balance -f drewr3.dat
@end smallexample
-@noindent which will print the balances of every account in your journal.
+
+@noindent
+which will print the balances of every account in your journal.
@smallexample
$ -3,804.00 Assets
@@ -3556,35 +3699,40 @@ ledger balance -f drewr3.dat
$ -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.
+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
+$ 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 @code{Auto} and @code{Mastercard}.
-If you want the entire contents of a branch of your account tree, use the
-highest common name in the branch:
+@noindent
+note the implicit logical and between @code{Auto} and
+@code{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
+$ 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:
+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
+$ ledger balance -f drewr3.dat ^Bo
+$ ledger balance -f drewr3.dat Bo
$ 20.00 Expenses:Books
@end smallexample
@@ -3593,64 +3741,76 @@ there are none. The second looks for any account with ``Bo'', which is
@code{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/)"
+$ 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
+
+@noindent
+will show you the amount expended on gasoline at Chevron. The second
+example is the first example of the very power expression language
+available to shape reports. The first example may be easier to
remember, but learning to use the second will open up far more
possibilities.
If you want to exclude specific accounts from the report, you can
exclude multiple accounts with parentheses:
+
@smallexample
-ledger -s bal Expenses and not \(Expenses:Drinks or Expenses:Candy or Expenses:Gifts\)
+$ ledger -s bal Expenses and not \(Expenses:Drinks or Expenses:Candy or Expenses:Gifts\)
@end smallexample
@node Controlling formatting, , Controlling the Accounts and Payees, Balance Reports
@subsection Controlling Formatting
+
These examples all use the default formatting for the balance
report. Customizing the formatting can easily allowing to see only what
you want, or interface Ledger with other programs.
+
@node Typical queries, Advanced Reports, Balance Reports, Building Reports
@section Typical queries
A query such as the following shows all expenses since last
October, sorted by total:
-@example
-ledger -b "last oct" -s -S T bal ^expenses
-@end example
+@smallexample
+$ ledger -b "last oct" -s -S T bal ^expenses
+@end smallexample
-From left to right the options mean: Show transactions since last October;
-show all sub-accounts; sort by the absolute value of the total; and
-report the balance for all accounts that begin with ``expenses''.
+From left to right the options mean: Show transactions since last
+October; show all sub-accounts; sort by the absolute value of the
+total; and report the balance for all accounts that begin with
+``expenses''.
@menu
-* Reporting monthly expenses::
+* Reporting monthly expenses::
@end menu
@node Reporting monthly expenses, , Typical queries, Typical queries
@subsection Reporting monthly expenses
+@findex --monthly
+@findex -M
+@findex --display @var{EXPR}
+@findex --period-sort @var{VEXPR}
The following query makes it easy to see monthly expenses, with each
month's expenses sorted by the amount:
-@example
-ledger -M --period-sort "(amount)" reg ^expenses
-@end example
+@smallexample
+$ ledger -M --period-sort "(amount)" reg ^expenses
+@end smallexample
Now, you might wonder where the money came from to pay for these
things. To see that report, add @code{-r}, which shows the
``related account'' postings:
-@example
-ledger -M --period-sort "(amount)" -r reg ^expenses
-@end example
+@smallexample
+$ ledger -M --period-sort "(amount)" -r reg ^expenses
+@end smallexample
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
@@ -3658,9 +3818,9 @@ requires the use of a display predicate, since the postings
calculated must match @code{^expenses}, while the postings
displayed must match @code{mastercard}. The command would be:
-@example
-ledger -M -r --display "account =~ /mastercard/" reg ^expenses
-@end example
+@smallexample
+$ ledger -M -r --display "account =~ /mastercard/" reg ^expenses
+@end smallexample
This query says: Report monthly subtotals; report the ``related
account'' postings; display only related postings whose
@@ -3669,26 +3829,25 @@ postings matching @code{^expenses}.
This works just as well for report the overall total, too:
-@example
-ledger -s -r --display "account =~ /mastercard/"/ reg ^expenses
-@end example
+@smallexample
+$ ledger -s -r --display "account =~ /mastercard/" reg ^expenses
+@end smallexample
The @code{-s} option subtotals all postings, just as @code{-M}
subtotaled by the month. The running total in both cases is off,
however, since a display expression is being used.
-
-
@node Advanced Reports, , Typical queries, Building Reports
@section Advanced Reports
@menu
-* Asset Allocation::
-* Visualizing with Gnuplot::
+* Asset Allocation::
+* Visualizing with Gnuplot::
@end menu
@node Asset Allocation, Visualizing with Gnuplot, Advanced Reports, Advanced Reports
@subsection Asset Allocation
+
A very popular method of managing portfolios is to control the
percent allocation of assets by certain categories. The mix of
categories and the weights applied to them vary by investing
@@ -3699,21 +3858,21 @@ 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:
+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 @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 VTHRX @tab 24.0% @tab 56.3% @tab 19.7%
@item VSGBX @tab @tab @tab 100%
@end multitable
@@ -3733,27 +3892,28 @@ 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
+ (Allocation:Equities:Domestic) 1.000
= expr ( commodity == 'VTHRX' )
- (Allocation:Equities:Global) 0.240
- (Allocation:Equities:Domestic) 0.563
- (Allocation:Bonds/Cash) 0.197
+ (Allocation:Equities:Global) 0.240
+ (Allocation:Equities:Domestic) 0.563
+ (Allocation:Bonds/Cash) 0.197
= expr ( commodity == 'VBMFX')
- (Allocation:Bonds/Cash) 1.000
+ (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.
+How do these work? First the @samp{=} sign at the beginning of the
+line tells ledger this is an automatic transaction to be applied when
+the condition following the @samp{=} is true. After the @samp{=} 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
@@ -3762,15 +3922,18 @@ 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!
+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%/"
+ %-17((depth_spacer)+(partial_account))\
+ %10(percent(market(display_total), market(parent.total)))\
+ %16(market(display_total))\n%/"
@end smallexample
-@noindent Which yields:
+@noindent
+Which yields:
@smallexample
Allocation 100.00% $100000.00
@@ -3786,37 +3949,41 @@ 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
+@cindex display_total
+@cindex parent.total
The magic is in the formatter. The second line simply tells Ledger to
print the partial account name indented by its depth in the tree. The
third line is where we calculate and display the percentages. The
-@code{display_total} command give the values of the total calculated for
-the account in this line. The @code{parent.total} command gives the
-total for the next level up in the tree. @code{percent} formats their
-ratio as a percentage. The fourth line tells ledger to display the
-current market value of the the line. The last two characters ``%/''
-tell Ledger what to do for the last line, in this case, nothing.
+@code{display_total} command give the values of the total calculated
+for the account in this line. The @code{parent.total} command gives
+the total for the next level up in the tree. @code{percent} formats
+their ratio as a percentage. The fourth line tells ledger to display
+the current market value of the line. The last two characters
+@samp{%/} tell Ledger what to do for the last line, in this case,
+nothing.
-@cindex plotting
-@cindex GNUplot
@node Visualizing with Gnuplot, , Asset Allocation, Advanced Reports
@subsection Visualizing with Gnuplot
-@cindex GNUplot script
-If you have @command{Gnuplot} installed, you can graph any of the above
-register reports. The script to do this is included in the ledger
-distribution, and is named @file{contrib/report}. Install @file{report}
-anywhere along your @env{PATH}, and then use @command{report} instead of
-@command{ledger} when doing a register report. The only thing to keep
-in mind is that you must specify @code{-j (--amount-data)} or
-@code{-J (--total-data)} to indicate whether Gnuplot should plot the
-amount, or the running total. For example, this command plots total
-monthly expenses made on your MasterCard.
-
-@example
-report -j -M -r --display "account =~ /mastercard/" reg ^expenses
-@end example
+@cindex Gnuplot script
+@cindex plotting
+@cindex Gnuplot
+@findex --amount-data
+@findex --total-data
+
+If you have @command{Gnuplot} installed, you can graph any of the
+above register reports. The script to do this is included in the
+ledger distribution, and is named @file{contrib/report}. Install
+@file{report} anywhere along your @env{PATH}, and then use
+@command{report} instead of @command{ledger} when doing a register
+report. The only thing to keep in mind is that you must specify
+@code{-j (--amount-data)} or @code{-J (--total-data)} to indicate
+whether Gnuplot should plot the amount, or the running total. For
+example, this command plots total monthly expenses made on your
+MasterCard.
+
+@smallexample
+$ report -j -M -r --display "account =~ /mastercard/" reg ^expenses
+@end smallexample
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
@@ -3841,53 +4008,54 @@ report -J -l "Ua>=@{\$0.01@}" reg ^assets ^liab
report -J -l "Ua>=@{\$0.01@}" -d "d>=[last feb]" reg ^assets ^liab
@end smallexample
-The last report uses both a calculation predicate (@code{-l}) and a
-display predicate (@code{-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.
-
-
-
-
+The last report uses both a calculation predicate (@code{-l}) and
+a display predicate (@code{-d}). The calculation predicates limits
+the report to postings whose amount is greater than $1 (which can only
+happen if the posting amount is in dollars). The display predicate
+limits the transactions @emph{displayed} to just those since last
+February, even those transactions from before then will be computed as
+part of the balance.
@node Reporting Commands, Command-line Syntax, Building Reports, Top
@chapter Reporting Commands
+
@menu
* Primary Financial Reports:: Reports in other formats:: Reports about
-* Reports in other Formats::
-* Reports about your Journals::
+* Reports in other Formats::
+* Reports about your Journals::
@end menu
@node Primary Financial Reports, Reports in other Formats, Reporting Commands, Reporting Commands
@section Primary Financial Reports
@menu
-* The balance Command::
-* The equity Command::
-* The register Command::
-* The print Command::
+* The balance Command::
+* The equity Command::
+* The register Command::
+* The print Command::
@end menu
@node The balance Command, The equity Command, Primary Financial Reports, Primary Financial Reports
-@subsection The @code{balance} Command
+@subsection The @code{balance} command
+@findex 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 The equity Command, The register Command, The balance Command, Primary Financial Reports
-@subsection The @code{equity} Command
+@subsection The @code{equity} command
+@findex 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}.
+were transactions. This makes it easy to establish the starting
+balances for an account, such as when @ref{Archiving Previous Years}.
@node The register Command, The print Command, The equity Command, Primary Financial Reports
-@subsection The @code{register} Command
+@subsection The @code{register} command
+@findex register
The @command{register} command displays all the postings occurring
in a single account, line by line. The account regexp must be
@@ -3908,7 +4076,8 @@ add either @code{-j} or @code{-J} to your register command, in
order to plot either the amount or total column, respectively.
@node The print Command, , The register Command, Primary Financial Reports
-@subsection The @code{print} Command
+@subsection The @code{print} command
+@findex print
The @command{print} command prints out ledger transactions in a textual
format that can be parsed by Ledger. They will be properly formatted,
@@ -3919,50 +4088,59 @@ postings which match in some way to be printed.
The @command{print} command can be a handy way to clean up a ledger
file whose formatting has gotten out of hand.
-
@node Reports in other Formats, Reports about your Journals, Primary Financial Reports, Reporting Commands
@section Reports in other Formats
+
@menu
-* Comma Separated Variable files::
-* The lisp command::
-* Emacs Org mode::
-* The pricemap Command::
-* The xml Command::
-* prices and pricedb::
+* Comma Separated Values files::
+* The lisp command::
+* Emacs Org mode::
+* Org mode with Babel::
+* The pricemap Command::
+* The xml Command::
+* prices and pricedb::
@end menu
-@node Comma Separated Variable files, The lisp command, Reports in other Formats, Reports in other Formats
-@subsection Comma Separated Variable files
+@node Comma Separated Values files, The lisp command, Reports in other Formats, Reports in other Formats
+@subsection Comma Separated Values files
+
@menu
-* The csv command::
-* The convert command::
+* The csv command::
+* The convert command::
@end menu
-@node The csv command, The convert command, Comma Separated Variable files, Comma Separated Variable files
+@node The csv command, The convert command, Comma Separated Values files, Comma Separated Values files
@subsubsection The @code{csv} command
-The @command{csv} command will output print out the desired ledger transactions in
-a csv format suitable for import into other programs. You can specify
-the transactions to print using all the normal limiting and searching
-functions.
+@findex csv
+
+The @command{csv} command will output print out the desired ledger
+transactions in a csv format suitable for import into other programs.
+You can specify the transactions to print using all the normal
+limiting and searching functions.
+
+@node The convert command, , The csv command, Comma Separated Values files
+@subsubsection The @code{convert} command
@cindex csv conversion
@cindex reading csv
@cindex comma separated variable file reading
-@node The convert command, , The csv command, Comma Separated Variable files
-@subsubsection The @code{convert} command
-The @code{convert} command parses a comma separated value
-(csv) file and outputs Ledger transactions. Many banks offer csv file
-downloads. Unfortunately, the file formats, aside the from commas, are
-all different. The ledger @code{convert} command tries to help as much as it
-can.
+@findex convert
+@findex --input-date-format @var{DATE_FORMAT}
+
+The @code{convert} command parses a comma separated value (csv) file
+and outputs Ledger transactions. Many banks offer csv file downloads.
+Unfortunately, the file formats, aside the from commas, are all
+different. The ledger @code{convert} command tries to help as much as
+it can.
Your banks csv files will have fields in different orders from other
-banks, so there must be a way to tell Ledger what to expect. Insert a
-line at the beginning of the csv file that describes the fields to Ledger.
+banks, so there must be a way to tell Ledger what to expect. Insert
+a line at the beginning of the csv file that describes the fields to
+Ledger.
For example, this is a portion of a csv file downloaded from a credit
union in the United States:
-@smallexample
+@smallexample
Account Name: VALUFIRST CHECKING
Account Number: 71
Date Range: 11/13/2011 - 12/13/2011
@@ -3975,27 +4153,31 @@ Transaction Number,Date,Description,Memo,Amount Debit,Amount Credit,Balance,Chec
1113648,12/12/2011,"Withdrawal","Tuscan IT #00037657",-29.73,,00001908.37,,
@end smallexample
-Unfortunately, as it stands Ledger cannot read it, but you can. Ledger
+Unfortunately, as it stands Ledger cannot read it, but you can. Ledger
expects the first line to contain a description of the fields on each
-line of the file. The fields ledger can recognize are called
-``@code{date}'' ``@code{posted}'', ``@code{code}'', ``@code{payee} or
-@code{desc}'', ``@code{amount}'', ``@code{cost}'', ``@code{total}'', and
-``@code{note}''.
+line of the file. The fields ledger can recognize are called
+@option{date}, @option{posted}, @option{code}, @option{payee} or
+@option{desc}, @option{amount}, @option{cost}, @option{total}, and
+@option{note}.
+
+Delete the account description lines at the top, and replace the first
+line in the data above with:
-Delete the account description lines at the top, and replace the first line in the data above with:
@smallexample
,date,payee,note,amount,,,code,
@end smallexample
Then execute ledger like this:
+
@smallexample
-ledger convert download.csv --input-date-format "%m/%d/%Y"
+$ ledger convert download.csv --input-date-format "%m/%d/%Y"
@end smallexample
Where the @code{--input-date-format} option tells ledger how to
interpret the dates.
-Importing csv files is a lot of work, and but is very amenable to scripting.
+Importing csv files is a lot of work, and but is very amenable to
+scripting.
If there are columns in the bank data you would like to keep in your
ledger data, besides the primary fields described above, you can name
@@ -4004,28 +4186,31 @@ transaction as meta data if it doesn't recognize the field name. For
example, if you want to capture the bank transaction number and it
occurs in the first column of the data use:
-
@smallexample
transid,date,payee,note,amount,,,code,
@end smallexample
-Ledger will include @code{; transid: 767718} in the first transaction is
-from the file above.
+Ledger will include @code{; transid: 767718} in the first transaction
+is from the file above.
+
+@findex --invert
+@findex --account @var{STR}
+@findex --rich-data
The @code{convert} command accepts three options, the most important
ones are @code{--invert} which inverts the amount field, and
-@code{--account NAME} which you can use to specify the account to
-balance against and @code{--rich-data}. When using the rich-data switch
-additional metadata is stored as tags. There is, for example, a UUID field. If
-an entry with the same UUID tag is already included in the normal ledger
-file (specified via @code{-f} or @code{$LEDGER_FILE}) this entry will not be printed
-again.
+@code{--account @var{NAME}} which you can use to specify the account to
+balance against and @code{--rich-data}. When using the rich-data
+switch additional metadata is stored as tags. There is, for example,
+a UUID field. If an entry with the same UUID tag is already included
+in the normal ledger file (specified via @code{-f} or via environment
+variable @env{LEDGER_FILE}) this entry will not be printed again.
You can also use @code{convert} with @code{payee} and @code{account}
directives. First, you can use the @code{payee} and @code{alias}
-directive to rewrite the @code{payee} field based on some rules. Then you can
-use the account and its @code{payee} directive to specify the account. I use it
-like this, for example:
+directive to rewrite the @code{payee} field based on some rules. Then
+you can use the account and its @code{payee} directive to specify the
+account. I use it like this, for example:
@smallexample
payee Aldi
@@ -4034,13 +4219,16 @@ account Aufwand:Einkauf:Lebensmittel
payee ^(Aldi|Alnatura|Kaufland|REWE)$
@end smallexample
-Note that it may be necessary for the output of @code{ledger convert} to be
-passed through @code{ledger print} a second time if you want to match on the
-new payee field. During the @code{ledger convert} run only the original payee
-name as specified in the csv data seems to be used.
+Note that it may be necessary for the output of @code{ledger convert}
+to be passed through @code{ledger print} a second time if you want to
+match on the new payee field. During the @code{ledger convert} run
+only the original payee name as specified in the csv data seems to be
+used.
-@node The lisp command, Emacs Org mode, Comma Separated Variable files, Reports in other Formats
+@node The lisp command, Emacs Org mode, Comma Separated Values files, Reports in other Formats
@subsection The @code{lisp} command
+@findex lisp
+@findex emacs
The @command{lisp} command outputs results in a form that can be read
directly by Emacs Lisp. The format of the @code{sexp} is:
@@ -4051,26 +4239,29 @@ directly by Emacs Lisp. The format of the @code{sexp} is:
...) ; list of transactions
@end smallexample
-@noindent @code{emacs} can also be used as a synonym for @code{lisp}
+@noindent
+@code{emacs} can also be used as a synonym for @code{lisp}
-@node Emacs Org mode, The pricemap Command, The lisp command, Reports in other Formats
+@node Emacs Org mode, Org mode with Babel, The lisp command, Reports in other Formats
@subsection Emacs @code{org} Mode
+@findex 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.
+document and automatically execute code which may generate results
+which will then appear in the text.
-One of the languages supported by @code{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.
+One of the languages supported by @code{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 @code{org+babel} system:
+For instance, the following Org mode text document snippet illustrates
+a very naive but still useful of the @code{org+babel} system:
@smallexample
* A simple test of ledger in an org file
@@ -4101,58 +4292,73 @@ line options.
: £-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).
+Typing @kbd{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).
+@node Org mode with Babel, The pricemap Command, Emacs Org mode, Reports in other Formats
@subsection Org mode with Babel
Using Babel, it is possible to record financial transactions
conveniently in an org file and subsequently generate the financial
reports required.
-With a recent version of org (7.01+), Ledger support is provided. To use
-it, enable Ledger support. Check the Babel documentation on Worg for
-instructions on how to achieve this but I currently do this directly as
-follows:
+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
+@item
place all Ledger entries within one source block and execute
- this block with different arguments to generate the appropriate
- reports;
-@item
+ 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
+@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.
+The first two are described in more detail in this short tutorial.
+
+@menu
+* Embedded Ledger example with single source block::
+* Multiple Ledger source blocks with @command{noweb}::
+* Income Entries::
+* Expenses::
+* Financial Summaries::
+* An overall balance summary::
+* Generating a monthly register::
+* Summary::
+@end menu
-@subsubheading Embedded Ledger example with single source block
+@node Embedded Ledger example with single source block, Multiple Ledger source blocks with @command{noweb}, Org mode with Babel, Org mode with Babel
+@subsubsection Embedded Ledger example with single source block
The easiest, albeit possibly less useful, way in which to use Ledger
within an org file is to use a single source block to record all Ledger
entries. The following is an example source block:
+
@smallexample
#+name: allinone
#+begin_src ledger
@@ -4179,26 +4385,31 @@ entries. The following is an example source block:
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:
+
+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 (@kbd{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
@@ -4208,7 +4419,8 @@ financial state. Eventually, babel will support passing arguments to
currently. Instead, we can use the concepts of literary programming, as
implemented by the noweb features of babel, to help us.
-@subsubheading Multiple Ledger source blocks with @command{noweb}
+@node Multiple Ledger source blocks with @command{noweb}, Income Entries, Embedded Ledger example with single source block, Org mode with Babel
+@subsubsection Multiple Ledger source blocks with @command{noweb}
The @command{noweb} feature of babel allows us to expand references to
other code blocks within a code block. For Ledger, this can be used to
@@ -4217,13 +4429,16 @@ of transactions together to generate reports.
Using the same transactions used above, we could consider splitting
these into expenses and income, as follows:
-@subsubheading Income Entries
+
+@node Income Entries, Expenses, Multiple Ledger source blocks with @command{noweb}, Org mode with Babel
+@subsubsection Income Entries
The first set of entries relates to income, either monthly pay or
interest, all typically going into one of my bank accounts. Here, I have
placed several entries, but we could have had each entry in a separate
src block. Note that all code blocks you wish to refer to later must
have the :noweb yes babel header argument specified.
+
@smallexample
#+name: income
#+begin_src ledger :noweb yes
@@ -4244,11 +4459,14 @@ have the :noweb yes babel header argument specified.
income:salary
#+end_src
@end smallexample
-@subsubheading Expenses
+
+@node Expenses, Financial Summaries, Income Entries, Org mode with Babel
+@subsubsection Expenses
The following entries relate to personal expenses, such as rent and
food. Again, these have all been placed in a single src block but could
have been done individually.
+
@smallexample
#+name: expenses
#+begin_src ledger :noweb yes
@@ -4261,21 +4479,25 @@ have been done individually.
#+end_src
@end smallexample
-@subsubheading Financial Summaries
+@node Financial Summaries, An overall balance summary, Expenses, Org mode with Babel
+@subsubsection 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,
-@code{<<name>>}. We can now define different code blocks to generate specific
-reports for those transactions. Below are two examples, one to generate
-a balance report and one to generate a register report of all
-transactions.
-@subsubheading An overall balance summary
+blocks, we can now refer to these using the noweb expansion
+directives, @code{<<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.
+
+@node An overall balance summary, Generating a monthly register, Financial Summaries, Org mode with Babel
+@subsubsection 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 (@code{C-c C-c}) and the
-results generated by incorporating the transactions referred to by the
-@code{<<income>>} and @code{<<expenses>>} lines.
+according to category is specified by passing the :cmdline bal
+argument to Ledger. This code block can now be evaluated (@kbd{C-c
+C-c}) and the results generated by incorporating the transactions
+referred to by the @code{<<income>>} and @code{<<expenses>>} lines.
+
@smallexample
#+name: balance
#+begin_src ledger :cmdline bal :noweb yes
@@ -4290,8 +4512,9 @@ results generated by incorporating the transactions referred to by the
@end smallexample
If you want a more detailed breakdown of where your money is and where
-it has been spent, you can specify the @code{-s} flag (i.e. @code{:cmdline -s bal}) to
-tell Ledger to include sub-accounts in the report.
+it has been spent, you can specify the @code{-s} flag
+(i.e. @code{:cmdline -s bal}) to tell Ledger to include sub-accounts
+in the report.
@smallexample
#+begin_src ledger :cmdline -s bal :noweb yes
@@ -4311,12 +4534,15 @@ tell Ledger to include sub-accounts in the report.
: £-2000.00 salary
: £-1300.00 starting balances
@end smallexample
-@subsubheading Generating a monthly register
-You can also generate a monthly register (the reg command) by executing
-the following src block. This presents a summary of transactions for
-each monthly period (the @code{-M} argument) with a running total in the final
-column (which should be 0 at the end if all the entries are correct).
+@node Generating a monthly register, Summary, An overall balance summary, Org mode with Babel
+@subsubsection 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 @code{-M} argument) with
+a running total in the final column (which should be 0 at the end if
+all the entries are correct).
@smallexample
#+name: monthlyregister
@@ -4356,18 +4582,20 @@ the running total of the assets in our ledger.
: 2010/08/01 - 2010/08/01 assets:bank:chequing £1000.00 £2653.53
@end smallexample
-@subsubheading Summary
+@node Summary, , Generating a monthly register, Org mode with Babel
+@subsubsection Summary
This short tutorial shows how Ledger entries can be embedded in a org
file and manipulated using Babel. However, only simple Ledger features
have been illustrated; please refer to the Ledger documentation for
examples of more complex operations with a ledger.
-@node The pricemap Command, The xml Command, Emacs Org mode, Reports in other Formats
-@subsection The @code{pricemap} Command
+@node The pricemap Command, The xml Command, Org mode with Babel, Reports in other Formats
+@subsection The @code{pricemap} command
+@findex pricemap
-If you have the @code{graphviz} graph visualization package installed, ledger
-can generate a graph of the relationship between your various
+If you have the @code{graphviz} graph visualization package installed,
+ledger can generate a graph of the relationship between your various
commodities. The output file is in the ``dot'' format.
This is probably not very interesting, unless you have many different
@@ -4375,7 +4603,8 @@ commodities valued in terms of each other. For example, multiple
currencies and multiples investments valued in those currencies.
@node The xml Command, prices and pricedb, The pricemap Command, Reports in other Formats
-@subsection The @code{xml} Command
+@subsection The @code{xml} command
+@findex 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
@@ -4474,7 +4703,7 @@ 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
+@table @code
@item P
The commodity is prefixed to the value.
@item S
@@ -4487,8 +4716,8 @@ marker, and comma used as the decimal point.
@end table
The actual quantity for an amount is an integer of arbitrary size.
-Ledger uses the GNU multiple precision arithmetic library to handle such
-values. The XML format assumes the reader to be equally capable.
+Ledger uses the GNU multiple precision arithmetic library to handle
+such values. The XML format assumes the reader to be equally capable.
Here is an example amount:
@smallexample
@@ -4524,9 +4753,10 @@ That is the extent of the XML data format used by Ledger. It will
output such data if the @command{xml} command is used, and can read
the same data.
-
@node prices and pricedb, , The xml Command, Reports in other Formats
-@subsection @code{prices} and @code{pricedb}
+@subsection @code{prices} and @code{pricedb} commands
+@findex prices
+@findex pricedb
The @command{prices} command displays the price history for matching
commodities. The @code{-A} flag is useful with this report, to
@@ -4534,53 +4764,78 @@ display the running average price, or @code{-D} to show each price's
deviation from that average.
There is also a @command{pricedb} command which outputs the same
-information as @command{prices}, but does in a format that can be parsed
-by Ledger. This is useful for generating and tidying up pricedb
-database files.
-
+information as @command{prices}, but does in a format that can be
+parsed by Ledger. This is useful for generating and tidying up
+pricedb database files.
@node Reports about your Journals, , Reports in other Formats, Reporting Commands
@section Reports about your Journals
+@findex --count
@menu
-* accounts::
-* commodities::
-* tags::
-* entry and xact::
-* payees::
+* accounts::
+* payees::
+* commodities::
+* tags::
+* entry and xact::
+* stats::
+* select::
@end menu
-@node accounts, commodities, Reports about your Journals, Reports about your Journals
+@node accounts, payees, Reports about your Journals, Reports about your Journals
@subsection @code{accounts}
+@findex 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. The output is sorted by name. Using the
-@code{--count} option will tell you haw many entries use each account.
+Following the command with a regular expression will limit the output
+to accounts matching the regex. The output is sorted by name. Using
+the @code{--count} option will tell you how many entries use each
+account.
+
+@node payees, commodities, accounts, Reports about your Journals
+@subsection @code{payees}
+@findex payees
+The @command{payees} reports all of the unique payees in the journal.
+Using the @code{--count} option will tell you how many entries use
+each payee. To filter the payees displayed you must use the prefix:
-@node commodities, tags, accounts, Reports about your Journals
+@smallexample
+$ ledger payees @@Nic
+Nicolas
+Nicolas BOILABUS
+Oudtshoorn Municipality
+Vaca Veronica
+@end smallexample
+
+@node commodities, tags, payees, Reports about your Journals
@subsection @command{commodities}
-Report all commodities present in the journals under consideration. The
- output is sorted by name. Using the @code{--count} option will tell
- you haw many entries use each commodity.
+@findex commodities
+
+Report all commodities present in the journals under consideration.
+The output is sorted by name. Using the @code{--count} option will
+tell you how many entries use each commodity.
@node tags, entry and xact, commodities, Reports about your Journals
@subsection @command{tags}
+@findex tags
+@findex --values
The @command{tags} reports all of the tags in the journal. The output
-is sorted by name. Using the @code{--count} option will tell you haw
-many entries use each tag. Using the @code{--values} option will report
-the values used by each tag.
-
+is sorted by name. Using the @code{--count} option will tell you how
+many entries use each tag. Using the @code{--values} option will
+report the values used by each tag.
-
-@node entry and xact, payees, tags, Reports about your Journals
+@node entry and xact, stats, tags, Reports about your Journals
@subsection @command{draft}, @command{entry} and @command{xact}
+@findex draft
+@findex entry
+@findex xact
-The @code{draft}, @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:
+The @code{draft}, @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:
@@ -4596,7 +4851,7 @@ 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
+$ ledger entry 2004/4/9 viva food 11 tips 2.50
@end smallexample
This produces the following output:
@@ -4611,49 +4866,45 @@ This produces the following output:
It works by finding a past posting matching the regular expression
@code{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 @code{1}.
+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"
+$ 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 @code{payees}
-The @command{payees} reports all of the unique payees in the journal. To
-filter the payees displayed you must use the prefix:
-@smallexample
-macbook-2:$ ledger payees 'Tar.+t'
-El Dorade Restaraunt
-My Big Fat Greek Restaraunt
-Target
-macbook-2:$
-@end smallexample
-
+@node stats, select, entry and xact, Reports about your Journals
+@subsection @code{stats}
+@findex stats
+@findex stat
+FIX THIS ENTRY @c FIXME thdox
+@node select, , stats, Reports about your Journals
+@subsection @code{select}
+@findex select
+FIX THIS ENTRY @c FIXME thdox
@node Command-line Syntax, Budgeting and Forecasting, Reporting Commands, Top
@chapter Command-line Syntax
-
@menu
-* Basic Usage::
-* Command Line Quick Reference::
-* Detailed Options Description::
-* Period Expressions::
+* Basic Usage::
+* Command Line Quick Reference::
+* Detailed Options Description::
+* Period Expressions::
@end menu
@node Basic Usage, Command Line Quick Reference, Command-line Syntax, Command-line Syntax
@@ -4669,7 +4920,7 @@ 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...]
+$ ledger [OPTIONS...] COMMAND [ARGS...]
@end smallexample
After the command word there may appear any number of arguments. For
@@ -4678,18 +4929,22 @@ 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 @code{payee} or @@. For example, the
-following balance command reports account totals for rent, food and
-movies, but only those whose payee matches Freddie:
+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
+@samp{@@}. 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
+$ ledger bal rent food movies payee freddie
@end smallexample
-@noindent or
+
+@noindent
+or
+
@smallexample
-ledger bal rent food movies @@freddie
+$ ledger bal rent food movies @@freddie
@end smallexample
There are many, many command options available with the
@@ -4701,154 +4956,288 @@ commands.
@section Command Line Quick Reference
@menu
-* Reporting Commands Quick Reference::
-* Basic Options Quick Reference::
-* Report Filtering Quick Reference::
-* Error Checking and Calculation Options::
-* Output Customization Quick Reference::
-* Grouping Options::
-* Commodity Reporting Quick Reference::
+* Reporting Commands Quick Reference::
+* Basic Options Quick Reference::
+* Report Filtering Quick Reference::
+* Error Checking and Calculation Options::
+* Output Customization Quick Reference::
+* Grouping Options::
+* Commodity Reporting Quick Reference::
@end menu
@node Reporting Commands Quick Reference, Basic Options Quick Reference, Command Line Quick Reference, Command Line Quick Reference
@subsection Reporting Commands
-@multitable @columnfractions .2 .8
-@item @strong{Report} @tab @strong{Description}
-@item @code{balance} @tab Show account balances
-@item @code{register} @tab Show all transactions with running total
-@item @code{csv} @tab Show transactions in csv format, for exporting to other programs
-@item @code{print} @tab Print transaction in a ledger readable format
-@item @code{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
+
+@ftable @code
+@item balance
+@itemx bal
+Show account balances
+@item register
+@itemx reg
+Show all transactions with running total
+@item csv
+Show transactions in csv format, for exporting to other programs
+@item print
+Print transaction in a ledger readable format
+@item xml
+Produce XML output of the register command
+@item lisp
+@itemx emacs
+Produce Emacs lisp output
+@item equity
+Print account balances as transactions
+@item prices
+Print price history for matching commodities
+@item pricedb
+Print price history for matching commodities in ledger readable format
+@item xact
+Generate transactions based on previous postings
+@end ftable
@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
-
+
+@ftable @code
+@item --help
+@itemx -h
+Print summary of all options
+
+@item --version
+@itemx -v
+Print version of ledger executable
+
+@item --file @var{FILE}
+@itemx -f @var{FILE}
+Read @file{FILE} as a ledger file
+
+@item --output @var{FILE}
+@itemx -o @var{FILE}
+Redirect output to @file{FILE}
+
+@item --init-file @var{FILE}
+@itemx -i @var{FILE}
+Specify options file
+
+@item --account @var{STR}
+@itemx -a @var{STR}
+Specify default account @var{STR} for QIF file postings
+@end ftable
+
@node Report Filtering Quick Reference, Error Checking and Calculation Options, Basic Options Quick Reference, Command Line Quick Reference
@subsection Report Filtering
-@multitable @columnfractions .1 .25 .65
-@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
-@item @code{-c} @tab @code{--current} @tab Display transaction on or before the current date
-@item @code{-b DATE} @tab @code{--begin DATE} @tab Begin reports on or after @code{DATE}
-@item @code{-e DATE} @tab @code{--end DATE} @tab Limits end date of transactions for report
-@item @code{-p STR} @tab @code{--period} @tab Set report period to STR
-@item @code{ } @tab @code{--period-sort} @tab Sort postings within each period
-@item @code{-C} @tab @code{--cleared} @tab Display only cleared postings
-@item @code{} @tab @code{--dc} @tab Display register or balance in debit/credit format
-@item @code{-U} @tab @code{--uncleared} @tab Display only uncleared postings
-@item @code{-R} @tab @code{--real} @tab Display only real postings
-@item @code{-L} @tab @code{--actual} @tab Displays only actual postings, not automated
-@item @code{-r} @tab @code{--related} @tab Display related postings
-@item @code{} @tab @code{--budget} @tab Display how close your postings meet your budget
-@item @code{} @tab @code{--add-budget} @tab Shows un-budgeted postings
-@item @code{} @tab @code{--unbudgeted} @tab Shows only un-budgeted postings
-@item @code{} @tab @code{--forecast} @tab Project balances into the future
-@item @code{-l EXPR} @tab @code{--limit EXPR} @tab Limits postings in calculations
-@item @code{-t EXPR} @tab @code{--amount} @tab Change value expression reported in register report
-@item @code{-T EXPR} @tab @code{--total} @tab Change the value expression used for ``totals'' column in register and balance reports
-@end multitable
+
+@ftable @code
+@item --current
+@itemx -c
+Display transaction on or before the current date
+@item --begin @var{DATE}
+@itemx -b @var{DATE}
+Begin reports on or after @var{DATE}
+@item --end @var{DATE}
+@itemx -e @var{DATE}
+Limit end date of transactions for report
+@item --period @var{PERIOD_EXPRESSION}
+@itemx -p @var{PERIOD_EXPRESSION}
+Set report period to @var{PERIOD_EXPRESSION}
+@item --period-sort @var{VEXPR}
+Sort postings within each period
+@item --cleared
+@itemx -C
+Display only cleared postings
+@item --dc
+Display register or balance in debit/credit format
+@item --uncleared
+@itemx -U
+Display only uncleared postings
+@item --real
+@itemx -R
+Display only real postings
+@item --actual
+@itemx -L
+Display only actual postings, not automated
+@item --related
+@itemx -r
+Display related postings
+@item --budget
+Display how close your postings meet your budget
+@item --add-budget
+Show un-budgeted postings
+@item --unbudgeted
+Show only un-budgeted postings
+@item --forecast
+Project balances into the future
+@item --limit @var{EXPR}
+@itemx -l @var{EXPR}
+Limit postings in calculations
+@item --amount @var{EXPR}
+@itemx -t @var{EXPR}
+Change value expression reported in @command{register} report
+@item --total @var{VEXPR}
+@itemx -T @var{VEXPR}
+Change the value expression used for ``totals'' column in
+@command{register} and @command{balance} reports
+@end ftable
@node Error Checking and Calculation Options, Output Customization Quick Reference, Report Filtering Quick Reference, Command Line Quick Reference
-@subsection Error Checking and Calculation Options
-
-@multitable @columnfractions .1 .25 .65
-@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
-@item @code{} @tab @code{--strict} @tab accounts, tags or commodities not previously declared will cause warnings
-@item @code{} @tab @code{--pedantic} @tab accounts, tags or commodities not previously declared will cause errors
-@item @code{} @tab @code{--check-payees} @tab enable strict and pedantic checking for payees as well as accounts, commodities and tags.
-@item @code{} @tab @code{--immediate} @tab instructs ledger to evaluate calculations immediately rather than lazily
-@end multitable
+@subsection Error Checking and Calculation Options
+@ftable @code
+@item --strict
+Accounts, tags or commodities not previously declared will cause warnings
+@item --pedantic
+Accounts, tags or commodities not previously declared will cause errors
+@item --check-payees
+Enable strict and pedantic checking for payees as well as accounts, commodities and tags
+@item --immediate
+Instruct ledger to evaluate calculations immediately rather than lazily
+@end ftable
@node Output Customization Quick Reference, Grouping Options, Error Checking and Calculation Options, Command Line Quick Reference
@subsection Output Customization
-@multitable @columnfractions .15 .4 .45
-@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
-@item @code{-n} @tab @code{--collapse} @tab Collapse transactions with multiple postings
-@item @code{-s} @tab @code{--subtotal} @tab Report register as a single subtotal
-@item @code{-P} @tab @code{--by-payee} @tab Report subtotals by payee
-@item @code{-E} @tab @code{--empty} @tab Include empty accounts in report
-@item @code{-W} @tab @code{--weekly} @tab Report posting totals by week
-@item @code{-Y} @tab @code{--yearly} @tab Report posting totals by year
-@item @code{} @tab @code{--dow} @tab report Posting totals by day of week
-@item @code{-S EXPR} @tab @code{--sort EXPR} @tab Sorts a report using @code{EXPR}
-@item @code{-w} @tab @code{--wide} @tab Assume 132 columns instead of 80
-@item @code{} @tab @code{--head N} @tab Report the first N postings
-@item @code{} @tab @code{--tail N} @tab Report the last N postings
-@item @code{} @tab @code{--pager PATH} @tab Direct output to @code{PATH} 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 to format the output for plots
-@item @tab @code{--plot-amount-format STR} @tab specify the format for the plot output
-@item @code{-J} @tab @code{--total-data} @tab Show only dates and totals to format the output for plots
-@item @tab @code{--plot-total-format STR} @tab specify the format for the plot output
-@item @code{-d EXPR} @tab @code{--display EXPR} @tab Display only posting that meet the criteris in the EXPR
-@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{--prices-format STR} @tab
-@item @code{-w register} @tab @code{--wide-register-format STR} @tab
-@item @code{} @tab @code{--anon} @tab Print the ledger register with anonymized accounts and payees, useful for filing bug reports
-@end multitable
+
+@ftable @code
+@item --collapse
+@itemx -n
+Collapse transactions with multiple postings
+@item --subtotal
+@itemx -s
+Report register as a single subtotal
+@item --by-payee
+@itemx -P
+Report subtotals by payee
+@item --empty
+@itemx -E
+Include empty accounts in report
+@item --weekly
+@itemx -W
+Report posting totals by week
+@item --yearly
+@itemx -Y
+Report posting totals by year
+@item --dow
+Report Posting totals by day of week
+@item --sort @var{VEXPR}
+@itemx -S @var{VEXPR}
+Sort a report using @var{VEXPR}
+@item --wide
+@itemx -w
+Assume 132 columns instead of 80
+@item --head @var{INT}
+Report the first @var{INT} postings
+@item --tail @var{INT}
+Report the last @var{INT} postings
+@item --pager @var{FILE}
+Direct output to @var{FILE} pager program
+@item --average
+@itemx -A
+Report average posting value
+@item --deviation
+@itemx -D
+Report each posting deviation from the average
+@item --percent
+@itemx -%
+Show subtotals in the balance report as percentages
+@c @item --totals
+@c Include running total in the @code{xml} report
+@item --pivot @var{TAG}
+Produce a pivot table of the @var{TAG} type specified
+@item --amount-data
+@itemx -j
+Show only date and value column to format the output for plots
+@item --plot-amount-format @var{FORMAT_STRING}
+Specify the format for the plot output
+@item --total-data
+@itemx -J
+Show only dates and totals to format the output for plots
+@item --plot-total-format @var{FORMAT_STRING}
+Specify the format for the plot output
+@item --display @var{EXPR}
+@itemx -d @var{EXPR}
+Display only posting that meet the criterias in the @var{EXPR}
+@item --date-format @var{DATE_FORMAT}
+@itemx -y @var{DATE_FORMAT}
+Change the basic date format used in reports
+@item --format @var{FORMAT_STRING}
+@itemx --balance-format @var{FORMAT_STRING}
+@itemx --register-format @var{FORMAT_STRING}
+@itemx --prices-format @var{FORMAT_STRING}
+@itemx -F @var{FORMAT_STRING}
+Set reporting format
+@item --wide
+@itemx -w
+Wide
+@item --anon
+Print the ledger register with anonymized accounts and payees, useful for filing bug reports
+@end ftable
@node Grouping Options, Commodity Reporting Quick Reference, Output Customization Quick Reference, Command Line Quick Reference
@subsection Grouping Options
-@multitable @columnfractions .1 .25 .65
-@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
-@item @code{-P} @tab @code{--by-payee} @tab Group postings by common payee names
-@item @code{-D} @tab @code{--daily} @tab Group postings by day
-@item @code{-W} @tab @code{--weekly} @tab Group postings by week
-@item @code{-M} @tab @code{--monthly} @tab Group postings by month
-@item @code{} @tab @code{--quarterly} @tab Group postings by quarter
-@item @code{-Y} @tab @code{--yearly} @tab Group postings by year
-@item @code{} @tab @code{--dow} @tab Group by day of weeks
-@item @code{-s} @tab @code{--subtotal} @tab Group posting together, similar to balance report
-@end multitable
+
+@ftable @code
+@item --by-payee
+@itemx -P
+Group postings by common payee names
+@item --daily
+@itemx -D
+Group postings by day
+@item --weekly
+@itemx -W
+Group postings by week
+@item --monthly
+@itemx -M
+Group postings by month
+@item --quarterly
+Group postings by quarter
+@item --yearly
+@itemx -Y
+Group postings by year
+@item --dow
+Group by day of weeks
+@item --subtotal
+@itemx -s
+Group posting together, similar to balance report
+@end ftable
@node Commodity Reporting Quick Reference, , Grouping Options, Command Line Quick Reference
@subsection Commodity Reporting
-@multitable @columnfractions .1 .25 .65
-@item @strong{Short} @tab @strong{Long} @tab @strong{Description}
-@item @code{} @tab @code{--price-db FILE} @tab Use @file{FILE} for retrieving stored commodity prices
-@item @code{-L MINS} @tab @code{--price-exp MINS} @tab Set expected freshness of prices in minutes
-@item @code{-Q} @tab @code{--download} @tab Download quotes using @code{getquote}
-@item @code{} @tab @code{--getquote} @tab Sets path to a user defined script to download commodity prices.
-@item @code{-O} @tab @code{--quantity} @tab Report commodity totals without conversion
-@item @code{-B} @tab @code{--basis} @tab Report cost basis
-@item @code{-V} @tab @code{--market} @tab Report last known market value
-@item @code{-G} @tab @code{--gain} @tab Report net gain loss for commodities that have a price history
-@end multitable
+@ftable @code
+@item --price-db @var{FILE}
+Use @file{FILE} for retrieving stored commodity prices.
+@item --price-exp @var{INT}
+@itemx -L @var{INT}
+Set expected freshness of prices in @var{INT} minutes.
+@item --download
+@itemx -Q
+Download quotes using named @file{getquote}.
+@item --getquote @var{FILE}
+Sets path to a user defined script to download commodity prices.
+@item --quantity
+@itemx -O
+Report commodity totals without conversion.
+@item --basis
+@itemx -B
+Report cost basis.
+@item --market
+@itemx -V
+Report last known market value.
+@item --gain
+@itemx -G
+Report net gain loss for commodities that have a price history.
+@end ftable
@node Detailed Options Description, Period Expressions, Command Line Quick Reference, Command-line Syntax
@section Detailed Option Description
@menu
-* Global Options::
-* Session Options::
-* Report Options::
-* Report Filtering::
-* Output Customization::
-* Commodity Reporting::
-* Environment Variables::
+* Global Options::
+* Session Options::
+* Report Options::
+* Basic options::
+* Report Filtering::
+* Output Customization::
+* Commodity Reporting::
+* Environment Variables::
@end menu
@node Global Options, Session Options, Detailed Options Description, Detailed Options Description
@@ -4861,25 +5250,30 @@ 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.
-@table @code
-@item --args-only
+@ftable @code
+@item --args-only
Ignore all environment and init-file settings and
use only command-line arguments to control Ledger. Useful for debugs
or testing small Journal files not associated with you main financial
database.
+@item --debug @var{CODE}
+FIX THIS ENTRY @c FIXME thdox
+
@item --help
-Displays the info page for ledger.
+@itemx -h
+Display the info page for ledger.
-@item --init-file <PATH>
-Specifies the location of the init file. The default is @file{~/.ledgerrc}
+@item --init-file @var{FILE}
+Specify the location of the init file. The default is @file{~/.ledgerrc}
@item --options
- Display the options in effect for this Ledger invocation, along with
+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
-===============================================================================
+$ ledger --options bal --cleared -f ~/ledger/test/input/drewr3.dat
+===========================================================================
[Global scope options]
[Session scope options]
@@ -4898,22 +5292,40 @@ their values and the source of those values, for example:
--account-width = 21 ?normalize
--amount-width = 12 ?normalize
--total-width = 12 ?normalize
-===============================================================================
+===========================================================================
$ 775.00 Assets:Checking
$ -1,000.00 Equity:Opening Balances
$ 225.00 Expenses:Food:Groceries
--------------------
0
@end smallexample
-@noindent For the source column, a value starting with a @code{-} or
-@code{--} indicated the source was a command line argument. It the
-entry starts with a @code{$}, the source was an environment
-variable. If the source is @code{?normalize} the value was set
-internally by ledger, in a function called @code{normalize_options}.
-@item --script <PATH>
+@noindent
+For the source column, a value starting with a @samp{-} or @samp{--}
+indicated the source was a command line argument. It the entry starts
+with a @samp{$}, the source was an environment variable. If the source
+is @code{?normalize} the value was set internally by ledger, in
+a function called @code{normalize_options}.
+
+@item --script @var{FILE}
Execute a ledger script.
-@end table
+
+@item --trace @var{INT}
+FIX THIS ENTRY @c FIXME thdox
+
+@item --verbose
+@itemx -v
+FIX THIS ENTRY @c FIXME thdox
+
+@item --verify
+FIX THIS ENTRY @c FIXME thdox
+
+@item --verify-memory
+FIX THIS ENTRY @c FIXME thdox
+
+@item --version
+FIX THIS ENTRY @c FIXME thdox
+@end ftable
@node Session Options, Report Options, Global Options, Detailed Options Description
@subsection Session Options
@@ -4925,38 +5337,54 @@ 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.
-@table @code
+@ftable @code
+@item --cache @var{FIXME}
+FIX THIS ENTRY @c FIXME thdox
+
+@item --check-payees
+FIX THIS ENTRY @c FIXME thdox
+
+@item --day-break
+FIX THIS ENTRY @c FIXME thdox
+
@item --decimal-comma
Direct Ledger to parse journals using the European standard comma as
decimal separator, vice a period.
@item --download
+@itemx -Q
Direct Ledger to download prices using the script defined in
-@code{--getquote}.
+@code{--getquote @var{FILE}}.
+
+@item --explicit
+FIX THIS ENTRY @c FIXME thdox
-@item --file <PATH>
-Specify the input file path for this invocation.
+@item --file @var{FILE}
+@itemx -f @var{FILE}
+Specify the input @file{FILE} for this invocation.
+@item --getquote @var{FILE}
@cindex getquote
-@cindex download prices
-@item --getquote <PATH>
-Tells ledger where to find the user defined script to download prices
+@cindex download prices
+Tell ledger where to find the user defined script to download prices
information.
-@item --input-date-format <DATE-FORMAT>
+@item --input-date-format @var{DATE_FORMAT}
Specify the input date format for journal entries. For example,
+
@smallexample
-ledger convert Export.csv --input-date-format "%m/%d/%Y"
+$ ledger convert Export.csv --input-date-format "%m/%d/%Y"
@end smallexample
-Would convert the @file{Export.csv} file to ledger format, assuming the
-the dates in the CSV file are like 12/23/2009 (@pxref{Date and Time Format Codes}).
+Would convert the @file{Export.csv} file to ledger format, assuming
+the dates in the CSV file are like 12/23/2009 (@pxref{Date and Time
+Format Codes}).
+@item --master-account @var{STR}
+Prepend all account names with the argument.
-@item --master-account <STRING>
-Prepends all account names with the argument.
@smallexample
-21:51:39 ~/ledger (next)> ledger -f test/input/drewr3.dat bal --master-account HUMBUG
+$ ledger -f test/input/drewr3.dat bal --master-account HUMBUG
0 HUMBUG
$ -3,804.00 Assets
$ 1,396.00 Checking
@@ -4970,7 +5398,7 @@ Prepends all account names with the argument.
$ 300.00 Escrow
$ 334.00 Food:Groceries
$ 500.00 Interest:Mortgage
- $ -5,520.00 ssets:Checking
+ $ -5,520.00 Assets:Checking
$ -2,030.00 Income
$ -2,000.00 Salary
$ -30.00 Sales
@@ -4979,26 +5407,43 @@ Prepends all account names with the argument.
$ 200.00 Mortgage:Principal
@end smallexample
-@item --price-db <PATH>
+@item --pedantic
+FIX THIS ENTRY @c FIXME thdox
+
+@item --permissive
+FIX THIS ENTRY @c FIXME thdox
+
+@item --price-db @var{FILE}
Specify the location of the price entry data file.
-@item --price-exp INTEGER_MINUTES
-Set the expected freshness of price quotes, in minutes. That is, if the
-last known quote for any commodity is older than this value, and if
-@code{--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.
+@item --price-exp @var{INT}
+@itemx -Z @var{INT}
+@itemx --leeway @var{INT}
+Set the expected freshness of price quotes, in @var{INT} minutes. That
+is, if the last known quote for any commodity is older than this
+value, and if @code{--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.
@item --strict
-Ledger normally silently accepts any account or commodity in a posting,
-even if you have misspelled a common used one. The option
+Ledger normally silently accepts any account or commodity in
+a posting, even if you have misspelled a common used one. The option
@code{--strict} changes that behavior. While running @code{--strict},
-Ledger interprets all cleared transactions as correct, and if it finds a
-new account or commodity (same as a misspelled commodity or account) it
-will issue a warning giving you the file and line number of the problem.
-@end table
-@node Report Options, Report Filtering, Session Options, Detailed Options Description
+Ledger interprets all cleared transactions as correct, and if it finds
+a new account or commodity (same as a misspelled commodity or account)
+it will issue a warning giving you the file and line number of the
+problem.
+
+@item --time-colon
+FIX THIS ENTRY @c FIXME thdox
+
+@item --value-expr @var{FIXME}
+FIX THIS ENTRY @c FIXME thdox
+@end ftable
+
+@node Report Options, Basic options, Session Options, Detailed Options Description
@subsection Report Options
+
Options for Ledger report affect three separate scopes of operation:
Global, Session, and Report. In practice there is very little
difference between these scopes. Ledger 3.0 contains provisions for
@@ -5006,337 +5451,354 @@ 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.
-@table @code
-@item --abbrev-len <INT>
-Sets the minimum
-length an account can be abbreviated to if it doesn't fit inside the
-@code{account-width}. If @code{abbrev-len} is zero, then the account
-name will be truncated on the right. If @code{abbrev-len} is greater
+@ftable @code
+@item --abbrev-len @var{INT}
+Set the minimum length an account can be abbreviated to if it doesn't
+fit inside the @code{account-width}. If @var{INT} is zero, then the
+account name will be truncated on the right. If @var{INT} is greater
than @code{account-width} then the account will be truncated on the
left, with no shortening of the account names in order to fit into the
desired width.
-@item --account <STR>
-Prepend @code{<STR>} to all accounts
-reported. That is, the option @code{--account Personal} would tack
-@code{Personal:} to the beginning of every account reported in a balance
-report or register report.
-@item --account-width <INT>
- Set the width of the account column in
-the @code{register} report to @code{N} characters.
+@item --account @var{STR}
+Prepend @var{STR} to all accounts reported. That is, the option
+@code{--account Personal} would tack @samp{Personal:} to the beginning
+of every account reported in a balance report or register report.
-@item --actual-dates
- Show actual dates of transactions
-(@pxref{Effective Dates}). Also @code{-L}.
+@item --account-width @var{INT}
+Set the width of the account column in the @command{register} report
+to @var{INT} characters.
@item --actual
- Report only real transactions, with no automated or
-virtual transactions used.
+@itemx -L
+Report only real transactions, with no automated or virtual
+transactions used.
@item --add-budget
- Show only unbudgeted postings.
+Show only un-budgeted postings.
+
+@item --amount @var{EXPR}
+@itemx -t @var{EXPR}
+Apply the given value expression to the posting amount (@pxref{Value
+Expressions}). Using @code{--amount} you can apply an arbitrary
+transformation to the postings.
@item --amount-data
- On a register report print only the dates and
-amount of postings. Useful for graphing and spreadsheet applications.
+@itemx -j
+On a register report print only the dates and amount of postings.
+Useful for graphing and spreadsheet applications.
+@item --amount-width @var{INT}
+Set the width in characters of the amount column in the
+@command{register} report.
-@item --amount <EXPR>
- Apply the given value expression to the posting
-amount (@pxref{Value Expressions}). Using @code{--amount} you can apply
-an arbitrary transformation to the postings.
+@item --anon
+Anonymize registry output, mostly for sending in bug reports.
-@item --amount-width <INT>
- Set the width in characters of the amount
-column in the register report.
+@item --auto-match
+FIX THIS ENTRY @c FIXME thdox
-@item --anon
- anonymizes registry output, mostly for sending in bug
-reports.
+@item --aux-date
+@itemx --effective
+Show auxiliary dates for all calculations (@pxref{Effective Dates}).
@item --average
- Print average values over the number of transactions
-instead of running totals.
+@itemx -A
+Print average values over the number of transactions instead of
+running totals.
+
+@item --balance-format @var{FORMAT_STRING}
+Specify the format to use for the @code{balance} report (@pxref{Format
+Strings}). The default is:
-@item --balance-format <STR>
- specifies the format to use for the
-@code{balance} report (@pxref{Format Strings}). The default is:
@smallexample
- "%(justify(scrub(display_total), 20, -1, true, color))"
- " %(!options.flat ? depth_spacer : \"\")"
- "%-(ansify_if(partial_account(options.flat), blue if color))\n%/"
- "%$1\n%/"
- "--------------------\n"
+"%(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
@item --base
- ASK JOHN
+FIX THIS ENTRY @c ASK JOHN
@item --basis
- Report the cost basis on all posting
+@itemx -B
+@itemx --cost
+Report the cost basis on all posting
-@item --begin <DATE>
- Specify the start date of all calculations.
-Transactions before that date will be ignored.
+@item --begin @var{DATE}
+Specify the start @var{DATE} of all calculations. Transactions before
+that date will be ignored.
-@item --bold-if <EXPR>
- print the entire line in bold if the given
-value expression is true (@pxref{Value Expressions}).
+@item --bold-if @var{VEXPR}
+Print the entire line in bold if the given value expression is true
+(@pxref{Value Expressions}).
@smallexample
-ledger reg Expenses --begin Dec --bold-if "amount > 100"
+$ ledger reg Expenses --begin Dec --bold-if "amount > 100"
@end smallexample
-@noindent list all transactions since the beginning of December and bold any posting greater than $100
-
-@item --budget-format <FORMAT_STRING>
-specifies the format to use for the @code{budget} report (@pxref{Format Strings}). The default is:
-@smallexample
- "%(justify(scrub(display_total), 20, -1, true, color))"
- " %(!options.flat ? depth_spacer : \"\")"
- "%-(ansify_if(partial_account(options.flat), blue if color))\n%/"
- "%$1\n%/"
- "--------------------\n"
-@end smallexample
+@noindent
+list all transactions since the beginning of December and bold any
+posting greater than $100
@item --budget
- only display budgeted items. In a register report this
+Only display budgeted items. In a register report this
displays transaction in the budget, in a balance report this displays
accounts in the budget (@pxref{Budgeting and Forecasting}).
-@item --by-payee <REGEXP>
-
-group the register report by payee.
-
-@item --cleared-format <FORMAT_STRING>
- specifies the format to use
-for the @code{cleared} report (@pxref{Format Strings}). The default is:
+@item --budget-format @var{FORMAT_STRING}
+Specify the format to use for the @code{budget} report (@pxref{Format
+Strings}). The default is:
@smallexample
- "%(justify(scrub(get_at(total_expr, 0)), 16, 16 + prepend_width, "
- " true, color)) %(justify(scrub(get_at(total_expr, 1)), 18, "
- " 36 + prepend_width, true, color))"
- " %(latest_cleared ? format_date(latest_cleared) : \" \")"
- " %(!options.flat ? depth_spacer : \"\")"
- "%-(ansify_if(partial_account(options.flat), blue if color))\n%/"
- "%$1 %$2 %$3\n%/"
- "%(prepend_width ? \" \" * prepend_width : \"\")"
- "---------------- ---------------- ---------\n"
+"%(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
+@item --by-payee
+@itemx -P
+Group the register report by payee.
+
@item --cleared
- consider only transaction that have been cleared for
+@itemx -C
+Consider only transaction that have been cleared for
display and calculation.
+@item --cleared-format @var{FORMAT_STRING}
+FIX THIS ENTRY @c FIXME thdox: to keep?
+Specify the format to use for the @code{cleared} report (@pxref{Format
+Strings}). The default is:
+
+@smallexample
+"%(justify(scrub(get_at(total_expr, 0)), 16, 16 + prepend_width, "
+" true, color)) %(justify(scrub(get_at(total_expr, 1)), 18, "
+" 36 + prepend_width, true, color))"
+" %(latest_cleared ? format_date(latest_cleared) : \" \")"
+" %(!options.flat ? depth_spacer : \"\")"
+"%-(ansify_if(partial_account(options.flat), blue if color))\n%/"
+"%$1 %$2 %$3\n%/"
+"%(prepend_width ? \" \" * prepend_width : \"\")"
+"---------------- ---------------- ---------\n"
+@end smallexample
+
@item --collapse
- By default ledger prints all account in an account
-tree. With @code{--collapse} it print only the top level account
-specified.
+@itemx -n
+By default ledger prints all account in an account tree. With
+@code{--collapse} it print only the top level account specified.
@item --collapse-if-zero
- Collapses the account display only if it has
+Collapse the account display only if it has
a zero balance.
@item --color
- use color is the tty supports it.
+@itemx --ansi
+Use color is the tty supports it.
-@item --columns <INT>
- specify the width of the register report in
-characters.
+@item --columns @var{INT}
+Specify the width of the @command{register} report in characters.
@item --count
- Direct ledger to report the number of items when
+Direct ledger to report the number of items when
appended to the commodities, accounts or payees command.
-@item --csv-format
- specifies the format to use for the @code{csv}
-report (@pxref{Format Strings}). The default is:
+@item --csv-format @var{FORMAT_STRING}
+Specify the format to use for the @code{csv} report (@pxref{Format
+Strings}). The default is:
+
@smallexample
- "%(quoted(date)),"
- "%(quoted(code)),"
- "%(quoted(payee)),"
- "%(quoted(display_account)),"
- "%(quoted(commodity)),"
- "%(quoted(quantity(scrub(display_amount)))),"
- "%(quoted(cleared ? \"*\" : (pending ? \"!\" : \"\"))),"
- "%(quoted(join(note | xact.note)))\n"
+"%(quoted(date)),"
+"%(quoted(code)),"
+"%(quoted(payee)),"
+"%(quoted(display_account)),"
+"%(quoted(commodity)),"
+"%(quoted(quantity(scrub(display_amount)))),"
+"%(quoted(cleared ? \"*\" : (pending ? \"!\" : \"\"))),"
+"%(quoted(join(note | xact.note)))\n"
@end smallexample
-@item --current
+@item --current
Shorthand for @code{--limit "date <= today"}
@item --daily
-
+@itemx -D
Shorthand for @code{--period "daily"}
-@item --date-format <DATE-FORMAT>
- specifies format ledger should use
-to print dates (@pxref{Date and Time Format Codes}).
+@item --date @var{EXPR}
+Transform the date of the transaction using @var{EXPR}.
-@item --date <EXPR>
- transforms the date of the transaction using
-@code{EXPR}
+@item --date-format @var{DATE_FORMAT}
+@itemx -y @var{DATE_FORMAT}
+Specify format ledger should use to print dates (@pxref{Date and Time
+Format Codes}).
-@item --date-width <INT>
- specifies the width, in characters, of the
-date column in the register report.
+@item --date-width @var{INT}
+Specify the width, in characters, of the date column in the
+@command{register} report.
-@item --datetime-format
-
-ASK JOHN
+@item --datetime-format @var{FIXME}
+FIX THIS ENTRY @c ASK JOHN
@item --dc
- Display register or balance in debit/credit format
-If you use @code{--dc} with either the register (reg) or balance (bal) commands, you
-will now get extra columns. The register goes from this:
-@smallexample
- 12-Mar-10 Employer Assets:Cash $100 $100
- Income:Employer $-100 0
- 12-Mar-10 KFC Expenses:Food $20 $20
- Assets:Cash $-20 0
- 12-Mar-10 KFC - Rebate Assets:Cash $5 $5
- Expenses:Food $-5 0
- 12-Mar-10 KFC - Food & Reb.. Expenses:Food $20 $20
- Expenses:Food $-5 $15
- Assets:Cash $-15 0
-@end smallexample
-@noindent To this:
-@smallexample
- 12-Mar-10 Employer Assets:Cash $100 0 $100
- In:Employer 0 $100 0
- 12-Mar-10 KFC Expens:Food $20 0 $20
- Assets:Cash 0 $20 0
- 12-Mar-10 KFC - Rebate Assets:Cash $5 0 $5
- Expens:Food 0 $5 0
- 12-Mar-10 KFC - Food &.. Expens:Food $20 0 $20
- Expens:Food 0 $5 $15
- Assets:Cash 0 $15 0
-@end smallexample
-
-@noindent Where the first column is debits, the second is credits, and the third is the
-running total. Only the running total may contain negative values.
+Display register or balance in debit/credit format If you use
+@code{--dc} with either the register (reg) or balance (bal) commands,
+you will now get extra columns. The register goes from this:
-For the balance report without @code{--dc}:
+@smallexample
+12-Mar-10 Employer Assets:Cash $100 $100
+ Income:Employer $-100 0
+12-Mar-10 KFC Expenses:Food $20 $20
+ Assets:Cash $-20 0
+12-Mar-10 KFC - Rebate Assets:Cash $5 $5
+ Expenses:Food $-5 0
+12-Mar-10 KFC - Food & Reb.. Expenses:Food $20 $20
+ Expenses:Food $-5 $15
+ Assets:Cash $-15 0
+@end smallexample
+
+@noindent
+To this:
@smallexample
- $70 Assets:Cash
- $30 Expenses:Food
- $-100 Income:Employer
- --------------------
- 0
+12-Mar-10 Employer Assets:Cash $100 0 $100
+ In:Employer 0 $100 0
+12-Mar-10 KFC Expens:Food $20 0 $20
+ Assets:Cash 0 $20 0
+12-Mar-10 KFC - Rebate Assets:Cash $5 0 $5
+ Expens:Food 0 $5 0
+12-Mar-10 KFC - Food &.. Expens:Food $20 0 $20
+ Expens:Food 0 $5 $15
+ Assets:Cash 0 $15 0
@end smallexample
-@noindent And with @code{--dc} it becomes this:
+@noindent
+Where the first column is debits, the second is credits, and the third
+is the running total. Only the running total may contain negative
+values.
+
+For the balance report without @code{--dc}:
@smallexample
- $105 $35 $70 Assets:Cash
- $40 $10 $30 Expenses:Food
- 0 $100 $-100 Income:Employer
- --------------------------------------------
- $145 $145 0
+ $70 Assets:Cash
+ $30 Expenses:Food
+ $-100 Income:Employer
+--------------------
+ 0
@end smallexample
+@noindent
+And with @code{--dc} it becomes this:
-@item --depth <INT>
- limit the depth of the account tree. In a balance report, for example,
-a @code{--depth 2} statement will print balances only for account with
-two levels, i.e. @code{Expenses:Entertainment} but not
-@code{Expenses:entertainemnt:Dining}. This is a display predicate, which
-means it only affects display, not the total calculations.
+@smallexample
+ $105 $35 $70 Assets:Cash
+ $40 $10 $30 Expenses:Food
+ 0 $100 $-100 Income:Employer
+--------------------------------------------
+ $145 $145 0
+@end smallexample
-@item --deviation
- reports each posting’s deviation from the average. It is only
- meaningful in the register and prices reports.
+@item --depth @var{INT}
+Limit the depth of the account tree. In a balance report, for
+example, a @code{--depth 2} statement will print balances only for
+account with two levels, i.e. @code{Expenses:Entertainment} but not
+@code{Expenses:entertainemnt:Dining}. This is a display predicate,
+which means it only affects display, not the total calculations.
-@item --display-amount <EXPR>
- apply a transform to the
-@strong{displayed} amount. This occurs after calculations occur.
+@item --deviation
+Report each posting’s deviation from the average. It is only
+meaningful in the register and prices reports.
-@item --display <BOOLEAN_EXPR>
+@item --display @var{EXPR}
+Display lines that satisfy the expression given.
-display lines that satisfy the expression given.
+@item --display-amount @var{EXPR}
+Apply a transform to the @emph{displayed} amount. This occurs after
+calculations occur.
-@item --display-total <EXPR>
- apply a transform to the
-@strong{displayed} total. This occurs after calculations occur.
+@item --display-total @var{EXPR}
+Apply a transform to the @emph{displayed} total. This occurs after
+calculations occur.
@item --dow
+@itemx --days-of-week
+Group transactions by the days of the week.
-group transactions by the day of the week.
@smallexample
-ledger reg Expenses --dow --collapse
+$ ledger reg Expenses --dow --collapse
@end smallexample
-@noindent will print all Expenses totalled for each day of the week.
-@item --effective
-
-use effective dates for all calculations (@pxref{Effective Dates}).
+@noindent
+Will print all Expenses totaled for each day of the week.
@item --empty
+@itemx -E
+Include empty accounts in the report.
-include empty accounts in the report.
-
-@item --end <DATE>
-
-specify the end date for transaction to be considered in the report.
+@item --end @var{DATE}
+Specify the end @var{DATE} for transaction to be considered in the
+report.
@item --equity
- related to the @code{equity} command (@pxref{The
+Related to the @code{equity} command (@pxref{The
equity Command}). Gives current account balances in the form of a
register report.
@item --exact
+FIX THIS ENTRY @c ASK JOHN
-ASK JOHN
-
-@item --exchange <COMMODITY>
- display values in terms of the given
-commodity. The latest available price is used.
+@item --exchange @var{COMMODITY}
+@itemx -X @var{COMMODITY}
+Display values in terms of the given @var{COMMODITY}. The latest
+available price is used.
@item --flat
- force the full names of accounts to be used in the
-balance report. The balance report will not use an indented tree.
+Force the full names of accounts to be used in the balance report. The
+balance report will not use an indented tree.
@item --force-color
- output tty color codes even if the tty doesn't
-support them. Useful for TTY that don't advertise their capabilities
-correctly.
+Output tty color codes even if the tty doesn't support them. Useful
+for TTY that don't advertise their capabilities correctly.
@item --force-pager
+Force Ledger to paginate its output.
-force Ledger to paginate its output.
-
-@item --forecast-while <VEXPR>
-Continue forecasting while @code{<VEXPR>} is true.
-
-@item --forecast-years <INT>
-Forecast at most @code{N} years in the future.
+@item --forecast-while @var{VEXPR}
+@itemx --forecast @var{VEXPR}
+Continue forecasting while @var{VEXPR} is true.
-@item --format <FORMAT STRING>
+@item --forecast-years @var{INT}
+Forecast at most @var{INT} years in the future.
-use the given format string to print output.
+@item --format @var{FORMAT_STRING}
+@itemx -F @var{FORMAT_STRING}
+Use the given format string to print output.
@item --gain
-
-report on gains using the latest available prices.
+@itemx -G
+@itemx --change
+Report on gains using the latest available prices.
@item --generated
-Include auto-generated postings (such as those from automated transactions)
-in the report, in cases where you normally wouldn't want
+Include auto-generated postings (such as those from automated
+transactions) in the report, in cases where you normally wouldn't want
them.
-@item --group-by <EXPR>
- group transaction together in the register
-report. @code{EXPR} can be anything, although most common would be
-@code{payee} or @code{commodity}. The @code{tags()} function is
-also useful here.
+@item --group-by @var{EXPR}
+Group transaction together in the @command{register} report.
+@var{EXPR} can be anything, although most common would be @code{payee}
+or @code{commodity}. The @code{tags()} function is also useful here.
+
+@item --group-title-format @var{FORMAT_STRING}
+Set the format for the headers that separate reports section of
+a grouped report. Only has effect with a @code{--group-by} register
+report.
-@item --group-title-format
- sets the format for the headers that
-separate reports section of a grouped report. Only has effect with a
-@code{--group-by} register report.
@smallexample
-ledger reg Expenses --group-by "payee" --group-title-format "------------------------ %-20(value) ---------------------\n"
+$ ledger reg Expenses --group-by "payee" --group-title-format "------------------------ %-20(value) ---------------------\n"
------------------------ 7-Eleven ---------------------
2011/08/13 7-Eleven Expenses:Auto:Misc $ 5.80 $ 5.80
@@ -5348,132 +5810,135 @@ ledger reg Expenses --group-by "payee" --group-title-format "-------------------
...
@end smallexample
+@item --head @var{INT}
+@itemx --first @var{INT}
+Print the first @var{INT} entries. Opposite of @code{--tail}.
-@item --head <INT>
+@item --historical
+@itemx -H
+FIX THIS ENTRY @c FIXME thdox
-Print the first @code{INT} entries. Opposite of @code{--tail}.
+@item --immediate
+FIX THIS ENTRY @c FIXME thdox
@item --inject
Use @code{Expected} amounts in calculations. In the case that you know
that amount a transaction should be, but the actual transaction has the
wrong value you can use metadata to put in the expected amount:
+
@smallexample
2012-03-12 Paycheck
- Income $-990; Expected:: $-1000.00
- Checking
+ Income $-990; Expected:: $-1000.00
+ Checking
@end smallexample
Then using the command @code{ledger reg --inject=Expected Income} would
treat the transaction as if the ``Expected Value'' was actual.
-@item --invert
+@item --invert
Change the sign of all reported values.
-@item --limit <EXPR>
- Only transactions that satisfy the expression will be considered in the
+@item --limit @var{EXPR}
+@itemx -l @var{EXPR}
+Only transactions that satisfy the expression will be considered in the
calculation.
@item --lot-dates
-Report the date on which each commodity in a balance report was purchased.
-
-@item --lot-prices
-
-Report the price at which each commodity in a balance report was purchased.
-
-@item --lot-tags
+Report the date on which each commodity in a balance report was
+purchased.
+@item --lot-notes
+@itemx --lot-tags
Report the tag attached to each commodity in a balance report.
-@item --lots-actual
-
-FIX THIS ENTRY
+@item --lot-prices
+Report the price at which each commodity in a balance report was
+purchased.
@item --lots
+Report the date and price at which each commodity was purchased in
+a balance report.
-Report the date and price at which each commodity was purchased in a balance report.
+@item --lots-actual
+FIX THIS ENTRY
@item --market
-
+@itemx -V
Use the latest market value for all commodities.
-@item --meta <TAG>
-
-In the register report, prepend the transaction with the value of the given tag.
+@item --meta @var{TAG}
+In the register report, prepend the transaction with the value of the
+given @var{TAG}.
-@item --meta-width
-
-Specify the width of the Meta column used for the @code{--meta} options.
+@item --meta-width @var{INT}
+Specify the width of the Meta column used for the @code{--meta}
+options.
@item --monthly
-
-synonym for @code{--period "monthly"}
+@itemx -M
+Synonym for @code{--period "monthly"}
@item --no-color
-
suppress any color TTY output.
@item --no-rounding
-Don't output <Rounding> postings. Note that this will cause the running total
-to often not add up! It's main use is for @code{-j} and @code{-J} reports.
+Don't output <Rounding> postings. Note that this will cause the
+running total to often not add up! It's main use is for @code{-j} and
+@code{-J} reports.
@item --no-titles
-
Suppress the output of group titles
@item --no-total
-
Suppress printing the final total line in a balance report.
-@item --now
+@item --now @var{DATE}
Define the current date in case to you to do calculate in the past or
future using @code{--current}
-@item --only
-
+@item --only @var{FIXME}
This is a postings predicate that applies after certain transforms have
been executed, such as periodic gathering.
-@item --output <PATH>
-Redirect the output of ledger to the file defined in @file{PATH}.
-
-@item --pager
+@item --output @var{FILE}
+Redirect the output of ledger to the file defined in @file{FILE}.
+@item --pager @var{FILE}
Specify the pager program to use.
-@item --payee <VEXPR>
-
-Sets a value expression for formatting the payee. In the register report
-this prevents the second entry from having a date and payee for each
-transaction
+@item --payee @var{VEXPR}
+Sets a value expression for formatting the payee. In the
+@command{register} report this prevents the second entry from having
+a date and payee for each transaction.
-@item --payee-width N
-
-Set the number of columns dedicated to the payee in the register report.
+@item --payee-width @var{INT}
+Set the number of columns dedicated to the payee in the register
+report.
@item --pending
-
Use only postings that are marked pending
@item --percent
+@itemx -%
Calculate the percentage value of each account in a balance reports.
Only works for account that have a single commodity.
-@item --period <PERIOD EXPRESSION>
+@item --period @var{PERIOD_EXPRESSION}
+Define a period expression that sets the time period during which
+transactions are to be accounted. For a @command{register} report only
+the transactions that satisfy the period expression with be displayed.
+For a balance report only those transactions will be accounted in the
+final balances.
-Define a period expression the sets the time period during which
-transactions are to be accounted. For a register report only the
-transactions that satisfy the period expression with be displayed. For
-a balance report only those transactions will be accounted in the final
-balances.
-
-@item --pivot <VALUED TAG>
-
-Produce a balance pivot report ``around'' the given tag. For example,
-if you have multiple cars and track each fuel purchase in
+@item --pivot @var{TAG}
+Produce a balance pivot report ``around'' the given @var{TAG}. For
+example, if you have multiple cars and track each fuel purchase in
@code{Expenses:Auto:Fuel} and tag each fuel purchase with a tag
-identifying which car the purchase was for @code{; Car: Prius}, then the command:
+identifying which car the purchase was for @code{; Car: Prius}, then
+the command:
+
@smallexample
-ledger bal Fuel --pivot "Car" --period "this year"
+$ ledger bal Fuel --pivot "Car" --period "this year"
$ 3491.26 Car
$ 1084.22 M3:Expenses:Auto:Fuel
$ 149.65 MG V11:Expenses:Auto:Fuel
@@ -5485,189 +5950,201 @@ ledger bal Fuel --pivot "Car" --period "this year"
@end smallexample
@xref{Metadata values}.
-@item --plot-amount-format
-Define the output format for a amount data plot. @xref{Visualizing with Gnuplot}.
+@item --plot-amount-format @var{FORMAT_STRING}
+Define the output format for an amount data plot. @xref{Visualizing
+with Gnuplot}.
-@item --plot-total-format
+@item --plot-total-format @var{FORMAT_STRING}
+Define the output format for a total data plot. @xref{Visualizing with
+Gnuplot}.
-Define the output format for a total data plot. @xref{Visualizing with Gnuplot}.
+@item --prepend-format @var{FORMAT_STRING}
+Prepend @var{STR} to every line of the output
-@item --prepend-format STR
+@item --prepend-width @var{INT}
+Reserve @var{INT} spaces at the beginning of each line of the output.
-Prepend STR to every line of the output
-
-@item --prepend-width N
+@item --price
+@itemx -I
+Use the price of the commodity purchase for performing calculations.
-Reserve @code{N} spaces at the beginning of each line of the output
+@item --pricedb-format @var{FORMAT_STRING}
+FIX THIS ENTRY @c FIXME thdox
+@item --prices-format @var{FORMAT_STRING}
+FIX THIS ENTRY @c FIXME thdox
-@item --price
-use the price of the commodity purchase for performing calculations
+@item --primary-date
+@itemx --actual-dates
+Show primary dates for all calculations (@pxref{Effective Dates}).
@item --quantity
-
+@itemx -O
FIX THIS ENTRY
@item --quarterly
-
Synonym for @code{--period "quarterly"}.
@item --raw
-
In the print report, show transactions using the exact same syntax as
specified by the user in their data file. Don't do any massaging or
interpreting. Can be useful for minor cleanups, like just aligning
amounts.
@item --real
+@itemx -R
Account using only real transactions ignoring virtual and automatic
transactions.
-
-@item --related-all
-
-Show all postings in a transaction, similar to @code{--related} but show
-both ``sides'' of each transaction.
+@item --register-format @var{FORMAT_STRING}
+FIX THIS ENTRY @c FIXME thdox
@item --related
-
In a register report show the related account. This is the other
``side'' of the transaction.
-@item --revalued-only
+@item --related-all
+Show all postings in a transaction, similar to @code{--related} but
+show both ``sides'' of each transaction.
+@item --revalued
FIX THIS ENTRY
-@item --revalued-total
-
+@item --revalued-only
FIX THIS ENTRY
-@item --revalued
-
+@item --revalued-total @var{FIXME}
FIX THIS ENTRY
-@item --seed
+@item --rich-data
+@itemx --detail
+FIX THIS ENTRY @c FIXME thdox
-Sets the random seed for the @code{generate} command. Used as part of development testing.
+@item --seed @var{FIXME}
+Set the random seed for the @code{generate} command. Used as part of
+development testing.
-@item --sort-all
+@item --sort @var{VEXPR}
+@itemx -S @var{VEXPR}
+Sort the register report based on the value expression given to sort.
+@item --sort-all @var{FIXME}
FIX THIS ENTRY
-@item --sort <VEXPR>
-
-Sort the register report based on the value expression given to sort
-
-@item --sort-xacts <VEXPR>
+@item --sort-xacts @var{VEXPR}
+@itemx --period-sort @var{VEXPR}
+Sort the posting within transactions using the given value expression.
-Sort the posting within transactions using the given value expression
-
-@item --start-of-week <INT>
+@item --start-of-week @var{INT}
Tell ledger to use a particular day of the week to start its ``weekly''
summary. @code{--start-of-week=1} specifies Monday as the start of the
week.
@item --subtotal
-
FIX THIS ENTRY
-@item --tail <INT>
+@item --tail @var{INT}
+@itemx --last @var{INT}
+Report only the last @var{INT} entries. Only useful on a register
+report.
-report only the last @code{INT} entries. Only useful on a register report.
+@item --time-report
+FIX THIS ENTRY @c FIXME thdox
-@item --total-data
+@item --total @var{VEXPR}
+@itemx -T @var{VEXPR}
+Define a value expression used to calculate the total in reports.
+@item --total-data
+@itemx -J
FIX THIS ENTRY
-@item --total <VEXPR>
-Define a value expression used to calculate the total in reports.
-
-@item --total-width
+@item --total-width @var{INT}
Set the width of the total field in the register report.
-@item --truncate
+@item --truncate @var{CODE}
Indicates how truncation should happen when the contents of columns
-exceed their width. Valid arguments are @code{leading}, @code{middle},
-and @code{trailing}. The default is smarter than any of these three, as
-it considers sub-names within the account name (that style is called
-``abbreviate'').
+exceed their width. Valid arguments are @samp{leading}, @samp{middle},
+and @samp{trailing}. The default is smarter than any of these three,
+as it considers sub-names within the account name (that style is
+called ``abbreviate'').
@item --unbudgeted
-
FIX THIS ENTRY
@item --uncleared
-
+@itemx -U
Use only uncleared transactions in calculations and reports.
-@item --unrealized-gains
-
+@item --unrealized
FIX THIS ENTRY
-@item --unrealized-losses
-
+@item --unrealized-gains @var{FIXME}
FIX THIS ENTRY
-@item --unrealized
-
+@item --unrealized-losses @var{FIXME}
FIX THIS ENTRY
@item --unround
-Perform all calculations without rounding and display results to full precision.
+Perform all calculations without rounding and display results to full
+precision.
-@item --weekly
+@item --values
+FIX THIS ENTRY @c FIXME thdox
-synonym for @code{--period "weekly"}
+@item --weekly
+@itemx -W
+Synonym for @code{--period "weekly"}
@item --wide
-lets the register report use 132 columns. Identical to @code{--columns
+Let the register report use 132 columns. Identical to @code{--columns
"132"}
@item --yearly
-synonym for @code{--period "yearly"}
-
-@end table
-
+@itemx -Y
+Synonym for @code{--period "yearly"}
+@end ftable
+@node Basic options, Report Filtering, Report Options, Detailed Options Description
@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:
+want to set them using environment variables (see @ref{Environment
+Variables}), instead of using actual command-line options:
-@table @code
-@item --help
-@item -h
-Prints a summary of all the options, and what they are used for. This
+@ftable @code
+@item --help
+@itemx -h
+Print 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.
-@item --version
-@item -v
-prints the current version of ledger and exits. This is useful for
+@item --version
+@itemx -v
+Print 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.
-@item --file FILE
-@item -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.
+@item --file @var{FILE}
+@itemx -f @var{FILE}
+Read @file{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.
-@item --output FILE
-@item -o FILE
-redirects output from any command to @var{FILE}. By default, all output
+@item --output @var{FILE}
+@itemx -o @var{FILE}
+Redirect output from any command to @file{FILE}. By default, all output
goes to standard output.
-@item --init-file FILE
-@item -i FILE
-causes @code{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:
+@item --init-file @var{FILE}
+@itemx -i @var{FILE}
+Causes @file{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 its own line. Here is an
+example init file:
@smallexample
--price-db ~/finance/.pricedb
@@ -5678,84 +6155,84 @@ init file:
Option settings on the command-line or in the environment always take
precedence over settings in the init file.
-
-@item --account NAME
-@item -a NAME
-specifies the default account which QIF file postings are assumed to
+@item --account @var{STR}
+@itemx -a @var{STR}
+Specify the default account which QIF file postings are assumed to
relate to.
-@end table
+@end ftable
-@node Report Filtering, Output Customization, Report Options, Detailed Options Description
+@node Report Filtering, Output Customization, Basic 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:
-@table @code
+@ftable @code
@item --current
-@item -c
-displays only transactions occurring on or before the current date.
+@itemx -c
+Display only transactions occurring on or before the current date.
-@item --begin DATE
-@item -b DATE
-constrains the report to transactions on or after @var{DATE}. Only
+@item --begin @var{DATE}
+@itemx -b @var{DATE}
+Constrain 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
@code{--display} to constrain what is displayed).
-@item --end DATE
-@item -e DATE
-constrains the report so that transactions on or after @var{DATE} are
+@item --end @var{DATE}
+@itemx -e @var{DATE}
+Constrain the report so that transactions on or after @var{DATE} are
not considered. The ending date is inclusive.
-@item --period STR
-@item -p STR
-sets the reporting period to @var{STR}. This will subtotal all matching
+@item --period @var{PERIOD_EXPRESSION}
+@itemx -p @var{PERIOD_EXPRESSION}
+Set 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}.
-@item --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:
+@item --period-sort @var{VEXPR}
+Sort 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
+$ ledger -M --period-sort -At reg ^Expenses
@end smallexample
@item --cleared
-@item -C
- displays only postings whose transaction has been marked ``cleared''
+@itemx -C
+Display only postings whose transaction has been marked ``cleared''
(by placing an asterisk to the right of the date).
@item --uncleared
-@item -U
-displays only postings whose transaction has not been marked ``cleared''
+@itemx -U
+Display only postings whose transaction has not been marked ``cleared''
(i.e., if there is no asterisk to the right of the date).
@item --real
-@item -R
- displays only real postings, not virtual. (A virtual posting is
+@itemx -R
+Display only real postings, not virtual. (A virtual posting is
indicated by surrounding the account name with parentheses or brackets;
see @ref{Virtual postings} for more information).
@item --actual
-@item -L
-displays only actual postings, and not those created due to automated
+@itemx -L
+Display only actual postings, and not those created due to automated
postings.
@item --related
-@item -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:
+@itemx -r
+Display 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
@@ -5767,81 +6244,83 @@ related posting. For example, if a file had this transaction:
And the register command was:
@smallexample
-ledger -r register food
+$ 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
+2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00
+ Assets:Checking $85.00 $65.00
@end smallexample
@item --budget
-is useful for displaying how close your postings meet your budget.
+Useful for displaying how close your postings meet your budget.
@code{--add-budget} also shows un-budgeted postings, while
@code{--unbudgeted} shows only those. @code{--forecast} is a related
option that projects your budget into the future, showing how it will
affect future balances. @xref{Budgeting and Forecasting}.
-@item --limit EXPR
-@item -l EXPR
-limits which postings take part in the calculations of a report.
+@item --limit @var{EXPR}
+@itemx -l @var{EXPR}
+Limit which postings take part in the calculations of a report.
-@item --amount EXPR
-@item -t EXPR
-changes the value expression used to calculate the ``value'' column in
+@item --amount @var{EXPR}
+@itemx -t @var{EXPR}
+Change 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}.
-@item --total EXPR
-@item -T EXPR
-sets the value expression used for the ``totals'' column in the
+@item --total @var{VEXPR}
+@itemx -T @var{VEXPR}
+Set the value expression used for the ``totals'' column in the
@command{register} and @command{balance} reports.
-@end table
+@end ftable
+
@c @node Search Terms, Output Customization, Report Filtering, Detailed Options Description
@c @subsection Search Terms
@c Valid Ledger invocations look like:
@c @smallexample
-@c ledger [OPTIONS] <COMMAND> <SEARCH-TERMS>
+@c ledger [OPTIONS] <COMMAND> <SEARCH-TERMS>
@c @end smallexample
-@c Where @code{COMMAND} is any command verb (@pxref{Reporting Commands}), @code{OPTIONS} can occur
-@c anywhere, and @code{SEARCH-TERM} is one or more of the following:
+@c Where @code{COMMAND} is any command verb (@pxref{Reporting
+@c Commands}), @code{OPTIONS} can occur anywhere, and
+@c @code{SEARCH-TERM} is one or more of the following:
@c @smallexample
-@c word search for any account containing 'word'
-@c TERM and TERM boolean AND between terms
-@c TERM or TERM boolean OR between terms
-@c not TERM invert the meaning of the term
-@c payee word search for any payee containing 'word'
-@c @@word shorthand for 'payee word'
-@c desc word alternate for 'payee word'
-@c note word search for any note containing 'word'
-@c &word shorthand for 'note word'
-@c tag word search for any metadata tag containing 'word'
-@c tag word=value search for any metadata tag containing 'word'
-@c whose value contains 'value'
-@c %word shorthand for 'tag word'
-@c %word=value shorthand for 'tag word=value'
-@c meta word alternate for 'tag word'
-@c meta word=value alternate for 'tag word=value'
-@c expr 'EXPR' apply the given value expression as a predicate
-@c '=EXPR' shorthand for 'expr EXPR'
-@c \( TERMS \) group terms; useful if using and/or/not
+@c word search for any account containing 'word'
+@c TERM and TERM boolean AND between terms
+@c TERM or TERM boolean OR between terms
+@c not TERM invert the meaning of the term
+@c payee word search for any payee containing 'word'
+@c @@word shorthand for 'payee word'
+@c desc word alternate for 'payee word'
+@c note word search for any note containing 'word'
+@c &word shorthand for 'note word'
+@c tag word search for any metadata tag containing 'word'
+@c tag word=value search for any metadata tag containing 'word'
+@c whose value contains 'value'
+@c %word shorthand for 'tag word'
+@c %word=value shorthand for 'tag word=value'
+@c meta word alternate for 'tag word'
+@c meta word=value alternate for 'tag word=value'
+@c expr 'EXPR' apply the given value expression as a predicate
+@c '=EXPR' shorthand for 'expr EXPR'
+@c \( TERMS \) group terms; useful if using and/or/not
@c @end smallexample
-@c So, to list all transaction that charged to ``food'' but not ``dining''
-@c for any payee other than ``chang'' the following three commands would be
-@c equivalent:
+@c So, to list all transaction that charged to ``food'' but not
+@c ``dining'' for any payee other than ``chang'' the following three
+@c commands would be equivalent:
@c @smallexample
-@c ledger reg food not dining @@chang
-@c ledger reg food and not dining and not payee chang
-@c ledger reg food not dining expr 'payee =~ /chang/'
+@c ledger reg food not dining @@chang
+@c ledger reg food and not dining and not payee chang
+@c ledger reg food not dining expr 'payee =~ /chang/'
@c @end smallexample
@node Output Customization, Commodity Reporting, Report Filtering, Detailed Options Description
@@ -5850,115 +6329,117 @@ sets the value expression used for the ``totals'' column in the
These options affect only the output, but not which postings are
used to create it:
-@table @code
+@ftable @code
@item --collapse
-@item -n
-causes transactions in a @command{register} report with multiple
+@itemx -n
+Cause transactions in a @command{register} report with multiple
postings to be collapsed into a single, subtotaled transaction.
@item --subtotal
-@item -s
-causes all transactions in a @command{register} report to be collapsed
+@itemx -s
+Cause all transactions in a @command{register} report to be collapsed
into a single, subtotaled transaction.
@item --by-payee
-@item -P
-reports subtotals by payee.
-
+@itemx -P
+Report subtotals by payee.
@item --empty
-@item -E
-includes even empty accounts in the @command{balance} report.
+@itemx -E
+Include even empty accounts in the @command{balance} report.
@item --weekly
-@item -W
-reports posting totals by the week. The week begins on whichever day of
+@itemx -W
+Report 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 @code{weekly from DATE}.
+
@item --monthly
-@item -M
-reports posting totals by month;
+@itemx -M
+Report posting totals by month;
+
@item --yearly
-@item -Y
-reports posting totals by year. For more complex period, using the
-@item --period
-option described above.
+@itemx -Y
+Report posting totals by year. For more complex period, using the
+
+@item --period @var{PERIOD_EXPRESSION}
+Option described above.
@item --dow
-reports postings totals for each day of the week. This is an easy way
+Report postings totals for each day of the week. This is an easy way
to see if weekend spending is more than on weekdays.
-@item --sort EXPR
-@item -S EXPR
-sorts a report by comparing the values determined using the value
-expression @var{EXPR}. For example, using @code{-S -UT} in the
+@item --sort @var{VEXPR}
+@itemx -S @var{VEXPR}
+Sort a report by comparing the values determined using the value
+expression @var{VEXPR}. For example, using @code{-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}.
-@item --pivot TAG
-produces a pivot table around the tag provided. This requires meta data
-using valued tags.
+@item --pivot @var{TAG}
+Produce a pivot table around the @var{TAG} provided. This requires
+meta data using valued tags.
@item --wide
-@item -w
-causes the default @command{register} report to assume 132 columns
+@itemx -w
+Cause the default @command{register} report to assume 132 columns
instead of 80.
-@item --head
-causes only the first @code{N} transactions to be printed. This is different
-from using the command-line utility @command{head}, which would limit to
-the first N postings. @code{--tail} outputs only the last @code{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).
-
-@item --pager
-tells Ledger to pass its output to the given pager program; very useful
+@item --head @var{INT}
+Cause only the first @var{INT} transactions to be printed. This is
+different from using the command-line utility @command{head}, which
+would limit to the first @var{INT} postings. @code{--tail} outputs
+only the last @var{INT} 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).
+
+@item --pager @var{FILE}
+Tell 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.
-@item --average
-@item -A
-reports the average posting value.
+@item --average
+@itemx -A
+Report the average posting value.
@item --deviation
-@item -D
-reports each posting's deviation from the average. It is only
+@itemx -D
+Report each posting's deviation from the average. It is only
meaningful in the @command{register} and @command{prices} reports.
@item --percent
-@item -%
-shows account subtotals in the @command{balance} report as percentages
+@itemx -%
+Show account subtotals in the @command{balance} report as percentages
of the parent account.
@c @code{--totals} include running total information in the
@c @command{xml} report.
@item --amount-data
-@item -j
-changes the @command{register} report so that it outputs nothing but the
+@itemx -j
+Change 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.
@item --total-data
-@item -J
-changes the @command{register} report so that it outputs nothing but the
+@itemx -J
+Change the @command{register} report so that it outputs nothing but the
date and totals column, without commodities.
-@item --display EXPR
-@item -d EXPR
-limits which postings or accounts or actually displayed in a report.
+@item --display @var{EXPR}
+@itemx -d @var{EXPR}
+Limit 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
+$ ledger -d "d>=[last month]" reg checking
@end smallexample
The output from this command is very different from the following,
@@ -5966,93 +6447,102 @@ whose running total includes only postings from the last month
onward:
@smallexample
-ledger -p "last month" reg checking
+$ 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 (@code{-p}), or simply a display
restricted to the reporting range (using @code{-d}).
-@item --date-format STR
-@item -y STR
-changes the basic date format used by reports. The default uses a date
+@item --date-format @var{DATE_FORMAT}
+@itemx -y @var{DATE_FORMAT}
+Change the basic date format used by reports. The default uses a date
like @code{2004/08/01}, which represents the default date format of
@code{%Y/%m/%d}. To change the way dates are printed in general, the
-easiest way is to put @code{--date-format FORMAT} in the Ledger
-initialization file @file{~/.ledgerrc} (or the file referred to by
-@env{LEDGER_INIT}).
-
-@item --format STR
-@item -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:
-
-@item --balance-format STR
-Define the output format for the @code{balance} report. The default (defined in @code{report.h} is:
-@smallexample
- "%(ansify_if(
- justify(scrub(display_total), 20,
- 20 + int(prepend_width), true, color),
+easiest way is to put @code{--date-format @var{DATE_FORMAT}} in the
+Ledger initialization file @file{~/.ledgerrc} (or the file referred to
+by @env{LEDGER_INIT}).
+
+@item --format @var{FORMAT_STRING}
+@itemx -F @var{FORMAT_STRING}
+Set the reporting format for whatever report ledger is about to make.
+@xref{Format Strings}. There are also specific format commands for
+each report type:
+
+@item --balance-format @var{FORMAT_STRING}
+Define the output format for the @code{balance} report. The default
+(defined in @code{report.h} is:
+
+@smallexample
+"%(ansify_if(
+ justify(scrub(display_total), 20,
+ 20 + int(prepend_width), true, color),
+ bold if should_bold))
+ %(!options.flat ? depth_spacer : \"\")
+ %-(ansify_if(
+ ansify_if(partial_account(options.flat), blue if color),
+ bold if should_bold))\n%/
+ %$1\n%/
+ %(prepend_width ? \" \" * int(prepend_width) : \"\")
+ --------------------\n"
+@end smallexample
+
+@item --cleared-format @var{FORMAT_STRING}
+Define the format for the cleared report. The default is:
+
+@smallexample
+"%(justify(scrub(get_at(display_total, 0)), 16, 16 + int(prepend_width),
+ true, color)) %(justify(scrub(get_at(display_total, 1)), 18,
+ 36 + int(prepend_width), true, color))
+ %(latest_cleared ? format_date(latest_cleared) : \" \")
+ %(!options.flat ? depth_spacer : \"\")
+ %-(ansify_if(partial_account(options.flat), blue if color))\n%/
+ %$1 %$2 %$3\n%/
+ %(prepend_width ? \" \" * int(prepend_width) : \"\")
+ ---------------- ---------------- ---------\n"
+@end smallexample
+
+@item --register-format @var{FORMAT_STRING}
+Define the output format for the @code{register} report. The default
+(defined in @code{report.h} is:
+
+@smallexample
+"%(ansify_if(
+ ansify_if(justify(format_date(date), int(date_width)),
+ green if color and date > today),
+ bold if should_bold))
+ %(ansify_if(
+ ansify_if(justify(truncated(payee, int(payee_width)), int(payee_width)),
+ bold if color and !cleared and actual),
bold if should_bold))
- %(!options.flat ? depth_spacer : \"\")
- %-(ansify_if(
- ansify_if(partial_account(options.flat), blue if color),
- bold if should_bold))\n%/
- %$1\n%/
- %(prepend_width ? \" \" * int(prepend_width) : \"\")
- --------------------\n"
-@end smallexample
-@item --cleared-format
-Defines the format for the cleared report. The default is:
-@smallexample
- "%(justify(scrub(get_at(display_total, 0)), 16, 16 + int(prepend_width),
- true, color)) %(justify(scrub(get_at(display_total, 1)), 18,
- 36 + int(prepend_width), true, color))
- %(latest_cleared ? format_date(latest_cleared) : \" \")
- %(!options.flat ? depth_spacer : \"\")
- %-(ansify_if(partial_account(options.flat), blue if color))\n%/
- %$1 %$2 %$3\n%/
- %(prepend_width ? \" \" * int(prepend_width) : \"\")
- ---------------- ---------------- ---------\n"
-@end smallexample
-@item --register-format STR
-Define the output format for the @code{register} report. The default (defined in @code{report.h} is:
-@smallexample
- "%(ansify_if(
- ansify_if(justify(format_date(date), int(date_width)),
- green if color and date > today),
+ %(ansify_if(
+ ansify_if(justify(truncated(display_account, int(account_width),
+ int(abbrev_len)), int(account_width)),
+ blue if color),
bold if should_bold))
- %(ansify_if(
- ansify_if(justify(truncated(payee, int(payee_width)), int(payee_width)),
- bold if color and !cleared and actual),
- bold if should_bold))
- %(ansify_if(
- ansify_if(justify(truncated(display_account, int(account_width),
- int(abbrev_len)), int(account_width)),
- blue if color),
- bold if should_bold))
- %(ansify_if(
- justify(scrub(display_amount), int(amount_width),
- 3 + int(meta_width) + int(date_width) + int(payee_width)
- + int(account_width) + int(amount_width) + int(prepend_width),
- true, color),
- bold if should_bold))
- %(ansify_if(
- justify(scrub(display_total), int(total_width),
- 4 + int(meta_width) + int(date_width) + int(payee_width)
- + int(account_width) + int(amount_width) + int(total_width)
- + int(prepend_width), true, color),
- bold if should_bold))\n%/
- %(justify(\" \", int(date_width)))
- %(ansify_if(
- justify(truncated(has_tag(\"Payee\") ? payee : \" \",
- int(payee_width)), int(payee_width)),
- bold if should_bold))
- %$3 %$4 %$5\n"
-@end smallexample
-@item --csv-format
-Sets the format for @code{csv} reports. The default is:
+ %(ansify_if(
+ justify(scrub(display_amount), int(amount_width),
+ 3 + int(meta_width) + int(date_width) + int(payee_width)
+ + int(account_width) + int(amount_width) + int(prepend_width),
+ true, color),
+ bold if should_bold))
+ %(ansify_if(
+ justify(scrub(display_total), int(total_width),
+ 4 + int(meta_width) + int(date_width) + int(payee_width)
+ + int(account_width) + int(amount_width) + int(total_width)
+ + int(prepend_width), true, color),
+ bold if should_bold))\n%/
+ %(justify(\" \", int(date_width)))
+ %(ansify_if(
+ justify(truncated(has_tag(\"Payee\") ? payee : \" \",
+ int(payee_width)), int(payee_width)),
+ bold if should_bold))
+ %$3 %$4 %$5\n"
+@end smallexample
+
+@item --csv-format @var{FORMAT_STRING}
+Set the format for @code{csv} reports. The default is:
+
@smallexample
"%(quoted(date)),
%(quoted(code)),
@@ -6063,40 +6553,48 @@ Sets the format for @code{csv} reports. The default is:
%(quoted(cleared ? \"*\" : (pending ? \"!\" : \"\"))),
%(quoted(join(note | xact.note)))\n"
@end smallexample
-@item --plot-amount-format STR
-Sets the format for amount plots, using the @code{-j} option. The default is:
+
+@item --plot-amount-format @var{FORMAT_STRING}
+Set the format for amount plots, using the @code{-j} option. The
+default is:
+
@smallexample
"%(format_date(date, \"%Y-%m-%d\")) %(quantity(scrub(display_amount)))\n"
@end smallexample
-@item --plot-total-format STR
-Sets the format for total plots, using the @code{-J} option. The default is:
+
+@item --plot-total-format @var{FORMAT_STRING}
+Set the format for total plots, using the @code{-J} option. The
+default is:
+
@smallexample
"%(format_date(date, \"%Y-%m-%d\")) %(quantity(scrub(display_total)))\n"
@end smallexample
-@item --pricedb-format STR
-Sets the format expected for the historical price file. The default is
+
+@item --pricedb-format @var{FORMAT_STRING}
+Set the format expected for the historical price file. The default is
+
@smallexample
"P %(datetime) %(display_account) %(scrub(display_amount))\n"
@end smallexample
-@item --prices-format STR
-Sets the format for the @command{prices} report. The default is:
+@item --prices-format @var{FORMAT_STRING}
+Set the format for the @command{prices} report. The default is:
+
@smallexample
-"%(date) %-8(display_account) %(justify(scrub(display_amount), 12,
+"%(date) %-8(display_account) %(justify(scrub(display_amount), 12,
2 + 9 + 8 + 12, true, color))\n"
@end smallexample
-@item --wide-register-format STR
-(-w @command{register})
-@end table
+@end ftable
@node Commodity Reporting, Environment Variables, Output Customization, Detailed Options Description
@subsection Commodity Reporting
These options affect how commodity values are displayed:
-@table @code
-@item --price-db FILE
-sets the file that is used for recording downloaded commodity prices.
-It is always read on start up, to determine historical prices. Other
+
+@ftable @code
+@item --price-db @var{FILE}
+Set 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 commodity, for example. This is done by adding a
line like the following:
@@ -6107,52 +6605,57 @@ N $
N h
@end smallexample
-@noindent Note: Ledger NEVER writes output to files. You are responsible for
-updating the price-db file. The best way is to have your price download
-script maintain this file.
+@noindent
+Note: Ledger NEVER writes output to files. You are responsible for
+updating the price-db file. The best way is to have your price
+download script maintain this file.
The format of the file can be changed by telling ledger to use the
@code{--pricedb-format} you define.
-@item --price-exp MINS
-@item -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
-@code{--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.
+@item --price-exp @var{INT}
+@itemx -L @var{INT}
+Set the expected freshness of price quotes, in @var{INT} minutes. That
+is, if the last known quote for any commodity is older than this
+value, and if @code{--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.
@item --download
-@item -Q
-causes quotes to be automagically downloaded, as needed, by running a
+@itemx -Q
+Cause 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}.
-@end table
+@end ftable
+
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 @code{-t} and @code{-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)
+@ftable @code
+@item --quantity
+@itemx -O
+Report commodity totals (this is the default)
-@item -B, --basis
-Reports the cost basis for all postings.
+@item --basis
+@itemx -B
+Report the cost basis for all postings.
-@item -V, --market
+@item --market
+@itemx -V
Use the last known value for commodities to calculate final values.
-@item -G --gain
-Reports the net gain/loss for all commodities in the report that have
+@item --gain
+@itemx -G
+Report the net gain/loss for all commodities in the report that have
a price history.
-@end table
-
+@end ftable
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
@@ -6162,61 +6665,63 @@ commodity can mean different things to different people, depending on
the accounts involved, the commodities, the nature of the transactions,
etc.
-When you specify @code{-V}, or @code{-X COMM}, you are requesting that
-some or all of the commodities be valuated as of today (or whatever
-@code{--now} is set to). But what does such a valuation mean? This
-meaning is governed by the presence of a @code{VALUE} meta-data property,
-whose content is an expression used to compute that value.
+@findex --now @var{DATE}
+
+When you specify @code{-V}, or @code{-X @var{COMMODITY}}, you are
+requesting that some or all of the commodities be valuated as of today
+(or whatever @code{--now @var{DATE}} is set to). But what does such
+a valuation mean? This meaning is governed by the presence of
+a @code{VALUE} meta-data property, whose content is an expression used
+to compute that value.
If no VALUE property is specified, each posting is assumed to have a
default, as if you'd specified a global, automated transaction as
follows:
@smallexample
- = expr true
+= expr true
; VALUE:: market(amount, date, exchange)
@end smallexample
+
This definition emulates the present day behavior of @code{-V} and
-@code{-X} (in the case of @code{-X}, the requested commodity is passed
-via the string 'exchange' above).
+@code{-X @var{COMMODITY}} (in the case of @code{-X}, the requested
+commodity is passed via the string @samp{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 @code{--now} is some old date, use market prices as they
-were at that time; but if @code{--now} is past June 2008, use a fixed
-price for converting Deutsch Mark to Euro.
+This says: If @code{--now @var{DATE}} is some old date, use market
+prices as they were at that time; but if @code{--now @var{DATE}} 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:
+Or how about never re-valuating commodities used in Expenses, since
+they cannot have a different future value:
@smallexample
- = /^Expenses:/
+= /^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 @code{--now} (defaults to today).
+the value of @code{--now @var{DATE}} (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]
+= 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 @code{-X EUR} to expressly request all amounts in
+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.
@@ -6225,12 +6730,12 @@ posting or transaction, by overriding these general defaults using
specific meta-data:
@smallexample
- 2010-12-26 Example
- Expenses:Food $20
- ; Just to be silly, always valuate *these* $20 as 30 DM, no matter what
- ; the user asks for with -V or -X
- ; VALUE:: 30 DM
- Assets:Cash
+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
@@ -6239,20 +6744,21 @@ 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:
+Or, if it better suits your accounting, you can be less symbolic,
+which allows you to report most everything in EUR if you use @samp{-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, '$')
+= /^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, @samp{$})
@end smallexample
@cindex FIFO/LIFO
@cindex LIFO/FIFO
+@findex --lots
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
@@ -6260,37 +6766,39 @@ against itself. If @code{--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 @code{--lots} is not
-specified. But if you do specify @code{--lot-prices}, for example, then
-it will balance against that specific price for AAPL.
-
-Normally when you use @code{-X <commodity>} to request that amounts be reported in a
-specific commodity, Ledger uses these values:
+@findex --lot-prices
+If you specify an adorned commodity, like AAPL @{$10.00@}, it will
+also balance against itself, and against any AAPL if @code{--lots} is
+not specified. But if you do specify @code{--lot-prices}, for
+example, then it will balance against that specific price for AAPL.
+
+Normally when you use @code{-X @var{COMMODITY}} to request that
+amounts be reported in a specific commodity, Ledger uses these values:
@itemize
@item Register Report
- For the register report, use the value of that commodity on the date of
- the posting being reported, with a <Revalued> posting added at the end of
- today's value is different from the value of the last posting.
+For the register report, use the value of that commodity on the date
+of the posting being reported, with a <Revalued> posting added at the
+end of today's value is different from the value of the last posting.
@item Balance Report
- For the balance report, use the value of that commodity as of today.
+For the balance report, use the value of that commodity as of today.
@end itemize
-You can now specify @code{-H} to ask that all valuations for any amount be done
-relative to the date that amount was encountered.
+You can now specify @code{-H} to ask that all valuations for any
+amount be done relative to the date that amount was encountered.
+
+You can also now use @code{-X @var{COMMODITY}} (and @code{-H}) in
+conjunction with @code{-B} and @code{-I}, to see valuation reports of
+just your basis costs or lot prices.
-You can also now use @code{-X} (and @code{-H}) in conjunction with
-@code{-B} and @code{-I}, to see valuation reports of just your basis
-costs or lot prices.
@node Environment Variables, , Commodity Reporting, Detailed Options Description
@subsection Environment variables
Every option to ledger may be set using an environment variable. If
an option has a long name such @code{--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
+effect as specifying that option on the command-line. Options on the
command-line always take precedence over environment variable
settings, however.
@@ -6299,7 +6807,6 @@ option settings in the file @file{~/.ledgerrc}, for example:
@smallexample
--pager /bin/cat
-
@end smallexample
@node Period Expressions, , Detailed Options Description, Command-line Syntax
@@ -6317,7 +6824,7 @@ The optional @var{INTERVAL} part may be any one of:
@smallexample
every day
every week
-every monthly
+every month
every quarter
every year
every N days # N is any integer
@@ -6389,17 +6896,19 @@ last oct
weekly last august
@end smallexample
-
@node Budgeting and Forecasting, Time Keeping, Command-line Syntax, Top
@chapter Budgeting and Forecasting
@menu
-* Budgeting::
-* Forecasting::
+* Budgeting::
+* Forecasting::
@end menu
@node Budgeting, Forecasting, Budgeting and Forecasting, Budgeting and Forecasting
@section Budgeting
+@findex --budget
+@findex --add-budget
+@findex --unbudgeted
Keeping a budget allows you to pay closer attention to your income and
expenses, by reporting how far your actual financial activity is from
@@ -6413,67 +6922,68 @@ 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
+ 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
+ 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:
+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
+@smallexample
+$ ledger -p "this year" --monthly --average --subtotal balance ^expenses
+@end smallexample
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 @code{--budget} to the command-line. For example, a
-typical monthly expense report would be:
+Once these period transactions are defined, creating a budget report
+is as easy as adding @code{--budget} to the command-line. For
+example, a typical monthly expense report would be:
-@example
-ledger --monthly register ^expenses
-@end example
+@smallexample
+$ ledger --monthly register ^expenses
+@end smallexample
To see the same report balanced against your budget, use:
-@example
-ledger --budget --monthly register ^expenses
-@end example
+@smallexample
+$ ledger --budget --monthly register ^expenses
+@end smallexample
A budget report includes only those accounts that appear in the
budget. To see all expenses balanced against the budget, use
@code{--add-budget}. You can even see only the un-budgeted expenses
using @code{--unbudgeted}:
-@example
-ledger --unbudgeted --monthly register ^expenses
-@end example
+@smallexample
+$ ledger --unbudgeted --monthly register ^expenses
+@end smallexample
You can also use these flags with the @command{balance} command.
@node Forecasting, , Budgeting, Budgeting and Forecasting
@section Forecasting
+@findex --forecast
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:
+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
+@smallexample
+$ ledger --forecast "T>@{\$-500.00@}" register ^assets ^liabilities
+@end smallexample
This report continues outputting postings until the running total
is greater than $-500.00. A final posting is always output, to
@@ -6482,39 +6992,38 @@ 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
+@smallexample
+$ ledger --forecast "d<[2010]" bal ^assets ^liabilities
+@end smallexample
@node Time Keeping, Value Expressions, Budgeting and Forecasting, Top
@chapter Time Keeping
-
Ledger directly supports ``timelog'' entries, which have this form:
@smallexample
- i 2013/03/28 22:13:00 ACCOUNT[ PAYEE]
- o 2013/03/29 03:39:00
+i 2013/03/28 22:13:00 ACCOUNT[ PAYEE]
+o 2013/03/29 03:39:00
@end smallexample
-This records a check-in to the given ACCOUNT, and a check-out. You can
-be checked-in to multiple accounts at a time, if you wish, and they can
-span multiple days (use @code{--day-break} to break them up in the
-report). The number of seconds between is accumulated as time to that
-ACCOUNT. If the checkout uses a capital ``O'', the transaction is marked
-``cleared''. You can use an optional PAYEE for whatever meaning you like.
-
-Now, there are a few ways to generate this information. You can use the
-@file{timeclock.el} package, which is part of Emacs. Or you can write a
-simple script in whichever language you prefer to emit similar
-information. Or you can use Org mode's time-clocking abilities and the
-org2tc script developed by John Wiegly.
-
-These timelog entries can appear in a separate file, or directly in your
-main ledger file. The initial "i" and "o" count as Ledger "directives",
-and are accepted anywhere that ordinary transactions are.
+This records a check-in to the given ACCOUNT, and a check-out. You
+can be checked-in to multiple accounts at a time, if you wish, and
+they can span multiple days (use @code{--day-break} to break them up
+in the report). The number of seconds between is accumulated as time
+to that ACCOUNT. If the checkout uses a capital @samp{O}, the
+transaction is marked ``cleared''. You can use an optional PAYEE for
+whatever meaning you like.
+Now, there are a few ways to generate this information. You can use
+the @file{timeclock.el} package, which is part of Emacs. Or you can
+write a simple script in whichever language you prefer to emit similar
+information. Or you can use Org mode's time-clocking abilities and
+the org2tc script developed by John Wiegley.
+These timelog entries can appear in a separate file, or directly in
+your main ledger file. The initial @samp{i} and @samp{o} count as
+Ledger ``directives'', and are accepted anywhere that ordinary
+transactions are.
@node Value Expressions, Format Strings, Time Keeping, Top
@chapter Value Expressions
@@ -6535,11 +7044,10 @@ 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 functions and variables.
+addition to a set of functions and variables.
-@c A function's
-@c argument is whatever follows it. The following is a display predicate
-@c that I use with the @command{balance} command:
+@c A function's argument is whatever follows it. The following is
+@c a display predicate that I use with the @command{balance} command:
@c @smallexample
@c ledger -d /^Liabilities/?T<0:UT>100 balance
@@ -6557,7 +7065,7 @@ 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
+$ ledger -d "d>[this month]" register checking
@end smallexample
This advantage to this command's complexity is that it prints the
@@ -6566,14 +7074,14 @@ following, simpler command is similar, but totals only the displayed
postings:
@smallexample
-ledger -b "this month" register checking
+$ ledger -b "this month" register checking
@end smallexample
@menu
-* Variables::
-* Functions::
-* Operators::
-* Complex Expressions::
+* Variables::
+* Functions::
+* Operators::
+* Complex Expressions::
@end menu
@node Variables, Functions, Value Expressions, Value Expressions
@@ -6603,6 +7111,12 @@ not specified, the current report style's value expression is used.
This is always the present moment/date.
@end table
+@menu
+* Posting/account details::
+* Calculated totals::
+@end menu
+
+@node Posting/account details, Calculated totals, Variables, Variables
@subsection Posting/account details
@table @code
@@ -6623,7 +7137,7 @@ 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 @code{v-b}.
+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,
@@ -6634,15 +7148,16 @@ 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.
+@samp{1} if a posting's transaction has been cleared, @samp{0} otherwise.
@item R
-1 if a posting is not virtual, 0 otherwise.
+@samp{1} if a posting is not virtual, @samp{0} otherwise.
@item Z
-1 if a posting is not automated, 0 otherwise.
+@samp{1} if a posting is not automated, @samp{0} otherwise.
@end table
+@node Calculated totals, , Posting/account details, Variables
@subsection Calculated totals
@table @code
@@ -6665,7 +7180,7 @@ 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
-@code{V-B}.
+@samp{V-B}.
@end table
@node Functions, Operators, Variables, Value Expressions
@@ -6684,12 +7199,12 @@ The absolute (unsigned) value of the argument.
Strips the commodity from the argument.
@item A
-The arithmetic mean of the argument; @code{Ax} is the same as
-@code{x/n}.
+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 @code{P(x,d)} is
-supported, which yields the market value at time @code{d}. If no date
+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
@@ -6706,8 +7221,8 @@ The binary and ternary operators, in order of precedence, are:
@end enumerate
@menu
-* Unary Operators::
-* Binary Operators::
+* Unary Operators::
+* Binary Operators::
@end menu
@node Unary Operators, Binary Operators, Operators, Operators
@@ -6719,26 +7234,26 @@ The binary and ternary operators, in order of precedence, are:
@node Binary Operators, , Unary Operators, Operators
@subsection Binary Operators
-@code{==}
-@code{<}
-@code{<=}
-@code{>}
-@code{>=}
+@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}
+@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
@@ -6754,24 +7269,24 @@ 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/
+@itemx 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/
+@itemx p/REGEXP/
A regular expression that matches against a transaction's payee name.
@item ///REGEXP/
-@item w/REGEXP/
+@itemx 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).
+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
@@ -6788,119 +7303,139 @@ Useful specifying a date in plain terms. For example, you could say
@end table
@menu
-* Misc::
+* Misc::
@end menu
@node Misc, , Complex Expressions, Complex Expressions
@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{ceiling } @tab @code{} @tab Returns the next integer toward +infty
-@item @code{code} @tab @code{} @tab returns the transaction code, the string between the parenthesis after the date.
-@item @code{commodity } @tab @code{} @tab
-@item @code{display_amount } @tab @code{} @tab --> t
-@item @code{display_total } @tab @code{} @tab --> T
-@item @code{date } @tab @code{} @tab
-@item @code{format_date } @tab @code{} @tab
-@item @code{format } @tab @code{} @tab
-@item @code{floor } @tab @code{} @tab Returns the next integer toward -infty
-@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{roundto } @tab @code{} @tab Returns value rounded to n digits. Does not affect formatting.
-@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
+
+@table @code
+@item abs--> U
+@item amount_expr
+@item ansify_if
+@item ceiling
+Return the next integer toward +infinity
+@item code
+Return the transaction code, the string between the parenthesis after the date.
+@item commodity
+@item date
+@item display_amount --> t
+@item display_total --> T
+@item floor
+Return the next integer toward -infinity
+@item format
+@item format_date
+@item format_datetime
+@item get_at
+@item is_seq
+@item join
+@item justify
+@item market --> P
+@item nail_down
+@item now --> d m
+@item options
+@item percent
+@item print
+@item quantity
+@item quoted
+@item round
+@item rounded
+@item roundto
+Return value rounded to n digits. Does not affect formatting.
+@item scrub
+@item should_bold
+@item strip --> S
+@item to_amount
+@item to_balance
+@item to_boolean
+@item to_date
+@item to_datetime
+@item to_int
+@item to_mask
+@item to_sequence
+@item to_spring
+@item today
+@item top_amount
+@item total_expr
+@item trim
+@item truncated
+@item unround
+@item unrounded
+@item value_date
+@end table
@node Format Strings, Extending with Python, Value Expressions, Top
@chapter Format Strings
@menu
-* Basics::
-* Format String Structure::
-* Format Expressions::
-* --balance-format::
-* Formatting codes::
+* Basics::
+* Format String Structure::
+* Format Expressions::
+* --balance-format::
+* Formatting codes::
@end menu
@node Basics, Format String Structure, 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 @code{--format}
-(@code{-F}) option. Within that string, constructs are allowed which
+@findex --format @var{FORMAT_STRING}
+@findex -F @var{FORMAT_STRING}
+@findex --balance-format
+@findex --budget-format
+@findex --cleared-format
+@findex --csv-format
+@findex --plot-amount-format
+@findex --plot-total-format
+@findex --pricedb-format
+@findex --prices-format
+@findex --register-format
+
+Format strings may be used to change the output format of reports.
+They are specified by passing a formatting string to the @code{-F
+(--format)} option. Within that string, constructs are allowed which
make it possible to display the various parts of an account or posting
in custom ways.
-There are several additional flags that allow you to define formats for
-specific reports. These are useful to define in your configuration file
-and will allow you to run ledger reports from the command line without
-having to enter a new format for each command.
+There are several additional flags that allow you to define formats
+for specific reports. These are useful to define in your configuration
+file and will allow you to run ledger reports from the command line
+without having to enter a new format for each command.
@itemize
-@item @code{--balance-report}
-@item @code{--cleared-report}
-@item @code{--register-report}
-@item @code{--csv-report}
-@item @code{--plot-amount-report}
-@item @code{--plot-total-report}
-@item @code{--pricedb-report}
-@item @code{--prices-report}
-@item @code{--wide-register-report}
+@item @code{--balance-format}
+@item @code{--budget-format}
+@item @code{--cleared-format}
+@item @code{--csv-format}
+@item @code{--plot-amount-format}
+@item @code{--plot-total-format}
+@item @code{--pricedb-format}
+@item @code{--prices-format}
+@item @code{--register-format}
@end itemize
@node Format String Structure, Format Expressions, Basics, Format Strings
@section Format String Structure
+
Within a format string, a substitution is specified using a percent
-character (@code{%}). The basic format of all substitutions is:
+@samp{%} character. The basic format of all substitutions is:
@smallexample
%[-][MIN WIDTH][.MAX WIDTH](VALEXPR)
@end smallexample
-If the optional minus sign (@code{-}) 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:
+If the optional minus sign @samp{-} follows the percent character
+@samp{%}, 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:
@table @code
-@item %-20P
-a transaction's payee, left justified and padded to 20 characters wide.
-@item %20P
-The same, right justified, at least 20 chars wide
-@item %.20P
-The same, no more than 20 chars wide
+@item %-20P
+A transaction's payee, left justified and padded to 20 characters wide.
+@item %20P
+The same, right justified, at least 20 chars wide.
+@item %.20P
+The same, no more than 20 chars wide.
@end table
The expression following the format constraints can be a single letter,
@@ -6909,7 +7444,7 @@ or an expression enclosed in parentheses or brackets.
@node Format Expressions, --balance-format, Format String Structure, Format Strings
@section Format Expressions
- The allowable expressions are:
+The allowable expressions are:
@table @code
@item %
@@ -6955,10 +7490,10 @@ file.
@item e
Inserts the ending line of that transaction within the file.
-@c @item D
-@c By default, this is the same as @code{%[%Y/%m%/d]}. The date format
-@c used can be changed at any time with the @code{-y} flag, however. Using
-@c @code{%D} gives the user more control over the way dates are output.
+@c @item D By default, this is the same as @code{%[%Y/%m%/d]}. The
+@c date format used can be changed at any time with the @code{-y}
+@c flag, however. Using @code{%D} gives the user more control over
+@c the way dates are output.
@item d
Returns the date according to the default format. If the transaction
@@ -6968,7 +7503,7 @@ has an effective date, it prints @code{[ACTUAL_DATE=EFFECTIVE_DATE]}.
If a posting has been cleared, this returns a 1, otherwise returns 0.
@item Y
-This is the same as @code{%X}, except that it only displays a state
+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
@@ -6979,32 +7514,32 @@ parenthesis on the first line of the transaction.
Inserts the payee related to a posting.
@c @item a
-@c Inserts the optimal short name for an account. This is normally used in
-@c balance reports. It prints a parent account's name if that name has not
-@c been printed yet, otherwise it just prints the account's name.
+@c Inserts the optimal short name for an account. This is normally
+@c used in balance reports. It prints a parent account's name if that
+@c name has not been printed yet, otherwise it just prints the
+@c account's name.
@item A
Inserts the full name of an account.
@c @item W
@c This is the same as @code{%A}, except that it first displays the
-@c posting's state @emph{if the transaction's posting states are not all
-@c the same}, followed by the full account name. This is offered as a
-@c printing optimization, so that combined with @code{%Y}, only the minimum
-@c amount of state detail is printed.
+@c posting's state @emph{if the transaction's posting states are not
+@c all the same}, followed by the full account name. This is offered
+@c as a printing optimization, so that combined with @code{%Y}, only
+@c the minimum amount of state detail is printed.
@c @item o
-@c Inserts the ``optimized'' form of a posting's amount. This is used by
-@c the print report. In some cases, this inserts nothing; in others, it
-@c inserts the posting amount and its cost. It's use is not recommended
-@c unless you are modifying the print report.
-
+@c Inserts the ``optimized'' form of a posting's amount. This is used
+@c by the print report. In some cases, this inserts nothing; in
+@c others, it inserts the posting amount and its cost. It's use is
+@c not recommended unless you are modifying the print report.
@item N
Inserts the note associated with a posting, if one exists.
@item /
-The @code{%/} construct is special. It separates a format string
+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.
@@ -7012,36 +7547,41 @@ same format string is used for all postings.
@node --balance-format, Formatting codes, Format Expressions, Format Strings
@section --balance-format
+@findex --balance-format @var{FORMAT_STRING}
+@findex --format @var{FORMAT_STRING}
-As an example of how flexible the @code{--format} strings can be, the default
-balance format looks like this (the various functions are described later):
+As an example of how flexible the @code{--format} strings can be, the
+default balance format looks like this (the various functions are
+described later):
@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"
+"%(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 Formatting codes, , --balance-format, Format Strings
@section Formatting Functions and Codes
@menu
-* Field Widths::
-* Colors::
-* Quantities and Calculations::
-* Dates::
-* Date and Time Format Codes::
-* Text Formatting::
-* Data File Parsing Information::
+* Field Widths::
+* Colors::
+* Quantities and Calculations::
+* Dates::
+* Date and Time Format Codes::
+* Text Formatting::
+* Data File Parsing Information::
@end menu
@node Field Widths, Colors, Formatting codes, Formatting codes
@subsection Field Widths
+
The following codes return the width allocated for the specific fields.
The defaults can be changed using the corresponding command line
options:
+
@itemize
@item @code{date_width}
@item @code{payee_width}
@@ -7055,20 +7595,17 @@ options:
The character based formatting ledger can do is limited to the ANSI
terminal character colors and font highlights in a normal TTY session.
+
@multitable @columnfractions .3 .3 .3
-@item @code{red} @tab @code{magenta} @tab @code{bold}
-@item @code{green } @tab @code{cyan} @tab @code{underline}
-@item @code{yellow } @tab @code{white} @tab @code{blink}
-@item @code{blue }
+@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} @tab @code{black}
@end multitable
-
-
@node Quantities and Calculations, Dates, Colors, Formatting codes
@subsection Quantities and Calculations
-
-
@table @code
@item amount_expr
@item abs
@@ -7092,43 +7629,57 @@ terminal character colors and font highlights in a normal TTY session.
@item to_balance
@item unrounded
@end table
-
+
@node Dates, Date and Time Format Codes, Quantities and Calculations, Formatting codes
@subsection Date Functions
+@findex --now @var{DATE}
+
The following functions allow you to manipulate and format dates.
+
@table @code
@item date
-Returns the date of the current transaction
-@item format_date(date, "FORMAT STRING")
-formats the date using the given format string.
+Return the date of the current transaction
+@item format_date(date, "FORMAT_STRING")
+Format the date using the given format string.
@item now
-Returns the current date and time. If the @code{--now} option is
-defined it will return that value.
+Return the current date and time. If the @code{--now @var{DATE}}
+option is defined it will return that value.
@item today
-Returns the current date. If the @code{--now} option is
+Return the current date. If the @code{--now @var{DATE}} option is
defined it will return that value.
@item to_datetime
-convert a string to a date-time value
+Convert a string to a date-time value
@item to_date
-convert a string to date value
+Convert a string to date value
@item value_date
@end table
@menu
-* Date and Time Format Codes::
+* Date and Time Format Codes::
@end menu
@node Date and Time Format Codes, Text Formatting, Dates, Formatting codes
@subsection Date and Time Format Codes
+
Date and time format are specified as strings of single letter codes
preceded by percent signs. Any separator, or no separator can be
specified.
+
+@menu
+* Days::
+* Weekdays::
+* Month::
+* Miscellaneous Date Codes::
+@end menu
+
+@node Days, Weekdays, Date and Time Format Codes, Date and Time Format Codes
@subsubsection Days
+
Dates are formed from a combination of day, month and year codes, in
whatever order you prefer:
@table @code
-@item %Y
+@item %Y
Four digit year
@item %y
@@ -7141,21 +7692,26 @@ Two digit month
Two digit date
@end table
-@noindent So @code{"%Y%m%d"} yields @code{20111214} which provides a date that is simple to sort on.
+@noindent
+So @code{"%Y%m%d"} yields @code{20111214} which provides a date that
+is simple to sort on.
+@node Weekdays, Month, Days, Date and Time Format Codes
@subsubsection Weekdays
-You can have additional weekday information in your date with @code{%A}
+You can have additional weekday information in your date with @samp{%A}
as
@table @code
@item %m-%d-%Y %A
-yields @code{02-10-2010 Wednesday}
+yields @code{02-10-2010 Wednesday}
@item %A %m-%d-%Y
-yields @code{Wednesday 02-10-2010}
+yields @code{Wednesday 02-10-2010}
@end table
-@noindent These are options you can select for weekday
+
+@noindent
+These are options you can select for weekday
@table @code
@item %a
@@ -7173,31 +7729,40 @@ day of week starting with Monday (1), i.e. @code{mtwtfss} 3
@item %w
day of week starting with Sunday (0), i.e. @code{smtwtfs} 3
@end table
+
+@node Month, Miscellaneous Date Codes, Weekdays, Date and Time Format Codes
@subsubsection Month
-You can have additional month information in your date with @code{%B} as
+You can have additional month information in your date with @samp{%B}
+as
@table @code
@item %m-%d-%Y %B
-yields @code{ 02-10-2010 Februrary}
+yields @code{02-10-2010 February}
@item %B %m-%d-%Y
-yields @code{February 02-10-2010}
+yields @code{February 02-10-2010}
@end table
-@noindent These are options you can select for month
+
+@noindent
+These are options you can select for month
+
@table @code
@item %m
-@code{mm} month as two digits
+@samp{mm} month as two digits
@item %b
-Locale’s abbreviated month, for example @code{02} might be abbreviated as @code{Feb}
+Locale’s abbreviated month, for example @samp{02} might be abbreviated
+as @samp{Feb}
@item %B
Locale’s full month, variable length February
@end table
+@node Miscellaneous Date Codes, , Month, Date and Time Format Codes
@subsubsection Miscellaneous Date Codes
-Additional date format parameters which can be used :
+
+Additional date format parameters which can be used:
@table @code
@item %U
@@ -7209,38 +7774,45 @@ week of the year 01–53
@item %C
@code{cc} century 00–99
@item %D
-yields @code{mm/dd/yy 02/10/10}
+yields @code{mm/dd/yy 02/10/10}
@item %x
locale’s date representation @code{02/10/2010} for the U.S.
@item %F
-yields @code{%Y-%m-%d 2010-02-10}
+yields @code{%Y-%m-%d 2010-02-10}
@end table
+
@menu
-* Text Formatting::
-* Data File Parsing Information::
-* Misc::
+* Text Formatting::
+* Data File Parsing Information::
+* Misc::
@end menu
@node Text Formatting, Data File Parsing Information, Date and Time Format Codes, Formatting codes
@subsection Text Formatting
+
The following format functions allow you limited formatting of text:
+
@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)
+
+@item justify(value, first_width, latter_width, right_justify, colorize)
Right or left justify the string representing @code{value}. The width
of the field in the first line is given by @code{first_width}. For
subsequent lines the width is given by @code{latterwidth}. If
@code{latter_width=-1}, then @code{first_width} is use for all lines.
-If @code{right_justify=true} then the field is right justify within the
-width of the field. If it is @code{false}, then the field is left
-justified and padded to the full width of the field. If @code{colorize}
-is true then ledger will honor color settings.
+If @code{right_justify=true} then the field is right justify within
+the width of the field. If it is @code{false}, then the field is left
+justified and padded to the full width of the field. If
+@code{colorize} is true then ledger will honor color settings.
+
@item join(STR)
-Replaces line feeds in @code{STR} with @code{\n}.
+Replaces line feeds in @code{STR} with @samp{\n}.
+
@item quoted(STR)
Return @code{STR} surrounded by double quotes, @code{"STR"}.
+
@item strip(value)
Values can have numerous annotations, such as effective dates and lot
prices. @code{strip} removes these annotations.
@@ -7254,135 +7826,139 @@ regarding the coordinates of entries in the source data file(s) that
generated the posting.
@table @code
-@item filename
-name of ledger data file from whence posting came, abbreviated @code{S}
-@item beg_pos
-character position in @code{filename} where entry for posting begins, abbreviated @code{B}
-@item end_pos
-character position in @code{filename} where entry for posting ends, abbreviated @code{E}
-@item beg_line
-line number in @code{filename} where entry for posting begins, abbreviated @code{b}
-@item end_line
-line number in @code{filename} where posting's entry for posting ends, abbreviated @code{e}
+@item filename
+name of ledger data file from whence posting came, abbreviated @samp{S}
+@item beg_pos
+character position in @code{filename} where entry for posting begins,
+abbreviated @samp{B}
+@item end_pos
+character position in @code{filename} where entry for posting ends,
+abbreviated @samp{E}
+@item beg_line
+line number in @code{filename} where entry for posting begins,
+abbreviated @samp{b}
+@item end_line
+line number in @code{filename} where posting's entry for posting ends,
+abbreviated @samp{e}
@end table
-
-
@node Extending with Python, Ledger for Developers, Format Strings, Top
@chapter Extending with Python
-Python can be used to extend your Ledger
-experience. But first, a word must be said about Ledger's data model, so that
-other things make sense later.
+
+Python can be used to extend your Ledger experience. But first,
+a word must be said about Ledger's data model, so that other things
+make sense later.
@menu
-* Basic data traversal::
-* Raw vs. Cooked::
-* Queries::
-* Embedded Python::
-* Amounts::
+* Basic data traversal::
+* Raw vs. Cooked::
+* Queries::
+* Embedded Python::
+* Amounts::
@end menu
@node Basic data traversal, Raw vs. Cooked, Extending with Python, Extending with Python
@section Basic data traversal
-Every interaction with Ledger happens in the context of a Session. Even if
-you don't create a session manually, one is created for you by the top-level
-interface functions. The Session is where objects live like the Commodity's
-that Amount's refer to.
+Every interaction with Ledger happens in the context of a Session.
+Even if you don't create a session manually, one is created for you by
+the top-level interface functions. The Session is where objects live
+like the Commodity's that Amount's refer to.
-The make a Session useful, you must read a Journal into it, using the function
-`@code{read_journal}`. This reads Ledger data from the given file, populates a
-Journal object within the current Session, and returns a reference to that
-Journal object.
+The make a Session useful, you must read a Journal into it, using the
+function `@code{read_journal}`. This reads Ledger data from the given
+file, populates a Journal object within the current Session, and
+returns a reference to that Journal object.
-Within the Journal live all the Transaction's, Posting's, and other objects
-related to your data. There are also AutomatedTransaction's and
-PeriodicTransaction's, etc.
+Within the Journal live all the Transaction's, Posting's, and other
+objects related to your data. There are also AutomatedTransaction's
+and PeriodicTransaction's, etc.
Here is how you would traverse all the postings in your data file:
-@smallexample
- import ledger
+@smallexample
+import ledger
- for xact in ledger.read_journal("sample.dat").xacts:
- for post in xact.posts:
- print "Transferring %s to/from %s" % (post.amount, post.account)
+for xact in ledger.read_journal("sample.dat").xacts:
+ for post in xact.posts:
+ print "Transferring %s to/from %s" % (post.amount, post.account)
@end smallexample
@node Raw vs. Cooked, Queries, Basic data traversal, Extending with Python
@section Raw vs. Cooked
-Ledger data exists in one of two forms: raw and cooked. Raw objects are what
-you get from a traversal like the above, and represent exactly what was seen
-in the data file. Consider this journal:
+Ledger data exists in one of two forms: raw and cooked. Raw objects
+are what you get from a traversal like the above, and represent
+exactly what was seen in the data file. Consider this journal:
@smallexample
- = true
- (Assets:Cash) $100
+= true
+ (Assets:Cash) $100
- 2012-03-01 KFC
- Expenses:Food $100
- Assets:Credit
+2012-03-01 KFC
+ Expenses:Food $100
+ Assets:Credit
@end smallexample
-
In this case, the @emph{raw} regular transaction in this file is:
@smallexample
- 2012-03-01 KFC
- Expenses:Food $100
- Assets:Credit
+2012-03-01 KFC
+ Expenses:Food $100
+ Assets:Credit
@end smallexample
While the @emph{cooked} form is:
@smallexample
- 2012-03-01 KFC
- Expenses:Food $100
- Assets:Credit $-100
- (Assets:Cash) $100
+2012-03-01 KFC
+ Expenses:Food $100
+ Assets:Credit $-100
+ (Assets:Cash) $100
@end smallexample
-So the easy way to think about raw vs. cooked is that raw is the unprocessed
-data, and cooked has had all considerations applied.
+So the easy way to think about raw vs. cooked is that raw is the
+unprocessed data, and cooked has had all considerations applied.
-When you traverse a Journal by iterating its transactions, you are generally
-looking at raw data. In order to look at cooked data, you must generate a
-report of some kind by querying the journal:
+When you traverse a Journal by iterating its transactions, you are
+generally looking at raw data. In order to look at cooked data, you
+must generate a report of some kind by querying the journal:
@smallexample
- for post in ledger.read_journal("sample.dat").query("food"):
- print "Transferring %s to/from %s" % (post.amount, post.account)
+for post in ledger.read_journal("sample.dat").query("food"):
+ print "Transferring %s to/from %s" % (post.amount, post.account)
@end smallexample
-The reason why queries iterate over postings instead of transactions is that
-queries often return only a ``slice'' of the transactions they apply to. You
-can always get at a matching posting's transaction by looking at its "xact"
-member:
+The reason why queries iterate over postings instead of transactions
+is that queries often return only a ``slice'' of the transactions they
+apply to. You can always get at a matching posting's transaction by
+looking at its ``xact'' member:
@smallexample
- last_xact = None
- for post in ledger.read_journal("sample.dat").query(""):
- if post.xact != last_xact:
- for post in post.xact.posts:
- print "Transferring %s to/from %s" % (post.amount,
- post.account)
- last_xact = post.xact
+last_xact = None
+for post in ledger.read_journal("sample.dat").query(""):
+ if post.xact != last_xact:
+ for post in post.xact.posts:
+ print "Transferring %s to/from %s" % (post.amount,
+ post.account)
+ last_xact = post.xact
@end smallexample
-This query ends up reporting every cooked posting in the Journal, but does it
-transaction-wise. It relies on the fact that an unsorted report returns
-postings in the exact order they were parsed from the journal file.
+This query ends up reporting every cooked posting in the Journal, but
+does it transaction-wise. It relies on the fact that an unsorted
+report returns postings in the exact order they were parsed from the
+journal file.
@node Queries, Embedded Python, Raw vs. Cooked, Extending with Python
@section Queries
-The Journal.query() method accepts every argument you can specify on the
-command-line, including --options.
+The Journal.query() method accepts every argument you can specify on
+the command-line, including --options.
-Since a query ``cooks'' the journal it applies to, only one query may be active
-for that journal at a given time. Once the query object is gone (after the
-for loop), then the data reverts back to its raw state.
+Since a query ``cooks'' the journal it applies to, only one query may
+be active for that journal at a given time. Once the query object is
+gone (after the for loop), then the data reverts back to its raw
+state.
@node Embedded Python, Amounts, Queries, Extending with Python
@section Embedded Python
@@ -7390,54 +7966,53 @@ for loop), then the data reverts back to its raw state.
You can embed Python into your data files using the 'python' directive:
@smallexample
- python
- import os
- def check_path(path_value):
- print "%s => %s" % (str(path_value), os.path.isfile(str(path_value)))
- return os.path.isfile(str(path_value))
+python
+ import os
+ def check_path(path_value):
+ print "%s => %s" % (str(path_value), os.path.isfile(str(path_value)))
+ return os.path.isfile(str(path_value))
- tag PATH
- assert check_path(value)
+tag PATH
+ assert check_path(value)
- 2012-02-29 KFC
- ; PATH: somebogusfile.dat
- Expenses:Food $20
- Assets:Cash
+2012-02-29 KFC
+ ; PATH: somebogusfile.dat
+ Expenses:Food $20
+ Assets:Cash
@end smallexample
-Any Python functions you define this way become immediately available as
-valexpr functions.
+Any Python functions you define this way become immediately available
+as valexpr functions.
@node Amounts, , Embedded Python, Extending with Python
@section Amounts
-When numbers come from Ledger, like post.amount, the type of the value is
-Amount. It can be used just like an ordinary number, except that addition
-and subtraction are restricted to amounts with the same commodity. If you
-need to create sums of multiple commodities, use a Balance. For example:
+When numbers come from Ledger, like post.amount, the type of the value
+is Amount. It can be used just like an ordinary number, except that
+addition and subtraction are restricted to amounts with the same
+commodity. If you need to create sums of multiple commodities, use
+a Balance. For example:
@smallexample
- total = Balance()
- for post in ledger.read_journal("sample.dat").query(""):
- total += post.amount
- print total
+total = Balance()
+for post in ledger.read_journal("sample.dat").query(""):
+ total += post.amount
+print total
@end smallexample
-
-
-
@node Ledger for Developers, Major Changes from version 2.6, Extending with Python, Top
@chapter Ledger for Developers
@menu
-* Internal Design::
-* Journal File Format::
-* Developer Commands::
-* Ledger Development Environment::
+* Internal Design::
+* Journal File Format::
+* Developer Commands::
+* Ledger Development Environment::
@end menu
@node Internal Design, Journal File Format, Ledger for Developers, Ledger for Developers
@section Internal Design
+
Ledger is developed as a tiered set of functionality, where lower tiers
know nothing about the higher tiers. In fact, multiple libraries are
built during the development the process, and link unit tests to these
@@ -7449,216 +8024,219 @@ Those tiers are:
@itemize
@item Utility code
- There's lots of general utility in Ledger for doing time parsing, using
- Boost.Regex, error handling, etc. It's all done in a way that can be
- reused in other projects as needed.
+There's lots of general utility in Ledger for doing time parsing,
+using Boost.Regex, error handling, etc. It's all done in a way that
+can be reused in other projects as needed.
@item Commoditized Amounts (amount_t, commodity_t and friends)
- An numerical abstraction combining multi-precision rational numbers (via
- GMP) with commodities. These structures can be manipulated like regular
- numbers in either C++ or Python (as Amount objects).
+An numerical abstraction combining multi-precision rational numbers
+(via GMP) with commodities. These structures can be manipulated like
+regular numbers in either C++ or Python (as Amount objects).
@item Commodity Pool
- Commodities are all owned by a commodity pool, so that future parsing of
- amounts can link to the same commodity and established a consistent price
- history and record of formatting details.
+Commodities are all owned by a commodity pool, so that future parsing
+of amounts can link to the same commodity and established a consistent
+price history and record of formatting details.
@item Balances
- Adds the concept of multiple amounts with varying commodities. Supports
- simple arithmetic, and multiplication and division with non-commoditized
- values.
+Adds the concept of multiple amounts with varying commodities.
+Supports simple arithmetic, and multiplication and division with
+non-commoditized values.
@item Price history
- Amounts have prices, and these are kept in a data graph which the amount
- code itself is only dimly aware of (there's three points of access so an
- amount can query its revalued price on a given date).
+Amounts have prices, and these are kept in a data graph which the
+amount code itself is only dimly aware of (there's three points of
+access so an amount can query its revalued price on a given date).
@item Values
- Often the higher layers in Ledger don't care if something is an amount or a
- balance, they just want to add stuff to it or print it. For this, I
- created a type-erasure class, value_t/Value, into which many things can be
- stuffed and then operated on. They can contain amounts, balances, dates,
- strings, etc. If you try to apply an operation between two values that
- makes no sense (like dividing an amount by a balance), an error occurs at
- runtime, rather than at compile-time (as would happen if you actually tried
- to divide an @code{amount_t} by a @code{balance_t}).
-
- This is the core data type for the value expression language.
-
+Often the higher layers in Ledger don't care if something is an amount
+or a balance, they just want to add stuff to it or print it. For
+this, I created a type-erasure class, value_t/Value, into which many
+things can be stuffed and then operated on. They can contain amounts,
+balances, dates, strings, etc. If you try to apply an operation
+between two values that makes no sense (like dividing an amount by
+a balance), an error occurs at runtime, rather than at compile-time
+(as would happen if you actually tried to divide an @code{amount_t} by
+a @code{balance_t}).
+This is the core data type for the value expression language.
@item Value expressions
- The next layer up adds functions and operators around the Value concept.
- This lets you apply transformations and tests to Values at runtime without
- having to bake it into C++. The set of functions available is defined by
- each object type in Ledger (posts, accounts, transactions, etc.), though
- the core engine knows nothing about these. At its base, it only knows how
- to apply operators to values, and how to pass them to and receive them from
- functions.
+The next layer up adds functions and operators around the Value
+concept. This lets you apply transformations and tests to Values at
+runtime without having to bake it into C++. The set of functions
+available is defined by each object type in Ledger (posts, accounts,
+transactions, etc.), though the core engine knows nothing about these.
+At its base, it only knows how to apply operators to values, and how
+to pass them to and receive them from functions.
@item Query expressions
- Expressions can be onerous to type at the command-line, so there's a
- shorthand for reporting called ``query expressions''. These add no
- functionality of there own, but are purely translated from the input string
- (cash) down to the corresponding value expression @code{(account =~ /cash/)}.
- This is a convenience layer.
+Expressions can be onerous to type at the command-line, so there's
+a shorthand for reporting called ``query expressions''. These add no
+functionality of their own, but are purely translated from the input
+string (cash) down to the corresponding value expression
+@code{(account =~ /cash/)}. This is a convenience layer.
@item Format strings
- Format strings let you interpolate value expressions into string, with the
- requirement that any interpolated value have a string representation.
- Really all this does is calculate the value expression in the current
- report context, call the resulting value's @code{to_string()} method, and stuffs
- the result into the output string. It also provides printf-like behavior,
- such as min/max width, right/left justification, etc.
+Format strings let you interpolate value expressions into string, with
+the requirement that any interpolated value have a string
+representation. Really all this does is calculate the value
+expression in the current report context, call the resulting value's
+@code{to_string()} method, and stuffs the result into the output
+string. It also provides printf-like behavior, such as min/max width,
+right/left justification, etc.
@item Journal items
- Next is a base type shared by anything that can appear in a journal: an
- item_t. It contains details common to all such parsed entities, like what
- file and line it was found on, etc.
+Next is a base type shared by anything that can appear in a journal:
+an item_t. It contains details common to all such parsed entities,
+like what file and line it was found on, etc.
@item Journal posts
- The most numerous object found in a Journal, postings are a type of item
- that contain an account, an amount, a cost, and metadata. There are some
- other complications, like the account can be marked virtual, the amount
- could be an expression, etc.
+The most numerous object found in a Journal, postings are a type of
+item that contain an account, an amount, a cost, and metadata. There
+are some other complications, like the account can be marked virtual,
+the amount could be an expression, etc.
@item Journal transactions
- Postings are owned by transactions, always. This subclass of item_t knows
- about the date, the payee, etc. If a date or metadata tag is requested
- from a posting and it doesn't have that information, the transaction is
- queried to see if it can provide it.
+Postings are owned by transactions, always. This subclass of item_t
+knows about the date, the payee, etc. If a date or metadata tag is
+requested from a posting and it doesn't have that information, the
+transaction is queried to see if it can provide it.
@item Journal accounts
- Postings are also shared by accounts, though the actual memory is managed
- by the transaction. Each account knows all the postings within it, but
- contains relatively little information of its own.
+Postings are also shared by accounts, though the actual memory is
+managed by the transaction. Each account knows all the postings
+within it, but contains relatively little information of its own.
@item The Journal object
- Finally, all transactions with their postings, and all accounts, are owned
- by a @code{journal_t} object. This is the go-to object for querying ad reporting
- on your data.
+Finally, all transactions with their postings, and all accounts, are
+owned by a @code{journal_t} object. This is the go-to object for
+querying ad reporting on your data.
@item Textual journal parser
- There is a textual parser, wholly contained in textual.cc, which knows how
- to parse text into journal objects, which then get ``finalized'' and added to
- the journal. Finalization is the step that enforces the double-entry
- guarantee.
+There is a textual parser, wholly contained in textual.cc, which knows
+how to parse text into journal objects, which then get ``finalized''
+and added to the journal. Finalization is the step that enforces the
+double-entry guarantee.
@item Iterators
- Every journal object is ``iterable'', and these iterators are defined in
- iterators.h and iterators.cc. This iteration logic is kept out of the
- basic journal objects themselves for the sake of modularity.
+Every journal object is ``iterable'', and these iterators are defined
+in iterators.h and iterators.cc. This iteration logic is kept out of
+the basic journal objects themselves for the sake of modularity.
@item Comparators
- Another abstraction isolated to its own layer, this class encapsulating the
- comparison of journal objects, based on whatever value expression the user
- passed to @code{--sort}.
+Another abstraction isolated to its own layer, this class
+encapsulating the comparison of journal objects, based on whatever
+value expression the user passed to @code{--sort}.
@item Temporaries
- Many reports bring pseudo-journal objects into existence, like postings
- which report totals in a @code{<Total>} account. These objects are created and
- managed by a temporaries_t object, which gets used in many places by the
- reporting filters.
+Many reports bring pseudo-journal objects into existence, like
+postings which report totals in a @code{<Total>} account. These
+objects are created and managed by a temporaries_t object, which gets
+used in many places by the reporting filters.
@item Option handling
- There is an option handling subsystem used by many of the layers further
- down. It makes it relatively easy for me to add new options, and to have
- those option settings immediately accessible to value expressions.
+There is an option handling subsystem used by many of the layers
+further down. It makes it relatively easy for me to add new options,
+and to have those option settings immediately accessible to value
+expressions.
@item Session objects
- Every journal object is owned by a session, with the session providing
- support for that object. In GUI terms, this is the Controller object for
- the journal Data object, where every document window would be a separate
- session. They are all owned by the global scope.
+Every journal object is owned by a session, with the session providing
+support for that object. In GUI terms, this is the Controller object
+for the journal Data object, where every document window would be
+a separate session. They are all owned by the global scope.
@item Report objects
- Every time you create report output, a report object is created to
- determine what you want to see. In the Ledger REPL, a new report object is
- created every time a command is executed. In CLI mode, only one report
- object ever comes into being, as Ledger immediately exits after displaying
- the results.
+Every time you create report output, a report object is created to
+determine what you want to see. In the Ledger REPL, a new report
+object is created every time a command is executed. In CLI mode, only
+one report object ever comes into being, as Ledger immediately exits
+after displaying the results.
@item Reporting filters
- The way Ledger generates data is this: it asks the session for the current
- journal, and then creates an iterator applied to that journal. The kind of
- iterator depends on the type of report.
+The way Ledger generates data is this: it asks the session for the
+current journal, and then creates an iterator applied to that journal.
+The kind of iterator depends on the type of report.
- This iterator is then walked, and every object yielded from the iterator is
- passed to an ``item handler'', whose type is directly related to the type of
- the iterator.
+This iterator is then walked, and every object yielded from the
+iterator is passed to an ``item handler'', whose type is directly
+related to the type of the iterator.
- There are many, many item handlers, which can be chained together. Each
- one receives an item (post, account, xact, etc.), performs some action on
- it, and then passes it down to the next handler in the chain. There are
- filters which compute the running totals; that queue and sort all the input
- items before playing them back out in a new order; that filter out items
- which fail to match a predicate, etc. Almost every reporting feature in
- Ledger is related to one or more filters. Looking at @code{filters.h}, I see over
- 25 of them defined currently.
+There are many, many item handlers, which can be chained together.
+Each one receives an item (post, account, xact, etc.), performs some
+action on it, and then passes it down to the next handler in the
+chain. There are filters which compute the running totals; that queue
+and sort all the input items before playing them back out in a new
+order; that filter out items which fail to match a predicate, etc.
+Almost every reporting feature in Ledger is related to one or more
+filters. Looking at @code{filters.h}, I see over 25 of them defined
+currently.
@item The filter chain
- How filters get wired up, and in what order, is a complex process based on
- all the various options specified by the user. This is the job of the
- chain logic, found entirely in @code{chain.cc}. It took a really long time to get
- this logic exactly write, which is why I haven't exposed this layer to the
- Python bridge yet.
+How filters get wired up, and in what order, is a complex process
+based on all the various options specified by the user. This is the
+job of the chain logic, found entirely in @code{chain.cc}. It took
+a really long time to get this logic exactly write, which is why
+I haven't exposed this layer to the Python bridge yet.
@item Output modules
- Although filters are great and all, in the end you want to see stuff. This
- is the job of special ``leaf'' filters call output modules. They are
- implemented just like a regular filter, but they don't have a ``next'' filter
- to pass the time on down to. Instead, they are the end of the line and
- must do something with the item that results in the user seeing something
- on their screen or in a file.
+Although filters are great and all, in the end you want to see stuff.
+This is the job of special ``leaf'' filters call output modules. They
+are implemented just like a regular filter, but they don't have
+a ``next'' filter to pass the time on down to. Instead, they are the
+end of the line and must do something with the item that results in
+the user seeing something on their screen or in a file.
@item Select queries
- Select queries know a lot about everything, even though they implement
- their logic by implementing the user's query in terms of all the other
- features thus presented. Select queries have no functionality of their
- own, they are simple a shorthand to provide access to much of Ledger's
- functionality via a cleaner, more consistent syntax.
+Select queries know a lot about everything, even though they implement
+their logic by implementing the user's query in terms of all the other
+features thus presented. Select queries have no functionality of
+their own, they are simple a shorthand to provide access to much of
+Ledger's functionality via a cleaner, more consistent syntax.
@item The Global Scope
- There is a master object which owns every other objects, and this is
- Ledger's global scope. It creates the other objects, provides REPL
- behavior for the command-line utility, etc. In GUI terms, this is the
- Application object.
+There is a master object which owns every other objects, and this is
+Ledger's global scope. It creates the other objects, provides REPL
+behavior for the command-line utility, etc. In GUI terms, this is the
+Application object.
@item The Main Driver
- This creates the global scope object, performs error reporting, and handles
- command-line options which must precede even the creation of the global
- scope, such as @code{--debug}.
+This creates the global scope object, performs error reporting, and
+handles command-line options which must precede even the creation of
+the global scope, such as @code{--debug}.
@end itemize
-And that's Ledger in a nutshell. All the rest are details, such as which
-value expressions each journal item exposes, how many filters currently exist,
-which options the report and session scopes define, etc.
+And that's Ledger in a nutshell. All the rest are details, such as
+which value expressions each journal item exposes, how many filters
+currently exist, which options the report and session scopes define,
+etc.
@node Journal File Format, Developer Commands, Internal Design, Ledger for Developers
@section Journal File Format for Developers
@@ -7709,23 +8287,24 @@ amount of the first posting is typically positive. Consider:
@end smallexample
@menu
-* Comments and meta-data::
-* Specifying Amounts::
-* Posting costs::
-* Primary commodities::
+* Comments and meta-data::
+* Specifying Amounts::
+* Posting costs::
+* Primary commodities::
@end menu
@node Comments and meta-data, Specifying Amounts, Journal File Format, Journal File Format
@subsection Comments and meta-data
-Comments are generally started using a @code{;}. 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{*}.
+Comments are generally started using a @samp{;}. 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: @samp{#}, @samp{|}, and @samp{*}.
@node Specifying Amounts, Posting costs, Comments and meta-data, Journal File Format
@subsection Specifying Amounts
@cindex amounts
+
The heart of a journal is the amounts it records, and this fact is
reflected in the diversity of amount expressions allowed. All of them
are covered here, though it must be said that sometimes, there are
@@ -7736,8 +8315,8 @@ spaces between the end of the post and the beginning of the amount
(including a commodity designator).
@menu
-* Integer Amounts::
-* Commoditized Amounts::
+* Integer Amounts::
+* Commoditized Amounts::
@end menu
@node Integer Amounts, Commoditized Amounts, Specifying Amounts, Specifying Amounts
@@ -7750,6 +8329,7 @@ In the simplest form, bare decimal numbers are accepted:
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
@@ -7766,8 +8346,8 @@ case of @code{1000.00} above, the internal value is @code{100000/100}.
While rational numbers are great at not losing precision, the question
arises: How should they be displayed? A number like @code{100000/100}
is no problem, since it represents a clean decimal fraction. But what
-about when the number @code{1/1} is divided by three? How should one
-print @code{1/3}, an infinitely repeating decimal?
+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
@@ -7778,11 +8358,11 @@ 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
-@code{1/3} be printed as @code{0.33} or @code{0.33333}? For
+@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, @code{1/3} is printed back as @code{0.333333}.
+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
@@ -7828,17 +8408,18 @@ in the same form as parsed. If you specify dollar amounts using
@code{$100.000}. You may even use decimal commas, such as
@code{$100,00}, or thousand-marks, as in @code{$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.
+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.
+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.
@@ -7928,27 +8509,33 @@ commodities.
@node Developer Commands, Ledger Development Environment, Journal File Format, Ledger for Developers
@section Developer Commands
+
@menu
-* echo::
-* reload::
-* source::
-* Debug Options::
-* Pre-commands::
+* echo::
+* reload::
+* source::
+* Debug Options::
+* Pre-commands::
@end menu
@node echo, reload, Developer Commands, Developer Commands
@subsection @command{echo}
-This command simply echos its argument back to the output.
+@findex echo
+This command simply echoes its argument back to the output.
@node reload, source, echo, Developer Commands
@subsection @command{reload}
+@findex reload
+
Forces ledger to reload any journal files. This function exists to
support external programs controlling a running ledger process and does
nothing for a command line user.
@node source, Debug Options, reload, Developer Commands
@subsection @command{source}
+@findex source
+
The @code{source} command take a journal file as an argument and parses
it checking for errors, no other reports are generated, and no other
arguments are necessary. Ledger will return success if no errors are
@@ -7960,49 +8547,45 @@ found.
These options are primarily for Ledger developers, but may be of some
use to a user trying something new.
-@table @code
- @item --args-only
-ignore init
-files and environment variables for the ledger run.
-
-@item --verify
-enable additional assertions during run-time. This causes a significant
-slowdown. When combined with @code{--debug} ledger will produce
-memory trace information.
+@ftable @code
+@item --args-only
+Ignore init files and environment variables for the ledger run.
-@item --debug "argument"
-If Ledger has been built with debug options this will provide extra data
-during the run. The following are the available arguments to debug:
+@item --debug @var{CODE}
+If Ledger has been built with debug options this will provide extra
+data during the run. The following are the available @var{CODES} to
+debug:
@multitable @columnfractions .32 .43 .27
-@item @code{account.display} @tab @code{expr.calc.when} @tab @code{org.next_amount}
-@item @code{accounts.sorted} @tab @code{expr.compile} @tab @code{org.next_total}
-@item @code{amount.convert} @tab @code{filters.changed_value} @tab @code{parser.error}
-@item @code{amount.is_zero} @tab @code{filters.changed_value.rounding} @tab @code{pool.commodities}
-@item @code{amount.parse} @tab @code{filters.collapse} @tab @code{post.assign}
-@item @code{amount.price} @tab @code{filters.forecast} @tab @code{python.init}
-@item @code{amount.truncate} @tab @code{filters.revalued} @tab @code{python.interp}
-@item @code{amount.unround} @tab @code{format.abbrev} @tab @code{query.mask}
-@item @code{amounts.commodities} @tab @code{format.expr} @tab @code{report.predicate}
-@item @code{amounts.refs} @tab @code{generate.post} @tab @code{scope.symbols}
-@item @code{archive.journal} @tab @code{generate.post.string} @tab @code{textual.include}
-@item @code{auto.columns} @tab @code{item.meta} @tab @code{textual.parse}
-@item @code{budget.generate} @tab @code{ledger.read} @tab @code{timelog}
-@item @code{commodity.annotated.strip} @tab @code{ledger.validate} @tab @code{times.epoch}
-@item @code{commodity.annotations} @tab @code{lookup} @tab @code{times.interval}
-@item @code{commodity.compare} @tab @code{lookup.account} @tab @code{times.parse}
-@item @code{commodity.download} @tab @code{mask.match} @tab @code{value.sort}
-@item @code{commodity.prices.add} @tab @code{memory.counts} @tab @code{value.storage.refcount}
-@item @code{commodity.prices.find} @tab @code{memory.counts.live} @tab @code{xact.extend}
-@item @code{convert.csv} @tab @code{memory.debug} @tab @code{xact.extend.cleared}
-@item @code{csv.mappings} @tab @code{op.cons} @tab @code{xact.extend.fail}
-@item @code{csv.parse} @tab @code{op.memory} @tab @code{xact.finalize}
-@item @code{draft.xact} @tab @code{option.args}
-@item @code{expr.calc} @tab @code{option.names}
-@end multitable
-
-@item --trace INTEGER_TRACE_LEVEL
-Enable tracing. The integer specifies the level of trace desired:
+@item @code{account.display} @tab @code{expr.calc.when} @tab @code{org.next_amount}
+@item @code{accounts.sorted} @tab @code{expr.compile} @tab @code{org.next_total}
+@item @code{amount.convert} @tab @code{filters.changed_value} @tab @code{parser.error}
+@item @code{amount.is_zero} @tab @code{filters.changed_value.rounding} @tab @code{pool.commodities}
+@item @code{amount.parse} @tab @code{filters.collapse} @tab @code{post.assign}
+@item @code{amount.price} @tab @code{filters.forecast} @tab @code{python.init}
+@item @code{amount.truncate} @tab @code{filters.revalued} @tab @code{python.interp}
+@item @code{amount.unround} @tab @code{format.abbrev} @tab @code{query.mask}
+@item @code{amounts.commodities} @tab @code{format.expr} @tab @code{report.predicate}
+@item @code{amounts.refs} @tab @code{generate.post} @tab @code{scope.symbols}
+@item @code{archive.journal} @tab @code{generate.post.string} @tab @code{textual.include}
+@item @code{auto.columns} @tab @code{item.meta} @tab @code{textual.parse}
+@item @code{budget.generate} @tab @code{ledger.read} @tab @code{timelog}
+@item @code{commodity.annotated.strip} @tab @code{ledger.validate} @tab @code{times.epoch}
+@item @code{commodity.annotations} @tab @code{lookup} @tab @code{times.interval}
+@item @code{commodity.compare} @tab @code{lookup.account} @tab @code{times.parse}
+@item @code{commodity.download} @tab @code{mask.match} @tab @code{value.sort}
+@item @code{commodity.prices.add} @tab @code{memory.counts} @tab @code{value.storage.refcount}
+@item @code{commodity.prices.find} @tab @code{memory.counts.live} @tab @code{xact.extend}
+@item @code{convert.csv} @tab @code{memory.debug} @tab @code{xact.extend.cleared}
+@item @code{csv.mappings} @tab @code{op.cons} @tab @code{xact.extend.fail}
+@item @code{csv.parse} @tab @code{op.memory} @tab @code{xact.finalize}
+@item @code{draft.xact} @tab @code{option.args}
+@item @code{expr.calc} @tab @code{option.names}
+@end multitable
+
+@item --trace @var{INT}
+Enable tracing. The @var{INT} specifies the level of trace desired:
+
@multitable @columnfractions .3 .7
@item @code{LOG_OFF} @tab 0
@item @code{LOG_CRIT} @tab 1
@@ -8021,45 +8604,49 @@ Enable tracing. The integer specifies the level of trace desired:
@item --verbose
Print detailed information on the execution of Ledger.
+@item --verify
+Enable additional assertions during run-time. This causes a significant
+slowdown. When combined with @code{--debug} ledger will produce
+memory trace information.
+
+@item --verify-memory
+FIX THIS ENTRY @c FIXME thdox
+
@item --version
Print version information and exit.
-@end table
+@end ftable
@node Pre-commands, , Debug Options, Developer Commands
@subsection Pre-Commands
-Pre-commands are useful when you aren't sure how a command or option
-will work.
-@table @code
-@item args
-evaluate the given arguments against the following model transaction:
-@smallexample
-2004/05/27 Book Store
- ; This note applies to all postings. :SecondTag:
- Expenses:Books 20 BOOK @@ $10
- ; Metadata: Some Value
- ; Typed:: $100 + $200
- ; :ExampleTag:
- ; Here follows a note describing the posting.
- Liabilities:MasterCard $-200.00
-@end smallexample
-@item eval
-evaluate the given value expression against the model transaction
-@item expr "LIMIT EXPRESSION"
-Print details of how ledger parses the given limit expression and apply
-it against a model transaction.
-@item format "FORMATTING"
+@cindex pre-commands
+
+Pre-commands are useful when you aren't sure how a command or option
+will work. The difference between a pre-command and a regular command
+is that pre-commands ignore the journal data file completely, nor is
+the user's init file read.
+
+@ftable @code
+@item eval @var{VEXPR}
+Evaluate the given value expression against the model transaction
+
+@item format @var{FORMAT_STRING}
Print details of how ledger uses the given formatting description and
apply it against a model transaction.
+
@item generate
-Randomly generates syntactically valid Ledger data from a seed. Used by the
-GenerateTests harness for development testing
-@item parse <VALUE EXPR>
+Randomly generates syntactically valid Ledger data from a seed. Used
+by the GenerateTests harness for development testing
+
+@item parse @var{VEXPR}
+@itemx expr @var{VEXPR}
Print details of how ledger uses the given value expression description
and apply it against a model transaction.
-@item period
-evaluate the given period and report how Ledger interprets it:
+
+@item period @var{PERIOD_EXPRESSION}
+Evaluate the given period and report how Ledger interprets it:
+
@smallexample
-20:22:21 ~/ledger (next)> ledger period "this year"
+$ ledger period "this year"
--- Period expression tokens ---
TOK_THIS: this
TOK_YEAR: year
@@ -8076,12 +8663,14 @@ END_REACHED: <EOF>
--- Sample dates in range (max. 20) ---
1: 11-Jan-01
@end smallexample
+
@item query
-evaluate the given query and report how Ledger interprets it against the
-model transaction:
+@itemx args
+Evaluate the given arguments and report how Ledger interprets it against
+the following model transaction:
@smallexample
-20:25:42 ~/ledger (next)> ledger query "/Book/"
+$ ledger query "/Book/"
--- Input arguments ---
("/Book/")
@@ -8115,57 +8704,62 @@ model transaction:
--- Calculated value ---
true
@end smallexample
+
+@item script
+FIX THIS ENTRY @c FIXME thdox
+
@item template
-Shows the insertion template that a @code{draft} or @code{xact} sub-command generates.
-This is a debugging command.
-@end table
+Shows the insertion template that a @code{draft} or @code{xact}
+sub-command generates. This is a debugging command.
+@end ftable
@node Ledger Development Environment, , Developer Commands, Ledger for Developers
@section Ledger Development Environment
@menu
-* acrep build configuration tool::
-* Testing Framework::
+* acprep build configuration tool::
+* Testing Framework::
@end menu
-@node acrep build configuration tool, Testing Framework, Ledger Development Environment, Ledger Development Environment
+@node acprep build configuration tool, Testing Framework, Ledger Development Environment, Ledger Development Environment
@subsection @code{acprep} build configuration tool
-@node Testing Framework, , acrep build configuration tool, Ledger Development Environment
+@node Testing Framework, , acprep build configuration tool, Ledger Development Environment
@subsection Testing Framework
-Ledger source ships with a farily complete set of tests to verify that
+
+Ledger source ships with a fairly complete set of tests to verify that
all is well, and no old errors have been resurfaced. Tests are run
individually with @code{ctest}. All tests can be run using @code{make
check} or @code{ninja check} depending on which build tool you prefer.
Once built, the ledger executable resides under the @file{build}
-subdirectory in the source tree. Tests are built and stored in the test
-subdirectory for the build. For example,
-@file{~/ledger/build/ledger/opt/test}.
+subdirectory in the source tree. Tests are built and stored in the
+test subdirectory for the build. For example,
+@file{~/ledger/build/ledger/opt/test}.
@menu
-* Running Tests::
-* Writing Tests::
+* Running Tests::
+* Writing Tests::
@end menu
-
@node Running Tests, Writing Tests, Testing Framework, Testing Framework
@subsubsection Running Tests
The complete test sweet can be run from the build directory using the
check option for the build tool you use. For example, @code{make
-check}. The entire test suit tast around a minute for the optimized
-built and many times longer for the debug version. While developing and
-debugging, running individual tests can save a great deal of time.
+check}. The entire test suit lasts around a minute for the optimized
+built and many times longer for the debug version. While developing
+and debugging, running individual tests can save a great deal of time.
-Individual tests can be run fron the @file{test} subdirectory of the
+Individual tests can be run from the @file{test} subdirectory of the
build location. To execute a single test use @code{ctest -V -R regex},
-where the regex mathes the name of the test you want to build.
+where the regex matches the name of the test you want to build.
+
+There are nearly 300 tests stored under the @file{test} subdirectory
+in main source distribution. They are broken into two broad
+categories, baseline and regression. To run the @file{5FBF2ED8} test,
+for example, issue @code{ctest -V -R "5FB"}.
-There are nearly 300 tests stored under the @file{test} sudirectoro
-tmain source distribution. They are broken into two broad categories,
-baseline and regression. To run the @file{5FBF2ED8} test, for example,
-issue @code{ctest -V -R "5FB"}.
@node Writing Tests, , Running Tests, Testing Framework
@subsubsection Writing Tests
@@ -8179,9 +8773,11 @@ issue @code{ctest -V -R "5FB"}.
@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,
+
+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 -*-
@@ -8246,52 +8842,58 @@ issue @code{ctest -V -R "5FB"}.
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.
+Various notes from the discussion list that I haven't incorporated in
+to the main body of the documentation.
@menu
-* Cookbook::
+* Cookbook::
@end menu
@node Cookbook, , Miscellaneous Notes, Miscellaneous Notes
@section Cookbook
+@menu
+* Invoking Ledger::
+* Ledger Files::
+@end menu
+
+@node Invoking Ledger, Ledger Files, Cookbook, 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
+$ 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
+
+@node Ledger Files, , Invoking Ledger, Cookbook
@subsection Ledger Files
@smallexample
-= /^Income:Taxable/
+= /^Income:Taxable/
(Liabilities:Tithe Owed) -0.1
-= /Noah/
+= /Noah/
(Liabilities:Tithe Owed) -0.1
-= /Jonah/
+= /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
+@unnumbered Concepts Index
@printindex cp
@node Command Index, , Concept Index, Top
-@unnumbered Command Index
+@unnumbered Commands & Options Index
@printindex fn
diff --git a/lisp/ldg-commodities.el b/lisp/ldg-commodities.el
index 031bddeb..fdc5e802 100644
--- a/lisp/ldg-commodities.el
+++ b/lisp/ldg-commodities.el
@@ -36,50 +36,47 @@
(defun ledger-split-commodity-string (str)
"Split a commoditized string, STR, into two parts.
Returns a list with (value commodity)."
- (if (> (length str) 0)
- (let ((number-regex (if (assoc "decimal-comma" ledger-environment-alist)
- ledger-amount-decimal-comma-regex
- ledger-amount-decimal-period-regex)))
- (with-temp-buffer
- (insert str)
- (goto-char (point-min))
- (cond
- ((re-search-forward "\"\\(.*\\)\"" nil t) ; look for quoted commodities
- (let ((com (delete-and-extract-region
- (match-beginning 1)
- (match-end 1))))
- (if (re-search-forward number-regex nil t)
- (list
- (string-to-number
- (ledger-commodity-string-number-decimalize
- (delete-and-extract-region (match-beginning 0) (match-end 0)) :from-user))
- com))))
- ((re-search-forward number-regex nil t)
- ;; found a number in the current locale, return it in
- ;; the car. Anything left over is annotation,
- ;; the first thing should be the commodity, separated
- ;; by whitespace, return it in the cdr. I can't think of any
- ;; counterexamples
- (list
- (string-to-number
- (ledger-commodity-string-number-decimalize
- (delete-and-extract-region (match-beginning 0) (match-end 0)) :from-user))
- (nth 0 (split-string (buffer-substring-no-properties (point-min) (point-max))))))
- ((re-search-forward "0" nil t)
- ;; couldn't find a decimal number, look for a single 0,
- ;; indicating account with zero balance
- (list 0 ledger-reconcile-default-commodity)))))
- ;; nothing found, return 0
- (list 0 ledger-reconcile-default-commodity)))
+ (let ((number-regex (if (assoc "decimal-comma" ledger-environment-alist)
+ ledger-amount-decimal-comma-regex
+ ledger-amount-decimal-period-regex)))
+ (if (> (length str) 0)
+ (with-temp-buffer
+ (insert str)
+ (goto-char (point-min))
+ (cond
+ ((re-search-forward "\"\\(.*\\)\"" nil t) ; look for quoted commodities
+ (let ((com (delete-and-extract-region
+ (match-beginning 1)
+ (match-end 1))))
+ (if (re-search-forward
+ number-regex nil t)
+ (list
+ (ledger-string-to-number
+ (delete-and-extract-region (match-beginning 0) (match-end 0)))
+ com))))
+ ((re-search-forward number-regex nil t)
+ ;; found a number in the current locale, return it in the
+ ;; car. Anything left over is annotation, the first
+ ;; thing should be the commodity, separated by
+ ;; whitespace, return it in the cdr. I can't think of
+ ;; any counterexamples
+ (list
+ (ledger-string-to-number
+ (delete-and-extract-region (match-beginning 0) (match-end 0)))
+ (nth 0 (split-string (buffer-substring-no-properties (point-min) (point-max))))))
+ ((re-search-forward "0" nil t)
+ ;; couldn't find a decimal number, look for a single 0,
+ ;; indicating account with zero balance
+ (list 0 ledger-reconcile-default-commodity))))
+ ;; nothing found, return 0
+ (list 0 ledger-reconcile-default-commodity))))
(defun ledger-string-balance-to-commoditized-amount (str)
"Return a commoditized amount (val, 'comm') from STR."
- (let ((fields (split-string str "[\n\r]"))) ; break any balances
- ; with multi commodities
- ; into a list
- (mapcar #'(lambda (str)
- (ledger-split-commodity-string str))
- fields)))
+ ; break any balances with multi commodities into a list
+ (mapcar #'(lambda (st)
+ (ledger-split-commodity-string st))
+ (split-string str "[\n\r]")))
(defun -commodity (c1 c2)
"Subtract C2 from C1, ensuring their commodities match."
@@ -93,40 +90,39 @@ Returns a list with (value commodity)."
(list (+ (car c1) (car c2)) (cadr c1))
(error "Can't add different commodities, %S to %S" c1 c2)))
-(defun ledger-commodity-string-number-decimalize (number-string direction)
- "Take NUMBER-STRING and ensure proper decimalization for use by string-to-number and number-to-string.
-
-DIRECTION can be :to-user or :from-user. All math calculations
-are done with decimal-period, some users may prefer decimal-comma
-which must be translated both directions."
- (let ((val number-string))
- (if (assoc "decimal-comma" ledger-environment-alist)
- (cond ((eq direction :from-user)
- ;; change string to decimal-period
- (while (string-match "," val)
- (setq val (replace-match "." nil nil val)))) ;; switch to period separator
- ((eq direction :to-user)
- ;; change to decimal-comma
- (while (string-match "\\." val)
- (setq val (replace-match "," nil nil val)))) ;; gets rid of periods
- (t
- (error "ledger-commodity-string-number-decimalize: direction not properly specified %S" direction)))
- (while (string-match "," val)
- (setq val (replace-match "" nil nil val))))
- val))
-
-
+(defun ledger-strip (str char)
+ (let (new-str)
+ (concat (dolist (ch (append str nil) new-str)
+ (unless (= ch char)
+ (setq new-str (append new-str (list ch))))))))
+
+(defun ledger-string-to-number (str &optional decimal-comma)
+ "improve builtin string-to-number by handling internationalization, and return nil of number can't be parsed"
+ (let ((nstr (if (or decimal-comma
+ (assoc "decimal-comma" ledger-environment-alist))
+ (ledger-strip str ?.)
+ (ledger-strip str ?,))))
+ (while (string-match "," nstr) ;if there is a comma now, it is a thousands separator
+ (setq nstr (replace-match "." nil nil nstr)))
+ (string-to-number nstr)))
+
+(defun ledger-number-to-string (n &optional decimal-comma)
+ (let ((str (number-to-string n)))
+ (if (or decimal-comma
+ (assoc "decimal-comma" ledger-environment-alist))
+ (while (string-match "\\." str)
+ (setq str (replace-match "," nil nil str)))
+ str)))
(defun ledger-commodity-to-string (c1)
"Return string representing C1.
Single character commodities are placed ahead of the value,
longer ones are after the value."
-(let ((val (ledger-commodity-string-number-decimalize
- (number-to-string (car c1)) :to-user))
- (commodity (cadr c1)))
+ (let ((str (ledger-number-to-string (car c1)))
+ (commodity (cadr c1)))
(if (> (length commodity) 1)
- (concat val " " commodity)
- (concat commodity " " val))))
+ (concat str " " commodity)
+ (concat commodity " " str))))
(defun ledger-read-commodity-string (prompt)
(let ((str (read-from-minibuffer
diff --git a/lisp/ldg-complete.el b/lisp/ldg-complete.el
index bd907bc8..e3820924 100644
--- a/lisp/ldg-complete.el
+++ b/lisp/ldg-complete.el
@@ -38,6 +38,11 @@
(point)))
(end (point))
begins args)
+ ;; to support end of line metadata
+ (save-excursion
+ (when (search-backward ";"
+ (line-beginning-position) t)
+ (setq begin (match-beginning 0))))
(save-excursion
(goto-char begin)
(when (< (point) end)
@@ -73,7 +78,7 @@ Return tree structure"
(save-excursion
(goto-char (point-min))
(while (re-search-forward
- ledger-account-any-status-regex nil t)
+ ledger-account-or-metadata-regex nil t)
(unless (and (>= origin (match-beginning 0))
(< origin (match-end 0)))
(setq account-elements
@@ -90,6 +95,21 @@ Return tree structure"
(setq account-elements (cdr account-elements)))))))
account-tree))
+(defun ledger-find-metadata-in-buffer ()
+ "Search through buffer and build list of metadata.
+Return list."
+ (let ((origin (point)) accounts)
+ (save-excursion
+ (setq ledger-account-tree (list t))
+ (goto-char (point-min))
+ (while (re-search-forward
+ ledger-metadata-regex
+ nil t)
+ (unless (and (>= origin (match-beginning 0))
+ (< origin (match-end 0)))
+ (setq accounts (cons (match-string-no-properties 2) accounts)))))
+ accounts))
+
(defun ledger-accounts ()
"Return a tree of all accounts in the buffer."
(let* ((current (caar (ledger-parse-arguments)))
@@ -102,18 +122,19 @@ Return tree structure"
(setq prefix (concat prefix (and prefix ":")
(car elements))
root (cdr xact))
- (setq root nil elements nil)))
+ (setq root nil elements nil)))
(setq elements (cdr elements)))
+ (setq root (delete (list (car elements) t) root))
(and root
(sort
(mapcar (function
(lambda (x)
- (let ((term (if prefix
- (concat prefix ":" (car x))
- (car x))))
- (if (> (length (cdr x)) 1)
- (concat term ":")
- term))))
+ (let ((term (if prefix
+ (concat prefix ":" (car x))
+ (car x))))
+ (if (> (length (cdr x)) 1)
+ (concat term ":")
+ term))))
(cdr root))
'string-lessp))))
@@ -124,21 +145,24 @@ Return tree structure"
(if (eq (save-excursion
(ledger-thing-at-point)) 'transaction)
(if (null current-prefix-arg)
- (ledger-payees-in-buffer) ;; this completes against payee names
- (progn
- (let ((text (buffer-substring-no-properties (line-beginning-position)
- (line-end-position))))
- (delete-region (line-beginning-position)
- (line-end-position))
- (condition-case nil
- (ledger-add-transaction text t)
- (error nil)))
- (forward-line)
- (goto-char (line-end-position))
- (search-backward ";" (line-beginning-position) t)
- (skip-chars-backward " \t0123456789.,")
- (throw 'pcompleted t)))
- (ledger-accounts)))))
+ (delete
+ (caar (ledger-parse-arguments))
+ (ledger-payees-in-buffer)) ;; this completes against payee names
+ (progn
+ (let ((text (buffer-substring-no-properties
+ (line-beginning-position)
+ (line-end-position))))
+ (delete-region (line-beginning-position)
+ (line-end-position))
+ (condition-case nil
+ (ledger-add-transaction text t)
+ (error nil)))
+ (forward-line)
+ (goto-char (line-end-position))
+ (search-backward ";" (line-beginning-position) t)
+ (skip-chars-backward " \t0123456789.,")
+ (throw 'pcompleted t)))
+ (ledger-accounts)))))
(defun ledger-fully-complete-xact ()
"Completes a transaction if there is another matching payee in the buffer.
@@ -157,7 +181,7 @@ Does not use ledger xact"
(setq rest-of-name (match-string 3))
;; Start copying the postings
(forward-line)
- (while (looking-at ledger-account-any-status-regex)
+ (while (looking-at ledger-account-or-metadata-regex)
(setq xacts (cons (buffer-substring-no-properties
(line-beginning-position)
(line-end-position))
@@ -183,43 +207,43 @@ ledger-magic-tab in the previous commands list so that
ledger-magic-tab would cycle properly"
(interactive "p")
(if (and interactively
- pcomplete-cycle-completions
- pcomplete-current-completions
- (memq last-command '(ledger-magic-tab
- ledger-pcomplete
- pcomplete-expand-and-complete
- pcomplete-reverse)))
+ pcomplete-cycle-completions
+ pcomplete-current-completions
+ (memq last-command '(ledger-magic-tab
+ ledger-pcomplete
+ pcomplete-expand-and-complete
+ pcomplete-reverse)))
(progn
- (delete-backward-char pcomplete-last-completion-length)
- (if (eq this-command 'pcomplete-reverse)
- (progn
+ (delete-backward-char pcomplete-last-completion-length)
+ (if (eq this-command 'pcomplete-reverse)
+ (progn
(push (car (last pcomplete-current-completions))
pcomplete-current-completions)
- (setcdr (last pcomplete-current-completions 2) nil))
- (nconc pcomplete-current-completions
- (list (car pcomplete-current-completions)))
- (setq pcomplete-current-completions
- (cdr pcomplete-current-completions)))
- (pcomplete-insert-entry pcomplete-last-completion-stub
+ (setcdr (last pcomplete-current-completions 2) nil))
+ (nconc pcomplete-current-completions
+ (list (car pcomplete-current-completions)))
+ (setq pcomplete-current-completions
+ (cdr pcomplete-current-completions)))
+ (pcomplete-insert-entry pcomplete-last-completion-stub
(car pcomplete-current-completions)
- nil pcomplete-last-completion-raw))
+ nil pcomplete-last-completion-raw))
(setq pcomplete-current-completions nil
- pcomplete-last-completion-raw nil)
+ pcomplete-last-completion-raw nil)
(catch 'pcompleted
(let* ((pcomplete-stub)
- pcomplete-seen pcomplete-norm-func
- pcomplete-args pcomplete-last pcomplete-index
- (pcomplete-autolist pcomplete-autolist)
- (pcomplete-suffix-list pcomplete-suffix-list)
- (completions (pcomplete-completions))
- (result (pcomplete-do-complete pcomplete-stub completions)))
- (and result
- (not (eq (car result) 'listed))
- (cdr result)
- (pcomplete-insert-entry pcomplete-stub (cdr result)
- (memq (car result)
- '(sole shortest))
- pcomplete-last-completion-raw))))))
+ pcomplete-seen pcomplete-norm-func
+ pcomplete-args pcomplete-last pcomplete-index
+ (pcomplete-autolist pcomplete-autolist)
+ (pcomplete-suffix-list pcomplete-suffix-list)
+ (completions (pcomplete-completions))
+ (result (pcomplete-do-complete pcomplete-stub completions)))
+ (and result
+ (not (eq (car result) 'listed))
+ (cdr result)
+ (pcomplete-insert-entry pcomplete-stub (cdr result)
+ (memq (car result)
+ '(sole shortest))
+ pcomplete-last-completion-raw))))))
(provide 'ldg-complete)
diff --git a/lisp/ldg-fonts.el b/lisp/ldg-fonts.el
index cb7a81c0..fc0b7813 100644
--- a/lisp/ldg-fonts.el
+++ b/lisp/ldg-fonts.el
@@ -113,8 +113,9 @@
(defvar ledger-font-lock-keywords
`( ;; (,ledger-other-entries-regex 1
;; ledger-font-other-face)
- (,ledger-comment-regex 2
+ (,ledger-comment-regex 0
'ledger-font-comment-face)
+ (,ledger-multiline-comment-regex 0 'ledger-font-comment-face)
(,ledger-payee-pending-regex 2
'ledger-font-payee-pending-face) ; Works
(,ledger-payee-cleared-regex 2
@@ -130,7 +131,34 @@
(,ledger-other-entries-regex 1
'ledger-font-other-face))
"Expressions to highlight in Ledger mode.")
-
+
+(defun ledger-extend-region-multiline-comment ()
+ "Adjusts the variables font-lock-beg and font-lock-end if they
+ fall within a multiline comment. Returns non-nil if an
+ adjustment is made."
+ (let (beg end)
+ ;; fix beg
+ (save-excursion
+ (goto-char font-lock-beg)
+ (end-of-line)
+ (when (re-search-backward ledger-multiline-comment-start-regex nil t)
+ (setq beg (point))
+ (re-search-forward ledger-multiline-comment-regex nil t)
+ (if (and (>= (point) font-lock-beg)
+ (/= beg font-lock-beg))
+ (setq font-lock-beg beg)
+ (setq beg nil))))
+ ;; fix end
+ (save-excursion
+ (goto-char font-lock-end)
+ (end-of-line)
+ (when (re-search-backward ledger-multiline-comment-start-regex nil t)
+ (re-search-forward ledger-multiline-comment-regex nil t)
+ (setq end (point))
+ (if (> end font-lock-end)
+ (setq font-lock-end end)
+ (setq end nil))))
+ (or beg end)))
(provide 'ldg-fonts)
diff --git a/lisp/ldg-mode.el b/lisp/ldg-mode.el
index 4bc195ed..160296c3 100644
--- a/lisp/ldg-mode.el
+++ b/lisp/ldg-mode.el
@@ -68,13 +68,21 @@ And calculate the target-delta of the account being reconciled."
(message balance))))
(defun ledger-magic-tab (&optional interactively)
- "Decide what to with with <TAB> .
-Can be pcomplete, or align-posting"
+ "Decide what to with with <TAB>.
+Can indent, complete or align depending on context."
(interactive "p")
- (if (and (> (point) 1)
- (looking-back "[:A-Za-z0-9]" 1))
- (ledger-pcomplete interactively)
- (ledger-post-align-postings)))
+ (when (= (point) (line-end-position))
+ (if (= (point) (line-beginning-position))
+ (indent-to ledger-post-account-alignment-column)
+ (save-excursion
+ (re-search-backward
+ (rx-static-or ledger-account-any-status-regex
+ ledger-metadata-regex
+ ledger-payee-any-status-regex)
+ (line-beginning-position) t))
+ (when (= (point) (match-end 0))
+ (ledger-pcomplete interactively))))
+ (ledger-post-align-postings))
(defvar ledger-mode-abbrev-table)
@@ -102,6 +110,10 @@ Can be pcomplete, or align-posting"
(if (boundp 'font-lock-defaults)
(set (make-local-variable 'font-lock-defaults)
'(ledger-font-lock-keywords nil t)))
+ (setq font-lock-extend-region-functions
+ (list #'font-lock-extend-region-wholelines
+ #'ledger-extend-region-multiline-comment))
+ (setq font-lock-multiline nil)
(set (make-local-variable 'pcomplete-parse-arguments-function)
'ledger-parse-arguments)
diff --git a/lisp/ldg-occur.el b/lisp/ldg-occur.el
index 96c364d6..3ae1ea17 100644
--- a/lisp/ldg-occur.el
+++ b/lisp/ldg-occur.el
@@ -59,7 +59,7 @@
"A list of currently active overlays to the ledger buffer.")
(make-variable-buffer-local 'ledger-occur-overlay-list)
-(defun ledger-remove-all-overlays ()
+(defun ledger-occur-remove-all-overlays ()
"Remove all overlays from the ledger buffer."
(interactive)
(remove-overlays))
@@ -130,8 +130,7 @@ When REGEX is nil, unhide everything, and remove higlight"
buffer-matches))))
(mapcar (lambda (ovl)
(overlay-put ovl ledger-occur-overlay-property-name t)
- (overlay-put ovl 'invisible t)
- (overlay-put ovl 'intangible t))
+ (overlay-put ovl 'invisible t))
(push (make-overlay (cadr (car(last buffer-matches)))
(point-max)
(current-buffer) t nil) overlays)))))
diff --git a/lisp/ldg-post.el b/lisp/ldg-post.el
index 37722fbc..7e4a631c 100644
--- a/lisp/ldg-post.el
+++ b/lisp/ldg-post.el
@@ -217,7 +217,7 @@ BEG, END, and LEN control how far it can align."
(let ((end-of-amount (re-search-forward "[-.,0-9]+" (line-end-position) t)))
;; determine if there is an amount to edit
(if end-of-amount
- (let ((val (ledger-commodity-string-number-decimalize (match-string 0) :from-user)))
+ (let ((val (ledger-string-to-number (match-string 0))))
(goto-char (match-beginning 0))
(delete-region (match-beginning 0) (match-end 0))
(calc)
diff --git a/lisp/ldg-reconcile.el b/lisp/ldg-reconcile.el
index ca4d0004..3ee20a59 100644
--- a/lisp/ldg-reconcile.el
+++ b/lisp/ldg-reconcile.el
@@ -33,7 +33,7 @@
(defvar ledger-target nil)
(defgroup ledger-reconcile nil
- "Options for Ledger-mode reconciliation"
+ "Options for Ledger-mode reconciliation"
:group 'ledger)
(defcustom ledger-recon-buffer-name "*Reconcile*"
@@ -59,8 +59,8 @@ Then that transaction will be shown in its source buffer."
(defcustom ledger-reconcile-toggle-to-pending t
"If true then toggle between uncleared and pending.
reconcile-finish will mark all pending posting cleared."
- :type 'boolean
- :group 'ledger-reconcile)
+ :type 'boolean
+ :group 'ledger-reconcile)
(defcustom ledger-reconcile-default-date-format "%Y/%m/%d"
"Default date format for the reconcile buffer"
@@ -85,10 +85,10 @@ reconcile-finish will mark all pending posting cleared."
;; split arguments like the shell does, so you need to
;; specify the individual fields in the command line.
(if (ledger-exec-ledger buffer (current-buffer)
- "balance" "--limit" "cleared or pending" "--empty" "--collapse"
- "--format" "%(display_total)" account)
- (ledger-split-commodity-string
- (buffer-substring-no-properties (point-min) (point-max))))))
+ "balance" "--limit" "cleared or pending" "--empty" "--collapse"
+ "--format" "%(display_total)" account)
+ (ledger-split-commodity-string
+ (buffer-substring-no-properties (point-min) (point-max))))))
(defun ledger-display-balance ()
"Display the cleared-or-pending balance.
@@ -96,12 +96,12 @@ And calculate the target-delta of the account being reconciled."
(interactive)
(let* ((pending (ledger-reconcile-get-cleared-or-pending-balance ledger-buf ledger-acct)))
(when pending
- (if ledger-target
- (message "Pending balance: %s, Difference from target: %s"
- (ledger-commodity-to-string pending)
- (ledger-commodity-to-string (-commodity ledger-target pending)))
- (message "Pending balance: %s"
- (ledger-commodity-to-string pending))))))
+ (if ledger-target
+ (message "Pending balance: %s, Difference from target: %s"
+ (ledger-commodity-to-string pending)
+ (ledger-commodity-to-string (-commodity ledger-target pending)))
+ (message "Pending balance: %s"
+ (ledger-commodity-to-string pending))))))
(defun is-stdin (file)
"True if ledger FILE is standard input."
@@ -125,27 +125,27 @@ And calculate the target-delta of the account being reconciled."
status)
(when (ledger-reconcile-get-buffer where)
(with-current-buffer (ledger-reconcile-get-buffer where)
- (ledger-goto-line (cdr where))
- (forward-char)
- (setq status (ledger-toggle-current (if ledger-reconcile-toggle-to-pending
- 'pending
- 'cleared))))
- ;; remove the existing face and add the new face
+ (ledger-goto-line (cdr where))
+ (forward-char)
+ (setq status (ledger-toggle-current (if ledger-reconcile-toggle-to-pending
+ 'pending
+ 'cleared))))
+ ;; remove the existing face and add the new face
(remove-text-properties (line-beginning-position)
- (line-end-position)
- (list 'face))
+ (line-end-position)
+ (list 'face))
(cond ((eq status 'pending)
- (add-text-properties (line-beginning-position)
- (line-end-position)
- (list 'face 'ledger-font-reconciler-pending-face )))
- ((eq status 'cleared)
- (add-text-properties (line-beginning-position)
- (line-end-position)
- (list 'face 'ledger-font-reconciler-cleared-face )))
- (t
- (add-text-properties (line-beginning-position)
- (line-end-position)
- (list 'face 'ledger-font-reconciler-uncleared-face )))))
+ (add-text-properties (line-beginning-position)
+ (line-end-position)
+ (list 'face 'ledger-font-reconciler-pending-face )))
+ ((eq status 'cleared)
+ (add-text-properties (line-beginning-position)
+ (line-end-position)
+ (list 'face 'ledger-font-reconciler-cleared-face )))
+ (t
+ (add-text-properties (line-beginning-position)
+ (line-end-position)
+ (list 'face 'ledger-font-reconciler-uncleared-face )))))
(forward-line)
(beginning-of-line)
(ledger-display-balance)))
@@ -157,18 +157,18 @@ Return the number of uncleared xacts found."
(let ((inhibit-read-only t))
(erase-buffer)
(prog1
- (ledger-do-reconcile)
+ (ledger-do-reconcile)
(set-buffer-modified-p t))))
(defun ledger-reconcile-refresh-after-save ()
"Refresh the recon-window after the ledger buffer is saved."
(let ((curbuf (current-buffer))
- (curpoint (point))
- (recon-buf (get-buffer ledger-recon-buffer-name)))
+ (curpoint (point))
+ (recon-buf (get-buffer ledger-recon-buffer-name)))
(when (buffer-live-p recon-buf)
(with-current-buffer recon-buf
- (ledger-reconcile-refresh)
- (set-buffer-modified-p nil))
+ (ledger-reconcile-refresh)
+ (set-buffer-modified-p nil))
(select-window (get-buffer-window curbuf))
(goto-char curpoint))))
@@ -198,19 +198,19 @@ Return the number of uncleared xacts found."
(progn
(beginning-of-line)
(let* ((where (get-text-property (1+ (point)) 'where))
- (target-buffer (if where
- (ledger-reconcile-get-buffer where)
- nil))
- (cur-buf (get-buffer ledger-recon-buffer-name)))
+ (target-buffer (if where
+ (ledger-reconcile-get-buffer where)
+ nil))
+ (cur-buf (get-buffer ledger-recon-buffer-name)))
(when target-buffer
- (switch-to-buffer-other-window target-buffer)
- (ledger-goto-line (cdr where))
- (forward-char)
- (recenter)
- (ledger-highlight-xact-under-point)
- (forward-char -1)
- (if come-back
- (switch-to-buffer-other-window cur-buf))))))
+ (switch-to-buffer-other-window target-buffer)
+ (ledger-goto-line (cdr where))
+ (forward-char)
+ (recenter)
+ (ledger-highlight-xact-under-point)
+ (forward-char -1)
+ (if come-back
+ (switch-to-buffer-other-window cur-buf))))))
(defun ledger-reconcile-save ()
"Save the ledger buffer."
@@ -218,7 +218,7 @@ Return the number of uncleared xacts found."
(let ((curpoint (point)))
(dolist (buf (cons ledger-buf ledger-bufs))
(with-current-buffer buf
- (save-buffer)))
+ (save-buffer)))
(with-current-buffer (get-buffer ledger-recon-buffer-name)
(set-buffer-modified-p nil)
(ledger-display-balance)
@@ -247,84 +247,84 @@ and exit reconcile mode"
"Quit the reconcile window without saving ledger buffer."
(interactive)
(let ((recon-buf (get-buffer ledger-recon-buffer-name))
- buf)
+ buf)
(if recon-buf
- (with-current-buffer recon-buf
- (ledger-reconcile-quit-cleanup)
- (setq buf ledger-buf)
- ;; Make sure you delete the window before you delete the buffer,
- ;; otherwise, madness ensues
- (delete-window (get-buffer-window recon-buf))
- (kill-buffer recon-buf)
- (set-window-buffer (selected-window) buf)))))
+ (with-current-buffer recon-buf
+ (ledger-reconcile-quit-cleanup)
+ (setq buf ledger-buf)
+ ;; Make sure you delete the window before you delete the buffer,
+ ;; otherwise, madness ensues
+ (delete-window (get-buffer-window recon-buf))
+ (kill-buffer recon-buf)
+ (set-window-buffer (selected-window) buf)))))
(defun ledger-reconcile-quit-cleanup ()
"Cleanup all hooks established by reconcile mode."
(interactive)
(let ((buf ledger-buf))
(if (buffer-live-p buf)
- (with-current-buffer buf
- (remove-hook 'after-save-hook 'ledger-reconcile-refresh-after-save t)
- (when ledger-narrow-on-reconcile
- (ledger-occur-quit-buffer buf)
- (ledger-highlight-xact-under-point))))))
+ (with-current-buffer buf
+ (remove-hook 'after-save-hook 'ledger-reconcile-refresh-after-save t)
+ (when ledger-narrow-on-reconcile
+ (ledger-occur-quit-buffer buf)
+ (ledger-highlight-xact-under-point))))))
(defun ledger-marker-where-xact-is (emacs-xact posting)
"Find the position of the EMACS-XACT in the `ledger-buf'.
POSTING is used in `ledger-clear-whole-transactions' is nil."
(let ((buf (if (is-stdin (nth 0 emacs-xact))
- ledger-buf
- (find-file-noselect (nth 0 emacs-xact)))))
+ ledger-buf
+ (find-file-noselect (nth 0 emacs-xact)))))
(cons
buf
(if ledger-clear-whole-transactions
- (nth 1 emacs-xact) ;; return line-no of xact
- (nth 0 posting))))) ;; return line-no of posting
+ (nth 1 emacs-xact) ;; return line-no of xact
+ (nth 0 posting))))) ;; return line-no of posting
(defun ledger-do-reconcile ()
"Return the number of uncleared transactions in the account and display them in the *Reconcile* buffer."
(let* ((buf ledger-buf)
(account ledger-acct)
- (ledger-success nil)
+ (ledger-success nil)
(xacts
(with-temp-buffer
- (when (ledger-exec-ledger buf (current-buffer)
- "--uncleared" "--real" "emacs" account)
- (setq ledger-success t)
- (goto-char (point-min))
- (unless (eobp)
- (if (looking-at "(")
- (read (current-buffer)))))))) ;current-buffer is the *temp* created above
+ (when (ledger-exec-ledger buf (current-buffer)
+ "--uncleared" "--real" "emacs" account)
+ (setq ledger-success t)
+ (goto-char (point-min))
+ (unless (eobp)
+ (if (looking-at "(")
+ (read (current-buffer)))))))) ;current-buffer is the *temp* created above
(if (and ledger-success (> (length xacts) 0))
- (let ((date-format (cdr (assoc "date-format" ledger-environment-alist))))
- (dolist (xact xacts)
- (dolist (posting (nthcdr 5 xact))
- (let ((beg (point))
- (where (ledger-marker-where-xact-is xact posting)))
- (insert (format "%s %-4s %-30s %-30s %15s\n"
- (format-time-string (if date-format
- date-format
- ledger-reconcile-default-date-format) (nth 2 xact))
- (if (nth 3 xact)
- (nth 3 xact)
- "")
- (nth 4 xact) (nth 1 posting) (nth 2 posting)))
- (if (nth 3 posting)
- (if (eq (nth 3 posting) 'pending)
- (set-text-properties beg (1- (point))
- (list 'face 'ledger-font-reconciler-pending-face
- 'where where))
- (set-text-properties beg (1- (point))
- (list 'face 'ledger-font-reconciler-cleared-face
- 'where where)))
- (set-text-properties beg (1- (point))
- (list 'face 'ledger-font-reconciler-uncleared-face
- 'where where)))) ))
- (goto-char (point-max))
- (delete-char -1)) ;gets rid of the extra line feed at the bottom of the list
- (if ledger-success
- (insert (concat "There are no uncleared entries for " account))
- (insert "Ledger has reported a problem. Check *Ledger Error* buffer.")))
+ (let ((date-format (cdr (assoc "date-format" ledger-environment-alist))))
+ (dolist (xact xacts)
+ (dolist (posting (nthcdr 5 xact))
+ (let ((beg (point))
+ (where (ledger-marker-where-xact-is xact posting)))
+ (insert (format "%s %-4s %-30s %-30s %15s\n"
+ (format-time-string (if date-format
+ date-format
+ ledger-reconcile-default-date-format) (nth 2 xact))
+ (if (nth 3 xact)
+ (nth 3 xact)
+ "")
+ (nth 4 xact) (nth 1 posting) (nth 2 posting)))
+ (if (nth 3 posting)
+ (if (eq (nth 3 posting) 'pending)
+ (set-text-properties beg (1- (point))
+ (list 'face 'ledger-font-reconciler-pending-face
+ 'where where))
+ (set-text-properties beg (1- (point))
+ (list 'face 'ledger-font-reconciler-cleared-face
+ 'where where)))
+ (set-text-properties beg (1- (point))
+ (list 'face 'ledger-font-reconciler-uncleared-face
+ 'where where)))) ))
+ (goto-char (point-max))
+ (delete-char -1)) ;gets rid of the extra line feed at the bottom of the list
+ (if ledger-success
+ (insert (concat "There are no uncleared entries for " account))
+ (insert "Ledger has reported a problem. Check *Ledger Error* buffer.")))
(goto-char (point-min))
(set-buffer-modified-p nil)
(toggle-read-only t)
@@ -338,30 +338,30 @@ ledger buffer is at the bottom of the main window. The key to
this is to ensure the window is selected when the buffer point is
moved and recentered. If they aren't strange things happen."
- (let ((recon-window (get-buffer-window (get-buffer ledger-recon-buffer-name))))
- (when recon-window
- (fit-window-to-buffer recon-window)
- (with-current-buffer buf
- (add-hook 'kill-buffer-hook 'ledger-reconcile-quit nil t)
- (if (get-buffer-window buf)
- (select-window (get-buffer-window buf)))
- (goto-char (point-max))
- (recenter -1))
- (select-window recon-window)
- (ledger-reconcile-visit t))
- (add-hook 'post-command-hook 'ledger-reconcile-track-xact nil t)))
+ (let ((recon-window (get-buffer-window (get-buffer ledger-recon-buffer-name))))
+ (when recon-window
+ (fit-window-to-buffer recon-window)
+ (with-current-buffer buf
+ (add-hook 'kill-buffer-hook 'ledger-reconcile-quit nil t)
+ (if (get-buffer-window buf)
+ (select-window (get-buffer-window buf)))
+ (goto-char (point-max))
+ (recenter -1))
+ (select-window recon-window)
+ (ledger-reconcile-visit t))
+ (add-hook 'post-command-hook 'ledger-reconcile-track-xact nil t)))
(defun ledger-reconcile-track-xact ()
"Force the ledger buffer to recenter on the transaction at point in the reconcile buffer."
(if (and ledger-buffer-tracks-reconcile-buffer
- (member this-command (list 'next-line
- 'previous-line
- 'mouse-set-point
- 'ledger-reconcile-toggle
- 'end-of-buffer
- 'beginning-of-buffer)))
+ (member this-command (list 'next-line
+ 'previous-line
+ 'mouse-set-point
+ 'ledger-reconcile-toggle
+ 'end-of-buffer
+ 'beginning-of-buffer)))
(save-excursion
- (ledger-reconcile-visit t))))
+ (ledger-reconcile-visit t))))
(defun ledger-reconcile-open-windows (buf rbuf)
"Ensure that the ledger buffer BUF is split by RBUF."
@@ -374,39 +374,39 @@ moved and recentered. If they aren't strange things happen."
"Start reconciling, prompt for account."
(interactive)
(let ((account (ledger-read-account-with-prompt "Account to reconcile"))
- (buf (current-buffer))
+ (buf (current-buffer))
(rbuf (get-buffer ledger-recon-buffer-name)))
;; this means only one *Reconcile* buffer, ever Set up the
;; reconcile buffer
(if rbuf ;; *Reconcile* already exists
- (with-current-buffer rbuf
- (set 'ledger-acct account) ;; already buffer local
- (when (not (eq buf rbuf))
- ;; called from some other ledger-mode buffer
- (ledger-reconcile-quit-cleanup)
- (set 'ledger-buf buf)) ;; should already be buffer-local
-
- (unless (get-buffer-window rbuf)
- (ledger-reconcile-open-windows buf rbuf)))
-
- ;; no recon-buffer, starting from scratch.
- (add-hook 'after-save-hook 'ledger-reconcile-refresh-after-save nil t)
-
- (with-current-buffer (setq rbuf
- (get-buffer-create ledger-recon-buffer-name))
- (ledger-reconcile-open-windows buf rbuf)
- (ledger-reconcile-mode)
- (make-local-variable 'ledger-target)
- (set (make-local-variable 'ledger-buf) buf)
- (set (make-local-variable 'ledger-acct) account)))
+ (with-current-buffer rbuf
+ (set 'ledger-acct account) ;; already buffer local
+ (when (not (eq buf rbuf))
+ ;; called from some other ledger-mode buffer
+ (ledger-reconcile-quit-cleanup)
+ (set 'ledger-buf buf)) ;; should already be buffer-local
+
+ (unless (get-buffer-window rbuf)
+ (ledger-reconcile-open-windows buf rbuf)))
+
+ ;; no recon-buffer, starting from scratch.
+ (add-hook 'after-save-hook 'ledger-reconcile-refresh-after-save nil t)
+
+ (with-current-buffer (setq rbuf
+ (get-buffer-create ledger-recon-buffer-name))
+ (ledger-reconcile-open-windows buf rbuf)
+ (ledger-reconcile-mode)
+ (make-local-variable 'ledger-target)
+ (set (make-local-variable 'ledger-buf) buf)
+ (set (make-local-variable 'ledger-acct) account)))
;; Narrow the ledger buffer
(with-current-buffer rbuf
(save-excursion
- (if ledger-narrow-on-reconcile
- (ledger-occur-mode account ledger-buf)))
+ (if ledger-narrow-on-reconcile
+ (ledger-occur-mode account ledger-buf)))
(if (> (ledger-reconcile-refresh) 0)
- (ledger-reconcile-change-target))
+ (ledger-reconcile-change-target))
(ledger-display-balance))))
(defvar ledger-reconcile-mode-abbrev-table)
@@ -417,45 +417,45 @@ moved and recentered. If they aren't strange things happen."
(setq ledger-target (ledger-read-commodity-string ledger-reconcile-target-prompt-string)))
(define-derived-mode ledger-reconcile-mode text-mode "Reconcile"
- "A mode for reconciling ledger entries."
- (let ((map (make-sparse-keymap)))
- (define-key map [(control ?m)] 'ledger-reconcile-visit)
- (define-key map [return] 'ledger-reconcile-visit)
- (define-key map [(control ?l)] 'ledger-reconcile-refresh)
- (define-key map [(control ?c) (control ?c)] 'ledger-reconcile-finish)
- (define-key map [? ] 'ledger-reconcile-toggle)
- (define-key map [?a] 'ledger-reconcile-add)
- (define-key map [?d] 'ledger-reconcile-delete)
- (define-key map [?g] 'ledger-reconcile);
- (define-key map [?n] 'next-line)
- (define-key map [?p] 'previous-line)
- (define-key map [?t] 'ledger-reconcile-change-target)
- (define-key map [?s] 'ledger-reconcile-save)
- (define-key map [?q] 'ledger-reconcile-quit)
- (define-key map [?b] 'ledger-display-balance)
-
- (define-key map [menu-bar] (make-sparse-keymap "ldg-recon-menu"))
- (define-key map [menu-bar ldg-recon-menu] (cons "Reconcile" map))
- (define-key map [menu-bar ldg-recon-menu qui] '("Quit" . ledger-reconcile-quit))
- (define-key map [menu-bar ldg-recon-menu sep1] '("--"))
- (define-key map [menu-bar ldg-recon-menu pre] '("Previous Entry" . previous-line))
- (define-key map [menu-bar ldg-recon-menu vis] '("Visit Source" . ledger-reconcile-visit))
- (define-key map [menu-bar ldg-recon-menu nex] '("Next Entry" . next-line))
- (define-key map [menu-bar ldg-recon-menu sep2] '("--"))
- (define-key map [menu-bar ldg-recon-menu del] '("Delete Entry" . ledger-reconcile-delete))
- (define-key map [menu-bar ldg-recon-menu add] '("Add Entry" . ledger-reconcile-add))
- (define-key map [menu-bar ldg-recon-menu tog] '("Toggle Entry" . ledger-reconcile-toggle))
- (define-key map [menu-bar ldg-recon-menu sep3] '("--"))
- (define-key map [menu-bar ldg-recon-menu bal] '("Show Cleared Balance" . ledger-display-balance))
- (define-key map [menu-bar ldg-recon-menu tgt] '("Change Target Balance" . ledger-reconcile-change-target))
- (define-key map [menu-bar ldg-recon-menu sep4] '("--"))
- (define-key map [menu-bar ldg-recon-menu rna] '("Reconcile New Account" . ledger-reconcile))
- (define-key map [menu-bar ldg-recon-menu sep5] '("--"))
- (define-key map [menu-bar ldg-recon-menu fin] '("Finish" . ledger-reconcile-finish))
- (define-key map [menu-bar ldg-recon-menu ref] '("Refresh" . ledger-reconcile-refresh))
- (define-key map [menu-bar ldg-recon-menu sav] '("Save" . ledger-reconcile-save))
-
- (use-local-map map)))
+ "A mode for reconciling ledger entries."
+ (let ((map (make-sparse-keymap)))
+ (define-key map [(control ?m)] 'ledger-reconcile-visit)
+ (define-key map [return] 'ledger-reconcile-visit)
+ (define-key map [(control ?l)] 'ledger-reconcile-refresh)
+ (define-key map [(control ?c) (control ?c)] 'ledger-reconcile-finish)
+ (define-key map [? ] 'ledger-reconcile-toggle)
+ (define-key map [?a] 'ledger-reconcile-add)
+ (define-key map [?d] 'ledger-reconcile-delete)
+ (define-key map [?g] 'ledger-reconcile);
+ (define-key map [?n] 'next-line)
+ (define-key map [?p] 'previous-line)
+ (define-key map [?t] 'ledger-reconcile-change-target)
+ (define-key map [?s] 'ledger-reconcile-save)
+ (define-key map [?q] 'ledger-reconcile-quit)
+ (define-key map [?b] 'ledger-display-balance)
+
+ (define-key map [menu-bar] (make-sparse-keymap "ldg-recon-menu"))
+ (define-key map [menu-bar ldg-recon-menu] (cons "Reconcile" map))
+ (define-key map [menu-bar ldg-recon-menu qui] '("Quit" . ledger-reconcile-quit))
+ (define-key map [menu-bar ldg-recon-menu sep1] '("--"))
+ (define-key map [menu-bar ldg-recon-menu pre] '("Previous Entry" . previous-line))
+ (define-key map [menu-bar ldg-recon-menu vis] '("Visit Source" . ledger-reconcile-visit))
+ (define-key map [menu-bar ldg-recon-menu nex] '("Next Entry" . next-line))
+ (define-key map [menu-bar ldg-recon-menu sep2] '("--"))
+ (define-key map [menu-bar ldg-recon-menu del] '("Delete Entry" . ledger-reconcile-delete))
+ (define-key map [menu-bar ldg-recon-menu add] '("Add Entry" . ledger-reconcile-add))
+ (define-key map [menu-bar ldg-recon-menu tog] '("Toggle Entry" . ledger-reconcile-toggle))
+ (define-key map [menu-bar ldg-recon-menu sep3] '("--"))
+ (define-key map [menu-bar ldg-recon-menu bal] '("Show Cleared Balance" . ledger-display-balance))
+ (define-key map [menu-bar ldg-recon-menu tgt] '("Change Target Balance" . ledger-reconcile-change-target))
+ (define-key map [menu-bar ldg-recon-menu sep4] '("--"))
+ (define-key map [menu-bar ldg-recon-menu rna] '("Reconcile New Account" . ledger-reconcile))
+ (define-key map [menu-bar ldg-recon-menu sep5] '("--"))
+ (define-key map [menu-bar ldg-recon-menu fin] '("Finish" . ledger-reconcile-finish))
+ (define-key map [menu-bar ldg-recon-menu ref] '("Refresh" . ledger-reconcile-refresh))
+ (define-key map [menu-bar ldg-recon-menu sav] '("Save" . ledger-reconcile-save))
+
+ (use-local-map map)))
(provide 'ldg-reconcile)
diff --git a/lisp/ldg-regex.el b/lisp/ldg-regex.el
index 226475df..cdd06d39 100644
--- a/lisp/ldg-regex.el
+++ b/lisp/ldg-regex.el
@@ -37,39 +37,59 @@
"-?[1-9][0-9.]*[,]?[0-9]*")
(defconst ledger-amount-decimal-period-regex
- "-?[1-9][0-9.]*[.]?[0-9]*")
+ "-?[1-9][0-9,]*[.]?[0-9]*")
(defconst ledger-other-entries-regex
"\\(^[~=A-Za-z].+\\)+")
(defconst ledger-comment-regex
- "\\( \\| \\|^\\)\\(;.*\\)")
+ "^[;#|\\*%].*\\|[ \t]+;.*")
+
+(defconst ledger-multiline-comment-start-regex
+ "^!comment$")
+(defconst ledger-multiline-comment-end-regex
+ "^!end_comment$")
+(defconst ledger-multiline-comment-regex
+ "^!comment\n\\(.*\n\\)*?!end_comment$")
(defconst ledger-payee-any-status-regex
- "^[0-9/.=-]+\\(\\s-+\\*\\)?\\(\\s-+(.*?)\\)?\\s-+\\(.+?\\)\\(\t\\|\n\\| [ \t]\\)")
+ "^[0-9]+[-/][-/.=0-9]+\\(\\s-+\\*\\)?\\(\\s-+(.*?)\\)?\\s-+\\(.+?\\)\\s-*\\(;\\|$\\)")
(defconst ledger-payee-pending-regex
- "^[0-9]+[-/][-/.=0-9]+\\s-\\!\\s-+\\(([^)]+)\\s-+\\)?\\([^*].+?\\)\\(;\\|$\\)")
+ "^[0-9]+[-/][-/.=0-9]+\\s-\\!\\s-+\\(([^)]+)\\s-+\\)?\\([^*].+?\\)\\s-*\\(;\\|$\\)")
(defconst ledger-payee-cleared-regex
- "^[0-9]+[-/][-/.=0-9]+\\s-\\*\\s-+\\(([^)]+)\\s-+\\)?\\([^*].+?\\)\\(;\\|$\\)")
+ "^[0-9]+[-/][-/.=0-9]+\\s-\\*\\s-+\\(([^)]+)\\s-+\\)?\\([^*].+?\\)\\s-*\\(;\\|$\\)")
(defconst ledger-payee-uncleared-regex
- "^[0-9]+[-/][-/.=0-9]+\\s-+\\(([^)]+)\\s-+\\)?\\([^*].+?\\)\\(;\\|$\\)")
+ "^[0-9]+[-/][-/.=0-9]+\\s-+\\(([^)]+)\\s-+\\)?\\([^*].+?\\)\\s-*\\(;\\|$\\)")
(defconst ledger-init-string-regex
"^--.+?\\($\\|[ ]\\)")
(defconst ledger-account-any-status-regex
- "^[ \t]+\\([*!]\\s-+\\)?\\([[(]?.+?\\)\\(\t\\|\n\\| [ \t]\\)")
+ "^[ \t]+\\(?1:[*!]\\s-*\\)?\\(?2:[^ ;].*?\\)\\( \\|\t\\|$\\)")
(defconst ledger-account-pending-regex
- "\\(^[ \t]+\\)\\(!.+?\\)\\( \\|$\\)")
+ "\\(^[ \t]+\\)\\(!\\s-*.*?\\)\\( \\|\t\\|$\\)")
(defconst ledger-account-cleared-regex
- "\\(^[ \t]+\\)\\(\\*.+?\\)\\( \\|$\\)")
-
-
+ "\\(^[ \t]+\\)\\(*\\s-*.*?\\)\\( \\|\t\\|$\\)")
+
+(defconst ledger-metadata-regex
+ "[ \t]+\\(?2:;[ \t]+.+\\)$")
+
+(defconst ledger-account-or-metadata-regex
+ (concat
+ ledger-account-any-status-regex
+ "\\|"
+ ledger-metadata-regex))
+
+(defmacro rx-static-or (&rest rx-strs)
+ "Returns rx union of regexps which can be symbols that eval to strings."
+ `(rx (or ,@(mapcar #'(lambda (rx-str)
+ `(regexp ,(eval rx-str)))
+ rx-strs))))
(defmacro ledger-define-regexp (name regex docs &rest args)
"Simplify the creation of a Ledger regex and helper functions."
diff --git a/lisp/ldg-report.el b/lisp/ldg-report.el
index c3b83f55..9b16522f 100644
--- a/lisp/ldg-report.el
+++ b/lisp/ldg-report.el
@@ -295,32 +295,32 @@ Optional EDIT the command."
"\n\n")
(let ((data-pos (point))
(register-report (string-match " reg\\(ister\\)? " cmd))
- files-in-report)
+ files-in-report)
(shell-command
;; --subtotal does not produce identifiable transactions, so don't
;; prepend location information for them
(if (and register-report
- (not (string-match "--subtotal" cmd)))
- (concat cmd " --prepend-format='%(filename):%(beg_line):'")
- cmd)
+ (not (string-match "--subtotal" cmd)))
+ (concat cmd " --prepend-format='%(filename):%(beg_line):'")
+ cmd)
t nil)
(when register-report
(goto-char data-pos)
(while (re-search-forward "^\\(/[^:]+\\)?:\\([0-9]+\\)?:" nil t)
- (let ((file (match-string 1))
- (line (string-to-number (match-string 2))))
- (delete-region (match-beginning 0) (match-end 0))
- (when file
- (set-text-properties (line-beginning-position) (line-end-position)
- (list 'ledger-source (cons file (save-window-excursion
- (save-excursion
- (find-file file)
- (widen)
- (ledger-goto-line line)
- (point-marker))))))
- (add-text-properties (line-beginning-position) (line-end-position)
- (list 'face 'ledger-font-report-clickable-face))
- (end-of-line)))))
+ (let ((file (match-string 1))
+ (line (string-to-number (match-string 2))))
+ (delete-region (match-beginning 0) (match-end 0))
+ (when file
+ (set-text-properties (line-beginning-position) (line-end-position)
+ (list 'ledger-source (cons file (save-window-excursion
+ (save-excursion
+ (find-file file)
+ (widen)
+ (ledger-goto-line line)
+ (point-marker))))))
+ (add-text-properties (line-beginning-position) (line-end-position)
+ (list 'face 'ledger-font-report-clickable-face))
+ (end-of-line)))))
(goto-char data-pos)))
diff --git a/lisp/ldg-sort.el b/lisp/ldg-sort.el
index a50cd1cc..06efd348 100644
--- a/lisp/ldg-sort.el
+++ b/lisp/ldg-sort.el
@@ -49,7 +49,7 @@
(save-excursion
(goto-char (point-min))
(if (ledger-sort-find-start)
- (delete-region (match-beginning 0) (match-end 0))))
+ (delete-region (match-beginning 0) (match-end 0))))
(beginning-of-line)
(insert "\n; Ledger-mode: Start sort\n\n"))
@@ -58,7 +58,7 @@
(save-excursion
(goto-char (point-min))
(if (ledger-sort-find-end)
- (delete-region (match-beginning 0) (match-end 0))))
+ (delete-region (match-beginning 0) (match-end 0))))
(beginning-of-line)
(insert "\n; Ledger-mode: End sort\n\n"))
@@ -69,44 +69,57 @@
(defun ledger-sort-region (beg end)
"Sort the region from BEG to END in chronological order."
(interactive "r") ;; load beg and end from point and mark
- ;; automagically
+ ;; automagically
(let ((new-beg beg)
- (new-end end))
- (setq inhibit-modification-hooks t)
+ (new-end end)
+ point-delta
+ (bounds (ledger-find-xact-extents (point)))
+ target-xact)
+
+ (setq point-delta (- (point) (car bounds)))
+ (setq target-xact (buffer-substring (car bounds) (cadr bounds)))
+ (setq inhibit-modification-hooks t)
(save-excursion
(save-restriction
- (goto-char beg)
- (ledger-next-record-function) ;; make sure point is at the
- ;; beginning of a xact
- (setq new-beg (point))
- (goto-char end)
- (ledger-next-record-function) ;; make sure end of region is at
- ;; the beginning of next record
- ;; after the region
- (setq new-end (point))
- (narrow-to-region new-beg new-end)
- (goto-char new-beg)
-
- (let ((inhibit-field-text-motion t))
- (sort-subr
- nil
- 'ledger-next-record-function
- 'ledger-end-record-function
- 'ledger-sort-startkey))))
+ (goto-char beg)
+ (ledger-next-record-function) ;; make sure point is at the
+ ;; beginning of a xact
+ (setq new-beg (point))
+ (goto-char end)
+ (ledger-next-record-function) ;; make sure end of region is at
+ ;; the beginning of next record
+ ;; after the region
+ (setq new-end (point))
+ (narrow-to-region new-beg new-end)
+ (goto-char new-beg)
+
+ (let ((inhibit-field-text-motion t))
+ (sort-subr
+ nil
+ 'ledger-next-record-function
+ 'ledger-end-record-function
+ 'ledger-sort-startkey))))
+
+ (goto-char beg)
+ (re-search-forward (regexp-quote target-xact))
+ (goto-char (+ (match-beginning 0) point-delta))
(setq inhibit-modification-hooks nil)))
(defun ledger-sort-buffer ()
"Sort the entire buffer."
(interactive)
- (goto-char (point-min))
- (let ((sort-start (ledger-sort-find-start))
- (sort-end (ledger-sort-find-end)))
+ (let (sort-start
+ sort-end)
+ (save-excursion
+ (goto-char (point-min))
+ (setq sort-start (ledger-sort-find-start)
+ sort-end (ledger-sort-find-end)))
(ledger-sort-region (if sort-start
- sort-start
- (point-min))
- (if sort-end
- sort-end
- (point-max)))))
+ sort-start
+ (point-min))
+ (if sort-end
+ sort-end
+ (point-max)))))
(provide 'ldg-sort)
generated by cgit v1.2.3 (git 2.39.1) at 2025-01-09 20:50:29 +0000