Next: Period expressions, Previous: Format strings, Up: Running Ledger [Contents]
Value expressions are an expression language used by Ledger to calculate values used by the program for many different purposes:
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 balance
command:
ledger -d /^Liabilities/?T<0:UT>100 balance
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 entries are printed. For example, the following command shows only entries from the beginning of the current month, while still calculating the running balance based on all entries:
ledger -d "d>[this month]" register checking
This advantage to this command’s complexity is that it prints the running total in terms of all entries in the register. The following, simpler command is similar, but totals only the displayed transactions:
ledger -b "this month" register checking
Below are the one letter variables available in any value expression. For the register and print commands, these variables relate to individual transactions, and sometimes the account affected by a transaction. 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.
t
This maps to whatever the user specified with -t. In a register report, -t changes the value column; in a balance report, it has no meaning by default. If -t was not specified, the current report style’s value expression is used.
T
This maps to whatever the user specified with -T. In a register report, -T changes the totals column; in a balance report, this is the value given for each account. If -T was not specified, the current report style’s value expression is used.
m
This is always the present moment/date.
d
A transaction’s date, as the number of seconds past the epoch. This is always “today” for an account.
a
The transaction’s amount; the balance of an account, without considering children.
b
The cost of a transaction; the cost of an account, without its children.
v
The market value of a transaction, or an account without its children.
g
The net gain (market value minus cost basis), for a transaction or an account without its children. It is the same as ‘v-b’.
l
The depth (“level”) of an account. If an account has one parent, it’s depth is one.
n
The index of a transaction, or the count of transactions affecting an account.
X
1 if a transaction’s entry has been cleared, 0 otherwise.
R
1 if a transaction is not virtual, 0 otherwise.
Z
1 if a transaction is not automated, 0 otherwise.
O
The total of all transactions seen so far, or the total of an account and all its children.
N
The total count of transactions affecting an account and all its children.
B
The total cost of all transactions seen so far; the total cost of an account and all its children.
V
The market value of all transactions seen so far, or of an account and all its children.
G
The total net gain (market value minus cost basis), for a series of transactions, or an account and its children. It is the same as ‘V-B’.
The available one letter functions are:
-
Negates the argument.
U
The absolute (unsigned) value of the argument.
S
Strips the commodity from the argument.
A
The arithmetic mean of the argument; ‘Ax’ is the same as ‘x/n’.
P
The present market value of the argument. The syntax ‘P(x,d)’ is supported, which yields the market value at time ‘d’. If no date is given, then the current moment is used.
The binary and ternary operators, in order of precedence, are:
More complicated expressions are possible using:
NUM
A plain integer represents a commodity-less amount.
{AMOUNT}
An amount in braces can be any kind of amount supported by ledger, with or without a commodity. Use this for decimal values.
/REGEXP/
W/REGEXP/
A regular expression that matches against an account’s full name. If a transaction, this will match against the account affected by the transaction.
//REGEXP/
p/REGEXP/
A regular expression that matches against an entry’s payee name.
///REGEXP/
w/REGEXP/
A regular expression that matches against an account’s base name. If a transaction, this will match against the account affected by the transaction.
c/REGEXP/
A regular expression that matches against the entry code (the text that occurs between parentheses before the payee name).
e/REGEXP/
A regular expression that matches against a transaction’s note, or comment field.
(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.
[DATE]
Useful specifying a date in plain terms. For example, you could say ‘[2004/06/01]’.
Next: Period expressions, Previous: Format strings, Up: Running Ledger [Contents]