-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Interpret the command line and settings in a config file as commands and options -- -- This library provides a framework to build command line programs. -- -- The constructed program can have several "commands" that provide -- different modes of operation. Options can be declared to allow -- fine-tuning of the behaviour of the program. These options are read -- from the command line when running the program and from a simple -- configuration file. -- -- Additionally, there is an interactive mode that reads and executes -- commands from standard input. -- -- Examples of using this library may be found in the Examples directory -- in the package tarball. -- -- It provides functionality similar to the cmdargs package. Main -- differences: -- -- @package console-program @version 0.4.0.2 -- | This module contains functions to create option descriptions, together -- with their argument types. module System.Console.Argument -- | A value of type Option a describes an option, that delivers a -- value to the program of type a. data Option a -- | Create an option description. -- -- Options can have arguments, as in myprogram --foo=bar, where -- bar is the argument to foo. These arguments have -- types, dictated by the particular option; this type is the third -- parameter to option. option :: [Char] -> [String] -> Type a -> a -> String -> Option a -- | A Type a represents the type of an option or argument. -- -- Further below you can find some common types of option arguments. data Type a Type :: (String -> Either String a) -> String -> Maybe a -> Type a -- | Parse the option argument into a value (Right) or signal a -- parsing error (Left). [parser] :: Type a -> String -> Either String a -- | A name for this type of option argument (for usage info). [name] :: Type a -> String -- | The default value when the option occurs without option argument. -- Nothing means that an argument is required for this type of -- option. [defaultValue] :: Type a -> Maybe a optional :: a -> Type a -> Type a -- | A plain string. string :: Type String -- | A boolean. Argument can be -- "1","0","true","false","on","off","yes","no". boolean :: Type Bool -- | A directory path. A trailing slash is stripped, if present. directory :: Type FilePath -- | A file path. file :: Type FilePath -- | A device path. device :: Type FilePath -- | A natural number (in decimal). natural :: Type Integer -- | An integer number (in decimal). integer :: Type Integer instance GHC.Base.Functor System.Console.Argument.Type -- | A Command provides a mode of operation of your program. This -- allows a single program to provide many different pieces of -- functionality. The first argument to the program (or the first few, if -- it has subcommands) determines which command should be executed. -- (darcs and cabal are examples of programs with this -- behaviour.) -- -- An Action represents an IO action, together with information -- about applicable options and non-option arguments. module System.Console.Command -- | Commands m is a tree of commands (with action in the monad -- m). It represents the whole set of possible commands of a -- program. type Commands m = Tree (Command m) -- | Multi-way trees, also known as rose trees. data Tree a :: * -> * Node :: a -> Forest a -> Tree a -- | A Command m is an action (in the monad m), together -- with some descriptive information. data Command m Command :: String -> String -> Action m -> Bool -> Command m -- | This determines which command is executed. [name] :: Command m -> String -- | For usage info. [description] :: Command m -> String -- | The actual action performed by this command. [action] :: Command m -> Action m -- | Prefer shortened subcommands over non-option arguments. [shorten] :: Command m -> Bool -- | Create a new command having a given name and action. command :: String -> String -> Action m -> Command m -- | An Action m is an action (in the monad m), which may -- take arguments ("non-options") and options from the command line. data Action m -- | A simple action, taking no argument, and having no options. io :: (MonadIO m) => m () -> Action m -- | Create an action that takes an argument (non-option). -- -- The type of argument is specified by the first parameter; such values -- can be obtained from the module System.Console.Argument. withNonOption :: (MonadIO m) => Type x -> (x -> Action m) -> Action m -- | Create an action that takes an option. -- -- The first parameter is a description of the option; such a value can -- be constructed using option. withOption :: (MonadIO m) => Option a -> (a -> Action m) -> Action m -- | Create an action that allows, but ignores, the given option. -- -- This is especially useful if this option is given in the configuration -- file, but is meant for other commands; then this action will not give -- an error message about an unrecognised option. ignoreOption :: Option a -> Action m -> Action m -- | This module contains functions to build a console program, that parses -- the command line (and a configuration file), divides it into commands, -- options and non-options, and executes the corresponding action from a -- tree of available commands. -- -- These commands can be constructed using the module -- System.Console.Command. module System.Console.Program -- | Load the configuration file (if present), and run the command given on -- the command line. Settings on the command line override the -- configuration file. -- -- You may use this function, applied to your tree of available commands, -- as your main function. single :: (MonadIO m, Applicative m) => Commands m -> m () -- | Start an interactive session. Arguments to the program are ignored; -- instead, the user may repeatedly enter a command, possibly with -- options, which will be executed. interactive :: (MonadIO m, MonadException m, Applicative m) => Commands m -> m () -- | Print usage info for the program to stdout. showUsage :: (MonadIO m) => Commands n -> m ()