#
# The yagIRC script prototype + short manual
#
#  Copyright (C) 1998 Jere Sanisalo <jeress@iname.com> and Timo Sirainen
# 

# CUSTOM SCRIPTS (use module_name;)
# CUSTOM SCRIPTS


# Commands (alphabetic order):
#   *** commands marked with !! aren't implemented yet ***
#  ircBind(eventType,eventSpecifier,bindTime,functionName);
#         Binds an event to a SUB-function. The function depends on the
#         event. The bind returns 'yes' is it was successfull (or 'no' if
#         not). The bindTime is the amount of time (in milliseconds) the
#         binding lasts (0 = forever).
#         The callback functions should return 'yes' if they want the yagIRC
#         to process the event also. Note that if many functions have been
#         assigned to an event, then everyone must return 'yes' for yagIRC to
#         process the event.
#         List of all events:
#          CONNECTED - Called when the server connection has been established
#                      (and after the user has been logged on).
#                      The function is in the type of:
#                        functionName(serverId,serverName);
#          CTCP     - Called when someone sends a CTCP-request (eg. a
#                     'VERSION').
#                     The function is in the type of:
#                       functionName(nickName,userHost,destNick,ctcpData);
#          DCCMSG   - Called when a dcc message has been received. The
#                     eventSpecifier notifies the user nick on which to bind
#                     the event (the connection may not necessary be up)..
#                     The function is in the type of:
#                       functionName(nickName,message);
#          DISCONNECTED - Called when the server connection has been
#                         disconnected.
#                         The function is in the type of:
#                           functionName(serverId,serverName);
#          INVITE   - Called when someone invites you to a channel.
#                     The function is in the type of:
#                       functionName(nickName,channelName);
#          IRCJOIN  - Called when someone joins the irc (kind of a notify).
#                     The irc-nick is given in eventSpecifier.
#                     The function is in the type of:
#                       functionName(nickName,userHost);
#          IRCPART  - Called when someone leaves the irc (kind of a notify).
#                     The irc-nick is given in eventSpecifier.
#                     The function is in the type of:
#                       functionName(nickName,userHost);
#          JOIN     - Called when someone joins a channel. The eventSpecifier
#                     notifies the channel on which to bind the event (""
#                     means all channels).
#                     The function is in the type of:
#                       functionName(nickName,userHost,channelName);
#                     NOTE! Here only the channelName has the server info.
#          KICK     - Called when someone is kicked out of a channel you're
#                     on.
#                     The function is in the type of:
#                       functionName(kickerNick,ChannelName,kickedNick,kickedUserHost,kickReason);
#                     NOTE! Here only the channelName has the server info.
#          MODE     - Called when the channel mode has been changed. The
#                     eventSpecifier notifies the channel on which to bind
#                     the event ("" means all channels).
#                     The function is in the type of:
#                       functionName(nickName,userHost,channelName,modeString);
#                     NOTE! The modeString contains the whole mode-string,
#                           ie. '+oo-o john ira turbo'.
#          PART     - Called when someone leaves a channel you're on. The
#                     eventSpecifier notifies the channel on which to bind
#                     the event ("" means all channels).
#                     The function is in the type of:
#                       functionName(nickName,userHost,channelName,leaveMsg);
#          PRGQUIT  - Called upon the program quit (when yagIrc needs to
#                     end the script for some reason).
#                     The function is in the type of:
#                       functionName();
#          PRIVMSG  - Called when a private message is written to you.
#                     The function is in the type of:
#                       functionName(nickName,userHost,message);
#          PUBMSG   - Called when a message is written in a channel. The
#                     eventSpecifier notifies the channel on which to bind
#                     the event ("" means all channels).
#                     The function is in the type of:
#                       functionName(nickName,channelName,message);
#                     NOTE! Here only the channelName has the server info.
#          SERVERMSG - Called when the server sends up some text (ie. motd or
#                      anything, just as long as it's sent by the server).
#                      The function is in the type of:
#                        functionName(serverId,message);
#          TOPIC    - Called when the topic changes on a channel you're on.
#                     The function is in the type of:
#                       functionName(nickName,userHost,channelName,topic);
#          QUIT     - Called when someone who was on one or more of the 
#                     channels you're on quits.
#                     The function is in the type of:
#                       functionName(nickName,userHost,channelNames,leaveMsg);
#                     NOTE! The channelNames is a list of all the channels
#                           you know the user was before quitting, separated
#                           by a space.
#                     NOTE! This is called before IRCPART.
#         RETURN VALUES(S): The event binding id (given by yagIrc), or "" if
#                           there was an error.
#         NOTE! Where 'nickName' (or any nick in general) is the first
#               parameter, then the nick has the server info (and all other
#               nicks/channels do not have it).
#         NOTE! One binding type can only be done once (so no two exactly
#               the same bindings can be done, although even a small
#               difference is enough for the binding to happen)!
#  ircBindCmd(commandName,commandSpecifier,functionName);
#         Binds a local command. For example if you bind "test", then typing
#         '/TEST' in yagIRC would call this function. Everything written
#         after the command on irc will be passed as a single argument to the
#         function.
#         The commandSpecifier depends on commandName. Here's the list of
#         special commandNames:
#          '/JOIN'  -
#          '/PART'  - The eventSpecifier specifies the channel to bind.
#          '/MSG'   - The eventSpecifier specifies the user (dest) to bind.
#         RETURN VALUES(S): The event binding id (given by yagIrc), or "" if
#                           there was an error.
#         NOTE! Each command (type) may be bound only once!
#         NOTE! When eventSpecifier would otherwise be used, giving a "" means
#               to bind the command in whole.
#         NOTE! Beware of looped commands (bind a command and inside that
#               command call the same command again (infinite recursive
#               loop)).
#  ircCmd(channelName,command);
#         Issues a command (like "/names #test").
#         RETURN VALUES(S): 'yes' or 'no' depending on success.
#         NOTE! Beware of looped commands (bind a command and inside that
#               command call the same command again (infinite recursive
#               loop)).
#  ircCTCPSend(dest,ctcpData);
#         Sends a CTCP request to a user (dest can be a channel or a nick).
#         RETURN VALUES(S): 'yes' or 'no' depending on success.
#  ircCTCPReply(nickName,ctcpData);
#         Sends a CTCP reply to a user.
#         RETURN VALUES(S): 'yes' or 'no' depending on success.
#!!ircGetChannelList(serverId);
#         Gets the list of joined channels in a server.
#         RETURN VALUES(S): Channel list (list of strings).
#!!ircGetLocalUserInfo(serverId);
#         Gets the local user (the user the yagIrc is connected) info on a
#         server.
#         RETURN VALUES(S): On failure a 'undef' is returned.
#                           On success, the return is a list, which has the
#                           the folloring items (in the same order):
#                             userNick,userHost,userName
#!!ircGetNameList(channelName);
#         Gets the users of a channel. The list returned will contain a
#         string per user (the user will have any irc-additions in from of
#         the nick, ie. a '@' if the user is an operator and a '+' is the
#         user has voices etc.).
#         RETURN VALUES(S): User list (list of strings).
#         NOTE! The channelName-parameter should have the multiserver-ids
#               embedded on it (if not, then every server connected will
#               be checked and added to the list). Remember, every nick ends
#               with ' serverId' (where serverId is the id of the server).
#!!ircGetServerIdList();
#         Gets a list of the connected server ids and the servers addresses.
#         The list has ID-ADDRESS-pairs, so the return value is ready to be
#         hashed.
#         RETURN VALUES(S): Server Id+address list (list of strings).
#!!ircGetTopic(channelName);
#         Gets the channel topic.
#         RETURN VALUES(S): The topic is returned, or 'undef' if there was an
#                           error.
#         NOTE! The channelName must have the multiserver-id, or else this
#               command fails.
#  ircMenuAdd(menuType,menuText,menuDest,functionName);
#         Adds a menu item to any of the menus (main/channel/nick). The
#         menuText is the text displayed in the menu. The menuDest is the
#         destination for the menu item (if the menuType does not have a
#         destination, then set this to "", see the list at the end of the
#         the command-description). The functionName is the callback function
#         (defined as: functionName(menuType,menuDest,menuItemId);).
#         The menu types are as follow:
#           GLOBAL - Global menus for every window (no menuDest!).
#           CHANNEL - Channel specific pop-up menus (menuDest is the channel
#                     name).
#           NICK - Nick name specific pop-up menus (menuDest is the nick name
#                  to bind).
#         RETURN VALUES(S): The menuItemId (for later menu access). On error
#                           the returned value is "".
#         NOTE! One type of menu binding can only be done once!
#  ircMenuRemove(menuItemId);
#         Removes the menu item by menuItemId.
#         RETURN VALUES(S): 'yes' or 'no' depending on success.
#!!ircMenuRemoveMatch(menuType,menuText,menuDest,functionName);
#         Removes the menu item by the exact menu definition.
#         RETURN VALUES(S): 'yes' or 'no' depending on success.
#  ircMsg(dest,message);
#         Sends a /msg, dest can be #channel name, nick name or =dcc nick
#         name.
#         RETURN VALUES(S): 'yes' or 'no' depending on success.
#  ircNotice(dest,message);
#         Sends a /notice to a user/channel/dcc.
#         RETURN VALUES(S): 'yes' or 'no' depending on success.
#  ircServerCmd(serverId,command);
#         Sends raw, unformatted data to the server.
#         RETURN VALUES(S): 'yes' or 'no' depending on success.
#  ircText(channelName,text);
#         Writes text to screen (in specific channel).
#         RETURN VALUES(S): 'yes' or 'no' depending on success.
#         NOTE! If channelName is "", then the text will go to the current
#               active window.
#!!ircTimerCallback(functionName,timeMS,...);
#         Hooks up a callback timer. After the specified amount of time
#         (given in milliseconds) the functionName is called with the
#         specified parameters (timeMS + everything after it).
#         The callback function must return 'yes' or 'no', depending on
#         whether the callback should stop here. So returning 'yes' keeps the
#         timer calling itself (with the same parameters) and returning 'no'
#         removes this timer from the timer-stack.
#         RETURN VALUES(S): 'yes' or 'no' depending on success.
#         NOTE! If you hook up any more timer callbacks in a timer callback
#               function, just be sure the hooks end up somewhere (so you
#               don't accidentally hook up over a million timer callbacks,
#               which is, without saying, slow ;).
#  ircUnBind(bindId)
#         Unbinds a previously bound event by the bindId returned by ircBind.
#         RETURN VALUES(S): 'yes' or 'no' depending on success.
#!!ircUnBindMatch(eventType,eventSpecifier,functionName);
#         Unbinds a previously bound event (the eventType, eventSpecifier
#         and functionName must be a perfect match). The reason for this to
#         work is that you can do one binding only once with exactly the same
#         parameters (type/spec/func), so there can be only one binding of
#         any combination.
#         RETURN VALUES(S): 'yes' or 'no' depending on success.
#  ircUnBindCmd(bindId);
#         Unbinds a previously bound command by the bindId returned by
#         ircBindCmd.
#         RETURN VALUES(S): 'yes' or 'no' depending on success.
#!!ircUnBindCmdMatch(commandName,commandSpecifier,functionName);
#         Unbinds a previously bound command (according to name/specifier+
#         function).
#         RETURN VALUES(S): 'yes' or 'no' depending on success.
#
# '!!' means the function is yet-to-be-implemented.

#  HOW YAGIRC SCRIPTS MANAGES MULTIPLE SERVERS
#
#YagIrc can be connected to multiple servers at the same time. This, in the
#view of scripts, presents few problems. Here's how they are solved in yagIRC.
#Each server is given a serverId by yagIRC. This serverId presents the server
#from there on. You send and receive all information to yagIRC using these
#serverIds. When the serverId is not one of the parameters, it is included
#after the nick name separated by space (like "nick serverId") On most cases,
#if the server name is not given, then it applies to every server currently
#connected.


#  NOTES ON BOUND COMMANDS
#
#The script can bind any command to it's need, ie. the '/MSG' or '/QUIT'
#commands. This means that the original command is out of reach. There may
#be some need to still access the old commands, so by putting '//MSG' or
#'//QUIT' ignores effectively any bindings and ALWAYS uses the unbound
#commands (these work in the yagIRC itself also).

#  NOTES ON USERHOST
#
#The userHost returned by some events/commands is in the form of
#'who@where', not the common 'nick!who@where'. The nick is always given in a
#separate statement (to save a line or two of perl code required to split it).

# bind joins to channel #mikkeli
ircBind("join", "#mikkeli", join_msg);


# bind server connections
ircBind("connected", "", server_connected);


# connect to localhost at startup :)
ircCmd("", "/server localhost");


sub join_msg {
    ircNotice($_[0], "Hello ".$_[0].", this is just a stupid message sent to everyone who joins this channel.");
}


sub server_connected {
    ircText("", "%RHi there! So you've finally got this far and connected to IRC server!\n");
    ircCmd("", "/join #mikkeli");
}
