diff options
| -rw-r--r-- | doc/ledger3.texi | 369 | ||||
| -rwxr-xr-x | test/DocTests.py | 48 |
2 files changed, 240 insertions, 177 deletions
diff --git a/doc/ledger3.texi b/doc/ledger3.texi index cd9fbc59..d0b1ab54 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -291,7 +291,7 @@ finance programs use ``categories'', Ledger uses accounts. So, for example, if you buy some groceries at Trader Joe's then more groceries at Whole Foods Markets you might assign the transactions like this -@smallexample +@smallexample @c input:validate 2011/03/15 Trader Joe's Expenses:Groceries $100.00 Assets:Checking @@ -692,7 +692,7 @@ where the money comes from and where it goes to. For example, when you are paid a salary, you must add money to your bank account and also subtract it from an income account: -@smallexample +@smallexample @c input:validate 9/29 My Employer Assets:Checking $500.00 Income:Salary $-500.00 @@ -831,7 +831,7 @@ This is fairly easy to do in ledger. When spending the money, spend it @emph{to} your Assets:Reimbursements, using a different account for each person or business that you spend money for. For example: -@smallexample +@smallexample @c input:validate 2004/09/29 Circuit City Assets:Reimbursements:Company XYZ $100.00 Liabilities:MasterCard @@ -842,7 +842,7 @@ expense was made on behalf of Company XYZ. Later, when Company XYZ pays the amount back, the money will transfer from that reimbursement account back to a regular asset account: -@smallexample +@smallexample @c input:validate 2004/09/29 Company XYZ Assets:Checking $100.00 Assets:Reimbursements:Company XYZ @@ -864,7 +864,7 @@ company accounts. But keeping them in one file involves the same kinds of postings, so those are what is shown here. First, the personal transaction, which shows the need for reimbursement: -@smallexample +@smallexample @c input:validate 2004/09/29 Circuit City Assets:Reimbursements:Company XYZ $100.00 Liabilities:MasterCard @@ -876,7 +876,7 @@ transaction should be immediately followed by an equivalent transaction, which shows the kind of expense, and also notes the fact that $100.00 is now payable to you: -@smallexample +@smallexample @c input:validate 2004/09/29 Circuit City Company XYZ:Expenses:Computer:Software $100.00 Company XYZ:Accounts Payable:Your Name @@ -889,7 +889,7 @@ paid back. These two transactions can also be merged, to make things a little clearer. Note that all amounts must be specified now: -@smallexample +@smallexample @c input:validate 2004/09/29 Circuit City Assets:Reimbursements:Company XYZ $100.00 Liabilities:MasterCard $-100.00 @@ -903,7 +903,7 @@ paying it to accounts payable, and then drawing it again from the reimbursement account, and paying it to your personal asset account. It's easier shown than said: -@smallexample +@smallexample @c input:validate 2004/10/15 Company XYZ Assets:Checking $100.00 Assets:Reimbursements:Company XYZ $-100.00 @@ -1383,7 +1383,6 @@ list them as you would normally, for example: Liabilities:Credit Card $-50.00 (Funds:School) $-100.00 @end smallexample -@c TODO: Is the following section still relevant / correct? ledger seems to have lost --code-as-payee The second way of tracking funds is to use transaction codes. In this respect the codes become like virtual accounts that embrace the entire @@ -1391,11 +1390,15 @@ set of postings. Basically, we are associating a transaction with a fund by setting its code. Here are two transactions that deposit money into, and spend money from, the @samp{Funds:School} fund: -@smallexample +@smallexample @c input:AD068BA 2004/03/25 (Funds:School) Donations Assets:Checking $100.00 Income:Donations +2004/03/25 (Funds:Teachers) Donations + Assets:Checking $20.00 + Income:Donations + 2004/04/25 (Funds:School) Payment for books Expenses:Books $50.00 Assets:Checking @@ -1405,7 +1408,7 @@ Note how the accounts now relate only to the real accounts, and any balance or registers reports will reflect this. That the transactions relate to a particular fund is kept only in the code. -@findex --code-as-payee +@findex --payee=code @findex --by-payee How does this become a fund report? By using the @option{--code-as-payee} option, you can generate a register report @@ -1415,15 +1418,24 @@ terribly interesting; but when combined with the @option{--by-payee related to a specific fund. So, to see the current monetary balances of all funds, the command would be: -@smallexample -$ ledger --code-as-payee -P reg ^Assets +@smallexample @c command:AD068BA +$ ledger --payee=code -P reg ^Assets @end smallexample -Or to see a particular funds expenses, the @samp{School} fund in this +@smallexample @c output:AD068BA +04-Mar-25 Funds:School Assets:Checking $50.00 $50.00 +04-Mar-25 Funds:Teachers Assets:Checking $20.00 $70.00 +@end smallexample + +Or to see a particular fund's expenses, the @samp{School} fund in this case: -@smallexample -$ ledger --code-as-payee -P reg ^Expenses @@School +@smallexample @c command:E30B2FC,with_input:AD068BA +$ ledger --payee=code -P reg ^Expenses and code School +@end smallexample + +@smallexample @c output:E30B2FC +04-Apr-25 Funds:School Expenses:Books $50.00 $50.00 @end smallexample Both approaches yield different kinds of flexibility, depending on how @@ -1482,7 +1494,7 @@ posting. Here is the Pacific Bell example from above, given as a Ledger posting, with the additional of a check number: -@smallexample +@smallexample @c input:validate 9/29 (1023) Pacific Bell Expenses:Utilities:Phone $23.00 Assets:Checking $-23.00 @@ -1494,7 +1506,7 @@ work better with Ledger's scheme of things. In fact, since Ledger is smart about many things, you don't need to specify the balanced amount, if it is the same as the first line: -@smallexample +@smallexample @c input:validate 9/29 (1023) Pacific Bell Expenses:Utilities:Phone $23.00 Assets:Checking @@ -1536,7 +1548,7 @@ basis of the opening entry for ledger. For example if you chose the beginning of 2011 as the date to start tracking finances with ledger, your opening balance entry could look like this: -@smallexample +@smallexample @c input:validate 2011/01/01 * Opening Balance Assets:Joint Checking $800.14 Assets:Other Checking $63.44 @@ -1598,7 +1610,7 @@ beginning of a line: @samp{#}, @samp{|}, and @samp{*} and @samp{%}. Block comments can be made by use @code{comment} ... @code{end comment}. -@smallexample +@smallexample @c input:validate ; This is a single line comment, # and this, % and this, @@ -1613,7 +1625,7 @@ end comment There are several forms of comments within a transaction, for example: -@smallexample +@smallexample @c input:validate ; this is a global comment that is not applied to a specific transaction ; it can start with any of the five characters but is not included in the ; output from 'print' or 'output' @@ -1712,7 +1724,7 @@ Commodity names can have any character, including white-space. However, if you include white-space or numeric characters the commodity name must be enclosed in double quotes @samp{"}: -@smallexample +@smallexample @c input:validate 1999/06/09 ! Achat Actif:SG PEE STK 49.957 "Arcancia Équilibre 454" Actif:SG PEE STK $-234.90 @@ -1732,22 +1744,22 @@ multiple commodities in the same transaction. The type of the share unit you made the purchase in ($ for AAPL). Yes, the typical convention is as follows: -@smallexample +@smallexample @c input:validate 2004/05/01 Stock purchase Assets:Broker 50 AAPL @@ $30.00 Expenses:Broker:Commissions $19.95 - Assets:Broker $-1,500.00 + Assets:Broker $-1,519.95 @end smallexample This assumes you have a brokerage account that is capable of managed both liquid and commodity assets. Now, on the day of the sale: -@smallexample +@smallexample @c input:validate 2005/08/01 Stock sale Assets:Broker -50 APPL @{$30.00@} @@ $50.00 Expenses:Broker:Commissions $19.95 Income:Capital Gains $-1,000.00 - Assets:Broker $2,500.00 + Assets:Broker $2,480.05 @end smallexample @noindent @@ -1778,7 +1790,7 @@ reported in terms of today's price. This is supported as follows: -@smallexample +@smallexample @c input:validate 2009/01/01 Shell Expenses:Gasoline 11 GAL @{=$2.299@} Assets:Checking @@ -1792,7 +1804,7 @@ If you do not want price fixing, you can specify this same transaction in one of two ways, both equivalent (note the lack of the equal sign from the transaction above): -@smallexample +@smallexample @c input:validate 2009/01/01 Shell Expenses:Gasoline 11 GAL @{$2.299@} Assets:Checking @@ -1805,7 +1817,7 @@ from the transaction above): There is no difference in meaning between these two forms. Why do both exist, you ask? To support things like this: -@smallexample +@smallexample @c input:validate 2009/01/01 Shell Expenses:Gasoline 11 GAL @{=$2.299@} @@ $2.30 Assets:Checking @@ -2124,7 +2136,7 @@ Pre-declare valid account names. This only has effect if they immediately follow the account directive and if they begin with whitespace: -@smallexample +@smallexample @c input:validate account Expenses:Food note This account is all about the chicken! alias food @@ -2148,7 +2160,7 @@ provides regexes that identify the account if that payee is encountered and an account within its transaction ends in the name "Unknown". Example: -@smallexample +@smallexample @c input:validate 2012-02-27 KFC Expenses:Unknown $10.00 ; Read now as "Expenses:Food" Assets:Cash @@ -2177,7 +2189,7 @@ and all business account with @samp{business:}. You can easily split out large groups of transaction without manually editing them using the account directive. For example: -@smallexample +@smallexample @c input:validate apply account Personal 2011/11/15 Supermarket Expenses:Groceries $ 50.00 @@ -2193,7 +2205,7 @@ until an @samp{end apply account} directive was found. Define an alias for an account name. If you have a deeply nested tree of accounts, it may be convenient to define an alias, for example: -@smallexample +@smallexample @c input:94A99E8 alias Dining=Expenses:Entertainment:Dining alias Checking=Assets:Credit Union:Joint Checking Account @@ -2206,11 +2218,19 @@ The aliases are only in effect for transactions read in after the alias is defined and are affected by @code{account} directives that precede them. +@smallexample @c command:94A99E8 +$ ledger bal --no-total ^Exp +@end smallexample + +@smallexample @c output:94A99E8 + $10.00 Expenses:Entertainment:Dining +@end smallexample + With the option @option{--recursive-aliases}, aliases can refer to other aliases, the following example produces exactly the same transactions and account names as the preceding one: -@smallexample +@smallexample @c input:83E1FB3 alias Entertainment=Expenses:Entertainment alias Dining=Entertainment:Dining alias Checking=Assets:Credit Union:Joint Checking Account @@ -2220,6 +2240,14 @@ alias Checking=Assets:Credit Union:Joint Checking Account Checking @end smallexample +@smallexample @c command:83E1FB3 +$ ledger balance --no-total --recursive-aliases ^Exp +@end smallexample + +@smallexample @c output:83E1FB3 + $10.00 Expenses:Entertainment:Dining +@end smallexample + The option @option{--no-aliases} completely disables alias expansion. @item assert @@ -2242,7 +2270,7 @@ automatically generate an additional posting to the bucket account balancing the transaction. The following example set the @samp{Assets:Checking} as the bucket: -@smallexample +@smallexample @c input:validate bucket Assets:Checking 2011/01/25 Tom's Used Cars Expenses:Auto $ 5,500.00 @@ -2262,7 +2290,7 @@ bucket Assets:Checking Directs Ledger to replace any account matching a regex with the given account. For example: -@smallexample +@smallexample @c input:validate capture Expenses:Deductible:Medical Medical @end smallexample @@ -2289,7 +2317,7 @@ Start a block comment, closed by @code{end comment}. Pre-declare commodity names. This only has effect if @option{--strict} or @option{--pedantic} is used (see below). -@smallexample +@smallexample @c input:validate commodity $ commodity CAD @end smallexample @@ -2298,7 +2326,7 @@ The @code{commodity} directive supports several optional sub-directives, if they immediately follow the commodity directive and if they begin with whitespace: -@smallexample +@smallexample @c input:validate commodity $ note American Dollars format $1,000.00 @@ -2323,7 +2351,7 @@ The @code{default} directive marks this as the ``default'' commodity. @c instance_t::define_directive in textual.cc Allows you to define value expression for future use. For example: -@smallexample +@smallexample @c input:validate define var_name=$100 2011/12/01 Test @@ -2349,21 +2377,21 @@ use when entering many transactions with fixated prices. Thus, the following: -@smallexample +@smallexample @c input:validate fixed CAD $0.90 - 2012-04-10 Lunch in Canada - Assets:Wallet -15.50 CAD - Expenses:Food 15.50 CAD +2012-04-10 Lunch in Canada + Assets:Wallet -15.50 CAD + Expenses:Food 15.50 CAD - 2012-04-11 Second day Dinner in Canada - Assets:Wallet -25.75 CAD - Expenses:Food 25.75 CAD +2012-04-11 Second day Dinner in Canada + Assets:Wallet -25.75 CAD + Expenses:Food 25.75 CAD endfixed @end smallexample is equivalent to this: -@smallexample +@smallexample @c input:validate 2012-04-10 Lunch in Canada Assets:Wallet -15.50 CAD @{=$0.90@} Expenses:Food 15.50 CAD @{=$0.90@} @@ -2394,7 +2422,7 @@ The @code{payee} directive supports one optional sub-directive, if it immediately follows the payee directive and if it begins with whitespace: -@smallexample +@smallexample @c input:validate payee KFC alias KENTUCKY FRIED CHICKEN @end smallexample @@ -2415,7 +2443,7 @@ Ledger will display the mapped payees in @command{print} and Allows you to designate a block of transactions and assign the same tag to all. Tags can have values and may be nested. -@smallexample +@smallexample @c input:validate apply tag hastag apply tag nestedtag: true @@ -2428,34 +2456,34 @@ apply tag nestedtag: true Expenses:Books $20.00 Liabilities:MasterCard -end apply tag nestedtag +end apply tag 2011/12/01 Sale Assets:Checking:Business $ 30.00 Income:Sales -end apply tag hastag +end apply tag @end smallexample @noindent is the equivalent of: -@smallexample +@smallexample @c input:validate 2011/01/25 Tom's Used Cars - :hastag: - nestedtag: true + ; :hastag: + ; nestedtag: true Expenses:Auto $ 5,500.00 ; :nobudget: Assets:Checking 2011/01/27 Book Store - :hastag: - nestedtag: true + ; :hastag: + ; nestedtag: true Expenses:Books $20.00 Liabilities:MasterCard 2011/12/01 Sale - :hastag: + ; :hastag: Assets:Checking:Business $ 30.00 Income:Sales @end smallexample @@ -2468,7 +2496,7 @@ track. Pre-declares tag names. This only has effect if @option{--strict} or @option{--pedantic} is used (see below). -@smallexample +@smallexample @c input:validate tag Receipt tag CSV @end smallexample @@ -2477,7 +2505,7 @@ The @code{tag} directive supports two optional sub-directives, if they immediately follow the tag directive and if they begin with whitespace: -@smallexample +@smallexample @c input:validate tag Receipt check value =~ /pattern/ assert value != "foobar" @@ -2538,7 +2566,7 @@ whichever is seen last is used as the default commodity. For example, to set US dollars as the default commodity, while also setting the thousands flag and decimal flag for that commodity, use: -@smallexample +@smallexample @c input:validate D $1,000.00 @end smallexample @@ -2547,7 +2575,7 @@ Specifies a commodity conversion, where the first amount is given to be equivalent to the second amount. The first amount should use the decimal precision desired during reporting: -@smallexample +@smallexample @c input:validate C 1.00 Kb = 1024 bytes @end smallexample @@ -2673,7 +2701,7 @@ doing it. The most basic form of transaction is: -@smallexample +@smallexample @c input:validate 2012-03-10 KFC Expenses:Food $20.00 Assets:Cash $-20.00 @@ -2685,7 +2713,7 @@ posting specifies what action is taken related to that account. A transaction can have any number of postings: -@smallexample +@smallexample @c input:validate 2012-03-10 KFC Expenses:Food $20.00 Assets:Cash $-10.00 @@ -2699,7 +2727,7 @@ The first thing you can do to make things easier is elide amounts. That is, if exactly one posting has no amount specified, Ledger will infer the inverse of the other postings' amounts: -@smallexample +@smallexample @c input:validate 2012-03-10 KFC Expenses:Food $20.00 Assets:Cash $-10.00 @@ -2711,7 +2739,7 @@ If the other postings use multiple commodities, Ledger will copy the empty posting N times and fill in the negated values of the various commodities: -@smallexample +@smallexample @c input:validate 2012-03-10 KFC Expenses:Food $20.00 Expenses:Tips $2.00 @@ -2723,7 +2751,7 @@ commodities: @noindent This transaction is identical to writing: -@smallexample +@smallexample @c input:validate 2012-03-10 KFC Expenses:Food $20.00 Expenses:Tips $2.00 @@ -2741,7 +2769,7 @@ This transaction is identical to writing: You can associate a second date with a transaction by following the primary date with an equals sign: -@smallexample +@smallexample @c input:validate 2012-03-10=2012-03-08 KFC Expenses:Food $20.00 Assets:Cash $-20.00 @@ -2760,7 +2788,7 @@ only displayed by the print command. Checking accounts often use codes like DEP, XFER, etc., as well as check numbers. This is to give you a place to put those codes: -@smallexample +@smallexample @c input:validate 2012-03-10 (#100) KFC Expenses:Food $20.00 Assets:Checking @@ -2776,7 +2804,7 @@ A transaction can have a ``state'': cleared, pending, or uncleared. The default is uncleared. To mark a transaction cleared, put a * before the payee, and after date or code: -@smallexample +@smallexample @c input:validate 2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash @@ -2785,7 +2813,7 @@ before the payee, and after date or code: @noindent To mark it pending, use a !: -@smallexample +@smallexample @c input:validate 2012-03-10 ! KFC Expenses:Food $20.00 Assets:Cash @@ -2803,7 +2831,7 @@ a reconciliation. When you clear a transaction, that's really just shorthand for clearing all of its postings. That is: -@smallexample +@smallexample @c input:validate 2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash @@ -2812,7 +2840,7 @@ clearing all of its postings. That is: @noindent Is the same as writing: -@smallexample +@smallexample @c input:validate 2012-03-10 KFC * Expenses:Food $20.00 * Assets:Cash @@ -2822,7 +2850,7 @@ Is the same as writing: You can mark individual postings as cleared or pending, in case one ``side'' of the transaction has cleared, but the other hasn't yet: -@smallexample +@smallexample @c input:validate 2012-03-10 KFC Liabilities:Credit $100.00 * Assets:Checking @@ -2835,7 +2863,7 @@ After the payee, and after at least one tab or two spaces (or a space and a tab, which Ledger calls this a ``hard separator''), you may introduce a note about the transaction using the @samp{;} character: -@smallexample +@smallexample @c input:validate 2012-03-10 * KFC ; yum, chicken... Expenses:Food $20.00 Assets:Cash @@ -2845,7 +2873,7 @@ introduce a note about the transaction using the @samp{;} character: Notes can also appear on the next line, so long as that line begins with whitespace: -@smallexample +@smallexample @c input:validate 2012-03-10 * KFC ; yum, chicken... ; and more notes... Expenses:Food $20.00 @@ -2862,7 +2890,7 @@ significant when querying for metadata (see below). To specify that a note belongs only to one posting, place it after a hard separator after the amount, or on its own line preceded by whitespace: -@smallexample +@smallexample @c input:validate 2012-03-10 * KFC Expenses:Food $20.00 ; posting #1 note Assets:Cash @@ -2900,7 +2928,7 @@ The are two forms of metadata: tags and tag/value pairs. To tag an item, put any word not containing whitespace between two colons: -@smallexample +@smallexample @c input:validate 2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash @@ -2909,7 +2937,7 @@ colons: You can gang up multiple tags by sharing colons: -@smallexample +@smallexample @c input:validate 2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash @@ -2936,7 +2964,7 @@ This is useful when for example you deposit 4 checks at a time to the bank. On the bank statement, there is just one amount @samp{$400}, but you can specify from whom each check came from, as shown by example below: -@smallexample +@smallexample @c input:validate 2010-06-17 Sample Assets:Bank $400.00 Income:Check1 $-100.00 ; Payee: Person One @@ -2965,7 +2993,7 @@ To associate a value with a tag, use the syntax ``Key: Value'', where the value can be any string of characters. Whitespace is needed after the colon, and cannot appear in the Key: -@smallexample +@smallexample @c input:validate 2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash @@ -2979,7 +3007,7 @@ If a metadata tag ends in ::, its value will be parsed as a value expression and stored internally as a value rather than as a string. For example, although I can specify a date textually like so: -@smallexample +@smallexample @c input:validate 2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash @@ -3020,7 +3048,7 @@ reports using @option{--real}. To specify a virtual account, surround the account name with parentheses: -@smallexample +@smallexample @c input:validate 2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash @@ -3031,7 +3059,7 @@ If you want, you can state that virtual postings @emph{should} balance against one or more other virtual postings by using brackets (which look ``harder'') rather than parentheses: -@smallexample +@smallexample @c input:validate 2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash @@ -3046,7 +3074,7 @@ An amount is usually a numerical figure with an (optional) commodity, but it can also be any value expression. To indicate this, surround the amount expression with parentheses: -@smallexample +@smallexample @c input:validate 2012-03-10 * KFC Expenses:Food ($10.00 + $20.00) ; Ledger adds it up for you Assets:Cash @@ -3106,7 +3134,7 @@ Say your book-keeping has gotten a bit out of date, and your Ledger balance no longer matches your bank balance. You can create an adjustment transaction using balance assignments: -@smallexample +@smallexample @c input:validate 2012-03-10 Adjustment Assets:Cash = $500.00 Equity:Adjustments @@ -3152,7 +3180,7 @@ In those cases, Ledger will remember the ``cost'' of that transaction for you, and can use it during reporting in various ways. Here's an example of a stock purchase: -@smallexample +@smallexample @c input:validate 2012-03-10 My Broker Assets:Brokerage 10 AAPL Assets:Brokerage:Cash $-500.00 @@ -3168,7 +3196,7 @@ another. The resulting posting cost is $50.00 per share. You can make any posting's cost explicit using the @samp{@@} symbol after the amount or amount expression: -@smallexample +@smallexample @c input:validate 2012-03-10 My Broker Assets:Brokerage 10 AAPL @@ $50.00 Assets:Brokerage:Cash $-500.00 @@ -3177,7 +3205,7 @@ after the amount or amount expression: When you do this, since Ledger can now figure out the balancing amount from the first posting's cost, you can elide the other amount: -@smallexample +@smallexample @c input:validate 2012-03-10 My Broker Assets:Brokerage 10 AAPL @@ $50.00 Assets:Brokerage:Cash @@ -3213,7 +3241,7 @@ flag will never convert a primary commodity into any other commodity. Just as you can have amount expressions, you can have posting expressions: -@smallexample +@smallexample @c input:validate 2012-03-10 My Broker Assets:Brokerage 10 AAPL @@ ($500.00 / 10) Assets:Brokerage:Cash @@ -3221,7 +3249,7 @@ expressions: You can even have both: -@smallexample +@smallexample @c input:validate 2012-03-10 My Broker Assets:Brokerage (5 AAPL * 2) @@ ($500.00 / 10) Assets:Brokerage:Cash @@ -3234,7 +3262,7 @@ The cost figure following the @samp{@@} character specifies the @emph{per-unit} price for the commodity being transferred. If you'd like to specify the total cost instead, use @samp{@@@@}: -@smallexample +@smallexample @c input:validate 2012-03-10 My Broker Assets:Brokerage 10 AAPL @@@@ $500.00 Assets:Brokerage:Cash @@ -3242,7 +3270,7 @@ like to specify the total cost instead, use @samp{@@@@}: Ledger reads this as if you had written: -@smallexample +@smallexample @c input:validate 2012-03-10 My Broker Assets:Brokerage 10 AAPL @@ ($500.00 / 10) Assets:Brokerage:Cash @@ -3257,7 +3285,7 @@ Ledger's internal price history database. To prevent this from happening in the case of an exceptional transaction, surround the @samp{@@} or @samp{@@@@} with parentheses: -@smallexample +@smallexample @c input:validate 2012-03-10 My Brother Assets:Brokerage 1000 AAPL (@@) $1 Income:Gifts Received @@ -3275,7 +3303,7 @@ to show these hidden price figures. For example, consider the stock sale given above: -@smallexample +@smallexample @c input:validate 2012-03-10 My Broker Assets:Brokerage 10 AAPL @@ $50.00 Assets:Brokerage:Cash @@ -3290,7 +3318,7 @@ $5.00 was the price of that exchange. This becomes significant if you later sell that commodity again. For example, you might write this: -@smallexample +@smallexample @c input:validate 2012-04-10 My Broker Assets:Brokerage:Cash Assets:Brokerage -10 AAPL @@ $75.00 @@ -3299,7 +3327,7 @@ example, you might write this: And that would be perfectly fine, but how do you track the capital gains on the sale? It could be done with a virtual posting: -@smallexample +@smallexample @c input:validate 2012-04-10 My Broker Assets:Brokerage:Cash Assets:Brokerage -10 AAPL @@ $75.00 @@ -3335,7 +3363,7 @@ As a shorthand, you can specify the total price instead of the per-share price in doubled braces. This goes well with total costs, but is not required to be used with them: -@smallexample +@smallexample @c input:validate 2012-04-10 My Broker Assets:Brokerage:Cash $750.00 Assets:Brokerage -10 AAPL @{@{$500.00@}@} @@@@ $750.00 @@ -3565,7 +3593,7 @@ same query syntax as the Ledger command line. Consider this posting: -@smallexample +@smallexample @c input:validate 2012-03-10 KFC Expenses:Food $20.00 Assets:Cash @@ -3573,7 +3601,7 @@ Consider this posting: If I write this automated transaction before it in the file: -@smallexample +@smallexample @c input:validate = expr true Foo $50.00 Bar $-50.00 @@ -3582,7 +3610,7 @@ If I write this automated transaction before it in the file: Then the first transaction will be modified during parsing as if I'd written this: -@smallexample +@smallexample @c input:validate 2012-03-10 KFC Expenses:Food $20.00 Foo $50.00 @@ -3619,7 +3647,7 @@ As a special case, if an automated transaction's posting's amount (phew) has no commodity, it is taken as a multiplier upon the matching posting's cost. For example: -@smallexample +@smallexample @c input:validate = expr true Foo 50.00 Bar -50.00 @@ -3631,7 +3659,7 @@ posting's cost. For example: Then the latter transaction turns into this during parsing: -@smallexample +@smallexample @c input:validate 2012-03-10 KFC Expenses:Food $20.00 Foo $1000.00 @@ -3649,7 +3677,7 @@ posting, that expression has access to all the details of the matched posting. For example, you can refer to that posting's amount using the ``amount'' value expression variable: -@smallexample +@smallexample @c input:validate = expr true (Foo) (amount * 2) ; same as just "2" in this case @@ -3660,7 +3688,7 @@ the ``amount'' value expression variable: This becomes: -@smallexample +@smallexample @c input:validate 2012-03-10 KFC Expenses:Food $20.00 (Foo) $40.00 @@ -3675,7 +3703,7 @@ Sometimes want to refer to the account that matched in some way within the automated transaction itself. This is done by using the string $account, anywhere within the account part of the automated posting: -@smallexample +@smallexample @c input:validate = food (Budget:$account) 10 @@ -3686,7 +3714,7 @@ $account, anywhere within the account part of the automated posting: Becomes: -@smallexample +@smallexample @c input:validate 2012-03-10 KFC Expenses:Food $20.00 (Budget:Expenses:Food) $200.00 @@ -3700,7 +3728,7 @@ If the automated transaction has a transaction note, that note is copied (along with any metadata) to every posting that matches the predicate: -@smallexample +@smallexample @c input:validate = food ; Foo: Bar (Budget:$account) 10 @@ -3712,7 +3740,7 @@ predicate: Becomes: -@smallexample +@smallexample @c input:validate 2012-03-10 KFC Expenses:Food $20.00 ; Foo: Bar @@ -3726,7 +3754,7 @@ Becomes: If the automated transaction's posting has a note, that note is carried to the generated posting within the matched transaction: -@smallexample +@smallexample @c input:validate = food (Budget:$account) 10 ; Foo: Bar @@ -3738,7 +3766,7 @@ carried to the generated posting within the matched transaction: Becomes: -@smallexample +@smallexample @c input:validate 2012-03-10 KFC Expenses:Food $20.00 (Budget:Expenses:Food) $200.00 @@ -3774,7 +3802,7 @@ something like @cindex effective date of invoice -@smallexample +@smallexample @c input:validate 2008/01/01=2008/01/14 Client invoice ; estimated date you'll be paid Assets:Accounts Receivable $100.00 Income: Client name @@ -3782,7 +3810,7 @@ something like Then, when you receive the payment, you change it to -@smallexample +@smallexample @c input:validate 2008/01/01=2008/01/15 Client invoice ; actual date money received Assets:Accounts Receivable $100.00 Income: Client name @@ -3791,7 +3819,7 @@ Then, when you receive the payment, you change it to @noindent and add something like -@smallexample +@smallexample @c input:validate 2008/01/15 Client payment Assets:Checking $100.00 Assets:Accounts Receivable @@ -3799,14 +3827,14 @@ and add something like Now -@smallexample +@smallexample @c command:validate $ ledger --begin 2008/01/01 --end 2008/01/14 bal Income @end smallexample @noindent gives you your accrued income in the first two weeks of the year, and -@smallexample +@smallexample @c command:validate $ ledger --effective --begin 2008/01/01 --end 2008/01/14 bal Income @end smallexample @@ -3905,7 +3933,7 @@ much is owed in order to fulfill one's obligation to Huqúqu'lláh. When ready to pay, just write a check to cover the amount shown in @samp{Liabilities:Huququ'llah}. That transaction would look like: -@smallexample +@smallexample @c input:validate 2003/01/01 (101) Baha'i Huqúqu'lláh Trust Liabilities:Huququ'llah $1,000.00 Assets:Checking @@ -3929,6 +3957,7 @@ appear in the balance report only when it exceeds the present day value of 2.22 ounces of gold. This can be accomplished using the command: +@c TODO: fix this @smallexample $ ledger -Q -t "/Liab.*Huquq/?(a/P@{2.22 AU@}<=@{-1.0@}&a):a" bal liab @end smallexample @@ -3938,6 +3967,7 @@ Huqúqu'lláh is reported only if its value exceeds that of 2.22 ounces of gold. If you wish the liability to be reflected in the parent subtotal either way, use this instead: +@c TODO: fix this @smallexample $ ledger -Q -T "/Liab.*Huquq/?(O/P@{2.22 AU@}<=@{-1.0@}&O):O" bal liab @end smallexample @@ -3946,7 +3976,7 @@ In some cases, you may wish to refer to the account of whichever posting matched your automated transaction's value expression. To do this, use the special account name @samp{$account}: -@smallexample +@smallexample @c input:validate = /^Some:Long:Account:Name/ [$account] -0.10 [Savings] 0.10 @@ -4084,9 +4114,12 @@ This second example looks for any account with @samp{Bo}, which is If you want to know exactly how much you have spent in a particular account on a particular payee, the following are equivalent: -@smallexample +@smallexample @c command:validate $ ledger balance Auto:Fuel and Chevron -$ ledger balance --limit "(account=~/Fuel/) & (payee=~/Chev/)" +@end smallexample + +@smallexample @c command:validate +$ ledger balance --limit 'account=~/Fuel/' and 'payee=~/Chev/' @end smallexample @noindent @@ -4099,8 +4132,8 @@ possibilities. If you want to exclude specific accounts from the report, you can exclude multiple accounts with parentheses: -@smallexample -$ ledger bal Expenses and not \(Expenses:Drinks or Expenses:Candy or Expenses:Gifts\) +@smallexample @c command:validate +$ ledger bal Expenses and not (Expenses:Drinks or Expenses:Candy or Expenses:Gifts) @end smallexample @node Controlling Formatting, , Controlling the Accounts and Payees, Balance Reports @@ -4116,8 +4149,9 @@ you want, or interface Ledger with other programs. A query such as the following shows all expenses since last October, sorted by total: +@c TODO: does not validate with @c command:validate, because "last oct" is split at the space @smallexample -$ ledger -b "last oct" -S T bal ^expenses +$ ledger -b "last oct" -f sample.dat -S T bal ^expenses @end smallexample From left to right the options mean: Show transactions since last @@ -4139,7 +4173,7 @@ for all accounts that begin with @samp{expenses}. The following query makes it easy to see monthly expenses, with each month's expenses sorted by the amount: -@smallexample +@smallexample @c command:validate $ ledger -M --period-sort "(amount)" reg ^expenses @end smallexample @@ -4147,7 +4181,7 @@ Now, you might wonder where the money came from to pay for these things. To see that report, add @option{--related (-r)}, which shows the ``related account'' postings: -@smallexample +@smallexample @c command:validate $ ledger -M --period-sort "(amount)" -r reg ^expenses @end smallexample @@ -4157,8 +4191,8 @@ requires the use of a display predicate, since the postings calculated must match @samp{^expenses}, while the postings displayed must match @samp{mastercard}. The command would be: -@smallexample -$ ledger -M -r --display "account =~ /mastercard/" reg ^expenses +@smallexample @c command:validate +$ ledger -M -r --display 'account=~/mastercard/' reg ^expenses @end smallexample This query says: Report monthly subtotals; report the ``related @@ -4168,8 +4202,8 @@ postings matching @samp{^expenses}. This works just as well for report the overall total, too: -@smallexample -$ ledger -s -r --display "account =~ /mastercard/" reg ^expenses +@smallexample @c command:validate +$ ledger -s -r --display "account=~/mastercard/" reg ^expenses @end smallexample The @option{--subtotal (-s)} option subtotals all postings, just as @@ -4232,7 +4266,7 @@ actual balances. For the three instruments listed above, those automatic transactions would look like: -@smallexample +@smallexample @c input:validate ; ; automatic calculations for asset allocation tracking ; @@ -4264,6 +4298,7 @@ the various asset classes how do we get a report that tells us our current allocation? Using the balance command and some tricky formatting! +@c TODO: does not @c command:validate due to multiple lines @smallexample ledger bal Allocation --current --format "\ %-17((depth_spacer)+(partial_account))\ @@ -4553,7 +4588,7 @@ directive to rewrite the @code{payee} field based on some rules. Then you can use the account and its @code{payee} directive to specify the account. I use it like this, for example: -@smallexample +@smallexample @c input:validate payee Aldi alias ^ALDI SUED SAGT DANKE account Aufwand:Einkauf:Lebensmittel @@ -5292,14 +5327,14 @@ instead, precede the regular expression with @samp{payee} or totals for rent, food and movies, but only those whose payee matches Freddie: -@smallexample +@smallexample @c command:validate $ ledger bal rent food movies payee freddie @end smallexample @noindent or -@smallexample +@smallexample @c command:validate $ ledger bal rent food movies @@freddie @end smallexample @@ -5993,8 +6028,8 @@ that date will be ignored. Print the entire line in bold if the given value expression is true (@pxref{Value Expressions}). -@smallexample -$ ledger reg Expenses --begin Dec --bold-if "amount > 100" +@smallexample @c command:validate +$ ledger reg Expenses --begin Dec --bold-if "amount>100" @end smallexample @noindent @@ -6184,7 +6219,7 @@ calculations occur. @itemx --days-of-week Group transactions by the days of the week. -@smallexample +@smallexample @c command:validate $ ledger reg Expenses --dow --collapse @end smallexample @@ -6284,7 +6319,7 @@ Use @code{Expected} amounts in calculations. In the case that you know that amount a transaction should be, but the actual transaction has the wrong value you can use metadata to put in the expected amount: -@smallexample +@smallexample @c input:validate 2012-03-12 Paycheck Income $-990; Expected:: $-1000.00 Checking @@ -6670,7 +6705,7 @@ 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: -@smallexample +@smallexample @c input:validate $ ledger -M --period-sort -At reg ^Expenses @end smallexample @@ -6911,6 +6946,7 @@ 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: +@c TODO: does not @c command:validate due to space in "last month" @smallexample $ ledger -d "d>=[last month]" reg checking @end smallexample @@ -6919,6 +6955,7 @@ The output from this command is very different from the following, whose running total includes only postings from the last month onward: +@c TODO: does not @c command:validate due to space in "last month" @smallexample $ ledger -p "last month" reg checking @end smallexample @@ -7160,7 +7197,7 @@ If no @var{VALUE} property is specified, each posting is assumed to have a default, as if you'd specified a global, automated transaction as follows: -@smallexample +@smallexample @c input:validate = expr true ; VALUE:: market(amount, date, exchange) @end smallexample @@ -7174,7 +7211,7 @@ This definition emulates the present day behavior of @option{--market One thing many people have wanted to do is to fixate the valuation of old European currencies in terms of the Euro after a certain date: -@smallexample +@smallexample @c input:validate = expr commodity == "DM" ; VALUE:: date < [Jun 2008] ? market(amount, date, exchange) : 1.44 EUR @end smallexample @@ -7186,7 +7223,7 @@ past June 2008, use a fixed price for converting Deutsch Mark to Euro. Or how about never re-valuating commodities used in Expenses, since they cannot have a different future value: -@smallexample +@smallexample @c input:validate = /^Expenses:/ ; VALUE:: market(amount, post.date, exchange) @end smallexample @@ -7198,7 +7235,7 @@ the value of @option{--now @var{DATE}} (defaults to today). Or how about valuating miles based on a reimbursement rate during a specific time period: -@smallexample +@smallexample @c input:validate = expr commodity == "miles" and date >= [2007] and date < [2008] ; VALUE:: market($1.05, date, exchange) @end smallexample @@ -7212,7 +7249,7 @@ Note that you can have a valuation expression specific to a particular posting or transaction, by overriding these general defaults using specific meta-data: -@smallexample +@smallexample @c input:validate 2010-12-26 Example Expenses:Food $20 ; Just to be silly, always valuate *these* $20 as 30 DM, no matter what @@ -7232,7 +7269,7 @@ which allows you to report most everything in EUR if you use @samp{-X EUR}, except for certain accounts or postings which should always be valuated in another currency. For example: -@smallexample +@smallexample @c input:validate = /^Assets:Brokerage:CAD$/ ; Always report the value of commodities in this account in ; terms of present day dollars, despite what was asked for @@ -7417,7 +7454,7 @@ period transaction is almost identical to a regular transaction, except that it begins with a tilde and has a period expression in place of a payee. For example: -@smallexample +@smallexample @c input:validate ~ Monthly Expenses:Rent $500.00 Expenses:Food $450.00 @@ -7448,13 +7485,13 @@ Once these period transactions are defined, creating a budget report is as easy as adding @option{--budget} to the command-line. For example, a typical monthly expense report would be: -@smallexample +@smallexample @c command:validate $ ledger --monthly register ^expenses @end smallexample To see the same report balanced against your budget, use: -@smallexample +@smallexample @c command:validate $ ledger --budget --monthly register ^expenses @end smallexample @@ -7463,7 +7500,7 @@ To see all expenses balanced against the budget, use @option{--add-budget}. You can even see only the un-budgeted expenses using @option{--unbudgeted}: -@smallexample +@smallexample @c command:validate $ ledger --unbudgeted --monthly register ^expenses @end smallexample @@ -7478,7 +7515,7 @@ future, such as determining when an account will reach zero. Ledger makes this easy to do, using the same period transactions as are used for budgeting. An example forecast report can be generated with: -@smallexample +@smallexample @c command:validate $ ledger --forecast "T>@{\$-500.00@}" register ^assets ^liabilities @end smallexample @@ -7489,7 +7526,7 @@ show you what the total afterwards would be. Forecasting can also be used with the balance report, but by date only, and not against the running total: -@smallexample +@smallexample @c command:validate $ ledger --forecast "d<[2010]" bal ^assets ^liabilities @end smallexample @@ -7499,7 +7536,7 @@ $ ledger --forecast "d<[2010]" bal ^assets ^liabilities Ledger directly supports ``timelog'' entries, which have this form: -@smallexample +@smallexample @c input:validate i 2013/03/28 22:13:00 ACCOUNT[ PAYEE] o 2013/03/29 03:39:00 @end smallexample @@ -7556,7 +7593,7 @@ addition to a set of functions and variables. @c a display predicate that I use with the @command{balance} command: @c @smallexample -@c ledger -d /^Liabilities/?T<0:UT>100 balance +@c ledger -d '/^Liabilities/?T<0:UT>100' balance @c @end smallexample @c The effect is that account totals are displayed only if: 1) A @@ -8453,7 +8490,7 @@ Ledger data exists in one of two forms: raw and cooked. Raw objects are what you get from a traversal like the above, and represent exactly what was seen in the data file. Consider this journal: -@smallexample +@smallexample @c input:validate = true (Assets:Cash) $100 @@ -8464,7 +8501,7 @@ was seen in the data file. Consider this journal: In this case, the @emph{raw} regular transaction in this file is: -@smallexample +@smallexample @c input:validate 2012-03-01 KFC Expenses:Food $100 Assets:Credit @@ -8472,7 +8509,7 @@ In this case, the @emph{raw} regular transaction in this file is: While the @emph{cooked} form is: -@smallexample +@smallexample @c input:validate 2012-03-01 KFC Expenses:Food $100 Assets:Credit $-100 @@ -8813,7 +8850,7 @@ one or more @dfn{postings}, which describe how @dfn{amounts} flow from one @dfn{account} to another. Here is an example of the simplest of journal files: -@smallexample +@smallexample @c input:validate 2010/05/31 Just an example Expenses:Some:Account $100.00 Income:Another:Account @@ -8837,7 +8874,7 @@ It is also typical, though not enforced, to think of the first posting as the destination, and the final as the source. Thus, the amount of the first posting is typically positive. Consider: -@smallexample +@smallexample @c input:validate 2010/05/31 An income transaction Assets:Checking $1,000.00 Income:Salary @@ -8885,7 +8922,7 @@ spaces between the end of the post and the beginning of the amount In the simplest form, bare decimal numbers are accepted: -@smallexample +@smallexample @c input:validate 2010/05/31 An income transaction Assets:Checking 1000.00 Income:Salary @@ -8992,10 +9029,10 @@ amount for a posting. But what if the amount you paid for something was in one commodity, and the amount received was another? There are two main ways to express this: -@smallexample +@smallexample @c input:validate 2010/05/31 Farmer's Market Assets:My Larder 100 apples - Assets:Checking $20.00 + Assets:Checking -$20.00 @end smallexample In this example, you have paid twenty dollars for one hundred apples. @@ -9003,7 +9040,7 @@ The cost to you is twenty cents per apple, and Ledger calculates this implied cost for you. You can also make the cost explicit using a @dfn{cost amount}: -@smallexample +@smallexample @c input:validate 2010/05/31 Farmer's Market Assets:My Larder 100 apples @@ $0.200000 Assets:Checking @@ -9014,7 +9051,7 @@ amount; and since cost amount are @emph{unobserved}, the use of six decimal places has no effect on how dollar amounts are displayed in the final report. You can also specify the @dfn{total cost}: -@smallexample +@smallexample @c input:validate 2010/05/31 Farmer's Market Assets:My Larder 100 apples @@@@ $20 Assets:Checking @@ -9024,7 +9061,7 @@ These three forms have identical meaning. In most cases the first is preferred, but the second two are necessary when more than two postings are involved: -@smallexample +@smallexample @c input:validate 2010/05/31 Farmer's Market Assets:My Larder 100 apples @@ $0.200000 Assets:My Larder 100 pineapples @@ $0.33 @@ -9047,10 +9084,10 @@ to buy and sells units of the other commodity. In the fruit examples above, dollars are the primary commodity. This is decided by Ledger on the placement of the commodity in the transaction: -@smallexample +@smallexample @c input:validate 2010/05/31 Sample Transaction Expenses 100 secondary - Assets 50 primary + Assets -50 primary 2010/05/31 Sample Transaction Expenses 100 secondary @@ 0.5 primary @@ -9387,7 +9424,7 @@ The following journal file is included with the source distribution of ledger. It is called @file{drewr.dat} and exhibits many ledger features, include automatic and virtual transactions, -@smallexample +@smallexample @c input:validate ; -*- ledger -*- = /^Income/ @@ -9485,7 +9522,7 @@ $ ledger register Checking --sort d -d 'd>[2011/04/01]' until 2011/05/25 @node Ledger Files, , Invoking Ledger, Cookbook @subsection Ledger Files -@smallexample +@smallexample @c input:validate = /^Income:Taxable/ (Liabilities:Tithe Owed) -0.1 = /Noah/ diff --git a/test/DocTests.py b/test/DocTests.py index cc540aa9..d2931686 100755 --- a/test/DocTests.py +++ b/test/DocTests.py @@ -22,6 +22,7 @@ class DocTests: self.testin_token = 'command' self.testout_token = 'output' self.testdat_token = 'input' + self.validate_token = 'validate' self.testwithdat_token = 'with_input' def read_example(self): @@ -31,14 +32,14 @@ class DocTests: line = self.file.readline() self.current_line += 1 if len(line) <= 0 or endexample.match(line): break - example += line + example += line.replace("@@","@").replace("@{","{").replace("@}","}") return example def test_id(self, example): return hashlib.sha1(example.rstrip()).hexdigest()[0:7].upper() def find_examples(self): - startexample = re.compile(r'^@smallexample\s+@c\s+(%s|%s|%s)(?::([\dA-Fa-f]+))?(?:,(.*))?' + startexample = re.compile(r'^@smallexample\s+@c\s+(%s|%s|%s)(?::([\dA-Fa-f]+|validate))?(?:,(.*))?' % (self.testin_token, self.testout_token, self.testdat_token)) while True: line = self.file.readline() @@ -67,10 +68,16 @@ class DocTests: test_id = self.test_id(example) if test_kind == self.testin_token: print >> sys.stderr, 'Use', self.test_id(example) - elif test_kind == self.testin_token and test_id != self.test_id(example): + elif test_kind == self.testin_token and test_id != self.validate_token and test_id != self.test_id(example): print >> sys.stderr, 'Expected test id', test_id, 'for example' \ , test_kind, 'on line', test_begin_line, 'to be', self.test_id(example) + if test_id == self.validate_token: + test_id = "Val-" + str(test_begin_line) + if test_kind == self.testin_token: + test_kind = "validate-command" + elif test_kind == self.testdat_token: + test_kind = "validate-data" try: self.examples[test_id] except KeyError: @@ -91,10 +98,17 @@ class DocTests: } def parse_command(self, test_id, example): + validate_command = False try: command = example[self.testin_token][self.testin_token] except KeyError: - return None + if 'validate-data' in example: + command = '$ ledger bal' + elif 'validate-command' in example: + validate_command = True + command = example['validate-command']['validate-command'] + else: + return None command = command.rstrip().split() if command[0] == '$': command.remove('$') @@ -110,12 +124,18 @@ class DocTests: except ValueError: findex = index+1 command.insert(findex, '--file') - command.insert(findex+1, test_id + '.dat') + if validate_command: + command.insert(findex+1, 'sample.dat') + else: + command.insert(findex+1, test_id + '.dat') return (command, findex+1) def test_examples(self): failed = set() for test_id in self.examples: + validation = False + if "validate-data" in self.examples[test_id] or "validate-command" in self.examples[test_id]: + validation = True example = self.examples[test_id] try: (command, findex) = self.parse_command(test_id, example) @@ -135,9 +155,12 @@ class DocTests: with_input = example[self.testin_token]['opts'][self.testwithdat_token] input = self.examples[with_input][self.testdat_token][self.testdat_token] except KeyError: - input = None + try: + input = example['validate-data']['validate-data'] + except KeyError: + input = None - if command and output: + if command and (output or validation): test_file_created = False if findex: scriptpath = os.path.dirname(os.path.realpath(__file__)) @@ -150,11 +173,13 @@ class DocTests: f.write(input) elif os.path.exists(test_input_dir + test_file): command[findex] = test_input_dir + test_file + error = False try: verify = subprocess.check_output(command) except: verify = str() - valid = (output == verify) + error = True + valid = (output == verify) or (not error and validation) if valid and test_file_created: os.remove(test_file) if self.verbose > 0: @@ -166,9 +191,10 @@ class DocTests: failed.add(test_id) if self.verbose > 1: print ' '.join(command) - for line in unified_diff(output.split('\n'), verify.split('\n'), fromfile='generated', tofile='expected'): - print(line) - print + if not validation: + for line in unified_diff(output.split('\n'), verify.split('\n'), fromfile='generated', tofile='expected'): + print(line) + print if not self.verbose: print if len(failed) > 0: |