Network.IRC.Fun.Bot.Types

This module provides the datatypes.

Documentation

data Connection :: *

Details of the connection to IRC.

Constructors

Connection

Fields

server :: String

IRC Server address, e.g. "irc.freenode.net"

port :: Int

IRC server port, 6667 should be a safe default

tls :: Bool

Whether to make an encrypted connection via TLS (not implemented)

nick :: String

IRC nickname for the bot, e.g. "funbot"

password :: Maybe String

Connection password, use if the nickname is registered

Instances

Eq Connection

Show Connection

data Config

Configuration for the bot connection to IRC.

Constructors

Config

Fields

connection :: Connection

Connection details, including nickname and optional password

channels :: [String]

List of channels to join, e.g. ["rel4tion"]

logDir :: FilePath

Directory path under which IRC log files will be placed. Relative to the bot process working directory, or absolute.

stateRepo :: Maybe FilePath

Directory path for the state file. This enables Git commits of the state file. A relative (to the bot process working dir) or absolute path to the Git repository. You must create the directory yourself if it doesn't exist, but repo will be auto-created for you if needed.

stateFile :: FilePath

Filename into the bot state managed by this library will be stored. The custom part of the state isn't handled. If stateDir is Nothing, this is a path relative to the bot process working directory, or absolute. Otherwise, it's relative to the stateDir.

saveInterval :: TimeInterval

Minimal time interval between state saves. For example, to say "don't write state to file more than once per three seconds", set this field to 3 seconds, i.e. time (3 :: Second).

botEventLogFile :: FilePath

Filename for the bot's main event log, i.e. produced by the IRC event source.

Instances

Show Config

data Failure

Describes wrong usage of a bot command.

Constructors

WrongNumArgs

The number of arguments given is wrong

WrongNumArgsN (Maybe Int) (Maybe Int)

<first-param> arguments were given, instead of <second-param>

InvalidArgs

At least one of the arguments is invalid

InvalidArg (Maybe Int) (Maybe String)

Argument in position <first-param> and value <second-param> invalid

OtherFail String

Some other error, with a given description

Instances

Eq Failure

Show Failure

data Command e s

A bot command, triggered by a message sent to an IRC channel the bot has joined.

The type parameter e is the type of environment, i.e. real-only state. The type parameter s is the type of the writable state the bot holds. For example, maybe you want your bot to keep a list of to-do items and manage it using bot commands. The bot state is where you store the to-do list.

Constructors

Command

Fields

names :: [String]

The command's name string, e.g. "echo". More than one name is allowed per command, so that localized names and shortcuts can be made available.

The first name in the list is considered the primary name. When one name is shown, e.g. in help messages, it will be the primary name.

respond :: Maybe String -> String -> [String] -> (String -> Session e s ()) -> Session e s ()

What to do in response to the command being triggered by an IRC user. The bot can send an IRC message back to the channel, or modify its state, or both.

The returned value is in the Session monad (it is really RWST behind the scenes), which allows the bot to access the configuration and bot state, store and load data from files, communicate through the network (e.g. download RSS feeds) and more.

Parameters:

1. Channel in which the command was triggered, if any
2. Nickname of user who triggered the command
3. Command parameters given
4. Action for sending a message back to the sender, same as using sendBack with the channel and nickname

help :: String

Help string for the command, explaining it purpose, its parameters and its usage, possibly giving an example. May contain newlines.

data CommandSet e s

The bot recognizes commands by picking IRC channel messages which begin with a special character, the command prefix. It's possible to have several prefixes, maybe give each its own role or meaning. A command set is a set of commands which share a prefix.

A command can be in more than one set.

Common prefixes are !, \@, >, :.

Constructors

CommandSet

Fields

prefix :: Char

commands :: [Command e s]

type Session e s = RWST (BotEnv e s) () (BotState s) IO

Bot monad. It provides read-only bot environment (e.g. the configuration), read-writable bot state (for use by bot commands) and IO.

data Behavior e s

Bot behavior definition.

Constructors

Behavior

Fields

handleJoin :: String -> String -> Session e s ()

handlePart :: String -> String -> Maybe String -> Session e s ()

handleQuit :: String -> Maybe String -> Session e s ()

handleMsg :: String -> String -> String -> Bool -> Session e s ()

handleBotMsg :: String -> String -> String -> Session e s ()

commandSets :: [CommandSet e s]

handlePersonalMsg :: String -> String -> Session e s ()

handleNickChange :: String -> String -> Session e s ()

handleTopicChange :: String -> String -> String -> Session e s ()

handleNames :: String -> ChannelPrivacy -> [(Privilege, String)] -> Session e s ()

Handle a channel member list received. Parameters:

1. Channel name
2. Channel privacy
3. List of channel members: their privilege level in the channel and their nicknames

type EventSource e s a

Arguments

 = Config

The bot configuration. The event source may find this useful.

-> e

The bot's custom environment. The event source may find this useful.

-> (a -> IO ())

A non-blocking IO action which sends a given event to the processing queue.

-> ([a] -> IO ())

A non-blocking IO action which sends a given list of events to the processing queue.

-> (FilePath -> IO Logger)

An IO action which creates a logger with a given target filename. An event source can use it to log events, errors, debug into, etc. into files efficiently.

-> IO ()

An IO action, possibly running forever, which produces events for the bot to process. These event sources are run by the bot in dedicated threads.

Type parameters:

• e - custom bot environment type
• s - custom bot state type
• a - event type

type EventHandler e s a = a -> Session e s ()

A bot session action which reacts to a single event which came from an EventSource.

Type parameters:

• e - custom bot environment type
• s - custom bot state type
• a - event type

data Quotes

Quote types for string formatting.

Constructors

SingleQuotes Bool

Single quote on each side of the formatted string. The parameter sets whether to use Unicode (otherwise use ASCII fallback).

DoubleQuotes Bool

Double quote on each side of the formatted string. The parameter sets whether to use Unicode (otherwise use ASCII fallback).

BackTicks

Backtick on each side of the formatted string.

Instances

Eq Quotes

Show Quotes