Hledger.Cli.CliOptions

The name of this program's executable.

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

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

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

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

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

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

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

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.

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.

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

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.

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

Add command aliases to the command's help string.

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.

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.

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.

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.

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

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.

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

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.

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.)

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.

Like journalFilePathFromOpts, but does not use defaultJournalPath

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

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

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

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

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

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.

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

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.