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

Safe Haskell | None
Language | Haskell2010

Hledger.Cli

Contents

- Re-exports
  - System.Console.CmdArgs.Explicit

Description

This is the root module of the `hledger` package, providing hledger's command-line interface. The main function, commands, command-line options, and utilities useful to other hledger command-line programs are exported. It also re-exports hledger-lib:Hledger and cmdargs:System.Concole.CmdArgs.Explicit

See also:

- hledger-lib:Hledger
- The README files
- The high-level developer docs

## About

hledger - a fast, reliable, user-friendly plain text accounting tool. Copyright (c) 2007-2024 Simon Michael simon@joyful.com and contributors Released under GPL version 3 or later.

hledger is a Haskell rewrite of John Wiegley's "ledger". It generates financial reports from a plain text general journal. You can use the command line:

    $ hledger

or ghci:

    $ make ghci
    ghci> Right j <- runExceptT $ readJournalFile definputopts "examples/sample.journal"  -- or: j <- defaultJournal
    ghci> :t j
    j :: Journal
    ghci> stats defcliopts j
    Main file                : examples/sample.journal
    Included files           :
    Transactions span        : 2008-01-01 to 2009-01-01 (366 days)
    Last transaction         : 2008-12-31 (733772 days from now)
    Transactions             : 5 (0.0 per day)
    Transactions last 30 days: 0 (0.0 per day)
    Transactions last 7 days : 0 (0.0 per day)
    Payees/descriptions      : 5
    Accounts                 : 8 (depth 3)
    Commodities              : 1 ($)
    Market prices            : 0 ()

    Run time (throughput)    : 1695276900.00s (0 txns/s)
    ghci> balance defcliopts j
                      $1  assets:bank:saving
                     $-2  assets:cash
                      $1  expenses:food
                      $1  expenses:supplies
                     $-1  income:gifts
                     $-1  income:salary
                      $1  liabilities:debts
    --------------------
                       0
    ghci>

etc.

Synopsis

- main :: IO ()
- mainmode :: [Name] -> Mode RawOpts
- argsToCliOpts :: [String] -> [String] -> IO CliOpts
- module Hledger.Cli.CliOptions
- module Hledger.Cli.Conf
- module Hledger.Cli.Commands
- module Hledger.Cli.DocFiles
- module Hledger.Cli.Utils
- module Hledger.Cli.Version
- module Hledger
- process :: Mode a -> [String] -> Either String a
- data Complete
  - = CompleteValue String
  - | CompleteFile String FilePath
  - | CompleteDir String FilePath
- data Arg a = Arg {
  - argValue :: Update a
  - argType :: FlagHelp
  - argRequire :: Bool
  }
- expandArgsAt :: [String] -> IO [String]
- joinArgs :: [String] -> String
- splitArgs :: String -> [String]
- class Remap (m :: Type -> Type) where
  - remap :: (a -> b) -> (b -> (a, a -> b)) -> m a -> m b
- data Flag a = Flag {
  - flagNames :: [Name]
  - flagInfo :: FlagInfo
  - flagValue :: Update a
  - flagType :: FlagHelp
  - flagHelp :: Help
  }
- type Update a = String -> a -> Either String a
- data FlagInfo
  - = FlagReq
  - | FlagOpt String
  - | FlagOptRare String
  - | FlagNone
- data Mode a = Mode {
  - modeGroupModes :: Group (Mode a)
  - modeNames :: [Name]
  - modeValue :: a
  - modeCheck :: a -> Either String a
  - modeReform :: a -> Maybe [String]
  - modeExpandAt :: Bool
  - modeHelp :: Help
  - modeHelpSuffix :: [String]
  - modeArgs :: ([Arg a], Maybe (Arg a))
  - modeGroupFlags :: Group (Flag a)
  }
- data Group a = Group {
  - groupUnnamed :: [a]
  - groupHidden :: [a]
  - groupNamed :: [(Help, [a])]
  }
- type FlagHelp = String
- type Help = String
- parseBool :: String -> Maybe Bool
- fromGroup :: Group a -> [a]
- toGroup :: [a] -> Group a
- modeModes :: Mode a -> [Mode a]
- modeFlags :: Mode a -> [Flag a]
- fromFlagOpt :: FlagInfo -> String
- checkMode :: Mode a -> Maybe String
- remap2 :: Remap m => (a -> b) -> (b -> a) -> m a -> m b
- remapUpdate :: (a -> b) -> (b -> (a, a -> b)) -> Update a -> Update b
- modeEmpty :: a -> Mode a
- mode :: Name -> a -> Help -> Arg a -> [Flag a] -> Mode a
- modes :: String -> a -> Help -> [Mode a] -> Mode a
- flagNone :: [Name] -> (a -> a) -> Help -> Flag a
- flagOpt :: String -> [Name] -> Update a -> FlagHelp -> Help -> Flag a
- flagReq :: [Name] -> Update a -> FlagHelp -> Help -> Flag a
- flagArg :: Update a -> FlagHelp -> Arg a
- flagBool :: [Name] -> (Bool -> a -> a) -> Help -> Flag a
- complete :: Mode a -> [String] -> (Int, Int) -> [Complete]
- data HelpFormat
  - = HelpFormatDefault
  - | HelpFormatOne
  - | HelpFormatAll
  - | HelpFormatBash
  - | HelpFormatZsh
- helpText :: [String] -> HelpFormat -> Mode a -> [Text]
- processArgs :: Mode a -> IO a
- processValue :: Mode a -> [String] -> a
- processValueIO :: Mode a -> [String] -> IO a
- flagHelpSimple :: (a -> a) -> Flag a
- flagHelpFormat :: (HelpFormat -> TextFormat -> a -> a) -> Flag a
- flagVersion :: (a -> a) -> Flag a
- flagNumericVersion :: (a -> a) -> Flag a
- flagsVerbosity :: (Verbosity -> a -> a) -> [Flag a]

# Documentation

main :: IO () #

hledger CLI's main procedure.

Here we will parse the command line, read any config file, and search for hledger-* addon executables in the user's PATH, then choose the appropriate builtin operation or addon operation to run, then run it in the right way, usually reading input data (eg a journal) first.

When making a CLI usable and robust with main command, builtin subcommands, various kinds of addon commands, and config files that add general and command-specific options, while balancing circular dependencies, environment, idioms, legacy, and libraries with their own requirements and limitations: things get crazy, and there is a tradeoff against complexity and bug risk. We try to provide the most intuitive, expressive and robust CLI that's feasible while keeping the CLI processing below sufficiently comprehensible, troubleshootable, and tested. It's an ongoing quest. See also: Hledger.Cli.CliOptions, cli.test, addons.test, --debug and --debug=8.

Probably the biggest source of complexity here is that cmdargs can't parse a command line containing undeclared flags, but this arises often with our addon commands and builtin/custom commands which haven't implemented all options, so we have to work hard to work around this. https://github.com/ndmitchell/cmdargs/issues/36 is the wishlist issue; implementing that would simplify hledger's CLI processing a lot.

mainmode :: [Name] -> Mode RawOpts #

The overall cmdargs mode describing hledger's command-line options and subcommands. The names of known addons are provided so they too can be recognised as commands.

argsToCliOpts :: [String] -> [String] -> IO CliOpts #

A helper for addons/scripts: this parses hledger CliOpts from these command line arguments and add-on command names, roughly how hledger main does. If option parsing/validating fails, it exits the program with usageError. Unlike main, this does not read extra args from a config file or search for addons; to do those things, mimic the code in main for now.

# Re-exports

module Hledger.Cli.CliOptions

module Hledger.Cli.Conf

module Hledger.Cli.Commands

module Hledger.Cli.DocFiles

module Hledger.Cli.Utils

module Hledger.Cli.Version

module Hledger

## System.Console.CmdArgs.Explicit

process :: Mode a -> [String] -> Either String a #

Process a list of flags (usually obtained from `getArgs`/`expandArgsAt`) with a mode. Returns `Left` and an error message if the command line fails to parse, or `Right` and the associated value.

data Complete #

How to complete a command line option. The `Show` instance is suitable for parsing from shell scripts.

Constructors

CompleteValue String | Complete to a particular value
CompleteFile String FilePath | Complete to a prefix, and a file
CompleteDir String FilePath | Complete to a prefix, and a directory

#### Instances

Instances details

Show Complete |
Instance details Defined in System.Console.CmdArgs.Explicit.Complete Methods showsPrec :: Int -> Complete -> ShowS # show :: Complete -> String # showList :: [Complete] -> ShowS #
Eq Complete |
Instance details Defined in System.Console.CmdArgs.Explicit.Complete Methods (==) :: Complete -> Complete -> Bool # (/=) :: Complete -> Complete -> Bool #
Ord Complete |
Instance details Defined in System.Console.CmdArgs.Explicit.Complete Methods compare :: Complete -> Complete -> Ordering # (<) :: Complete -> Complete -> Bool # (<=) :: Complete -> Complete -> Bool # (>) :: Complete -> Complete -> Bool # (>=) :: Complete -> Complete -> Bool # max :: Complete -> Complete -> Complete # min :: Complete -> Complete -> Complete #

data Arg a #

An unnamed argument. Anything not starting with `-` is considered an argument, apart from `"-"` which is considered to be the argument `"-"`, and any arguments following `"--"`. For example:

    programname arg1 -j - --foo arg3 -- -arg4 --arg5=1 arg6

Would have the arguments:

    ["arg1","-","arg3","-arg4","--arg5=1","arg6"]

Constructors

Arg |

Fields

- argValue :: Update a

  A way of processing the argument.

- argType :: FlagHelp

  The type of data for the argument, i.e. FILE/DIR/EXT

- argRequire :: Bool

  Is at least one of these arguments required, the command line will fail if none are set

#### Instances

Instances details

Remap Arg |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods remap :: (a -> b) -> (b -> (a, a -> b)) -> Arg a -> Arg b #
Packer a => Packer (Arg a) |
Instance details Defined in System.Console.CmdArgs.Helper Methods pack :: Arg a -> Pack unpack :: Pack -> Arg a

expandArgsAt :: [String] -> IO [String] #

Expand `@` directives in a list of arguments, usually obtained from `getArgs`. As an example, given the file `test.txt` with the lines `hello` and `world`:

    expandArgsAt ["@test.txt","!"] == ["hello","world","!"]

Any `@` directives in the files will be recursively expanded (raising an error if there is infinite recursion).

To supress `@` expansion, pass any `@` arguments after `--`.

joinArgs :: [String] -> String #

Given a sequence of arguments, join them together in a manner that could be used on the command line, giving preference to the Windows `cmd` shell quoting conventions.

For an alternative version, intended for actual running the result in a shell, see "System.Process.showCommandForUser"

splitArgs :: String -> [String] #

Given a string, split into the available arguments. The inverse of `joinArgs`.

class Remap (m :: Type -> Type) where #

Like functor, but where the the argument isn't just covariant.

Methods

remap #

Arguments

:: (a -> b) | Embed a value
-> (b -> (a, a -> b)) | Extract the mode and give a way of re-embedding
-> m a |
-> m b |

Convert between two values.

#### Instances

Instances details

Remap Arg |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods remap :: (a -> b) -> (b -> (a, a -> b)) -> Arg a -> Arg b #
Remap Flag |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods remap :: (a -> b) -> (b -> (a, a -> b)) -> Flag a -> Flag b #
Remap Mode |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods remap :: (a -> b) -> (b -> (a, a -> b)) -> Mode a -> Mode b #

data Flag a #

A flag, consisting of a list of flag names and other information.

Constructors

Flag |

Fields

- flagNames :: [Name]

  The names for the flag.

- flagInfo :: FlagInfo

  Information about a flag's arguments.

- flagValue :: Update a

  The way of processing a flag.

- flagType :: FlagHelp

  The type of data for the flag argument, i.e. FILE/DIR/EXT

- flagHelp :: Help

  The help message associated with this flag.

#### Instances

Instances details

Remap Flag |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods remap :: (a -> b) -> (b -> (a, a -> b)) -> Flag a -> Flag b #
Packer a => Packer (Flag a) |
Instance details Defined in System.Console.CmdArgs.Helper Methods pack :: Flag a -> Pack unpack :: Pack -> Flag a

type Update a = String -> a -> Either String a #

A function to take a string, and a value, and either produce an error message (`Left`), or a modified value (`Right`).

data FlagInfo #

The `FlagInfo` type has the following meaning:

                 FlagReq     FlagOpt      FlagOptRare/FlagNone
    -xfoo        -x=foo      -x=foo       -x -foo
    -x foo       -x=foo      -x foo       -x foo
    -x=foo       -x=foo      -x=foo       -x=foo
    --xx foo     --xx=foo    --xx foo     --xx foo
    --xx=foo     --xx=foo    --xx=foo     --xx=foo

Constructors

FlagReq | Required argument
FlagOpt String | Optional argument
FlagOptRare String | Optional argument that requires an = before the value
FlagNone | No argument

#### Instances

Instances details

Packer FlagInfo |
Instance details Defined in System.Console.CmdArgs.Helper Methods pack :: FlagInfo -> Pack unpack :: Pack -> FlagInfo
Show FlagInfo |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods showsPrec :: Int -> FlagInfo -> ShowS # show :: FlagInfo -> String # showList :: [FlagInfo] -> ShowS #
Eq FlagInfo |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods (==) :: FlagInfo -> FlagInfo -> Bool # (/=) :: FlagInfo -> FlagInfo -> Bool #
Ord FlagInfo |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods compare :: FlagInfo -> FlagInfo -> Ordering # (<) :: FlagInfo -> FlagInfo -> Bool # (<=) :: FlagInfo -> FlagInfo -> Bool # (>) :: FlagInfo -> FlagInfo -> Bool # (>=) :: FlagInfo -> FlagInfo -> Bool # max :: FlagInfo -> FlagInfo -> FlagInfo # min :: FlagInfo -> FlagInfo -> FlagInfo #

data Mode a #

A mode. Do not use the `Mode` constructor directly, instead use `mode` to construct the `Mode` and then record updates. Each mode has three main features:

- A list of submodes (`modeGroupModes`)
- A list of flags (`modeGroupFlags`)
- Optionally an unnamed argument (`modeArgs`)

To produce the help information for a mode, either use `helpText` or `show`.

Constructors

Mode |

Fields

- modeGroupModes :: Group (Mode a)

  The available sub-modes

- modeNames :: [Name]

  The names assigned to this mode (for the root mode, this name is used as the program name)

- modeValue :: a

  Value to start with

- modeCheck :: a -> Either String a

  Check the value reprsented by a mode is correct, after applying all flags

- modeReform :: a -> Maybe [String]

  Given a value, try to generate the input arguments.

- modeExpandAt :: Bool

  Expand `@` arguments with `expandArgsAt`, defaults to `True`, only applied if using an `IO` processing function. Only the root `Mode`s value will be used.

- modeHelp :: Help

  Help text

- modeHelpSuffix :: [String]

  A longer help suffix displayed after a mode

- modeArgs :: ([Arg a], Maybe (Arg a))

  The unnamed arguments, a series of arguments, followed optionally by one for all remaining slots

- modeGroupFlags :: Group (Flag a)

  Groups of flags

#### Instances

Instances details

Remap Mode |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods remap :: (a -> b) -> (b -> (a, a -> b)) -> Mode a -> Mode b #
Packer a => Packer (Mode a) |
Instance details Defined in System.Console.CmdArgs.Helper Methods pack :: Mode a -> Pack unpack :: Pack -> Mode a

data Group a #

A group of items (modes or flags). The items are treated as a list, but the group structure is used when displaying the help message.

Constructors

Group |

Fields

- groupUnnamed :: [a]

  Normal items.

- groupHidden :: [a]

  Items that are hidden (not displayed in the help message).

- groupNamed :: [(Help, [a])]

  Items that have been grouped, along with a description of each group.

#### Instances

Instances details

Functor Group |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods fmap :: (a -> b) -> Group a -> Group b # (<$) :: a -> Group b -> Group a #
Packer a => Packer (Group a) |
Instance details Defined in System.Console.CmdArgs.Helper Methods pack :: Group a -> Pack unpack :: Pack -> Group a
Monoid (Group a) |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods mempty :: Group a # mappend :: Group a -> Group a -> Group a # mconcat :: [Group a] -> Group a #
Semigroup (Group a) |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods (<>) :: Group a -> Group a -> Group a # sconcat :: NonEmpty (Group a) -> Group a # stimes :: Integral b => b -> Group a -> Group a #
Show a => Show (Group a) |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods showsPrec :: Int -> Group a -> ShowS # show :: Group a -> String # showList :: [Group a] -> ShowS #

type FlagHelp = String #

The type of a flag, i.e. `--foo=TYPE`.

type Help = String #

A help message that goes with either a flag or a mode.

parseBool :: String -> Maybe Bool #

Parse a boolean, accepts as True: true yes on enabled 1.

fromGroup :: Group a -> [a] #

Convert a group into a list.

toGroup :: [a] -> Group a #

Convert a list into a group, placing all fields in `groupUnnamed`.

modeModes :: Mode a -> [Mode a] #

Extract the modes from a `Mode`

modeFlags :: Mode a -> [Flag a] #

Extract the flags from a `Mode`

fromFlagOpt :: FlagInfo -> String #

Extract the value from inside a `FlagOpt` or `FlagOptRare`, or raises an error.

checkMode :: Mode a -> Maybe String #

Check that a mode is well formed.

remap2 :: Remap m => (a -> b) -> (b -> a) -> m a -> m b #

Restricted version of `remap` where the values are isomorphic.

remapUpdate :: (a -> b) -> (b -> (a, a -> b)) -> Update a -> Update b #

Version of `remap` for the `Update` type alias.

modeEmpty :: a -> Mode a #

Create an empty mode specifying only `modeValue`. All other fields will usually be populated using record updates.

mode :: Name -> a -> Help -> Arg a -> [Flag a] -> Mode a #

Create a mode with a name, an initial value, some help text, a way of processing arguments and a list of flags.

modes :: String -> a -> Help -> [Mode a] -> Mode a #

Create a list of modes, with a program name, an initial value, some help text and the child modes.

flagNone :: [Name] -> (a -> a) -> Help -> Flag a #

Create a flag taking no argument value, with a list of flag names, an update function and some help text.

flagOpt :: String -> [Name] -> Update a -> FlagHelp -> Help -> Flag a #

Create a flag taking an optional argument value, with an optional value, a list of flag names, an update function, the type of the argument and some help text.

flagReq :: [Name] -> Update a -> FlagHelp -> Help -> Flag a #

Create a flag taking a required argument value, with a list of flag names, an update function, the type of the argument and some help text.

flagArg :: Update a -> FlagHelp -> Arg a #

Create an argument flag, with an update function and the type of the argument.

flagBool :: [Name] -> (Bool -> a -> a) -> Help -> Flag a #

Create a boolean flag, with a list of flag names, an update function and some help text.

complete #

Arguments

:: Mode a | Mode specifying which arguments are allowed
-> [String] | Arguments the user has already typed
-> (Int, Int) | 0-based index of the argument they are currently on, and the position in that argument
-> [Complete] |

Given a current state, return the set of commands you could type now, in preference order.

data HelpFormat #

Specify the format to output the help.

Constructors

HelpFormatDefault | Equivalent to `HelpFormatAll` if there is not too much text, otherwise `HelpFormatOne`.
HelpFormatOne | Display only the first mode.
HelpFormatAll | Display all modes.
HelpFormatBash | Bash completion information
HelpFormatZsh | Z shell completion information

#### Instances

Instances details

Default HelpFormat |
Instance details Defined in System.Console.CmdArgs.Explicit.Help Methods def :: HelpFormat #
Bounded HelpFormat |
Instance details Defined in System.Console.CmdArgs.Explicit.Help Methods minBound :: HelpFormat # maxBound :: HelpFormat #
Enum HelpFormat |

Instance details

Defined in System.Console.CmdArgs.Explicit.Help

Methods

succ :: HelpFormat -> HelpFormat #

pred :: HelpFormat -> HelpFormat #

toEnum :: Int -> HelpFormat #

fromEnum :: HelpFormat -> Int #

enumFrom :: HelpFormat -> [HelpFormat] #

enumFromThen :: HelpFormat -> HelpFormat -> [HelpFormat] #

enumFromTo :: HelpFormat -> HelpFormat -> [HelpFormat] #

enumFromThenTo :: HelpFormat -> HelpFormat -> HelpFormat -> [HelpFormat] #

Read HelpFormat |
Instance details Defined in System.Console.CmdArgs.Explicit.Help Methods readsPrec :: Int -> ReadS HelpFormat # readList :: ReadS [HelpFormat] # readPrec :: ReadPrec HelpFormat # readListPrec :: ReadPrec [HelpFormat] #
Show HelpFormat |
Instance details Defined in System.Console.CmdArgs.Explicit.Help Methods showsPrec :: Int -> HelpFormat -> ShowS # show :: HelpFormat -> String # showList :: [HelpFormat] -> ShowS #
Eq HelpFormat |
Instance details Defined in System.Console.CmdArgs.Explicit.Help Methods (==) :: HelpFormat -> HelpFormat -> Bool # (/=) :: HelpFormat -> HelpFormat -> Bool #
Ord HelpFormat |
Instance details Defined in System.Console.CmdArgs.Explicit.Help Methods compare :: HelpFormat -> HelpFormat -> Ordering # (<) :: HelpFormat -> HelpFormat -> Bool # (<=) :: HelpFormat -> HelpFormat -> Bool # (>) :: HelpFormat -> HelpFormat -> Bool # (>=) :: HelpFormat -> HelpFormat -> Bool # max :: HelpFormat -> HelpFormat -> HelpFormat # min :: HelpFormat -> HelpFormat -> HelpFormat #

helpText :: [String] -> HelpFormat -> Mode a -> [Text] #

Generate a help message from a mode. The first argument is a prefix, which is prepended when not using `HelpFormatBash` or `HelpFormatZsh`.

processArgs :: Mode a -> IO a #

Process the flags obtained by ``getArgs`` and ``expandArgsAt`` with a mode. Displays an error and exits with failure if the command line fails to parse, or returns the associated value. Implemented in terms of `process`. This function makes use of the following environment variables:

- `$CMDARGS_COMPLETE` - causes the program to produce completions using `complete`, then exit. Completions are based on the result of `getArgs`, the index of the current argument is taken from `$CMDARGS_COMPLETE` (set it to `-` to complete the last argument), and the index within that argument is taken from `$CMDARGS_COMPLETE_POS` (if set).
- `$CMDARGS_HELPER`/`$CMDARGS_HELPER_PROG` - uses the helper mechanism for entering command line programs as described in System.Console.CmdArgs.Helper.

processValue :: Mode a -> [String] -> a #

Process a list of flags (usually obtained from ``getArgs`` and ``expandArgsAt``) with a mode. Throws an error if the command line fails to parse, or returns the associated value. Implemeneted in terms of `process`. This function does not take account of any environment variables that may be set (see `processArgs`).

If you are in `IO` you will probably get a better user experience by calling `processValueIO`.

processValueIO :: Mode a -> [String] -> IO a #

Like `processValue` but on failure prints to stderr and exits the program.

flagHelpSimple :: (a -> a) -> Flag a #

Create a help flag triggered by `-?`/`--help`.

flagHelpFormat :: (HelpFormat -> TextFormat -> a -> a) -> Flag a #

Create a help flag triggered by `-?`/`--help`. The user may optionally modify help by specifying the format, such as:

    --help=all          - help for all modes
    --help=html         - help in HTML format
    --help=100          - wrap the text at 100 characters
    --help=100,one      - full text wrapped at 100 characters

flagVersion :: (a -> a) -> Flag a #

Create a version flag triggered by `-V`/`--version`.

flagNumericVersion :: (a -> a) -> Flag a #

Create a version flag triggered by `--numeric-version`.

flagsVerbosity :: (Verbosity -> a -> a) -> [Flag a] #

Create verbosity flags triggered by `-v`/`--verbose` and `-q`/`--quiet`