Next: , Previous: Options, Up: Running Ledger


2.4 Format strings

Format strings may be used to change the output format of reports. They are specified by passing a formatting string to the --format (-F) option. Within that string, constructs are allowed which make it possible to display the various parts of an account or transaction in custom ways.

Within a format strings, a substitution is specified using a percent character (‘%’). The basic format of all substitutions is:

     %[-][MIN WIDTH][.MAX WIDTH]EXPR

If the optional minus sign (‘-’) follows the percent character, whatever is substituted will be left justified. The default is right justified. If a minimum width is given next, the substituted text will be at least that wide, perhaps wider. If a period and a maximum width is given, the substituted text will never be wider than this, and will be truncated to fit. Here are some examples:

     %-P     An entry's payee, left justified
     %20P    The same, right justified, at least 20 chars wide
     %.20P   The same, no more than 20 chars wide
     %-.20P  Left justified, maximum twenty chars wide

The expression following the format constraints can be a single letter, or an expression enclosed in parentheses or brackets. The allowable expressions are:

%
Inserts a percent sign.
t
Inserts the results of the value expression specified by -t. If -t was not specified, the current report style's value expression is used.
T
Inserts the results of the value expression specified by -T. If -T was not specified, the current report style's value expression is used.
|
Inserts a single space. This is useful if a width is specified, for inserting a certain number of spaces.
_
Inserts a space for each level of an account's depth. That is, if an account has two parents, this construct will insert two spaces. If a minimum width is specified, that much space is inserted for each level of depth. Thus ‘%5_’, for an account with four parents, will insert twenty spaces.
(EXPR)
Inserts the amount resulting from the value expression given in parentheses. To insert five times the total value of an account, for example, one could say ‘%12(5*O)’. Note: It's important to put the five first in that expression, so that the commodity doesn't get stripped from the total.
[DATEFMT]
Inserts the result of formatting a transaction's date with a date format string, exactly like those supported by strftime. For example: ‘%[%Y/%m/%d %H:%M:%S]’.
S
Insert the pathname of the file from which the entry's data was read.
B
Inserts the beginning character position of that entry within the file.
b
Inserts the beginning line of that entry within the file.
E
Inserts the ending character position of that entry within the file.
e
Inserts the ending line of that entry within the file.
D
By default, this is the same as ‘%[%Y/%m%/d]’. The date format used can be changed at any time with the -y flag, however. Using ‘%D’ gives the user more control over the way dates are output.
d
This is the same as the ‘%D’ option, unless the entry has an effective date, in which case it prints ‘[ACTUAL_DATE=EFFECtIVE_DATE]’.
X
If a transaction has been cleared, this inserts ‘*’ followed by a space; otherwise nothing is inserted.
Y
This is the same as ‘%X’, except that it only displays a state character if all of the member transactions have the same state.
C
Inserts the checking number for an entry, in parentheses, followed by a space; if none was specified, nothing is inserted.
P
Inserts the payee related to a transaction.
a
Inserts the optimal short name for an account. This is normally used in balance reports. It prints a parent account's name if that name has not been printed yet, otherwise it just prints the account's name.
A
Inserts the full name of an account.
W
This is the same as ‘%A’, except that it first displays the transaction's state if the entry's transaction states are not all the same, followed by the full account name. This is offered as a printing optimization, so that combined with ‘%Y’, only the minimum amount of state detail is printed.
o
Inserts the “optimized” form of a transaction's amount. This is used by the print report. In some cases, this inserts nothing; in others, it inserts the transaction amount and its cost. It's use is not recommend unless you are modifying the print report.
n
Inserts the note associated with a transaction, preceded by two spaces and a semi-colon, if it exists. Thus, no none becomes an empty string, while the note ‘foo’ is substituted as ‘ ; foo’.
N
Inserts the note associated with a transaction, if one exists.
/
The ‘%/’ construct is special. It separates a format string between what is printed for the first transaction of an entry, and what is printed for all subsequent transactions. If not used, the same format string is used for all transactions.