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

Mainly moving @code to @samp when relevant (when valued example)

Browse source
This commit is contained in:
thdox 2013-05-20 16:16:31 +02:00
parent 43fed282a0
commit 11befb67aa
1 changed files with 208 additions and 210 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

418
doc/ledger3.texi
View file

@ -13,8 +13,9 @@
@c | @option | @findex | Ledger CLI Option (like --market) | @c | @option | @findex | Ledger CLI Option (like --market) |
@c | @var | | Ledger CLI option Variable (like -f FILE) | @c | @var | | Ledger CLI option Variable (like -f FILE) |
@c | | | Ledger file Syntax | @c | | | Ledger file Syntax |
@c | @samp | | Example | @c | @samp | | Valued example or single char |
@c | @file | | Program (like ledger, report, head) | @c | @file | | File |
@c | @file | | Program (like ledger, report, acprep) |
@c Restructuring manual ideas @c Restructuring manual ideas
@c http://beyondgrep.com/documentation/ack-2.04-man.html @c http://beyondgrep.com/documentation/ack-2.04-man.html
@ -225,9 +226,9 @@ at Whole Foods Markets you might assign the transactions like this
Assets:Checking Assets:Checking
@end smallexample @end smallexample
In both cases the money goes to the ``Groceries'' account, even though In both cases the money goes to the @samp{Groceries} account, even
the payees were different. You can set up your accounts in any way you though the payees were different. You can set up your accounts in any
choose. way you choose.
Enter the beauty of computerized accounting. The purpose of the Enter the beauty of computerized accounting. The purpose of the
Ledger program is to make general journal accounting simple, by Ledger program is to make general journal accounting simple, by
@ -462,7 +463,7 @@ $ ledger -f drewr3.dat register Groceries
@end smallexample @end smallexample
@noindent @noindent
Which matches the balance reported for the @code{Groceries} account: Which matches the balance reported for the @samp{Groceries} account:
@smallexample @smallexample
$ ledger -f drewr3.dat balance Groceries $ ledger -f drewr3.dat balance Groceries
@ -629,8 +630,8 @@ account, such as when you get paid. Here is a typical transaction:
Income:Salary Income:Salary
@end smallexample @end smallexample
Money, here, comes from an Income account belonging to ``My Money, here, comes from an Income account belonging to @samp{My
Employer'', and is transferred to your checking account. The money is Employer}, and is transferred to your checking account. The money is
now yours, which makes it an Asset. now yours, which makes it an Asset.
Liabilities track money owed to others. This can happen when you Liabilities track money owed to others. This can happen when you
@ -678,7 +679,7 @@ $ ledger -M register expenses:auto
@end smallexample @end smallexample
This assumes, of course, that you use account names like This assumes, of course, that you use account names like
@code{Expenses:Auto:Gas} and @code{Expenses:Auto:Repair}. @samp{Expenses:Auto:Gas} and @samp{Expenses:Auto:Repair}.
@menu @menu
* Tracking reimbursable expenses:: * Tracking reimbursable expenses::
@ -688,11 +689,11 @@ This assumes, of course, that you use account names like
@subsection Tracking reimbursable expenses @subsection Tracking reimbursable expenses
@cindex reimbursable expense tracking @cindex reimbursable expense tracking
Sometimes you will want to spend money on behalf of someone else, Sometimes you will want to spend money on behalf of someone else, which
which will eventually get repaid. Since the money is still ``yours'', will eventually get repaid. Since the money is still @emph{yours}, it
it is really an asset. And since the expenditure was for someone is really an asset. And since the expenditure was for someone else, you
else, you don't want it contaminating your Expenses reports. You will don't want it contaminating your Expenses reports. You will need to
need to keep an account for tracking reimbursements. keep an account for tracking reimbursements.
This is fairly easy to do in ledger. When spending the money, spend This is fairly easy to do in ledger. When spending the money, spend
it @emph{to} your Assets:Reimbursements, using a different account for it @emph{to} your Assets:Reimbursements, using a different account for
@ -778,12 +779,12 @@ It's easier shown than said:
Company XYZ:Assets:Checking $-100.00 Company XYZ:Assets:Checking $-100.00
@end smallexample @end smallexample
And now the reimbursements account is paid off, accounts payable is And now the reimbursements account is paid off, accounts payable is paid
paid off, and $100.00 has been effectively transferred from the off, and $100.00 has been effectively transferred from the company's
company's checking account to your personal checking account. The checking account to your personal checking account. The money simply
money simply ``waited''---in both @code{Assets:Reimbursements:Company ``waited''---in both @samp{Assets:Reimbursements:Company XYZ}, and
XYZ}, and @code{Company XYZ:Accounts Payable:Your Name}---until such @samp{Company XYZ:Accounts Payable:Your Name}---until such time as it
time as it could be paid off. could be paid off.
The value of tracking expenses from both sides like that is that you The value of tracking expenses from both sides like that is that you
do not contaminate your personal expense report with expenses made on do not contaminate your personal expense report with expenses made on
@ -965,7 +966,7 @@ or days, it should be possible to convert between the various forms.
Doing this requires the use of commodity equivalencies. Doing this requires the use of commodity equivalencies.
For example, you might have the following two postings, one which For example, you might have the following two postings, one which
transfers an hour of time into a @code{Billable} account, and another transfers an hour of time into a @samp{Billable} account, and another
which decreases the same account by ten minutes. The resulting report which decreases the same account by ten minutes. The resulting report
will indicate that fifty minutes remain: will indicate that fifty minutes remain:
@ -1005,7 +1006,7 @@ In the above example, kilobytes are reported with two decimal places
of precision and each kilobyte is equal to 1024 bytes. of precision and each kilobyte is equal to 1024 bytes.
Equivalency chains can be as long as desired. Whenever a commodity Equivalency chains can be as long as desired. Whenever a commodity
would report as a decimal amount (less than @code{1.00}), the next would report as a decimal amount (less than @samp{1.00}), the next
smallest commodity is used. If a commodity could be reported in terms smallest commodity is used. If a commodity could be reported in terms
of a higher commodity without resulting to a partial fraction, then of a higher commodity without resulting to a partial fraction, then
the larger commodity is used. the larger commodity is used.
@ -1030,8 +1031,8 @@ EverQuest account:
Now your EverQuest:Inventory has 3 apples and 5 steaks in it. The Now your EverQuest:Inventory has 3 apples and 5 steaks in it. The
amounts are negative, because you are taking @emph{from} Black's amounts are negative, because you are taking @emph{from} Black's
Tavern in order to add to your Inventory account. Note that you don't Tavern in order to add to your Inventory account. Note that you don't
have to use @code{Places:Black's Tavern} as the source account. You have to use @samp{Places:Black's Tavern} as the source account. You
could use @code{EverQuest:System} to represent the fact that you could use @samp{EverQuest:System} to represent the fact that you
acquired them online. The only purpose for choosing one kind of acquired them online. The only purpose for choosing one kind of
source account over another is for generate more informative reports source account over another is for generate more informative reports
later on. The more you know, the better analysis you can perform. later on. The more you know, the better analysis you can perform.
@ -1097,7 +1098,7 @@ a few large ones, as with checks.
One solution is: don't bother. Move your spending to a debit card, One solution is: don't bother. Move your spending to a debit card,
but in general ignore cash. Once you withdraw it from the ATM, mark but in general ignore cash. Once you withdraw it from the ATM, mark
it as already spent to an @code{Expenses:Cash} category: it as already spent to an @samp{Expenses:Cash} category:
@smallexample @smallexample
2004/03/15 ATM 2004/03/15 ATM
@ -1106,8 +1107,8 @@ it as already spent to an @code{Expenses:Cash} category:
@end smallexample @end smallexample
If at some point you make a large cash expense that you want to track, If at some point you make a large cash expense that you want to track,
just ``move'' the amount of the expense from @code{Expenses:Cash} into just @emph{move} the amount of the expense from @samp{Expenses:Cash}
the target account: into the target account:
@smallexample @smallexample
2004/03/20 Somebody 2004/03/20 Somebody
@ -1146,8 +1147,8 @@ reserves resources for later:
The problem with this kind of setup is that when you spend money, it The problem with this kind of setup is that when you spend money, it
comes from two or more places at once: the account and the fund. And comes from two or more places at once: the account and the fund. And
yet, the correlation of amounts between funds and accounts is rarely yet, the correlation of amounts between funds and accounts is rarely
one-to-one. What if the school fund has @code{$500.00}, but one-to-one. What if the school fund has @samp{$500.00}, but
@code{$400.00} of that comes from Checking, and @code{$100.00} from @samp{$400.00} of that comes from Checking, and @samp{$100.00} from
Savings? Savings?
Traditional finance packages require that the money reside in only one Traditional finance packages require that the money reside in only one
@ -1185,7 +1186,7 @@ account:
When reports are generated, by default they'll appear in terms of the When reports are generated, by default they'll appear in terms of the
funds. In this case, you will likely want to mask out your funds. In this case, you will likely want to mask out your
@code{Assets} account, because otherwise the balance won't make much @samp{Assets} account, because otherwise the balance won't make much
sense: sense:
@smallexample @smallexample
@ -1327,7 +1328,7 @@ amount, if it is the same as the first line:
@end smallexample @end smallexample
For this transaction, Ledger will figure out that $-23.00 must come For this transaction, Ledger will figure out that $-23.00 must come
from @code{Assets:Checking} in order to balance the transaction. from @samp{Assets:Checking} in order to balance the transaction.
Also note the structure of the account entries. There is an implied Also note the structure of the account entries. There is an implied
hierarchy established by separating with colons (@pxref{Structuring your hierarchy established by separating with colons (@pxref{Structuring your
@ -1724,7 +1725,7 @@ account Expenses:Food5
value myfunc_five value myfunc_five
@end smallexample @end smallexample
The metadata field @code{Value}, if found, overrides the valuation The metadata field @samp{Value}, if found, overrides the valuation
function on a transaction-wide or per-posting basis. function on a transaction-wide or per-posting basis.
@smallexample @smallexample
@ -1991,8 +1992,8 @@ Sets the root for all accounts following the directive. Ledger
supports a hierarchical tree of accounts. It may be convenient to supports a hierarchical tree of accounts. It may be convenient to
keep two ``root accounts''. For example you may be tracking your keep two ``root accounts''. For example you may be tracking your
personal finances and your business finances. In order to keep them personal finances and your business finances. In order to keep them
separate you could preface all personal accounts with @code{personal:} separate you could preface all personal accounts with @samp{personal:}
and all business account with @code{business:}. You can easily split and all business account with @samp{business:}. You can easily split
out large groups of transaction without manually editing them using out large groups of transaction without manually editing them using
the account directive. For example: the account directive. For example:
@ -2004,8 +2005,8 @@ apply account Personal
@end smallexample @end smallexample
Would result in all postings going into Would result in all postings going into
@code{Personal:Expenses:Groceries} and @code{Personal:Assets:Checking} @samp{Personal:Expenses:Groceries} and @samp{Personal:Assets:Checking}
until and @code{end apply account} directive was found. until and @samp{end apply account} directive was found.
@item alias @item alias
@c instance_t::alias_directive @c instance_t::alias_directive
@ -2043,7 +2044,7 @@ amount and automatically calculate balance the transaction in the
posting. The @code{bucket} allows you to fill in all postings and posting. The @code{bucket} allows you to fill in all postings and
automatically generate an additional posting to the bucket account automatically generate an additional posting to the bucket account
balancing the transaction. The following example set the balancing the transaction. The following example set the
@code{Assets:Checking} as the bucket: @samp{Assets:Checking} as the bucket:
@smallexample @smallexample
bucket Assets:Checking bucket Assets:Checking
@ -2263,7 +2264,7 @@ is the equivalent of:
Income:Sales Income:Sales
@end smallexample @end smallexample
Note that anything following ``@code{end tag}'' is ignored. placing Note that anything following @code{end apply tag} is ignored. placing
the name of the tag that is being closed is a simple way to keep the name of the tag that is being closed is a simple way to keep
track. track.
@ -3760,8 +3761,8 @@ $ ledger balance -f drewr3.dat Auto MasterCard
@end smallexample @end smallexample
@noindent @noindent
note the implicit logical and between @code{Auto} and note the implicit logical and between @samp{Auto} and
@code{Mastercard}. @samp{Mastercard}.
If you want the entire contents of a branch of your account tree, use If you want the entire contents of a branch of your account tree, use
the highest common name in the branch: the highest common name in the branch:
@ -3784,9 +3785,9 @@ $ ledger balance -f drewr3.dat Bo
$ 20.00 Expenses:Books $ 20.00 Expenses:Books
@end smallexample @end smallexample
The first example looks for any account starting with ``Bo'', of which The first example looks for any account starting with @samp{Bo}, of
there are none. The second looks for any account with ``Bo'', which is which there are none. The second looks for any account with @samp{Bo},
@code{Expenses:Books}. which is @samp{Expenses:Books}.
@cindex limit by payees @cindex limit by payees
@findex --limit @var{EXPR} @findex --limit @var{EXPR}
@ -3833,7 +3834,7 @@ $ ledger -b "last oct" -s -S T bal ^expenses
From left to right the options mean: Show transactions since last From left to right the options mean: Show transactions since last
October; show all sub-accounts; sort by the absolute value of the October; show all sub-accounts; sort by the absolute value of the
total; and report the balance for all accounts that begin with total; and report the balance for all accounts that begin with
``expenses''. @samp{expenses}.
@menu @menu
* Reporting monthly expenses:: * Reporting monthly expenses::
@ -3865,8 +3866,8 @@ $ ledger -M --period-sort "(amount)" -r reg ^expenses
But maybe this prints too much information. You might just want to But maybe this prints too much information. You might just want to
see how much you're spending with your MasterCard. That kind of query see how much you're spending with your MasterCard. That kind of query
requires the use of a display predicate, since the postings requires the use of a display predicate, since the postings
calculated must match @code{^expenses}, while the postings calculated must match @samp{^expenses}, while the postings
displayed must match @code{mastercard}. The command would be: displayed must match @samp{mastercard}. The command would be:
@smallexample @smallexample
$ ledger -M -r --display "account =~ /mastercard/" reg ^expenses $ ledger -M -r --display "account =~ /mastercard/" reg ^expenses
@ -3874,8 +3875,8 @@ $ ledger -M -r --display "account =~ /mastercard/" reg ^expenses
This query says: Report monthly subtotals; report the ``related This query says: Report monthly subtotals; report the ``related
account'' postings; display only related postings whose account'' postings; display only related postings whose
account matches @code{mastercard}, and base the calculation on account matches @samp{mastercard}, and base the calculation on
postings matching @code{^expenses}. postings matching @samp{^expenses}.
This works just as well for report the overall total, too: This works just as well for report the overall total, too:
@ -4134,9 +4135,9 @@ column, respectively.
The @command{print} command prints out ledger transactions in a textual The @command{print} command prints out ledger transactions in a textual
format that can be parsed by Ledger. 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 and output in the most economic form possible. The @command{print}
also takes a list of optional regexes, which will cause only those command also takes a list of optional regexes, which will cause only
postings which match in some way to be printed. those postings which match in some way to be printed.
The @command{print} command can be a handy way to clean up a ledger The @command{print} command can be a handy way to clean up a ledger
file whose formatting has gotten out of hand. file whose formatting has gotten out of hand.
@ -4242,7 +4243,7 @@ occurs in the first column of the data use:
transid,date,payee,note,amount,,,code, transid,date,payee,note,amount,,,code,
@end smallexample @end smallexample
Ledger will include @code{; transid: 767718} in the first transaction Ledger will include @samp{; transid: 767718} in the first transaction
is from the file above. is from the file above.
@findex --invert @findex --invert
@ -4651,7 +4652,7 @@ examples of more complex operations with a ledger.
@subsection The @command{pricemap} command @subsection The @command{pricemap} command
@findex pricemap @findex pricemap
If you have the @code{graphviz} graph visualization package installed, If you have the @file{graphviz} graph visualization package installed,
ledger can generate a graph of the relationship between your various ledger can generate a graph of the relationship between your various
commodities. The output file is in the ``dot'' format. commodities. The output file is in the ``dot'' format.
@ -4706,7 +4707,7 @@ both contain whatever text the user wishes.
After the initial transaction data, there must follow a set of postings After the initial transaction data, there must follow a set of postings
marked with @code{en:postings}. Typically these postings will all marked with @code{en:postings}. Typically these postings will all
balance each other, but if not they will be automatically balanced into balance each other, but if not they will be automatically balanced into
an account named @code{<Unknown>}. an account named @samp{Unknown}.
Within the @code{en:postings} tag is a series of one or more Within the @code{en:postings} tag is a series of one or more
@code{posting}'s, which have the following form: @code{posting}'s, which have the following form:
@ -4907,7 +4908,7 @@ Say you currently have this posting in your ledger file:
Liabilities:MasterCard $-15.00 Liabilities:MasterCard $-15.00
@end smallexample @end smallexample
Now it's @code{2004/4/9}, and you've just eating at @code{Viva Italiano} 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 again. The exact amounts are different, but the overall form is the
same. With the @command{xact} command you can type: same. With the @command{xact} command you can type:
@ -4925,7 +4926,7 @@ This produces the following output:
@end smallexample @end smallexample
It works by finding a past posting matching the regular expression It works by finding a past posting matching the regular expression
@code{viva}, and assuming that any accounts or amounts specified will be @samp{viva}, and assuming that any accounts or amounts specified will be
similar to that earlier posting. If Ledger does not succeed in similar to that earlier posting. If Ledger does not succeed in
generating a new transaction, an error is printed and the exit code is generating a new transaction, an error is printed and the exit code is
set to @samp{1}. set to @samp{1}.
@ -6036,9 +6037,9 @@ Synonym for @samp{--period "monthly"}.
Suppress any color TTY output. Suppress any color TTY output.
@item --no-rounding @item --no-rounding
Don't output <Rounding> postings. Note that this will cause the running Don't output @samp{<Rounding>} postings. Note that this will cause the
total to often not add up! It's main use is for @option{--amount-data running total to often not add up! It's main use is for
(-j)} and @option{--total-data (-J)} reports. @option{--amount-data (-j)} and @option{--total-data (-J)} reports.
@item --no-titles @item --no-titles
Suppress the output of group titles. Suppress the output of group titles.
@ -6156,11 +6157,11 @@ FIX THIS ENTRY @c FIXME thdox
@item --related @item --related
In a register report show the related account. This is the other In a register report show the related account. This is the other
``side'' of the transaction. @emph{side} of the transaction.
@item --related-all @item --related-all
Show all postings in a transaction, similar to @option{--related} but Show all postings in a transaction, similar to @option{--related} but
show both ``sides'' of each transaction. show both @emph{sides} of each transaction.
@item --revalued @item --revalued
FIX THIS ENTRY FIX THIS ENTRY
@ -6353,7 +6354,7 @@ Set the reporting period to @var{STR}. This will subtotal all matching
transactions within each period separately, making it easy to see transactions within each period separately, making it easy to see
weekly, monthly, quarterly, etc., posting totals. A period string can weekly, monthly, quarterly, etc., posting totals. A period string can
even specify the beginning and end of the report range, using simple even specify the beginning and end of the report range, using simple
terms like ``last June'' or ``next month''. For more using period terms like @samp{last June} or @samp{next month}. For more using period
expressions, see @ref{Period Expressions}. expressions, see @ref{Period Expressions}.
@item --period-sort @var{VEXPR} @item --period-sort @var{VEXPR}
@ -6516,7 +6517,7 @@ Include even empty accounts in the @command{balance} report.
@itemx -W @itemx -W
Report posting totals by the week. The week begins on whichever day of Report posting totals by the week. The week begins on whichever day of
the week begins the month containing that posting. To set a specific the week begins the month containing that posting. To set a specific
begin date, use a period string, such as @code{weekly from DATE}. begin date, use a period string, such as @samp{weekly from DATE}.
@item --monthly @item --monthly
@itemx -M @itemx -M
@ -6623,7 +6624,7 @@ reporting range (using @option{--display @var{EXPR} (-d)}).
@item --date-format @var{DATE_FORMAT} @item --date-format @var{DATE_FORMAT}
@itemx -y @var{DATE_FORMAT} @itemx -y @var{DATE_FORMAT}
Change the basic date format used by reports. The default uses a date Change the basic date format used by reports. The default uses a date
like @code{2004/08/01}, which represents the default date format of like @samp{2004/08/01}, which represents the default date format of
@code{%Y/%m/%d}. To change the way dates are printed in general, the @code{%Y/%m/%d}. To change the way dates are printed in general, the
easiest way is to put @option{--date-format @var{DATE_FORMAT}} in the easiest way is to put @option{--date-format @var{DATE_FORMAT}} in the
Ledger initialization file @file{~/.ledgerrc} (or the file referred to Ledger initialization file @file{~/.ledgerrc} (or the file referred to
@ -6637,7 +6638,7 @@ each report type:
@item --balance-format @var{FORMAT_STRING} @item --balance-format @var{FORMAT_STRING}
Define the output format for the @command{balance} report. The default Define the output format for the @command{balance} report. The default
(defined in @code{report.h} is: (defined in @file{report.h} is:
@smallexample @smallexample
"%(ansify_if( "%(ansify_if(
@ -6670,7 +6671,7 @@ Define the format for the cleared report. The default is:
@item --register-format @var{FORMAT_STRING} @item --register-format @var{FORMAT_STRING}
Define the output format for the @command{register} report. The default Define the output format for the @command{register} report. The default
(defined in @code{report.h} is: (defined in @file{report.h} is:
@smallexample @smallexample
"%(ansify_if( "%(ansify_if(
@ -6845,11 +6846,11 @@ When you specify @option{--market (-V)}, or @option{--exchange
@var{COMMODITY} (-X)}, you are requesting that some or all of the @var{COMMODITY} (-X)}, you are requesting that some or all of the
commodities be valuated as of today (or whatever @option{--now commodities be valuated as of today (or whatever @option{--now
@var{DATE}} is set to). But what does such a valuation mean? This @var{DATE}} is set to). But what does such a valuation mean? This
meaning is governed by the presence of a @code{VALUE} meta-data meaning is governed by the presence of a @var{VALUE} meta-data property,
property, whose content is an expression used to compute that value. whose content is an expression used to compute that value.
If no VALUE property is specified, each posting is assumed to have a If no @var{VALUE} property is specified, each posting is assumed to have
default, as if you'd specified a global, automated transaction as a default, as if you'd specified a global, automated transaction as
follows: follows:
@smallexample @smallexample
@ -6960,9 +6961,10 @@ these values:
@itemize @itemize
@item Register Report @item Register Report
For the register report, use the value of that commodity on the date For the register report, use the value of that commodity on the date of
of the posting being reported, with a <Revalued> posting added at the the posting being reported, with a @samp{<Revalued>} posting added at
end of today's value is different from the value of the last posting. the end of today's value is different from the value of the last
posting.
@item Balance Report @item Balance Report
For the balance report, use the value of that commodity as of today. For the balance report, use the value of that commodity as of today.
@ -7059,7 +7061,7 @@ last week
The beginning and ending can be given at the same time, if it spans a 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 single period. In that case, just use @var{SPEC} by itself. In that
case, the period @code{oct}, for example, will cover all the days in case, the period @samp{oct}, for example, will cover all the days in
October. The possible forms are: October. The possible forms are:
@smallexample @smallexample
@ -7509,7 +7511,7 @@ precedence order of operators.
@item [DATE] @item [DATE]
Useful specifying a date in plain terms. For example, you could say Useful specifying a date in plain terms. For example, you could say
@code{[2004/06/01]}. @samp{[2004/06/01]}.
@end table @end table
@ -7681,14 +7683,14 @@ specified, the current report style's value expression is used.
@item (EXPR) @item (EXPR)
Inserts the amount resulting from the value expression given in Inserts the amount resulting from the value expression given in
parentheses. To insert five times the total value of an account, for parentheses. To insert five times the total value of an account, for
example, one could say @code{%12(5*O)}. Note: It's important to put the 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 five first in that expression, so that the commodity doesn't get
stripped from the total. stripped from the total.
@item [DATEFMT] @item [DATEFMT]
Inserts the result of formatting a posting's date with a date Inserts the result of formatting a posting's date with a date
format string, exactly like those supported by @code{strftime}. For format string, exactly like those supported by @code{strftime}. For
example: @code{%[%Y/%m/%d %H:%M:%S]}. example: @samp{%[%Y/%m/%d %H:%M:%S]}.
@item S @item S
Insert the pathname of the file from which the transaction's data was Insert the pathname of the file from which the transaction's data was
@ -8057,7 +8059,7 @@ justified and padded to the full width of the field. If
Replaces line feeds in @code{STR} with @samp{\n}. Replaces line feeds in @code{STR} with @samp{\n}.
@item quoted(STR) @item quoted(STR)
Return @code{STR} surrounded by double quotes, @code{"STR"}. Return @code{STR} surrounded by double quotes, @samp{"STR"}.
@item strip(value) @item strip(value)
Values can have numerous annotations, such as effective dates and lot Values can have numerous annotations, such as effective dates and lot
@ -8140,9 +8142,9 @@ for xact in ledger.read_journal("sample.dat").xacts:
@node Raw vs. Cooked, Queries, Basic data traversal, Extending with Python @node Raw vs. Cooked, Queries, Basic data traversal, Extending with Python
@section Raw vs. Cooked @section Raw vs. Cooked
Ledger data exists in one of two forms: raw and cooked. Raw objects Ledger data exists in one of two forms: raw and cooked. Raw objects are
are what you get from a traversal like the above, and represent what you get from a traversal like the above, and represent exactly what
exactly what was seen in the data file. Consider this journal: was seen in the data file. Consider this journal:
@smallexample @smallexample
= true = true
@ -8182,10 +8184,10 @@ for post in ledger.read_journal("sample.dat").query("food"):
print "Transferring %s to/from %s" % (post.amount, post.account) print "Transferring %s to/from %s" % (post.amount, post.account)
@end smallexample @end smallexample
The reason why queries iterate over postings instead of transactions The reason why queries iterate over postings instead of transactions is
is that queries often return only a ``slice'' of the transactions they that queries often return only a ``slice'' of the transactions they
apply to. You can always get at a matching posting's transaction by apply to. You can always get at a matching posting's transaction by
looking at its ``xact'' member: looking at its @code{xact} member:
@smallexample @smallexample
last_xact = None last_xact = None
@ -8198,20 +8200,19 @@ for post in ledger.read_journal("sample.dat").query(""):
@end smallexample @end smallexample
This query ends up reporting every cooked posting in the Journal, but This query ends up reporting every cooked posting in the Journal, but
does it transaction-wise. It relies on the fact that an unsorted does it transaction-wise. It relies on the fact that an unsorted report
report returns postings in the exact order they were parsed from the returns postings in the exact order they were parsed from the journal
journal file. file.
@node Queries, Embedded Python, Raw vs. Cooked, Extending with Python @node Queries, Embedded Python, Raw vs. Cooked, Extending with Python
@section Queries @section Queries
The Journal.query() method accepts every argument you can specify on The Journal.query() method accepts every argument you can specify on the
the command-line, including @option{--options}. command-line, including @option{--options}.
Since a query ``cooks'' the journal it applies to, only one query may Since a query ``cooks'' the journal it applies to, only one query may be
be active for that journal at a given time. Once the query object is active for that journal at a given time. Once the query object is gone
gone (after the for loop), then the data reverts back to its raw (after the for loop), then the data reverts back to its raw state.
state.
@node Embedded Python, Amounts, Queries, Extending with Python @node Embedded Python, Amounts, Queries, Extending with Python
@section Embedded Python @section Embedded Python
@ -8234,8 +8235,8 @@ tag PATH
Assets:Cash Assets:Cash
@end smallexample @end smallexample
Any Python functions you define this way become immediately available Any Python functions you define this way become immediately available as
as valexpr functions. valexpr functions.
@node Amounts, , Embedded Python, Extending with Python @node Amounts, , Embedded Python, Extending with Python
@section Amounts @section Amounts
@ -8278,88 +8279,88 @@ Those tiers are:
@item Utility code @item Utility code
There's lots of general utility in Ledger for doing time parsing, There's lots of general utility in Ledger for doing time parsing, using
using Boost.Regex, error handling, etc. It's all done in a way that Boost.Regex, error handling, etc. It's all done in a way that can be
can be reused in other projects as needed. reused in other projects as needed.
@item Commoditized Amounts (amount_t, commodity_t and friends) @item Commoditized Amounts (amount_t, commodity_t and friends)
An numerical abstraction combining multi-precision rational numbers An numerical abstraction combining multi-precision rational numbers (via
(via GMP) with commodities. These structures can be manipulated like GMP) with commodities. These structures can be manipulated like regular
regular numbers in either C++ or Python (as Amount objects). numbers in either C++ or Python (as Amount objects).
@item Commodity Pool @item Commodity Pool
Commodities are all owned by a commodity pool, so that future parsing Commodities are all owned by a commodity pool, so that future parsing of
of amounts can link to the same commodity and established a consistent amounts can link to the same commodity and established a consistent
price history and record of formatting details. price history and record of formatting details.
@item Balances @item Balances
Adds the concept of multiple amounts with varying commodities. Adds the concept of multiple amounts with varying commodities. Supports
Supports simple arithmetic, and multiplication and division with simple arithmetic, and multiplication and division with non-commoditized
non-commoditized values. values.
@item Price history @item Price history
Amounts have prices, and these are kept in a data graph which the Amounts have prices, and these are kept in a data graph which the amount
amount code itself is only dimly aware of (there's three points of code itself is only dimly aware of (there's three points of access so an
access so an amount can query its revalued price on a given date). amount can query its revalued price on a given date).
@item Values @item Values
Often the higher layers in Ledger don't care if something is an amount Often the higher layers in Ledger don't care if something is an amount
or a balance, they just want to add stuff to it or print it. For or a balance, they just want to add stuff to it or print it. For this,
this, I created a type-erasure class, value_t/Value, into which many I created a type-erasure class, value_t/Value, into which many things
things can be stuffed and then operated on. They can contain amounts, can be stuffed and then operated on. They can contain amounts,
balances, dates, strings, etc. If you try to apply an operation balances, dates, strings, etc. If you try to apply an operation between
between two values that makes no sense (like dividing an amount by two values that makes no sense (like dividing an amount by a balance),
a balance), an error occurs at runtime, rather than at compile-time an error occurs at runtime, rather than at compile-time (as would happen
(as would happen if you actually tried to divide an @code{amount_t} by if you actually tried to divide an @code{amount_t} by
a @code{balance_t}). a @code{balance_t}).
This is the core data type for the value expression language. This is the core data type for the value expression language.
@item Value expressions @item Value expressions
The next layer up adds functions and operators around the Value The next layer up adds functions and operators around the Value concept.
concept. This lets you apply transformations and tests to Values at This lets you apply transformations and tests to Values at runtime
runtime without having to bake it into C++. The set of functions without having to bake it into C++. The set of functions available is
available is defined by each object type in Ledger (posts, accounts, defined by each object type in Ledger (posts, accounts, transactions,
transactions, etc.), though the core engine knows nothing about these. etc.), though the core engine knows nothing about these. At its base,
At its base, it only knows how to apply operators to values, and how it only knows how to apply operators to values, and how to pass them to
to pass them to and receive them from functions. and receive them from functions.
@item Query expressions @item Query expressions
Expressions can be onerous to type at the command-line, so there's Expressions can be onerous to type at the command-line, so there's
a shorthand for reporting called ``query expressions''. These add no a shorthand for reporting called ``query expressions''. These add no
functionality of their own, but are purely translated from the input functionality of their own, but are purely translated from the input
string (cash) down to the corresponding value expression string (cash) down to the corresponding value expression @samp{(account
@code{(account =~ /cash/)}. This is a convenience layer. =~ /cash/)}. This is a convenience layer.
@item Format strings @item Format strings
Format strings let you interpolate value expressions into string, with Format strings let you interpolate value expressions into string, with
the requirement that any interpolated value have a string the requirement that any interpolated value have a string
representation. Really all this does is calculate the value representation. Really all this does is calculate the value expression
expression in the current report context, call the resulting value's in the current report context, call the resulting value's
@code{to_string()} method, and stuffs the result into the output @code{to_string()} method, and stuffs the result into the output string.
string. It also provides printf-like behavior, such as min/max width, It also provides printf-like behavior, such as min/max width, right/left
right/left justification, etc. justification, etc.
@item Journal items @item Journal items
Next is a base type shared by anything that can appear in a journal: Next is a base type shared by anything that can appear in a journal: an
an item_t. It contains details common to all such parsed entities, item_t. It contains details common to all such parsed entities, like
like what file and line it was found on, etc. what file and line it was found on, etc.
@item Journal posts @item Journal posts
The most numerous object found in a Journal, postings are a type of The most numerous object found in a Journal, postings are a type of item
item that contain an account, an amount, a cost, and metadata. There that contain an account, an amount, a cost, and metadata. There are
are some other complications, like the account can be marked virtual, some other complications, like the account can be marked virtual, the
the amount could be an expression, etc. amount could be an expression, etc.
@item Journal transactions @item Journal transactions
@ -8371,8 +8372,8 @@ transaction is queried to see if it can provide it.
@item Journal accounts @item Journal accounts
Postings are also shared by accounts, though the actual memory is Postings are also shared by accounts, though the actual memory is
managed by the transaction. Each account knows all the postings managed by the transaction. Each account knows all the postings within
within it, but contains relatively little information of its own. it, but contains relatively little information of its own.
@item The Journal object @item The Journal object
@ -8383,15 +8384,15 @@ querying ad reporting on your data.
@item Textual journal parser @item Textual journal parser
There is a textual parser, wholly contained in textual.cc, which knows There is a textual parser, wholly contained in textual.cc, which knows
how to parse text into journal objects, which then get ``finalized'' how to parse text into journal objects, which then get ``finalized'' and
and added to the journal. Finalization is the step that enforces the added to the journal. Finalization is the step that enforces the
double-entry guarantee. double-entry guarantee.
@item Iterators @item Iterators
Every journal object is ``iterable'', and these iterators are defined Every journal object is ``iterable'', and these iterators are defined in
in iterators.h and iterators.cc. This iteration logic is kept out of iterators.h and iterators.cc. This iteration logic is kept out of the
the basic journal objects themselves for the sake of modularity. basic journal objects themselves for the sake of modularity.
@item Comparators @item Comparators
@ -8401,17 +8402,16 @@ the user passed to @option{--sort @var{VEXPR}}.
@item Temporaries @item Temporaries
Many reports bring pseudo-journal objects into existence, like Many reports bring pseudo-journal objects into existence, like postings
postings which report totals in a @code{<Total>} account. These which report totals in a @samp{Total} account. These objects are
objects are created and managed by a temporaries_t object, which gets created and managed by a temporaries_t object, which gets used in many
used in many places by the reporting filters. places by the reporting filters.
@item Option handling @item Option handling
There is an option handling subsystem used by many of the layers There is an option handling subsystem used by many of the layers further
further down. It makes it relatively easy for me to add new options, down. It makes it relatively easy for me to add new options, and to
and to have those option settings immediately accessible to value have those option settings immediately accessible to value expressions.
expressions.
@item Session objects @item Session objects
@ -8423,10 +8423,10 @@ a separate session. They are all owned by the global scope.
@item Report objects @item Report objects
Every time you create report output, a report object is created to Every time you create report output, a report object is created to
determine what you want to see. In the Ledger REPL, a new report determine what you want to see. In the Ledger REPL, a new report object
object is created every time a command is executed. In CLI mode, only is created every time a command is executed. In CLI mode, only one
one report object ever comes into being, as Ledger immediately exits report object ever comes into being, as Ledger immediately exits after
after displaying the results. displaying the results.
@item Reporting filters @item Reporting filters
@ -8434,28 +8434,26 @@ The way Ledger generates data is this: it asks the session for the
current journal, and then creates an iterator applied to that journal. current journal, and then creates an iterator applied to that journal.
The kind of iterator depends on the type of report. The kind of iterator depends on the type of report.
This iterator is then walked, and every object yielded from the This iterator is then walked, and every object yielded from the iterator
iterator is passed to an ``item handler'', whose type is directly is passed to an ``item handler'', whose type is directly related to the
related to the type of the iterator. type of the iterator.
There are many, many item handlers, which can be chained together. There are many, many item handlers, which can be chained together. Each
Each one receives an item (post, account, xact, etc.), performs some one receives an item (post, account, xact, etc.), performs some action
action on it, and then passes it down to the next handler in the on it, and then passes it down to the next handler in the chain. There
chain. There are filters which compute the running totals; that queue are filters which compute the running totals; that queue and sort all
and sort all the input items before playing them back out in a new the input items before playing them back out in a new order; that filter
order; that filter out items which fail to match a predicate, etc. out items which fail to match a predicate, etc. Almost every reporting
Almost every reporting feature in Ledger is related to one or more feature in Ledger is related to one or more filters. Looking at
filters. Looking at @code{filters.h}, I see over 25 of them defined @file{filters.h}, I see over 25 of them defined currently.
currently.
@item The filter chain @item The filter chain
How filters get wired up, and in what order, is a complex process How filters get wired up, and in what order, is a complex process based
based on all the various options specified by the user. This is the on all the various options specified by the user. This is the job of
job of the chain logic, found entirely in @code{chain.cc}. It took the chain logic, found entirely in @file{chain.cc}. It took a really
a really long time to get this logic exactly write, which is why long time to get this logic exactly right, which is why I haven't
I haven't exposed this layer to the Python bridge yet. exposed this layer to the Python bridge yet.
@c TODO : correct above ``write'' as ``right'' ?
@item Output modules @item Output modules
@ -8463,16 +8461,16 @@ Although filters are great and all, in the end you want to see stuff.
This is the job of special ``leaf'' filters call output modules. They This is the job of special ``leaf'' filters call output modules. They
are implemented just like a regular filter, but they don't have are implemented just like a regular filter, but they don't have
a ``next'' filter to pass the time on down to. Instead, they are the a ``next'' filter to pass the time on down to. Instead, they are the
end of the line and must do something with the item that results in end of the line and must do something with the item that results in the
the user seeing something on their screen or in a file. user seeing something on their screen or in a file.
@item Select queries @item Select queries
Select queries know a lot about everything, even though they implement Select queries know a lot about everything, even though they implement
their logic by implementing the user's query in terms of all the other their logic by implementing the user's query in terms of all the other
features thus presented. Select queries have no functionality of features thus presented. Select queries have no functionality of their
their own, they are simple a shorthand to provide access to much of own, they are simple a shorthand to provide access to much of Ledger's
Ledger's functionality via a cleaner, more consistent syntax. functionality via a cleaner, more consistent syntax.
@item The Global Scope @item The Global Scope
@ -8484,8 +8482,8 @@ Application object.
@item The Main Driver @item The Main Driver
This creates the global scope object, performs error reporting, and This creates the global scope object, performs error reporting, and
handles command-line options which must precede even the creation of handles command-line options which must precede even the creation of the
the global scope, such as @option{--debug @var{CODE}}. global scope, such as @option{--debug @var{CODE}}.
@end itemize @end itemize
@ -8498,9 +8496,9 @@ etc.
@section Journal File Format for Developers @section Journal File Format for Developers
This chapter offers a complete description of the journal data format, This chapter offers a complete description of the journal data format,
suitable for implementers in other languages to follow. For users, suitable for implementers in other languages to follow. For users, the
the chapter on keeping a journal is less extensive, but more typical chapter on keeping a journal is less extensive, but more typical of
of common usage (@pxref{Keeping a Journal}). common usage (@pxref{Keeping a Journal}).
Data is collected in the form of @dfn{transactions} which occur in one Data is collected in the form of @dfn{transactions} which occur in one
or more @dfn{journal files}. Each transaction, in turn, is made up of or more @dfn{journal files}. Each transaction, in turn, is made up of
@ -8522,15 +8520,15 @@ arbitrary, with no preferences implied, although you will find it useful
to follow standard accounting practice (@pxref{Principles of Accounting to follow standard accounting practice (@pxref{Principles of Accounting
with Ledger}). with Ledger}).
Since an amount is missing from the second posting, it is assumed to Since an amount is missing from the second posting, it is assumed to be
be the inverse of the first. This guarantees the cardinal rule of the inverse of the first. This guarantees the cardinal rule of
double-entry accounting: the sum of every transaction must balance to double-entry accounting: the sum of every transaction must balance to
zero, or it is in error. Whenever Ledger encounters a @dfn{null zero, or it is in error. Whenever Ledger encounters a @dfn{null
posting} in a transaction, it uses it to balance the remainder. posting} in a transaction, it uses it to balance the remainder.
It is also typical, though not enforced, to think of the first It is also typical, though not enforced, to think of the first posting
posting as the destination, and the final as the source. Thus, the as the destination, and the final as the source. Thus, the amount of
amount of the first posting is typically positive. Consider: the first posting is typically positive. Consider:
@smallexample @smallexample
2010/05/31 An income transaction 2010/05/31 An income transaction
@ -8553,9 +8551,9 @@ amount of the first posting is typically positive. Consider:
@subsection Comments and meta-data @subsection Comments and meta-data
Comments are generally started using a @samp{;}. However, in order to Comments are generally started using a @samp{;}. However, in order to
increase compatibility with other text manipulation programs and increase compatibility with other text manipulation programs and methods
methods three additional comment characters are valid if used at the three additional comment characters are valid if used at the beginning
beginning of a line: @samp{#}, @samp{|}, and @samp{*}. of a line: @samp{#}, @samp{|}, and @samp{*}.
@node Specifying Amounts, Posting costs, Comments and meta-data, Journal File Format for Developers @node Specifying Amounts, Posting costs, Comments and meta-data, Journal File Format for Developers
@subsection Specifying Amounts @subsection Specifying Amounts
@ -8587,20 +8585,20 @@ In the simplest form, bare decimal numbers are accepted:
@end smallexample @end smallexample
@cindex uncommoditized amounts @cindex uncommoditized amounts
Such amounts may only use an optional period for a decimal point. Such amounts may only use an optional period for a decimal point. These
These are referred to as @dfn{integer amounts} or @dfn{uncommoditized are referred to as @dfn{integer amounts} or @dfn{uncommoditized
amounts}. In most ways they are similar to @dfn{commoditized amounts}. In most ways they are similar to @dfn{commoditized amounts},
amounts}, but for one significant difference: They always display in but for one significant difference: They always display in reports with
reports with @dfn{full precision}. More on this in a moment. For @dfn{full precision}. More on this in a moment. For now, a word must
now, a word must be said about how Ledger stores numbers. be said about how Ledger stores numbers.
Every number parsed by Ledger is stored internally as an Every number parsed by Ledger is stored internally as an
infinite-precision rational value. Floating-point math is never used, infinite-precision rational value. Floating-point math is never used,
as it cannot be trusted to maintain precision of values. So, in the as it cannot be trusted to maintain precision of values. So, in the
case of @code{1000.00} above, the internal value is @code{100000/100}. case of @samp{1000.00} above, the internal value is @samp{100000/100}.
While rational numbers are great at not losing precision, the question While rational numbers are great at not losing precision, the question
arises: How should they be displayed? A number like @code{100000/100} arises: How should they be displayed? A number like @samp{100000/100}
is no problem, since it represents a clean decimal fraction. But what is no problem, since it represents a clean decimal fraction. But what
about when the number @samp{1/1} is divided by three? How should one about when the number @samp{1/1} is divided by three? How should one
print @samp{1/3}, an infinitely repeating decimal? print @samp{1/3}, an infinitely repeating decimal?
@ -8660,9 +8658,9 @@ part is the commodity.
Another feature of commoditized amounts is that they are reported back Another feature of commoditized amounts is that they are reported back
in the same form as parsed. If you specify dollar amounts using in the same form as parsed. If you specify dollar amounts using
@code{$100}, they will print the same; likewise with @code{100 $} or @samp{$100}, they will print the same; likewise with @samp{100 $} or
@code{$100.000}. You may even use decimal commas, such as @samp{$100.000}. You may even use decimal commas, such as
@code{$100,00}, or thousand-marks, as in @code{$10,000.00}. @samp{$100,00}, or thousand-marks, as in @samp{$10,000.00}.
These display characteristics become associated with the commodity, These display characteristics become associated with the commodity,
with the result being that all amounts of the same commodity are with the result being that all amounts of the same commodity are
@ -8727,7 +8725,7 @@ postings are involved:
Assets:Checking Assets:Checking
@end smallexample @end smallexample
Here the implied cost is @code{$57.00}, which is entered into the null Here the implied cost is @samp{$57.00}, which is entered into the null
posting automatically so that the transaction balances. posting automatically so that the transaction balances.
@node Primary commodities, , Posting costs, Journal File Format for Developers @node Primary commodities, , Posting costs, Journal File Format for Developers
@ -8980,19 +8978,19 @@ This is a debugging command.
@section Ledger Development Environment @section Ledger Development Environment
@menu @menu
* @code{acprep} build configuration tool:: * @file{acprep} build configuration tool::
* Testing Framework:: * Testing Framework::
@end menu @end menu
@node @code{acprep} build configuration tool, Testing Framework, Ledger Development Environment, Ledger Development Environment @node @file{acprep} build configuration tool, Testing Framework, Ledger Development Environment, Ledger Development Environment
@subsection @code{acprep} build configuration tool @subsection @file{acprep} build configuration tool
@node Testing Framework, , @code{acprep} build configuration tool, Ledger Development Environment @node Testing Framework, , @file{acprep} build configuration tool, Ledger Development Environment
@subsection Testing Framework @subsection Testing Framework
Ledger source ships with a fairly complete set of tests to verify that Ledger source ships with a fairly complete set of tests to verify that
all is well, and no old errors have been resurfaced. Tests are run all is well, and no old errors have been resurfaced. Tests are run
individually with @code{ctest}. All tests can be run using @code{make individually with @file{ctest}. All tests can be run using @code{make
check} or @code{ninja check} depending on which build tool you prefer. check} or @code{ninja check} depending on which build tool you prefer.
Once built, the ledger executable resides under the @file{build} Once built, the ledger executable resides under the @file{build}
@ -9021,7 +9019,7 @@ where the regex matches the name of the test you want to build.
There are nearly 300 tests stored under the @file{test} subdirectory There are nearly 300 tests stored under the @file{test} subdirectory
in main source distribution. They are broken into two broad in main source distribution. They are broken into two broad
categories, baseline and regression. To run the @file{5FBF2ED8} test, categories, baseline and regression. To run the @file{5FBF2ED8} test,
for example, issue @code{ctest -V -R "5FB"}. for example, issue @samp{ctest -V -R "5FB"}.
@node Writing Tests, , Running Tests, Testing Framework @node Writing Tests, , Running Tests, Testing Framework
@subsubsection Writing Tests @subsubsection Writing Tests