WRITING MODULES FOR IQ <=0.9.2 (0.9.3+ may not act as expected, documentation in the works)

This file will explain, in some detail, the standards used by IQ and how to get started writing your own modules for your bot.

* Object Oriented Nature
	IQ uses Object Oriented PHP, mainly to keep a sense of code organization. While the IQBot class is not exactly plug-and-play in the traditional class sense, it still helps in keeping code neat. See the code for IQ 0.1.x if you're confused on how ugly the code can be when it isn't spread out.

* Library: library.php
	This file contains (mostly) functions that are used by IQ, that could be used by other programs.

* Objects, methods, and variables, oh my.
>> $bot
	$bot is the object created from the IQBot class. It is referred to as $bot when used in core.php, and inside a pseudo-function created by a module (lambda-style function created by create_function()). However, it is referred to as $this inside class.IQBot.php, as the IQBot class is origin of the object.

	Since the rehash() method (in $bot) loads the config.php file, it will therefore run the code in config.php inside of the method. As rehash() is a method in the $bot object, the config.php must also use the $this reference. When $this->loadmodule() is called from the config.php file, the loadmodule() method will include the code from the module. Similarly to rehash(), the module code is inherently inside the original $bot object, and thus must use the $this context. Make sense?
	
	When creating lambda-style functions (using PHP's create_function()), you must first "global $bot", and then refer to the $bot object as simply $bot. DO NOT use traditional functions (function yourfunc($args) { code; }) in modules, as PHP will not allow you to redefine functions and will freak out when you perform a rehash to reload the modules.
	
>> Variables used by IQ
	NOTE: for this section, I will use the "$bot->" context for purposes of example only. It is up to you to figure out when it is appropriate to use $this and $bot. Read the above section on "$bot" for an explanation.
	
	$bot->functions[]
		This is an array of lambda-style functions for exclusive use by modules. All functions in modules should use the lambda-style as in http://php.net/create_function, which basically assigns a function to a variable so that it may be unset and reset. This is a workaround for PHP not allowing the redeclaration of functions.
		
		It is a standard that the string of args for create_function is simply '$args'. You must use single quotes or double quotes with a backslash (\) before the $, otherwise $args will be evaluated. When $bot->execbind() is called by IQ, it will send an array of information to the module's function.
	
	$bot->info[]
		This is an array of information containing information discovered after it has started and while it is connected to IRC.
	
		$bot->info["my_channels"][]
			Array of channels split from the $bot->config["chans"] setting.
		
		$bot->info["in_channels"][]
			Array of channels the bot is currently in.
			
		$bot->info["channel_users"][]
			Extended array of users in the channels the bot is in and information about them.
			
		$bot->info["channel_topics"][]
			Array of topics of the channels the bot is in.
		
		$bot->info["user_counts"][]
			Array of users in each channel the bot is in.
			
		$bot->info["lagcheck"]
		$bot->info["lagcheck_reply"]
			Strings used by IQ's lag-checking code.
			
		$bot->info["lag"]
			Informational number containing the bot's lag from the IRC server. Measured in seconds.
		
		$bot->info["registered"]
			Boolean setting that is set when the bot is connected to IRC and registered (has a nickname)
		
		$bot->info["network"]
			String containing the name of the network the bot is connected to.
		
		$bot->info["server"]
			String containing the name of the server the bot is connected to.
			
		$bot->info["mynick"]
			String containing the current nickname of the bot.
			
		$bot->info["modes_with_args"]
			String of modes that have arguments. Used by IQ's MODE event handling code.
		
		$bot->info["trig_prefix"]
			String containing a regex-safe trigger prefix that is converted from the config setting.
			
	$bot->buffering
		Boolean setting that globally enables or disables buffering. Turned on by default at connect time.
		
	$starttime
		Variable containing epoch of bot's beginning.
		
>> Useful IQ methods
	The following methods are used throughout the IQ core, and will help in writing modules.
	
	/* IRC Related */
	
	$bot->action($target,$action,$verbose=1,$buffer=true) 
	
	$bot->raw($text="",$buffer=true)
		Sends $text to the IRC server. Pass false to $buffer to skipping the queueing process and send $text immediately
		
	$bot->msg($target,$text,$verbose=1,$buffer=true)
		Sends $text to $target. $target can be a channel or user. If $verbose is true (default), the bot will log itself saying the message to the user/channel. $buffer behaves the same way as in $bot->raw().
		
	$bot->notice($target,$text,$verbose=1,$buffer=true)
		Same as $bot->msg() for notices.
	
	$bot->mode($target,$modes,$buffer=true)
		Set $modes on $target

	$bot->ctcp($target,$type,$text,$verbose=1,$buffer=true)
		Send a CTCP message of $type to $target with $text

	$bot->ctcpreply($target,$type,$text,$verbose=1,$buffer=true)
		Reply to a CTCP message of $type with $text to $target
	
	$bot->join($target,$buffer=true)
		Join a channel $target. This will read from the internal list of channel keys and use a key from it if the key for $target is known.
	
	$bot->part($target,$reason="",$buffer=true)
		Part a channel $target
		
	/* Logging functions */
		
	$bot->log($text,$timestamp=true)
		Logs $text straight to the bot's console/buffer. $timestamp is a boolean to enable/disable the timestamp.
	
	$bot->infoLog($text,$timestamp=true)
		Alias for $bot->log that will automatically themeize $text to the "info" theme entry. See themes.php for more information.
	
	$bot->problemLog($text,$timestamp=true)
		Same as $bot->infoLog for the "problem" theme entry.
	
	$bot->debug($text)
		Will log $text only to buffer/console prefixed with "(debug)", if debug mode is on (set in config.php).
	
	/* Core related */
	
	$bot->replyto($msgtype,$sec=5)
		This method is designed to buffer responses so the bot will not flood. It will return true if $sec or greater has passed since $msgtype was last sent or false if not. $msgtype should be a unique keyword to describe the type of delay. 
		Example: if (!$bot->replyto("idle_msg",300)) { $bot->msg("#channel","This message will be said every five minutes (300 seconds) if this code is constantly called (probably by an "all" bind)"); }
		
	$bot->bind($type,$flags,$target,$trigger,$function)
		Bind $function to $trigger on $type event, if user (if any) has $flags (if any).
		
		Example: $this->bind("pub","","","<prefix>acro ",'acronymfinder'); // taken from acronym.mod.php
		The above example will bind the "acronymfinder" function to type "pub" on any target. Flags is obviously blank, so the function will be called by anyone that typed "<prefix>acro ".
		NOTE: <prefix> is internally replaced by the core with the actual trig_prefix set in the config. (More specifically, it is replaced with the one in the $bot->info[] array, which is regex safe.) As of IQ 0.9.1, the nickname can be used as a prefix in the form of "nick, " or "nick: " or "nick; "
		
		BIND TYPES:
			The following is a list of current events that can be bound to.
			
			"pub"		executed on a channel message
			"msg"		executed on a private message
			"pubm"		executed on a channel message or private message
			"join"		runs when someone joins a channel
			"part"		runs when someone parts a channel
			"nick"		executed when someone changes his or her nickname
			"quit"		executed when someone quits IRC
			"topic"		executed when someone changes the topic
			"invite"		executed when someone is invited
			"kick"		executed when someone is kicked from a channel
			"raw"		executed on any numeric message, the numeric is passed as $args["trigger"]
			
			"idle"		executed when the bot is idling and has received no text from the server
			"connect"		executed on connect to the server, before registering
			"register"	executed when the bot has successfully registered (obtained a nickname)
			"all"		executed on all events, will be executed at least once a second
			
>> Module hacking
	If you have a bit of an understanding of the above, you can start writing your own module. The basic things you need for a module are a $this->bind() call, and a $this->functions["yourfunc"] function.
	
	Dissection of a an IQ module (opme.mod.php):
		<?php	
		$this->bind("pubm","o","","^opme","opme");
			
		$this->functions["opme"]=create_function('$args','
			// print_r($args) // do this if you want to see the argument array sent to the function
			// global $bot so can use it
			global $bot;
			// $args["extmsg"] is a string containing all words after the first in the message
			// select the chan to op the user in
			$chan=($args["extmsg"]) ? strtolower($args["extmsg"]) : $args["target"]; 	
			
			// determine if the bot is an OP and the user is in the channel requested
			// if, so op the user.
			if ($bot->info["channel_users"][$chan][$bot->info["mynick"]]["modes"]["o"] && $bot->info["channel_users"][$chan][$args["nick"]]) {
				$bot->mode($chan,"+o {$args["nick"]}");
			}
		');
		
		$this->infoLog("Opme module loaded");
		?>
			
More documentation to come at a later date. For now, you may look at the official modules that I have written, provided in the modules directory of the latest IQ release available at http://f0rked.com/IQ
			
			
			
	
	
