hledger-1.52.1: Command-line interface for the hledger accounting system

Safe Haskell | None
Language | GHC2021

Hledger.Cli.CliOptions

Contents

- cmdargs flags & modes
- CLI options
- CLI option accessors
- Other utils

Description

Common cmdargs modes and flags, a command-line options type, and related utilities used by hledger commands.

Synopsis

- progname :: ProgramName
- prognameandversion :: String
- binaryinfo :: HledgerBinaryInfo
- inputflags :: [Flag RawOpts]
- reportflags :: [Flag RawOpts]
- helpflags :: [Flag RawOpts]
- terminalflags :: [Flag RawOpts]
- helpflagstitle :: String
- flattreeflags :: Bool -> [Flag RawOpts]
- confflags :: [Flag RawOpts]
- hiddenflags :: [Flag RawOpts]
- hiddenflagsformainmode :: [Flag RawOpts]
- outputFormatFlag :: [String] -> Flag RawOpts
- outputFileFlag :: Flag RawOpts
- generalflagsgroup1 :: (String, [Flag RawOpts])
- generalflagsgroup2 :: (String, [Flag RawOpts])
- generalflagsgroup3 :: (String, [Flag RawOpts])
- mkgeneralflagsgroups1 :: [Flag RawOpts] -> [(String, [Flag RawOpts])]
- mkgeneralflagsgroups2 :: [Flag RawOpts] -> [(String, [Flag RawOpts])]
- mkgeneralflagsgroups3 :: [Flag RawOpts] -> [(String, [Flag RawOpts])]
- cligeneralflagsgroups1 :: [(String, [Flag RawOpts])]
- cligeneralflagsgroups2 :: [(String, [Flag RawOpts])]
- cligeneralflagsgroups3 :: [(String, [Flag RawOpts])]
- defMode :: Mode RawOpts
- defCommandMode :: [Name] -> Mode RawOpts
- addonCommandMode :: Name -> Mode RawOpts
- hledgerCommandMode :: CommandHelpStr -> [Flag RawOpts] -> [(String, [Flag RawOpts])] -> [Flag RawOpts] -> ([Arg RawOpts], Maybe (Arg RawOpts)) -> Mode RawOpts
- argsFlag :: FlagHelp -> Arg RawOpts
- showModeUsage :: Mode a -> String
- withAliases :: String -> [String] -> String
- likelyExecutablesInPath :: IO [String]
- data CliOpts = CliOpts {
  - rawopts_ :: RawOpts
  - command_ :: String
  - file_ :: [FilePath]
  - inputopts_ :: InputOpts
  - reportspec_ :: ReportSpec
  - output_file_ :: Maybe FilePath
  - output_format_ :: Maybe String
  - pageropt_ :: Maybe Bool
  - coloropt_ :: Maybe YNA
  - debug_ :: Int
  - no_new_accounts_ :: Bool
  - width_ :: Maybe String
  - available_width_ :: Int
  - progstarttime_ :: POSIXTime
  }
- class HasCliOpts c where
  - cliOpts :: Lens' c CliOpts
  - available_width :: Lens' c Int
  - coloropt :: Lens' c (Maybe YNA)
  - command :: Lens' c String
  - debug__ :: Lens' c Int
  - file__ :: Lens' c [FilePath]
  - inputopts :: Lens' c InputOpts
  - no_new_accounts :: Lens' c Bool
  - output_file :: Lens' c (Maybe FilePath)
  - output_format :: Lens' c (Maybe String)
  - pageropt :: Lens' c (Maybe Bool)
  - progstarttime :: Lens' c POSIXTime
  - rawopts__ :: Lens' c RawOpts
  - reportspec :: Lens' c ReportSpec
  - width__ :: Lens' c (Maybe String)
- defcliopts :: CliOpts
- getHledgerCliOpts :: Mode RawOpts -> IO CliOpts
- getHledgerCliOpts' :: Mode RawOpts -> [String] -> IO CliOpts
- rawOptsToCliOpts :: RawOpts -> IO CliOpts
- cliOptsDropArgs :: CliOpts -> CliOpts
- argsAddDoubleDash :: (Eq a, IsString a) => [a] -> [a]
- outputFormats :: [String]
- defaultOutputFormat :: String
- type CommandHelpStr = String
- parseCommandHelp :: CommandHelpStr -> Maybe CommandHelp
- journalFilePathFromOpts :: CliOpts -> IO (NonEmpty String)
- journalFilePathFromOptsNoDefault :: CliOpts -> IO (Maybe (NonEmpty String))
- rulesFilePathFromOpts :: CliOpts -> IO (Maybe FilePath)
- outputFileFromOpts :: CliOpts -> IO (Maybe FilePath)
- outputFormatFromOpts :: CliOpts -> String
- defaultWidth :: Int
- replaceNumericFlags :: [String] -> [String]
- ensureDebugFlagHasVal :: [String] -> [String]
- registerWidthsFromOpts :: CliOpts -> (Int, Maybe Int)
- topicForMode :: Mode a -> Topic
- data DeclarablesSelector
  - = Used
  - | Declared
  - | Undeclared
  - | Unused
  - | Find
- declarablesSelectorFromOpts :: CliOpts -> Maybe DeclarablesSelector
- findMatchedByArgument :: RawOpts -> String -> [Text] -> Text

# Documentation

progname :: ProgramName Source #

The name of this program's executable.

prognameandversion :: String Source #

Generate the version string for this program. The template haskell call is here rather than in Hledger.Cli.Version to avoid wasteful recompilation.

binaryinfo :: HledgerBinaryInfo Source #

# cmdargs flags & modes

inputflags :: [Flag RawOpts] Source #

Common input-related flags: --file, --rules, --conf, --alias...

reportflags :: [Flag RawOpts] Source #

Common report-related flags: --period, --cost, etc.

helpflags :: [Flag RawOpts] Source #

terminalflags :: [Flag RawOpts] Source #

helpflagstitle :: String Source #

flattreeflags :: Bool -> [Flag RawOpts] Source #

Flags for selecting flat/tree mode, used for reports organised by account. With a True argument, shows some extra help about inclusive/exclusive amounts.

confflags :: [Flag RawOpts] Source #

hledger CLI's --conf/--no-conf flags.

hiddenflags :: [Flag RawOpts] Source #

hiddenflagsformainmode :: [Flag RawOpts] Source #

Common legacy flags that are accepted but not shown in --help, when running the main mode.

outputFormatFlag :: [String] -> Flag RawOpts Source #

Common output-related flags: --output-file, --output-format...

outputFileFlag :: Flag RawOpts Source #

generalflagsgroup1 :: (String, [Flag RawOpts]) Source #

generalflagsgroup2 :: (String, [Flag RawOpts]) Source #

generalflagsgroup3 :: (String, [Flag RawOpts]) Source #

mkgeneralflagsgroups1 :: [Flag RawOpts] -> [(String, [Flag RawOpts])] Source #

mkgeneralflagsgroups2 :: [Flag RawOpts] -> [(String, [Flag RawOpts])] Source #

mkgeneralflagsgroups3 :: [Flag RawOpts] -> [(String, [Flag RawOpts])] Source #

cligeneralflagsgroups1 :: [(String, [Flag RawOpts])] Source #

cligeneralflagsgroups2 :: [(String, [Flag RawOpts])] Source #

cligeneralflagsgroups3 :: [(String, [Flag RawOpts])] Source #

defMode :: Mode RawOpts Source #

An empty cmdargs mode to use as a template. Modes describe the top-level command, ie the program, or a subcommand, telling cmdargs how to parse a command line and how to generate the command's usage text.

defCommandMode :: [Name] -> Mode RawOpts Source #

A cmdargs mode suitable for a hledger built-in command with the given names (primary name + optional aliases). The usage message shows [QUERY] as argument.

addonCommandMode :: Name -> Mode RawOpts Source #

A cmdargs mode representing the hledger add-on command with the given name, providing hledger's common inputreportinghelp flags. Just used when invoking addons.

hledgerCommandMode :: CommandHelpStr -> [Flag RawOpts] -> [(String, [Flag RawOpts])] -> [Flag RawOpts] -> ([Arg RawOpts], Maybe (Arg RawOpts)) -> Mode RawOpts Source #

Build a cmdarg mode for a hledger command, from a help template and flag/argument specifications. Reduces boilerplate a little, though the complicated cmdargs flag and argument specs are still required.

argsFlag :: FlagHelp -> Arg RawOpts Source #

showModeUsage :: Mode a -> String Source #

Get a mode's usage message as a nicely wrapped string.

withAliases :: String -> [String] -> String Source #

Add command aliases to the command's help string.

likelyExecutablesInPath :: IO [String] Source #

Get all sorted unique filenames in the current user's PATH. We do not currently filter out non-file objects or files without execute permission.

# CLI options

data CliOpts Source #

Command line options, used in the `hledger` package and above. This is the "opts" used throughout hledger CLI code. representing the options and arguments that were provided at startup on the command-line.

Constructors

CliOpts |

Fields

- rawopts_ :: RawOpts
- command_ :: String
- file_ :: [FilePath]
- inputopts_ :: InputOpts
- reportspec_ :: ReportSpec
- output_file_ :: Maybe FilePath
- output_format_ :: Maybe String
- pageropt_ :: Maybe Bool
  - -pager
- coloropt_ :: Maybe YNA
  - -color. Controls use of ANSI color and ANSI styles.
- debug_ :: Int

  debug level, set by `--debug[=N]`. See also `debugLevel`.

- no_new_accounts_ :: Bool
- width_ :: Maybe String

  the --width value provided, if any

- available_width_ :: Int

  estimated usable screen width, based on 1. the width reported by the terminal, if supported 2. the default (80)

- progstarttime_ :: POSIXTime

#### Instances

Instances details

Default CliOpts Source # |
Instance details Defined in Hledger.Cli.CliOptions Methods def :: CliOpts Source #
Show CliOpts Source # |
Instance details Defined in Hledger.Cli.CliOptions Methods showsPrec :: Int -> CliOpts -> ShowS Source # show :: CliOpts -> String Source # showList :: [CliOpts] -> ShowS Source #
HasCliOpts CliOpts Source # |

Instance details

Defined in Hledger.Cli.CliOptions

Methods

cliOpts :: Lens' CliOpts CliOpts Source #

available_width :: Lens' CliOpts Int Source #

coloropt :: Lens' CliOpts (Maybe YNA) Source #

command :: Lens' CliOpts String Source #

debug__ :: Lens' CliOpts Int Source #

file__ :: Lens' CliOpts [FilePath] Source #

inputopts :: Lens' CliOpts InputOpts Source #

no_new_accounts :: Lens' CliOpts Bool Source #

output_file :: Lens' CliOpts (Maybe FilePath) Source #

output_format :: Lens' CliOpts (Maybe String) Source #

pageropt :: Lens' CliOpts (Maybe Bool) Source #

progstarttime :: Lens' CliOpts POSIXTime Source #

rawopts__ :: Lens' CliOpts RawOpts Source #

reportspec :: Lens' CliOpts ReportSpec Source #

width__ :: Lens' CliOpts (Maybe String) Source #

HasBalancingOpts CliOpts Source # |

Instance details

Defined in Hledger.Cli.CliOptions

Methods

balancingOpts :: Lens' CliOpts BalancingOpts Source #

account_types :: Lens' CliOpts (Map AccountName AccountType) Source #

commodity_styles :: Lens' CliOpts (Maybe (Map CommoditySymbol AmountStyle)) Source #

ignore_assertions :: Lens' CliOpts Bool Source #

infer_balancing_costs :: Lens' CliOpts Bool Source #

txn_balancing :: Lens' CliOpts TransactionBalancingPrecision Source #

HasInputOpts CliOpts Source # |

Instance details

Defined in Hledger.Cli.CliOptions

Methods

inputOpts :: Lens' CliOpts InputOpts Source #

aliases :: Lens' CliOpts [String] Source #

anon__ :: Lens' CliOpts Bool Source #

auto__ :: Lens' CliOpts Bool Source #

auto_posting_tags :: Lens' CliOpts Bool Source #

balancingopts :: Lens' CliOpts BalancingOpts Source #

defer :: Lens' CliOpts Bool Source #

forecast :: Lens' CliOpts (Maybe DateSpan) Source #

infer_costs :: Lens' CliOpts Bool Source #

infer_equity :: Lens' CliOpts Bool Source #

ioDay :: Lens' CliOpts Day Source #

mformat :: Lens' CliOpts (Maybe StorageFormat) Source #

mrules_file :: Lens' CliOpts (Maybe FilePath) Source #

new__ :: Lens' CliOpts Bool Source #

new_save :: Lens' CliOpts Bool Source #

oldtimeclock :: Lens' CliOpts Bool Source #

pivot :: Lens' CliOpts String Source #

reportspan :: Lens' CliOpts DateSpan Source #

strict :: Lens' CliOpts Bool Source #

verbose_tags :: Lens' CliOpts Bool Source #

HasReportOpts CliOpts Source # |

Instance details

Defined in Hledger.Cli.CliOptions

Methods

reportOpts :: ReportableLens' CliOpts ReportOpts Source #

period :: ReportableLens' CliOpts Period Source #

statuses :: ReportableLens' CliOpts [Status] Source #

depth :: ReportableLens' CliOpts DepthSpec Source #

date2 :: ReportableLens' CliOpts Bool Source #

real :: ReportableLens' CliOpts Bool Source #

querystring :: ReportableLens' CliOpts [Text] Source #

HasReportOptsNoUpdate CliOpts Source # |

Instance details

Defined in Hledger.Cli.CliOptions

Methods

reportOptsNoUpdate :: Lens' CliOpts ReportOpts Source #

accountlistmode :: Lens' CliOpts AccountListMode Source #

average :: Lens' CliOpts Bool Source #

balance_base_url :: Lens' CliOpts (Maybe Text) Source #

balanceaccum :: Lens' CliOpts BalanceAccumulation Source #

balancecalc :: Lens' CliOpts BalanceCalculation Source #

budgetpat :: Lens' CliOpts (Maybe Text) Source #

color__ :: Lens' CliOpts Bool Source #

conversionop :: Lens' CliOpts (Maybe ConversionOp) Source #

date2NoUpdate :: Lens' CliOpts Bool Source #

declared :: Lens' CliOpts Bool Source #

depthNoUpdate :: Lens' CliOpts DepthSpec Source #

drop__ :: Lens' CliOpts Int Source #

empty__ :: Lens' CliOpts Bool Source #

format :: Lens' CliOpts StringFormat Source #

infer_prices :: Lens' CliOpts Bool Source #

interval :: Lens' CliOpts Interval Source #

invert :: Lens' CliOpts Bool Source #

layout :: Lens' CliOpts Layout Source #

no_elide :: Lens' CliOpts Bool Source #

no_total :: Lens' CliOpts Bool Source #

normalbalance :: Lens' CliOpts (Maybe NormalSign) Source #

percent :: Lens' CliOpts Bool Source #

periodNoUpdate :: Lens' CliOpts Period Source #

pretty :: Lens' CliOpts Bool Source #

querystringNoUpdate :: Lens' CliOpts [Text] Source #

realNoUpdate :: Lens' CliOpts Bool Source #

related :: Lens' CliOpts Bool Source #

row_total :: Lens' CliOpts Bool Source #

show_costs :: Lens' CliOpts Bool Source #

sort_amount :: Lens' CliOpts Bool Source #

sortspec :: Lens' CliOpts SortSpec Source #

statusesNoUpdate :: Lens' CliOpts [Status] Source #

summary_only :: Lens' CliOpts Bool Source #

transpose__ :: Lens' CliOpts Bool Source #

txn_dates :: Lens' CliOpts Bool Source #

value :: Lens' CliOpts (Maybe ValuationType) Source #

HasReportSpec CliOpts Source # |
Instance details Defined in Hledger.Cli.CliOptions Methods reportSpec :: Lens' CliOpts ReportSpec Source # rsDay :: Lens' CliOpts Day Source # rsQuery :: Lens' CliOpts Query Source # rsQueryOpts :: Lens' CliOpts [QueryOpt] Source # rsReportOpts :: Lens' CliOpts ReportOpts Source #

class HasCliOpts c where Source #

Minimal complete definition

cliOpts

Methods

cliOpts :: Lens' c CliOpts Source #

available_width :: Lens' c Int Source #

coloropt :: Lens' c (Maybe YNA) Source #

command :: Lens' c String Source #

debug__ :: Lens' c Int Source #

file__ :: Lens' c [FilePath] Source #

inputopts :: Lens' c InputOpts Source #

no_new_accounts :: Lens' c Bool Source #

output_file :: Lens' c (Maybe FilePath) Source #

output_format :: Lens' c (Maybe String) Source #

pageropt :: Lens' c (Maybe Bool) Source #

progstarttime :: Lens' c POSIXTime Source #

rawopts__ :: Lens' c RawOpts Source #

reportspec :: Lens' c ReportSpec Source #

width__ :: Lens' c (Maybe String) Source #

#### Instances

Instances details

HasCliOpts CliOpts Source # |

Instance details

Defined in Hledger.Cli.CliOptions

Methods

cliOpts :: Lens' CliOpts CliOpts Source #

available_width :: Lens' CliOpts Int Source #

coloropt :: Lens' CliOpts (Maybe YNA) Source #

command :: Lens' CliOpts String Source #

debug__ :: Lens' CliOpts Int Source #

file__ :: Lens' CliOpts [FilePath] Source #

inputopts :: Lens' CliOpts InputOpts Source #

no_new_accounts :: Lens' CliOpts Bool Source #

output_file :: Lens' CliOpts (Maybe FilePath) Source #

output_format :: Lens' CliOpts (Maybe String) Source #

pageropt :: Lens' CliOpts (Maybe Bool) Source #

progstarttime :: Lens' CliOpts POSIXTime Source #

rawopts__ :: Lens' CliOpts RawOpts Source #

reportspec :: Lens' CliOpts ReportSpec Source #

width__ :: Lens' CliOpts (Maybe String) Source #

defcliopts :: CliOpts Source #

getHledgerCliOpts :: Mode RawOpts -> IO CliOpts Source #

getHledgerCliOpts' :: Mode RawOpts -> [String] -> IO CliOpts Source #

A helper for addon commands: this parses options and arguments from the current command line using the given hledger-style cmdargs mode, and returns a CliOpts. Or, with --help or -h present, it prints long or short help, and exits the program. When --debug is present, also prints some debug output. Note this is not used by the main hledger executable.

The help texts are generated from the mode. Long help includes the full usage description generated by cmdargs (including all supported options), framed by whatever pre- and postamble text the mode specifies. It's intended that this forms a complete help document or manual.

Short help is a truncated version of the above: the preamble and the first part of the usage, up to the first line containing "flags:" (normally this marks the start of the common hledger flags); plus a mention of --help and the (presumed supported) common hledger options not displayed.

Tips: Empty lines in the pre/postamble are removed by cmdargs; add a space character to preserve them.

rawOptsToCliOpts :: RawOpts -> IO CliOpts Source #

Parse raw option string values to the desired final data types. Any relative smart dates will be converted to fixed dates based on today's date. Parsing failures will raise an error. Also records the terminal width, if supported.

cliOptsDropArgs :: CliOpts -> CliOpts Source #

Drop the arguments ("args") from this CliOpts' rawopts field.

argsAddDoubleDash :: (Eq a, IsString a) => [a] -> [a] Source #

cmdargs eats the first double-dash (--) argument when parsing a command line, which causes problems for the run and repl commands. Sometimes we work around this by duplicating that first -- argument. This doesn't break anything that we know of yet.

outputFormats :: [String] Source #

All the output formats known by any command, for outputFormatFromOpts. To automatically infer it from -o/--output-file, it needs to be listed here.

defaultOutputFormat :: String Source #

type CommandHelpStr = String Source #

A command's name, optional official abbreviation, and help preamble & postamble, as a specially formatted single string. Used to generate the CLI help, and also the command's doc in the hledger manual. See parseCommandHelp for the format.

parseCommandHelp :: CommandHelpStr -> Maybe CommandHelp Source #

Parse a command's embedded help text (`Somecommand.txt`). That text is generated by `Shake cmdhelp` from the command's doc source (`Somecommand.md`). `Somecommand.md` should be formatted as follows:

- First line: the command name, as a markdown heading.
- Optional third line: the command's official abbreviated name, parenthesised.
- From third or fifth line to a ````flags` line: the command help preamble. Usually one sentence or paragraph; any blank lines will not be rendered.
- A fenced code block beginning with ````flags`, containing a `Flags:` line, followed by a snapshot of the command-specific flags help as generated by cmdargs or "none" if there are no command-specific flags. This should contain no blank lines (no extra newlines in the cmdargs command mode help strings). This is shown as-is in manuals, and regenerated at runtime for --help output.
- Any remaining lines: the command help postamble.

(Note the difference between `Somecommand.md`, which is the markdown source file, and `Somecommand.txt`, which is the plain text file generated by `Shake cmdhelp`, which this function parses.)

# CLI option accessors

These do the extra processing required for some options.

journalFilePathFromOpts :: CliOpts -> IO (NonEmpty String) Source #

Get the (tilde-expanded, absolute) journal file path from 1. options, 2. an environment variable, or 3. the default. Actually, returns one or more file paths. There will be more than one if multiple -f options were provided. File paths can have a READER: prefix naming a reader/data format.

journalFilePathFromOptsNoDefault :: CliOpts -> IO (Maybe (NonEmpty String)) Source #

Like journalFilePathFromOpts, but does not use defaultJournalPath

rulesFilePathFromOpts :: CliOpts -> IO (Maybe FilePath) Source #

Get the (tilde-expanded) rules file path from options, if any.

outputFileFromOpts :: CliOpts -> IO (Maybe FilePath) Source #

Get the expanded, absolute output file path specified by an -o/--output-file options, or nothing, meaning stdout.

outputFormatFromOpts :: CliOpts -> String Source #

Get the output format from the --output-format option, otherwise from a recognised file extension in the --output-file option, otherwise the default (txt).

defaultWidth :: Int Source #

Default width for hledger console output, when not otherwise specified.

replaceNumericFlags :: [String] -> [String] Source #

Replace any numeric flags (eg -2) with their long form (--depth 2), as I'm guessing cmdargs doesn't support this directly.

ensureDebugFlagHasVal :: [String] -> [String] Source #

For register:

registerWidthsFromOpts :: CliOpts -> (Int, Maybe Int) Source #

Get the width in characters to use for the register command's console output, and also the description column width if specified (following the main width, comma-separated). The widths will be as follows: `no --width flag - overall width is the available width (or terminal width, or 80); description width is unspecified (auto) --width W - overall width is W, description width is auto --width W,D - overall width is W, description width is D` Will raise a parse error for a malformed --width argument.

# Other utils

topicForMode :: Mode a -> Topic Source #

Get the most appropriate documentation topic for a mode. Currently, that is either the hledger, hledger-ui or hledger-web manual.

data DeclarablesSelector Source #

Constructors

Used |
Declared |
Undeclared |
Unused |
Find |

#### Instances

Instances details

Show DeclarablesSelector Source # |
Instance details Defined in Hledger.Cli.CliOptions Methods showsPrec :: Int -> DeclarablesSelector -> ShowS Source # show :: DeclarablesSelector -> String Source # showList :: [DeclarablesSelector] -> ShowS Source #
Eq DeclarablesSelector Source # |
Instance details Defined in Hledger.Cli.CliOptions Methods (==) :: DeclarablesSelector -> DeclarablesSelector -> Bool Source # (/=) :: DeclarablesSelector -> DeclarablesSelector -> Bool Source #

declarablesSelectorFromOpts :: CliOpts -> Maybe DeclarablesSelector Source #

findMatchedByArgument :: RawOpts -> String -> [Text] -> Text Source #

A helper for the --find mode offered by commands like accounts, commodities, payees, tags (see also `DeclarablesSelector`). Interpret the first command argument found in rawopts as a case insensitive regular expression, then return the first of the provided items that it matches; or raise an error if there's no valid argument or no matched item. This function's second argument describes the items' type, for the error message.