Options.Commander

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:

main :: IO ()
main = command_ . toplevel "file" $
 (sub "maybe-read" $
  arg "filename" filename ->
  flag "read" b -> raw $
    if b
      then putStrLn =<< readFile filename
      else pure ())
  <+>
 (sub "maybe-write" $
  opt "file" @"file-to-write" mfilename -> raw $
    case mfilename of
      Just filename -> putStrLn =<< readFile filename
      Nothing -> pure ())

If I run this program with the argument help, it will output:

usage:
name: file
|
+- subprogram: help
|
+- subprogram: maybe-read
|  |
|  `- argument: filename :: [Char]
|     |
|     `- flag: ~read
|
`- subprogram: maybe-write
   |
   `- option: -file :: [Char]

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.

Parsing Arguments and Options

If you want to use a Haskell type as an argument or option, you will need to implement the Unrender class. Your type needs to be Typeable for the sake of generating documentation.

class Typeable t => Unrender t where

A class for interpreting command line arguments into Haskell types.

Methods

unrender :: Text -> Maybe t

Instances

Unrender Bool

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Bool

Unrender Char

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Char

Unrender Int

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Int

Unrender Int8

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Int8

Unrender Int16

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Int16

Unrender Int32

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Int32

Unrender Int64

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Int64

Unrender Integer

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Integer

Unrender Natural

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Natural

Unrender Word

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Word

Unrender Word8

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Word8

Unrender Word16

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Word16

Unrender Word32

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Word32

Unrender Word64

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Word64

Unrender ()

Defined in Options.Commander

Methods

unrender :: Text -> Maybe ()

Unrender String

Defined in Options.Commander

Methods

unrender :: Text -> Maybe String

Unrender ByteString

Defined in Options.Commander

Methods

unrender :: Text -> Maybe ByteString

Unrender ByteString

Defined in Options.Commander

Methods

unrender :: Text -> Maybe ByteString

Unrender Text

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Text

(Unrender a, Unrender b) => Unrender (Either a b)

Defined in Options.Commander

Methods

unrender :: Text -> Maybe (Either a b)

Defining CLI Programs

To construct a ProgramT (a specification of a CLI program), you can have arguments, options, raw actions in a monad (typically IO), subprograms, named programs, environment variables, you can combine programs together using <+>, and you can generate primitive usage information with usage. There are combinators for retrieving environment variables as well. We also have a convenience combinator, toplevel, which lets you add a name and a help command to your program using the usage combinator.

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

Environment

Argument combinator

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

Option combinator

optDef :: (KnownSymbol option, KnownSymbol name) => x -> (x -> ProgramT p m a) -> ProgramT (Opt option name x & p) m a

Option combinator with default

raw :: m a -> ProgramT Raw m a

Raw monadic combinator

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

Subcommand combinator

named :: KnownSymbol s => ProgramT p m a -> ProgramT (Named 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.

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

Boolean flag combinator

toplevel :: forall s p m. (HasProgram p, KnownSymbol s, MonadIO m) => ProgramT p m () -> ProgramT (Named s & (("help" & Raw) + p)) m ()

A convenience combinator that constructs the program I often want to run out of a program I want to write.

(<+>) :: forall x y m a. ProgramT x m a -> ProgramT y m a -> ProgramT (x + y) m a infixr 2

The command line program which consists of trying to enter one and then trying the other.

usage :: forall p m. (MonadIO m, HasProgram p) => ProgramT Raw m ()

A meta-combinator that takes a type-level description of a command line program and produces a simple usage program.

env :: KnownSymbol name => (x -> ProgramT p m a) -> ProgramT (Env Required name x & p) m a

Required environment variable combinator

envOpt :: KnownSymbol name => (Maybe x -> ProgramT p m a) -> ProgramT (Env Optional name x & p) m a

Optional environment variable combinator

envOptDef :: KnownSymbol name => x -> (x -> ProgramT p m a) -> ProgramT (Env Optional name x & p) m a

Optional environment variable combinator with default

description :: forall description p m a. (HasProgram p, KnownSymbol description) => ProgramT p m a -> ProgramT (Description description & p) m a

A combinator which takes a program, and a type-level Symbol description of that program, and produces a program here the documentation is annotated with the given description.

annotated :: forall annotation combinator p m a. ProgramT (combinator & p) m a -> ProgramT (Annotated annotation combinator & p) m a

A combinator which augments the documentation of the next element, by adding a description after its name and type.

Run CLI Programs

To run a ProgramT (a specification of a CLI program), you will need to use command or command_.

command :: HasProgram p => ProgramT p IO a -> IO (Maybe a)

This is a combinator which runs a ProgramT with the options, arguments, and flags that I get using the initialState function, returning Just the output of the program upon successful option and argument parsing and returning Nothing otherwise.

command_ :: HasProgram p => ProgramT p IO a -> IO ()

This is a combinator which runs a ProgramT with the options, arguments, and flags that I get using the initialState function, ignoring the output of the program.

Each ProgramT has a type level description, build from these type level combinators.

data (&) :: k -> * -> * infixr 4

The type level program sequencing combinator, taking two program types and sequencing them one after another.

Instances

(KnownSymbol annotation, HasProgram (combinator & p)) => HasProgram (Annotated annotation combinator & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Annotated annotation combinator & p) m a :: Type

Methods

run :: ProgramT (Annotated annotation combinator & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Annotated annotation combinator & p) m a -> ProgramT (Annotated annotation combinator & p) n a

documentation :: Forest String

(KnownSymbol description, HasProgram p) => HasProgram (Description description & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Description description & p) m a :: Type

Methods

run :: ProgramT (Description description & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Description description & p) m a -> ProgramT (Description description & p) n a

documentation :: Forest String

(Unrender t, KnownSymbol name, HasProgram p) => HasProgram (Env Required name t & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Env Required name t & p) m a :: Type

Methods

run :: ProgramT (Env Required name t & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Env Required name t & p) m a -> ProgramT (Env Required name t & p) n a

documentation :: Forest String

(Unrender t, KnownSymbol name, HasProgram p) => HasProgram (Env Optional name t & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Env Optional name t & p) m a :: Type

Methods

run :: ProgramT (Env Optional name t & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Env Optional name t & p) m a -> ProgramT (Env Optional name t & p) n a

documentation :: Forest String

(KnownSymbol flag, HasProgram p) => HasProgram (Flag flag & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Flag flag & p) m a :: Type

Methods

run :: ProgramT (Flag flag & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Flag flag & p) m a -> ProgramT (Flag flag & p) n a

documentation :: Forest String

(KnownSymbol name, KnownSymbol option, HasProgram p, Unrender t) => HasProgram (Opt option name t & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Opt option name t & p) m a :: Type

Methods

run :: ProgramT (Opt option name t & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Opt option name t & p) m a -> ProgramT (Opt option name t & p) n a

documentation :: Forest String

(Unrender t, KnownSymbol name, HasProgram p) => HasProgram (Arg name t & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Arg name t & p) m a :: Type

Methods

run :: ProgramT (Arg name t & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Arg name t & p) m a -> ProgramT (Arg name t & p) n a

documentation :: Forest String

(KnownSymbol name, HasProgram p) => HasProgram (Named name & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Named name & p) m a :: Type

Methods

run :: ProgramT (Named name & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Named name & p) m a -> ProgramT (Named name & p) n a

documentation :: Forest String

(KnownSymbol sub, HasProgram p) => HasProgram (sub & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (sub & p) m a :: Type

Methods

run :: ProgramT (sub & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (sub & p) m a -> ProgramT (sub & p) n a

documentation :: Forest String

newtype ProgramT (Annotated annotation combinator & p :: Type) m a

Defined in Options.Commander

newtype ProgramT (Annotated annotation combinator & p :: Type) m a = AnnotatedProgramT {

• unAnnotatedProgramT :: ProgramT (combinator & p) m a

}

newtype ProgramT (Description description & p :: Type) m a

Defined in Options.Commander

newtype ProgramT (Description description & p :: Type) m a = DescriptionProgramT {

• unDescriptionProgramT :: ProgramT p m a

}

newtype ProgramT (Env Required name t & p :: Type) m a

Defined in Options.Commander

newtype ProgramT (Env Required name t & p :: Type) m a = EnvProgramT'Required {

• unEnvProgramT'Required :: t -> ProgramT p m a

}

data ProgramT (Env Optional name t & p :: Type) m a

Defined in Options.Commander

data ProgramT (Env Optional name t & p :: Type) m a = EnvProgramT'Optional {

• unEnvProgramT'Optional :: Maybe t -> ProgramT p m a
• unEnvDefault :: Maybe t

}

newtype ProgramT (Flag flag & p :: Type) m a

Defined in Options.Commander

newtype ProgramT (Flag flag & p :: Type) m a = FlagProgramT {

• unFlagProgramT :: Bool -> ProgramT p m a

}

data ProgramT (Opt option name t & p :: Type) m a

Defined in Options.Commander

data ProgramT (Opt option name t & p :: Type) m a = OptProgramT {

• unOptProgramT :: Maybe t -> ProgramT p m a
• unOptDefault :: Maybe t

}

newtype ProgramT (Arg name t & p :: Type) m a

Defined in Options.Commander

newtype ProgramT (Arg name t & p :: Type) m a = ArgProgramT {

• unArgProgramT :: t -> ProgramT p m a

}

newtype ProgramT (Named name & p :: Type) m a

Defined in Options.Commander

newtype ProgramT (Named name & p :: Type) m a = NamedProgramT {

• unNamedProgramT :: ProgramT p m a

}

newtype ProgramT (sub & p :: Type) m a

Defined in Options.Commander

newtype ProgramT (sub & p :: Type) m a = SubProgramT {

• unSubProgramT :: ProgramT p m a

}

data a + b infixr 2

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.

Instances

(HasProgram x, HasProgram y) => HasProgram (x + y :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (x + y) m a :: Type

Methods

run :: ProgramT (x + y) IO a -> CommanderT State IO a

hoist :: (forall x0. m x0 -> n x0) -> ProgramT (x + y) m a -> ProgramT (x + y) n a

documentation :: Forest String

data ProgramT (x + y :: Type) m a

Defined in Options.Commander

data ProgramT (x + y :: Type) m a = (ProgramT x m a) :+: (ProgramT y m a)

data Arg :: Symbol -> * -> *

The type level argument combinator, with a Symbol designating the name of that argument.

Instances

(Unrender t, KnownSymbol name, HasProgram p) => HasProgram (Arg name t & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Arg name t & p) m a :: Type

Methods

run :: ProgramT (Arg name t & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Arg name t & p) m a -> ProgramT (Arg name t & p) n a

documentation :: Forest String

newtype ProgramT (Arg name t & p :: Type) m a

Defined in Options.Commander

newtype ProgramT (Arg name t & p :: Type) m a = ArgProgramT {

• unArgProgramT :: t -> ProgramT p m a

}

data Opt :: Symbol -> Symbol -> * -> *

The type level option combinator, with a Symbol designating the option's name and another representing the metavariables name for documentation purposes.

Instances

(KnownSymbol name, KnownSymbol option, HasProgram p, Unrender t) => HasProgram (Opt option name t & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Opt option name t & p) m a :: Type

Methods

run :: ProgramT (Opt option name t & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Opt option name t & p) m a -> ProgramT (Opt option name t & p) n a

documentation :: Forest String

data ProgramT (Opt option name t & p :: Type) m a

Defined in Options.Commander

data ProgramT (Opt option name t & p :: Type) m a = OptProgramT {

• unOptProgramT :: Maybe t -> ProgramT p m a
• unOptDefault :: Maybe t

}

data Named :: Symbol -> *

The type level combinator for constructing named programs, giving your program a name at the toplevel for the sake of documentation.

Instances

(KnownSymbol name, HasProgram p) => HasProgram (Named name & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Named name & p) m a :: Type

Methods

run :: ProgramT (Named name & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Named name & p) m a -> ProgramT (Named name & p) n a

documentation :: Forest String

newtype ProgramT (Named name & p :: Type) m a

Defined in Options.Commander

newtype ProgramT (Named name & p :: Type) m a = NamedProgramT {

• unNamedProgramT :: ProgramT p m a

}

data Raw :: *

The type level raw monadic program combinator, allowing a command line program to just do some computation.

Instances

HasProgram Raw

Defined in Options.Commander

Associated Types

data ProgramT Raw m a :: Type

Methods

run :: ProgramT Raw IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT Raw m a -> ProgramT Raw n a

documentation :: Forest String

newtype ProgramT Raw m a

Defined in Options.Commander

newtype ProgramT Raw m a = RawProgramT {

• unRawProgramT :: m a

}

data Flag :: Symbol -> *

The type level flag combinator, taking a name as input, allowing your program to take flags with the syntax ~flag.

Instances

(KnownSymbol flag, HasProgram p) => HasProgram (Flag flag & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Flag flag & p) m a :: Type

Methods

run :: ProgramT (Flag flag & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Flag flag & p) m a -> ProgramT (Flag flag & p) n a

documentation :: Forest String

newtype ProgramT (Flag flag & p :: Type) m a

Defined in Options.Commander

newtype ProgramT (Flag flag & p :: Type) m a = FlagProgramT {

• unFlagProgramT :: Bool -> ProgramT p m a

}

data Env :: Optionality -> Symbol -> * -> *

The type level environment variable combinator, taking a name as input, allowing your program to take environment variables as input automatically.

Instances

(Unrender t, KnownSymbol name, HasProgram p) => HasProgram (Env Required name t & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Env Required name t & p) m a :: Type

Methods

run :: ProgramT (Env Required name t & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Env Required name t & p) m a -> ProgramT (Env Required name t & p) n a

documentation :: Forest String

(Unrender t, KnownSymbol name, HasProgram p) => HasProgram (Env Optional name t & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Env Optional name t & p) m a :: Type

Methods

run :: ProgramT (Env Optional name t & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Env Optional name t & p) m a -> ProgramT (Env Optional name t & p) n a

documentation :: Forest String

newtype ProgramT (Env Required name t & p :: Type) m a

Defined in Options.Commander

newtype ProgramT (Env Required name t & p :: Type) m a = EnvProgramT'Required {

• unEnvProgramT'Required :: t -> ProgramT p m a

}

data ProgramT (Env Optional name t & p :: Type) m a

Defined in Options.Commander

data ProgramT (Env Optional name t & p :: Type) m a = EnvProgramT'Optional {

• unEnvProgramT'Optional :: Maybe t -> ProgramT p m a
• unEnvDefault :: Maybe t

}

data Optionality

The type level tag for whether or not a variable is required or not.

Constructors

Required

Optional

data Description :: Symbol -> *

The type level description combinator, allowing a command line program to have better documentation.

Instances

(KnownSymbol description, HasProgram p) => HasProgram (Description description & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Description description & p) m a :: Type

Methods

run :: ProgramT (Description description & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Description description & p) m a -> ProgramT (Description description & p) n a

documentation :: Forest String

newtype ProgramT (Description description & p :: Type) m a

Defined in Options.Commander

newtype ProgramT (Description description & p :: Type) m a = DescriptionProgramT {

• unDescriptionProgramT :: ProgramT p m a

}

data Annotated :: Symbol -> * -> *

The type level annotated combinator, allowing a command line

Instances

(KnownSymbol annotation, HasProgram (combinator & p)) => HasProgram (Annotated annotation combinator & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Annotated annotation combinator & p) m a :: Type

Methods

run :: ProgramT (Annotated annotation combinator & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Annotated annotation combinator & p) m a -> ProgramT (Annotated annotation combinator & p) n a

documentation :: Forest String

newtype ProgramT (Annotated annotation combinator & p :: Type) m a

Defined in Options.Commander

newtype ProgramT (Annotated annotation combinator & p :: Type) m a = AnnotatedProgramT {

• unAnnotatedProgramT :: ProgramT (combinator & p) m a

}

Interpreting CLI Programs

The HasProgram class forms the backbone of this library, defining the syntax for CLI programs using the ProgramT data family, and defining the interpretation of all of the various pieces of a CLI.

class HasProgram p where

This is the workhorse of the library. Basically, it allows you to run your ProgramT representation of your program as a CommanderT and pump the State through it until you've processed all of the arguments, options, and flags that you have specified must be used in your ProgramT. You can think of ProgramT as a useful syntax for command line programs, but CommanderT as the semantics of that program. We also give the ability to hoist ProgramT actions between monads if you can uniformly turn computations in one into another. We also store documentation in the form of a Forest String, in order to automatically generate usage programs.

Associated Types

data ProgramT p (m :: * -> *) a

Methods

run :: ProgramT p IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT p m a -> ProgramT p n a

documentation :: Forest String

Instances

HasProgram Raw

Defined in Options.Commander

Associated Types

data ProgramT Raw m a :: Type

Methods

run :: ProgramT Raw IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT Raw m a -> ProgramT Raw n a

documentation :: Forest String

(KnownSymbol annotation, HasProgram (combinator & p)) => HasProgram (Annotated annotation combinator & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Annotated annotation combinator & p) m a :: Type

Methods

run :: ProgramT (Annotated annotation combinator & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Annotated annotation combinator & p) m a -> ProgramT (Annotated annotation combinator & p) n a

documentation :: Forest String

(KnownSymbol description, HasProgram p) => HasProgram (Description description & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Description description & p) m a :: Type

Methods

run :: ProgramT (Description description & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Description description & p) m a -> ProgramT (Description description & p) n a

documentation :: Forest String

(Unrender t, KnownSymbol name, HasProgram p) => HasProgram (Env Required name t & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Env Required name t & p) m a :: Type

Methods

run :: ProgramT (Env Required name t & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Env Required name t & p) m a -> ProgramT (Env Required name t & p) n a

documentation :: Forest String

(Unrender t, KnownSymbol name, HasProgram p) => HasProgram (Env Optional name t & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Env Optional name t & p) m a :: Type

Methods

run :: ProgramT (Env Optional name t & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Env Optional name t & p) m a -> ProgramT (Env Optional name t & p) n a

documentation :: Forest String

(KnownSymbol flag, HasProgram p) => HasProgram (Flag flag & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Flag flag & p) m a :: Type

Methods

run :: ProgramT (Flag flag & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Flag flag & p) m a -> ProgramT (Flag flag & p) n a

documentation :: Forest String

(KnownSymbol name, KnownSymbol option, HasProgram p, Unrender t) => HasProgram (Opt option name t & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Opt option name t & p) m a :: Type

Methods

run :: ProgramT (Opt option name t & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Opt option name t & p) m a -> ProgramT (Opt option name t & p) n a

documentation :: Forest String

(Unrender t, KnownSymbol name, HasProgram p) => HasProgram (Arg name t & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Arg name t & p) m a :: Type

Methods

run :: ProgramT (Arg name t & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Arg name t & p) m a -> ProgramT (Arg name t & p) n a

documentation :: Forest String

(KnownSymbol name, HasProgram p) => HasProgram (Named name & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Named name & p) m a :: Type

Methods

run :: ProgramT (Named name & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (Named name & p) m a -> ProgramT (Named name & p) n a

documentation :: Forest String

(KnownSymbol sub, HasProgram p) => HasProgram (sub & p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (sub & p) m a :: Type

Methods

run :: ProgramT (sub & p) IO a -> CommanderT State IO a

hoist :: (forall x. m x -> n x) -> ProgramT (sub & p) m a -> ProgramT (sub & p) n a

documentation :: Forest String

(HasProgram x, HasProgram y) => HasProgram (x + y :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (x + y) m a :: Type

Methods

run :: ProgramT (x + y) IO a -> CommanderT State IO a

hoist :: (forall x0. m x0 -> n x0) -> ProgramT (x + y) m a -> ProgramT (x + y) n a

documentation :: Forest String

The CommanderT Monad

The CommanderT monad is how your CLI programs are interpreted by run. It has the ability to backtrack and it maintains some state.

data CommanderT state (f :: Type -> Type) a

A CommanderT action is a metaphor for a military commander. At each step, we have a new Action to take, or we could have experienced Defeat, or we can see Victory. While a real life commander worries about moving his troops around in order to achieve a victory in battle, a CommanderT worries about iteratively transforming a state to find some value.

In more practical terms, a term of type CommanderT 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 Monad for any base Functor you want to use as the effect inside of the stateful computation, similarly to the free monad.

Constructors

Action (state -> f (CommanderT state f a, state))

Defeat

Victory a

Instances

MonadTrans (CommanderT state)

Defined in Control.Monad.Commander

Methods

lift :: Monad m => m a -> CommanderT state m a

Functor f => Monad (CommanderT state f)

Defined in Control.Monad.Commander

Methods

(>>=) :: CommanderT state f a -> (a -> CommanderT state f b) -> CommanderT state f b

(>>) :: CommanderT state f a -> CommanderT state f b -> CommanderT state f b

return :: a -> CommanderT state f a

fail :: String -> CommanderT state f a

Functor f => Functor (CommanderT state f)

Defined in Control.Monad.Commander

Methods

fmap :: (a -> b) -> CommanderT state f a -> CommanderT state f b

(<$) :: a -> CommanderT state f b -> CommanderT state f a

Functor f => Applicative (CommanderT state f)

Defined in Control.Monad.Commander

Methods

pure :: a -> CommanderT state f a

(<*>) :: CommanderT state f (a -> b) -> CommanderT state f a -> CommanderT state f b

liftA2 :: (a -> b -> c) -> CommanderT state f a -> CommanderT state f b -> CommanderT state f c

(*>) :: CommanderT state f a -> CommanderT state f b -> CommanderT state f b

(<*) :: CommanderT state f a -> CommanderT state f b -> CommanderT state f a

MonadIO m => MonadIO (CommanderT state m)

Defined in Control.Monad.Commander

Methods

liftIO :: IO a -> CommanderT state m a

Functor f => Alternative (CommanderT state f)

Defined in Control.Monad.Commander

Methods

empty :: CommanderT state f a

(<|>) :: CommanderT state f a -> CommanderT state f a -> CommanderT state f a

some :: CommanderT state f a -> CommanderT state f [a]

many :: CommanderT state f a -> CommanderT state f [a]

runCommanderT :: Monad m => CommanderT state m a -> state -> m (Maybe a)

We can run a CommanderT on some state and see if it has a successful campaign.

initialState :: IO State

A simple default for getting out the arguments, options, and flags using getArgs. We use the syntax ~flag for flags and -opt for options, with arguments using the typical ordered representation.

data State

This is the State that the CommanderT library uses for its role in this library. It is not inlined, because that does nothing but obfuscate the CommanderT monad. It consists of arguments, options, and flags.

Constructors

State

Fields

• arguments :: [Text]
• options :: HashMap Text Text
• flags :: HashSet Text

Instances

Eq State

Defined in Options.Commander

Methods

(==) :: State -> State -> Bool

(/=) :: State -> State -> Bool

Ord State

Defined in Options.Commander

Methods

compare :: State -> State -> Ordering

(<) :: State -> State -> Bool

(<=) :: State -> State -> Bool

(>) :: State -> State -> Bool

(>=) :: State -> State -> Bool

max :: State -> State -> State

min :: State -> State -> State

Show State

Defined in Options.Commander

Methods

showsPrec :: Int -> State -> ShowS

show :: State -> String

showList :: [State] -> ShowS

Generic State

Defined in Options.Commander

Associated Types

type Rep State :: Type -> Type

Methods

from :: State -> Rep State x

to :: Rep State x -> State

type Rep State

Defined in Options.Commander

type Rep State = D1 (MetaData "State" "Options.Commander" "commander-cli-0.10.1.2-E65fVVm2RFK4C0G1IYGAcb" False) (C1 (MetaCons "State" PrefixI True) (S1 (MetaSel (Just "arguments") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Text]) :*: (S1 (MetaSel (Just "options") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (HashMap Text Text)) :*: S1 (MetaSel (Just "flags") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (HashSet Text)))))

Middleware for CommanderT

If you want to modify your interpreted CLI program, in its CommanderT form, you can use the concept of Middleware. A number of these are provided for debugging complex CLI programs, in case they aren't doing what you'd expect.

type Middleware m n = forall a. CommanderT State m a -> CommanderT State n a

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.

logState :: MonadIO m => Middleware m m

Middleware to log the state to standard out for every step of the CommanderT computation.

transform :: (Monad m, Monad n) => (forall a. m a -> n a) -> Middleware m n

Middleware to transform the base monad with a natural transformation.

withActionEffects :: Monad m => m a -> Middleware m m

Middleware to add monadic effects for every Action. Useful for debugging complex command line programs.

withDefeatEffects :: Monad m => m a -> Middleware m m

Middleware to have effects whenever the program might backtrack.

withVictoryEffects :: Monad m => m a -> Middleware m m

Middleware to have effects whenever the program successfully computes a result.