hledger-1.3: Command-line interface for the hledger accounting tool

Safe Haskell | None
Language | Haskell2010

Hledger.Cli.CliOptions

Contents

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

Description

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

Synopsis

- helpflags :: [Flag RawOpts]
- detailedversionflag :: Flag RawOpts
- inputflags :: [Flag RawOpts]
- reportflags :: [Flag RawOpts]
- outputflags :: [Flag RawOpts]
- generalflagsgroup1 :: (String, [Flag RawOpts])
- generalflagsgroup2 :: (String, [Flag RawOpts])
- generalflagsgroup3 :: (String, [Flag RawOpts])
- defMode :: Mode RawOpts
- defCommandMode :: [Name] -> Mode RawOpts
- quickAddonCommandMode :: Name -> Mode RawOpts
- hledgerCommandMode :: HelpTemplate -> [Flag RawOpts] -> [(Help, [Flag RawOpts])] -> [Flag RawOpts] -> ([Arg RawOpts], Maybe (Arg RawOpts)) -> Mode RawOpts
- argsFlag :: FlagHelp -> Arg RawOpts
- showModeUsage :: Mode a -> String
- withAliases :: String -> [String] -> String
- data CliOpts = CliOpts {
  - rawopts_ :: RawOpts
  - command_ :: String
  - file_ :: [FilePath]
  - rules_file_ :: Maybe FilePath
  - output_file_ :: Maybe FilePath
  - output_format_ :: Maybe String
  - alias_ :: [String]
  - ignore_assertions_ :: Bool
  - debug_ :: Int
  - no_new_accounts_ :: Bool
  - width_ :: Maybe String
  - available_width_ :: Int
  - reportopts_ :: ReportOpts
  }
- defcliopts :: CliOpts
- getHledgerCliOpts :: Mode RawOpts -> IO CliOpts
- decodeRawOpts :: RawOpts -> RawOpts
- rawOptsToCliOpts :: RawOpts -> IO CliOpts
- checkCliOpts :: CliOpts -> CliOpts
- outputFormats :: [[Char]]
- defaultOutputFormat :: [Char]
- defaultBalanceLineFormat :: StringFormat
- aliasesFromOpts :: CliOpts -> [AccountAlias]
- journalFilePathFromOpts :: CliOpts -> IO [String]
- rulesFilePathFromOpts :: CliOpts -> IO (Maybe FilePath)
- outputFileFromOpts :: CliOpts -> IO FilePath
- outputFormatFromOpts :: CliOpts -> String
- defaultWidth :: Int
- widthFromOpts :: CliOpts -> Int
- registerWidthsFromOpts :: CliOpts -> (Int, Maybe Int)
- maybeAccountNameDrop :: ReportOpts -> AccountName -> AccountName
- lineFormatFromOpts :: ReportOpts -> Either String StringFormat
- hledgerAddons :: IO [String]
- topicForMode :: Mode a -> Topic
- tests_Hledger_Cli_CliOptions :: Test

# cmdargs flags & modes

helpflags :: [Flag RawOpts] #

Common help flags: --help, --debug, --version...

detailedversionflag :: Flag RawOpts #

A hidden flag, just for the hledger executable.

inputflags :: [Flag RawOpts] #

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

reportflags :: [Flag RawOpts] #

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

outputflags :: [Flag RawOpts] #

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

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

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

generalflagsgroup3 :: (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 default flags are short and long help (-h and --help). The usage message shows [QUERY] as argument.

quickAddonCommandMode :: Name -> Mode RawOpts #

A cmdargs mode representing the hledger add-on command with the given name. Like defCommandMode, but adds a appropriate short help message if the addon name is recognised, and includes hledger's common inputreportinghelp flags as default. Just used by hledger for generating the commands list I think (or possibly for invoking the addons as well ?)

hledgerCommandMode :: HelpTemplate -> [Flag RawOpts] -> [(Help, [Flag RawOpts])] -> [Flag RawOpts] -> ([Arg RawOpts], Maybe (Arg RawOpts)) -> Mode RawOpts #

Build a cmdarg mode suitable for a hledger add-on command, from a help template and flag/argument specifications. Reduces boilerplate a little, though the complicated cmdargs flag and argument specs are still required. See the addons in bin/ for examples of usage.

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.

# 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] rules_file_ :: Maybe FilePath output_file_ :: Maybe FilePath output_format_ :: Maybe String alias_ :: [String] ignore_assertions_ :: Bool 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) reportopts_ :: ReportOpts

Instances

Data CliOpts # |
Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> CliOpts -> c CliOpts # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c CliOpts # toConstr :: CliOpts -> Constr # dataTypeOf :: CliOpts -> DataType # dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c CliOpts) # dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c CliOpts) # gmapT :: (forall b. Data b => b -> b) -> CliOpts -> CliOpts # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> CliOpts -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> CliOpts -> r # gmapQ :: (forall d. Data d => d -> u) -> CliOpts -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> CliOpts -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> CliOpts -> m CliOpts # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> CliOpts -> m CliOpts # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> CliOpts -> m CliOpts #
Show CliOpts # |
Methods showsPrec :: Int -> CliOpts -> ShowS # show :: CliOpts -> String # showList :: [CliOpts] -> ShowS #
Default CliOpts # |
Methods def :: CliOpts #

defcliopts :: CliOpts #

getHledgerCliOpts :: Mode RawOpts -> 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.

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.

decodeRawOpts :: RawOpts -> RawOpts #

Convert possibly encoded option values to regular unicode strings.

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.

checkCliOpts :: CliOpts -> CliOpts #

Do final validation of processed opts, raising an error if there is trouble.

outputFormats :: [[Char]] #

defaultOutputFormat :: [Char] #

defaultBalanceLineFormat :: StringFormat #

Default line format for balance report: "%20(total) %2(depth_spacer)%-(account)"

# CLI option accessors

These do the extra processing required for some options.

aliasesFromOpts :: CliOpts -> [AccountAlias] #

Get the account name aliases from options, if any.

journalFilePathFromOpts :: CliOpts -> IO [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 FilePath #

Get the expanded, absolute output file path from options, or the default (-, 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.

widthFromOpts :: CliOpts -> Int #

Get the width in characters to use for console output. This comes from the --width option, or the COLUMNS environment variable, or (on posix platforms) the current terminal width, or 80. Will raise a parse error for a malformed --width argument.

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.

maybeAccountNameDrop :: ReportOpts -> AccountName -> AccountName #

Drop leading components of accounts names as specified by --drop, but only in --flat mode.

For balance:

lineFormatFromOpts :: ReportOpts -> Either String StringFormat #

Parse the format option if provided, possibly returning an error, otherwise get the default value.

# 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, hledger-web or hledger-api manual.

# Tests

tests_Hledger_Cli_CliOptions :: Test #