Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
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
- flagsVerbosity :: (Verbosity -> a -> a) -> [Flag a]
- flagNumericVersion :: (a -> a) -> Flag a
- flagVersion :: (a -> a) -> Flag a
- flagHelpFormat :: (HelpFormat -> TextFormat -> a -> a) -> Flag a
- flagHelpSimple :: (a -> a) -> Flag a
- processValueIO :: Mode a -> [String] -> IO a
- processValue :: Mode a -> [String] -> a
- processArgs :: Mode a -> IO a
- helpText :: [String] -> HelpFormat -> Mode a -> [Text]
- data HelpFormat
- complete :: Mode a -> [String] -> (Int, Int) -> [Complete]
- data Complete
- process :: Mode a -> [String] -> Either String a
- flagBool :: [Name] -> (Bool -> a -> a) -> Help -> Flag a
- flagArg :: Update a -> FlagHelp -> Arg a
- flagReq :: [Name] -> Update a -> FlagHelp -> Help -> Flag a
- flagOpt :: String -> [Name] -> Update a -> FlagHelp -> Help -> Flag a
- flagNone :: [Name] -> (a -> a) -> Help -> Flag a
- modes :: String -> a -> Help -> [Mode a] -> Mode a
- mode :: Name -> a -> Help -> Arg a -> [Flag a] -> Mode a
- modeEmpty :: a -> Mode a
- remapUpdate :: (a -> b) -> (b -> (a, a -> b)) -> Update a -> Update b
- remap2 :: Remap m => (a -> b) -> (b -> a) -> m a -> m b
- checkMode :: Mode a -> Maybe String
- fromFlagOpt :: FlagInfo -> String
- modeFlags :: Mode a -> [Flag a]
- modeModes :: Mode a -> [Mode a]
- toGroup :: [a] -> Group a
- fromGroup :: Group a -> [a]
- parseBool :: String -> Maybe Bool
- type Help = String
- type FlagHelp = String
- data Group a = Group {
- groupUnnamed :: [a]
- groupHidden :: [a]
- groupNamed :: [(Help, [a])]
- 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 FlagInfo
- type Update a = String -> a -> Either String a
- data Flag a = Flag {}
- data Arg a = Arg {}
- class Remap (m :: TYPE LiftedRep -> Type) where
- remap :: (a -> b) -> (b -> (a, a -> b)) -> m a -> m b
- splitArgs :: String -> [String]
- joinArgs :: [String] -> String
- expandArgsAt :: [String] -> IO [String]
- 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
flagsVerbosity :: (Verbosity -> a -> a) -> [Flag a] #
Create verbosity flags triggered by -v
/--verbose
and
-q
/--quiet
flagNumericVersion :: (a -> a) -> Flag a #
Create a version flag triggered by --numeric-version
.
flagVersion :: (a -> a) -> Flag a #
Create a version flag triggered by -V
/--version
.
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
flagHelpSimple :: (a -> a) -> Flag a #
Create a help flag triggered by -?
/--help
.
processValueIO :: Mode a -> [String] -> IO a #
Like processValue
but on failure prints to stderr and exits the program.
processValue :: Mode a -> [String] -> a #
Process a list of flags (usually obtained from
and getArgs
) with a mode.
Throws an error if the command line fails to parse, or returns
the associated value. Implemeneted in terms of expandArgsAt
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
.
processArgs :: Mode a -> IO a #
Process the flags obtained by
and getArgs
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 expandArgsAt
process
. This function makes
use of the following environment variables:
$CMDARGS_COMPLETE
- causes the program to produce completions usingcomplete
, then exit. Completions are based on the result ofgetArgs
, 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.
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
.
data HelpFormat #
Specify the format to output the help.
HelpFormatDefault | Equivalent to |
HelpFormatOne | Display only the first mode. |
HelpFormatAll | Display all modes. |
HelpFormatBash | Bash completion information |
HelpFormatZsh | Z shell completion information |
Instances
:: 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.
How to complete a command line option.
The Show
instance is suitable for parsing from shell scripts.
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 |
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.
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.
flagArg :: Update a -> FlagHelp -> Arg a #
Create an argument flag, with an update function and the type of the argument.
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.
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.
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.
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.
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.
Create an empty mode specifying only modeValue
. All other fields will usually be populated
using record updates.
remapUpdate :: (a -> b) -> (b -> (a, a -> b)) -> Update a -> Update b #
remap2 :: Remap m => (a -> b) -> (b -> a) -> m a -> m b #
Restricted version of remap
where the values are isomorphic.
fromFlagOpt :: FlagInfo -> String #
Extract the value from inside a FlagOpt
or FlagOptRare
, or raises an error.
Convert a list into a group, placing all fields in groupUnnamed
.
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.
Group | |
|
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
.
Mode | |
|
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
FlagReq | Required argument |
FlagOpt String | Optional argument |
FlagOptRare String | Optional argument that requires an = before the value |
FlagNone | No argument |
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
).
A flag, consisting of a list of flag names and other information.
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"]
class Remap (m :: TYPE LiftedRep -> Type) where #
Like functor, but where the the argument isn't just covariant.
:: (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
Remap Arg | |
Defined in System.Console.CmdArgs.Explicit.Type | |
Remap Flag | |
Defined in System.Console.CmdArgs.Explicit.Type | |
Remap Mode | |
Defined in System.Console.CmdArgs.Explicit.Type |
splitArgs :: String -> [String] #
Given a string, split into the available arguments. The inverse of joinArgs
.
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"
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 --
.
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.