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


-- | A command line argument/option parser library built around a monadic metaphor
--   
--   A command line argument/option parser library built around a monadic
--   metaphor.
@package commander-cli
@version 0.7.0.0


module Control.Monad.Commander

-- | A <a>CommanderT</a> action is a metaphor for a military commander. At
--   each step, we have a new <a>Action</a> to take, or we could have
--   experienced <a>Defeat</a>, or we can see <a>Victory</a>. While a real
--   life commander worries about moving his troops around in order to
--   achieve a victory in battle, a <a>CommanderT</a> worries about
--   iteratively transforming a state to find some value. We will deal with
--   the subset of these actions where every function must decrease the
--   size of the state, as those are the actions for which this is a monad.
data CommanderT state m a
Action :: (state -> m (CommanderT state m a, state)) -> CommanderT state m a
Defeat :: CommanderT state m a
Victory :: a -> CommanderT state m a

-- | We can run a <a>CommanderT</a> action on a state and see if it has a
--   successful campaign.
runCommanderT :: Monad m => CommanderT state m a -> state -> m (Maybe a)
instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.Commander.CommanderT state m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Control.Monad.Commander.CommanderT state m)
instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.Commander.CommanderT state)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Commander.CommanderT state m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Commander.CommanderT state m)
instance GHC.Base.Monad m => GHC.Base.Alternative (Control.Monad.Commander.CommanderT state m)


-- | Commander is an embedded domain specific language describing a command
--   line interface, along with ways to run those as real programs. An
--   complete example of such a command line interface is:
--   
--   <pre>
--   main :: IO ()
--   main = command_ . toplevel <tt>"file" $
--    (sub </tt>"maybe-read" $
--     arg <tt>"filename" filename -&gt;
--     flag </tt>"read" b -&gt; raw $
--       if b
--         then putStrLn =&lt;&lt; readFile filename
--         else pure ())
--     &lt;+&gt;
--    (sub <tt>"maybe-write" $
--     opt </tt>"file" @"file-to-write" mfilename -&gt; raw $
--       case mfilename of
--         Just filename -&gt; putStrLn =&lt;&lt; readFile filename
--         Nothing -&gt; pure ())
--   </pre>
--   
--   If I run this program with the argument help, it will output:
--   
--   <pre>
--   usage:
--   file help
--   file maybe-read &lt;filename :: String&gt; ~read
--   file maybe-write -file &lt;file-to-write :: String&gt;
--   </pre>
--   
--   The point of this library is mainly so that you can write command line
--   interfaces quickly and easily, with somewhat useful help messages, and
--   not have to write any boilerplate.
module Options.Commander

-- | A class for interpreting command line arguments into Haskell types.
class Typeable t => Unrender t
unrender :: Unrender t => Text -> Maybe t

-- | Environment
--   
--   Argument combinator
arg :: KnownSymbol name => (x -> ProgramT p m a) -> ProgramT (Arg name x & p) m a

-- | Option combinator
opt :: (KnownSymbol option, KnownSymbol name) => (Maybe x -> ProgramT p m a) -> ProgramT (Opt option name x & p) m a

-- | Option combinator with default
optDef :: (KnownSymbol option, KnownSymbol name) => x -> (x -> ProgramT p m a) -> ProgramT (Opt option name x & p) m a

-- | Raw monadic combinator
raw :: m a -> ProgramT Raw m a

-- | Subcommand combinator
sub :: KnownSymbol s => ProgramT p m a -> ProgramT (s & p) m a

-- | Named command combinator, useful at the top level for naming a
--   program. Typically, the name will be the name or alias of the
--   executable you expect to produce.
named :: KnownSymbol s => ProgramT p m a -> ProgramT (Named s & p) m a

-- | Boolean flag combinator
flag :: KnownSymbol f => (Bool -> ProgramT p m a) -> ProgramT (Flag f & p) m a

-- | A convenience combinator that constructs the program I often want to
--   run out of a program I want to write.
toplevel :: forall s p m. (HasProgram p, KnownSymbol s, MonadIO m) => ProgramT p m () -> ProgramT (Named s & (("help" & Raw) + p)) m ()

-- | The command line program which consists of trying to enter one and
--   then trying the other.
(<+>) :: forall x y m a. ProgramT x m a -> ProgramT y m a -> ProgramT (x + y) m a
infixr 2 <+>

-- | A meta-combinator that takes a type-level description of a command
--   line program and produces a simple usage program.
usage :: forall p m. (MonadIO m, HasProgram p) => ProgramT Raw m ()

-- | Required environment variable combinator
env :: KnownSymbol name => (x -> ProgramT p m a) -> ProgramT (Env  'Required name x & p) m a

-- | Optional environment variable combinator
envOpt :: KnownSymbol name => (Maybe x -> ProgramT p m a) -> ProgramT (Env  'Optional name x & p) m a

-- | Optional environment variable combinator with default
envOptDef :: KnownSymbol name => x -> (x -> ProgramT p m a) -> ProgramT (Env  'Optional name x & p) m a

-- | This is a combinator which runs a <a>ProgramT</a> with the options,
--   arguments, and flags that I get using the <a>initialState</a>
--   function, returning <a>Just</a> the output of the program upon
--   successful option and argument parsing and returning <a>Nothing</a>
--   otherwise.
command :: HasProgram p => ProgramT p IO a -> IO (Maybe a)

-- | This is a combinator which runs a <a>ProgramT</a> with the options,
--   arguments, and flags that I get using the <a>initialState</a>
--   function, ignoring the output of the program.
command_ :: HasProgram p => ProgramT p IO a -> IO ()

-- | The type level program sequencing combinator, taking two program types
--   and sequencing them one after another.
data (&) :: k -> * -> *
infixr 4 &

-- | The type level combining combinator, taking two program types as
--   input, and being interpreted as a program which attempts to run the
--   first command line program and, if parsing its flags, subprograms,
--   options or arguments fails, runs the second, otherwise failing.
data a + b
infixr 2 +

-- | The type level argument combinator, with a <a>Symbol</a> designating
--   the name of that argument.
data Arg :: Symbol -> * -> *

-- | The type level option combinator, with a <a>Symbol</a> designating the
--   option's name and another representing the metavariables name for
--   documentation purposes.
data Opt :: Symbol -> Symbol -> * -> *

-- | The type level naming combinator, giving your program a name for the
--   sake of documentation.
data Named :: Symbol -> *

-- | The type level raw monadic program combinator, allowing a command line
--   program to just do some computation.
data Raw :: *

-- | The type level flag combinator, taking a name as input, allowing your
--   program to take flags with the syntax <tt>~flag</tt>.
data Flag :: Symbol -> *

-- | The type level environment variable combinator, taking a name as
--   input, allowing your program to take environment variables as input
--   automatically.
data Env :: Optionality -> Symbol -> * -> *

-- | The type level tag for whether or not a variable is required or not.
data Optionality
Required :: Optionality
Optional :: Optionality

-- | This is the workhorse of the library. Basically, it allows you to
--   <a>run</a> your <a>ProgramT</a> representation of your program as a
--   <a>CommanderT</a> and pump the <a>State</a> through it until you've
--   processed all of the arguments, options, and flags that you have
--   specified must be used in your <a>ProgramT</a>. You can think of
--   <a>ProgramT</a> as a useful syntax for command line programs, but
--   <a>CommanderT</a> as the semantics of that program. We also give the
--   ability to <a>hoist</a> <a>ProgramT</a> actions between monads if you
--   can uniformly turn computations in one into another. All of the
--   different <a>invocations</a> are also stored to give a primitive form
--   of automatically generated documentation.
class HasProgram p
run :: HasProgram p => ProgramT p IO a -> CommanderT State IO a
hoist :: HasProgram p => (forall x. m x -> n x) -> ProgramT p m a -> ProgramT p n a
invocations :: HasProgram p => [Text]

-- | A <a>CommanderT</a> action is a metaphor for a military commander. At
--   each step, we have a new <a>Action</a> to take, or we could have
--   experienced <a>Defeat</a>, or we can see <a>Victory</a>. While a real
--   life commander worries about moving his troops around in order to
--   achieve a victory in battle, a <a>CommanderT</a> worries about
--   iteratively transforming a state to find some value. We will deal with
--   the subset of these actions where every function must decrease the
--   size of the state, as those are the actions for which this is a monad.
data CommanderT state m a
Action :: (state -> m (CommanderT state m a, state)) -> CommanderT state m a
Defeat :: CommanderT state m a
Victory :: a -> CommanderT state m a

-- | We can run a <a>CommanderT</a> action on a state and see if it has a
--   successful campaign.
runCommanderT :: Monad m => CommanderT state m a -> state -> m (Maybe a)

-- | A simple default for getting out the arguments, options, and flags
--   using <a>getArgs</a>. We use the syntax ~flag for flags and ~opt for
--   options, with arguments using the typical ordered representation.
initialState :: IO State

-- | This is the <a>State</a> that the <a>CommanderT</a> library uses for
--   its role in this library. It is not inlined, because that does nothing
--   but obfuscate the <a>CommanderT</a> monad. It consists of
--   <a>arguments</a>, <a>options</a>, and <a>flags</a>.
data State
State :: [Text] -> HashMap Text Text -> HashSet Text -> State
[arguments] :: State -> [Text]
[options] :: State -> HashMap Text Text
[flags] :: State -> HashSet Text

-- | The type of middleware, which can transform interpreted command line
--   programs by meddling with arguments, options, or flags, or by adding
--   effects for every step. You can also change the underlying monad.
type Middleware m n = forall a. CommanderT State m a -> CommanderT State n a

-- | Middleware to log the state to standard out for every step of the
--   <a>CommanderT</a> computation.
logState :: MonadIO m => Middleware m m

-- | Middleware to transform the base monad with a natural transformation.
transform :: (Monad m, Monad n) => (forall a. m a -> n a) -> Middleware m n

-- | Middleware to add monadic effects for every <a>Action</a>. Useful for
--   debugging complex command line programs.
withActionEffects :: Monad m => m a -> Middleware m m

-- | Middleware to have effects whenever the program might backtrack.
withDefeatEffects :: Monad m => m a -> Middleware m m

-- | Middleware to have effects whenever the program successfully computes
--   a result.
withVictoryEffects :: Monad m => m a -> Middleware m m
instance GHC.Classes.Ord Options.Commander.State
instance GHC.Classes.Eq Options.Commander.State
instance GHC.Show.Show Options.Commander.State
instance GHC.Generics.Generic Options.Commander.State
instance GHC.Real.Integral i => GHC.Real.Integral (Options.Commander.WrappedNatural i)
instance GHC.Enum.Enum i => GHC.Enum.Enum (Options.Commander.WrappedNatural i)
instance GHC.Classes.Eq i => GHC.Classes.Eq (Options.Commander.WrappedNatural i)
instance GHC.Classes.Ord i => GHC.Classes.Ord (Options.Commander.WrappedNatural i)
instance GHC.Real.Real i => GHC.Real.Real (Options.Commander.WrappedNatural i)
instance GHC.Num.Num i => GHC.Num.Num (Options.Commander.WrappedNatural i)
instance GHC.Real.Integral i => GHC.Real.Integral (Options.Commander.WrappedIntegral i)
instance GHC.Enum.Enum i => GHC.Enum.Enum (Options.Commander.WrappedIntegral i)
instance GHC.Classes.Eq i => GHC.Classes.Eq (Options.Commander.WrappedIntegral i)
instance GHC.Classes.Ord i => GHC.Classes.Ord (Options.Commander.WrappedIntegral i)
instance GHC.Real.Real i => GHC.Real.Real (Options.Commander.WrappedIntegral i)
instance GHC.Num.Num i => GHC.Num.Num (Options.Commander.WrappedIntegral i)
instance Options.Commander.Unrender GHC.Integer.Type.Integer
instance Options.Commander.Unrender GHC.Types.Int
instance Options.Commander.Unrender GHC.Int.Int8
instance Options.Commander.Unrender GHC.Int.Int16
instance Options.Commander.Unrender GHC.Int.Int32
instance Options.Commander.Unrender GHC.Int.Int64
instance Options.Commander.Unrender GHC.Natural.Natural
instance Options.Commander.Unrender GHC.Types.Word
instance Options.Commander.Unrender GHC.Word.Word8
instance Options.Commander.Unrender GHC.Word.Word16
instance Options.Commander.Unrender GHC.Word.Word32
instance Options.Commander.Unrender GHC.Word.Word64
instance (Options.Commander.Unrender t, GHC.TypeLits.KnownSymbol name, Options.Commander.HasProgram p) => Options.Commander.HasProgram (Options.Commander.Env 'Options.Commander.Required name t Options.Commander.& p)
instance (Options.Commander.Unrender t, GHC.TypeLits.KnownSymbol name, Options.Commander.HasProgram p) => Options.Commander.HasProgram (Options.Commander.Env 'Options.Commander.Optional name t Options.Commander.& p)
instance (Options.Commander.Unrender t, GHC.TypeLits.KnownSymbol name, Options.Commander.HasProgram p) => Options.Commander.HasProgram (Options.Commander.Arg name t Options.Commander.& p)
instance forall k1 k2 (x :: k2) (y :: k1). (Options.Commander.HasProgram x, Options.Commander.HasProgram y) => Options.Commander.HasProgram (x Options.Commander.+ y)
instance Options.Commander.HasProgram Options.Commander.Raw
instance (GHC.TypeLits.KnownSymbol name, GHC.TypeLits.KnownSymbol option, Options.Commander.HasProgram p, Options.Commander.Unrender t) => Options.Commander.HasProgram (Options.Commander.Opt option name t Options.Commander.& p)
instance (GHC.TypeLits.KnownSymbol flag, Options.Commander.HasProgram p) => Options.Commander.HasProgram (Options.Commander.Flag flag Options.Commander.& p)
instance (GHC.TypeLits.KnownSymbol name, Options.Commander.HasProgram p) => Options.Commander.HasProgram (Options.Commander.Named name Options.Commander.& p)
instance (GHC.TypeLits.KnownSymbol sub, Options.Commander.HasProgram p) => Options.Commander.HasProgram (sub Options.Commander.& p)
instance (Data.Typeable.Internal.Typeable i, GHC.Real.Integral i) => Options.Commander.Unrender (Options.Commander.WrappedNatural i)
instance (Data.Typeable.Internal.Typeable i, GHC.Real.Integral i) => Options.Commander.Unrender (Options.Commander.WrappedIntegral i)
instance Options.Commander.Unrender GHC.Base.String
instance Options.Commander.Unrender Data.Text.Internal.Text
instance Options.Commander.Unrender Data.ByteString.Internal.ByteString
instance Options.Commander.Unrender Data.ByteString.Lazy.Internal.ByteString
instance Options.Commander.Unrender ()
instance (Options.Commander.Unrender a, Options.Commander.Unrender b) => Options.Commander.Unrender (Data.Either.Either a b)
instance Options.Commander.Unrender GHC.Types.Bool
instance Options.Commander.Unrender GHC.Types.Char