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

imp:cli: make mutually exclusive flags clearer in --help

Browse Source
This commit is contained in:
Simon Michael 2025-03-08 12:42:16 -10:00
parent 7aae0d9595
commit 02ef6e45e7
8 changed files with 59 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
hledger-ui/Hledger/UI/UIOptions.hs
View File

@ -45,11 +45,11 @@ prognameandversion =
uiflags = [
flagNone ["watch","w"] (setboolopt "watch") "watch for data and date changes and reload automatically"
,flagReq ["theme"] (\s opts -> Right $ setopt "theme" s opts) "THEME" ("use this custom display theme ("++intercalate ", " themeNames++")")
,flagNone ["cash"] (setboolopt "cash") "start in the cash accounts screen"
,flagNone ["bs"] (setboolopt "bs") "start in the balance sheet accounts screen"
,flagNone ["is"] (setboolopt "is") "start in the income statement accounts screen"
,flagNone ["all"] (setboolopt "all") "start in the all accounts screen"
,flagReq ["register"] (\s opts -> Right $ setopt "register" s opts) "ACCTREGEX" "start in the (first matched) account's register"
,flagNone ["cash"] (setboolopt "cash") "start in: the cash accounts screen"
,flagNone ["bs"] (setboolopt "bs") "start in: the balance sheet accounts screen"
,flagNone ["is"] (setboolopt "is") "start in: the income statement accounts screen"
,flagNone ["all"] (setboolopt "all") "start in: the all accounts screen"
,flagReq ["register"] (\s opts -> Right $ setopt "register" s opts) "ACCTREGEX" "start in: the (first matched) account's register"
,flagNone ["change"] (setboolopt "change")
"show period balances (changes) at startup instead of historical balances"
-- ,flagNone ["cumulative"] (setboolopt "cumulative")

2
hledger-web/Hledger/Web/WebOptions.hs
View File

@ -108,7 +108,7 @@ webflags =
"run hledger-web's tests and exit. hspec test runner args may follow a --, eg: hledger-web --test -- --help"
]
where
serveprefix = ""
serveprefix = "server mode: "
webmode :: Mode RawOpts
webmode =

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

@ -183,11 +183,11 @@ reportflags = [
-- report period, interval, dates
flagReq ["begin","b"] (\s opts -> Right $ setopt "begin" s opts) "DATE" "include postings/transactions on/after this date"
,flagReq ["end","e"] (\s opts -> Right $ setopt "end" s opts) "DATE" "include postings/transactions before this date (with a report interval, will be adjusted to following subperiod end)"
,flagNone ["daily","D"] (setboolopt "daily") "multiperiod report with 1 day interval"
,flagNone ["weekly","W"] (setboolopt "weekly") "multiperiod report with 1 week interval"
,flagNone ["monthly","M"] (setboolopt "monthly") "multiperiod report with 1 month interval"
,flagNone ["quarterly","Q"] (setboolopt "quarterly") "multiperiod report with 1 quarter interval"
,flagNone ["yearly","Y"] (setboolopt "yearly") "multiperiod report with 1 year interval"
,flagNone ["daily","D"] (setboolopt "daily") "set report interval: 1 day"
,flagNone ["weekly","W"] (setboolopt "weekly") "set report interval: 1 week"
,flagNone ["monthly","M"] (setboolopt "monthly") "set report interval: 1 month"
,flagNone ["quarterly","Q"] (setboolopt "quarterly") "set report interval: 1 quarter"
,flagNone ["yearly","Y"] (setboolopt "yearly") "set report interval: 1 year"
,flagReq ["period","p"] (\s opts -> Right $ setopt "period" s opts) "PERIODEXP" "set begin date, end date, and/or report interval, with more flexibility"
,flagReq ["today"] (\s opts -> Right $ setopt "today" s opts) "DATE" "override today's date (affects relative dates)"
,flagNone ["date2"] (setboolopt "date2") "match/use secondary dates instead (deprecated)" -- see also hiddenflags
@ -257,11 +257,13 @@ terminalflags = [
flattreeflags :: Bool -> [Flag RawOpts]
flattreeflags showamounthelp = [
flagNone ["flat","l"] (setboolopt "flat")
("show accounts as a flat list (default)"
(prefix ++ "show accounts as a flat list (default)"
++ if showamounthelp then ". Amounts exclude subaccount amounts, except where the account is depth-clipped." else "")
,flagNone ["tree","t"] (setboolopt "tree")
("show accounts as a tree" ++ if showamounthelp then ". Amounts include subaccount amounts." else "")
(prefix ++ "show accounts as a tree" ++ if showamounthelp then ". Amounts include subaccount amounts." else "")
]
where
prefix = "list/tree mode: "
-- | hledger CLI's --conf/--no-conf flags.
confflags = [

6
hledger/Hledger/Cli/Commands/Aregister.hs
View File

@ -49,9 +49,9 @@ aregistermode = hledgerCommandMode
"filter strictly by transaction date, not posting date. Warning: this can show a wrong running balance."
,flagNone ["no-elide"] (setboolopt "no-elide") "don't show only 2 commodities per amount"
,flagNone ["cumulative"] (setboolopt "cumulative")
"show running total from report start date"
(accumprefix ++ "show running total from report start date")
,flagNone ["historical","H"] (setboolopt "historical")
"show historical running total/balance (includes postings before report start date) (default)"
(accumprefix ++ "show historical running total/balance (includes postings before report start date) (default)")
-- ,flagNone ["average","A"] (setboolopt "average")
-- "show running average of posting amounts instead of total (implies --empty)"
-- ,flagNone ["related","r"] (setboolopt "related") "show postings' siblings instead"
@ -74,6 +74,8 @@ aregistermode = hledgerCommandMode
cligeneralflagsgroups1
hiddenflags
([], Just $ argsFlag "ACCTPAT [QUERY]")
where
accumprefix = "accumulation mode: "
-- based on Hledger.UI.RegisterScreen:

25
hledger/Hledger/Cli/Commands/Balance.hs
View File

@ -317,39 +317,40 @@ balancemode = hledgerCommandMode
(
-- https://hledger.org/dev/hledger.html#calculation-type :
[flagNone ["sum"] (setboolopt "sum")
"show sum of posting amounts (default)"
(calcprefix ++ "show sum of posting amounts (default)")
,flagNone ["valuechange"] (setboolopt "valuechange")
"show total change of value of period-end historical balances (caused by deposits, withdrawals, market price fluctuations)"
(calcprefix ++ "show total change of value of period-end historical balances (caused by deposits, withdrawals, market price fluctuations)")
,flagNone ["gain"] (setboolopt "gain")
"show unrealised capital gain/loss (historical balance value minus cost basis)"
(calcprefix ++ "show unrealised capital gain/loss (historical balance value minus cost basis)")
-- XXX --budget[=DESCPAT], --forecast[=PERIODEXP], could be more consistent
,flagOpt "" ["budget"] (\s opts -> Right $ setopt "budget" s opts) "DESCPAT"
(unlines
[ "show sum of posting amounts together with budget goals defined by periodic"
[ calcprefix ++ "show sum of posting amounts together with budget goals defined by periodic"
, "transactions. With a DESCPAT argument (must be separated by = not space),"
, "use only periodic transactions with matching description"
, "(case insensitive substring match)."
])
,flagNone ["count"] (setboolopt "count") "show the count of postings"
,flagNone ["count"] (setboolopt "count")
(calcprefix ++ "show the count of postings")
-- https://hledger.org/dev/hledger.html#accumulation-type :
,flagNone ["change"] (setboolopt "change")
"accumulate amounts from column start to column end (in multicolumn reports, default)"
(accumprefix ++ "accumulate amounts from column start to column end (in multicolumn reports, default)")
,flagNone ["cumulative"] (setboolopt "cumulative")
"accumulate amounts from report start (specified by e.g. -b/--begin) to column end"
(accumprefix ++ "accumulate amounts from report start (specified by e.g. -b/--begin) to column end")
,flagNone ["historical","H"] (setboolopt "historical")
"accumulate amounts from journal start to column end (includes postings before report start date)"
(accumprefix ++ "accumulate amounts from journal start to column end (includes postings before report start date)")
]
-- other options specific to this command:
++ flattreeflags True ++
[flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "omit N leading account name parts (in flat mode)"
[flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "in list mode, omit N leading account name parts"
,flagNone ["declared"] (setboolopt "declared") "include non-parent declared accounts (best used with -E)"
,flagNone ["average","A"] (setboolopt "average") "show a row average column (in multicolumn reports)"
,flagNone ["row-total","T"] (setboolopt "row-total") "show a row total column (in multicolumn reports)"
,flagNone ["summary-only"] (setboolopt "summary-only") "display only row summaries (e.g. row total, average) (in multicolumn reports)"
,flagNone ["no-total","N"] (setboolopt "no-total") "omit the final total row"
,flagNone ["no-elide"] (setboolopt "no-elide") "don't squash boring parent accounts (in tree mode)"
,flagNone ["no-elide"] (setboolopt "no-elide") "in tree mode, don't squash boring parent accounts"
,flagReq ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format (in simple reports)"
,flagNone ["sort-amount","S"] (setboolopt "sort-amount") "sort by amount instead of account code/name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed."
,flagNone ["percent", "%"] (setboolopt "percent") "express values in percentage of each column's total"
@ -379,6 +380,10 @@ balancemode = hledgerCommandMode
])
([], Just $ argsFlag "[QUERY]")
where
calcprefix = "calculation mode: "
accumprefix = "accumulation mode: "
-- | The balance command, prints a balance report.
balance :: CliOpts -> Journal -> IO ()
balance opts@CliOpts{reportspec_=rspec} j = case balancecalc_ ropts of

6
hledger/Hledger/Cli/Commands/Register.hs
View File

@ -47,9 +47,9 @@ import qualified System.IO as IO
registermode = hledgerCommandMode
$(embedFileRelative "Hledger/Cli/Commands/Register.txt")
([flagNone ["cumulative"] (setboolopt "cumulative")
"show running total from report start date (default)"
(accumprefix ++ "show running total from report start date (default)")
,flagNone ["historical","H"] (setboolopt "historical")
"show historical running total/balance (includes postings before report start date)"
(accumprefix ++ "show historical running total/balance (includes postings before report start date)")
,flagNone ["average","A"] (setboolopt "average")
"show running average of posting amounts instead of total (implies --empty)"
,let arg = "DESC" in
@ -77,6 +77,8 @@ registermode = hledgerCommandMode
cligeneralflagsgroups1
hiddenflags
([], Just $ argsFlag "[QUERY]")
where
accumprefix = "accumulation mode: "
-- | Print a (posting) register report.
register :: CliOpts -> Journal -> IO ()

39
hledger/Hledger/Cli/CompoundBalanceCommand.hs
View File

@ -69,37 +69,36 @@ compoundBalanceCommandMode CompoundBalanceCommandSpec{..} =
hledgerCommandMode
cbcdoc
-- keep roughly consistent order with Balance.hs. XXX refactor
([flagNone ["sum"] (setboolopt "sum")
"show sum of posting amounts (default)"
,flagNone ["valuechange"] (setboolopt "valuechange")
"show total change of period-end historical balance value (caused by deposits, withdrawals, market price fluctuations)"
(
-- https://hledger.org/dev/hledger.html#calculation-type :
[flagNone ["sum"] (setboolopt "sum")
(calcprefix ++ "show sum of posting amounts (default)")
,flagNone ["valuechange"] (setboolopt "valuechange")
(calcprefix ++ "show total change of value of period-end historical balances (caused by deposits, withdrawals, market price fluctuations)")
,flagNone ["gain"] (setboolopt "gain")
"show unrealised capital gain/loss (historical balance value minus cost basis)"
(calcprefix ++ "show unrealised capital gain/loss (historical balance value minus cost basis)")
-- currently not supported by compound balance commands:
-- ,flagNone ["budget"] (setboolopt "budget")
-- "show sum of posting amounts compared to budget goals defined by periodic transactions"
,flagNone ["count"] (setboolopt "count") "show the count of postings"
-- (calcprefix ++ "show sum of posting amounts compared to budget goals defined by periodic transactions")
,flagNone ["count"] (setboolopt "count") (calcprefix ++ "show the count of postings")
-- https://hledger.org/dev/hledger.html#accumulation-type :
,flagNone ["change"] (setboolopt "change")
("accumulate amounts from column start to column end (in multicolumn reports)"
++ defaultMarker PerPeriod)
(accumprefix ++ "accumulate amounts from column start to column end (in multicolumn reports)" ++ defaultMarker PerPeriod)
,flagNone ["cumulative"] (setboolopt "cumulative")
("accumulate amounts from report start (specified by e.g. -b/--begin) to column end"
++ defaultMarker Cumulative)
(accumprefix ++ "accumulate amounts from report start (specified by e.g. -b/--begin) to column end" ++ defaultMarker Cumulative)
,flagNone ["historical","H"] (setboolopt "historical")
("accumulate amounts from journal start to column end (includes postings before report start date)"
++ defaultMarker Historical)
(accumprefix ++ "accumulate amounts from journal start to column end (includes postings before report start date)" ++ defaultMarker Historical)
]
++ flattreeflags True ++
[flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts"
[flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "in list mode, omit N leading account name parts"
,flagNone ["declared"] (setboolopt "declared") "include non-parent declared accounts (best used with -E)"
,flagNone ["average","A"] (setboolopt "average") "show a row average column (in multicolumn reports)"
,flagNone ["row-total","T"] (setboolopt "row-total") "show a row total column (in multicolumn reports)"
,flagNone ["summary-only"] (setboolopt "summary-only") "display only row summaries (e.g. row total, average) (in multicolumn reports)"
,flagNone ["no-total","N"] (setboolopt "no-total") "omit the final total row"
,flagNone ["no-elide"] (setboolopt "no-elide") "don't squash boring parent accounts (in tree mode)"
,flagNone ["no-elide"] (setboolopt "no-elide") "in tree mode, don't squash boring parent accounts"
,flagReq ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format (in simple reports)"
,flagNone ["sort-amount","S"] (setboolopt "sort-amount") "sort by amount instead of account code/name"
,flagNone ["percent", "%"] (setboolopt "percent") "express values in percentage of each column's total"
@ -123,9 +122,11 @@ compoundBalanceCommandMode CompoundBalanceCommandSpec{..} =
])
([], Just $ argsFlag "[QUERY]")
where
defaultMarker :: BalanceAccumulation -> String
defaultMarker bacc | bacc == cbcaccum = " (default)"
| otherwise = ""
calcprefix = "calculation mode: "
accumprefix = "accumulation mode: "
defaultMarker :: BalanceAccumulation -> String
defaultMarker bacc | bacc == cbcaccum = " (default)"
| otherwise = ""
-- | Generate a runnable command from a compound balance command specification.
compoundBalanceCommand :: CompoundBalanceCommandSpec -> (CliOpts -> Journal -> IO ())

1
hledger/hledger.m4.md
View File

@ -268,6 +268,7 @@ eg you can write `--tl` instead of `--tldr` or `--dry` instead of `--dry-run`.
If the same option appears more than once in a command line, usually the last (right-most) wins.
Similarly, if mutually exclusive flags are used together, the right-most wins.
(When flags are mutually exclusive, they'll usually have a group prefix in --help.)
With most commands, arguments are interpreted as a hledger [query](hledger.md#queries) which filter the data.
Some queries can be expressed either with options or with arguments.