From bc35c6c07c62dea99a1b93b3704da5f8ca5023db Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Sun, 2 Oct 2011 21:10:21 -0700 Subject: Ready for first publication --- doc/Ledger3.texi | 3459 +++++++++++++++++++++++++++++------------------------- 1 file changed, 1892 insertions(+), 1567 deletions(-) (limited to 'doc/Ledger3.texi') diff --git a/doc/Ledger3.texi b/doc/Ledger3.texi index ae614f56..d80dc57c 100644 --- a/doc/Ledger3.texi +++ b/doc/Ledger3.texi @@ -214,11 +214,11 @@ formatted as the LEDGER program wishes to see them: The account balances and registers in this file, if saved as @file{ledger.dat}, could be reported using: -@example +@smallexample $ ledger -f ledger.dat balance $ ledger -f ledger.dat register checking -$ ledger -f ledger.dat register bell -@end example +$ ledger -f ledger.dat register Bell +@end smallexample An important difference between LEDGER and other finance packages is that journal will never alter your input file. You can create and edit @@ -237,9 +237,9 @@ make and gcc 3.3, on a PowerBook running OS/X. To build and install once you have these libraries on your system, enter these commands: -@example +@smallexample ./configure && make install -@end example +@end smallexample @node Getting Help, , Building the Program, Introduction to Ledger @section Getting help @@ -247,9 +247,9 @@ enter these commands: If you need help on how to use LEDGER, or run into problems, you can join the LEDGER mailing list at the following Web address: -@example +@smallexample http://groups.google.com/group/ledger-cli -@end example +@end smallexample You can also find help at the @samp{#ledger} channel on the IRC server @samp{irc.freenode.net}. @@ -260,6 +260,7 @@ You can also find help at the @samp{#ledger} channel on the IRC server @menu * Start a Journal:: * Run Some Reports:: +* Command Line Quick Reference:: @end menu @node Start a Journal, Run Some Reports, Ledger Tutorial , Ledger Tutorial @@ -268,23 +269,33 @@ You can also find help at the @samp{#ledger} channel on the IRC server A journal is a record of your financial transactions and will be central to using LEDGER. For now we just want to get a taste of what LEDGER can do. An example journal is included with the source code distribution, -called @file{drewr3.dat} (it is copied in @pxref{Example Data File}). +called @file{drewr3.dat} (@pxref{Example Data File}). Copy it someplace convenient and open up a terminal window in that directory. If you would rather start with your own journal right away please skip to @xref{Keeping a Journal}. -@node Run Some Reports, , Start a Journal, Ledger Tutorial +@node Run Some Reports, Command Line Quick Reference, Start a Journal, Ledger Tutorial @section Run a Few Reports + +@menu +* Balance Report:: +* Register Report:: +* Cleared Report:: +@end menu + +@node Balance Report, Register Report, Run Some Reports, Run Some Reports @subsection Balance Report -Run this command: +To find the balances of all of your accounts, run this command: + @smallexample -ledger -f drewr.dat balance +ledger -f drewr3.dat balance @end smallexample LEDGER will generate: + @smallexample $ -3,804.00 Assets $ 1,396.00 Checking @@ -308,6 +319,237 @@ LEDGER will generate: $ -243.60 @end smallexample +@noindent Showing you the balance of all accounts. Options and search terms can pare this down to show only the accounts you want. + +A more useful report is to show only your Assets and Liabilities: + +@smallexample +$ ledger -f drewr3.dat balance Assets Liabilities + $ -3,804.00 Assets + $ 1,396.00 Checking + $ 30.00 Business + $ -5,200.00 Savings + $ -63.60 Liabilities + $ -20.00 MasterCard + $ 200.00 Mortgage:Principal + $ -243.60 Tithe +-------------------- + $ -3,867.60 +@end smallexample + + +@node Register Report, Cleared Report, Balance Report, Run Some Reports +@subsection Register Report + +To show all transactions and a running total: +@smallexample +ledger -f drewr3.dat register +@end smallexample + +LEDGER will generate: + +@smallexample +10-Dec-01 Checking balance Assets:Checking $ 1,000.00 $ 1,000.00 + Equity:Opening Balances $ -1,000.00 0 +10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50 + Expense:Food:Groceries $ 37.50 $ 75.00 + Expense:Food:Groceries $ 37.50 $ 112.50 + Expense:Food:Groceries $ 37.50 $ 150.00 + Expense:Food:Groceries $ 37.50 $ 187.50 + Expense:Food:Groceries $ 37.50 $ 225.00 + Assets:Checking $ -225.00 0 +10-Dec-28 Acme Mortgage Lia:Mortgage:Principal $ 200.00 $ 200.00 + Expe:Interest:Mortgage $ 500.00 $ 700.00 + Expenses:Escrow $ 300.00 $ 1,000.00 + Assets:Checking $ -1,000.00 0 +11-Jan-02 Grocery Store Expense:Food:Groceries $ 65.00 $ 65.00 + Assets:Checking $ -65.00 0 +11-Jan-05 Employer Assets:Checking $ 2,000.00 $ 2,000.00 + Income:Salary $ -2,000.00 0 + (Liabilities:Tithe) $ -240.00 $ -240.00 +11-Jan-14 Bank Assets:Savings $ 300.00 $ 60.00 + Assets:Checking $ -300.00 $ -240.00 +11-Jan-19 Grocery Store Expense:Food:Groceries $ 44.00 $ -196.00 + Assets:Checking $ -44.00 $ -240.00 +11-Jan-25 Bank Assets:Checking $ 5,500.00 $ 5,260.00 + Assets:Savings $ -5,500.00 $ -240.00 +11-Jan-25 Tom's Used Cars Expenses:Auto $ 5,500.00 $ 5,260.00 + Assets:Checking $ -5,500.00 $ -240.00 +11-Jan-27 Book Store Expenses:Books $ 20.00 $ -220.00 + Liabilities:MasterCard $ -20.00 $ -240.00 +11-Dec-01 Sale Asse:Checking:Business $ 30.00 $ -210.00 + Income:Sales $ -30.00 $ -240.00 + (Liabilities:Tithe) $ -3.60 $ -243.60 +@end smallexample + +@noindent To limit this to a more useful subset, simply add the accounts you are are interested in seeing transactions for: + +@smallexample +$ ledger -f drewr3.dat register Groceries +10-Dec-20 Organic Co-op Expense:Food:Groceries $ 37.50 $ 37.50 + Expense:Food:Groceries $ 37.50 $ 75.00 + Expense:Food:Groceries $ 37.50 $ 112.50 + Expense:Food:Groceries $ 37.50 $ 150.00 + Expense:Food:Groceries $ 37.50 $ 187.50 + Expense:Food:Groceries $ 37.50 $ 225.00 +11-Jan-02 Grocery Store Expense:Food:Groceries $ 65.00 $ 290.00 +11-Jan-19 Grocery Store Expense:Food:Groceries $ 44.00 $ 334.00 +@end smallexample + +@noindent Which matches the balance reported for the @samp{Groceries} account: + +@smallexample +$ ledger -f drewr3.dat balance Groceries + $ 334.00 Expenses:Food:Groceries +@end smallexample + +@node Cleared Report, , Register Report, Run Some Reports +@subsection Cleared Report + +A very useful report is to show what your obligations are versus what +expenditures have actually been recorded. It can take several days for +a check to clear, but you should treat it as money spent. The +@samp{cleared} report shows just that: + +@smallexample +$ ledger -f drewr3.dat cleared + $ -3,804.00 $ 775.00 Assets + $ 1,396.00 $ 775.00 10-Dec-20 Checking + $ 30.00 0 Business + $ -5,200.00 0 Savings + $ -1,000.00 $ -1,000.00 10-Dec-01 Equity:Opening Balances + $ 6,654.00 $ 225.00 Expenses + $ 5,500.00 0 Auto + $ 20.00 0 Books + $ 300.00 0 Escrow + $ 334.00 $ 225.00 10-Dec-20 Food:Groceries + $ 500.00 0 Interest:Mortgage + $ -2,030.00 0 Income + $ -2,000.00 0 Salary + $ -30.00 0 Sales + $ -63.60 0 Liabilities + $ -20.00 0 MasterCard + $ 200.00 0 Mortgage:Principal + $ -243.60 0 Tithe +---------------- ---------------- --------- + $ -243.60 0 +@end smallexample + +@noindent The first column shows the outstanding balance, the second column show the ``cleared'' balance. + +@node Command Line Quick Reference, , Run Some Reports, Ledger Tutorial +@section Command Line Quick Reference + +@menu +* Reporting Commands:: +* Basic Options:: +* Report Filtering:: +* Output Customization:: +* Commodity Reporting:: +@end menu + +@node Reporting Commands, Basic Options, Command Line Quick Reference, Command Line Quick Reference +@subsection Reporting Commands +@multitable @columnfractions .2 .8 +@item @strong{Report} @tab @strong{Description} +@item @code{balance} @tab Show account balances +@item @code{register} @tab Show all transactions with running total +@item @code{print} @tab Print transaction in a ledger readable format +@item @code{output} @tab Similar to print without included transactions +@item @code{xml} @tab Produce XML output of the register command +@item @code{emacs} @tab Produce emacs lisp output +@item @code{equity} @tab Print account balances as transactions +@item @code{prices} @tab Print price history for matching commodities +@item @code{pricesdb} @tab Print price history for matching commodities in ledger readable format +@item @code{xact} @tab Used to generate transactions based on previous postings +@end multitable + +@node Basic Options, Report Filtering, Reporting Commands, Command Line Quick Reference +@subsection Basic Options +@multitable @columnfractions .1 .25 .65 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{-h} @tab @code{--help} @tab prints summary of all options +@item @code{-v} @tab @code{--version} @tab prints version of ledger executable +@item @code{-f FILE} @tab @code{--file FILE} @tab read @file{FILE} as a ledger file +@item @code{-o FILE} @tab @code{--output FILE} @tab redirects output to @file{FILE} +@item @code{-i FILE} @tab @code{--init-file FILE} @tab specify options file +@item @tab @code{--cache FILE} @tab specify binary cache file +@item @code{-a NAME} @tab @code{--account NAME} @tab specify default account name for QIF file postings +@end multitable + +@node Report Filtering, Output Customization, Basic Options, Command Line Quick Reference +@subsection Report Filtering +@multitable @columnfractions .1 .25 .65 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{-c} @tab @code{--current} @tab Display transaction on or before the current date +@item @code{-b DATE} @tab @code{--begin DATE} @tab Begin reports on or after @code{DATE} +@item @code{-e DATE} @tab @code{--end DATE} @tab Limits end date od transactions for report +@item @code{-p STR} @tab @code{--period} @tab Set report period to STR +@item @code{ } @tab @code{--period-sort} @tab Sort postings within each period +@item @code{-C} @tab @code{--cleared} @tab Display only cleared postings +@item @code{-U} @tab @code{--uncleared} @tab Display only uncleared postings +@item @code{-R} @tab @code{--real} @tab Display only real postings +@item @code{-L} @tab @code{--actual} @tab Displays only actual postings, not automated +@item @code{-r} @tab @code{--related} @tab Display related postings +@item @code{} @tab @code{--budget} @tab Display how close your postings meet your budget +@item @code{} @tab @code{--add-budget} @tab Shows unbudgeted postings +@item @code{} @tab @code{--unbedgeted} @tab Shows only unbudgeted postings +@item @code{} @tab @code{--forecast} @tab Project balances into the future +@item @code{-l EXPR} @tab @code{--limit EXPR} @tab Limits postings in calculations +@item @code{-t EXPR} @tab @code{--amount} @tab Change value expression reported in register report +@item @code{-T EXPR} @tab @code{--total} @tab Change the value expression used for ``totals'' column in register and balance reports +@end multitable + +@node Output Customization, Commodity Reporting, Report Filtering, Command Line Quick Reference +@subsection Output Customization +@multitable @columnfractions .15 .4 .45 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{-n} @tab @code{--collapse} @tab Collapse transactions with multiple postings +@item @code{-s} @tab @code{--subtotal} @tab Report register as a single subtotal +@item @code{-P} @tab @code{--by-payee} @tab Report subtotals by payee +@item @code{-x} @tab @code{--comm-as-payee} @tab Change the payee of every posting to be the commodity used in that posting +@item @code{-E} @tab @code{--empty} @tab Include empty accounts in report +@item @code{-W} @tab @code{--weekly} @tab Report posting totals by week +@item @code{-Y} @tab @code{--yearly} @tab Report posting totals by year +@item @code{} @tab @code{--dow} @tab report Posting totals by day of week +@item @code{-S EXPR} @tab @code{--sort EXPR} @tab Sorts a report using @code{EXPR} +@item @code{-w} @tab @code{--wide} @tab Assume 132 columns instead of 80 +@item @code{} @tab @code{--head N} @tab Report the first N postings +@item @code{} @tab @code{--tail N} @tab Report the last N postings +@item @code{} @tab @code{--pager prog} @tab Direct output @code{prog} pager program +@item @code{-A} @tab @code{--average} @tab Reports average posting value +@item @code{-D} @tab @code{--deviation} @tab Reports each posting deviation from the average +@item @code{-%} @tab @code{--percentage} @tab Show subtotals in the balance report as percentages +@item @code{} @tab @code{--totals} @tab Include running total in the @code{xml} report +@item @code{-j} @tab @code{--amount-data} @tab Show only date and value column +@item @code{-J} @tab @code{--total-data} @tab Show only dates and totals +@item @code{-d EXPR} @tab @code{--display EXPR} @tab Limit only the display of certain postings +@item @code{-y STR} @tab @code{--date-format STR} @tab Change the basic date format used in reports +@item @code{-F STR} @tab @code{--format STR} @tab Set reporting format +@item @code{} @tab @code{--balance-format STR} @tab +@item @code{} @tab @code{--register-format STR} @tab +@item @code{} @tab @code{--print-format STR} @tab +@item @code{-j register} @tab @code{--plot-amount-format STR} @tab +@item @code{-J register} @tab @code{--plot-total-format STR} @tab +@item @code{} @tab @code{--equity-format STR} @tab +@item @code{} @tab @code{--prices-format STR} @tab +@item @code{-w register} @tab @code{--wide-register-format STR} @tab +@end multitable + +@node Commodity Reporting, , Output Customization, Command Line Quick Reference +@subsection Commodity Reporting + +@multitable @columnfractions .1 .25 .65 +@item @strong{Short} @tab @strong{Long} @tab @strong{Description} +@item @code{} @tab @code{--price-db FILE} @tab Use @file{FILE} for retrieving downloaded commodity prices +@item @code{-L MINS} @tab @code{--price-exp MINS} @tab Set expected freshness of prices in minutes +@item @code{-Q} @tab @code{--download} @tab Download quotes using @code{getquote} +@item @code{-O} @tab @code{--quantity} @tab Report commodity totals without conversion +@item @code{-B} @tab @code{--basis} @tab Report cost basis +@item @code{-V} @tab @code{--market} @tab Report last known market value +@item @code{-G} @tab @code{--gain} @tab Report net gain loss for commodities that have a price history +@end multitable + @node Principles of Accounting, Keeping a Journal, Ledger Tutorial , Top @chapter Principles of Accounting @@ -401,10 +643,10 @@ calculating} LEDGER is agnostic when it comes to how you value your accounts. Dollars, Euros, Pounds, Francs, Shares etc. are just ``commodities''. Holdings in stocks, bonds, mutual funds and other financial instruments -can be label using whatever is convenient for you (stock ticker symbols -are suggested for publicly traded assets).@footnote{you can track -ANYTHING, even time. As long as it cannot be created or destroyed inside -your accounting system.} +can be labelled using whatever is convenient for you (stock ticker +symbols are suggested for publicly traded assets).@footnote{you can +track ANYTHING, even time or distance travelled. As long as it cannot be +created or destroyed inside your accounting system.} For the rest of this manual, we will only use the word ``commodities'' when refering to the units on a transaction value. @@ -433,11 +675,12 @@ business trip to Europe from the US: @end smallexample This says that $66.00 came out of checking and turned into 50 Euros. The -implied exchange rate was $1.32. Then 35.00 Euros was spent on Dinner in Munich. +implied exchange rate was $1.32. Then 35.00 Euros was spent on Dinner +in Munich. Running a ledger balance report shows: @smallexample -macbook-2:$ ledger -f example.dat bal +$ ledger -f example.dat bal $-66.00 E15.00 Assets E15.00 Cash @@ -454,6 +697,7 @@ checking account) and E15.00. After spending on dinner i have E15.00 in my wallet. The bottom line balances to zero, but is shown in two lines since we haven't told ledger to convert commodities. + @node Structuring Your Accounts, Advanced Transactions, Currency and Commodities, Keeping a Journal @section Structuring your Accounts @@ -464,24 +708,23 @@ system. At the highest level you have five sorts of accounts: @enumerate @item -Expenses, where money goes +Expenses: where money goes @item -Assets, where money sits +Assets: where money sits @item -Income, where moeny comes from +Income: where moeny comes from @item -Liabilities, money you owe +Liabilities: money you owe @item -Equity, the real value of your property. +Equity: the real value of your property. @end enumerate Starting the structure off this way will make it simpler for you to get answers to the questions you really need to ask about your finances. Beneath these top level accounts you can have any level of detail you -desire. If you want to keep specific track of how much you spend on +desire. For example, if you want to keep specific track of how much you spend on burgers and fries, you could have the following: - @smallexample Expenses:Food:Hamburgers and Fries @end smallexample @@ -497,6 +740,8 @@ Expenses:Food:Hamburgers and Fries * Virtual Transactions:: * Automatic Transactions:: * Periodic Transactions:: +* Recording Commodity Lot Prices:: +* Commodity Pricing Problem:: @end menu @node Transaction Notes and Tags, Multiple Account Transactions, Advanced Transactions, Advanced Transactions @@ -710,9 +955,9 @@ When ready to pay, just write a check to cover the amount shown in That's it. To see how much Huqúq is currently owed based on your ledger transactions, use: -@example +@smallexample ledger balance Liabilities:Huquq -@end example +@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 @@ -748,1989 +993,2069 @@ 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}. -@node Periodic Transactions, , Automatic Transactions, Advanced Transactions -@subsection Periodic Transactions +Automated transactions can use the full range of value expressions in +their predicate. If you wanted to specify a transaction only occur to +certain accounts that meet cetain value criteria you could specify: -A periodic transaction starts with a ~ followed by a period expression. -Periodic transactions are used for budgeting and forecasting only, they -have no effect withouth the @samp{--budget} option specified. +@smallexample += /Employees:.*:Payroll$/ and expr (amount >= $1000 and amount < $10000) + Expenses:Tax 0.27 +@end smallexample +In this case, @samp{amount} is tied to the amount of the posting being +tested. -See @ref{Budgeting and Forecasting} for exmaples and details. +But, wait! There's more! -@node File Format, Archiving Previous Years , Advanced Transactions, Keeping a Journal -@section File Format for Users +In the short example above we calculated the taxes due for income within +a certain bracket. But in reality this calculation is more difficult. +There are different rate for difference marginal incomes and those taxes +are not easily descirbe by a simple multiplicative coefficient. +Automated transaction can use value expressions in there posting to +determine the ammounts. So to expand the example above for a three tax +bracket system we could enter: -The ledger file format is quite simple, but also very flexible. It -supports many options, though typically the user can ignore most of -them. They are summarized below. +@smallexample += /Employees:.*:Payroll$/ and expr (amount < $10000.00) + (Expenses:Tax) 0.1 += /Employees:.*:Payroll$/ and expr (amount > $10000.00 and amount < $100000.00 ) + (Expenses:Tax) ($1000.00 + .15 * (amount - $10000.00)) += /Employees:.*:Payroll$/ and expr (amount > $100000.00) + (Expenses:Tax) ($13500.00 + .20 * (amount-$100000.00)) +@end smallexample -The initial character of each line determines what the line means, and -how it should be interpreted. Allowable initial characters are: -@table @code -@item NUMBER -A line beginning with a number denotes a transaction. It may be followed -by any number of lines, each beginning with whitespace, to denote the -transaction's account postings. The format of the first line is: +@node Periodic Transactions, Recording Commodity Lot Prices, Automatic Transactions, Advanced Transactions +@subsection Periodic Transactions -@example -DATE[=EDATE] [*|!] [(CODE)] DESC -@end example +A periodic transaction starts with a ~ followed by a period expression. +Periodic transactions are used for budgeting and forecasting only, they +have no effect withouth the @samp{--budget} option specified. -If @samp{*} appears after the date (with optional effective date), it -indicates the transaction is ``cleared'', which can mean whatever the user -wants it to mean. If @samp{!} appears after the date, it indicates d -the transaction is ``pending''; i.e., tentatively cleared from the user's -point of view, but not yet actually cleared. If a @samp{CODE} appears -in parentheses, it may be used to indicate a check number, or the type -of the posting. Following these is the payee, or a description of -the posting. +See @ref{Budgeting and Forecasting} for examples and details. -The format of each following posting is: +@node Recording Commodity Lot Prices, Commodity Pricing Problem, Periodic Transactions, Advanced Transactions +@subsection Recording Commodity Lot Prices -@example - ACCOUNT AMOUNT [; NOTE] -@end example +If you are tracking investments it is often necessary to keep track of +specific purchases of a commodity bought at difference prices. These +specific purchases are referred to as ``lots''. Tracking lots using ledger +requires some additional info in the journal as well as additional +command-line options when generating reports. -The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual -posting, or square brackets if it is a virtual posting that -must balance. The @samp{AMOUNT} can be followed by a per-unit -posting cost, by specifying @samp{@@ AMOUNT}, or a complete -posting cost with @samp{@@@@ AMOUNT}. Lastly, the @samp{NOTE} may -specify an actual and/or effective date for the posting by using -the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or -@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}.(See @pxref{Virtual Transactions}) +Say you want to record purchase of two separate lots of ACME, then sell +some shares. The correct way to do this is: -@item = -An automated transaction. A value expression must appear after the equal -sign. +@smallexample +2010-09-01 * Buy 2 shares of ACME @@ $100 + Assets:Broker 2 ACME @@ $100.00 + Assets:Cash + +2010-09-10 * Buy 2 share of ACME @@ $110 + Assets:Broker 2 ACME @@ $110.00 + Assets:Cash + +2011-09-20 * Sell 2 shares of ACME @@ $150 + Assets:Broker -1 ACME @{$100.00@} @@ $150.00 + Assets:Broker -1 ACME @{$200.00@} @@ $150.00 + Assets:Cash +@end smallexample -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{Automatic Transactions}). +To report which lots of commodities you hold, use the +@samp{--lot-prices} option. For example, after buying the 2 shares at +$100 and 1 at $200 it would show you: +@smallexample +$ ledger balance --lot-prices Assets:Broker until 2011-09-15 + 2 ACME @{$100.00@} + 1 ACME @{$200.00@} Assets:Broker +@end smallexample +@noindent without the @samp{--lot-prices} option you would only see the total number of shares you held: +@smallexample +$ ledger balance Assets:Broker until 2011-09-15 + 3 ACME Assets:Broker +@end smallexample +@noindent and after the sale on @samp{2011-09-20} it would show you: +@smallexample +$ ledger balance --lot-prices Assets:Broker + 1 ACME @{$100.00@} Assets:Broker +@end smallexample -@item ~ -A period transaction. A period expression must appear after the tilde. +@node Commodity Pricing Problem, , Recording Commodity Lot Prices, Advanced Transactions +@subsection Commodity Valuation -After this initial line there should be a set of one or more -postings, just as if it were normal transaction. +[THIS SUBSECTION COULD BELONG IN REPORTING SECTION, OR MAYBE EVEN SPLIT BETWEEN THE TWO] -@item ! -A line beginning with an exclamation mark denotes a command directive. -It must be immediately followed by the command word. The supported -commands are: -@table @samp -@item !include -Include the stated journal file. +Often you will be more interested in the value of your entire holdings, in +your preferred currency. It might be nice to know you hold 10,000 shares +of PENNY, but you are more interested in whether or not that is worth +$1000.00 or $10,000.00. However, the current day value of a commodity can +mean different things to different people, depending on the accounts +involved, the commodities, the nature of the transactions, etc. -@item !account -The account name is given is taken to be the parent of all -postings that follow, until @samp{!end} is seen. +When you specify @samp{-V}, or @samp{-X COMM}, you are requesting that +some or all of the commodities be valuated as of today (or whatever +@samp{--now} is set to). But what does such a valuation mean? This +meaning is governed by the presence of a @samp{VALUE} metadata +property, whose content is an expression used to compute that value. -@item !end -Ends an account block. -@end table +If no VALUE property is specified, each posting is assumed to have a default, +as if you'd specified a global, automated transaction as follows: -@item ; -A line beginning with a colon indicates a comment, and is -ignored. Comments will not be returned in a ``print'' response. -@item indented ; -If the semi colon is indented and occurs inside a transaction, it is -parsed as a persistent note for its preceding category. These notes or -tags can be used to augment to reporting and filtering capabilities of -LEDGER. -@item Y -If a line begins with a capital Y, it denotes the year used for all -subsequent transactions that give a date without a year. The year should -appear immediately after the Y, for example: @samp{Y2004}. 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. +@smallexample + = expr true + ; VALUE:: market(amount, date, exchange) +@end smallexample +This definition emulates the present day behavior of -V and -X (in the case of +-X, the requested commodity is passed via the string 'exchange' above). -@item P -Specifies a historical price for a commodity. These are usually found -in a pricing history file (see the @option{-Q} option). The syntax -is: -@example -P DATE SYMBOL PRICE -@end example +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: -@item N SYMBOL -Indicates that pricing information is to be ignored for a given -symbol, nor will quotes ever be downloaded for that symbol. Useful -with a home currency, such as the dollar ($). It is recommended that -these pricing options be set in the price database file, which -defaults to @file{~/.pricedb}. The syntax for this command is: -@example -N SYMBOL -@end example +@smallexample + = expr commodity == "DM" + ; VALUE:: date < [Jun 2008] ? market(amount, date, exchange) : 1.44 EUR +@end smallexample -@item D AMOUNT -Specifies the default commodity to use, by specifying an amount in the -expected format. The @command{transaction} command will use this commodity -as the default when none other can be determined. This command may be -used multiple times, to set the default flags for different -commodities; 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: -@example -D $1,000.00 -@end example +This says: If --now is some old date, use market prices as they were at that +time; but if --now is past June 2008, use a fixed price for converting Deutsch +Mark to Euro. -@item C AMOUNT1 = AMOUNT2 -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: -@example -C 1.00 Kb = 1024 bytes -@end example +Or how about never re-valuating commodities used in Expenses, since they +cannot have a different future value: -@item i, o, b, h -These four relate to timeclock support, which permits LEDGER to read -timelog files. See the timeclock's documentation for more info on the -syntax of its timelog files. -@end table +@smallexample + = /^Expenses:/ + ; VALUE:: market(amount, post.date, exchange) +@end smallexample +This says the future valuation is the same as the valuation at the time of +posting. post.date equals the posting's date, while just 'date' is the value +of --now (defaults to today). -@node Archiving Previous Years , , File Format, Keeping a Journal -@section Archiving Previous Years +Or how about valuating miles based on a reimbursement rate during a specific +time period: -After a while, your journal can get to be pretty large. While this will -not slow down LEDGER---it's designed to process journals very -quickly---things can start to feel ``messy''; and it's a universal -complaint that when finances feel messy, people avoid them. +@smallexample + = expr commodity == "miles" and date >= [2007] and date < [2008] + ; VALUE:: market($1.05, date, exchange) +@end smallexample -Thus, archiving the data from previous years into their own files can -offer a sense of completion, and freedom from the past. But how to best -accomplish this with the ledger program? There are two commands that -make it very simple: @command{print}, and @command{equity}. +In this case, miles driven in 2007 will always be valuated at $1.05 each. If +you use -X EUR to expressly request all amounts in Euro, Ledger shall convert +$1.05 to Euro by whatever means are appropriate for dollars. -Let's take an example file, with data ranging from year 2000 until 2004. -We want to archive years 2000 and 2001 to their own file, leaving just -2003 and 2004 in the current file. So, use @command{print} to output -all the earlier transactions to a file called @file{ledger-old.dat}: +Note that you can have a valuation expression specific to a particular posting +or transaction, by overriding these general defaults using specific metadata: @smallexample -ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat + + 2010-12-26 Example + Expenses:Food $20 + ; Just to be silly, always valuate *these* $20 as 30 DM, no matter what + ; the user asks for with -V or -X + ; VALUE:: 30 DM + Assets:Cash @end smallexample -To delete older data from the current ledger file, use @command{print} -again, this time specifying year 2002 as the starting date: +This example demonstrates that your VALUE expression should be as symbolic as +possible, using terms like 'amount' and 'date', rather than specific amounts +and dates. Also, you should pass the amount along to the function 'market' so +it can be further revalued if the user has asked for a specific currency. -@example -ledger -f ledger.dat -b 2002 print > x -mv x ledger.dat -@end example +Or, if it better suits your accounting, you can be less symbolic, which allows +you to report most everything in EUR if you use -X EUR, except for certain +accounts or postings which should always be valuated in another currency. For +example: -However, now the current file contains @emph{only} postings from 2002 -onward, which will not yield accurate present-day balances, because the -net income from previous years is no longer being tallied. To -compensate for this, we must append an equity report for the old ledger -at the beginning of the new one: +@smallexample + = /^Assets:Brokerage:CAD$/ + ; Always report the value of commodities in this account in + ; terms of present day dollars, despite what was asked for + ; on the command-line VALUE:: market(amount, date, '$') +@end smallexample -@example -ledger -f ledger-old.dat equity > equity.dat -cat equity.dat ledger.dat > x -mv x ledger.dat -rm equity.dat -@end example +I think this scheme, of using predicated value expressions which can be +generalized in automated transactions, and made specific via transaction and +posting-based metadata, provides sufficient flexibility to express most of the +use cases which have occurred on this topic. -Now the balances reported from @file{ledger.dat} are identical to what -they were before the data was split. -How often should you split your ledger? You never need to, if you -don't want to. Even eighty years of data will not slow down ledger -much---and that's just using present day hardware! Or, you can keep -the previous and current year in one file, and each year before that -in its own file. It's really up to you, and how you want to organize -your finances. For those who also keep an accurate paper trail, it -might be useful to archive the older years to their own files, then -burn those files to a CD to keep with the paper records---along with -any electronic statements received during the year. In the arena of -organization, just keep in mind this maxim: Do whatever keeps you -doing it. +Ledger presently has no way of handling such things as FIFO and LIFO. +If you specify an unadorned commodity name, like AAPL, it will balance +against itself. If --lots are not being displayed, then it will appear +to balance against any lot of AAPL. +If you specify an adorned commodity, like AAPL @{$10.00@}, it will also +balance against itself, and against any AAPL if --lots is not specified. +But if you do specify --lot-prices, for example, then it will balance +against that specific price for AAPL. +I may, for the sake of reporting *only*, be able to implement some sort +of guessing strategy, based on the order in which transactions appear in +the data file... But I'll have to think about this a lot more, and it +would be a 3.1 thing. -@node Command-line Syntax, Basic Reporting Commands, Keeping a Journal, Top -@chapter Command-line Syntax +@smallexample +> b) I don't see how this VALUE property can differentiate between -V +> and -B. Does this imply that you want to get rid of the -B option and +> simply let users define what VALUE they get with -V? If so, I think +> this would be a bad idea... I really like the ability to see different +> valuation methods using command line options (i.e. -B for cost basis +> and -V for market value). (Incidentally, while I initially liked your +> example of using the posting date for Expenses, I later realized that +> I sometimes use -V to see what my expenses (in a foreign currency) +> would have been if I bought everything at today's exchange rate.) +@end smallexample +-V and -B are entirely unrelated. Perhaps I could support a BASIS +property setting, for customizing -B in the same way VALUE +customizes -V... +@smallexample +> c) I never fully understood what -X does exactly but afaik -X is a +> special version of -V. However, I believe that -X should _only_ do +> conversion. This would allow -X to be combined with other options, +> such as -X and -V. Example: let's say I bought 10 shares for 10.00 +> GBP and they are now worth 15.00. Because my main assets are in EUR, +> I want to see what those shares are worth in EUR. Since I'm +> conservative I want to see the cost basis, i.e. I want to use -B and +> -X EUR together. (This actually works today but I'm told this is an +> accident and won't work in all cases.) +@end smallexample +-V asks for the present day value of all commodities, and lets Ledger +pick the target commodity based on its own hueristics. -X is the same +as -V, except that it overrides those hueristics and forces the target +commodity. (Although, as you've seen, the VALUE property could now +countermand that). -@menu -* Cookbook:: -* Quick Reference:: -* Options:: -* Period Expressions:: -@end menu +There are reasons why -X can't be applied to any report. Mainly it has +to do with rounding. For example, let's say I have 10 postings that +each trade 1 DM, and the value of 1 DM is 0.001 EUR. If I add all +10 DM and then apply -X, I get 0.01 EUR. But if I apply -X to each +1 DM and *then* total them, I get 0.00 EUR. -@node Cookbook, Quick Reference, Command-line Syntax, Command-line Syntax -@section Cookbook +This becomes very important to Ledger because -X is applied to totals, +not just to individual amounts. I'm going to have to use some magic +internally to avoid this problem with the VALUE property (in most, but +not all, cases). -@subsection Invoking Ledger +And so, -X gets applied after, when the posting-origin of the +commodities has been lost -- required information if a basis cost +calculation is to be deferred. -@example -ledger --group-by "tag('trip')" bal -legder reg --sort "tag('foo')" %foo -ledger cleared VWCU NFCU Tithe Misentry -ledger register Joint --uncleared -ledger register NFCUChecking --sort d -d 'd>[2011/04/01]' until 2011/05/25 -@end example -@subsection Ledger Files +The alternative would involve ever-growing lists of individual amounts, +which would slow many parts of Ledger from O(N) to O(N^2). Plus, it +still wouldn't solve the rounding problem. -@example -= /^Income:Taxable/ - (Liabilities:Tithe Owed) -0.1 -= /Noah/ - (Liabilities:Tithe Owed) -0.1 -= /Jonah/ - (Liabilities:Tithe Owed) -0.1 -= /Tithe/ - (Liabilities:Tithe Owed) -1.0 -@end example -@node Quick Reference, Options, Cookbook, Command-line Syntax -@section Quick Reference +> Ledger presently has no way of handling such things as FIFO and LIFO. -This chapter describes LEDGER's features and serves as a quick -reference. You may wish to survey this to get an overview before diving -in to the @ref{Ledger Tutorial} and more detailed examples that follow. +Yeah, I know... but I think it's a feature that ledger should +eventually get (obviously not for 3.0). -LEDGER has a very simple command-line interface, named---enticingly -enough---@command{ledger}. It supports a few reporting commands, and -a large number of options for refining the output from those commands. -The basic syntax of any ledger command is: +@smallexample +> If you specify an adorned commodity, like AAPL @{$10.00@}, it will also +> balance against itself, and against any AAPL if --lots is not specified. +> But if you do specify --lot-prices, for example, then it will balance +> against that specific price for AAPL. +> +> I may, for the sake of reporting *only*, be able to implement some sort +> of guessing strategy, based on the order in which transactions appear in +> the data file... +@end smallexample +Why for reporting only? It seems to me that ledger has all the +information to do FIFO and LIFO properly (i.e. to remove the right +commodities from the list). Let's take this example: -@example -ledger [OPTIONS...] COMMAND [ARGS...] -@end example +@smallexample -Command options must always precede the command word. After the -command word there may appear any number of arguments. For most -commands, these arguments are regular expressions that cause the -output to relate only to postings matching those regular -expressions. For the @command{transaction} command, the arguments have a -special meaning, described below. +2011-01-01 * Buy AAA + Assets:Shares 5 AAA @ 10.00 EUR + Assets:Cash -The regular expressions arguments always match the account name that a -posting refers to. To match on the payee of the transaction instead, -precede the regular expression with @samp{--}. For example, the -following balance command reports account totals for rent, food and -movies, but only those whose payee matches Freddie: +2011-01-03 * Buy AAA + Assets:Shares 2 AAA @ 10.00 EUR + Assets:Cash -@example -ledger bal rent food movies -- freddie -@end example +2011-01-11 * Buy AAA + Assets:Shares 5 AAA @ 12.00 EUR + Assets:Cash -There are many, many command options available with the -@command{ledger} command, and it takes a while to master them. -However, none of them are required to use the basic reporting -commands. +2011-01-21 * Buy AAA + Assets:Shares 5 AAA @ 13.00 EUR + Assets:Cash +@end smallexample +So we end up with (ledger --lots): -@node Options, Period Expressions, Quick Reference, Command-line Syntax -@section Options +@smallexample +5 AAA @{10.00 EUR@} [2011/01/01] +2 AAA @{10.00 EUR@} [2011/01/03] +5 AAA @{12.00 EUR@} [2011/01/11] +5 AAA @{13.00 EUR@} [2011/01/21] Assets:Shares +@end smallexample -With all of the reports, command-line options are useful to modify the -output generated. These command-line options always occur before the -command word. This is done to distinguish options from exclusive -regular expressions, which also begin with a dash. The basic form for -most commands is: +So if I sell 6 shares now, according to FIFO, I would do: -@example -ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] -@end example +@smallexample +2011-02-01 * Sell AAA + Assets:Shares -5 AAA @{10.00 EUR@} [2011/01/01] @ +13.50 EUR + Assets:Shares -1 AAA @{10.00 EUR@} [2011/01/03] @ +13.50 EUR + Assets:Cash +@end smallexample -The @var{OPTIONS} and @var{REGEXPS} expressions are both optional. -You could just use @samp{ledger balance}, without any options---which -prints a summary of all accounts. But for more specific reporting, or -to change the appearance of the output, options are needed. +ledger --lots: -@subsection Basic options +@smallexample +1 AAA @{10.00 EUR@} [2011/01/03] +5 AAA @{12.00 EUR@} [2011/01/11] +5 AAA @{13.00 EUR@} [2011/01/21] Assets:Shares +@end smallexample -These are the most basic command options. Most likely, the user will -want to set them using environment variables (see @ref{Options}), -instead of using actual command-line options: +According to LIFO, I would do this instead: -@option{--help} (@option{-h}) prints a summary of all the options, and -what they are used for. This can be a handy way to remember which -options do what. This help screen is also printed if ledger is run -without a command. +@smallexample +2011-02-01 * Sell AAA + Assets:Shares -5 AAA @{13.00 EUR@} [2011/01/21] @ +13.50 EUR + Assets:Shares -1 AAA @{12.00 EUR@} [2011/01/11] @ +13.50 EUR + Assets:Cash +@end smallexample -@option{--version} (@option{-v}) prints the current version of ledger -and exits. This is useful for sending bug reports, to let the author -know which version of ledger you are using. +In other words, you can manually do FIFO and LIFO with ledger already. +However, it would be great if ledger would make this easier, e.g. that +you could specify: -@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. -This command may be used multiple times. -Typically, the environment variable -@env{LEDGER_FILE} is set, rather than using this command-line option. +@smallexample + 2011-02-01 * Sell AAA + Assets:Shares -6 AAA @{FIFO@} @ 13.50 EUR + Assets:Cash +@end smallexample -@option{--output FILE} (@option{-o FILE}) redirects output from any -command to @var{FILE}. By default, all output goes to standard -output. +and ledger would iterate through all AAA commodities and take out the +right ones (after all, it knows the date and price). -@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by -ledger before any other ledger file. This file may not contain any -postings, but it may contain option settings. To specify options -in the init file, use the same syntax as the command-line, but put each -option on it's own line. Here's an example init file: +The only thing I don't think is possible with ledger at the moment is +average cost. I'm also not sure how --lot-dates should behave for +average cost. @smallexample ---price-db ~/finance/.pricedb ---cache /tmp/ledger-cache - -; ~/.ledgerrc ends here +> There are reasons why -X can't be applied to any report. Mainly it has +> to do with rounding. For example, let's say I have 10 postings that +> each trade 1 DM, and the value of 1 DM is 0.001 EUR. If I add all +> 10 DM and then apply -X, I get 0.01 EUR. But if I apply -X to each +> 1 DM and *then* total them, I get 0.00 EUR. @end smallexample +Thanks for the explanation... what I was thinking of is that ledger +would just produce a report according to -V or -B or whatever and +*then* convert it with -X. I use a shell script to do this for now: -Option settings on the command-line or in the environment always take -precedence over settings in the init file. +@smallexample +GBP2EUR="117/100" -@option{--cache FILE} identifies FILE as the default binary cache -file. That is, if the ledger files to be read are specified using the -environment variable @env{LEDGER_FILE}, then whenever a command is -finished a binary copy will be written to the specified cache, to -speed up the loading time of subsequent queries. This filename can -also be given using the environment variable @env{LEDGER_CACHE}, or by -putting the option into your init file. The @option{--no-cache} -option causes LEDGER to always ignore the binary cache. +eurgbp=$(ledger -f $FILE -p "until $YEAR-$NEXT_MONTH-01" -B bal "^assets" +"^liabilities" | egrep " (EUR|GBP)$" | tail -n 2) +eur=$(echo "$eurgbp" | grep "EUR" | sed 's/ EUR//') +gbp=$(echo "$eurgbp" | grep "GBP" | sed 's/ GBP//') +eur=$(echo "$eur" | sed 's/\..*//') +gbp=$(echo "$gbp" | sed 's/\..*//') +gbpineur=$(($gbp*$GBP2EUR)) +echo " " $(($eur + $gbpineur)) " EUR Total" +@end smallexample -@option{--account NAME} (@option{-a NAME}) specifies the default -account which QIF file postings are assumed to relate to. - -@subsection Report filtering - -These options change which postings affect the outcome of a -report, in ways other than just using regular expressions: - -@option{--current}(@option{-c}) displays only transactions occurring on or -before the current date. - -@option{--begin DATE} (@option{-b DATE}) constrains the report to -transactions on or after @var{DATE}. Only transactions after that date will be -calculated, which means that the running total in the balance report -will always start at zero with the first matching transaction. (Note: This -is different from using @option{--display} to constrain what is -displayed). - -@option{--end DATE} (@option{-e DATE}) constrains the report so that -transactions on or after @var{DATE} are not considered. The ending date -is inclusive. +I'm kinda surprised that you no longer think it's a good idea to split +-X from -V. Last time I brought this up on IRC, you thought it was a +good idea: -@option{--period STR} (@option{-p STR}) sets the reporting period -to @var{STR}. This will subtotal all matching transactions within each -period separately, making it easy to see weekly, monthly, quarterly, -etc., posting totals. A period string can even specify the -beginning and end of the report range, using simple terms like ``last -june'' or ``next month''. For more using period expressions, see -@ref{Period Expressions}. +@smallexample +10:44 < johnw> I think having -H, in addition to -X, may make what you want + to see both natural and simple +10:45 < johnw> you'd use -H for income/expense accounts, and -X for + assets/liabilities +10:45 < johnw> -H = historical values +10:45 < johnw> -X = current exchange values +10:45 < tbm> so what's the difference between -X and -V again? +10:45 < johnw> -V is an automated version of -X +10:45 < johnw> it tries to figure out what the reported commodity should be +10:45 < johnw> we may then need an automated version of -H, to complete the + reflection +10:46 < johnw> btw, this is just an inside-out version of my "final" + feature :) +10:46 < tbm> why not change the meaning of -X to _only do conversion_? And + then you could combine -X with -B, -V or -H +10:46 < johnw> instead of having it be syntactic, we're moving the semantic + difference to a difference in options +10:46 < johnw> oh HMM +10:46 < johnw> -X with -B, -V and -I +10:46 < johnw> (and -O, incidentally) +10:46 < johnw> O = amount, B = cost, V = market value, I = price +10:47 < johnw> that's really an excellent suggestion +10:48 < johnw> i'd still need a flag to mean "historical" vs "current" +10:48 < johnw> as well as "target commodity" (-X) +@end smallexample -@option{--period-sort EXPR} sorts the postings within each -reporting period using the value expression @var{EXPR}. This is most -often useful when reporting monthly expenses, in order to view the -highest expense categories at the top of each month: +@node File Format, Archiving Previous Years , Advanced Transactions, Keeping a Journal +@section File Format for Users -@example -ledger -M --period-sort -At reg ^Expenses -@end example +The ledger file format is quite simple, but also very flexible. It +supports many options, though typically the user can ignore most of +them. They are summarized below. -@option{--cleared} (@option{-C}) displays only postings whose transaction -has been marked ``cleared'' (by placing an asterix to the right of the -date). +The initial character of each line determines what the line means, and +how it should be interpreted. Allowable initial characters are: -@option{--uncleared} (@option{-U}) displays only postings whose -transaction has not been marked ``cleared'' (i.e., if there is no asterix to -the right of the date). +@table @code +@item NUMBER +A line beginning with a number denotes a transaction. It may be followed +by any number of lines, each beginning with whitespace, to denote the +transaction's account postings. The format of the first line is: -@option{--real} (@option{-R}) displays only real postings, not virtual. -(A virtual posting is indicated by surrounding the account name with -parentheses or brackets; see @ref{Virtual Transactions} for more -information). +@smallexample +DATE[=EDATE] [*|!] [(CODE)] DESC +@end smallexample -@option{--actual} (@option{-L}) displays only actual postings, and -not those created due to automated postings. +If @samp{*} appears after the date (with optional effective date), it +indicates the transaction is ``cleared'', which can mean whatever the user +wants it to mean. If @samp{!} appears after the date, it indicates d +the transaction is ``pending''; i.e., tentatively cleared from the user's +point of view, but not yet actually cleared. If a @samp{CODE} appears +in parentheses, it may be used to indicate a check number, or the type +of the posting. Following these is the payee, or a description of +the posting. -@option{--related} (@option{-r}) displays postings that are -related to whichever postings would otherwise have matched the -filtering criteria. In the register report, this shows where money -went to, or the account it came from. In the balance report, it shows -all the accounts affected by transactions having a related posting. -For example, if a file had this transaction: +The format of each following posting is: @smallexample -2004/03/20 Safeway - Expenses:Food $65.00 - Expenses:Cash $20.00 - Assets:Checking $-85.00 + ACCOUNT AMOUNT [; NOTE] @end smallexample -And the register command was: +The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual +posting, or square brackets if it is a virtual posting that +must balance. The @samp{AMOUNT} can be followed by a per-unit +posting cost, by specifying @samp{@@ AMOUNT}, or a complete +posting cost with @samp{@@@@ AMOUNT}. Lastly, the @samp{NOTE} may +specify an actual and/or effective date for the posting by using +the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or +@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}.(See @pxref{Virtual Transactions}) -@example -ledger -r register food -@end example +@item = +An automated transaction. A value expression must appear after the equal +sign. -The following would be output, showing the postings related to the -posting that matched: +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{Automatic Transactions}). -@smallexample -2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 - Assets:Checking $85.00 $65.00 -@end smallexample +@item ~ +A period transaction. A period expression must appear after the tilde. -@option{--budget} is useful for displaying how close your postings -meet your budget. @option{--add-budget} also shows unbudgeted -postings, while @option{--unbudgeted} shows only those. -@option{--forecast} is a related option that projects your budget into -the future, showing how it will affect future balances. -@xref{Budgeting and Forecasting}. +After this initial line there should be a set of one or more +postings, just as if it were normal transaction. -@option{--limit EXPR} (@option{-l EXPR}) limits which postings -take part in the calculations of a report. +@item ! +A line beginning with an exclamation mark denotes a command directive. +It must be immediately followed by the command word. The supported +commands are: -@option{--amount EXPR} (@option{-t EXPR}) changes the value expression -used to calculate the ``value'' column in the @command{register} -report, the amount used to calculate account totals in the -@command{balance} report, and the values printed in the -@command{equity} report. @xref{Value Expressions}. +@table @samp +@item !include +Include the stated journal file. -@option{--total EXPR} (@option{-T EXPR}) sets the value expression -used for the ``totals'' column in the @command{register} and -@command{balance} reports. +@item !account +The account name is given is taken to be the parent of all +postings that follow, until @samp{!end} is seen. -@menu -* Search Terms:: -* Output Customization:: -@end menu +@item !end +Ends an account block. +@end table -@node Search Terms, Output Customization, Options, Options -@subsection Search Terms +@item ; +A line beginning with a colon indicates a comment, and is +ignored. Comments will not be returned in a ``print'' response. +@item indented ; +If the semi colon is indented and occurs inside a transaction, it is +parsed as a persistent note for its preceding category. These notes or +tags can be used to augment to reporting and filtering capabilities of +LEDGER. +@item Y +If a line begins with a capital Y, it denotes the year used for all +subsequent transactions that give a date without a year. The year should +appear immediately after the Y, for example: @samp{Y2004}. 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. -Valid LEDGER invocations look like: +@item P +Specifies a historical price for a commodity. These are usually found +in a pricing history file (see the @option{-Q} option). The syntax +is: @smallexample - ledger [OPTIONS] +P DATE SYMBOL PRICE @end smallexample -Where @samp{COMMAND} is any command verb (@pxref{Basic Reporting Commands}), @samp{OPTIONS} can occur -anywhere, and @samp{SEARCH-TERM} is one or more of the following: - +@item N SYMBOL +Indicates that pricing information is to be ignored for a given +symbol, nor will quotes ever be downloaded for that symbol. Useful +with a home currency, such as the dollar ($). It is recommended that +these pricing options be set in the price database file, which +defaults to @file{~/.pricedb}. The syntax for this command is: @smallexample - word search for any account containing 'word' - TERM and TERM boolean AND between terms - TERM or TERM boolean OR between terms - not TERM invert the meaning of the term - payee word search for any payee containing 'word' - @@word shorthand for 'payee word' - desc word alternate for 'payee word' - note word search for any note containing 'word' - &word shorthand for 'note word' - tag word search for any metadata tag containing 'word' - tag word=value search for any metadata tag containing 'word' - whose value contains 'value' - %word shorthand for 'tag word' - %word=value shorthand for 'tag word=value' - meta word alternate for 'tag word' - meta word=value alternate for 'tag word=value' - expr 'EXPR' apply the given value expression as a predicate - '=EXPR' shorthand for 'expr EXPR' - \( TERMS \) group terms; useful if using and/or/not +N SYMBOL @end smallexample -So, to list all transaction that charged to ``ffod'' but not ``dining'' for any payee other than ``chang'' the following three commands would be equivalent: +@item D AMOUNT +Specifies the default commodity to use, by specifying an amount in the +expected format. The @command{transaction} command will use this commodity +as the default when none other can be determined. This command may be +used multiple times, to set the default flags for different +commodities; 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 +D $1,000.00 +@end smallexample +@item C AMOUNT1 = AMOUNT2 +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 - ledger reg food not dining @@chang - ledger reg food and not dining and not payee chang - ledger reg food not dining expr 'payee =~ /chang/' +C 1.00 Kb = 1024 bytes @end smallexample -@node Output Customization, , Search Terms, Options -@subsection Output Customization +@item i, o, b, h +These four relate to timeclock support, which permits LEDGER to read +timelog files. See the timeclock's documentation for more info on the +syntax of its timelog files. +@end table -These options affect only the output, but not which postings are -used to create it: -@option{--collapse} (@option{-n}) causes transactions in a -@command{register} report with multiple postings to be collapsed -into a single, subtotaled transaction. +@node Archiving Previous Years , , File Format, Keeping a Journal +@section Archiving Previous Years -@option{--subtotal} (@option{-s}) causes all transactions in a -@command{register} report to be collapsed into a single, subtotaled -transaction. -@option{--by-payee} (@option{-P}) reports subtotals by payee. +After a while, your journal can get to be pretty large. While this will +not slow down LEDGER---it's designed to process journals very +quickly---things can start to feel ``messy''; and it's a universal +complaint that when finances feel messy, people avoid them. -@option{--comm-as-payee} (@option{-x}) changes the payee of every -posting to be the commodity used in that posting. This can be -useful when combined with other options, such as @option{-s}. +Thus, archiving the data from previous years into their own files can +offer a sense of completion, and freedom from the past. But how to best +accomplish this with the ledger program? There are two commands that +make it very simple: @command{print}, and @command{equity}. -@option{--empty} (@option{-E}) includes even empty accounts in the -@command{balance} report. +Let's take an example file, with data ranging from year 2000 until 2004. +We want to archive years 2000 and 2001 to their own file, leaving just +2003 and 2004 in the current file. So, use @command{print} to output +all the earlier transactions to a file called @file{ledger-old.dat}: -@option{--weekly} (@option{-W}) reports posting totals by the -week. The week begins on whichever day of the week begins the month -containing that posting. To set a specific begin date, use a -period string, such as @samp{weekly from DATE}. @option{--monthly} -(@option{-M}) reports posting totals by month; @option{--yearly} -(@option{-Y}) reports posting totals by year. For more complex -period, using the @option{--period} option described above. +@smallexample +ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat +@end smallexample -@option{--dow} reports postings totals for each day of the week. -This is an easy way to see if weekend spending is more than on -weekdays. +To delete older data from the current ledger file, use @command{print} +again, this time specifying year 2002 as the starting date: -@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing -the values determined using the value expression @var{EXPR}. For -example, using @option{-S -UT} in the balance report will sort account -balances from greatest to least, using the absolute value of the -total. For more on how to use value expressions, see @ref{Value -Expressions}. +@smallexample +ledger -f ledger.dat -b 2002 print > x +mv x ledger.dat +@end smallexample -@option{--wide} (@option{-w}) causes the default @command{register} -report to assume 132 columns instead of 80. +However, now the current file contains @emph{only} postings from 2002 +onward, which will not yield accurate present-day balances, because the +net income from previous years is no longer being tallied. To +compensate for this, we must append an equity report for the old ledger +at the beginning of the new one: -@option{--head} causes only the first N transactions to be printed. This -is different from using the command-line utility @command{head}, which -would limit to the first N postings. @option{--tail} outputs only -the last N transactions. Both options may be used simultaneously. If a -negative amount is given, it will invert the meaning of the flag -(instead of the first five transactions being printed, for example, it -would print all but the first five). +@smallexample +ledger -f ledger-old.dat equity > equity.dat +cat equity.dat ledger.dat > x +mv x ledger.dat +rm equity.dat +@end smallexample -@option{--pager} tells LEDGER to pass its output to the given pager -program---very useful when the output is especially long. This -behavior can be made the default by setting the @env{LEDGER_PAGER} -environment variable. +Now the balances reported from @file{ledger.dat} are identical to what +they were before the data was split. -@option{--average} (@option{-A}) reports the average posting -value. +How often should you split your ledger? You never need to, if you +don't want to. Even eighty years of data will not slow down ledger +much---and that's just using present day hardware! Or, you can keep +the previous and current year in one file, and each year before that +in its own file. It's really up to you, and how you want to organize +your finances. For those who also keep an accurate paper trail, it +might be useful to archive the older years to their own files, then +burn those files to a CD to keep with the paper records---along with +any electronic statements received during the year. In the arena of +organization, just keep in mind this maxim: Do whatever keeps you +doing it. -@option{--deviation} (@option{-D}) reports each posting's -deviation from the average. It is only meaningful in the -@command{register} and @command{prices} reports. -@option{--percentage} (@option{-%}) shows account subtotals in the -@command{balance} report as percentages of the parent account. -@option{--totals} include running total information in the -@command{xml} report. -@option{--amount-data} (@option{-j}) changes the @command{register} -report so that it outputs nothing but the date and the value column, -and the latter without commodities. This is only meaningful if the -report uses a single commodity. This data can then be fed to other -programs, which could plot the date, analyze it, etc. +@node Command-line Syntax, Basic Reporting Commands, Keeping a Journal, Top +@chapter Command-line Syntax -@option{--total-data} (@option{-J}) changes the @command{register} -report so that it outputs nothing but the date and totals column, -without commodities. -@option{--display EXPR} (@option{-d EXPR}) limits which postings -or accounts or actually displayed in a report. They might still be -calculated, and be part of the running total of a register report, for -example, but they will not be displayed. This is useful for seeing -last month's checking postings, against a running balance which -includes all posting values: +@menu +* Basic Usage:: +* Detailed Options Description:: +* Period Expressions:: +@end menu -@example -ledger -d "d>=[last month]" reg checking -@end example +@node Basic Usage, Detailed Options Description, Command-line Syntax, Command-line Syntax +@section Basic Usage -The output from this command is very different from the following, -whose running total includes only postings from the last month -onward: +This chapter describes LEDGER's features and options. You may wish to +survey this to get an overview before diving in to the @ref{Ledger +Tutorial} and more detailed examples that follow. -@example -ledger -p "last month" reg checking -@end example +LEDGER has a very simple command-line interface, named---enticingly +enough---@command{ledger}. It supports a few reporting commands, and +a large number of options for refining the output from those commands. +The basic syntax of any ledger command is: -Which is more useful depends on what you're looking to know: the total -amount for the reporting range (@option{-p}), or simply a display -restricted to the reporting range (using @option{-d}). +@smallexample +ledger [OPTIONS...] COMMAND [ARGS...] +@end smallexample -@option{--date-format STR} (@option{-y STR}) changes the basic date -format used by reports. The default uses a date like 2004/08/01, -which represents the default date format of @samp{%Y/%m/%d}. To -change the way dates are printed in general, the easiest way is to put -@option{--date-format FORMAT} in the LEDGER initialization file -@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). +After the command word there may appear any number of arguments. For +most commands, these arguments are regular expressions that cause the +output to relate only to postings matching those regular expressions. +For the @command{transaction} command, the arguments have a special +meaning, described below. -@option{--format STR} (@option{-F STR}) sets the reporting format for -whatever report ledger is about to make. @xref{Format Strings}. -There are also specific format commands for each report type: +The regular expressions arguments always match the account name that a +posting refers to. To match on the payee of the transaction instead, +precede the regular expression with @samp{--}. For example, the +following balance command reports account totals for rent, food and +movies, but only those whose payee matches Freddie: + +@smallexample +ledger bal rent food movies -- freddie +@end smallexample + +There are many, many command options available with the +@command{ledger} command, and it takes a while to master them. +However, none of them are required to use the basic reporting +commands. -@itemize -@item @option{--balance-format STR} -@item @option{--register-format STR} -@item @option{--print-format STR} -@item @option{--plot-amount-format STR} (-j @command{register}) -@item @option{--plot-total-format STR} (-J @command{register}) -@item @option{--equity-format STR} -@item @option{--prices-format STR} -@item @option{--wide-register-format STR} (-w @command{register}) -@end itemize -@subsection Commodity reporting -These options affect how commodity values are displayed: -@option{--price-db FILE} sets the file that is used for recording -downloaded commodity prices. It is always read on startup, to -determine historical prices. Other settings can be placed in this -file manually, to prevent downloading quotes for a specific, for -example. This is done by adding a line like the following: -@example -; Don't download quotes for the dollar, or timelog values -N $ -N h -@end example -@option{--price-exp MINS} (@option{-L MINS}) sets the expected -freshness of price quotes, in minutes. That is, if the last known -quote for any commodity is older than this value---and if -@option{--download} is being used---then the Internet will be -consulted again for a newer price. Otherwise, the old price is still -considered to be fresh enough. -@option{--download} (@option{-Q}) causes quotes to be automagically -downloaded, as needed, by running a script named @command{getquote} -and expecting that script to return a value understood by ledger. A -sample implementation of a @command{getquote} script, implemented in -Perl, is provided in the distribution. Downloaded quote price are -then appended to the price database, usually specified using the -environment variable @env{LEDGER_PRICE_DB}. -There are several different ways that ledger can report the totals it -displays. The most flexible way to adjust them is by using value -expressions, and the @option{-t} and @option{-T} options. However, -there are also several ``default'' reports, which will satisfy most -users basic reporting needs: -@table @code -@item -O, --quantity -Reports commodity totals (this is the default) +@node Detailed Options Description, Period Expressions, Basic Usage, Command-line Syntax +@section Detailed Option Description -@item -B, --basis -Reports the cost basis for all postings. +With all of the reports, command-line options are useful to modify the +output generated. The basic form for most commands is: -@item -V, --market -Reports the last known market value for all commodities. +@smallexample +ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] +@end smallexample -@item -G --gain -Reports the net gain/loss for all commodities in the report that have -a price history. -@end table +The @var{OPTIONS} and @var{REGEXPS} expressions are both optional. +You could just use @samp{ledger balance}, without any options---which +prints a summary of all accounts. But for more specific reporting, or +to change the appearance of the output, options are needed. -@subsection Environment variables +@subsection Basic options -Every option to ledger may be set using an environment variable. If -an option has a long name such @option{--this-option}, setting the -environment variable @env{LEDGER_THIS_OPTION} will have the same -affect as specifying that option on the command-line. Options on the -command-line always take precedence over environment variable -settings, however. +These are the most basic command options. Most likely, the user will +want to set them using environment variables (see @ref{Environment Variables}), +instead of using actual command-line options: -Note that you may also permanently specify option values by placing -option settings in the file @file{~/.ledgerrc}, for example: +@option{--help} (@option{-h}) prints a summary of all the options, and +what they are used for. This can be a handy way to remember which +options do what. This help screen is also printed if ledger is run +without a command. -@example ---cache /tmp/.mycache ---pager /bin/cat +@option{--version} (@option{-v}) prints the current version of ledger +and exits. This is useful for sending bug reports, to let the author +know which version of ledger you are using. -@end example +@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file. +This command may be used multiple times. +Typically, the environment variable +@env{LEDGER_FILE} is set, rather than using this command-line option. -@node Period Expressions, , Options, Command-line Syntax -@section Period Expressions +@option{--output FILE} (@option{-o FILE}) redirects output from any +command to @var{FILE}. By default, all output goes to standard +output. -A period expression indicates a span of time, or a reporting interval, -or both. The full syntax is: +@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by +ledger before any other ledger file. This file may not contain any +postings, but it may contain option settings. To specify options +in the init file, use the same syntax as the command-line, but put each +option on it's own line. Here's an example init file: -@example -[INTERVAL] [BEGIN] [END] -@end example +@smallexample +--price-db ~/finance/.pricedb +--cache /tmp/ledger-cache -The optional @var{INTERVAL} part may be any one of: +; ~/.ledgerrc ends here +@end smallexample -@example -every day -every week -every monthly -every quarter -every year -every N days # N is any integer -every N weeks -every N months -every N quarters -every N years -daily -weekly -biweekly -monthly -bimonthly -quarterly -yearly -@end example +Option settings on the command-line or in the environment always take +precedence over settings in the init file. -After the interval, a begin time, end time, both or neither may be -specified. As for the begin time, it can be either of: +@option{--cache FILE} identifies FILE as the default binary cache +file. That is, if the ledger files to be read are specified using the +environment variable @env{LEDGER_FILE}, then whenever a command is +finished a binary copy will be written to the specified cache, to +speed up the loading time of subsequent queries. This filename can +also be given using the environment variable @env{LEDGER_CACHE}, or by +putting the option into your init file. The @option{--no-cache} +option causes LEDGER to always ignore the binary cache. -@example -from -since -@end example +@option{--account NAME} (@option{-a NAME}) specifies the default +account which QIF file postings are assumed to relate to. -The end time can be either of: +@subsection Report filtering -@example -to -until -@end example +These options change which postings affect the outcome of a +report, in ways other than just using regular expressions: -Where @var{SPEC} can be any of: +@option{--current}(@option{-c}) displays only transactions occurring on or +before the current date. -@example -2004 -2004/10 -2004/10/1 -10/1 -october -oct -this week # or day, month, quarter, year -next week -last week -@end example +@option{--begin DATE} (@option{-b DATE}) constrains the report to +transactions on or after @var{DATE}. Only transactions after that date will be +calculated, which means that the running total in the balance report +will always start at zero with the first matching transaction. (Note: This +is different from using @option{--display} to constrain what is +displayed). -The beginning and ending can be given at the same time, if it spans a -single period. In that case, just use @var{SPEC} by itself. In that -case, the period @samp{oct}, for example, will cover all the days in -october. The possible forms are: +@option{--end DATE} (@option{-e DATE}) constrains the report so that +transactions on or after @var{DATE} are not considered. The ending date +is inclusive. -@example - -in -@end example +@option{--period STR} (@option{-p STR}) sets the reporting period +to @var{STR}. This will subtotal all matching transactions within each +period separately, making it easy to see weekly, monthly, quarterly, +etc., posting totals. A period string can even specify the +beginning and end of the report range, using simple terms like ``last +june'' or ``next month''. For more using period expressions, see +@ref{Period Expressions}. -Here are a few examples of period expressions: +@option{--period-sort EXPR} sorts the postings within each +reporting period using the value expression @var{EXPR}. This is most +often useful when reporting monthly expenses, in order to view the +highest expense categories at the top of each month: -@example -monthly -monthly in 2004 -weekly from oct -weekly from last month -from sep to oct -from 10/1 to 10/5 -monthly until 2005 -from apr -until nov -last oct -weekly last august -@end example +@smallexample +ledger -M --period-sort -At reg ^Expenses +@end smallexample +@option{--cleared} (@option{-C}) displays only postings whose transaction +has been marked ``cleared'' (by placing an asterix to the right of the +date). -@node Basic Reporting Commands, Budgeting and Forecasting, Command-line Syntax, Top -@chapter Basic Reporting Commands -@menu -* balance:: -* register:: -* print:: -* output:: -* xml:: -* emacs:: -* equity:: -* prices:: -* xact:: -@end menu +@option{--uncleared} (@option{-U}) displays only postings whose +transaction has not been marked ``cleared'' (i.e., if there is no asterix to +the right of the date). -@node balance, register, Basic Reporting Commands, Basic Reporting Commands -@section balance +@option{--real} (@option{-R}) displays only real postings, not virtual. +(A virtual posting is indicated by surrounding the account name with +parentheses or brackets; see @ref{Virtual Transactions} for more +information). -The @command{balance} command reports the current balance of all -accounts. It accepts a list of optional regexps, which confine the -balance report to the matching accounts. If an account contains -multiple types of commodities, each commodity's total is reported -separately. +@option{--actual} (@option{-L}) displays only actual postings, and +not those created due to automated postings. -@node register, print, balance, Basic Reporting Commands -@section register +@option{--related} (@option{-r}) displays postings that are +related to whichever postings would otherwise have matched the +filtering criteria. In the register report, this shows where money +went to, or the account it came from. In the balance report, it shows +all the accounts affected by transactions having a related posting. +For example, if a file had this transaction: -The @command{register} command displays all the postings occurring -in a single account, line by line. The account regexp must be -specified as the only argument to this command. If any regexps occur -after the required account name, the register will contain only those -postings that match. Very useful for hunting down a particular -posting. +@smallexample +2004/03/20 Safeway + Expenses:Food $65.00 + Expenses:Cash $20.00 + Assets:Checking $-85.00 +@end smallexample -The output from @command{register} is very close to what a typical -checkbook, or single-account ledger, would look like. It also shows a -running balance. The final running balance of any register should -always be the same as the current balance of that account. +And the register command was: -If you have Gnuplot installed, you may plot the amount or running -total of any register by using the script @file{report}, which is -included in the LEDGER distribution. The only requirement is that you -add either @option{-j} or @option{-J} to your register command, in -order to plot either the amount or total column, respectively. +@smallexample +ledger -r register food +@end smallexample -@node print, output, register, Basic Reporting Commands -@section print +The following would be output, showing the postings related to the +posting that matched: -The @command{print} command prints out ledger transactions in a textual -format that can be parsed by LEDGER. They will be properly formatted, -and output in the most economic form possible. The ``print'' command -also takes a list of optional regexps, which will cause only those -postings which match in some way to be printed. +@smallexample +2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 + Assets:Checking $85.00 $65.00 +@end smallexample -The @command{print} command can be a handy way to clean up a ledger -file whose formatting has gotten out of hand. +@option{--budget} is useful for displaying how close your postings +meet your budget. @option{--add-budget} also shows unbudgeted +postings, while @option{--unbudgeted} shows only those. +@option{--forecast} is a related option that projects your budget into +the future, showing how it will affect future balances. +@xref{Budgeting and Forecasting}. -@node output, xml, print, Basic Reporting Commands -@section output +@option{--limit EXPR} (@option{-l EXPR}) limits which postings +take part in the calculations of a report. -The @command{output} command is very similar to the @command{print} -command, except that it attempts to replicate the specified ledger -file exactly. The format of the command is: +@option{--amount EXPR} (@option{-t EXPR}) changes the value expression +used to calculate the ``value'' column in the @command{register} +report, the amount used to calculate account totals in the +@command{balance} report, and the values printed in the +@command{equity} report. @xref{Value Expressions}. -@example -ledger -f FILENAME output FILENAME -@end example +@option{--total EXPR} (@option{-T EXPR}) sets the value expression +used for the ``totals'' column in the @command{register} and +@command{balance} reports. -Where @file{FILENAME} is the name of the ledger file to output. The -reason for specifying this command is that only transactions contained -within that file will be output, and not an included transactions (as can -happen with the @command{print} command). +@menu +* Search Terms:: +* Output Customization:: +* Commodity Reporting:: +* Environment Variables:: +@end menu -@node xml, emacs, output, Basic Reporting Commands -@section xml +@node Search Terms, Output Customization, Detailed Options Description, Detailed Options Description +@subsection Search Terms -The @command{xml} command outputs results similar to what -@command{print} and @command{register} display, but as an XML form. -This data can then be read in and processed. Use the -@option{--totals} option to include the running total with each -posting. +Valid LEDGER invocations look like: +@smallexample + ledger [OPTIONS] +@end smallexample -@node emacs, equity, xml, Basic Reporting Commands -@section emacs +Where @samp{COMMAND} is any command verb (@pxref{Basic Reporting Commands}), @samp{OPTIONS} can occur +anywhere, and @samp{SEARCH-TERM} is one or more of the following: -The @command{emacs} command outputs results in a form that can be read -directly by Emacs Lisp. The format of the sexp is: +@smallexample + word search for any account containing 'word' + TERM and TERM boolean AND between terms + TERM or TERM boolean OR between terms + not TERM invert the meaning of the term + payee word search for any payee containing 'word' + @@word shorthand for 'payee word' + desc word alternate for 'payee word' + note word search for any note containing 'word' + &word shorthand for 'note word' + tag word search for any metadata tag containing 'word' + tag word=value search for any metadata tag containing 'word' + whose value contains 'value' + %word shorthand for 'tag word' + %word=value shorthand for 'tag word=value' + meta word alternate for 'tag word' + meta word=value alternate for 'tag word=value' + expr 'EXPR' apply the given value expression as a predicate + '=EXPR' shorthand for 'expr EXPR' + \( TERMS \) group terms; useful if using and/or/not +@end smallexample -@example -((BEG-POS CLEARED DATE CODE PAYEE - (ACCOUNT AMOUNT)...) ; list of postings - ...) ; list of transactions -@end example +So, to list all transaction that charged to ``ffod'' but not ``dining'' for any payee other than ``chang'' the following three commands would be equivalent: -@node equity, prices, emacs, Basic Reporting Commands -@section equity +@smallexample + ledger reg food not dining @@chang + ledger reg food and not dining and not payee chang + ledger reg food not dining expr 'payee =~ /chang/' +@end smallexample -The @command{equity} command prints out accounts balances as if they -were transactions. This makes it easy to establish the starting balances -for an account, such as when @ref{Archiving Previous Years}. +@node Output Customization, Commodity Reporting, Search Terms, Detailed Options Description +@subsection Output Customization -@node prices, xact, equity, Basic Reporting Commands -@section prices +These options affect only the output, but not which postings are +used to create it: -The @command{prices} command displays the price history for matching -commodities. The @option{-A} flag is useful with this report, to -display the running average price, or @option{-D} to show each price's -deviation from that average. +@option{--collapse} (@option{-n}) causes transactions in a +@command{register} report with multiple postings to be collapsed +into a single, subtotaled transaction. -There is also a @command{pricesdb} command which outputs the same -information as @command{prices}, but does in a format that can be -parsed by LEDGER. +@option{--subtotal} (@option{-s}) causes all transactions in a +@command{register} report to be collapsed into a single, subtotaled +transaction. -@node xact, , prices, Basic Reporting Commands -@section xact +@option{--by-payee} (@option{-P}) reports subtotals by payee. -The @command{xact} commands simplifies the creation of new transactions. -It works on the principle that 80% of all postings are variants of -earlier postings. Here's how it works: +@option{--comm-as-payee} (@option{-x}) changes the payee of every +posting to be the commodity used in that posting. This can be +useful when combined with other options, such as @option{-s}. -Say you currently have this posting in your ledger file: +@option{--empty} (@option{-E}) includes even empty accounts in the +@command{balance} report. -@smallexample -2004/03/15 * Viva Italiano - Expenses:Food $12.45 - Expenses:Tips $2.55 - Liabilities:MasterCard $-15.00 -@end smallexample +@option{--weekly} (@option{-W}) reports posting totals by the +week. The week begins on whichever day of the week begins the month +containing that posting. To set a specific begin date, use a +period string, such as @samp{weekly from DATE}. @option{--monthly} +(@option{-M}) reports posting totals by month; @option{--yearly} +(@option{-Y}) reports posting totals by year. For more complex +period, using the @option{--period} option described above. -Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva -Italiano} again. The exact amounts are different, but the overall -form is the same. With the @command{xact} command you can type: +@option{--dow} reports postings totals for each day of the week. +This is an easy way to see if weekend spending is more than on +weekdays. -@example -ledger xact 2004/4/9 viva food 11 tips 2.50 -@end example +@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing +the values determined using the value expression @var{EXPR}. For +example, using @option{-S -UT} in the balance report will sort account +balances from greatest to least, using the absolute value of the +total. For more on how to use value expressions, see @ref{Value +Expressions}. -This produces the following output: +@option{--wide} (@option{-w}) causes the default @command{register} +report to assume 132 columns instead of 80. -@smallexample -2004/04/09 Viva Italiano - Expenses:Food $11.00 - Expenses:Tips $2.50 - Liabilities:MasterCard $-13.50 -@end smallexample +@option{--head} causes only the first N transactions to be printed. This +is different from using the command-line utility @command{head}, which +would limit to the first N postings. @option{--tail} outputs only +the last N transactions. Both options may be used simultaneously. If a +negative amount is given, it will invert the meaning of the flag +(instead of the first five transactions being printed, for example, it +would print all but the first five). -It works by finding a past posting matching the regular expression -@samp{viva}, and assuming that any accounts or amounts specified will -be similar to that earlier posting. If LEDGER does not succeed in -generating a new transaction, an error is printed and the exit code is set -to @samp{1}. +@option{--pager} tells LEDGER to pass its output to the given pager +program---very useful when the output is especially long. This +behavior can be made the default by setting the @env{LEDGER_PAGER} +environment variable. -There is a shell script in the distribution's @file{scripts} directory -called @file{xact}, which simplifies the task of adding a new transaction -to your ledger. It launches @command{vi} to confirm that the transaction -looks appropriate. +@option{--average} (@option{-A}) reports the average posting +value. -Here are a few more examples of the @command{xact} command, assuming -the above journal transaction: +@option{--deviation} (@option{-D}) reports each posting's +deviation from the average. It is only meaningful in the +@command{register} and @command{prices} reports. -@example -ledger xact 4/9 viva 11.50 -ledger xact 4/9 viva 11.50 checking # (from `checking') -ledger xact 4/9 viva food 11.50 tips 8 -ledger xact 4/9 viva food 11.50 tips 8 cash -ledger xact 4/9 viva food $11.50 tips $8 cash -ledger xact 4/9 viva dining "DM 11.50" -@end example +@option{--percentage} (@option{-%}) shows account subtotals in the +@command{balance} report as percentages of the parent account. +@option{--totals} include running total information in the +@command{xml} report. -@menu -* Budgeting and Forecasting:: -@end menu +@option{--amount-data} (@option{-j}) changes the @command{register} +report so that it outputs nothing but the date and the value column, +and the latter without commodities. This is only meaningful if the +report uses a single commodity. This data can then be fed to other +programs, which could plot the date, analyze it, etc. -@node Budgeting and Forecasting, Value Expressions, Basic Reporting Commands, Top -@chapter Budgeting and Forecasting +@option{--total-data} (@option{-J}) changes the @command{register} +report so that it outputs nothing but the date and totals column, +without commodities. + +@option{--display EXPR} (@option{-d EXPR}) limits which postings +or accounts or actually displayed in a report. They might still be +calculated, and be part of the running total of a register report, for +example, but they will not be displayed. This is useful for seeing +last month's checking postings, against a running balance which +includes all posting values: +@smallexample +ledger -d "d>=[last month]" reg checking +@end smallexample -@node Value Expressions, Format Strings, Budgeting and Forecasting, Top -@chapter Value Expressions +The output from this command is very different from the following, +whose running total includes only postings from the last month +onward: -Value expressions are an expression language used by LEDGER to -calculate values used by the program for many different purposes: +@smallexample +ledger -p "last month" reg checking +@end smallexample -@enumerate -@item -The values displayed in reports -@item -For predicates (where truth is anything non-zero), to determine which -postings are calculated (@option{-l}) or displayed (@option{-d}). -@item -For sorting criteria, to yield the sort key. -@item -In the matching criteria used by automated postings. -@end enumerate +Which is more useful depends on what you're looking to know: the total +amount for the reporting range (@option{-p}), or simply a display +restricted to the reporting range (using @option{-d}). -Value expressions support most simple math and logic operators, in -addition to a set of one letter functions and variables. A function's -argument is whatever follows it. The following is a display predicate -that I use with the @command{balance} command: +@option{--date-format STR} (@option{-y STR}) changes the basic date +format used by reports. The default uses a date like 2004/08/01, +which represents the default date format of @samp{%Y/%m/%d}. To +change the way dates are printed in general, the easiest way is to put +@option{--date-format FORMAT} in the LEDGER initialization file +@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). -@example -ledger -d /^Liabilities/?T<0:UT>100 balance -@end example +@option{--format STR} (@option{-F STR}) sets the reporting format for +whatever report ledger is about to make. @xref{Format Strings}. +There are also specific format commands for each report type: -The effect is that account totals are displayed only if: 1) A -Liabilities account has a total less than zero; or 2) the absolute -value of the account's total exceeds 100 units of whatever commodity -contains. If it contains multiple commodities, only one of them must -exceed 100 units. +@itemize +@item @option{--balance-format STR} +@item @option{--register-format STR} +@item @option{--print-format STR} +@item @option{--plot-amount-format STR} (-j @command{register}) +@item @option{--plot-total-format STR} (-J @command{register}) +@item @option{--equity-format STR} +@item @option{--prices-format STR} +@item @option{--wide-register-format STR} (-w @command{register}) +@end itemize -Display predicates are also very handy with register reports, to -constrain which transactions are printed. For example, the following -command shows only transactions from the beginning of the current month, -while still calculating the running balance based on all transactions: +@node Commodity Reporting, Environment Variables, Output Customization, Detailed Options Description +@subsection Commodity Reporting -@example -ledger -d "d>[this month]" register checking -@end example +These options affect how commodity values are displayed: -This advantage to this command's complexity is that it prints the -running total in terms of all transactions in the register. The following, -simpler command is similar, but totals only the displayed -postings: +@option{--price-db FILE} sets the file that is used for recording +downloaded commodity prices. It is always read on startup, to +determine historical prices. Other settings can be placed in this +file manually, to prevent downloading quotes for a specific, for +example. This is done by adding a line like the following: -@example -ledger -b "this month" register checking -@end example +@smallexample +; Don't download quotes for the dollar, or timelog values +N $ +N h +@end smallexample -@menu -* Variables:: -@end menu +@option{--price-exp MINS} (@option{-L MINS}) sets the expected +freshness of price quotes, in minutes. That is, if the last known +quote for any commodity is older than this value---and if +@option{--download} is being used---then the Internet will be +consulted again for a newer price. Otherwise, the old price is still +considered to be fresh enough. -@node Variables, , Value Expressions, Value Expressions -@section Variables +@option{--download} (@option{-Q}) causes quotes to be automagically +downloaded, as needed, by running a script named @command{getquote} +and expecting that script to return a value understood by ledger. A +sample implementation of a @command{getquote} script, implemented in +Perl, is provided in the distribution. Downloaded quote price are +then appended to the price database, usually specified using the +environment variable @env{LEDGER_PRICE_DB}. -Below are the one letter variables available in any value expression. -For the register and print commands, these variables relate to -individual postings, and sometimes the account affected by a -posting. For the balance command, these variables relate to -accounts---often with a subtle difference in meaning. The use of each -variable for both is specified. +There are several different ways that ledger can report the totals it +displays. The most flexible way to adjust them is by using value +expressions, and the @option{-t} and @option{-T} options. However, +there are also several ``default'' reports, which will satisfy most +users basic reporting needs: @table @code -@item t -This maps to whatever the user specified with @option{-t}. In a -register report, @option{-t} changes the value column; in a balance -report, it has no meaning by default. If @option{-t} was not -specified, the current report style's value expression is used. +@item -O, --quantity +Reports commodity totals (this is the default) -@item T -This maps to whatever the user specified with @option{-T}. In a -register report, @option{-T} changes the totals column; in a balance -report, this is the value given for each account. If @option{-T} was -not specified, the current report style's value expression is used. +@item -B, --basis +Reports the cost basis for all postings. -@item m -This is always the present moment/date. +@item -V, --market +Reports the last known market value for all commodities. + +@item -G --gain +Reports the net gain/loss for all commodities in the report that have +a price history. @end table -@subsection Posting/account details +@node Environment Variables, , Commodity Reporting, Detailed Options Description +@subsection Environment variables -@table @code -@item d -A posting's date, as the number of seconds past the epoch. This -is always ``today'' for an account. +Every option to ledger may be set using an environment variable. If +an option has a long name such @option{--this-option}, setting the +environment variable @env{LEDGER_THIS_OPTION} will have the same +affect as specifying that option on the command-line. Options on the +command-line always take precedence over environment variable +settings, however. -@item a -The posting's amount; the balance of an account, without -considering children. +Note that you may also permanently specify option values by placing +option settings in the file @file{~/.ledgerrc}, for example: -@item b -The cost of a posting; the cost of an account, without its -children. +@smallexample +--cache /tmp/.mycache +--pager /bin/cat -@item v -The market value of a posting, or an account without its children. +@end smallexample -@item g -The net gain (market value minus cost basis), for a posting or an -account without its children. It is the same as @samp{v-b}. +@node Period Expressions, , Detailed Options Description, Command-line Syntax +@section Period Expressions -@item l -The depth (``level'') of an account. If an account has one parent, -it's depth is one. +A period expression indicates a span of time, or a reporting interval, +or both. The full syntax is: -@item n -The index of a posting, or the count of postings affecting an -account. +@smallexample +[INTERVAL] [BEGIN] [END] +@end smallexample -@item X -1 if a posting's transaction has been cleared, 0 otherwise. +The optional @var{INTERVAL} part may be any one of: -@item R -1 if a posting is not virtual, 0 otherwise. +@smallexample +every day +every week +every monthly +every quarter +every year +every N days # N is any integer +every N weeks +every N months +every N quarters +every N years +daily +weekly +biweekly +monthly +bimonthly +quarterly +yearly +@end smallexample -@item Z -1 if a posting is not automated, 0 otherwise. -@end table +After the interval, a begin time, end time, both or neither may be +specified. As for the begin time, it can be either of: -@subsection Calculated totals +@smallexample +from +since +@end smallexample -@table @code -@item O -The total of all postings seen so far, or the total of an account -and all its children. +The end time can be either of: -@item N -The total count of postings affecting an account and all its -children. +@smallexample +to +until +@end smallexample -@item B -The total cost of all postings seen so far; the total cost of an -account and all its children. +Where @var{SPEC} can be any of: -@item V -The market value of all postings seen so far, or of an account and -all its children. +@smallexample +2004 +2004/10 +2004/10/1 +10/1 +october +oct +this week # or day, month, quarter, year +next week +last week +@end smallexample -@item G -The total net gain (market value minus cost basis), for a series of -postings, or an account and its children. It is the same as -@samp{V-B}. -@end table +The beginning and ending can be given at the same time, if it spans a +single period. In that case, just use @var{SPEC} by itself. In that +case, the period @samp{oct}, for example, will cover all the days in +october. The possible forms are: -@section Functions +@smallexample + +in +@end smallexample -The available one letter functions are: +Here are a few examples of period expressions: -@table @code -@item - -Negates the argument. +@smallexample +monthly +monthly in 2004 +weekly from oct +weekly from last month +from sep to oct +from 10/1 to 10/5 +monthly until 2005 +from apr +until nov +last oct +weekly last august +@end smallexample -@item U -The absolute (unsigned) value of the argument. -@item S -Strips the commodity from the argument. +@node Basic Reporting Commands, Budgeting and Forecasting, Command-line Syntax, Top +@chapter Basic Reporting Commands +@menu +* balance:: +* register:: +* print:: +* output:: +* xml:: +* emacs:: +* equity:: +* prices:: +* xact:: +@end menu -@item A -The arithmetic mean of the argument; @samp{Ax} is the same as -@samp{x/n}. +@node balance, register, Basic Reporting Commands, Basic Reporting Commands +@section balance -@item P -The present market value of the argument. The syntax @samp{P(x,d)} is -supported, which yields the market value at time @samp{d}. If no date -is given, then the current moment is used. -@end table +The @command{balance} command reports the current balance of all +accounts. It accepts a list of optional regexps, which confine the +balance report to the matching accounts. If an account contains +multiple types of commodities, each commodity's total is reported +separately. -@section Operators +@node register, print, balance, Basic Reporting Commands +@section register -The binary and ternary operators, in order of precedence, are: +The @command{register} command displays all the postings occurring +in a single account, line by line. The account regexp must be +specified as the only argument to this command. If any regexps occur +after the required account name, the register will contain only those +postings that match. Very useful for hunting down a particular +posting. -@enumerate -@item @samp{* /} -@item @samp{+ -} -@item @samp{! < > =} -@item @samp{& | ?:} -@end enumerate +The output from @command{register} is very close to what a typical +checkbook, or single-account ledger, would look like. It also shows a +running balance. The final running balance of any register should +always be the same as the current balance of that account. -@section Complex expressions +If you have Gnuplot installed, you may plot the amount or running +total of any register by using the script @file{report}, which is +included in the LEDGER distribution. The only requirement is that you +add either @option{-j} or @option{-J} to your register command, in +order to plot either the amount or total column, respectively. -More complicated expressions are possible using: +@node print, output, register, Basic Reporting Commands +@section print -@table @code -@item NUM -A plain integer represents a commodity-less amount. +The @command{print} command prints out ledger transactions in a textual +format that can be parsed by LEDGER. They will be properly formatted, +and output in the most economic form possible. The ``print'' command +also takes a list of optional regexps, which will cause only those +postings which match in some way to be printed. -@item @{AMOUNT@} -An amount in braces can be any kind of amount supported by ledger, -with or without a commodity. Use this for decimal values. +The @command{print} command can be a handy way to clean up a ledger +file whose formatting has gotten out of hand. -@item /REGEXP/ -@item W/REGEXP/ -A regular expression that matches against an account's full name. If -a posting, this will match against the account affected by the -posting. +@node output, xml, print, Basic Reporting Commands +@section output -@item //REGEXP/ -@item p/REGEXP/ -A regular expression that matches against a transaction's payee name. +The @command{output} command is very similar to the @command{print} +command, except that it attempts to replicate the specified ledger +file exactly. The format of the command is: -@item ///REGEXP/ -@item w/REGEXP/ -A regular expression that matches against an account's base name. If -a posting, this will match against the account affected by the -posting. +@smallexample +ledger -f FILENAME output FILENAME +@end smallexample -@item c/REGEXP/ -A regular expression that matches against the transaction code (the text -that occurs between parentheses before the payee name). +Where @file{FILENAME} is the name of the ledger file to output. The +reason for specifying this command is that only transactions contained +within that file will be output, and not an included transactions (as can +happen with the @command{print} command). -@item e/REGEXP/ -A regular expression that matches against a posting's note, or -comment field. +@node xml, emacs, output, Basic Reporting Commands +@section xml -@item (EXPR) -A sub-expression is nested in parenthesis. This can be useful passing -more complicated arguments to functions, or for overriding the natural -precedence order of operators. +The @command{xml} command outputs results similar to what +@command{print} and @command{register} display, but as an XML form. +This data can then be read in and processed. Use the +@option{--totals} option to include the running total with each +posting. -@item [DATE] -Useful specifying a date in plain terms. For example, you could say -@samp{[2004/06/01]}. -@end table +@node emacs, equity, xml, Basic Reporting Commands +@section emacs +The @command{emacs} command outputs results in a form that can be read +directly by Emacs Lisp. The format of the sexp is: -@node Format Strings, Journal File Format, Value Expressions, Top -@chapter Format Strings +@smallexample +((BEG-POS CLEARED DATE CODE PAYEE + (ACCOUNT AMOUNT)...) ; list of postings + ...) ; list of transactions +@end smallexample -Format strings may be used to change the output format of reports. -They are specified by passing a formatting string to the -@option{--format} (@option{-F}) option. Within that string, -constructs are allowed which make it possible to display the various -parts of an account or posting in custom ways. +@node equity, prices, emacs, Basic Reporting Commands +@section equity -Within a format strings, a substitution is specified using a percent -character (@samp{%}). The basic format of all substitutions is: +The @command{equity} command prints out accounts balances as if they +were transactions. This makes it easy to establish the starting balances +for an account, such as when @ref{Archiving Previous Years}. -@example -%[-][MIN WIDTH][.MAX WIDTH]EXPR -@end example +@node prices, xact, equity, Basic Reporting Commands +@section prices -If the optional minus sign (@samp{-}) follows the percent character, -whatever is substituted will be left justified. The default is right -justified. If a minimum width is given next, the substituted text -will be at least that wide, perhaps wider. If a period and a maximum -width is given, the substituted text will never be wider than this, -and will be truncated to fit. Here are some examples: +The @command{prices} command displays the price history for matching +commodities. The @option{-A} flag is useful with this report, to +display the running average price, or @option{-D} to show each price's +deviation from that average. -@example -%-P a transaction's payee, left justified -%20P The same, right justified, at least 20 chars wide -%.20P The same, no more than 20 chars wide -%-.20P Left justified, maximum twenty chars wide -@end example +There is also a @command{pricesdb} command which outputs the same +information as @command{prices}, but does in a format that can be +parsed by LEDGER. -The expression following the format constraints can be a single -letter, or an expression enclosed in parentheses or brackets. The -allowable expressions are: +@node xact, , prices, Basic Reporting Commands +@section xact -@table @code -@item % -Inserts a percent sign. +The @command{xact} commands simplifies the creation of new transactions. +It works on the principle that 80% of all postings are variants of +earlier postings. Here's how it works: -@item t -Inserts the results of the value expression specified by @option{-t}. -If @option{-t} was not specified, the current report style's value -expression is used. +Say you currently have this posting in your ledger file: -@item T -Inserts the results of the value expression specified by @option{-T}. -If @option{-T} was not specified, the current report style's value -expression is used. +@smallexample +2004/03/15 * Viva Italiano + Expenses:Food $12.45 + Expenses:Tips $2.55 + Liabilities:MasterCard $-15.00 +@end smallexample -@item | -Inserts a single space. This is useful if a width is specified, for -inserting a certain number of spaces. +Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva +Italiano} again. The exact amounts are different, but the overall +form is the same. With the @command{xact} command you can type: -@item _ -Inserts a space for each level of an account's depth. That is, if an -account has two parents, this construct will insert two spaces. If a -minimum width is specified, that much space is inserted for each level -of depth. Thus @samp{%5_}, for an account with four parents, will -insert twenty spaces. +@smallexample +ledger xact 2004/4/9 viva food 11 tips 2.50 +@end smallexample -@item (EXPR) -Inserts the amount resulting from the value expression given in -parentheses. To insert five times the total value of an account, for -example, one could say @samp{%12(5*O)}. Note: It's important to put -the five first in that expression, so that the commodity doesn't get -stripped from the total. +This produces the following output: -@item [DATEFMT] -Inserts the result of formatting a posting's date with a date -format string, exactly like those supported by @code{strftime}. For -example: @samp{%[%Y/%m/%d %H:%M:%S]}. +@smallexample +2004/04/09 Viva Italiano + Expenses:Food $11.00 + Expenses:Tips $2.50 + Liabilities:MasterCard $-13.50 +@end smallexample -@item S -Insert the pathname of the file from which the transaction's data was read. +It works by finding a past posting matching the regular expression +@samp{viva}, and assuming that any accounts or amounts specified will +be similar to that earlier posting. If LEDGER does not succeed in +generating a new transaction, an error is printed and the exit code is set +to @samp{1}. -@item B -Inserts the beginning character position of that transaction within the file. +There is a shell script in the distribution's @file{scripts} directory +called @file{xact}, which simplifies the task of adding a new transaction +to your ledger. It launches @command{vi} to confirm that the transaction +looks appropriate. -@item b -Inserts the beginning line of that transaction within the file. +Here are a few more examples of the @command{xact} command, assuming +the above journal transaction: -@item E -Inserts the ending character position of that transaction within the file. +@smallexample +ledger xact 4/9 viva 11.50 +ledger xact 4/9 viva 11.50 checking # (from `checking') +ledger xact 4/9 viva food 11.50 tips 8 +ledger xact 4/9 viva food 11.50 tips 8 cash +ledger xact 4/9 viva food $11.50 tips $8 cash +ledger xact 4/9 viva dining "DM 11.50" +@end smallexample -@item e -Inserts the ending line of that transaction within the file. -@item D -By default, this is the same as @samp{%[%Y/%m%/d]}. The date format -used can be changed at any time with the @option{-y} flag, however. -Using @samp{%D} gives the user more control over the way dates are -output. +@menu +* Budgeting and Forecasting:: +@end menu -@item d -This is the same as the @samp{%D} option, unless the transaction has an -effective date, in which case it prints -@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}. +@node Budgeting and Forecasting, Value Expressions, Basic Reporting Commands, Top +@chapter Budgeting and Forecasting -@item X -If a posting has been cleared, this inserts @samp{*} followed by a -space; otherwise nothing is inserted. -@item Y -This is the same as @samp{%X}, except that it only displays a state -character if all of the member postings have the same state. +@node Value Expressions, Format Strings, Budgeting and Forecasting, Top +@chapter Value Expressions -@item C -Inserts the checking number for a transaction, in parentheses, followed by -a space; if none was specified, nothing is inserted. +Value expressions are an expression language used by LEDGER to +calculate values used by the program for many different purposes: -@item P -Inserts the payee related to a posting. +@enumerate +@item +The values displayed in reports +@item +For predicates (where truth is anything non-zero), to determine which +postings are calculated (@option{-l}) or displayed (@option{-d}). +@item +For sorting criteria, to yield the sort key. +@item +In the matching criteria used by automated postings. +@end enumerate -@item a -Inserts the optimal short name for an account. This is normally used -in balance reports. It prints a parent account's name if that name -has not been printed yet, otherwise it just prints the account's name. +Value expressions support most simple math and logic operators, in +addition to a set of one letter functions and variables. A function's +argument is whatever follows it. The following is a display predicate +that I use with the @command{balance} command: -@item A -Inserts the full name of an account. +@smallexample +ledger -d /^Liabilities/?T<0:UT>100 balance +@end smallexample + +The effect is that account totals are displayed only if: 1) A +Liabilities account has a total less than zero; or 2) the absolute +value of the account's total exceeds 100 units of whatever commodity +contains. If it contains multiple commodities, only one of them must +exceed 100 units. -@item W -This is the same as @samp{%A}, except that it first displays the -posting's state @emph{if the transaction's posting states are not -all the same}, followed by the full account name. This is offered as -a printing optimization, so that combined with @samp{%Y}, only the -minimum amount of state detail is printed. +Display predicates are also very handy with register reports, to +constrain which transactions are printed. For example, the following +command shows only transactions from the beginning of the current month, +while still calculating the running balance based on all transactions: -@item o -Inserts the ``optimized'' form of a posting's amount. This is -used by the print report. In some cases, this inserts nothing; in -others, it inserts the posting amount and its cost. It's use is -not recommend unless you are modifying the print report. +@smallexample +ledger -d "d>[this month]" register checking +@end smallexample -@item n -Inserts the note associated with a posting, preceded by two spaces -and a semi-colon, if it exists. Thus, no none becomes an empty -string, while the note @samp{foo} is substituted as @samp{ ; foo}. +This advantage to this command's complexity is that it prints the +running total in terms of all transactions in the register. The following, +simpler command is similar, but totals only the displayed +postings: -@item N -Inserts the note associated with a posting, if one exists. +@smallexample +ledger -b "this month" register checking +@end smallexample -@item / -The @samp{%/} construct is special. It separates a format string -between what is printed for the first posting of a transaction, and -what is printed for all subsequent postings. If not used, the -same format string is used for all postings. -@end table +@menu +* Variables:: +@end menu +@node Variables, , Value Expressions, Value Expressions +@section Variables -@node Journal File Format, Extending with Python, Format Strings, Top -@chapter Journal File Format for Developers +Below are the one letter variables available in any value expression. +For the register and print commands, these variables relate to +individual postings, and sometimes the account affected by a +posting. For the balance command, these variables relate to +accounts---often with a subtle difference in meaning. The use of each +variable for both is specified. -This chapter offers a complete description of the journal data format, -suitable for implementors in other languages to follow. For users, -the chapter on keeping a journal is less extensive, but more typical -of common usage (@pxref{Keeping a Journal}). +@table @code +@item t +This maps to whatever the user specified with @option{-t}. In a +register report, @option{-t} changes the value column; in a balance +report, it has no meaning by default. If @option{-t} was not +specified, the current report style's value expression is used. -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 -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: +@item T +This maps to whatever the user specified with @option{-T}. In a +register report, @option{-T} changes the totals column; in a balance +report, this is the value given for each account. If @option{-T} was +not specified, the current report style's value expression is used. -@example -2010/05/31 Just an example - Expenses:Some:Account $100.00 - Income:Another:Account -@end example +@item m +This is always the present moment/date. +@end table -In this example, there is a transaction date, a payee, or description -of the transaction, and two postings. The postings show movement of -one hundred dollars from an account within the Income hierarchy, to -the specified expense account. The name and meaning of these accounts -in arbitrary, with no preferences implied, although you will find it -useful to follow standard accounting practice (@pxref{Principles of -Accounting}). +@subsection Posting/account details -Since an amount is missing from the second posting, it is assumed to -be the inverse of the first. This guarantee the cardinal rule of -double-entry accounting: the sum of every transaction must balance to -zero, or it is in error. Whenever Ledger encounters a @dfn{null -posting} in a transaction, it uses it to balance the remainder. +@table @code +@item d +A posting's date, as the number of seconds past the epoch. This +is always ``today'' for an account. -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: +@item a +The posting's amount; the balance of an account, without +considering children. -@example -2010/05/31 An income transaction - Assets:Checking $1,000.00 - Income:Salary +@item b +The cost of a posting; the cost of an account, without its +children. -2010/05/31 An expense transaction - Expenses:Dining $100.00 - Assets:Checking -@end example +@item v +The market value of a posting, or an account without its children. -@emph{Note:} It is important to note that there must be at least two spaces between -the end of the post and the beginning of the amount (including and -commdity designator). +@item g +The net gain (market value minus cost basis), for a posting or an +account without its children. It is the same as @samp{v-b}. -@section Specifying amounts +@item l +The depth (``level'') of an account. If an account has one parent, +it's depth is one. -The heart of a journal is the amounts it records, and this fact is -reflected in the diversity of amount expressions allowed. All of them -are covered here, though it must be said that sometimes, there are -multiple ways to achieve a desired result. +@item n +The index of a posting, or the count of postings affecting an +account. -@subsection Integer amounts +@item X +1 if a posting's transaction has been cleared, 0 otherwise. -In the simplest form, bare decimal numbers are accepted: +@item R +1 if a posting is not virtual, 0 otherwise. -@example -2010/05/31 An income transaction - Assets:Checking 1000.00 - Income:Salary -@end example +@item Z +1 if a posting is not automated, 0 otherwise. +@end table -Such amounts may only use an optional period for a decimal point. -These are referred to as @dfn{integer amounts} or @dfn{uncommoditized -amounts}. In most ways they are similar to @dfn{commoditized -amounts}, but for one signficant difference: They always display in -reports with @dfn{full precision}. More on this in a moment. For -now, a word must be said about how Ledger stores numbers. +@subsection Calculated totals -Every number parsed by Ledger is stored internally as an -infinite-precision rational value. Floating-point math is never used, -as it cannot be trusted to maintain precision of values. So, in the -case of @samp{1000.00} above, the internal value is @samp{100000/100}. +@table @code +@item O +The total of all postings seen so far, or the total of an account +and all its children. -While rational numbers are great at not losing precision, the question -arises: How should they be displayed? A number like @samp{100000/100} -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 -print @samp{1/3}, an infinitely repeating decimal? +@item N +The total count of postings affecting an account and all its +children. -Ledger gets around this problem by rendering rationals into decimal at -the last possible moment, and only for display. As such, some -rounding must, at times, occur. If this rounding would affect the -calculation of a running total, special accommodation postings are -generated to make you aware it has happened. In practice, it happens -rarely, but even then it does not reflect adjustment of the -@emph{internal amount}, only the displayed amount. +@item B +The total cost of all postings seen so far; the total cost of an +account and all its children. -What has still not been answered is how Ledger rounds values. Should -@samp{1/3} be printed as @samp{0.33} or @samp{0.33333}? For -commoditized amounts, the number of decimal places is decided by -observing how each commodity is used; but in the case of integer -amounts, an arbitrary factor must be chosen. Initially, this factor -is six. Thus, @samp{1/3} is printed back as @samp{0.333333}. -Further, this rounding factor becomes associated with each particular -value, and is carried through mathematical operations. For example, -if that particular number were multiplied by itself, the decimal -precision of the result would be twelve. Addition and subtraction do -not affect precision. +@item V +The market value of all postings seen so far, or of an account and +all its children. -Since each integer amount retains its own display precision, this is -called @dfn{full precision}, as opposed to commoditized amounts, which -always look to their commodity to know what precision they should -round to, and so use @dfn{commodity precision}. +@item G +The total net gain (market value minus cost basis), for a series of +postings, or an account and its children. It is the same as +@samp{V-B}. +@end table -@subsection Commoditized amounts +@section Functions -A @dfn{commoditized amount} is an integer amount which has an -associated commodity. This commodity can appear before or after the -amount, and may or may not be separated from it by a space. Most -characters are allowed in a commodity name, except for the following: +The available one letter functions are: -@itemize -@item Any kind of whitespace -@item Numerical digits -@item Punctuation: @samp{.,;:?!} -@item Mathematical and logical operators: @samp{-+*/^&|=} -@item Bracketing characters: @samp{<>[]()}@{@} -@item The at symbol: @samp{@@} -@end itemize +@table @code +@item - +Negates the argument. -And yet, any of these may appear in a commodity name if it is -surrounded by double quotes, for example: +@item U +The absolute (unsigned) value of the argument. -@example -100 "EUN+133" -@end example +@item S +Strips the commodity from the argument. -If a @dfn{quoted commodity} is found, it is displayed in quotes as -well, to avoid any confusion as to which part is the amount, and which -part is the commodity. +@item A +The arithmetic mean of the argument; @samp{Ax} is the same as +@samp{x/n}. -Another feature of commoditized amounts is that they are reported back -in the same form as parsed. If you specify dollar amounts using -@samp{$100}, they will print the same; likewise with @samp{100 $} or -@samp{$100.000}. You may even use decimal commas, such as -@samp{$100,00}, or thousand-marks, as in @samp{$10,000.00}. +@item P +The present market value of the argument. The syntax @samp{P(x,d)} is +supported, which yields the market value at time @samp{d}. If no date +is given, then the current moment is used. +@end table -These display characteristics become associated with the commodity, -with the result being that all amounts of the same commodity are -reported consistently. Where this is most noticeable is the -@dfn{display precision}, which is determined by the most precise value -seen for a given commodity. In most cases. +@section Operators -Ledger makes a distinction by @dfn{observed amounts} and unobserved -amounts. An observed amount is critiqued by Ledger to determine how -amounts using that commodity should be displayed; unobserved amounts -are significant in their value only---no matter how they are -specified, it does not change how other amounts in that commodity will -be displayed. +The binary and ternary operators, in order of precedence, are: -An example of this is found in cost expressions, covered next. +@enumerate +@item @samp{* /} +@item @samp{+ -} +@item @samp{! < > =} +@item @samp{& | ?:} +@end enumerate -@section Posting costs +@section Complex expressions -You have seen how to specify either a commoditized or an integer -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: +More complicated expressions are possible using: -@example -2010/05/31 Farmer's Market - Assets:My Larder 100 apples - Assets:Checking $20.00 -@end example +@table @code +@item NUM +A plain integer represents a commodity-less amount. -In this example, you have paid twenty dollars for one hundred apples. -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}: +@item @{AMOUNT@} +An amount in braces can be any kind of amount supported by ledger, +with or without a commodity. Use this for decimal values. -@example -2010/05/31 Farmer's Market - Assets:My Larder 100 apples @@ $0.200000 - Assets:Checking -@end example +@item /REGEXP/ +@item W/REGEXP/ +A regular expression that matches against an account's full name. If +a posting, this will match against the account affected by the +posting. -Here the @dfn{per-unit cost} is given explicitly in the form of a cost -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}: +@item //REGEXP/ +@item p/REGEXP/ +A regular expression that matches against a transaction's payee name. -@example -2010/05/31 Farmer's Market - Assets:My Larder 100 apples @@@@ $20 - Assets:Checking -@end example +@item ///REGEXP/ +@item w/REGEXP/ +A regular expression that matches against an account's base name. If +a posting, this will match against the account affected by the +posting. -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: +@item c/REGEXP/ +A regular expression that matches against the transaction code (the text +that occurs between parentheses before the payee name). -@example -2010/05/31 Farmer's Market - Assets:My Larder 100 apples @@ $0.200000 - Assets:My Larder 100 pineapples @@ $0.33 - Assets:My Larder 100 "crab apples" @@ $0.04 - Assets:Checking -@end example +@item e/REGEXP/ +A regular expression that matches against a posting's note, or +comment field. -Here the implied cost is @samp{$57.00}, which is entered into the null -posting automatically so that the transaction balances. +@item (EXPR) +A sub-expression is nested in parenthesis. This can be useful passing +more complicated arguments to functions, or for overriding the natural +precedence order of operators. -@subsection Primary commodities +@item [DATE] +Useful specifying a date in plain terms. For example, you could say +@samp{[2004/06/01]}. +@end table -In every transaction involving more than one commodity, there is -always one which is the @dfn{primary commodity}. This commodity -should be thought of as the exchange commodity, or the commodity used -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: -@example -2010/05/31 Sample Transaction - Expenses 100 secondary - Assets 50 primary +@node Format Strings, Journal File Format, Value Expressions, Top +@chapter Format Strings -2010/05/31 Sample Transaction - Expenses 100 secondary @@ 0.5 primary - Assets +Format strings may be used to change the output format of reports. +They are specified by passing a formatting string to the +@option{--format} (@option{-F}) option. Within that string, +constructs are allowed which make it possible to display the various +parts of an account or posting in custom ways. -2010/05/31 Sample Transaction - Expenses 100 secondary @@@@ 50 primary - Assets -@end example +Within a format strings, a substitution is specified using a percent +character (@samp{%}). The basic format of all substitutions is: -The only case where knowledge of primary versus secondary comes into -play is in reports that use the @option{-V} or @option{-B} options. -With these, only primary commodities are shown. +@smallexample +%[-][MIN WIDTH][.MAX WIDTH]EXPR +@end smallexample -If a transaction uses only one commodity, this commodity is also -considered a primary. In fact, when Ledger goes about ensures that -all transactions balance to zero, it only ever asks this of primary -commodities. +If the optional minus sign (@samp{-}) follows the percent character, +whatever is substituted will be left justified. The default is right +justified. If a minimum width is given next, the substituted text +will be at least that wide, perhaps wider. If a period and a maximum +width is given, the substituted text will never be wider than this, +and will be truncated to fit. Here are some examples: -@node Extending with Python, Example Data File, Journal File Format, Top -@chapter Extending with Python +@smallexample +%-P a transaction's payee, left justified +%20P The same, right justified, at least 20 chars wide +%.20P The same, no more than 20 chars wide +%-.20P Left justified, maximum twenty chars wide +@end smallexample -@node Example Data File, Miscellaneous Notes, Extending with Python, Top -@appendix Example Journal File: drewr.dat - 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, -@example -; -*- ledger -*- +The expression following the format constraints can be a single +letter, or an expression enclosed in parentheses or brackets. The +allowable expressions are: -= /^Income/ - (Liabilities:Tithe) 0.12 +@table @code +@item % +Inserts a percent sign. -~ Monthly - Assets:Checking $500.00 - Income:Salary +@item t +Inserts the results of the value expression specified by @option{-t}. +If @option{-t} was not specified, the current report style's value +expression is used. -2003/12/01 * Checking balance - Assets:Checking $1,000.00 - Equity:Opening Balances +@item T +Inserts the results of the value expression specified by @option{-T}. +If @option{-T} was not specified, the current report style's value +expression is used. -2003/12/20 Organic Co-op - Expenses:Food:Groceries $ 37.50 ; [=2004/01/01] - Expenses:Food:Groceries $ 37.50 ; [=2004/02/01] - Expenses:Food:Groceries $ 37.50 ; [=2004/03/01] - Expenses:Food:Groceries $ 37.50 ; [=2004/04/01] - Expenses:Food:Groceries $ 37.50 ; [=2004/05/01] - Expenses:Food:Groceries $ 37.50 ; [=2004/06/01] - Assets:Checking $ -225.00 +@item | +Inserts a single space. This is useful if a width is specified, for +inserting a certain number of spaces. -2003/12/28=2004/01/01 Acme Mortgage - Liabilities:Mortgage:Principal $ 200.00 - Expenses:Interest:Mortgage $ 500.00 - Expenses:Escrow $ 300.00 - Assets:Checking $ -1000.00 +@item _ +Inserts a space for each level of an account's depth. That is, if an +account has two parents, this construct will insert two spaces. If a +minimum width is specified, that much space is inserted for each level +of depth. Thus @samp{%5_}, for an account with four parents, will +insert twenty spaces. -2004/01/02 Grocery Store - Expenses:Food:Groceries $ 65.00 - Assets:Checking +@item (EXPR) +Inserts the amount resulting from the value expression given in +parentheses. To insert five times the total value of an account, for +example, one could say @samp{%12(5*O)}. Note: It's important to put +the five first in that expression, so that the commodity doesn't get +stripped from the total. -2004/01/05 Employer - Assets:Checking $ 2000.00 - Income:Salary +@item [DATEFMT] +Inserts the result of formatting a posting's date with a date +format string, exactly like those supported by @code{strftime}. For +example: @samp{%[%Y/%m/%d %H:%M:%S]}. -2004/01/14 Bank - ; Regular monthly savings transfer - Assets:Savings $ 300.00 - Assets:Checking +@item S +Insert the pathname of the file from which the transaction's data was read. -2004/01/19 Grocery Store - Expenses:Food:Groceries $ 44.00 - Assets:Checking +@item B +Inserts the beginning character position of that transaction within the file. -2004/01/25 Bank - ; Transfer to cover car purchase - Assets:Checking $ 5,500.00 - Assets:Savings - ; :nobudget: +@item b +Inserts the beginning line of that transaction within the file. -2004/01/25 Tom's Used Cars - Expenses:Auto $ 5,500.00 - ; :nobudget: - Assets:Checking +@item E +Inserts the ending character position of that transaction within the file. -2004/01/27 Book Store - Expenses:Books $20.00 - Liabilities:MasterCard +@item e +Inserts the ending line of that transaction within the file. -2004/02/01 Sale - Assets:Checking:Business $ 30.00 - Income:Sales +@item D +By default, this is the same as @samp{%[%Y/%m%/d]}. The date format +used can be changed at any time with the @option{-y} flag, however. +Using @samp{%D} gives the user more control over the way dates are +output. -@end example +@item d +This is the same as the @samp{%D} option, unless the transaction has an +effective date, in which case it prints +@samp{[ACTUAL_DATE=EFFECTIVE_DATE]}. -@node Miscellaneous Notes, , Example Data File, Top -@appendix Miscellaneous Notes +@item X +If a posting has been cleared, this inserts @samp{*} followed by a +space; otherwise nothing is inserted. -Various notes from the discussion list that I haven't incorporated in to the main body of the documentation. +@item Y +This is the same as @samp{%X}, except that it only displays a state +character if all of the member postings have the same state. -@menu -* Commodity Pricing Problem:: -@end menu +@item C +Inserts the checking number for a transaction, in parentheses, followed by +a space; if none was specified, nothing is inserted. -@node Commodity Pricing Problem, , Miscellaneous Notes, Miscellaneous Notes -@section Commodity Pricing Problem +@item P +Inserts the payee related to a posting. -Sun, 26 Dec 2010 04:13:04 -0800 +@item a +Inserts the optimal short name for an account. This is normally used +in balance reports. It prints a parent account's name if that name +has not been printed yet, otherwise it just prints the account's name. -One of the things which stalled Ledger development recently is that I'd never -found a truly satisfying way to handle the "commodity pricing problem". That -is, the current day value of a commodity can mean different things to -different people, depending on the accounts involved, the commodities, the -nature of the transactions, etc. +@item A +Inserts the full name of an account. -After experimenting with several different concepts and syntaxes, I found none -of them were either satisfying or general enough. My one attempt at providing -"fixated prices" was too specific, and too inelegant for many usage patterns. +@item W +This is the same as @samp{%A}, except that it first displays the +posting's state @emph{if the transaction's posting states are not +all the same}, followed by the full account name. This is offered as +a printing optimization, so that combined with @samp{%Y}, only the +minimum amount of state detail is printed. -This morning, however, I think I've finally cracked this nut; and in a way -which fits harmoniously into the Ledger architecture as if it were meant to be -there all along... +@item o +Inserts the ``optimized'' form of a posting's amount. This is +used by the print report. In some cases, this inserts nothing; in +others, it inserts the posting amount and its cost. It's use is +not recommend unless you are modifying the print report. -Here's how the new scheme will work: When a user specifies '-V', or '-X COMM', -they are requesting that some or all of the commodities in their Ledger file -be valuated as of today (or whatever --now is set to). But what does such a -valuation mean? This meaning shall be governed by the presence of a "VALUE" -metadata property, whose content is an expression used to compute that value. +@item n +Inserts the note associated with a posting, preceded by two spaces +and a semi-colon, if it exists. Thus, no none becomes an empty +string, while the note @samp{foo} is substituted as @samp{ ; foo}. -If no VALUE property is specified, each posting is assumed to have a default, -as if you'd specified a global, automated transaction as follows: +@item N +Inserts the note associated with a posting, if one exists. -@smallexample - = expr true - ; VALUE:: market(amount, date, exchange) -@end smallexample -This definition emulates the present day behavior of -V and -X (in the case of --X, the requested commodity is passed via the string 'exchange' above). +@item / +The @samp{%/} construct is special. It separates a format string +between what is printed for the first posting of a transaction, and +what is printed for all subsequent postings. If not used, the +same format string is used for all postings. +@end table -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 - = expr commodity == "DM" - ; VALUE:: date < [Jun 2008] ? market(amount, date, exchange) : 1.44 EUR -@end smallexample +@node Journal File Format, Extending with Python, Format Strings, Top +@chapter Journal File Format for Developers -This says: If --now is some old date, use market prices as they were at that -time; but if --now is past June 2008, use a fixed price for converting Deutsch -Mark to Euro. +This chapter offers a complete description of the journal data format, +suitable for implementors in other languages to follow. For users, +the chapter on keeping a journal is less extensive, but more typical +of common usage (@pxref{Keeping a Journal}). -Or how about never re-valuating commodities used in Expenses, since they -cannot have a different future value: +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 +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 - = /^Expenses:/ - ; VALUE:: market(amount, post.date, exchange) +2010/05/31 Just an example + Expenses:Some:Account $100.00 + Income:Another:Account @end smallexample -This says the future valuation is the same as the valuation at the time of -posting. post.date equals the posting's date, while just 'date' is the value -of --now (defaults to today). +In this example, there is a transaction date, a payee, or description +of the transaction, and two postings. The postings show movement of +one hundred dollars from an account within the Income hierarchy, to +the specified expense account. The name and meaning of these accounts +in arbitrary, with no preferences implied, although you will find it +useful to follow standard accounting practice (@pxref{Principles of +Accounting}). -Or how about valuating miles based on a reimbursement rate during a specific -time period: +Since an amount is missing from the second posting, it is assumed to +be the inverse of the first. This guarantee the cardinal rule of +double-entry accounting: the sum of every transaction must balance to +zero, or it is in error. Whenever Ledger encounters a @dfn{null +posting} in a transaction, it uses it to balance the remainder. +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 - = expr commodity == "miles" and date >= [2007] and date < [2008] - ; VALUE:: market($1.05, date, exchange) -@end smallexample +2010/05/31 An income transaction + Assets:Checking $1,000.00 + Income:Salary -In this case, miles driven in 2007 will always be valuated at $1.05 each. If -you use -X EUR to expressly request all amounts in Euro, Ledger shall convert -$1.05 to Euro by whatever means are appropriate for dollars. +2010/05/31 An expense transaction + Expenses:Dining $100.00 + Assets:Checking +@end smallexample -Note that you can have a valuation expression specific to a particular posting -or transaction, by overriding these general defaults using specific metadata: +@emph{Note:} It is important to note that there must be at least two spaces between +the end of the post and the beginning of the amount (including and +commdity designator). -@smallexample +@section Specifying amounts - 2010-12-26 Example - Expenses:Food $20 - ; Just to be silly, always valuate *these* $20 as 30 DM, no matter what - ; the user asks for with -V or -X - ; VALUE:: 30 DM - Assets:Cash -@end smallexample +The heart of a journal is the amounts it records, and this fact is +reflected in the diversity of amount expressions allowed. All of them +are covered here, though it must be said that sometimes, there are +multiple ways to achieve a desired result. -This example demonstrates that your VALUE expression should be as symbolic as -possible, using terms like 'amount' and 'date', rather than specific amounts -and dates. Also, you should pass the amount along to the function 'market' so -it can be further revalued if the user has asked for a specific currency. +@subsection Integer amounts -Or, if it better suits your accounting, you can be less symbolic, which allows -you to report most everything in EUR if you use -X EUR, except for certain -accounts or postings which should always be valuated in another currency. For -example: +In the simplest form, bare decimal numbers are accepted: @smallexample - = /^Assets:Brokerage:CAD$/ - ; Always report the value of commodities in this account in terms of - ; present day dollars, despite what was asked for on the command-line - ; VALUE:: market(amount, date, '$') +2010/05/31 An income transaction + Assets:Checking 1000.00 + Income:Salary @end smallexample -I think this scheme, of using predicated value expressions which can be -generalized in automated transactions, and made specific via transaction and -posting-based metadata, provides sufficient flexibility to express most of the -use cases which have occurred on this topic. - - -Ledger presently has no way of handling such things as FIFO and LIFO. - -If you specify an unadorned commodity name, like AAPL, it will balance -against itself. If --lots are not being displayed, then it will appear -to balance against any lot of AAPL. - -If you specify an adorned commodity, like AAPL @{$10.00@}, it will also -balance against itself, and against any AAPL if --lots is not specified. -But if you do specify --lot-prices, for example, then it will balance -against that specific price for AAPL. - -I may, for the sake of reporting *only*, be able to implement some sort -of guessing strategy, based on the order in which transactions appear in -the data file... But I'll have to think about this a lot more, and it -would be a 3.1 thing. +Such amounts may only use an optional period for a decimal point. +These are referred to as @dfn{integer amounts} or @dfn{uncommoditized +amounts}. In most ways they are similar to @dfn{commoditized +amounts}, but for one signficant difference: They always display in +reports with @dfn{full precision}. More on this in a moment. For +now, a word must be said about how Ledger stores numbers. -> b) I don't see how this VALUE property can differentiate between -V -> and -B. Does this imply that you want to get rid of the -B option and -> simply let users define what VALUE they get with -V? If so, I think -> this would be a bad idea... I really like the ability to see different -> valuation methods using command line options (i.e. -B for cost basis -> and -V for market value). (Incidentally, while I initially liked your -> example of using the posting date for Expenses, I later realized that -> I sometimes use -V to see what my expenses (in a foreign currency) -> would have been if I bought everything at today's exchange rate.) +Every number parsed by Ledger is stored internally as an +infinite-precision rational value. Floating-point math is never used, +as it cannot be trusted to maintain precision of values. So, in the +case of @samp{1000.00} above, the internal value is @samp{100000/100}. --V and -B are entirely unrelated. Perhaps I could support a BASIS -property setting, for customizing -B in the same way VALUE -customizes -V... +While rational numbers are great at not losing precision, the question +arises: How should they be displayed? A number like @samp{100000/100} +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 +print @samp{1/3}, an infinitely repeating decimal? -> c) I never fully understood what -X does exactly but afaik -X is a -> special version of -V. However, I believe that -X should _only_ do -> conversion. This would allow -X to be combined with other options, -> such as -X and -V. Example: let's say I bought 10 shares for 10.00 -> GBP and they are now worth 15.00. Because my main assets are in EUR, -> I want to see what those shares are worth in EUR. Since I'm -> conservative I want to see the cost basis, i.e. I want to use -B and -> -X EUR together. (This actually works today but I'm told this is an -> accident and won't work in all cases.) +Ledger gets around this problem by rendering rationals into decimal at +the last possible moment, and only for display. As such, some +rounding must, at times, occur. If this rounding would affect the +calculation of a running total, special accommodation postings are +generated to make you aware it has happened. In practice, it happens +rarely, but even then it does not reflect adjustment of the +@emph{internal amount}, only the displayed amount. --V asks for the present day value of all commodities, and lets Ledger -pick the target commodity based on its own hueristics. -X is the same -as -V, except that it overrides those hueristics and forces the target -commodity. (Although, as you've seen, the VALUE property could now -countermand that). +What has still not been answered is how Ledger rounds values. Should +@samp{1/3} be printed as @samp{0.33} or @samp{0.33333}? For +commoditized amounts, the number of decimal places is decided by +observing how each commodity is used; but in the case of integer +amounts, an arbitrary factor must be chosen. Initially, this factor +is six. Thus, @samp{1/3} is printed back as @samp{0.333333}. +Further, this rounding factor becomes associated with each particular +value, and is carried through mathematical operations. For example, +if that particular number were multiplied by itself, the decimal +precision of the result would be twelve. Addition and subtraction do +not affect precision. -There are reasons why -X can't be applied to any report. Mainly it has -to do with rounding. For example, let's say I have 10 postings that -each trade 1 DM, and the value of 1 DM is 0.001 EUR. If I add all -10 DM and then apply -X, I get 0.01 EUR. But if I apply -X to each -1 DM and *then* total them, I get 0.00 EUR. +Since each integer amount retains its own display precision, this is +called @dfn{full precision}, as opposed to commoditized amounts, which +always look to their commodity to know what precision they should +round to, and so use @dfn{commodity precision}. -This becomes very important to Ledger because -X is applied to totals, -not just to individual amounts. I'm going to have to use some magic -internally to avoid this problem with the VALUE property (in most, but -not all, cases). +@subsection Commoditized amounts -And so, -X gets applied after, when the posting-origin of the -commodities has been lost -- required information if a basis cost -calculation is to be deferred. +A @dfn{commoditized amount} is an integer amount which has an +associated commodity. This commodity can appear before or after the +amount, and may or may not be separated from it by a space. Most +characters are allowed in a commodity name, except for the following: -The alternative would involve ever-growing lists of individual amounts, -which would slow many parts of Ledger from O(N) to O(N^2). Plus, it -still wouldn't solve the rounding problem. +@itemize +@item Any kind of whitespace +@item Numerical digits +@item Punctuation: @samp{.,;:?!} +@item Mathematical and logical operators: @samp{-+*/^&|=} +@item Bracketing characters: @samp{<>[]()}@{@} +@item The at symbol: @samp{@@} +@end itemize +And yet, any of these may appear in a commodity name if it is +surrounded by double quotes, for example: -> Ledger presently has no way of handling such things as FIFO and LIFO. +@smallexample +100 "EUN+133" +@end smallexample -Yeah, I know... but I think it's a feature that ledger should -eventually get (obviously not for 3.0). +If a @dfn{quoted commodity} is found, it is displayed in quotes as +well, to avoid any confusion as to which part is the amount, and which +part is the commodity. -> If you specify an adorned commodity, like AAPL @{$10.00@}, it will also -> balance against itself, and against any AAPL if --lots is not specified. -> But if you do specify --lot-prices, for example, then it will balance -> against that specific price for AAPL. -> -> I may, for the sake of reporting *only*, be able to implement some sort -> of guessing strategy, based on the order in which transactions appear in -> the data file... +Another feature of commoditized amounts is that they are reported back +in the same form as parsed. If you specify dollar amounts using +@samp{$100}, they will print the same; likewise with @samp{100 $} or +@samp{$100.000}. You may even use decimal commas, such as +@samp{$100,00}, or thousand-marks, as in @samp{$10,000.00}. -Why for reporting only? It seems to me that ledger has all the -information to do FIFO and LIFO properly (i.e. to remove the right -commodities from the list). Let's take this example: +These display characteristics become associated with the commodity, +with the result being that all amounts of the same commodity are +reported consistently. Where this is most noticeable is the +@dfn{display precision}, which is determined by the most precise value +seen for a given commodity. In most cases. -@smallexample +Ledger makes a distinction by @dfn{observed amounts} and unobserved +amounts. An observed amount is critiqued by Ledger to determine how +amounts using that commodity should be displayed; unobserved amounts +are significant in their value only---no matter how they are +specified, it does not change how other amounts in that commodity will +be displayed. -2011-01-01 * Buy AAA - Assets:Shares 5 AAA @ 10.00 EUR - Assets:Cash +An example of this is found in cost expressions, covered next. -2011-01-03 * Buy AAA - Assets:Shares 2 AAA @ 10.00 EUR - Assets:Cash +@section Posting costs -2011-01-11 * Buy AAA - Assets:Shares 5 AAA @ 12.00 EUR - Assets:Cash +You have seen how to specify either a commoditized or an integer +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: -2011-01-21 * Buy AAA - Assets:Shares 5 AAA @ 13.00 EUR - Assets:Cash +@smallexample +2010/05/31 Farmer's Market + Assets:My Larder 100 apples + Assets:Checking $20.00 @end smallexample -So we end up with (ledger --lots): +In this example, you have paid twenty dollars for one hundred apples. +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 -5 AAA @{10.00 EUR@} [2011/01/01] -2 AAA @{10.00 EUR@} [2011/01/03] -5 AAA @{12.00 EUR@} [2011/01/11] -5 AAA @{13.00 EUR@} [2011/01/21] Assets:Shares +2010/05/31 Farmer's Market + Assets:My Larder 100 apples @@ $0.200000 + Assets:Checking @end smallexample -So if I sell 6 shares now, according to FIFO, I would do: +Here the @dfn{per-unit cost} is given explicitly in the form of a cost +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 -2011-02-01 * Sell AAA - Assets:Shares -5 AAA @{10.00 EUR@} [2011/01/01] @ -13.50 EUR - Assets:Shares -1 AAA @{10.00 EUR@} [2011/01/03] @ -13.50 EUR - Assets:Cash +2010/05/31 Farmer's Market + Assets:My Larder 100 apples @@@@ $20 + Assets:Checking @end smallexample -ledger --lots: +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 -1 AAA @{10.00 EUR@} [2011/01/03] -5 AAA @{12.00 EUR@} [2011/01/11] -5 AAA @{13.00 EUR@} [2011/01/21] Assets:Shares +2010/05/31 Farmer's Market + Assets:My Larder 100 apples @@ $0.200000 + Assets:My Larder 100 pineapples @@ $0.33 + Assets:My Larder 100 "crab apples" @@ $0.04 + Assets:Checking @end smallexample -According to LIFO, I would do this instead: +Here the implied cost is @samp{$57.00}, which is entered into the null +posting automatically so that the transaction balances. + +@subsection Primary commodities + +In every transaction involving more than one commodity, there is +always one which is the @dfn{primary commodity}. This commodity +should be thought of as the exchange commodity, or the commodity used +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 -2011-02-01 * Sell AAA - Assets:Shares -5 AAA @{13.00 EUR@} [2011/01/21] @ -13.50 EUR - Assets:Shares -1 AAA @{12.00 EUR@} [2011/01/11] @ -13.50 EUR - Assets:Cash +2010/05/31 Sample Transaction + Expenses 100 secondary + Assets 50 primary + +2010/05/31 Sample Transaction + Expenses 100 secondary @@ 0.5 primary + Assets + +2010/05/31 Sample Transaction + Expenses 100 secondary @@@@ 50 primary + Assets @end smallexample -In other words, you can manually do FIFO and LIFO with ledger already. -However, it would be great if ledger would make this easier, e.g. that -you could specify: +The only case where knowledge of primary versus secondary comes into +play is in reports that use the @option{-V} or @option{-B} options. +With these, only primary commodities are shown. + +If a transaction uses only one commodity, this commodity is also +considered a primary. In fact, when Ledger goes about ensures that +all transactions balance to zero, it only ever asks this of primary +commodities. + +@node Extending with Python, Example Data File, Journal File Format, Top +@chapter Extending with Python +@node Example Data File, Miscellaneous Notes, Extending with Python, Top +@appendix Example Journal File: drewr.dat + 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 - 2011-02-01 * Sell AAA - Assets:Shares -6 AAA @{FIFO@} @ 13.50 EUR - Assets:Cash -@end smallexample +; -*- ledger -*- -and ledger would iterate through all AAA commodities and take out the -right ones (after all, it knows the date and price). += /^Income/ + (Liabilities:Tithe) 0.12 -The only thing I don't think is possible with ledger at the moment is -average cost. I'm also not sure how --lot-dates should behave for -average cost. +~ Monthly + Assets:Checking $500.00 + Income:Salary -> There are reasons why -X can't be applied to any report. Mainly it has -> to do with rounding. For example, let's say I have 10 postings that -> each trade 1 DM, and the value of 1 DM is 0.001 EUR. If I add all -> 10 DM and then apply -X, I get 0.01 EUR. But if I apply -X to each -> 1 DM and *then* total them, I get 0.00 EUR. +2003/12/01 * Checking balance + Assets:Checking $1,000.00 + Equity:Opening Balances -Thanks for the explanation... what I was thinking of is that ledger -would just produce a report according to -V or -B or whatever and -*then* convert it with -X. I use a shell script to do this for now: +2003/12/20 Organic Co-op + Expenses:Food:Groceries $ 37.50 ; [=2004/01/01] + Expenses:Food:Groceries $ 37.50 ; [=2004/02/01] + Expenses:Food:Groceries $ 37.50 ; [=2004/03/01] + Expenses:Food:Groceries $ 37.50 ; [=2004/04/01] + Expenses:Food:Groceries $ 37.50 ; [=2004/05/01] + Expenses:Food:Groceries $ 37.50 ; [=2004/06/01] + Assets:Checking $ -225.00 -@smallexample -GBP2EUR="117/100" +2003/12/28=2004/01/01 Acme Mortgage + Liabilities:Mortgage:Principal $ 200.00 + Expenses:Interest:Mortgage $ 500.00 + Expenses:Escrow $ 300.00 + Assets:Checking $ -1000.00 + +2004/01/02 Grocery Store + Expenses:Food:Groceries $ 65.00 + Assets:Checking + +2004/01/05 Employer + Assets:Checking $ 2000.00 + Income:Salary + +2004/01/14 Bank + ; Regular monthly savings transfer + Assets:Savings $ 300.00 + Assets:Checking + +2004/01/19 Grocery Store + Expenses:Food:Groceries $ 44.00 + Assets:Checking + +2004/01/25 Bank + ; Transfer to cover car purchase + Assets:Checking $ 5,500.00 + Assets:Savings + ; :nobudget: + +2004/01/25 Tom's Used Cars + Expenses:Auto $ 5,500.00 + ; :nobudget: + Assets:Checking + +2004/01/27 Book Store + Expenses:Books $20.00 + Liabilities:MasterCard + +2004/02/01 Sale + Assets:Checking:Business $ 30.00 + Income:Sales -eurgbp=$(ledger -f $FILE -p "until $YEAR-$NEXT_MONTH-01" -B bal "^assets" -"^liabilities" | egrep " (EUR|GBP)$" | tail -n 2) -eur=$(echo "$eurgbp" | grep "EUR" | sed 's/ EUR//') -gbp=$(echo "$eurgbp" | grep "GBP" | sed 's/ GBP//') -eur=$(echo "$eur" | sed 's/\..*//') -gbp=$(echo "$gbp" | sed 's/\..*//') -gbpineur=$(($gbp*$GBP2EUR)) -echo " " $(($eur + $gbpineur)) " EUR Total" @end smallexample -I'm kinda surprised that you no longer think it's a good idea to split --X from -V. Last time I brought this up on IRC, you thought it was a -good idea: +@node Miscellaneous Notes, , Example Data File, Top +@appendix Miscellaneous Notes + +Various notes from the discussion list that I haven't incorporated in to the main body of the documentation. + +@menu +* Cookbook:: +@end menu + +@node Cookbook, , Miscellaneous Notes, Miscellaneous Notes +@section Cookbook + +@subsection Invoking Ledger @smallexample -10:44 < johnw> I think having -H, in addition to -X, may make what you want - to see both natural and simple -10:45 < johnw> you'd use -H for income/expense accounts, and -X for - assets/liabilities -10:45 < johnw> -H = historical values -10:45 < johnw> -X = current exchange values -10:45 < tbm> so what's the difference between -X and -V again? -10:45 < johnw> -V is an automated version of -X -10:45 < johnw> it tries to figure out what the reported commodity should be -10:45 < johnw> we may then need an automated version of -H, to complete the - reflection -10:46 < johnw> btw, this is just an inside-out version of my "final" - feature :) -10:46 < tbm> why not change the meaning of -X to _only do conversion_? And - then you could combine -X with -B, -V or -H -10:46 < johnw> instead of having it be syntactic, we're moving the semantic - difference to a difference in options -10:46 < johnw> oh HMM -10:46 < johnw> -X with -B, -V and -I -10:46 < johnw> (and -O, incidentally) -10:46 < johnw> O = amount, B = cost, V = market value, I = price -10:47 < johnw> that's really an excellent suggestion -10:48 < johnw> i'd still need a flag to mean "historical" vs "current" -10:48 < johnw> as well as "target commodity" (-X) +ledger --group-by "tag('trip')" bal +legder reg --sort "tag('foo')" %foo +ledger cleared VWCU NFCU Tithe Misentry +ledger register Joint --uncleared +ledger register Checking --sort d -d 'd>[2011/04/01]' until 2011/05/25 @end smallexample +@subsection Ledger Files +@smallexample += /^Income:Taxable/ + (Liabilities:Tithe Owed) -0.1 += /Noah/ + (Liabilities:Tithe Owed) -0.1 += /Jonah/ + (Liabilities:Tithe Owed) -0.1 += /Tithe/ + (Liabilities:Tithe Owed) -1.0 +@end smallexample @bye -- cgit v1.2.3