journal: fix balance assertions/assignments & prices (#824)

Hopefully this is will do it. This restores the past behaviour:

- parsing prices in balance assertions/assignments
- ignoring them in assertions
- using them in assignments
- and printing them

and clarifies tests and docs.

hledger-lib/Hledger/Read/Common.hs

@@ -737,11 +737,11 @@ balanceassertionp = do
   char '='
   exact <- optional $ try $ char '='
   lift (skipMany spacenonewline)
-  -- allow this amount to have a price, for compatibility, but discard it
+  -- this amount can have a price; balance assertions ignore it,
+  -- but balance assignments will use it
   a <- amountp <?> "amount (for a balance assertion or assignment)"
-  let a' = a{aprice=NoPrice}
   return BalanceAssertion
-    { baamount = a'
+    { baamount = a
     , baexact = isJust exact
     , baposition = sourcepos
     }

hledger-lib/hledger_journal.m4.md

@@ -438,10 +438,18 @@ One workaround is to isolate each commodity into its own subaccount:
 
 ### Assertions and prices
 
-Balance assertion (or assignment) amounts should not have a [price](#transaction-prices),
+Balance assertions ignore [transaction prices](#transaction-prices),
-as the meaning of that is unclear.
+and should normally be written without one:
-A price written there will be ignored.
+
-(hledger's [close](/manual.html#close) command used to generate balance assertions with prices.)
+``` journal
+2019/1/1
+  (a)     $1 @ €1 = $1
+```
+
+We do allow prices to be written there, however, and [print](/manual.html#print) shows them,
+even though they don't affect whether the assertion passes or fails.
+This is for backward compatibility (hledger's [close](/manual.html#close) command used to generate balance assertions with prices),
+and because [balance *assignments*](#balance-assignments) do use them (see below).
 
 ### Assertions and subaccounts
 
@@ -505,6 +513,20 @@ Note that using balance assignments makes your journal a little less explicit;
 to know the exact amount posted, you have to run hledger or do the calculations yourself,
 instead of just reading it.
 
+### Balance assignments and prices
+
+A [transaction price](#transaction-prices) in a balance assignment
+will cause the calculated amount to have that price attached:
+
+``` journal
+2019/1/1
+  (a)             = $1 @ €2
+```
+```
+$ hledger print --explicit
+2019/01/01
+    (a)         $1 @ €2 = $1 @ €2
+```
 
 ## Transaction prices
 

tests/journal/balance-assertions.test

@@ -1,4 +1,6 @@
 #!/usr/bin/env shelltest
+# balance assertion & balance assignment tests
+
 # 1. test some balance assertions
 hledger -f - stats
 <<<
@@ -358,16 +360,46 @@ hledger -f - stats
 >>>=0
 
 # 20. Balance assertions may have a price, but it's ignored
-hledger -f- stats
+hledger -f- print
 <<<
 2019/01/01
     (a)         1A @ 1B = 1A @ 2B
 >>>
->>>2 /unexpected '@'/
+2019/01/01
->>>=1
+    (a)         1A @ 1B = 1A @ 2B
 
-# 21. The exact amounts are compared; display precision does not affect assertions.
+>>>=0
-hledger -f- stats
+
+# 21. Balance assignments may have a price, and it's used for the posting amount.
+# But not shown as part of the balance assertion in the resulting posting.
+hledger -f- print --explicit
+<<<
+2019/01/01
+    (a)                 = 1A @ 2B
+>>>
+2019/01/01
+    (a)         1A @ 2B = 1A @ 2B
+
+>>>=0
+
+# 22. close generates balance assertions without prices
+hledger -f- close -e 2019/1/2
+<<<
+2019/01/01
+    (a)         1A @ 1B = 1A @ 2B
+>>>
+2019/01/01 closing balances
+    a                              -1A @ 1B = 0A
+    equity:closing balances
+
+2019/01/02 opening balances
+    a                               1A @ 1B = 1A
+    equity:opening balances
+
+>>>=0
+
+# 23. The exact amounts are compared; display precision does not affect assertions.
+hledger -f- print
 <<<
 commodity $1000.00
 
@@ -377,12 +409,12 @@ commodity $1000.00
 2019/01/02
     (a)             $1.00  = $1.006
 
->>> /Transactions/
+>>> /2019/
 >>>2
 >>>=0
 
-# 22. This fails
+# 24. This fails
-hledger -f- stats
+hledger -f- print
 <<<
 commodity $1000.00
 
@@ -395,8 +427,8 @@ commodity $1000.00
 >>>2 /difference: 0\.004/
 >>>=1
 
-# 23. This fails
+# 25. This fails
-hledger -f- stats
+hledger -f- print
 <<<
 commodity $1000.00