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


-- | A command line argument/option parser library
--   
--   A command line argument/option parser library.
@package commander-cli
@version 0.10.2.0


-- | 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:
--   name: file
--   |
--   +- subprogram: help
--   |
--   +- subprogram: maybe-read
--   |  |
--   |  `- argument: filename :: [Char]
--   |     |
--   |     `- flag: ~read
--   |
--   `- subprogram: maybe-write
--      |
--      `- option: -file <a>:: [Char]</a>
--   </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 :: forall name x p m a. KnownSymbol name => (x -> ProgramT p m a) -> ProgramT (Arg name x & p) m a

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

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

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

-- | Subcommand combinator
sub :: forall s p m a. 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 :: forall s p m a. KnownSymbol s => ProgramT p m a -> ProgramT (Named s & p) m a

-- | Boolean flag combinator
flag :: forall f p m a. 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 :: forall name p x m a. KnownSymbol name => (x -> ProgramT p m a) -> ProgramT (Env 'Required name x & p) m a

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

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

-- | A combinator which takes a program, and a type-level <a>Symbol</a>
--   description of that program, and produces a program here the
--   documentation is annotated with the given description.
description :: forall description p m a. (HasProgram p, KnownSymbol description) => ProgramT p m a -> ProgramT (Description description & p) m a

-- | A combinator which augments the documentation of the next element, by
--   adding a description after its name and type.
annotated :: forall annotation combinator p m a. ProgramT (combinator & p) m a -> ProgramT (Annotated annotation combinator & 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 :: forall p a. 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_ :: forall p a. 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 <a>arg</a>ument combinator, with a <a>Symbol</a>
--   designating the name of that argument.
data Arg :: Symbol -> * -> *

-- | The type level <a>opt</a>ion 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 combinator for constructing <a>named</a> programs,
--   giving your program a name at the toplevel for the sake of
--   documentation.
data Named :: Symbol -> *

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

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

-- | The type level <a>env</a>ironment 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

-- | The type level <a>description</a> combinator, allowing a command line
--   program to have better documentation.
data Description :: Symbol -> *

-- | The type level <a>annotated</a> combinator, allowing a command line
data Annotated :: Symbol -> * -> *

-- | 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. We also store
--   <a>documentation</a> in the form of a <tt><a>Forest</a>
--   <a>String</a></tt>, in order to automatically generate <a>usage</a>
--   programs.
class HasProgram p where {
    data family ProgramT p (m :: * -> *) a;
}
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
documentation :: HasProgram p => Forest String

-- | 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.
--   
--   In more practical terms, a term of type <a>CommanderT</a> can be
--   thought of as a backtracking, stateful computation which can either
--   result in a result being produced, or nothing being produced. It is a
--   <a>Monad</a> for any base <a>Functor</a> you want to use as the effect
--   inside of the stateful computation, similarly to the free monad.
data CommanderT state (f :: Type -> Type) a
Action :: (state -> f (CommanderT state f a, state)) -> CommanderT state (f :: Type -> Type) a
Defeat :: CommanderT state (f :: Type -> Type) a
Victory :: a -> CommanderT state (f :: Type -> Type) a

-- | We can run a <a>CommanderT</a> on some 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.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 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.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 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 :: k1) (y :: k2). (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 description, Options.Commander.HasProgram p) => Options.Commander.HasProgram (Options.Commander.Description description Options.Commander.& p)
instance (GHC.TypeLits.KnownSymbol annotation, Options.Commander.HasProgram (combinator Options.Commander.& p)) => Options.Commander.HasProgram (Options.Commander.Annotated annotation combinator 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