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.