-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Interpret the command line and 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:
--   
--   <ul>
--   <li>console-program does not use unsafePerformIO, and tries to give a
--   more haskellish, referentially transparent interface;</li>
--   <li>it allows a full tree of commands, instead of a list, so a command
--   can have subcommands;</li>
--   <li>it parses a configuration file, in addition to the command line
--   arguments.</li>
--   </ul>
@package console-program
@version 0.4.2.3


-- | This module contains functions to create option descriptions, together
--   with their argument types.
module System.Console.Argument

-- | A value of type <tt>Option a</tt> describes an option, that delivers a
--   value to the program of type <tt>a</tt>.
data Option a

-- | Create an option description.
--   
--   Options can have arguments, as in <tt>myprogram --foo=bar</tt>, where
--   <tt>bar</tt> is the argument to <tt>foo</tt>. These arguments have
--   types, dictated by the particular option; this type is the third
--   parameter to <tt>option</tt>.
option :: [Char] -> [String] -> Type a -> a -> String -> Option a

-- | A <tt>Type a</tt> 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 (<tt>Right</tt>) or signal a
--   parsing error (<tt>Left</tt>).
[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.
--   <tt>Nothing</tt> 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 <a>Command</a> 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.
--   (<tt>darcs</tt> and <tt>cabal</tt> are examples of programs with this
--   behaviour.)
--   
--   An <a>Action</a> represents an IO action, together with information
--   about applicable options and non-option arguments.
module System.Console.Command

-- | <tt>Commands m</tt> is a tree of commands (with action in the monad
--   <tt>m</tt>). It represents the whole set of possible commands of a
--   program.
type Commands m = Tree (Command m)

-- | Non-empty, possibly infinite, multi-way trees; also known as <i>rose
--   trees</i>.
data Tree a
Node :: a -> Forest a -> Tree a

-- | A <tt>Command m</tt> is an action (in the monad <tt>m</tt>), 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 <tt>Action m</tt> is an action (in the monad <tt>m</tt>), 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 <a>System.Console.Argument</a>.
withNonOption :: MonadIO m => Type x -> (x -> Action m) -> Action m

-- | Create an action that takes all remaining non-option arguments.
--   
--   The type of arguments is specified by the first parameter; such values
--   can be obtained from the module <a>System.Console.Argument</a>.
withNonOptions :: 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 <a>option</a>.
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
--   <a>System.Console.Command</a>.
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 <tt>main</tt> 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 ()

-- | Same as <a>interactive</a>, but with a custom monadic function
--   specifying the text of the prompt.
interactiveWithPrompt :: (MonadIO m, MonadException m, Applicative m) => m String -> Commands m -> m ()

-- | Print usage info for the program to stdout.
showUsage :: MonadIO m => Commands n -> m ()