Magsbot Help

Macros (formerly called "User-Defined Functions")

Magsbot lets you define your own function macros in the userdefs.udf file. To create or edit macros, click on the "EditUserDefs" button on the Action panel, or just open userdefs.udf manually using notepad. Then simply add a macro definition of the form:

@funcname[argtypes]=definition (for a macro that returns a number)
or
$funcname[argtypes]=definition (for a macro that returns a string)

...where funcname is whatever name you choose to give to the function, and definition is a valid expression returning the same type (i.e. number or string) as the macro definition. Argtypes represents a sequence of type specifiers (usually @ or $) separated by commas, representing the type (number or string) of the macro arguments. The argument list is optional, but most always used.

Within the definition, the tilde ~ followed by a number, is used to represent an argument. That is, ~1 for the first argument, ~2 for the second argument, etc.

For example: @myfunc[$]=@ipos["a",~1] would define a function the takes a string as an argument and returns 0 or 1 depending on whether the string contains the letter "a". The @myfunc macro would be used within Magsbot code like this:

IF @myfunc[$x] {
REPORT "The string contains an 'a'. " }
ELSE {
REPORT "The string does not contain an 'a'. " }

You can also use n or s for a type specifier, to represent a number or string that is optional, but such specifiers must go last in the argument list. Furthermore, there are some additional type specifiers, the same as used internally by Magsbot, which you can try (however I can't guarantee that these will work with macros, as I haven't tested them extensively):

variable name: v
any optional (string or numeric, and optional) : a
expression (see @loop for an example of a function that takes an expression as an argument): e
conditional (like numeric, but no error message if the following argument is false): ?

Here are some more examples to clarify:

$myname="Magine"
The macro $myname is a simple assignment of a string contant, "Magine". In any expressions, $myname would be equivalent to "Magine".
$LF=$cat[$asc[13],$asc[10]]
The macro $LF (for "line feed") can be used for a carriage return. For instance, REPORT "Test"+$LF+"This" would print out in the chat/log window as:
Test
This
@objnum=@atr[OBJECT_NUMBER]
The macro @objnum calls the @atr function to return the AW attribute OBJECT_NUMBER.
$word[@]=$par[$chat,$chatdelims,~1]
The $word macro returns the nth word in the chat stream, by using the $par function.
$ww=$tail[$chat,(@botcmd<>0)*(@len[$word[1]]+1)+@len[$w1]+2]
The more complicated $ww macro uses several different functions to return everything in the chat string past the first word, (not counting the bot's name if that is the first word). This is frequently used along with the @cmd macro, which checks the first word of the chat string (not counting the bot's name) to see if it matches the specified word.

Back to Functions.