ledger-cli/doc/ledger-mode.texi

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

@setfilename ledger-mode.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.

@copying

Copyright @copyright{} 2013, Craig Earls.  All rights reserved.

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

@itemize

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

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

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

@end itemize

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

@end copying

@dircategory Major Modes
@direntry
* Ledger Mode: (ledger-mode).           Command-Line Accounting
@end direntry

@documentencoding UTF-8

@iftex
@finalout
@end iftex

@titlepage
@title Ledger Mode
@subtitle Emacs Support For Version 3.0 of Ledger
@author Craig Earls
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex

@node Top, Introduction to Ledger-mode, (dir), (dir)
@top Overview

Ledger is a command line accounting tool that provides double-entry
accounting based on a text journal.  It provides no bells or whistles,
and returns the user to the days before user interfaces were even
a 1twinkling in their father's CRT.

Ledger-mode assists you in maintaining input files for Ledger, running
reports and much more...

@end ifnottex

@menu
* Introduction to Ledger-mode::
* The Ledger Buffer::
* The Reconcile Buffer::
* The Report Buffer::
* Scheduling Transactions::
* Customizing Ledger-mode::
* Generating Ledger Regression Tests::
* Embedding Example results in Ledger Documentation::
* Hacking Ledger-mode::
* Concept Index::
* Command & Variable Index::
* Keystroke Index::
@end menu

@node Introduction to Ledger-mode, The Ledger Buffer, Top, Top
@chapter Introduction to Ledger-mode

@menu
* Quick Installation::
* Menus::
* Quick Demo::
@end menu

@node Quick Installation, Menus, Introduction to Ledger-mode, Introduction to Ledger-mode
@section Quick Installation
@cindex installation

The Emacs lisp source for Ledger-mode is included with the source
distribution of Ledger.  It is entirely included in the @file{lisp}
subdirectory. To use Ledger-mode, include the following in your Emacs
initialization file (@file{~/.emacs}, @file{~/.emacs.d/init.el}, or
@file{~/.Aquamacs/Preferences.el}).

@lisp
(autoload 'ledger-mode "ledger-mode" "A major mode for Ledger" t)
(add-to-list 'load-path
             (expand-file-name "/path/to/ledger/source/lisp/"))
(add-to-list 'auto-mode-alist '("\\.ledger$" . ledger-mode))
@end lisp

This sets up Emacs to automatically recognize files that end with
@file{.ledger} and start Ledger-mode.  Nothing else should be required
as long as the ledger command line utility is properly installed.

@node Menus, Quick Demo, Quick Installation, Introduction to Ledger-mode
@section Menus
@cindex menu

The vast majority of Ledger-mode functionality is available from the
Emacs menu system.  The keystrokes are shown in the menu to help you
learn the faster keyboard methods.

@node Quick Demo,  , Menus, Introduction to Ledger-mode
@section Quick Demo
@cindex demo

Load the demo file @file{demo.ledger} from the Ledger source
@file{test/input} directory.  The ledger will be loaded and font
highlighted.  At this point you could manually edit transactions and run
Ledger from a convenient command line.

@menu
* Quick Add::
* Reconciliation::
* Reports::
* Narrowing::
@end menu

@node Quick Add, Reconciliation, Quick Demo, Quick Demo
@subsection Quick Add
@kindex C-c TAB
@kindex C-c C-a

As simple as the Ledger transaction format is, it can still be daunting
to add many transactions manually.  Ledger provides two way to add
transactions with minimal typing. Both are based on the idea that most
transactions are repetitions of earlier transactions.

In the @file{demo.ledger} buffer enter a date using the correct
format. Then type the first few characters of another payee in the
@file{demo.ledger} buffer.  Type @kbd{C-c TAB}.  Ledger-mode will
search for a Payee that has the same beginning and copy the rest of the
transaction to you new entry.

Additionally you can use the ledger @command{xact} command, by either
typing @kbd{C-c C-a} or using @samp{Add Transaction} menu entry. Then
typing a close match to the payee. Ledger-mode will call @command{ledger
xact} with the data you enter and place the transaction in the proper
chronological place in the ledger.

If you need to add a lot of transactions that are not near your current
date you can set the current year and month so that using @samp{Add
Transaction} will prompt you with a more convenient month and year.  To
set the month type @kbd{C-c RET} and enter the month you want.  @kbd{C-c
C-y} will prompt you for the year.  These settings only effect the
@samp{Add Transaction} command.

@node Reconciliation, Reports, Quick Add, Quick Demo
@subsection Reconciliation
@kindex C-c C-r
@kindex SPC
@kindex C-c C-c
@kindex q

The biggest task of maintaining a ledger is ensuring that it matches the
outside world.  This process is called reconciliation (@pxref{Basics of
Reconciliation}) and can be quite onerous.  Ledger-mode attempts to make
it as painless as possible.

In the @file{demo.ledger} buffer type @kbd{C-c C-r}.  If cursor is on an
account, Ledger-mode will propose this account, or in the Minibuffer,
will prompt for an account to reconcile.  Hit @kbd{RET} if you are happy
with proposed account, or enter @samp{Checking} as example.
Emacs will then prompt for a target value.  The target value is the
amount you want the cleared transactions in the buffer to total.
Normally this would be the ending value from your bank statement, or the
latest value in your on-line transaction summary.  Enter @samp{1710}.
Note that Ledger-mode assumes your are using @samp{$} (USD) as your
default commodity, this can be easily changed in the customization
variables. @xref{Ledger-mode Customization}.

You now see a list of uncleared transactions in a buffer below the
@file{demo.ledger} buffer.  Touching the @kbd{SPC} bar will mark
a transaction as pending and display the current cleared (and pending)
balance, along with the difference remaining to meet your target. Clear
the first three transactions, and you will see the difference to target
reach @samp{$0}.  End the reconciliation by typing @kbd{C-c C-c}.  This
saves the @file{demo.ledger} buffer and marks the transactions and
finally cleared.  Type @kbd{q} to close out the reconciliation buffer.

@node Reports, Narrowing, Reconciliation, Quick Demo
@subsection Reports
@kindex C-c C-o C-r
@kindex C-c C-c

The real power of Ledger is in it reporting capabilities.  Reports can
be run and displayed in a separate Emacs buffer.  In the
@file{demo.ledger} buffer, type @kbd{C-c C-o C-r}.  In the Minibuffer
Emacs will prompt for a report name.  There are a few built-in reports,
and you can add any report you need @xref{Adding and Editing Reports}.

In the Minibuffer type @samp{account}.  When prompted for an account
type @samp{checking}.  In a buffer named @file{*Ledger Report*}, you
will see a Ledger register report. You can move around the buffer, with
the point on a transaction, type @kbd{RET}.  Ledger-mode will take you
directly to that transaction in the @file{demo.ledger} buffer.

Another built-in report is the balance report.  In the
@file{demo.ledger} buffer, type @kbd{C-c C-o C-r}.  When prompted for
a report to run, type @samp{bal}, and a balance report of all accounts
will be shown.

@node Narrowing,  , Reports, Quick Demo
@subsection Narrowing
@kindex C-c C-f
@kindex C-c C-g

A ledger file can get very large.  It can be helpful to collapse the
buffer to display only the transactions you are interested in.
Ledger-mode copies the @command{occur} mode functionality.  Typing
@kbd{C-c C-f} and entering any regex in the Minibuffer will show only
transactions that match the regex.  The regex can be on any field, or
amount.  Use @kbd{C-c C-g} after editing transactions to re-apply the
current regex.  Cancel the narrowing by typing @kbd{C-c C-f} again.

@node The Ledger Buffer, The Reconcile Buffer, Introduction to Ledger-mode, Top
@chapter The Ledger Buffer

@menu
* Adding Transactions::
* Copying Transactions::
* Editing Amounts::
* Marking Transactions::
* Formatting Transactions::
* Deleting Transactions::
* Sorting Transactions::
* Narrowing Transactions::
@end menu


@node Adding Transactions, Copying Transactions, The Ledger Buffer, The Ledger Buffer
@section Adding Transactions
@findex ledger-post-auto-adjust-amounts
@findex ledger-post-amount-alignment-column
@kindex TAB
@cindex transaction, adding

Beyond the two ways of quickly adding transactions (@pxref{Quick Add})
Ledger-mode assists you by providing robust @kbd{TAB} completion for
payees and accounts.  Ledger-mode will scan the existing buffer for
payees and accounts. Included files are not currently included in the
completion scan. Repeatedly hitting @kbd{TAB} will cycle through the
possible completions.

Ledger-mode can also help you keep your amounts aligned.  Setting
@option{ledger-post-auto-adjust-amounts} to true tells Ledger-mode to
automatically place any amounts such that their last digit is aligned to
the column specified by @option{ledger-post-amount-alignment-column},
which defaults to @samp{52}. @xref{Ledger Post Customization Group}.

@menu
* Setting a Transactions Effective Date::
* Quick Balance Display::
@end menu

@node Setting a Transactions Effective Date, Quick Balance Display, Adding Transactions, Adding Transactions
@subsection Setting a Transactions Effective Date
@kindex C-c C-t
@cindex effective date

Ledger provides for adding information to a transaction that add details
to the dates.  For example, you can specify when the transaction was
entered, when the transaction was cleared, or when individual postings
were cleared.
Ledger-mode refers to these additional dates as @emph{effective} dates.
To set the effective date of a transaction, place the point in the first
line of a transaction and type @kbd{C-c C-t}.  The effective date will
be added to the transaction.  To set the effective date for an
individual posting, place point in the posting and type @kbd{C-c C-t} and
the effective date for that posting will be added at the end of the
posting.

@node Quick Balance Display,  , Setting a Transactions Effective Date, Adding Transactions
@subsection Quick Balance Display
@kindex C-c C-p
@cindex balance

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,
and type @kbd{C-c C-p}.  The Minibuffer will ask you to verify the name
of the account you want, if it is already correct hit @kbd{RET}, then
the balance of the account will be displayed in the Minibuffer.

@node Copying Transactions, Editing Amounts, Adding Transactions, The Ledger Buffer
@section Copying Transactions
@kindex C-c C-k
@cindex transaction, copying

An easy way to copy a transaction is to type @kbd{C-c C-k} or menu entry
@samp{Copy Trans at Point}. You will be prompted the new date for the
copied transaction, and after having confirmed with @kbd{RET}, new
transaction will be inserted at @emph{date} position in buffer.

@node Editing Amounts, Marking Transactions, Copying Transactions, The Ledger Buffer
@section Editing Amounts
@kindex C-c C-b
@kindex y
@cindex Calc
@cindex GNU Emacs Calculator
@cindex transaction, editing amounts

GNU Emacs Calculator, aka @samp{Calc}, is a very powerful Reverse Polish
Notation calculator built into all recent version of Emacs.  Ledger-mode
makes it easy to calculate values for amount by integrating
@command{Calc}. With the point anywhere in the same line as a posting,
typing @kbd{C-c C-b} will bring up the @file{Calc} buffer, and push the
current amount for the posting onto the top of the @command{Calc} stack.
Perform any calculations you need to arrive at the final value, then
type @kbd{y} to yank the value at the top of stack back into the ledger
buffer.  Note: @command{Calc} does not directly support commas as
decimal separators.  Ledger-mode will translate values from
decimal-comma format to decimal-period format for use in @command{Calc},
but it cannot intercept the value being yanked form the @command{Calc}
stack, so decimal-comma users will have to manually replace the period
with a comma.

@node Marking Transactions, Formatting Transactions, Editing Amounts, The Ledger Buffer
@section Marking Transactions
@cindex transaction, marking
@cindex uncleared
@cindex pending
@cindex cleared

Ledger considers transaction or posting to be in one of three states:
uncleared, cleared, and pending.  For calculation Ledger ignores these
states unless specifically instructed to use them.  Ledger-mode assigns
some additional meaning to the states:

@itemize

@item Uncleared.
No state.  This is equivalent to sticking a check in the mail.  It has
been obligated, but not been cashed by the recipient.  It could also
apply to credit/debit card transactions that have not been cleared into
your account balance.  You bank may call these transactions @emph{pending},
but Ledger-mode uses a slightly different meaning.

@item Pending.
Ledger-mode's reconciliation function see pending transactions as an
intermediate step in reconciling an account.  When doing
a reconciliation (@pxref{Reconciliation}), marking a transaction as
pending means that you have seen the transaction finally recorded by the
recipient, but you have not completely reconciled the account.

@item Cleared.
The transaction has been completely recognized by all parties to the
transaction.

@end itemize

@kindex C-c C-c
@kindex C-c C-e

Typing @kbd{C-c C-c}, depending where is the point, will clear the
complete transaction, or an individual posting. This places an asterisk
@samp{*} prior to the payee for the complete transaction, or prior to
the account for an individual posting. When point is inside
a transaction, specifically on an individual posting, you can still
clear the complete transaction by typing @kbd{C-c C-e}.

@node Formatting Transactions, Deleting Transactions, Marking Transactions, The Ledger Buffer
@section Formatting Transactions
@cindex transaction, formatting

When editing a transaction, liberal use of the @kbd{TAB} key can keep
the transaction well formatted.  If you want to have Ledger-mode cleanup
the formatting of a transaction you can use @samp{Align Transaction} or
@samp{Align Region} from the menu bar.

The menu item @samp{Clean-up Buffer} sorts all transactions in the buffer
by date, removes extraneous empty lines and aligns every transaction.


@node Deleting Transactions, Sorting Transactions, Formatting Transactions, The Ledger Buffer
@section Deleting Transactions
@kindex C-c C-d
@cindex transaction, deleting

Along with normal buffer editing methods to delete text, Ledger-mode
provides an easy way to delete the transaction under point: @kbd{C-c
C-d}.  The advantage to using this method is that the complete
transaction operation is in the undo buffer.

@node Sorting Transactions, Narrowing Transactions, Deleting Transactions, The Ledger Buffer
@section Sorting Transactions
@kindex C-c C-s
@cindex transaction, sorting

As you operating on the Ledger files, they may become disorganized.  For
the most part, Ledger doesn't care, but our human brains prefer a bit of
order.  Sorting the transactions in a buffer into chronological order
can help bring order to chaos.  Either using @samp{Sort Region} menu
entry or typing @kbd{C-c C-s} will sort all of the transactions in
a region by date.  Ledger-mode isn't particularly smart about handling
dates and it simply sorts the transactions using the string at the
beginning of the transaction.  So, you should use the preferred ISO 8601
standard date format @samp{YYYY/MM/DD} which easily sorts.

Note, there is a menu entry @samp{Sort Buffer} to sort the entire
buffer.  Special transactions like automated transaction, will be moved
in the sorting process and may not function correctly afterwards.  For
this reason there is no key sequence.

You can limit the allowed sort region by using embedded Ledger-mode
markup within your ledger.  For example:

@example
<<< information to not sort >>>

; Ledger-mode: Start sort

<<< transactions to sort >>>

; Ledger-mode: End sort

<<< information to not sort >>>
@end example

You can use menu entries @samp{Mark Sort Beginning} to insert start and
@samp{Mark Sort End} to insert end markers.  These functions will
automatically delete old markers and put new new marker at point.

@node Narrowing Transactions,  , Sorting Transactions, The Ledger Buffer
@section Narrowing Transactions
@kindex C-c C-f
@kindex C-c C-g
@cindex transaction, narrowing
@cindex transaction, display filtering

Often you will want to run Ledger register reports just to look at
a specific set of transactions.  If you don't need the running total
calculation handled by Ledger, Ledger-mode provides a rapid way of
narrowing what is displayed in the buffer in a way that is simpler than
the Ledger register command.

Based on the Emacs Occur mode by Alexey Veretennikov, Ledger-occur hides
all transactions that do @emph{not} meet a specific regular expression.
The regular expression can match on any part of the transaction.  If you
want to find all transactions whose amount ends in @samp{.37}, you can
do that (I don't know why, but hey, whatever ever floats you aerostat).

Using @kbd{C-c C-f} or the @samp{Narrow to Regex} menu entry, enter a
regular expression in the Minibuffer.  Ledger-mode will hide all other
transactions.  For details of the regular expression syntax, see your
Emacs documentation.  A few examples using the @file{demo.ledger} are
given here:

@table @samp

@item Groceries
Show only transactions that have a posting to the @samp{Groceries}
account.

@item ^2011/01
Show only transactions occurring in January of 2011.

@item ^2011/.*/25
Show only transactions occurring on the 25th of the month in 2011.

@item auto
Show only transactions with payees or accounts or comments containing.
@samp{auto}

@item harley$
Show only transactions with any line ending with @samp{harley}.

@end table

To show back all transactions simply invoke @samp{Narrow to Regex} or
@kbd{C-c C-f} again.

If you've edited some transactions after narrowing such that they would
no longer match the regular expression, you can refresh the narrowed
view using @kbd{C-c C-g}.

@node The Reconcile Buffer, The Report Buffer, The Ledger Buffer, Top
@chapter The Reconcile Buffer

@menu
* Basics of Reconciliation::
* Starting a Reconciliation::
* Mark Transactions Pending::
* Edit Transactions During Reconciliation::
* Finalize Reconciliation::
* Adding and Deleting Transactions during Reconciliation::
* Changing Reconciliation Account::
* Changing Reconciliation Target::
@end menu

@node Basics of Reconciliation, Starting a Reconciliation, The Reconcile Buffer, The Reconcile Buffer
@section Basics of Reconciliation
@cindex reconciliation, basics

Even in this relatively modern era, financial transactions do not happen
instantaneously, unless you are paying cash.  When you swipe your debit
card the money may take several days to actually come out of your
account, or a check may take several days to @emph{clear}.  That is the
root of the difference between @emph{obligating} funds and
@emph{expending} funds.  Obligation says you have agreed to pay it, the
expenditure doesn't happen until the money actually leaves your
account. Or in the case of receiving payment, you have an account
receivable until the money has actually made it to you.

After an account has been reconciled you have verified that all the
transactions in that account have been correctly recorded and all
parties agree.

@node Starting a Reconciliation, Mark Transactions Pending, Basics of Reconciliation, The Reconcile Buffer
@section Starting a Reconciliation
@findex ledger-reconcile-default-commodity
@kindex C-c C-r
@cindex reconciliation, starting

To start reconciling an account you must have a target, both the
transactions that you know about and the transactions the bank knows
about.  You can get this from a monthly statement, or from checking your
on-line transaction history.  It also helps immensely to know the final
cleared balance you are aiming for.

Use menu @samp{Reconcile Account} or keyboard shortcut @kbd{C-c C-r} to
start reconciliation.

If cursor is on an account, Ledger-mode will propose this account, or in
the Minibuffer, will prompt for an account to reconcile. Hit @kbd{RET}
if you are happy with proposed account, or enter @samp{Checking} as
example. Ledger-mode is not particular about what you enter for the
account.  You can leave it blank and @file{*Reconcile*} buffer will show
you @emph{all} uncleared transactions.

After you enter the account enter the target amount. It is helpful to
enter an amount with a commodity. You can also leave it blank, you will
be able to clear transactions but not benefit from balance calculations.
It assumes initially that you are using @samp{$} (USD) as your default
commodity.  If you are working in a different currency you can change
the default in variable @option{ledger-reconcile-default-commodity} to
whatever you need.  If you work in multiple commodities simply enter the
commoditized amount (for example @samp{340 VSDX}, for 340 shares of
VSDX).

Ledger-mode reconcile cannot currently reconcile accounts that have
multiple commodities, such as brokerage accounts. You may use
reconciliation mode to clear transactions, but balance calculations will
not display the complete list of commodities.

@node Mark Transactions Pending, Edit Transactions During Reconciliation, Starting a Reconciliation, The Reconcile Buffer
@section Mark Transactions Pending
@kindex SPC
@cindex reconciliation, transaction marking

The @file{*Reconcile*} buffer will show all the uncleared transactions
that meet the criteria set in the regex.  By default uncleared
transactions are shown in red.  When you have verified that
a transaction has been correctly and completely recorded by the opposing
party, mark the transaction as pending using the @kbd{SPC} bar.
Continue this process until you agree with the opposing party and the
difference from your target is zero.

@node Edit Transactions During Reconciliation, Finalize Reconciliation, Mark Transactions Pending, The Reconcile Buffer
@section Edit Transactions during Reconciliation
@kindex RET
@kindex C-c C-c
@cindex reconciliation, transaction editing

If you find errors during reconciliation.  You can visit the transaction
under point in the @file{*Reconcile*} buffer by hitting the @kbd{RET}
key.  This will take you to the transaction in the Ledger buffer.  When
you have finished editing the transaction, saving the buffer will
automatically return you to the @file{*Reconcile*} buffer and you can
mark the transaction if appropriate.

@node Finalize Reconciliation, Adding and Deleting Transactions during Reconciliation, Edit Transactions During Reconciliation, The Reconcile Buffer
@section Finalize Reconciliation
@cindex reconciliation, finalizing
@kindex C-c C-c
@kindex q

Once you have marked all transactions as pending and the cleared balance
is correct.  Finish the reconciliation by typing @kbd{C-c C-c}.  This
marks all pending transactions as cleared and saves the ledger buffer.

Type @kbd{q} to close out the reconciliation buffer. If variable
@var{ledger-reconcile-finish-force-quit} is set, the reconciliation
buffer will be killed automatically after @kbd{C-c C-c}.

@node Adding and Deleting Transactions during Reconciliation, Changing Reconciliation Account, Finalize Reconciliation, The Reconcile Buffer
@section Adding and Deleting Transactions during Reconciliation
@kindex a
@kindex d
@cindex reconciliation, transaction adding and deleting

While reconciling, you may find new transactions that need to be entered
into your ledger.  Simply type @kbd{a} to bring up the quick add for the
ledger buffer.

Typing @kbd{d} will delete the transaction under point in the
@file{*Reconcile*} buffer from the ledger buffer.

@node Changing Reconciliation Account, Changing Reconciliation Target, Adding and Deleting Transactions during Reconciliation, The Reconcile Buffer
@section Changing Reconciliation Account
@kindex g
@cindex reconciliation, account changing

You can conveniently switch the account being reconciled by typing
@kbd{g}, and entering a new account to reconcile.  This simply restarts
the reconcile process. Any transactions that were marked @emph{pending} in
the ledger buffer are left in that state when the account is switched.

@node Changing Reconciliation Target,  , Changing Reconciliation Account, The Reconcile Buffer
@section Changing Reconciliation Target
@kindex t
@cindex reconciliation, target changing

If for some reason during reconciliation your target amount changes,
type @kbd{t} and enter the new target value.

@node The Report Buffer, Scheduling Transactions, The Reconcile Buffer, Top
@chapter The Report Buffer

@menu
* Running Basic Reports::
* Adding and Editing Reports::
* Reversing Report Order::
@end menu

@node Running Basic Reports, Adding and Editing Reports, The Report Buffer, The Report Buffer
@section Running Reports
@kindex C-c C-o C-r
@kindex C-c C-o C-g
@kindex C-c C-o C-a
@cindex report, running

The real power behind Ledger is in its amazing reporting capability.
Ledger-mode provides easy facility to run reports directly from Emacs.
It has four reports built-in and facilities for adding custom reports.

Typing @kbd{C-c C-o C-r} or using menu @samp{Run Report} prompts
for the name of a saved report.  The built-in reports are:

@table @var

@item bal
Produce a balance reports of all accounts.

@item reg
Produce a register report of all transactions.

@item payee
Prompt for a payee, then produce a register report of all transactions
involving that payee.

@item account
Prompt for an account, then produce a register report of all
transactions involving that account.

@end table

While viewing reports you can easily switch back and forth between the
ledger buffer and the @file{*Ledger Report*} buffer.  In @file{*Ledger
Report*} buffer, typing @kbd{RET} will take you to that transaction in
the ledger buffer.  While in the ledger buffer @kbd{C-c C-o C-g} returns
you to the @file{*Ledger Report*} buffer.

By default Ledger-mode will refresh the report buffer when the ledger
buffer is saved.  If you want to rerun the report at another time
@kbd{C-c C-o C-a}.  This is useful if you have other programs altering
your ledger file outside of Emacs.


@node Adding and Editing Reports, Reversing Report Order, Running Basic Reports, The Report Buffer
@section Adding and Editing Reports
@findex ledger-reports
@kindex M-1 C-c C-o C-r
@kindex S
@kindex C-c C-o C-e
@kindex e
@cindex report, adding and editing

@menu
* Expansion Formats::
* Make Report Transactions Active::
@end menu

If you type a report name that Ledger-mode doesn't recognize it will
prompt you for a ledger command line to run.  That command is
automatically saved with the name given and you can re-run it at any
time.

There are two ways to edit the command line for a report. The first is
to provide a prefix argument to the run-report command.  For example,
type @kbd{M-1 C-c C-o C-r}. This will prompt you for the report name,
then present the report command line to be edited.  When you hit
@kbd{RET}, the report will be run, but it will not be permanently saved.
If you want to save it, type @kbd{S} in the @file{*Ledger Report*}
buffer you will have the option to give it a new name, or overwrite the
old report.

Deleting reports is accomplished by typing @kbd{C-c C-o C-e} or using
@samp{Edit Report} menu in the ledger buffer, or typing @kbd{e} in the
@file{*Ledger Report*} buffer.  This takes you to the Emacs
customization window for the Ledger Reports variables.  Use the widgets
to delete the report you want removed.

Typing @kbd{C-c C-o C-s} will prompt for a name and save the current
report.

@node Expansion Formats, Make Report Transactions Active, Adding and Editing Reports, Adding and Editing Reports
@subsection Expansion Formats
@cindex report, custom variable

It is sometimes convenient to leave room to customize a report without
saving the command line every time.  For example running a register
report for a specific account entered at runtime by the user.  The
built-in report @var{account} does exactly that, using a variable
expansion to prompt the user for the account to use.  There are four
variables that can be expanded to run a report:

@table @var

@item ledger-file
Returns the file to be operated on.

@item payee
Prompts for a payee.

@item account
Prompt for an account.

@item tagname
Prompt for a meta-data tag name.

@item tagvalue
Prompt for a meta-data tag value.

@end table

You can use these expansion values in your ledger report commands.  For
example, if you wanted to specify a register report the displayed
transactions from a user-determined account with a particular meta-data
tag value, you specify the following command line:

@example
ledger -f %(ledger-file) reg %(account) \
  --limit \"tag('my-tag') =~/%(value)/\"
@end example

Note how the double-quotes are escaped with back-slashes.

@node Make Report Transactions Active,  , Expansion Formats, Adding and Editing Reports
@subsection Make Report Transactions Active
@cindex report, custom command

In a large register report it is convenient to be able to jump to the
source transaction.  Ledger-mode will automatically include source
information in every register file that doesn't contain
a @option{--subtotal} option. It does this by adding
@option{--prepend-format='%(filename):%(beg_line):'} to the register
report command-line you specify.  You should never have to see this, but
if there is an error in your ledger output this additional information
may not get stripped out of the visible report.

@node Reversing Report Order,  , Adding and Editing Reports, The Report Buffer
@section Reversing Report Order
@kindex R
@cindex report, order reversing

Often, banks show their on-line transaction histories with the most
recent transaction at the top.  Ledger itself cannot do a sensible
ledger report in reverse chronological order, if you sort on reverse
date the calculation will also run in the opposite direction.  If you
want to compare a ledger register report to a bank report with the most
recent transactions at the top, type @kbd{R} in the @file{*Ledger
Report*} buffer and it will reverse the order of the transactions and
maintain the proper mathematical sense.

@node Scheduling Transactions, Customizing Ledger-mode, The Report Buffer, Top
@chapter Scheduling Transactions

The Ledger program provides for automating transactions but these
transaction aren't @emph{real}, they only exist inside a ledger session and
are not reflected in the actual data file.  Many transactions are very
repetitive, but may vary slightly in the date they occur on, or the
amount.  Some transactions are weekly, monthly, quarterly or annually.
Ledger mode provides a way to schedule upcoming transaction with a
flexible scheduler that allows you to specify the transactions in a
separate ledger file and calculate the upcoming occurrences of those
transactions.  You can then copy the transactions into your live data
file.

@menu
* Specifying Upcoming Transactions::
@end menu

@node Specifying Upcoming Transactions,  , Scheduling Transactions, Scheduling Transactions
@section Specifying Upcoming Transactions

The format for specifying transactions is identical to Ledger's file
format with the exception of the date field.  The data field is modified
by surrounding it with brackets and using wild cards and special
characters to specify when the transactions should appear.

@menu
* Transactions that occur on specific dates::
* Transactions that occur on specific days::
@end menu

@node Transactions that occur on specific dates, Transactions that occur on specific days, Specifying Upcoming Transactions, Specifying Upcoming Transactions
@subsection Transactions that occur on specific dates

Many times you will enter repetitive transactions that occur on the same
day of the month each month.  These can be specified using a wild card
in the year and month with a fixed date in the day.  The following entry
specifies a transaction that occurs on the first and fifteenth of every
month in every year.
@example
[*/*/1,15] Paycheck
    Income:Job       $1000.00
    Assets:Checking
@end example

Some transactions do not occur every month.  Comma separated lists of
the months, or @samp{E} for even, or @samp{O} for odd number months can
also be specified.  The following entry specifies a bi-monthly
exterminator bill that occurs in the even months:
@example
[*/E/01]  Exterminator
    Expenses:Home   $100.00
    Assets:Checking
@end example

@node Transactions that occur on specific days,  , Transactions that occur on specific dates, Specifying Upcoming Transactions
@subsection Transactions that occur on specific days

Some transactions occur every relative to the day of the week rather
than the date of the month.  For example, many people are paid every two
weeks without regard to the day of the month.  Other events may occur on
specific days regardless of the date.  For example the following
transactions creates a transaction every other Thursday:

@example
[2014/11/27+2Th]  Paycheck
    Income:Job       $1000.00
    Assets:Checking
@end example

It is necessary to specify a starting date in order for this type of
recurrence relation to be specified.  The day names are two character
codes that default to Mo, Tu, We, Th, Fr, Sa, Su, for Monday, Tuesday,
Wednesday, Thursday, Friday, Saturday, Sunday respectively.  You can
change the codes to something more convenient for your locale by
customizing the ledger @option{ledger-schedule-week-days}. They must be two
characters long.



@node Customizing Ledger-mode, Generating Ledger Regression Tests, Scheduling Transactions, Top
@chapter Customizing Ledger-mode

@menu
* Ledger-mode Customization::
* Customization Variables::
@end menu

@node Ledger-mode Customization, Customization Variables, Customizing Ledger-mode, Customizing Ledger-mode
@section Ledger-mode Customization

Ledger-mode has several options available for configuration.  All
options can be configured through the Emacs customization menus, or
specified in your Emacs initialization file.  The complete list of
options is shown below. To change the option using the Emacs
customization menu, simply chose customize in the Options menu and look
for Ledger under the data options.  Alternately you can choose
@samp{Customize Specific Group} and enter @samp{Ledger} as the group.

@node Customization Variables,  , Ledger-mode Customization, Customizing Ledger-mode
@section Customization Variables

@menu
* Ledger Customization Group::
* Ledger Reconcile Customization Group::
* Ledger Report Customization Group::
* Ledger Faces Customization Group::
* Ledger Post Customization Group::
* Ledger Exec Customization Group::
* Ledger Test Customization Group::
* Ledger Texi Customization Group::
@end menu

@node Ledger Customization Group, Ledger Reconcile Customization Group, Customization Variables, Customization Variables
@subsection Ledger Customization Group
@cindex customization, ledger-mode

@ftable @option

@item ledger-occur-use-face-shown
If non-nil, use a custom face for transactions shown in
@option{ledger-occur} mode using @option{ledger-occur-xact-face}.

@item ledger-clear-whole-transactions
If non-nil, clear whole transactions, not individual postings.

@item ledger-highlight-xact-under-point
If non-nil, highlight transaction under point using
@option{ledger-font-highlight-face}.

@end ftable

@node Ledger Reconcile Customization Group, Ledger Report Customization Group, Ledger Customization Group, Customization Variables
@subsection Ledger Reconcile Customization Group
@cindex customization, reconcile

@ftable @option

@item ledger-recon-buffer-name
Name to use for reconciliation buffer. Defaults to @file{*Reconcile*}.

@item ledger-narrow-on-reconcile
If t, limit transactions shown in main buffer to those matching
the reconcile regex.

@item ledger-buffer-tracks-reconcile-buffer
If t, then when the cursor is moved to a new transaction in the
@file{*Reconcile*} buffer. Then that transaction will be shown in its
source buffer.

@item ledger-reconcile-force-window-bottom
If t, make the @file{*Reconcile*} window appear along the bottom
of the register window and resize.

@item ledger-reconcile-toggle-to-pending
If t, then toggle between uncleared and pending @samp{!}. If
false toggle between uncleared and cleared @samp{*}.

@item ledger-reconcile-default-date-format
Date format for the reconcile buffer. Defaults to
@option{ledger-default-date-format}.

@item ledger-reconcile-target-prompt-string
Prompt for recon target. Defaults to "Target amount for reconciliation ".

@item ledger-reconcile-buffer-header
Header string for the reconcile buffer. If non-nil, the name of the
account being reconciled will be substituted into the '%s'.  If nil, no
header will be displayed.  Defaults to "Reconciling account %s\n\n".

@item ledger-reconcile-buffer-line-format
Format string for the ledger reconcile posting format.  Available fields
are date, status, code, payee, account, amount.  The format for each
field is %WIDTH(FIELD), WIDTH can be preceded by a minus sign which mean
to left justify and pad the field.  WIDTH is the minimum number of
characters to display; if string is longer, it is not truncated unless
@option{ledger-reconcile-buffer-payee-max-chars} or
@option{ledger-reconcile-buffer-account-max-chars} is defined.  Defaults to
"%(date)s %-4(code)s %-50(payee)s %-30(account)s %15(amount)s\n"

@item ledger-reconcile-buffer-payee-max-chars
If positive, truncate payee name right side to max number of characters.

@item ledger-reconcile-buffer-account-max-chars
If positive, truncate account name left side to max number of characters.

@item ledger-reconcile-sort-key
Key for sorting reconcile buffer. Possible values are '(date)',
'(amount)', '(payee)' or '(0)' for no sorting, i.e. using
ledger file order. Defaults to '(0)'.

@item ledger-reconcile-insert-effective-date nil
If t, prompt for effective date when clearing transactions during
reconciliation.

@item ledger-reconcile-finish-force-quit nil
If t, will force closing reconcile window after @kbd{C-c C-c}.

@end ftable

@node Ledger Report Customization Group, Ledger Faces Customization Group, Ledger Reconcile Customization Group, Customization Variables
@subsection Ledger Report Customization Group
@cindex customization, report

@ftable @option

@item ledger-reports
Definition of reports to run.

@item ledger-report-format-specifiers
An alist mapping ledger report format specifiers to implementing
functions.

@end ftable

@node Ledger Faces Customization Group, Ledger Post Customization Group, Ledger Report Customization Group, Customization Variables
@subsection Ledger Faces Customization Group
@cindex customization, faces

Ledger Faces: Ledger-mode highlighting

@ftable @option

@item ledger-font-uncleared-face
Default face for Ledger.

@item ledger-font-cleared-face
Default face for cleared @samp{*} transactions.

@item ledger-font-highlight-face
Default face for transaction under point.

@item ledger-font-pending-face
Default face for pending @samp{!} transactions.

@item ledger-font-other-face
Default face for other transactions.

@item ledger-font-posting-account-face
Face for Ledger accounts.

@item ledger-font-posting-account-cleared-face
Face for cleared Ledger accounts.

@item ledger-font-posting-account-pending-face
Face for Ledger pending accounts.

@item ledger-font-posting-amount-face
Face for Ledger amounts.

@item ledger-occur-narrowed-face
Default face for Ledger occur mode hidden transactions.

@item ledger-occur-xact-face
Default face for Ledger occur mode shown transactions.

@item ledger-font-comment-face
Face for Ledger comments.

@item ledger-font-reconciler-uncleared-face
Default face for uncleared transactions in the @file{*Reconcile*} buffer.

@item ledger-font-reconciler-cleared-face
Default face for cleared @samp{*} transactions in the @file{*Reconcile*}
buffer.

@item ledger-font-reconciler-pending-face
Default face for pending @samp{!} transactions in the @file{*Reconcile*}
buffer.

@item ledger-font-report-clickable-face
FIXME

@end ftable

@node Ledger Post Customization Group, Ledger Exec Customization Group, Ledger Faces Customization Group, Customization Variables
@subsection Ledger Post Customization Group
@cindex customization, post

Ledger Post:

@ftable @option

@item ledger-post-auto-adjust-amounts
If non-nil, then automatically align amounts to column specified in
@option{ledger-post-amount-alignment-column}.

@item ledger-post-amount-alignment-column
The column Ledger-mode uses to align amounts.

@item ledger-default-acct-transaction-indent
Default indentation for account transactions in an entry.

@item ledger-post-use-completion-engine
Which completion engine to use: @var{iswitchb}, @var{ido}, or built-in.

@item ledger-post-use-ido

@end ftable

@node Ledger Exec Customization Group, Ledger Test Customization Group, Ledger Post Customization Group, Customization Variables
@subsection Ledger Exec Customization Group
@cindex customization, executable

Ledger Exec: Interface to the Ledger command-line accounting program.

@ftable @option

@item ledger-binary-path
Path to the ledger executable.

@item ledger-init-file-name
Location of the ledger initialization file. nil if you don't have one.

@end ftable

@node Ledger Test Customization Group, Ledger Texi Customization Group, Ledger Exec Customization Group, Customization Variables
@subsection Ledger Test Customization Group
@cindex customization, test

@ftable @option

@item ledger-source-directory
Directory where the Ledger sources are located.

@item ledger-test-binary
Directory where the debug binary.

@end ftable

@node Ledger Texi Customization Group,  , Ledger Test Customization Group, Customization Variables
@subsection Ledger Texi Customization Group
@cindex customization, texi

@ftable @option

@item ledger-texi-sample-doc-path
Location for sample data to be used in texi tests, defaults to
@file{~/ledger/doc/sample.dat}.

@item ledger-texi-normalization-args
texi normalization for producing ledger output, defaults to
@samp{--args-only --columns 80}.

@end ftable

@node Generating Ledger Regression Tests, Embedding Example results in Ledger Documentation, Customizing Ledger-mode, Top
@chapter Generating Ledger Regression Tests

Work in Progress.

@node Embedding Example results in Ledger Documentation, Hacking Ledger-mode, Generating Ledger Regression Tests, Top
@chapter Embedding Example results in Ledger Documentation

Work in Progress.

@node Hacking Ledger-mode, Concept Index, Embedding Example results in Ledger Documentation, Top
@chapter Hacking Ledger-mode

Work in Progress.

@node Concept Index, Command & Variable Index, Hacking Ledger-mode, Top
@unnumbered Concept Index

@printindex cp

@node Command & Variable Index, Keystroke Index, Concept Index, Top
@unnumbered Command & Variable Index

@printindex fn

@node Keystroke Index,  , Command & Variable Index, Top
@unnumbered Keystroke Index

@printindex ky

@bye

@c Local Variables:
@c mode: texinfo
@c TeX-master: t
@c End: