diff options
Diffstat (limited to 'doc/ledger3.texi')
| -rw-r--r-- | doc/ledger3.texi | 278 |
1 files changed, 189 insertions, 89 deletions
diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 5e266253..45afe1ae 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -111,7 +111,7 @@ @copying -Copyright @copyright{} 2003–2015, John Wiegley. All rights reserved. +Copyright @copyright{} 2003--2018, John Wiegley. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are @@ -179,7 +179,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Ledger is a command-line accounting tool that provides double-entry accounting based on a text journal. It provides no bells or whistles, and returns the user to the days before user interfaces were even a -twinkling in their father's CRT. +twinkling in their fathers' CRTs. @end ifnottex @@ -212,6 +212,7 @@ twinkling in their father's CRT. * Fat-free Accounting:: * Building the program:: * Getting help:: +* Third-Party Ledger Tutorials:: @end menu @node Fat-free Accounting, Building the program, Introduction to Ledger, Introduction to Ledger @@ -400,7 +401,7 @@ options. You can run `make check` to confirm the result, and `make install` to install. If these intructions do not work for you can check the `INSTALL.md` in the source directory for more up do date build instructions. -@node Getting help, , Building the program, Introduction to Ledger +@node Getting help, , Building the program, Introduction to Ledger @section Getting help @findex help @@ -417,6 +418,23 @@ join the Ledger mailing list at You can also find help in the @code{#ledger} channel on the IRC server @code{irc.freenode.net}. +@node Third-Party Ledger Tutorials, , Getting help, Introduction to Ledger +@section Third-Party Ledger Tutorials + +There are plenty of people using Ledger for accounting applications. +Some have documented how they use Ledger's features to solve their +accounting problems. + +Once such tutorial, specifically designed for non-profit charities that seek +to use Ledger, can be found at +@url{https://k.sfconservancy.org/npo-ledger-cli} (with a copy on GitHub also +available at @url{https://github.com/conservancy/npo-ledger-cli/}). If +you're looking for information about how to use Ledger's tagging system to +handle invoicing, track expenses by program targets, and other such concepts, +you might find the tutorial useful. (Some of the auditor reporting scripts +that relate to the aformentioned Ledger setup can be found +@var{contrib/non-profit-audit-reports/} in Ledger's own source repository.) + @node Ledger Tutorial, Principles of Accounting with Ledger, Introduction to Ledger, Top @chapter Ledger Tutorial @cindex tutorial @@ -1078,7 +1096,7 @@ $40880.00 Assets:Brokerage You can convert from any commodity to any other commodity. Let's say you had $5000 in your checking account, and for whatever reason you -wanted to know many ounces of gold that would buy, in terms of the +wanted to know how many ounces of gold that would buy, in terms of the current price of gold: @smallexample @@ -1255,7 +1273,7 @@ worth $5000, then you have $5000 in equity in that car. In order to turn that car (a commodity) into a cash flow, or a credit to your bank account, you will have to debit the equity by selling it. -When you start a ledger, you are probably already worth something. +When you start a ledger, you probably already have a net worth. Your net worth is your current equity. By transferring the money in the ledger from your equity to your bank accounts, you are crediting the ledger account based on your prior equity. That is why, when you @@ -1339,7 +1357,7 @@ account point of view and from the fund point of view---yet both sets should reflect the same overall expenses and cash flow. It's simply where the money resides that differs. -This situation can be handled one of two ways. The first is using +This situation can be handled in one of two ways. The first is using virtual postings to represent the fact that money is moving to and from two kind of accounts at the same time: @@ -1490,13 +1508,14 @@ nature of your transactions. For example, you do not need to tell Ledger about the accounts you use. Any time Ledger sees a posting involving an account it knows nothing about, it will create it@footnote{This also means if you -misspell an account it will end up getting counted separately from what -you intended. The provided Emacs major mode provides for automatically -filling in account names.}. If you use a commodity that is new to -Ledger, it will create that commodity, and determine its display -characteristics (placement of the symbol before or after the amount, -display precision, etc.) based on how you used the commodity in the -posting. +misspell an account it will end up getting counted separately from +what you intended. An Emacs major mode +@uref{https://github.com/ledger/ledger-mode/, ledger-mode} provides +tab completion for automatically filling in account names.}. If you +use a commodity that is new to Ledger, it will create that commodity, +and determine its display characteristics (placement of the symbol +before or after the amount, display precision, etc.) based on how you +used the commodity in the posting. @menu * The Most Basic Entry:: @@ -1976,7 +1995,7 @@ amount using the @samp{(( ))} commodity annotation. 2012-03-07 KFC Expenses:Food7 1 CAD - Assets:Cas7 + Assets:Cash7 2012-03-08 XACT Expenses:Food8 $1 @@ -2236,6 +2255,41 @@ Would result in all postings going into @samp{Personal:Expenses:Groceries} and @samp{Personal:Assets:Checking} until an @samp{end apply account} directive was found. +@item apply fixed +@findex fixed +@cindex fixated prices +@c instance_t::fixed_directive in textual.cc + +A fixed block is used to set fixated prices (@pxref{Fixated prices and +costs}) for a series of transactions. It's purely a typing saver, for +use when entering many transactions with fixated prices. + +Thus, the following: + +@smallexample @c input:validate +apply fixed CAD $0.90 +2012-04-10 Lunch in Canada + Assets:Wallet -15.50 CAD + Expenses:Food 15.50 CAD + +2012-04-11 Second day Dinner in Canada + Assets:Wallet -25.75 CAD + Expenses:Food 25.75 CAD +end apply fixed +@end smallexample + +is equivalent to this: + +@smallexample @c input:validate +2012-04-10 Lunch in Canada + Assets:Wallet -15.50 CAD @{=$0.90@} + Expenses:Food 15.50 CAD @{=$0.90@} + +2012-04-11 Second day Dinner in Canada + Assets:Wallet -25.75 CAD @{=$0.90@} + Expenses:Food 25.75 CAD @{=$0.90@} +@end smallexample + @item alias @findex alias @cindex account, alias @@ -2383,6 +2437,7 @@ commodity $ note American Dollars format $1,000.00 nomarket + alias USD default @end smallexample @@ -2397,6 +2452,9 @@ provide the ``canonical'' representation. The @code{nomarket} sub-directive states that the commodity's price should never be auto-downloaded. +The @code{alias} sub-directive states that any commodity matching this +symbol is to use the commodity declared in this block. + The @code{default} sub-directive marks this as the ``default'' commodity. @item define @@ -2417,59 +2475,18 @@ The posting will have a cost of $400. @item end @findex end @c instance_t::end_directive in textual.cc -Closes block commands like @code{tag} or @code{comment}. +Closes block commands like @code{apply} or @code{comment}. @item expr @findex expr @c instance_t::expr_directive in textual.cc -@item fixed -@findex fixed -@cindex fixated prices -@c instance_t::fixed_directive in textual.cc - -A fixed block is used to set fixated prices (@pxref{Fixated prices and -costs}) for a series of transactions. It's purely a typing saver, for -use when entering many transactions with fixated prices. - -Thus, the following: - -@smallexample @c input:validate -fixed CAD $0.90 -2012-04-10 Lunch in Canada - Assets:Wallet -15.50 CAD - Expenses:Food 15.50 CAD - -2012-04-11 Second day Dinner in Canada - Assets:Wallet -25.75 CAD - Expenses:Food 25.75 CAD -endfixed CAD -@end smallexample - -is equivalent to this: - -@smallexample @c input:validate -2012-04-10 Lunch in Canada - Assets:Wallet -15.50 CAD @{=$0.90@} - Expenses:Food 15.50 CAD @{=$0.90@} - -2012-04-11 Second day Dinner in Canada - Assets:Wallet -25.75 CAD @{=$0.90@} - Expenses:Food 25.75 CAD @{=$0.90@} -@end smallexample - -Note that ending a @code{fixed} is done differently than other -directives, as @code{fixed} is closed with an @code{endfixed} (i.e., -there is @emph{no space} between @code{end} and @code{fixed}). - -For the moment, users may wish to study -@uref{http://bugs.ledger-cli.org/show_bug.cgi?id=789, Bug Report 789} -before using the @code{fixed} directive in production. - @item include @findex include @c instance_t::include_directive in textual.cc -Include the stated file as if it were part of the current file. +Include the stated file as if it were part of the current file. The file +name can contain a wildcard (@samp{*}) to refer to multiple files (e.g. +@samp{bank/*.ledger}). @item payee @findex payee @@ -2714,14 +2731,17 @@ 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}: +leaving 2002--2004 in the current file. So, use @command{print} to +output all the earlier transactions to a file called +@file{ledger-old.dat}: @smallexample -$ ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat +$ ledger -f ledger.dat -b 2000 -e 2002 print > ledger-old.dat @end smallexample +Note that @option{-e} limits output to transactions @emph{before} the +date specified. + To delete older data from the current ledger file, use @command{print} again, this time specifying year 2002 as the starting date: @@ -2892,7 +2912,7 @@ you a place to put those codes: A transaction can have a ``state'': cleared, pending, or uncleared. The default is uncleared. To mark a transaction cleared, put an asterisk -@samp{*} before the payee, after the date or code: +@samp{*} after the date, before the code or payee: @smallexample @c input:validate 2012-03-10 * KFC @@ -2950,7 +2970,7 @@ You can mark individual postings as cleared or pending, in case one @section Transaction notes After the payee, and after at least one tab or two spaces (or a space -and a tab, which Ledger calls a ``hard separator''), you may +and a tab), which Ledger calls a ``hard separator'', you may introduce a note about the transaction using the @samp{;} character: @smallexample @c input:validate @@ -3052,7 +3072,7 @@ used as the payee name for that posting. This affects the This is useful when for example you deposit 4 checks at a time to the bank. On the bank statement, there is just one amount @samp{$400}, but -you can specify from whom each check came from, as shown by example +you can specify from whom each check came, as shown by example below: @smallexample @c input:9B43E57 @@ -3210,6 +3230,45 @@ A balance assertion has this general form: This simply asserts that after subtracting $20.00 from Assets:Cash, that the resulting total matches $500.00. If not, it is an error. +The assertion has an effect only on the specified commodity. If an account has +multiple commodities, then only the one asserted is verified: + +@smallexample +2012-03-10 KFC New York + Expenses:Food $20.00 + Assets:Cash $-20.00 = $500.00 + +2012-03-11 KFC Montreal + Expenses:Food 15.00 CAD + Assets:Cash -15.00 CAD = $500.00 +@end smallexample + +In this case, the amount in USD of cash (which has not changed) is validated. +Nothing is asserted about the current amount of Canadian dollars in @samp{Asset:Cash}. + +@subsubsection Special assertion value 0 + +The only value that can be asserted without a commodity is @samp{0}. +This results in a cross-commodities assertion, which makes it possible to +assert that an account is totally empty. + +@smallexample +2012-03-09 Fill Wallet + Revenue $20.00 + Revenue 15.00 CAD + Assets:Cash + +2012-03-10 KFC New York + Expenses:Food $20.00 + Assets:Cash $-20.00 + +2012-03-11 KFC Montreal + Expenses:Food 15.00 CAD + Assets:Cash -15.00 CAD = 0 +@end smallexample + +The last transaction will assert that we are out of cash of any sort. + @node Balance assignments, Resetting a balance, Balance assertions, Balance verification @subsection Balance assignments @@ -3238,7 +3297,7 @@ adjustment transaction using balance assignments: Equity:Adjustments @end smallexample -Since the second posting is also null, it's value will become the +Since the second posting is also null, its 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 @@ -3501,7 +3560,7 @@ But this does not do what you might expect: @smallexample 2012-04-10 My Broker Assets:Brokerage 10 AAPL @@ $50.00 - Assets:Brokerage:Cash $750.00 + Assets:Brokerage:Cash $-500.00 2012-04-10 My Broker Assets:Brokerage:Cash $375.00 @@ -3527,11 +3586,11 @@ following two transactions are equivalent: @smallexample 2012-04-10 My Broker Assets:Brokerage 10 AAPL @@ $50.00 - Assets:Brokerage:Cash $750.00 + Assets:Brokerage:Cash $-500.00 2012-04-10 My Broker Assets:Brokerage 10 AAPL @{$50.00@} - Assets:Brokerage:Cash $750.00 + Assets:Brokerage:Cash $-500.00 @end smallexample However, note that what you see in some reports may differ, for @@ -3542,15 +3601,16 @@ sensitive to this difference. @node Fixated prices and costs, Lot dates, Prices versus costs, Transactions @section Fixated prices and costs -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 @samp{@{=AMOUNT@}}: +If you bought 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 +@samp{@{=AMOUNT@}}: @smallexample 2012-04-10 My Broker Assets:Brokerage 10 AAPL @{=$50.00@} - Assets:Brokerage:Cash $750.00 + Assets:Brokerage:Cash $-500.00 @end smallexample These 10 AAPL will now always be reported as being worth $50, no @@ -3566,7 +3626,7 @@ fixated prices by way of the cost: @smallexample 2012-04-10 My Broker Assets:Brokerage 10 AAPL @@ =$50.00 - Assets:Brokerage:Cash $750.00 + Assets:Brokerage:Cash $-500.00 @end smallexample This is the same as the previous transaction, with the same caveats @@ -6234,11 +6294,25 @@ Specify the format to use for the @command{budget} report (@pxref{Format Strings}). The default is: @smallexample -"%(justify(scrub(display_total), 20, -1, true, color))" +"%(justify(scrub(get_at(display_total, 0)), 12, -1, true, color))" +" %(justify(-scrub(get_at(display_total, 1)), 12, " +" 12 + 1 + 12, true, color))" +" %(justify(scrub(get_at(display_total, 1) + " +" get_at(display_total, 0)), 12, " +" 12 + 1 + 12 + 1 + 12, true, color))" +" %(ansify_if(" +" justify((get_at(display_total, 1) ? " +" (100% * quantity(scrub(get_at(display_total, 0)))) / " +" -quantity(scrub(get_at(display_total, 1))) : 0), " +" 5, -1, true, false)," +" magenta if (color and get_at(display_total, 1) and " +" (abs(quantity(scrub(get_at(display_total, 0))) / " +" quantity(scrub(get_at(display_total, 1)))) >= 1))))" " %(!options.flat ? depth_spacer : \"\")" -"%-(ansify_if(partial_account(options.flat), blue if color))\n%/" -"%$1\n%/" -"--------------------\n" +"%-(ansify_if(partial_account(options.flat), blue if color))\n" +"%/%$1 %$2 %$3 %$4\n%/" +"%(prepend_width ? \" \" * int(prepend_width) : \"\")" +"------------ ------------ ------------ -----\n" @end smallexample @item --by-payee @@ -7581,7 +7655,9 @@ option settings in the file @file{~/.ledgerrc} one option per line, for example: @c TODO use @var below A period expression indicates a span of time, or a reporting interval, -or both. The full syntax is: +or both. Ledger's end dates are always exclusive, imagine the date is +followed by 00:00:00 time. They are instants in time not entire days. +The full syntax is: @smallexample [INTERVAL] [BEGIN] [END] @@ -8122,6 +8198,19 @@ posting. A regular expression that matches against the transaction code (the text that occurs between parentheses before the payee). +@item expr any(KEYWORD =~ /REGEX/) +The @command{any} keyword is used to specify that at least one posting of +the transaction must match the expression in brackets. For example, +@samp{ledger -f d reg expr "any(account =~ /Assets:/)"} can be used to +display all transactions which involve at least one @samp{Assets:} +account. + +@item expr all(KEYWORD =~ /REGEX/) +The @command{all} keyword is used to specify that all postings of a +transactions must match the expression in brackets. For example, +@samp{ledger -f d reg expr "all(account =~ /Assets:/)"} can be used to +display all transactions where all accounts are @samp{Assets:}. + @end table The @command{query} command can be used to see how Ledger interprets @@ -8340,7 +8429,7 @@ Return the quantity of @var{value} for values that have a per-unit cost. @end defun @defun quoted expression -Surround @var{expression} with double-quotes. +Surround @var{expression} with double-quotes. If expression contains a double-quote, it will be escaped with a backslash. @smallexample @c command:EAD8AA7,with_input:3406FC1 $ ledger -f expr.dat --format "%(quoted(account)) %(quoted(amount))\n" reg @end smallexample @@ -8350,6 +8439,17 @@ $ ledger -f expr.dat --format "%(quoted(account)) %(quoted(amount))\n" reg @end smallexample @end defun +@c @defun quoted_rfc4180 expression +@c Surround @var{expression} with double-quotes, compliant with RFC 4180. If expression contains a double-quote, it will be represented with two double-quotes. +@c @smallexample @c command:EAD8AA7,with_input:3406FC1 +@c $ ledger -f expr.dat --format "%(quoted_rfc4180(account)) %(quoted_rfc4180(amount))\n" reg +@c @end smallexample +@c @smallexample @c output:EAD8AA7 +@c "Assets:Cash" "¤ -123,45" +@c "Expenses:Office Supplies" "¤ 123,45" +@c @end smallexample +@c @end defun + @defun round @value{FIXME:UNDOCUMENTED} @end defun @@ -8935,7 +9035,7 @@ day of the month (dd), zero padded up to 10. day of the month (dd), no leading zero up to 10. @item %j -day of year, zero padded 000–366. +day of year, zero padded 000--366. @item %u day of week starting with Monday (1), i.e. @code{mtwtfss} 3. @@ -8986,16 +9086,16 @@ Additional date format parameters which can be used: @table @code @item %U -week number Sunday as first day of week, ranging 01–53. +week number Sunday as first day of week, ranging 01--53. @item %W -week number Monday as first day of week, ranging 01–53. +week number Monday as first day of week, ranging 01--53. @item %V -week of the year, ranging 01–53. +week of the year, ranging 01--53. @item %C -century, ranging 00–99. +century, ranging 00--99. @item %D yields @code{%m/%d/%y} as in @samp{02/10/10}. @@ -9095,7 +9195,7 @@ Even if you don't create a session manually, one is created for you by the top-level interface functions. The Session is where objects live like the Commodities that Amounts refer to. -The make a Session useful, you must read a Journal into it, using the +To make a Session useful, you must read a Journal into it, using the function `@code{read_journal}`. This reads Ledger data from the given file, populates a Journal object within the current Session, and returns a reference to that Journal object. @@ -9168,7 +9268,7 @@ looking at its @code{xact} member: last_xact = None for post in ledger.read_journal("sample.dat").query(""): if post.xact != last_xact: - for post in post.xact.posts: + for post in post.xact.posts(): print "Transferring %s to/from %s" % (post.amount, post.account) last_xact = post.xact |