Next: , Previous: Format strings, Up: Running Ledger


2.5 Value expressions

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

  1. The values displayed in reports
  2. For predicates (where truth is anything non-zero), to determine which transactions are calculated (-l) or displayed (-d).
  3. For sorting criteria, to yield the sort key.
  4. In the matching criteria used by automated transactions.

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

2.5.1 Variables

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.
2.5.1.1 Transaction/account details
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.
2.5.1.2 Calculated totals
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’.

2.5.2 Functions

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.

2.5.3 Operators

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

  1. * /
  2. + -
  3. ! < > =
  4. & | ?:

2.5.4 Complex expressions

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]’.