meh-design.js

// hi, this explains the current bot architecture. comment pl0x.

// this is the object which the bot sees (and all listeners/commands receive)
var message = {
    text : 'message text sans any invocation stuff',
    user : {
        name : '',
        id : '',
        reputation : '',
        isOwner : function () { /*...*/ }
    },
    room : {
        id : 17,
        messages : [ 'array of messages sent in this room' ],
        users : { userId : User }
    },

    reply : function () { /* reply to this message */ },
    replyToUser : function () { /* guess */ },
    sendToRoom : function () { /* guess again! */ }
};

// you create a command
var fooCommand = bot.Command({
    // should a name be specified inside the command object? (see later for
    //why not)
    
    description : 'something',
    usage : 'how to use this command',
    // notice the distinction between what a command does and how it's used
    
    permissions : {
        use : 'all',
        del : 'none'
        // still possible to specify 'owner' or a list of uids
    }
});

// it's an Observable, so you just subscribe to it in order to do stuff
// bonus: you can subscribe multiple times!
// ...is this a good idea?
fooCommand.subscribe(function (message) {
    // do command stuff
});

// finally, you add the command in
bot.addCommand('foo', fooCommand);
// this is the only step in which we care about the command name

// the bot has two streams in it, both of which receive messages just like
//regular commands do:

// 1. invoke stream
bot.invokeStream.subscribe(function (message) { /* ... */ });
// this stream is the messages the bot sees and wants to respond to.
// basically, sans any ignored users etc and the invocation pattern check.
// note that the bot itself is a subscriber to this stream, so whether you
//get notified of a message before or after the bot is stream implementation
//dependant.

// tl;dr you subscribe to the invokeStream if you want to see bot messages.

// 2. message stream
bot.messageStream.subscribe(function (message) { /* ... */ });
// this stream is all the checks above, WITHOUT the invocation pattern check.
// so you can use this stream to listen to "raw" messages, for instance to
//implement STOP.
// one important note is that it doesn't mean that a message DOES NOT invoke the
//bot. the invokeStream is actually just a derivative of this stream.
// should this be changed? should a separate stream be made for non-bot-invoking
//messages?

/*
open issues (that I can pull off the top of my head, there're more):
 1. is command/listener separation a good idea? it was a very ad-hoc thing.
aren't all commands ostensibly listeners, sans the automagic argument capture?
counter: no, commands have a name, listeners only have a regexp...
 
listeners seem to be better favoured, but then how will one search for help on
a listener?
 
 2. I really don't like /tell, it should be done in the bot level. maybe replace
it, so the following:
 !!@target command ...args...
would do the same thing as:
 !!tell target command ...args...
And similarly for message ids, replacing the '@' with a ':'. Maybe even :target
to have it reply to the user's last message (or, failing to find it, reply to
the user).
*/