Kolmafia - User contributions [en]

VS Code Setup

2020-12-22T05:20:55Z

Fredg1: Windows-related schtuff, && Tasks

This guide assumes that you have a recent enough version of the Java JDK, ANT, and VS Code. Completing [[Compiling from Source]] is a requirement for this guide, although experienced developers can skip to whatever step is appropriate.

=== Build and Config Project Setup ===
# Open the KoLmafia directory in VS Code.
# Install the Java Extension Pack, Language Support for Java, Project Manager for Java, and Debugger for Java VS Code extensions.
# Install the following files in .vscode:

===== launch.json: =====
{
"version": "0.2.0",
"configurations": [
{
"type": "java",
"name": "Debug (Launch)-KoLmafia<kolmafia>",
"request": "launch",
"mainClass": "net.sourceforge.kolmafia.KoLmafia",
"projectName": "kolmafia",
"windows": {
"cwd": "${workspaceFolder}/dist",
"sourcePaths": ["${workspaceFolder}"]
},
"args": "--CLI"
}
]
}

===== settings.json: =====
{
"files.exclude": {
"**/.classpath": true,
"**/.factorypath": true,
"**/.project": true,
"**/.settings": true,
"**/*.class": true
},
"java.project.referencedLibraries": [
"lib/**/*.jar",
"src/**/*.jar"
]
}
Test by pressing F5 to run KoLmafia.
=== Optional Steps ===
===== Style definitions =====
*For easier coding, download the [[:File:KoLMafia Style.xml|KoLMafia Style Definitions]] and figure out how to install them in VS Code.

===== Making Tasks =====
*Tasks are individual commands that can be used at will. There are two general situations in which they currently come in handy.
*To use them, add the following file in .vscode:
'''tasks.json:'''
{
"version": "2.0.0",
"problemMatcher": "$eslint-compact",
"type": "shell",
"tasks": [
{
"label": "build .jar",
"command": "ant.bat daily<nul",
"windows": {
"command": "& ((get-command $env:ANT_HOME/bin/ant.bat).Source) daily<nul -lib ${workspaceFolder} -buildfile ${workspaceFolder}/build.xml"
},
"group": {
"kind": "build",
"isDefault": true
}
},
{
"label": "reset constants for patchmaking",
"command": "ant.bat unset.properties<nul",
"windows": {
"command": "& ((get-command $env:ANT_HOME/bin/ant.bat).Source) unset.properties<nul -lib ${workspaceFolder} -buildfile ${workspaceFolder}/build.xml"
}
},
{
"label": "ant.bat set.version",
"command": "ant.bat set.version<nul",
"windows": {
"command": "& ((get-command $env:ANT_HOME/bin/ant.bat).Source) set.version<nul -lib ${workspaceFolder} -buildfile ${workspaceFolder}/build.xml"
}
},
{
"label": "ant.bat set.released.false",
"command": "ant.bat set.released.false<nul",
"windows": {
"command": "& ((get-command $env:ANT_HOME/bin/ant.bat).Source) set.released.false<nul -lib ${workspaceFolder} -buildfile ${workspaceFolder}/build.xml"
}
},
{
"label": "set constants for code running",
"dependsOrder": "sequence",
"dependsOn": [
"reset constants for patchmaking",
"ant.bat set.version",
"ant.bat set.released.false"
]
}
]
}

*Here are the two uses for them:
====== Automate version-setting when debugging ======
*In its current state, if you were to start debugging, it would work. However, KoLmafia would think that your revision is 0. This would cause any script beginning with a ''since'' statement to abort immediately.
*To counter this without having to manually change KoLConstants.java, add these two lines to <code>launch.json</code>:
{
"version": "0.2.0",
"configurations": [
{
"type": "java",
"name": "Debug (Launch)-KoLmafia<kolmafia>",
"request": "launch",
"mainClass": "net.sourceforge.kolmafia.KoLmafia",
"projectName": "kolmafia",
"windows": {
"cwd": "${workspaceFolder}/dist",
"sourcePaths": ["${workspaceFolder}"]
},
<u>'''"preLaunchTask": "set constants for code running",'''</u>
<u>'''"postDebugTask": "reset constants for patchmaking",'''</u>
"args": "--CLI"
}
]
}
====== Building the .jar ======

* If you are not on Windows and already made your own Wrapper file, this is most likely not that much of an improvement, but these tasks allow you to build the .jar file in only two clicks (if you ever need to).

[[File:Build Task.png|alt=Terminal => Run Build Task...|left|frameless]]

File:Build Task.png

2020-12-22T05:17:23Z

Fredg1:

Terminal => Run Build Task...

File:Save Workspace.png

2020-12-21T23:54:22Z

Fredg1:

You may make it anywhere you want with any name you want, but you may NOT move it once created.

File:Open folder in VScode.png

2020-12-21T23:15:15Z

Fredg1:

Select "New Window" first if you were using the current one previously.

Data Types

2020-11-05T00:07:53Z

Fredg1: mutability

{{TOCright}}
==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.

Be careful when doing math with integers! As with some other strongly-typed languages, numbers are converted to integers at every step of the operation when only integer types are used. For example:
{{
CodeSample|
code=
<syntaxhighlight>
int a = 1;
int b = 2;
print( a / b * 2 );
</syntaxhighlight>}}
Will give the output "0," not "1" as you may expect. Changing either variable to a float type will "correct" this.

===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 [http://java.sun.com/docs/books/jls/third_edition/html/typesValues.html#4.2.3 section 4.2.3 of the Java Language Specification], and a tool to help understand / quickly see how/where imprecisions happen can be found [https://www.h-schmidt.net/FloatConverter/IEEE754.html here].

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.
{{
CodeSample|
description=For instance, try the following code as an example of how rather long post-decimal portions are handled:|
code=
<syntaxhighlight>
float f;
f = 4.9999999;
print( f );
</syntaxhighlight>}}
The default value of a <code>float</code> 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, enclose the desired value in either single quotes (<code>'</code>), double quotes (<code>"</code>) or backticks (<code>`</code>) (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.

{{
CodeSample
|description=For example:
|code=<syntaxhighlight>string s = "This is my \"friend\" Pete.";</syntaxhighlight>
|moreinfo=Will result in the following being stored to s:<pre>This is my "friend" Pete</pre>
}}

The default value of a string is an empty string, or literally <code>""</code>

When using backticks, you can concatenate expressions into your string using curly braces.

{{
CodeSample
|description=For example:
|code=<syntaxhighlight>string s = `Hello {my_name()}, you have {$item[lime].item_amount()} lime(s)!`;</syntaxhighlight>
}}

===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 [[String Handling Routines#Regular Expressions|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.
{{CodeSample|
description=For example, to declare an item datatype and assign it a value, you would use the following line of code:|
code=
<syntaxhighlight>
item it = $item[ broken skull ];
</syntaxhighlight>}}
The default values of any variable of one of the following types is <code>$''type''[ none ]</code>. For example, the default value of a <code>item</code> variable is <code>$item[ none ]</code>.

===bounty===

([[Bounty#Related Functions|Related Functions]]) ([[Bounty#Proxy Record Fields|Proxy Record Fields]])

These are the non-items that the bounty hunter asks you to retrieve from monsters around the kingdom. There are quite a lot of them (42 in total) so I won't list them all here. You can find more about bounties at the {{kolwiki|The Bounty Hunter Hunter's Shack}}.

===class===

([[Class#Related Functions|Related Functions]]) ([[Class#Proxy Record Fields|Proxy Record Fields]])

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

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

===coinmaster===

([[Coinmaster#Related Functions|Related Functions]]) ([[Coinmaster#Proxy Record Fields|Proxy Record Fields]])

All shops that deal with currency other than meat. Known values include:

* {{kolwiki|The Bounty Hunter Hunter's Shack|Bounty Hunter Hunter}}
* {{kolwiki|Mr. Store}}
* {{kolwiki|Hermit}}
* {{kolwiki|The Shore, Inc. Gift Shop}}
* {{kolwiki|The Trapper's Cabin|The Trapper}}
* {{kolwiki|A Vending Machine|Vending Machine}}
* {{kolwiki|The Swagger Shop}}
* {{kolwiki|The Hippy Camp (Wartime)|Dimemaster}}
* {{kolwiki|The Orcish Frat House|Quartersmaster}}
* {{kolwiki|BURT|Bugbear Token}}
* {{kolwiki|Freshwater Fishbonery}}
* {{kolwiki|Big Brother}}
* {{kolwiki|The Terrified Eagle Inn}}
* {{kolwiki|Ticket Redemption Counter|Arcade Ticket Counter}}
* {{kolwiki|Cashier|Game Shoppe}}
* {{kolwiki|Cashier|Game Shoppe Snacks}}
* {{kolwiki|The Isotope Smithery|Isotope Smithery}}
* {{kolwiki|Dollhawker's Emporium}}
* {{kolwiki|The Lunar Lunch-o-Mat|Lunar Lunch-o-Mat}}
* {{kolwiki|Paul's Boutique}}
* {{kolwiki|The Frozen Brogurt Stand}}
* {{kolwiki|Buff Jimmy's Souvenir Shop}}
* {{kolwiki|Taco Dan's Taco Stand}}
* {{kolwiki|You're the Fudge Wizard Now, Dog|Fudge Wand}}
* {{kolwiki|The Neandermall}}
* {{kolwiki|Legitimate Shoe Repair, Inc.}}
* {{kolwiki|warbear black box|Warbear Black Box}}
* {{kolwiki|The Dinsey Company Store}}
* {{kolwiki|Internet Meme Shop}}

===effect===

([[Effect#Related Functions|Related Functions]]) ([[Effect#Proxy Record Fields|Proxy Record Fields]])

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 {{kolwiki|Effects}} page for more information.

===element===

([[Element#Related Functions|Related Functions]]) ([[Element#Proxy Record Fields|Proxy Record Fields]])

Besides $element[ none ], there are seven 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
* supercold

===familiar===

([[Familiar#Related Functions|Related Functions]]) ([[Familiar#Proxy Record Fields|Proxy Record Fields]])

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 {{kolwiki|Familiars}} page for more information.

===item===

([[Item#Related Functions|Related Functions]]) ([[Item#Proxy Record Fields|Proxy Record Fields]])

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.
{{CodeSample|
description=For example, you could assign the item plexiglass pants as follows:|
code=
<syntaxhighlight>
item it = $item[ 1234 ];
</syntaxhighlight>}}
The full range, besides $item[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Items}} page for more information.

===location===

([[Location#Related Functions|Related Functions]]) ([[Location#Proxy Record Fields|Proxy Record Fields]])

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 {{kolwiki|Locations}} page for more information.

===monster===

([[Monster#Related Functions|Related Functions]]) ([[Monster#Proxy Record Fields|Proxy Record Fields]])

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 {{kolwiki|Monster Compendium}} page for more information.

===phylum===

([[Phylum#Related Functions|Related Functions]]) ([[Phylum#Proxy Record Fields|Proxy Record Fields]])

Each monster has a {{kolwiki|Phylum}}. Besides $phylum[none], the possible values for this datatype are:

* beast
* bug
* constellation
* construct
* demon
* dude
* elemental
* elf
* fish
* goblin
* hippy
* hobo
* humanoid
* horror
* mer-kin
* orc
* penguin
* pirate
* plant
* slime
* undead
* weird

===servant===

([[Servant#Related Functions|Related Functions]]) ([[Servant#Proxy Record Fields|Proxy Record Fields]])

Servants are unique to the {{kolwiki|Actually Ed the Undying}} path and located {{kolwiki|The Servants' Quarters}}, replacing familiars.

* Assassin
* Belly-Dancer
* Bodyguard
* Cat
* Maid
* Priest
* Scribe

===skill===

([[Skill#Related Functions|Related Functions]]) ([[Skill#Proxy Record Fields|Proxy Record Fields]])

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 {{kolwiki|Skills}} page for more information.

===slot===

([[Slot#Related Functions|Related Functions]]) (slot has no proxy record fields)

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

* hat
* back
* weapon
* off-hand
* shirt
* pants
* acc1
* acc2
* acc3
* familiar
* sticker1
* sticker2
* sticker3
* fakehand
* bootspur
* bootskin

===stat===

([[Stat#Related Functions|Related Functions]]) (stat has no proxy record fields)

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

===thrall===

([[Thrall#Related Functions|Related Functions]]) ([[Thrall#Proxy Record Fields|Proxy Record Fields]])

Pastamancers have the ability to summon {{kolwiki|Pasta Thralls}}.

* Angel Hair Wisp
* Elbow Macaroni
* Lasagmbie
* Penne Dreadful
* Spaghetti Elemental
* Spice Ghost
* Vampieroghi
* Vermincelli

==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:
{{CodeSample|code=<syntaxhighlight>
foreach weapon in $items[star sword, star staff, star crossbow] {
if (available_amount(weapon) > 0) {
equip(weapon);
break;
}
}</syntaxhighlight>}}
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:
{{CodeSample|code=<syntaxhighlight>
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!");
}
}</syntaxhighlight>}}
(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:
{{CodeSample|code=<syntaxhighlight>
foreach it in $items[] {
if (autosell_price(it) == 42) print(it);
}</syntaxhighlight>}}
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 {{f|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]].

==Notes==

Buffers, aggregates, records and matchers are [https://developer.mozilla.org/en-US/docs/Glossary/Mutable mutable]. All other datatypes are immutable.

[[Category:Scripting]]

Operators

2020-10-23T11:18:39Z

Fredg1: /* Boolean Operators */ Short-circuit_evaluation

{{TOCright}}
==Mathematical Operators==

The following mathematical operators are used in KoLmafia:
{{
eztable|
{{eztr|{{eztd| + |Addition|Performs addition and string concatenation}}}}
{{eztr|{{eztd| - |Subtraction|Performs subtraction}}}}
{{eztr|{{eztd| * |Multiplication|Performs multiplication}}}}
{{eztr|{{eztd| / |Division|Performs division}}}}
{{eztr|{{eztd| % |Modulo|Returns the remainder after division}}}}
{{eztr|{{eztd| ** |Exponent|Performs exponentiation}}}}
}}
Note that, with the exception of using <nowiki>"+"</nowiki> for string concatenation, these operators can only be used on int or float datatypes.

==Bitwise Operators==

The following mathematical operators are used for operating on the bits of integers. The logical operators (&, |, ^) work either with booleans or integers while the others operate upon integers only. If the operands are booleans, then result will also be a boolean.
{{
eztable|
{{eztr|{{eztd| <nowiki>&</nowiki> |and|a & b}}}}
{{eztr|{{eztd| <nowiki>|</nowiki> |or|a <nowiki>|</nowiki> b}}}}
{{eztr|{{eztd| <nowiki>^</nowiki> |XOR|a <nowiki>^</nowiki> b}}}}
{{eztr|{{eztd| ~ |not|~a}}}}
{{eztr|{{eztd| << |left shift|a << b}}}}
{{eztr|{{eztd| >> |right shift|a >> b}}}}
{{eztr|{{eztd| <nowiki>&=</nowiki> |and|<nowiki>a &= b --> a = a & b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>|=</nowiki> |or|<nowiki>a |= b --> a = a | b</nowiki>}}}}
{{eztr|{{eztd| >>> |unsigned right shift|a >>> b}}}}
}}

==Assignment Operators==
The following assignment operators are used in KoLmafia (let a = left operand, b = right operand):
{{
eztable|
{{eztr|{{eztd| <nowiki>=</nowiki> |<nowiki>a = b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>+=</nowiki> |<nowiki>a = a + b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>-=</nowiki> |<nowiki>a = a - b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>*=</nowiki> |<nowiki>a = a * b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>/=</nowiki> |<nowiki>a = a / b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>%=</nowiki> |<nowiki>a = a % b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>**=</nowiki> |<nowiki>a = a ** b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>^=</nowiki> |<nowiki>a = a ^ b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>>>=</nowiki> |<nowiki>a = a >> b</nowiki>}}}}
{{eztr|{{eztd| <nowiki>>>>=</nowiki> |<nowiki>a = a >>> b</nowiki>}}}}
}}
Of these, only += and = are usable for strings. See [[Operators#Mathematical Operators|Mathematical Operators]] for information regarding the basic Mathematical Operators.

==Relational Operators==

To follow these examples, a basic understanding of the concepts found on [[Control Structures]] would be helpful.

In order to create more complex if statements, we need to understand the basic relational operators:
{{
eztable|
{{eztr|{{eztd| <nowiki>==</nowiki> |equal to}}}}
{{eztr|{{eztd| <nowiki>!=</nowiki> |not equal to}}}}
{{eztr|{{eztd| <nowiki><</nowiki> |less than}}}}
{{eztr|{{eztd| <nowiki>></nowiki> |greater than}}}}
{{eztr|{{eztd| <nowiki><=</nowiki> |less than or equal to}}}}
{{eztr|{{eztd| <nowiki>>=</nowiki> |greater than or equal to}}}}
}}
Note that you cannot mix most datatypes within a comparison or KoLmafia will abort with an error, with the exception of mixing types int and float, where KoLmafia will do a transparent type conversion behind-the-scenes. If you need to compare different datatypes, use one or more of the [[Datatype Conversions|Datatype Conversion]] functions. Also, == is case-insensitive with respect to strings.

{{
CodeSample|
code=
<syntaxhighlight>
if ( true == true )
{
print( "This line DOES get printed." );
}
if ( true == false )
{
print( "This line does NOT get printed." );
}
if ( 1 == 1.0 )
{
print( "This line DOES get printed." );
}
if ( 1 == 2 )
{
print( "This line does NOT get printed." );
}
if ( "Hello" == "hello" )
{
print( "This line DOES get printed." );
}
</syntaxhighlight>}}

{{CodeSample|
description=Another exception is with strings. If the '''first''' datatype is a string, and the second isn't, the latter will be silently converted into a string. Remember that strings are compared alphabetically (with the alphabet here being the characters' [https://www.asciitable.com/ ASCII value]), just like in a dictionary, in which "smaller" means "would come before".|
code=
<syntaxhighlight>
if ( "a" < "b" )
{
print( "This line DOES get printed." );
}
if ( "apple" < "b" )
{
print( "This line DOES get printed." );
}
if ( "1" < 2 )
{
print( "This line DOES get printed." );
}
if ( "1487" < 2 )
{
print( "This line DOES get printed." );
}
if ( "a" < 2 )
{
print( "This line does NOT get printed." );
}

if ( "3" == 3 )
{
print( "This line DOES get printed." );
}
if ( "3.0" == 3 )
{
print( "This line does NOT get printed." );
}
if ( 3 == "3" )
{
print( "This GENERATES AN ERROR!" );
}

if ( "true" == true )
{
print( "This line DOES get printed." );
}
</syntaxhighlight>|
moreinfo=Take the habit of always converting your datatypes to avoid unexpected problems.}}

==Boolean Operators==
{{
eztable|
{{eztr|{{eztd| <nowiki>&&</nowiki> |and}}}}
{{eztr|{{eztd| <nowiki>||</nowiki> |or}}}}
{{eztr|{{eztd| <nowiki>!</nowiki> |not}}}}
}}
Note that the above operators only work with boolean values & datatypes. To make use of them with other datatypes, you will either need to first perform a [[Datatype Conversions|Datatype Conversion]], or you will need to nest your operations such that a boolean value is used with the boolean operators.
{{
CodeSample|
code=
<syntaxhighlight>
if ( true && true )
{
print( "This line DOES get printed (both possibilities proved true)." );
}
if ( true && false )
{
print( "This line does NOT get printed (only one possibility proved true)." );
}
if ( true || false )
{
print( "This line DOES get printed (since at least one of the possibilities proved true)." );
}
if ( ! false )
{
print( "This line DOES get printed (since the not operator converted false to true)." );
}
</syntaxhighlight>}}

====Notes====
ASH uses [https://en.wikipedia.org/wiki/Short-circuit_evaluation Short-circuit_evaluation].<br>
What this means is that in both of these examples, expensive_function() is not evaluated (i.e. is skipped):

{{
CodeSample|
code=
<syntaxhighlight>
if ( false && expensive_function() ) {
...
}
</syntaxhighlight>}}
{{
CodeSample|
code=
<syntaxhighlight>
if ( true || expensive_function() ) {
...
}
</syntaxhighlight>}}

==Operator Precedence==

KoLmafia follows [http://download.oracle.com/javase/tutorial/java/nutsandbolts/operators.html Java's Operator Precedence rules] with a few exceptions.

(The exceptions being operators that exist in only one or the other; operators that exist in both have the same precedence in both.)

{{
eztable|
{{eztr|{{eztd|14| <nowiki>(reserved for postfix ++ and --)</nowiki> }}}}
{{eztr|{{eztd|13| <nowiki>! ~ contains remove (reserved for prefix ++ and --)</nowiki> }}}}
{{eztr|{{eztd|12| <nowiki>**</nowiki> }}}}
{{eztr|{{eztd|11| <nowiki>* / %</nowiki> }}}}
{{eztr|{{eztd|10| <nowiki>+ -</nowiki> }}}}
{{eztr|{{eztd| 9| <nowiki><< >> >>></nowiki> }}}}
{{eztr|{{eztd|8| <nowiki>< > <= >=</nowiki> }}}}
{{eztr|{{eztd|7| <nowiki>== !=</nowiki> }}}}
{{eztr|{{eztd|6| <nowiki>&</nowiki> }}}}
{{eztr|{{eztd|5| <nowiki>^</nowiki> (xor) }}}}
{{eztr|{{eztd|5| <nowiki>|</nowiki> }}}}
{{eztr|{{eztd|3| <nowiki>&&</nowiki> }}}}
{{eztr|{{eztd|2| <nowiki>||</nowiki> }}}}
{{eztr|{{eztd|1|(reserved for <nowiki>?:</nowiki>(ternary conditional))}}}}
{{eztr|{{eztd|0| (reserved for assignments)}}}}
}}

Statements inside a () pair are always evaluated first, then in order of precedence as listed above (highest number precedence first), then left-to-right.
{{
CodeSample|
code=
<syntaxhighlight>
if ( true || true && false )
{
print( "This line DOES get printed." );
// && has highest precedence
// true or (true && false) returns true
}
if ( ( true && false ) && true )
{
print( "This line does NOT get printed." );
// ( true && false ) is evaluated first since it is inside of parentheses
// so we end up evaluating ( false && true ) which returns false
}
if ( true && ! ( true && false ) )
{
print( "This line DOES get printed." );
// ( true && false ) is evaluated first since it is inside of parentheses
// the ! operator converts the false from ( true && false ) to true
// ( true && true ) returns true
}
</syntaxhighlight>}}
[[Category:Scripting]]

User confirm

2020-10-23T11:12:05Z

Fredg1:

{{
#vardefine:name|user_confirm}}{{
#vardefine:return_type|boolean}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|message}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|message}}|
parameter2={{Param|int|timeOutMillis}}|
parameter3={{Param|boolean|defaultValue}}|
p1desc={{pspan|message}} is the text to display in the confirmation pop-up|
p2desc={{pspan|timeOutMillis}} the length of time to display the dialog, in milliseconds|
p3desc={{pspan|defaultValue}} the value to return if the user does not choose an input before <b>timeOutMillis</b> ms|
}}|

function_description=Presents the user with a pop-up dialog box with the text in {{pspan|message}} (can use escaped characters, such as "<nowiki>\n</nowiki>" for a newline); returns true if the user selects "Yes" and false if the user selects "No."</p>
<p>If you wish for the dialog to "time out" and return a default value if the user does not select an option, use the three-parameter version.</p>
<p>Please use these sparingly, as it can defeat the purpose of scripting if the user must constantly provide information during execution.|

code1={{CodeSample|
title=Code Sample|
description=A check to see if the user truly wants to execute a script.|
code=
<syntaxhighlight>
if (!user_confirm("Are you sure you want to proceed with executing this script?") )
{
abort("Script execution canceled by user.");
}
</syntaxhighlight>}}|

code2={{CodeSample|
title=Conditional pop-ups|
description=By taking in consideration that ASH has lazy booleans, it is possible to make confirmation messages that will only appear if the user doesn't satisfy a condition without having to isolate the user_confirm() call.<br>In this example, the user is asked to input the amount of adventures to spend. If they have at least that much, the script simply executes, without a pop-up appearing. Otherwise, a pop-up appears, and the script only executes if the user answers yes.|
code=
<syntaxhighlight>
void main( int adventures_to_spend )
{
if (my_adventures() < adventures_to_spend && !user_confirm("You don't have that many adventures. Use as many as possible instead?"))
{
abort("Script execution canceled by user.");
}

// Rest of the script
}
</syntaxhighlight>|
moreinfo=See [[Operators#Boolean_Operators]] for how/why this works.}}|

}}

[[Category:Miscellaneous Functions]]

Print

2020-09-20T23:20:49Z

Fredg1:

{{
#vardefine:name|print}}{{
#vardefine:return_type|void}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|message}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|message}}|
parameter2={{Param|string|color}}|
p1desc={{Pspan|message}} is the text to print|
p2desc={{Pspan|color}} is an html color name or code|
}}|
function_description=Print the specified text {{pspan|message}} to the CLI. If the optional {{pspan|color}} parameter is specified and a valid html color code or entity, it will print in that color. See the [http://www.w3.org/TR/CSS21/syndata.html#color-units CSS 2.1 color specification] for a description of valid color syntax and keywords.|

code1={{CodeSample|
title=Code Sample|
description=Prints stuff in color and black. Note that it prints black twice: first and last.|
code=
<syntaxhighlight>
print("This is black.");
foreach color in $strings[blue, green, olive, darkorange, magenta, black]
print("This is "+color+".", color);
</syntaxhighlight>
}}|

see_also={{SeeAlso|dump|logprint|print_html|chat_notify}}|
cli_equiv=The CLI commands "fprint," "echo" and "fecho" have similar functionality, minus the color option. However, "cecho" (also "colorecho") does have this option for color.|
special=A list of common color commands that can be used: olive, yellow, orange, gray, fuchsia, red, white, silver, teal, navy, blue, maroon, purple. <br> More advance colors can be used by entering their Hexadecimal code as the string. <br>Using an invalid color name or code can cause odd colors to be chosen; see the [[Talk:Print|Talk Page]] for details.
<br />As of r8638, attempting to print a string beginning with a slash(/) will cause KoLmafia to print a blank line instead. To avoid this behavior, you must specify the second argument for the text color. Any color will do, and even a blank string (<code>""</code>) will work.
|
}}

[[Category:Miscellaneous Functions]]

Dump

2020-09-20T23:19:58Z

Fredg1: create dump()

{{
#vardefine:name|dump}}{{
#vardefine:return_type|void}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
return_type={{#var:return_type}}|
parameter1={{Param|any|composite}}|
}}|

function2={{Function|
name={{#var:name}}|
return_type={{#var:return_type}}|
parameter1={{Param|any|composite}}|
parameter2={{Param|string|color}}|
p1desc={{Pspan|composite}} is the variable to dump. Can be any data type (besides ''void''), but the intended use is with [[Data_Types#aggregate|an aggregate]] or [[Data_Types#record|a record]].|
p2desc={{Pspan|color}} is an html color name or code. See [[print]] for more information.|
}}|
function_description="Dumps" (i.e. "unfolds", showing every key/field of the variable, and their value) {{pspan|composite}} to the CLI (in <color>, if specified and valid) and to the session logs.<br>
If {{pspan|composite}} isn't a composite value (record or aggregate), functions similarly to print().|

code1={{CodeSample|
title=Code Sample|
description=This example starts with [https://kolmafia.us/showthread.php?280-Records-in-ASH Veracity's introductory example on records].|
code=
<syntaxhighlight>
/* definition */
record my_type {
int ifield;
string sfield;
record {
int first;
int second;
} rfield;
int [int, int] mfield;
};

my_type rvar;
my_type [int] mrvar;

/* population/assignments */
rvar.ifield = 10;
rvar.sfield = "secret";
rvar.rfield.first = 1000;
rvar.rfield.second = 2000;
rvar.mfield[ 2, 3 ] = 12;

mrvar[ 1 ] = rvar;
</syntaxhighlight>|
}}|

code2={{CodeSample|
description=Then, instead of using ''foreach'' loops, simply does:|
code=
<syntaxhighlight>
dump(mrvar);
</syntaxhighlight>|
moreinfo=which will print in the CLI:
<pre>
aggregate my_type [int]
1 => record my_type
  ifield => 10
  sfield => secret
  rfield => record (anonymous record 7dbf2293)
    first => 1000
    second => 2000
  mfield => aggregate int [int, int]
    2 => aggregate int [int]
      3 => 12
</pre>
}}|

cli_equiv=This is the equivalent of returning/ending with a variable with the CLI command "ash", minus the color option.|
see_also={{SeeAlso|print|logprint}}|
special=[https://kolmafia.us/showthread.php?25398-print()&p=158966&viewfull=1#post158966 Take note that the behaviour of this function with non-composite values is NOT the exact same as print().]
}}

[[Category:Miscellaneous Functions]]

Appearance rates

2020-08-31T10:28:52Z

Fredg1: code snippet is now obsolete

{{
#vardefine:name|appearance_rates}}{{
#vardefine:return_type|float [monster]}}{{
#vardefine:aggregate|yes}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|location|place}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|location|place}}|
parameter2={{Param|boolean|queue}}|
p1desc={{Pspan|place}} is the adventuring location to parse|
p2desc=The optional parameter {{Pspan|queue}} is false if not included.|
}}|

function_description=Returns a map, keyed by monster, with the appearance rate percentages as decimal values (ie a 30% rate monster has a value of 30.0). Account for combat rate modifiers, olfaction, etc. (as best as it can).<br> Bosses, semirare encounters, and other one-time-only monsters have a value of 0.0.<br> Ultra-Rare monsters have a value of -1.0.<br> Impossible monsters (mostly just monsters that only appear on odd/even ascensions) have a value of -2.0.<br> (Properly, as in not-also-olfacted) Banished monsters have a value of -3.0.<br> Monsters banished by in-game mechanics (such as pygmy janitors in the hidden city) have a value of -4.0 (is often mixed up with 0.0 values). </p>
<p>If there is a chance of non-combat encounters, that will be listed as the chance of encountering $monster[none].</p>
<p>If {{Pspan|queue}} is true, then the monsters currently in the adventuring queue will be considered when determining the likelihood of future encounters. This is better for a real prediction of what monster will actually occur next while not considering the queue is better for modeling theoretical situations.|

code1={{CodeSample|
title=Simple Example|
description=Prints the encounters in a zone and their rates of appearing.|
code=
<syntaxhighlight>
foreach mob, freq in appearance_rates($location[Dungeon of Doom])
switch {
case mob == $monster[none]:
if(freq > 0) print("Frequency of non-combats: "+ freq + "%");
break;
case freq > 0:
print("Frequency of " + mob + ": " + freq + "%");
break;
case freq == 0:
print("Frequency of " + mob + ": Boss (one time encounter) or semirare encounter.");
break;
case freq < 0:
print("Frequency of " + mob + ": Ultra-rare!");
break;
default:
print("Frequency of " + mob + ": Unknown");
break;
}
</syntaxhighlight>}}|
see_also={{SeeAlso|get_monsters|last_monster}}|
special=When not logged in, this function still returns the same data, as it is pulled from KoLmafia's data files.|
}}

[[Category:Adventuring]]

Appearance rates

2020-08-31T10:27:12Z

Fredg1:

{{
#vardefine:name|appearance_rates}}{{
#vardefine:return_type|float [monster]}}{{
#vardefine:aggregate|yes}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|location|place}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|location|place}}|
parameter2={{Param|boolean|queue}}|
p1desc={{Pspan|place}} is the adventuring location to parse|
p2desc=The optional parameter {{Pspan|queue}} is false if not included.|
}}|

function_description=Returns a map, keyed by monster, with the appearance rate percentages as decimal values (ie a 30% rate monster has a value of 30.0). Account for combat rate modifiers, olfaction, etc. (as best as it can).<br> Bosses, semirare encounters, and other one-time-only monsters have a value of 0.0.<br> Ultra-Rare monsters have a value of -1.0.<br> Impossible monsters (e.g. encountering a clingy pirate corresponding to your gender) have a value of -2.0.<br> (Properly, as in not-also-olfacted) Banished monsters have a value of -3.0.<br> Monsters banished by in-game mechanics (such as pygmy janitors in the hidden city) have a value of -4.0 (is often mixed up with 0.0 values). </p>
<p>If there is a chance of non-combat encounters, that will be listed as the chance of encountering $monster[none].</p>
<p>If {{Pspan|queue}} is true, then the monsters currently in the adventuring queue will be considered when determining the likelihood of future encounters. This is better for a real prediction of what monster will actually occur next while not considering the queue is better for modeling theoretical situations.|

code1={{CodeSample|
title=Simple Example|
description=Prints the encounters in a zone and their rates of appearing.|
code=
<syntaxhighlight>
foreach mob, freq in appearance_rates($location[Dungeon of Doom])
switch {
case mob == $monster[none]:
if(freq > 0) print("Frequency of non-combats: "+ freq + "%");
break;
case freq > 0:
print("Frequency of " + mob + ": " + freq + "%");
break;
case freq == 0:
print("Frequency of " + mob + ": Boss (one time encounter) or semirare encounter.");
break;
case freq < 0:
print("Frequency of " + mob + ": Ultra-rare!");
break;
default:
print("Frequency of " + mob + ": Unknown");
break;
}
</syntaxhighlight>}}|
see_also={{SeeAlso|get_monsters|last_monster}}|
special=When not logged in, this function still returns the same data, as it is pulled from KoLmafia's data files.|
}}

[[Category:Adventuring]]

Data Structures

2020-08-29T23:46:58Z

Fredg1: /* Aggregate literals */ not providing keys with a map keyed by integers

{{TOCright}}

KoLmafia supports complex data structures such as maps and records made from simple [[Data Types|data types]].

== Maps ==
If you are new to programming or find the information below confusing, you may want to read [[Map_Guide | A Noob's Guide to Maps]] first.

Most of this information was copied directly from ASH Maps Tutorial, by Veracity (http://kolmafia.sourceforge.net/advanced.html#maps)

A map is indexed by one data type (the key) and associates that key with another (or the same) data type (the value). The key can be any ASH simple data type: boolean, int, float, string, item, location, class, stat, skill, effect, familiar, slot, or monster. The value can be any ASH data type at all: a simple type, a record, or can be another map. This effectively allows multi-dimensional maps and. In fact, that's how the syntax we provide for multi-dimensional maps actually operate: maps of maps of maps ...

You can declare a map any time you can declare a variable: as a top level (global) variable, as a function parameter, or as a local variable in any scope.

You can fetch data from a map any time you can provide a data value: in an expression, as a function parameter, on the right side of an assignment statement, from a "return" statement, as so on. You can pass around entire maps, individual elements, or intermediate maps: "slices".

=== Declarations ===

The syntax for declaring the data type of a map:

<pre>
<data type> [ <key type>, ... ] <aggregate_name>
</pre>

For example:

{{CodeSample
|code=<syntaxhighlight>
string [item] map1;
float [class, string, int] another_map;
</syntaxhighlight>}}

=== Assignments ===

==== Assigning individual values ====

If you specify a map and a complete set of indices (of the correct types) on the left side of an assignment statement, you set a single element.

{{CodeSample
|code=<syntaxhighlight>
int[item] my_pricelist;
my_pricelist[ $item[ pail ] ] = 1000;
my_pricelist[ $item[ bum cheek ] ] = 404;
my_pricelist[ $item[ red button ] ] = 100;
my_pricelist[ $item[ red balloon ] ] = 100000;
</syntaxhighlight>}}

==== Aggregate literals ====
You can declare ready to use, anonymous (single use) maps on the fly, called ''aggregate literals'', at any time you can provide a data value. They follow the syntax:
<pre>
{ <key>: <value>, <key>: <value>, <key>: <value> ... }
</pre>

An ''aggregate literal'' can be used to initialize an entire aggregate at once. For example:

{{CodeSample
|code=<syntaxhighlight>
int[item] my_pricelist = {
$item[pail]: 1000,
$item[bum cheek]: 404,
$item[red button]: 100,
$item[red balloon]: 100000
};
</syntaxhighlight>}}
which achieves the same as what was done in the 'Assigning individual values' example.

Note: when using an aggregate literal for anything else than assignment (e.g. as a return statement, in an expression, or as a function parameter), you need to supply the data types of the aggregate in front of the aggregate literal, even when the expected data types are already known. Example:
{{CodeSample
|code=<syntaxhighlight>
item [int] my_function () {

...

return item [int] {<int>: <item>, <int>: <item>, <int>: <item> ...};
}
</syntaxhighlight>}}

Note bis: if the key of your map is integers, providing the keys is not mandatory; the keys will be automatically supplied in order, so:
{{CodeSample
|code=<syntaxhighlight>
string [int] {"this","is","called","a","list"};
</syntaxhighlight>}}
Creates a map that contains:
{{CodeSample
|code=<syntaxhighlight>
0 => this
1 => is
2 => called
3 => a
4 => list
</syntaxhighlight>}}

It is possible to make an aggregate literal of a multi-dimensional map. Since multi-dimensional maps are effectively maps of maps (of maps) ''(of maps)'' ''(...)'', their aggregate literal would be an aggregate literal, inside an aggregate literal ''(inside an aggregate literal)'' (...). Nested aggregate literals.
{{CodeSample
|code=<syntaxhighlight>
item[class, slot] basic_equipments = {
$class[Seal Clubber]: {
$slot[hat]: $item[seal-skull helmet],
$slot[weapon]: $item[seal-clubbing club],
$slot[pants]: $item[old sweatpants]
},
$class[Turtle Tamer]: {
$slot[hat]: $item[helmet turtle],
$slot[weapon]: $item[turtle totem],
$slot[pants]: $item[old sweatpants]
},
$class[Pastamancer]: {
$slot[hat]: $item[ravioli hat],
$slot[weapon]: $item[pasta spoon],
$slot[pants]: $item[old sweatpants]
},
$class[Sauceror]: {
$slot[hat]: $item[Hollandaise helmet],
$slot[weapon]: $item[saucepan],
$slot[pants]: $item[old sweatpants]
},
$class[Disco Bandit]: {
$slot[hat]: $item[disco mask],
$slot[weapon]: $item[disco ball],
$slot[pants]: $item[old sweatpants]
},
$class[Accordion Thief]: {
$slot[hat]: $item[mariachi hat],
$slot[weapon]: $item[stolen accordion],
$slot[pants]: $item[mariachi pants]
}
};
</syntaxhighlight>}}

==== Map-map assignments ====
If you use a map on the left side of an assignment, you set the whole map at once to the new value.

{{CodeSample
|code=<syntaxhighlight>
int [item] my_pricelist;
int [item] new_pricelist;

/* Some code that updates my_pricelist with new_pricelist */

my_pricelist = new_pricelist;

/* Now my_pricelist and new_pricelist point to the same aggregate;
changes to an element of one of them will be visible in the other */
</syntaxhighlight>}}

==== Slices ====
If you specify a map and a prefix of indices (of the correct type), you directly set one of the intermediate maps, a "slice".

{{CodeSample
|code=<syntaxhighlight>
float [string, int, string] my_map;
float [int, string] slice1;

/* Some code that fills my_map[ "slice1" ] with slice1 */
my_map[ "slice1" ] = slice1;
</syntaxhighlight>}}

=== References ===

The syntax for referencing an element (or slice) of a map:

<pre>
<aggregate name>[ <key expression>, ... ]
</pre>

All the key expressions will be evaluated at run time. If you specify all the keys the map expects, you fetch data of the type specified by the map. If you specify fewer keys than the map expects, you get an intermediate map, a "slice".

As an example:
{{
CodeSample|
code=
<syntaxhighlight>
boolean [string, string] props;
</syntaxhighlight>}}

might be used to hold "properties" associated with names.
{{
CodeSample|
code=
<syntaxhighlight>
props[ "dog", "mammal" ] = true;
props[ "dog", "pet" ] = true;
props[ "dog", "fun" ] = false;
props[ "turtle", "mammal" ] = false;
props[ "turtle", "pet" ] = true;
props[ "turtle", "fun" ] = false;
props[ "aardvark", "mammal" ] = true;
props[ "aardvark", "pet" ] = false;
props[ "aardvark", "fun" ] = true;
</syntaxhighlight>}}

references:

<pre>
props[ "dog", "mammal"] => true
boolean [string] animal = props[ "turtle" ];
animal[ "fun" ] => false
</pre>

=== Contains ===

You can test the presence of a key in a map using the "contains" operator:

<pre>
<aggregate reference expression> contains <key expression>
</pre>

Where <aggregate reference expression> must evaluate at run time to a map or slice, and must evaluate at run time to a key of the appropriate type. (Note that that is enforced at parse time; ASH can tell the datatype any expression will produce).

<pre>
props contains "dog" => true
props contains "elephant" => false
props[ "aardvark" ] contains "fun" => true
animal contains "pet" => true
animal contains "favorite food" => false
</pre>

Note that only the current slice's keys are evaluated. This means that:

<pre>
boolean [ boolean ] [ boolean ] [ boolean ] [ boolean ] [ boolean ] much_truthness;
much_truthness [ true ] [ true ] [ false ] [ true ] [ true ] = true;

return much_truthness [ true ] [ true ] contains true;
</pre>

yields:
<pre>
Returned: false
</pre>

=== Remove ===

You can remove a key-value association from a map using the "remove" unary operator:

<pre>
remove <aggregate reference>
</pre>

For clarification, an aggregate reference is "<map name>[ <index 1> ... <index n> ]" where <map name>[ <index 1> ... <index n-1> ] specifies the "slice" and <index n> specifies the "key". Which is just what you expect, if you fully specify the indices; for a single dimensional map, "map[10]" -> "map" is the slice and 10 is the key. The "remove" operator removes the "key" from the "slice". For example:

{{CodeSample|code=<syntaxhighlight>
string [int] map1;
map1[5] = "foo";
print( count( map1 ) + " " + map1 contains 5 + " " + map1[5] );
print( "remove: " + remove map1[5] );
print( count( map1 ) + " " + map1 contains 5 + " " + map1[5] );
print( "remove: " + remove map1[5] );
int [string, string] map2;
map2["me","you"] = 17;
print( count( map2["me"] ) + " " + map2["me"] contains "you" + " " + map2["me","you"] );
print( "remove: " + remove map2["me", "you"] );
print( count( map2["me"] ) + " " + map2["me"] contains "you" + " " + map2["me","you"] );
print( "remove: " + remove map2["me", "you"] );
print( count( map2 ) + " " + map2["me"] );
print( "remove: " + remove map2["me"] );
print( count( map2 ) + " " + map2["me"] );
</syntaxhighlight>}}

yields:

<pre>
1 true foo
remove: foo
0 false
remove:
1 true 17
remove: 17
0 false 0
remove: 0
1 aggregate int [string]
remove: aggregate int [string]
0 aggregate int [string]
</pre>

=== Clear ===

You can remove all <code>key => value</code> entries from a map using the {{f|clear}} function:

{{CodeSample|code=<syntaxhighlight>clear( <aggregate> );</syntaxhighlight>}}

=== Count ===

The {{f|count}} function returns the number of defined keys for the specified aggregate.

{{CodeSample|code=<syntaxhighlight>int size = count( <aggregate> );</syntaxhighlight>}}

=== Sort ===

From http://kolmafia.us/showthread.php?t=1738 and http://kolmafia.us/showthread.php?10729

The syntax is:
{{CodeSample|code=<syntaxhighlight>sort aggregate by keyExpr;</syntaxhighlight>}}

<code>aggregate</code> is a reference to the object to be sorted - arrays are probably the most useful things to sort, but any mapping type can be used. But please note that when you sort a map, you change the values that correspond to the index. To sort on a map, you would want to use a multidimensional maps, but note that you can only sort along a single dimension at a time when doing this. Simply put... "sort" is only useful in cases where your data exists entirely in the values of the map; the keys can have no meaning beyond simply being distinct.

The reference must not be enclosed in parentheses, as that would look like a call to a function named <code>sort()</code> - which is still perfectly valid, "sort" has not become a [[Reserved Words|reserved word]].

<code>keyExpr</code> is an arbitrary expression that defines how the items should be ordered. It is evaluated once for every entry in the aggregate, in a scope with two additional variables implicitly defined: '<code>index</code>' and '<code>value</code>', holding the details of that entry. The value of the <code>keyExpr</code> is used as the sort key; typically it would be an <code>int</code> or <code>string</code>, but can be any ASH type that can be compared via "<" and the other relational operators.

The most basic form of sorting would therefore be "<code>sort ... by value</code>", but many useful things can be done with the use of a more complex <code>keyExpr</code> - the only real restriction is that the expression should not modify the object you're sorting. For example, if you had an array of items, you could sort it "<code>by autosell_price(value)</code>". An array of weapon items could be sorted "<code>by -get_power(value)</code>" to put it in decreasing order of power. If the elements of your aggregate are records, you'd need to use something like "<code>by value.fieldName</code>", since the records themselves can't be meaningfully compared.

After the sort statement, the aggregate will have exactly the same sets of keys and values as before (even if the keys weren't consecutive), and the iteration order of the keys will be the same, but the values will likely be associated with different keys. The sort is stable - in other words, elements with sort keys that compare as equal will remain in the same order. This means that you can sort on multiple criteria by simply performing separate sorts for each of the criteria, in increasing order of significance.

To find out how many things you have, you might do:
{{CodeSample|code=<syntaxhighlight>
item [int] whatGot;
int ctr =0;

foreach it in get_inventory() {
whatGot[ctr] = it;
ctr+=1;
}

sort whatGot by item_amount(value);

foreach x, it in whatGot
print(item_amount(it) + ' of ' + it);
</syntaxhighlight>}}
Note that this use of an optional feature of foreach. The second variable in the foreach is the value of whatGot[x].

A few more examples of things you can do:
* "<code>by -value</code>" sorts integers in decreasing order (there's no similar trick for <code>string</code> values).
* "<code>by -index</code>" reverses the existing order of an array (or map with integer keys).
* "<code>by random(1000000)</code>" shuffles into a random order.
* "<code>by otherArray[index]</code>" uses values from a parallel array as the sort keys (you'd then need to do "<code>sort otherArray by value;</code>" if you wanted the two arrays to remain in sync).

===Iteration===
To iterate through a map, use the '''foreach''' operator. For instance, if you wanted to print out how many of each item you had, you could do something like the following:
{{CodeSample|code=<syntaxhighlight>
int[item] map = get_inventory();
foreach key in map {
print(key + " (" + map[key] + ")");
}
</syntaxhighlight>}}

Multidimensional maps are implemented as maps that map keys to maps. '''int[item][string]map''' is really a mapping of items to int[string] maps. Iteration, therefore, is as follows:
{{CodeSample|code=<syntaxhighlight>
int[item][string] map;
file_to_map("somefile.txt", map);
foreach k1 in map {
print(k1 + ": ");
foreach k2 in map[k1] {
print("\t" + k2 + ": " + map[k1][k2]);
}
}
</syntaxhighlight>}}

Two things to note: First, '''int[item][string]map''' is equivalent to '''int[item, string]map'''. This really comes down to author preference, although the second form is generally more common. Second, the two following foreach loops are equivalent:
{{CodeSample|code=<syntaxhighlight>
int[item][string] map;
foreach k1 in map {
foreach k2 in map[k1] {
func(map[k1][k2]);
}
}

foreach k1, k2 in map {
func(map[k1][k2]);
}
</syntaxhighlight>}}

Of course, the latter does not lend itself to, say, only printing the first key once, whereas the former can be used that way (see the preceding example).

===Implementation===
Maps in ASH are implemented internally as TreeMaps [http://download.oracle.com/javase/1.5.0/docs/api/java/util/TreeMap.html]. See below for some implications.

== Arrays ==
These look and behave like mappings of integers to values, where the keys only take values from 0 to n, but these are implemented as Java Arrays.

===Differences between arrays and maps===

'''item [12] array;'''

Can use keys 0 - 11. You get a runtime error if you use any other key. It always uses memory to hold 12 items, even if you only use a couple of them. But it's a constant time - O(1) - to access any element.

'''item [int] map;'''

Can use any int as a key. It has constant memory for the Java map, and additional memory for each element in the map, but is O( log n) to access any particular element.

If you are able to use (a fairly densely packed set of) integers as keys, your program will be faster and use (potentially) slightly more memory.

If you have a sparse set of integers, you can still use an array and get fast access, but you will waste a lot of memory.

If you can't use integers as keys or don't want to waste memory on a sparse array, you can have a slower but less memory consuming map.

[http://kolmafia.us/showthread.php?6425-Sorting-skills-by-mana-cost&p=48703&viewfull=1#post48703]

====Time considerations====
* Given '''if (a == item1 || a == item2 || a == item3)''' and '''if ($items[item1, item2, item3] contains a)''', which is faster?

This is going to depend on the number of items in the list, and which one happens to match; if 'a' is almost always item1, then the first form is likely to win on practical grounds, even though it's theoretically slower (O(n) vs. O(log n)).

The second form is a definite win assuming no such coincidences of the item chosen, a somewhat larger set of items, and that the code is executed more than once per run of the script. The first lookup in a plural constant actually builds an internal map that allows such queries to be efficiently done; this is deferred because typical use of a plural constant involves only iteration, not lookups.

There's always the "profile" command, if you really need to know which is more efficient in a given situation - although it's unlikely that either would have a noticeable effect on your script's performance.

[http://kolmafia.us/showthread.php?6425-Sorting-skills-by-mana-cost&p=48728&viewfull=1#post48728]

== Records ==

(Link to Veracity's post introducing the record [http://kolmafia.us/showthread.php?t=280])

Records are custom-made data types, that act like compartmentalized boxes [https://i.imgur.com/rgxLKRC.jpg].

They are "variable packages", that allow you to group together data of any type, including other records, in them.

Records have "models" (the custom data type of the record itself), and names representing them (though not all of them are creative, such as ''"the_black_one_that_I_bought_a_year_ago"'', or ''"the_one_that_is_over_there_by_the_door"'').

Each "compartment" (field) also has a name, as well as an expected data type. ''(Stop trying to put screws "there"; that's my god damn lunchbox, and this is "the spot in which you put the guacamole"!)''

Once a "box's model" (record's data type) is declared, it can be used (almost) anywhere that can use a built-in type name (as long as you don't leave the scope in which the record was declared), such as in functions and other records.

===Declarations===
The syntax for declaring a new record:
<pre>
record <"model" name> { <data type 1> <field name 1>; <data type 2> <field name 2>; ... }
</pre>

For example:
{{CodeSample
|code=<syntaxhighlight>
record human {
string name;
int date_of_birth;
location location_of_birth;
item [slot] clothes;
};
</syntaxhighlight>}}

This declared a new data '''''type''''', a ''mold'', a ''blueprint''... No variable was created here.

To actually ''create'' a variable that ''uses'' this "model", you would '''then''' do:
{{CodeSample
|code=<syntaxhighlight>
human that_guy;
human this_guy;
human that_other_guy;
</syntaxhighlight>}}
You now have 3 "human"s, each with a name, date of birth, location of birth, and clothes (though none of them has had those assigned, yet).

It is possible to declare a record and create a variable of that type at the same time. The following is equivalent to the two previous code samples combined:
{{CodeSample
|code=<syntaxhighlight>
record human {
string name;
int date_of_birth;
location location_of_birth;
item [slot] clothes;
} that_guy;

human this_guy;
human that_other_guy;
</syntaxhighlight>}}

===Accessing the fields===
Once a variable of a recorded data type was created, you may access its fields with <variable name>.<field name>:

{{CodeSample
|code=<syntaxhighlight>
that_guy.name = "Andrew";
that_guy.date_of_birth = 08212006;
that_guy.location_of_birth = $location[Noob Cave];

that_other_guy.name = "Bob";
that_other_guy.location_of_birth = $location[South of the Border];

if ( that_other_guy.clothes [ $slot[pants] ] == $item[none] )
print( "Put some pants on, " + that_other_guy.name + "!" );
</syntaxhighlight>}}

===Omitting the "model" name===
When declaring a record, supplying the "model" name (what goes between "record" and the left curly bracket) is not mandatory. If you don't, the record will be "anonymous".

An "anonymous" record is like a makeshift bindle; you made it on a whim, it's unique, it's yours, you couldn't replicate it even if you tried, and nobody else wants it.

If you omit data type's name, you'll definitely want to supply a variable name after the curly braces, or it will have been a pure waste of time:
{{CodeSample|code=<syntaxhighlight>
record {
int days_spent_travelling;
item [int] content;
} mah_bindle;

mah_bindle.content [0] = $item[ big rock ];
</syntaxhighlight>}}

===[[New]]===
[[New]] can be used to assign a whole record at once.

[[Category:Scripting]]

Split string

2020-08-21T00:41:43Z

Fredg1:

{{
#vardefine:name|split_string}}{{
#vardefine:return_type|string [int]}}{{
#vardefine:aggregate|yes}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|source}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|source}}|
parameter2={{Param|string|delimiter}}|
p1desc={{Pspan|source}} is the string to split|
p2desc={{Pspan|delimiter}} is the (optional) [[Regular Expressions|regular expression]] to split with|
}}|

function_description=Returns an array of your {{pspan|source}}, split by either {{pspan|delimiter}} or by line-breaks if not supplied.|

code1={{CodeSample|
title=Code Samples|
description=The following example shows how split string can easily convert comma separated strings into useful data.|
code=
<syntaxhighlight>
string items, numbers, total_string;
int total;
item thing;
string[int] split_map;
numbers = "1, 203, 20002, 450, 194, 92992, 9000, 1";
items = "mae west, asshat, hell ramen, bird, batblade";

split_map = split_string(numbers, ",");
print("You have a total of "+count(split_map)+" numbers.", "blue");
print("They are the following:", "blue");
foreach it in split_map {
print(split_map[it]);
total+=to_int(split_map[it]);
}
total_string = to_string(total, "%,d");
print("Their total is: "+total_string+".", "blue");
print("");
//Items
clear(split_map);
split_map = split_string(items, ",");
print("You have a total of "+count(split_map)+" items.", "blue");
print("They are the following:", "blue");
foreach it in split_map {
thing = to_item(split_map[it]);
if (thing == $item[none])
print(split_map[it]+" is not a valid item", "red");
else
print(thing);
}
</syntaxhighlight>|
moreinfo=
}}

{{CodeSample|
description=The following example uses KoLMafia's proxy record of an consumable to return the min-max values of the consumable's moxie/muscle/mysticality/adventure gains. Using split string, it finds the average of each gain and returns it in a record. |
code=
<syntaxhighlight>
record item_range {
float mox;
float mus;
float mys;
float adv;
item thing;
};
item_range stats;

item_range item_avg(item consumable) { //Input food/drink/spleen
item_range attributes;
string[int] avgmap;
float realavg;
string range_string;
attributes.thing = consumable;
if (consumable.fullness == 0 && consumable.inebriety == 0 && consumable.spleen == 0){
print(consumable+" is not a valid consumable.", "red");
return attributes;
}

//Moxie
range_string = consumable.moxie;
avgmap = split_string(range_string, "-");
if (count(avgmap) == 1)
attributes.mox = to_int(range_string);
else {
foreach it in avgmap
realavg += to_int(avgmap[it]);
attributes.mox = (realavg/2);
}
realavg = 0;
clear(avgmap);

//Muscle
range_string = consumable.muscle;
avgmap = split_string(range_string, "-");
if (count(avgmap) == 1)
attributes.mus = to_int(range_string);
else {
foreach it in avgmap
realavg += to_int(avgmap[it]);
attributes.mus = (realavg/2);
}
realavg = 0;
clear(avgmap);

//Mysticality
range_string = consumable.mysticality;
avgmap = split_string(range_string, "-");
if (count(avgmap) == 1)
attributes.mys = to_int(range_string);
else {
foreach it in avgmap
realavg += to_int(avgmap[it]);
attributes.mys = (realavg/2);
}
realavg = 0;
clear(avgmap);

//Adventures
range_string = consumable.adventures;
avgmap = split_string(range_string, "-");
if (count(avgmap) == 1)
attributes.adv = to_int(range_string);
else {
foreach it in avgmap
realavg += to_int(avgmap[it]);
attributes.adv = (realavg/2);
}
realavg = 0;
clear(avgmap);
return attributes;
}

stats = item_avg($item[mae west]);
print("Item "+stats.thing+" is a "+item_type(stats.thing)+" which gives the following averages:", "green");
print("Moxie--"+stats.mox+", Muscle--"+stats.mus+", Mysticality--"+stats.mys+", and Adventures--"+stats.adv+".", "blue");
</syntaxhighlight>|
moreinfo=
}}|

special=This function technically returns an array, not a map. The information in both is accessed in the same way. However, you cannot add new key-value pairs to an array (its length is static once set).<br></p>
{{CodeSample|
description=This also means that the array will always contain at least 1 key (0), even if it was supplied an empty string. As such, using [[count]] on the result is not a fully reliable way to know how many items were in a list.|
code=
<syntaxhighlight>
print( split_string("", ",").count() );
print( split_string("a", ",").count() );
print( split_string("a,b", ",").count() );
print( split_string("a,b,c", ",").count() );
print( split_string("a,b,c,d,e,f,g", ",").count() );
</syntaxhighlight>|
moreinfo=Will return: 1, 1, 2, 3, 7
}}<p>
|
}}

[[Category:String Handling Routines]]

Remove property

2020-08-20T00:25:22Z

Fredg1: return value

{{
#vardefine:name|remove_property}}{{
#vardefine:return_type|string}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|prop}}|
p1desc={{Pspan|prop}} is the property to remove.|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|prop}}|
parameter2={{Param|boolean|global}}|
p1desc={{Pspan|prop}} is the property to remove.|
p2desc={{Pspan|global}} if true, look for the property specifically in the global map. If false or not included will look at the user map.|
}}|

function_description=If {{Pspan|prop}} is a built-in property, resets to default. Otherwise, removes from the user map, or global if {{Pspan|global}} is true.

The return value is the value the property had prior to being reset.|

see_also={{SeeAlso|Miscellaneous_Functions#Property_Functions}}|
}}

[[Category:Miscellaneous Functions]]

Miscellaneous Functions

2020-08-20T00:20:18Z

Fredg1: /* Property Functions */ remove_property return strings

{{TOCright}}
== Chat Functions ==
{{Flink|void|chat_clan|string}}
{{Flink|void|chat_clan|string|string|desc=Sends a message to clan chat.}}
{{Flink|void|chat_macro|string|desc=Submits a chat macro to KoL.}}
{{Flink|void|chat_notify|string|string|desc=Sends a notification to the player's own chat.}}
{{Flink|void|chat_private|string|string|desc=Sends a private message to another player.}}
{{Flink|boolean|is_online|string|desc=Check to see if a player is online.}}
{{Flink|boolean [string]|who_clan|desc=Returns a list of whom is in your clan and if they are in chat.}}
{{Flink|boolean|can_faxbot|monster|desc=Check to see if a monster can be faxed.}}
{{Flink|boolean|faxbot|monster|desc=Attempts to receive a fax of a given monster.}}

== Debugging Functions ==
{{Flink|void|disable|string|desc=Disables the specified function.}}
{{Flink|void|enable|string|desc=Enables the specified function.}}
{{Flink|buffer|load_html|string|desc=Works like visit_url(), but for debugging.}}
{{Flink|string|make_url|string|boolean|boolean|desc=Crafts the URL to visit.}}

== Map Management Functions ==
''Note: Information about maps (including creating, assigning, and removing keys, can be found at [[Data Structures#Maps|Map Data Structures]].''

{{Flink|boolean|file_to_map|string|aggregate|desc=Loads a map from a tab-delimited text file.}}
{{Flink|boolean|map_to_file|aggregate|string|desc=Saves a map to a tab-delimited text file.}}
{{Flink|int|count|aggregate|desc=Returns the number of defined keys for the specified aggregate.}}
{{Flink|void|clear|aggregate|desc=Removes all keys from the specified aggregate.}}

== Time Functions ==
{{Flink|string|format_date_time|string|string|string|desc=Reformats dates.}}
{{Flink|int|gameday_to_int|desc=Returns the current KoL date as an integer.}}
{{Flink|string|gameday_to_string|desc=Returns the current KoL date as a string.}}
{{Flink|int|gametime_to_int|desc=Returns the current KoL time in ms as an integer.}}
{{Flink|string|now_to_string|string|desc=Returns current local time/date in SimpleDateFormat format.}}
{{Flink|string|time_to_string|desc=Returns the current local time in HH:mm:ss z format.}}
{{Flink|string|today_to_string|desc=Returns the current local day in ISO format.}}

== SVN Functions ==
''There is much additional information in the [[SVN Primer]]''.
{{Flink|boolean|svn_exists|string|desc=Returns true if a valid working copy named projectname exists in the svn/ folder.}}
{{Flink|boolean|svn_at_head|string|desc=Returns true if projectname exists, is a valid working copy, and is currently at the same revision number as the repository.}}
{{Flink|record|svn_info|string|desc=Returns a record containing additional information about the given projectname: svnurl, last author, last revision, last change date.}}

== User Interaction ==
{{Flink|void|print|string|{{opt|string}}|desc=Prints to CLI and status line of Adventuring window, optionally in a specified color.}}
{{Flink|void|print_html|string|desc=Prints to CLI, parsing any included html.}}
{{Flink|void|logprint|string|desc=Prints to the session log.}}
{{Flink|void|wait|int}}
{{Flink|void|waitq|int|desc=Sleeps for the specified number of seconds.}}
{{Flink|boolean|user_confirm|string|desc=Allows user input in Y/N format.}}

== Property Functions ==

{{Flink|boolean [string]|get_all_properties|string|boolean|desc=Returns a map of all user or global properties.}}
{{Flink|boolean|property_exists|string}}
{{Flink|boolean|property_exists|string|boolean|desc=Returns true if the named property exists.}}
{{Flink|boolean|property_has_default|string name|desc=Returns true if the named property in has a default value.}}
{{Flink|string|property_default_value|string name|desc=Returns the default value for a built-in property.}}
{{Flink|string|get_property|string}}
{{Flink|string|get_property|string|boolean|desc=Gets a global or user preference as appropriate.}}
{{Flink|void|set_property|string|string|desc=Sets a global or user preference as appropriate.}}
{{Flink|string|remove_property|string}}
{{Flink|string|remove_property|string|boolean|desc=Removes property or resets it to default.}}
{{Flink|boolean|rename_property|string|string|desc=Changes name of a property.}}

== Other Functions ==
{{Flink|void|abort|{{opt|string}}|desc=Aborts the current script with an optional message.}}
{{Flink|boolean|cli_execute|string|desc=Executes the given command as if it were entered into the CLI.}}
{{Flink|void|batch_open|desc=Used to mark the beginning of a block of functions to operate in batch mode (see page for {{f|batch_close}} for details).}}
{{Flink|boolean|batch_close|desc=Used to mark the end of a block of functions to operate in batch mode (see page for details).}}
{{Flink|int|get_revision|desc=Returns the current KoLmafia revision number.}}
{{Flink|string|get_version|desc=Returns the most recent KoLmafia version.}}
{{Flink|string|get_player_id|string|desc=Returns the user id number of a given player.}}
{{Flink|string|to_json|aggregate|desc=Converts a simple aggregate into JSON.}}

Additional functions that are considered not really to be ash functions are available in [[Miscellaneous ASH Features#Special Syntax Functions|Misc ASH Features]]

[[Category:Scripting]]

Insert

2020-08-19T06:37:19Z

Fredg1:

{{
#vardefine:name|insert}}{{
#vardefine:return_type|buffer}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|buffer|original}}|
parameter2={{Param|int|strStart}}|
parameter3={{Param|string|stuff}}|
p1desc={{Pspan|original}} is the buffer to modify|
p2desc={{Pspan|strStart}} marks where to insert the string|
p3desc={{Pspan|stuff}} is the string to insert|
}}|

function_description=Returns the buffer {{pspan|original}} with the string {{pspan|stuff}} inserted at {{pspan|strStart}}.|

code1={{CodeSample|
title=Code Sample|
description=Inserts a "Refresh page" link to the Pyramid inside KoL's default border.|
code=
<syntaxhighlight>
buffer results;
results.append(visit_url());

int strEnd = results.index_of("height=137 border=0>");
if(strEnd > 0) {
results.insert(strEnd + 20,"<br /><div align='center' class='tiny'><a href='pyramid.php'>Refresh page</a></div>");
}
results.write();
</syntaxhighlight>
}}|

see_also={{SeeAlso|delete|append|set_length}}|
}}

[[Category:String Handling Routines]]

Delete

2020-08-19T06:37:03Z

Fredg1:

{{
#vardefine:name|delete}}{{
#vardefine:return_type|buffer}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|buffer|original}}|
parameter2={{Param|int|strStart}}|
parameter3={{Param|int|strEnd}}|
p1desc={{Pspan|original}} is the buffer to modify|
p2desc={{Pspan|strStart}} marks where to start deleting|
p3desc={{Pspan|strEnd}} marks where to end deleting|
}}|

function_description=Returns the buffer {{pspan|original}} with the substring from {{pspan|strStart}} to {{pspan|strEnd}} removed.|

code1={{CodeSample|
title=Code Sample|
description=Removes the border that KoL uses to frame some tables.|
code=
<syntaxhighlight>
buffer results;
results.append(visit_url());

string del = " style=\"padding: 5px; border: 1px solid blue;\"";
int st = results.index_of(del);
if ( st > -1 ) results.delete(st, st+length(del));
else print("string '"+del+ "' not found");
results.write();
</syntaxhighlight>
}}|

see_also={{SeeAlso|insert|append|set_length}}|
}}

[[Category:String Handling Routines]]

Append

2020-08-19T06:36:16Z

Fredg1:

{{
#vardefine:name|append}}{{
#vardefine:return_type|buffer}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|buffer|original}}|
parameter2={{Param|string|add}}|
p1desc={{Pspan|original}} is the buffer to add to|
p2desc={{Pspan|add}} is a string to add on|
}}|

function_description=Returns a buffer containing {{pspan|original}} with {{pspan|add}} tacked on to the end.|

code1={{CodeSample|
title=Code Sample|
description=Print a list of all items currently equipped.|
code=
<syntaxhighlight>
buffer gear;

foreach slot in $slots[]
if(equipped_item(slot) != $item[none]) {
if(length(gear) != 0)
gear = append(gear, ", ");
gear = append(gear, to_string(equipped_item(slot)));
}

print("I am wearing: "+ gear);
</syntaxhighlight>
}}|

see_also={{SeeAlso|append_tail|set_length|delete|insert}}|
}}

[[Category:String Handling Routines]]

Data Structures

2020-08-19T00:02:51Z

Fredg1: /* Assignments */ map-map assignments still needs work

{{TOCright}}

KoLmafia supports complex data structures such as maps and records made from simple [[Data Types|data types]].

== Maps ==
If you are new to programming or find the information below confusing, you may want to read [[Map_Guide | A Noob's Guide to Maps]] first.

Most of this information was copied directly from ASH Maps Tutorial, by Veracity (http://kolmafia.sourceforge.net/advanced.html#maps)

A map is indexed by one data type (the key) and associates that key with another (or the same) data type (the value). The key can be any ASH simple data type: boolean, int, float, string, item, location, class, stat, skill, effect, familiar, slot, or monster. The value can be any ASH data type at all: a simple type, a record, or can be another map. This effectively allows multi-dimensional maps and. In fact, that's how the syntax we provide for multi-dimensional maps actually operate: maps of maps of maps ...

You can declare a map any time you can declare a variable: as a top level (global) variable, as a function parameter, or as a local variable in any scope.

You can fetch data from a map any time you can provide a data value: in an expression, as a function parameter, on the right side of an assignment statement, from a "return" statement, as so on. You can pass around entire maps, individual elements, or intermediate maps: "slices".

=== Declarations ===

The syntax for declaring the data type of a map:

<pre>
<data type> [ <key type>, ... ] <aggregate_name>
</pre>

For example:

{{CodeSample
|code=<syntaxhighlight>
string [item] map1;
float [class, string, int] another_map;
</syntaxhighlight>}}

=== Assignments ===

==== Assigning individual values ====

If you specify a map and a complete set of indices (of the correct types) on the left side of an assignment statement, you set a single element.

{{CodeSample
|code=<syntaxhighlight>
int[item] my_pricelist;
my_pricelist[ $item[ pail ] ] = 1000;
my_pricelist[ $item[ bum cheek ] ] = 404;
my_pricelist[ $item[ red button ] ] = 100;
my_pricelist[ $item[ red balloon ] ] = 100000;
</syntaxhighlight>}}

==== Aggregate literals ====
You can declare ready to use, anonymous (single use) maps on the fly, called ''aggregate literals'', at any time you can provide a data value. They follow the syntax:
<pre>
{ <key>: <value>, <key>: <value>, <key>: <value> ... }
</pre>

An ''aggregate literal'' can be used to initialize an entire aggregate at once. For example:

{{CodeSample
|code=<syntaxhighlight>
int[item] my_pricelist = {
$item[pail]: 1000,
$item[bum cheek]: 404,
$item[red button]: 100,
$item[red balloon]: 100000
};
</syntaxhighlight>}}
which achieves the same as what was done in the 'Assigning individual values' example.

Note: when using an aggregate literal for anything else than assignment (e.g. as a return statement, in an expression, or as a function parameter), you need to supply the data types of the aggregate in front of the aggregate literal, even when the expected data types are already known. Example:
{{CodeSample
|code=<syntaxhighlight>
item [int] my_function () {

...

return item [int] {<int>: <item>, <int>: <item>, <int>: <item> ...};
}
</syntaxhighlight>}}

It is possible to make an aggregate literal of a multi-dimensional map. Since multi-dimensional maps are effectively maps of maps (of maps) ''(of maps)'' ''(...)'', their aggregate literal would be an aggregate literal, inside an aggregate literal ''(inside an aggregate literal)'' (...). Nested aggregate literals.
{{CodeSample
|code=<syntaxhighlight>
item[class, slot] basic_equipments = {
$class[Seal Clubber]: {
$slot[hat]: $item[seal-skull helmet],
$slot[weapon]: $item[seal-clubbing club],
$slot[pants]: $item[old sweatpants]
},
$class[Turtle Tamer]: {
$slot[hat]: $item[helmet turtle],
$slot[weapon]: $item[turtle totem],
$slot[pants]: $item[old sweatpants]
},
$class[Pastamancer]: {
$slot[hat]: $item[ravioli hat],
$slot[weapon]: $item[pasta spoon],
$slot[pants]: $item[old sweatpants]
},
$class[Sauceror]: {
$slot[hat]: $item[Hollandaise helmet],
$slot[weapon]: $item[saucepan],
$slot[pants]: $item[old sweatpants]
},
$class[Disco Bandit]: {
$slot[hat]: $item[disco mask],
$slot[weapon]: $item[disco ball],
$slot[pants]: $item[old sweatpants]
},
$class[Accordion Thief]: {
$slot[hat]: $item[mariachi hat],
$slot[weapon]: $item[stolen accordion],
$slot[pants]: $item[mariachi pants]
}
};
</syntaxhighlight>}}

==== Map-map assignments ====
If you use a map on the left side of an assignment, you set the whole map at once to the new value.

{{CodeSample
|code=<syntaxhighlight>
int [item] my_pricelist;
int [item] new_pricelist;

/* Some code that updates my_pricelist with new_pricelist */

my_pricelist = new_pricelist;

/* Now my_pricelist and new_pricelist point to the same aggregate;
changes to an element of one of them will be visible in the other */
</syntaxhighlight>}}

==== Slices ====
If you specify a map and a prefix of indices (of the correct type), you directly set one of the intermediate maps, a "slice".

{{CodeSample
|code=<syntaxhighlight>
float [string, int, string] my_map;
float [int, string] slice1;

/* Some code that fills my_map[ "slice1" ] with slice1 */
my_map[ "slice1" ] = slice1;
</syntaxhighlight>}}

=== References ===

The syntax for referencing an element (or slice) of a map:

<pre>
<aggregate name>[ <key expression>, ... ]
</pre>

All the key expressions will be evaluated at run time. If you specify all the keys the map expects, you fetch data of the type specified by the map. If you specify fewer keys than the map expects, you get an intermediate map, a "slice".

As an example:
{{
CodeSample|
code=
<syntaxhighlight>
boolean [string, string] props;
</syntaxhighlight>}}

might be used to hold "properties" associated with names.
{{
CodeSample|
code=
<syntaxhighlight>
props[ "dog", "mammal" ] = true;
props[ "dog", "pet" ] = true;
props[ "dog", "fun" ] = false;
props[ "turtle", "mammal" ] = false;
props[ "turtle", "pet" ] = true;
props[ "turtle", "fun" ] = false;
props[ "aardvark", "mammal" ] = true;
props[ "aardvark", "pet" ] = false;
props[ "aardvark", "fun" ] = true;
</syntaxhighlight>}}

references:

<pre>
props[ "dog", "mammal"] => true
boolean [string] animal = props[ "turtle" ];
animal[ "fun" ] => false
</pre>

=== Contains ===

You can test the presence of a key in a map using the "contains" operator:

<pre>
<aggregate reference expression> contains <key expression>
</pre>

Where <aggregate reference expression> must evaluate at run time to a map or slice, and must evaluate at run time to a key of the appropriate type. (Note that that is enforced at parse time; ASH can tell the datatype any expression will produce).

<pre>
props contains "dog" => true
props contains "elephant" => false
props[ "aardvark" ] contains "fun" => true
animal contains "pet" => true
animal contains "favorite food" => false
</pre>

Note that only the current slice's keys are evaluated. This means that:

<pre>
boolean [ boolean ] [ boolean ] [ boolean ] [ boolean ] [ boolean ] much_truthness;
much_truthness [ true ] [ true ] [ false ] [ true ] [ true ] = true;

return much_truthness [ true ] [ true ] contains true;
</pre>

yields:
<pre>
Returned: false
</pre>

=== Remove ===

You can remove a key-value association from a map using the "remove" unary operator:

<pre>
remove <aggregate reference>
</pre>

For clarification, an aggregate reference is "<map name>[ <index 1> ... <index n> ]" where <map name>[ <index 1> ... <index n-1> ] specifies the "slice" and <index n> specifies the "key". Which is just what you expect, if you fully specify the indices; for a single dimensional map, "map[10]" -> "map" is the slice and 10 is the key. The "remove" operator removes the "key" from the "slice". For example:

{{CodeSample|code=<syntaxhighlight>
string [int] map1;
map1[5] = "foo";
print( count( map1 ) + " " + map1 contains 5 + " " + map1[5] );
print( "remove: " + remove map1[5] );
print( count( map1 ) + " " + map1 contains 5 + " " + map1[5] );
print( "remove: " + remove map1[5] );
int [string, string] map2;
map2["me","you"] = 17;
print( count( map2["me"] ) + " " + map2["me"] contains "you" + " " + map2["me","you"] );
print( "remove: " + remove map2["me", "you"] );
print( count( map2["me"] ) + " " + map2["me"] contains "you" + " " + map2["me","you"] );
print( "remove: " + remove map2["me", "you"] );
print( count( map2 ) + " " + map2["me"] );
print( "remove: " + remove map2["me"] );
print( count( map2 ) + " " + map2["me"] );
</syntaxhighlight>}}

yields:

<pre>
1 true foo
remove: foo
0 false
remove:
1 true 17
remove: 17
0 false 0
remove: 0
1 aggregate int [string]
remove: aggregate int [string]
0 aggregate int [string]
</pre>

=== Clear ===

You can remove all <code>key => value</code> entries from a map using the {{f|clear}} function:

{{CodeSample|code=<syntaxhighlight>clear( <aggregate> );</syntaxhighlight>}}

=== Count ===

The {{f|count}} function returns the number of defined keys for the specified aggregate.

{{CodeSample|code=<syntaxhighlight>int size = count( <aggregate> );</syntaxhighlight>}}

=== Sort ===

From http://kolmafia.us/showthread.php?t=1738 and http://kolmafia.us/showthread.php?10729

The syntax is:
{{CodeSample|code=<syntaxhighlight>sort aggregate by keyExpr;</syntaxhighlight>}}

<code>aggregate</code> is a reference to the object to be sorted - arrays are probably the most useful things to sort, but any mapping type can be used. But please note that when you sort a map, you change the values that correspond to the index. To sort on a map, you would want to use a multidimensional maps, but note that you can only sort along a single dimension at a time when doing this. Simply put... "sort" is only useful in cases where your data exists entirely in the values of the map; the keys can have no meaning beyond simply being distinct.

The reference must not be enclosed in parentheses, as that would look like a call to a function named <code>sort()</code> - which is still perfectly valid, "sort" has not become a [[Reserved Words|reserved word]].

<code>keyExpr</code> is an arbitrary expression that defines how the items should be ordered. It is evaluated once for every entry in the aggregate, in a scope with two additional variables implicitly defined: '<code>index</code>' and '<code>value</code>', holding the details of that entry. The value of the <code>keyExpr</code> is used as the sort key; typically it would be an <code>int</code> or <code>string</code>, but can be any ASH type that can be compared via "<" and the other relational operators.

The most basic form of sorting would therefore be "<code>sort ... by value</code>", but many useful things can be done with the use of a more complex <code>keyExpr</code> - the only real restriction is that the expression should not modify the object you're sorting. For example, if you had an array of items, you could sort it "<code>by autosell_price(value)</code>". An array of weapon items could be sorted "<code>by -get_power(value)</code>" to put it in decreasing order of power. If the elements of your aggregate are records, you'd need to use something like "<code>by value.fieldName</code>", since the records themselves can't be meaningfully compared.

After the sort statement, the aggregate will have exactly the same sets of keys and values as before (even if the keys weren't consecutive), and the iteration order of the keys will be the same, but the values will likely be associated with different keys. The sort is stable - in other words, elements with sort keys that compare as equal will remain in the same order. This means that you can sort on multiple criteria by simply performing separate sorts for each of the criteria, in increasing order of significance.

To find out how many things you have, you might do:
{{CodeSample|code=<syntaxhighlight>
item [int] whatGot;
int ctr =0;

foreach it in get_inventory() {
whatGot[ctr] = it;
ctr+=1;
}

sort whatGot by item_amount(value);

foreach x, it in whatGot
print(item_amount(it) + ' of ' + it);
</syntaxhighlight>}}
Note that this use of an optional feature of foreach. The second variable in the foreach is the value of whatGot[x].

A few more examples of things you can do:
* "<code>by -value</code>" sorts integers in decreasing order (there's no similar trick for <code>string</code> values).
* "<code>by -index</code>" reverses the existing order of an array (or map with integer keys).
* "<code>by random(1000000)</code>" shuffles into a random order.
* "<code>by otherArray[index]</code>" uses values from a parallel array as the sort keys (you'd then need to do "<code>sort otherArray by value;</code>" if you wanted the two arrays to remain in sync).

===Iteration===
To iterate through a map, use the '''foreach''' operator. For instance, if you wanted to print out how many of each item you had, you could do something like the following:
{{CodeSample|code=<syntaxhighlight>
int[item] map = get_inventory();
foreach key in map {
print(key + " (" + map[key] + ")");
}
</syntaxhighlight>}}

Multidimensional maps are implemented as maps that map keys to maps. '''int[item][string]map''' is really a mapping of items to int[string] maps. Iteration, therefore, is as follows:
{{CodeSample|code=<syntaxhighlight>
int[item][string] map;
file_to_map("somefile.txt", map);
foreach k1 in map {
print(k1 + ": ");
foreach k2 in map[k1] {
print("\t" + k2 + ": " + map[k1][k2]);
}
}
</syntaxhighlight>}}

Two things to note: First, '''int[item][string]map''' is equivalent to '''int[item, string]map'''. This really comes down to author preference, although the second form is generally more common. Second, the two following foreach loops are equivalent:
{{CodeSample|code=<syntaxhighlight>
int[item][string] map;
foreach k1 in map {
foreach k2 in map[k1] {
func(map[k1][k2]);
}
}

foreach k1, k2 in map {
func(map[k1][k2]);
}
</syntaxhighlight>}}

Of course, the latter does not lend itself to, say, only printing the first key once, whereas the former can be used that way (see the preceding example).

===Implementation===
Maps in ASH are implemented internally as TreeMaps [http://download.oracle.com/javase/1.5.0/docs/api/java/util/TreeMap.html]. See below for some implications.

== Arrays ==
These look and behave like mappings of integers to values, where the keys only take values from 0 to n, but these are implemented as Java Arrays.

===Differences between arrays and maps===

'''item [12] array;'''

Can use keys 0 - 11. You get a runtime error if you use any other key. It always uses memory to hold 12 items, even if you only use a couple of them. But it's a constant time - O(1) - to access any element.

'''item [int] map;'''

Can use any int as a key. It has constant memory for the Java map, and additional memory for each element in the map, but is O( log n) to access any particular element.

If you are able to use (a fairly densely packed set of) integers as keys, your program will be faster and use (potentially) slightly more memory.

If you have a sparse set of integers, you can still use an array and get fast access, but you will waste a lot of memory.

If you can't use integers as keys or don't want to waste memory on a sparse array, you can have a slower but less memory consuming map.

[http://kolmafia.us/showthread.php?6425-Sorting-skills-by-mana-cost&p=48703&viewfull=1#post48703]

====Time considerations====
* Given '''if (a == item1 || a == item2 || a == item3)''' and '''if ($items[item1, item2, item3] contains a)''', which is faster?

This is going to depend on the number of items in the list, and which one happens to match; if 'a' is almost always item1, then the first form is likely to win on practical grounds, even though it's theoretically slower (O(n) vs. O(log n)).

The second form is a definite win assuming no such coincidences of the item chosen, a somewhat larger set of items, and that the code is executed more than once per run of the script. The first lookup in a plural constant actually builds an internal map that allows such queries to be efficiently done; this is deferred because typical use of a plural constant involves only iteration, not lookups.

There's always the "profile" command, if you really need to know which is more efficient in a given situation - although it's unlikely that either would have a noticeable effect on your script's performance.

[http://kolmafia.us/showthread.php?6425-Sorting-skills-by-mana-cost&p=48728&viewfull=1#post48728]

== Records ==

(Link to Veracity's post introducing the record [http://kolmafia.us/showthread.php?t=280])

Records are custom-made data types, that act like compartmentalized boxes [https://i.imgur.com/rgxLKRC.jpg].

They are "variable packages", that allow you to group together data of any type, including other records, in them.

Records have "models" (the custom data type of the record itself), and names representing them (though not all of them are creative, such as ''"the_black_one_that_I_bought_a_year_ago"'', or ''"the_one_that_is_over_there_by_the_door"'').

Each "compartment" (field) also has a name, as well as an expected data type. ''(Stop trying to put screws "there"; that's my god damn lunchbox, and this is "the spot in which you put the guacamole"!)''

Once a "box's model" (record's data type) is declared, it can be used (almost) anywhere that can use a built-in type name (as long as you don't leave the scope in which the record was declared), such as in functions and other records.

===Declarations===
The syntax for declaring a new record:
<pre>
record <"model" name> { <data type 1> <field name 1>; <data type 2> <field name 2>; ... }
</pre>

For example:
{{CodeSample
|code=<syntaxhighlight>
record human {
string name;
int date_of_birth;
location location_of_birth;
item [slot] clothes;
};
</syntaxhighlight>}}

This declared a new data '''''type''''', a ''mold'', a ''blueprint''... No variable was created here.

To actually ''create'' a variable that ''uses'' this "model", you would '''then''' do:
{{CodeSample
|code=<syntaxhighlight>
human that_guy;
human this_guy;
human that_other_guy;
</syntaxhighlight>}}
You now have 3 "human"s, each with a name, date of birth, location of birth, and clothes (though none of them has had those assigned, yet).

It is possible to declare a record and create a variable of that type at the same time. The following is equivalent to the two previous code samples combined:
{{CodeSample
|code=<syntaxhighlight>
record human {
string name;
int date_of_birth;
location location_of_birth;
item [slot] clothes;
} that_guy;

human this_guy;
human that_other_guy;
</syntaxhighlight>}}

===Accessing the fields===
Once a variable of a recorded data type was created, you may access its fields with <variable name>.<field name>:

{{CodeSample
|code=<syntaxhighlight>
that_guy.name = "Andrew";
that_guy.date_of_birth = 08212006;
that_guy.location_of_birth = $location[Noob Cave];

that_other_guy.name = "Bob";
that_other_guy.location_of_birth = $location[South of the Border];

if ( that_other_guy.clothes [ $slot[pants] ] == $item[none] )
print( "Put some pants on, " + that_other_guy.name + "!" );
</syntaxhighlight>}}

===Omitting the "model" name===
When declaring a record, supplying the "model" name (what goes between "record" and the left curly bracket) is not mandatory. If you don't, the record will be "anonymous".

An "anonymous" record is like a makeshift bindle; you made it on a whim, it's unique, it's yours, you couldn't replicate it even if you tried, and nobody else wants it.

If you omit data type's name, you'll definitely want to supply a variable name after the curly braces, or it will have been a pure waste of time:
{{CodeSample|code=<syntaxhighlight>
record {
int days_spent_travelling;
item [int] content;
} mah_bindle;

mah_bindle.content [0] = $item[ big rock ];
</syntaxhighlight>}}

===[[New]]===
[[New]] can be used to assign a whole record at once.

[[Category:Scripting]]

Data Structures

2020-08-18T21:47:23Z

Fredg1: /* Contains */

{{TOCright}}

KoLmafia supports complex data structures such as maps and records made from simple [[Data Types|data types]].

== Maps ==
If you are new to programming or find the information below confusing, you may want to read [[Map_Guide | A Noob's Guide to Maps]] first.

Most of this information was copied directly from ASH Maps Tutorial, by Veracity (http://kolmafia.sourceforge.net/advanced.html#maps)

A map is indexed by one data type (the key) and associates that key with another (or the same) data type (the value). The key can be any ASH simple data type: boolean, int, float, string, item, location, class, stat, skill, effect, familiar, slot, or monster. The value can be any ASH data type at all: a simple type, a record, or can be another map. This effectively allows multi-dimensional maps and. In fact, that's how the syntax we provide for multi-dimensional maps actually operate: maps of maps of maps ...

You can declare a map any time you can declare a variable: as a top level (global) variable, as a function parameter, or as a local variable in any scope.

You can fetch data from a map any time you can provide a data value: in an expression, as a function parameter, on the right side of an assignment statement, from a "return" statement, as so on. You can pass around entire maps, individual elements, or intermediate maps: "slices".

=== Declarations ===

The syntax for declaring the data type of a map:

<pre>
<data type> [ <key type>, ... ] <aggregate_name>
</pre>

For example:

{{CodeSample
|code=<syntaxhighlight>
string [item] map1;
float [class, string, int] another_map;
</syntaxhighlight>}}

=== Assignments ===

If you use a map on the left side of an assignment, you set the whole map at once to the new value.

{{CodeSample
|code=<syntaxhighlight>
int [item] my_pricelist;
int [item] new_pricelist;

/* Some code that updates my_pricelist with new_pricelist */

my_pricelist = new_pricelist;

/* Now my_pricelist and new_pricelist point to the same aggregate;
changes to an element of one of them will be visible in the other */
</syntaxhighlight>}}

You can initialize an entire aggregate with an ''aggregate literal''. For example:

{{CodeSample
|code=<syntaxhighlight>
int[item] my_pricelist = { $item[bum cheek]: 404,
$item[red button]: 100,
$item[red balloon]: 100000 };
</syntaxhighlight>}}

If you specify a map and a complete set of indices (of the correct types) on the left side of an assignment statement, you set a single element.

{{CodeSample
|code=<syntaxhighlight>
int [item] my_pricelist;
my_pricelist[ $item[ pail ] ] = 1000;
</syntaxhighlight>}}

If you specify a map and a prefix of indices (of the correct type), you directly set one of the intermediate maps, a "slice".

{{CodeSample
|code=<syntaxhighlight>
float [string, int, string] my_map;
float [int, string] slice1;

/* Some code that fills my_map[ "slice1" ] with slice1 */
my_map[ "slice1" ] = slice1;
</syntaxhighlight>}}

=== References ===

The syntax for referencing an element (or slice) of a map:

<pre>
<aggregate name>[ <key expression>, ... ]
</pre>

All the key expressions will be evaluated at run time. If you specify all the keys the map expects, you fetch data of the type specified by the map. If you specify fewer keys than the map expects, you get an intermediate map, a "slice".

As an example:
{{
CodeSample|
code=
<syntaxhighlight>
boolean [string, string] props;
</syntaxhighlight>}}

might be used to hold "properties" associated with names.
{{
CodeSample|
code=
<syntaxhighlight>
props[ "dog", "mammal" ] = true;
props[ "dog", "pet" ] = true;
props[ "dog", "fun" ] = false;
props[ "turtle", "mammal" ] = false;
props[ "turtle", "pet" ] = true;
props[ "turtle", "fun" ] = false;
props[ "aardvark", "mammal" ] = true;
props[ "aardvark", "pet" ] = false;
props[ "aardvark", "fun" ] = true;
</syntaxhighlight>}}

references:

<pre>
props[ "dog", "mammal"] => true
boolean [string] animal = props[ "turtle" ];
animal[ "fun" ] => false
</pre>

=== Contains ===

You can test the presence of a key in a map using the "contains" operator:

<pre>
<aggregate reference expression> contains <key expression>
</pre>

Where <aggregate reference expression> must evaluate at run time to a map or slice, and must evaluate at run time to a key of the appropriate type. (Note that that is enforced at parse time; ASH can tell the datatype any expression will produce).

<pre>
props contains "dog" => true
props contains "elephant" => false
props[ "aardvark" ] contains "fun" => true
animal contains "pet" => true
animal contains "favorite food" => false
</pre>

Note that only the current slice's keys are evaluated. This means that:

<pre>
boolean [ boolean ] [ boolean ] [ boolean ] [ boolean ] [ boolean ] much_truthness;
much_truthness [ true ] [ true ] [ false ] [ true ] [ true ] = true;

return much_truthness [ true ] [ true ] contains true;
</pre>

yields:
<pre>
Returned: false
</pre>

=== Remove ===

You can remove a key-value association from a map using the "remove" unary operator:

<pre>
remove <aggregate reference>
</pre>

For clarification, an aggregate reference is "<map name>[ <index 1> ... <index n> ]" where <map name>[ <index 1> ... <index n-1> ] specifies the "slice" and <index n> specifies the "key". Which is just what you expect, if you fully specify the indices; for a single dimensional map, "map[10]" -> "map" is the slice and 10 is the key. The "remove" operator removes the "key" from the "slice". For example:

{{CodeSample|code=<syntaxhighlight>
string [int] map1;
map1[5] = "foo";
print( count( map1 ) + " " + map1 contains 5 + " " + map1[5] );
print( "remove: " + remove map1[5] );
print( count( map1 ) + " " + map1 contains 5 + " " + map1[5] );
print( "remove: " + remove map1[5] );
int [string, string] map2;
map2["me","you"] = 17;
print( count( map2["me"] ) + " " + map2["me"] contains "you" + " " + map2["me","you"] );
print( "remove: " + remove map2["me", "you"] );
print( count( map2["me"] ) + " " + map2["me"] contains "you" + " " + map2["me","you"] );
print( "remove: " + remove map2["me", "you"] );
print( count( map2 ) + " " + map2["me"] );
print( "remove: " + remove map2["me"] );
print( count( map2 ) + " " + map2["me"] );
</syntaxhighlight>}}

yields:

<pre>
1 true foo
remove: foo
0 false
remove:
1 true 17
remove: 17
0 false 0
remove: 0
1 aggregate int [string]
remove: aggregate int [string]
0 aggregate int [string]
</pre>

=== Clear ===

You can remove all <code>key => value</code> entries from a map using the {{f|clear}} function:

{{CodeSample|code=<syntaxhighlight>clear( <aggregate> );</syntaxhighlight>}}

=== Count ===

The {{f|count}} function returns the number of defined keys for the specified aggregate.

{{CodeSample|code=<syntaxhighlight>int size = count( <aggregate> );</syntaxhighlight>}}

=== Sort ===

From http://kolmafia.us/showthread.php?t=1738 and http://kolmafia.us/showthread.php?10729

The syntax is:
{{CodeSample|code=<syntaxhighlight>sort aggregate by keyExpr;</syntaxhighlight>}}

<code>aggregate</code> is a reference to the object to be sorted - arrays are probably the most useful things to sort, but any mapping type can be used. But please note that when you sort a map, you change the values that correspond to the index. To sort on a map, you would want to use a multidimensional maps, but note that you can only sort along a single dimension at a time when doing this. Simply put... "sort" is only useful in cases where your data exists entirely in the values of the map; the keys can have no meaning beyond simply being distinct.

The reference must not be enclosed in parentheses, as that would look like a call to a function named <code>sort()</code> - which is still perfectly valid, "sort" has not become a [[Reserved Words|reserved word]].

<code>keyExpr</code> is an arbitrary expression that defines how the items should be ordered. It is evaluated once for every entry in the aggregate, in a scope with two additional variables implicitly defined: '<code>index</code>' and '<code>value</code>', holding the details of that entry. The value of the <code>keyExpr</code> is used as the sort key; typically it would be an <code>int</code> or <code>string</code>, but can be any ASH type that can be compared via "<" and the other relational operators.

The most basic form of sorting would therefore be "<code>sort ... by value</code>", but many useful things can be done with the use of a more complex <code>keyExpr</code> - the only real restriction is that the expression should not modify the object you're sorting. For example, if you had an array of items, you could sort it "<code>by autosell_price(value)</code>". An array of weapon items could be sorted "<code>by -get_power(value)</code>" to put it in decreasing order of power. If the elements of your aggregate are records, you'd need to use something like "<code>by value.fieldName</code>", since the records themselves can't be meaningfully compared.

After the sort statement, the aggregate will have exactly the same sets of keys and values as before (even if the keys weren't consecutive), and the iteration order of the keys will be the same, but the values will likely be associated with different keys. The sort is stable - in other words, elements with sort keys that compare as equal will remain in the same order. This means that you can sort on multiple criteria by simply performing separate sorts for each of the criteria, in increasing order of significance.

To find out how many things you have, you might do:
{{CodeSample|code=<syntaxhighlight>
item [int] whatGot;
int ctr =0;

foreach it in get_inventory() {
whatGot[ctr] = it;
ctr+=1;
}

sort whatGot by item_amount(value);

foreach x, it in whatGot
print(item_amount(it) + ' of ' + it);
</syntaxhighlight>}}
Note that this use of an optional feature of foreach. The second variable in the foreach is the value of whatGot[x].

A few more examples of things you can do:
* "<code>by -value</code>" sorts integers in decreasing order (there's no similar trick for <code>string</code> values).
* "<code>by -index</code>" reverses the existing order of an array (or map with integer keys).
* "<code>by random(1000000)</code>" shuffles into a random order.
* "<code>by otherArray[index]</code>" uses values from a parallel array as the sort keys (you'd then need to do "<code>sort otherArray by value;</code>" if you wanted the two arrays to remain in sync).

===Iteration===
To iterate through a map, use the '''foreach''' operator. For instance, if you wanted to print out how many of each item you had, you could do something like the following:
{{CodeSample|code=<syntaxhighlight>
int[item] map = get_inventory();
foreach key in map {
print(key + " (" + map[key] + ")");
}
</syntaxhighlight>}}

Multidimensional maps are implemented as maps that map keys to maps. '''int[item][string]map''' is really a mapping of items to int[string] maps. Iteration, therefore, is as follows:
{{CodeSample|code=<syntaxhighlight>
int[item][string] map;
file_to_map("somefile.txt", map);
foreach k1 in map {
print(k1 + ": ");
foreach k2 in map[k1] {
print("\t" + k2 + ": " + map[k1][k2]);
}
}
</syntaxhighlight>}}

Two things to note: First, '''int[item][string]map''' is equivalent to '''int[item, string]map'''. This really comes down to author preference, although the second form is generally more common. Second, the two following foreach loops are equivalent:
{{CodeSample|code=<syntaxhighlight>
int[item][string] map;
foreach k1 in map {
foreach k2 in map[k1] {
func(map[k1][k2]);
}
}

foreach k1, k2 in map {
func(map[k1][k2]);
}
</syntaxhighlight>}}

Of course, the latter does not lend itself to, say, only printing the first key once, whereas the former can be used that way (see the preceding example).

===Implementation===
Maps in ASH are implemented internally as TreeMaps [http://download.oracle.com/javase/1.5.0/docs/api/java/util/TreeMap.html]. See below for some implications.

== Arrays ==
These look and behave like mappings of integers to values, where the keys only take values from 0 to n, but these are implemented as Java Arrays.

===Differences between arrays and maps===

'''item [12] array;'''

Can use keys 0 - 11. You get a runtime error if you use any other key. It always uses memory to hold 12 items, even if you only use a couple of them. But it's a constant time - O(1) - to access any element.

'''item [int] map;'''

Can use any int as a key. It has constant memory for the Java map, and additional memory for each element in the map, but is O( log n) to access any particular element.

If you are able to use (a fairly densely packed set of) integers as keys, your program will be faster and use (potentially) slightly more memory.

If you have a sparse set of integers, you can still use an array and get fast access, but you will waste a lot of memory.

If you can't use integers as keys or don't want to waste memory on a sparse array, you can have a slower but less memory consuming map.

[http://kolmafia.us/showthread.php?6425-Sorting-skills-by-mana-cost&p=48703&viewfull=1#post48703]

====Time considerations====
* Given '''if (a == item1 || a == item2 || a == item3)''' and '''if ($items[item1, item2, item3] contains a)''', which is faster?

This is going to depend on the number of items in the list, and which one happens to match; if 'a' is almost always item1, then the first form is likely to win on practical grounds, even though it's theoretically slower (O(n) vs. O(log n)).

The second form is a definite win assuming no such coincidences of the item chosen, a somewhat larger set of items, and that the code is executed more than once per run of the script. The first lookup in a plural constant actually builds an internal map that allows such queries to be efficiently done; this is deferred because typical use of a plural constant involves only iteration, not lookups.

There's always the "profile" command, if you really need to know which is more efficient in a given situation - although it's unlikely that either would have a noticeable effect on your script's performance.

[http://kolmafia.us/showthread.php?6425-Sorting-skills-by-mana-cost&p=48728&viewfull=1#post48728]

== Records ==

(Link to Veracity's post introducing the record [http://kolmafia.us/showthread.php?t=280])

Records are custom-made data types, that act like compartmentalized boxes [https://i.imgur.com/rgxLKRC.jpg].

They are "variable packages", that allow you to group together data of any type, including other records, in them.

Records have "models" (the custom data type of the record itself), and names representing them (though not all of them are creative, such as ''"the_black_one_that_I_bought_a_year_ago"'', or ''"the_one_that_is_over_there_by_the_door"'').

Each "compartment" (field) also has a name, as well as an expected data type. ''(Stop trying to put screws "there"; that's my god damn lunchbox, and this is "the spot in which you put the guacamole"!)''

Once a "box's model" (record's data type) is declared, it can be used (almost) anywhere that can use a built-in type name (as long as you don't leave the scope in which the record was declared), such as in functions and other records.

===Declarations===
The syntax for declaring a new record:
<pre>
record <"model" name> { <data type 1> <field name 1>; <data type 2> <field name 2>; ... }
</pre>

For example:
{{CodeSample
|code=<syntaxhighlight>
record human {
string name;
int date_of_birth;
location location_of_birth;
item [slot] clothes;
};
</syntaxhighlight>}}

This declared a new data '''''type''''', a ''mold'', a ''blueprint''... No variable was created here.

To actually ''create'' a variable that ''uses'' this "model", you would '''then''' do:
{{CodeSample
|code=<syntaxhighlight>
human that_guy;
human this_guy;
human that_other_guy;
</syntaxhighlight>}}
You now have 3 "human"s, each with a name, date of birth, location of birth, and clothes (though none of them has had those assigned, yet).

It is possible to declare a record and create a variable of that type at the same time. The following is equivalent to the two previous code samples combined:
{{CodeSample
|code=<syntaxhighlight>
record human {
string name;
int date_of_birth;
location location_of_birth;
item [slot] clothes;
} that_guy;

human this_guy;
human that_other_guy;
</syntaxhighlight>}}

===Accessing the fields===
Once a variable of a recorded data type was created, you may access its fields with <variable name>.<field name>:

{{CodeSample
|code=<syntaxhighlight>
that_guy.name = "Andrew";
that_guy.date_of_birth = 08212006;
that_guy.location_of_birth = $location[Noob Cave];

that_other_guy.name = "Bob";
that_other_guy.location_of_birth = $location[South of the Border];

if ( that_other_guy.clothes [ $slot[pants] ] == $item[none] )
print( "Put some pants on, " + that_other_guy.name + "!" );
</syntaxhighlight>}}

===Omitting the "model" name===
When declaring a record, supplying the "model" name (what goes between "record" and the left curly bracket) is not mandatory. If you don't, the record will be "anonymous".

An "anonymous" record is like a makeshift bindle; you made it on a whim, it's unique, it's yours, you couldn't replicate it even if you tried, and nobody else wants it.

If you omit data type's name, you'll definitely want to supply a variable name after the curly braces, or it will have been a pure waste of time:
{{CodeSample|code=<syntaxhighlight>
record {
int days_spent_travelling;
item [int] content;
} mah_bindle;

mah_bindle.content [0] = $item[ big rock ];
</syntaxhighlight>}}

===[[New]]===
[[New]] can be used to assign a whole record at once.

[[Category:Scripting]]

Relay Override Scripting

2020-08-14T22:35:38Z

Fredg1: :|

{{TOCright}}
A relay script is a script that creates or modifies a web page in the relay browser. It is only in the relay browser that the effects of these scripts can be seen. There are two different kinds of relay override scripts. The first is simply known as a Relay Script. The second is an User Interface script.

==Relay Script==
Basic relay scripts are used to change the appearance of a KoL page. You will find many examples of relay scripts that you may download from the [http://kolmafia.us/forumdisplay.php?16-Relay-Override-Scripts KoLmafia Forums] to your /relay directory.

===Writing a Relay Script===
For a simple Relay Script, there are several basic rules:
#The name of the script must be the same as the page it is overriding, except with an ash extension instead of a php extension. For users who have enabled relay override scripts, mafia will automatically call xyz.ash every time the relay browser attempts to visit xyz.php.
#Unless the script will display entirely new content, it should first load the unmodified page from KoL using the command [[visit_url|visit_url()]] with no parameters.
#Then the contents of the page can be modified with [[replace_string|replace_string()]] or other string manipulation functions.
#Finally, the modified page is written with the [[write|write()]] command.

===Whichplace, Whichshop and Whichstore Overrides===
For overrides to place.php, shop.php and store.php it is possible to override based on the whichplace, whichshop and whichstore parameters. This is quite helpful so that you can choose to override only specific places and shops without needing to make an override for all of them.

An example is that to override the plains, you'll note that the URL is <code> place.php?whichplace=plains </code> so you could override all place.php pages with a place.ash override, or you could choose to override only the plains with a script named place.plains.ash.

===Example of Relay Override===
Here is an example of a relay script. Assuming it is named shop.shore.ash, it will modify "The Shore, Inc." Shop at <code> shop.php?whichshop=shore.php </code> to reveal items that are needed for the level 6 tower monster.
<div style="margin-bottom: 1em; border: dashed 1px green; padding: 1em; margin:0px 20px;"><syntaxhighlight>
// This script will only work if it is named shop.shore.ash
buffer telescope(buffer page) {

void dynamite() {
if(available_amount($item[stick of dynamite]) < 1) page.replace_string("<b>dude ranch souvenir crate</b>",
"<font color=\"green\"><b>dude ranch souvenir crate<br />(stick of dynamite needed)</b></font>");
}

void orchid() {
if(available_amount($item[tropical orchid]) < 1 && available_amount($item[packet of orchid seeds]) < 1) page.replace_string("<b>tropical island souvenir crate</b>",
"<font color=\"green\"><b>tropical island souvenir crate<br />(tropical orchid needed)</b></font>");
}

void fence() {
if(available_amount($item[barbed-wire fence]) < 1) page.replace_string("<b>ski resort souvenir crate</b>",
"<font color=\"green\"><b>ski resort souvenir crate<br />(barbed-wire fence needed)</b></font>");
}

if(!can_interact() && my_path() != "Bugbear Invasion") {
if(my_path() == "Bees Hate You") {
orchid();
} else if(get_property("telescopeUpgrades") == "7" && !in_bad_moon()) {
switch(get_property("telescope7")) {
case "see a wooden beam":
dynamite(); break;
case "see a formidable stinger":
orchid(); break;
case "see a pair of horns":
fence(); break;
}
} else {
dynamite();
orchid();
fence();
}
}

// If dinghy plans are needed, you will always need to buy them! Otherwise it is time to look into that UV-resistant compass
if(get_property("lastIslandUnlock").to_int() < my_ascensions() && page.contains_text("dinghy plans"))
page.replace_string("<b>dinghy plans</b>", "<font color=\"green\"><b>dinghy plans</b></font>");
else if(available_amount($item[UV-resistant compass]) + available_amount($item[ornate dowsing rod]) == 0)
page.replace_string("UV-resistant compass", "<font color=\"green\"><b>UV-resistant compass</b></font>");

return page;
}

void main() {
visit_url().telescope().ShopWTF().write();
}
</syntaxhighlight></div>
<br />

==User Interface Script==

There are special kinds of relay scripts; scripts with user interfaces. As with a regular relay override script, they go in the "relay" directory. However, they don't override other pages; their entire content is created from scratch. These scripts can be accessed under the relay drop-down in the bottom-right of the top pane. Their names must start with "relay_" in order for them to show up there.

This can provide a pretty interface and automate tasks, but relay scripts aren't really suitable for long, ongoing processes such as autoadventuring, since nothing appears in the browser until the script exits. Also, writing them requires a rather different mindset than the sequential execution of a normal script: if the relay script presents options for the user, they are actually read by an entirely separate invocation of the script than the one that displayed the options. The areas in which relay scripts will be the most useful are user-friendly configuration of other scripts, and presentation of options for the user to carry out in the relay browser themselves since the script can simply link to any in-game activity.

===Writing an Interface Script===
For writing interface scripts, several features were added to KoLmafia.
* ASH predefined string constant __FILE__, which is the filename of the current script. This allows relay scripts to link or submit a form to themselves, even if the user has renamed them.
* ASH function [[form_fields|form_fields()]], which returns a string[string] map with all the name/value pairs from the relay request being handled.
* ASH string functions [[entity_encode|entity_encode()]] and [[entity_decode|entity_decode()]], for converting text that might contain special characters such as ampersands and angle brackets so that it can safely be displayed in HTML, and retrieving such text from form fields.

Additionally, there are some excellent tools for writing form elements in interface scripts on the [http://kolmafia.us/showthread.php?3842-Form-of...HTML KoLmafia Forum]. That script is a toolbox of essential functions for any advanced interface script so make good use of it.

===Example of User Interface===
Here is an example of a User Interface script. This must be saved in /relay with a name starting with relay, such as '''relay_breakables.ash''' to appear in the relay drop-down in KoL's top menu. This was originally presented by Jason Harper [http://kolmafia.us/showthread.php?3769-Breakable-equipment-fine-tuning here] and makes an excellent example.
<div style="margin-bottom: 1em; font-size: 12px; border: dashed 1px green; padding: 1em; margin:0px 20px;"><syntaxhighlight>
// The following constant can be edited to add more breakable items.
// However, please note that adding items here does no good at all
// unless KoLmafia has been updated to recognize the specific breakage
// messages of those items.
boolean[item] breakable = $items[
antique helmet, antique spear, antique shield, antique greaves,
cyber-mattock, cheap studded belt,
sugar chapeau, sugar shank, sugar shield, sugar shillelagh,
sugar shirt, sugar shotgun, sugar shorts];

void write_option(string label, string value, string current) {
write("<option value='");
write(value);
write("'");
if (value == current)
write(" selected");
write(">");
write(entity_encode(label));
writeln("</option>");
}

void write_select(string label, string pref, boolean addDefault, string[string] fields) {
if (fields contains pref)
set_property(pref, fields[pref]);

string current = get_property(pref);
write("<tr><td align=right>");
write(label);
write("</td><td><select name='");
write(pref);
writeln("'>");

if (addDefault)
write_option("Use default", "", current);
write_option("Abort on breakage", "1", current);
write_option("Equip previous item", "2", current);
write_option("Re-equip from inventory (if available), or abort", "3", current);
write_option("Re-equip from inventory, or equip previous item", "4", current);
write_option("Acquire new item & re-equip", "5", current);
writeln("</select></td></tr>");
}

void main() {
write("<html><body><form method=POST action='");
write(__FILE__);
writeln("'>");
write("Breakable equipment fine tuning v1.0, by jasonharper@pobox.com");
writeln(" (in-game: <a href='sendmessage.php?toid=363053'>Seventh</a>)");
write("<p>");
write("This script lets you override the default behavior when equipment breaks in combat,");
write(" on an item-by-item basis. The default setting (found in the Item section of Choice Advs)");
writeln(" is duplicated here for your convenience.");
writeln("<table border=0>");
string[string] fields = form_fields();
write_select("Default", "breakableHandling", false, fields);
foreach itm in breakable
write_select(to_string(itm), "breakableHandling" + to_int(itm), true, fields);
writeln("</table>");
writeln("<input type=submit value='Save changes'>");
writeln("</form></body></html>");
}
</syntaxhighlight></div>

===Advance Techniques for Interface Scripting===
Adding CSS Styles:
*To have a fancier Relay Script, one can add CSS styles to certain elements. Example of this can be found Bale’s OCD Manager Relay script.

Tools:
*[http://www.quackit.com/ Quackit] has a lot of basic info on HTML/CSS/etc. It also has a decent [http://www.quackit.com/html/online-html-editor/full/ WYSIWYG editor] for basic styling and layouts.
*[http://jsfiddle.net/ JSFiddle] allows you to enter HTML, CSS, and java script and run it all to see what it creates. It also has a handy “TidyUP” feature which will auto-indent HTML and will highlight HTML tags in red if they are improper which is great for debugging.
*[http://www.css-generators.com/#Markup CSS Generator] Offers quick CSS for buttons/paragraphs/tables/etc for more advance styling options.
*[http://www.csstablegenerator.com/ CSS Table Generator] is an excellent resource for CSS Tables designs.
*[http://www.regexplanet.com/advanced/java/index.html RegexPlanet] is a handy tool to convert CSS/HTML into a Java string. After writing/generating HTML/CSS for your relay script, it can be a pain to “convert” it all by hand into text that will work well within the .ash Relay Script. Instead, you can copy/paste it all into Regexplannet as a Regular Expression. After clicking Test, it will throw up some error (obviously), but will still convert it all into a Java string, which is what you want. Copy paste “as a Java string” into your relay script, after a page.append, and you should be good to go. You can then break it up for easier reading, but it is not necessary.

===Example of Using CSS in a User Interface Script===
Note: Instead of using the function write, the example will use a buffer called page which everything will be appended too.
<br>
Note 2: Example also shows why it is a good practice to use \" instead of single quotes when typing HTML. Using \” will prevent values containing a single quote from messing up.
<div style="margin-bottom: 1em; font-size: 12px; border: dashed 1px green; padding: 1em; margin:0px 20px;"><syntaxhighlight>
////////// Beginning of form functions based strongly on jasonharper's htmlform.ash from http://kolmafia.us/showthread.php?3842
string[string] fields; // shared result from form_fields()
boolean success; // form successfully submitted
buffer page;

boolean test_button(string name) {
if(name == "") return false;
return success && fields contains name;
}

//This Example shows what it is a bad idea to use single quotes instead of full quotes for values
boolean write_button_Example(string name, string label) {
page.append("<input type=\"submit\" name=\""+name+"\" value='"+label+"'/>");
return test_button(name);
}

//Jason's Button re-written to use page.append instead of write
boolean write_button(string name, string label) {
page.append("<input type=\"submit\" name=\""+name+"\" value=\""+label+"\"/>");
return test_button(name);
}

//Added a class to the button, designating a class will allow all buttons of that class to be changed by that class's CSS
boolean write_button2(string name, string label, string css_class) {
page.append("<input type=\"submit\" name=\""+name+"\" class=\""+css_class+"\" value=\""+label+"\"/>");
return test_button(name);
}
boolean write_button2(string name, string label) {return write_button2(name, label, "");}
////////// End of jasonharper's htmlform.ash

void styles() { //Function that contains all CSS
page.append("<style type='text/css'>"+
//Shiny button CSS, turned into a convenient Java String. Note: For the purpose of Wiki formatting, it was broken up into segments. However, it could have been left as one long string.
".shiny{ cursor:pointer; border-width:4px; border-style:solid; border-color:#000000; -webkit-border-radius: 18px; -moz-border-radius: 18px; border-radius: 18px; text-align:center;"+
"height:40px; padding-top:undefinedpx; padding-bottom:undefinedpx; font-size:15px; font-family:arial; color:#ffffff;"+
"background:#2d10bc; display:inline-block; }.shiny:hover{ background:#e85b4c; }"+
"</style>");
}

/*CSS For Shiny Button, before it was put into regexplanet as a regular expression, was generated using the "CSS Generator" listed above.
.shiny{
cursor:pointer;
border-width:4px;
border-style:solid;
border-color:#000000;
-webkit-border-radius: 18px;
-moz-border-radius: 18px;
border-radius: 18px;
text-align:center;
width:100px; //Delete the width so it isn't fixed
height:40px;
padding-top:undefinedpx;
padding-bottom:undefinedpx;
font-size:15px;
font-family:arial;
color:#ffffff;
background:#2d10bc;
display:inline-block;
}.shiny:hover{
background:#e85b4c;
}
*/

void main() {
fields = form_fields();
success = count(fields) > 0;

page.append("<html><head>"); // write_page()
styles();
page.append("</head><body><form name='relayform' method='POST' action=''>");
write_button_Example("test", "John's Button"); //Will generate a button with just "John" as it uses single quotes in the label instead of \"
write_button("test2", "John's Button");
write_button2("test3", "John's Super Button", "shiny");
write_button2("test4", "John's not so super button");
write_button2("test5", "John's super awesome shiny button again", "shiny");
page.append("</form></body></html>"); // finish_page()
writeln(page);
}
</syntaxhighlight></div>

Additional CSS Styling Ideas and Jason's functions using page.append can be found in [http://kolmafia.us/showthread.php?1818-OCD-Inventory-control Bale's OCD Relay Script] and [http://kolmafia.us/showthread.php?17230-EoD-SC-Ascension-Checklist-Handler EoD's Ascension Checklist Relay Script].

[[Category:Scripting]]

Item

2020-08-14T04:45:31Z

Fredg1: /* Proxy Record Fields */ proxy record: name

{{DISPLAYTITLE:item}}

{{TOCright}}

This datatype represents any item in all of KoL. Note that unlike most special datatypes,
item references can make use of the item ID number.
{{CodeSample|
description=For example, you could assign the item plexiglass pants as follows:|
code=
<syntaxhighlight>
item it = $item[ 1234 ];
</syntaxhighlight>}}
The full range, besides $item[ none ], is too much to list and keep up with here.
Please see the Wiki {{kolwiki|Items}} page for more item information.

==Related Functions==

{{Flink|void|add_item_condition|int|item}}
{{Flink|boolean|autosell|int|item}}
{{Flink|int|autosell_price|item}}
{{Flink|int|available_amount|item}}
{{Flink|boolean|boolean_modifier|item|string}}
{{Flink|boolean|buy|{{opt|coinmaster}}|int|item}}
{{Flink|int|buy|int|item|int}}
{{Flink|int|buy_price|coinmaster|item}}
{{Flink|boolean|buy_using_storage|int|item}}
{{Flink|int|buy_using_storage|int|item|int}}
{{Flink|boolean|buys_item|coinmaster|item}}
{{Flink|boolean|can_equip|item}}
{{Flink|boolean|chew|int|item}}
{{Flink|class|class_modifier|item|string}}
{{Flink|int|closet_amount|item}}
{{Flink|boolean|craft|string|int|item|item}}
{{Flink|string|craft_type|item}}
{{Flink|int|creatable_amount|item}}
{{Flink|int|creatable_turns|{{opt|item}}|{{opt|int}}|{{opt|boolean}}}}
{{Flink|boolean|create|int|item}}
{{Flink|item|daily_special}}
{{Flink|int|display_amount|item}}
{{Flink|boolean|drink|int|item}}
{{Flink|boolean|eat|int|item}}
{{Flink|boolean|eatsilent|int|item}}
{{Flink|effect|effect_modifier|item|string}}
{{Flink|boolean|equip|{{opt|slot}}|item}}
{{Flink|int|equipped_amount|item}}
{{Flink|item|equipped_item|slot}}
{{Flink|int [item]|extract_items|string}}
{{Flink|item|familiar_equipment|familiar}}
{{Flink|item|familiar_equipped_equipment|familiar}}
{{Flink|int [item]|get_campground}}
{{Flink|int [item]|get_chateau}}
{{Flink|int [item]|get_clan_lounge}}
{{Flink|item|get_dwelling}}
{{Flink|int [item]|get_ingredients|item}}
{{Flink|int [item]|get_inventory}}
{{Flink|int|get_power|item}}
{{Flink|int [item]|get_related|item|string}}
{{Flink|int [item]|get_shop}}
{{Flink|boolean|have_equipped|item}}
{{Flink|boolean|hermit|int|item}}
{{Flink|float|historical_age|item}}
{{Flink|int|historical_price|item}}
{{Flink|boolean|is_coinmaster_item|item}}
{{Flink|boolean|is_discardable|item}}
{{Flink|boolean|is_displayable|item}}
{{Flink|boolean|is_giftable|item}}
{{Flink|boolean|is_goal|item}}
{{Flink|boolean|is_npc_item|item}}
{{Flink|boolean|is_tradeable|item}}
{{Flink|boolean|is_trendy|item/familiar/skill/string}}
{{Flink|boolean|is_unrestricted|item/familiar/skill/string}}
{{Flink|int|item_amount|item}}
{{Flink|float|item_drop_modifier}}
{{Flink|int [item]|item_drops|{{opt|monster}}}}
{{Flink|record [int]|item_drops_array|{{opt|monster}}}}
{{Flink|string|item_type|item}}
{{Flink|string|last_item_message}}
{{Flink|int|mall_price|item}}
{{Flink|item|minstrel_instrument}}
{{Flink|int|npc_price|item}}
{{Flink|float|numeric_modifier|item|string}}
{{Flink|float|numeric_modifier|familiar|string|int|item}}
{{Flink|item [int]|outfit_pieces|string}}
{{Flink|boolean|overdrink|int|item}}
{{Flink|boolean|put_closet|int|{{opt|item}}}}
{{Flink|boolean|put_display|int|item}}
{{Flink|boolean|put_shop|int|int|{{opt|int}}|item}}
{{Flink|boolean|put_stash|int|item}}
{{Flink|void|remove_item_condition|int|item}}
{{Flink|boolean|retrieve_item|int|item}}
{{Flink|boolean|sell|coinmaster|int|item}}
{{Flink|int|sell_price|coinmaster|item}}
{{Flink|boolean|sells_item|coinmaster|item}}
{{Flink|int|shop_amount|item}}
{{Flink|int|shop_price|item}}
{{Flink|int|stash_amount|item}}
{{Flink|int|storage_amount|item}}
{{Flink|boolean|take_closet|int|{{opt|item}}}}
{{Flink|boolean|take_display|int|item}}
{{Flink|boolean|take_shop|{{opt|int}}|item}}
{{Flink|boolean|take_stash|int|item}}
{{Flink|boolean|take_storage|int|item}}
{{Flink|buffer|throw_item|item}}
{{Flink|buffer|throw_items|item|item}}
{{Flink|item|to_item|strict_string}}
{{Flink|item|to_item|int}}
{{Flink|item|to_item|string|int}}
{{Flink|string|to_plural|item}}
{{Flink|slot|to_slot|item}}
{{Flink|boolean|use|int|item}}
{{Flink|int|weapon_hands|item}}
{{Flink|stat|weapon_type|item}}

==Proxy Record Fields==

Here are the proxy record fields for items. Proxy records are discussed in more detail [[Proxy Records|here]].

{| cellpadding="3" cellspacing="0" border="1px" class="sortable"
|- | style="background-color: #F2F2F2"
|-
! Field
! Data type
! Default value
! ASH Accessor Function / Notes
|-
| name
| string
| ""
|
|-
| plural
| string
| ""
|
|-
| descid
| string
| ""
|
|-
| image
| string
| ""
|
|-
| smallimage
| string
| ""
|
|-
| levelreq
| int
| 0
|
|-
| quality
| string
| ""
|
|-
| adventures
| string
| ""
|
|-
| muscle
| string
| ""
|
|-
| mysticality
| string
| ""
|
|-
| moxie
| string
| ""
|
|-
| fullness
| int
| 0
|
|-
| inebriety
| int
| 0
|
|-
| spleen
| int
| 0
|
|-
| minhp
| int
| 0
|
|-
| maxhp
| int
| 0
|
|-
| minmp
| int
| 0
|
|-
| maxmp
| int
| 0
|
|-
| dailyusesleft
| int
| 0
|
|-
| notes
| string
| ""
|
|-
| quest
| boolean
| false
|
|-
| gift
| boolean
| false
|
|-
| tradeable
| boolean
| false
|
|-
| discardable
| boolean
| false
|
|-
| combat
| boolean
| false
|
|-
| combat_reusable
| boolean
| false
|
|-
| usable
| boolean
| false
|
|-
| reusable
| boolean
| false
|
|-
| multi
| boolean
| false
|
|-
| fancy
| boolean
| false
|
|-
| candy
| boolean
| false
|
|-
| seller
| coinmaster
| none
|
|-
| buyer
| coinmaster
| none
|
|-
| name_length
| int
| 0
|
|}

[[Category:Scripting]] [[Category:Data Types]]

Control Structures

2020-08-08T20:36:42Z

Fredg1: /* for */ no floats

{{TOCright}}
==Conditional==
===if===
{{
CodeSample|
code=
<syntaxhighlight>
if ( boolean )
{
// any statements here
// are only going to be executed
// if the boolean returns true
}
</syntaxhighlight>}}
{{
CodeSample|
description=Single-statement conditionals may omit the curly braces.|
code=
<syntaxhighlight>
if ( boolean )
// curly braces aren't required if only one statement follows the conditional
</syntaxhighlight>}}
===else===
{{
CodeSample|
code=
<syntaxhighlight>
if ( boolean )
{
// statements if true
}
else
{
// the statements here
// are only going to be executed
// if the boolean returns false
}
</syntaxhighlight>}}

===else if===
{{
CodeSample|
code=
<syntaxhighlight>
if ( boolean 1 )
{
// statements if true
}
else if ( boolean 2 )
{
// the statements here
// are only going to be executed
// if boolean 1 returns false
// & boolean 2 returns true
}
</syntaxhighlight>}}

===switch===
{{
CodeSample|
code=
<syntaxhighlight>
switch ( variable )
{
case value:
// statements if variable == value
// more such statements
break;
//repeat above for as many values as desired
default:
// statements executed if
// none of the cases were true
}
</syntaxhighlight>}}

{{
CodeSample|
description="variable" and every "value" can be expressions as complex as wanted, as long as their end result is always of the same datatype. NO silent conversion is done, so the following '''will generate an error''':|
code=
<syntaxhighlight>
switch ( 10 + 1 )
{
case "1" + "1":
// Whatever you want; it doesn't matter, as 11 can't be compared with "11"
break;
}
</syntaxhighlight>}}

{{
CodeSample|
description=Putting a ''break'' in each case isn't mandatory. If no ''break'' is placed on the path taken, once the last line of the case is reached, execution simply goes on, and will execute (will "fall-through") the content of the next case/default.|
code=
<syntaxhighlight>
switch ( int guess_my_age )
{
case 24:
case 26:
print("You were SO close!");
break;
case 25:
print("You got it!");
break;
default:
print("Nope");
}
</syntaxhighlight>}}

{{
CodeSample|
description=The default value of a switch structure's parameter is true. This means that if switch has no parameter, it is the same as submitting '''switch (true) [...]'''. Each case is then evaluated as a boolean expression, like a string of if-then statements.|
code=
<syntaxhighlight>
switch
{
case boolean expression:
// if the expression is true, this statement is executed
// more such statements
break;
//repeat above for as many conditionals as desired
default:
// statements executed if
// none of the cases were true
}
</syntaxhighlight>}}

The default doesn't need to be the last statement (which is useful when using the aforementioned fall-through mechanic). If the default is placed early (e.g. as the first statement), it will NOT have priority over the other cases; if the value submitted to the switch matches one of the cases, execution will jump to it, even if placed after the default. <br>
Putting a ''break'' at the end of the switch is generally considered good practice, but achieves nothing.

==Unconditional==
===try / finally===
{{
CodeSample|
description=Block1 is executed as normal, and then block2 is executed regardless of whether
block1 finished normally, generated an error, or encountered a 'return',
'break', or 'continue' statement.|
code=
<syntaxhighlight>
try
{
// block1
}
finally
{
// block2
}
</syntaxhighlight>}}

===static===
{{
CodeSample|
code=
<syntaxhighlight>
static
{
// any statements here
// are only going to be executed once at the
// first time the script executes in a session.
}
</syntaxhighlight>}}
{{
CodeSample|
description=Single-statement static declarations may omit the curly braces.|
code=
<syntaxhighlight>
static
// curly braces aren't required if only one statement follows the static keyword.
</syntaxhighlight>}}
Keep in mind that when using imports, a static call will only apply to the script that imports it.
*If foo.ash has a static variable, but bar.ash imports foo.ash, KoLmafia will keep separate values for both foo.ash and bar.ash.
*If bar.ash is changed, its static variable is reset, but not foo.ash's.
*If foo.ash is changed, both scripts' variables are reset.

==Loops==
===while===
{{
CodeSample|
code=
<syntaxhighlight>
while ( boolean )
{
// as with an if statement
// this area is only entered
// if the boolean tests true
// once all this is done
// it goes back to the begining
// and will keep executing
// as long as the boolean remains true
}
</syntaxhighlight>}}

===repeat until===

This is similar to the [http://en.wikipedia.org/wiki/Do_while_loop do...while loop], but only ends the loop when the <code>boolean</code> expression evaluates to <code>true</code>.

{{
CodeSample|
code=
<syntaxhighlight>
repeat
{
// this is the same
// as the while loop above
// with one exception:
// all of this code will
// execute at least once
// as the test doesn't occur
// until the very end
} until ( boolean );
</syntaxhighlight>}}

===for===
{{
CodeSample|
code=
<syntaxhighlight>
for x from a to b by c {
//do stuff
}
</syntaxhighlight>}}
Above is the general case. You don't need to specify whether it's going up or down - although doing so by using upto or downto does allow a runtime check to make sure you didn't screw up.

If you don't specify "c", it defaults to incrementing/decrementing by 1. The first iteration is at a and the last is at b (that is to say, it goes from a to b, inclusive).

a, b and c are automatically converted to integers. You can't use floats here.

===foreach===
{{
CodeSample|
code=
<syntaxhighlight>
foreach key in aggregate {
//do stuff
}
</syntaxhighlight>}}
Assigns each key in the supplied map or slice to "<code>key</code>" and iterates through the map. Due to how maps are handled, <code>foreach</code> is guaranteed to iterate through the map in sorted order.

{{
CodeSample|
description=For example:|
code=
<syntaxhighlight>
boolean [int][string] map;
map[15]["test"] = true;
foreach int_index in map {
print(int_index); //this will print '15' once, since there is only one valid value for this index
foreach string_index in map[int_index] //this iterates over the "slice" of the map where 1 is fixed as the index
{
print(string_index); //This will print "test" once, since there is only one valid value for this index
print(map[int_index][string_index]); //this will print "true"
}
}
</syntaxhighlight>|
moreinfo=
So the output is
<pre>
15
test
true
</pre>}}
{{
CodeSample|
description=For a multidimensional map, instead of nesting <code>foreach</code> statements two iterators can be used inline.|
code=
<syntaxhighlight>
foreach x, y in map {
//do stuff
}
</syntaxhighlight>}}
{{
CodeSample|
description=This is identical to:|
code=
<syntaxhighlight>
foreach x in map {
foreach y in map[x] {
//do stuff
}
}
</syntaxhighlight>}}

{{CodeSample|
description=You can also directly specify the value stored in the map by specifying one more variable than the number of keys in the map:|
code=
<syntaxhighlight>
//string [string, int, item] my_map;
foreach s, i, m, value in my_map {
print( s + ", " + i + ", " + m + " => " + value );
}
</syntaxhighlight>
}}

See the page for [[Data Structures]] for more information on aggregates.

==Continuation & Exiting==
Like many languages with looping structures, ASH supports the break and continue statements. All looping structures (for, while, repeat until, and foreach) support these statements.

===break===
Breaks out of the smallest enclosing loop. In a switch statement, breaks out of the switch statement. Execution resumes at the first statement after the end of the loop/switch statement.

===continue===
Continues on to the next iteration of the loop (skipping any statements in this iteration that occur after the continue statement). In a switch statement, continue is allowed if the switch is inside a loop, and acts as any other continue.

===return===
Exits the function and returns the value following the return statement, if specified. Note that the value's datatype must match that of the function itself (void functions can only use return by itself).
If in a switch statement, don't place a break after a return!

===exit===
Exits the script. Using return when in main() achieves the same effect. Note that while this will end the current script, it will not stop automation.

[[Category:Scripting]]

Data Structures

2020-08-07T00:31:10Z

Fredg1: /* Records */

{{TOCright}}

KoLmafia supports complex data structures such as maps and records made from simple [[Data Types|data types]].

== Maps ==
If you are new to programming or find the information below confusing, you may want to read [[Map_Guide | A Noob's Guide to Maps]] first.

Most of this information was copied directly from ASH Maps Tutorial, by Veracity (http://kolmafia.sourceforge.net/advanced.html#maps)

A map is indexed by one data type (the key) and associates that key with another (or the same) data type (the value). The key can be any ASH simple data type: boolean, int, float, string, item, location, class, stat, skill, effect, familiar, slot, or monster. The value can be any ASH data type at all: a simple type, a record, or can be another map. This effectively allows multi-dimensional maps and. In fact, that's how the syntax we provide for multi-dimensional maps actually operate: maps of maps of maps ...

You can declare a map any time you can declare a variable: as a top level (global) variable, as a function parameter, or as a local variable in any scope.

You can fetch data from a map any time you can provide a data value: in an expression, as a function parameter, on the right side of an assignment statement, from a "return" statement, as so on. You can pass around entire maps, individual elements, or intermediate maps: "slices".

=== Declarations ===

The syntax for declaring the data type of a map:

<pre>
<data type> [ <key type>, ... ] <aggregate_name>
</pre>

For example:

{{CodeSample
|code=<syntaxhighlight>
string [item] map1;
float [class, string, int] another_map;
</syntaxhighlight>}}

=== Assignments ===

If you use a map on the left side of an assignment, you set the whole map at once to the new value.

{{CodeSample
|code=<syntaxhighlight>
int [item] my_pricelist;
int [item] new_pricelist;

/* Some code that updates my_pricelist with new_pricelist */

my_pricelist = new_pricelist;

/* Now my_pricelist and new_pricelist point to the same aggregate;
changes to an element of one of them will be visible in the other */
</syntaxhighlight>}}

You can initialize an entire aggregate with an ''aggregate literal''. For example:

{{CodeSample
|code=<syntaxhighlight>
int[item] my_pricelist = { $item[bum cheek]: 404,
$item[red button]: 100,
$item[red balloon]: 100000 };
</syntaxhighlight>}}

If you specify a map and a complete set of indices (of the correct types) on the left side of an assignment statement, you set a single element.

{{CodeSample
|code=<syntaxhighlight>
int [item] my_pricelist;
my_pricelist[ $item[ pail ] ] = 1000;
</syntaxhighlight>}}

If you specify a map and a prefix of indices (of the correct type), you directly set one of the intermediate maps, a "slice".

{{CodeSample
|code=<syntaxhighlight>
float [string, int, string] my_map;
float [int, string] slice1;

/* Some code that fills my_map[ "slice1" ] with slice1 */
my_map[ "slice1" ] = slice1;
</syntaxhighlight>}}

=== References ===

The syntax for referencing an element (or slice) of a map:

<pre>
<aggregate name>[ <key expression>, ... ]
</pre>

All the key expressions will be evaluated at run time. If you specify all the keys the map expects, you fetch data of the type specified by the map. If you specify fewer keys than the map expects, you get an intermediate map, a "slice".

As an example:
{{
CodeSample|
code=
<syntaxhighlight>
boolean [string, string] props;
</syntaxhighlight>}}

might be used to hold "properties" associated with names.
{{
CodeSample|
code=
<syntaxhighlight>
props[ "dog", "mammal" ] = true;
props[ "dog", "pet" ] = true;
props[ "dog", "fun" ] = false;
props[ "turtle", "mammal" ] = false;
props[ "turtle", "pet" ] = true;
props[ "turtle", "fun" ] = false;
props[ "aardvark", "mammal" ] = true;
props[ "aardvark", "pet" ] = false;
props[ "aardvark", "fun" ] = true;
</syntaxhighlight>}}

references:

<pre>
props[ "dog", "mammal"] => true
boolean [string] animal = props[ "turtle" ];
animal[ "fun" ] => false
</pre>

=== Contains ===

You can test the presence of a key in a map using the "contains" operator:

<pre>
<aggregate reference expression> contains <key expression>
</pre>

Where <aggregate reference expression> must evaluate at run time to a map or slice, and must evaluate at run time to a key of the appropriate type. (Note that that is enforced at parse time; ASH can tell the datatype any expression will produce).

<pre>
props contains "dog" => true
props contains "elephant" => false
props[ "aardvark" ] contains "fun" => true
animal contains "pet" => true
animal contains "favorite food" => false
</pre>

=== Remove ===

You can remove a key-value association from a map using the "remove" unary operator:

<pre>
remove <aggregate reference>
</pre>

For clarification, an aggregate reference is "<map name>[ <index 1> ... <index n> ]" where <map name>[ <index 1> ... <index n-1> ] specifies the "slice" and <index n> specifies the "key". Which is just what you expect, if you fully specify the indices; for a single dimensional map, "map[10]" -> "map" is the slice and 10 is the key. The "remove" operator removes the "key" from the "slice". For example:

{{CodeSample|code=<syntaxhighlight>
string [int] map1;
map1[5] = "foo";
print( count( map1 ) + " " + map1 contains 5 + " " + map1[5] );
print( "remove: " + remove map1[5] );
print( count( map1 ) + " " + map1 contains 5 + " " + map1[5] );
print( "remove: " + remove map1[5] );
int [string, string] map2;
map2["me","you"] = 17;
print( count( map2["me"] ) + " " + map2["me"] contains "you" + " " + map2["me","you"] );
print( "remove: " + remove map2["me", "you"] );
print( count( map2["me"] ) + " " + map2["me"] contains "you" + " " + map2["me","you"] );
print( "remove: " + remove map2["me", "you"] );
print( count( map2 ) + " " + map2["me"] );
print( "remove: " + remove map2["me"] );
print( count( map2 ) + " " + map2["me"] );
</syntaxhighlight>}}

yields:

<pre>
1 true foo
remove: foo
0 false
remove:
1 true 17
remove: 17
0 false 0
remove: 0
1 aggregate int [string]
remove: aggregate int [string]
0 aggregate int [string]
</pre>

=== Clear ===

You can remove all <code>key => value</code> entries from a map using the {{f|clear}} function:

{{CodeSample|code=<syntaxhighlight>clear( <aggregate> );</syntaxhighlight>}}

=== Count ===

The {{f|count}} function returns the number of defined keys for the specified aggregate.

{{CodeSample|code=<syntaxhighlight>int size = count( <aggregate> );</syntaxhighlight>}}

=== Sort ===

From http://kolmafia.us/showthread.php?t=1738 and http://kolmafia.us/showthread.php?10729

The syntax is:
{{CodeSample|code=<syntaxhighlight>sort aggregate by keyExpr;</syntaxhighlight>}}

<code>aggregate</code> is a reference to the object to be sorted - arrays are probably the most useful things to sort, but any mapping type can be used. But please note that when you sort a map, you change the values that correspond to the index. To sort on a map, you would want to use a multidimensional maps, but note that you can only sort along a single dimension at a time when doing this. Simply put... "sort" is only useful in cases where your data exists entirely in the values of the map; the keys can have no meaning beyond simply being distinct.

The reference must not be enclosed in parentheses, as that would look like a call to a function named <code>sort()</code> - which is still perfectly valid, "sort" has not become a [[Reserved Words|reserved word]].

<code>keyExpr</code> is an arbitrary expression that defines how the items should be ordered. It is evaluated once for every entry in the aggregate, in a scope with two additional variables implicitly defined: '<code>index</code>' and '<code>value</code>', holding the details of that entry. The value of the <code>keyExpr</code> is used as the sort key; typically it would be an <code>int</code> or <code>string</code>, but can be any ASH type that can be compared via "<" and the other relational operators.

The most basic form of sorting would therefore be "<code>sort ... by value</code>", but many useful things can be done with the use of a more complex <code>keyExpr</code> - the only real restriction is that the expression should not modify the object you're sorting. For example, if you had an array of items, you could sort it "<code>by autosell_price(value)</code>". An array of weapon items could be sorted "<code>by -get_power(value)</code>" to put it in decreasing order of power. If the elements of your aggregate are records, you'd need to use something like "<code>by value.fieldName</code>", since the records themselves can't be meaningfully compared.

After the sort statement, the aggregate will have exactly the same sets of keys and values as before (even if the keys weren't consecutive), and the iteration order of the keys will be the same, but the values will likely be associated with different keys. The sort is stable - in other words, elements with sort keys that compare as equal will remain in the same order. This means that you can sort on multiple criteria by simply performing separate sorts for each of the criteria, in increasing order of significance.

To find out how many things you have, you might do:
{{CodeSample|code=<syntaxhighlight>
item [int] whatGot;
int ctr =0;

foreach it in get_inventory() {
whatGot[ctr] = it;
ctr+=1;
}

sort whatGot by item_amount(value);

foreach x, it in whatGot
print(item_amount(it) + ' of ' + it);
</syntaxhighlight>}}
Note that this use of an optional feature of foreach. The second variable in the foreach is the value of whatGot[x].

A few more examples of things you can do:
* "<code>by -value</code>" sorts integers in decreasing order (there's no similar trick for <code>string</code> values).
* "<code>by -index</code>" reverses the existing order of an array (or map with integer keys).
* "<code>by random(1000000)</code>" shuffles into a random order.
* "<code>by otherArray[index]</code>" uses values from a parallel array as the sort keys (you'd then need to do "<code>sort otherArray by value;</code>" if you wanted the two arrays to remain in sync).

===Iteration===
To iterate through a map, use the '''foreach''' operator. For instance, if you wanted to print out how many of each item you had, you could do something like the following:
{{CodeSample|code=<syntaxhighlight>
int[item] map = get_inventory();
foreach key in map {
print(key + " (" + map[key] + ")");
}
</syntaxhighlight>}}

Multidimensional maps are implemented as maps that map keys to maps. '''int[item][string]map''' is really a mapping of items to int[string] maps. Iteration, therefore, is as follows:
{{CodeSample|code=<syntaxhighlight>
int[item][string] map;
file_to_map("somefile.txt", map);
foreach k1 in map {
print(k1 + ": ");
foreach k2 in map[k1] {
print("\t" + k2 + ": " + map[k1][k2]);
}
}
</syntaxhighlight>}}

Two things to note: First, '''int[item][string]map''' is equivalent to '''int[item, string]map'''. This really comes down to author preference, although the second form is generally more common. Second, the two following foreach loops are equivalent:
{{CodeSample|code=<syntaxhighlight>
int[item][string] map;
foreach k1 in map {
foreach k2 in map[k1] {
func(map[k1][k2]);
}
}

foreach k1, k2 in map {
func(map[k1][k2]);
}
</syntaxhighlight>}}

Of course, the latter does not lend itself to, say, only printing the first key once, whereas the former can be used that way (see the preceding example).

===Implementation===
Maps in ASH are implemented internally as TreeMaps [http://download.oracle.com/javase/1.5.0/docs/api/java/util/TreeMap.html]. See below for some implications.

== Arrays ==
These look and behave like mappings of integers to values, where the keys only take values from 0 to n, but these are implemented as Java Arrays.

===Differences between arrays and maps===

'''item [12] array;'''

Can use keys 0 - 11. You get a runtime error if you use any other key. It always uses memory to hold 12 items, even if you only use a couple of them. But it's a constant time - O(1) - to access any element.

'''item [int] map;'''

Can use any int as a key. It has constant memory for the Java map, and additional memory for each element in the map, but is O( log n) to access any particular element.

If you are able to use (a fairly densely packed set of) integers as keys, your program will be faster and use (potentially) slightly more memory.

If you have a sparse set of integers, you can still use an array and get fast access, but you will waste a lot of memory.

If you can't use integers as keys or don't want to waste memory on a sparse array, you can have a slower but less memory consuming map.

[http://kolmafia.us/showthread.php?6425-Sorting-skills-by-mana-cost&p=48703&viewfull=1#post48703]

====Time considerations====
* Given '''if (a == item1 || a == item2 || a == item3)''' and '''if ($items[item1, item2, item3] contains a)''', which is faster?

This is going to depend on the number of items in the list, and which one happens to match; if 'a' is almost always item1, then the first form is likely to win on practical grounds, even though it's theoretically slower (O(n) vs. O(log n)).

The second form is a definite win assuming no such coincidences of the item chosen, a somewhat larger set of items, and that the code is executed more than once per run of the script. The first lookup in a plural constant actually builds an internal map that allows such queries to be efficiently done; this is deferred because typical use of a plural constant involves only iteration, not lookups.

There's always the "profile" command, if you really need to know which is more efficient in a given situation - although it's unlikely that either would have a noticeable effect on your script's performance.

[http://kolmafia.us/showthread.php?6425-Sorting-skills-by-mana-cost&p=48728&viewfull=1#post48728]

== Records ==

(Link to Veracity's post introducing the record [http://kolmafia.us/showthread.php?t=280])

Records are custom-made data types, that act like compartmentalized boxes [https://i.imgur.com/rgxLKRC.jpg].

They are "variable packages", that allow you to group together data of any type, including other records, in them.

Records have "models" (the custom data type of the record itself), and names representing them (though not all of them are creative, such as ''"the_black_one_that_I_bought_a_year_ago"'', or ''"the_one_that_is_over_there_by_the_door"'').

Each "compartment" (field) also has a name, as well as an expected data type. ''(Stop trying to put screws "there"; that's my god damn lunchbox, and this is "the spot in which you put the guacamole"!)''

Once a "box's model" (record's data type) is declared, it can be used (almost) anywhere that can use a built-in type name (as long as you don't leave the scope in which the record was declared), such as in functions and other records.

===Declarations===
The syntax for declaring a new record:
<pre>
record <"model" name> { <data type 1> <field name 1>; <data type 2> <field name 2>; ... }
</pre>

For example:
{{CodeSample
|code=<syntaxhighlight>
record human {
string name;
int date_of_birth;
location location_of_birth;
item [slot] clothes;
};
</syntaxhighlight>}}

This declared a new data '''''type''''', a ''mold'', a ''blueprint''... No variable was created here.

To actually ''create'' a variable that ''uses'' this "model", you would '''then''' do:
{{CodeSample
|code=<syntaxhighlight>
human that_guy;
human this_guy;
human that_other_guy;
</syntaxhighlight>}}
You now have 3 "human"s, each with a name, date of birth, location of birth, and clothes (though none of them has had those assigned, yet).

It is possible to declare a record and create a variable of that type at the same time. The following is equivalent to the two previous code samples combined:
{{CodeSample
|code=<syntaxhighlight>
record human {
string name;
int date_of_birth;
location location_of_birth;
item [slot] clothes;
} that_guy;

human this_guy;
human that_other_guy;
</syntaxhighlight>}}

===Accessing the fields===
Once a variable of a recorded data type was created, you may access its fields with <variable name>.<field name>:

{{CodeSample
|code=<syntaxhighlight>
that_guy.name = "Andrew";
that_guy.date_of_birth = 08212006;
that_guy.location_of_birth = $location[Noob Cave];

that_other_guy.name = "Bob";
that_other_guy.location_of_birth = $location[South of the Border];

if ( that_other_guy.clothes [ $slot[pants] ] == $item[none] )
print( "Put some pants on, " + that_other_guy.name + "!" );
</syntaxhighlight>}}

===Omitting the "model" name===
When declaring a record, supplying the "model" name (what goes between "record" and the left curly bracket) is not mandatory. If you don't, the record will be "anonymous".

An "anonymous" record is like a makeshift bindle; you made it on a whim, it's unique, it's yours, you couldn't replicate it even if you tried, and nobody else wants it.

If you omit data type's name, you'll definitely want to supply a variable name after the curly braces, or it will have been a pure waste of time:
{{CodeSample|code=<syntaxhighlight>
record {
int days_spent_travelling;
item [int] content;
} mah_bindle;

mah_bindle.content [0] = $item[ big rock ];
</syntaxhighlight>}}

===[[New]]===
[[New]] can be used to assign a whole record at once.

[[Category:Scripting]]

Equipment

2020-07-31T21:37:30Z

Fredg1: /* Equipment Commands */ equipped_amount()

{{TOCright}}
==Equipment Commands==
{{Flink|boolean|equip|{{opt|slot}}|item|desc=Equips the specified item and reports success.}}
{{Flink|item|equipped_item|slot|desc=Returns the item equipped in the specified slot.}}
{{Flink|boolean|have_equipped|item|desc=Reports if the specified item is currently equipped by your character.}}
{{Flink|int|equipped_amount|item|desc=Returns the amount of a given item currently equipped on your character.}}
{{Flink|boolean|can_equip|item|desc=Tells if you meet the requirements for equipping the given item (regardless of its availability).}}
{{Flink|int|weapon_hands|item|desc=Reports how many weapon-hand slots are required for a given item (0 - 2). Off-hand items return 0.}}
{{Flink|stat|weapon_type|item|desc=Returns the equip requirement stat for the specified item. If it is not a weapon, this function returns $stat[none].}}
{{Flink|boolean|have_familiar|familiar|desc=Reports on whether you have the specified familiar either in your Terrarium or equipped.}}
{{Flink|boolean|use_familiar|familiar|desc=Attempts to make the specified familiar your currently used one and reports success.}}
{{Flink|item|familiar_equipment|familiar|desc=Reports the most commonly associated familiar equipment for the specified familiar.}}
{{Flink|item|familiar_equipped_equipment|familiar|desc=Returns the item currently equipped on the specified familiar (or $item[none] if you don't have that familiar).}}
{{Flink|boolean|enthrone_familiar|familiar|desc=Enthrones the specified familiar.}}
{{Flink|familiar|my_enthroned_familiar|desc=Returns the familiar currently enthroned.}}
{{Flink|boolean|bjornify_familiar|familiar|desc=Bjornifies the specified familiar.}}
{{Flink|familiar|my_bjorned_familiar|desc=Returns the familiar currently in the Buddy Bjorn.}}
{{Flink|boolean|maximize|string|boolean}}
{{Flink|boolean|maximize|string|int|int|boolean|desc=Checks for and optionally equips the optimal gear for any given parameters.}}

==Outfit Commands==
{{Flink|boolean|have_outfit|string|desc=Reports on whether or not you're currently capable of equipping the specified (in-game or custom) outfit, based on your stats & inventory availability of all outfit pieces.}}
{{Flink|boolean|outfit|string|desc=Attempts to wear the specified outfit and reports success.}}
{{Flink|item [int]|outfit_pieces|string|desc=Returns an array of the items which compose an outfit.}}
{{Flink|boolean|is_wearing_outfit|string|desc=Reports on whether or not you're wearing the specified (in-game or custom) outfit.}}
{{Flink|string [int]|get_outfits|desc=This function returns a list of all KoL outfits that the character currently owns and can wear.}}
{{Flink|string [int]|get_custom_outfits|desc=This function returns a list of all currently defined custom outfits.}}

[[Category:Scripting]]

Control Structures

2020-07-29T23:04:41Z

Fredg1: /* switch */

{{TOCright}}
==Conditional==
===if===
{{
CodeSample|
code=
<syntaxhighlight>
if ( boolean )
{
// any statements here
// are only going to be executed
// if the boolean returns true
}
</syntaxhighlight>}}
{{
CodeSample|
description=Single-statement conditionals may omit the curly braces.|
code=
<syntaxhighlight>
if ( boolean )
// curly braces aren't required if only one statement follows the conditional
</syntaxhighlight>}}
===else===
{{
CodeSample|
code=
<syntaxhighlight>
if ( boolean )
{
// statements if true
}
else
{
// the statements here
// are only going to be executed
// if the boolean returns false
}
</syntaxhighlight>}}

===else if===
{{
CodeSample|
code=
<syntaxhighlight>
if ( boolean 1 )
{
// statements if true
}
else if ( boolean 2 )
{
// the statements here
// are only going to be executed
// if boolean 1 returns false
// & boolean 2 returns true
}
</syntaxhighlight>}}

===switch===
{{
CodeSample|
code=
<syntaxhighlight>
switch ( variable )
{
case value:
// statements if variable == value
// more such statements
break;
//repeat above for as many values as desired
default:
// statements executed if
// none of the cases were true
}
</syntaxhighlight>}}

{{
CodeSample|
description="variable" and every "value" can be expressions as complex as wanted, as long as their end result is always of the same datatype. NO silent conversion is done, so the following '''will generate an error''':|
code=
<syntaxhighlight>
switch ( 10 + 1 )
{
case "1" + "1":
// Whatever you want; it doesn't matter, as 11 can't be compared with "11"
break;
}
</syntaxhighlight>}}

{{
CodeSample|
description=Putting a ''break'' in each case isn't mandatory. If no ''break'' is placed on the path taken, once the last line of the case is reached, execution simply goes on, and will execute (will "fall-through") the content of the next case/default.|
code=
<syntaxhighlight>
switch ( int guess_my_age )
{
case 24:
case 26:
print("You were SO close!");
break;
case 25:
print("You got it!");
break;
default:
print("Nope");
}
</syntaxhighlight>}}

{{
CodeSample|
description=The default value of a switch structure's parameter is true. This means that if switch has no parameter, it is the same as submitting '''switch (true) [...]'''. Each case is then evaluated as a boolean expression, like a string of if-then statements.|
code=
<syntaxhighlight>
switch
{
case boolean expression:
// if the expression is true, this statement is executed
// more such statements
break;
//repeat above for as many conditionals as desired
default:
// statements executed if
// none of the cases were true
}
</syntaxhighlight>}}

The default doesn't need to be the last statement (which is useful when using the aforementioned fall-through mechanic). If the default is placed early (e.g. as the first statement), it will NOT have priority over the other cases; if the value submitted to the switch matches one of the cases, execution will jump to it, even if placed after the default. <br>
Putting a ''break'' at the end of the switch is generally considered good practice, but achieves nothing.

==Unconditional==
===try / finally===
{{
CodeSample|
description=Block1 is executed as normal, and then block2 is executed regardless of whether
block1 finished normally, generated an error, or encountered a 'return',
'break', or 'continue' statement.|
code=
<syntaxhighlight>
try
{
// block1
}
finally
{
// block2
}
</syntaxhighlight>}}

===static===
{{
CodeSample|
code=
<syntaxhighlight>
static
{
// any statements here
// are only going to be executed once at the
// first time the script executes in a session.
}
</syntaxhighlight>}}
{{
CodeSample|
description=Single-statement static declarations may omit the curly braces.|
code=
<syntaxhighlight>
static
// curly braces aren't required if only one statement follows the static keyword.
</syntaxhighlight>}}
Keep in mind that when using imports, a static call will only apply to the script that imports it.
*If foo.ash has a static variable, but bar.ash imports foo.ash, KoLmafia will keep separate values for both foo.ash and bar.ash.
*If bar.ash is changed, its static variable is reset, but not foo.ash's.
*If foo.ash is changed, both scripts' variables are reset.

==Loops==
===while===
{{
CodeSample|
code=
<syntaxhighlight>
while ( boolean )
{
// as with an if statement
// this area is only entered
// if the boolean tests true
// once all this is done
// it goes back to the begining
// and will keep executing
// as long as the boolean remains true
}
</syntaxhighlight>}}

===repeat until===

This is similar to the [http://en.wikipedia.org/wiki/Do_while_loop do...while loop], but only ends the loop when the <code>boolean</code> expression evaluates to <code>true</code>.

{{
CodeSample|
code=
<syntaxhighlight>
repeat
{
// this is the same
// as the while loop above
// with one exception:
// all of this code will
// execute at least once
// as the test doesn't occur
// until the very end
} until ( boolean );
</syntaxhighlight>}}

===for===
{{
CodeSample|
code=
<syntaxhighlight>
for x from a to b by c {
//do stuff
}
</syntaxhighlight>}}
Above is the general case. You don't need to specify whether it's going up or down - although doing so by using upto or downto does allow a runtime check to make sure you didn't screw up.

If you don't specify "c", it defaults to incrementing/decrementing by 1. The first iteration is at a and the last is at b (that is to say, it goes from a to b, inclusive).

===foreach===
{{
CodeSample|
code=
<syntaxhighlight>
foreach key in aggregate {
//do stuff
}
</syntaxhighlight>}}
Assigns each key in the supplied map or slice to "<code>key</code>" and iterates through the map. Due to how maps are handled, <code>foreach</code> is guaranteed to iterate through the map in sorted order.

{{
CodeSample|
description=For example:|
code=
<syntaxhighlight>
boolean [int][string] map;
map[15]["test"] = true;
foreach int_index in map {
print(int_index); //this will print '15' once, since there is only one valid value for this index
foreach string_index in map[int_index] //this iterates over the "slice" of the map where 1 is fixed as the index
{
print(string_index); //This will print "test" once, since there is only one valid value for this index
print(map[int_index][string_index]); //this will print "true"
}
}
</syntaxhighlight>|
moreinfo=
So the output is
<pre>
15
test
true
</pre>}}
{{
CodeSample|
description=For a multidimensional map, instead of nesting <code>foreach</code> statements two iterators can be used inline.|
code=
<syntaxhighlight>
foreach x, y in map {
//do stuff
}
</syntaxhighlight>}}
{{
CodeSample|
description=This is identical to:|
code=
<syntaxhighlight>
foreach x in map {
foreach y in map[x] {
//do stuff
}
}
</syntaxhighlight>}}

{{CodeSample|
description=You can also directly specify the value stored in the map by specifying one more variable than the number of keys in the map:|
code=
<syntaxhighlight>
//string [string, int, item] my_map;
foreach s, i, m, value in my_map {
print( s + ", " + i + ", " + m + " => " + value );
}
</syntaxhighlight>
}}

See the page for [[Data Structures]] for more information on aggregates.

==Continuation & Exiting==
Like many languages with looping structures, ASH supports the break and continue statements. All looping structures (for, while, repeat until, and foreach) support these statements.

===break===
Breaks out of the smallest enclosing loop. In a switch statement, breaks out of the switch statement. Execution resumes at the first statement after the end of the loop/switch statement.

===continue===
Continues on to the next iteration of the loop (skipping any statements in this iteration that occur after the continue statement). In a switch statement, continue is allowed if the switch is inside a loop, and acts as any other continue.

===return===
Exits the function and returns the value following the return statement, if specified. Note that the value's datatype must match that of the function itself (void functions can only use return by itself).
If in a switch statement, don't place a break after a return!

===exit===
Exits the script. Using return when in main() achieves the same effect. Note that while this will end the current script, it will not stop automation.

[[Category:Scripting]]

Get campground

2020-07-22T04:45:29Z

Fredg1: lists the telescope

{{
#vardefine:name|get_campground}}{{
#vardefine:return_type|int [item]}}{{
#vardefine:aggregate|yes}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
}}|

function_description=Returns a map of your campground items as integers, keyed by item names.
<ul>
<li> Most values will be 1 to represent the item exists; some can be as high as 9, such as pretty bouquets and fences.</li>
<li> Not all items will be included; Hippy Stone, Colossal Closet, Quest Log, Trophy Case, Terrarium, and Mystical Bookshelf are ignored.</li>
<li> Your dwelling itself is processed separately, using {{f|get_dwelling}}</li>
<li> Furnishings for your dwelling (some "Tasteful" gifts, Really Good Feng Shui, etc.) will be listed on their own in the result.</li>
</ul>|

code1={{CodeSample|
title=Code Sample|
description=The following will save a text file in your data directory with your campground information.|
code=
<syntaxhighlight>
int [item] mystuff;
mystuff = get_campground();
map_to_file(mystuff , "campy.txt");
</syntaxhighlight>}}|

see_also={{SeeAlso|get_dwelling|get_clan_lounge|map_to_file}}|
}}

[[Category:Item Management]]

Boolean modifier

2020-07-01T21:20:15Z

Fredg1:

{{
#vardefine:name|boolean_modifier}}{{
#vardefine:return_type|boolean}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|str}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|item|it}}|
parameter2={{Param|string|str}}|
p1desc={{pspan|it}} is the (optional) item in question|
p2desc={{pspan|str}} is the modifier name|
}}|

function_description=Accesses fields of your current modifiers for all of your current equipment and effects. This is the same mechanism that lets mafia decide whether you can adventure underwater, or how many songs you can keep in your head. <br /><br />
For a list of fields that this function takes, see [[Modifiers#Boolean_Modifiers|Modifiers]].|

code1={{CodeSample|
title=Simple Examples|
description=Tells you if you can adventure underwater or not.|
code=
<syntaxhighlight>
if(!(boolean_modifier("Adventure Underwater"))||!(boolean_modifier("Underwater Familiar"))) {
print("You can't adventure underwater.", "red");
print("Either you won't be able to breathe, or your familiar won't.","red");
exit;
}
print("You can adventure underwater.");
</syntaxhighlight>}}
{{CodeSample|
description=Informs the player of how many accordion thief songs he can have active at one time.|
code=
<syntaxhighlight>
boolean four_songs = boolean_modifier("four songs");
# plexiglass pendant and/or brimstone beret grant 4 songs total.
boolean extra_song = boolean_modifier("additional song");
# La Hebilla del Cinturón de Lopez adds one song
int max_songs = 3 + to_int(four_songs) + to_int(extra_song);
print("You can currently hold "+ max_songs +" songs in your head at a time.");
</syntaxhighlight>}}

{{SeeAlso|effect_modifier|numeric_modifier|string_modifier}}|
}}

[[Category:Modifier Functions]]

Effect modifier

2020-07-01T21:19:58Z

Fredg1:

{{
#vardefine:name|effect_modifier}}{{
#vardefine:return_type|effect}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|check_me}}|
parameter2={{Param|string|modifier_name}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|item|check_me}}|
parameter2={{Param|string|modifier_name}}|
}}|
function_description=Returns an effect if {{pspan|check_me}} is effect specific. {{pspan|modifier_name}} is the <b>[[modifiers|modifier]]</b> to check for.|

code1={{CodeSample|
title=Code Sample|
description=Prints a list of all items that have intrinsic effects|
code=
<syntaxhighlight>
effect eff;
foreach doodad in $items[] {
eff = effect_modifier( doodad , "Intrinsic Effect" );
if(eff != $effect[none])
print(doodad +" grants "+ eff);
}
</syntaxhighlight>}}
{{CodeSample|
description=Return the effect granted by drinking a particular potion.|
code=<syntaxhighlight>
effect potion_to_effect(item potion) }
return effect_modifier(potion, "effect");
}
</syntaxhighlight>}}|

more_info= See [http://kolmafia.us/showthread.php?802 this thread] for details.|
}}

{{SeeAlso|boolean_modifier|numeric_modifier|string_modifier}}

[[Category:Modifier Functions]]

Numeric modifier

2020-07-01T21:19:44Z

Fredg1:

{{
#vardefine:name|numeric_modifier}}{{
#vardefine:return_type|float}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|modifier_name}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|check_me}}|
parameter2={{Param|string|modifier_name}}|
}}|

function3={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|item|check_me}}|
parameter2={{Param|string|modifier_name}}|
}}|

function4={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|effect|check_me}}|
parameter2={{Param|string|modifier_name}}|
}}|

function5={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|skill|check_me}}|
parameter2={{Param|string|modifier_name}}|
p1desc={{Pspan|check_me}} is the string, item, effect or skill to check|
p2desc={{Pspan|modifier_name}} is the <b>[[modifiers|modifier]]</b> to check|
}}|

function_description=Returns your current modifier total for {{pspan|modifier_name}}, or the amount of modification from {{pspan|check_me}} if specified.</p>
===Special Syntax for Familiars===
{{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|familiar|buddy}}|
parameter2={{Param|string|check_me}}|
parameter3={{Param|int|weight}}|
parameter4={{Param|item|equipment}}|
p1desc={{Pspan|buddy}} is the familiar to check|
p2desc={{Pspan|check_me}} is the modifier to check|
p3desc={{Pspan|weight}} is the familiar's weight (buffed, not including equipment)|
p4desc={{Pspan|equipment}} is the familiar's equipment|
}}
<p>Returns the familiar's effect on this modifier (for instance, a baby gravy fairy would return some positive float for "Item Drop").|

code1={{CodeSample|
title=Code Sample|
description=Prints your current Initiative:|
code=
<syntaxhighlight>
float init = numeric_modifier( "initiative" );
print(init);
</syntaxhighlight>}}
{{CodeSample|
description=Function that checks if a single effect from a given list will buff your muscle over an amount goal. The name of the first effect to satisfy the goal is printed, or you are warned if none is found.|
code=
<syntaxhighlight>
boolean buffMuscleTo( int goal ) {
int current_muscle = my_buffedstat( $stat[Muscle] ) ;
int base_muscle = my_basestat( $stat[Muscle] ) ;
int muscle_increase ;
if ( current_muscle >= goal ) return true ;

foreach it in $effects[Tomato Power, Phorcefullness, Gr8tness, Incredibly Hulking] {
if ( have_effect(it) > 0 ) continue ;
muscle_increase = floor( base_muscle * numeric_modifier( it, "Muscle Percent" ) / 100 );
if ( current_muscle + muscle_increase >= goal ) {
print(it + " will bring your muscle over " + goal);
return true;
}
}
print("No effect found");
return false;
}
</syntaxhighlight>}}|

code2={{CodeSample|
title=Potion/effect-giving items|
description=To get a modifier from a consumable which gives an effect, it is first necessary to convert the item into its given effect with [[effect_modifier]]. <br> This snippet calculates what your meat drop bonus would be after eating a {{kolwiki|sweet roll alabama}}:|
code=<syntaxhighlight>
float meat_boost = numeric_modifier( "meat drop" );
effect effect_from_item = effect_modifier( $item[Sweet roll Alabama] , "effect" );

meat_boost += numeric_modifier( effect_from_item , "meat drop" );
</syntaxhighlight>}}|

cli_equiv=The CLI command "modtrace" gives access to the same information when the correct parameters are specified.|

more_info= For a full list of modifiers, see [[modifiers]].<br>
For more information about numeric_modifier(), see the following thread: [http://kolmafia.us/showthread.php?802 List].|
}}

{{SeeAlso|boolean_modifier|effect_modifier|string_modifier}}

[[Category:Modifier Functions]]

String modifier

2020-07-01T21:19:23Z

Fredg1:

{{
#vardefine:name|string_modifier}}{{
#vardefine:return_type|string}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|check_me}}||
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|check_me}}|
parameter2={{Param|string|modifier_name}}|
}}|
function_description=Returns a string modifier. <br /><br />
For a list of fields that this function takes, see [[Modifiers#String_Modifiers|Modifiers]].|

code1={{CodeSample|
title=Code Samples|
description=Checks current equipped outfit.|
code=
<syntaxhighlight>
if(string_modifier("outfit") == "knob goblin elite guard uniform")
print("You are equipped to purchase seltzer.");
else print("The Knob scientists won't let you into their store dressed like that.");
</syntaxhighlight>}}
{{CodeSample|
description=Display all modifiers related to your current moon sign.|
code=
<syntaxhighlight>
print("I was born under the sign of the "+ my_sign() +" which gives me these modifiers:");
print( string_modifier("Sign:"+ my_sign(), "Modifiers" ) );
</syntaxhighlight>
}}|

more_info= See [http://kolmafia.us/showthread.php?802 this thread] for details.|
}}

{{SeeAlso|boolean_modifier|effect_modifier|numeric_modifier}}

[[Category:Modifier Functions]]

String modifier

2020-07-01T21:09:43Z

Fredg1:

Boolean modifier

2020-07-01T21:06:01Z

Fredg1:

{{
#vardefine:name|boolean_modifier}}{{
#vardefine:return_type|boolean}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|str}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|item|it}}|
parameter2={{Param|string|str}}|
p1desc={{pspan|it}} is the (optional) item in question|
p2desc={{pspan|str}} is the modifier name|
}}|

function_description=Accesses fields of your current modifiers for all of your current equipment and effects. This is the same mechanism that lets mafia decide whether you can adventure underwater, or how many songs you can keep in your head. <br /><br />
For a list of fields that this function takes, see [[Modifiers#Boolean_Modifiers|Modifiers]].|

code1={{CodeSample|
title=Simple Examples|
description=Tells you if you can adventure underwater or not.|
code=
<syntaxhighlight>
if(!(boolean_modifier("Adventure Underwater"))||!(boolean_modifier("Underwater Familiar"))) {
print("You can't adventure underwater.", "red");
print("Either you won't be able to breathe, or your familiar won't.","red");
exit;
}
print("You can adventure underwater.");
</syntaxhighlight>}}
{{CodeSample|
description=Informs the player of how many accordion thief songs he can have active at one time.|
code=
<syntaxhighlight>
boolean four_songs = boolean_modifier("four songs");
# plexiglass pendant and/or brimstone beret grant 4 songs total.
boolean extra_song = boolean_modifier("additional song");
# La Hebilla del Cinturón de Lopez adds one song
int max_songs = 3 + to_int(four_songs) + to_int(extra_song);
print("You can currently hold "+ max_songs +" songs in your head at a time.");
</syntaxhighlight>}}

{{SeeAlso|effect_modifier|numeric_modifier|stat_modifier|string_modifier}}|
}}

[[Category:Modifier Functions]]

Effect modifier

2020-07-01T21:04:26Z

Fredg1:

Numeric modifier

2020-07-01T21:02:14Z

Fredg1: more info about other functions/list of modifiers

Numeric modifier

2020-07-01T20:47:29Z

Fredg1: add the use of effect_modifier() to get potions' effect modifiers

{{
#vardefine:name|numeric_modifier}}{{
#vardefine:return_type|float}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|modifier_name}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|check_me}}|
parameter2={{Param|string|modifier_name}}|
}}|

function3={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|item|check_me}}|
parameter2={{Param|string|modifier_name}}|
}}|

function4={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|effect|check_me}}|
parameter2={{Param|string|modifier_name}}|
}}|

function5={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|skill|check_me}}|
parameter2={{Param|string|modifier_name}}|
p1desc={{Pspan|check_me}} is the string, item, effect or skill to check|
p2desc={{Pspan|modifier_name}} is the modifier to check|
}}|

function_description=Returns your current modifier total for {{pspan|modifier_name}}, or the amount of modification from {{pspan|check_me}} if specified.</p>
===Special Syntax for Familiars===
{{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|familiar|buddy}}|
parameter2={{Param|string|check_me}}|
parameter3={{Param|int|weight}}|
parameter4={{Param|item|equipment}}|
p1desc={{Pspan|buddy}} is the familiar to check|
p2desc={{Pspan|check_me}} is the modifier to check|
p3desc={{Pspan|weight}} is the familiar's weight (buffed, not including equipment)|
p4desc={{Pspan|equipment}} is the familiar's equipment|
}}
<p>Returns the familiar's effect on this modifier (for instance, a baby gravy fairy would return some positive float for "Item Drop").|

code1={{CodeSample|
title=Code Sample|
description=Prints your current Initiative:|
code=
<syntaxhighlight>
float init = numeric_modifier( "initiative" );
print(init);
</syntaxhighlight>}}
{{CodeSample|
description=Function that checks if a single effect from a given list will buff your muscle over an amount goal. The name of the first effect to satisfy the goal is printed, or you are warned if none is found.|
code=
<syntaxhighlight>
boolean buffMuscleTo( int goal ) {
int current_muscle = my_buffedstat( $stat[Muscle] ) ;
int base_muscle = my_basestat( $stat[Muscle] ) ;
int muscle_increase ;
if ( current_muscle >= goal ) return true ;

foreach it in $effects[Tomato Power, Phorcefullness, Gr8tness, Incredibly Hulking] {
if ( have_effect(it) > 0 ) continue ;
muscle_increase = floor( base_muscle * numeric_modifier( it, "Muscle Percent" ) / 100 );
if ( current_muscle + muscle_increase >= goal ) {
print(it + " will bring your muscle over " + goal);
return true;
}
}
print("No effect found");
return false;
}
</syntaxhighlight>}}|

code2={{CodeSample|
title=Potion/effect-giving items|
description=To get a modifier from a consumable which gives an effect, it is first necessary to convert the item into its given effect with [[effect_modifier]]. <br> This snippet calculates what your meat drop bonus would be after eating a {{kolwiki|sweet roll alabama}}:|
code=<syntaxhighlight>
float meat_boost = numeric_modifier( "meat drop" );
effect effect_from_item = effect_modifier( $item[Sweet roll Alabama] , "effect" );

meat_boost += numeric_modifier( effect_from_item , "meat drop" );
</syntaxhighlight>}}|

cli_equiv=The CLI command "modtrace" gives access to the same information when the correct parameters are specified.|

more_info= For a full list of numeric modifiers, see the following thread: [http://kolmafia.us/showthread.php?802 List].|
}}

{{SeeAlso|effect_modifier}}

[[Category:Modifier Functions]]

Your Character

2020-06-30T23:23:06Z

Fredg1: /* Viewable Info */ get_campground and get_dwelling

{{TOCright}}
==Viewable Info==
{{flink|string|my_name|desc=Returns your character's name in lowercase.}}
{{flink|string|my_id|desc=Returns your character ID.}}
{{flink|int|get_clan_id|desc=Returns the ID number of the character's current clan.}}
{{flink|string|get_clan_name|desc=Returns the name of the character's current clan.}}
{{Flink|int|my_ascensions|desc=Returns the number of times your character has ascended.}}
{{flink|class|my_class|desc=Returns your class.}}
{{flink|int|my_level|desc=Returns your level.}}
{{flink|int|my_adventures|desc=Returns the number of adventures you have remaining.}}
{{flink|int|total_turns_played|desc=Returns total turns played since the character was created.}}
{{flink|int|turns_played}}
{{flink|int|my_turncount|desc=Both functions return the number of adventures used this ascension.}}
{{flink|int|my_daycount|desc=Return the number of days used this ascension.}}
{{flink|stat|my_primestat|desc=Returns the main stat of your current class.}}
{{flink|int|my_basestat|stat|desc=Returns your base value in the given stat (or substat).}}
{{flink|int|my_buffedstat|stat|desc=Returns your buffed value in the given stat (or substat).}}
{{flink|boolean|hippy_stone_broken|desc=Reports if your Hippy Stone is currently broken.}}
{{flink|int|pvp_attacks_left|desc=Returns number of PvP attacks remaining.}}
{{flink|int|total_free_rests|desc=Returns the total number of free rests available to your character.}}
{{flink|int [item]|get_campground|desc=Returns a map of your campground items as integers, keyed by item names.}}
{{flink|item|get_dwelling|desc=Returns the item corresponding with your dwelling (the item used to get the dwelling).}}
{{flink|thrall|my_thrall|desc=Returns your current pasta thrall.}}

==Resources==
{{flink|int|my_hp|desc=Returns your current HP.}}
{{flink|int|my_mp|desc=Returns your current MP.}}
{{flink|int|my_maxhp|desc=Returns your current maximum HP.}}
{{flink|int|my_maxmp|desc=Returns your current maximum MP.}}
{{flink|int|my_soulsauce|desc=Returns your current Soulsauce.}}
{{flink|int|my_audience|desc=Returns your current Audience.}}
{{flink|int|my_thunder|desc=Returns your current Thunder.}}
{{flink|int|my_rain|desc=Returns your current Rain.}}
{{flink|int|my_lightning|desc=Returns your current Lightning.}}

==Familiars and Substitutes==
{{flink|familiar|my_familiar|desc=Returns your current familiar.}}
{{flink|int|familiar_weight|familiar|desc=Returns the base weight of the specified familiar.}}
{{flink|boolean|is_familiar_equipment_locked|desc=Returns lock status of familiar equipment.}}
{{flink|void|lock_familiar_equipment|boolean|desc=Locks or Unlocks familiar equipment.}}
{{flink|int|minstrel_level|desc=Reports Clancy's level.}}
{{flink|item|minstrel_instrument|desc=Reports Clancy's equipped item.}}
{{flink|boolean|minstrel_quest|desc=Reports if Clancy has a new quest for you.}}
{{flink|string|my_companion|desc=Returns your current companion.}}

==Hidden Info==
{{flink|string|my_hash|desc=Returns the password hash for your current session.}}
{{flink|stat|current_hit_stat|desc=Returns the stat currently used to calculate to-hit percentage.}}
{{flink|int|buffed_hit_stat|desc=Returns the buffed value of your currently used to-hit stat.}}
{{flink|int|raw_damage_absorption|desc=Returns your current DA total.}}
{{flink|float|damage_absorption_percent|desc=Returns the percentage of damage mitigated by your DA.}}
{{flink|int|damage_reduction|desc=Returns the amount of damage reduction your character currently has.}}
{{flink|float|elemental_resistance|element|desc=Returns the percentage of damage reduction to the given element based on your current resistance to that element.}}
{{flink|float|combat_rate_modifier|desc=Returns the percentage adjustment to your combat rate.}}
{{flink|float|initiative_modifier|desc=Returns the percentage adjustment to your chance of gaining initiative.}}
{{flink|float|experience_bonus|desc=Returns the amount of bonus experience your receive after combat.}}
{{flink|float|meat_drop_modifier|desc=Returns the percentage adjustment to meat drops after combat.}}
{{flink|float|item_drop_modifier|desc=Returns the percentage adjustment to item drops after combat.}}
{{flink|int|monster_level_adjustment|desc=Returns the total +ML you have active, including your sign-specific device.}}
{{flink|stat|stat_bonus_today}}
{{flink|stat|stat_bonus_tomorrow|desc=These two functions report on what stat has a stat-day bonus or $stat[none] if it isn't a stat day.}}
{{flink|int|current_mcd|desc=Returns the current setting of your sign-specific +ML device.}}
{{flink|int|weight_adjustment|desc=Returns the cumulative total of all familiar weight adjustments from all sources.}}
{{flink|boolean|get_ignore_zone_warnings|desc=Returns the value of the KoL option to disable "This area might be too tough for you" warnings.}}
{{flink|string [location] [int]|get_florist_plants|desc=Returns the a map of all plants currently planted in every location.}}

==Sign & Path==
{{flink|boolean|can_eat|desc=Reports on whether your characters path allows food consumption.}}
{{flink|boolean|can_drink|desc=Reports on whether your characters path allows booze consumption}}
{{flink|boolean|can_interact|desc=Reports on whether your character can access the mall, gift packages, etc.}}
{{flink|boolean|in_hardcore|desc=Reports on whether your character is under Hardcore restrictions.}}
{{flink|item|daily_special|desc=Returns the daily special at your sign eatery.}}
{{flink|boolean|in_moxie_sign}}
{{flink|boolean|in_muscle_sign}}
{{flink|boolean|in_mysticality_sign}}
{{flink|boolean|in_bad_moon|desc=These four functions report on the stat gains granted by your character's ascension moon sign.}}
{{flink|string|my_path|desc=The ascension path your character chose.}}
{{flink|string|my_path_id|desc=The number of the ascension path your character chose.}}
{{flink|string|my_sign|desc=The moon sign your character ascended under.}}

==Consumption==
{{flink|int|my_fullness|desc=Returns how full you are.}}
{{flink|int|fullness_limit|desc=Returns your maximum fullness.}}
{{flink|int|my_inebriety|desc=Returns your current drunkenness.}}
{{flink|int|inebriety_limit|desc=Returns your maximum safe drunk (before overdrinking).}}
{{flink|int|my_spleen_use|desc=Returns your current spleen use.}}
{{flink|int|spleen_limit|desc=Returns your spleen limit.}}

==Location Availability==
{{flink|boolean|black_market_available|desc=Returns the availability of the Black Market.}}
{{flink|boolean|canadia_available|desc=Returns the availability of Little Canadia.}}
{{flink|boolean|dispensary_available|desc=Returns the availability of the Knob Dispensary.}}
{{flink|boolean|florist_available|desc=Returns the availability of The Florist Friar's Cottage.}}
{{flink|boolean|gnomads_available|desc=Returns the availability of the Gnomish Gnomad Camp.}}
{{flink|boolean|guild_store_available|desc=Returns the availability of your guild store.}}
{{flink|boolean|hidden_temple_unlocked|desc=Returns the availability of the Hidden Temple.}}
{{flink|boolean|hippy_store_available|desc=Returns the availability of the Hippy Store.}}
{{flink|boolean|knoll_available|desc=Returns the availability of the Degrassi Knoll.}}
{{flink|boolean|white_citadel_available|desc=Returns the availability of White Citadel.}}

==Misc.==
{{Flink|string|eudora|desc=Returns your current Eudora correspondent.}}
{{Flink|boolean|galaktik_cures_discounted|desc=Returns whether Doc's offers you a discount for quest completion.}}
{{Flink|int|is_unrestricted|desc=Checks whether a given game resource is available.}}
{{Flink|int|moon_light|desc=Returns the total lit moon segments.}}
{{Flink|int|moon_phase|desc=Returns the phase (0-15) of the main moons.}}

[[Category:Scripting]]

Available amount

2020-06-23T00:34:28Z

Fredg1: storage_amount()

{{
#vardefine:name|available_amount}}{{
#vardefine:return_type|int}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|item|it}}|
p1desc={{Pspan|it}} is the item to check|
}}|

function_description=Returns the total number available of a given item in all inventory sections accessible to your character based on current restrictions, including equipped items (for equipment). In Ronin, this includes free pulls, but does not include any other items in Hangk's Storage. Once out of Ronin/run, if [[KoLmafia_Properties#Global_Variables|autoSatisfyWithStorage]] is set to true, this includes items in Hangk's Storage.
If [[KoLmafia_Properties#Global_Variables|autoSatisfyWithCloset]] is set to true, this includes closet. If [[KoLmafia_Properties#Global_Variables|autoSatisfyWithStash]] is set to true, this includes clan stash.|

code1={{CodeSample|
title=Code Sample|
description=Enumerates total number of scrolls of ancient forbidden unspeakable evil.|
code=
<syntaxhighlight>
int current_afue = available_amount($item[scroll of ancient forbidden unspeakable evil]);
// Calculate minimum of pens, paper and ink:
int make_afue = available_amount($item[disintegrating quill pen]);
make_afue = min(make_afue, available_amount($item[tattered scrap of paper]));
make_afue = min(make_afue, available_amount($item[inkwell]));
print("Currently possess "+ current_afue + " afue scrolls.");
print("Can make another "+ make_afue +" scrolls from parts.");
</syntaxhighlight>
}}|

see_also={{SeeAlso|closet_amount|display_amount|equipped_amount|item_amount|shop_amount|stash_amount|storage_amount}}|
more_info=Information on handling free pulls is at [[Tips, Tricks and Workarounds#Free Pulls|Tips, Tricks and Workarounds]].|
}}

[[Category:Item Management]]

Path name to id

2020-06-08T00:48:04Z

Fredg1:

{{
#vardefine:name|path_name_to_id}}{{
#vardefine:return_type|int}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|name}}|
p1desc={{Pspan|name}} is the full, exact, case-sensitive name of the path to convert.|
}}|

function_description=Returns the specified path {{pspan|name}} as its {{kolwiki|Paths_by_number|path number}}.|

code1={{CodeSample|
title=Code Samples|
description=Following example shows basic path_name_to_id operations.||
code=
<syntaxhighlight>
string first = "Bees Hate You";
string second = "G-Lover";
string third = "Live. Ascend. Repeat.";

print(first+" gives "+path_name_to_id(first)+".");
print(second+" gives "+path_name_to_id(second)+".");
print(third+" gives "+path_name_to_id(third)+".");
</syntaxhighlight>|
moreinfo=
Gives the following output.
<pre>
Bees Hate You gives 4.
G-Lover gives 33.
Live. Ascend. Repeat. gives 31.
</pre>
}}|

see_also={{SeeAlso|my_path|my_path_id|path_id_to_name}}|
special=Returns -1 if given an incorrect/unknown name. Also, "Unrestricted" and "Aftercore" are not valid inputs for 0. "None" is instead expected.|
}}

[[Category:Datatype Conversions]]

Path name to id

2020-06-08T00:42:28Z

Fredg1:

{{
#vardefine:name|path_name_to_id}}{{
#vardefine:return_type|int}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|name}}|
p1desc={{Pspan|name}} is the ''exact'' name of the path to convert.|
}}|

function_description=Returns the specified path {{pspan|name}} as its {{kolwiki|Paths_by_number|path number}}.|

code1={{CodeSample|
title=Code Samples|
description=Following example shows basic path_name_to_id operations.||
code=
<syntaxhighlight>
string first = "Bees Hate You";
string second = "G-Lover";
string third = "Live. Ascend. Repeat.";

print(first+" gives "+path_name_to_id(first)+".");
print(second+" gives "+path_name_to_id(second)+".");
print(third+" gives "+path_name_to_id(third)+".");
</syntaxhighlight>|
moreinfo=
Gives the following output.
<pre>
Bees Hate You gives 4.
G-Lover gives 33.
Live. Ascend. Repeat. gives 31.
</pre>
}}|

see_also={{SeeAlso|my_path|my_path_id|path_id_to_name}}|
special=The input is case-sensitive, and doesn't accept partial matches. Also, "Unrestricted" and "Aftercore" are not valid inputs. "None" is instead expected.|
}}

[[Category:Datatype Conversions]]

Datatype Conversions

2020-06-08T00:14:51Z

Fredg1: path_id_to_name and path_name_to_id

<p>These functions will convert one type of data to another.</p>
{{flink|boolean|to_boolean|any|desc=Converts any datatype to a boolean.}}
{{flink|bounty|to_bounty|string|desc=Converts a string to a bounty.}}
{{flink|class|to_class|string|desc=Converts a string to a class.}}
{{flink|effect|to_effect|int}}
{{flink|effect|to_effect|string}}
{{flink|effect|to_effect|skill|desc=Converts an int, string or skill to an effect.}}
{{flink|element|to_element|string|desc=Converts a string to an element.}}
{{flink|familiar|to_familiar|int}}
{{flink|familiar|to_familiar|string|desc=Converts an int or a string to a familiar.}}
{{flink|float|to_float|any|desc=Converts from any datatype to a float.}}
{{flink|int|path_name_to_id|string}}
{{flink|int|to_int|any|desc=Converts from any datatype to an int.}}
{{flink|item|to_item|string}}
{{flink|item|to_item|int}}
{{flink|item|to_item|string|int|desc=Converts an int or a string to an item (optionally allowing plural strings with both parameters).}}
{{flink|location|to_location|string|desc=Converts a string to a location.}}
{{flink|monster|to_monster|string|desc=Converts a string to a monster.}}
{{flink|phylum|to_phylum|string|desc=Converts a string to a phylum.}}
{{flink|string|to_plural|item|desc=Converts an item into the string value of its plural.}}
{{flink|skill|to_skill|int}}
{{flink|skill|to_skill|string}}
{{flink|skill|to_skill|effect|desc=Converts an int, string or effect to a skill.}}
{{flink|slot|to_slot|item}}
{{flink|slot|to_slot|string|desc=Converts an item or string to a slot.}}
{{flink|stat|to_stat|string|desc=Converts a string to a stat.}}
{{flink|string|path_id_to_name|int}}
{{flink|string|to_string|any|desc=Converts any datatype to a string.}}
{{flink|thrall|to_thrall|string}}
{{flink|thrall|to_thrall|int|desc=Converts a string or int to a thrall.}}
== Historical note ==
ASH did not originally support polymorphic functions, so it was not possible to have (for example) a single '''to_string(any)''' function that worked on any datatype. Instead, there were separate '''int_to_string(int)''', '''item_to_string(item)''', etc. functions. You may see these used in older scripts, and in fact they still work. The rule is that if a function name is not otherwise defined anywhere, and it ends with one of the modern type conversion function names shown above, it is treated as a call to the modern function. No check is made to verify that the chopped-off portion of the old function name actually matches the type of its parameter.

[[Category:Scripting]]

Path name to id

2020-06-08T00:03:25Z

Fredg1: temporary draft until function is fixed

Path id to name

2020-06-07T22:37:56Z

Fredg1: Created page with "{{ #vardefine:name|path_id_to_name}}{{ #vardefine:return_type|string}}{{ FunctionPage| name={{#var:name}}| function1={{Function| name={{#var:name}}| aggregate={{#var:aggrega..."

{{
#vardefine:name|path_id_to_name}}{{
#vardefine:return_type|string}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|int|id}}|
p1desc={{Pspan|id}} is the {{kolwiki|Paths_by_number|ID of the path}} to convert|
}}|

function_description=Returns the name of the specified path {{pspan|id}}.|

code1={{CodeSample|
title=Code Samples|
description=Following example shows basic path_id_to_name operations.||
code=
<syntaxhighlight>
int first = 3;
int second = 7;
int third = 24;

print(first+" gives "+path_id_to_name(first)+".");
print(second+" gives "+path_id_to_name(second)+".");
print(third+" gives "+path_id_to_name(third)+".");
</syntaxhighlight>|
moreinfo=
Gives the following output.
<pre>
3 gives Oxygenarian.
7 gives Trendy.
24 gives One Crazy Random Summer.
</pre>
}}|

see_also={{SeeAlso|my_path|my_path_id|path_name_to_id}}|
special=Returns "None" when submitting an ID which doesn't have a known path tied to, such as 5 (never released), or 60 (not yet known). Also, the 3 first unknown paths return "Path {{Pspan|id}}", for internal reasons (as of writing this, for example, 40, 41 and 42 return "Path 40", "Path 41" and "Path 42".|
}}

[[Category:Datatype Conversions]]

Your Character

2020-06-07T22:04:33Z

Fredg1: /* Sign & Path */ + my_path_id

{{TOCright}}
==Viewable Info==
{{flink|string|my_name|desc=Returns your character's name in lowercase.}}
{{flink|string|my_id|desc=Returns your character ID.}}
{{flink|int|get_clan_id|desc=Returns the ID number of the character's current clan.}}
{{flink|string|get_clan_name|desc=Returns the name of the character's current clan.}}
{{Flink|int|my_ascensions|desc=Returns the number of times your character has ascended.}}
{{flink|class|my_class|desc=Returns your class.}}
{{flink|int|my_level|desc=Returns your level.}}
{{flink|int|my_adventures|desc=Returns the number of adventures you have remaining.}}
{{flink|int|total_turns_played|desc=Returns total turns played since the character was created.}}
{{flink|int|turns_played}}
{{flink|int|my_turncount|desc=Both functions return the number of adventures used this ascension.}}
{{flink|int|my_daycount|desc=Return the number of days used this ascension.}}
{{flink|stat|my_primestat|desc=Returns the main stat of your current class.}}
{{flink|int|my_basestat|stat|desc=Returns your base value in the given stat (or substat).}}
{{flink|int|my_buffedstat|stat|desc=Returns your buffed value in the given stat (or substat).}}
{{flink|boolean|hippy_stone_broken|desc=Reports if your Hippy Stone is currently broken.}}
{{flink|int|pvp_attacks_left|desc=Returns number of PvP attacks remaining.}}
{{flink|int|total_free_rests|desc=Returns the total number of free rests available to your character.}}
{{flink|thrall|my_thrall|desc=Returns your current pasta thrall.}}

==Resources==
{{flink|int|my_hp|desc=Returns your current HP.}}
{{flink|int|my_mp|desc=Returns your current MP.}}
{{flink|int|my_maxhp|desc=Returns your current maximum HP.}}
{{flink|int|my_maxmp|desc=Returns your current maximum MP.}}
{{flink|int|my_soulsauce|desc=Returns your current Soulsauce.}}
{{flink|int|my_audience|desc=Returns your current Audience.}}
{{flink|int|my_thunder|desc=Returns your current Thunder.}}
{{flink|int|my_rain|desc=Returns your current Rain.}}
{{flink|int|my_lightning|desc=Returns your current Lightning.}}

==Familiars and Substitutes==
{{flink|familiar|my_familiar|desc=Returns your current familiar.}}
{{flink|int|familiar_weight|familiar|desc=Returns the base weight of the specified familiar.}}
{{flink|boolean|is_familiar_equipment_locked|desc=Returns lock status of familiar equipment.}}
{{flink|void|lock_familiar_equipment|boolean|desc=Locks or Unlocks familiar equipment.}}
{{flink|int|minstrel_level|desc=Reports Clancy's level.}}
{{flink|item|minstrel_instrument|desc=Reports Clancy's equipped item.}}
{{flink|boolean|minstrel_quest|desc=Reports if Clancy has a new quest for you.}}
{{flink|string|my_companion|desc=Returns your current companion.}}

==Hidden Info==
{{flink|string|my_hash|desc=Returns the password hash for your current session.}}
{{flink|stat|current_hit_stat|desc=Returns the stat currently used to calculate to-hit percentage.}}
{{flink|int|buffed_hit_stat|desc=Returns the buffed value of your currently used to-hit stat.}}
{{flink|int|raw_damage_absorption|desc=Returns your current DA total.}}
{{flink|float|damage_absorption_percent|desc=Returns the percentage of damage mitigated by your DA.}}
{{flink|int|damage_reduction|desc=Returns the amount of damage reduction your character currently has.}}
{{flink|float|elemental_resistance|element|desc=Returns the percentage of damage reduction to the given element based on your current resistance to that element.}}
{{flink|float|combat_rate_modifier|desc=Returns the percentage adjustment to your combat rate.}}
{{flink|float|initiative_modifier|desc=Returns the percentage adjustment to your chance of gaining initiative.}}
{{flink|float|experience_bonus|desc=Returns the amount of bonus experience your receive after combat.}}
{{flink|float|meat_drop_modifier|desc=Returns the percentage adjustment to meat drops after combat.}}
{{flink|float|item_drop_modifier|desc=Returns the percentage adjustment to item drops after combat.}}
{{flink|int|monster_level_adjustment|desc=Returns the total +ML you have active, including your sign-specific device.}}
{{flink|stat|stat_bonus_today}}
{{flink|stat|stat_bonus_tomorrow|desc=These two functions report on what stat has a stat-day bonus or $stat[none] if it isn't a stat day.}}
{{flink|int|current_mcd|desc=Returns the current setting of your sign-specific +ML device.}}
{{flink|int|weight_adjustment|desc=Returns the cumulative total of all familiar weight adjustments from all sources.}}
{{flink|boolean|get_ignore_zone_warnings|desc=Returns the value of the KoL option to disable "This area might be too tough for you" warnings.}}
{{flink|string [location] [int]|get_florist_plants|desc=Returns the a map of all plants currently planted in every location.}}

==Sign & Path==
{{flink|boolean|can_eat|desc=Reports on whether your characters path allows food consumption.}}
{{flink|boolean|can_drink|desc=Reports on whether your characters path allows booze consumption}}
{{flink|boolean|can_interact|desc=Reports on whether your character can access the mall, gift packages, etc.}}
{{flink|boolean|in_hardcore|desc=Reports on whether your character is under Hardcore restrictions.}}
{{flink|item|daily_special|desc=Returns the daily special at your sign eatery.}}
{{flink|boolean|in_moxie_sign}}
{{flink|boolean|in_muscle_sign}}
{{flink|boolean|in_mysticality_sign}}
{{flink|boolean|in_bad_moon|desc=These four functions report on the stat gains granted by your character's ascension moon sign.}}
{{flink|string|my_path|desc=The ascension path your character chose.}}
{{flink|string|my_path_id|desc=The number of the ascension path your character chose.}}
{{flink|string|my_sign|desc=The moon sign your character ascended under.}}

==Consumption==
{{flink|int|my_fullness|desc=Returns how full you are.}}
{{flink|int|fullness_limit|desc=Returns your maximum fullness.}}
{{flink|int|my_inebriety|desc=Returns your current drunkenness.}}
{{flink|int|inebriety_limit|desc=Returns your maximum safe drunk (before overdrinking).}}
{{flink|int|my_spleen_use|desc=Returns your current spleen use.}}
{{flink|int|spleen_limit|desc=Returns your spleen limit.}}

==Location Availability==
{{flink|boolean|black_market_available|desc=Returns the availability of the Black Market.}}
{{flink|boolean|canadia_available|desc=Returns the availability of Little Canadia.}}
{{flink|boolean|dispensary_available|desc=Returns the availability of the Knob Dispensary.}}
{{flink|boolean|florist_available|desc=Returns the availability of The Florist Friar's Cottage.}}
{{flink|boolean|gnomads_available|desc=Returns the availability of the Gnomish Gnomad Camp.}}
{{flink|boolean|guild_store_available|desc=Returns the availability of your guild store.}}
{{flink|boolean|hidden_temple_unlocked|desc=Returns the availability of the Hidden Temple.}}
{{flink|boolean|hippy_store_available|desc=Returns the availability of the Hippy Store.}}
{{flink|boolean|knoll_available|desc=Returns the availability of the Degrassi Knoll.}}
{{flink|boolean|white_citadel_available|desc=Returns the availability of White Citadel.}}

==Misc.==
{{Flink|string|eudora|desc=Returns your current Eudora correspondent.}}
{{Flink|boolean|galaktik_cures_discounted|desc=Returns whether Doc's offers you a discount for quest completion.}}
{{Flink|int|is_unrestricted|desc=Checks whether a given game resource is available.}}
{{Flink|int|moon_light|desc=Returns the total lit moon segments.}}
{{Flink|int|moon_phase|desc=Returns the phase (0-15) of the main moons.}}

[[Category:Scripting]]

My path id

2020-06-07T22:03:23Z

Fredg1: Created page with "{{ #vardefine:name|my_path_id}}{{ #vardefine:return_type|int}}{{ FunctionPage| name={{#var:name}}| function1={{Function| name={{#var:name}}| aggregate={{#var:aggregate}}| re..."

{{
#vardefine:name|my_path_id}}{{
#vardefine:return_type|int}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
}}|

function_description=Returns the {{kolwiki|Paths_by_number|ID of the path}} your character chose upon ascension ("0" when in aftercore).|

see_also={{SeeAlso|my_path|path_id_to_name|path_name_to_id|my_sign|knoll_available|canadia_available|gnomads_available}}|
special=This function returns "0" when not logged in.|
}}

[[Category:Your Character]]

My path

2020-06-07T21:53:32Z

Fredg1: see also: the 3 new path ID functions

{{
#vardefine:name|my_path}}{{
#vardefine:return_type|string}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
}}|

function_description=Returns the path your character chose upon ascension ("None" when in aftercore).|

code1={{CodeSample|
title=Code Samples|
description=This prints all the affects of your moon sign.|
code=<syntaxhighlight>
if(my_path() == "Bees Hate You")
print("I'm doing a Bees Hate You run.");
else print("Bees do not hate me, thank goodness.");
</syntaxhighlight>
}}|
see_also={{SeeAlso|my_path_id|path_id_to_name|path_name_to_id|my_sign|knoll_available|canadia_available|gnomads_available}}|
special=This function returns "None" when not logged in.|
}}

[[Category:Your Character]]

Combat rate modifier

2020-06-03T21:46:24Z

Fredg1: functionally equivalent to numeric_modifier("Combat Rate")

{{
#vardefine:name|combat_rate_modifier}}{{
#vardefine:return_type|float}}{{

FunctionPage|
name={{#var:name}}|

function1={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}
}}|

function_description=Returns the current percentage change on combat frequency including equipment and effects.|

code1={{CodeSample|
title=Code Samples|
description=Checks that your combat frequency modifier is positive (for example, before adventuring in the Purple Light District).|
code=
<syntaxhighlight>
boolean is_combat_positive() {
if(combat_rate_modifier() > 0) {
return true;
}
return false;
}
</syntaxhighlight>|

moreinfo=This is functionally equivalent to doing <code>numeric_modifier("Combat Rate")</code>}}|

see_also={{SeeAlso|appearance_rates}}|
special=Returns 0.0 when not logged in.
}}

[[Category:Your Character]]

Location

2020-06-03T21:40:38Z

Fredg1: /* Proxy Record Fields */

{{DISPLAYTITLE:location}}

{{TOCright}}

This data type represents any location in KoL in which one can adventure.

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

==Related Functions==

{{Flink|boolean|adv1|location|int|string}}
{{Flink|boolean|adventure|int|location|{{opt|string}}}}
{{Flink|float [monster]|appearance_rates|location|{{opt|boolean}}}}
{{Flink|string [location, 3]|get_florist_plants}}
{{Flink|monster [int]|get_monsters|location}}
{{flink|int|jump_chance|location|{{opt|int}}|{{opt|int}}}}
{{Flink|location|my_location}}
{{Flink|void|set_location|location}}
{{Flink|location|to_location|strict_string}}
{{Flink|location|to_location|int}}
{{Flink|string|to_url|location}}

==Proxy Record Fields==

Here are the proxy record fields for locations. Proxy records are discussed in more
detail [[Proxy Records|here]].

{| cellpadding="3" cellspacing="0" border="1px" class="sortable"
|- | style="background-color: #F2F2F2"
|-
! Field
! Data type
! Default value
! ASH Accessor Function / Notes
|-
| nocombats
| boolean
| false
|
|-
| combat_percent
| float
| 0.0
| the chance of getting a combat encounter INCLUDING your combat_rate_modifier()
|-
| zone
| string
| ""
|
|-
| parent
| string
| ""
|
|-
| parentdesc
| string
| ""
|
|-
| environment
| string
| ""
|
|-
| bounty
| bounty
| none
|
|-
| combat_queue
| string
| ""
|
|-
| noncombat_queue
| string
| ""
|
|-
| turns_spent
| int
| 0
|
|-
| kisses
| int
| 0
| {{kolwiki|Dreadsylvania}}
|-
| recommended_stat
| int
| 0
|
|-
| water_level
| int
| 0
| {{kolwiki|Heavy Rains}}
|-
| wanderers
| boolean
| false
| whether wandering monsters can spawn in this zone
|}

[[Category:Scripting]] [[Category:Data Types]]

Location

2020-06-03T21:28:36Z

Fredg1: /* Proxy Record Fields */ added combat_percent, wanderers and described some fields

{{DISPLAYTITLE:location}}

{{TOCright}}

This data type represents any location in KoL in which one can adventure.

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

==Related Functions==

{{Flink|boolean|adv1|location|int|string}}
{{Flink|boolean|adventure|int|location|{{opt|string}}}}
{{Flink|float [monster]|appearance_rates|location|{{opt|boolean}}}}
{{Flink|string [location, 3]|get_florist_plants}}
{{Flink|monster [int]|get_monsters|location}}
{{flink|int|jump_chance|location|{{opt|int}}|{{opt|int}}}}
{{Flink|location|my_location}}
{{Flink|void|set_location|location}}
{{Flink|location|to_location|strict_string}}
{{Flink|location|to_location|int}}
{{Flink|string|to_url|location}}

==Proxy Record Fields==

Here are the proxy record fields for locations. Proxy records are discussed in more
detail [[Proxy Records|here]].

{| cellpadding="3" cellspacing="0" border="1px" class="sortable"
|- | style="background-color: #F2F2F2"
|-
! Field
! Data type
! Default value
! ASH Accessor Function / Notes
|-
| nocombats
| boolean
| false
|
|-
| combat_percent
| float
| 0.0
| the chance of getting a combat encounter AFTER applying numeric_modifier("Combat Rate")
|-
| zone
| string
| ""
|
|-
| parent
| string
| ""
|
|-
| parentdesc
| string
| ""
|
|-
| environment
| string
| ""
|
|-
| bounty
| bounty
| none
|
|-
| combat_queue
| string
| ""
|
|-
| noncombat_queue
| string
| ""
|
|-
| turns_spent
| int
| 0
|
|-
| kisses
| int
| 0
| {{kolwiki|Dreadsylvania}}
|-
| recommended_stat
| int
| 0
|
|-
| water_level
| int
| 0
| {{kolwiki|Heavy Rains}}
|-
| wanderers
| boolean
| false
| whether wandering monsters can spawn in this zone
|}

[[Category:Scripting]] [[Category:Data Types]]

Data Types

2020-03-17T22:21:44Z

Fredg1: /* float */

{{TOCright}}
==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.

Be careful when doing math with integers! As with some other strongly-typed languages, numbers are converted to integers at every step of the operation when only integer types are used. For example:
{{
CodeSample|
code=
<syntaxhighlight>
int a = 1;
int b = 2;
print( a / b * 2 );
</syntaxhighlight>}}
Will give the output "0," not "1" as you may expect. Changing either variable to a float type will "correct" this.

===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 [http://java.sun.com/docs/books/jls/third_edition/html/typesValues.html#4.2.3 section 4.2.3 of the Java Language Specification], and a tool to help understand / quickly see how/where imprecisions happen can be found [https://www.h-schmidt.net/FloatConverter/IEEE754.html here].

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.
{{
CodeSample|
description=For instance, try the following code as an example of how rather long post-decimal portions are handled:|
code=
<syntaxhighlight>
float f;
f = 4.9999999;
print( f );
</syntaxhighlight>}}
The default value of a <code>float</code> 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.{{CodeSample|
description=For example:|
code=
<syntaxhighlight>
string s = "This is my \"friend\" Pete.";
</syntaxhighlight>|
moreinfo=
Will result in the following being stored to s:
<pre>This is my "friend" Pete</pre>}}
The default value of a string is an empty string, or literally <code>""</code>.

===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 [[String Handling Routines#Regular Expressions|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.
{{CodeSample|
description=For example, to declare an item datatype and assign it a value, you would use the following line of code:|
code=
<syntaxhighlight>
item it = $item[ broken skull ];
</syntaxhighlight>}}
The default values of any variable of one of the following types is <code>$''type''[ none ]</code>. For example, the default value of a <code>item</code> variable is <code>$item[ none ]</code>.

===bounty===

([[Bounty#Related Functions|Related Functions]]) ([[Bounty#Proxy Record Fields|Proxy Record Fields]])

These are the non-items that the bounty hunter asks you to retrieve from monsters around the kingdom. There are quite a lot of them (42 in total) so I won't list them all here. You can find more about bounties at the {{kolwiki|The Bounty Hunter Hunter's Shack}}.

===class===

([[Class#Related Functions|Related Functions]]) ([[Class#Proxy Record Fields|Proxy Record Fields]])

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

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

===coinmaster===

([[Coinmaster#Related Functions|Related Functions]]) ([[Coinmaster#Proxy Record Fields|Proxy Record Fields]])

All shops that deal with currency other than meat. Known values include:

* {{kolwiki|The Bounty Hunter Hunter's Shack|Bounty Hunter Hunter}}
* {{kolwiki|Mr. Store}}
* {{kolwiki|Hermit}}
* {{kolwiki|The Shore, Inc. Gift Shop}}
* {{kolwiki|The Trapper's Cabin|The Trapper}}
* {{kolwiki|A Vending Machine|Vending Machine}}
* {{kolwiki|The Swagger Shop}}
* {{kolwiki|The Hippy Camp (Wartime)|Dimemaster}}
* {{kolwiki|The Orcish Frat House|Quartersmaster}}
* {{kolwiki|BURT|Bugbear Token}}
* {{kolwiki|Freshwater Fishbonery}}
* {{kolwiki|Big Brother}}
* {{kolwiki|The Terrified Eagle Inn}}
* {{kolwiki|Ticket Redemption Counter|Arcade Ticket Counter}}
* {{kolwiki|Cashier|Game Shoppe}}
* {{kolwiki|Cashier|Game Shoppe Snacks}}
* {{kolwiki|The Isotope Smithery|Isotope Smithery}}
* {{kolwiki|Dollhawker's Emporium}}
* {{kolwiki|The Lunar Lunch-o-Mat|Lunar Lunch-o-Mat}}
* {{kolwiki|Paul's Boutique}}
* {{kolwiki|The Frozen Brogurt Stand}}
* {{kolwiki|Buff Jimmy's Souvenir Shop}}
* {{kolwiki|Taco Dan's Taco Stand}}
* {{kolwiki|You're the Fudge Wizard Now, Dog|Fudge Wand}}
* {{kolwiki|The Neandermall}}
* {{kolwiki|Legitimate Shoe Repair, Inc.}}
* {{kolwiki|warbear black box|Warbear Black Box}}
* {{kolwiki|The Dinsey Company Store}}
* {{kolwiki|Internet Meme Shop}}

===effect===

([[Effect#Related Functions|Related Functions]]) ([[Effect#Proxy Record Fields|Proxy Record Fields]])

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 {{kolwiki|Effects}} page for more information.

===element===

([[Element#Related Functions|Related Functions]]) ([[Element#Proxy Record Fields|Proxy Record Fields]])

Besides $element[ none ], there are seven 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
* supercold

===familiar===

([[Familiar#Related Functions|Related Functions]]) ([[Familiar#Proxy Record Fields|Proxy Record Fields]])

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 {{kolwiki|Familiars}} page for more information.

===item===

([[Item#Related Functions|Related Functions]]) ([[Item#Proxy Record Fields|Proxy Record Fields]])

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.
{{CodeSample|
description=For example, you could assign the item plexiglass pants as follows:|
code=
<syntaxhighlight>
item it = $item[ 1234 ];
</syntaxhighlight>}}
The full range, besides $item[ none ], is too much to list and keep up with here: please see the Wiki {{kolwiki|Items}} page for more information.

===location===

([[Location#Related Functions|Related Functions]]) ([[Location#Proxy Record Fields|Proxy Record Fields]])

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 {{kolwiki|Locations}} page for more information.

===monster===

([[Monster#Related Functions|Related Functions]]) ([[Monster#Proxy Record Fields|Proxy Record Fields]])

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 {{kolwiki|Monster Compendium}} page for more information.

===phylum===

([[Phylum#Related Functions|Related Functions]]) ([[Phylum#Proxy Record Fields|Proxy Record Fields]])

Each monster has a {{kolwiki|Phylum}}. Besides $phylum[none], the possible values for this datatype are:

* beast
* bug
* constellation
* construct
* demon
* dude
* elemental
* elf
* fish
* goblin
* hippy
* hobo
* humanoid
* horror
* mer-kin
* orc
* penguin
* pirate
* plant
* slime
* undead
* weird

===servant===

([[Servant#Related Functions|Related Functions]]) ([[Servant#Proxy Record Fields|Proxy Record Fields]])

Servants are unique to the {{kolwiki|Actually Ed the Undying}} path and located {{kolwiki|The Servants' Quarters}}, replacing familiars.

* Assassin
* Belly-Dancer
* Bodyguard
* Cat
* Maid
* Priest
* Scribe

===skill===

([[Skill#Related Functions|Related Functions]]) ([[Skill#Proxy Record Fields|Proxy Record Fields]])

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 {{kolwiki|Skills}} page for more information.

===slot===

([[Slot#Related Functions|Related Functions]]) (slot has no proxy record fields)

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

* hat
* back
* weapon
* off-hand
* shirt
* pants
* acc1
* acc2
* acc3
* familiar
* sticker1
* sticker2
* sticker3
* fakehand
* bootspur
* bootskin

===stat===

([[Stat#Related Functions|Related Functions]]) (stat has no proxy record fields)

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

===thrall===

([[Thrall#Related Functions|Related Functions]]) ([[Thrall#Proxy Record Fields|Proxy Record Fields]])

Pastamancers have the ability to summon {{kolwiki|Pasta Thralls}}.

* Angel Hair Wisp
* Elbow Macaroni
* Lasagmbie
* Penne Dreadful
* Spaghetti Elemental
* Spice Ghost
* Vampieroghi
* Vermincelli

==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:
{{CodeSample|code=<syntaxhighlight>
foreach weapon in $items[star sword, star staff, star crossbow] {
if (available_amount(weapon) > 0) {
equip(weapon);
break;
}
}</syntaxhighlight>}}
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:
{{CodeSample|code=<syntaxhighlight>
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!");
}
}</syntaxhighlight>}}
(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:
{{CodeSample|code=<syntaxhighlight>
foreach it in $items[] {
if (autosell_price(it) == 42) print(it);
}</syntaxhighlight>}}
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 {{f|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]].

[[Category:Scripting]]