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


-- | An interface for describing and executing terminal applications
--   
--   A quick and modular way to construct terminal interfaces.
@package quickterm
@version 0.1.0.0

module Quickterm

-- | In general, the applications I use have two sorts of endpoints:
--   
--   1) The application has a main command which takes arguments and
--   options and performs basically the same behavior, with some variation,
--   based on these inputs.
--   
--   2) The application has a variety of sub-modules which have their own
--   pretty unique functionality and usage. I prefer these for two reasons:
--   The first is that, as the user, it separates the learning curve for
--   one aspect of the program from some other one. The second is that it
--   allows me as the developer of such software to truly make modular
--   systems and plug them in and unplug them as I wish.
--   
--   As I like this and I am developing this, I will then focus my efforts
--   as such. We shall call a program which contain submodules a Choice,
--   whereas we shall call a program which is simply a command to be run a
--   Command.
--   
--   A Choice should simply have a Name, a list of Quickterms, and a
--   description of its Usage.
--   
--   A Command may simply have a Name, a TerminalAction, and a description
--   of its Usage.
data Quickterm
Choice :: Name -> [Quickterm] -> Usage -> Quickterm
Command :: Name -> TerminalAction -> Usage -> Quickterm

-- | The options, on the other hand, tend to be a mapping from some set of
--   names to some string.
type Options = Map Name [String]

-- | I tend to call my applications by some name
type Name = String

-- | The sorts of actions which take place on the terminal are of the form
--   "cmd {<a>arg</a> | ("--" | "-") <a>opt-name</a> <a>opt-val</a>}". The
--   arguments are, in general, sequentially ordered.
type Args = [String]

-- | This function will generate the usage information and will be exposed
--   at the top level.
usage :: Quickterm -> [Char]

-- | The terminal action itself should take some arguments, some options,
--   and be able to produce some IO action dependent based on these. The
--   key here is that the TerminalAction is a pure function, taking pure
--   values and deterministically attempting some IO action based on these.
--   This is important to me in terms of designing and using programs.
type TerminalAction = Args -> Options -> IO ()

-- | This is a function which will take a top level program and attempt to
--   run it, printing out the usage information for the deepest Choice
--   achieved if the attempt is failed, i.e we did not find a Command to
--   run at all.
quickrun :: [String] -> Quickterm -> IO ()