diff options
Diffstat (limited to 'doc/ledger3.texi')
| -rw-r--r-- | doc/ledger3.texi | 164 |
1 files changed, 121 insertions, 43 deletions
diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 52f6b79f..f60bb26e 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -1312,9 +1312,9 @@ your opening balance entry could look like this: Assets:Joint Checking $800.14 Assets:Other Checking $63.44 Assets:Savings $2805.54 - Assets:Investments:401K:Deferred 100.0000 VIFSX @ $80.5227 - Assets:Investments:401K:Matching 50.0000 VIFSX @ $83.7015 - Assets:Investments:IRA 250.0000 VTHRX @ $20.5324 + Assets:Investments:401K:Deferred 100.0000 VIFSX @@ $80.5227 + Assets:Investments:401K:Matching 50.0000 VIFSX @@ $83.7015 + Assets:Investments:IRA 250.0000 VTHRX @@ $20.5324 Liabilities:Mortgage $-175634.88 Liabilities:Car Loan $-3494.26 Liabilities:Visa -$1762.44 @@ -1814,7 +1814,7 @@ sign. After this initial line there should be a set of one or more postings, just as if it were normal transaction. If the amounts of the postings have no commodity, they will be applied as modifiers to -whichever real posting is matched by the value expression(See @pxref{Automated transactions}). +whichever real posting is matched by the value expression(See @pxref{Automated Transactions}). @item ~ A period transaction. A period expression must appear after the tilde. @@ -2182,7 +2182,7 @@ This is a synonym for @code{comment} and must be closed by an @code{end} tag. @item year @c instance_t::year_directive in textual.cc Denotes the year used for all subsequent transactions that give a date -without a year. The year should appear immediately after the Y, for +without a year. The year should appear immediately after the directive, for example: @code{year 2004}. This is useful at the beginning of a file, to specify the year for that file. If all transactions specify a year, however, this command has no effect. @@ -2542,7 +2542,7 @@ kill the report buffer * Lot dates:: * Lot notes:: * Lot value expressions:: -* Automated transactions:: +* Automated Transactions:: @end menu @node Basic format, Eliding amounts, Transactions , Transactions @@ -2970,12 +2970,12 @@ resulting posting cost is $50.00 per share. @node Explicit posting costs, Posting cost expressions, Posting cost, Transactions @section Explicit posting costs -You can make any posting's cost explicit using the @ symbol after the amount +You can make any posting's cost explicit using the @@ symbol after the amount or amount expression: @smallexample 2012-03-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage 10 AAPL @@ $50.00 Assets:Brokerage:Cash $-500.00 @end smallexample @@ -2984,7 +2984,7 @@ the first posting's cost, you can elide the other amount: @smallexample 2012-03-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage 10 AAPL @@ $50.00 Assets:Brokerage:Cash @end smallexample @@ -3029,7 +3029,7 @@ You can even have both: @node Total posting costs, Virtual posting costs, Posting cost expressions, Transactions @section Total posting costs -The cost figure following the @ character specifies the @emph{per-unit} price for +The cost figure following the @@ character specifies the @emph{per-unit} price for the commodity being transferred. If you'd like to specify the total cost instead, use @@@@: @@ -3149,7 +3149,7 @@ Plus, it comes with dangers. This works fine: @smallexample 2012-04-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage 10 AAPL @@ $50.00 Assets:Brokerage:Cash $750.00 2012-04-10 My Broker @@ -3167,7 +3167,7 @@ Plus, it comes with dangers. This works fine: @smallexample 2012-04-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage 10 AAPL @@ $50.00 Assets:Brokerage:Cash $750.00 2012-04-10 My Broker @@ -3192,7 +3192,7 @@ following two transactions are equivalent: @smallexample 2012-04-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage 10 AAPL @@ $50.00 Assets:Brokerage:Cash $750.00 2012-04-10 My Broker @@ -3257,7 +3257,7 @@ that dates are parsed in value expressions): You can also associate arbitrary notes for your own record keeping in parentheses, and reveal them with --lot-notes. One caveat is that the note -cannot begin with an @ character, as that would indicate a virtual cost: +cannot begin with an @@ character, as that would indicate a virtual cost: @smallexample 2012-04-10 My Broker @@ -3271,7 +3271,7 @@ all optional. To show all lot information in a report, use @code{--lots}. -@node Lot value expressions, Automated transactions, Lot notes, Transactions +@node Lot value expressions, Automated Transactions, Lot notes, Transactions @section Lot value expressions Normally when you ask Ledger to display the values of commodities held, it @@ -3338,8 +3338,8 @@ In most cases, it is simplest to either use explicit amounts in your valuation expressions, or just pass the arguments down to market after modifying them to suit your needs. -@node Automated transactions, , Lot value expressions, Transactions -@section Automated transactions +@node Automated Transactions, , Lot value expressions, Transactions +@section Automated Transactions An automated transaction is a special kind of transaction which adds its postings to other transactions any time one of that other transactions' @@ -3391,9 +3391,10 @@ transaction. * State flags:: * Effective Dates:: * Periodic Transactions:: +* Concrete Example of Automated Transactions:: @end menu -@node Amount multipliers, Accessing the matching posting's amount, Automated transactions, Automated transactions +@node Amount multipliers, Accessing the matching posting's amount, Automated Transactions, Automated Transactions @subsection Amount multipliers As a special case, if an automated transaction's posting's amount (phew) has @@ -3422,7 +3423,7 @@ Then the latter transaction turns into this during parsing: Bar $-1000.00 @end smallexample -@node Accessing the matching posting's amount, Referring to the matching posting's account, Amount multipliers, Automated transactions +@node Accessing the matching posting's amount, Referring to the matching posting's account, Amount multipliers, Automated Transactions @subsection Accessing the matching posting's amount If you use an amount expression for an automated transaction's posting, that @@ -3449,7 +3450,7 @@ This becomes: (Foo) $-40.00 @end smallexample -@node Referring to the matching posting's account, Applying metadata to every matched posting, Accessing the matching posting's amount, Automated transactions +@node Referring to the matching posting's account, Applying metadata to every matched posting, Accessing the matching posting's amount, Automated Transactions @subsection Referring to the matching posting's account Sometimes want to refer to the account that matched in some way within the @@ -3474,7 +3475,7 @@ Becomes: Assets:Cash $-20.00 @end smallexample -@node Applying metadata to every matched posting, Applying metadata to the generated posting, Referring to the matching posting's account, Automated transactions +@node Applying metadata to every matched posting, Applying metadata to the generated posting, Referring to the matching posting's account, Automated Transactions @subsection Applying metadata to every matched posting If the automated transaction has a transaction note, that note is copied @@ -3500,7 +3501,7 @@ Becomes: Assets:Cash $-20.00 @end smallexample -@node Applying metadata to the generated posting, State flags, Applying metadata to every matched posting, Automated transactions +@node Applying metadata to the generated posting, State flags, Applying metadata to every matched posting, Automated Transactions @subsection Applying metadata to the generated posting If the automated transaction's posting has a note, that note is carried to the @@ -3530,14 +3531,14 @@ This is slightly different from the rules for regular transaction notes, in that an automated transaction's note does not apply to every posting within the automated transaction itself, but rather to every posting it matches. -@node State flags, Effective Dates, Applying metadata to the generated posting, Automated transactions +@node State flags, Effective Dates, Applying metadata to the generated posting, Automated Transactions @subsection State flags Although you cannot mark an automated transaction as a whole as cleared or pending, you can mark its postings with a * or ! before the account name, and that state flag gets carried to the generated posting. -@node Effective Dates, Periodic Transactions, State flags, Automated transactions +@node Effective Dates, Periodic Transactions, State flags, Automated Transactions @subsection Effective Dates @cindex effective dates @@ -3604,7 +3605,7 @@ automatic $37.50 deficit like you should, while your checking account really knows that it debited $225 this month. -@node Periodic Transactions, , Effective Dates, Automated transactions +@node Periodic Transactions, Concrete Example of Automated Transactions, Effective Dates, Automated Transactions @subsection Periodic Transactions A periodic transaction starts with a ~ followed by a period expression. @@ -3614,6 +3615,83 @@ have no effect without the @code{--budget} option specified. See @ref{Budgeting and Forecasting} for examples and details. +@node Concrete Example of Automated Transactions, , Periodic Transactions, Automated Transactions +@subsection Concrete Example of Automated Transactions + + +As a Bahá'í, I need to compute Huqúqu'lláh whenever I acquire assets. +It is similar to tithing for Jews and Christians, or to Zakát for +Muslims. The exact details of computing Huqúqu'lláh are somewhat +complex, but if you have further interest, please consult the Web. + +Ledger makes this otherwise difficult law very easy. Just set up an +automated posting at the top of your ledger file: + +@smallexample +; This automated transaction will compute Huqúqu'lláh based on this +; journal's postings. Any that match will affect the +; Liabilities:Huququ'llah account by 19% of the value of that posting. + += /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/ + (Liabilities:Huququ'llah) 0.19 +@end smallexample + +This automated posting works by looking at each posting in the +ledger file. If any match the given value expression, 19% of the +posting's value is applied to the @samp{Liabilities:Huququ'llah} +account. So, if $1000 is earned from @samp{Income:Salary}, $190 is +added to @samp{Liabilities:Huqúqu'lláh}; if $1000 is spent on Rent, +$190 is subtracted. The ultimate balance of Huqúqu'lláh reflects how +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 +2003/01/01 (101) Baha'i Huqúqu'lláh Trust + Liabilities:Huququ'llah $1,000.00 + Assets:Checking +@end smallexample + +That's it. To see how much Huqúq is currently owed based on your +ledger transactions, use: + +@smallexample +ledger balance Liabilities:Huquq +@end smallexample + +This works fine, but omits one aspect of the law: that Huquq is only +due once the liability exceeds the value of 19 mithqáls of gold (which +is roughly 2.22 ounces). So what we want is for the liability to +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: + +@smallexample +ledger -Q -t "/Liab.*Huquq/?(a/P@{2.22 AU@}<=@{-1.0@}&a):a" -s bal liab +@end smallexample + +With this command, the current price for gold is downloaded, and the +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: + +@smallexample +ledger -Q -T "/Liab.*Huquq/?(O/P@{2.22 AU@}<=@{-1.0@}&O):O" -s bal liab +@end smallexample + +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 += /^Some:Long:Account:Name/ + [$account] -0.10 + [Savings] 0.10 +@end smallexample + +This example causes 10% of the matching account's total to be deferred +to the @samp{Savings} account---as a balanced virtual posting, +which may be excluded from reports by using @option{--real}. @@ -4119,7 +4197,7 @@ interpret the dates. Importing csv files is a lot of work, and but is very amenable to scripting. If there are columns in the bank data you would like to keep in your -ledger data, besides the primary fileds described above, you can name +ledger data, besides the primary fields described above, you can name them in the field descriptor list and Ledger will include them in the transaction as meta data if it doesn't recognize the field name. For example, if you want to capture the bank transaction number and it @@ -4131,7 +4209,7 @@ transid,date,payee,note,amount,,,code, @end smallexample Ledger will include @code{; transid: 767718} in the first transaction is -fromthe file above. +from the file above. The @code{convert} command accepts three options, the most important ones are @code{--invert} which inverts the amount field, and @@ -4172,7 +4250,7 @@ directly by EMACS Lisp. The format of the @code{sexp} is: ...) ; list of transactions @end smallexample -@noindent @code{emacs} can also be used as asynonym for @code{lisp} +@noindent @code{emacs} can also be used as a synonym for @code{lisp} @node EMACS org mode, The pricemap Command, The lisp command, Reports in other Formats @subsection EMACS @code{org} Mode @@ -4914,7 +4992,7 @@ model transaction: --- Context is first posting of the following transaction --- 2004/05/27 Book Store ; This note applies to all postings. :SecondTag: - Expenses:Books 20 BOOK @ $10 + Expenses:Books 20 BOOK @@ $10 ; Metadata: Some Value ; Typed:: $100 + $200 ; :ExampleTag: @@ -5595,12 +5673,12 @@ ASK JOHN commodity. The latest available price is used. @item --flat - force the full names of accounts to be used inthe + force the full names of accounts to be used in the balance report. The balance report will not use an indented tree. @item --force-color output tty color codes even if the tty doesn't -support them. Ueful for TTY that don't advertise their capabilities +support them. Useful for TTY that don't advertise their capabilities correctly. @item --force-pager @@ -5707,7 +5785,7 @@ Specify the width of the Meta column used for the @code{--meta} options. @item --monthly -synonymn for @code{--period "monthly"} +synonym for @code{--period "monthly"} @item --no-color @@ -5735,7 +5813,7 @@ This is a postings predicate that applies after certain transforms have been executed, such as periodic gathering. @item --output <PATH> -Redriect the output of ledger to the file defined in @file{PATH}. +Redirect the output of ledger to the file defined in @file{PATH}. @item --pager @@ -5756,8 +5834,8 @@ Set the number of columns dedicated to the payee in the register report. Use only postings that are marked pending @item --percent -Calculate the percentage value of each account in a blance reports. -Only works for account that have a single commoditiy. +Calculate the percentage value of each account in a balance reports. +Only works for account that have a single commodity. @item --period <PERIOD EXPRESSION> @@ -5875,14 +5953,14 @@ FIX THIS ENTRY @item --tail <INT> -report only the last @code{INT} entries. Only useful ona register report. +report only the last @code{INT} entries. Only useful on a register report. @item --total-data FIX THIS ENTRY @item --total <VEXPR> -Define a vlaue expression used to calulate the total in reports. +Define a value expression used to calculate the total in reports. @item --total-width Set the width of the total field in the register report. @@ -5919,14 +5997,14 @@ Perform all calculations without rounding and display results to full precision. @item --weekly -synonymn for @code{--period "weekly"} +synonym for @code{--period "weekly"} @item --wide lets the register report use 132 columns. Identical to @code{--columns "132"} @item --yearly -synonymn for @code{--period "yearly"} +synonym for @code{--period "yearly"} @end table @@ -6375,13 +6453,13 @@ Sets the format for total plots, using the @code{-J} option. The default is: "%(format_date(date, \"%Y-%m-%d\")) %(quantity(scrub(display_total)))\n" @end smallexample @item --pricedb-format STR -Sets the format expected for the histroical price file. The default is +Sets the format expected for the historical price file. The default is @smallexample "P %(datetime) %(display_account) %(scrub(display_amount))\n" @end smallexample @item --prices-format STR -Sets the format for the @command{prices} report. The deault is: +Sets the format for the @command{prices} report. The default is: @smallexample "%(date) %-8(display_account) %(justify(scrub(display_amount), 12, 2 + 9 + 8 + 12, true, color))\n" @@ -7231,7 +7309,7 @@ Inserts the ending line of that transaction within the file. @c @code{%D} gives the user more control over the way dates are output. @item d -Returns the data accoridng to the default format. If the transaction +Returns the data according to the default format. If the transaction has an effective date, it prints @code{[ACTUAL_DATE=EFFECTIVE_DATE]}. @item X @@ -7284,7 +7362,7 @@ same format string is used for all postings. @section --balance-format As an example of how flexible the @code{--format} strings can be, the default -balance format looks like this (the various functions are descirbed later): +balance format looks like this (the various functions are described later): @smallexample "%(justify(scrub(display_total), 20, -1, true, color))" |