diff --git a/haskbot-core.cabal b/haskbot-core.cabal --- a/haskbot-core.cabal +++ b/haskbot-core.cabal @@ -1,5 +1,5 @@ name: haskbot-core -version: 0.0.1.0 +version: 0.0.1.1 maintainer: Jonathan Childress homepage: https://github.com/jonplussed/haskbot-core diff --git a/src/Network/Haskbot.hs b/src/Network/Haskbot.hs --- a/src/Network/Haskbot.hs +++ b/src/Network/Haskbot.hs @@ -1,18 +1,10 @@ --- | Module : Network.Haskbot --- Description : An easily-extensible Slack chatbot server --- Copyright : (c) Jonathan Childress 2014 --- License : MIT --- Maintainer : jon@childr.es --- Stability : experimental --- Portability : POSIX --- --- A minimal Haskbot server can be run via: +-- | A minimal Haskbot server can be run via: -- -- > {-# LANGUAGE OverloadedStrings #-} -- > -- > import Network.Haskbot -- > import Network.Haskbot.Plugin --- > import qualified Slack.Haskbot.Plugin.Help as Help +-- > import qualified Network.Haskbot.Plugin.Help as Help -- > -- > main :: IO () -- > main = haskbot registry 3000 @@ -21,9 +13,9 @@ -- > registry = [ Help.register registry "my_secret_token" ] -- -- This will run Haskbot on port 3000 with the included --- "Help" plugin installed, where @\"my_secret_token\"@ is the secret token --- of a Slack slash command integration corresponding to the @/haskbot@ --- command and pointing to the Haskbot server. +-- "Network.Haskbot.Plugin.Help" plugin installed, where @\"my_secret_token\"@ +-- is the secret token of a Slack slash command integration corresponding to +-- the @/haskbot@ command and pointing to the Haskbot server. -- -- Be sure to create a Slack incoming integration (usually named /Haskbot/) -- with the local @HASKBOT_ENDPOINT@ environment variable set to the diff --git a/src/Network/Haskbot/Incoming.hs b/src/Network/Haskbot/Incoming.hs --- a/src/Network/Haskbot/Incoming.hs +++ b/src/Network/Haskbot/Incoming.hs @@ -1,12 +1,4 @@ --- | Module : Network.Haskbot.Incoming --- Description : Wrapper for the Slack API /incoming/ integration --- Copyright : (c) Jonathan Childress 2014 --- License : MIT --- Maintainer : jon@childr.es --- Stability : experimental --- Portability : POSIX --- --- This provides a simple representation of the request data for a Slack +-- | This provides a simple representation of the request data for a Slack -- /incoming/ integration- the means via which Haskbot replies to Slack. -- Currently only simple text replies are supported, but this will be expanded -- to support fully-slack-formatted messages in the future. diff --git a/src/Network/Haskbot/Plugin.hs b/src/Network/Haskbot/Plugin.hs --- a/src/Network/Haskbot/Plugin.hs +++ b/src/Network/Haskbot/Plugin.hs @@ -1,24 +1,15 @@ --- | Module : Network.Haskbot.Plugin --- Description : Everything needed to create a Haskbot plugin --- Copyright : (c) Jonathan Childress 2014 --- License : MIT --- Maintainer : jon@childr.es --- Stability : experimental --- Portability : POSIX --- --- Haskbot plugins are functions returning a "Plugin" data type. The "Plugin" +-- | Haskbot plugins are functions returning a 'Plugin' data type. The 'Plugin' -- type is not exported directly; you should create new plugins via -- 'newPlugin'. -- -- The recommended process for exporting plugins is to create a new module -- that exports a single function currying the first three arguments to --- 'newPlugin'. The remaining argument, the Slack secret token of the --- corresponding Slack /slash command/ service integration, can be supplied --- in a separate file exporting the list of installed commands for "Haskbot". --- This enables you to recreate a registry of installed tokens and +-- 'newPlugin'. The remaining argument, the Slack secret token, can be +-- supplied in a separate file exporting the list of installed commands for +-- Haskbot. This enables you to recreate a registry of installed tokens and -- corresponding secret tokens in a separate file outside of version control. -- --- A basic /Hello World/ plugin can created via: +-- A basic /Hello World/ plugin can be created via: -- -- > {-# LANGUAGE OverloadedStrings #-} -- > @@ -41,21 +32,20 @@ -- To run the plugin, create a new Slack /slash command/ integration -- corresponding to the command @\/hello_world@ that points to your Haskbot -- server. Add the plugin's @register@ function to your Haskbot server's --- plugin registry like detailed in "Slack.Haskbot", giving it the Slack +-- plugin registry like detailed in "Network.Haskbot", giving it the Slack -- integration's secret token as the remaining argument. Rebuild and run the -- server. Typing @\/hello_word@ into any Slack channel should return a --- Haskbot response of /Hellow, world!/ +-- Haskbot response of /Hello, world!/ module Network.Haskbot.Plugin ( --- * Plugins - Plugin --- ** PLugin components -, plCommand, plHelpText, plHandler, plToken --- ** Type aliases +-- * The Plugin type + Plugin (..) +-- * Creating Plugins +-- ** Helpful Type aliases , NameStr, HelpStr, HandlerFn, TokenStr -- ** Creating a new Plugin , newPlugin --- * Slack replies +-- * Common Slack replies , replySameChan, replyAsDM ) where @@ -65,26 +55,30 @@ import Network.Haskbot.Internal.SlashCommand (SlashCom (..)) import Network.Haskbot.Types -data Plugin = Plugin { plCommand :: {-# UNPACK #-} !Command - , plHelpText :: {-# UNPACK #-} !Text - , plHandler :: !HandlerFn - , plToken :: {-# UNPACK #-} !Token - } +data Plugin = + Plugin { plCommand :: {-# UNPACK #-} !Command + -- ^ The command that invokes this plugin + , plHelpText :: {-# UNPACK #-} !Text + -- ^ Help text displayed for this plugin via + -- "Network.Haskbot.Plugin.Help" + , plHandler :: !HandlerFn + -- ^ The function that receives a "Network.Haskbot.SlashCommand" + -- and maybe returns a "Network.Haskbot.Incoming" + , plToken :: {-# UNPACK #-} !Token + -- ^ The secret token corresponding with this plugin's /slash command/ + -- Slack integration + } type NameStr = Text type HelpStr = Text type HandlerFn = SlashCom -> Haskbot (Maybe Incoming) type TokenStr = Text --- | Create a new 'Plugin' from the components newPlugin :: NameStr -- ^ The text name of the plugin command - -> HelpStr -- ^ Help text displayed in conjunction with the - -- "Slack.Haskbot.Plugin.Help" plugin - -> HandlerFn -- ^ A function that takes a "Slack.Haskbot.SlashCommand" - -- and potentially returns a 'Incoming' - -> TokenStr -- ^ The secret token of the Slack /slash command/ - -- integration associated with this plugin - -> Plugin + -> HelpStr -- ^ (see 'plHelpText') + -> HandlerFn -- ^ (see 'plHandler') + -> TokenStr -- ^ The text value of the /slash command/ secret token + -> Plugin -- ^ Creates a plugin to be run by Haskbot newPlugin com help handler token = Plugin (setCommand com) help handler (setToken token) diff --git a/src/Network/Haskbot/SlashCommand.hs b/src/Network/Haskbot/SlashCommand.hs --- a/src/Network/Haskbot/SlashCommand.hs +++ b/src/Network/Haskbot/SlashCommand.hs @@ -1,13 +1,5 @@ --- | Module : Network.Haskbot.SlashCommand --- Description : Wrapper for the Slack API /slash command/ integration --- Copyright : (c) Jonathan Childress 2014 --- License : MIT --- Maintainer : jon@childr.es --- Stability : experimental --- Portability : POSIX --- --- This provides a representation of the request data from a Slack /slash --- command/ integration. A "Plugin" handler function is given +-- | This provides a representation of the request data from a Slack /slash +-- command/ integration. A "Network.Haskbot.Plugin" handler function is given -- direct access to this data type when a /slash command/ is invoked via -- Slack. module Network.Haskbot.SlashCommand @@ -23,12 +15,20 @@ -- integration data SlashCom = SlashCom - { token :: {-# UNPACK #-} !Token -- ^ the secret token corresponding to the /slash command/ integration token - , teamID :: {-# UNPACK #-} !TeamID -- ^ the team ID of the invoker - , channelID :: {-# UNPACK #-} !ChannelID -- ^ the channel ID where the command was invoked - , channelName :: {-# UNPACK #-} !ChannelName -- ^ the channel name where the command was invoked - , userID :: {-# UNPACK #-} !UserID -- ^ the user ID of the invoker - , userName :: {-# UNPACK #-} !UserName -- ^ the username of the invoker - , command :: {-# UNPACK #-} !Command -- ^ the name of the command invoked - , text :: {-# UNPACK #-} !Text -- ^ any text following the invoked slash command + { token :: {-# UNPACK #-} !Token + -- ^ the token corresponding to the /slash command/ integration secret token + , teamID :: {-# UNPACK #-} !TeamID + -- ^ the team ID of the command invoker + , channelID :: {-# UNPACK #-} !ChannelID + -- ^ the channel ID where the command was invoked + , channelName :: {-# UNPACK #-} !ChannelName + -- ^ the channel name where the command was invoked + , userID :: {-# UNPACK #-} !UserID + -- ^ the user ID of the command invoker + , userName :: {-# UNPACK #-} !UserName + -- ^ the username of the command invoker + , command :: {-# UNPACK #-} !Command + -- ^ the name of the command invoked + , text :: {-# UNPACK #-} !Text + -- ^ any text following the invoked slash command } deriving (Eq, Show) diff --git a/src/Network/Haskbot/Types.hs b/src/Network/Haskbot/Types.hs --- a/src/Network/Haskbot/Types.hs +++ b/src/Network/Haskbot/Types.hs @@ -1,12 +1,4 @@ --- | Module : Network.Haskbot.Types --- Description : Wrappers for Slack API data types --- Copyright : (c) Jonathan Childress 2014 --- License : MIT --- Maintainer : jon@childr.es --- Stability : experimental --- Portability : POSIX --- --- This provides wrappers for the various types of data supplied by the Slack +-- | This provides wrappers for the various types of data supplied by the Slack -- API, so that any processing of the API data remains type-safe. No -- constructors are directly exported to allow for flexibility with the -- currently-beta Slack API.