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


-- | Interprets the command line and 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 "actions" (commands, or modes of operation,
--   of the program);</li>
--   <li>declare options of the program;</li>
--   <li>collect options and actions from a configuration file and the
--   command line, and execute the proper action.</li>
--   </ul>
--   
--   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 "modes", 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.2.0.1

module System.Console.Argument

-- | 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.
--   
--   Note that this may be different from the corresponding value in the
--   default configuration (the first argument of
--   <tt>System.Console.Command.execute</tt>); the latter is what you get
--   when this option does not occur at all in the configuration file or
--   command line.
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".
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

-- | Create an option description. You need this to describe the options
--   your command uses; see <tt>System.Console.Command.Command</tt>.
option :: (a -> s) -> [Char] -> [String] -> Type a -> String -> OptDescr (Either String s)
instance Functor Type


-- | This module defines a class for dealing with configurations and
--   settings. It also exports a Template Haskell function to easily create
--   datatypes to deal with the configuration of your program.
--   
--   For an example using this module, see the file "Examples/Options.hs"
--   in the package tarball.
module System.Console.Options

-- | An instance <tt>c</tt> of <a>Configuration</a> has as values complete
--   configurations, as the program peruses. <tt><a>Setting</a> s</tt> is
--   the associated type of a single setting, or option assignments, as
--   given by the user in a configuration file or command line options.
class Configuration c where { type family Setting c; }
set :: Configuration c => Setting c -> c -> c
apply :: Configuration c => [Setting c] -> c -> c

-- | <a>create</a> is a template haskell computation. Given names for the
--   "configuration" type and the "settings" type, and a list of settings
--   (pairs of their names and types), it creates those datatypes, and an
--   instance of the <a>Configuration</a> class.
create :: String -> String -> [(String, Type)] -> Q [Dec]
data Type :: *

-- | <pre>
--   T
--   </pre>
ConT :: Name -> Type
instance Configuration ()

module System.Console.Action

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

-- | A simple action, taking no argument.
simple :: IO () -> Action c

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

-- | Create an action that depends on the program configuration (determined
--   by the configuration file and command line arguments).
usingConfiguration :: (c -> Action c) -> Action c


-- | This is the main module of console-program. You can use it to build a
--   console program, that parses the command line (and a configuration
--   file), divides it into modes/commands, options and non-options, and
--   executes the corresponding action from a tree of commands.
--   
--   The main function is <a>execute</a>; provided with a tree of commands
--   and a default configuration, it can be used as the <tt>main</tt>
--   function.
--   
--   A "mode" or "command" provides a mode of operation of your program.
--   This allows a single executable 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 that make
--   heavy use of modes.)
--   
--   Options can be given in a configuration file, and on the command line.
--   Commands specify which options apply to them (the
--   <a>applicableOptions</a> field). Such option descriptions can be
--   created by <tt>System.Console.Argument.option</tt>.
--   
--   Options can have arguments, as in <tt>program --option=value</tt>,
--   where <tt>value</tt> is the argument to <tt>option</tt>. These
--   arguments have types, dictated by the particular option. These types
--   are represented by a <tt>System.Console.Argument.Type</tt>.
--   
--   A command can have also non-option arguments (plain arguments). These
--   also have types. Create such commands using the function
--   <tt>System.Console.Action.withArgument</tt>.
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 setting = Tree (Command setting)

-- | A <tt>Command s</tt> is an action, together with some descriptive
--   information. The description, and lists of applicable options and
--   non-options are used only to show usage information for the command.
--   <tt>s</tt> is the type of settings that the action may use.
data Command c
Command :: String -> [String] -> [OptDescr (Either String (Setting c))] -> String -> Action c -> Command c

-- | This determines which command is executed, depending on the command
--   line.
name :: Command c -> String

-- | For usage info.
applicableNonOptions :: Command c -> [String]

-- | For usage info; also, the union of this field, over all commands in
--   the command tree, determines which options will be recognised when
--   parsing the configuration file and command line.
applicableOptions :: Command c -> [OptDescr (Either String (Setting c))]

-- | For usage info.
description :: Command c -> String
action :: Command c -> Action c

-- | Load the configuration file (if present), and run the action given on
--   the command line. You may use this function, with appropriate
--   arguments, as your <tt>main</tt> function.
--   
--   Settings in the configuration file override the default configuration;
--   settings on the command line override both.
execute :: Configuration c => c -> Commands c -> IO ()

-- | Print usage info for the program to stdout.
showUsage :: Commands c -> IO ()
instance Ord (OptDescr a)
instance Eq (OptDescr a)