diff --git a/doc/lib.m4 b/doc/lib.m4 index 1fea4ccbc..2f5a56cbe 100644 --- a/doc/lib.m4 +++ b/doc/lib.m4 @@ -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 diff --git a/hledger-lib/doc/hledger_journal.5.m4.md b/hledger-lib/doc/hledger_journal.5.m4.md index 6b29f569d..aea6b1f72 100644 --- a/hledger-lib/doc/hledger_journal.5.m4.md +++ b/hledger-lib/doc/hledger_journal.5.m4.md @@ -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. + + -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 ``` +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 ``` - - - ## Comments Lines in the journal beginning with a semicolon (`;`) or hash (`#`) or diff --git a/hledger/Hledger/Cli/Balance.hs b/hledger/Hledger/Cli/Balance.hs index f43c63cfe..f7681855f 100644 --- a/hledger/Hledger/Cli/Balance.hs +++ b/hledger/Hledger/Cli/Balance.hs @@ -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" diff --git a/hledger/Hledger/Cli/CliOptions.hs b/hledger/Hledger/Cli/CliOptions.hs index 7c781a3d0..9d7b5adc8 100644 --- a/hledger/Hledger/Cli/CliOptions.hs +++ b/hledger/Hledger/Cli/CliOptions.hs @@ -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." ] diff --git a/hledger/doc/commands-balance.m4.md b/hledger/doc/commands-balance.m4.md index 45604e321..631d0327d 100644 --- a/hledger/doc/commands-balance.m4.md +++ b/hledger/doc/commands-balance.m4.md @@ -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. - -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. +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). + +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 diff --git a/hledger/doc/options.m4.md b/hledger/doc/options.m4.md index 4e911087d..6c58b3bc8 100644 --- a/hledger/doc/options.m4.md +++ b/hledger/doc/options.m4.md @@ -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