Marvin

For the proper, verbose documentation see https://marvin.readthedocs.org/en/latest/scripting.html.

The Script

data Script a

An abstract type describing a marvin script.

This is basically a collection of event handlers.

Internal structure is exposed for people wanting to extend this.

defineScript :: ScriptId -> ScriptDefinition a () -> ScriptInit a

Define a new script for marvin

You need to provide a ScriptId (which can be written as a non-empty string, needs the OverloadedStrings language extension). This id is used as the key for the section in the bot config belonging to this script and in logging output.

Roughly equivalent to "module.exports" in hubot.

data ScriptInit a

Initializer for a script. This gets run by the server during startup and creates a Script

data ScriptId

A type, basically a String, which identifies a script to the config and the logging facilities.

For conversion please use mkScriptId and unwrapScriptId. They will perform necessary checks.

Instances

Eq ScriptId

Methods

(==) :: ScriptId -> ScriptId -> Bool

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

Show ScriptId

Methods

showsPrec :: Int -> ScriptId -> ShowS

show :: ScriptId -> String

showList :: [ScriptId] -> ShowS

IsString ScriptId

Methods

fromString :: String -> ScriptId

ShowT ScriptId

Methods

showT :: ScriptId -> Text

showListT :: [ScriptId] -> Text

data ScriptDefinition a r

A monad for gradually defining a Script using respond and hear as well as any IO action.

Instances

MonadBase IO (ScriptDefinition a)

Methods

liftBase :: IO α -> ScriptDefinition a α

Monad (ScriptDefinition a)

Methods

(>>=) :: ScriptDefinition a a -> (a -> ScriptDefinition a b) -> ScriptDefinition a b

(>>) :: ScriptDefinition a a -> ScriptDefinition a b -> ScriptDefinition a b

return :: a -> ScriptDefinition a a

fail :: String -> ScriptDefinition a a

Functor (ScriptDefinition a)

Methods

fmap :: (a -> b) -> ScriptDefinition a a -> ScriptDefinition a b

(<$) :: a -> ScriptDefinition a b -> ScriptDefinition a a

Applicative (ScriptDefinition a)

Methods

pure :: a -> ScriptDefinition a a

(<*>) :: ScriptDefinition a (a -> b) -> ScriptDefinition a a -> ScriptDefinition a b

(*>) :: ScriptDefinition a a -> ScriptDefinition a b -> ScriptDefinition a b

(<*) :: ScriptDefinition a a -> ScriptDefinition a b -> ScriptDefinition a a

MonadIO (ScriptDefinition a)

Methods

liftIO :: IO a -> ScriptDefinition a a

MonadLogger (ScriptDefinition a)

Methods

monadLoggerLog :: ToLogStr msg => Loc -> LogSource -> LogLevel -> msg -> ScriptDefinition a ()

HasConfigAccess (ScriptDefinition a)

Methods

getConfigInternal :: ScriptDefinition a Config

AccessAdapter (ScriptDefinition a)

Associated Types

type AdapterT (ScriptDefinition a :: * -> *) :: *

Methods

getAdapter :: ScriptDefinition a (AdapterT (ScriptDefinition a))

IsScript (ScriptDefinition a)

Methods

getScriptId :: ScriptDefinition a ScriptId

type AdapterT (ScriptDefinition a)

type AdapterT (ScriptDefinition a) = a

class IsAdapter a

Basic functionality required of any adapter

Minimal complete definition

adapterId, messageChannel, initAdapter, runWithAdapter, getUsername, getChannelName, resolveChannel, resolveUser

Associated Types

type User a

Concrete, adapter specific representation of a user. Could be an id string or a full object for instance

type Channel a

Concrete, adapter specific representation of a channel. Could be an id string or a full object for instance

Instances

IsAdapter ShellAdapter

Associated Types

type User ShellAdapter :: *

type Channel ShellAdapter :: *

Methods

adapterId :: AdapterId ShellAdapter

messageChannel :: Channel ShellAdapter -> Text -> AdapterM ShellAdapter ()

initAdapter :: RunnerM ShellAdapter

runWithAdapter :: RunWithAdapter ShellAdapter

getUsername :: User ShellAdapter -> AdapterM ShellAdapter Text

getChannelName :: Channel ShellAdapter -> AdapterM ShellAdapter Text

resolveChannel :: Text -> AdapterM ShellAdapter (Maybe (Channel ShellAdapter))

resolveUser :: Text -> AdapterM ShellAdapter (Maybe (User ShellAdapter))

MkTelegram a => IsAdapter (TelegramAdapter a)

Associated Types

type User (TelegramAdapter a) :: *

type Channel (TelegramAdapter a) :: *

Methods

adapterId :: AdapterId (TelegramAdapter a)

messageChannel :: Channel (TelegramAdapter a) -> Text -> AdapterM (TelegramAdapter a) ()

initAdapter :: RunnerM (TelegramAdapter a)

runWithAdapter :: RunWithAdapter (TelegramAdapter a)

getUsername :: User (TelegramAdapter a) -> AdapterM (TelegramAdapter a) Text

getChannelName :: Channel (TelegramAdapter a) -> AdapterM (TelegramAdapter a) Text

resolveChannel :: Text -> AdapterM (TelegramAdapter a) (Maybe (Channel (TelegramAdapter a)))

resolveUser :: Text -> AdapterM (TelegramAdapter a) (Maybe (User (TelegramAdapter a)))

Reacting

data BotReacting a d r

Monad for reacting in the bot. Allows use of functions like send, reply and messageChannel as well as any arbitrary IO action using liftIO.

The type parameter d is the accessible data provided by the trigger for this action and can be obtained with getData or other custom functions like getMessage and getMatch which typically depend on a particular type of data in d.

For completeness: a is the adapter type and r is the return type of the monadic computation.

This is also a MonadReader instance, there you can inspect the entire state of this reaction. This is typically only used in internal or utility functions and not necessary for the user. To inspect particular pieces of this state refer to the *Lenses* section.

Instances

MonadBase IO (BotReacting a d)

Methods

liftBase :: IO α -> BotReacting a d α

Monad (BotReacting a d)

Methods

(>>=) :: BotReacting a d a -> (a -> BotReacting a d b) -> BotReacting a d b

(>>) :: BotReacting a d a -> BotReacting a d b -> BotReacting a d b

return :: a -> BotReacting a d a

fail :: String -> BotReacting a d a

Functor (BotReacting a d)

Methods

fmap :: (a -> b) -> BotReacting a d a -> BotReacting a d b

(<$) :: a -> BotReacting a d b -> BotReacting a d a

Applicative (BotReacting a d)

Methods

pure :: a -> BotReacting a d a

(<*>) :: BotReacting a d (a -> b) -> BotReacting a d a -> BotReacting a d b

(*>) :: BotReacting a d a -> BotReacting a d b -> BotReacting a d b

(<*) :: BotReacting a d a -> BotReacting a d b -> BotReacting a d a

MonadIO (BotReacting a d)

Methods

liftIO :: IO a -> BotReacting a d a

MonadLogger (BotReacting a d)

Methods

monadLoggerLog :: ToLogStr msg => Loc -> LogSource -> LogLevel -> msg -> BotReacting a d ()

MonadLoggerIO (BotReacting a d)

Methods

askLoggerIO :: BotReacting a d (Loc -> LogSource -> LogLevel -> LogStr -> IO ())

HasConfigAccess (BotReacting a b)

Methods

getConfigInternal :: BotReacting a b Config

AccessAdapter (BotReacting a b)

Associated Types

type AdapterT (BotReacting a b :: * -> *) :: *

Methods

getAdapter :: BotReacting a b (AdapterT (BotReacting a b))

IsScript (BotReacting a b)

Methods

getScriptId :: BotReacting a b ScriptId

type AdapterT (BotReacting a b)

type AdapterT (BotReacting a b) = a

Reaction Functions

hear :: Regex -> BotReacting a (User' a, Channel' a, Match, Message, TimeStamp) () -> ScriptDefinition a ()

Whenever any message matches the provided regex this handler gets run.

Equivalent to "robot.hear" in hubot

respond :: Regex -> BotReacting a (User' a, Channel' a, Match, Message, TimeStamp) () -> ScriptDefinition a ()

Runs the handler only if the bot was directly addressed.

Equivalent to "robot.respond" in hubot

enter :: BotReacting a (User' a, Channel' a, TimeStamp) () -> ScriptDefinition a ()

This handler runs whenever a user enters any channel (which the bot is subscribed to)

The payload contains the entering user and the channel which was entered.

exit :: BotReacting a (User' a, Channel' a, TimeStamp) () -> ScriptDefinition a ()

This handler runs whenever a user exits any channel (which the bot is subscribed to)

The payload contains the exiting user and the channel which was exited.

enterIn :: Text -> BotReacting a (User' a, Channel' a, TimeStamp) () -> ScriptDefinition a ()

This handler runs whenever a user enters the specified channel.

The argument is the human readable name for the channel.

The payload contains the entering user.

exitFrom :: Text -> BotReacting a (User' a, Channel' a, TimeStamp) () -> ScriptDefinition a ()

This handler runs whenever a user exits the specified channel, provided the bot is subscribed to the channel in question.

The argument is the human readable name for the channel.

The payload contains the exting user.

topic :: BotReacting a (User' a, Channel' a, Topic, TimeStamp) () -> ScriptDefinition a ()

This handler runs when the topic in any channel the bot is subscribed to changes.

The payload contains the new topic and the channel in which it was set.

topicIn :: Text -> BotReacting a (User' a, Channel' a, Topic, TimeStamp) () -> ScriptDefinition a ()

This handler runs when the topic in the specified channel is changed, provided the bot is subscribed to the channel in question.

The argument is the human readable channel name.

customTrigger :: (Event a -> Maybe d) -> BotReacting a d () -> ScriptDefinition a ()

Extension point for the user

Allows you to handle the raw event yourself. Returning Nothing from the trigger function means you dont want to react to the event. The value returned inside the Just is available in the handler later using getData.

Getting data

getData :: BotReacting a d d

Obtain the event reaction data.

The type of this data depends on the reaction function used. For instance hear and respond will contain MessageReactionData. The actual contents comes from the event itself and was put together by the trigger.

getMessage :: Get m Message => BotReacting a m Message

Get the message that triggered this action Includes sender, target channel, as well as the full, untruncated text of the original message

getMatch :: Get m Match => BotReacting a m Match

Get the results from matching the regular expression.

Equivalent to "msg.match" in hubot.

getTopic :: Get m Topic => BotReacting a m Topic

Get the the new topic.

getChannel :: forall a m. Get m (Channel' a) => BotReacting a m (Channel a)

Get the stored channel in which something happened.

getUser :: forall m a. Get m (User' a) => BotReacting a m (User a)

Get the user which was part of the triggered action.

getUsername :: (HasConfigAccess m, AccessAdapter m, IsAdapter a, MonadIO m, AdapterT m ~ a) => User a -> m Text

Get the username of a registered user. The type signature is so large to allow this function to be used both in BotReacting and ScriptDefinition.

getChannelName :: (HasConfigAccess m, AccessAdapter m, IsAdapter a, MonadIO m, AdapterT m ~ a) => Channel a -> m Text

Get the human readable name of a channel. The type signature is so large to allow this function to be used both in BotReacting and ScriptDefinition.

resolveUser :: (HasConfigAccess m, AccessAdapter m, IsAdapter a, MonadIO m, AdapterT m ~ a) => Text -> m (Maybe (User a))

Try to get the user with a particular username. The type signature is so large to allow this function to be used both in BotReacting and ScriptDefinition.

resolveChannel :: (HasConfigAccess m, AccessAdapter m, IsAdapter a, MonadIO m, AdapterT m ~ a) => Text -> m (Maybe (Channel a))

Try to get the channel with a particular human readable name. The type signature is so large to allow this function to be used both in BotReacting and ScriptDefinition.

Sending messages

send :: (IsAdapter a, Get d (Channel' a)) => Text -> BotReacting a d ()

Send a message to the channel the triggering message came from.

Equivalent to "robot.send" in hubot

reply :: (IsAdapter a, Get d (User' a), Get d (Channel' a)) => Text -> BotReacting a d ()

Send a message to the channel the original message came from and address the user that sent the original message.

Equivalent to "robot.reply" in hubot

messageChannel :: (HasConfigAccess m, AccessAdapter m, IsAdapter (AdapterT m), MonadLoggerIO m) => Text -> Text -> m ()

Send a message to a Channel (by name)

messageChannel' :: (HasConfigAccess m, AccessAdapter m, IsAdapter (AdapterT m), MonadIO m) => Channel (AdapterT m) -> Text -> m ()

Send a message to a channel (by adapter dependent channel object)

Interaction with the config

getConfigVal :: (Configured a, HasConfigAccess m) => Name -> m (Maybe a)

Get a value out of the config, returns Nothing if the value didn't exist.

This config is the config for this script. Ergo all config vars registered under the config section for the ScriptId of this script.

The HasConfigAccess Constraint means this function can be used both during script definition and when a handler is run.

requireConfigVal :: (Configured a, HasConfigAccess m) => Name -> m a

Get a value out of the config and fail with an error if the specified key is not found.

This config is the config for this script. Ergo all config vars registered under the config section for the ScriptId of this script.

The HasConfigAccess Constraint means this function can be used both during script definition and when a handler is run.

getBotName :: HasConfigAccess m => m Text

Get the configured name of the bot.

Handler Types

type Message = Text

The contents of a recieved message

type Topic = Text

The topic in a channel

Advanced actions

extractAction :: BotReacting a () o -> ScriptDefinition a (IO o)

Take an action and produce an IO action with the same effect. Useful for creating actions which can be scheduled to execute a certain time or asynchronous. The idea is that one can conveniently send messages from inside a schedulable action.

extractReaction :: BotReacting a s o -> BotReacting a s (IO o)

Take a reaction and produce an IO action with the same effect. Useful for creating actions which can be scheduled to execute a certain time or asynchronous. The idea is that one can conveniently send messages from inside a schedulable action.