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 can be found as:

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 ())

The point of this library is mainly so that you can write command line interfaces quickly and easily, and not have to write any boilerplate.

Run CLI Programs

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.

CLI Combinators

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

Argument combinator

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

Option combinator

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, should only really be used at the top level.

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

Boolean flag combinator

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

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

usage :: HasProgram p => ProgramT (Usage p) m a

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

(<+>) :: 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.

Type Level CLI Description

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

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

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

invocations :: [Text]

(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

invocations :: [Text]

(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

invocations :: [Text]

(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

invocations :: [Text]

(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

invocations :: [Text]

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

}

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 (Opt option name t & p :: Type) m a

Defined in Options.Commander

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

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

}

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 (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

invocations :: [Text]

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

invocations :: [Text]

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

invocations :: [Text]

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

Defined in Options.Commander

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

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

}

data Named :: Symbol -> *

The type level naming combinator, giving your program a name 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

invocations :: [Text]

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 Usage :: * -> *

The type level usage combinator, taking a program type as an argument and being interpreted as a program which prints out all of the invocations of that particular program.

Instances

HasProgram p => HasProgram (Usage p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Usage p) m a :: Type

Methods

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

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

invocations :: [Text]

data ProgramT (Usage p :: Type) m a

Defined in Options.Commander

data ProgramT (Usage p :: Type) m a = UsageProgramT

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

invocations :: [Text]

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

invocations :: [Text]

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

}

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. All of the different invocations are also stored to give a primitive form of automatically generated documentation.

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

invocations :: [Text]

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

invocations :: [Text]

HasProgram p => HasProgram (Usage p :: Type)

Defined in Options.Commander

Associated Types

data ProgramT (Usage p) m a :: Type

Methods

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

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

invocations :: [Text]

(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

invocations :: [Text]

(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

invocations :: [Text]

(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

invocations :: [Text]

(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

invocations :: [Text]

(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

invocations :: [Text]

(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

invocations :: [Text]

The CommanderT Monad

data CommanderT state m 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. 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.

Constructors

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

Defeat

Victory a

Instances

MonadTrans (CommanderT state)

Defined in Options.Commander

Methods

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

Monad m => Monad (CommanderT state m)

Defined in Options.Commander

Methods

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

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

return :: a -> CommanderT state m a

fail :: String -> CommanderT state m a

Functor m => Functor (CommanderT state m)

Defined in Options.Commander

Methods

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

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

Monad m => Applicative (CommanderT state m)

Defined in Options.Commander

Methods

pure :: a -> CommanderT state m a

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

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

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

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

MonadIO m => MonadIO (CommanderT state m)

Defined in Options.Commander

Methods

liftIO :: IO a -> CommanderT state m a

Monad m => Alternative (CommanderT state m)

Defined in Options.Commander

Methods

empty :: CommanderT state m a

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

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

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

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

We can run a CommanderT action on a 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

Parsing Arguments and Options

class 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 Text

Defined in Options.Commander

Methods

unrender :: Text -> Maybe Text

Unrender a => Unrender (Maybe a)

Defined in Options.Commander

Methods

unrender :: Text -> Maybe (Maybe a)

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

Defined in Options.Commander

Methods

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