slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc, cli: improvements for -B, -V, prices docs #403

Browse Source
This commit is contained in:
Simon Michael 2016-12-30 14:30:23 -08:00
parent a5992c38a8
commit 701fb5496f
6 changed files with 85 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
doc/lib.m4
View File

@ -140,11 +140,15 @@ m4_define({{_reportingoptions_}}, {{
: show items with zero amount, normally hidden
`-B --cost`
: show amounts in their cost price's commodity
: convert amounts to their cost at transaction time
(using the [transaction price](journal.html#transaction-prices), if any)
`--pivot TAG`
: will transform the journal before any other processing by replacing the account name of every posting having the tag TAG with content VALUE by the account name "TAG:VALUE".
: The TAG will only match if it is a full-length match. The pivot will only happen if the TAG is on a posting, not if it is on the transaction. If the tag value is a multi:level:account:name the new account name will be "TAG:multi:level:account:name".
: will transform the journal before any other processing by replacing
the account name of every posting having the tag TAG with content VALUE
by the account name "TAG:VALUE". The TAG will only match if it is a full-length match.
The pivot will only happen if the TAG is on a posting, not if it is on the transaction.
If the tag value is a multi:level:account:name the new account name will be "TAG:multi:level:account:name".
`--anon`
: show anonymized accounts and payees

55
hledger-lib/doc/hledger_journal.5.m4.md
View File

@ -373,15 +373,23 @@ instead of just reading it.
### Transaction prices
When recording a transaction, you can also record an amount's price in another commodity.
This documents the exchange rate, cost (of a purchase), or selling price (of a sale) that was in effect within this particular transaction (or more precisely, within the particular posting).
These transaction prices are fixed, and do not change.
Within a transaction posting, you can record an amount's price in another commodity.
This can be used to document the cost (for a purchase), or selling price (for a sale),
or the exchange rate that was used, for this transaction.
These transaction prices are fixed, and do not change over time.
<!--
This is different from Ledger, where transaction prices fluctuate by
default. Ledger has a different syntax for specifying
[fixed prices](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices):
`{=PRICE}`. hledger parses that syntax, and (currently) ignores it.
-->
<!-- hledger treats this as an alternate spelling of `@ PRICE`, for greater compatibility with Ledger files. -->
Such priced amounts can be displayed in their transaction price's
commodity, by using the `--cost/-B` flag (B for "cost Basis"),
supported by most hledger commands.
Amounts with transaction prices can be displayed in the transaction price's
commodity, by using the [`--cost/-B`](hledger.html#reporting-options) flag
supported by most hledger commands (mnemonic: "cost Basis").
There are three ways to specify a transaction price:
There are several ways to record a transaction price:
1. Write the unit price (aka exchange rate), as `@ UNITPRICE` after the amount:
@ -423,37 +431,30 @@ rate of purchases made in a foreign currency.
### Market prices
Market prices are not tied to a particular transaction; they represent
historical exchange rates between two commodities. For example, the prices
published by a [stock exchange](https://en.wikipedia.org/wiki/Stock_exchange)
Market prices are not tied to a particular transaction; they represent historical exchange rates between two commodities.
(Ledger calls them historical prices.)
For example, the prices published by a [stock exchange](https://en.wikipedia.org/wiki/Stock_exchange)
or the [foreign exchange market](https://en.wikipedia.org/wiki/Foreign_exchange_market).
Some commands ([balance](hledger.html#market-value), currently) can use this information to show the market value of things at a given date.
When market prices are known and in effect at the
[report end date](hledger.html#report-start-end-date) (see hledger -> Report start & end date),
the balance command's `-V/--value` option will show balances as their market value on that date.
(This option is currently available only with the [balance](#balance) command.)
To record market prices (Ledger calls them historical prices), use P directives,
in the journal or an [included](#including-other-files) file. Their format is:
To record market prices, use P directives in the main journal or
in an [included](#including-other-files) file. Their format is:
```journal
P DATE COMMODITYSYMBOL UNITPRICE
P DATE COMMODITYBEINGPRICED UNITPRICE
```
<!-- (A time and numeric time zone are allowed but ignored, like ledger.) -->
DATE is a [simple date](#simple-dates) as usual.
COMMODITYBEINGPRICED is the symbol of the commodity being priced (just the symbol, no quantity).
UNITPRICE is an ordinary [amount](#amounts) (symbol and quantity) in a second commodity,
specifying the unit price or conversion rate for the first commodity in terms of the second, on the given date.
For example, the following directives say that the euro's exchange rate was 1.35 US dollars during 2009, and $1.40 from 2010 onward (and unknown before 2009).
For example, the following directives say that one euro was worth 1.35 US dollars during 2009,
and $1.40 from 2010 onward:
```journal
P 2009/1/1 € $1.35
P 2010/1/1 € $1.40
```
<!--
This is different from Ledger, where transaction prices fluctuate by
default. Ledger has a different syntax for specifying
[fixed prices](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices):
`{=PRICE}`. hledger parses that syntax, and (currently) ignores it.
-->
<!-- hledger treats this as an alternate spelling of `@ PRICE`, for greater compatibility with Ledger files. -->
## Comments
Lines in the journal beginning with a semicolon (`;`) or hash (`#`) or

2
hledger/Hledger/Cli/Balance.hs
View File

@ -275,7 +275,7 @@ balancemode = (defCommandMode $ ["balance"] ++ aliases) { -- also accept but don
"show historical ending balance in each period (includes postings before report start date)\n "
,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show accounts as a tree; amounts include subaccounts (default in simple reports)"
,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list; amounts exclude subaccounts except when account is depth-clipped (default in multicolumn reports)\n "
,flagNone ["value","V"] (setboolopt "value") "convert amounts to current market value in their default valuation commodity"
,flagNone ["value","V"] (setboolopt "value") "convert amounts to their market value on the report end date (using the most recent applicable market price, if any)"
,flagNone ["average","A"] (\opts -> setboolopt "average" opts) "show a row average column (in multicolumn reports)"
,flagNone ["row-total","T"] (\opts -> setboolopt "row-total" opts) "show a row total column (in multicolumn reports)"
,flagNone ["no-total","N"] (\opts -> setboolopt "no-total" opts) "omit the final total row"

2
hledger/Hledger/Cli/CliOptions.hs
View File

@ -142,7 +142,7 @@ reportflags = [
,flagNone ["real","R"] (setboolopt "real") "include only non-virtual postings"
,flagReq ["depth"] (\s opts -> Right $ setopt "depth" s opts) "N" "hide accounts/postings deeper than N"
,flagNone ["empty","E"] (setboolopt "empty") "show items with zero amount, normally hidden"
,flagNone ["cost","B"] (setboolopt "cost") "show amounts in their cost price's commodity"
,flagNone ["cost","B"] (setboolopt "cost") "convert amounts to their cost at transaction time (using the transaction price, if any)"
,flagNone ["anon"] (setboolopt "anon") "output ledger with anonymized accounts and payees."
]

54
hledger/doc/commands-balance.m4.md
View File

@ -17,7 +17,8 @@ Show accounts and their balances. Alias: bal.
: show accounts as a list; amounts exclude subaccounts except when account is depth-clipped (default in multicolumn reports)
`-V --value`
: convert amounts to current market value in their default valuation commodity
: convert amounts to their market value on the report end date
(using the most recent applicable [market price](journal.html#market-prices), if any)
`-A --average`
: show a row average column (in multicolumn mode)
@ -235,15 +236,50 @@ Balance changes in 2008:
### Market value
The `-V/--value` flag converts all the reported amounts to their
"current market value" using their default market price. That is the
latest [market price](#market-prices) (P directive) found in the
journal (or an included file), for the amount's commodity, dated on or
before the report end date.
The `-V/--value` flag converts the reported amounts to their market value
on the report end date, using the most recent applicable market prices,
when known.
Specifically, when there is a [market price](journal.html#market-prices) (P directive)
for the amount's commodity, dated on or before the
[report end date](hledger.html#report-start-end-date) (see hledger -> Report start & end date),
the amount will be converted to the price's commodity.
If multiple applicable prices are defined, the latest-dated one is used
(and if dates are equal, the one last parsed).
Unlike Ledger, hledger's -V only uses the market prices recorded with
P directives, ignoring transaction prices recorded as part of posting
amounts (which -B/--cost uses). Using -B and -V together is allowed.
For example:
```journal
# one euro is worth this many dollars from nov 1
P 2016/11/01 € $1.10
# purchase some euros on nov 3
2016/11/3
assets:euros €100
assets:checking
# the euro is worth fewer dollars by dec 21
P 2016/12/21 € $1.03
```
How many euros do I have ?
```
$ hledger -f t.j bal euros
€100 assets:euros
```
What are they worth on nov 3 ? (no report end date specified, defaults to the last date in the journal)
```
$ hledger -f t.j bal euros -V
$110.00 assets:euros
```
What are they worth on dec 21 ?
```
$ hledger -f t.j bal euros -V -e 2016/12/21
$103.00 assets:euros
```
Currently, hledger's -V only uses market prices recorded with P directives,
not [transaction prices](journal.html#transaction-prices) (unlike Ledger).
Using -B and -V together is allowed.
### Custom balance output

4
hledger/doc/options.m4.md
View File

@ -130,7 +130,7 @@ and can have less-significant date parts omitted (defaulting to 1).
Examples:
------------------------------------------------- ------------------------------------------------------
------------------------------------------------- -----------------------------------------------------------------------------
`2009/1/1`, `2009/01/01`, `2009-1-1`, `2009.1.1` simple dates, several separators allowed
`2009/1`, `2009` same as above - a missing day or month defaults to 1
`1/1`, `january`, `jan`, `this year` relative dates, meaning january 1 of the current year
@ -159,7 +159,7 @@ so you need to write the date *after* the last day you want to include.
Examples:
----------------------------------- ------------------------------------------------------
----------------------------------- -------------------------------------------------------------------------------------------
`-b 2016/3/17` begin on St. Patrick's day 2016
`-e 12/1` end at the start of december 1st of the current year (11/30 will be the last date included)
`-b thismonth` all transactions on or after the 1st of the current month