Plugin Stats Question Stats Add A Question Home CCX Documentation StealthBot.net STW





:Welcome to CCX Documentation:

[UNDER CONSTRUCTION]
Last update 03/03/09.- Relevent for CCX V 1.9

INDEX

Commands



NOTE: These commands will respond with help when used incorrectly.

listcc:
Lists out all commands that the user has access to use.

findcc [Part of command name]:
Finds all commands with the search string supplied.
Example: !findcc news
Response: Matching commands (that you can use): addnews, delnews, news

addcc [Name] [Access/Flags(optional)] [Command Response]
View Examples

delcc [Name]
Deletes the command.

editcc [Name] [New Response]
Example: !editcc MyCmd New Response

appendcc [Name] [Data added at the end of Command]
Appends the command.
Example: !appendcc MyCmd Additional text.
Command now contains 'Response Additional text'

renamecc [Name] [New Name]
Renames the command.

showcc [Name]
Returns the command response of chosen command.

testcc [CCX Code]
Tests CCX-Function-Only code. - Used for experimentation.
Example: !testcc %if(1=2,True,False)

reloadcc
Reloads custom commands from text file.

setcc [Name] [NewAccess/NewFlags(Optional)]
Sets command access for
Example: !setcc MyCmd 50

clipcc [Name]
Puts the command on the bot-owners clipboard- useful for re-writing or modifying a command.

sortcc
Sorts the commands file - so commands will be listed alphabetically in commands like !listcc and !findcc



Setting Aliases


Aliases are set in your "PluginSettings.ini" 2.6R3 or "Settings.ini" BETA. Located in your Plugin folder.
Open the settings file and find [CCX]
You should find 2 examples of an Alias: Alias_addcmd=addcc and Alias_delcmd=delcc
If you wanted to create an alias for findcc you would add this line under [CCX]
Alias_findcmd=findcc
Notice it's:
Alias_WHATVERYOUWANT=Command



Setting Access


Access for built-in commands is set in your Plugin's Setting file.
BETA: Plugins > Options > Open Settings.ini
Open the settings file and find [CCX]
You will find these lines:
access_listcc=20
access_findcc=20
etc. Simply change the numbers to your desired access.

Examples


More examples pending....

Making a simple command.
Upgrading a simple command.
Advanced commands.

CCX Add-On support

CCX was designed to be added-onto by other plugins. Many features have been designed to make it easy to interact with the CCX plugin. The main one being:

Registering Functions to CCX

(For VBs scripters only)
Functions can be registered to increase functionality to the CCX plugin. An example of this is the CCXE plugin, which adds (among others) the %speak function.
How to register a function:

First you should remember to only register functions after checking if CCX is installed:
If psVersions.Item("ccx") Then

ccx.RegisterFunction(Name, CallBack, Args, Priority)
Example usage:
Sub Event_Load()
  ccx.RegisterFunction "speak", "ccxe_speak", 1, 2
End Sub
Public Function ccxe_speak(Text)
  spvoice.Speak Text, 17
End Function

Now, lets go over the arguments.

ccx.RegisterFunction(Name, CallBack, Args, Priority)
Name (String)
The name of the function to be used in CCX. In the above example the function will be called with %speak(Text).
CallBack (String)
The name of the function to be executed.
Args (Int)
The number of arguments the function has.
Note; you cannot require the user to use a specific number. The %function(arguments) will always be optional.
If not all arguments are inputed in the CCX function, VBNullString will be used for the missing data.
Priority (Int) (MUST be a 1 or 2)
CCX uses multiple passes to parse the CCX code - as some functions need to be parsed sooner than others.
An example CCX statment shows why this is required:
%if(%user=Snap,%setvar(OhSnap,True),%setvar(OhSnap,False))
If %setvar is parsed before the %if function this would result in %setvar being executed the same way every time.
So, even though %setvar is nested within the %if function, it is parsed after %if is.
%setvar is a Priority 2 function, and %if is a Priority 1 function.

%if(%var(OhSnap)=True,Yes,No)
%var is also a Priority 1 function.- As it needs to be parsed in the natural nesting order for the %if to function correctly.

Basically you can rely on this to decide the priority.
If it is setting or modifying data or doing something it should be priority 2.
If it is getting/comparing/using data it should be priority 1.

Priority is important - for example, if %speak was a Priority 1 function, this would not work:
%if(%var(dospeak)=true,%speak(%rest),Not going to say anything)


The RunCC Sub

(For VBs scripters only)
The ccx_runcc sub was created to skip the PressedEnter process and give you some more options.
This makes it easy to have make a CC execute in any manner you wish. - To whisper it, check access - run silently - etc.
If you wish to simply execute some CCX code - see below; ParseFunctions
(Note: If a command is run from source "Enter" emotes and talk will be addchated, but kicking/banning and other battle.net specific commands will be executed.)

'//Command Name, Username, Arguement string, Source(Enter, Talk, Whisper, UEnter (double-slash enter //dance))
Public Sub ccx_runcc(Name, Username, Arguments, Source)

Sounds strait forward right? Well it is. But I have to document it anyway - so here we go.
Name (String)
The name of the command you want to execute, duh.
Username (String)
The name of the username you want it to be executed as - note that access will be checked - and %user will be affected.
To avoid this access check, you can use UEnter as the source. - However there is no way to avoid the access check and use Whisper as source. Sorry. (as far as V1.9)
Arguments (String) (Not an array)
Text to be used in the command - such as %1 %2 %rest %all etc.
Source (String) (Must be one of the following: Enter, Talk, Whisper, UEnter)
The source the command will act as if it was executed from.
[Enter]: Command will run silent, all CCX code will be executed, but the resulting text will be Addchated not Addq'd. Exceptions are battle.net commands other than /emote and /me.
[Talk]: Command will run as if someone said it from the channel.
[Whisper]: As if someone whispered the bot the command.
[UEnter]: Command will run as if someone said it from the channel - with unlimited access.

Again, just a reminder - before calling this sub arbitrarily to do a check:
If psVersions.Item("ccx") Then


The ParseFunctions Function

(For VBs scripters only)
The ParseFunction Function does exactly that. It executes "CCX Code" and returns the result.

ccx.ParseFunctions(Text)
Usage:
strRes = ccx.ParseFunctions(strRes)
Example:
MyString = ccx.ParseFunctions("%ucase(hello world!!)")
MyString is now "HELLO WORLD!!"

Rather than using the RunCC Sub you could use this sub to modify CCX variables like so:
MyResult = ccx.ParseFunctions("%setvar(VarName,New var data)")

This way you can interact with your CCX commands on a plugin-level.

Security
Remember, if you use dynamic data in ParseFunctions you may open a security or parsing issue. - As "(),%" are all special chars used in the CCX Engine.
For example, if you used the VBs Variable MyChannel and in ccx.ParseFunctions and someone made the bot join channel "%setvar(whatever,whatever)" That code would execute. - Or if they just joined a channel with a ) in it, you may mess up the nesting order of the CCX Code!
Don't worry, I have you covered. I use Hidden-Escape chars. To make something not execute use:
Text = ccx.AddEscape(Text)
If you ever used PHP or SQL you may already have the concept of Escaping code. For example, the PHP Function "AddSlashes". - The same concept applys. - Except that I use rare ASCII chars to get the job done.
The ccx.AddEscape function will replace all (),% chars with different chars.
At the end of ccx.ParseFunctions these chars are replaced back with the (),% they were meant to be.
Just make sure that if you do use AddEscape, to be sure to use ccx.ParseFunctions - Or ccx.RemoveEscape







Functions

Function lists, explinations, uses.
Explanation Functions are simply varriables with "arguments". These arguments (listed inside the function) impact the variable.
Example: %ucase(hello world) will result in: HELLO WORLD (Ucase standing for Upper-Case)
A yell command could be created like this:
!addcc yell 20 %ucase(%rest)
Functions can be "nested" (Function within a function) to create more complex CC's (custom commands)
!addcc choose 10/ I recommend: %item(%all,%rand(1,%args))
!choose Cats Dogs Fish Hamsters
[bot] I recommend: Cats

There are no limits to nesting functions.
Some Plugins may add more functions to allow further customization. To see if functions have been added type /Rfunctions. (v 1.8+)



String manipulation
%len(string)
Returns the length of "string", in this case; 6.
%replace(string,replace what,with what)
%replace(H3llo goodby3,3,e) -> Hello goodbye
%count(search what,with what)
Returns how many times a search string is found.
%count(hello,l) -> 2


%seco(seconds)
PENDING...
%secf(seconds)
PENDING...





Functions are separated in 2 different categories. Priority 1, and Priority 2.

Priority 1 Functions "len", "seco", "secf", "round", "getgid", "wins", "count", "xitem", "item" "if", "ifnot", "switch", "for", "now", "rand", "mid", "instr", "chr", "no@", "getdl", "var", "math" "do", "listsize", "listitem", "listout", "inlist", "getdef", "ucase", "lcase", "replace"

Priority 2 Functions "die", "setdl", "setvar", "withdl", "withvar" "listclear", "listadd", "listdel", "setdef"



PRIORITY 1 Functions: (EXECUTES FIRST - IN NESTING ORDER - 1st Pass)
%round (NUMBER,TO DECIMAL)
Notes:
Rounds a number to the Xth decimal.
%round(22.1234,1) -> 22.1
%if (TEST,True Response,[False Response] = NULL)
Notes:
The most powerful function of all. - A simple if statement, similar to the popular IIF function.
%switch (Compare String,String,Response,String,Response - ETC) - Often understood as a PARAM ARRAY
Notes:
Attempts to copy the Switch method - available in most programming languages
A very handy function.
Example:
!addcc pickgame 10/ %switch(%rand(1,3),1,Starcraft,2,Diablo,3,Warcraft)

%for (START,STOP,STRING TO SAY,[Variable to replace with Number] = %i)
Notes:
Every language gotz to have one of these.
%i is default, but you can have it replace any string to be replaced with the number.
- Currently no other functions can be accessed inside this loop - rendering it somewhat useless.

!addcc dofor 10/ Look! I can count to 4!: %for(1,4,,%i)
%rand (LOWEST,HIGHEST)
Notes:
Picks a number between LOWEST and HIGHEST randomly
- See the Choose command.
%mid (STRING,START,[HOW DEEP]) - {This function may be upgraded to mimic PHP's StrStr function}
Notes:
Mimics VBs's Mid function.
%item (STRING,POSITION OF ITEM,[SEPARATOR] = Space)
Notes:
Selects an item out of a string. Intended to nullify the need for arrays.
%xitem (STRING,POSITION OF ITEM TO REMOVE,[SEPARATOR] = Space)
Notes:
The opposite of %item, this function instead of picking one out, it removes one out.

%count (STRING,WHAT)
Notes:
This was intended to replace the UBound function.
Returns the amount of WHAT is located in STRING
%count(HELLO,L) -> 2 (2 L's in HELLO)

%instr (STRING,STRING2,[COMPARE])
Notes:
Mimic of VBs's instr function. - Returns the amount of characters in STRING2 is located in STRING
%chr (NUMBER CODE)
Notes:
Mimics VBs's Chr function (Found in almost any programming language)
%no@ (USERNAME)
Notes:
Removes the # or @ suffix at the end of a username.
Bob@Lordaeron -> Bob
%getdl (DL NAME,[LOCATION ENTRY] = main)
Notes:
Returns the data stored in a DATALIST.
See:
%withdl, %setdl
%getgid (USERNAME,NUMBER KEY)
Notes:
Mimics StealthBot's GetInternalDataByUsername
%seco (SECONDS)
Notes:
Seconds to Orgin.
Returns what time it was X seconds go
Example:
!addcc lasttalked 10/ %if(%getgid(%1, 7) = -5,"%1" is not in channel!,%1 Last talked %secf(%getgid(%1, 7)) ago {%seco(%getgid(%1, 7))})
%secf (SECONDS)
Notes:
Seconds to Full. 60 = 1:00.
2147 = 35:47
- For use with the %gid function
Example:
!addcc lasttalked 10/ %if(%getgid(%1, 7) = -5,"%1" is not in channel!,%1 Last talked %secf(%getgid(%1, 7)) ago {%seco(%getgid(%1, 7))})


PRIORITY 2 Functions: (EXECUTES AFTER ALL PRIORITY 1 FUNCTIONS - 2nd Pass.)
Function Name (Arguments separated by comma - Optional arguments in [brackets])

%die (STRING) - SPECIAL
Returns:
Argument untouched.
Notes:
This function acts like PHP's die. It will respond with the arguments, and everything else is ignored.
Example:
!addcc TestDie 10 %if(%user<>Snap,%die(This CC will only work for Snap))Hi Snap I Wuv your CC System!
Result:
!testdie
This CC will only work for Snap

%redirect (CUSTOM COMMAND, []) SPECIAL, See %runcc
Returns:
The CustomCommand supplied by Args
Notes:
This function is similar to %die - except that it uses a custom command.
Example:
None

%wait (STRING, [Time Amount] = 5) - SPECIAL, See %do
Returns:
NULL
Notes:
Executes string like %do after time is up.
- This does NOT padq it simply adds the message to the Que after time runs out.
*May use escaped CCX Text using @ instead of %

%makecc (NAME,ACCESS/FLAGS,TEXT,[Allow Rename] = False,[Return Response] = False)
Returns:
If Return Response = True, it will return with: "Created CC [name]" or "CC Already existed"
Notes:
Creates a Custom Command.

%setdl (DL NAME,NEW SETTING,[RETURN RESULT] = False,[LOCATION ENTRY] = main)

%withdl (DL NAME,OPERATION,[RETURN RESULT] = False,[LOCATION ENTRY] = main)
Operations:
& - Appends to.
%setdl(MYVAR,Hello)
%withdl(MYVAR,& World)




Examples

/addcc vote 20 %if(%inlist(voted,%user),%die(You have already voted))%if(%var(vote_expires) > %now,%die(Vote over %listsize(voted) users voted %var(vote_yes) YES %var(vote_no) NO))
/appendcc vote %if(%1 = YES,%listadd(voted,%user)%withvar(vote_yes,+1) Vote added)%if(%1 = NO,%listadd(voted,%user)%withvar(vote_no,+1) Vote added)
/addcc setvote 80 %setvar(vote_expires,%now(60*60)%listclear(voted)%setvar(vote_yes,0)%setvar(vote_no,0)Vote set to [%setvar(voteQ,%rest,true)]
/addcc showvoted 70 Users that have voted: %listout(voted)