path: root/doc/L3-Syntax.texi

@c -*-texinfo-*-
@node Command-line Syntax, Basic Reporting Commands, File Format, Top
@chapter Command-line Syntax


@menu
* Cookbook::                    
* Quick Reference::             
* Commands::                    
* Options::                     
* Period Expressions::          
@end menu

@node Cookbook, Quick Reference, Command-line Syntax, Command-line Syntax
@section Cookbook

@subsection Invoking Ledger

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

@example
= /^Income:Taxable/ 
  (Liabilities:Tithe Owed)    -0.1
= /Noah/ 
  (Liabilities:Tithe Owed)    -0.1
= /Jonah/ 
  (Liabilities:Tithe Owed)    -0.1
= /Tithe/
  (Liabilities:Tithe Owed)    -1.0
@end example

@node Quick Reference, Commands, Cookbook, Command-line Syntax
@section Quick Reference

This chapter describes LEDGER's features and serves as a quick
reference. You may wish to survey this to get an overview before diving
in to the @ref{Ledger Tutorial} and more detailed examples that follow.

LEDGER has a very simple command-line interface, named---enticingly
enough---@command{ledger}.  It supports a few reporting commands, and
a large number of options for refining the output from those commands.
The basic syntax of any ledger command is:

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

Command options must always precede the command word.  After the
command word there may appear any number of arguments.  For most
commands, these arguments are regular expressions that cause the
output to relate only to postings matching those regular
expressions.  For the @command{transaction} command, the arguments have a
special meaning, described below.

The regular expressions arguments always match the account name that a
posting refers to.  To match on the payee of the transaction instead,
precede the regular expression with @samp{--}.  For example, the
following balance command reports account totals for rent, food and
movies, but only those whose payee matches Freddie:

@example
ledger bal rent food movies -- freddie
@end example

There are many, many command options available with the
@command{ledger} command, and it takes a while to master them.
However, none of them are required to use the basic reporting
commands.


@node Commands, Options, Quick Reference, Command-line Syntax
@section Commands

@subsection balance

The @command{balance} command reports the current balance of all
accounts.  It accepts a list of optional regexps, which confine the
balance report to the matching accounts.  If an account contains
multiple types of commodities, each commodity's total is reported
separately.

@subsection register

The @command{register} command displays all the postings occurring
in a single account, line by line.  The account regexp must be
specified as the only argument to this command.  If any regexps occur
after the required account name, the register will contain only those
postings that match.  Very useful for hunting down a particular
posting.

The output from @command{register} is very close to what a typical
checkbook, or single-account ledger, would look like.  It also shows a
running balance.  The final running balance of any register should
always be the same as the current balance of that account.

If you have Gnuplot installed, you may plot the amount or running
total of any register by using the script @file{report}, which is
included in the LEDGER distribution.  The only requirement is that you
add either @option{-j} or @option{-J} to your register command, in
order to plot either the amount or total column, respectively.

@subsection print

The @command{print} command prints out ledger transactions in a textual
format that can be parsed by LEDGER.  They will be properly formatted,
and output in the most economic form possible.  The ``print'' command
also takes a list of optional regexps, which will cause only those
postings which match in some way to be printed.

The @command{print} command can be a handy way to clean up a ledger
file whose formatting has gotten out of hand.

@subsection output

The @command{output} command is very similar to the @command{print}
command, except that it attempts to replicate the specified ledger
file exactly.  The format of the command is:

@example
ledger -f FILENAME output FILENAME
@end example

Where @file{FILENAME} is the name of the ledger file to output.  The
reason for specifying this command is that only transactions contained
within that file will be output, and not an included transactions (as can
happen with the @command{print} command).

@subsection xml

The @command{xml} command outputs results similar to what
@command{print} and @command{register} display, but as an XML form.
This data can then be read in and processed.  Use the
@option{--totals} option to include the running total with each
posting.

@subsection emacs

The @command{emacs} command outputs results in a form that can be read
directly by Emacs Lisp.  The format of the sexp is:

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

@subsection equity

The @command{equity} command prints out accounts balances as if they
were transactions.  This makes it easy to establish the starting balances
for an account, such as when @ref{Archiving Previous Years}.

@subsection prices

The @command{prices} command displays the price history for matching
commodities.  The @option{-A} flag is useful with this report, to
display the running average price, or @option{-D} to show each price's
deviation from that average.

There is also a @command{pricesdb} command which outputs the same
information as @command{prices}, but does in a format that can be
parsed by LEDGER.

@subsection xact

The @command{xact} commands simplifies the creation of new transactions.
It works on the principle that 80% of all postings are variants of
earlier postings.  Here's how it works:

Say you currently have this posting in your ledger file:

@smallexample
2004/03/15 * Viva Italiano
    Expenses:Food                       $12.45
    Expenses:Tips                        $2.55
    Liabilities:MasterCard             $-15.00
@end smallexample

Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva
Italiano} again.  The exact amounts are different, but the overall
form is the same.  With the @command{xact} command you can type:

@example
ledger xact 2004/4/9 viva food 11 tips 2.50
@end example

This produces the following output:

@smallexample
2004/04/09 Viva Italiano
    Expenses:Food                       $11.00
    Expenses:Tips                        $2.50
    Liabilities:MasterCard             $-13.50
@end smallexample

It works by finding a past posting matching the regular expression
@samp{viva}, and assuming that any accounts or amounts specified will
be similar to that earlier posting.  If LEDGER does not succeed in
generating a new transaction, an error is printed and the exit code is set
to @samp{1}.

There is a shell script in the distribution's @file{scripts} directory
called @file{xact}, which simplifies the task of adding a new transaction
to your ledger.  It launches @command{vi} to confirm that the transaction
looks appropriate.

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

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

@node Options, Period Expressions, Commands, Command-line Syntax
@section Options

With all of the reports, command-line options are useful to modify the
output generated.  These command-line options always occur before the
command word.  This is done to distinguish options from exclusive
regular expressions, which also begin with a dash.  The basic form for
most commands is:

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

The @var{OPTIONS} and @var{REGEXPS} expressions are both optional.
You could just use @samp{ledger balance}, without any options---which
prints a summary of all accounts.  But for more specific reporting, or
to change the appearance of the output, options are needed.

@subsection Basic options

These are the most basic command options.  Most likely, the user will
want to set them using environment variables (see @ref{Options}),
instead of using actual command-line options:

@option{--help} (@option{-h}) prints a summary of all the options, and
what they are used for.  This can be a handy way to remember which
options do what.  This help screen is also printed if ledger is run
without a command.

@option{--version} (@option{-v}) prints the current version of ledger
and exits.  This is useful for sending bug reports, to let the author
know which version of ledger you are using.

@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file.
This command may be used multiple times.
Typically, the environment variable
@env{LEDGER_FILE} is set, rather than using this command-line option.

@option{--output FILE} (@option{-o FILE}) redirects output from any
command to @var{FILE}.  By default, all output goes to standard
output.

@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by
ledger before any other ledger file.  This file may not contain any
postings, but it may contain option settings.  To specify options
in the init file, use the same syntax as the command-line, but put each
option on it's own line.  Here's an example init file:

@smallexample
--price-db ~/finance/.pricedb
--cache /tmp/ledger-cache

; ~/.ledgerrc ends here
@end smallexample

Option settings on the command-line or in the environment always take
precedence over settings in the init file.

@option{--cache FILE} identifies FILE as the default binary cache
file.  That is, if the ledger files to be read are specified using the
environment variable @env{LEDGER_FILE}, then whenever a command is
finished a binary copy will be written to the specified cache, to
speed up the loading time of subsequent queries.  This filename can
also be given using the environment variable @env{LEDGER_CACHE}, or by
putting the option into your init file.  The @option{--no-cache}
option causes LEDGER to always ignore the binary cache.

@option{--account NAME} (@option{-a NAME}) specifies the default
account which QIF file postings are assumed to relate to.

@subsection Report filtering

These options change which postings affect the outcome of a
report, in ways other than just using regular expressions:

@option{--current}(@option{-c}) displays only transactions occurring on or
before the current date.

@option{--begin DATE} (@option{-b DATE}) constrains the report to
transactions on or after @var{DATE}.  Only transactions after that date will be
calculated, which means that the running total in the balance report
will always start at zero with the first matching transaction.  (Note: This
is different from using @option{--display} to constrain what is
displayed).

@option{--end DATE} (@option{-e DATE}) constrains the report so that
transactions on or after @var{DATE} are not considered.  The ending date
is inclusive.

@option{--period STR} (@option{-p STR}) sets the reporting period
to @var{STR}.  This will subtotal all matching transactions within each
period separately, making it easy to see weekly, monthly, quarterly,
etc., posting totals.  A period string can even specify the
beginning and end of the report range, using simple terms like ``last
june'' or ``next month''.  For more using period expressions, see
@ref{Period Expressions}.

@option{--period-sort EXPR} sorts the postings within each
reporting period using the value expression @var{EXPR}.  This is most
often useful when reporting monthly expenses, in order to view the
highest expense categories at the top of each month:

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

@option{--cleared} (@option{-C}) displays only postings whose transaction
has been marked ``cleared'' (by placing an asterix to the right of the
date).

@option{--uncleared} (@option{-U}) displays only postings whose
transaction has not been marked ``cleared'' (i.e., if there is no asterix to
the right of the date).

@option{--real} (@option{-R}) displays only real postings, not
virtual.  (A virtual posting is indicated by surrounding the
account name with parentheses or brackets; see the section on using
virtual postings for more information).

@option{--actual} (@option{-L}) displays only actual postings, and
not those created due to automated postings.

@option{--related} (@option{-r}) displays postings that are
related to whichever postings would otherwise have matched the
filtering criteria.  In the register report, this shows where money
went to, or the account it came from.  In the balance report, it shows
all the accounts affected by transactions having a related posting.
For example, if a file had this transaction:

@smallexample
2004/03/20 Safeway
    Expenses:Food                       $65.00
    Expenses:Cash                       $20.00
    Assets:Checking                    $-85.00
@end smallexample

And the register command was:

@example
ledger -r register food
@end example

The following would be output, showing the postings related to the
posting that matched:

@smallexample
2004/03/20 Safeway              Expenses:Cash               $-20.00      $-20.00
                                Assets:Checking              $85.00       $65.00
@end smallexample

@option{--budget} is useful for displaying how close your postings
meet your budget.  @option{--add-budget} also shows unbudgeted
postings, while @option{--unbudgeted} shows only those.
@option{--forecast} is a related option that projects your budget into
the future, showing how it will affect future balances.
@xref{Budgeting and Forecasting}.

@option{--limit EXPR} (@option{-l EXPR}) limits which postings
take part in the calculations of a report.

@option{--amount EXPR} (@option{-t EXPR}) changes the value expression
used to calculate the ``value'' column in the @command{register}
report, the amount used to calculate account totals in the
@command{balance} report, and the values printed in the
@command{equity} report.  @xref{Value Expressions}.

@option{--total EXPR} (@option{-T EXPR}) sets the value expression
used for the ``totals'' column in the @command{register} and
@command{balance} reports.

@subsection Output customization

These options affect only the output, but not which postings are
used to create it:

@option{--collapse} (@option{-n}) causes transactions in a
@command{register} report with multiple postings to be collapsed
into a single, subtotaled transaction.

@option{--subtotal} (@option{-s}) causes all transactions in a
@command{register} report to be collapsed into a single, subtotaled
transaction.

@option{--by-payee} (@option{-P}) reports subtotals by payee.

@option{--comm-as-payee} (@option{-x}) changes the payee of every
posting to be the commodity used in that posting.  This can be
useful when combined with other options, such as @option{-s}.

@option{--empty} (@option{-E}) includes even empty accounts in the
@command{balance} report.

@option{--weekly} (@option{-W}) reports posting totals by the
week.  The week begins on whichever day of the week begins the month
containing that posting.  To set a specific begin date, use a
period string, such as @samp{weekly from DATE}.  @option{--monthly}
(@option{-M}) reports posting totals by month; @option{--yearly}
(@option{-Y}) reports posting totals by year.  For more complex
period, using the @option{--period} option described above.

@option{--dow} reports postings totals for each day of the week.
This is an easy way to see if weekend spending is more than on
weekdays.

@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing
the values determined using the value expression @var{EXPR}.  For
example, using @option{-S -UT} in the balance report will sort account
balances from greatest to least, using the absolute value of the
total.  For more on how to use value expressions, see @ref{Value
Expressions}.

@option{--wide} (@option{-w}) causes the default @command{register}
report to assume 132 columns instead of 80.

@option{--head} causes only the first N transactions to be printed.  This
is different from using the command-line utility @command{head}, which
would limit to the first N postings.  @option{--tail} outputs only
the last N transactions.  Both options may be used simultaneously.  If a
negative amount is given, it will invert the meaning of the flag
(instead of the first five transactions being printed, for example, it
would print all but the first five).

@option{--pager} tells LEDGER to pass its output to the given pager
program---very useful when the output is especially long.  This
behavior can be made the default by setting the @env{LEDGER_PAGER}
environment variable.

@option{--average} (@option{-A}) reports the average posting
value.

@option{--deviation} (@option{-D}) reports each posting's
deviation from the average.  It is only meaningful in the
@command{register} and @command{prices} reports.

@option{--percentage} (@option{-%}) shows account subtotals in the
@command{balance} report as percentages of the parent account.

@option{--totals} include running total information in the
@command{xml} report.

@option{--amount-data} (@option{-j}) changes the @command{register}
report so that it outputs nothing but the date and the value column,
and the latter without commodities.  This is only meaningful if the
report uses a single commodity.  This data can then be fed to other
programs, which could plot the date, analyze it, etc.

@option{--total-data} (@option{-J}) changes the @command{register}
report so that it outputs nothing but the date and totals column,
without commodities.

@option{--display EXPR} (@option{-d EXPR}) limits which postings
or accounts or actually displayed in a report.  They might still be
calculated, and be part of the running total of a register report, for
example, but they will not be displayed.  This is useful for seeing
last month's checking postings, against a running balance which
includes all posting values:

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

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

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

Which is more useful depends on what you're looking to know: the total
amount for the reporting range (@option{-p}), or simply a display
restricted to the reporting range (using @option{-d}).

@option{--date-format STR} (@option{-y STR}) changes the basic date
format used by reports.  The default uses a date like 2004/08/01,
which represents the default date format of @samp{%Y/%m/%d}.  To
change the way dates are printed in general, the easiest way is to put
@option{--date-format FORMAT} in the LEDGER initialization file
@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}).

@option{--format STR} (@option{-F STR}) sets the reporting format for
whatever report ledger is about to make.  @xref{Format Strings}.
There are also specific format commands for each report type:

@itemize
@item @option{--balance-format STR}
@item @option{--register-format STR}
@item @option{--print-format STR}
@item @option{--plot-amount-format STR} (-j @command{register})
@item @option{--plot-total-format STR} (-J @command{register})
@item @option{--equity-format STR}
@item @option{--prices-format STR}
@item @option{--wide-register-format STR} (-w @command{register})
@end itemize

@subsection Commodity reporting

These options affect how commodity values are displayed:

@option{--price-db FILE} sets the file that is used for recording
downloaded commodity prices.  It is always read on startup, to
determine historical prices.  Other settings can be placed in this
file manually, to prevent downloading quotes for a specific, for
example.  This is done by adding a line like the following:

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

@option{--price-exp MINS} (@option{-L MINS}) sets the expected
freshness of price quotes, in minutes.  That is, if the last known
quote for any commodity is older than this value---and if
@option{--download} is being used---then the Internet will be
consulted again for a newer price.  Otherwise, the old price is still
considered to be fresh enough.

@option{--download} (@option{-Q}) causes quotes to be automagically
downloaded, as needed, by running a script named @command{getquote}
and expecting that script to return a value understood by ledger.  A
sample implementation of a @command{getquote} script, implemented in
Perl, is provided in the distribution.  Downloaded quote price are
then appended to the price database, usually specified using the
environment variable @env{LEDGER_PRICE_DB}.

There are several different ways that ledger can report the totals it
displays.  The most flexible way to adjust them is by using value
expressions, and the @option{-t} and @option{-T} options.  However,
there are also several ``default'' reports, which will satisfy most
users basic reporting needs:

@table @code
@item -O, --quantity
Reports commodity totals (this is the default)

@item -B, --basis
Reports the cost basis for all postings.

@item -V, --market
Reports the last known market value for all commodities.

@item -G --gain
Reports the net gain/loss for all commodities in the report that have
a price history.
@end table

@subsection Environment variables

Every option to ledger may be set using an environment variable.  If
an option has a long name such @option{--this-option}, setting the
environment variable @env{LEDGER_THIS_OPTION} will have the same
affect as specifying that option on the command-line.  Options on the
command-line always take precedence over environment variable
settings, however.

Note that you may also permanently specify option values by placing
option settings in the file @file{~/.ledgerrc}, for example:

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

@end example

@node Period Expressions, Format Strings, Options, Command-line Syntax
@section Period Expressions

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

@example
[INTERVAL] [BEGIN] [END]
@end example

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

@example
every day
every week
every monthly
every quarter
every year
every N days     # N is any integer
every N weeks
every N months
every N quarters
every N years
daily
weekly
biweekly
monthly
bimonthly
quarterly
yearly
@end example

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

@example
from <SPEC>
since <SPEC>
@end example

The end time can be either of:

@example
to <SPEC>
until <SPEC>
@end example

Where @var{SPEC} can be any of:

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

The beginning and ending can be given at the same time, if it spans a
single period.  In that case, just use @var{SPEC} by itself.  In that
case, the period @samp{oct}, for example, will cover all the days in
october.  The possible forms are:

@example
<SPEC>
in <SPEC>
@end example

Here are a few examples of period expressions:

@example
monthly
monthly in 2004
weekly from oct
weekly from last month
from sep to oct
from 10/1 to 10/5
monthly until 2005
from apr
until nov
last oct
weekly last august
@end example