Value Expression Functions¶

This document lists the built-in functions available in Ledger's value expression language.

Amount Functions¶

abs(x)¶

Returns absolute value:

assert abs($-100) == $100
assert abs(amount) < $1000

round(x)¶

Rounds to commodity precision:

2024/01/15 Rounded
    Expenses:A    (round($33.333))  ; $33.33
    Assets:Checking

floor(x)¶

Rounds down:

(floor($33.9))  ; $33.00

ceiling(x)¶

Rounds up:

(ceiling($33.1))  ; $34.00

truncate(x)¶

Truncates toward zero:

(truncate($33.9))   ; $33.00
(truncate($-33.9))  ; $-33.00

commodity(x)¶

Returns the commodity symbol:

= expr commodity(amount) == "$"
    ; :usd:

quantity(x)¶

Returns numeric quantity without commodity:

assert quantity($100.50) == 100.50

Account Functions¶

total(account)¶

Sum of account balances:

assert total(Assets) > 0
assert total(Expenses:Food) < $1000

display_total(account)¶

Formatted total for display:

--format "%(account): %(display_total)\n"

has_tag(name)¶

Check if posting has tag:

= expr has_tag("reimbursable")
    Receivables:Reimbursement    (amount)

tag(name)¶

Get tag value:

= expr tag("project") == "alpha"
    ; Additional processing

account¶

Current account (variable, not function):

= expr account =~ /Expenses:Food/
    (Budget:Food)  (amount * -1)

Date Functions¶

date¶

Current transaction date:

= expr date >= [2024/01/01]
    ; :this-year:

today¶

Current calendar date:

= expr date < today
    ; :past:

year(d)¶

Extract year:

= expr year(date) == 2024
    ; :2024:

month(d)¶

Extract month (1-12):

= expr month(date) == 12
    ; :december:

day(d)¶

Extract day (1-31):

= expr day(date) == 1
    ; :month-start:

String Functions¶

payee¶

Transaction payee:

= expr payee =~ /Whole Foods/
    ; :groceries:

note¶

Transaction note/narration:

= expr note =~ /reimbursable/i
    ; :reimbursable:

format(fmt, ...)¶

Format string:

= format("%s-%04d", commodity, quantity)

join(sep, ...)¶

Join strings:

= join(", ", account, payee)

substr(s, start, len)¶

Substring:

= substr(payee, 0, 10)

Logical Functions¶

any(account, expr)¶

True if any posting matches:

assert any(Expenses, amount > $100)

all(account, expr)¶

True if all postings match:

assert all(Expenses, amount >= 0)

count(account)¶

Number of postings:

assert count(Expenses:Food) < 100

Collection Functions¶

sum(expr)¶

Sum over collection:

= sum(amount)

min(...)¶

Minimum value:

(min($100, $50, $75))  ; $50

max(...)¶

Maximum value:

(max($100, $50, $75))  ; $100

average(expr)¶

Average value:

= average(amount)

Market Value Functions¶

market(amount)¶

Current market value:

--format "%(account): %(market(display_total))\n"

price(commodity)¶

Current price of commodity:

= price(AAPL)  ; Returns price in default commodity

exchange(amount, commodity)¶

Convert to different commodity:

(exchange($100, "EUR"))

Utility Functions¶

print(...)¶

Debug output:

= expr print("Processing: ", account)

now¶

Current datetime:

= expr now

default¶

Check if value is default/empty:

= expr default(amount)
    ; Handle empty amount

Report-Specific Functions¶

These functions are primarily used in --format expressions:

quoted(x)¶

Quote for output:

--format "%(quoted(payee))\n"

justify(x, width)¶

Right-justify:

--format "%(justify(total, 12))\n"

strip(x)¶

Remove surrounding whitespace:

--format "%(strip(payee))\n"

scrub(x)¶

Clean for display:

--format "%(scrub(total))\n"

Function Categories¶

Pure Functions¶

No side effects: - abs, round, floor, ceiling - min, max, sum, average - quantity, commodity

Query Functions¶

Read state: - total, has_tag, tag - price, market - date, today, now

Format Functions¶

For output: - format, justify, quoted - strip, scrub

Examples¶

Complex Validation¶

assert total(Assets) - total(Liabilities) > $0
  and all(Assets:Cash, amount >= $0)
  and count(Expenses) > 0

Automated Categorization¶

= expr payee =~ /^Amazon/ and amount > $100
    ; :large-amazon-purchase:
    ; review: true

= expr account =~ /Expenses:Food/ and month(date) == 12
    ; :holiday-food:

Report Formatting¶

ledger bal --format "%(account)-40s %(justify(market(display_total), 15))\n"

Calculations¶

2024/01/15 Tax Withholding
    Assets:Checking    (income - (income * tax_rate))
    Expenses:Tax       (income * tax_rate)
    Income:Salary      (-income)