Marvin.Internal

Exposed API

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

Define a new script for marvin

You need to provide a ScriptId (which can simple be written as a non-empty string). 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.

Reacting

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

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.

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.

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.

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

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.

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

Get the user whihc was part of the triggered action.

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

Get the results from matching the regular expression.

Equivalent to "msg.match" in hubot.

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

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

Get the stored channel in which something happened.

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

Get the the new topic.

getBotName :: HasConfigAccess m => m Text

Get the configured name of the bot.

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

Get the human readable name of a channel.

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

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

Get the username of a registered user.

Interacting 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.

Access config (advanced, internal)

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

INTERNAL, USE WITH CARE

Get a value from the bot config (should be "bot" subconfig)

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

INTERNAL, USE WITH CARE

Get a value from the bot config (should be "bot" subconfig)

getConfig :: HasConfigAccess m => m Config

Get the config part for the currect script

getConfigInternal :: HasConfigAccess m => m Config

INTERNAL USE WITH CARE

Obtain the entire config structure

Types

type Topic = Text

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.

Internals

Values

defaultBotName :: Text

Functions

runDefinitions :: ScriptId -> ScriptDefinition a () -> a -> Config -> RunnerM (Script a)

Types

data BotActionState a d

Read only data available to a handler when the bot reacts to an event.

Constructors

BotActionState ScriptId Config a d

Instances

HasScriptId (BotActionState a0 d0) ScriptId

Methods

scriptId :: Lens' (BotActionState a0 d0) ScriptId

MonadReader (BotActionState a d) (BotReacting a d)

Methods

ask :: BotReacting a d (BotActionState a d)

local :: (BotActionState a d -> BotActionState a d) -> BotReacting a d a -> BotReacting a d a

reader :: (BotActionState a d -> a) -> BotReacting a d a

newtype 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 message handlers like hear and respond this would be a regex Match and a Message for instance.

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.

Constructors

BotReacting

Fields

• runReaction :: ReaderT (BotActionState a d) RunnerM r

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

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

HasConfigAccess (BotReacting a b)

Methods

getConfigInternal :: BotReacting a b Config

MonadReader (BotActionState a d) (BotReacting a d)

Methods

ask :: BotReacting a d (BotActionState a d)

local :: (BotActionState a d -> BotActionState a d) -> BotReacting a d a -> BotReacting a d a

reader :: (BotActionState a d -> a) -> BotReacting a d a

type AdapterT (BotReacting a b)

type AdapterT (BotReacting a b) = a

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.

Constructors

Script (Handlers a) ScriptId Config a

Instances

HasScriptId (Script a0) ScriptId

Methods

scriptId :: Lens' (Script a0) ScriptId

HasActions (Script a0) (Handlers a0)

Methods

actions :: Lens' (Script a0) (Handlers a0)

newtype ScriptDefinition a r

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

Constructors

ScriptDefinition

Fields

• runScript :: StateT (Script a) RunnerM r

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

AccessAdapter (ScriptDefinition a)

Associated Types

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

Methods

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

IsScript (ScriptDefinition a)

Methods

getScriptId :: ScriptDefinition a ScriptId

HasConfigAccess (ScriptDefinition a)

Methods

getConfigInternal :: ScriptDefinition a Config

type AdapterT (ScriptDefinition a)

type AdapterT (ScriptDefinition a) = a

newtype ScriptInit a

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

Constructors

ScriptInit (ScriptId, a -> Config -> RunnerM (Script a))

newtype ScriptId

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

Constructors

ScriptId

Fields

• unwrapScriptId :: Text

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

HasScriptId (Script a0) ScriptId

Methods

scriptId :: Lens' (Script a0) ScriptId

HasScriptId (BotActionState a0 d0) ScriptId

Methods

scriptId :: Lens' (BotActionState a0 d0) ScriptId

data Handlers a

Constructors

Handlers (Vector (Regex, (User' a, Channel' a, Match, Message, TimeStamp) -> RunnerM ())) (Vector (Regex, (User' a, Channel' a, Match, Message, TimeStamp) -> RunnerM ())) (Vector (Event a -> Maybe (RunnerM ()))) (Vector ((User' a, Channel' a, TimeStamp) -> RunnerM ())) (Vector ((User' a, Channel' a, TimeStamp) -> RunnerM ())) (Vector ((User' a, Channel' a, Topic, TimeStamp) -> RunnerM ())) (HashMap Text (Vector ((User' a, Channel' a, TimeStamp) -> RunnerM ()))) (HashMap Text (Vector ((User' a, Channel' a, TimeStamp) -> RunnerM ()))) (HashMap Text (Vector ((User' a, Channel' a, Topic, TimeStamp) -> RunnerM ())))

Instances

Monoid (Handlers a)

Methods

mempty :: Handlers a

mappend :: Handlers a -> Handlers a -> Handlers a

mconcat :: [Handlers a] -> Handlers a

HasTopicChange (Handlers a0) (Vector ((User' a0, Channel' a0, Topic, TimeStamp) -> RunnerM ()))

Methods

topicChange :: Lens' (Handlers a0) (Vector ((User' a0, Channel' a0, Topic, TimeStamp) -> RunnerM ()))

HasResponds (Handlers a0) (Vector (Regex, (User' a0, Channel' a0, Match, Message, TimeStamp) -> RunnerM ()))

Methods

responds :: Lens' (Handlers a0) (Vector (Regex, (User' a0, Channel' a0, Match, Message, TimeStamp) -> RunnerM ()))

HasLeaves (Handlers a0) (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ()))

Methods

leaves :: Lens' (Handlers a0) (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ()))

HasJoins (Handlers a0) (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ()))

Methods

joins :: Lens' (Handlers a0) (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ()))

HasHears (Handlers a0) (Vector (Regex, (User' a0, Channel' a0, Match, Message, TimeStamp) -> RunnerM ()))

Methods

hears :: Lens' (Handlers a0) (Vector (Regex, (User' a0, Channel' a0, Match, Message, TimeStamp) -> RunnerM ()))

HasCustoms (Handlers a0) (Vector (Event a0 -> Maybe (RunnerM ())))

Methods

customs :: Lens' (Handlers a0) (Vector (Event a0 -> Maybe (RunnerM ())))

HasActions (Script a0) (Handlers a0)

Methods

actions :: Lens' (Script a0) (Handlers a0)

HasTopicChangeIn (Handlers a0) (HashMap Text (Vector ((User' a0, Channel' a0, Topic, TimeStamp) -> RunnerM ())))

Methods

topicChangeIn :: Lens' (Handlers a0) (HashMap Text (Vector ((User' a0, Channel' a0, Topic, TimeStamp) -> RunnerM ())))

HasLeavesFrom (Handlers a0) (HashMap Text (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ())))

Methods

leavesFrom :: Lens' (Handlers a0) (HashMap Text (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ())))

HasJoinsIn (Handlers a0) (HashMap Text (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ())))

Methods

joinsIn :: Lens' (Handlers a0) (HashMap Text (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ())))

Helper lenses

class HasActions s a | s -> a where

Minimal complete definition

actions

Methods

actions :: Lens' s a

Instances

HasActions (Script a0) (Handlers a0)

Methods

actions :: Lens' (Script a0) (Handlers a0)

class HasHears s a | s -> a where

Minimal complete definition

hears

Methods

hears :: Lens' s a

Instances

HasHears (Handlers a0) (Vector (Regex, (User' a0, Channel' a0, Match, Message, TimeStamp) -> RunnerM ()))

Methods

hears :: Lens' (Handlers a0) (Vector (Regex, (User' a0, Channel' a0, Match, Message, TimeStamp) -> RunnerM ()))

class HasResponds s a | s -> a where

Minimal complete definition

responds

Methods

responds :: Lens' s a

Instances

HasResponds (Handlers a0) (Vector (Regex, (User' a0, Channel' a0, Match, Message, TimeStamp) -> RunnerM ()))

Methods

responds :: Lens' (Handlers a0) (Vector (Regex, (User' a0, Channel' a0, Match, Message, TimeStamp) -> RunnerM ()))

class HasJoins s a | s -> a where

Minimal complete definition

joins

Methods

joins :: Lens' s a

Instances

HasJoins (Handlers a0) (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ()))

Methods

joins :: Lens' (Handlers a0) (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ()))

class HasCustoms s a | s -> a where

Minimal complete definition

customs

Methods

customs :: Lens' s a

Instances

HasCustoms (Handlers a0) (Vector (Event a0 -> Maybe (RunnerM ())))

Methods

customs :: Lens' (Handlers a0) (Vector (Event a0 -> Maybe (RunnerM ())))

class HasJoinsIn s a | s -> a where

Minimal complete definition

joinsIn

Methods

joinsIn :: Lens' s a

Instances

HasJoinsIn (Handlers a0) (HashMap Text (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ())))

Methods

joinsIn :: Lens' (Handlers a0) (HashMap Text (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ())))

class HasLeaves s a | s -> a where

Minimal complete definition

leaves

Methods

leaves :: Lens' s a

Instances

HasLeaves (Handlers a0) (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ()))

Methods

leaves :: Lens' (Handlers a0) (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ()))

class HasLeavesFrom s a | s -> a where

Minimal complete definition

leavesFrom

Methods

leavesFrom :: Lens' s a

Instances

HasLeavesFrom (Handlers a0) (HashMap Text (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ())))

Methods

leavesFrom :: Lens' (Handlers a0) (HashMap Text (Vector ((User' a0, Channel' a0, TimeStamp) -> RunnerM ())))

class HasTopicChange s a | s -> a where

Minimal complete definition

topicChange

Methods

topicChange :: Lens' s a

Instances

HasTopicChange (Handlers a0) (Vector ((User' a0, Channel' a0, Topic, TimeStamp) -> RunnerM ()))

Methods

topicChange :: Lens' (Handlers a0) (Vector ((User' a0, Channel' a0, Topic, TimeStamp) -> RunnerM ()))

class HasTopicChangeIn s a | s -> a where

Minimal complete definition

topicChangeIn

Methods

topicChangeIn :: Lens' s a

Instances

HasTopicChangeIn (Handlers a0) (HashMap Text (Vector ((User' a0, Channel' a0, Topic, TimeStamp) -> RunnerM ())))

Methods

topicChangeIn :: Lens' (Handlers a0) (HashMap Text (Vector ((User' a0, Channel' a0, Topic, TimeStamp) -> RunnerM ())))

HelperClasses

class AccessAdapter m where

Minimal complete definition

getAdapter

Associated Types

type AdapterT m

Methods

getAdapter :: m (AdapterT m)

Instances

AccessAdapter (AdapterM a)

Associated Types

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

Methods

getAdapter :: AdapterM a (AdapterT (AdapterM a))

AccessAdapter (ScriptDefinition a)

Associated Types

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

Methods

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

AccessAdapter (BotReacting a b)

Associated Types

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

Methods

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

class Get a b where

Class which says that there is a way to get to a Message from this type m.

Minimal complete definition

getLens

Methods

getLens :: Lens' a b

Instances

Get (a, b, TimeStamp) TimeStamp

Methods

getLens :: Lens' (a, b, TimeStamp) TimeStamp

Get (a, Channel' b, c) (Channel' b)

Methods

getLens :: Lens' (a, Channel' b, c) (Channel' b)

Get (User' a, b, c) (User' a)

Methods

getLens :: Lens' (User' a, b, c) (User' a)

Get (a, b, Topic, d) Topic

Methods

getLens :: Lens' (a, b, Topic, d) Topic

Get (a, b, c, TimeStamp) TimeStamp

Methods

getLens :: Lens' (a, b, c, TimeStamp) TimeStamp

Get (a, Channel' b, c, d) (Channel' b)

Methods

getLens :: Lens' (a, Channel' b, c, d) (Channel' b)

Get (User' a, b, c, d) (User' a)

Methods

getLens :: Lens' (User' a, b, c, d) (User' a)

Get (a, b, c, Message, e) Message

Methods

getLens :: Lens' (a, b, c, Message, e) Message

Get (a, b, Match, d, e) Match

Methods

getLens :: Lens' (a, b, Match, d, e) Match

Get (a, b, c, d, TimeStamp) TimeStamp

Methods

getLens :: Lens' (a, b, c, d, TimeStamp) TimeStamp

Get (a, Channel' b, c, d, e) (Channel' b)

Methods

getLens :: Lens' (a, Channel' b, c, d, e) (Channel' b)

Get (User' a, b, c, d, e) (User' a)

Methods

getLens :: Lens' (User' a, b, c, d, e) (User' a)