230 lines
6.2 KiB
Text
230 lines
6.2 KiB
Text
@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
|
|
|