sfos/ledger
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Established info node consistency

Browse source
This commit is contained in:
Craig Earls 2011-09-28 12:06:47 -07:00
parent a45ae5d8de
commit 49f9a28715
9 changed files with 484 additions and 438 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

146
doc/L3-FormatStrings.texi
View file

@ -1,3 +1,149 @@
@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

28
doc/L3-Introduction.texi
View file

@ -1,7 +1,8 @@
@c -*-texinfo-*-
@chapter Introduction
@node Introduction to Ledger, Principles of Accounting, ,Top
@chapter Introduction to Ledger
@ledgerprog@ is an accounting tool with the moxie to exist. It provides no
LEDGER is an accounting tool with the moxie to exist. It provides no
bells or whistles, and returns the user to the days before user
interfaces were even a twinkling in their father's CRT.
@ -78,9 +79,9 @@ deal with multiple accounts.
Here is a good place for an aside on the use of the word `account'.
Most private people consider an account to be something that holds money
at an institution for them. @ledgerprog@ uses a more general definition
at an institution for them. LEDGER uses a more general definition
of the word. An account is anywhere money can go. Other finance
programs use ``categories'', @ledgerprog@ uses accounts. So, for
programs use ``categories'', LEDGER uses accounts. So, for
example, if you buy some groceries at Trader Joe's then more groceries
at Whole Foods Markets you might assign the transactions like this
@smallexample
@ -96,19 +97,19 @@ the payees were different. You can set up your accounts in any way you
choose.
Enter the beauty of computerized accounting. The purpose of the
@ledgerprog@ program is to make general journal accounting simple, by keeping
LEDGER program is to make general journal accounting simple, by keeping
track of the balances for you. Your only job is to enter the
postings. If a posting does not balance, @ledgerprog@ displays an
postings. If a posting does not balance, LEDGER displays an
error and indicates the incorrect posting.@footnote{In some
special cases, it automatically balances this transaction for you.}
In summary, there are two aspects of @ledgerprog@ use: updating the journal
data file, and using the @ledgerprog@ tool to view the summarized result of
In summary, there are two aspects of LEDGER use: updating the journal
data file, and using the LEDGER tool to view the summarized result of
your transactions.
And just for the sake of example---as a starting point for those who
want to dive in head-first---here are the journal transactions from above,
formatted as the @ledgerprog program wishes to see them:
formatted as the LEDGER program wishes to see them:
@smallexample
2004/09/29 Pacific Bell
@ -125,7 +126,7 @@ $ ledger -f ledger.dat register checking
$ ledger -f ledger.dat register bell
@end example
An important difference between @ledgerprog@ and other finance packages is
An important difference between LEDGER and other finance packages is
that journal will never alter your input file. You can create and edit
that file in any way you prefer, but journal is only for analyzing the
data, not for altering it.
@ -135,7 +136,7 @@ data, not for altering it.
@section Building the program
@ledgerprog@ is written in ANSI C++, and should compile on any platform. It
LEDGER is written in ANSI C++, and should compile on any platform. It
depends on the GNU multiprecision integer library (libgmp), and the
Perl regular expression library (libpcre). It was developed using GNU
make and gcc 3.3, on a PowerBook running OS/X.
@ -149,8 +150,8 @@ enter these commands:
@section Getting help
If you need help on how to use @ledgerprog, or run into problems, you can
join the @ledgerprog@ mailing list at the following Web address:
If you need help on how to use LEDGER, or run into problems, you can
join the LEDGER mailing list at the following Web address:
@example
http://groups.google.com/group/ledger-cli
@ -159,4 +160,3 @@ http://groups.google.com/group/ledger-cli
You can also find help at the @samp{#ledger} channel on the IRC server
@samp{irc.freenode.net}.
@node Quick Reference, Ledger Tutorial, Introduction, Top

58
doc/L3-Journal.texi
View file

@ -1,5 +1,6 @@
@c -*-texinfo-*-
@node Keeping a Journal, Most Basic Entry, Principles of Accounting, Top
@chapter Keeping a Journal
The most important part of accounting is keeping a good journal. If you
@ -7,33 +8,44 @@ have a good journal, tools can be written to work whatever mathematical
tricks you need to better understand your spending patterns. Without a
good journal, no tool, however smart, can help you.
The @ledgerprog@ program aims at making journal transactions as simple as
The LEDGER program aims at making journal transactions as simple as
possible. Since it is a command-line tool, it does not provide a user
interface for keeping a journal. If you like, you may use GnuCash to
maintain your journal, in which case @ledgerprog@ will read
maintain your journal, in which case LEDGER will read
GnuCash's data files directly. In that case, read the GnuCash manual
now, and skip to the next chapter.
If you are not using GnuCash, but a text editor to maintain your
journal, read on. @ledgerprog@ has been designed to make data transactions as
journal, read on. LEDGER has been designed to make data transactions as
simple as possible, by keeping the journal format easy, and also by
automagically determining as much information as possible based on the
nature of your transactions.
For example, you do not need to tell @ledgerprog@ about the accounts you
use. Any time @ledgerprog@ sees a posting involving an account it knows
For example, you do not need to tell LEDGER about the accounts you
use. Any time LEDGER sees a posting involving an account it knows
nothing about, it will create it@footnote{This also means if you
misspell an account it will end up getting counted separately from what
you intended. The provided Emacs major mode provides for automatically
filling in account names.}. If you use a commodity that is new to
@ledgerprog@, it will create that commodity, and determine its display
LEDGER, it will create that commodity, and determine its display
characteristics (placement of the symbol before or after the amount,
display precision, etc) based on how you used the commodity in the
posting.
@menu
* Most Basic Entry::
* Commodities::
* Structuring Your Accounts::
* Transaction Notes and Tags::
* File Format::
* Archiving Previous Years ::
* Ledger Tutorial ::
@end menu
@node Most Basic Entry, Commodities, Keeping a Journal, Keeping a Journal
@section The Most Basic Entry
Here is the Pacific Bell example from above, given as a @ledgerprog@
Here is the Pacific Bell example from above, given as a LEDGER
posting, with the additional of a check number:
@smallexample
@ -44,8 +56,8 @@ posting, with the additional of a check number:
As you can see, it is very similar to what would be written on paper,
minus the computed balance totals, and adding in account names that work
better with @ledgerprog@'s scheme of things. In fact, since
@ledgerprog@ is smart about many things, you don't need to specify the
better with LEDGER's scheme of things. In fact, since
LEDGER is smart about many things, you don't need to specify the
balanced amount, if it is the same as the first line:
@smallexample
@ -54,7 +66,7 @@ balanced amount, if it is the same as the first line:
Assets:Checking
@end smallexample
For this transaction, @ledgerprog@ will figure out that $-23.00 must come from
For this transaction, LEDGER will figure out that $-23.00 must come from
@samp{Assets:Checking} in order to balance the transaction.
Also note the structure of the account entries. There is an implied
@ -69,15 +81,16 @@ indent and space out things exactly as shown. The only requirements are
that the start of the transaction (the date typically) is at the
beginning of the first line of the transaction, and the accounts are
indented by at least one space. If you omit the leading spaces in the
account lines @ledgerprog@ will not count the transaction and will not
account lines LEDGER will not count the transaction and will not
give an error. There must be at least two spaces, or a tab, between the
amount and the account. If you do not have adequate separation between
the amount and the account @ledgerprog@ will give an error and stop
the amount and the account LEDGER will give an error and stop
calculating}
@node Commodities, Structuring Your Accounts, Most Basic Entry, Keeping a Journal
@section Commodities
@ledgerprog@ is agnostic when it comes to how you value your accounts.
LEDGER is agnostic when it comes to how you value your accounts.
Dollars, Euros, Pounds, Francs, etc. are just ``commodities''. Holdings
in stocks, bonds, mutual funds and other financial instrument can be
label using whatever is convenient for you (stock ticker symbols are
@ -112,7 +125,7 @@ This says that $66.00 came out of checking and turned into 50 Euros. The
implied exchange rate was $1.32. Then 35 Euros was spent on Dinner in Munich.
@node Structuring Your Accounts, Transaction Notes and Tags , Commodities ,Keeping a Journal
@section Structuring your Accounts
There really are no requirements for how you do this, but to preserve
@ -126,8 +139,9 @@ places money sits, places money comes from and money you owe.
Starting the structure off this way will make it simpler for you to get
answers to the questions you really need to ask about your finances.
@node Transaction Notes and Tags, File Format, Structuring Your Accounts, Keeping a Journal
@section Transaction Notes and Tags
@ledgerprog@ 3.0 supports entry and transaction ``notes'', which may
LEDGER 3.0 supports entry and transaction ``notes'', which may
contain new metadata and tag markers. Here's an example:
@smallexample
@ -178,7 +192,7 @@ The group-by and sort functions also support tags:
@smallexample
ledger --group-by "tag('foo')" bal
@end smallexample
Will produce a balalnce summary of all transanction with tag `foo' group by transactions wiht the same value for `foo'.
Will produce a balance summary of all transanction with tag `foo' group by transactions wiht the same value for `foo'.
@smallexample
ledger reg --sort "tag('foo')" %foo
@ -190,7 +204,7 @@ zero, are always ignored and are neither searched nor printed back.
@node File format, , Value expressions, Quick Reference
@node File Format, Command-line Syntax ,Transaction Notes and Tags, Keeping a Journal
@section File format
The ledger file format is quite simple, but also very flexible. It
@ -273,7 +287,7 @@ ignored. Comments will not be returned in a ``print'' response.
If the semi colon is indented and occurs inside a transaction, it is
parsed as a persistent note for its preceding category. These notes or
tags can be used to augment to reporting and filtering capabilities of
@ledgerprog.
LEDGER.
@item Y
If a line begins with a capital Y, it denotes the year used for all
subsequent transactions that give a date without a year. The year should
@ -320,7 +334,13 @@ C 1.00 Kb = 1024 bytes
@end example
@item i, o, b, h
These four relate to timeclock support, which permits @ledgerprog@ to read
These four relate to timeclock support, which permits LEDGER to read
timelog files. See the timeclock's documentation for more info on the
syntax of its timelog files.
@end table
@node Archiving Previous Years , , ,Keeping a Journal
@section Archiving Previous Years
@node Ledger Tutorial , , ,Keeping a Journal
@section Ledger Tutorial

18
doc/L3-Main.texi
View file

@ -47,7 +47,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@titlepage
@title @ledgerprog: Command-Line Accounting
@title LEDGER: Command-Line Accounting
@author John Wiegley
@end titlepage
@ -69,16 +69,28 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@insertcopying
@end ifnottex
@menu
* Introduction to Ledger::
* Principles of Accounting::
* Keeping a Journal::
* Command-line Syntax::
* Basic Reporting Commands::
* Value Expressions::
* Format Strings::
* Journal File Format::
* Extending with Python::
@end menu
@c each chapter is in an idividual texi file included here
@include L3-Introduction.texi
@include L3-Principles.texi
@include L3-Journal.texi
@include L3-Reporting.texi
@include L3-Syntax.texi
@include L3-JournalFormat.texi
@include L3-Reporting.texi
@include L3-ValueExpressions.texi
@include L3-FormatStrings.texi
@include L3-JournalFormat.texi
@include L3-Python.texi
@bye

1
doc/L3-Principles.texi
View file

@ -1,3 +1,4 @@
@c -*-texinfo-*-
@node Principles of Accounting, Keeping a Journal, Introduction to Ledger, Top
@chapter Principles of Accounting

2
doc/L3-Python.texi
View file

@ -1,3 +1,3 @@
@c -*-texinfo-*-
@node Extending with Python, , Journal File Format, Top
@chapter Extending with Python

8
doc/L3-Reporting.texi
View file

@ -1,3 +1,11 @@
@c -*-texinfo-*-
@node Basic Reporting Commands, Value Expressions, Command-line Syntax, Top
@chapter Basic Reporting Commands
@menu
* Budgeting and Forecasting::
@end menu
@node Budgeting and Forecasting, , ,Basic Reporting Commands
@section Budgeting and Forecasting

432
doc/L3-Syntax.texi
View file

@ -1,6 +1,17 @@
@c -*-texinfo-*-
@node Command-line Syntax, Basic Reporting Commands, File Format, Top
@chapter Command-line Syntax
@menu
* Cookbook::
* Quick Reference::
* Commands::
* Options::
* Period Expressions::
@end menu
@node Cookbook, Quick Reference, Command-line Syntax, Command-line Syntax
@section Cookbook
@subsection Invoking Ledger
@ -25,14 +36,14 @@ ledger register NFCUChecking --sort d -d 'd>[2011/04/01]' until 2011/05/25
(Liabilities:Tithe Owed) -1.0
@end example
@node Quick Reference, Commands, Cookbook, Command-line Syntax
@section Quick Reference
This chapter describes @ledgerprog's features and serves as a quick
This chapter describes LEDGER's features and serves as a quick
reference. You may wish to survey this to get an overview before diving
in to the @ref{Ledger Tutorial} and more detailed examples that follow.
@ledgerprog@ has a very simple command-line interface, named---enticingly
LEDGER has a very simple command-line interface, named---enticingly
enough---@command{ledger}. It supports a few reporting commands, and
a large number of options for refining the output from those commands.
The basic syntax of any ledger command is:
@ -63,16 +74,8 @@ There are many, many command options available with the
However, none of them are required to use the basic reporting
commands.
@menu
* Commands::
* Options::
* Period expressions::
* Format strings::
* Value expressions::
* File format::
@end menu
@node Commands, Options, Quick Reference, Quick Reference
@node Commands, Options, Quick Reference, Command-line Syntax
@section Commands
@subsection balance
@ -99,14 +102,14 @@ always be the same as the current balance of that account.
If you have Gnuplot installed, you may plot the amount or running
total of any register by using the script @file{report}, which is
included in the @ledgerprog@ distribution. The only requirement is that you
included in the LEDGER distribution. The only requirement is that you
add either @option{-j} or @option{-J} to your register command, in
order to plot either the amount or total column, respectively.
@subsection print
The @command{print} command prints out ledger transactions in a textual
format that can be parsed by @ledgerprog@. They will be properly formatted,
format that can be parsed by LEDGER. They will be properly formatted,
and output in the most economic form possible. The ``print'' command
also takes a list of optional regexps, which will cause only those
postings which match in some way to be printed.
@ -152,7 +155,7 @@ directly by Emacs Lisp. The format of the sexp is:
The @command{equity} command prints out accounts balances as if they
were transactions. This makes it easy to establish the starting balances
for an account, such as when @ref{Archiving previous years}.
for an account, such as when @ref{Archiving Previous Years}.
@subsection prices
@ -163,7 +166,7 @@ deviation from that average.
There is also a @command{pricesdb} command which outputs the same
information as @command{prices}, but does in a format that can be
parsed by @ledgerprog@.
parsed by LEDGER.
@subsection xact
@ -199,7 +202,7 @@ This produces the following output:
It works by finding a past posting matching the regular expression
@samp{viva}, and assuming that any accounts or amounts specified will
be similar to that earlier posting. If @ledgerprog@ does not succeed in
be similar to that earlier posting. If LEDGER does not succeed in
generating a new transaction, an error is printed and the exit code is set
to @samp{1}.
@ -220,7 +223,7 @@ ledger xact 4/9 viva food $11.50 tips $8 cash
ledger xact 4/9 viva dining "DM 11.50"
@end example
@node Options, Period expressions, Commands, Quick Reference
@node Options, Period Expressions, Commands, Command-line Syntax
@section Options
With all of the reports, command-line options are useful to modify the
@ -285,7 +288,7 @@ finished a binary copy will be written to the specified cache, to
speed up the loading time of subsequent queries. This filename can
also be given using the environment variable @env{LEDGER_CACHE}, or by
putting the option into your init file. The @option{--no-cache}
option causes @ledgerprog@ to always ignore the binary cache.
option causes LEDGER to always ignore the binary cache.
@option{--account NAME} (@option{-a NAME}) specifies the default
account which QIF file postings are assumed to relate to.
@ -315,7 +318,7 @@ period separately, making it easy to see weekly, monthly, quarterly,
etc., posting totals. A period string can even specify the
beginning and end of the report range, using simple terms like ``last
june'' or ``next month''. For more using period expressions, see
@ref{Period expressions}.
@ref{Period Expressions}.
@option{--period-sort EXPR} sorts the postings within each
reporting period using the value expression @var{EXPR}. This is most
@ -375,7 +378,7 @@ meet your budget. @option{--add-budget} also shows unbudgeted
postings, while @option{--unbudgeted} shows only those.
@option{--forecast} is a related option that projects your budget into
the future, showing how it will affect future balances.
@xref{Budgeting and forecasting}.
@xref{Budgeting and Forecasting}.
@option{--limit EXPR} (@option{-l EXPR}) limits which postings
take part in the calculations of a report.
@ -384,7 +387,7 @@ take part in the calculations of a report.
used to calculate the ``value'' column in the @command{register}
report, the amount used to calculate account totals in the
@command{balance} report, and the values printed in the
@command{equity} report. @xref{Value expressions}.
@command{equity} report. @xref{Value Expressions}.
@option{--total EXPR} (@option{-T EXPR}) sets the value expression
used for the ``totals'' column in the @command{register} and
@ -429,7 +432,7 @@ the values determined using the value expression @var{EXPR}. For
example, using @option{-S -UT} in the balance report will sort account
balances from greatest to least, using the absolute value of the
total. For more on how to use value expressions, see @ref{Value
expressions}.
Expressions}.
@option{--wide} (@option{-w}) causes the default @command{register}
report to assume 132 columns instead of 80.
@ -442,7 +445,7 @@ negative amount is given, it will invert the meaning of the flag
(instead of the first five transactions being printed, for example, it
would print all but the first five).
@option{--pager} tells @ledgerprog@ to pass its output to the given pager
@option{--pager} tells LEDGER to pass its output to the given pager
program---very useful when the output is especially long. This
behavior can be made the default by setting the @env{LEDGER_PAGER}
environment variable.
@ -497,11 +500,11 @@ restricted to the reporting range (using @option{-d}).
format used by reports. The default uses a date like 2004/08/01,
which represents the default date format of @samp{%Y/%m/%d}. To
change the way dates are printed in general, the easiest way is to put
@option{--date-format FORMAT} in the @ledgerprog@ initialization file
@option{--date-format FORMAT} in the LEDGER initialization file
@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}).
@option{--format STR} (@option{-F STR}) sets the reporting format for
whatever report ledger is about to make. @xref{Format strings}.
whatever report ledger is about to make. @xref{Format Strings}.
There are also specific format commands for each report type:
@itemize
@ -585,8 +588,8 @@ option settings in the file @file{~/.ledgerrc}, for example:
@end example
@node Period expressions, Format strings, Options, Quick Reference
@section Period expressions
@node Period Expressions, Format Strings, Options, Command-line Syntax
@section Period Expressions
A period expression indicates a span of time, or a reporting interval,
or both. The full syntax is:
@ -672,374 +675,3 @@ last oct
weekly last august
@end example
@node Format strings, Value expressions, Period expressions, Quick Reference
@section 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
@node Value expressions, File format, Format strings, Quick Reference
@section Value expressions
Value expressions are an expression language used by @ledgerprog@ to
calculate values used by the program for many different purposes:
@enumerate
@item
The values displayed in reports
@item
For predicates (where truth is anything non-zero), to determine which
postings are calculated (@option{-l}) or displayed (@option{-d}).
@item
For sorting criteria, to yield the sort key.
@item
In the matching criteria used by automated postings.
@end enumerate
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 @command{balance} command:
@example
ledger -d /^Liabilities/?T<0:UT>100 balance
@end example
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 transactions are printed. For example, the following
command shows only transactions from the beginning of the current month,
while still calculating the running balance based on all transactions:
@example
ledger -d "d>[this month]" register checking
@end example
This advantage to this command's complexity is that it prints the
running total in terms of all transactions in the register. The following,
simpler command is similar, but totals only the displayed
postings:
@example
ledger -b "this month" register checking
@end example
@subsection Variables
Below are the one letter variables available in any value expression.
For the register and print commands, these variables relate to
individual postings, and sometimes the account affected by a
posting. 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.
@table @code
@item t
This maps to whatever the user specified with @option{-t}. In a
register report, @option{-t} changes the value column; in a balance
report, it has no meaning by default. If @option{-t} was not
specified, the current report style's value expression is used.
@item T
This maps to whatever the user specified with @option{-T}. In a
register report, @option{-T} changes the totals column; in a balance
report, this is the value given for each account. If @option{-T} was
not specified, the current report style's value expression is used.
@item m
This is always the present moment/date.
@end table
@subsubsection Posting/account details
@table @code
@item d
A posting's date, as the number of seconds past the epoch. This
is always ``today'' for an account.
@item a
The posting's amount; the balance of an account, without
considering children.
@item b
The cost of a posting; the cost of an account, without its
children.
@item v
The market value of a posting, or an account without its children.
@item g
The net gain (market value minus cost basis), for a posting or an
account without its children. It is the same as @samp{v-b}.
@item l
The depth (``level'') of an account. If an account has one parent,
it's depth is one.
@item n
The index of a posting, or the count of postings affecting an
account.
@item X
1 if a posting's transaction has been cleared, 0 otherwise.
@item R
1 if a posting is not virtual, 0 otherwise.
@item Z
1 if a posting is not automated, 0 otherwise.
@end table
@subsubsection Calculated totals
@table @code
@item O
The total of all postings seen so far, or the total of an account
and all its children.
@item N
The total count of postings affecting an account and all its
children.
@item B
The total cost of all postings seen so far; the total cost of an
account and all its children.
@item V
The market value of all postings seen so far, or of an account and
all its children.
@item G
The total net gain (market value minus cost basis), for a series of
postings, or an account and its children. It is the same as
@samp{V-B}.
@end table
@subsection Functions
The available one letter functions are:
@table @code
@item -
Negates the argument.
@item U
The absolute (unsigned) value of the argument.
@item S
Strips the commodity from the argument.
@item A
The arithmetic mean of the argument; @samp{Ax} is the same as
@samp{x/n}.
@item P
The present market value of the argument. The syntax @samp{P(x,d)} is
supported, which yields the market value at time @samp{d}. If no date
is given, then the current moment is used.
@end table
@subsection Operators
The binary and ternary operators, in order of precedence, are:
@enumerate
@item @samp{* /}
@item @samp{+ -}
@item @samp{! < > =}
@item @samp{& | ?:}
@end enumerate
@subsection Complex expressions
More complicated expressions are possible using:
@table @code
@item NUM
A plain integer represents a commodity-less amount.
@item @{AMOUNT@}
An amount in braces can be any kind of amount supported by ledger,
with or without a commodity. Use this for decimal values.
@item /REGEXP/
@item W/REGEXP/
A regular expression that matches against an account's full name. If
a posting, this will match against the account affected by the
posting.
@item //REGEXP/
@item p/REGEXP/
A regular expression that matches against a transaction's payee name.
@item ///REGEXP/
@item w/REGEXP/
A regular expression that matches against an account's base name. If
a posting, this will match against the account affected by the
posting.
@item c/REGEXP/
A regular expression that matches against the transaction code (the text
that occurs between parentheses before the payee name).
@item e/REGEXP/
A regular expression that matches against a posting's note, or
comment field.
@item (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.
@item [DATE]
Useful specifying a date in plain terms. For example, you could say
@samp{[2004/06/01]}.
@end table

229
doc/L3-ValueExpressions.texi
View file

@ -1,3 +1,230 @@
@c -*-texinfo-*-
@chapter Value Expression
@node Value Expressions, Variables, Basic Reporting Commands, Top
@chapter Value Expressions
Value expressions are an expression language used by LEDGER to
calculate values used by the program for many different purposes:
@enumerate
@item
The values displayed in reports
@item
For predicates (where truth is anything non-zero), to determine which
postings are calculated (@option{-l}) or displayed (@option{-d}).
@item
For sorting criteria, to yield the sort key.
@item
In the matching criteria used by automated postings.
@end enumerate
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 @command{balance} command:
@example
ledger -d /^Liabilities/?T<0:UT>100 balance
@end example
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 transactions are printed. For example, the following
command shows only transactions from the beginning of the current month,
while still calculating the running balance based on all transactions:
@example
ledger -d "d>[this month]" register checking
@end example
This advantage to this command's complexity is that it prints the
running total in terms of all transactions in the register. The following,
simpler command is similar, but totals only the displayed
postings:
@example
ledger -b "this month" register checking
@end example
@menu
* Variables::
@end menu
@node Variables, , Value Expressions, Value Expressions
@section Variables
Below are the one letter variables available in any value expression.
For the register and print commands, these variables relate to
individual postings, and sometimes the account affected by a
posting. 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.
@table @code
@item t
This maps to whatever the user specified with @option{-t}. In a
register report, @option{-t} changes the value column; in a balance
report, it has no meaning by default. If @option{-t} was not
specified, the current report style's value expression is used.
@item T
This maps to whatever the user specified with @option{-T}. In a
register report, @option{-T} changes the totals column; in a balance
report, this is the value given for each account. If @option{-T} was
not specified, the current report style's value expression is used.
@item m
This is always the present moment/date.
@end table
@subsection Posting/account details
@table @code
@item d
A posting's date, as the number of seconds past the epoch. This
is always ``today'' for an account.
@item a
The posting's amount; the balance of an account, without
considering children.
@item b
The cost of a posting; the cost of an account, without its
children.
@item v
The market value of a posting, or an account without its children.
@item g
The net gain (market value minus cost basis), for a posting or an
account without its children. It is the same as @samp{v-b}.
@item l
The depth (``level'') of an account. If an account has one parent,
it's depth is one.
@item n
The index of a posting, or the count of postings affecting an
account.
@item X
1 if a posting's transaction has been cleared, 0 otherwise.
@item R
1 if a posting is not virtual, 0 otherwise.
@item Z
1 if a posting is not automated, 0 otherwise.
@end table
@subsection Calculated totals
@table @code
@item O
The total of all postings seen so far, or the total of an account
and all its children.
@item N
The total count of postings affecting an account and all its
children.
@item B
The total cost of all postings seen so far; the total cost of an
account and all its children.
@item V
The market value of all postings seen so far, or of an account and
all its children.
@item G
The total net gain (market value minus cost basis), for a series of
postings, or an account and its children. It is the same as
@samp{V-B}.
@end table
@section Functions
The available one letter functions are:
@table @code
@item -
Negates the argument.
@item U
The absolute (unsigned) value of the argument.
@item S
Strips the commodity from the argument.
@item A
The arithmetic mean of the argument; @samp{Ax} is the same as
@samp{x/n}.
@item P
The present market value of the argument. The syntax @samp{P(x,d)} is
supported, which yields the market value at time @samp{d}. If no date
is given, then the current moment is used.
@end table
@section Operators
The binary and ternary operators, in order of precedence, are:
@enumerate
@item @samp{* /}
@item @samp{+ -}
@item @samp{! < > =}
@item @samp{& | ?:}
@end enumerate
@section Complex expressions
More complicated expressions are possible using:
@table @code
@item NUM
A plain integer represents a commodity-less amount.
@item @{AMOUNT@}
An amount in braces can be any kind of amount supported by ledger,
with or without a commodity. Use this for decimal values.
@item /REGEXP/
@item W/REGEXP/
A regular expression that matches against an account's full name. If
a posting, this will match against the account affected by the
posting.
@item //REGEXP/
@item p/REGEXP/
A regular expression that matches against a transaction's payee name.
@item ///REGEXP/
@item w/REGEXP/
A regular expression that matches against an account's base name. If
a posting, this will match against the account affected by the
posting.
@item c/REGEXP/
A regular expression that matches against the transaction code (the text
that occurs between parentheses before the payee name).
@item e/REGEXP/
A regular expression that matches against a posting's note, or
comment field.
@item (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.
@item [DATE]
Useful specifying a date in plain terms. For example, you could say
@samp{[2004/06/01]}.
@end table