diff options
Diffstat (limited to 'doc/L3-Syntax.texi')
| -rw-r--r-- | doc/L3-Syntax.texi | 1044 |
1 files changed, 1044 insertions, 0 deletions
diff --git a/doc/L3-Syntax.texi b/doc/L3-Syntax.texi new file mode 100644 index 00000000..afe4520d --- /dev/null +++ b/doc/L3-Syntax.texi @@ -0,0 +1,1044 @@ +@c -*-texinfo-*- + +@section Cookbook + +@subsection Invoking Ledger + +@example +ledger --group-by "tag('trip')" bal +legder reg --sort "tag('foo')" %foo +ledger cleared VWCU NFCU Tithe Misentry +ledger register Joint --uncleared +ledger register NFCUChecking --sort d -d 'd>[2011/04/01]' until 2011/05/25 +@end example +@subsection Ledger Files + +@example += /^Income:Taxable/ + (Liabilities:Tithe Owed) -0.1 += /Noah/ + (Liabilities:Tithe Owed) -0.1 += /Jonah/ + (Liabilities:Tithe Owed) -0.1 += /Tithe/ + (Liabilities:Tithe Owed) -1.0 +@end example + + +@section Quick Reference + +This chapter describes @ledgerprog'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 +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: + +@example +ledger [OPTIONS...] COMMAND [ARGS...] +@end example + +Command options must always precede the command word. After the +command word there may appear any number of arguments. For most +commands, these arguments are regular expressions that cause the +output to relate only to postings matching those regular +expressions. For the @command{transaction} command, the arguments have a +special meaning, described below. + +The regular expressions arguments always match the account name that a +posting refers to. To match on the payee of the transaction instead, +precede the regular expression with @samp{--}. For example, the +following balance command reports account totals for rent, food and +movies, but only those whose payee matches Freddie: + +@example +ledger bal rent food movies -- freddie +@end example + +There are many, many command options available with the +@command{ledger} command, and it takes a while to master them. +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 +@section Commands + +@subsection balance + +The @command{balance} command reports the current balance of all +accounts. It accepts a list of optional regexps, which confine the +balance report to the matching accounts. If an account contains +multiple types of commodities, each commodity's total is reported +separately. + +@subsection register + +The @command{register} command displays all the postings occurring +in a single account, line by line. The account regexp must be +specified as the only argument to this command. If any regexps occur +after the required account name, the register will contain only those +postings that match. Very useful for hunting down a particular +posting. + +The output from @command{register} is very close to what a typical +checkbook, or single-account ledger, would look like. It also shows a +running balance. The final running balance of any register should +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 +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, +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. + +The @command{print} command can be a handy way to clean up a ledger +file whose formatting has gotten out of hand. + +@subsection output + +The @command{output} command is very similar to the @command{print} +command, except that it attempts to replicate the specified ledger +file exactly. The format of the command is: + +@example +ledger -f FILENAME output FILENAME +@end example + +Where @file{FILENAME} is the name of the ledger file to output. The +reason for specifying this command is that only transactions contained +within that file will be output, and not an included transactions (as can +happen with the @command{print} command). + +@subsection xml + +The @command{xml} command outputs results similar to what +@command{print} and @command{register} display, but as an XML form. +This data can then be read in and processed. Use the +@option{--totals} option to include the running total with each +posting. + +@subsection emacs + +The @command{emacs} command outputs results in a form that can be read +directly by Emacs Lisp. The format of the sexp is: + +@example +((BEG-POS CLEARED DATE CODE PAYEE + (ACCOUNT AMOUNT)...) ; list of postings + ...) ; list of transactions +@end example + +@subsection equity + +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}. + +@subsection prices + +The @command{prices} command displays the price history for matching +commodities. The @option{-A} flag is useful with this report, to +display the running average price, or @option{-D} to show each price's +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@. + +@subsection xact + +The @command{xact} commands simplifies the creation of new transactions. +It works on the principle that 80% of all postings are variants of +earlier postings. Here's how it works: + +Say you currently have this posting in your ledger file: + +@smallexample +2004/03/15 * Viva Italiano + Expenses:Food $12.45 + Expenses:Tips $2.55 + Liabilities:MasterCard $-15.00 +@end smallexample + +Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva +Italiano} again. The exact amounts are different, but the overall +form is the same. With the @command{xact} command you can type: + +@example +ledger xact 2004/4/9 viva food 11 tips 2.50 +@end example + +This produces the following output: + +@smallexample +2004/04/09 Viva Italiano + Expenses:Food $11.00 + Expenses:Tips $2.50 + Liabilities:MasterCard $-13.50 +@end smallexample + +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 +generating a new transaction, an error is printed and the exit code is set +to @samp{1}. + +There is a shell script in the distribution's @file{scripts} directory +called @file{xact}, which simplifies the task of adding a new transaction +to your ledger. It launches @command{vi} to confirm that the transaction +looks appropriate. + +Here are a few more examples of the @command{xact} command, assuming +the above journal transaction: + +@example +ledger xact 4/9 viva 11.50 +ledger xact 4/9 viva 11.50 checking # (from `checking') +ledger xact 4/9 viva food 11.50 tips 8 +ledger xact 4/9 viva food 11.50 tips 8 cash +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 +@section Options + +With all of the reports, command-line options are useful to modify the +output generated. These command-line options always occur before the +command word. This is done to distinguish options from exclusive +regular expressions, which also begin with a dash. The basic form for +most commands is: + +@example +ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] +@end example + +The @var{OPTIONS} and @var{REGEXPS} expressions are both optional. +You could just use @samp{ledger balance}, without any options---which +prints a summary of all accounts. But for more specific reporting, or +to change the appearance of the output, options are needed. + +@subsection Basic options + +These are the most basic command options. Most likely, the user will +want to set them using environment variables (see @ref{Options}), +instead of using actual command-line options: + +@option{--help} (@option{-h}) prints a summary of all the options, and +what they are used for. This can be a handy way to remember which +options do what. This help screen is also printed if ledger is run +without a command. + +@option{--version} (@option{-v}) prints the current version of ledger +and exits. This is useful for sending bug reports, to let the author +know which version of ledger you are using. + +@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. +This command may be used multiple times. +Typically, the environment variable +@env{LEDGER_FILE} is set, rather than using this command-line option. + +@option{--output FILE} (@option{-o FILE}) redirects output from any +command to @var{FILE}. By default, all output goes to standard +output. + +@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by +ledger before any other ledger file. This file may not contain any +postings, but it may contain option settings. To specify options +in the init file, use the same syntax as the command-line, but put each +option on it's own line. Here's an example init file: + +@smallexample +--price-db ~/finance/.pricedb +--cache /tmp/ledger-cache + +; ~/.ledgerrc ends here +@end smallexample + +Option settings on the command-line or in the environment always take +precedence over settings in the init file. + +@option{--cache FILE} identifies FILE as the default binary cache +file. That is, if the ledger files to be read are specified using the +environment variable @env{LEDGER_FILE}, then whenever a command is +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{--account NAME} (@option{-a NAME}) specifies the default +account which QIF file postings are assumed to relate to. + +@subsection Report filtering + +These options change which postings affect the outcome of a +report, in ways other than just using regular expressions: + +@option{--current}(@option{-c}) displays only transactions occurring on or +before the current date. + +@option{--begin DATE} (@option{-b DATE}) constrains the report to +transactions on or after @var{DATE}. Only transactions after that date will be +calculated, which means that the running total in the balance report +will always start at zero with the first matching transaction. (Note: This +is different from using @option{--display} to constrain what is +displayed). + +@option{--end DATE} (@option{-e DATE}) constrains the report so that +transactions on or after @var{DATE} are not considered. The ending date +is inclusive. + +@option{--period STR} (@option{-p STR}) sets the reporting period +to @var{STR}. This will subtotal all matching transactions within each +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}. + +@option{--period-sort EXPR} sorts the postings within each +reporting period using the value expression @var{EXPR}. This is most +often useful when reporting monthly expenses, in order to view the +highest expense categories at the top of each month: + +@example +ledger -M --period-sort -At reg ^Expenses +@end example + +@option{--cleared} (@option{-C}) displays only postings whose transaction +has been marked ``cleared'' (by placing an asterix to the right of the +date). + +@option{--uncleared} (@option{-U}) displays only postings whose +transaction has not been marked ``cleared'' (i.e., if there is no asterix to +the right of the date). + +@option{--real} (@option{-R}) displays only real postings, not +virtual. (A virtual posting is indicated by surrounding the +account name with parentheses or brackets; see the section on using +virtual postings for more information). + +@option{--actual} (@option{-L}) displays only actual postings, and +not those created due to automated postings. + +@option{--related} (@option{-r}) displays postings that are +related to whichever postings would otherwise have matched the +filtering criteria. In the register report, this shows where money +went to, or the account it came from. In the balance report, it shows +all the accounts affected by transactions having a related posting. +For example, if a file had this transaction: + +@smallexample +2004/03/20 Safeway + Expenses:Food $65.00 + Expenses:Cash $20.00 + Assets:Checking $-85.00 +@end smallexample + +And the register command was: + +@example +ledger -r register food +@end example + +The following would be output, showing the postings related to the +posting that matched: + +@smallexample +2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 + Assets:Checking $85.00 $65.00 +@end smallexample + +@option{--budget} is useful for displaying how close your postings +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}. + +@option{--limit EXPR} (@option{-l EXPR}) limits which postings +take part in the calculations of a report. + +@option{--amount EXPR} (@option{-t EXPR}) changes the value expression +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}. + +@option{--total EXPR} (@option{-T EXPR}) sets the value expression +used for the ``totals'' column in the @command{register} and +@command{balance} reports. + +@subsection Output customization + +These options affect only the output, but not which postings are +used to create it: + +@option{--collapse} (@option{-n}) causes transactions in a +@command{register} report with multiple postings to be collapsed +into a single, subtotaled transaction. + +@option{--subtotal} (@option{-s}) causes all transactions in a +@command{register} report to be collapsed into a single, subtotaled +transaction. + +@option{--by-payee} (@option{-P}) reports subtotals by payee. + +@option{--comm-as-payee} (@option{-x}) changes the payee of every +posting to be the commodity used in that posting. This can be +useful when combined with other options, such as @option{-s}. + +@option{--empty} (@option{-E}) includes even empty accounts in the +@command{balance} report. + +@option{--weekly} (@option{-W}) reports posting totals by the +week. The week begins on whichever day of the week begins the month +containing that posting. To set a specific begin date, use a +period string, such as @samp{weekly from DATE}. @option{--monthly} +(@option{-M}) reports posting totals by month; @option{--yearly} +(@option{-Y}) reports posting totals by year. For more complex +period, using the @option{--period} option described above. + +@option{--dow} reports postings totals for each day of the week. +This is an easy way to see if weekend spending is more than on +weekdays. + +@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing +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}. + +@option{--wide} (@option{-w}) causes the default @command{register} +report to assume 132 columns instead of 80. + +@option{--head} causes only the first N transactions to be printed. This +is different from using the command-line utility @command{head}, which +would limit to the first N postings. @option{--tail} outputs only +the last N transactions. Both options may be used simultaneously. If a +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 +program---very useful when the output is especially long. This +behavior can be made the default by setting the @env{LEDGER_PAGER} +environment variable. + +@option{--average} (@option{-A}) reports the average posting +value. + +@option{--deviation} (@option{-D}) reports each posting's +deviation from the average. It is only meaningful in the +@command{register} and @command{prices} reports. + +@option{--percentage} (@option{-%}) shows account subtotals in the +@command{balance} report as percentages of the parent account. + +@option{--totals} include running total information in the +@command{xml} report. + +@option{--amount-data} (@option{-j}) changes the @command{register} +report so that it outputs nothing but the date and the value column, +and the latter without commodities. This is only meaningful if the +report uses a single commodity. This data can then be fed to other +programs, which could plot the date, analyze it, etc. + +@option{--total-data} (@option{-J}) changes the @command{register} +report so that it outputs nothing but the date and totals column, +without commodities. + +@option{--display EXPR} (@option{-d EXPR}) limits which postings +or accounts or actually displayed in a report. They might still be +calculated, and be part of the running total of a register report, for +example, but they will not be displayed. This is useful for seeing +last month's checking postings, against a running balance which +includes all posting values: + +@example +ledger -d "d>=[last month]" reg checking +@end example + +The output from this command is very different from the following, +whose running total includes only postings from the last month +onward: + +@example +ledger -p "last month" reg checking +@end example + +Which is more useful depends on what you're looking to know: the total +amount for the reporting range (@option{-p}), or simply a display +restricted to the reporting range (using @option{-d}). + +@option{--date-format STR} (@option{-y STR}) changes the basic date +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 +@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}. +There are also specific format commands for each report type: + +@itemize +@item @option{--balance-format STR} +@item @option{--register-format STR} +@item @option{--print-format STR} +@item @option{--plot-amount-format STR} (-j @command{register}) +@item @option{--plot-total-format STR} (-J @command{register}) +@item @option{--equity-format STR} +@item @option{--prices-format STR} +@item @option{--wide-register-format STR} (-w @command{register}) +@end itemize + +@subsection Commodity reporting + +These options affect how commodity values are displayed: + +@option{--price-db FILE} sets the file that is used for recording +downloaded commodity prices. It is always read on startup, to +determine historical prices. Other settings can be placed in this +file manually, to prevent downloading quotes for a specific, for +example. This is done by adding a line like the following: + +@example +; Don't download quotes for the dollar, or timelog values +N $ +N h +@end example + +@option{--price-exp MINS} (@option{-L MINS}) sets the expected +freshness of price quotes, in minutes. That is, if the last known +quote for any commodity is older than this value---and if +@option{--download} is being used---then the Internet will be +consulted again for a newer price. Otherwise, the old price is still +considered to be fresh enough. + +@option{--download} (@option{-Q}) causes quotes to be automagically +downloaded, as needed, by running a script named @command{getquote} +and expecting that script to return a value understood by ledger. A +sample implementation of a @command{getquote} script, implemented in +Perl, is provided in the distribution. Downloaded quote price are +then appended to the price database, usually specified using the +environment variable @env{LEDGER_PRICE_DB}. + +There are several different ways that ledger can report the totals it +displays. The most flexible way to adjust them is by using value +expressions, and the @option{-t} and @option{-T} options. However, +there are also several ``default'' reports, which will satisfy most +users basic reporting needs: + +@table @code +@item -O, --quantity +Reports commodity totals (this is the default) + +@item -B, --basis +Reports the cost basis for all postings. + +@item -V, --market +Reports the last known market value for all commodities. + +@item -G --gain +Reports the net gain/loss for all commodities in the report that have +a price history. +@end table + +@subsection Environment variables + +Every option to ledger may be set using an environment variable. If +an option has a long name such @option{--this-option}, setting the +environment variable @env{LEDGER_THIS_OPTION} will have the same +affect as specifying that option on the command-line. Options on the +command-line always take precedence over environment variable +settings, however. + +Note that you may also permanently specify option values by placing +option settings in the file @file{~/.ledgerrc}, for example: + +@example +--cache /tmp/.mycache +--pager /bin/cat + +@end example + +@node Period expressions, Format strings, Options, Quick Reference +@section Period expressions + +A period expression indicates a span of time, or a reporting interval, +or both. The full syntax is: + +@example +[INTERVAL] [BEGIN] [END] +@end example + +The optional @var{INTERVAL} part may be any one of: + +@example +every day +every week +every monthly +every quarter +every year +every N days # N is any integer +every N weeks +every N months +every N quarters +every N years +daily +weekly +biweekly +monthly +bimonthly +quarterly +yearly +@end example + +After the interval, a begin time, end time, both or neither may be +specified. As for the begin time, it can be either of: + +@example +from <SPEC> +since <SPEC> +@end example + +The end time can be either of: + +@example +to <SPEC> +until <SPEC> +@end example + +Where @var{SPEC} can be any of: + +@example +2004 +2004/10 +2004/10/1 +10/1 +october +oct +this week # or day, month, quarter, year +next week +last week +@end example + +The beginning and ending can be given at the same time, if it spans a +single period. In that case, just use @var{SPEC} by itself. In that +case, the period @samp{oct}, for example, will cover all the days in +october. The possible forms are: + +@example +<SPEC> +in <SPEC> +@end example + +Here are a few examples of period expressions: + +@example +monthly +monthly in 2004 +weekly from oct +weekly from last month +from sep to oct +from 10/1 to 10/5 +monthly until 2005 +from apr +until nov +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 + |