Xbot › Documentation

From Botdom Documentation

The correct title of this article is xbot/Documentation. The initial letter is capitalized due to technical limitations.

This page could be in the process of being Moved from the Botdom Wiki.
Go to this article on the Wiki!

Template:Menu/xbot

Template:Header/xbot

Last updated at version 1.2

1 Global variables
- 1.1 System trigger
2 Functions
3 Classes

Global variables

$rd, $rdx, $rdlg, $rdsv: path of bot's root folder, modules folder, logs folder, and savedata folder respectively
$sdlg, $sdsv: path of bot's server logs folder and server savedata folder respectively
$sys_info: Static array. Contains information data, such as admin/abouttext. Defined in config.php
$sys_cfg: Static array. Contains configuration data, such as user/pass/trigger/homechannels etc. Defined in ~/config.php
$sys_cl: Object containing network functions. Initiated and populated in ~/system/load.php
$sys_ch: Similar to NoodleBot/dAmnBot's $properties, except that $sys_ch[channel] is a dAmnChan object. Initiated in ~/system/load.php and populated when needed.
$sys_users: An array of User objects. Initiated in ~/system/load.php and populated when needed.
$sys_privs: An array of arrays. Contains privclass names/members. Initiated in ~/system/load.php. Data is auto-synchronised with $sys_users using cacheUsers(); and cachePriv();
$sys_mod: An array of Module objects. Initiated and populated (once) in ~/system/load.php
$sys_evt: Contains data for events, including their current status. Its keys are defined in ~/system/class.modules.php and its values are populated (once) in ~/system/load.php
$sys_modsys: Static array. Lists the system modules. Defined in ~/system/class.modules.php

System trigger

$sys_trg

An array containing data about the last triggered event/command. The array contains:

type: The type of trigger. Ideally one of the triggertypes as defined in $sys_evt. (type == 'cmds' for commands.)
mod: Module which the command/event belongs to.
subj: Subject of the event/command. (For kick/privchg, this is the kickee/privchangee.)
obj: Object of the event. (obj is blank for commands.) (For kick/privchg, this is the kickER/privchangER.)
chan: Channel in which the event/command took place.
cmd: Command name. (cmd is blank for events.)
args: Any arguments passed by the event/command.

Any one of these may be blank, except type which always has a value.

Functions

Misc

This documents the functions in ~/system/functions.php. At the moment it is incomplete.

args(ARGUMENT_STRING,(RETURN_NUMBER|OFFSET_ARRAY)[,SEPARATOR])

Explodes ARGUMENT_STRING on occurences of SEPARATOR (default value ' ') into RETURN_NUMBER parts. If the resulting array has less elements than RETURN_NUMBER, it is array_pad() with [emptystring] up to RETURN_NUMBER of elements. Alternatively, explosion is done at each OFFSET (a negative OFFSET indicates an offset from the right);. Examples:

args('a b c',4) gives array('a','b','c','')
args('a b c d e f g h',4) gives array('a','b','c','defgh')
args('a b c d e f g h',4,array(1,4,-1)) gives array('a','bcd','efg','h')
args('a-b-c-d-e-f-g-h-i-j-k-l-m-n',10,array(1,4,-3,-1),'-') gives array('a','bcd','efghijk','lm','n','','','','','')

IT IS IMPORTANT TO NOTE THAT list($command,$name,$channel) = args('promote infinity0 #Botdom accidental extra stuff',3) results in $channel='#Botdom accidental extra stuff' whilst list($command,$name,$channel,) = args('kick infinity0 #Botdom accidental extra stuff',4) gives you the desired result, $channel='#Botdom'. For this reason it is recommended to use list($command,$name,$channel,) in your code, with the extra comma, to clarify to future coders that any "extra accidental stuff" is returned by the function in an array key separate from the last desired argument, and discarded (not stored in any variable).

Data functions

loaddata(FILE,SERIALISE): If SERIALISE is true (default), returns the data of the file, unserialised. If SERIALISE is false, returns the lines of a file. If $sys_trg['mod'] is set and different from the FILE first directory, returns false.
savedata(ARRAY,FILE,SERIALISE): If SERIALISE is true (default), saves the serialised ARRAY into FILE. If SERIALISE is false, implodes the array with newline and saves it into FILE. If $sys_trg['mod'] is set and different from the FILE first directory, returns false.
verifyModFile(FILENAME): Checks which module the incoming command is coming from. Returns TRUE if the incoming command is from the FILENAME-first-directory module or no module (empty string). Returns FALSE otherwise.

User/Priv functions

These are global functions, not attached to a User object, but meant to be used on a User object (which may or may not exist).

whoisUser(USER): Sends a whois request to dAmn.
purgeDefaultUsers(USER_ARRAY): takes a user array and returns the same array, but without the users which have $sys_priv['default']. The parameter user array is NOT changed.
saveUsers(): purges $sys_users and saves the resulting data to savedata/users.txt. (Note: Because purgeDefaultUsers() does not change any variables, $sys_users is not changed; only the purged form is saved to file.)
cacheUsers(): synchronises $sys_privs with $sys_users, specifically priv/member data.
savePrivs(): saves a stripped version of $sys_privs (specifically, priv/member data removed) to savedata/privs.txt. $sys_privs is not changed itself.
hasMinPriv(USER,PRIV): Returns true if USER has PRIV or more. If PRIV is a boolean, it returns PRIV.
hasMaxPriv(USER,PRIV): Returns true if USER has PRIV or less. If PRIV is a boolean, it returns PRIV.
parsePriv(PRIV[,RETURNSTRING]): If PRIV is a privclass value (integer) or name (string), it returns the corresponding privclass value (integer) or name (string) depending on whether RETURNSTRING is true or (false/omitted). If PRIV is false, returns false. If PRIV is null, returns true.

Trigger functions

These control the data in $sys_trg, which stores data for the last triggered event.

setTrgData(SUBJECT,OBJECT,CHANNEL,COMMAND,ARGS): self explanatory
setTrgType(TYPE): self explanatory
setTrgModule(MODULE): self explanatory
getTrgData(RESET): returns an numerically indexed array consisting of TYPE,MODULE,SUBJECT,OBJECT,CHANNEL,COMMAND,ARGS. If RESET == 'reset', it resets $sys_trg.

Classes

Module

Module(NAME)

$name, $evts[evttype][data], $status, $loaded, $priority

$info

an array containing

auth: comma-delimited list of authors
v: version
title: title of module
about: UNPARSED description (use $module->about() to parse it).

$data: an array in which you may store any data you wish, for example, to keep track of arguments in between commands.
setInfo(AUTHORS,TITLE,VERSION[,DESCRIPTION]): Sets the module's info. AUTHORS is a comma delimited list of authors. Eg, "infinity0, electrinet". For the DECSRIPTION, the strings "{author}" or "{authors}", "{devauthor}" or "{devauthors}", "{title}", "{version}" will be replaced by (a comma delimited list of authors), (a comma delimited list of authors with links to their dA pages), (module title) and (module version) respectively. The default value of DESCRIPTION is "{title} {version} by {devauthors}.".
authors(): returns an array of the module's authors
about(): returns the parsed description of the module
addCmd(COMMAND_NAME,COMMAND_FILE[,LOWEST_USER_PERMISSION]): adds a new command to module data. LOWEST_USER_PERMISSION has a default value of 'd' which sets the priv to the system default. If LOWEST_USER_PERMISSION is null, then the command runs for all users.
addCmdInfo(COMMAND_NAME,DESCRIPTION,SYNTAX): adds description and syntax data for the command. Or, if DESCRIPTION is "aliasfor", then the information is retrieved from the command called SYNTAX.
setCmdStatus(COMMAND,STATUS): self explanatory
addEvt(TRIGGER_NAME,COMMAND_FILE[,LOWEST_USER_PERMISSION]): adds a new event to module data. LOWEST_USER_PERMISSION has a default value of 'd' which sets the priv to the system default. If LOWEST_USER_PERMISSION is null, then the event runs for all users.
addEvtInfo(TRIGGER_NAME,COMMAND_FILE,DESCRIPTION): adds description data for the event.
setEvtStatus(TRIGGER_NAME,FILENAME,STATUS): self explanatory
load(): loads module into system events. Automatically called by loading script.
setStatus(STATUS): If STATUS is true, sets all commands/events to its default status. If STATUS is false, it switches them off. System & core modules cannot be deactivated.
loaddata(FILENAME): same as global function, except it loads from the module subfolder. Returns false if FILENAME contains '../'.
savedata(ARRAY,FILENAME): same as global function, except it saves into the module subfolder. Returns false if FILENAME contains '../'.
verifyMod(): Checks which module the incoming command is coming from. Returns TRUE if the incoming command is from this module or no module (empty string). Returns FALSE otherwise.

User

User(NAME)
$name, $priv
setPriv(PRIV)
cachePriv(PRIV): synchronises user priv data to $sys_users.
[hasMinPriv(PRIV), hasMaxPriv(PRIV)]: almost never used; exactly the same as the global functions, which also work even for non-existent or unregistered users

dAmnChan

dAmnChan(NAME)
$title[p,by,ts,data], $topic[p,by,ts,data], $members[name][pc,usericon,symbol,realname,typename,gpc,count], $pcs[number][name,perms,members]
getTitle()
getTopic()
userJoined(USER,PRIV): used in bot's system. Should not be used in modules.
userParted(USER): used in bot's system. Should not be used in modules.
userKicked(USER): used in bot's system. Should not be used in modules.
userPrivChged(USER,PRIV): used in bot's system. Should not be used in modules.
parsePriv(PRIV[,RETURNSTRING])
[getPrivMembers() not implemented as of 1.2]

dAmn

dAmn(SERVER,LOGIN)
$channels, $client, $server, $socket, $connected, $loggedin, $loggedsince, $connects, $buffer, $data, $pkt
open()
close()
connect()
login(RESET): If RESET is true, re-gets authtoken from server
checkQueues()
listen()
processIncoming(DATA)
processMessage(FROM,MSG,CHAN,TYPE)
command(CMD,ARGS,FROM,CHAN)
event(TRIGGER,FROM,TARGET,CHAN,ARGS)
joinchans()
send(DATA)
join(CHAN)
pchat(USER)
msg(CHAN,MSG,TYPE)
promote(CHAN,USER,PRIV)
demote(CHAN,USER,PRIV)
ban(CHAN,USER)
unban(CHAN,USER)
kick(CHAN,USER,REASON)
set(CHAN,PROPERTY,TYPE)
admin(CHAN,TYPE,TYPEVAL[,PRIV[,VALS]])
part(CHAN)
whois(USER)
dc(): disconnects gracefully
parseChan(CHAN): returns chat:ChannelName or pchat:BotName:UserName
parsePChan(USER1,USER2): returns a well-formed pchat Channel when given two users
formatChan(CHAN): returns #ChannelName or @UserName
findWho(USER): checks if USER is in any of the channels as the bot is in
urgtMsg(USER): sends a message via dAmn to USER, if bot is able to. Used for system messages such as bot crash.
parseTabLumps(TEXT)
symbol(NAME);get_token(),

Retrieved from "http://botdom.com/documentation/Xbot/Documentation"

Categories: Moving | Documentation