Permalink
Browse files

Merge pull request #30 from callumacrae/issue/27

[issues/27] Added comments
  • Loading branch information...
2 parents 3ae545c + 5b149fe commit 2ea6bd4b4e8b004501d807afe37ed5ddb8418f3e @callumacrae committed Feb 18, 2012
Showing with 406 additions and 3 deletions.
  1. +98 −2 Hex/handler.js
  2. +28 −0 Hex/hex.js
  3. +280 −1 docs/commands.md
View
100 Hex/handler.js
@@ -4,22 +4,26 @@ handler = function (info, admin, noreply) {
nick = info[1];
chan = info[3];
+ // If received as a PM, replies to the PM.
pm = chan.search(/^[^#]/) !== -1;
if (pm) {
chan = nick;
}
+ // If it is @ someone, sets the nick to be them (see commands.md)
reply = /^(.+) @ ?(.+)/.exec(info[4]);
if (reply) {
info[4] = reply[1];
nick = reply[2];
}
reply = null;
+ // sets cmd and cmd_end
index = info[4].indexOf(' ');
cmd = (index === -1) ? info[4] : info[4].slice(0, index);
cmd_end = (index === -1) ? null : info[4].slice(index + 1);
+ // prevents h4x!
if (cmd.search(/(\.|\/)/) !== -1) {
return false;
}
@@ -31,11 +35,17 @@ handler = function (info, admin, noreply) {
console.log(nick + ' tried to access admin without correct permissions.')
return false;
}
+
+ // splits cmd_end; find the subcommand.
index = cmd_end.indexOf(' ');
cmd = (index === -1) ? cmd_end : cmd_end.slice(0, index);
cmd_end = (index === -1) ? null : cmd_end.slice(index + 1);
switch (cmd.toLowerCase()) {
+
+ /**
+ * Sends a list of admin commands to the user via PM.
+ */
case 'help':
case 'h':
chan = nick;
@@ -65,6 +75,9 @@ handler = function (info, admin, noreply) {
];
break;
+ /**
+ * Bans user from current or specified channel.
+ */
case 'ban':
if (admin < 4) {
reply = 'Admin level 4 required for this operation.';
@@ -78,6 +91,9 @@ handler = function (info, admin, noreply) {
log = 'ban ' + cmd_end + ' (from ' + chan + ')';
break;
+ /**
+ * Devoices user in current or specified channel.
+ */
case 'devoice':
if (admin < 2) {
reply = 'Admin level 2 required for this operation.';
@@ -91,11 +107,17 @@ handler = function (info, admin, noreply) {
log = 'devoice ' + cmd_end + ' (from ' + chan + ')';
break;
+ /**
+ * Reloads handler.js
+ */
case 'flush':
flush = true;
reply = 'Flushing...';
break;
+ /**
+ * Makes the bot join specified channel.
+ */
case 'join':
if (admin < 7) {
reply = 'Admin level 7 required for this operation.';
@@ -107,6 +129,9 @@ handler = function (info, admin, noreply) {
flush = true;
break;
+ /**
+ * Kicks user from current or specified channel.
+ */
case 'kick':
if (admin < 3) {
reply = 'Admin level 3 required for this operation.';
@@ -120,6 +145,9 @@ handler = function (info, admin, noreply) {
log = 'kick ' + cmd_end + ' (from ' + chan + ')';
break;
+ /**
+ * Mutes the bot in the current channel.
+ */
case 'mute':
if (admin < 6) {
reply = 'Admin level 6 required for this operation.';
@@ -131,6 +159,9 @@ handler = function (info, admin, noreply) {
reply = 'Muted.';
break;
+ /**
+ * Parts the current or specified channel.
+ */
case 'part':
if (admin < 7) {
reply = 'Admin level 7 required for this operation.';
@@ -144,6 +175,9 @@ handler = function (info, admin, noreply) {
flush = true;
break;
+ /**
+ * Restarts the bot.
+ */
case 'quit':
case 'q':
case 'restart':
@@ -156,6 +190,9 @@ handler = function (info, admin, noreply) {
process.exit();
break;
+ /**
+ * Sends raw data to the IRC server.
+ */
case 'raw':
if (admin < 10) {
reply = 'Admin level 10 required for this operation.';
@@ -165,6 +202,9 @@ handler = function (info, admin, noreply) {
console.log(nick + ' sent RAW: ' + cmd_end);
break;
+ /**
+ * Removes the specified command.
+ */
case 'remove':
case 'rm':
if (admin < 6) {
@@ -177,6 +217,9 @@ handler = function (info, admin, noreply) {
log = cmd + ' ' + cmd_end;
break;
+ /**
+ * Adds or sets the specified command.
+ */
case 'set':
if (admin < 6) {
reply = 'Admin level 6 required for this operation.';
@@ -193,8 +236,11 @@ handler = function (info, admin, noreply) {
reply = 'Successfully set ' + cmd;
break;
+ /**
+ * Adds, modifies, removes or lists super users.
+ */
case 'su':
- //dont check whether admin is level 10 yet - level 3s can list admins
+ // Don't check whether admin is level 10 yet - level 3s can list admins
cmd = cmd_end.split(' ', 3);
switch (cmd[0].toLowerCase()) {
case 'add':
@@ -255,6 +301,9 @@ handler = function (info, admin, noreply) {
log = 'su ' + cmd;
break;
+ /**
+ * Mutes bot for half an hour.
+ */
case 'tmpmute':
if (admin < 4) {
reply = 'Admin level 4 required for this operation.';
@@ -274,6 +323,11 @@ handler = function (info, admin, noreply) {
reply = 'Muted for half an hour.';
break;
+ /**
+ * Unmutes the bot.
+ *
+ * Can unmute mutes set using both mute and tmpmute.
+ */
case 'unmute':
if (admin < 4) {
reply = 'Admin level 4 required for this operation.';
@@ -287,6 +341,9 @@ handler = function (info, admin, noreply) {
}
break;
+ /**
+ * Voices specified user in current or specified channel.
+ */
case 'voice':
if (admin < 2) {
reply = 'Admin level 2 required for this operation.';
@@ -306,6 +363,9 @@ handler = function (info, admin, noreply) {
console.log('"admin ' + ((log === undefined) ? cmd : log) + '" called by ' + nick);
break;
+ /**
+ * Returns a link to a specified google search.
+ */
case 'g':
case 'google':
reply = 'http://google.com/';
@@ -314,6 +374,9 @@ handler = function (info, admin, noreply) {
}
break;
+ /**
+ * Executes given JavaScript and returns value.
+ */
case 'js':
case 'javascript':
var exec = require('child_process').exec;
@@ -341,13 +404,19 @@ handler = function (info, admin, noreply) {
});
break;
+ /**
+ * Returns a link to a specified lmgtfy search.
+ */
case 'lmgtfy':
reply = 'http://lmgtfy.com/';
if (cmd_end) {
reply += '?q=' + encodeURIComponent(cmd_end);
}
break;
+ /**
+ * Shows the bot uptime.
+ */
case 'uptime':
var num, uptime = new Date().getTime() - start.getTime();
reply = 'Uptime: ';
@@ -395,7 +464,9 @@ handler = function (info, admin, noreply) {
}
break;
-
+ /**
+ * Displays a wiki link
+ */
case 'w':
case 'wiki':
if (!cmd_end) {
@@ -427,6 +498,9 @@ handler = function (info, admin, noreply) {
req.end();
break;
+ /**
+ * Displays a wolframalpha link.
+ */
case 'wa':
case 'wolfram':
case 'wolframalpha':
@@ -436,12 +510,18 @@ handler = function (info, admin, noreply) {
}
break;
+ /**
+ * Displays info the bot has on the user.
+ */
case 'whoami':
nick = info[1];
reply = 'Your nick is "' + info[1] + '". Your hostmask is "' + info[2] + '". ';
reply += (admin) ? 'You are admin level ' + admin + '.' : 'You are not an admin.';
break;
+ /**
+ * Searches the msgs directory for other messages set using the set command.
+ */
default:
var file, fs = require('fs');
try {
@@ -456,6 +536,7 @@ handler = function (info, admin, noreply) {
break;
}
+ // Splits the message and sends them one by one.
if (reply && !noreply) {
if (typeof reply === 'string') {
reply = [reply];
@@ -472,6 +553,11 @@ handler = function (info, admin, noreply) {
return flush;
};
+/**
+ * Turns HTML into a string.
+ *
+ * @param s The HTML string.
+ */
html_decode = function (s) {
var c, m, d = s;
@@ -492,6 +578,13 @@ html_decode = function (s) {
return d;
};
+/**
+ * Function called by Hex on every message; simply monitors how many messages
+ * users are sending to a channel. Takes action if they're flooding.
+ *
+ * @param nick The nick of the user.
+ * @param chan The channel the message was sent to.
+ */
antiflood = function (nick, chan) {
if (hex.info.names[chan][nick] === undefined) {
return;
@@ -562,6 +655,9 @@ antiflood = function (nick, chan) {
}
};
+/**
+ * Simple server to handle HTTP requests to the logs.
+ */
server = function (req, res) {
var date, file, output;
View
28 Hex/hex.js
@@ -25,6 +25,10 @@ hex = new IRC(config, function (msg) {
global.mute = [];
+/**
+ * Handles all private messages. Handles messages sent to the bot, but also
+ * handles stuff like flooding.
+ */
hex.on(/^:([^!]+)![^@]+@([^ ]+) PRIVMSG ([^ ]+) :(.+)$/i, function (info) {
var admin, ad_info, flush;
admin = (admins[info[1]] === undefined) ? 0 : admins[info[1]].level;
@@ -64,6 +68,11 @@ hex.on(/^:([^!]+)![^@]+@([^ ]+) PRIVMSG ([^ ]+) :(.+)$/i, function (info) {
}
});
+/**
+ * Listens for kicks, and if it is the bot which is kicked then it rejoin and
+ * sends an angry message to whoever kicked it. If it cannot rejoin, it waits
+ * until it can rejoin before sending said angry message.
+ */
hex.on(/^:([^!]+)![^@]+@[^ ]+ KICK (#[^ ]+) ([^ ]+) :/, function(info) {
if (info[3] === hex.info.nick) {
console.log('Kicked from ' + info[2] + ' by ' + info[1] + '. Rejoining.');
@@ -74,6 +83,11 @@ hex.on(/^:([^!]+)![^@]+@[^ ]+ KICK (#[^ ]+) ([^ ]+) :/, function(info) {
}
});
+/**
+ * Handles bot admin stuff - when someone joins, it checks whether they
+ * are a super user or not and if they are it validates it. If they quit, it clears
+ * up the admin array.
+ */
hex.on(/^:([^!]+)![^@]+@([^ ]+) (JOIN|QUIT)/, function (info) {
if (config.su[info[1]] !== undefined) {
if (info[3] === 'JOIN') {
@@ -94,18 +108,28 @@ hex.on(/^:([^!]+)![^@]+@([^ ]+) (JOIN|QUIT)/, function (info) {
}
});
+/**
+ * Handles admins who change nick.
+ */
hex.on(/^:([^!]+)![^@]+@[^ ]+ NICK :(.+)$/, function (info) {
if (admins[info[1]] !== undefined) {
admins[info[2]] = admins[info[1]];
delete admins[info[1]];
}
});
+/**
+ * Creates the server for displaying logs. May also handle more, in the
+ * distant and faraway future…
+ */
http.createServer(function (req, res) {
server(req, res); //wrapper here so that we can edit server()
}).listen(config.log.web.port, config.log.web.addr);
console.log('Server now listening.');
+/**
+ * Listens to the x10hosting twitter, and forwards any tweets into #x10hosting
+ */
var Twitter = require('twitter');
var twit = new Twitter({
user: config.twitter.user,
@@ -121,6 +145,10 @@ twit.on('tweet', function (tweet) {
console.log('Tweet streamer error: ' + err);
});
+/**
+ * Logs any uncaught exceptions, so that the bot doesn't shut down whenever
+ * anyone finds a bug.
+ */
process.on('uncaughtException', function (error) {
console.log('Uncaught Exception: ' + error);
});
View
281 docs/commands.md
@@ -5,10 +5,40 @@ completely up to date, just throw something at one of us on irc or file an
issue if you find any out of date content.
This is in addition to `Hex: help` and `Hex: a help`, as it is more
-comprehensive and detailed (and easier to read). It is divided into two
+comprehensive and detailed (and easier to read). It is divided into two main
sections; user commands and admin commands.
+## Calling the bot ##
+
+There are a couple ways to call the bot. You can either send it a private
+message, or you can send it in the channel by prefixing "Hex" to it:
+
+```irc
+<callumacrae> Hex: help
+<@Hex> callumacrae: Currently available commands:
+<@Hex> callumacrae: about, admin (a), buydomain, cpanel (cp), dns, domainadd,
+ flushdns, google (d), help, lmgtfy, mysql, paid, tickets, tos, upgrade,
+ uptime, wiki (w), wolframalpha (wa) and whoami.
+```
+
+The colon is entirely optional, and both the bot name and commands are
+not case sensitive.
+
+
+### Directing a command ###
+
+You can direct a command at someone using the `@` operator:
+
+```irc
+<callumacrae> Hex: help @ GtoXic
+<@Hex> GtoXic: Currently available commands:
+<@Hex> GtoXic: about, admin (a), buydomain, cpanel (cp), dns, domainadd, flushdns,
+ google (d), help, lmgtfy, mysql, paid, tickets, tos, upgrade, uptime, wiki
+ (w), wolframalpha (wa) and whoami.
+```
+
+
## User Commands ##
### google ###
@@ -61,6 +91,21 @@ That For You) instead.
```
+### login ###
+**Aliases:** None
+
+```
+Hex: login
+```
+
+Logs the user in as an admin, instead of them having to cycle.
+
+```irc
+<callumacrae> Hex: login
+<@Hex> callumacrae: You have been identified as an admin.
+```
+
+
### uptime ###
**Aliases:** None
@@ -165,3 +210,237 @@ change at any time. The below list contains most of them, as of 16/ 02/12.
* **ping:** Shouts PONG at the user.
* **tickets:** Tells the user how to create a ticket.
* **tos:** Links the user to the ToS.
+
+
+
+## Admin Commands ##
+
+Admin commands can be accessed by appending the command with "admin "
+or "a ". For example:
+
+```irc
+<callumacrae> Hex: a ban Dead-i
+```
+
+They require the user calling them to be of a certain admin level (specified
+below the commands below by "Level"). Failing to be of that level will result
+in an error (or if they're not an admin at all, it will fail silently).
+
+
+### help ###
+**Aliases:** h
+**Level:** 0
+
+```
+Hex: a help [ all ]
+```
+
+Sends the user a list of admin commands that they can use, or if they
+specify "all", it gives them more detail about each command (but it doesn't
+contain quite as much detail as this document).
+
+It is sent in multiple private messages, not into the channel you requested
+it in (assuming you requested it in a channel).
+
+
+### ban ###
+**Aliases:** None
+**Level:** 4
+
+```
+Hex: a ban <user> [ <channel >]
+```
+
+Bans the specified user from either the current channel or the specified
+channel; if a channel is not specified, it will ban the user from the
+current channel.
+
+
+### devoice ###
+**Aliases:** None
+**Level:** 2
+
+```
+Hex: a devoice <user> [ <channel> ]
+```
+
+Devoices the specified user in either the current channel or the specified
+channel; if the channel is not specified, it will devoice the user in the
+current channel.
+
+
+### flush ###
+**Aliases:** None
+**Level:** 0 (not harmful)
+
+```
+Hex: a flush
+```
+
+Reloads handler.js, causing any updates in that file to be applied.
+
+
+### join ###
+**Aliases:** None
+**Level:** 7
+
+```
+Hex: a join <channel>
+```
+
+Commands the bot to join the specified channel. If it is banned from that
+channel, it will *not* try to join the channel again or try to unban itself, it
+just won't join.
+
+
+### kick ###
+**Aliases:** None
+**Level:** 3
+
+```
+Hex: a kick <user> [ <channel> ]
+```
+
+Kicks the specified user from either the current channel or the specified
+channel; if the channel is not specified, it will kick the user from the
+current channel. This command does not ban the user, and they will be able
+to rejoin immediately.
+
+
+### mute ###
+**Aliases:** None
+**Level:** 6
+
+```
+Hex: a mute
+```
+
+Mutes the bot in the current channel. Use the `unmute` command to unmute
+the bot, or `tmpmute` if you only want to mute the bot for a period of time.
+
+
+### part ###
+**Aliases:** None
+**Level:** 7
+
+```
+Hex: a part [ <channel> ]
+```
+
+Commands the bot to part either the current channel or the specified
+channel; if the channel is not specified, it will part the current channel.
+
+
+### restart ###
+**Aliases:** quit, q
+**Level:** 10
+
+```
+Hex: a restart
+```
+
+Restarts the bot. It is not possible to quit the bot without access to the
+server.
+
+
+### raw ###
+**Aliases:** None
+**Level:** 10
+
+```
+Hex: a raw <text>
+```
+
+Sends the specified text as raw IRC (equivilant to client /quote).
+
+
+### remove ###
+**Aliases:** rm
+**Level:** 6
+
+```
+Hex: a rm <command>
+```
+
+Removes the specified command. Use `set` to modify or add a command.
+
+
+### set ###
+**Aliases**: None
+**Level:** 6
+
+```
+Hex: a set <command> <text>
+```
+
+Sets the specified command to the specified text.
+
+
+### su add ###
+**Aliases:** su add
+**Level:** 10
+
+```
+Hex: a su add <user> <level>
+```
+
+Adds the specified user as a super user of the specified level.
+
+
+### su remove ###
+**Aliases:** su rm
+**Level:** 10
+
+```
+Hex: a su remove <user>
+```
+
+Removes the super user permissions of the specified user.
+
+
+### su list ###
+**Aliases:** None
+**Level:** 3
+
+```
+Hex: a su list
+```
+
+Sends a list of super users, their levels, and whether they're logged into the
+bot or not in a private message to the user who requested it.
+
+
+### tmpmute ###
+**Aliases:** None
+**Level:** 4
+
+```
+Hex: a tmpmute
+```
+
+Mutes the bot in the current channel for half an hour.
+
+
+### unmute ###
+**Aliases:** None
+**Level:** 4
+
+```
+Hex: a unmute
+```
+
+Unmutes the bot in the current channel. It can unmute mutes set with both
+`mute` and `tmpmute`.
+
+
+### voice ###
+**Aliases:** None
+**Level:** 2
+
+```
+Hex: a voice <user> [ <channel> ]
+```
+
+Voices the specified user in either the current channel or the specified
+channel; if the channel is not specified, it will voice the user in the
+current channel.

0 comments on commit 2ea6bd4

Please sign in to comment.