sfos/ledger
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #392 from thdox/doc-validation

Browse source 
Changes mainly about validation of @smallexample
This commit is contained in:
Alexis Hildebrandt 2015-02-20 14:34:40 +01:00
commit b1d73eaa84
1 changed files with 88 additions and 70 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

158
doc/ledger3.texi
View file

@ -1396,7 +1396,7 @@ $ ledger --real --no-total bal
If more asset accounts are needed as the source of a posting, just
list them as you would normally, for example:
@smallexample
@smallexample @c input:validate
2004/03/25 Payment for books (paid from Checking)
Expenses:Books $100.00
Assets:Checking $-50.00
@ -1612,7 +1612,7 @@ Beneath these top level accounts you can have any level of detail you
desire. For example, if you want to keep specific track of how much
you spend on burgers and fries, you could have the following:
@smallexample
@smallexample @c input:validate
Expenses:Food:Hamburgers and Fries
@end smallexample
@ -1898,14 +1898,14 @@ your function in Python, you can return something like
that value is always used, regardless of the commodity, the date, or
the desired target commodity. For example,
@smallexample
@smallexample @c input:validate
define myfunc_seven(s, d, t) = 7 EUR
@end smallexample
In order to specify a fixed price, but still valuate that price into
the target commodity, use something like this:
@smallexample
@smallexample @c input:validate
define myfunc_five(s, d, t) = market(5 EUR, d, t)
@end smallexample
@ -1913,14 +1913,14 @@ The @code{value} directive sets the valuation used for all commodities
used in the rest of the data stream. This is the fallback, if nothing
more specific is found.
@smallexample
@smallexample @c input:validate
value myfunc_seven
@end smallexample
You can set a specific valuation function on a per-commodity basis.
Instead of defining a function, you can also pass a lambda.
@smallexample
@smallexample @c input:validate
commodity $
value s, d, t -> 6 EUR
@end smallexample
@ -1928,7 +1928,7 @@ commodity $
Each account can also provide a default valuation function for any
commodities transferred to that account.
@smallexample
@smallexample @c input:validate
account Expenses:Food5
value myfunc_five
@end smallexample
@ -1936,7 +1936,7 @@ account Expenses:Food5
The metadata field @samp{Value}, if found, overrides the valuation
function on a transaction-wide or per-posting basis.
@smallexample
@smallexample @c input:validate
= @@XACT and Food
; Value:: 8 EUR
(Equity) $1
@ -2019,10 +2019,9 @@ In order to combat inconsistency you can define allowable accounts and
payees. For simplicity, create a separate text file and define accounts
and payees like
@smallexample
@smallexample @c input:validate
account Expenses
account Expenses:Utilities
...
@end smallexample
Using the @option{--strict} option will cause Ledger to complain if any
@ -2038,7 +2037,7 @@ Warning: "FinanceData/Master.dat", line 15: Unknown account 'Allocation:Equities
If you have a large Ledger register already created use the
@command{accounts} command to get started:
@smallexample
@smallexample @c command:validate
$ ledger accounts >> Accounts.dat
@end smallexample
@ -2457,15 +2456,14 @@ payee KFC
The @code{alias} sub-directive provides a regex which, if it matches
a parsed payee, the declared payee name is substituted:
@smallexample
@smallexample @c input:validate
2012-02-27 KENTUCKY FRIED CHICKEN ; will be read as being 'KFC'
...
@end smallexample
The @code{uuid} sub-directive specifies that a transaction with exactly
the uuid given should have the declared payee name substituted:
@smallexample
@smallexample @c input:validate
2014-05-13 UNHELPFUL PAYEE ; will be read as being 'KFC'
; UUID: 2a2e21d434356f886c84371eebac6e44f1337fda
@end smallexample
@ -2593,7 +2591,7 @@ with a home currency, such as the dollar @samp{$}. 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
@smallexample @c input:validate
N SYMBOL
@end smallexample
@ -3015,7 +3013,7 @@ 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
below:
@smallexample @c input:validate
@smallexample @c input:9B43E57
2010-06-17 Sample
Assets:Bank $400.00
Income:Check1 $-100.00 ; Payee: Person One
@ -3024,14 +3022,20 @@ below:
Income:Check4 $-100.00 ; Payee: Person Four
@end smallexample
When reporting this, it appears as:
When reporting with
@smallexample
10-Jun-17 Sample Assets:Bank $400.00 $400.00
Person One Income:Check1 $-100.00 $300.00
Person Two Income:Check2 $-100.00 $200.00
Person Three Income:Check3 $-100.00 $100.00
Person Four Income:Check4 $-100.00 0
@smallexample @c command:9B43E57
$ ledger reg
@end smallexample
it appears as:
@smallexample @c output:9B43E57
10-Jun-17 Sample Assets:Bank $400.00 $400.00
Person One Income:Check1 $-100.00 $300.00
Person Two Income:Check2 $-100.00 $200.00
Person Three Income:Check3 $-100.00 $100.00
Person Four Income:Check4 $-100.00 0
@end smallexample
This shows that they are all in the same transaction (which is why the
@ -3585,13 +3589,13 @@ 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
@smallexample @c input:validate
define ten_dollars(s, date, t) = market($10, date, t)
@end smallexample
I can now use that in a lot value expression as follows:
@smallexample
@smallexample @c input:validate
2012-04-10 My Broker
Assets:Brokerage:Cash $375.00
Assets:Brokerage -5 AAPL @{$50.00@} ((ten_dollars)) @@@@ $375.00
@ -4203,8 +4207,7 @@ you want, or interface Ledger with other programs.
A query such as the following shows all expenses since last
October, sorted by total:
@c TODO: does not validate with @c command:validate, because "last oct" is split at the space
@smallexample
@smallexample @c command:validate
$ ledger -b "last oct" -S T bal ^expenses
@end smallexample
@ -4296,11 +4299,11 @@ invested in equities, and partially invested in bonds and cash. Below
is the asset allocation for each of the instruments listed above:
@multitable @columnfractions .2 .2 .3 .3
@item @tab Domestic @tab Global @tab
@item Symbol @tab Equity @tab Equity @tab bonds/cash
@item VIFSX @tab 100% @tab @tab
@item VTHRX @tab 24.0% @tab 56.3% @tab 19.7%
@item VSGBX @tab @tab @tab 100%
@item @tab Domestic @tab Global @tab
@item Symbol @tab Equity @tab Equity @tab bonds/cash
@item VIFSX @tab 100% @tab @tab
@item VTHRX @tab 24.0% @tab 56.3% @tab 19.7%
@item VSGBX @tab @tab @tab 100%
@end multitable
These numbers are available from the prospectus of any publicly
@ -4309,7 +4312,7 @@ and a single bond issue is 100% bonds.
We track purchases of specific investments using the symbol of that
investment as its commodity. How do we tell Ledger that a share of
VTHRX is 24% Global equity etc.? Enter automatic transactions and
VTHRX is 24% Domestic equity? Enter automatic transactions and
virtual accounts.
At the top of our ledger we enter automatic transactions that describe
@ -4320,12 +4323,9 @@ actual balances.
For the three instruments listed above, those automatic transactions
would look like:
@smallexample @c input:validate
;
; automatic calculations for asset allocation tracking
;
@smallexample @c input:582C8C2
= expr ( commodity == 'VIFSX' )
(Allocation:Equities:Domestic) 1.000
(Allocation:Equities:Domestic) 1.000
= expr ( commodity == 'VTHRX' )
(Allocation:Equities:Global) 0.240
@ -4334,6 +4334,18 @@ would look like:
= expr ( commodity == 'VBMFX')
(Allocation:Bonds/Cash) 1.000
2015-01-01 Buy VIFSX
Assets:Broker 100 VIFSX
Assets:Cash $-10000
2015-01-01 Buy VTHRX
Assets:Broker 10 VTHRX
Assets:Cash $-10000
2015-01-01 Buy VBMFX
Assets:Broker 1 VBMFX
Assets:Cash $-10000
@end smallexample
How do these work? First the @samp{=} sign at the beginning of the
@ -4352,23 +4364,21 @@ the various asset classes how do we get a report that tells us our
current allocation? Using the balance command and some tricky
formatting!
@c TODO: does not @c command:validate due to multiple lines
@smallexample
@smallexample @c command:582C8C2
ledger bal Allocation --current --format "\
%-17((depth_spacer)+(partial_account))\
%10(percent(market(display_total), market(parent.total)))\
%16(market(display_total))\n%/"
@end smallexample
@noindent
Which yields:
@smallexample
Allocation 100.00% $100000.00
Bonds/Cash 38.94% $38940.00
Equities 61.06% $61060.00
Domestic 95.31% $58196.29
Global 4.69% $2863.71
@smallexample @c result:582C8C2
Allocation 100.00% $30000
Bonds/Cash 39.90% $11970
Equities 60.10% $18030
Domestic 86.69% $15630
Global 13.31% $2400
@end smallexample
Let's look at the Ledger invocation a bit closer. The command above is
@ -5249,8 +5259,10 @@ journal. Using the @option{--count} option will tell you how many
entries use each payee. To filter the payees displayed you must use the
prefix @@:
@smallexample
@smallexample @c command:validate
$ ledger payees @@Nic
@end smallexample
@smallexample
Nicolas
Nicolas BOILABUS
Oudtshoorn Municipality
@ -6380,8 +6392,10 @@ Set the format for the headers that separates the report sections of
a grouped report. Only has an effect with a @option{--group-by
@var{EXPR}} register report.
@smallexample
@smallexample @c command:validate
$ ledger reg Expenses --group-by "payee" --group-title-format "------------------------ %-20(value) ---------------------\n"
@end smallexample
@smallexample
------------------------ 7-Eleven ---------------------
2011/08/13 7-Eleven Expenses:Auto:Misc $ 5.80 $ 5.80
@ -6528,8 +6542,10 @@ example, if you have multiple cars and track each fuel purchase in
identifying which car the purchase was for @samp{; Car: Prius}, then the
command:
@smallexample
@smallexample @c command:validate
$ ledger bal Fuel --pivot "Car" --period "this year"
@end smallexample
@smallexample
$ 3491.26 Car
$ 1084.22 M3:Expenses:Auto:Fuel
$ 149.65 MG V11:Expenses:Auto:Fuel
@ -6752,7 +6768,7 @@ settings. To specify options in the init file, use the same syntax as
on the command-line, but put each option on its own line. Here is an
example init file:
@smallexample
@smallexample @c input:validate
--price-db ~/finance/.pricedb
--wide
; ~/.ledgerrc ends here
@ -7055,8 +7071,7 @@ register report, for example, but they will not be displayed. This is
useful for seeing last month's checking postings, against a running
balance which includes all posting values:
@c TODO: does not @c command:validate due to space in "last month"
@smallexample
@smallexample @c command:validate
$ ledger -d "d>=[last month]" reg checking
@end smallexample
@ -7064,8 +7079,7 @@ The output from this command is very different from the following,
whose running total includes only postings from the last month
onward:
@c TODO: does not @c command:validate due to space in "last month"
@smallexample
@smallexample @c command:validate
$ ledger -p "last month" reg checking
@end smallexample
@ -7221,7 +7235,7 @@ settings can be placed in this file manually, to prevent downloading
quotes for a specific commodity, for example. This is done by adding a
line like the following:
@smallexample
@smallexample @c input:validate
; Don't download quotes for the dollar, or timelog values
N $
N h
@ -7459,7 +7473,7 @@ command-line always take precedence over environment variable settings, however.
Note that you may also permanently specify option values by placing
option settings in the file @file{~/.ledgerrc} one option per line, for example:
@smallexample
@smallexample @c input:validate
--pager /bin/cat
@end smallexample
@ -7597,7 +7611,7 @@ These two periodic transactions give the usual monthly expenses, as well
as one typical yearly expense. For help on finding out what your
average monthly expenses are for any category, use a command like:
@smallexample
@smallexample @c command:validate
$ ledger -p "this year" --monthly --average balance ^expenses
@end smallexample
@ -7730,7 +7744,7 @@ constrain which transactions are printed. For example, the following
command shows only transactions from the beginning of the current month,
while still calculating the running balance based on all transactions:
@smallexample
@smallexample @c command:validate
$ ledger -d "d>[this month]" register checking
@end smallexample
@ -7739,7 +7753,7 @@ running total in terms of all transactions in the register. The
following, simpler command is similar, but totals only the displayed
postings:
@smallexample
@smallexample @c command:validate
$ ledger -b "this month" register checking
@end smallexample
@ -7945,7 +7959,7 @@ field. This searches only a posting's field, not the transaction's note
or comment field. For example, @code{ledger reg "expr" "comment =~
/landline/"} will match:
@smallexample
@smallexample @c input:validate
2014/1/29 Phone bill
Assets:Checking $50.00
Expenses:Phone $-50.00 ; landline bill
@ -7953,7 +7967,7 @@ or comment field. For example, @code{ledger reg "expr" "comment =~
but will not match:
@smallexample
@smallexample @c input:validate
2014/1/29 Phone bill ; landline bill
; landline bill
Assets:Checking $50.00
@ -7969,19 +7983,19 @@ This searches all comments in the transaction, including comments on
individual postings. Thus, @samp{ledger reg "expr" "note =~ /landline/"}
will match both all the three examples below:
@smallexample
@smallexample @c input:validate
2014/1/29 Phone bill
Assets:Checking $50.00
Expenses:Phone $-50.00 ; landline bill
@end smallexample
@smallexample
@smallexample @c input:validate
2014/1/29 Phone bill ; landline bill
Assets:Checking $50.00
Expenses:Phone $-50.00
@end smallexample
@smallexample
@smallexample @c input:validate
2014/1/29 Phone bill
; landline bill
Assets:Checking $50.00
@ -8130,7 +8144,7 @@ for format string details.
$ ledger -f expr.dat --format "%(format_date(date, '%A, %B %d. %Y'))\n" reg assets
@end smallexample
@smallexample @c output:9605B13
Friday, January 16. 2015
Friday, January 16. 2015
@end smallexample
@end defun
@ -9757,8 +9771,10 @@ and apply it against a model transaction.
@item period @var{PERIOD_EXPRESSION}
Evaluate the given period and report how Ledger interprets it:
@smallexample
$ ledger period "this year"
@smallexample @c command:51F6A2C
$ ledger period "this year" --now 2011-01-01
@end smallexample
@smallexample @c result:51F6A2C
--- Period expression tokens ---
TOK_THIS: this
TOK_YEAR: year
@ -9781,8 +9797,10 @@ END_REACHED: <EOF>
Evaluate the given arguments and report how Ledger interprets it against
the following model transaction:
@smallexample
@smallexample @c command:validate
$ ledger query "/Book/"
@end smallexample
@smallexample
--- Input arguments ---
("/Book/")
@ -9910,7 +9928,7 @@ The test scripts take the remainder of the @code{test} line and use
it as command-line arguments for ledger, the text enclosed in @code{test}
and @code{end test} is expected output, for example:
@smallexample
@smallexample @c input:validate
; This is the journal data
year 2014
12/24 (C0d3) Santa Claus