diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 213 |
1 files changed, 56 insertions, 157 deletions
@@ -1,162 +1,61 @@ # idalius idalius started out as a novelty IRC bot. Its original functionality has now -been moved into an optional module, "tittilate", while the remainder of the +been moved into an optional module, "titillate", while the remainder of the bot's functionality is mostly configurable and extensible. -## Commands - -Arbitrary commands can be registered by any module. Commands (currently -separate from admin commands) are issued in-channel, prefixed with the string -configured in the `bot.conf` parameter `prefix`. This is `%` by default, and -this default will be used in this README. - -## Module: URL Title - -idalius can pick a URL out of any channel message and respond in-channel with -the title of the link, followed by the hostname so you know roughly what link -the title is for. - - <phillid> Testing the URL title thingy https://sighup.nz/ and presuming it works - <idalius> Ahoy-hoy β SIGHUP (sighup.nz) - - -## Module: Tittilate - -The tittilate module is one which will ask idalius to check all channel -messages for special keywords, and for each message containing some of those -keywords, respond with a message with as many user-set responses to those -keywords, in order. It's kind of hard to get your head around with plain -words, so I'll give an example. - -Under the default configuration, idalius will trigger on 'sax', 'trumpet' -and 'snake', replying with 'π·', 'πΊ' and 'π' respectively. Take a look at -this IRC log: - - <someuser> sax - <somebot> π· - <someuser> sax snake - <somebot> π· π - <someuser> saxaphone woosaxsnakeSAXalright trumpetTRUMPET - <somebot> π· π· π π· πΊ πΊ - -Simple eh. - -## Module: Antiflood - -This module will kick someone who send more than 5 messages in 11 seconds on -a channel. It's on the to-do list to make these parameters configurable. - -## Module: Echo - -This module adds a command to echo strings on-channel. Example: - - <someone> %echo woo stuff - <somebot> woo stuff - -## Module: Map - -This module allows simplistic mapping of a function across a list of arguments. -At the moment, array syntax is just prototypical, and uses regex to split on -commas. Thus, nesting of , within arguments is not yet possible. Examples: - - <someone> %map echo foo,bar, foobar - <somebot> [foo, bar, foobar] - -## Module: Timezone - -This module allows timezones to be associated with words (intended for use -with nicks) so that the command `%time foo` will return the current time, -adjusted for the timezone associated with `foo`. Example: - - <person1> %time person1 - <somebot> person1: person1's clock reads 2018-04-10T06:39:44 - -## Admin commands - -idalius also supports some basic administration commands. These should be sent -in a private message to the bot by someone with a hostmask configured to be an -administrator's hostmask. - -At the moment these commands comprise: - -### Nick change - - nick fooeybot - -Attempt to change the bot's IRC nick name to fooeybot. - -### Part/leave from channels - - part #channel - part #channel some part message - part #channel #anotherone - part #channel #anotherone witty part message here - -Leave/part from one or more channels, giving an optional part message. This -part message will be used for the parts sent to each channel specified. - -### Join channels - - join #channel - join #channel #someotherchannel #omganotherchannel #holymoly - -Join one or more channels - -### Say something to a channel or person - - say nick I'm here for you, Jack - say #channel Hey hi hello howdy - -Tell a person or a channel something, perferably something useful. Useful for -puppeting if you are not on a channel, or you could talk to yourself through -an idalius bot if you get lonely. Additionally, it might be useful for your -idalius to contact services like nickserv, memoserv, chanserv etc. - -### Perform a CTCP action to a channel or person - - action nick slaps you with a fish - action #channel stares down everyone in the room - -Not really useful apart from having a laugh in a channel. Really not sure why -I added this except for a lame gag or two. Worth it. - -### Set channel topic - - topic #channel new topic - -Does what it says on the tin. - -### Set channel/user modes - - mode #channel +v someone - mode #channel +vo someone opguy - mode #channel +n - mode #channel +l 5 - -So on and so forth. What comes after "mode" is sent verbatim to the IRC client -idalius wraps, which (as far as I know) sends it verbatim to the server. So -you're really down to whatever the IRC server you're on will understand. - -### Kick someone from a channel - - kick #channel badPerson - kick #channel badPerson You've been very naughty! - -Kicks badPerson from #channel, and optionally takes your specified kick reason -to relay with the kick. If you do not specify a kick reason, then idalius will -use a default message "Requested by <yourNameHere!>". - -### Reconnect - - reconnect - reconnect witty message - -Code isn't bug-free, and idalius is far from it. If you manage to break your -idalius beyond repair, you might want to look at asking it remotely to -disconnect from the IRC server and connect back to it again to start from a -clean slate. - -Your idalius will ask the IRC server to use a witty quit message if you -specify one, otherwise it will fall back on the default quit message specified -in the config file (quit_msg) +Gradually, what used to be the bot's core, `idalius.pl` is becoming more +and more of a shell/framework, with what used to be "core functionality" being +moved off to loadable modules. This is work is still in-progress. + +## Plugins/Modules + +idalius allows a lot of what is often considered a bot's standard functionality +to be swapped out, or disabled altogether. Below is a list of some common +plugins that you probably want to enable for your run-of-the-mill IRC bot. + +### Recommended plugins + +These plugins will give you a "base" bot that does nothing more than joining +(and staying joined to) channels, logging messages to stdout, allowing basic +puppeting. + +* **Plugin::Admin** - Allows specific users to puppet the bot (kick, join, part + set modes, say things to channels/people, etc.). Also allows runtime plugin + loading/unloading. +* **Plugin::Autojoin** - Causes the bot to ask to join a preconfigured set of + channels when first connecting to an IRC server. +* **Plugin::Log** - Logs IRC traffic and other events that the bot sees in the + channels it joins, server announcements, notices etc. +* **Plugin::Rejoin** - This one only just makes it into the recommended list, + since the behaviour this module enables can be viewed by some people as + annoying. This plugin will cause your bot to automatically attempt to rejoin + a channel if it is kicked from it. + +### All Plugins + +These are all plugins available in the standard distribution. + +* **Plugin::Admin** - Puppeting, ignoring/unignoring users, setting of command prefix, killing the bot, loading/unloading of plugins. +* **Plugin::Antiflood** - Kicks users who send too many messages at once. +* **Plugin::Autojoin** - Joins a configured set of channels when connecting to a server. +* **Plugin::Convert** - Wraps and requires the GNU Units utility for unit conversion in-channel. +* **Plugin::Dad** - Jumps in on certain phrases in channels to tell crappy dad jokes. +* **Plugin::DevNull** - Adds commands to wrap and silence other commands. +* **Plugin::Echo** - Adds a simple echo command for anyone to use. +* **Plugin::Greet** - Triggers the bot to have a chance of greeting a channel as it joins, and other users as they join. +* **Plugin::Hmm** - Say some pensive words if a channel receives no activity for some time. +* **Plugin::Jinx** - Repeat messages in a channel if they are "on streak". E.g. say "lol" if it's been said twice in a row in a channel. +* **Plugin::Log** - Log a variety of bot and IRC events to stdout. +* **Plugin::Map** - Adds a functional mapping command, useful for running bot commands over varied of values. +* **Plugin::Men** - Sometimes respond to messages with "men" in them with "not just the men, but the women and children, too!". E.g. "Not just the comments, but the cowoments and cochildrents, too!" +* **Plugin::Natural** - Sometimes respond to messages in the channel, to make the bot seem vaguely more human. +* **Plugin::Ping** - Adds a ping command. +* **Plugin::Random** - Adds a shuffle and choose/random choice command. +* **Plugin::Rejoin** - Rejoin to channels the bot is kicked from. +* **Plugin::Source** - Adds some commands for displaying the upstream source locations for the bot. +* **Plugin::Thanks** - Adds some commands so the bot responds to being thanked directly. +* **Plugin::Timezone** - Adds a command to calculate the current time of day for various timezones or users. +* **Plugin::Titillate** - Auto-respond to configured parts of messages in channels. +* **Plugin::URL_Title** - Respond in-channel with a title for any URLs posted which point to HTML/SVG. +* **Plugin::Vote** - Adds commands for voting on topics. |