A Command is a datatype containing the metadata for a user-registered command.

Command m is a command that runs in the monad m, which when triggered will run a polyvariadic handler function. The handler *must* run in the m monad, which is enforced by the type-checker (to see the details, look in CommandHandlerType in the source code).

The contents of this abstract datatype are not exported from this module for encapsulation. Use command, parsecCommand, or regexCommand to instantiate one.

command name handler creates a Command named name, which upon receiving a message will run handler. The name cannot contain any spaces, as it breaks the parser. The handler function can take an arbitrary amount of arguments of arbitrary types (it is polyvariadic), as long as they are instances of ParsableArgument.

The Command that this function creates is polymorphic in the Monad it is run in. This means you can call it from DiscordHandler or any other Monad that satisfies the constraints of MonadDiscord.

See some examples

pong :: (MonadDiscord m) => Command m
pong = command "ping" $ \msg -> respond msg "pong!"

pong2 :: (MonadDiscord m) => Message -> m ()
pong2 = runCommand $ command "ping" $ \msg -> respond msg "pong!"

weather = command "weather" $ \msg location -> do
    result <- liftIO $ getWeather location
    respond msg $ "Weather at " <> location <> " is " <> result <> "!"

instance ParsableArgument Int where
    parserForArg = read <$> many digit -- some Parsec that returns an Int

complex :: (MonadDiscord m) => Command m
complex = command "setLimit" $ \m i -> do
    respond m $ show (i + 20 / 4 + 78^3) -- i is automatically inferred as Int!
    ...

runCommand command msg runs the specified Command with the given message. It first does the initial checks:

For commands registered with command, the check will check for the prefix and the name.

For commands registered with regexCommand, the check will check against the regex.

For commands registered with parsecCommand, the check will check for the prefix and the custom parser.

Any failures during this stage is silently ignored, as it may still be a valid command elsewhere. After this, the requirements are checked (chance, priv, etc). Finally, the commandApplier is called. Any errors inside the handler is caught and appropriately handled.

runCommand pong :: (MonadDiscord m) => Message -> m ()

runCommands calls runCommand for all the Commands, and folds them with the Monadic bind (>>).

runHelp creates a super duper simple help command that just lists each command's names together with their help text.

parsecCommand defines a command that has no name, and has a custom parser that begins from the start of a message. It can help things like "::quotes" because they have special syntax that demands a special parser.

alias, if used together, is ignored. Other compoasble functions like help, prefix, requires, and onError are still valid.

The handler must take a Message and a String as argument (nothing more, nothing less), where the latter is the result of the parser.

example
    = requires moderatorPrivs
    . prefix "~~"
    . parsecCommand (string "abc" >> many1 anyChar) $ \msg quoteName -> do
        ...
         this is triggered on "~~abc<one or more chars>" where quoteName
         contains the section enclosed in <>

regexCommand defines a command that has no name, and has a custom regular expression matcher, that searches across any part of the message.

prefix and alias, if used together, are ignored. Other compoasble functions like help, requires, and onError are still valid.

The handler must take a Message and a '[T.Text]' as argument, where the latter are the list of captured values from the Regex (same as the past newCommand).

thatcher = regexCommand "thatcher [Ii]s ([Dd]ead|[Aa]live)" $ \msg caps -> do
    let verb = head caps
...

help sets the help message for the command. The default is "Help not available."

alias adds an alias for the command's name. This is ignored if a custom parser like regexCommand or parsecCommand is used.

Functionally, this is equivalent to defining a new command with the same handler, however the aliases may not appear on help pages.

onError overwrites the default error handler of a command with a custom implementation. Usually the default defaultErrorHandler suffices.

example
    = onError (\msg e -> respond msg (T.pack $ show e))
    . command "example" $ do
        ...

defaultErrorHandler m e is the default error handler unless you override it manually. This is exported and documented for reference only.

On argument error

It calls respond with the errors. This isn't owoified for legibility.

On requirement error

It sends a DM to the invoking user with the errors.

On a processing error

It calls respond with the error.

On a Discord request failure

It calls respond with the error.

On a Runtime/Haskell error

It calls respond with the error, owoified.

requires adds a requirement to the command. The requirement is a function that takes a Message and either returns Nothing (no problem) or Just "explanation". The function is in the m monad so it can access any additional information from Discord as necessary.

Commands default to having no requirements.

This represents any error that can arise from an invocation of a command. Some are thrown by the system (such as ArgumentParseError), however you can also manually throw them with throwM within any handler.

A ParsableArgument is a dataclass that represents arguments that can be parsed from a message text. Any datatype that is an instance of this dataclass can be used as function arguments for a command handler in command.

Datatype wrapper for the remaining text in the input. Handy for capturing everything remaining. The accessor function getDeez isn't really meant to be used since pattern matching can do everything. Open to renaming.

Example usage:

setStatus =
    command "status"
    $ \msg newStatus newType (Remaining newName) -> do
        ...

Monads in which IO computations may be embedded. Any monad built by applying a sequence of monad transformers to the IO monad will be an instance of this class.

Instances should satisfy the following laws, which state that liftIO is a transformer of monads:

• liftIO . return = return

• liftIO (m >>= f) = liftIO m >>= (liftIO . f)