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


-- | Interpret the command line and contents of a config file as commands and options
--   
--   This library provides an infrastructure to build command line
--   programs. It provides the following features:
--   
--   <ul>
--   <li>declare any number of "commands" (modes of operation) of the
--   program;</li>
--   <li>declare options of these commands;</li>
--   <li>collect options from a configuration file and the command line,
--   and execute the proper command.</li>
--   </ul>
--   
--   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.3.1.4


-- | 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 Functor 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 s</tt> is a tree of commands. It represents the whole set
--   of possible commands of a program.
type Commands = Tree Command

-- | Multi-way trees, also known as <i>rose trees</i>.
data Tree a :: * -> *
Node :: a -> Forest a -> Tree a

-- | A <tt>Command</tt> is an action, together with some descriptive
--   information.
data Command
Command :: String -> String -> Action -> Command

-- | This determines which command is executed.
name :: Command -> String

-- | For usage info.
description :: Command -> String

-- | The actual action performed by this command.
action :: Command -> Action

-- | An <tt>Action</tt> is an <tt>IO</tt> action, which may take arguments
--   ("non-options") and options from the command line.
data Action

-- | A simple action, taking no argument, and having no options.
io :: IO () -> Action

-- | 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 :: Type x -> (x -> Action) -> Action

-- | 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 :: Option a -> (a -> Action) -> Action

-- | 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 -> Action


-- | 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 :: Commands -> IO ()

-- | 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 :: Commands -> IO ()

-- | Print usage info for the program to stdout.
showUsage :: Commands -> IO ()