diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/NEWS | 85 | ||||
| -rw-r--r-- | doc/ledger.1 | 5 | ||||
| -rw-r--r-- | doc/ledger3.texi | 191 |
3 files changed, 197 insertions, 84 deletions
@@ -1,33 +1,80 @@ Ledger NEWS -* 3.1.2 +* 3.1.2 (2019-02-05) -- Increased maximum length for regex from 255 to 4095 (bug #981). +- Increase maximum length for regex from 255 to 4095 (bug #981) - Initialize periods from from/since clause rather than earliest - transaction date (bug #1159). + transaction date (bug #1159) -- Check balance assertions against the amount after the posting (bug #1147). +- Check balance assertions against the amount after the posting (bug #1147) -- Allow balance assertions with multiple posts to same account (bug #1187). +- Allow balance assertions with multiple posts to same account (bug #1187) -- Fixed period duration of "every X days" and similar statements (bug #370). +- Fix period duration of "every X days" and similar statements (bug #370) -- Option --force-color does not require --color anymore (bug #1109). +- Make option --force-color not require --color anymore (bug #1109) -- Added quoted_rfc4180 to allow CVS output with RFC 4180 compliant quoting. +- Add quoted_rfc4180 to allow CVS output with RFC 4180 compliant quoting. + +- Add support for --prepend-format in accounts command + +- Fix handling of edge cases in trim function (bug #520) + +- Fix auto xact posts not getting applied to account total during + journal parse (bug #552) + +- Transfer null_post flags to generated postings + +- Fix segfault when using --market with --group-by + +- Use amount_width variable for budget report + +- Keep pending items in budgets until the last day they apply + +- Fix bug where .total used in value expressions breaks totals + +- Make automated transactions work with assertions (bug #1127) + +- Improve parsing of date tokens (bug #1626) + +- Don't attempt to invert a value if it's already zero (bug #1703) + +- Do not parse user-specified init-file twice + +- Fix parsing issue of effective dates (bug #1722, TALOS-2017-0303, + CVE-2017-2807) + +- Fix use-after-free issue with deferred postings (bug #1723, TALOS-2017-0304, + CVE-2017-2808) + +- Fix possible stack overflow in option parsing routine (bug #1222, + CVE-2017-12481) + +- Fix possible stack overflow in date parsing routine (bug #1224, + CVE-2017-12482) + +- Fix use-after-free when using --gain (bug #541) - Python: Removed double quotes from Unicode values. +- Python: Ensure that parse errors produce useful RuntimeErrors + +- Python: Expose journal expand_aliases + +- Python: Expose journal_t::register_account + +- Improve bash completion + - Emacs Lisp files have been moved to https://github.com/ledger/ledger-mode -- Fixed build under MSYS (32-bit). +- Fix build under MSYS (32-bit). -- Fixed build under Cygwin. +- Fix build under Cygwin. - Various documentation improvements -* 3.1.1 +* 3.1.1 (2016-01-11) - Added a --no-revalued option @@ -57,7 +104,7 @@ - Add continuous integration (https://travis-ci.org/ledger/ledger) -* 3.1 +* 3.1 (2014-10-05) - Changed the definition of cost basis to preserve the original cost basis when a gain or loss is made (if you bought 1 AAA for $10 and then sold @@ -154,7 +201,7 @@ features, please see the manual. 2008/07/27 Starting fresh Assets:Checking $750.00 Equity:Opening Balances - + 2008/07/27 Starting fresh Assets:Checking = $1,000.00 Equity:Adjustments @@ -164,7 +211,7 @@ features, please see the manual. 2008/07/27 Starting fresh Assets:Checking $750.00 Equity:Opening Balances - + 2008/07/27 Starting fresh Assets:Checking $250.00 Equity:Adjustments @@ -183,7 +230,7 @@ features, please see the manual. 2008/07/24 Opening Balance Assets:Checking = $250.00 ; we force set it Equity:Opening Balances - + 2008/07/24 Opening Balance Assets:Checking = EC 250.00 ; we force set it again Equity:Opening Balances @@ -195,7 +242,7 @@ features, please see the manual. Assets:Checking = $250.00 ; we force set it again Assets:Checking EC 100.00 ; and add some EC's Equity:Opening Balances - + 2008/07/24 Opening Balance Assets:Checking = EC 250.00 ; we force set the EC's Equity:Opening Balances @@ -213,15 +260,15 @@ features, please see the manual. 2008/07/24 Opening Balance Assets:Checking = $100.00 Equity:Opening Balances - + 2008/07/30 We spend money, with a known balance afterward Expenses:Food $20.00 Assets:Checking = $80.00 - + 2008/07/30 Again we spend money, but this time with all the info Expenses:Food $20.00 Assets:Checking $-20.00 = $60.00 - + 2008/07/30 This entry yield an 'unbalanced' error Expenses:Food $20.00 Assets:Checking $-20.00 = $30.00 diff --git a/doc/ledger.1 b/doc/ledger.1 index 85a9937b..a76750ba 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -214,6 +214,9 @@ Note that a comma-separated list of expressions is allowed, in which case each sorting term is used in order to determine the final ordering. For example, to search by date and then amount, one would use: .Dl ledger reg --sort 'date, amount' +The sort order may be controlled with the '-' sign. For example, to sort in +reverse chronological order: +.Dl ledger reg --sort '-date' .It Fl \-tail Ar number Only show the last .Ar number @@ -578,7 +581,7 @@ Direct to require pre-declarations for entities (such as accounts, commodities and tags) rather than taking entities from cleared transactions as defined. -.It Fl \-file Ar FILE +.It Fl \-file Ar FILE Pq Fl f Read journal data from .Ar FILE . .It Fl \-first Ar INT diff --git a/doc/ledger3.texi b/doc/ledger3.texi index a955be9a..0ac62b29 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -111,7 +111,7 @@ @copying -Copyright @copyright{} 2003--2018, John Wiegley. All rights reserved. +Copyright @copyright{} 2003--2019, 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 @@ -427,7 +427,7 @@ 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 +@url{https://k.sfconservancy.org/NPO-Accounting/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, @@ -1384,10 +1384,11 @@ account: (Funds:School) $-100.00 @end smallexample -When reports are generated, by default they'll appear in terms of the -funds. In this case, you will likely want to mask out your -@samp{Assets} account, because otherwise the balance won't make much -sense: +The use of round brackets creates a virtual posting without ensuring +a balance to zero. When reports are generated, by default they'll +appear in terms of the funds. In this case, you will likely want to +mask out your @samp{Assets} account, because otherwise the balance +won't make much sense: @smallexample @c command:396F24E $ ledger --no-total bal not ^Assets @@ -2255,6 +2256,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 @@ -2402,6 +2438,7 @@ commodity $ note American Dollars format $1,000.00 nomarket + alias USD default @end smallexample @@ -2416,6 +2453,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 @@ -2436,59 +2476,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 @@ -2914,7 +2913,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 @@ -3105,6 +3104,13 @@ it appears as: This shows that they are all in the same transaction (which is why the date is not repeated), but they have different payees now. +If using the @option{--strict} or @option{--pedantic} options, you must +declare this tag to avoid warnings and errors. + +The payee name used with the tag is not enforced by the +@option{--check-payees} option, due to a bug: +@url{https://github.com/ledger/ledger/issues/556}. + @node Metadata values, Typed metadata, Metadata tags, Metadata @subsection Metadata values @@ -3189,9 +3195,9 @@ look ``harder'') rather than parentheses: @node Expression amounts, Balance verification, Virtual postings, Transactions @section Expression amounts -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: +An amount is a numerical figure with a commodity, but it can also be +any value expression. To indicate this, surround the amount +expression with parentheses: @smallexample @c input:validate 2012-03-10 * KFC @@ -3232,6 +3238,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 @@ -3508,12 +3553,12 @@ Plus, it comes with dangers. This works fine: 2012-04-10 My Broker Assets:Brokerage:Cash $375.00 - Assets:Brokerage -5 AAPL @{$50.00@} @@ $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 + Assets:Brokerage -5 AAPL @{$50.00@} @@@@ $375.00 Income:Capital Gains $-125.00 @end smallexample @@ -3527,12 +3572,12 @@ But this does not do what you might expect: 2012-04-10 My Broker Assets:Brokerage:Cash $375.00 - Assets:Brokerage -5 AAPL @{@{$500.00@}@} @@ $375.00 + Assets:Brokerage -5 AAPL @{@{$500.00@}@} @@@@ $375.00 Income:Capital Gains $-125.00 2012-04-10 My Broker Assets:Brokerage:Cash $375.00 - Assets:Brokerage -5 AAPL @{@{$500.00@}@} @@ $375.00 + Assets:Brokerage -5 AAPL @{@{$500.00@}@} @@@@ $375.00 Income:Capital Gains $-125.00 @end smallexample @@ -3608,7 +3653,7 @@ expressions): @smallexample 2012-04-10 My Broker Assets:Brokerage:Cash $375.00 - Assets:Brokerage -5 AAPL @{$50.00@} [2012-04-10] @@ $375.00 + Assets:Brokerage -5 AAPL @{$50.00@} [2012-04-10] @@@@ $375.00 Income:Capital Gains $-125.00 @end smallexample @@ -3625,7 +3670,7 @@ 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 + Assets:Brokerage -5 AAPL @{$50.00@} [2012-04-10] (Oh my!) @@@@ $375.00 Income:Capital Gains $-125.00 @end smallexample @@ -8091,8 +8136,13 @@ posting. A regular expression that matches against a transaction's payee name. @item %/REGEX/ -@itemx tag(REGEX) -A regular expression that matches against a transaction's tags. +@itemx expr has_tag(/REGEX/) +@itemx expr has_tag('TAG') +A regular expression (REGEX) or string (TAG) that checks for the tags of +a transaction. + +@item tag(REGEX) =~ /REGEX/ +A regular expression that matches a transaction's tags against its values. @item expr date =~ /REGEX/ Useful for specifying a date in plain terms. For example, you could say @@ -8161,6 +8211,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 @@ -9218,7 +9281,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 |