hledger-1.32.3: Command-line interface for the hledger accounting system
Safe HaskellSafe-Inferred
LanguageHaskell2010

Hledger.Cli

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:

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

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

System.Console.CmdArgs.Explicit

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

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

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

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:

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

Constructors

Mode 

Fields

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

Enum HelpFormat 
Instance details

Defined in System.Console.CmdArgs.Explicit.Help

Read HelpFormat 
Instance details

Defined in System.Console.CmdArgs.Explicit.Help

Show HelpFormat 
Instance details

Defined in System.Console.CmdArgs.Explicit.Help

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

Ord HelpFormat 
Instance details

Defined in System.Console.CmdArgs.Explicit.Help

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