imp:pivot: support pivoting on commodity symbol; doc improvements

hledger-lib/Hledger/Data/Journal.hs

@@ -1164,9 +1164,16 @@ pivotAccount :: Text -> Posting -> Text
 pivotAccount fieldortagname p =
   T.intercalate ":" [pivotComponent x p | x <- T.splitOn ":" fieldortagname]
 
+-- | Get the value of the given field or tag for this posting, otherwise the empty string.
+-- "comm" and "cur" are accepted as synonyms meaning the commodity symbol.
+-- We currently don't handle pivoting of a posting with more than one commodity symbol; in that case we return "".
 pivotComponent :: Text -> Posting -> Text
 pivotComponent fieldortagname p
   |                           fieldortagname == "acct"        = paccount p
+  |                           fieldortagname `elem` ["cur","comm"] =
+    case map acommodity $ amounts $ pamount p of
+      [s] -> s
+      _   -> ""
   | Just t <- ptransaction p, fieldortagname == "code"        = tcode t
   | Just t <- ptransaction p, fieldortagname == "desc"        = tdescription t
   | Just t <- ptransaction p, fieldortagname == "description" = tdescription t  -- backward compatible with 1.30 and older

hledger/hledger.m4.md

@@ -5373,15 +5373,22 @@ When amounts are converted to other commodities in [cost](#cost-reporting) or [v
 
 # Pivoting
 
-Normally, hledger groups and sums amounts within each account.
+Normally, hledger groups amounts and displays their totals by account (name).
-The `--pivot FIELD` option substitutes some other transaction field for account names,
+With `--pivot PIVOTEXPR`, some other field's (or multiple fields') value is used as a synthetic account name, causing different grouping and display.
-causing amounts to be grouped and summed by that field's value instead.
+PIVOTEXPR can be 
-FIELD can be any of the transaction fields `acct`, `status`, `code`, `desc`, `payee`, `note`, or a tag name.
-When pivoting on a tag and a posting has multiple values of that tag, only the first value is displayed.
-Values containing `colon:separated:parts` will be displayed hierarchically, like account names.
-Multiple, colon-delimited fields can be pivoted simultaneously, generating a hierarchical account name.
 
-Some examples:
+- any of these standard transaction or posting fields (their value is substituted): `status`, `code`, `desc`, `payee`, `note`, `acct`, `comm`/`cur`
+- or a tag name
+- or any combination of these, colon-separated.
+
+Some special cases:
+
+- Colons, in PIVOTEXPR or in a pivoted tag value, will appear in the generated account name, influencing the account tree.
+- When an unrecognised tag name or field is provided, its pivoted value will be "".
+- When a posting has multiple commodities, the pivoted value of "comm"/"cur" will be "".
+- When pivoting a posting has multiple values for a tag, the pivoted value of that tag will be the first value.
+
+For example:
 
 ```journal
 2016/02/16 Yearly Dues Payment
@@ -5418,7 +5425,7 @@ $ hledger balance --pivot member acct:.
 --------------------
               -2 EUR
 ```
-Hierarchical reports can be generated with multiple pivots:
+Hierarchical reports can be generated with multiple pivot values:
 ```cli
 $ hledger balance Income:Dues --pivot kind:member
               -2 EUR  Lifetime:John Doe

hledger/test/pivot.test

@@ -117,6 +117,7 @@ $ hledger -f- --pivot payee reg -D ^expense
 2016-02-16   Auchan                                         22 EUR        22 EUR
              StarBars                                        5 EUR        27 EUR
 2016-02-17   Auchan                                         30 EUR        57 EUR
+
 # ** 11. pivot on multiple tags
 <
 2023-01-01 compound purchase
@@ -128,3 +129,52 @@ $ hledger -f- --pivot acct:kind:project bal ^expense -N
                   10  expenses:equipment:job1
                   20  expenses:equipment:job2
                   25  expenses:fee:job2
+
+# ** 12. Pivot on the commodity symbol with "comm".
+<
+2025-01-01
+    expenses   1 A
+    expenses   2 B
+    assets
+
+$ hledger -f- bal -Y expenses --pivot=comm 
+Balance changes in 2025:
+
+   ||     2025 
+===++==========
+ A ||      1 A 
+ B ||      2 B 
+---++----------
+   || 1 A, 2 B 
+
+# ** 13. "cur" is accepted as a synonym. Postings with multiple commodities currently are lumped in the "" bucket, not pivoted fully.
+$ hledger -f- bal -Y assets --pivot=cur
+Balance changes in 2025:
+
+  ||       2025 
+==++============
+  || -1 A, -2 B 
+--++------------
+  || -1 A, -2 B 
+
+# ** 14. When commodities are being converted, the original commodity is shown.
+$ hledger -f- bal -Y expenses --pivot=comm -B
+Balance changes in 2025, converted to cost:
+
+   || 2025 
+===++======
+ A ||   $1 
+ B ||   $2 
+---++------
+   ||   $3 
+
+# ** 15. The "" bucket looks a bit strange in this case..
+$ hledger -f- bal -Y assets --pivot=comm -B
+Balance changes in 2025, converted to cost:
+
+   || 2025 
+===++======
+ $ ||  $-3 
+---++------
+   ||  $-3 
+