-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A framework for modular, portable chat bots.
--   
--   A framework for writing portable chat bots. Inspired by hubot.
--   
--   The best way to get started with this library is with the
--   documentation on readthedocs: <a>https://marvin.readthedocs.io</a>
@package marvin
@version 0.2.2


module Marvin.Util.Regex

-- | Abstract Wrapper for a reglar expression implementation. Has an
--   <a>IsString</a> implementation, so literal strings can be used to
--   create a <a>Regex</a>. Alternatively use <a>r</a> to create one with
--   custom options.
data Regex

-- | A match to a <a>Regex</a>. Index 0 is the full match, all other
--   indices are match groups.
type Match = [Text]

-- | Compile a regex with options
--   
--   Normally it is sufficient to just write the regex as a plain string
--   and have it be converted automatically, but if you want certain match
--   options you can use this function.
r :: [MatchOption] -> Text -> Regex

-- | Match a regex against a string and return the first match found (if
--   any).
match :: Regex -> Text -> Maybe Match

-- | Options for controlling matching behaviour.
data MatchOption :: *

-- | Enable case insensitive matching.
CaseInsensitive :: MatchOption

-- | Allow comments and white space within patterns.
Comments :: MatchOption

-- | If set, <tt>'.'</tt> matches line terminators. Otherwise <tt>'.'</tt>
--   matching stops at line end.
DotAll :: MatchOption

-- | If set, treat the entire pattern as a literal string. Metacharacters
--   or escape sequences in the input sequence will be given no special
--   meaning.
--   
--   The option <a>CaseInsensitive</a> retains its meanings on matching
--   when used in conjunction with this option. Other options become
--   superfluous.
Literal :: MatchOption

-- | Control behaviour of <tt>'$'</tt> and <tt>'^'</tt>. If set, recognize
--   line terminators within string, Otherwise, match only at start and end
--   of input string.
Multiline :: MatchOption

-- | Haskell-only line endings. When this mode is enabled, only
--   <tt>'\n'</tt> is recognized as a line ending in the behavior of
--   <tt>'.'</tt>, <tt>'^'</tt>, and <tt>'$'</tt>.
HaskellLines :: MatchOption

-- | Unicode word boundaries. If set, <tt>'\\b'</tt> uses the Unicode TR 29
--   definition of word boundaries.
--   
--   <i>Warning</i>: Unicode word boundaries are quite different from
--   traditional regular expression word boundaries. See
--   <a>http://unicode.org/reports/tr29/#Word_Boundaries</a>.
UnicodeWord :: MatchOption

-- | Throw an error on unrecognized backslash escapes. If set, fail with an
--   error on patterns that contain backslash-escaped ASCII letters without
--   a known special meaning. If this flag is not set, these escaped
--   letters represent themselves.
ErrorOnUnknownEscapes :: MatchOption

-- | Set a processing limit for match operations.
--   
--   Some patterns, when matching certain strings, can run in exponential
--   time. For practical purposes, the match operation may appear to be in
--   an infinite loop. When a limit is set a match operation will fail with
--   an error if the limit is exceeded.
--   
--   The units of the limit are steps of the match engine. Correspondence
--   with actual processor time will depend on the speed of the processor
--   and the details of the specific pattern, but will typically be on the
--   order of milliseconds.
--   
--   By default, the matching time is not limited.
WorkLimit :: Int -> MatchOption

-- | Set the amount of heap storage avaliable for use by the match
--   backtracking stack.
--   
--   ICU uses a backtracking regular expression engine, with the backtrack
--   stack maintained on the heap. This function sets the limit to the
--   amount of memory that can be used for this purpose. A backtracking
--   stack overflow will result in an error from the match operation that
--   caused it.
--   
--   A limit is desirable because a malicious or poorly designed pattern
--   can use excessive memory, potentially crashing the process. A limit is
--   enabled by default.
StackLimit :: Int -> MatchOption
instance Control.DeepSeq.NFData Marvin.Util.Regex.Regex
instance GHC.Show.Show Marvin.Util.Regex.Regex
instance Data.String.IsString Marvin.Util.Regex.Regex


module Marvin.Util.Random

-- | Generate a random value. For more information see <a>random</a>
randomVal :: (MonadIO m, Random a) => m a

-- | Generate a random value frbounded by a range. See <a>randomR</a> for
--   how the range works.
randomValFromRange :: (MonadIO m, Random a) => (a, a) -> m a

-- | Get a random value out of an integer indexed sequence, like
--   (<tt>Vector</tt>, '[a]', <tt>Seq</tt> or <tt>Set</tt>) This uses the
--   sequences <a>length</a> and therefore does not terminate for infinite
--   sequences.
--   
--   Uses the global random number generator.
--   
--   Usable in all IO capable monads, such as <tt>BotReacting</tt> and
--   <tt>ScriptDefinition</tt>.
randomFrom :: MonadIO m => [e] -> m e


module Marvin.Util.Mutable

-- | A mutable reference to a value of type <tt>v</tt>
--   
--   This is like a pointer in c, the value behind which can be mutated by
--   several functions. So long as they retain this reference they are able
--   to retrieve the updated value.
type Mutable v = IORef v

-- | Create a new mutable reference of type <tt>v</tt> from an initial
--   value.
newMutable :: MonadIO m => a -> m (Mutable a)

-- | Retrieve the value behind by a mutable reference.
readMutable :: MonadIO m => Mutable a -> m a

-- | Set the value inside a mutable reference.
writeMutable :: MonadIO m => Mutable a -> a -> m ()

-- | Change the value behind a mutable reference.
modifyMutable :: MonadIO m => Mutable a -> (a -> a) -> m ()

-- | A value that can be shared on multiple concurrent Threads.
--   
--   This value works like a channel. It can either be empty or full. If it
--   is empty <a>writeSynchronized</a> fills it, otherwise the write
--   blocks. If it is full <a>takeSynchronized</a> empties, otherwise it
--   blocks until it is filled. <a>readSynchronized</a> does not empty it
--   and also blocks if the <a>Synchronized</a> is empty.
--   
--   Should you just use it as a thread safe mutable variable, mutations
--   typically follow the pattern:
--   
--   <pre>
--   val &lt;- takeSynchronized -- obtain the value and leave it empty to block concurrent reads
--   mod &lt;- modifyWithIO val -- modify the value, typically involves IO
--   writeSynchronized mod -- write back the result
--   </pre>
--   
--   Another use for this type is as a message channel, where we have a
--   producer and a consumer, the producer tries to write values into the
--   <a>Synchronized</a> (<a>writeSynchronized</a>) and the consumer waits
--   for the <a>Synchronized</a> to be filled and takes the value
--   (<a>takeSynchronized</a>) for procesing.
--   
--   It works generally best if any <a>Synchronized</a> is only used for
--   one of these two applications at the same time.
--   
--   This type is the same as <a>MVar</a>, only renamed for readability. If
--   you want a more in depth documentation, see the documentation for
--   <a>MVar</a>.
type Synchronized = MVar

-- | Read the vaue, but don't empty the <a>Synchronized</a>. Blocks if it
--   is empty.
readSynchronized :: MonadIO m => Synchronized a -> m a

-- | Non blocking version of <a>readSynchronized</a>. Returns
--   <a>Nothing</a> if it was empty.
tryReadSynchronized :: MonadIO m => Synchronized a -> m (Maybe a)

-- | Read the value and empty the <a>Synchronized</a>, blocks if already
--   empty.
takeSynchronized :: MonadIO m => Synchronized a -> m a

-- | Non blocking version of <a>takeSynchronized</a>, returns
--   <a>Nothing</a> if it was empty.
tryTakeSynchronized :: MonadIO m => Synchronized a -> m (Maybe a)

-- | Fills the empty <a>Synchronized</a> with a value, blocks if it is
--   full.
writeSynchronized :: MonadIO m => Synchronized a -> a -> m ()

-- | Non blocking version of <a>writeSynchronized</a>. Returns <a>False</a>
--   if it was full.
tryWriteSynchronized :: MonadIO m => Synchronized a -> a -> m Bool

-- | Query if the <a>Synchronized</a> is empty or full.
isEmptySynchronized :: MonadIO m => Synchronized a -> m Bool


-- | This is provisionary, this might get properly wrapped at some point.
module Marvin.Util.JSON

-- | Read a file containing JSON encoded data
readJSON :: (MonadIO m, FromJSON a) => FilePath -> m (Either String a)

-- | Write some data to a file using JSON serialization
writeJSON :: (MonadIO m, ToJSON a) => FilePath -> a -> m ()


module Marvin.Util.HTTP


module Marvin.Types

-- | The contents of a recieved message
type Message = Text

-- | 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.
data Script a_aufx

-- | A type, basically a String, which identifies a script to the config
--   and the logging facilities.
--   
--   For conversion please use <a>mkScriptId</a> and <a>unwrapScriptId</a>.
--   They will perform necessary checks.
data ScriptId

-- | Attempt to create a script id from <tt>Text</tt>
mkScriptId :: Text -> Either String ScriptId
unwrapScriptId :: ScriptId -> Text

-- | Script id sed for the bot itself
applicationScriptId :: ScriptId

-- | Similar to <a>AccessAdapter</a>, this class says there is a
--   <a>ScriptId</a> reachable from the type (usually a monad) <tt>m</tt>.
class IsScript m

-- | Retrieve the script id out of <tt>m</tt>, ususally a monad.
getScriptId :: IsScript m => m ScriptId

-- | Retrieve the script id out of <tt>m</tt>, ususally a monad.
getScriptId :: IsScript m => m ScriptId

-- | Denotes a place from which we may access the configuration.
--   
--   During script definition or when handling a request we can obtain the
--   config with <tt>getConfigVal</tt> or <tt>requireConfigVal</tt>.
class (IsScript m, MonadIO m) => HasConfigAccess m

-- | A timestamp type. Supplied with most <a>Event</a> types
newtype TimeStamp
TimeStamp :: UTCTime -> TimeStamp
[unwrapTimeStamp] :: TimeStamp -> UTCTime

-- | Similar to <a>IsScript</a>, this class says that there is an adapter
--   <a>AdapterT</a> available from this type (usually a monad) <tt>m</tt>.
--   
--   The type of adapter depends on the monad itself. This class can be
--   thought of as <a>MonadReader</a> specified to <a>AdapterT</a>.
class AccessAdapter m where type AdapterT m where {
    type family AdapterT m;
}

-- | Wrapping type for users. Only used to enable <a>Get</a> typeclass
--   instances.
newtype User' a
User' :: User a -> User' a
[unwrapUser'] :: User' a -> User a

-- | Wrapping type for channels. Only used to enable <a>Get</a> typeclass
--   instances.
newtype Channel' a
Channel' :: Channel a -> Channel' a
[unwrapChannel'] :: Channel' a -> Channel a

-- | Class which says that there is a way to get to <tt>b</tt> from this
--   type <tt>a</tt>.
--   
--   This typeclass is used to allow handlers with different types of
--   payload to share common accessor functions such as <a>getUser</a> and
--   <a>getMessage</a>.
--   
--   The instances specify for each type of payload which pieces of data
--   can be extracted and how.
class Get a b
getLens :: Get a b => Lens' a b

-- | Representation for the types of events which can occur
data Event a
MessageEvent :: (User a) -> (Channel a) -> Message -> TimeStamp -> Event a
CommandEvent :: (User a) -> (Channel a) -> Message -> TimeStamp -> Event a
ChannelJoinEvent :: (User a) -> (Channel a) -> TimeStamp -> Event a
ChannelLeaveEvent :: (User a) -> (Channel a) -> TimeStamp -> Event a
TopicChangeEvent :: (User a) -> (Channel a) -> Topic -> TimeStamp -> Event a

-- | Basic monad which most internal actions run in
type RunnerM = LoggingT IO

-- | Read only data available to a handler when the bot reacts to an event.
data BotActionState a_atqZ d_atr0
class HasScriptId s a | s -> a
scriptId :: HasScriptId s a => Lens' s a
class HasAdapter s a | s -> a
adapter :: HasAdapter s a => Lens' s a
class HasPayload s a | s -> a
payload :: HasPayload s a => Lens' s a
class HasActions s a | s -> a
actions :: HasActions s a => Lens' s a


module Marvin.Adapter
type RunWithAdapter a = EventHandler a -> AdapterM a ()
type EventHandler a = Event a -> IO ()

-- | Basic functionality required of any adapter
class IsAdapter a where type User a type Channel a where {
    type family User a;
    type family Channel a;
}

-- | Used for scoping config and logging
adapterId :: IsAdapter a => AdapterId a

-- | Post a message to a channel given the internal channel identifier
messageChannel :: IsAdapter a => Channel a -> Text -> AdapterM a ()

-- | Initialize the adapter state
initAdapter :: IsAdapter a => RunnerM a

-- | Run the bot
runWithAdapter :: IsAdapter a => RunWithAdapter a

-- | Resolve a username given the internal user identifier
getUsername :: IsAdapter a => User a -> AdapterM a Text

-- | Resolve the human readable name for a channel given the internal
--   channel identifier
getChannelName :: IsAdapter a => Channel a -> AdapterM a Text

-- | Resolve to the internal channel structure given a human readable name
resolveChannel :: IsAdapter a => Text -> AdapterM a (Maybe (Channel a))

-- | Resolve to the internal user structure given a human readable name
resolveUser :: IsAdapter a => Text -> AdapterM a (Maybe (User a))

-- | A type, basically a String, which identifies an adapter to the config
--   and the logging facilities.
--   
--   For conversion please use <a>mkAdapterId</a> and
--   <a>unwrapAdapterId</a>. They will perform necessary checks.
data AdapterId a

-- | Attempt to create an adapter id from <tt>Text</tt>
mkAdapterId :: Text -> Either String (AdapterId a)
unwrapAdapterId :: AdapterId a -> Text

-- | Monad in which adapter actions run in
data AdapterM a r

-- | Representation for the types of events which can occur
data Event a
MessageEvent :: (User a) -> (Channel a) -> Message -> TimeStamp -> Event a
CommandEvent :: (User a) -> (Channel a) -> Message -> TimeStamp -> Event a
ChannelJoinEvent :: (User a) -> (Channel a) -> TimeStamp -> Event a
ChannelLeaveEvent :: (User a) -> (Channel a) -> TimeStamp -> Event a
TopicChangeEvent :: (User a) -> (Channel a) -> Topic -> TimeStamp -> Event a
lookupFromAdapterConfig :: (IsAdapter a, Configured v) => Name -> AdapterM a (Maybe v)
requireFromAdapterConfig :: (IsAdapter a, Configured v) => Name -> AdapterM a v
lookupFromAppConfig :: Configured v => Name -> AdapterM a (Maybe v)
requireFromAppConfig :: Configured v => Name -> AdapterM a v
getBotname :: AdapterM a Text
getAdapterConfig :: forall a. IsAdapter a => AdapterM a Config
getAppConfig :: AdapterM a Config
getAdapter :: AccessAdapter m => m (AdapterT m)
liftAdapterAction :: (MonadIO m, HasConfigAccess m, AccessAdapter m, IsAdapter a, a ~ AdapterT m) => AdapterM a r -> m r


-- | See caveats and potential issues with this adapter here
--   <a>https://marvin.readthedocs.io/en/latest/adapters.html#irc</a>.
module Marvin.Adapter.IRC
data IRCAdapter
data IRCChannel
instance Marvin.Internal.Types.IsAdapter Marvin.Adapter.IRC.IRCAdapter


module Marvin.Adapter.Shell

-- | Adapter for a shell prompt
data ShellAdapter
instance Marvin.Internal.Types.IsAdapter Marvin.Adapter.Shell.ShellAdapter


module Marvin.Adapter.Slack.EventsAPI

-- | Adapter for interacting with Slack API's. Polymorphic over the method
--   for retrieving events.
data SlackAdapter a

-- | Recieve events as a server via HTTP webhook (not implemented yet)
data EventsAPI

-- | Identifier for a user (internal and not equal to the username)
data SlackUserId

-- | Identifier for a channel (internal and not equal to the channel name)
data SlackChannelId

-- | Class to enable polymorphism for <a>SlackAdapter</a> over the method
--   used for retrieving updates. (<tt>RTM</tt> or <tt>EventsAPI</tt>)
class MkSlack a
instance Marvin.Adapter.Slack.Common.MkSlack Marvin.Adapter.Slack.EventsAPI.EventsAPI


module Marvin.Adapter.Slack.RTM

-- | Adapter for interacting with Slack API's. Polymorphic over the method
--   for retrieving events.
data SlackAdapter a

-- | Recieve events by opening a websocket to the Real Time Messaging API
data RTM

-- | Identifier for a user (internal and not equal to the username)
data SlackUserId

-- | Identifier for a channel (internal and not equal to the channel name)
data SlackChannelId

-- | Class to enable polymorphism for <a>SlackAdapter</a> over the method
--   used for retrieving updates. (<tt>RTM</tt> or <tt>EventsAPI</tt>)
class MkSlack a
instance Marvin.Adapter.Slack.Common.MkSlack Marvin.Adapter.Slack.RTM.RTM


-- | <h3>Caveats:</h3>
--   
--   <a>resolveUser</a> and <a>resolveChannel</a> resolving are not yet
--   supported in this adapter and always returns <a>Nothing</a>. See
--   <a>#10</a>.
module Marvin.Adapter.Telegram.Poll

-- | The telegram adapter type for a particular update type. Either
--   <tt>Push</tt> or <tt>Poll</tt>
data TelegramAdapter updateType

-- | Use the telegram API by fetching updates via HTTP
data Poll

-- | A telegram chat object as contained in telegram updates
data TelegramChat
TelegramChat :: Integer -> ChatType -> (Maybe Text) -> (Maybe Text) -> (Maybe Text) -> TelegramChat

-- | Chat type as defined by the telegram api
data ChatType
PrivateChat :: ChatType
GroupChat :: ChatType
SupergroupChat :: ChatType
ChannelChat :: ChatType

-- | A user object as contained in the telegram update objects
data TelegramUser
TelegramUser :: Integer -> Text -> (Maybe Text) -> (Maybe Text) -> TelegramUser

-- | Class to enable polymorphism over update mechanics for
--   <a>TelegramAdapter</a>
class MkTelegram a
class HasUsername s a | s -> a
username :: HasUsername s a => Lens' s a
class HasLastName s a | s -> a
lastName :: HasLastName s a => Lens' s a
class HasId_ s a | s -> a
id_ :: HasId_ s a => Lens' s a
class HasFirstName s a | s -> a
firstName :: HasFirstName s a => Lens' s a
class HasType_ s a | s -> a
type_ :: HasType_ s a => Lens' s a
instance Data.Aeson.Types.FromJSON.FromJSON Marvin.Adapter.Telegram.Poll.UpdateWithId
instance Marvin.Adapter.Telegram.Common.MkTelegram Marvin.Adapter.Telegram.Poll.Poll


-- | <h3>Caveats:</h3>
--   
--   <a>resolveUser</a> and <a>resolveChannel</a> resolving are not yet
--   supported in this adapter and always returns <a>Nothing</a>. See
--   <a>#10</a>.
module Marvin.Adapter.Telegram.Push

-- | The telegram adapter type for a particular update type. Either
--   <tt>Push</tt> or <tt>Poll</tt>
data TelegramAdapter updateType

-- | Use the telegram API by recieving updates as a server via webhook
--   
--   Note: The initialization for this adapter _includes_ registering or
--   clearing its own webhook.
data Push

-- | A telegram chat object as contained in telegram updates
data TelegramChat
TelegramChat :: Integer -> ChatType -> (Maybe Text) -> (Maybe Text) -> (Maybe Text) -> TelegramChat

-- | Chat type as defined by the telegram api
data ChatType
PrivateChat :: ChatType
GroupChat :: ChatType
SupergroupChat :: ChatType
ChannelChat :: ChatType

-- | A user object as contained in the telegram update objects
data TelegramUser
TelegramUser :: Integer -> Text -> (Maybe Text) -> (Maybe Text) -> TelegramUser

-- | Class to enable polymorphism over update mechanics for
--   <a>TelegramAdapter</a>
class MkTelegram a
class HasUsername s a | s -> a
username :: HasUsername s a => Lens' s a
class HasLastName s a | s -> a
lastName :: HasLastName s a => Lens' s a
class HasId_ s a | s -> a
id_ :: HasId_ s a => Lens' s a
class HasFirstName s a | s -> a
firstName :: HasFirstName s a => Lens' s a
class HasType_ s a | s -> a
type_ :: HasType_ s a => Lens' s a
instance Marvin.Adapter.Telegram.Common.MkTelegram Marvin.Adapter.Telegram.Push.Push


module Marvin.Run

-- | Runs the marvin bot using whatever method the adapter uses.
runMarvin :: forall a. IsAdapter a => [ScriptInit a] -> IO ()

-- | Initializer for a script. This gets run by the server during startup
--   and creates a <a>Script</a>
data ScriptInit a

-- | Basic functionality required of any adapter
class IsAdapter a

-- | Retrieve a value from the application config, given the whole config
--   structure. Fails if value not parseable as <tt>a</tt> or not present.
requireFromAppConfig :: Configured a => Config -> Name -> IO a

-- | Retrieve a value from the application config, given the whole config
--   structure. Returns <a>Nothing</a> if value not parseable as <tt>a</tt>
--   or not present.
lookupFromAppConfig :: Configured a => Config -> Name -> IO (Maybe a)

-- | Default name for the config file
defaultConfigName :: FilePath


-- | For the proper, verbose documentation see
--   <a>https://marvin.readthedocs.org/en/latest/scripting.html</a>.
module Marvin

-- | 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.
data Script a_aufx

-- | Define a new script for marvin
--   
--   You need to provide a ScriptId (which can be written as a non-empty
--   string, needs the <tt>OverloadedStrings</tt> 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.
defineScript :: ScriptId -> ScriptDefinition a () -> ScriptInit a

-- | Initializer for a script. This gets run by the server during startup
--   and creates a <a>Script</a>
data ScriptInit a

-- | A type, basically a String, which identifies a script to the config
--   and the logging facilities.
--   
--   For conversion please use <a>mkScriptId</a> and <a>unwrapScriptId</a>.
--   They will perform necessary checks.
data ScriptId

-- | A monad for gradually defining a <a>Script</a> using <a>respond</a>
--   and <a>hear</a> as well as any <a>IO</a> action.
data ScriptDefinition a r

-- | Basic functionality required of any adapter
class IsAdapter a where type User a type Channel a where {
    type family User a;
    type family Channel a;
}

-- | Monad for reacting in the bot. Allows use of functions like
--   <a>send</a>, <a>reply</a> and <a>messageChannel</a> as well as any
--   arbitrary <a>IO</a> action using <a>liftIO</a>.
--   
--   The type parameter <tt>d</tt> is the accessible data provided by the
--   trigger for this action and can be obtained with <a>getData</a> or
--   other custom functions like <a>getMessage</a> and <a>getMatch</a>
--   which typically depend on a particular type of data in <tt>d</tt>.
--   
--   For completeness: <tt>a</tt> is the adapter type and <tt>r</tt> is the
--   return type of the monadic computation.
--   
--   This is also a <a>MonadReader</a> 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.
data BotReacting a d r

-- | Whenever any message matches the provided regex this handler gets run.
--   
--   Equivalent to "robot.hear" in hubot
hear :: 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
respond :: Regex -> BotReacting a (User' a, Channel' a, Match, Message, TimeStamp) () -> ScriptDefinition a ()

-- | This handler runs whenever a user enters <b>any channel</b> (which the
--   bot is subscribed to)
--   
--   The payload contains the entering user and the channel which was
--   entered.
enter :: BotReacting a (User' a, Channel' a, TimeStamp) () -> ScriptDefinition a ()

-- | This handler runs whenever a user exits <b>any channel</b> (which the
--   bot is subscribed to)
--   
--   The payload contains the exiting user and the channel which was
--   exited.
exit :: BotReacting a (User' a, Channel' a, TimeStamp) () -> ScriptDefinition a ()

-- | This handler runs whenever a user enters <b>the specified channel</b>.
--   
--   The argument is the human readable name for the channel.
--   
--   The payload contains the entering user.
enterIn :: Text -> BotReacting a (User' a, Channel' a, TimeStamp) () -> ScriptDefinition a ()

-- | This handler runs whenever a user exits <b>the specified channel</b>,
--   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.
exitFrom :: Text -> BotReacting a (User' a, Channel' a, TimeStamp) () -> ScriptDefinition a ()

-- | This handler runs when the topic in <b>any channel</b> the bot is
--   subscribed to changes.
--   
--   The payload contains the new topic and the channel in which it was
--   set.
topic :: BotReacting a (User' a, Channel' a, Topic, TimeStamp) () -> ScriptDefinition a ()

-- | This handler runs when the topic in <b>the specified channel</b> is
--   changed, provided the bot is subscribed to the channel in question.
--   
--   The argument is the human readable channel name.
topicIn :: Text -> BotReacting a (User' a, Channel' a, Topic, TimeStamp) () -> ScriptDefinition a ()

-- | Extension point for the user
--   
--   Allows you to handle the raw event yourself. Returning <a>Nothing</a>
--   from the trigger function means you dont want to react to the event.
--   The value returned inside the <a>Just</a> is available in the handler
--   later using <a>getData</a>.
customTrigger :: (Event a -> Maybe d) -> BotReacting a d () -> ScriptDefinition a ()

-- | Obtain the event reaction data.
--   
--   The type of this data depends on the reaction function used. For
--   instance <a>hear</a> and <a>respond</a> will contain
--   <tt>MessageReactionData</tt>. The actual contents comes from the event
--   itself and was put together by the trigger.
getData :: BotReacting a d d

-- | Get the message that triggered this action Includes sender, target
--   channel, as well as the full, untruncated text of the original message
getMessage :: Get m Message => BotReacting a m Message

-- | Get the results from matching the regular expression.
--   
--   Equivalent to "msg.match" in hubot.
getMatch :: Get m Match => BotReacting a m Match

-- | Get the the new topic.
getTopic :: Get m Topic => BotReacting a m Topic

-- | Get the stored channel in which something happened.
getChannel :: forall a m. Get m (Channel' a) => BotReacting a m (Channel a)

-- | Get the user which was part of the triggered action.
getUser :: forall m a. Get m (User' a) => BotReacting a m (User a)

-- | Get the username of a registered user. The type signature is so large
--   to allow this function to be used both in <a>BotReacting</a> and
--   <a>ScriptDefinition</a>.
getUsername :: (HasConfigAccess m, AccessAdapter m, IsAdapter a, MonadIO m, AdapterT m ~ a) => User 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 <a>BotReacting</a> and
--   <a>ScriptDefinition</a>.
getChannelName :: (HasConfigAccess m, AccessAdapter m, IsAdapter a, MonadIO m, AdapterT m ~ a) => Channel a -> m Text

-- | Try to get the user with a particular username. The type signature is
--   so large to allow this function to be used both in <a>BotReacting</a>
--   and <a>ScriptDefinition</a>.
resolveUser :: (HasConfigAccess m, AccessAdapter m, IsAdapter a, MonadIO m, AdapterT m ~ a) => Text -> m (Maybe (User 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
--   <a>BotReacting</a> and <a>ScriptDefinition</a>.
resolveChannel :: (HasConfigAccess m, AccessAdapter m, IsAdapter a, MonadIO m, AdapterT m ~ a) => Text -> m (Maybe (Channel a))

-- | Send a message to the channel the triggering message came from.
--   
--   Equivalent to "robot.send" in hubot
send :: (IsAdapter 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
reply :: (IsAdapter a, Get d (User' a), Get d (Channel' a)) => Text -> BotReacting a d ()

-- | Send a message to a Channel (by name)
messageChannel :: (HasConfigAccess m, AccessAdapter m, IsAdapter (AdapterT m), MonadLoggerIO m) => Text -> Text -> m ()

-- | Send a message to a channel (by adapter dependent channel object)
messageChannel' :: (HasConfigAccess m, AccessAdapter m, IsAdapter (AdapterT m), MonadIO m) => Channel (AdapterT m) -> Text -> m ()

-- | Get a value out of the config, returns <a>Nothing</a> 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 <a>HasConfigAccess</a> Constraint means this function can be used
--   both during script definition and when a handler is run.
getConfigVal :: (Configured a, HasConfigAccess m) => Name -> m (Maybe 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 <a>HasConfigAccess</a> 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 the configured name of the bot.
getBotName :: HasConfigAccess m => m Text

-- | The contents of a recieved message
type Message = Text

-- | The topic in a channel
type Topic = Text

-- | 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.
extractAction :: BotReacting a () o -> ScriptDefinition a (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.
extractReaction :: BotReacting a s o -> BotReacting a s (IO o)


module Marvin.Prelude

-- | <b>i</b>nterpolate <b>s</b>plice to <b>L</b>azy Text
--   
--   Template Haskell splice function, used like <tt>$(isL "my str
--   #{expr}")</tt>
--   
--   converts all expressions to <a>Text</a> by calling <a>showL</a> on the
--   result.
isL :: String -> Q Exp

-- | <b>i</b>nterpolate <b>s</b>plice to <b>T</b>ext
--   
--   Template Haskell splice function, used like <tt>$(isT "my str
--   #{expr}")</tt>
--   
--   converts all expressions to <a>Text</a> by calling <a>showT</a> on the
--   result.
isT :: String -> Q Exp

-- | <b>i</b>nterpolate <b>s</b>plice to <b>S</b>tring
--   
--   Template Haskell splice function, used like <tt>$(isS "my str
--   #{expr}")</tt>
--   
--   converts all expressions to <a>String</a> by calling <a>showStr</a> on
--   the result.
isS :: String -> Q Exp

-- | Monads in which <a>IO</a> computations may be embedded. Any monad
--   built by applying a sequence of monad transformers to the <a>IO</a>
--   monad will be an instance of this class.
--   
--   Instances should satisfy the following laws, which state that
--   <a>liftIO</a> is a transformer of monads:
--   
--   <ul>
--   <li><pre><a>liftIO</a> . <a>return</a> = <a>return</a></pre></li>
--   <li><pre><a>liftIO</a> (m &gt;&gt;= f) = <a>liftIO</a> m &gt;&gt;=
--   (<a>liftIO</a> . f)</pre></li>
--   </ul>
class Monad m => MonadIO (m :: * -> *)

-- | Lift a computation from the <a>IO</a> monad.
liftIO :: MonadIO m => IO a -> m a

-- | Lift a computation from the <a>IO</a> monad.
liftIO :: MonadIO m => forall a. IO a -> m a

-- | Conditional execution of <a>Applicative</a> expressions. For example,
--   
--   <pre>
--   when debug (putStrLn "Debugging")
--   </pre>
--   
--   will output the string <tt>Debugging</tt> if the Boolean value
--   <tt>debug</tt> is <a>True</a>, and otherwise do nothing.
when :: Applicative f => Bool -> f () -> f ()

-- | The reverse of <a>when</a>.
unless :: Applicative f => Bool -> f () -> f ()

-- | <a>for</a> is <a>traverse</a> with its arguments flipped. For a
--   version that ignores the results see <a>for_</a>.
for :: (Traversable t, Applicative f) => t a -> (a -> f b) -> f (t b)

-- | <a>for_</a> is <a>traverse_</a> with its arguments flipped. For a
--   version that doesn't ignore the results see <a>for</a>.
--   
--   <pre>
--   &gt;&gt;&gt; for_ [1..4] print
--   1
--   2
--   3
--   4
--   </pre>
for_ :: (Foldable t, Applicative f) => t a -> (a -> f b) -> f ()

-- | The <a>fromMaybe</a> function takes a default value and and
--   <a>Maybe</a> value. If the <a>Maybe</a> is <a>Nothing</a>, it returns
--   the default values; otherwise, it returns the value contained in the
--   <a>Maybe</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybe "" (Just "Hello, World!")
--   "Hello, World!"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybe "" Nothing
--   ""
--   </pre>
--   
--   Read an integer from a string using <tt>readMaybe</tt>. If we fail to
--   parse an integer, we want to return <tt>0</tt> by default:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; fromMaybe 0 (readMaybe "5")
--   5
--   
--   &gt;&gt;&gt; fromMaybe 0 (readMaybe "")
--   0
--   </pre>
fromMaybe :: a -> Maybe a -> a