From 64adad8e75befead3668204aa43408f79dd4a95a Mon Sep 17 00:00:00 2001 From: Stephen Morgan Date: Fri, 22 Nov 2024 23:57:25 +1100 Subject: [PATCH] ;imp: doc: Document new regular expression limited depth. --- hledger/Hledger/Cli/CliOptions.hs | 2 +- hledger/hledger.m4.md | 37 ++++++++++++++++++++++++++++--- 2 files changed, 35 insertions(+), 4 deletions(-) diff --git a/hledger/Hledger/Cli/CliOptions.hs b/hledger/Hledger/Cli/CliOptions.hs index 5b9f8e54671..73cefbd142d 100644 --- a/hledger/Hledger/Cli/CliOptions.hs +++ b/hledger/Hledger/Cli/CliOptions.hs @@ -201,7 +201,7 @@ reportflags = [ ,flagNone ["pending","P"] (setboolopt "pending") "include only pending postings/transactions" ,flagNone ["cleared","C"] (setboolopt "cleared") "include only cleared postings/transactions\n(-U/-P/-C can be combined)" ,flagNone ["real","R"] (setboolopt "real") "include only non-virtual postings" - ,flagReq ["depth"] (\s opts -> Right $ setopt "depth" s opts) "NUM" "or -NUM: show only top NUM levels of accounts" + ,flagReq ["depth"] (\s opts -> Right $ setopt "depth" s opts) "DEPTHEXP" "if a number (or -NUM): show only top NUM levels of accounts. If REGEXP=NUM, only apply limiting to accounts matching the regular expression." ,flagNone ["empty","E"] (setboolopt "empty") "Show zero items, which are normally hidden.\nIn hledger-ui & hledger-web, do the opposite." -- valuation diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 0d961845c21..f1a1de0f580 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -5098,7 +5098,36 @@ Examples: With the `--depth NUM` option (short form: `-NUM`), reports will show accounts only to the specified depth, hiding deeper subaccounts. Use this when you want a summary with less detail. -This flag has the same effect as a `depth:` query argument: `depth:2`, `--depth=2` or `-2` are equivalent. +This flag has the same effect as a `depth:` query argument: `depth:2`, +`--depth=2` or `-2` are equivalent. + +In place of a single number which limits the depth for all accounts, you can +also provide separate depth limits for different accounts using regular +expressions. +For example, `--depth assets=2` (or, equivalently: `depth:assets=2`) +will collapse accounts matching the regular expression `assets` to depth 2. +So `assets:bank:savings` would be collapsed to `assets:bank`, while +`liabilities:bank:credit card` would not be affected. +This can be combined with a flat depth to collapse other accounts not matching +the regular expression, so `--depth assets=2 --depth 1` would collapse +`assets:bank:savings` to `assets:bank` and `liabilities:bank:credit card` to +`liabilities`. + +You can supply multiple depth arguments and they will all be applied, so +`--depth assets=2 --depth liabilities=3 --depth 1` would collapse: + +- accounts matching `assets` to depth 2, +- accounts matching `liabilities` to depth 3, +- all other accounts to depth 1. + +If an account is matched by more than one regular expression depth argument +then the more specific one will used. +For example, if `--depth assets=1 --depth assets:bank:savings=2` is provided, +then `assets:bank:savings` will be collapsed to depth 2 rather than depth 1. +This is because `assets:bank:savings` matches at level 3 in the account name, +while `assets` matches at level 1. +The same would be true with the argument `--depth assets=1 --depth savings=2`. + # Queries @@ -5191,8 +5220,10 @@ Examples:\ **`date2:PERIODEXPR`**\ Match secondary dates within the specified period (independent of the `--date2` flag). -**`depth:N`**\ -Match (or display, depending on command) accounts at or above this depth. +**`depth:[REGEXP=]N`**\ +Match (or display, depending on command) accounts at or above this depth, +optionally only for accounts matching a provided regular expression. +See [Depth](#depth) for detailed rules. **`expr:"TERM AND NOT (TERM OR TERM)"`** (eg)\ Match with a boolean combination of queries (which must be enclosed in quotes).