Data Types

Primitive Datatypes

void

Can be thought of better as the absence of a datatype. No value can be assigned to void nor can a value be returned from a function of datatype void.

boolean

A boolean value is either true or false. By default, a boolean variable is set to false.

int

A whole number (short for "integer"), either positive or negative (or 0). The int used by KoLmafia is a 32-bit signed int, meaning it has a maximum value of 2,147,483,647 and a minimum value of -2,147,483,648. The default value of a integer variable is 0.

float

The float data type is a single-precision 32-bit IEEE 754 floating point. Its range of values is beyond the scope of this discussion, but is specified in section 4.2.3 of the Java Language Specification. [1]

When assigning to a variable of type float, one should be careful to always enter numbers in decimal form, as unwanted behavior can result from supplying a value that KoLmafia may interpret as an int type without the decimal point.

Note that float is not infinitely precise; it intrinsically rounds off after a certain point. This loss of accuracy is for the sake of storage, but beware of the possibility of small errors compounding from multiple float types.

For instance, try the following code as an example of how rather long post-decimal portions are handled:

float f;
f = 4.9999999;
print( f );

The default value of a float variable is 0.0.

string

A group of characters including, but not limited to: lowercase letters, uppercase characters, numbers, and various control characters. When assigning a value to a string, always enclose the desired value in either single or double quotes (note you must use the same quote type on both ends of the string assignment). If you need to include the same character inside of the string itself, you will need to escape it first with a backslash.

For example:

string s = "This is my \"friend\" Pete.";

Will result in the following being stored to s:

This is my "friend" Pete

The default value of a string is an empty string, or literally "".

buffer

Similar to a string, but more efficient in certain operations, including concatenation and passing as function arguments. For the most part, you can interchange references to strings and buffers. However, you should test all such actions first, as a few functions require a specific datatype to be supplied as a parameter. (Most notably, those listed under Regular Expressions.)

Special Datatypes

Several datatypes are included in KoLmafia to represent common categories within the KoL universe.

Note that while variables of these types are declared in the same way as for Primitive Datatypes; assigning and referencing them is done differently.

For example, to declare an item datatype and assign it a value, you would use the following line of code:

item it = $item[ broken skull ];

The default values of any variable of one of the following types is $type[ none ]. For example, the default value of a item variable is $item[ none ].

class

Besides $class[ none ], there are six possible values for this datatype:

• Seal Clubber
• Turtle Tamer
• Pastamancer
• Sauceror
• Disco Bandit
• Accordion Thief

effect

Any effect you can be under in KoL, whether from items, skills, or what-have-you, is valid for this datatype.

The full range, besides $effect[ none ], is too much to list and keep up with here: please see the Wiki Effects page for more information.

element

Besides $element[ none ], there are six possible values for this datatype. (Note that "Bad Spelling" is not considered a true element.) Also note that these names are case-sensitive (referencing $element[ Spooky ] will generate an error).

• cold
• hot
• sleaze
• spooky
• stench
• slime

familiar

Any familiar available in KoL is valid for this datatype.

The full range, besides $familiar[ none ], is too much to list and keep up with here: please see the Wiki Familiars page for more information.

item

Any item in all of KoL is valid for this datatype. Note that unlike most special datatypes, item references can make use of the item ID number.

For example, you could assign the item plexiglass pants as follows:

item it = $item[ 1234 ];

The full range, besides $item[ none ], is too much to list and keep up with here: please see the Wiki Items page for more information.

location

Any location one can adventure at in KoL is valid for this datatype.

The full range, besides $location[ none ], is too much to list and keep up with here: please see the Wiki Locations page for more information.

monster

Any monster you can encounter in KoL is valid for this datatype.

The full range, besides $monster[ none ], is too much to list and keep up with here: please see the Wiki Monster Compendium page for more information.

skill

Any skill you can have in KoL (whether permable or not, granted by items, etc.) is valid for this datatype.

The full range, besides $skill[ none ], is too much to list and keep up with here: please see the Wiki Skills page for more information.

slot

Besides $slot[ none ], there are 13 possible values for this datatype.

• hat
• weapon
• off-hand
• shirt
• pants
• acc1
• acc2
• acc3
• familiar
• sticker1
• sticker2
• sticker3
• fakehand

stat

Besides $stat[ none ], there are six possible values for this datatype (the last three are for referencing sub-stats).

• muscle
• mysticality
• moxie
• submuscle
• submysticality
• submoxie

aggregate

An aggregate is a complex datatype composed of two or more primitive or special datatypes. For more information, see Data Structures.

record

Records are user-defined datatypes that hold as many sub-datatypes as desired. For more information, see the page for Data Structures.

Plural Typed Constants

(see http://kolmafia.us/showthread.php?p=15592, from which this section is reproduced)

Plural typed constants allow you to easily do something with a list of specified objects, without having to replicate code or laboriously build up an array of the objects so that you can iterate over it. Here's a quick example:

foreach weapon in $items[star sword, star staff, star crossbow] {
   if (available_amount(weapon) > 0) {
      equip(weapon);
      break;
   }
}

The syntax is basically the same as the existing typed constant feature, but with an "s" or "es" after the type name. (The "es" case is there so that you can properly pluralize "class".) The text between the square brackets is interpreted as a comma-separated list of elements, each of which is converted to the specified type as if it were an individual constant. More details:

• The list can span multiple lines.
• Whitespace before or after elements is ignored.
• Completely empty elements are ignored (so that you can leave a comma at the end of the list).
• You can include a comma or closing square bracket in an element by writing it as "\," or "\]".
• All the other escape sequences allowed in strings are possible, such as "\n" (newline), "\t" (tab), and "\uXXXX" (Unicode character value). To put an actual backslash in an element, you have to write it as "\\".

The value generated by a plural constant is of type boolean[type], with the keys being the specified elements, and the boolean value always being true - although you won't normally do anything with the boolean, you'd use a foreach loop to iterate over the keys. You can assign a plural constant to a variable declared as that type, but note that the value differs from a normal map in three important respects:

• Since the expression that generates it is syntactically a constant, the value has to be immutable. If you were allowed to change it in any way, those changes would appear in every future use of the same constant.
• There can be multiple instances of the same key - $ints[1,1,2,3,5,8] is perfectly valid, and will result in the value 1 appearing twice in a foreach loop.
• The keys will appear in the order you wrote them, rather than being sorted alphanumerically as maps usually do.

In addition to being used in a foreach loop, plural constants also efficiently support membership testing via the 'contains' operator. Here's another example:

for hour from 1 to 12 {
   print("It's " + hour + " o'clock.");
   if ($ints[10, 2, 4] contains hour) {
      print("Time to drink a Dr Pepper!");
   }
}

(Yes, that example could just as easily have been done with a switch statement.)

Iterating over an empty list is rather pointless, so plural constants with no elements are given a different meaning: they represent every value of the specified type, where this is practical. (The 'none' value, if defined for a given type, is omitted.) The biggest benefit here is $items[], which lets you loop over every defined item, more efficiently than you could otherwise write in a script (since the list is generated once per session and then cached), and without having to hard-code a maximum item ID number in your script. Example:

foreach it in $items[] {
   if (autosell_price(it) == 42) print(it);
}

Enumeration of all possible values works with the following types:

• $booleans[] - false and true.
• $items[]
• $locations[]
• $classes[]
• $stats[] - Muscle, Mysticality, Moxie: the substat values are omitted.
• $skills[]
• $effects[]
• $familiars[]
• $slots[] - includes sticker slots and fake hands, which you might not want to consider as normal slots.
• $monsters[]
• $elements[] - includes slime now, and possibly other not-quite-elements like cute in the future.

The remaining types that can be used in plural constants require an explicit list of elements, since there are too many possible values:

• $ints[] - you don't have enough RAM to store a list with 4 billion elements.
• $floats[] - ditto.
• $strings[] - nobody has that much RAM.

Custom

matcher

A matcher isn't really a datatype so much as it's a class, but it is included here for reference, as it is used much as datatypes are in ASH. It can only be declared through the function create_matcher(), using two strings. One is the string to find matches in, the other a regular expression to test against. For more information on using a matcher, see Regular Expressions.