149 lines
5.2 KiB
Text
149 lines
5.2 KiB
Text
@c -*-texinfo-*-
|
|
|
|
@node Format Strings, Journal File Format, Period Expressions, Top
|
|
@chapter Format Strings
|
|
|
|
Format strings may be used to change the output format of reports.
|
|
They are specified by passing a formatting string to the
|
|
@option{--format} (@option{-F}) option. Within that string,
|
|
constructs are allowed which make it possible to display the various
|
|
parts of an account or posting in custom ways.
|
|
|
|
Within a format strings, a substitution is specified using a percent
|
|
character (@samp{%}). The basic format of all substitutions is:
|
|
|
|
@example
|
|
%[-][MIN WIDTH][.MAX WIDTH]EXPR
|
|
@end example
|
|
|
|
If the optional minus sign (@samp{-}) 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:
|
|
|
|
@example
|
|
%-P a transaction'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
|
|
@end example
|
|
|
|
The expression following the format constraints can be a single
|
|
letter, or an expression enclosed in parentheses or brackets. The
|
|
allowable expressions are:
|
|
|
|
@table @code
|
|
@item %
|
|
Inserts a percent sign.
|
|
|
|
@item t
|
|
Inserts the results of the value expression specified by @option{-t}.
|
|
If @option{-t} was not specified, the current report style's value
|
|
expression is used.
|
|
|
|
@item T
|
|
Inserts the results of the value expression specified by @option{-T}.
|
|
If @option{-T} was not specified, the current report style's value
|
|
expression is used.
|
|
|
|
@item |
|
|
Inserts a single space. This is useful if a width is specified, for
|
|
inserting a certain number of spaces.
|
|
|
|
@item _
|
|
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 @samp{%5_}, for an account with four parents, will
|
|
insert twenty spaces.
|
|
|
|
@item (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 @samp{%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.
|
|
|
|
@item [DATEFMT]
|
|
Inserts the result of formatting a posting's date with a date
|
|
format string, exactly like those supported by @code{strftime}. For
|
|
example: @samp{%[%Y/%m/%d %H:%M:%S]}.
|
|
|
|
@item S
|
|
Insert the pathname of the file from which the transaction's data was read.
|
|
|
|
@item B
|
|
Inserts the beginning character position of that transaction within the file.
|
|
|
|
@item b
|
|
Inserts the beginning line of that transaction within the file.
|
|
|
|
@item E
|
|
Inserts the ending character position of that transaction within the file.
|
|
|
|
@item e
|
|
Inserts the ending line of that transaction within the file.
|
|
|
|
@item D
|
|
By default, this is the same as @samp{%[%Y/%m%/d]}. The date format
|
|
used can be changed at any time with the @option{-y} flag, however.
|
|
Using @samp{%D} gives the user more control over the way dates are
|
|
output.
|
|
|
|
@item d
|
|
This is the same as the @samp{%D} option, unless the transaction has an
|
|
effective date, in which case it prints
|
|
@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}.
|
|
|
|
@item X
|
|
If a posting has been cleared, this inserts @samp{*} followed by a
|
|
space; otherwise nothing is inserted.
|
|
|
|
@item Y
|
|
This is the same as @samp{%X}, except that it only displays a state
|
|
character if all of the member postings have the same state.
|
|
|
|
@item C
|
|
Inserts the checking number for a transaction, in parentheses, followed by
|
|
a space; if none was specified, nothing is inserted.
|
|
|
|
@item P
|
|
Inserts the payee related to a posting.
|
|
|
|
@item 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.
|
|
|
|
@item A
|
|
Inserts the full name of an account.
|
|
|
|
@item W
|
|
This is the same as @samp{%A}, except that it first displays the
|
|
posting's state @emph{if the transaction's posting states are not
|
|
all the same}, followed by the full account name. This is offered as
|
|
a printing optimization, so that combined with @samp{%Y}, only the
|
|
minimum amount of state detail is printed.
|
|
|
|
@item o
|
|
Inserts the ``optimized'' form of a posting's amount. This is
|
|
used by the print report. In some cases, this inserts nothing; in
|
|
others, it inserts the posting amount and its cost. It's use is
|
|
not recommend unless you are modifying the print report.
|
|
|
|
@item n
|
|
Inserts the note associated with a posting, preceded by two spaces
|
|
and a semi-colon, if it exists. Thus, no none becomes an empty
|
|
string, while the note @samp{foo} is substituted as @samp{ ; foo}.
|
|
|
|
@item N
|
|
Inserts the note associated with a posting, if one exists.
|
|
|
|
@item /
|
|
The @samp{%/} construct is special. It separates a format string
|
|
between what is printed for the first posting of a transaction, and
|
|
what is printed for all subsequent postings. If not used, the
|
|
same format string is used for all postings.
|
|
@end table
|