@c -*-texinfo-*-

@node Value Expressions, Variables, Basic Reporting Commands, Top
@chapter Value Expressions

Value expressions are an expression language used by LEDGER to
calculate values used by the program for many different purposes:

@enumerate
@item
The values displayed in reports
@item
For predicates (where truth is anything non-zero), to determine which
postings are calculated (@option{-l}) or displayed (@option{-d}).
@item
For sorting criteria, to yield the sort key.
@item
In the matching criteria used by automated postings.
@end enumerate

Value expressions support most simple math and logic operators, in
addition to a set of one letter functions and variables.  A function's
argument is whatever follows it.  The following is a display predicate
that I use with the @command{balance} command:

@example
ledger -d /^Liabilities/?T<0:UT>100 balance
@end example

The effect is that account totals are displayed only if: 1) A
Liabilities account has a total less than zero; or 2) the absolute
value of the account's total exceeds 100 units of whatever commodity
contains.  If it contains multiple commodities, only one of them must
exceed 100 units.

Display predicates are also very handy with register reports, to
constrain which transactions are printed.  For example, the following
command shows only transactions from the beginning of the current month,
while still calculating the running balance based on all transactions:

@example
ledger -d "d>[this month]" register checking
@end example

This advantage to this command's complexity is that it prints the
running total in terms of all transactions in the register.  The following,
simpler command is similar, but totals only the displayed
postings:

@example
ledger -b "this month" register checking
@end example

@menu
* Variables::                   
@end menu

@node Variables,  , Value Expressions, Value Expressions
@section Variables

Below are the one letter variables available in any value expression.
For the register and print commands, these variables relate to
individual postings, and sometimes the account affected by a
posting.  For the balance command, these variables relate to
accounts---often with a subtle difference in meaning.  The use of each
variable for both is specified.

@table @code
@item t
This maps to whatever the user specified with @option{-t}.  In a
register report, @option{-t} changes the value column; in a balance
report, it has no meaning by default.  If @option{-t} was not
specified, the current report style's value expression is used.

@item T
This maps to whatever the user specified with @option{-T}.  In a
register report, @option{-T} changes the totals column; in a balance
report, this is the value given for each account.  If @option{-T} was
not specified, the current report style's value expression is used.

@item m
This is always the present moment/date.
@end table

@subsection Posting/account details

@table @code
@item d
A posting's date, as the number of seconds past the epoch.  This
is always ``today'' for an account.

@item a
The posting's amount; the balance of an account, without
considering children.

@item b
The cost of a posting; the cost of an account, without its
children.

@item v
The market value of a posting, or an account without its children.

@item g
The net gain (market value minus cost basis), for a posting or an
account without its children.  It is the same as @samp{v-b}.

@item l
The depth (``level'') of an account.  If an account has one parent,
it's depth is one.

@item n
The index of a posting, or the count of postings affecting an
account.

@item X
1 if a posting's transaction has been cleared, 0 otherwise.

@item R
1 if a posting is not virtual, 0 otherwise.

@item Z
1 if a posting is not automated, 0 otherwise.
@end table

@subsection Calculated totals

@table @code
@item O
The total of all postings seen so far, or the total of an account
and all its children.

@item N
The total count of postings affecting an account and all its
children.

@item B
The total cost of all postings seen so far; the total cost of an
account and all its children.

@item V
The market value of all postings seen so far, or of an account and
all its children.

@item G
The total net gain (market value minus cost basis), for a series of
postings, or an account and its children.  It is the same as
@samp{V-B}.
@end table

@section Functions

The available one letter functions are:

@table @code
@item -
Negates the argument.

@item U
The absolute (unsigned) value of the argument.

@item S
Strips the commodity from the argument.

@item A
The arithmetic mean of the argument; @samp{Ax} is the same as
@samp{x/n}.

@item P
The present market value of the argument.  The syntax @samp{P(x,d)} is
supported, which yields the market value at time @samp{d}.  If no date
is given, then the current moment is used.
@end table

@section Operators

The binary and ternary operators, in order of precedence, are:

@enumerate
@item @samp{* /}
@item @samp{+ -}
@item @samp{! < > =}
@item @samp{& | ?:}
@end enumerate

@section Complex expressions

More complicated expressions are possible using:

@table @code
@item NUM
A plain integer represents a commodity-less amount.

@item @{AMOUNT@}
An amount in braces can be any kind of amount supported by ledger,
with or without a commodity.  Use this for decimal values.

@item /REGEXP/
@item W/REGEXP/
A regular expression that matches against an account's full name.  If
a posting, this will match against the account affected by the
posting.

@item //REGEXP/
@item p/REGEXP/
A regular expression that matches against a transaction's payee name.

@item ///REGEXP/
@item w/REGEXP/
A regular expression that matches against an account's base name.  If
a posting, this will match against the account affected by the
posting.

@item c/REGEXP/
A regular expression that matches against the transaction code (the text
that occurs between parentheses before the payee name).

@item e/REGEXP/
A regular expression that matches against a posting's note, or
comment field.

@item (EXPR)
A sub-expression is nested in parenthesis.  This can be useful passing
more complicated arguments to functions, or for overriding the natural
precedence order of operators.

@item [DATE]
Useful specifying a date in plain terms.  For example, you could say
@samp{[2004/06/01]}.
@end table