From 4f21cd2700fd68a9005fc5186cdc13bbc05accc7 Mon Sep 17 00:00:00 2001 From: Craig Earls Date: Sun, 18 Mar 2012 16:27:48 -0700 Subject: Reorganized command directives --- doc/ledger3.texi | 2954 +++++++++++++++++++++++++++--------------------------- 1 file changed, 1467 insertions(+), 1487 deletions(-) diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 8e7c8b50..e61805d7 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -261,14 +261,6 @@ can be searched directly from the command line using the following options: @option{ledger --help} bring up this entire manual in your tty. -@option{ledger --help-info} brings up help on how to use the info system. - -@option{ledger --help-comm concept} searches the manual index and brings up pages associated with `concept'. - -@option{ledger --help-calc} brings up the value expressions chapter of this manual (@pxref{Value Expressions}). - -@option{ledger --help-disp} brings up the Format Strings chapter of this manual (@pxref{Format Strings}). - 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: @@ -347,7 +339,8 @@ 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. +@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: @@ -494,6 +487,7 @@ cannot display any currency symbols other than dollar signs ($). * Reporting Commands Quick Reference:: * Basic Options Quick Reference:: * Report Filtering Quick Reference:: +* Error Checking and Calculation Options:: * Output Customization Quick Reference:: * Grouping Options:: * Commodity Reporting Quick Reference:: @@ -528,7 +522,7 @@ cannot display any currency symbols other than dollar signs ($). @item @code{-a NAME} @tab @code{--account NAME} @tab specify default account name for QIF file postings @end multitable -@node Report Filtering Quick Reference, Output Customization Quick Reference, Basic Options Quick Reference, Command Line Quick Reference +@node Report Filtering Quick Reference, Error Checking and Calculation Options, Basic Options Quick Reference, Command Line Quick Reference @subsection Report Filtering @multitable @columnfractions .1 .25 .65 @item @strong{Short} @tab @strong{Long} @tab @strong{Description} @@ -552,7 +546,7 @@ cannot display any currency symbols other than dollar signs ($). @item @code{-T EXPR} @tab @code{--total} @tab Change the value expression used for ``totals'' column in register and balance reports @end multitable -@node Error Checking and Calculation Options +@node Error Checking and Calculation Options, Output Customization Quick Reference, Report Filtering Quick Reference, Command Line Quick Reference @subsection Error Checking and Calculation Options @multitable @columnfractions .1 .25 .65 @@ -564,7 +558,7 @@ cannot display any currency symbols other than dollar signs ($). @end multitable -@node Output Customization Quick Reference, Grouping Options, Report Filtering Quick Reference, Command Line Quick Reference +@node Output Customization Quick Reference, Grouping Options, Error Checking and Calculation Options, Command Line Quick Reference @subsection Output Customization @multitable @columnfractions .15 .4 .45 @item @strong{Short} @tab @strong{Long} @tab @strong{Description} @@ -1387,6 +1381,9 @@ posting. * Commenting on your journal:: * Currency and Commodities:: * Keeping it Consistent:: +* Journal Format:: +* Archiving Previous Years :: +* Using Emacs:: @end menu @node Most Basic Entry, Starting up, Keeping a Journal, Keeping a Journal @@ -1722,7 +1719,7 @@ its amount is null. @node Complete control over commodity pricing, , Fixing Lot Prices, Currency and Commodities @subsection Complete control over commodity pricing -@node Keeping it Consistent, , Currency and Commodities, Keeping a Journal +@node Keeping it Consistent, Journal Format, Currency and Commodities, Keeping a Journal @section Keeping it Consistent Sometimes Ledger's flexibility can lead to difficulties. Using a @@ -1753,1823 +1750,1821 @@ ledger accounts >> Accounts.dat @noindent You will have to edit this file to add the @samp{account} directive. +@node Journal Format, Archiving Previous Years , Keeping it Consistent, Keeping a Journal +@section Journal Format +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. -@node Transactions , Building Reports, Keeping a Journal, Top -@chapter Transactions @menu -* Basic format:: -* Eliding amounts:: -* Auxiliary dates:: -* Codes:: -* Transaction state:: -* Transaction notes:: -* Metadata:: -* Virtual postings:: -* Expression amounts:: -* Balance verification:: -* Posting cost:: -* Explicit posting costs:: -* Posting cost expressions:: -* Total posting costs:: -* Virtual posting costs:: -* Commodity prices:: -* Prices vs. costs:: -* Lot dates:: -* Lot notes:: -* Lot value expressions:: -* Automated transactions:: -* File Format:: -* Archiving Previous Years :: -* Using Emacs:: +* Transaction and Comments:: +* Command Directives:: @end menu -@node Basic format, Eliding amounts, Transactions , Transactions -@section Basic format - +@node Transaction and Comments, Command Directives, Journal Format, Journal Format +@subsection Transactions and Comments +The initial character of each line determines what the line means, and +how it should be interpreted. Allowable initial characters are: -The most basic form of transaction is: +@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 white-space, to denote the +transaction's account postings. The format of the first line is: @smallexample - 2012-03-10 KFC - Expenses:Food $20.00 - Assets:Cash $-20.00 +DATE[=EDATE] [*|!] [(CODE)] DESC @end smallexample -This transaction has a date, a payee or description, a target account (the -first posting), and a source account (the second posting). Each posting -specifies what action is taken related to that account. +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. -A transaction can have any number of postings: +The format of each following posting is: @smallexample - 2012-03-10 KFC - Expenses:Food $20.00 - Assets:Cash $-10.00 - Liabilities:Credit $-10.00 + ACCOUNT AMOUNT [; NOTE] @end smallexample -@node Eliding amounts, Auxiliary dates, Basic format, Transactions -@section Eliding amounts - -The first thing you can do to make things easier is elide amounts. That is, -if exactly one posting has no amount specified, Ledger will infer the inverse -of the other postings' amounts: +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 postings}) +@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 - 2012-03-10 KFC - Expenses:Food $20.00 - Assets:Cash $-10.00 - Liabilities:Credit ; same as specifying $-10 +P DATE SYMBOL PRICE @end smallexample -@noindent If the other postings use multiple commodities, Ledger will copy the empty -posting N times and fill in the negated values of the various commodities: +@item = +An automated transaction. A value expression must appear after the equal +sign. -@smallexample - 2012-03-10 KFC - Expenses:Food $20.00 - Expenses:Tips $2.00 - Assets:Cash EUR -10.00 - Assets:Cash GBP -10.00 - Liabilities:Credit -@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{Automated transactions}). -@noindent This transaction is identical to writing: +@item ~ +A period transaction. A period expression must appear after the tilde. -@smallexample - 2012-03-10 KFC - Expenses:Food $20.00 - Expenses:Tips $2.00 - Assets:Cash EUR -10.00 - Assets:Cash GBP -10.00 - Liabilities:Credit $-22.00 - Liabilities:Credit EUR 10.00 - Liabilities:Credit GBP 10.00 -@end smallexample +After this initial line there should be a set of one or more +postings, just as if it were normal transaction. -@node Auxiliary dates, Codes, Eliding amounts, Transactions -@section Auxiliary dates +@item ; # % | * +A line beginning with a colon, pound, percent, bar or asterisk 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 the reporting and filtering capabilities of +Ledger. +@end table -You can associate a second date with a transaction by following the primary -date with an equals sign: +@node Command Directives, , Transaction and Comments, Journal Format +@subsection Command Directives + +@table @code +@item beginning of line +Command directives must occur at the beginning of a line. Use of ! and +@@ is deprecated. + +@item account + +Pre-declare valid account names. This only has effect if +@samp{--strict} or @samp{--pedantic} is used (see below). The +@samp{account} directive supports several optional sub-directives, if +they immediately follow the account directive and if they begin with +whitespace: @smallexample - 2012-03-10=2012-03-08 KFC - Expenses:Food $20.00 - Assets:Cash $-20.00 + account Expenses:Food + note This account is all about the chicken! + alias food + payee ^(KFC|Popeyes)$ + check commodity == "$" + assert commodity == "$" + eval print("Hello!") + default @end smallexample -What this auxiliary date means is entirely up to you. The only use Ledger has -for it is that if you specify --aux-date, then all reports and calculations -(including pricing) will use the aux date as if it were the primary date. +The @samp{note} sub-directive associates a textual note with the account. This can +be accessed later using the @samp{note} valexpr function in any account context. -@node Codes, Transaction state, Auxiliary dates, Transactions -@section Codes +The @samp{alias} sub-directive, which can occur multiple times, allows the alias to +be used in place of the full account name anywhere that account names are +allowed. -A transaction can have a textual "code". This has no meaning and is only -displayed by the print command. Checking accounts often use codes like DEP, -XFER, etc., as well as check numbers. This is to give you a place to put -those codes: +The @samp{payee} sub-directive, which can occur multiple times, provides regexps +that identify the account if that payee is encountered and an account within +its transaction ends in the name "Unknown". Example: @smallexample - 2012-03-10 (#100) KFC - Expenses:Food $20.00 - Assets:Checking + 2012-02-27 KFC + Expenses:Unknown $10.00 ; Read now as "Expenses:Food" + Assets:Cash @end smallexample -@node Transaction state, Transaction notes, Codes, Transactions -@section Transaction state +The @samp{check} and @samp{assert} directives warn or error (respectively) if the given +value expression evaluates to false within the context of any posting. -A transaction can have a ``state'': cleared, pending, or uncleared. The default -is uncleared. To mark a transaction cleared, put a * before the payee, and -after date or code: +The @samp{eval} directive evaluates the value expression in the context of the +account at the time of definition. At the moment this has little value. -@smallexample - 2012-03-10 * KFC - Expenses:Food $20.00 - Assets:Cash -@end smallexample +The @samp{default} directive specifies that this account should be used as the +``balancing account'' for any future transactions that contain only a single +posting. -@noindent To mark it pending, use a !: +@item apply account +@c instance_t::master_account_directive +Sets the root for all accounts following the directive. Ledger supports +a hierarchical tree of accounts. It may be convenient to keep two +``root accounts''. For example you may be tracking your personal +finances and your business finances. In order to keep them separate you +could preface all personal accounts with @code{personal:} and all +business account with @code{business:}. You can easily split out large +groups of transaction without manually editing them using the account +directive. For example: @smallexample - 2012-03-10 ! KFC - Expenses:Food $20.00 - Assets:Cash +apply account Personal +2011/11/15 Supermarket + Expenses:Groceries + Assets:Checking @end smallexample -What these mean is entirely up to you. The --cleared option will limits to -reports to only cleared items, while --uncleared shows both uncleared and -pending items, and --pending shows only pending items. +Would result in all postings going into +@code{Personal:Expenses:Groceries} and @code{Personal:Assets:hecking} +until and @code{end apply account} directive was found. -I use cleared to mean that I've reconciled the transaction with my bank -statement, and pending to mean that I'm in the middle of a reconciliation. +@item alias +@c instance_t::alias_directive +Define an alias for an account name. If you have a deeply nested tree +of accounts, it may be convenient to define an alias, for example: +@smallexample +alias Dining=Expenses:Entertainment:Dining +alias Checking=Assets:Credit Union:Joint Checking Account -When you clear a transaction, that's really just shorthand for clearing all of -its postings. That is: +2011/11/28 YummyPalace + Dining $10.00 + Checking -@smallexample - 2012-03-10 * KFC - Expenses:Food $20.00 - Assets:Cash @end smallexample -@noindent Is the same as writing: +The aliases are only in effect for transactions read in after the alias +is defined and are effected by @code{account} directives that precede +them. +@item assert +@c instance_t::assert_directive +An assertion can throw an error if a condition is not met during Ledger's run. @smallexample - 2012-03-10 KFC - * Expenses:Food $20.00 - * Assets:Cash -@end smallexample -@noindent You can mark individual postings as cleared or pending, in case one "side" of -the transaction has cleared, but the other hasn't yet: +assert -@smallexample - 2012-03-10 KFC - Liabilities:Credit $100.00 - * Assets:Checking @end smallexample -@node Transaction notes, Metadata, Transaction state, Transactions -@section Transaction notes - -After the payee, and after at least one tab or two spaces (or a space -and a tab, which Ledger calls this a ``hard separator''), you may -introduce a note about the transaction using the ; character: +@item bucket +@c instance_t::default_account_directive +Defines the default account to use for balancing transactions. +Normally, each transaction has at least two postings, which must balance +to zero. Ledger allows you to leave one posting with no amount and +automatically calculate balance the transaction in the posting. The +@code{bucket} allows you to fill in all postings and automatically +generate an additional posting to the bucket account balancing the +transaction. The following example set the @code{Assets:Checking} as +the bucket: @smallexample - 2012-03-10 * KFC ; yum, chicken... - Expenses:Food $20.00 - Assets:Cash -@end smallexample -@noindent Notes can also appear on the next line, so long as that line begins with -whitespace: +bucket Assets:Checking +2011/01/25 Tom's Used Cars + Expenses:Auto $ 5,500.00 -@smallexample - 2012-03-10 * KFC ; yum, chicken... - ; and more notes... - Expenses:Food $20.00 - Assets:Cash +2011/01/27 Book Store + Expenses:Books $20.00 - 2012-03-10 * KFC - ; just these notes... - Expenses:Food $20.00 - Assets:Cash -@end smallexample +2011/12/01 Sale + Assets:Checking:Business $ 30.00 +@end smallexample -A transaction note is shared by all its postings. This becomes significant -when querying for metadata (see below). To specify that a note belongs only -to one posting, place it after a hard separator after the amount, or on its -own line preceded by whitespace: +@item capture +@c instance_t::account_mapping_directive +Directs Ledger to replace any account matching a regex with the given +account. For example: @smallexample - 2012-03-10 * KFC - Expenses:Food $20.00 ; posting #1 note - Assets:Cash - ; posting #2 note, extra indentation is optional +capture Expenses:Deductible:Medical Medical @end smallexample -@node Metadata, Virtual postings, Transaction notes, Transactions -@section Metadata +Would cause any posting with @code{Medical} in it's name to be replaced with +@code{Expenses:Deductible:Medical}. -One of Ledger's more powerful features is the ability to associate typed -metadata with postings and transactions (by which I mean all of a -transaction's postings). This metadata can be queried, displayed, and used in -calculations. -The are two forms of metadata: tags and tag/value pairs. +Ledger will display the mapped payees in @code{print} and +@code{register} reports. -@menu -* Metadata tags:: -* Metadata values:: -* Typed metadata:: -@end menu +@item check +@c instance_t::check_directive in textual.cc +A check can issue a warning if a condition is not met during Ledger's run. -@node Metadata tags, Metadata values, Metadata, Metadata -@subsection Metadata tags +@smallexample -To tag an item, put any word not containing whitespace between two colons: +check -@smallexample - 2012-03-10 * KFC - Expenses:Food $20.00 - Assets:Cash - ; :TAG: @end smallexample +@item comment +@c instance_t::comment_directive in textual.cc +Start a block comment, closed by @code{end comment}. -You can gang up multiple tags by sharing colons: +@item commodity +Pre-declare commodity names. This only has effect if @samp{--strict} or +@samp{--pedantic} is used (see below). + + commodity $ + commodity CAD + +The @samp{commodity} directive supports several optional sub-directives, if they +immediately follow the commodity directive and if they begin with whitespace: @smallexample - 2012-03-10 * KFC - Expenses:Food $20.00 - Assets:Cash - ; :TAG1:TAG2:TAG3: + commodity $ + note American Dollars + format $1,000.00 + nomarket + default @end smallexample -@node Metadata values, Typed metadata, Metadata tags, Metadata -@subsection Metadata values +The @samp{note} sub-directive associates a textual note with the commodity. At +present this has no value other than documentation. -To associate a value with a tag, use the syntax "Key: Value", where the value -can be any string of characters. Whitespace is needed after the colon, and -cannot appear in the Key: +The @samp{format} directive gives you a way to tell Ledger how to format this +commodity. In future using this directive will disable Ledger's observation +of other ways that commodity is used, and will provide the ``canonical'' +representation. + +The @samp{nomarket} directive states that the commodity's price should never be +auto-downloaded. + +The @samp{default} directive marks this as the ``default'' commodity. +@item define +@c instance_t::define_directive in textual.cc +Allows you to define value expression for future use. For example: @smallexample - 2012-03-10 * KFC - Expenses:Food $20.00 - Assets:Cash - ; MyTag: This is just a bogus value for MyTag +define var_name=$100 + +2011/12/01 Test + Expenses (var_name*4) + Assets @end smallexample -@node Typed metadata, , Metadata values, Metadata -@subsection Typed metadata +The posting will have a cost of $400. +@item end +@c instance_t::end_directive in textual.cc +Closes block commands like @code{tag} or @code{comment}. +@item expr +@c instance_t::expr_directive in textual.cc -If a metadata tag ends in ::, it's value will be parsed as a value expression -and stored internally as a value rather than as a string. For example, -although I can specify a date textually like so: +@item fixed +@c instance_t::fixed_directive in textual.cc + +@item include +@c instance_t::include_directive in textual.cc +Include the stated file as if it were part of the current file. + +@item payee +@c instance_t::payee_mapping_directive in textual.cc +The @samp{payee} directive supports one optional sub-directive, if it immediately +follows the payee directive and if it begins with whitespace: @smallexample - 2012-03-10 * KFC - Expenses:Food $20.00 - Assets:Cash - ; AuxDate: 2012/02/30 + payee KFC + alias KENTUCKY FRIED CHICKEN @end smallexample -@noindent This date is just a string, and won't be parsed as a date unless its value is -used in a date-context (at which time the string is parsed into a date -automatically every time it is needed as a date). If on the other hand I -write this: +The @samp{alias} directive provides a regexp which, if it matches a parsed payee, +the declared payee name is substituted: @smallexample - 2012-03-10 * KFC - Expenses:Food $20.00 - Assets:Cash - ; AuxDate:: [2012/02/30] + 2012-02-27 KENTUCKY FRIED CHICKEN ; will be read as being 'KFC' + ... @end smallexample -@noindent Then it is parsed as a date only once, and during parsing of the journal file, -which would let me know right away that it is an invalid date. - -@node Virtual postings, Expression amounts, Metadata, Transactions -@section Virtual postings +Ledger will display the mapped payees in @code{print} and +@code{register} reports. -Ordinarily, the amounts of all postings in a transaction must balance to zero. -This is non-negotiable. It's what double-entry accounting is all about! But -there are some tricks up Ledger's sleeve... +@item apply tag +@c instance_t::tag_directive in textual.cc +Allows you to designate a block of transactions and assign the same tag to all. Tags can have values and may be nested. +@smallexample +apply tag hastag +apply tag nestedtag: true +2011/01/25 Tom's Used Cars + Expenses:Auto $ 5,500.00 + ; :nobudget: + Assets:Checking -You can use virtual accounts to transfer amounts to an account on the sly, -bypassing the balancing requirement. The trick is that these postings are not -considered ``real'', and can be removed from all reports using @samp{--real}. +2011/01/27 Book Store + Expenses:Books $20.00 + Liabilities:MasterCard -To specify a virtual account, surround the account name with parentheses: +end apply tag nestedtag -@smallexample - 2012-03-10 * KFC - Expenses:Food $20.00 - Assets:Cash - (Budget:Food) $-20.00 +2011/12/01 Sale + Assets:Checking:Business $ 30.00 + Income:Sales +end apply tag hastag @end smallexample -If you want, you can state that virtual postings @emph{should} balance against -one or more other virtual postings by using brackets (which look ``harder'') -rather than parentheses: +@noindent is the equivalent of @smallexample - 2012-03-10 * KFC - Expenses:Food $20.00 - Assets:Cash - [Budget:Food] $-20.00 - [Equity:Budgets] $20.00 +2011/01/25 Tom's Used Cars + :hastag: + nestedtag: true + Expenses:Auto $ 5,500.00 + ; :nobudget: + Assets:Checking + +2011/01/27 Book Store + :hastag: + nestedtag: true + Expenses:Books $20.00 + Liabilities:MasterCard + +2011/12/01 Sale + :hastag: + Assets:Checking:Business $ 30.00 + Income:Sales @end smallexample -@node Expression amounts, Balance verification, Virtual postings, Transactions -@section Expression amounts +Note that anything following ``@code{end tag}'' is ignored. placing the +name of the tag that is being closed is a simple way to keep track. -An amount is usually a numerical figure with an (optional) commodity, but it -can also be any value expression. To indicate this, surround the amount -expression with parentheses: +@item tag +Pre-declares tag names. This only has effect if @samp{--strict} or +@samp{--pedantic} is used (see below). @smallexample - 2012-03-10 * KFC - Expenses:Food ($10.00 + $20.00) ; Ledger adds it up for you - Assets:Cash + tag Receipt + tag CSV @end smallexample -@node Balance verification, Posting cost, Expression amounts, Transactions -@section Balance verification -@menu -* Balance assertions:: -* Balance assignments:: -* Resetting a balance:: -* Balancing transactions:: -@end menu +The 'tag' directive supports two optional sub-directives, if they immediately +follow the tag directive and if they begin with whitespace: -If at the end of a posting's amount (and after the cost too, if there is one) -there is an equals sign, then Ledger will verify that the total value for that -account as of that posting matches the amount specified. +@smallexample + tag Receipt + check value =~ /pattern/ + assert value != "foobar" +@end smallexample -There are two forms of this features: balance assertions, and balance -assignments. +The @samp{check} and @samp{assert} directives warn or error (respectively) if the given +value expression evaluates to false within the context of any use of the +related tag. In such a context, ``value'' is bound to the value of the tag +(which may not be a string if typed-metadata is used!). Such checks or +assertions are not called if no value is given. +@item test +@c instance_t::comment_directive in textual.cc +This is a synonym for @code{comment} and must be closed by and @code{end} tag. -@node Balance assertions, Balance assignments, Balance verification, Balance verification -@subsection Balance assertions +@item year +@c instance_t::year_directive in textual.cc +Denotes the year used for all subsequent transactions that give a date +without a year. The year should appear immediately after the Y, for +example: @samp{year 2004}. This is useful at the beginning of a file, to +specify the year for that file. If all transactions specify a year, +however, this command has no effect. -A balance assertion has this general form: +@end table -@smallexample - 2012-03-10 KFC - Expenses:Food $20.00 - Assets:Cash $-20.00 = $500.00 -@end smallexample +The following single letter commands may be at the beginning of a line +alone, for backwards compatibility with older Ledger versions. -This simply asserts that after subtracting $20.00 from Assets:Cash, that the -resulting total matches $500.00. If not, it is an error. -@node Balance assignments, Resetting a balance, Balance assertions, Balance verification -@subsection Balance assignments +@table @code +@item A +See @code{bucket} +@item Y +See @code{year} -A balance assignment has this form: +@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 - 2012-03-10 KFC - Expenses:Food $20.00 - Assets:Cash = $500.00 +N SYMBOL @end smallexample -This sets the amount of the second posting to whatever it would need to be for -the total in Assets:Cash to be $500.00 after the posting. If the resulting -amount is not $-20.00 in this case, it is an error. - -@node Resetting a balance, Balancing transactions, Balance assignments, Balance verification -@subsection Resetting a balance - -Say your book-keeping has gotten a bit out of date, and your Ledger balance no -longer matches your bank balance. You can create an adjustment transaction -using balance assignments: - +@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 - 2012-03-10 Adjustment - Assets:Cash = $500.00 - Equity:Adjustments +D $1,000.00 @end smallexample -Since the second posting is also null, it's value will become the inverse of -whatever amount is generated for the first posting. - -This is the only time in ledger when more than one posting's amount may be -empty -- and then only because it's not true empty, it is indirectly provided -by the balance assignment's value. - -@node Balancing transactions, , Resetting a balance, Balance verification -@subsection Balancing transactions - -As a consequence of all the above, consider the following transaction: - +@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 - 2012-03-10 My Broker - [Assets:Brokerage] = 10 AAPL +C 1.00 Kb = 1024 bytes @end smallexample -What this says is: set the amount of the posting to whatever value is needed -so that Assets:Brokerage contains 10 AAPL. Then, because this posting must -balance, ensure that its value is zero. This can only be true if -Assets:Brokerage does indeed contain 10 AAPL at that point in the input file. +@item I, i, O, 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 -A balanced virtual transaction is used simply to indicate to Ledger that this -is not a "real" transaction. It won't appear in any reports anyway (unless -you use a register report with --empty). +@node Archiving Previous Years , Using Emacs, Journal Format, Keeping a Journal +@section Archiving Previous Years -@node Posting cost, Explicit posting costs, Balance verification, Transactions -@section Posting cost -When you transfer a commodity from one account to another, sometimes it get -transformed during the transaction. This happens when you spend money on gas, -for example, which transforms dollars into gallons of gasoline, or dollars -into stocks in a company. +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. -In those cases, Ledger will remember the "cost" of that transaction for you, -and can use it during reporting in various ways. Here's an example of a stock -purchase: +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}. + +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}: @smallexample - 2012-03-10 My Broker - Assets:Brokerage 10 AAPL - Assets:Brokerage:Cash $-500.00 +ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat @end smallexample -This is different from transferring 10 AAPL shares from one account to -another, in this case you are @emph{exchanging} one commodity for another. The -resulting posting cost is $50.00 per share. - -@node Explicit posting costs, Posting cost expressions, Posting cost, Transactions -@section Explicit posting costs - -You can make any posting's cost explicit using the @ symbol after the amount -or amount expression: +To delete older data from the current ledger file, use @command{print} +again, this time specifying year 2002 as the starting date: @smallexample - 2012-03-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 - Assets:Brokerage:Cash $-500.00 +ledger -f ledger.dat -b 2002 print > x +mv x ledger.dat @end smallexample -When you do this, since Ledger can now figure out the balancing amount from -the first posting's cost, you can elide the other amount: +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 - 2012-03-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 - Assets:Brokerage:Cash +ledger -f ledger-old.dat equity > equity.dat +cat equity.dat ledger.dat > x +mv x ledger.dat +rm equity.dat @end smallexample -@menu -* Primary and secondary commodities:: -@end menu - -@node Primary and secondary commodities, , Explicit posting costs, Explicit posting costs -@subsection Primary and secondary commodities - -It is a general convention within Ledger that the "top" postings in a -transaction contain the target accounts, while the final posting contains the -source account. Whenever a commodity is exchanged like this, the commodity -moved to the target account is considered "secondary", while the commodity -used for purchasing and tracked in the cost is "primary". - -Said another way, whenever Ledger sees a posting cost of the form "AMOUNT @ -AMOUNT", the commodity used in the second amount is marked "primary". +Now the balances reported from @file{ledger.dat} are identical to what +they were before the data was split. -The only meaning a primary commodity has is that -V flag will never convert a -primary commodity into any other commodity. -X still will, however. +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. -@node Posting cost expressions, Total posting costs, Explicit posting costs, Transactions -@section Posting cost expressions +@node Using Emacs, , Archiving Previous Years , Keeping a Journal +@section Using Emacs to Maintain Your Journal +@cindex Emacs -Just as you can have amount expressions, you can have posting expressions: +@menu +* running ledger-mode:: +* Working with entries:: +* Reconciling accounts:: +* Generating Reports:: +@end menu -@smallexample - 2012-03-10 My Broker - Assets:Brokerage 10 AAPL @ ($500.00 / 10) - Assets:Brokerage:Cash -@end smallexample +@node running ledger-mode, Working with entries, Using Emacs, Using Emacs +@subsection Running ledger-mode -You can even have both: +Journal files are simple free text files easily modified by any text +editor. A special mode for Emacs is included with the source +distribution. +@cindex Emacs .emacs file +To use the Emacs mode, copy the several lisp files from the source lisp +directory your your @file{site-lisp} directory and add the following line +to your @file{.emacs} (or equivalent, @file{~/Aquamacs/Preferences.el} +for Aquamacs on Mac OS X) @smallexample - 2012-03-10 My Broker - Assets:Brokerage (5 AAPL * 2) @ ($500.00 / 10) - Assets:Brokerage:Cash +(load "ledger") @end smallexample -@node Total posting costs, Virtual posting costs, Posting cost expressions, Transactions -@section Total posting costs - -The cost figure following the @ character specifies the *per-unit* price for -the commodity being transferred. If you'd like to specify the total cost -instead, use @@@@: - +To trigger ledger mode when you visit a journal file, the first line of +each of your journal files should be: @smallexample - 2012-03-10 My Broker - Assets:Brokerage 10 AAPL @@@@ $500.00 - Assets:Brokerage:Cash +; -*-ledger-*- @end smallexample +To enter ledger-mode on a new file, type M-x ledger-mode. + +Once you have loaded a Journal file into Emacs, you have several +commands available to make entering, clearing and reconciling +transactions and producing reports: -Ledger reads this as if you had written: - -@smallexample - 2012-03-10 My Broker - Assets:Brokerage 10 AAPL @@@@ ($500.00 / 10) - Assets:Brokerage:Cash -@end smallexample +@cindex Emacs commands +@table @code +@item C-i or +auto complete entry +@item C-c C-a +add a new entry, based on previous entries +@item C-c C-e +toggle cleared status of an entire entry +@item C-c C-c +toggle cleared status of an individual posting +@item C-c C-y +set default year for entry mode +@item C-c C-m +set default month for entry mode +@item C-c C-r +reconcile uncleared entries related to an account +@item C-c C-d +delete the current entry +@item C-c C-s +sort all entries in the journal by date. Drop comments outside of entries +@item C-c C-o C-r +run a ledger report +@item C-C C-o C-g +go to the ledger report buffer +@item C-c C-o C-e +edit the defined ledger reports +@item C-c C-o C-s +save a report definition based on the current report +@item C-c C-o C-a +rerun a ledger report +@item C-c C-o C-k +kill the ledger report buffer +@end table -@node Virtual posting costs, Commodity prices, Total posting costs, Transactions -@section Virtual posting costs +@menu +* Working with entries:: +* Reconciling accounts:: +* Generating Reports:: +@end menu -Normally whenever a commodity exchange like this happens, the price of the -exchange (such as $50 per share of AAPL, above) is recorded in Ledger's -internal price history database. To prevent this from happening in the case -of an exceptional transaction, surround the @@ or @@@@ with parentheses: +@node Working with entries, Reconciling accounts, running ledger-mode, Using Emacs +@subsection Working with entries +@menu +* Manual Entry Support:: +* Automagically Adding new entries:: +* Clearing Transactions:: +@end menu -@smallexample - 2012-03-10 My Brother - Assets:Brokerage 1000 AAPL (@@) $1 - Income:Gifts Received -@end smallexample +@node Manual Entry Support, Automagically Adding new entries, Working with entries, Working with entries +@subsubsection Manual Entry Support -@node Commodity prices, Prices vs. costs, Virtual posting costs, Transactions -@section Commodity prices +@cindex completion +@cindex auto-completion +@cindex misspelled accounts treated as new -When a transaction occurs that exchange one commodity for another, Ledger -records that commodity price not only within its internal price database, but -also attached to the commodity itself. Usually this fact remains invisible to -the user, unless you turn on @samp{--lot-prices} to show these hidden price figures. +In most financial programs, some sort of auto-completion is available to +save typing and improve accuracy. Ledger doesn't leave you hanging, +@code{ledger-mode} provides tab completion on all portions of an entry. +Type a portion of the payee and hit , and @code{ledger-mode} will +suggest a completion. When filling in the account type the first few +letters followed by a and the account will be filled in. For +example typing @samp{ExAuF} would yield +@samp{Expenses:Auto:Fuel} if you had previously used that account in +this journal. If there are more than one account with similar starting, +hitting multiple times will iterate through them. This is a good +habit to get in to prevent misspellings of accounts. Remember Ledger +does not validate the names of payees or account so a misspelled account +will be interpreted as a new account by ledger. -For example, consider the stock sale given above: +@node Automagically Adding new entries, Clearing Transactions, Manual Entry Support, Working with entries +@subsubsection Automagically Adding new entries +@cindex new transactions in Emacs +@cindex Emacs, adding new transactions +@code{C-c C-a} will run the @code{ledger entry} command (@pxref{entry +and xact}) from within Emacs. When typed, the mini-buffer will appear +with the current year and month, waiting for you to enter the day and +the payee. Ledger will generate a new entry based on the most recent +entry for that payee, using the amount and accounts from that +transaction. If you have a new amount simply type the amount after the +payee. For example, if your journal contains an entry @smallexample - 2012-03-10 My Broker - Assets:Brokerage 10 AAPL @@ $50.00 - Assets:Brokerage:Cash +2011/11/25 Viva Italiano + Expenses:Food $12.45 + Expenses:Tips $2.55 + Liabilities:MasterCard $-15.00 +@end smallexample +@noindent and you type @samp{C-c C-a}, the mini-buffer will appear showing the +current year and month. If you complete the mini-buffer entry by typing +@smallexample +Entry: 2011/11/28 viva food 34 tip 7 @end smallexample - -The commodity transferred into Assets:Brokerage is not actually 10 AAPL, but -rather 10 AAPL @{$5.00@}. The figure in braces after the amount is called the -"lot price". It's Ledger's way of remembering that this commodity was -transferred through an exchange, and that $5.00 was the price of that -exchange. - -This becomes significant if you later sell that commodity again. For example, -you might write this: - +@noindent Emacs will add the following entry to your journal: @smallexample - 2012-04-10 My Broker - Assets:Brokerage:Cash - Assets:Brokerage -10 AAPL @@ $75.00 +2011/11/30 Viva Italiano + Expenses:Food $34.00 + Expenses:Tips $7.00 + Liabilities:MasterCard @end smallexample - -And that would be perfectly fine, but how do you track the capital gains on -the sale? It could be done with a virtual posting: - +@noindent Notice that the entry will appear at the correct place in the journal +ordered by date, not necessarily at the bottom of the file. +@node Clearing Transactions, , Automagically Adding new entries, Working with entries +@subsubsection Clearing Transactions and Postings +@cindex clearing transactions in Emacs +@cindex Emacs, clear transaction +@code{C-c C-e} will place an asterisk after the date in the current +transaction. The tells ledger the transaction has been cleared through +your bank (or whatever else you want the concept to mean) @smallexample - 2012-04-10 My Broker - Assets:Brokerage:Cash - Assets:Brokerage -10 AAPL @@ $75.00 - (Income:Capital Gains) $-250.00 +2011/11/25 Viva Italiano + Expenses:Food $12.45 + Expenses:Tips $2.55 + Liabilities:MasterCard $-15.00 @end smallexample - -But this gets messy since capital gains income is very real, and not quite -appropriate for a virtual posting. - -Instead, if you reference that same hidden price annotation, Ledger will -figure out that the price of the shares you're selling, and the cost you're -selling them at, don't balance: - +@noindent becomes @smallexample - 2012-04-10 My Broker - Assets:Brokerage:Cash $750.00 - Assets:Brokerage -10 AAPL @{$50.00@} @@ $75.00 +2011/11/25 * Viva Italiano + Expenses:Food $12.45 + Expenses:Tips $2.55 + Liabilities:MasterCard $-15.00 @end smallexample -This transaction will fail because the $250.00 price difference between the -price you bought those shares at, and the cost you're selling them for, does -not match. The lot price also identifies which shares you purchased on that -prior date. +If, for some reason you need to clear a specific posting in the +transaction you can type @samp{C-c C-c} and the posting at point will be +toggled. -@menu -* Total commodity prices:: -@end menu +@node Reconciling accounts, Generating Reports, Working with entries, Using Emacs +@subsection Reconciling accounts -@node Total commodity prices, , Commodity prices, Commodity prices -@subsection Total commodity prices +In the reconcile buffer, use SPACE to toggle the cleared status of a +transaction, C-x C-s to save changes (to the ledger file as well). -As a shorthand, you can specify the total price instead of the per-share -price in doubled braces. This goes well with total costs, but is not required -to be used with them: +@node Generating Reports, , Reconciling accounts, Using Emacs +@subsection Generating Reports -@smallexample - 2012-04-10 My Broker - Assets:Brokerage:Cash $750.00 - Assets:Brokerage -10 AAPL @{@{$500.00@}@} @@@@ $750.00 - Income:Capital Gains $-250.00 -@end smallexample +The ledger reports command asks the user to select a report to run then +creates a report buffer containing the results of running the associated +command line. Its' behavior is modified by a prefix argument which, +when given, causes the generated command line that will be used to +create the report to be presented for editing before the report is +actually run. Arbitrary unnamed command lines can be run by specifying +an empty name for the report. The command line used can later be named +and saved for future use as a named report from the generated reports +buffer. -It should be noted that this is a convenience only for cases where you buy and -sell whole lots. The @{@{$500.00@}@} is @emph{not} an attribute of commodity, whereas -@{$5.00@} is. In fact, when you write @{@{$500.00@}@}, Ledger just divides that -value by 10 and sees @{$50.00@}. So if you use the print command to look at -this transaction, you'll see the single form in the output. The double price -form is a shorthand only. +In a report buffer, the following keys are available: +@table @code +@item (space) +scroll up +@item e +edit the defined ledger reports +@item s +save a report definition based on the current report +@item q +quit the report (return to ledger buffer) +@item r +redo the report +@item k +kill the report buffer +@end table -Plus, it comes with dangers. This works fine: -@smallexample - 2012-04-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 - Assets:Brokerage:Cash $750.00 - 2012-04-10 My Broker - Assets:Brokerage:Cash $375.00 - Assets:Brokerage -5 AAPL @{$50.00@} @@ $375.00 - Income:Capital Gains $-125.00 - 2012-04-10 My Broker - Assets:Brokerage:Cash $375.00 - Assets:Brokerage -5 AAPL @{$50.00@} @@ $375.00 - Income:Capital Gains $-125.00 -@end smallexample +@node Transactions , Building Reports, Keeping a Journal, Top +@chapter Transactions +@menu +* Basic format:: +* Eliding amounts:: +* Auxiliary dates:: +* Codes:: +* Transaction state:: +* Transaction notes:: +* Metadata:: +* Virtual postings:: +* Expression amounts:: +* Balance verification:: +* Posting cost:: +* Explicit posting costs:: +* Posting cost expressions:: +* Total posting costs:: +* Virtual posting costs:: +* Commodity prices:: +* Prices vs. costs:: +* Lot dates:: +* Lot notes:: +* Lot value expressions:: +* Automated transactions:: +@end menu -@noindent But this does not do what you might expect: +@node Basic format, Eliding amounts, Transactions , Transactions +@section Basic format -@smallexample - 2012-04-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 - Assets:Brokerage:Cash $750.00 - 2012-04-10 My Broker - Assets:Brokerage:Cash $375.00 - Assets:Brokerage -5 AAPL @{@{$500.00@}@} @@ $375.00 - Income:Capital Gains $-125.00 +The most basic form of transaction is: - 2012-04-10 My Broker - Assets:Brokerage:Cash $375.00 - Assets:Brokerage -5 AAPL @{@{$500.00@}@} @@ $375.00 - Income:Capital Gains $-125.00 +@smallexample + 2012-03-10 KFC + Expenses:Food $20.00 + Assets:Cash $-20.00 @end smallexample -And in cases where the amounts do not divide into whole figure and must be -rounded, the capital gains figure could be off by a cent. Use with caution. - -@node Prices vs. costs, Lot dates, Commodity prices, Transactions -@section Prices vs. costs +This transaction has a date, a payee or description, a target account (the +first posting), and a source account (the second posting). Each posting +specifies what action is taken related to that account. -Because lot pricing provides enough information to infer the cost, the -following two transactions are equivalent: +A transaction can have any number of postings: @smallexample - 2012-04-10 My Broker - Assets:Brokerage 10 AAPL @ $50.00 - Assets:Brokerage:Cash $750.00 - - 2012-04-10 My Broker - Assets:Brokerage 10 AAPL @{$50.00@} - Assets:Brokerage:Cash $750.00 + 2012-03-10 KFC + Expenses:Food $20.00 + Assets:Cash $-10.00 + Liabilities:Credit $-10.00 @end smallexample -However, note that what you see in some reports may differ, for example in the -print report. Functionally, however, there is no difference, and neither the -register nor the balance report are sensitive to this difference. - -@section Fixated prices +@node Eliding amounts, Auxiliary dates, Basic format, Transactions +@section Eliding amounts -If you buy a stock last year, and ask for its value today, Ledger will consult -its price database to see what the most recent price for that stock is. You -can short-circuit this lookup by ``fixing'' the price at the time of a -transaction. This is done using @{=AMOUNT@}: +The first thing you can do to make things easier is elide amounts. That is, +if exactly one posting has no amount specified, Ledger will infer the inverse +of the other postings' amounts: @smallexample - 2012-04-10 My Broker - Assets:Brokerage 10 AAPL @{=$50.00@} - Assets:Brokerage:Cash $750.00 + 2012-03-10 KFC + Expenses:Food $20.00 + Assets:Cash $-10.00 + Liabilities:Credit ; same as specifying $-10 @end smallexample -These 10 AAPL will now always be reported as being worth $50, no matter what -else happens to the stock in the meantime. +@noindent If the other postings use multiple commodities, Ledger will copy the empty +posting N times and fill in the negated values of the various commodities: -Fixated prices are a special case of using lot valuation expressions (see -below) to fix the value of a commodity lot. +@smallexample + 2012-03-10 KFC + Expenses:Food $20.00 + Expenses:Tips $2.00 + Assets:Cash EUR -10.00 + Assets:Cash GBP -10.00 + Liabilities:Credit +@end smallexample -@menu -* Fixated costs:: -@end menu +@noindent This transaction is identical to writing: -@node Fixated costs, , Prices vs. costs, Prices vs. costs -@subsection Fixated costs +@smallexample + 2012-03-10 KFC + Expenses:Food $20.00 + Expenses:Tips $2.00 + Assets:Cash EUR -10.00 + Assets:Cash GBP -10.00 + Liabilities:Credit $-22.00 + Liabilities:Credit EUR 10.00 + Liabilities:Credit GBP 10.00 +@end smallexample -Since price annotations are costs are largely interchangeable and a matter of -preference, there is an equivalent syntax for specified fixated prices by way -of the cost: +@node Auxiliary dates, Codes, Eliding amounts, Transactions +@section Auxiliary dates + +You can associate a second date with a transaction by following the primary +date with an equals sign: @smallexample - 2012-04-10 My Broker - Assets:Brokerage 10 AAPL @@ =$50.00 - Assets:Brokerage:Cash $750.00 + 2012-03-10=2012-03-08 KFC + Expenses:Food $20.00 + Assets:Cash $-20.00 @end smallexample -This is the same as the previous transaction, with the same caveats found in -the section ``Prices vs. costs''. +What this auxiliary date means is entirely up to you. The only use Ledger has +for it is that if you specify --aux-date, then all reports and calculations +(including pricing) will use the aux date as if it were the primary date. -@node Lot dates, Lot notes, Prices vs. costs, Transactions -@section Lot dates +@node Codes, Transaction state, Auxiliary dates, Transactions +@section Codes -In addition to lot prices, you can specify lot dates and reveal them with -@samp{--lot-dates}. Other than that, however, they have no special meaning to -Ledger. They are specified after the amount in square brackets (the same way -that dates are parsed in value expressions): +A transaction can have a textual "code". This has no meaning and is only +displayed by the print command. Checking accounts often use codes like DEP, +XFER, etc., as well as check numbers. This is to give you a place to put +those codes: @smallexample - 2012-04-10 My Broker - Assets:Brokerage:Cash $375.00 - Assets:Brokerage -5 AAPL @{$50.00@} [2012-04-10] @@ $375.00 - Income:Capital Gains $-125.00 + 2012-03-10 (#100) KFC + Expenses:Food $20.00 + Assets:Checking @end smallexample -@node Lot notes, Lot value expressions, Lot dates, Transactions -@section Lot notes +@node Transaction state, Transaction notes, Codes, Transactions +@section Transaction state -You can also associate arbitrary notes for your own record keeping in -parentheses, and reveal them with --lot-notes. One caveat is that the note -cannot begin with an @ character, as that would indicate a virtual cost: +A transaction can have a ``state'': cleared, pending, or uncleared. The default +is uncleared. To mark a transaction cleared, put a * before the payee, and +after date or code: @smallexample - 2012-04-10 My Broker - Assets:Brokerage:Cash $375.00 - Assets:Brokerage -5 AAPL @{$50.00@} [2012-04-10] (Oh my!) @@ $375.00 - Income:Capital Gains $-125.00 + 2012-03-10 * KFC + Expenses:Food $20.00 + Assets:Cash @end smallexample -You can any combination of lot prices, dates or notes, in any order. They are -all optional. +@noindent To mark it pending, use a !: -To show all lot information in a report, use @samp{--lots}. +@smallexample + 2012-03-10 ! KFC + Expenses:Food $20.00 + Assets:Cash +@end smallexample -@node Lot value expressions, Automated transactions, Lot notes, Transactions -@section Lot value expressions +What these mean is entirely up to you. The --cleared option will limits to +reports to only cleared items, while --uncleared shows both uncleared and +pending items, and --pending shows only pending items. -Normally when you ask Ledger to display the values of commodities held, it -uses a value expression called "market" to determine the most recent value -from its price database -- even downloading prices from the Internet, if -Q -was specified and a suitable "getquote" script is found on your system. +I use cleared to mean that I've reconciled the transaction with my bank +statement, and pending to mean that I'm in the middle of a reconciliation. -However, you can override this valuation logic by providing a commodity -valuation expression in doubled parentheses. This expression must result in -one of two values: either an amount to always be used as the per-share price -for that commodity; or a function taking three argument which is called to -determine that price. -If you use the functional form, you can either specify a function name, or a -lambda expression. Here's a function that yields the price as $10 in whatever -commodity is being requested: +When you clear a transaction, that's really just shorthand for clearing all of +its postings. That is: @smallexample - define ten_dollars(s, date, t) = market($10, date, t) + 2012-03-10 * KFC + Expenses:Food $20.00 + Assets:Cash @end smallexample -I can now use that in a lot value expression as follows: +@noindent Is the same as writing: @smallexample - 2012-04-10 My Broker - Assets:Brokerage:Cash $375.00 - Assets:Brokerage -5 AAPL @{$50.00@} ((ten_dollars)) @@@@ $375.00 - Income:Capital Gains $-125.00 + 2012-03-10 KFC + * Expenses:Food $20.00 + * Assets:Cash @end smallexample -Alternatively, I could do the same thing without pre-defining a function by -using a lambda expression taking three arguments: +@noindent You can mark individual postings as cleared or pending, in case one "side" of +the transaction has cleared, but the other hasn't yet: @smallexample - 2012-04-10 My Broker - A:B:Cash $375.00 - A:B -5 AAPL @{$50.00@} ((s, d, t -> market($10, date, t))) @@@@ $375.00 - Income:Capital Gains $-125.00 + 2012-03-10 KFC + Liabilities:Credit $100.00 + * Assets:Checking @end smallexample -The arguments passed to these functions have the following meaning: - -@itemize -@item source - The source commodity string, or an amount object. If it is a - string, the return value must be an amount representing the - price of the commodity identified by that string (example: "$"). - If it is an amount, return the value of that amount as a new - amount (usually calculated as commodity price * source amount). - -@item date - The date to use for determining the value. If null, it means no - date was specified, which can mean whatever you want it to mean. - -@item target - If not null, a string representing the desired target commodity - that the commodity price, or repriced amount, should be valued - in. Note that this string can be a comma-separated list, and - that some or all of the commodities in that list may be suffixed - with an exclamation mark, to indicate what is being desired. -@end itemize - -In most cases, it is simplest to either use explicit amounts in your valuation -expressions, or just pass the arguments down to market after modifying them to -suit your needs. - -@node Automated transactions, File Format, Lot value expressions, Transactions -@section Automated transactions - -An automated transaction is a special kind of transaction which adds its -postings to other transactions any time one of that other transactions' -postings matches its predicate. The predicate uses the same query syntax as -the Ledger command line. +@node Transaction notes, Metadata, Transaction state, Transactions +@section Transaction notes -Consider this posting: +After the payee, and after at least one tab or two spaces (or a space +and a tab, which Ledger calls this a ``hard separator''), you may +introduce a note about the transaction using the ; character: @smallexample - 2012-03-10 KFC + 2012-03-10 * KFC ; yum, chicken... Expenses:Food $20.00 Assets:Cash @end smallexample -If I write this automated transaction before it in the file: +@noindent Notes can also appear on the next line, so long as that line begins with +whitespace: @smallexample - = expr true - Foo $50.00 - Bar $-50.00 + 2012-03-10 * KFC ; yum, chicken... + ; and more notes... + Expenses:Food $20.00 + Assets:Cash + + 2012-03-10 * KFC + ; just these notes... + Expenses:Food $20.00 + Assets:Cash @end smallexample -Then the first transaction will be modified during parsing as if I'd written -this: + +A transaction note is shared by all its postings. This becomes significant +when querying for metadata (see below). To specify that a note belongs only +to one posting, place it after a hard separator after the amount, or on its +own line preceded by whitespace: @smallexample - 2012-03-10 KFC - Expenses:Food $20.00 - Foo $50.00 - Bar $-50.00 - Assets:Cash $-20.00 - Foo $50.00 - Bar $-50.00 + 2012-03-10 * KFC + Expenses:Food $20.00 ; posting #1 note + Assets:Cash + ; posting #2 note, extra indentation is optional @end smallexample -Despite this fancy logic, automated transactions themselves follow most of the -same rules as regular transactions: their postings must balance (unless you -use a virtual posting), you can have metadata, etc. +@node Metadata, Virtual postings, Transaction notes, Transactions +@section Metadata -One thing you cannot do, however, is elide amounts in an automated -transaction. +One of Ledger's more powerful features is the ability to associate typed +metadata with postings and transactions (by which I mean all of a +transaction's postings). This metadata can be queried, displayed, and used in +calculations. + +The are two forms of metadata: tags and tag/value pairs. @menu -* Amount multipliers:: -* Accessing the matching posting's amount:: -* Referring to the matching posting's account:: -* Applying metadata to every matched posting:: -* Applying metadata to the generated posting:: -* State flags:: -* Effective Dates:: -* Periodic Transactions:: +* Metadata tags:: +* Metadata values:: +* Typed metadata:: @end menu -@node Amount multipliers, Accessing the matching posting's amount, Automated transactions, Automated transactions -@subsection Amount multipliers +@node Metadata tags, Metadata values, Metadata, Metadata +@subsection Metadata tags -As a special case, if an automated transaction's posting's amount (phew) has -no commodity, it is taken as a multiplier upon the matching posting's cost. -For example: +To tag an item, put any word not containing whitespace between two colons: + +@smallexample + 2012-03-10 * KFC + Expenses:Food $20.00 + Assets:Cash + ; :TAG: +@end smallexample + +You can gang up multiple tags by sharing colons: @smallexample - = expr true - Foo 50.00 - Bar -50.00 - - 2012-03-10 KFC + 2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash + ; :TAG1:TAG2:TAG3: @end smallexample -Then the latter transaction turns into this during parsing: +@node Metadata values, Typed metadata, Metadata tags, Metadata +@subsection Metadata values + +To associate a value with a tag, use the syntax "Key: Value", where the value +can be any string of characters. Whitespace is needed after the colon, and +cannot appear in the Key: @smallexample - 2012-03-10 KFC + 2012-03-10 * KFC Expenses:Food $20.00 - Foo $1000.00 - Bar $-1000.00 - Assets:Cash $-20.00 - Foo $1000.00 - Bar $-1000.00 + Assets:Cash + ; MyTag: This is just a bogus value for MyTag @end smallexample -@node Accessing the matching posting's amount, Referring to the matching posting's account, Amount multipliers, Automated transactions -@subsection Accessing the matching posting's amount +@node Typed metadata, , Metadata values, Metadata +@subsection Typed metadata -If you use an amount expression for an automated transaction's posting, that -expression has access to all the details of the matched posting. For example, -you can refer to that posting's amount using the "amount" value expression -variable: +If a metadata tag ends in ::, it's value will be parsed as a value expression +and stored internally as a value rather than as a string. For example, +although I can specify a date textually like so: @smallexample - = expr true - (Foo) (amount * 2) ; same as just "2" in this case - - 2012-03-10 KFC + 2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash + ; AuxDate: 2012/02/30 @end smallexample -This becomes: +@noindent This date is just a string, and won't be parsed as a date unless its value is +used in a date-context (at which time the string is parsed into a date +automatically every time it is needed as a date). If on the other hand I +write this: @smallexample - 2012-03-10 KFC + 2012-03-10 * KFC Expenses:Food $20.00 - (Foo) $40.00 - Assets:Cash $-20.00 - (Foo) $-40.00 + Assets:Cash + ; AuxDate:: [2012/02/30] @end smallexample -@node Referring to the matching posting's account, Applying metadata to every matched posting, Accessing the matching posting's amount, Automated transactions -@subsection Referring to the matching posting's account +@noindent Then it is parsed as a date only once, and during parsing of the journal file, +which would let me know right away that it is an invalid date. -Sometimes want to refer to the account that matched in some way within the -automated transaction itself. This is done by using the string $account, -anywhere within the account part of the automated posting: +@node Virtual postings, Expression amounts, Metadata, Transactions +@section Virtual postings -@smallexample - = food - (Budget:$account) 10 +Ordinarily, the amounts of all postings in a transaction must balance to zero. +This is non-negotiable. It's what double-entry accounting is all about! But +there are some tricks up Ledger's sleeve... - 2012-03-10 KFC +You can use virtual accounts to transfer amounts to an account on the sly, +bypassing the balancing requirement. The trick is that these postings are not +considered ``real'', and can be removed from all reports using @samp{--real}. + +To specify a virtual account, surround the account name with parentheses: + +@smallexample + 2012-03-10 * KFC Expenses:Food $20.00 Assets:Cash + (Budget:Food) $-20.00 @end smallexample -Becomes: +If you want, you can state that virtual postings @emph{should} balance against +one or more other virtual postings by using brackets (which look ``harder'') +rather than parentheses: @smallexample - 2012-03-10 KFC + 2012-03-10 * KFC Expenses:Food $20.00 - (Budget:Expenses:Food) $200.00 - Assets:Cash $-20.00 + Assets:Cash + [Budget:Food] $-20.00 + [Equity:Budgets] $20.00 @end smallexample -@node Applying metadata to every matched posting, Applying metadata to the generated posting, Referring to the matching posting's account, Automated transactions -@subsection Applying metadata to every matched posting +@node Expression amounts, Balance verification, Virtual postings, Transactions +@section Expression amounts -If the automated transaction has a transaction note, that note is copied -(along with any metadata) to every posting that matches the predicate: +An amount is usually a numerical figure with an (optional) commodity, but it +can also be any value expression. To indicate this, surround the amount +expression with parentheses: @smallexample - = food - ; Foo: Bar - (Budget:$account) 10 - - 2012-03-10 KFC - Expenses:Food $20.00 + 2012-03-10 * KFC + Expenses:Food ($10.00 + $20.00) ; Ledger adds it up for you Assets:Cash @end smallexample -Becomes: +@node Balance verification, Posting cost, Expression amounts, Transactions +@section Balance verification +@menu +* Balance assertions:: +* Balance assignments:: +* Resetting a balance:: +* Balancing transactions:: +@end menu + +If at the end of a posting's amount (and after the cost too, if there is one) +there is an equals sign, then Ledger will verify that the total value for that +account as of that posting matches the amount specified. + +There are two forms of this features: balance assertions, and balance +assignments. + + +@node Balance assertions, Balance assignments, Balance verification, Balance verification +@subsection Balance assertions + +A balance assertion has this general form: @smallexample 2012-03-10 KFC Expenses:Food $20.00 - ; Foo: Bar - (Budget:Expenses:Food) $200.00 - Assets:Cash $-20.00 + Assets:Cash $-20.00 = $500.00 @end smallexample -@node Applying metadata to the generated posting, State flags, Applying metadata to every matched posting, Automated transactions -@subsection Applying metadata to the generated posting +This simply asserts that after subtracting $20.00 from Assets:Cash, that the +resulting total matches $500.00. If not, it is an error. -If the automated transaction's posting has a note, that note is carried to the -generated posting within the matched transaction: +@node Balance assignments, Resetting a balance, Balance assertions, Balance verification +@subsection Balance assignments -@smallexample - = food - (Budget:$account) 10 - ; Foo: Bar +A balance assignment has this form: +@smallexample 2012-03-10 KFC Expenses:Food $20.00 - Assets:Cash + Assets:Cash = $500.00 @end smallexample -Becomes: +This sets the amount of the second posting to whatever it would need to be for +the total in Assets:Cash to be $500.00 after the posting. If the resulting +amount is not $-20.00 in this case, it is an error. + +@node Resetting a balance, Balancing transactions, Balance assignments, Balance verification +@subsection Resetting a balance + +Say your book-keeping has gotten a bit out of date, and your Ledger balance no +longer matches your bank balance. You can create an adjustment transaction +using balance assignments: @smallexample - 2012-03-10 KFC - Expenses:Food $20.00 - (Budget:Expenses:Food) $200.00 - ; Foo: Bar - Assets:Cash $-20.00 + 2012-03-10 Adjustment + Assets:Cash = $500.00 + Equity:Adjustments @end smallexample -This is slightly different from the rules for regular transaction notes, in -that an automated transaction's note does not apply to every posting within -the automated transaction itself, but rather to every posting it matches. - -@node State flags, Effective Dates, Applying metadata to the generated posting, Automated transactions -@subsection State flags +Since the second posting is also null, it's value will become the inverse of +whatever amount is generated for the first posting. -Although you cannot mark an automated transaction as a whole as cleared or -pending, you can mark its postings with a * or ! before the account name, and -that state flag gets carried to the generated posting. +This is the only time in ledger when more than one posting's amount may be +empty -- and then only because it's not true empty, it is indirectly provided +by the balance assignment's value. -@node Effective Dates, Periodic Transactions, State flags, Automated transactions -@subsection Effective Dates -@cindex effective dates +@node Balancing transactions, , Resetting a balance, Balance verification +@subsection Balancing transactions -In the real world transactions do not take place instantaneously. -Purchases can take several days to post to a bank account. And you may -pay ahead for something for which you want to distribute costs. With -Ledger you can control every aspect of the timing of a transaction. +As a consequence of all the above, consider the following transaction: -Say you're in business. If you bill a customer, you can enter -something like -@cindex effective date of invoice @smallexample -2008/01/01=2008/01/14 Client invoice ; estimated date you'll be paid - Assets:Accounts Receivable $100.00 - Income: Client name + 2012-03-10 My Broker + [Assets:Brokerage] = 10 AAPL @end smallexample -@noindent Then, when you receive the payment, you change it to -@smallexample -2008/01/01=2008/01/15 Client invoice ; actual date money received - Assets:Accounts Receivable $100.00 - Income: Client name -@end smallexample -@noindent and add something like +What this says is: set the amount of the posting to whatever value is needed +so that Assets:Brokerage contains 10 AAPL. Then, because this posting must +balance, ensure that its value is zero. This can only be true if +Assets:Brokerage does indeed contain 10 AAPL at that point in the input file. -@smallexample -2008/01/15 Client payment - Assets:Checking $100.00 - Assets:Accounts Receivable -@end smallexample -Now +A balanced virtual transaction is used simply to indicate to Ledger that this +is not a "real" transaction. It won't appear in any reports anyway (unless +you use a register report with --empty). + +@node Posting cost, Explicit posting costs, Balance verification, Transactions +@section Posting cost + +When you transfer a commodity from one account to another, sometimes it get +transformed during the transaction. This happens when you spend money on gas, +for example, which transforms dollars into gallons of gasoline, or dollars +into stocks in a company. + +In those cases, Ledger will remember the "cost" of that transaction for you, +and can use it during reporting in various ways. Here's an example of a stock +purchase: @smallexample - ledger --subtotal --begin 2008/01/01 --end 2008/01/14 bal Income -@end smallexample -@noindent gives you your accrued income in the first two weeks of the year, and -@smallexample - ledger --effective --subtotal --begin 2008/01/01 --end 2008/01/14 bal Income + 2012-03-10 My Broker + Assets:Brokerage 10 AAPL + Assets:Brokerage:Cash $-500.00 @end smallexample -@noindent gives you your cash basis income in the same two weeks. -Another use is distributing costs out in time. As an example, suppose -you just prepaid into a local vegetable co-op that sustains you through -the winter. It cost $225 to join the program, so you write a check. -You don't want your October grocery budget to be blown because you bought -food ahead, however. What you really want is for the money to be evenly -distributed over the next six months so that your monthly budgets -gradually take a hit for the vegetables you'll pick up from the co-op, -even though you've already paid for them. +This is different from transferring 10 AAPL shares from one account to +another, in this case you are @emph{exchanging} one commodity for another. The +resulting posting cost is $50.00 per share. + +@node Explicit posting costs, Posting cost expressions, Posting cost, Transactions +@section Explicit posting costs + +You can make any posting's cost explicit using the @ symbol after the amount +or amount expression: @smallexample -2008/10/16 * (2090) Bountiful Blessings Farm - Expenses:Food:Groceries $ 37.50 ; [=2008/10/01] - Expenses:Food:Groceries $ 37.50 ; [=2008/11/01] - Expenses:Food:Groceries $ 37.50 ; [=2008/12/01] - Expenses:Food:Groceries $ 37.50 ; [=2009/01/01] - Expenses:Food:Groceries $ 37.50 ; [=2009/02/01] - Expenses:Food:Groceries $ 37.50 ; [=2009/03/01] - Assets:Checking + 2012-03-10 My Broker + Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage:Cash $-500.00 @end smallexample -This entry accomplishes this. Every month until you'll start with an -automatic $37.50 deficit like you should, while your checking account -really knows that it debited $225 this month. - +When you do this, since Ledger can now figure out the balancing amount from +the first posting's cost, you can elide the other amount: -@node Periodic Transactions, , Effective Dates, Automated transactions -@subsection Periodic Transactions +@smallexample + 2012-03-10 My Broker + Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage:Cash +@end smallexample -A periodic transaction starts with a ~ followed by a period expression. -Periodic transactions are used for budgeting and forecasting only, they -have no effect without the @samp{--budget} option specified. +@menu +* Primary and secondary commodities:: +@end menu -See @ref{Budgeting and Forecasting} for examples and details. +@node Primary and secondary commodities, , Explicit posting costs, Explicit posting costs +@subsection Primary and secondary commodities +It is a general convention within Ledger that the "top" postings in a +transaction contain the target accounts, while the final posting contains the +source account. Whenever a commodity is exchanged like this, the commodity +moved to the target account is considered "secondary", while the commodity +used for purchasing and tracked in the cost is "primary". +Said another way, whenever Ledger sees a posting cost of the form "AMOUNT @ +AMOUNT", the commodity used in the second amount is marked "primary". +The only meaning a primary commodity has is that -V flag will never convert a +primary commodity into any other commodity. -X still will, however. -@node File Format, Archiving Previous Years , Automated transactions, Transactions -@section File Format for Users -@menu -* File Format Intro:: -* Transaction and Comments:: -* Command Directives:: -@end menu +@node Posting cost expressions, Total posting costs, Explicit posting costs, Transactions +@section Posting cost expressions -@node File Format Intro, Transaction and Comments, File Format, File Format -@subsection Introduction -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. +Just as you can have amount expressions, you can have posting expressions: -@node Transaction and Comments, Command Directives, File Format Intro, File Format -@subsection Transactions and Comments -The initial character of each line determines what the line means, and -how it should be interpreted. Allowable initial characters are: +@smallexample + 2012-03-10 My Broker + Assets:Brokerage 10 AAPL @ ($500.00 / 10) + Assets:Brokerage:Cash +@end smallexample -@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 white-space, to denote the -transaction's account postings. The format of the first line is: +You can even have both: @smallexample -DATE[=EDATE] [*|!] [(CODE)] DESC + 2012-03-10 My Broker + Assets:Brokerage (5 AAPL * 2) @ ($500.00 / 10) + Assets:Brokerage:Cash @end smallexample -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. +@node Total posting costs, Virtual posting costs, Posting cost expressions, Transactions +@section Total posting costs -The format of each following posting is: +The cost figure following the @ character specifies the @emph{per-unit} price for +the commodity being transferred. If you'd like to specify the total cost +instead, use @@@@: @smallexample - ACCOUNT AMOUNT [; NOTE] + 2012-03-10 My Broker + Assets:Brokerage 10 AAPL @@@@ $500.00 + Assets:Brokerage:Cash @end smallexample -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 postings}) +Ledger reads this as if you had written: -@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 -P DATE SYMBOL PRICE + 2012-03-10 My Broker + Assets:Brokerage 10 AAPL @@@@ ($500.00 / 10) + Assets:Brokerage:Cash @end smallexample -@item = -An automated transaction. A value expression must appear after the equal -sign. - -After this initial line there should be a set of one or more -postings, just as if it were normal transaction. If the amounts of the -postings have no commodity, they will be applied as modifiers to -whichever real posting is matched by the value expression(See @pxref{Automated transactions}). - -@item ~ -A period transaction. A period expression must appear after the tilde. - -After this initial line there should be a set of one or more -postings, just as if it were normal transaction. +@node Virtual posting costs, Commodity prices, Total posting costs, Transactions +@section Virtual posting costs -@item ; # % | * -A line beginning with a colon, pound, percent, bar or asterisk 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 the reporting and filtering capabilities of -Ledger. -@end table +Normally whenever a commodity exchange like this happens, the price of the +exchange (such as $50 per share of AAPL, above) is recorded in Ledger's +internal price history database. To prevent this from happening in the case +of an exceptional transaction, surround the @@ or @@@@ with parentheses: -@node Command Directives, , Transaction and Comments, File Format -@subsection Command Directives +@smallexample + 2012-03-10 My Brother + Assets:Brokerage 1000 AAPL (@@) $1 + Income:Gifts Received +@end smallexample -@table @code -@item beginning of line -Command directives must occur at the beginning of a line. Use of ! and -@@ is deprecated. +@node Commodity prices, Prices vs. costs, Virtual posting costs, Transactions +@section Commodity prices -@item account +When a transaction occurs that exchange one commodity for another, Ledger +records that commodity price not only within its internal price database, but +also attached to the commodity itself. Usually this fact remains invisible to +the user, unless you turn on @samp{--lot-prices} to show these hidden price figures. -The @samp{account} directive supports several optional sub-directives, if they -immediately follow the account directive and if they begin with whitespace: +For example, consider the stock sale given above: @smallexample - account Expenses:Food - note This account is all about the chicken! - alias food - payee ^(KFC|Popeyes)$ - check commodity == "$" - assert commodity == "$" - eval print("Hello!") - default + 2012-03-10 My Broker + Assets:Brokerage 10 AAPL @@ $50.00 + Assets:Brokerage:Cash @end smallexample -The @samp{note} sub-directive associates a textual note with the account. This can -be accessed later using the @samp{note} valexpr function in any account context. - -The @samp{alias} sub-directive, which can occur multiple times, allows the alias to -be used in place of the full account name anywhere that account names are -allowed. +The commodity transferred into Assets:Brokerage is not actually 10 AAPL, but +rather 10 AAPL @{$5.00@}. The figure in braces after the amount is called the +``lot price''. It's Ledger's way of remembering that this commodity was +transferred through an exchange, and that $5.00 was the price of that +exchange. -The @samp{payee} sub-directive, which can occur multiple times, provides regexps -that identify the account if that payee is encountered and an account within -its transaction ends in the name "Unknown". Example: +This becomes significant if you later sell that commodity again. For example, +you might write this: @smallexample - 2012-02-27 KFC - Expenses:Unknown $10.00 ; Read now as "Expenses:Food" - Assets:Cash + 2012-04-10 My Broker + Assets:Brokerage:Cash + Assets:Brokerage -10 AAPL @@ $75.00 @end smallexample -The @samp{check} and @samp{assert} directives warn or error (respectively) if the given -value expression evaluates to false within the context of any posting. +And that would be perfectly fine, but how do you track the capital gains on +the sale? It could be done with a virtual posting: -The @samp{eval} directive evaluates the value expression in the context of the -account at the time of definition. At the moment this has little value. +@smallexample + 2012-04-10 My Broker + Assets:Brokerage:Cash + Assets:Brokerage -10 AAPL @@ $75.00 + (Income:Capital Gains) $-250.00 +@end smallexample -The @samp{default} directive specifies that this account should be used as the -``balancing account'' for any future transactions that contain only a single -posting. +But this gets messy since capital gains income is very real, and not quite +appropriate for a virtual posting. -@item apply account -@c instance_t::master_account_directive -Sets the root for all accounts following the directive. Ledger supports -a hierarchical tree of accounts. It may be convenient to keep two -``root accounts''. For example you may be tracking your personal -finances and your business finances. In order to keep them separate you -could preface all personal accounts with @code{personal:} and all -business account with @code{business:}. You can easily split out large -groups of transaction without manually editing them using the account -directive. For example: +Instead, if you reference that same hidden price annotation, Ledger will +figure out that the price of the shares you're selling, and the cost you're +selling them at, don't balance: @smallexample -apply account Personal -2011/11/15 Supermarket - Expenses:Groceries - Assets:Checking + 2012-04-10 My Broker + Assets:Brokerage:Cash $750.00 + Assets:Brokerage -10 AAPL @{$50.00@} @@ $75.00 @end smallexample -Would result in all postings going into -@code{Personal:Expenses:Groceries} and @code{Personal:Assets:hecking} -until and @code{end apply account} directive was found. +This transaction will fail because the $250.00 price difference between the +price you bought those shares at, and the cost you're selling them for, does +not match. The lot price also identifies which shares you purchased on that +prior date. -@item alias -@c instance_t::alias_directive -Define an alias for an account name. If you have a deeply nested tree -of accounts, it may be convenient to define an alias, for example: -@smallexample +@menu +* Total commodity prices:: +@end menu -alias Dining=Expenses:Entertainment:Dining -alias Checking=Assets:Credit Union:Joint Checking Account +@node Total commodity prices, , Commodity prices, Commodity prices +@subsection Total commodity prices -2011/11/28 YummyPalace - Dining $10.00 - Checking +As a shorthand, you can specify the total price instead of the per-share +price in doubled braces. This goes well with total costs, but is not required +to be used with them: +@smallexample + 2012-04-10 My Broker + Assets:Brokerage:Cash $750.00 + Assets:Brokerage -10 AAPL @{@{$500.00@}@} @@@@ $750.00 + Income:Capital Gains $-250.00 @end smallexample -The aliases are only in effect for transactions read in after the alias -is defined and are effected by @code{account} directives that precede -them. -@item assert -@c instance_t::assert_directive -An assertion can throw an error if a condition is not met during Ledger's run. +It should be noted that this is a convenience only for cases where you buy and +sell whole lots. The @{@{$500.00@}@} is @emph{not} an attribute of commodity, whereas +@{$5.00@} is. In fact, when you write @{@{$500.00@}@}, Ledger just divides that +value by 10 and sees @{$50.00@}. So if you use the print command to look at +this transaction, you'll see the single form in the output. The double price +form is a shorthand only. + +Plus, it comes with dangers. This works fine: @smallexample + 2012-04-10 My Broker + Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage:Cash $750.00 -assert + 2012-04-10 My Broker + Assets:Brokerage:Cash $375.00 + Assets:Brokerage -5 AAPL @{$50.00@} @@ $375.00 + Income:Capital Gains $-125.00 + 2012-04-10 My Broker + Assets:Brokerage:Cash $375.00 + Assets:Brokerage -5 AAPL @{$50.00@} @@ $375.00 + Income:Capital Gains $-125.00 @end smallexample +@noindent But this does not do what you might expect: -@item bucket -@c instance_t::default_account_directive -Defines the default account to use for balancing transactions. -Normally, each transaction has at least two postings, which must balance -to zero. Ledger allows you to leave one posting with no amount and -automatically calculate balance the transaction in the posting. The -@code{bucket} allows you to fill in all postings and automatically -generate an additional posting to the bucket account balancing the -transaction. The following example set the @code{Assets:Checking} as -the bucket: @smallexample + 2012-04-10 My Broker + Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage:Cash $750.00 -bucket Assets:Checking -2011/01/25 Tom's Used Cars - Expenses:Auto $ 5,500.00 + 2012-04-10 My Broker + Assets:Brokerage:Cash $375.00 + Assets:Brokerage -5 AAPL @{@{$500.00@}@} @@ $375.00 + Income:Capital Gains $-125.00 -2011/01/27 Book Store - Expenses:Books $20.00 + 2012-04-10 My Broker + Assets:Brokerage:Cash $375.00 + Assets:Brokerage -5 AAPL @{@{$500.00@}@} @@ $375.00 + Income:Capital Gains $-125.00 +@end smallexample -2011/12/01 Sale - Assets:Checking:Business $ 30.00 +And in cases where the amounts do not divide into whole figure and must be +rounded, the capital gains figure could be off by a cent. Use with caution. -@end smallexample +@node Prices vs. costs, Lot dates, Commodity prices, Transactions +@section Prices vs. costs -@item capture -@c instance_t::account_mapping_directive -Directs Ledger to replace any account matching a regex with the given -account. For example: +Because lot pricing provides enough information to infer the cost, the +following two transactions are equivalent: @smallexample -capture Expenses:Deductible:Medical Medical -@end smallexample + 2012-04-10 My Broker + Assets:Brokerage 10 AAPL @ $50.00 + Assets:Brokerage:Cash $750.00 -Would cause any posting with @code{Medical} in it's name to be replaced with -@code{Expenses:Deductible:Medical}. + 2012-04-10 My Broker + Assets:Brokerage 10 AAPL @{$50.00@} + Assets:Brokerage:Cash $750.00 +@end smallexample +However, note that what you see in some reports may differ, for example in the +print report. Functionally, however, there is no difference, and neither the +register nor the balance report are sensitive to this difference. -Ledger will display the mapped payees in @code{print} and -@code{register} reports. +@section Fixated prices -@item check -@c instance_t::check_directive in textual.cc -A check can issue a warning if a condition is not met during Ledger's run. +If you buy a stock last year, and ask for its value today, Ledger will consult +its price database to see what the most recent price for that stock is. You +can short-circuit this lookup by ``fixing'' the price at the time of a +transaction. This is done using @{=AMOUNT@}: @smallexample + 2012-04-10 My Broker + Assets:Brokerage 10 AAPL @{=$50.00@} + Assets:Brokerage:Cash $750.00 +@end smallexample -check +These 10 AAPL will now always be reported as being worth $50, no matter what +else happens to the stock in the meantime. -@end smallexample -@item comment -@c instance_t::comment_directive in textual.cc -Start a block comment, closed by @code{end comment}. +Fixated prices are a special case of using lot valuation expressions (see +below) to fix the value of a commodity lot. -@item commodity -Pre-declare commodity names. This only has effect if @samp{--strict} or -@samp{--pedantic} is used (see below). +@menu +* Fixated costs:: +@end menu - commodity $ - commodity CAD +@node Fixated costs, , Prices vs. costs, Prices vs. costs +@subsection Fixated costs -The @samp{commodity} directive supports several optional sub-directives, if they -immediately follow the commodity directive and if they begin with whitespace: +Since price annotations are costs are largely interchangeable and a matter of +preference, there is an equivalent syntax for specified fixated prices by way +of the cost: @smallexample - commodity $ - note American Dollars - format $1,000.00 - nomarket - default + 2012-04-10 My Broker + Assets:Brokerage 10 AAPL @@ =$50.00 + Assets:Brokerage:Cash $750.00 @end smallexample -The @samp{note} sub-directive associates a textual note with the commodity. At -present this has no value other than documentation. - -The @samp{format} directive gives you a way to tell Ledger how to format this -commodity. In future using this directive will disable Ledger's observation -of other ways that commodity is used, and will provide the ``canonical'' -representation. +This is the same as the previous transaction, with the same caveats found in +the section ``Prices vs. costs''. -The @samp{nomarket} directive states that the commodity's price should never be -auto-downloaded. +@node Lot dates, Lot notes, Prices vs. costs, Transactions +@section Lot dates -The @samp{default} directive marks this as the ``default'' commodity. +In addition to lot prices, you can specify lot dates and reveal them with +@samp{--lot-dates}. Other than that, however, they have no special meaning to +Ledger. They are specified after the amount in square brackets (the same way +that dates are parsed in value expressions): -@item define -@c instance_t::define_directive in textual.cc -Allows you to define value expression for future use. For example: @smallexample -define var_name=$100 + 2012-04-10 My Broker + Assets:Brokerage:Cash $375.00 + Assets:Brokerage -5 AAPL @{$50.00@} [2012-04-10] @@ $375.00 + Income:Capital Gains $-125.00 +@end smallexample -2011/12/01 Test - Expenses (var_name*4) - Assets +@node Lot notes, Lot value expressions, Lot dates, Transactions +@section Lot notes + +You can also associate arbitrary notes for your own record keeping in +parentheses, and reveal them with --lot-notes. One caveat is that the note +cannot begin with an @ character, as that would indicate a virtual cost: + +@smallexample + 2012-04-10 My Broker + Assets:Brokerage:Cash $375.00 + Assets:Brokerage -5 AAPL @{$50.00@} [2012-04-10] (Oh my!) @@ $375.00 + Income:Capital Gains $-125.00 @end smallexample -The posting will have a cost of $400. -@item end -@c instance_t::end_directive in textual.cc -Closes block commands like @code{tag} or @code{comment}. -@item expr -@c instance_t::expr_directive in textual.cc +You can any combination of lot prices, dates or notes, in any order. They are +all optional. -@item fixed -@c instance_t::fixed_directive in textual.cc +To show all lot information in a report, use @samp{--lots}. -@item include -@c instance_t::include_directive in textual.cc -Include the stated file as if it were part of the current file. +@node Lot value expressions, Automated transactions, Lot notes, Transactions +@section Lot value expressions -@item payee -@c instance_t::payee_mapping_directive in textual.cc -The @samp{payee} directive supports one optional sub-directive, if it immediately -follows the payee directive and if it begins with whitespace: +Normally when you ask Ledger to display the values of commodities held, it +uses a value expression called ``market'' to determine the most recent value +from its price database -- even downloading prices from the Internet, if -Q +was specified and a suitable ``getquote'' script is found on your system. + +However, you can override this valuation logic by providing a commodity +valuation expression in doubled parentheses. This expression must result in +one of two values: either an amount to always be used as the per-share price +for that commodity; or a function taking three argument which is called to +determine that price. + +If you use the functional form, you can either specify a function name, or a +lambda expression. Here's a function that yields the price as $10 in whatever +commodity is being requested: @smallexample - payee KFC - alias KENTUCKY FRIED CHICKEN + define ten_dollars(s, date, t) = market($10, date, t) @end smallexample -The @samp{alias} directive provides a regexp which, if it matches a parsed payee, -the declared payee name is substituted: +I can now use that in a lot value expression as follows: @smallexample - 2012-02-27 KENTUCKY FRIED CHICKEN ; will be read as being 'KFC' - ... + 2012-04-10 My Broker + Assets:Brokerage:Cash $375.00 + Assets:Brokerage -5 AAPL @{$50.00@} ((ten_dollars)) @@@@ $375.00 + Income:Capital Gains $-125.00 @end smallexample -Ledger will display the mapped payees in @code{print} and -@code{register} reports. +Alternatively, I could do the same thing without pre-defining a function by +using a lambda expression taking three arguments: -@item apply tag -@c instance_t::tag_directive in textual.cc -Allows you to designate a block of transactions and assign the same tag to all. Tags can have values and may be nested. @smallexample -apply tag hastag -apply tag nestedtag: true -2011/01/25 Tom's Used Cars - Expenses:Auto $ 5,500.00 - ; :nobudget: - Assets:Checking - -2011/01/27 Book Store - Expenses:Books $20.00 - Liabilities:MasterCard + 2012-04-10 My Broker + A:B:Cash $375.00 + A:B -5 AAPL @{$50.00@} ((s, d, t -> market($10, date, t))) @@@@ $375.00 + Income:Capital Gains $-125.00 +@end smallexample -end apply tag nestedtag +The arguments passed to these functions have the following meaning: -2011/12/01 Sale - Assets:Checking:Business $ 30.00 - Income:Sales -end apply tag hastag -@end smallexample +@itemize +@item source + The source commodity string, or an amount object. If it is a + string, the return value must be an amount representing the + price of the commodity identified by that string (example: ``$''). + If it is an amount, return the value of that amount as a new + amount (usually calculated as commodity price times source amount). -@noindent is the equivalent of +@item date + The date to use for determining the value. If null, it means no + date was specified, which can mean whatever you want it to mean. -@smallexample -2011/01/25 Tom's Used Cars - :hastag: - nestedtag: true - Expenses:Auto $ 5,500.00 - ; :nobudget: - Assets:Checking +@item target + If not null, a string representing the desired target commodity + that the commodity price, or repriced amount, should be valued + in. Note that this string can be a comma-separated list, and + that some or all of the commodities in that list may be suffixed + with an exclamation mark, to indicate what is being desired. +@end itemize -2011/01/27 Book Store - :hastag: - nestedtag: true - Expenses:Books $20.00 - Liabilities:MasterCard +In most cases, it is simplest to either use explicit amounts in your valuation +expressions, or just pass the arguments down to market after modifying them to +suit your needs. -2011/12/01 Sale - :hastag: - Assets:Checking:Business $ 30.00 - Income:Sales -@end smallexample +@node Automated transactions, , Lot value expressions, Transactions +@section Automated transactions -Note that anything following ``@code{end tag}'' is ignored. placing the -name of the tag that is being closed is a simple way to keep track. +An automated transaction is a special kind of transaction which adds its +postings to other transactions any time one of that other transactions' +postings matches its predicate. The predicate uses the same query syntax as +the Ledger command line. -@item tag -Pre-declares tag names. This only has effect if @samp{--strict} or -@item{--pedantic} is used (see below). +Consider this posting: @smallexample - tag Receipt - tag CSV + 2012-03-10 KFC + Expenses:Food $20.00 + Assets:Cash @end smallexample -The 'tag' directive supports two optional sub-directives, if they immediately -follow the tag directive and if they begin with whitespace: +If I write this automated transaction before it in the file: @smallexample - tag Receipt - check value =~ /pattern/ - assert value != "foobar" + = expr true + Foo $50.00 + Bar $-50.00 @end smallexample -The @samp{check} and @samp{assert} directives warn or error (respectively) if the given -value expression evaluates to false within the context of any use of the -related tag. In such a context, ``value'' is bound to the value of the tag -(which may not be a string if typed-metadata is used!). Such checks or -assertions are not called if no value is given. - -@item test -@c instance_t::comment_directive in textual.cc -This is a synonym for @code{comment} and must be closed by and @code{end} tag. +Then the first transaction will be modified during parsing as if I'd written +this: -@item year -@c instance_t::year_directive in textual.cc -Denotes the year used for all subsequent transactions that give a date -without a year. The year should appear immediately after the Y, for -example: @samp{year 2004}. This is useful at the beginning of a file, to -specify the year for that file. If all transactions specify a year, -however, this command has no effect. +@smallexample + 2012-03-10 KFC + Expenses:Food $20.00 + Foo $50.00 + Bar $-50.00 + Assets:Cash $-20.00 + Foo $50.00 + Bar $-50.00 +@end smallexample -@end table +Despite this fancy logic, automated transactions themselves follow most of the +same rules as regular transactions: their postings must balance (unless you +use a virtual posting), you can have metadata, etc. -The following single letter commands may be at the beginning of a line -alone, for backwards compatibility with older Ledger versions. +One thing you cannot do, however, is elide amounts in an automated +transaction. +@menu +* Amount multipliers:: +* Accessing the matching posting's amount:: +* Referring to the matching posting's account:: +* Applying metadata to every matched posting:: +* Applying metadata to the generated posting:: +* State flags:: +* Effective Dates:: +* Periodic Transactions:: +@end menu -@table @code -@item A -See @code{bucket} -@item Y -See @code{year} +@node Amount multipliers, Accessing the matching posting's amount, Automated transactions, Automated transactions +@subsection Amount multipliers +As a special case, if an automated transaction's posting's amount (phew) has +no commodity, it is taken as a multiplier upon the matching posting's cost. +For example: -@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 -N SYMBOL -@end smallexample + = expr true + Foo 50.00 + Bar -50.00 -@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 + 2012-03-10 KFC + Expenses:Food $20.00 + Assets:Cash @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: +Then the latter transaction turns into this during parsing: + @smallexample -C 1.00 Kb = 1024 bytes + 2012-03-10 KFC + Expenses:Food $20.00 + Foo $1000.00 + Bar $-1000.00 + Assets:Cash $-20.00 + Foo $1000.00 + Bar $-1000.00 @end smallexample -@item I, i, O, 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 - -@node Archiving Previous Years , Using Emacs, File Format, Transactions -@section Archiving Previous Years +@node Accessing the matching posting's amount, Referring to the matching posting's account, Amount multipliers, Automated transactions +@subsection Accessing the matching posting's amount +If you use an amount expression for an automated transaction's posting, that +expression has access to all the details of the matched posting. For example, +you can refer to that posting's amount using the ``amount'' value expression +variable: -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 true + (Foo) (amount * 2) ; same as just "2" in this case -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}. + 2012-03-10 KFC + Expenses:Food $20.00 + Assets:Cash +@end smallexample -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}: +This becomes: @smallexample -ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat + 2012-03-10 KFC + Expenses:Food $20.00 + (Foo) $40.00 + Assets:Cash $-20.00 + (Foo) $-40.00 @end smallexample -To delete older data from the current ledger file, use @command{print} -again, this time specifying year 2002 as the starting date: +@node Referring to the matching posting's account, Applying metadata to every matched posting, Accessing the matching posting's amount, Automated transactions +@subsection Referring to the matching posting's account + +Sometimes want to refer to the account that matched in some way within the +automated transaction itself. This is done by using the string $account, +anywhere within the account part of the automated posting: @smallexample -ledger -f ledger.dat -b 2002 print > x -mv x ledger.dat + = food + (Budget:$account) 10 + + 2012-03-10 KFC + Expenses:Food $20.00 + Assets:Cash @end smallexample -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: +Becomes: @smallexample -ledger -f ledger-old.dat equity > equity.dat -cat equity.dat ledger.dat > x -mv x ledger.dat -rm equity.dat + 2012-03-10 KFC + Expenses:Food $20.00 + (Budget:Expenses:Food) $200.00 + Assets:Cash $-20.00 @end smallexample -Now the balances reported from @file{ledger.dat} are identical to what -they were before the data was split. +@node Applying metadata to every matched posting, Applying metadata to the generated posting, Referring to the matching posting's account, Automated transactions +@subsection Applying metadata to every matched posting -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. +If the automated transaction has a transaction note, that note is copied +(along with any metadata) to every posting that matches the predicate: -@node Using Emacs, , Archiving Previous Years , Transactions -@section Using Emacs to Maintain Your Journal -@cindex Emacs +@smallexample + = food + ; Foo: Bar + (Budget:$account) 10 -@menu -* running ledger-mode:: -* Working with entries:: -* Reconciling accounts:: -* Generating Reports:: -@end menu + 2012-03-10 KFC + Expenses:Food $20.00 + Assets:Cash +@end smallexample -@node running ledger-mode, Working with entries, Using Emacs, Using Emacs -@subsection Running ledger-mode +Becomes: -Journal files are simple free text files easily modified by any text -editor. A special mode for Emacs is included with the source -distribution. +@smallexample + 2012-03-10 KFC + Expenses:Food $20.00 + ; Foo: Bar + (Budget:Expenses:Food) $200.00 + Assets:Cash $-20.00 +@end smallexample + +@node Applying metadata to the generated posting, State flags, Applying metadata to every matched posting, Automated transactions +@subsection Applying metadata to the generated posting + +If the automated transaction's posting has a note, that note is carried to the +generated posting within the matched transaction: -@cindex Emacs .emacs file -To use the Emacs mode, copy the several lisp files from the source lisp -directory your your @file{site-lisp} directory and add the following line -to your @file{.emacs} (or equivalent, @file{~/Aquamacs/Preferences.el} -for Aquamacs on Mac OS X) @smallexample -(load "ledger") + = food + (Budget:$account) 10 + ; Foo: Bar + + 2012-03-10 KFC + Expenses:Food $20.00 + Assets:Cash @end smallexample -To trigger ledger mode when you visit a journal file, the first line of -each of your journal files should be: +Becomes: + @smallexample -; -*-ledger-*- + 2012-03-10 KFC + Expenses:Food $20.00 + (Budget:Expenses:Food) $200.00 + ; Foo: Bar + Assets:Cash $-20.00 @end smallexample -To enter ledger-mode on a new file, type M-x ledger-mode. - -Once you have loaded a Journal file into Emacs, you have several -commands available to make entering, clearing and reconciling -transactions and producing reports: - -@cindex Emacs commands -@table @code -@item C-i or -auto complete entry -@item C-c C-a -add a new entry, based on previous entries -@item C-c C-e -toggle cleared status of an entire entry -@item C-c C-c -toggle cleared status of an individual posting -@item C-c C-y -set default year for entry mode -@item C-c C-m -set default month for entry mode -@item C-c C-r -reconcile uncleared entries related to an account -@item C-c C-d -delete the current entry -@item C-c C-s -sort all entries in the journal by date. Drop comments outside of entries -@item C-c C-o C-r -run a ledger report -@item C-C C-o C-g -go to the ledger report buffer -@item C-c C-o C-e -edit the defined ledger reports -@item C-c C-o C-s -save a report definition based on the current report -@item C-c C-o C-a -rerun a ledger report -@item C-c C-o C-k -kill the ledger report buffer -@end table -@menu -* Working with entries:: -* Reconciling accounts:: -* Generating Reports:: -@end menu +This is slightly different from the rules for regular transaction notes, in +that an automated transaction's note does not apply to every posting within +the automated transaction itself, but rather to every posting it matches. -@node Working with entries, Reconciling accounts, running ledger-mode, Using Emacs -@subsection Working with entries -@menu -* Manual Entry Support:: -* Automagically Adding new entries:: -* Clearing Transactions:: -@end menu +@node State flags, Effective Dates, Applying metadata to the generated posting, Automated transactions +@subsection State flags -@node Manual Entry Support, Automagically Adding new entries, Working with entries, Working with entries -@subsubsection Manual Entry Support +Although you cannot mark an automated transaction as a whole as cleared or +pending, you can mark its postings with a * or ! before the account name, and +that state flag gets carried to the generated posting. -@cindex completion -@cindex auto-completion -@cindex misspelled accounts treated as new +@node Effective Dates, Periodic Transactions, State flags, Automated transactions +@subsection Effective Dates +@cindex effective dates -In most financial programs, some sort of auto-completion is available to -save typing and improve accuracy. Ledger doesn't leave you hanging, -@code{ledger-mode} provides tab completion on all portions of an entry. -Type a portion of the payee and hit , and @code{ledger-mode} will -suggest a completion. When filling in the account type the first few -letters followed by a and the account will be filled in. For -example typing @samp{ExAuF} would yield -@samp{Expenses:Auto:Fuel} if you had previously used that account in -this journal. If there are more than one account with similar starting, -hitting multiple times will iterate through them. This is a good -habit to get in to prevent misspellings of accounts. Remember Ledger -does not validate the names of payees or account so a misspelled account -will be interpreted as a new account by ledger. +In the real world transactions do not take place instantaneously. +Purchases can take several days to post to a bank account. And you may +pay ahead for something for which you want to distribute costs. With +Ledger you can control every aspect of the timing of a transaction. +Say you're in business. If you bill a customer, you can enter +something like +@cindex effective date of invoice +@smallexample +2008/01/01=2008/01/14 Client invoice ; estimated date you'll be paid + Assets:Accounts Receivable $100.00 + Income: Client name +@end smallexample +@noindent Then, when you receive the payment, you change it to -@node Automagically Adding new entries, Clearing Transactions, Manual Entry Support, Working with entries -@subsubsection Automagically Adding new entries -@cindex new transactions in Emacs -@cindex Emacs, adding new transactions -@code{C-c C-a} will run the @code{ledger entry} command (@pxref{entry -and xact}) from within Emacs. When typed, the mini-buffer will appear -with the current year and month, waiting for you to enter the day and -the payee. Ledger will generate a new entry based on the most recent -entry for that payee, using the amount and accounts from that -transaction. If you have a new amount simply type the amount after the -payee. For example, if your journal contains an entry @smallexample -2011/11/25 Viva Italiano - Expenses:Food $12.45 - Expenses:Tips $2.55 - Liabilities:MasterCard $-15.00 -@end smallexample -@noindent and you type @samp{C-c C-a}, the mini-buffer will appear showing the -current year and month. If you complete the mini-buffer entry by typing +2008/01/01=2008/01/15 Client invoice ; actual date money received + Assets:Accounts Receivable $100.00 + Income: Client name +@end smallexample +@noindent and add something like + @smallexample -Entry: 2011/11/28 viva food 34 tip 7 +2008/01/15 Client payment + Assets:Checking $100.00 + Assets:Accounts Receivable @end smallexample -@noindent Emacs will add the following entry to your journal: +Now + @smallexample -2011/11/30 Viva Italiano - Expenses:Food $34.00 - Expenses:Tips $7.00 - Liabilities:MasterCard + ledger --subtotal --begin 2008/01/01 --end 2008/01/14 bal Income @end smallexample -@noindent Notice that the entry will appear at the correct place in the journal -ordered by date, not necessarily at the bottom of the file. -@node Clearing Transactions, , Automagically Adding new entries, Working with entries -@subsubsection Clearing Transactions and Postings -@cindex clearing transactions in Emacs -@cindex Emacs, clear transaction -@code{C-c C-e} will place an asterisk after the date in the current -transaction. The tells ledger the transaction has been cleared through -your bank (or whatever else you want the concept to mean) +@noindent gives you your accrued income in the first two weeks of the year, and @smallexample -2011/11/25 Viva Italiano - Expenses:Food $12.45 - Expenses:Tips $2.55 - Liabilities:MasterCard $-15.00 + ledger --effective --subtotal --begin 2008/01/01 --end 2008/01/14 bal Income @end smallexample -@noindent becomes +@noindent gives you your cash basis income in the same two weeks. + +Another use is distributing costs out in time. As an example, suppose +you just prepaid into a local vegetable co-op that sustains you through +the winter. It cost $225 to join the program, so you write a check. +You don't want your October grocery budget to be blown because you bought +food ahead, however. What you really want is for the money to be evenly +distributed over the next six months so that your monthly budgets +gradually take a hit for the vegetables you'll pick up from the co-op, +even though you've already paid for them. + @smallexample -2011/11/25 * Viva Italiano - Expenses:Food $12.45 - Expenses:Tips $2.55 - Liabilities:MasterCard $-15.00 +2008/10/16 * (2090) Bountiful Blessings Farm + Expenses:Food:Groceries $ 37.50 ; [=2008/10/01] + Expenses:Food:Groceries $ 37.50 ; [=2008/11/01] + Expenses:Food:Groceries $ 37.50 ; [=2008/12/01] + Expenses:Food:Groceries $ 37.50 ; [=2009/01/01] + Expenses:Food:Groceries $ 37.50 ; [=2009/02/01] + Expenses:Food:Groceries $ 37.50 ; [=2009/03/01] + Assets:Checking @end smallexample -If, for some reason you need to clear a specific posting in the -transaction you can type @samp{C-c C-c} and the posting at point will be -toggled. +This entry accomplishes this. Every month until you'll start with an +automatic $37.50 deficit like you should, while your checking account +really knows that it debited $225 this month. -@node Reconciling accounts, Generating Reports, Working with entries, Using Emacs -@subsection Reconciling accounts -In the reconcile buffer, use SPACE to toggle the cleared status of a -transaction, C-x C-s to save changes (to the ledger file as well). +@node Periodic Transactions, , Effective Dates, Automated transactions +@subsection Periodic Transactions -@node Generating Reports, , Reconciling accounts, Using Emacs -@subsection Generating Reports +A periodic transaction starts with a ~ followed by a period expression. +Periodic transactions are used for budgeting and forecasting only, they +have no effect without the @samp{--budget} option specified. + +See @ref{Budgeting and Forecasting} for examples and details. -The ledger reports command asks the user to select a report to run then -creates a report buffer containing the results of running the associated -command line. Its' behavior is modified by a prefix argument which, -when given, causes the generated command line that will be used to -create the report to be presented for editing before the report is -actually run. Arbitrary unnamed command lines can be run by specifying -an empty name for the report. The command line used can later be named -and saved for future use as a named report from the generated reports -buffer. -In a report buffer, the following keys are available: -@table @code -@item (space) -scroll up -@item e -edit the defined ledger reports -@item s -save a report definition based on the current report -@item q -quit the report (return to ledger buffer) -@item r -redo the report -@item k -kill the report buffer -@end table @@ -3675,14 +3670,14 @@ account on a particular payee, the following are equivalent: > ledger balance Auto:Fuel and Chevron > ledger balance --limit "(account=~/Fuel/) & (payee=~/Chev/)" @end smallexample -@noindent will show you the amount expended on gasoline at Chevron. The second -example is the first example of the very power expression language -available to shape reports. The first example may be easier to -remember, but learning to use the second will open up far -more possibilities. +@noindent will show you the amount expended on gasoline at Chevron. +The second example is the first example of the very power expression +language available to shape reports. The first example may be easier to +remember, but learning to use the second will open up far more +possibilities. -If you want to exclude specific accounts from the report, you can exclude multiple accounts with -parentheses: +If you want to exclude specific accounts from the report, you can +exclude multiple accounts with parentheses: @smallexample ledger -s bal Expenses and not \(Expenses:Drinks or Expenses:Candy or Expenses:Gifts\) @end smallexample @@ -3846,7 +3841,7 @@ ledger bal Allocation --current --format "\ %16(market(display_total))\n%/" @end smallexample -Which yields: +@noindent Which yields: @smallexample Allocation 100.00% $100000.00 @@ -4142,14 +4137,12 @@ You can combine multiple source code blocks before executing ledger and do all kinds of other wonderful things with Babel (and org). -@subsubsection Using Ledger for Accounting in Org-mode with Babel +@subsection Org-mode with Babel Using Babel, it is possible to record financial transactions conveniently in an org file and subsequently generate the financial reports required. -@unnumberedsubsubsec Getting Started - With a recent version of org (7.01+), Ledger support is provided. To use it, enable Ledger support. Check the Babel documentation on Worg for instructions on how to achieve this but I currently do this directly as @@ -4182,7 +4175,7 @@ least) in which these can be included: The first two are described in more detail in this short tutorial. -@unnumberedsubsubsec Embedded Ledger example with single source block +@subsubheading Embedded Ledger example with single source block The easiest, albeit possibly less useful, way in which to use Ledger within an org file is to use a single source block to record all Ledger @@ -4242,7 +4235,7 @@ financial state. Eventually, babel will support passing arguments to currently. Instead, we can use the concepts of literary programming, as implemented by the noweb features of babel, to help us. -@unnumberedsubsubsec Multiple Ledger source blocks with noweb +@subsubheading Multiple Ledger source blocks with noweb The noweb feature of babel allows us to expand references to other code blocks within a code block. For Ledger, this can be used to group @@ -4251,7 +4244,7 @@ transactions together to generate reports. Using the same transactions used above, we could consider splitting these into expenses and income, as follows: -@unnumberedsubsubsec Income Entries +@subsubheading Income Entries The first set of entries relates to income, either monthly pay or interest, all typically going into one of my bank accounts. Here, I have @@ -4278,7 +4271,7 @@ have the :noweb yes babel header argument specified. income:salary #+end_src @end smallexample -@unnumberedsubsubsec Expenses +@subsubheading Expenses The following entries relate to personal expenses, such as rent and food. Again, these have all been placed in a single src block but could @@ -4295,7 +4288,7 @@ have been done individually. #+end_src @end smallexample -@unnumberedsubsubsec Financial Summaries +@subsubheading Financial Summaries Given the ledger entries defined above in the income and expenses code blocks, we can now refer to these using the noweb expansion directives, @@ -4303,7 +4296,7 @@ blocks, we can now refer to these using the noweb expansion directives, reports for those transactions. Below are two examples, one to generate a balance report and one to generate a register report of all transactions. -@unnumberedsubsubsec An overall balance summary +@subsubheading An overall balance summary The overall balance of your account and expenditure with a breakdown according to category is specified by passing the :cmdline bal argument @@ -4345,7 +4338,7 @@ tell Ledger to include sub-accounts in the report. : £-2000.00 salary : £-1300.00 starting balances @end smallexample -@unnumberedsubsubsec Generating a monthly register +@subsubheading Generating a monthly register You can also generate a monthly register (the reg command) by executing the following src block. This presents a summary of transactions for @@ -4390,7 +4383,7 @@ the running total of the assets in our ledger. : 2010/08/01 - 2010/08/01 assets:bank:chequing £1000.00 £2653.53 @end smallexample -@unnumberedsubsubsec Summary +@subsubheading Summary This short tutorial shows how Ledger entries can be embedded in a org file and manipulated using Babel. However, only simple Ledger features @@ -4420,8 +4413,8 @@ The general format used for Ledger data is: @end smallexample The data stream is enclosed in a @samp{ledger} tag, which contains a -series of one or more transactions. Each @samp{xact} describes the transaction -and contains a series of one or more postings: +series of one or more transactions. Each @samp{xact} describes the +transaction and contains a series of one or more postings: @smallexample @@ -4438,16 +4431,15 @@ and contains a series of one or more postings: @end smallexample The date format for @samp{en:date} is always @samp{YYYY/MM/DD}. The -@samp{en:cleared} tag is optional, and indicates whether the -posting has been cleared or not. There is also an -@samp{en:pending} tag, for marking pending postings. The -@samp{en:code} and @samp{en:payee} tags both contain whatever text the -user wishes. +@samp{en:cleared} tag is optional, and indicates whether the posting has +been cleared or not. There is also an @samp{en:pending} tag, for +marking pending postings. The @samp{en:code} and @samp{en:payee} tags +both contain whatever text the user wishes. After the initial transaction data, there must follow a set of postings -marked with @samp{en:postings}. Typically these postings will -all balance each other, but if not they will be automatically balanced -into an account named @samp{}. +marked with @samp{en:postings}. Typically these postings will all +balance each other, but if not they will be automatically balanced into +an account named @samp{}. Within the @samp{en:postings} tag is a series of one or more @samp{posting}'s, which have the following form: @@ -4755,7 +4747,8 @@ Print version information and exit. @node Pre-commands, , Debug Options, Developer Commands @subsection Pre-Commands -Pre-commands are useful when you aren't sure how a command or option will work. +Pre-commands are useful when you aren't sure how a command or option +will work. @table @code @item args evaluate the given arguments against the following model transaction: @@ -4772,12 +4765,15 @@ evaluate the given arguments against the following model transaction: @item eval evaluate the given value expression against the model transaction @item expr "LIMIT EXPRESSION" -Print details of how ledger parses the given limit expression and apply it against a model transaction. +Print details of how ledger parses the given limit expression and apply +it against a model transaction. @item format "FORMATTING" -Print details of how ledger uses the given formatting description and apply it against a model transaction. +Print details of how ledger uses the given formatting description and +apply it against a model transaction. @item generate @item parse -Print details of how ledger uses the given value expression description and apply it against a model transaction. +Print details of how ledger uses the given value expression description +and apply it against a model transaction. @item period evaluate the given period and report how Ledger interprets it: @smallexample @@ -4799,7 +4795,8 @@ END_REACHED: 1: 11-Jan-01 @end smallexample @item query -evaluate the given query and report how Ledger interprets it against the model transaction: +evaluate the given query and report how Ledger interprets it against the +model transaction: @smallexample 20:25:42 ~/ledger (next)> ledger query "/Book/" @@ -4891,13 +4888,6 @@ However, none of them are required to use the basic reporting commands. - - - - - - - @node Detailed Options Description, Period Expressions, Basic Usage, Command-line Syntax @section Detailed Option Description @@ -4932,23 +4922,12 @@ database. @option{--help} Displays the info page for ledger. -@option{--help-calc} -Displays the Value Expression chapter in the info ledger. - -@option{--help-comm } -Search the info index for @code{}. - -@option{--help-disp} -Displays the Format String chapter in the info ledger. - -@option{--help-info} -Displays the info page for the info reader. - @option{--init-file } Specifies the location of the init file @file{.ledgerrc} -@option{--options} -Display the options in effect for this Ledger invocation, along with their values and the source of those values, for example: +@option{--options} Display the options in effect for this Ledger +invocation, along with their values and the source of those values, for +example: @smallexample 14:15:02 > ledger --options bal --cleared -f ~/ledger/test/input/drewr3.dat =============================================================================== @@ -4995,20 +4974,22 @@ GUIs, which would make use of the different scopes by keeping an instance of Ledger running in the background and running multiple sessions with multiple reports per session. -@option{--decimal-comma} -Direct Ledger to parse journals using the European standard comma as decimal separator, vice a period. +@option{--decimal-comma} Direct Ledger to parse journals using the +European standard comma as decimal separator, vice a period. -@option{--download} -Direct Ledger to download prices using the script defined in @code{--getquote}. +@option{--download} Direct Ledger to download prices using the script +defined in @code{--getquote}. @option{--file } Specify the input file path for this invocation. @cindex getquote @cindex download prices -@option{--getquote } Tells ledger where to find the user defined script to download prices information. -@option{--input-date-format } -Specify the input date format for journal entries. For example, +@option{--getquote } Tells ledger where to find the user defined +script to download prices information. + +@option{--input-date-format } Specify the input date format +for journal entries. For example, @smallexample ledger convert Export.csv --input-date-format "%m/%d/%Y" @end smallexample @@ -5017,8 +4998,8 @@ Would convert the @file{Export.csv} file to ledger format, assuming the the dates in the CSV file are like 12/23/2009 (@pxref{Date and Time Format Codes}). -@option{--master-account } -Prepends all account names with the argument. +@option{--master-account } Prepends all account names with the +argument. @smallexample 21:51:39 ~/ledger (next)> ledger -f test/input/drewr3.dat bal --master-account HUMBUG 0 HUMBUG @@ -5043,8 +5024,8 @@ Prepends all account names with the argument. $ 200.00 Mortgage:Principal @end smallexample -@option{--price-db } -Specify the location of the price entry data file. +@option{--price-db } Specify the location of the price entry data +file. @option{--price-exp INTEGER_MINUTES} Set the expected freshness of price quotes, in minutes. That is, if the last known quote for any commodity @@ -5081,17 +5062,16 @@ reported. That is, the option @code{--account Personal} would tack @code{Personal:} to the beginning of every account reported in a balance report or register report. -@option{--account-width } -Set the width of the account column in the @code{register} report to @code{N} characters. +@option{--account-width } Set the width of the account column in +the @code{register} report to @code{N} characters. -@option{--actual-dates} -Show actual dates of transactions (@pxref{Effective Dates}). Also @code{-L}. +@option{--actual-dates} Show actual dates of transactions +(@pxref{Effective Dates}). Also @code{-L}. -@option{--actual} -Report only real transactions, with no automated or virtual transactions used. +@option{--actual} Report only real transactions, with no automated or +virtual transactions used. -@option{--add-budget} -Show only unbudgeted postings. +@option{--add-budget} Show only unbudgeted postings. @option{--amount-data} On a register report print only the dates and amount of postings. Useful for graphing and spreadsheet applications. @@ -5101,37 +5081,35 @@ amount of postings. Useful for graphing and spreadsheet applications. amount (@pxref{Value Expressions}). Using @code{--amount} you can apply an arbitrary transformation to the postings. -@option{--amount-width } -Set the width in characters of the amount column in the register report. +@option{--amount-width } Set the width in characters of the amount +column in the register report. -@option{--anon} -anonymizes registry output, mostly for sending in bug reports. +@option{--anon} anonymizes registry output, mostly for sending in bug +reports. -@option{--average} -Print average values over the number of transactions instead of running totals. +@option{--average} Print average values over the number of transactions +instead of running totals. -@option{--balance-format } -specifies the format to use for the @code{balance} report (@pxref{Format Strings}). The default is: +@option{--balance-format } specifies the format to use for the +@code{balance} report (@pxref{Format Strings}). The default is: @smallexample "%(justify(scrub(display_total), 20, -1, true, color))" " %(!options.flat ? depth_spacer : \"\")" "%-(ansify_if(partial_account(options.flat), blue if color))\n%/" "%$1\n%/" "--------------------\n" - @end smallexample -@option{--base} -ASK JOHN +@option{--base} ASK JOHN -@option{--basis} -Report the cost basis on all posting +@option{--basis} Report the cost basis on all posting -@option{--begin } -Specify the start date of all calculations. Transactions before that date will be ignored. +@option{--begin } Specify the start date of all calculations. +Transactions before that date will be ignored. + +@option{--bold-if } print the entire line in bold if the given +value expression is true (@pxref{Value Expressions}). -@option{--bold-if } -print the entire line in bold if the given value expression is true (@pxref{Value Expressions}). @smallexample ledger reg Expenses --begin Dec --bold-if "amount > 100" @end smallexample @@ -5154,8 +5132,9 @@ accounts in the budget (@pxref{Budgeting and Forecasting}). @option{--by-payee } group the register report by payee. -@option{--cleared-format } -specifies the format to use for the @code{cleared} report (@pxref{Format Strings}). The default is: +@option{--cleared-format } specifies the format to use +for the @code{cleared} report (@pxref{Format Strings}). The default is: + @smallexample "%(justify(scrub(get_at(total_expr, 0)), 16, 16 + prepend_width, " " true, color)) %(justify(scrub(get_at(total_expr, 1)), 18, " @@ -5168,26 +5147,26 @@ specifies the format to use for the @code{cleared} report (@pxref{Format Strings "---------------- ---------------- ---------\n" @end smallexample -@option{--cleared} -consider only transaction that have been cleared for display and calculation. +@option{--cleared} consider only transaction that have been cleared for +display and calculation. +@option{--collapse} By default ledger prints all account in an account +tree. With @code{--collapse} it print only the top level account +specified. +@option{--collapse-if-zero} Collapses the account display only if it has +a zero balance. -@option{--collapse} -By default ledger prints all account in an account tree. With @code{--collapse} it print only the top level account specified. -@option{--collapse-if-zero} -Collapses the account display only if it has a zero balance. -@option{--color} -use color is the tty supports it. +@option{--color} use color is the tty supports it. -@option{--columns } -specify the width of the register report in characters. +@option{--columns } specify the width of the register report in +characters. -@option{--count} -Direct ledger to report the number of items when appended to the commodities, accounts or payees command. +@option{--count} Direct ledger to report the number of items when +appended to the commodities, accounts or payees command. -@option{--csv-format} -specifies the format to use for the @code{csv} report (@pxref{Format Strings}). The default is: +@option{--csv-format} specifies the format to use for the @code{csv} +report (@pxref{Format Strings}). The default is: @smallexample "%(quoted(date))," "%(quoted(code))," @@ -5204,14 +5183,14 @@ Shorthand for @code{--limit "date <= today"} @option{--daily} Shorthand for @code{--period "daily"} -@option{--date-format } -specifies format ledger should use to print dates (@pxref{Date and Time Format Codes}). +@option{--date-format } specifies format ledger should use +to print dates (@pxref{Date and Time Format Codes}). -@option{--date } -transforms the date of the transaction using @code{EXPR} +@option{--date } transforms the date of the transaction using +@code{EXPR} -@option{--date-width } -specifies the width, in characters, of the date column in the register report. +@option{--date-width } specifies the width, in characters, of the +date column in the register report. @option{--datetime-format} ASK JOHN @@ -5273,18 +5252,17 @@ only for account with two levels, i.e. @code{Expenses:Entertainment} but not @code{Expenses:entertainemnt:Dining}. This is a display predicate, which means it only affects display, not the total calculations. -@option{--deviation} - reports each posting’s deviation from the average. It is only mean- -ingful in the register and prices reports. +@option{--deviation} reports each posting’s deviation from the + average. It is only mean- ingful in the register and prices reports. -@option{--display-amount } -apply a transform to the @strong{displayed} amount. This occurs after calculations occur. +@option{--display-amount } apply a transform to the +@strong{displayed} amount. This occurs after calculations occur. @option{--display } display lines that satisfy the expression given. -@option{--display-total } -apply a transform to the @strong{displayed} total. This occurs after calculations occur. +@option{--display-total } apply a transform to the +@strong{displayed} total. This occurs after calculations occur. @option{--dow} group transactions by the day of the week. @@ -5309,11 +5287,11 @@ register report. @option{--exact} ASK JOHN -@option{--exchange } -display values in terms of the given commodity. The latest available price is used. +@option{--exchange } display values in terms of the given +commodity. The latest available price is used. -@option{--flat} -force the full names of accounts to be used inthe balance report. The balance report will not use an indented tree. +@option{--flat} force the full names of accounts to be used inthe +balance report. The balance report will not use an indented tree. @option{--force-color} output tty color codes even if the tty doesn't support them. Ueful for TTY that don't advertise their capabilities @@ -5342,8 +5320,9 @@ report. EXPR can be anything, although most common would be @code{"payee"} or @code{"commodity"}. The @code{tags()} function is also useful here. -@option{--group-title-format} -sets the format for the headers that separate reports section of a grouped report. Only has effect with a @code{--group-by} register report. +@option{--group-title-format} sets the format for the headers that +separate reports section of a grouped report. Only has effect with a +@code{--group-by} register report. @smallexample ledger reg Expenses --group-by "payee" --group-title-format "------------------------ %-20(value) ---------------------\n" ------------------------ 7-Eleven --------------------- @@ -5367,22 +5346,22 @@ See email from John W. @option{--invert} Change the sign of all reported values. -@option{--limit } -Only transactions that satisfy the expression will be considered in the calculation. +@option{--limit } Only transactions that satisfy the expression +will be considered in the calculation. @option{--lot-dates} FIX THIS ENTRY -@option{lot-prices} +@option{--lot-prices} FIX THIS ENTRY -@option{lot-tags} +@option{--lot-tags} FIX THIS ENTRY -@option{lots-actual} +@option{--lots-actual} FIX THIS ENTRY -@option{lots} +@option{--lots} FIX THIS ENTRY @option{market} @@ -5394,31 +5373,31 @@ FIX THIS ENTRY @option{meta-width} FIX THIS ENTRY -@option{monthly} +@option{--monthly} FIX THIS ENTRY -@option{no-color} -FIX THIS ENTRY +@option{--no-color} +suppress any color TTY output. -@option{no-rounding} +@option{--no-rounding} FIX THIS ENTRY -@option{no-titles} +@option{--no-titles} FIX THIS ENTRY -@option{no-total} +@option{--no-total} FIX THIS ENTRY -@option{now} +@option{--now} FIX THIS ENTRY @option{only} FIX THIS ENTRY -@option{output} +@option{--output} FIX THIS ENTRY -@option{pager} +@option{--pager} FIX THIS ENTRY @option{payee} @@ -5427,8 +5406,8 @@ FIX THIS ENTRY @option{payee-width} FIX THIS ENTRY -@option{pending} -FIX THIS ENTRY +@option{--pending} +Use only postings tht are marked pending @option{percent} FIX THIS ENTRY @@ -5436,7 +5415,7 @@ FIX THIS ENTRY @option{period} FIX THIS ENTRY -@option{pivot} +@option{--pivot} FIX THIS ENTRY @option{plot-amount-format} @@ -5463,14 +5442,14 @@ FIX THIS ENTRY @option{quantity} FIX THIS ENTRY -@option{quarterly} +@option{--quarterly} FIX THIS ENTRY @option{raw} FIX THIS ENTRY -@option{real} -FIX THIS ENTRY +@option{--real} Account using only real transactions ignoring virtual +and automatic transactions. @option{register-format} FIX THIS ENTRY @@ -5478,16 +5457,16 @@ FIX THIS ENTRY @option{related-all} FIX THIS ENTRY -@option{related} -FIX THIS ENTRY +@option{--related} +In a register report show the related account. -@option{revalued-only} +@option{--revalued-only} FIX THIS ENTRY -@option{revalued-total} +@option{--revalued-total} FIX THIS ENTRY -@option{revalued} +@option{--revalued} FIX THIS ENTRY @option{seed} @@ -5496,16 +5475,17 @@ FIX THIS ENTRY @option{sort-all} FIX THIS ENTRY -@option{sort} -FIX THIS ENTRY +@option{--sort } +Sort the register report based on the value expression given to sort -@option{sort-xacts} +@option{--sort-xacts} FIX THIS ENTRY -@option{--start-of-week } -Tell ledger to use a particular day of the week to start its ``weekly'' summary. @code{--start-of-week=1} specifies Monday as the start of the week. +@option{--start-of-week } Tell ledger to use a particular day of +the week to start its ``weekly'' summary. @code{--start-of-week=1} +specifies Monday as the start of the week. -@option{subtotal} +@option{--subtotal} FIX THIS ENTRY @option{--tail } @@ -5544,8 +5524,8 @@ FIX THIS ENTRY @option{--weekly} synonymn for @code{--period "weekly"} -@option{--wide} -lets the register report use 132 columns. Identical to @code{--columns "132"} +@option{--wide} lets the register report use 132 columns. Identical to +@code{--columns "132"} @option{yearly} synonymn for @code{--period "yearly"} -- cgit v1.2.3