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

Safe Haskell | Safe-Inferred
Language | Haskell2010

Hledger.Cli

Description

Hledger.Cli re-exports the options, utilities and commands provided by the hledger command-line program. This module also aggregates the built-in unit tests defined throughout hledger and hledger-lib, and adds some more which are easier to define here.

Synopsis

- module Hledger.Cli.CliOptions
- module Hledger.Cli.Commands
- module Hledger.Cli.DocFiles
- module Hledger.Cli.Utils
- module Hledger.Cli.Version
- module Hledger
- data Complete
  - = CompleteValue String
  - | CompleteFile String FilePath
  - | CompleteDir String FilePath
- 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 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]
- prognameandversion :: String
- versionString :: ProgramName -> PackageVersion -> String

# Documentation

module Hledger.Cli.CliOptions

module Hledger.Cli.Commands

module Hledger.Cli.DocFiles

module Hledger.Cli.Utils

module Hledger.Cli.Version

module Hledger

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 #

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 #

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

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 #

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

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

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
Default HelpFormat |
Instance details Defined in System.Console.CmdArgs.Explicit.Help Methods def :: HelpFormat #
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 #

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.

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

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.

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`

prognameandversion :: String #

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 #

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.