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

Safe Haskell | Safe-Inferred
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-2023 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

- prognameandversion :: String
- versionString :: ProgramName -> PackageVersion -> String
- main :: IO ()
- mainmode :: [Name] -> Mode RawOpts
- argsToCliOpts :: [String] -> [String] -> IO CliOpts
- module Hledger.Cli.CliOptions
- module Hledger.Cli.Commands
- module Hledger.Cli.DocFiles
- module Hledger.Cli.Utils
- module Hledger.Cli.Version
- module Hledger
- data Arg a = Arg {
  - argValue :: Update a
  - argType :: FlagHelp
  - argRequire :: Bool
  }
- 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
- data Complete
  - = CompleteValue String
  - | CompleteFile String FilePath
  - | CompleteDir String FilePath
- data HelpFormat
  - = HelpFormatDefault
  - | HelpFormatOne
  - | HelpFormatAll
  - | HelpFormatBash
  - | HelpFormatZsh
- process :: Mode a -> [String] -> Either String a
- expandArgsAt :: [String] -> IO [String]
- joinArgs :: [String] -> String
- splitArgs :: String -> [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]
- 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

prognameandversion :: String Source #

The program name and version string for this build of the hledger tool, including any git info available at build time.

versionString :: ProgramName -> PackageVersion -> String Source #

A helper to generate the best version string we can from the given program name and package version strings, current os and architecture, and any git info available at build time (commit hash, commit date, branch name, patchlevel since latest release tag for that program's package). Typically called for programs "hledger", "hledger-ui", or "hledger-web".

The git info changes whenever any file in the repository changes. Keeping this template haskell call here and not down in Hledger.Cli.Version helps reduce the number of modules recompiled.

main :: IO () Source #

Let's go!

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

The overall cmdargs mode describing hledger's command-line options and subcommands.

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

Parse hledger CLI options from these command line arguments and add-on command names, or raise any error.

# Re-exports

module Hledger.Cli.CliOptions

module Hledger.Cli.Commands

module Hledger.Cli.DocFiles

module Hledger.Cli.Utils

module Hledger.Cli.Version

module Hledger

## System.Console.CmdArgs.Explicit

data Arg a Source #

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 Source #

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

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

Methods

remap Source #

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 Source #
Remap Flag |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods remap :: (a -> b) -> (b -> (a, a -> b)) -> Flag a -> Flag b Source #
Remap Mode |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods remap :: (a -> b) -> (b -> (a, a -> b)) -> Mode a -> Mode b Source #

data Flag a Source #

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 Source #

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

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

data FlagInfo Source #

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

Show FlagInfo |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods showsPrec :: Int -> FlagInfo -> ShowS Source # show :: FlagInfo -> String Source # showList :: [FlagInfo] -> ShowS Source #
Eq FlagInfo |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods (==) :: FlagInfo -> FlagInfo -> Bool Source # (/=) :: FlagInfo -> FlagInfo -> Bool Source #
Ord FlagInfo |

Instance details

Defined in System.Console.CmdArgs.Explicit.Type

Methods

compare :: FlagInfo -> FlagInfo -> Ordering Source #

(<) :: FlagInfo -> FlagInfo -> Bool Source #

(<=) :: FlagInfo -> FlagInfo -> Bool Source #

(>) :: FlagInfo -> FlagInfo -> Bool Source #

(>=) :: FlagInfo -> FlagInfo -> Bool Source #

max :: FlagInfo -> FlagInfo -> FlagInfo Source #

min :: FlagInfo -> FlagInfo -> FlagInfo Source #

data Mode a Source #

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 Source #

data Group a Source #

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 Source # (<$) :: a -> Group b -> Group a Source #
Monoid (Group a) |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods mempty :: Group a Source # mappend :: Group a -> Group a -> Group a Source # mconcat :: [Group a] -> Group a Source #
Semigroup (Group a) |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods (<>) :: Group a -> Group a -> Group a Source # sconcat :: NonEmpty (Group a) -> Group a Source # stimes :: Integral b => b -> Group a -> Group a Source #
Show a => Show (Group a) |
Instance details Defined in System.Console.CmdArgs.Explicit.Type Methods showsPrec :: Int -> Group a -> ShowS Source # show :: Group a -> String Source # showList :: [Group a] -> ShowS Source #

type FlagHelp = String Source #

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

type Help = String Source #

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

data Complete Source #

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 Source # show :: Complete -> String Source # showList :: [Complete] -> ShowS Source #
Eq Complete |
Instance details Defined in System.Console.CmdArgs.Explicit.Complete Methods (==) :: Complete -> Complete -> Bool Source # (/=) :: Complete -> Complete -> Bool Source #
Ord Complete |

Instance details

Defined in System.Console.CmdArgs.Explicit.Complete

Methods

compare :: Complete -> Complete -> Ordering Source #

(<) :: Complete -> Complete -> Bool Source #

(<=) :: Complete -> Complete -> Bool Source #

(>) :: Complete -> Complete -> Bool Source #

(>=) :: Complete -> Complete -> Bool Source #

max :: Complete -> Complete -> Complete Source #

min :: Complete -> Complete -> Complete Source #

data HelpFormat Source #

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

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

Instance details

Defined in System.Console.CmdArgs.Explicit.Help

Methods

succ :: HelpFormat -> HelpFormat Source #

pred :: HelpFormat -> HelpFormat Source #

toEnum :: Int -> HelpFormat Source #

fromEnum :: HelpFormat -> Int Source #

enumFrom :: HelpFormat -> [HelpFormat] Source #

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

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

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

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

Instance details

Defined in System.Console.CmdArgs.Explicit.Help

Methods

compare :: HelpFormat -> HelpFormat -> Ordering Source #

(<) :: HelpFormat -> HelpFormat -> Bool Source #

(<=) :: HelpFormat -> HelpFormat -> Bool Source #

(>) :: HelpFormat -> HelpFormat -> Bool Source #

(>=) :: HelpFormat -> HelpFormat -> Bool Source #

max :: HelpFormat -> HelpFormat -> HelpFormat Source #

min :: HelpFormat -> HelpFormat -> HelpFormat Source #

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

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.

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

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 Source #

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] Source #

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

parseBool :: String -> Maybe Bool Source #

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

fromGroup :: Group a -> [a] Source #

Convert a group into a list.

toGroup :: [a] -> Group a Source #

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

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

Extract the modes from a `Mode`

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

Extract the flags from a `Mode`

fromFlagOpt :: FlagInfo -> String Source #

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

checkMode :: Mode a -> Maybe String Source #

Check that a mode is well formed.

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

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

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

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

modeEmpty :: a -> Mode a Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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

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

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

complete Source #

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.

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

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 Source #

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 Source #

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 Source #

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

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

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

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

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 Source #

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

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

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

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

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