Hledger.Cli.CliOptions

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

Documentation

progname :: ProgramName

The name of this program's executable.

prognameandversion :: String

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

cmdargs flags & modes

inputflags :: [Flag RawOpts]

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

reportflags :: [Flag RawOpts]

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

helpflags :: [Flag RawOpts]

helpflagstitle :: String

flattreeflags :: Bool -> [Flag RawOpts]

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]

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

hiddenflags :: [Flag RawOpts]

hiddenflagsformainmode :: [Flag RawOpts]

Common legacy flags that are accepted but not shown in --help.

outputFormatFlag :: [String] -> Flag RawOpts

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

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

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

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

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

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

showModeUsage :: Mode a -> String

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

withAliases :: String -> [String] -> String

Add command aliases to the command's help string.

likelyExecutablesInPath :: IO [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.

hledgerExecutablesInPath :: IO [String]

Get the sorted unique filenames of all hledger-* executables in the current user's PATH. These are files in any of the PATH directories, named hledger-*, with either no extension (and no periods in the name) or one of the addonExtensions. We do not currently filter out non-file objects or files without execute permission.

CLI options

data CliOpts

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
• 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 COLUMNS env var, if set 2. the width reported by the terminal, if supported 3. the default (80)

• progstarttime_ :: POSIXTime

Instances

Show CliOpts

Defined in Hledger.Cli.CliOptions

Methods

showsPrec :: Int -> CliOpts -> ShowS

show :: CliOpts -> String

showList :: [CliOpts] -> ShowS

Default CliOpts

Defined in Hledger.Cli.CliOptions

Methods

def :: CliOpts

HasCliOpts CliOpts

Defined in Hledger.Cli.CliOptions

Methods

cliOpts :: Lens' CliOpts CliOpts

available_width :: Lens' CliOpts Int

command :: Lens' CliOpts String

debug__ :: Lens' CliOpts Int

file__ :: Lens' CliOpts [FilePath]

inputopts :: Lens' CliOpts InputOpts

no_new_accounts :: Lens' CliOpts Bool

output_file :: Lens' CliOpts (Maybe FilePath)

output_format :: Lens' CliOpts (Maybe String)

progstarttime :: Lens' CliOpts POSIXTime

rawopts__ :: Lens' CliOpts RawOpts

reportspec :: Lens' CliOpts ReportSpec

width__ :: Lens' CliOpts (Maybe String)

HasBalancingOpts CliOpts

Defined in Hledger.Cli.CliOptions

Methods

balancingOpts :: Lens' CliOpts BalancingOpts

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

ignore_assertions :: Lens' CliOpts Bool

infer_balancing_costs :: Lens' CliOpts Bool

HasInputOpts CliOpts

Defined in Hledger.Cli.CliOptions

Methods

inputOpts :: Lens' CliOpts InputOpts

aliases :: Lens' CliOpts [String]

anon__ :: Lens' CliOpts Bool

auto__ :: Lens' CliOpts Bool

balancingopts :: Lens' CliOpts BalancingOpts

defer :: Lens' CliOpts Bool

forecast :: Lens' CliOpts (Maybe DateSpan)

infer_costs :: Lens' CliOpts Bool

infer_equity :: Lens' CliOpts Bool

ioDay :: Lens' CliOpts Day

mformat :: Lens' CliOpts (Maybe StorageFormat)

mrules_file :: Lens' CliOpts (Maybe FilePath)

new__ :: Lens' CliOpts Bool

new_save :: Lens' CliOpts Bool

pivot :: Lens' CliOpts String

reportspan :: Lens' CliOpts DateSpan

strict :: Lens' CliOpts Bool

verbose_tags :: Lens' CliOpts Bool

HasReportOpts CliOpts

Defined in Hledger.Cli.CliOptions

Methods

reportOpts :: ReportableLens' CliOpts ReportOpts

period :: ReportableLens' CliOpts Period

statuses :: ReportableLens' CliOpts [Status]

depth :: ReportableLens' CliOpts (Maybe Int)

date2 :: ReportableLens' CliOpts Bool

real :: ReportableLens' CliOpts Bool

querystring :: ReportableLens' CliOpts [Text]

HasReportOptsNoUpdate CliOpts

Defined in Hledger.Cli.CliOptions

Methods

reportOptsNoUpdate :: Lens' CliOpts ReportOpts

accountlistmode :: Lens' CliOpts AccountListMode

average :: Lens' CliOpts Bool

balanceaccum :: Lens' CliOpts BalanceAccumulation

balancecalc :: Lens' CliOpts BalanceCalculation

budgetpat :: Lens' CliOpts (Maybe Text)

color__ :: Lens' CliOpts Bool

conversionop :: Lens' CliOpts (Maybe ConversionOp)

date2NoUpdate :: Lens' CliOpts Bool

declared :: Lens' CliOpts Bool

depthNoUpdate :: Lens' CliOpts (Maybe Int)

drop__ :: Lens' CliOpts Int

empty__ :: Lens' CliOpts Bool

format :: Lens' CliOpts StringFormat

infer_prices :: Lens' CliOpts Bool

interval :: Lens' CliOpts Interval

invert :: Lens' CliOpts Bool

layout :: Lens' CliOpts Layout

no_elide :: Lens' CliOpts Bool

no_total :: Lens' CliOpts Bool

normalbalance :: Lens' CliOpts (Maybe NormalSign)

percent :: Lens' CliOpts Bool

periodNoUpdate :: Lens' CliOpts Period

pretty :: Lens' CliOpts Bool

querystringNoUpdate :: Lens' CliOpts [Text]

realNoUpdate :: Lens' CliOpts Bool

related :: Lens' CliOpts Bool

row_total :: Lens' CliOpts Bool

show_costs :: Lens' CliOpts Bool

sort_amount :: Lens' CliOpts Bool

sortspec :: Lens' CliOpts SortSpec

statusesNoUpdate :: Lens' CliOpts [Status]

summary_only :: Lens' CliOpts Bool

transpose__ :: Lens' CliOpts Bool

txn_dates :: Lens' CliOpts Bool

value :: Lens' CliOpts (Maybe ValuationType)

HasReportSpec CliOpts

Defined in Hledger.Cli.CliOptions

Methods

reportSpec :: Lens' CliOpts ReportSpec

rsDay :: Lens' CliOpts Day

rsQuery :: Lens' CliOpts Query

rsQueryOpts :: Lens' CliOpts [QueryOpt]

rsReportOpts :: Lens' CliOpts ReportOpts

class HasCliOpts c where

Minimal complete definition

cliOpts

Methods

cliOpts :: Lens' c CliOpts

available_width :: Lens' c Int

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)

progstarttime :: Lens' c POSIXTime

rawopts__ :: Lens' c RawOpts

reportspec :: Lens' c ReportSpec

width__ :: Lens' c (Maybe String)

Instances

HasCliOpts CliOpts

Defined in Hledger.Cli.CliOptions

Methods

cliOpts :: Lens' CliOpts CliOpts

available_width :: Lens' CliOpts Int

command :: Lens' CliOpts String

debug__ :: Lens' CliOpts Int

file__ :: Lens' CliOpts [FilePath]

inputopts :: Lens' CliOpts InputOpts

no_new_accounts :: Lens' CliOpts Bool

output_file :: Lens' CliOpts (Maybe FilePath)

output_format :: Lens' CliOpts (Maybe String)

progstarttime :: Lens' CliOpts POSIXTime

rawopts__ :: Lens' CliOpts RawOpts

reportspec :: Lens' CliOpts ReportSpec

width__ :: Lens' CliOpts (Maybe String)

defcliopts :: CliOpts

getHledgerCliOpts :: Mode RawOpts -> IO CliOpts

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

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

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.

outputFormats :: [String]

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

type CommandHelpStr = String

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

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

• First line: main command name, as a markdown heading.
• Optional parenthesised third line: an official abbreviation of the command name.
• 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)

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.

rulesFilePathFromOpts :: CliOpts -> IO (Maybe FilePath)

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

outputFileFromOpts :: CliOpts -> IO (Maybe FilePath)

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

outputFormatFromOpts :: CliOpts -> String

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

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

replaceNumericFlags :: [String] -> [String]

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]

For register:

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

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 (COLUMNS, or posix 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

hledgerAddons :: IO [String]

Get the sorted unique canonical names of hledger addon commands found in the current user's PATH. These are used in command line parsing and to display the commands list.

Canonical addon names are the filenames of hledger-* executables in PATH, without the "hledger-" prefix, and without the file extension except when it's needed for disambiguation (see below).

When there are exactly two versions of an executable (same base name, different extensions) that look like a source and compiled pair (one has .exe, .com, or no extension), the source version will be excluded (even if it happens to be newer). When there are three or more versions (or two versions that don't look like a source/compiled pair), they are all included, with file extensions intact.

topicForMode :: Mode a -> Topic

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