home *** CD-ROM | disk | FTP | other *** search
/ Dream 52 / Amiga_Dream_52.iso / Linux / Divers / yagirc-0.51.tar.gz / yagirc-0.51.tar / yagirc-0.51 / irc.pl < prev    next >
Text File  |  1998-05-06  |  16KB  |  289 lines
  1. #
  2. # The yagIRC script prototype + short manual
  3. #
  4. #  Copyright (C) 1998 Jere Sanisalo <jeress@iname.com> and Timo Sirainen
  5. # 
  6.  
  7. # CUSTOM SCRIPTS (use module_name;)
  8. # CUSTOM SCRIPTS
  9.  
  10.  
  11. # Commands (alphabetic order):
  12. #   *** commands marked with !! aren't implemented yet ***
  13. #  ircBind(eventType,eventSpecifier,bindTime,functionName);
  14. #         Binds an event to a SUB-function. The function depends on the
  15. #         event. The bind returns 'yes' is it was successfull (or 'no' if
  16. #         not). The bindTime is the amount of time (in milliseconds) the
  17. #         binding lasts (0 = forever).
  18. #         The callback functions should return 'yes' if they want the yagIRC
  19. #         to process the event also. Note that if many functions have been
  20. #         assigned to an event, then everyone must return 'yes' for yagIRC to
  21. #         process the event.
  22. #         List of all events:
  23. #          CONNECTED - Called when the server connection has been established
  24. #                      (and after the user has been logged on).
  25. #                      The function is in the type of:
  26. #                        functionName(serverId,serverName);
  27. #          CTCP     - Called when someone sends a CTCP-request (eg. a
  28. #                     'VERSION').
  29. #                     The function is in the type of:
  30. #                       functionName(nickName,userHost,destNick,ctcpData);
  31. #          DCCMSG   - Called when a dcc message has been received. The
  32. #                     eventSpecifier notifies the user nick on which to bind
  33. #                     the event (the connection may not necessary be up)..
  34. #                     The function is in the type of:
  35. #                       functionName(nickName,message);
  36. #          DISCONNECTED - Called when the server connection has been
  37. #                         disconnected.
  38. #                         The function is in the type of:
  39. #                           functionName(serverId,serverName);
  40. #          INVITE   - Called when someone invites you to a channel.
  41. #                     The function is in the type of:
  42. #                       functionName(nickName,channelName);
  43. #          IRCJOIN  - Called when someone joins the irc (kind of a notify).
  44. #                     The irc-nick is given in eventSpecifier.
  45. #                     The function is in the type of:
  46. #                       functionName(nickName,userHost);
  47. #          IRCPART  - Called when someone leaves the irc (kind of a notify).
  48. #                     The irc-nick is given in eventSpecifier.
  49. #                     The function is in the type of:
  50. #                       functionName(nickName,userHost);
  51. #          JOIN     - Called when someone joins a channel. The eventSpecifier
  52. #                     notifies the channel on which to bind the event (""
  53. #                     means all channels).
  54. #                     The function is in the type of:
  55. #                       functionName(nickName,userHost,channelName);
  56. #                     NOTE! Here only the channelName has the server info.
  57. #          KICK     - Called when someone is kicked out of a channel you're
  58. #                     on.
  59. #                     The function is in the type of:
  60. #                       functionName(kickerNick,ChannelName,kickedNick,kickedUserHost,kickReason);
  61. #                     NOTE! Here only the channelName has the server info.
  62. #          MODE     - Called when the channel mode has been changed. The
  63. #                     eventSpecifier notifies the channel on which to bind
  64. #                     the event ("" means all channels).
  65. #                     The function is in the type of:
  66. #                       functionName(nickName,userHost,channelName,modeString);
  67. #                     NOTE! The modeString contains the whole mode-string,
  68. #                           ie. '+oo-o john ira turbo'.
  69. #          PART     - Called when someone leaves a channel you're on. The
  70. #                     eventSpecifier notifies the channel on which to bind
  71. #                     the event ("" means all channels).
  72. #                     The function is in the type of:
  73. #                       functionName(nickName,userHost,channelName,leaveMsg);
  74. #          PRGQUIT  - Called upon the program quit (when yagIrc needs to
  75. #                     end the script for some reason).
  76. #                     The function is in the type of:
  77. #                       functionName();
  78. #          PRIVMSG  - Called when a private message is written to you.
  79. #                     The function is in the type of:
  80. #                       functionName(nickName,userHost,message);
  81. #          PUBMSG   - Called when a message is written in a channel. The
  82. #                     eventSpecifier notifies the channel on which to bind
  83. #                     the event ("" means all channels).
  84. #                     The function is in the type of:
  85. #                       functionName(nickName,channelName,message);
  86. #                     NOTE! Here only the channelName has the server info.
  87. #          SERVERMSG - Called when the server sends up some text (ie. motd or
  88. #                      anything, just as long as it's sent by the server).
  89. #                      The function is in the type of:
  90. #                        functionName(serverId,message);
  91. #          TOPIC    - Called when the topic changes on a channel you're on.
  92. #                     The function is in the type of:
  93. #                       functionName(nickName,userHost,channelName,topic);
  94. #          QUIT     - Called when someone who was on one or more of the 
  95. #                     channels you're on quits.
  96. #                     The function is in the type of:
  97. #                       functionName(nickName,userHost,channelNames,leaveMsg);
  98. #                     NOTE! The channelNames is a list of all the channels
  99. #                           you know the user was before quitting, separated
  100. #                           by a space.
  101. #                     NOTE! This is called before IRCPART.
  102. #         RETURN VALUES(S): The event binding id (given by yagIrc), or "" if
  103. #                           there was an error.
  104. #         NOTE! Where 'nickName' (or any nick in general) is the first
  105. #               parameter, then the nick has the server info (and all other
  106. #               nicks/channels do not have it).
  107. #         NOTE! One binding type can only be done once (so no two exactly
  108. #               the same bindings can be done, although even a small
  109. #               difference is enough for the binding to happen)!
  110. #  ircBindCmd(commandName,commandSpecifier,functionName);
  111. #         Binds a local command. For example if you bind "test", then typing
  112. #         '/TEST' in yagIRC would call this function. Everything written
  113. #         after the command on irc will be passed as a single argument to the
  114. #         function.
  115. #         The commandSpecifier depends on commandName. Here's the list of
  116. #         special commandNames:
  117. #          '/JOIN'  -
  118. #          '/PART'  - The eventSpecifier specifies the channel to bind.
  119. #          '/MSG'   - The eventSpecifier specifies the user (dest) to bind.
  120. #         RETURN VALUES(S): The event binding id (given by yagIrc), or "" if
  121. #                           there was an error.
  122. #         NOTE! Each command (type) may be bound only once!
  123. #         NOTE! When eventSpecifier would otherwise be used, giving a "" means
  124. #               to bind the command in whole.
  125. #         NOTE! Beware of looped commands (bind a command and inside that
  126. #               command call the same command again (infinite recursive
  127. #               loop)).
  128. #  ircCmd(channelName,command);
  129. #         Issues a command (like "/names #test").
  130. #         RETURN VALUES(S): 'yes' or 'no' depending on success.
  131. #         NOTE! Beware of looped commands (bind a command and inside that
  132. #               command call the same command again (infinite recursive
  133. #               loop)).
  134. #  ircCTCPSend(dest,ctcpData);
  135. #         Sends a CTCP request to a user (dest can be a channel or a nick).
  136. #         RETURN VALUES(S): 'yes' or 'no' depending on success.
  137. #  ircCTCPReply(nickName,ctcpData);
  138. #         Sends a CTCP reply to a user.
  139. #         RETURN VALUES(S): 'yes' or 'no' depending on success.
  140. #!!ircGetChannelList(serverId);
  141. #         Gets the list of joined channels in a server.
  142. #         RETURN VALUES(S): Channel list (list of strings).
  143. #!!ircGetLocalUserInfo(serverId);
  144. #         Gets the local user (the user the yagIrc is connected) info on a
  145. #         server.
  146. #         RETURN VALUES(S): On failure a 'undef' is returned.
  147. #                           On success, the return is a list, which has the
  148. #                           the folloring items (in the same order):
  149. #                             userNick,userHost,userName
  150. #!!ircGetNameList(channelName);
  151. #         Gets the users of a channel. The list returned will contain a
  152. #         string per user (the user will have any irc-additions in from of
  153. #         the nick, ie. a '@' if the user is an operator and a '+' is the
  154. #         user has voices etc.).
  155. #         RETURN VALUES(S): User list (list of strings).
  156. #         NOTE! The channelName-parameter should have the multiserver-ids
  157. #               embedded on it (if not, then every server connected will
  158. #               be checked and added to the list). Remember, every nick ends
  159. #               with ' serverId' (where serverId is the id of the server).
  160. #!!ircGetServerIdList();
  161. #         Gets a list of the connected server ids and the servers addresses.
  162. #         The list has ID-ADDRESS-pairs, so the return value is ready to be
  163. #         hashed.
  164. #         RETURN VALUES(S): Server Id+address list (list of strings).
  165. #!!ircGetTopic(channelName);
  166. #         Gets the channel topic.
  167. #         RETURN VALUES(S): The topic is returned, or 'undef' if there was an
  168. #                           error.
  169. #         NOTE! The channelName must have the multiserver-id, or else this
  170. #               command fails.
  171. #  ircMenuAdd(menuType,menuText,menuDest,functionName);
  172. #         Adds a menu item to any of the menus (main/channel/nick). The
  173. #         menuText is the text displayed in the menu. The menuDest is the
  174. #         destination for the menu item (if the menuType does not have a
  175. #         destination, then set this to "", see the list at the end of the
  176. #         the command-description). The functionName is the callback function
  177. #         (defined as: functionName(menuType,menuDest,menuItemId);).
  178. #         The menu types are as follow:
  179. #           GLOBAL - Global menus for every window (no menuDest!).
  180. #           CHANNEL - Channel specific pop-up menus (menuDest is the channel
  181. #                     name).
  182. #           NICK - Nick name specific pop-up menus (menuDest is the nick name
  183. #                  to bind).
  184. #         RETURN VALUES(S): The menuItemId (for later menu access). On error
  185. #                           the returned value is "".
  186. #         NOTE! One type of menu binding can only be done once!
  187. #  ircMenuRemove(menuItemId);
  188. #         Removes the menu item by menuItemId.
  189. #         RETURN VALUES(S): 'yes' or 'no' depending on success.
  190. #!!ircMenuRemoveMatch(menuType,menuText,menuDest,functionName);
  191. #         Removes the menu item by the exact menu definition.
  192. #         RETURN VALUES(S): 'yes' or 'no' depending on success.
  193. #  ircMsg(dest,message);
  194. #         Sends a /msg, dest can be #channel name, nick name or =dcc nick
  195. #         name.
  196. #         RETURN VALUES(S): 'yes' or 'no' depending on success.
  197. #  ircNotice(dest,message);
  198. #         Sends a /notice to a user/channel/dcc.
  199. #         RETURN VALUES(S): 'yes' or 'no' depending on success.
  200. #  ircServerCmd(serverId,command);
  201. #         Sends raw, unformatted data to the server.
  202. #         RETURN VALUES(S): 'yes' or 'no' depending on success.
  203. #  ircText(channelName,text);
  204. #         Writes text to screen (in specific channel).
  205. #         RETURN VALUES(S): 'yes' or 'no' depending on success.
  206. #         NOTE! If channelName is "", then the text will go to the current
  207. #               active window.
  208. #!!ircTimerCallback(functionName,timeMS,...);
  209. #         Hooks up a callback timer. After the specified amount of time
  210. #         (given in milliseconds) the functionName is called with the
  211. #         specified parameters (timeMS + everything after it).
  212. #         The callback function must return 'yes' or 'no', depending on
  213. #         whether the callback should stop here. So returning 'yes' keeps the
  214. #         timer calling itself (with the same parameters) and returning 'no'
  215. #         removes this timer from the timer-stack.
  216. #         RETURN VALUES(S): 'yes' or 'no' depending on success.
  217. #         NOTE! If you hook up any more timer callbacks in a timer callback
  218. #               function, just be sure the hooks end up somewhere (so you
  219. #               don't accidentally hook up over a million timer callbacks,
  220. #               which is, without saying, slow ;).
  221. #  ircUnBind(bindId)
  222. #         Unbinds a previously bound event by the bindId returned by ircBind.
  223. #         RETURN VALUES(S): 'yes' or 'no' depending on success.
  224. #!!ircUnBindMatch(eventType,eventSpecifier,functionName);
  225. #         Unbinds a previously bound event (the eventType, eventSpecifier
  226. #         and functionName must be a perfect match). The reason for this to
  227. #         work is that you can do one binding only once with exactly the same
  228. #         parameters (type/spec/func), so there can be only one binding of
  229. #         any combination.
  230. #         RETURN VALUES(S): 'yes' or 'no' depending on success.
  231. #  ircUnBindCmd(bindId);
  232. #         Unbinds a previously bound command by the bindId returned by
  233. #         ircBindCmd.
  234. #         RETURN VALUES(S): 'yes' or 'no' depending on success.
  235. #!!ircUnBindCmdMatch(commandName,commandSpecifier,functionName);
  236. #         Unbinds a previously bound command (according to name/specifier+
  237. #         function).
  238. #         RETURN VALUES(S): 'yes' or 'no' depending on success.
  239. #
  240. # '!!' means the function is yet-to-be-implemented.
  241.  
  242. #  HOW YAGIRC SCRIPTS MANAGES MULTIPLE SERVERS
  243. #
  244. #YagIrc can be connected to multiple servers at the same time. This, in the
  245. #view of scripts, presents few problems. Here's how they are solved in yagIRC.
  246. #Each server is given a serverId by yagIRC. This serverId presents the server
  247. #from there on. You send and receive all information to yagIRC using these
  248. #serverIds. When the serverId is not one of the parameters, it is included
  249. #after the nick name separated by space (like "nick serverId") On most cases,
  250. #if the server name is not given, then it applies to every server currently
  251. #connected.
  252.  
  253.  
  254. #  NOTES ON BOUND COMMANDS
  255. #
  256. #The script can bind any command to it's need, ie. the '/MSG' or '/QUIT'
  257. #commands. This means that the original command is out of reach. There may
  258. #be some need to still access the old commands, so by putting '//MSG' or
  259. #'//QUIT' ignores effectively any bindings and ALWAYS uses the unbound
  260. #commands (these work in the yagIRC itself also).
  261.  
  262. #  NOTES ON USERHOST
  263. #
  264. #The userHost returned by some events/commands is in the form of
  265. #'who@where', not the common 'nick!who@where'. The nick is always given in a
  266. #separate statement (to save a line or two of perl code required to split it).
  267.  
  268. # bind joins to channel #mikkeli
  269. ircBind("join", "#mikkeli", join_msg);
  270.  
  271.  
  272. # bind server connections
  273. ircBind("connected", "", server_connected);
  274.  
  275.  
  276. # connect to localhost at startup :)
  277. ircCmd("", "/server localhost");
  278.  
  279.  
  280. sub join_msg {
  281.     ircNotice($_[0], "Hello ".$_[0].", this is just a stupid message sent to everyone who joins this channel.");
  282. }
  283.  
  284.  
  285. sub server_connected {
  286.     ircText("", "%RHi there! So you've finally got this far and connected to IRC server!\n");
  287.     ircCmd("", "/join #mikkeli");
  288. }
  289.