Kolmafia - User contributions [en]

ASH For Beginners

2010-11-10T17:49:46Z

PhilmASTErpLus: /* Programming */ grammar fix

{{TOCright}}
==File Editing==
To create and edit ASH scripts, you need a text editing program that doesn't automatically add line-breaks for word wrapping.

===Mac===
While the built in editor TextEdit will work fine (as long as you remember to write only in plaintext), [http://www.barebones.com/products/textwrangler/ TextWrangler] is a much more powerful tool. It may not be designed for ASH scripting specifically, but it was written for a similar purpose.

===Linux===
If you use Linux, you probably already know about the options available for text editing. Emacs, Vi, etc. are all fine for creating ASH scripts.

===Windows===
Windows users beware; using Microsoft Word to create ASH files will lead to no end of headaches! The built-in program notepad will work, as can wordpad when configured with the option "No Wrap" for text. However, having a program that can handle syntax-highlighting can be very beneficial. Many scripters recommend [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] for ASH (and other programmatic) scripting. In this case, it's also beneficial to have a style configuration that works well with ASH, and one example can be found [http://kolmafia.us/showthread.php?3164-How-do-you-write-an-ASH-file&p=21567&viewfull=1#post21567 here].

==Saving==
ASH scripts need to be saved with the file extension ".ash" to be properly recognized by KoLmafia. If you're using a built-in text editor on a Windows machine, it may automatically save your files with the ".txt" extension by default. (So you may end up with a file called "script.ash.txt" instead of the desired "script.ash".) One way around this on Windows that usually works is to put quotes around the file name when you save it, including the extension.

Most advanced text editors (such as Notepad++) will save files as specified, without the need for the quotes-trick.

Most files should be saved in the "scripts" directory, which is located by default at the same directory level as the KoLmafia .jar or .exe file on Windows. You can also create a sub-directory under "scripts," and it will be listed in KoLmafia's Scripts Menu.

Relay browser scripts are the exception to the rule: they must be saved in the "relay" directory. Relay browser overrides need to be saved in the top level of "relay," and must be named the same as the page they will override, except with an ".ash" extension. For example, to override "charpane.php" your script would need to be named "charpane.ash". For user-interface scripts, the script name needs to start with "relay_" and end with ".ash". These scripts must also be saved in the top-level of the "relay" directory.

==Programming==
You should first read through the various pages listed under "LANGUAGE CONVENTIONS" on the [[Main Page]]. One should also be aware that, with the exception of [[Control Structures]], all ASH commands need to end with a semi-colon. Also, every identifier in ASH—variables, functions, and other various keywords—are case-insensitive, so <code>string myVar="abb"</code> and <code>STRing MYvar="abb"</code> produce the same results.

===Variables===
Variables are used to hold information that you need to access multiple times. They must be declared before they can be used, by specifying the [[Data Types|Data Type]] that they will hold, followed by the variable name.
{{CodeSample|description=For example:|code=<syntaxhighlight>int count;</syntaxhighlight>}}
would declare a variable named "count" of an integer type. You can also set the initial value of a variable on the same line it is declared.
{{CodeSample|description=On the other hand:|code=<syntaxhighlight>int count = 6;</syntaxhighlight>}}
would declare the variable "count" with an initial value of 6.

Notice that you would not want to have both of the above lines in your script! Variables operate under what's referred to as their scope. In a nutshell, scope defines where a variable is accessible. Scope "cascades" down, similar to stylesheets for those familiar with web programming. A variable declared at the top-level of a script (a "global" variable), outside of any functions, will be accessible anywhere in your script, or in any other scripts that import it. A variable declared inside of a function will be accessible only inside that function (including inside of control structures), but is considered to not exist by other functions. Since ASH uses curly brace scope, variables within a set of curly braces ('''{ }''') will not be available outside that same set of braces.

Declaring a variable multiple times will generate an [[ASH Errors#Variable is already defined|error]]. Note that this only applies to variable with overlapping scope; if one function uses a variable named "bob" that is declared inside of the function, another function can declare another variable with the same name, even as a different datatype. However, the error will still occur if you have a globally-defined variable, and then declare a variable with the same name inside of a function (as their scopes overlap).

===Functions===
Functions are groupings of operations that can be applied multiple times by referencing the function name. Basically, they avoid having to re-type the same code over and over.

====Built-in functions====
Many functions are built-in to KoLmafia, and examples can be found all over this wiki. Examples on the wiki are given in the following format:

datatypeReturned function_name([datatype1 parameter1] ...)

The first part is the datatype that the function returns. Though you don't have to make use of this in a script, you would almost always want to (except for some functions that return a boolean). You need to be careful to match datatypes (though sometimes an implicit conversion is done; ie KoLmafia will usually translate a float into an int, and many commands that output text will implicitly convert from most datatypes). For example, if you have a variable of the datatype string, it is often an error to assign to it a function that returns an item.

The function name follows and then parentheses, which may have nothing or multiple sets of datatypes & parameters.

The parameter names are used for reference on the rest of the page (so you can match descriptions of parameters to the parameter in question, which is especially useful if the function takes more than one parameter with the same datatype).

Note that, as with assignments of a fucntion's return value, it is important to match the parameter datatypes when using the function. If you have a function with the parameter item it, and you supply the name of the item as text in quotes (which is how a string is written), you will get an error for doing so.

====Custom-coded functions====
It's also possible to write your own functions. To do so, you declare them similarly to a variable as above. However, a function can also have the datatype of "void," which is not allowed for variables. A "void" function is one that does not return any value; it simply does what it's programmed to do and the rest of your program moves on, regardless of the results (unless of course an [[ASH Errors|error]] occurs, including a call to [[abort|abort()]].)
{{CodeSample|description=For example, this simple function will double an integer:|code=<syntaxhighlight>
int double_it(int value) {
return 2 * value;
}
</syntaxhighlight>}}
{{CodeSample|description=Furthermore, there are two distinct ways to call functions, user-defined or built-in: Conventional,|code=<syntaxhighlight>
function(param1[,param2,param3,...]);
</syntaxhighlight>}}
{{CodeSample|description=and "Java style":|code=<syntaxhighlight>
param1.function([param2,param3,...]);
</syntaxhighlight>}}
The only difference between the two forms is aesthetics, as they are functionally equivalent.
{{CodeSample|description=Also somewhat important to note is that these commands can be chained together, and they will be executed from left-to-right. So, for instance,|code=<syntaxhighlight>
"polka pop".to_item().to_int()
</syntaxhighlight>}}
{{CodeSample|description=will return the item number for $item[Polka Pop], 4342. This is one instance where "Java style" is more aesthetically pleasing compared to the conventional|code=<syntaxhighlight>
to_int(to_item("polka pop"))
</syntaxhighlight>}}

Note that scope (discussed above, under [[ASH_For_Beginners#Variables|Variables]]) also applies to user-defined functions. Also, functions built into KoLmafia have priority over any user-defined functions with the same name and parameters.

===String Concatenation===
The basics to string concatenation: "Hello" + "world" yields "Helloworld". Likewise, variables can be strung together in this fashion. Unless the variables are both numbers (floats, booleans, or ints), they will be converted to strings, then concatenated. For instance: "3x " + $item[Polka Pop] yields "3x Polka Pop".

[[Category:Scripting]]

Miscellaneous ASH Features

2010-11-10T17:47:37Z

PhilmASTErpLus: /* A little CLI help */ reworded and added ashwiki

{{TOCright}}
==Special Syntax Functions==

'''[[notify]]'''

Used to send a simple kmail to the script's author, letting them know you use their script.

'''[[import]]'''

Used to load an external script into your current one.

'''[[call]]'''

Enables the script writer to invoke a function whose name is known at runtime.

'''[[new]]'''

Constructor function used to populate a record.

==Comments==

Adding '''[[Comments]]''' to your code can make it much easier to maintain, and helps other users understand what's going on.

==Errors==

For help when things go wrong, please see the page on [[ASH Errors]].

==Additional Script Uses==

In addition to regular scripts, relay override scripts, and consult scripts, mafia has a few other hooks for adding event-driven scripts. These situations are listed below, along with the preference that you can set a script name to (in parentheses).

'''Between Battle (betweenBattleScript)'''
*Executed whenever mafia is about to enter a combat. That means before every adventure if auto-adventuring, or before using an item that could lead to combat such as black pudding or drum machine.
*Does not require any special main() declaration.
*This only works for automated adventuring. The script will not fire if you're using the relay browser.
*Example: Zarqon's [http://kolmafia.us/showthread.php?t=1240 Best Between Battle]

'''Buy (buyScript)'''
*Will execute whenever mafia needs to determine if it is to purchase or create an item.
*Requires a special main declaration boolean main(item itm, int qty, int ingredientLevel, boolean defaultBuy). These values will be supplied by mafia when the script is automatically called. A return value of true will instruct mafia to purchase the item and false will cause it to create the item possibly leading to other buy/create decisions.
**''itm'' and ''qty'' specify the item under consideration.
**''ingredientLevel'' indicates what's already available:
***0 = none of the ingredients
***1 = some of them
***2 = enough to create at least one of the requested item
**defaultBuy indicates what KoLmafia would have done otherwise; returning this value is the safest thing your script could do. It will normally be true if ingredientLevel is 0, false if 2. The default at level 1 depends on the item, and is subject to change - normally, anything made with star charts, pixels, the Malus, or multi-use are bought, anything else is created.
*Example: Bale's [http://kolmafia.us/showthread.php?p=18313#post18313 potionBuy].

'''Chatbot (chatbotScript)'''
*Will execute whenever a private message is received
*Requires a special main declaration void main(string sender, string message)
**'sender' is the name of the player who sent the message
**'message' is the message that was sent

'''Counters (counterScript)'''
*Will execute whenever a counter will expire as a result of an intended use of adventures.
*Requires a special main declaration: boolean main(string name, int remain). These values will be supplied by mafia when the script is automatically called and the return value will determine whether mafia continues operation (true) or aborts (false).
**''name'' will be the name of the counter that is about to expire.
**''remain'' is the number of turns remaining before the counter expires. Remain will usually be 0, but may be higher if you are about to multi-create items, adventure underwater, or take a vacation. It may be negative if the counter was informational (one that doesn't abort adventuring), and it actually expired in the middle of an action that used multiple turns at once.
*Example: Bale's [http://kolmafia.us/showthread.php?t=2519 CounterChecker].

'''Login (loginScript)'''
:This script is immediately executed once your character is logged in. Requires no special main() declaration.

'''Logout (logoutScript)'''
:Same as the loginScript, but runs on logout. Note that an [[abort|abort()]] in the script won't stop a logout unless the logout was called in (specific ways, please list).

'''Planting (plantingScript)'''
*This script can be used to manage the mushroom fields, which are available when under a muscle zodiac sign. It runs after logging in, if you have a mushroom field. Main function takes no arguments. Generally should take into account current [[moon phase]] so that it can be started in the middle of a cycle.
*Example: [http://kolmafia.us/showthread.php?563-Modified-mushroom-script-to-produce-3rd-4th-gen-crop&p=7507&viewfull=1#post7507 Sandiman's mushroom planting script].

'''Post-Ascension (postAscensionScript)'''
:Executed at once when your character starts a new ascension. (Example: Bales's [http://kolmafia.us/showthread.php?t=2769 newLife])

'''Pre-Ascension (preAscensionScript)'''
:Executed right before entering Valhalla.

'''Recovery (recoveryScript)'''
*Executed whenever mafia would recover your HP / MP.
*Requires a special main() declaration: boolean main(string type, int amount). These values will be supplied when mafia automatically calls the script, and the return value will instruct mafia if it should attempt to use mafia's default healing after the script concludes.
**''type'' is either "HP" or "MP".
**''amount'' is the desired amount of restoration needed or 0 to use mafia's default recovery level and target.
*Example: Bale's [http://kolmafia.us/showthread.php?t=1780 Universal Recovery]

==A little CLI help==

Three CLI commands are of great use to ASH scripters:
* [[ashref]] allows one to get a list of ASH functions
* [[ash (CLI)|ash]] or [[ash (CLI)|ashq]] allows one to run ASH directly on the CLI.
* [[ashwiki]] allows you to search this wiki by launching a web browser.

==Useful forum threads==
[http://kolmafia.us/showthread.php?523-Did-you-know...-It-s-a-secret-feature.&p=2968&viewfull=1#post2968 This thread], started by holatuwol, is a tidy compilation of various undocumented features in KoLmafia.

[[Category:Scripting]]

ASH For Beginners

2010-11-10T17:29:09Z

PhilmASTErpLus: /* Programming */ Wow, ASH is case-insensitive. *Boggles*

{{TOCright}}
==File Editing==
To create and edit ASH scripts, you need a text editing program that doesn't automatically add line-breaks for word wrapping.

===Mac===
While the built in editor TextEdit will work fine (as long as you remember to write only in plaintext), [http://www.barebones.com/products/textwrangler/ TextWrangler] is a much more powerful tool. It may not be designed for ASH scripting specifically, but it was written for a similar purpose.

===Linux===
If you use Linux, you probably already know about the options available for text editing. Emacs, Vi, etc. are all fine for creating ASH scripts.

===Windows===
Windows users beware; using Microsoft Word to create ASH files will lead to no end of headaches! The built-in program notepad will work, as can wordpad when configured with the option "No Wrap" for text. However, having a program that can handle syntax-highlighting can be very beneficial. Many scripters recommend [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] for ASH (and other programmatic) scripting. In this case, it's also beneficial to have a style configuration that works well with ASH, and one example can be found [http://kolmafia.us/showthread.php?3164-How-do-you-write-an-ASH-file&p=21567&viewfull=1#post21567 here].

==Saving==
ASH scripts need to be saved with the file extension ".ash" to be properly recognized by KoLmafia. If you're using a built-in text editor on a Windows machine, it may automatically save your files with the ".txt" extension by default. (So you may end up with a file called "script.ash.txt" instead of the desired "script.ash".) One way around this on Windows that usually works is to put quotes around the file name when you save it, including the extension.

Most advanced text editors (such as Notepad++) will save files as specified, without the need for the quotes-trick.

Most files should be saved in the "scripts" directory, which is located by default at the same directory level as the KoLmafia .jar or .exe file on Windows. You can also create a sub-directory under "scripts," and it will be listed in KoLmafia's Scripts Menu.

Relay browser scripts are the exception to the rule: they must be saved in the "relay" directory. Relay browser overrides need to be saved in the top level of "relay," and must be named the same as the page they will override, except with an ".ash" extension. For example, to override "charpane.php" your script would need to be named "charpane.ash". For user-interface scripts, the script name needs to start with "relay_" and end with ".ash". These scripts must also be saved in the top-level of the "relay" directory.

==Programming==
You should first read through the various pages listed under "LANGUAGE CONVENTIONS" on the [[Main Page]]. One should also be aware that, with the exception of [[Control Structures]], all ASH commands need to end with a semi-colon. Also, every identifier in ASH—variables, functions, and other various keywords—are case-insensitive, so <code>string myVar="abb"</code> and <code>STRing MYvar="abb"</code> produces the same results.

===Variables===
Variables are used to hold information that you need to access multiple times. They must be declared before they can be used, by specifying the [[Data Types|Data Type]] that they will hold, followed by the variable name.
{{CodeSample|description=For example:|code=<syntaxhighlight>int count;</syntaxhighlight>}}
would declare a variable named "count" of an integer type. You can also set the initial value of a variable on the same line it is declared.
{{CodeSample|description=On the other hand:|code=<syntaxhighlight>int count = 6;</syntaxhighlight>}}
would declare the variable "count" with an initial value of 6.

Notice that you would not want to have both of the above lines in your script! Variables operate under what's referred to as their scope. In a nutshell, scope defines where a variable is accessible. Scope "cascades" down, similar to stylesheets for those familiar with web programming. A variable declared at the top-level of a script (a "global" variable), outside of any functions, will be accessible anywhere in your script, or in any other scripts that import it. A variable declared inside of a function will be accessible only inside that function (including inside of control structures), but is considered to not exist by other functions. Since ASH uses curly brace scope, variables within a set of curly braces ('''{ }''') will not be available outside that same set of braces.

Declaring a variable multiple times will generate an [[ASH Errors#Variable is already defined|error]]. Note that this only applies to variable with overlapping scope; if one function uses a variable named "bob" that is declared inside of the function, another function can declare another variable with the same name, even as a different datatype. However, the error will still occur if you have a globally-defined variable, and then declare a variable with the same name inside of a function (as their scopes overlap).

===Functions===
Functions are groupings of operations that can be applied multiple times by referencing the function name. Basically, they avoid having to re-type the same code over and over.

====Built-in functions====
Many functions are built-in to KoLmafia, and examples can be found all over this wiki. Examples on the wiki are given in the following format:

datatypeReturned function_name([datatype1 parameter1] ...)

The first part is the datatype that the function returns. Though you don't have to make use of this in a script, you would almost always want to (except for some functions that return a boolean). You need to be careful to match datatypes (though sometimes an implicit conversion is done; ie KoLmafia will usually translate a float into an int, and many commands that output text will implicitly convert from most datatypes). For example, if you have a variable of the datatype string, it is often an error to assign to it a function that returns an item.

The function name follows and then parentheses, which may have nothing or multiple sets of datatypes & parameters.

The parameter names are used for reference on the rest of the page (so you can match descriptions of parameters to the parameter in question, which is especially useful if the function takes more than one parameter with the same datatype).

Note that, as with assignments of a fucntion's return value, it is important to match the parameter datatypes when using the function. If you have a function with the parameter item it, and you supply the name of the item as text in quotes (which is how a string is written), you will get an error for doing so.

====Custom-coded functions====
It's also possible to write your own functions. To do so, you declare them similarly to a variable as above. However, a function can also have the datatype of "void," which is not allowed for variables. A "void" function is one that does not return any value; it simply does what it's programmed to do and the rest of your program moves on, regardless of the results (unless of course an [[ASH Errors|error]] occurs, including a call to [[abort|abort()]].)
{{CodeSample|description=For example, this simple function will double an integer:|code=<syntaxhighlight>
int double_it(int value) {
return 2 * value;
}
</syntaxhighlight>}}
{{CodeSample|description=Furthermore, there are two distinct ways to call functions, user-defined or built-in: Conventional,|code=<syntaxhighlight>
function(param1[,param2,param3,...]);
</syntaxhighlight>}}
{{CodeSample|description=and "Java style":|code=<syntaxhighlight>
param1.function([param2,param3,...]);
</syntaxhighlight>}}
The only difference between the two forms is aesthetics, as they are functionally equivalent.
{{CodeSample|description=Also somewhat important to note is that these commands can be chained together, and they will be executed from left-to-right. So, for instance,|code=<syntaxhighlight>
"polka pop".to_item().to_int()
</syntaxhighlight>}}
{{CodeSample|description=will return the item number for $item[Polka Pop], 4342. This is one instance where "Java style" is more aesthetically pleasing compared to the conventional|code=<syntaxhighlight>
to_int(to_item("polka pop"))
</syntaxhighlight>}}

Note that scope (discussed above, under [[ASH_For_Beginners#Variables|Variables]]) also applies to user-defined functions. Also, functions built into KoLmafia have priority over any user-defined functions with the same name and parameters.

===String Concatenation===
The basics to string concatenation: "Hello" + "world" yields "Helloworld". Likewise, variables can be strung together in this fashion. Unless the variables are both numbers (floats, booleans, or ints), they will be converted to strings, then concatenated. For instance: "3x " + $item[Polka Pop] yields "3x Polka Pop".

[[Category:Scripting]]

Custom Combat Script

2010-10-13T08:16:35Z

PhilmASTErpLus: /* Legal commands are */ Added some more commands found at http://kolmafia.sourceforge.net/combat.html and renamed section to be more "formal".

{{TOCright}}
== Basic CCS ==
A Custom Combat Script (CCS) is a way of instructing mafia how to handle combat, round by round. For example, a simple CCS would be to tell mafia to pickpocket on round 1, then cast entangling noodles on round 2 and finally on rounds 3+ to use shieldbutt. If it is unable to carry out one of those steps, then that step will be skipped. For instance, if the character failed to get initiative, then pickpocket will be skipped and the character will go straight to entangling noodles. That CCS would look like this:

<div style="border: solid 1px black; padding: 1em; margin:0px 20px;">
[ default ] 
try to steal an item 
skill entangling noodles 
skill shieldbutt 
</div>

If you wanted to treat different monsters differently, that can be accommodated also. For instance, the following CCS will attempt to cast Transcendent Olfaction upon Black Knights while treating all other monsters differently. If the character currently has "On the Trail" then that line will be skipped.

<div style="border: solid 1px black; padding: 1em; margin:0px 20px;">
[ Black Knight ] 
try to steal an item 
skill transcendent olfaction 
skill entangling noodles 
skill shieldbutt 

[ default ] 
try to steal an item 
skill entangling noodles 
skill shieldbutt 
</div>

Note that when you use a CCS, your CLI will report "character executes a macro!" because the CCS is converted into a macro to save on page loads

=== Available Commands ===
* attack
* skill
* item, use
* try to steal an item, pickpocket
* summon pastamancer ghost
* jiggle chefstaff
* combo {followed by one of the following}
** Disco Concentration, Disco Nirvana, Disco Inferno, Disco Bleeding, Disco Blindness
** Rave Knockout, Rave Bleeding, Rave Concentration, Rave Steal, Rave Nirvana, Rave Stats
* abort
* abort after
* section [section name]
* special
* delevel
* skip
* note
* twiddle

== Macros in CCS ==
Macros may be used in a Custom Combat Script in addition to the basic commands. Any line in quotes and any macro command used in a CCS will be made into part of the macro which KoLmafia is passing to KoL. You can find an primer on all KoL's macros at {{kolwiki|Combat Macros}}.

Also there is a section in the CCS called "global prefix" which will be part of every combat macro KoLmafia generates, regardless of the monster encountered.

=== Example of CCS Macro ===
Here's an example of a CCS that generates a macro which will cause KoL to wait for a hobo monkey to steal meat from your enemy before launching attacks.
<div style="border: solid 1px black; padding: 1em; margin:0px 20px;">
[ default ] 
sub monkey_stasis 
:while !match "climbs up and sits on your shoulder" && !pastround 20 && !hppercentbelow 20
::call stasis_item
:endwhile
endsub 
call monkey_stasis 
attack

[ global prefix ] 
scrollwhendone 
"abort missed 5" 
"abort pastround 27" 
sub stasis_item 
:if hascombatitem facsimile dictionary
::item facsimile dictionary
::goto _endstasisitem
:endif
:if hascombatitem seal tooth
::item seal tooth
::goto _endstasisitem
:endif
:if hascombatitem spices
::item spices
::goto _endstasisitem
:endif
:if hascombatitem spectre scepter
::item spectre scepter
::goto _endstasisitem
:endif
:if hascombatitem dictionary
::item dictionary
::goto _endstasisitem
:endif
:if hascombatitem fat stacks of cash
::item fat stacks of cash
::goto _endstasisitem
:endif
:"abort "No infinite use items detected!" "
:mark _endstasisitem
endsub 
sub stasis 
:while !pastround 20 && !hppercentbelow 20 && mppercentbelow 99
::call stasis_item
:endwhile
endsub
</div>

=== Concerns for macros in CCS ===
*A macro's abort command needs to be encased in quotes because abort is also a legal CCS command. That's why all aborts in the previous example were quoted.

*If a comment is the last line in a CCS, that will be used as your finishing attack even though it does nothing. Never conclude a CCS with a macro comment or it will abort to the mini-browser with a warning from KoL that you executed 37 commands in a row without taking an action.

== Consult Scripts ==
While this may seem reasonably flexible, sometimes you will want to do something too complicated to express in this format. For instance if you want your character to take different actions based on your characters current stats or current monster level, a consult script can automatically figure it out. There are few limits to what a consult script can enable. The downside to using a consult script is that KoLmafia will not be able to generate a combat macro to pass to KoL. As a result multi-round combat will take somewhat longer.

A consult script is called by using the "consult" command in your CCS, as follows:

<div style="border: solid 1px black; padding: 1em; margin:0px 20px;">
[ default ] 
consult myscript.ash 
attack 
</div>

The main() function in the ASH script being consulted must accept three parameters:

void main(int round, monster mob, string combat)

These values will be supplied by mafia when the consult script is called.

=== Example of a Consult Script ===
This example will attempt to maximize use of a Sauceror's spells as a Sauceror by making use of sauce splash effects when they can be used.
<div style="margin-bottom: 1em; border: dashed 1px green; padding: 1em; margin:0px 20px;"><syntaxhighlight>
// Save this as SauceSplash.ash
boolean sauceSplash() {
if(!(have_effect($effect[Jabañero Saucesphere]) >0
|| have_effect($effect[Jalapeño Saucesphere]) >0))
return false;
int normal = numeric_modifier("spell damage");
if(normal >= 25)
return true;
int cold = numeric_modifier("cold spell damage");
int hot = numeric_modifier("hot spell damage");
if(have_skill($skill[Immaculate Seasoning])
&& cold != hot && max(cold, hot) + normal >= 25)
return true;
if(monster_element() == $element[cold] && cold + normal >= 25
&& (have_skill($skill[Immaculate Seasoning])
|| have_equipped($item[Gazpacho's Glacial Grimoire])))
return true;
if(monster_element() == $element[hot] && hot + normal >= 25
&& (have_skill($skill[Immaculate Seasoning])
|| have_equipped($item[Codex of Capsaicin Conjuration])
|| have_equipped($item[Ol' Scratch's manacles])
|| (have_equipped($item[Ol' Scratch's ash can]) && my_class() == $class[Sauceror])))
return true;
return false;
}

void main(int initround, monster foe, string page) {
if(have_effect($effect[Burning Soul]) || have_effect($effect[Soul Freeze]) || !sauceSplash())
use_skill($skill[Saucegeyser]);
else
use_skill($skill[Wave of Sauce]);
}
</syntaxhighlight></div>

This consult script can then be integrated into a CCS like this:
<div style="border: solid 1px black; padding: 1em; margin:0px 20px;">
[ default ] 
consult SauceSplash.ash 
attack 
</div>

=== Parts of a Combat Consultation Script ===
As you can see in the above example, a consultation script is called with three parameters.
*The first parameter is the round of combat that the script is called. Sometimes it is important to keep track of the round. This is particularly important to keep from losing the fight by going over 30 rounds.
*The second parameter is the monster that you are fighting. This is important because it enables you to take different actions for different monsters.
*The third parameter is the text of the page. This is important because it enables you to examine every detail of the fight as it is taking place. It can be analyzed for potential actions, damage that you deal to a monster and all other events.

All possible actions you can take in a round of combat are listed under [[In-combat Consulting]].

=== Resolution of a Combat Consultation Script ===
The consult script can automate as many, or as few rounds of combat as desired to achieve its goal. When it finishes executing, if the monster is not yet dead, then the CCS will continue combat from the current round. Note that the current round is not always the next line in a script. For instance, if the consult script is called at round 1 and executes three actions, then it will return to the CCS at round 4. This is why most CCSs containing consult script prefer to have only a line after the consult script, usually a simple method of killing a monster.

== Employ Scripts ==
<div style="padding: 1em; border: solid 1px red; color: red; font-weight: bold;">Please note! This section is speculative; Employ Scripts have not yet been implemented.</div>
An employ script is a like a consultation script, with benefits. While a consultation script operates turn-by-turn, an employ script operates only at the beginning of the combat and generates a combat macro.

Employ scripts do not yet exist in KolMafia at this time, but they are a goal that jasonharper is working towards as he [http://kolmafia.us/showthread.php?4098-Dynamic-Combat-in-the-Age-of-Macros describes on the mafia forum].

It is currently proposed that they will have the following format:

'''string main( string opponent, string pageText, string macroSoFar, string parameter )'''

* opponent is the name of the monster being fought, just as in a consult script or combat filter function.
* pageText is the raw HTML of the initial combat page. This isn't necessarily going to be useful (since it's a one-time snapshot), however you may want to examine the Skills popup to see what conditionally-available skills are actually available.
* macroSoFar is the current text of the macro being built - a mafia-generated header with some useful subroutines defined, followed by macro translations of all the prior lines in the CCS.
* parameter contains any extra text from the CCS line; it could be used to customize the behavior of the script, more conveniently than using a "note" line with a consult script. It also serves the less obvious purpose of making the parameter count something other than 3, so that mistakenly attempting to employ a consult script, or consult an employ script, will fail before any code runs.
* The return value entirely replaces the macro being built. It would probably be an error for this to be any shorter than the original value of macroSoFar.

The simplest thing an employ script could do is to append some commands to macroSoFar, and return that. Other possibilities include:
* It could look back through the previously-generated macro commands to decide what to do. For example, it could refrain from adding a "pickpocket" action if that has already been done
* If it wanted to set up a global abort condition, active throughout the combat, it could insert the command at the beginning of the macro.
* There will be a subroutine called "mafiaround" defined in the header, and called before every combat action to handle things like automatic antidote use. The script could insert commands into that subroutine, for example to implement an eye color check for using He-Boulder major rays.
* There will likely be other defined subroutines for the script to call or modify.

[[Category:Scripting]]

Monster element

2010-10-04T02:59:54Z

PhilmASTErpLus: Added a dumb code sample...critics welcome!

{{
#vardefine:name|monster_element}}{{
#vardefine:return_type|element}}{{

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

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

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|monster|check_me}}|
p1desc={{Pspan|check_me}} is the (optional) monster to get the elemental alignment of|
}}|
function_description=Returns the elemental alignment of the specified monster {{pspan|check_me}}. If {{pspan|check_me}} is not specified, it defaults to the last monster you encountered.
This function can be used from within an [[In-combat Consulting]] script to help determine your fight strategy. When used this way, it isn't necessary to specify a monster, as the function will default to the one currently being fought.|

code1={{CodeSample|
title=Sample Code|
description=This example attempts to find element(s) that the monster being fought right now is weak against.|
code=<syntaxhighlight>
boolean [element] weak_elements;

switch (monster_element())
{
case $element[cold]: weak_elements = $element[spooky, hot]; break;
case $element[spooky]: weak_elements = $element[hot, stench]; break;
case $element[hot]: weak_elements = $element[stench, sleaze]; break;
case $element[stench]: weak_elements = $element[sleaze, cold]; break;
case $element[sleaze]: weak_elements = $element[cold, spooky]; break;
}
</syntaxhighlight>
}}|

see_also={{SeeAlso|monster_attack|monster_defense|monster_hp}}|
special=If no monster is specified and no monster has been fought in this session, this function returns $element[none]. This is because mafia forgets the value of [[last_monster|last_monster()]] when it logs out.|
}}

[[Category:Adventuring]]|[[Category:In-combat Consulting]]

Tips, Tricks and Workarounds

2010-10-01T07:02:06Z

PhilmASTErpLus: Added 1-liner page intro and Offline Testing seciton

{{TOCright}}

This page contains various tips and tricks that may help you in using KoLmafia and writing scripts.

==Free Pulls==

KoLmafia considers free pulls as completely separate from other items in Hangks. Because there is no resource being consumed by pulling them, they do not use the functions involved in pulls, specifically {{f|storage_amount}} and {{f|take_storage}}.

To find the quantity of a free pull in Hangks, such as a brick you need to use {{f|available_amount}}. To remove a free pull item from Hangks you need to use {{f|retrieve_item}}.

== Anonymous closures ==

{{CodeSample|description=ASH does not seem to accept anonymous closures by default. This is an example of an anonymous closure.|
code=<syntaxhighlight>
int var1;
/* Do stuff */
{
int var1;
call_some_function();
/* Do other stuff */
}
</syntaxhighlight>}}

{{CodeSample|description=However, you can use a workaround with a if-clause like the following example.|
code=<syntaxhighlight>
int var1;
/* Do stuff */
if (true)
{
int var1;
/* Do other stuff */
}
</syntaxhighlight>}}
As for where stuff like this could be used... It can initialize ASH scripts without creating any unnecessary functions or variables in the "namespace". Not everyone's cup of tea, but at least you know.

== Capturing an Abort ==

By default, whenever an ASH function returns false, everything will abort ''unless'' you somehow capture the return value (i.e. assigning it to a variable or enclosing it in a control structure). So, if you want to make use of, say, the hermit() function in a way that won't abort if the function returns false, you could:
<div style="margin-bottom: 1em; padding: 1em; margin:0px 20px;">
{{CodeSample|
description=Save the result as a boolean variable.|
code=<syntaxhighlight>
boolean fakeBool = hermit(1, $item[Ten-leaf clover]);
</syntaxhighlight>}}
{{CodeSample|
description=Capture the result in an if() conditional.|
code=<syntaxhighlight>
if(!hermit(1, $item[Ten-leaf clover])) print("Hermit looting failed: continuing on.");
</syntaxhighlight>}}
{{CodeSample|
description=An if() conditional doesn't even have to do anything.|
code=<syntaxhighlight>
if(hermit(1, $item[Ten-leaf clover])) {}
</syntaxhighlight>}}
{{CodeSample|
description=The most minimalistic method is to capture it with a not operator and parenthesis.|
code=<syntaxhighlight>
(!hermit(1, $item[Ten-leaf clover]));
</syntaxhighlight>}}
</div>

Any of these will capture the return value and prevent mafia from aborting.

== Syntax Highlighting for Notepad++ ==

== Testing Scripts Offline ==

Because KoLmafia CLI and ASH are interpreted, it is impossible to know whether there are any errors in your scripts until you run it. If you want to check only the syntax of the script, you can run it without logging in. From the top menu of the login pane, select "General", then "Graphical CLI". The CLI (and the rest of the mafia interface) will appear, and running scripts will properly validate them. Note that because you are not logged in, any functions or commands that use or interact with KoL will not work. Thus, testing scripts this way will not reveal any KoL-related logical errors.

[[Category:Scripting]]

ASH For Beginners

2010-09-27T23:19:32Z

PhilmASTErpLus: It bothers me that several articles have top-level section headings using <h1>, not <h2>. Unless there is a specific reason for this, I will correct them whenever I see one.

{{TOCright}}
==File Editing==
To create and edit ASH scripts, you need a text editing program that doesn't automatically add line-breaks for word wrapping.

===Mac===
While the built in editor TextEdit will work fine (as long as you remember to write only in plaintext), [http://www.barebones.com/products/textwrangler/ TextWrangler] is a much more powerful tool. It may not be designed for ASH scripting specifically, but it was written for a similar purpose.

===Linux===
If you use Linux, you probably already know about the options available for text editing. Emacs, Vi, etc. are all fine for creating ASH scripts.

===Windows===
Windows users beware; using Microsoft Word to create ASH files will lead to no end of headaches! The built-in program notepad will work, as can wordpad when configured with the option "No Wrap" for text. However, having a program that can handle syntax-highlighting can be very beneficial. Many scripters recommend [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] for ASH (and other programmatic) scripting. In this case, it's also beneficial to have a style configuration that works well with ASH, and one example can be found [http://kolmafia.us/showthread.php?3164-How-do-you-write-an-ASH-file&p=21567&viewfull=1#post21567 here].

==Saving==
ASH scripts need to be saved with the file extension ".ash" to be properly recognized by KoLmafia. If you're using a built-in text editor on a Windows machine, it may automatically save your files with the ".txt" extension by default. (So you may end up with a file called "script.ash.txt" instead of the desired "script.ash".) One way around this on Windows that usually works is to put quotes around the file name when you save it, including the extension.

Most advanced text editors (such as Notepad++) will save files as specified, without the need for the quotes-trick.

Most files should be saved in the "scripts" directory, which is located by default at the same directory level as the KoLmafia .jar or .exe file on Windows. You can also create a sub-directory under "scripts," and it will be listed in KoLmafia's Scripts Menu.

Relay browser scripts are the exception to the rule: they must be saved in the "relay" directory. Relay browser overrides need to be saved in the top level of "relay," and must be named the same as the page they will override, except with an ".ash" extension. For example, to override "charpane.php" your script would need to be named "charpane.ash". For user-interface scripts, the script name needs to start with "relay_" and end with ".ash". These scripts must also be saved in the top-level of the "relay" directory.

==Programming==
You should first read through the various pages listed under "LANGUAGE CONVENTIONS" on the [[Main Page]]. One should also be aware that, with the exception of [[Control Structures]], all ASH commands need to end with a semi-colon.

===Variables===
Variables are used to hold information that you need to access multiple times. They must be declared before they can be used, by specifying the [[Data Types|Data Type]] that they will hold, followed by the variable name.
{{CodeSample|description=For example:|code=<syntaxhighlight>int count;</syntaxhighlight>}}
would declare a variable named "count" of an integer type. You can also set the initial value of a variable on the same line it is declared.
{{CodeSample|description=On the other hand:|code=<syntaxhighlight>int count = 6;</syntaxhighlight>}}
would declare the variable "count" with an initial value of 6.

Notice that you would not want to have both of the above lines in your script! Variables operate under what's referred to as their scope. In a nutshell, scope defines where a variable is accessible. Scope "cascades" down, similar to stylesheets for those familiar with web programming. A variable declared at the top-level of a script (a "global" variable), outside of any functions, will be accessible anywhere in your script, or in any other scripts that import it. A variable declared inside of a function will be accessible only inside that function (including inside of control structures), but is considered to not exist by other functions. Since ASH uses curly brace scope, variables within a set of curly braces ('''{ }''') will not be available outside that same set of braces.

Declaring a variable multiple times will generate an [[ASH Errors#Variable is already defined|error]]. Note that this only applies to variable with overlapping scope; if one function uses a variable named "bob" that is declared inside of the function, another function can declare another variable with the same name, even as a different datatype. However, the error will still occur if you have a globally-defined variable, and then declare a variable with the same name inside of a function (as their scopes overlap).

===Functions===
Functions are groupings of operations that can be applied multiple times by referencing the function name. Basically, they avoid having to re-type the same code over and over.

====Built-in functions====
Many functions are built-in to KoLmafia, and examples can be found all over this wiki. Examples on the wiki are given in the following format:

datatypeReturned function_name([datatype1 parameter1] ...)

The first part is the datatype that the function returns. Though you don't have to make use of this in a script, you would almost always want to (except for some functions that return a boolean). You need to be careful to match datatypes (though sometimes an implicit conversion is done; ie KoLmafia will usually translate a float into an int, and many commands that output text will implicitly convert from most datatypes). For example, if you have a variable of the datatype string, it is often an error to assign to it a function that returns an item.

The function name follows and then parentheses, which may have nothing or multiple sets of datatypes & parameters.

The parameter names are used for reference on the rest of the page (so you can match descriptions of parameters to the parameter in question, which is especially useful if the function takes more than one parameter with the same datatype).

Note that, as with assignments of a fucntion's return value, it is important to match the parameter datatypes when using the function. If you have a function with the parameter item it, and you supply the name of the item as text in quotes (which is how a string is written), you will get an error for doing so.

====Custom-coded functions====
It's also possible to write your own functions. To do so, you declare them similarly to a variable as above. However, a function can also have the datatype of "void," which is not allowed for variables. A "void" function is one that does not return any value; it simply does what it's programmed to do and the rest of your program moves on, regardless of the results (unless of course an [[ASH Errors|error]] occurs, including a call to [[abort|abort()]].)
{{CodeSample|description=For example, this simple function will double an integer:|code=<syntaxhighlight>
int double_it(int value) {
return 2 * value;
}
</syntaxhighlight>}}
{{CodeSample|description=Furthermore, there are two distinct ways to call functions, user-defined or built-in: Conventional,|code=<syntaxhighlight>
function(param1[,param2,param3,...]);
</syntaxhighlight>}}
{{CodeSample|description=and "Java style":|code=<syntaxhighlight>
param1.function([param2,param3,...]);
</syntaxhighlight>}}
The only difference between the two forms is aesthetics, as they are functionally equivalent.
{{CodeSample|description=Also somewhat important to note is that these commands can be chained together, and they will be executed from left-to-right. So, for instance,|code=<syntaxhighlight>
"polka pop".to_item().to_int()
</syntaxhighlight>}}
{{CodeSample|description=will return the item number for $item[Polka Pop], 4342. This is one instance where "Java style" is more aesthetically pleasing compared to the conventional|code=<syntaxhighlight>
to_int(to_item("polka pop"))
</syntaxhighlight>}}

Note that scope (discussed above, under [[ASH_For_Beginners#Variables|Variables]]) also applies to user-defined functions. Also, functions built into KoLmafia have priority over any user-defined functions with the same name and parameters.

===String Concatenation===
The basics to string concatenation: "Hello" + "world" yields "Helloworld". Likewise, variables can be strung together in this fashion. Unless the variables are both numbers (floats, booleans, or ints), they will be converted to strings, then concatenated. For instance: "3x " + $item[Polka Pop] yields "3x Polka Pop".

[[Category:Scripting]]

Print

2010-09-26T12:33:52Z

PhilmASTErpLus: Reverted to line breaks. I have yet to understand how wiki markup works with templates...

{{
#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|logprint|print_html}}|
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=Using an invalid color name or code can cause odd colors to be chosen; see the [[Talk:Print|Talk Page]] for details.
 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]]

Print

2010-09-26T12:32:08Z

PhilmASTErpLus: Formatting - abandoned line breaks for unordered lists.

{{
#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|logprint|print_html}}|
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=
*Using an invalid color name or code can cause odd colors to be chosen; see the [[Talk:Print|Talk Page]] for details.
*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]]

Print

2010-09-26T12:30:19Z

PhilmASTErpLus: Added info about the [print("/write a blank string instead of this text")] bug.

{{
#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|logprint|print_html}}|
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=
Using an invalid color name or code can cause odd colors to be chosen; see the [[Talk:Print|Talk Page]] for details.
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]]

Talk:Tips, Tricks and Workarounds

2010-09-26T12:18:12Z

PhilmASTErpLus: /* Quirks & Hacks from PhilmASTErpLus */ How about moving the information about print() to the function's page?

__TOC__

== Discussion Recap ==

=== Discussion from [[Talk:Storage amount]] ===

Can anyone else verify, before I edit it in, that this function doesn't work on free pulls? --[[User:StDoodle|StDoodle (#1059825)]] 11:45, 21 September 2010 (UTC)

Verified. I believe that this was reported as a bug once. (Back when we had that awesome bug tracker.) However this behavior was clarified to be working as intended and hence, not a bug. The fact that an itemd doesn't require a pulls means that it is supposed to be treated differently. Use {{f|available_amount}} minus {{f|item_amount}} to verify presence of free pulls in Hangks. Then get them into inventory with {{f|retrieve_item}} instead of with {{f|take_storage}}. You're right that info should probably be on all relevant pages. --[[User:Bale|Bale]] 05:17, 22 September 2010 (UTC)

Perhaps we should start a special "caveats" page, and link to subheadings on it, for such info; it seems a bit much may be required to explain the situation to include it on every page. It would also be a good place to put info on things like Between Battle Scripts and adventure count in automation, etc. Thoughts? --[[User:StDoodle|StDoodle (#1059825)]] 15:10, 22 September 2010 (UTC)

I favor a caveats page. Or perhaps we could call it Tricks & Tips. We should add [[User:PhilmASTErpLus#ASH_Quirks_and_Hacks|THIS]] there also. --[[User:Bale|Bale]] 22:22, 22 September 2010 (UTC)

Tips, Tricks and Workarounds* sounds good to me. I agree that those items philmaterplus points out should go there. Also, we should clean up the FAQ to only include one example of non-aborting booleans, and move the full list to this new page, I think (with a link of course). Perhaps this would even be a good page to put a dedicated file link to the syntax highlighting scheme for Notepadd++ (I favor having it on the wiki, so when it's updated with new ash functions, it's... you know, updated). I'll come up with other ideas, too, and leave them on the talk page when it's there. --[[User:StDoodle|StDoodle (#1059825)]] 17:04, 23 September 2010 (UTC)

*Actually it doesn't sound perfect, which is why I'm not making it yet... hrmph.

Moving Discussion to [[Talk: Tips, Tricks and Workarounds]]. Since there may be a bit of discussion about the page before it gets created properly. We can always move the talk page if we change our minds about what it should be called. --[[User:Bale|Bale]] 21:18, 23 September 2010 (UTC)

=== Quirks & Hacks from [[User:PhilmASTErpLus|PhilmASTErpLus]] ===

*{{f|print}} displays a blank line when given a string starting with a slash (<code>/</code>). To prevent this, the text color must be explicitly given. Easy to bypass, but weird.
*"Anonymous" closures: ASH does not seem to accept anonymous closures by default.
{{CodeSample|code=<syntaxhighlight>
int var1;
/* Do stuff */
{
int var1;
call_some_function();
/* Do other stuff */
}
</syntaxhighlight>}}
However, you can use a workaround with a if-clause.
{{CodeSample|code=<syntaxhighlight>
int var1;
/* Do stuff */
if (true)
{
int var1;
/* Do other stuff */
}
</syntaxhighlight>}}
As for where stuff like this could be used...I'm using it for initializing ASH scripts without creating any unnecessary functions or variables in the "namespace".

:Great work so far, guys. One nitpick, though: I think the tip about using print() should be put in {{print|the appropriate function page}}, instead. I'll add it there ASAP. --[[User:PhilmASTErpLus|PhilmASTErpLus]] 12:18, 26 September 2010 (UTC)

== New Discussion ==

Ugh, sorry. Can't think of the best way to fix that ATM, it was half a joke. (Note to self; don't edit wiki drunk.) --[[User:StDoodle|StDoodle (#1059825)]] 06:32, 24 September 2010 (UTC)

Import

2010-09-16T20:44:48Z

PhilmASTErpLus: Reworded--automatic "#pragma once" feature is not only important for name collisions, but also for preventing a script from being executed multiple times. Also, it's okay to remove 'Formatting Needed

{{DISPLAYTITLE:import}}
'''import <filename>'''

'''Import''' is a command that is used to import (hence the name) an entire file's contents into the file in which '''import''' is called. "Nested" imports are possible; a script that is being imported may import another script. If a single file is imported more than once, KoLmafia will not import that file again. Note that when a script that has a <code>main()</code> function is imported into another script with another <code>main()</code> function, only the primary script's <code>main()</code> is executed, and all <code>main()</code> functions from imported scripts will be ignored. However, any of the imported top-level commands will be executed and all of the imported global variables will be accessible to the primary script. An import can only be used as a top-level command; attempting to import another script inside a closure (e.g. a function or a loop) will result in an error.

Because '''import''' looks inside the /scripts directory and all its subfolders for the given script name, moving your scripts around inside the /scripts directory will not affect other scripts that rely on them. If there are multiple scripts with the same file name, KoLmafia will use the first script found. You can use your OS-specific directory path separators (usually slashes(/) and backslashes(\)) to explicitly '''import''' a script inside a subdirectory.

==Example==


{{CodeSample|code=<syntaxhighlight>
# snippet from my aftercore.ash file
import <lib/utilities.ash> // import a utility function library in the scripts/lib/ directory
import <aftercore_config.ash> // import the configuration file (loaded with variables) into the script
import <aftercore_bounty.ash> // import bounty functionality (loaded with functions) into the script

int first_meat = my_meat();
int first_advs = my_adventures();
boolean using_upcs_curr = false;

# ...
</syntaxhighlight>}}

[[Category:Scripting]]

Alias

2010-09-16T20:32:39Z

PhilmASTErpLus: Expanded general how-to on aliases.

{{DISPLAYTITLE:alias}}
Creates a new alias in the KoLmafia CLI or displays the list of registered aliases.
An alias is a shortcut for complex CLI command(s) that are too long to type every time you want to. To create a new alias, type
alias ''[alias_name]'' => ''[actual_command]''
into the CLI, where <code>''[alias_name]''</code> and <code>''[alias_command]''</code> are replaced with the shortcut string you want to use and the actual command string. For example, to create an alias "f" for the <code>[[familiar]]</code> CLI command, type:
<pre>alias f => familiar</pre>
Now, instead of typing <code>familiar pixie</code> or <code>familiar sandworm</code>, you can just type <code>f pixie</code> or <code>f sandworm</code>.

To see the list of aliases that you have created so far, type <code>alias</code> into the CLI without any arguments.

Aliases are preserved across multiple characters. You can remove existing aliases by using the <code>[[unalias]]</code> command.

== Complex Examples ==

<pre>alias dentures => checkpoint; equip frilly skirt; ash visit_url("inv_use.php?which=3&whichitem=2951&pwd"); visit_url("choice.php?whichchoice=188&option=3&choiceform3=Catburgle&pwd"); cli_execute("outfit checkpoint");</pre>

This equips a frilly skirt, chooses the right choice in the Orcish Frat House Blueprints adventure, and then re-equips whatever pants you had on when you type ''dentures'' into the CLI.

[[Category:CLI Commands]]

KoLmafia Guide: Eating & Drinking

2010-09-16T20:11:59Z

PhilmASTErpLus: Minor grammar nitpicks and slight rewording to reflect recent food update.

This lesson covers managing and creating food, drink, and spleen-damaging items with Mafia. Eating and drinking in KoL's native interface sucks. As a new player you have no clue what most of the items do, and their description is only somewhat helpful and lacking in any concrete info in adventures gained or fullness used. Digging through the wiki for every item is time-consuming and irritating.
Once you get into recipes for creating food and booze, it becomes very difficult to get anything done without tons of wiki studying. You will master several common recipes but will likely overlook a lot of food and drinks you '''could''' make because you don't have them in mind.

Mafia does a lot to address this and help you automate and keep track of your consumption. In this lesson, we will attempt to make and consume some drinks.

# We are going to make some drinks. I am assuming that you have at least '''some''' stuff in your inventory that you can use to make drinks, AND you are not almost-drunk already. Go ahead and use advanced cocktail to summon Ice Cubes, etc if you can do so. Note that breakfast will do this for you.
# Click the top icon that looks like a backpack, or from the main menubar under General, select Item Manager.
#: [[File:Lesson11 topicons.png]]
# This is a big interface. On the left hand side, amongst the long list of stuff, under Usable, click on Booze. I recommend that you click the checkbox labeled "per drunk" to sort it with the highest quality booze at the top.
#:[[File:Lesson11 manager.png]]
# The screen is split into a top half and a bottom half. The bottom half contains a scrollpanel which has listings of booze, sorted by the quality of the beverage. Note that each drink has complete info as to stats and adventures per inebriation all spelled out. It's really awesome!
# You will notice that each drink has a number in parenthesis for Possible and Current. The Current number is how many of that drink you really have in your inventory. Possible is how many you COULD have, by mixing, buying, etc. When the Potential number is the same as the Actual, this means you have all of that drink that you could with your current state of inventory.
# You can click the 'No Create' checkbox which will then only show drinks you have in your inventory, vs showing all drinks you could conceivably make. Consider though that Mafia '''does'' adjust the quality of created drinks based on the number of turns needed to create them. For example, you will notice that your adventures per drunk increase for all your mixed drinks when you have a bartender-in-a-box. Especially the 1 and 2 drunkenness drinks since spending a turn to make a 1 drunk drink is much worse than 1 turn to make a 4 drunk one. The Per-Drunk checkbox should be active as Adventures per Drunk point are a much more useful measurement than total adventures.
# Going through the scrollbar, find the highest drink where you have more Possible than Current. This means you can make this drink. Select it and click Enqueue. It will ask how many to enqueue. It defaults to the difference between how many you have and can have, up to how much you can actually consume. In other words, if you have 3 martinis and 2 olive/gin, then it will default to enqueueing 2.
# Now, that drink goes to the Top of your screen's panel. Notice that the tab now shows how much Drunkenness you have enqueued. You can click the Ingredients Used tab to show exactly what the drink consists of. This is particularly useful for both food and drink as you want to keep a tight rein on your Spices in many cases. You also would probably not want to waste a precious Lime making a margarita with training wheels when you could make a Key Lime pie instead!
#:[[File:Lesson11 queue.png]]
# Click the Create button. It will now mix that drink for you. Depending on the settings it may even automatically create a bartender-in-a-box to ensure that it doesn't cost any turns. See below for how to do that!
# That drink now disappears from the top box and now your Current number has gone up for that drink. It made that drink for you.
# '''In-a-box feature:''' In the item manager, under Creatable, there are checkboxes to ensure Mafia will '''only''' create food/drink using a in-a-box from your campsite and another to automatically create an in-a-box when you lack one or it breaks. This is nice in that it ensures that you will not use up precious turns. It is also very helpful when your in-a-Box breaks and Mafia doesn't have enough parts to reassemble it. In which case, you would normally use up turns when cooking/mixing. With this feature active you would all the sudden notice all your recipes disappear from mafia, which would alert you that something is amiss. However, it is very important that you turn this feature off when you ascend! The reason being that Mafia will simply not show any recipes until you make the appropriate in-a-box, which might be a while during hardcore. In the meantime you are left wondering why can't make any drinks! Note that if you do not have sufficient parts to create the in-a-box, you might want to change your preferences temporarily to allow Mafia to purchase from the mall. Mafia will then buy what it needs in order to assemble it in the ''cheapest manner possible'' if not in ronin/hardcore.
#:[[File:Lesson11 in-a-boxen.png]]
# You will probably wanna go ahead and drink. Use any booze-booster like the Ode to Booze buff or whatever first. Then, assuming you have a max drunkenness of 15 (the default), enqueue 14 drunkenness worth of your best booze. You can Consume directly if desired, but I prefer to queue it all up first and make it. It is usually a good idea to make all your booze and food first, then consume it. This ensures that if you must use turns to create something that it won't mess up your Ode to Booze or Milk of Magnesium. Nothing is worse than using those then running out of buff turns while making all the consumables!
# The top box will populate with your booze and auto-count the intoxication, warning you if you are about to overdrink. Click Consume when ready and it will drink.
# Exit the Inventory Manager, click the CGI Graphical tab and look at the log. See what all it really did for you behind the scenes. You might see that it bought a fruit from a hippy (by disguising if you had the suit), or a soda water from the Market. The log lets you see EXACTLY what it did, which is an important step when learning KoLmafia!
# Bring up the Inventory Manager again. Repeat this process for Food. Then, click Spleen and go ahead and consume all the various Moxie Weeds and other junk that accumulates in your inventory for the free substats (unless you want to autosell them for meat). If you've got wads or other adventure-granting spleen items this is where you consume them.

'''Warning:''' It should be noted that the Food and Booze Manager is VERY pesky about allowing you to make drinks that it knows you cannot consume. If you are totally drunk, you will find that the Item Manager will not let you make any drinks! In this case you can still make them by going to the Createable section where it has listings for food and booze. The drawback is that it won't show you detailed consumption information in that window. This might be necessary if you wanted to make a bunch of cocktails to sell for example.

'''Bottom Line:''' KoLmafia really takes the guesswork/research out of eating and drinking, and is a huge help for cooking/mixing.

Continue to [[KoLmafia Guide: PvP (Beating Up People)|Lesson 12: PvP (Beating Up People)]]

[[Category:KoLmafia Guide]][[Category:New User Help]]

Fullness limit

2010-09-16T20:02:26Z

PhilmASTErpLus: Unwrapped overflowing long code is long.

{{
#vardefine:name|fullness_limit}}{{
#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 logged-in character's maximum fullness level as an int. For most characters, the returned value will be 15. On the Feast of Boris this number is raised by 15. The number is also raised by 5 for characters with Stomach of Steel.|

code1={{CodeSample|
title=Code Samples|
description=This example calculates how many hot hi meins it can eat and then eats them.|
code=
<syntaxhighlight>
if (my_fullness() + 5 <= fullness_limit())
{
eat(floor((fullness_limit() - my_fullness()) / 5) , $item[hot hi mein]);
// We're using floor() here because if (fullness_limit() - my_fullness())/5 returns, say, 2.6,
//we only want it to consume 2.
// Also, eat() takes an integer, not a float, as a parameter.
}
</syntaxhighlight>
}}|

see_also={{SeeAlso|my_fullness|eat}}|
special=When not logged in, this function returns 15.
}}

[[Category:Your Character]]

My primestat

2010-09-16T19:58:42Z

PhilmASTErpLus: Reformatted code

{{
#vardefine:name|my_primestat}}{{
#vardefine:return_type|stat}}{{

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 stat associated with your class.|

code1={{CodeSample|
title=Code Samples|
description=The following example attempts to create as many scrumpdiddlyumptious solutions as you have scrumptious reagents if you can access the Mysticality guild store. Since Accordion Thieves above level 9 can also access {{kolwiki|Gouda's Grimoire and Grocery}}, this code checks for it as well.|
code=
<syntaxhighlight>
if ((my_primestat() == $stat[mysticality] || (my_class() == $class[Accordion Thief] && my_level() > 9))
&& guild_store_available())
{
retrieve_item(item_amount($item[scrumptious reagent]) , $item[delectable catalyst]);
use(item_amount($item[delectable catalyst]) , $item[delectable catalyst]);
}
</syntaxhighlight>
}}|

see_also={{SeeAlso|retrieve_item|item_amount|use}}|
special=When not logged in, this function returns $stat[moxie] (Needs spading).
}}

[[Category:Your Character]]

Contains

2010-09-16T01:31:47Z

PhilmASTErpLus: Redirected page to Data Structures#Contains

#REDIRECT [[Data_Structures#Contains]]

Talk:To item

2010-09-16T00:58:32Z

PhilmASTErpLus: Created page with 'Surprisingly, {{f|to_item}} works on familiars, but with unexpected results. For many familiars, it returns the hatchling of the given familiar: <blockquote>Fuzzy Dice, Spooky P…'

Surprisingly, {{f|to_item}} works on familiars, but with unexpected results. For many familiars, it returns the hatchling of the given familiar:

<blockquote>Fuzzy Dice, Spooky Pirate Skeleton, Barrrnacle, Blood-Faced Volleyball, Star Starfish, Hovering Sombrero, Ghost Pickle on a Stick, Jill-O-Lantern, Hand Turkey, Hanukkimbo Dreidl, Baby Yeti, Clockwork Grapefruit, Inflatable Dodecapede, Pygmy Bugbear Shaman, Attention-Deficit Demon, Cymbal-Playing Monkey, Sweet Nutcracker, Pet Rock, Snowy Owl, Teddy Bear, Ninja Pirate Zombie Robot, Wind-up Chattering Teeth, Astral Badger, Comma Chameleon, Misshapen Animal Skeleton, Scary Death Orb, Jitterbug, Nervous Tick, Reassembled Blackbird, Evil Teddy Bear, Toothsome Rock, Dandy Lion, O.A.F., Exotic Parrot, Wizard Action Figure, Casagnova Gnome, Hunchbacked Minion, Crimbo P. R. E. S. S. I. E., Bulky Buddy Box, Teddy Borg, RoboGoose, El Vibrato Megadrone, Adorable Seal Larva, Hobo Monkey, Uniclops, Psychedelic Bear, Mutant Fire Ant, Mutant Cactus Bud, Mutant Gila Monster, Cuddlefish, Pair of Ragged Claws, Magic Dragonfish, Midget Clownfish, Syncopated Turtle, Grinning Turtle, Wereturtle, Rock Lobster, Chauvinist Pig, Jack-in-the-Box, Pottery Barn Owl</blockquote>

However, there were several interesting exceptions:
<pre>
Mosquito => tiny plastic mosquito
Levitating Potato => tiny plastic levitating potato
Angry Goat => tiny plastic angry goat
Howling Balloon Monkey => tiny plastic howling balloon monkey
Grue => tiny plastic grue
Baby Gravy Fairy => tiny plastic baby gravy fairy
Cocoabo => tiny plastic cocoabo
Coffee Pixie => tiny plastic coffee pixie
Cheshire Bat => tiny plastic Cheshire bat
MagiMechTech MicroMechaMech => stuffed MagiMechTech MicroMechaMech
Flaming Gravy Fairy => stuffed flaming gravy fairy
Frozen Gravy Fairy => stuffed frozen gravy fairy
Stinky Gravy Fairy => stuffed stinky gravy fairy
Spooky Gravy Fairy => stuffed spooky gravy fairy
Sleazy Gravy Fairy => stuffed sleazy gravy fairy
Ancient Yuletide Troll => tiny plastic ancient yuletide troll
Stocking Mimic => tiny plastic stocking mimic
</pre>
Perhaps they are chosen by matching the familiar name with the item name. For reference, the list of familiars for whom {{f|to_item}} returns nothing:

<blockquote>Leprechaun, Sabre-Toothed Lime, Stab Bat, Ghuol Whelp, Killer Bee, Whirling Maple Leaf, Crimbo Elf, Feather Boa Constrictor, Emo Squid, Personal Raincloud, Doppelshifter, Temporal Riftlet, Wild Hare, Spirit Hobo, Origami Towel Crane, Ninja Snowflake, Penguin Goodfella, Jumpsuited Hound Dog, Green Pixie, Ragamuffin Imp, Gluttonous Green Ghost, Mad Hatrack, Untamed Turtle, Animated Macaroni Duck, Pet Cheezling, Autonomous Disco Ball, Mariachi Chihuahua, Llama Lama, Cotton Candy Carnie, Disembodied Hand, Black Cat, Baby Mutant Rattlesnake, Sugar Fruit Fairy, Imitation Crab, Frumious Bandersnatch, Purse Rat, Baby Sandworm, Slimeling, He-Boulder, Urchin Urchin, Grouper Groupie, Squamous Gibberer, Dancing Frog, Snow Angel, BRICKO chick, Baby Bugged Bugbear, Underworld Bonsai, Rogue Program, Mini-Hipster</blockquote>

That's weird, though. If {{f|to_item}} is actually using the familiar name to match the item, why does it return <code>$item[none]</code> for the Leprechaun (tiny plastic leprechaun, leprechaun hatchling) or the Stab Bat (rewinged stab bat, tiny plastic stab bat)? Another mysterious quirks of ASH. --[[User:PhilmASTErpLus|PhilmASTErpLus]] 00:58, 16 September 2010 (UTC)

User:PhilmASTErpLus

2010-09-13T12:35:59Z

PhilmASTErpLus: /* ASH Quirks and Hacks */ Added information about the fairy gravy boat that I learned through the painful way.

I'm using this page as my own personal sandbox :) Please contribute your comments, opinions, and ideas in the [[User Talk:PhilmASTErpLus|talk page]].

--[[User:PhilmASTErpLus|PhilmASTErpLus]] 02:36, 21 June 2010 (UTC)

== Moving [[Datatype Constants]] to [[Data Types]] ==

"Datatype constants" are literals that begin with a dollar sign($), such as <code>$item[]</code>, <code>$effect[]</code>, etc. Types of data, such as <code>boolean</code> and <code>int</code>, are called [http://en.wikipedia.org/wiki/Data_type Data Types].

That is true, and deserves fixing; but please don't do so in a way that breaks a massive amount of links, ktx. --[[User:StDoodle|StDoodle (#1059825)]] 04:18, 21 June 2010 (UTC)

Heh, that's okay (re: discussion on Datatype Constants). For most pages it isn't a huge issue, but that one... it requires fixing in quite a few places, some of which unfortunately won't be automatically be fixed by redirects during a page move (this seems to happen when some of the links are from templates, which this page has a massive number of). For reference, this wiki has problems with both the "design by committee" philosophy & the "legacy problems" philosophy. Originally, the stuff here was simply copy & pasted from an guide that had been hosted elsewhere, which itself was about 2/3 original material and 1/3 copied from Hola's old reference material. That led to the problem of pages having inappropriate names, as by the time the issue was given thought, they were deeply ingrained in the wiki structure. Then there's the "committee" issue, which resulted in some over-elaborate templates. For the most part, the last issue doesn't present any issues with searching and display, but does up the learning curve for "proper" page editing in some places (mostly on the function pages). In the end, I'm glad to have another person interested in helping; but please, before making any massive-scale (many pages) edits, or moving pages, a discussion would be appreciated. As you now know, there are "methods in the madness" for some of this stuff... ;) Also, if you want to help with getting Datatype Constants corrected, I'd be happy to jot down some notes on what needs to be done in the next day or so. --[[User:StDoodle|StDoodle (#1059825)]] 15:51, 21 June 2010 (UTC)

P.S. User pages such as this are the perfect places for sandboxing & discussion; you can even make sub-pages in your own wiki-space by linking to them from here, with a "/" as the first character of the page name. Since user pages are outside of the normal search parameters, feel free to use them however you wish.

== Works ==
*Add information on directly accessing kolmafia data files--equipment.txt, pulverize.txt, etc. => see {{f|file_to_map}}
*[[Image:item_category.png|150px]] would go nicely in the pages for [[Item Management]]-related functions.
*To anyone who cares: the image above was created in Microsoft PowerPoint. You can get it [http://sites.google.com/site/philmasterplus/files/kolmafia_wiki.ppt here].

== ASH Quirks and Hacks ==
*{{f|print}} displays a blank line when given a string starting with a slash (<code>/</code>). To prevent this, the text color must be explicitly given. Easy to bypass, but weird.
*"Anonymous" closures: ASH does not seem to accept anonymous closures by default.
{{CodeSample|code=<syntaxhighlight>
int var1;
/* Do stuff */
{
int var1;
call_some_function();
/* Do other stuff */
}
</syntaxhighlight>}}
However, you can use a workaround with a if-clause.
{{CodeSample|code=<syntaxhighlight>
int var1;
/* Do stuff */
if (true)
{
int var1;
/* Do other stuff */
}
</syntaxhighlight>}}
As for where stuff like this could be used...I'm using it for initializing ASH scripts without creating any unnecessary functions or variables in the "namespace".
*Technically NOT ASH-related, but KoLmafia has difficulty understanding haiku combat. In particular, as of r8611, it cannot detect acquisition of {{kolwiki|fairy gravy boat}}s from the {{kolwiki|Gravy Fairy Wing}} adventure. Therefore you must NOT use a goal and auto-adventure to get one. Let the adventurer beware!

Import

2010-09-13T07:40:21Z

PhilmASTErpLus: Subdirectory stuff. Does a similar logic applies to file_to_map()/map_to_file()? I believe there was a forum discussion about security and preventing KoLmafia from accessing the parent directory.

{{DISPLAYTITLE:import}}
'''import <filename>'''

'''Import''' is a command that is used to import (hence the name) an entire file's contents into the file in which '''import''' is called. "Nested" imports are possible; a script that is being imported may import another script. If a single file is imported more than once, KoLmafia will automatically avoid function name collisions. Note that when a script that has a <code>main()</code> function is imported into another script with another <code>main()</code> function, only the primary script's <code>main()</code> is executed, and all <code>main()</code> functions from imported scripts will be ignored. However, any of the imported top-level commands will be executed and all of the imported global variables will be accessible to the primary script.

Because '''import''' looks inside the /scripts directory and all its subfolders for the given script name, moving your scripts around inside the /scripts directory will not affect other scripts that rely on them. If there are multiple scripts with the same file name, KoLmafia will use the first script found. You can use your OS-specific directory path separators (usually slashes(/) and backslashes(\)) to explicitly '''import''' a script inside a subdirectory.

==Example==


{{CodeSample|code=<syntaxhighlight>
# snippet from my aftercore.ash file
import <lib/utilities.ash> // import a utility function library in the scripts/lib/ directory
import <aftercore_config.ash> // import the configuration file (loaded with variables) into the script
import <aftercore_bounty.ash> // import bounty functionality (loaded with functions) into the script

int first_meat = my_meat();
int first_advs = my_adventures();
boolean using_upcs_curr = false;

# ...
</syntaxhighlight>}}
{{Format}}

[[Category:Scripting]]

User:PhilmASTErpLus

2010-09-13T02:13:55Z

PhilmASTErpLus: /* Works */

User:PhilmASTErpLus

2010-09-13T02:13:36Z

PhilmASTErpLus:

I'm using this page as my own personal sandbox :) Please contribute your comments, opinions, and ideas in the [[User Talk:PhilmASTErpLus|talk page]].

--[[User:PhilmASTErpLus|PhilmASTErpLus]] 02:36, 21 June 2010 (UTC)

== Moving [[Datatype Constants]] to [[Data Types]] ==

"Datatype constants" are literals that begin with a dollar sign($), such as <code>$item[]</code>, <code>$effect[]</code>, etc. Types of data, such as <code>boolean</code> and <code>int</code>, are called [http://en.wikipedia.org/wiki/Data_type Data Types].

That is true, and deserves fixing; but please don't do so in a way that breaks a massive amount of links, ktx. --[[User:StDoodle|StDoodle (#1059825)]] 04:18, 21 June 2010 (UTC)

Heh, that's okay (re: discussion on Datatype Constants). For most pages it isn't a huge issue, but that one... it requires fixing in quite a few places, some of which unfortunately won't be automatically be fixed by redirects during a page move (this seems to happen when some of the links are from templates, which this page has a massive number of). For reference, this wiki has problems with both the "design by committee" philosophy & the "legacy problems" philosophy. Originally, the stuff here was simply copy & pasted from an guide that had been hosted elsewhere, which itself was about 2/3 original material and 1/3 copied from Hola's old reference material. That led to the problem of pages having inappropriate names, as by the time the issue was given thought, they were deeply ingrained in the wiki structure. Then there's the "committee" issue, which resulted in some over-elaborate templates. For the most part, the last issue doesn't present any issues with searching and display, but does up the learning curve for "proper" page editing in some places (mostly on the function pages). In the end, I'm glad to have another person interested in helping; but please, before making any massive-scale (many pages) edits, or moving pages, a discussion would be appreciated. As you now know, there are "methods in the madness" for some of this stuff... ;) Also, if you want to help with getting Datatype Constants corrected, I'd be happy to jot down some notes on what needs to be done in the next day or so. --[[User:StDoodle|StDoodle (#1059825)]] 15:51, 21 June 2010 (UTC)

P.S. User pages such as this are the perfect places for sandboxing & discussion; you can even make sub-pages in your own wiki-space by linking to them from here, with a "/" as the first character of the page name. Since user pages are outside of the normal search parameters, feel free to use them however you wish.

=== Works ===

*Add information on directly accessing kolmafia data files--equipment.txt, pulverize.txt, etc. => see {{f|file_to_map}}
*[[Image:item_category.png|150px]] would go nicely in the pages for [[Item Management]]-related functions.
*To anyone who cares: the image above was created in Microsoft PowerPoint. You can get it [http://sites.google.com/site/philmasterplus/files/kolmafia_wiki.ppt here].

== ASH Quirks and Hacks ==
*{{f|print}} displays a blank line when given a string starting with a slash (<code>/</code>). To prevent this, the text color must be explicitly given. Easy to bypass, but weird.
*"Anonymous" closures: ASH does not seem to accept anonymous closures by default.
{{CodeSample|code=<syntaxhighlight>
int var1;
/* Do stuff */
{
int var1;
call_some_function();
/* Do other stuff */
}
</syntaxhighlight>}}
However, you can use a workaround with a if-clause.
{{CodeSample|code=<syntaxhighlight>
int var1;
/* Do stuff */
if (true)
{
int var1;
/* Do other stuff */
}
</syntaxhighlight>}}
As for where stuff like this could be used...I'm using it for initializing ASH scripts without creating any unnecessary functions or variables in the "namespace".

Item Management

2010-09-12T10:31:35Z

PhilmASTErpLus: /* Informational */ Reordered to correctly group X_amount() functions.

{{TOCright}}
==Informational==
{{Flink|int|my_meat|desc=Returns the amount of meat you have on hand.}}
{{Flink|int|my_closet_meat|desc=Returns the amount of meat you have in your Colossal Closet.}}
{{Flink|int|pulls_remaining|desc=Returns the number of pulls you can make from storage, or 0 if not applicable.}}
{{Flink|boolean|have_chef|desc=Returns true if you have a chef-boxen at your campground.}}
{{Flink|boolean|have_bartender|desc=Returns true if you have a bartender-boxen at your campground.}}
{{Flink|int [item]|get_campground|desc=Returns a map of your campground items.}}
{{Flink|boolean|have_mushroom_plot|desc=Returns true if and only if you've purchased a mushroom plot this run.}}
{{Flink|int|stills_available|desc=Returns the number of Nash Crosby's Still uses left for the day (0 if not accessible).}}
{{Flink|string|item_type|item|desc=Returns the type of item specified.}}
{{Flink|int|item_amount|item}}
{{Flink|int|closet_amount|item}}
{{Flink|int|display_amount|item}}
{{Flink|int|equipped_amount|item}}
{{Flink|int|shop_amount|item}}
{{Flink|int|stash_amount|item|}}
{{Flink|int|storage_amount|item|desc=These 7 functions return the total number available of a given item in the respective section of your inventory.}}
{{Flink|int|available_amount|item|desc=Returns the total number available of a given item in all inventory sections accessible to your character based on current restrictions.}}
{{Flink|int|creatable_amount|item|desc=Returns the amount of the item that you are capable of creating given your current inventory and skills.}}
{{Flink|int [item]|get_ingredients|item|desc=Returns a map where each key is one of the required ingredients, with the integer value the number required. If you don't have the skills needed to make the item, it will return an empty map.}}
{{Flink|int [item]|get_inventory|desc=Returns a map where each key is an item in your inventory, with the integer value its quantity.}}
{{Flink|int [item]|get_related|item|string|desc=Returns associated items in a zap or fold group (see page for details).}}
[[File:Item category.png|frame|You can categorize items in KoL using [[is tradeable|is_tradeable()]], [[is giftable|is_giftable()]], and [[is displayable|is_displayable()]].]]
{{Flink|boolean|is_tradeable|item|desc=Returns whether the item can be placed in the mall.}}
{{Flink|boolean|is_giftable|item|desc=Returns whether the item can be traded in a gift package.}}
{{Flink|boolean|is_displayable|item|desc=Returns whether the item can be put in a display case (true for all but quest items).}}
{{Flink|boolean|have_shop|desc=Returns whether you have a mall store.}}
{{Flink|boolean|have_display|desc=Returns whether you have a display case.}}
{{Flink|boolean|is_npc_item|item|desc=Returns whether the item can be bought from an NPC store.}}
{{Flink|void|refresh_stash|desc=Takes a new look at the contents of your clan stash, as that section of inventory cannot be internally tracked due to access by others.}}
{{Flink|boolean|mall_price|item|desc=Returns the current (lowest) mall price of the given item.}}
{{Flink|int|historical_price|item|desc=Returns the most recently checked price for an item. This will never hit the server, unlike mall_price().}}
{{Flink|float|historical_age|item|desc=Returns the age of the most recently checked price for an item in days. This allows you to decide if you want to use historical_price() or mall_price().}}
{{Flink|int|autosell_price|item|desc=Returns the autosell price of the item (0 for items that cannot be autosold).}}
{{Flink|int|get_power|item|desc=Returns the power of the item (0 for items that don't have a power).}}
{{Flink|string|to_plural|item|desc=Returns the plural of an item as a string.}}
{{Flink|int|meat_drop|{{opt|monster}}|desc=Returns a certain monster's base meat drop.}}
{{Flink|int [item]|item_drops|{{opt|monster}}|desc=Returns an array of a certain monster's base item drops, keying item to drop rate. Has certain limitations detailed on individual page.}}
{{Flink|record [int]|item_drops_array|{{opt|monster}}|desc=Returns an array of records holding information regarding a certain monster's base item drops.}}

==Moving Items Around==
{{Flink|boolean|put_closet|int|{{opt|item}}}}
{{Flink|boolean|put_display|int|item}}
{{Flink|boolean|put_stash|int|item}}
{{Flink|boolean|take_closet|int|{{opt|item}}}}
{{Flink|boolean|take_display|int|item}}
{{Flink|boolean|take_stash|int|item}}
{{Flink|boolean|take_storage|int|item|desc=Attempts to take or put the specified item in the appropriate section of your inventory, and returns its success. If the item parameter is omitted from put_closet() or take_closet(), meat is transferred instead of an item.}}
{{Flink|boolean|put_shop|int|int|{{opt|int}}|item|desc=Puts items in your store (see page for details).}}

==Acquiring & Using Items==
{{Flink|boolean|retrieve_item|int|item|desc=Uses KoLmafia internal logic to gather items (see page for details).}}
{{Flink|boolean|hermit|int|item|desc=Trades worthless items (adventuring in the sewer if needed) to the hermit for specified items (see page for details).}}
{{Flink|boolean|use|int|item|desc=Attempts to use items as specified and reports success.}}
{{Flink|boolean|eatsilent|int|item}}
{{Flink|boolean|eat|int|item|desc=Attempts to eat items as specified and reports success.}}
{{Flink|boolean|overdrink|int|item}}
{{Flink|boolean|drink|int|item|desc=Attempts to drink items as specified and reports success.}}
{{Flink|boolean|create|int|item|desc=Attempts to create the specified items, following your KoLmafia settings regarding purchases to gather ingredients & require boxen.}}
{{Flink|boolean|buy|int|item}}
{{Flink|int|buy|int|item|int|desc=Tries to purchase the specified items (see page for details).}}
{{Flink|boolean|autosell|int|item|desc=Attempts to autosell the given items and reports success.}}
{{Flink|int|craft|string|int|item|item|desc=Raw crafting that obeys KoLmafia settings (see page for details).}}
[[Category:Scripting]]

Weapon hands

2010-09-12T10:18:27Z

PhilmASTErpLus: This function returns 3 for 3-handed weapons as of r8607.

{{
#vardefine:name|weapon_hands}}{{
#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|check_me}}|
p1desc={{Pspan|check_me}} is the item to check|
}}|

function_description=Returns the number of hands required for a weapon. Everything else, including off-hand items, returns 0. Note that while weapons jokingly labeled as "3-handed" in KoL are actually 2-handed in reality, this function will return 3.|

needscode=yes|

see_also={{SeeAlso|weapon_type}}|
}}

[[Category:Equipment]]

CCS

2010-09-05T08:01:44Z

PhilmASTErpLus: Redirected page to Custom Combat Script

#REDIRECT [[Custom Combat Script]]

ASH Errors

2010-08-26T03:18:34Z

PhilmASTErpLus: /* Map modified within foreach */ More typos found. Sorry about that.

{{TOCright}}
Errors happen. When they do, it helps to have some idea of what what wrong.

===Abort===

Whenever a script runs the [[abort|abort()]] function, this error is generated.

{{CodeSample|
description=The zero-parameter form:|
code=
<syntaxhighlight>
abort();
</syntaxhighlight>}}
will stop the execution and print: KoLmafia declares world peace. Note that this message may also appear as a result of pressing Esc in the Main Interface or hitting "stop now" in the Adventure tab.

{{CodeSample|
description=The one-parameter form:|
code=
<syntaxhighlight>
abort("Aborting script...");
</syntaxhighlight>}}
will stop the execution and print: Aborting script...

===Cannot initialize parameter [parameter]===

This error is created when an assignment is attempted inside a function declaration.
The following code results in an error.

{{CodeSample|
code=
<syntaxhighlight>
/* test.ash */

void my_function( string myvar = "value" )
{
/* Do something */
}
</syntaxhighlight>}}
will halt the script and print: Cannot initialize parameter myvar (test.ash, line X)

===Cannot return [datatype] from [datatype] function===

This indicates that the return value does not match the function's type.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int stuff(){
return "4";
}
</syntaxhighlight>}}
will cause this error: Cannot return string value from int function (test.ash, line 2)

{{CodeSample|
description=Similarly, for void functions:|
code=
<syntaxhighlight>
void stuff(){
return 4;
}
</syntaxhighlight>}}
will cause this error: Cannot return a value from a void function (test.ash, line 2)

===Encountered '[break|continue]' outside loop===

This indicates that the control structure in question was not in a loop.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
continue;
</syntaxhighlight>}}
will cause this error: Encountered 'continue' outside of loop (test.ash, line 1)

===Expected===

This generally indicates a syntax problem (missing ending semi-colon, unmatched braces, unmatched parenthesis etc...).

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int a = 1
print(a);
</syntaxhighlight>}}
will cause this error: Expected ;, found print (test.ash, line 2)

===Function defined multiple times===

This indicates that the function in question has already been defined.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int abs(int a){
return a*((a>0).to_int()*2 - 1);
}
int abs(int a){
if(a<0) a = -a;
return a;
}
</syntaxhighlight>}}
will cause this error: Function <nowiki>'abs( int )'</nowiki> defined multiple times (test.ash, line 4)

==="if" requires a boolean conditional expression ===

This indicates that the condition inside an if statement is not a boolean.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
if(42) {
print("Don't panic.");
}
</syntaxhighlight>}}
will cause this error: "if" requires a boolean conditional expression (test.ash, line 1)

===Index type is not a primitive type===

This indicates that the map's index is not a standard datatype (float, int, string, etc.).

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
record alpha{
int a;
int b;
};
int[alpha] map;
</syntaxhighlight>}}
will cause this error: Index type 'alpha' is not a primitive type (test.ash, line 5)

===Invalid field name===

This indicates that the record does not contain the field in question.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
record my_record {
string a;
string b;
};

my_record [int] my_map;
my_map[1].c = "hello";
</syntaxhighlight>}}
will cause this error: Invalid field name 'c' (test.ash, line 7)

Note that this error may also be encountered when neglecting to name a field.
{{CodeSample|
description= For instance:|
code=
<syntaxhighlight>
record my_record {
string;
};
</syntaxhighlight>}}
will cause this error: Invalid field name ';' (test.ash, line 2)

===Invalid type name===

This indicates that the specified type is not recognized by Mafia.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int[fruit] map;
</syntaxhighlight>}}
will cause this error: Invalid type name 'fruit' (test.ash, line 1)

===Main method must appear at top level===

This indicates that the script's main method is inside another method, for some reason. This is usually caused by a missing brace.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
void stuff() {
// stuff happens here

void main() {
stuff();
}
</syntaxhighlight>}}
will cause this error: main method must appear at top level (test.ash, line 6)

===Map modified within foreach===

You cannot add new entries into a map within a <code>[[foreach]]</code> loop. This can happen if you accidentally wrap the name of a string variable with double-quotes for referencing a map entry.

{{CodeSample|
description=For example, the following code:|
code=
<syntaxhighlight>
/* test.ash */
item [string] my_map;
/* Populate my_map with several entries */
foreach str in my_map
print( str + " => " + my_map[ "str" ] );
</syntaxhighlight>}}
Yields: Map modified within foreach (test.ash, line X)

===Missing return value===

The last line of a user-defined function has to be "return <value>;" (although the [[Control_Structures#return|return]] command can be used before too).

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int my_function( int a, int b ) {
if ( a > b ) return a ;
else return b ;
}
</syntaxhighlight>}}
will cause this error: Missing return value (test.ash, line 4)

===No closing found===

This can be caused by forgetting to put a '''"''' or a ''']''' at the end of an argument

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
buy(1000 , $item[disco ball, 225);
</syntaxhighlight>}}
will cause this error: No closing ] found (testing.ash, line 1)

===Record expected===

This indicates that an unrecognized record was found. This often appears when you forget to append "()" to a function name.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
print(4.to_string);
</syntaxhighlight>}}
will cause this error: Record expected (test.ash, line 2)

===Record name is already defined===

This indicates that the record name has already been defined, and so cannot be reused. The solution is to change the record name.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
record str {
string a;
string b;
};
record str {
int a;
int b;
};
</syntaxhighlight>}}
will cause this error: Record name 'str' is already defined (test.ash, line 5)

===Return needs [datatype] value===

This indicates that the return value is void when the function is not.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int stuff() {
return;
}
</syntaxhighlight>}}
will cause this error: Return needs int value (test.ash, line 2)

===Reserved word cannot be a [function|record|variable] name===

This indicates that the desired name has been [[Reserved Words|reserved]], and so cannot be used. The solution is to use a different name.

{{CodeSample|
description=An invalid name:|
code=
<syntaxhighlight>
int float(float a) {
return round(a);
}
</syntaxhighlight>}}
will cause this error: Reserved word 'float' cannot be used as a function name (test.ash, line 1)

An interesting point to note is that ASH functions take precedent over identically named custom functions rather than throw an exception.

{{CodeSample|
description=An invalid record name:|
code=
<syntaxhighlight>
record string {
string a;
string b;
};
</syntaxhighlight>}}
will cause this error: Reserved word 'string' cannot be a record name (test.ash, line 1)

{{CodeSample|
description=An invalid variable name:|
code=
<syntaxhighlight>
string item = "bottle of gin";
</syntaxhighlight>}}
will cause this error: Reserved word 'item' cannot be a variable name (test.ash, line 1)

===Script parsing error===

This generally indicates a syntax problem, as in having an excess amount of braces or a variable/function/record name that starts with an invalid character.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
put_shop(0 ,0 ,$item[wolf mask]);
put_shop(0 ,0 ,$item[rave whistle]);
put_shop(0 ,0 ,$item[giant needle]);
cli_execute ("undercut");
}
</syntaxhighlight>}}
will cause this error: Script parsing error (test.ash, line 5)

===Variable is already defined===

This indicates that the same variable has been declared twice.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int Drops ;
int Meat ;
int Drops = numeric_modifier("Item Drop");
</syntaxhighlight>}}
will cause this error: Variable Drops is already defined (test.ash, line 3)

{{RFI|Obviously, a lot more info is needed here.}}

[[Category:Scripting]]

ASH Errors

2010-08-26T03:17:41Z

PhilmASTErpLus: /* Map modified within foreach */ Gah, typo fixed

{{TOCright}}
Errors happen. When they do, it helps to have some idea of what what wrong.

===Abort===

Whenever a script runs the [[abort|abort()]] function, this error is generated.

{{CodeSample|
description=The zero-parameter form:|
code=
<syntaxhighlight>
abort();
</syntaxhighlight>}}
will stop the execution and print: KoLmafia declares world peace. Note that this message may also appear as a result of pressing Esc in the Main Interface or hitting "stop now" in the Adventure tab.

{{CodeSample|
description=The one-parameter form:|
code=
<syntaxhighlight>
abort("Aborting script...");
</syntaxhighlight>}}
will stop the execution and print: Aborting script...

===Cannot initialize parameter [parameter]===

This error is created when an assignment is attempted inside a function declaration.
The following code results in an error.

{{CodeSample|
code=
<syntaxhighlight>
/* test.ash */

void my_function( string myvar = "value" )
{
/* Do something */
}
</syntaxhighlight>}}
will halt the script and print: Cannot initialize parameter myvar (test.ash, line X)

===Cannot return [datatype] from [datatype] function===

This indicates that the return value does not match the function's type.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int stuff(){
return "4";
}
</syntaxhighlight>}}
will cause this error: Cannot return string value from int function (test.ash, line 2)

{{CodeSample|
description=Similarly, for void functions:|
code=
<syntaxhighlight>
void stuff(){
return 4;
}
</syntaxhighlight>}}
will cause this error: Cannot return a value from a void function (test.ash, line 2)

===Encountered '[break|continue]' outside loop===

This indicates that the control structure in question was not in a loop.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
continue;
</syntaxhighlight>}}
will cause this error: Encountered 'continue' outside of loop (test.ash, line 1)

===Expected===

This generally indicates a syntax problem (missing ending semi-colon, unmatched braces, unmatched parenthesis etc...).

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int a = 1
print(a);
</syntaxhighlight>}}
will cause this error: Expected ;, found print (test.ash, line 2)

===Function defined multiple times===

This indicates that the function in question has already been defined.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int abs(int a){
return a*((a>0).to_int()*2 - 1);
}
int abs(int a){
if(a<0) a = -a;
return a;
}
</syntaxhighlight>}}
will cause this error: Function <nowiki>'abs( int )'</nowiki> defined multiple times (test.ash, line 4)

==="if" requires a boolean conditional expression ===

This indicates that the condition inside an if statement is not a boolean.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
if(42) {
print("Don't panic.");
}
</syntaxhighlight>}}
will cause this error: "if" requires a boolean conditional expression (test.ash, line 1)

===Index type is not a primitive type===

This indicates that the map's index is not a standard datatype (float, int, string, etc.).

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
record alpha{
int a;
int b;
};
int[alpha] map;
</syntaxhighlight>}}
will cause this error: Index type 'alpha' is not a primitive type (test.ash, line 5)

===Invalid field name===

This indicates that the record does not contain the field in question.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
record my_record {
string a;
string b;
};

my_record [int] my_map;
my_map[1].c = "hello";
</syntaxhighlight>}}
will cause this error: Invalid field name 'c' (test.ash, line 7)

Note that this error may also be encountered when neglecting to name a field.
{{CodeSample|
description= For instance:|
code=
<syntaxhighlight>
record my_record {
string;
};
</syntaxhighlight>}}
will cause this error: Invalid field name ';' (test.ash, line 2)

===Invalid type name===

This indicates that the specified type is not recognized by Mafia.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int[fruit] map;
</syntaxhighlight>}}
will cause this error: Invalid type name 'fruit' (test.ash, line 1)

===Main method must appear at top level===

This indicates that the script's main method is inside another method, for some reason. This is usually caused by a missing brace.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
void stuff() {
// stuff happens here

void main() {
stuff();
}
</syntaxhighlight>}}
will cause this error: main method must appear at top level (test.ash, line 6)

===Map modified within foreach===

You cannot add new entries into a map within a <code>[[foreach]]</code> loop. This can happen if you accidentally wrap the name of a string variable with double-quotes for referencing a map entry.

{{CodeSample|
description=For example, the following code|
code=
<syntaxhighlight>
item [string] my_map;
/* Populate my_map with several entries */
foreach str in my_map
print( str + " => " + my_map[ "str" ];
</syntaxhighlight>}}

Yields: Map modified within foreach (filename.ash, line X)

===Missing return value===

The last line of a user-defined function has to be "return <value>;" (although the [[Control_Structures#return|return]] command can be used before too).

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int my_function( int a, int b ) {
if ( a > b ) return a ;
else return b ;
}
</syntaxhighlight>}}
will cause this error: Missing return value (test.ash, line 4)

===No closing found===

This can be caused by forgetting to put a '''"''' or a ''']''' at the end of an argument

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
buy(1000 , $item[disco ball, 225);
</syntaxhighlight>}}
will cause this error: No closing ] found (testing.ash, line 1)

===Record expected===

This indicates that an unrecognized record was found. This often appears when you forget to append "()" to a function name.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
print(4.to_string);
</syntaxhighlight>}}
will cause this error: Record expected (test.ash, line 2)

===Record name is already defined===

This indicates that the record name has already been defined, and so cannot be reused. The solution is to change the record name.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
record str {
string a;
string b;
};
record str {
int a;
int b;
};
</syntaxhighlight>}}
will cause this error: Record name 'str' is already defined (test.ash, line 5)

===Return needs [datatype] value===

This indicates that the return value is void when the function is not.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int stuff() {
return;
}
</syntaxhighlight>}}
will cause this error: Return needs int value (test.ash, line 2)

===Reserved word cannot be a [function|record|variable] name===

This indicates that the desired name has been [[Reserved Words|reserved]], and so cannot be used. The solution is to use a different name.

{{CodeSample|
description=An invalid name:|
code=
<syntaxhighlight>
int float(float a) {
return round(a);
}
</syntaxhighlight>}}
will cause this error: Reserved word 'float' cannot be used as a function name (test.ash, line 1)

An interesting point to note is that ASH functions take precedent over identically named custom functions rather than throw an exception.

{{CodeSample|
description=An invalid record name:|
code=
<syntaxhighlight>
record string {
string a;
string b;
};
</syntaxhighlight>}}
will cause this error: Reserved word 'string' cannot be a record name (test.ash, line 1)

{{CodeSample|
description=An invalid variable name:|
code=
<syntaxhighlight>
string item = "bottle of gin";
</syntaxhighlight>}}
will cause this error: Reserved word 'item' cannot be a variable name (test.ash, line 1)

===Script parsing error===

This generally indicates a syntax problem, as in having an excess amount of braces or a variable/function/record name that starts with an invalid character.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
put_shop(0 ,0 ,$item[wolf mask]);
put_shop(0 ,0 ,$item[rave whistle]);
put_shop(0 ,0 ,$item[giant needle]);
cli_execute ("undercut");
}
</syntaxhighlight>}}
will cause this error: Script parsing error (test.ash, line 5)

===Variable is already defined===

This indicates that the same variable has been declared twice.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int Drops ;
int Meat ;
int Drops = numeric_modifier("Item Drop");
</syntaxhighlight>}}
will cause this error: Variable Drops is already defined (test.ash, line 3)

{{RFI|Obviously, a lot more info is needed here.}}

[[Category:Scripting]]

ASH Errors

2010-08-26T03:17:15Z

PhilmASTErpLus: Added "map modified within foreach" -- needs more testing, though.

{{TOCright}}
Errors happen. When they do, it helps to have some idea of what what wrong.

===Abort===

Whenever a script runs the [[abort|abort()]] function, this error is generated.

{{CodeSample|
description=The zero-parameter form:|
code=
<syntaxhighlight>
abort();
</syntaxhighlight>}}
will stop the execution and print: KoLmafia declares world peace. Note that this message may also appear as a result of pressing Esc in the Main Interface or hitting "stop now" in the Adventure tab.

{{CodeSample|
description=The one-parameter form:|
code=
<syntaxhighlight>
abort("Aborting script...");
</syntaxhighlight>}}
will stop the execution and print: Aborting script...

===Cannot initialize parameter [parameter]===

This error is created when an assignment is attempted inside a function declaration.
The following code results in an error.

{{CodeSample|
code=
<syntaxhighlight>
/* test.ash */

void my_function( string myvar = "value" )
{
/* Do something */
}
</syntaxhighlight>}}
will halt the script and print: Cannot initialize parameter myvar (test.ash, line X)

===Cannot return [datatype] from [datatype] function===

This indicates that the return value does not match the function's type.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int stuff(){
return "4";
}
</syntaxhighlight>}}
will cause this error: Cannot return string value from int function (test.ash, line 2)

{{CodeSample|
description=Similarly, for void functions:|
code=
<syntaxhighlight>
void stuff(){
return 4;
}
</syntaxhighlight>}}
will cause this error: Cannot return a value from a void function (test.ash, line 2)

===Encountered '[break|continue]' outside loop===

This indicates that the control structure in question was not in a loop.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
continue;
</syntaxhighlight>}}
will cause this error: Encountered 'continue' outside of loop (test.ash, line 1)

===Expected===

This generally indicates a syntax problem (missing ending semi-colon, unmatched braces, unmatched parenthesis etc...).

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int a = 1
print(a);
</syntaxhighlight>}}
will cause this error: Expected ;, found print (test.ash, line 2)

===Function defined multiple times===

This indicates that the function in question has already been defined.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int abs(int a){
return a*((a>0).to_int()*2 - 1);
}
int abs(int a){
if(a<0) a = -a;
return a;
}
</syntaxhighlight>}}
will cause this error: Function <nowiki>'abs( int )'</nowiki> defined multiple times (test.ash, line 4)

==="if" requires a boolean conditional expression ===

This indicates that the condition inside an if statement is not a boolean.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
if(42) {
print("Don't panic.");
}
</syntaxhighlight>}}
will cause this error: "if" requires a boolean conditional expression (test.ash, line 1)

===Index type is not a primitive type===

This indicates that the map's index is not a standard datatype (float, int, string, etc.).

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
record alpha{
int a;
int b;
};
int[alpha] map;
</syntaxhighlight>}}
will cause this error: Index type 'alpha' is not a primitive type (test.ash, line 5)

===Invalid field name===

This indicates that the record does not contain the field in question.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
record my_record {
string a;
string b;
};

my_record [int] my_map;
my_map[1].c = "hello";
</syntaxhighlight>}}
will cause this error: Invalid field name 'c' (test.ash, line 7)

Note that this error may also be encountered when neglecting to name a field.
{{CodeSample|
description= For instance:|
code=
<syntaxhighlight>
record my_record {
string;
};
</syntaxhighlight>}}
will cause this error: Invalid field name ';' (test.ash, line 2)

===Invalid type name===

This indicates that the specified type is not recognized by Mafia.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int[fruit] map;
</syntaxhighlight>}}
will cause this error: Invalid type name 'fruit' (test.ash, line 1)

===Main method must appear at top level===

This indicates that the script's main method is inside another method, for some reason. This is usually caused by a missing brace.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
void stuff() {
// stuff happens here

void main() {
stuff();
}
</syntaxhighlight>}}
will cause this error: main method must appear at top level (test.ash, line 6)

===Map modified within foreach===

You cannot add new entries into a map within a <code>[[foreach]]</code> loop. This can happen if you accidentally wrap the name of a string variable with double-quotes for referencing a map entry.

{{CodeSample|
description=For example, the following code
code=
<syntaxhighlight>
item [string] my_map;
/* Populate my_map with several entries */
foreach str in my_map
print( str + " => " + my_map[ "str" ];
</syntaxhighlight>}}

Yields: Map modified within foreach (filename.ash, line X)

===Missing return value===

The last line of a user-defined function has to be "return <value>;" (although the [[Control_Structures#return|return]] command can be used before too).

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int my_function( int a, int b ) {
if ( a > b ) return a ;
else return b ;
}
</syntaxhighlight>}}
will cause this error: Missing return value (test.ash, line 4)

===No closing found===

This can be caused by forgetting to put a '''"''' or a ''']''' at the end of an argument

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
buy(1000 , $item[disco ball, 225);
</syntaxhighlight>}}
will cause this error: No closing ] found (testing.ash, line 1)

===Record expected===

This indicates that an unrecognized record was found. This often appears when you forget to append "()" to a function name.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
print(4.to_string);
</syntaxhighlight>}}
will cause this error: Record expected (test.ash, line 2)

===Record name is already defined===

This indicates that the record name has already been defined, and so cannot be reused. The solution is to change the record name.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
record str {
string a;
string b;
};
record str {
int a;
int b;
};
</syntaxhighlight>}}
will cause this error: Record name 'str' is already defined (test.ash, line 5)

===Return needs [datatype] value===

This indicates that the return value is void when the function is not.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int stuff() {
return;
}
</syntaxhighlight>}}
will cause this error: Return needs int value (test.ash, line 2)

===Reserved word cannot be a [function|record|variable] name===

This indicates that the desired name has been [[Reserved Words|reserved]], and so cannot be used. The solution is to use a different name.

{{CodeSample|
description=An invalid name:|
code=
<syntaxhighlight>
int float(float a) {
return round(a);
}
</syntaxhighlight>}}
will cause this error: Reserved word 'float' cannot be used as a function name (test.ash, line 1)

An interesting point to note is that ASH functions take precedent over identically named custom functions rather than throw an exception.

{{CodeSample|
description=An invalid record name:|
code=
<syntaxhighlight>
record string {
string a;
string b;
};
</syntaxhighlight>}}
will cause this error: Reserved word 'string' cannot be a record name (test.ash, line 1)

{{CodeSample|
description=An invalid variable name:|
code=
<syntaxhighlight>
string item = "bottle of gin";
</syntaxhighlight>}}
will cause this error: Reserved word 'item' cannot be a variable name (test.ash, line 1)

===Script parsing error===

This generally indicates a syntax problem, as in having an excess amount of braces or a variable/function/record name that starts with an invalid character.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
put_shop(0 ,0 ,$item[wolf mask]);
put_shop(0 ,0 ,$item[rave whistle]);
put_shop(0 ,0 ,$item[giant needle]);
cli_execute ("undercut");
}
</syntaxhighlight>}}
will cause this error: Script parsing error (test.ash, line 5)

===Variable is already defined===

This indicates that the same variable has been declared twice.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int Drops ;
int Meat ;
int Drops = numeric_modifier("Item Drop");
</syntaxhighlight>}}
will cause this error: Variable Drops is already defined (test.ash, line 3)

{{RFI|Obviously, a lot more info is needed here.}}

[[Category:Scripting]]

ASH Errors

2010-08-26T03:08:15Z

PhilmASTErpLus: Added "cannot initialize parameter..." (finally!)

{{TOCright}}
Errors happen. When they do, it helps to have some idea of what what wrong.

===Abort===

Whenever a script runs the [[abort|abort()]] function, this error is generated.

{{CodeSample|
description=The zero-parameter form:|
code=
<syntaxhighlight>
abort();
</syntaxhighlight>}}
will stop the execution and print: KoLmafia declares world peace. Note that this message may also appear as a result of pressing Esc in the Main Interface or hitting "stop now" in the Adventure tab.

{{CodeSample|
description=The one-parameter form:|
code=
<syntaxhighlight>
abort("Aborting script...");
</syntaxhighlight>}}
will stop the execution and print: Aborting script...

===Cannot initialize parameter [parameter]====

This error is created when an assignment is attempted inside a function declaration.
The following code results in an error.

{{CodeSample|
code=
<syntaxhighlight>
/* test.ash */

void my_function( string myvar = "value" )
{
/* Do something */
}
</syntaxhighlight>}}

will halt the script and print: Cannot initialize parameter myvar (test.ash, line X)

===Cannot return [datatype] from [datatype] function===

This indicates that the return value does not match the function's type.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int stuff(){
return "4";
}
</syntaxhighlight>}}
will cause this error: Cannot return string value from int function (test.ash, line 2)

{{CodeSample|
description=Similarly, for void functions:|
code=
<syntaxhighlight>
void stuff(){
return 4;
}
</syntaxhighlight>}}
will cause this error: Cannot return a value from a void function (test.ash, line 2)

===Encountered '[break|continue]' outside loop===

This indicates that the control structure in question was not in a loop.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
continue;
</syntaxhighlight>}}
will cause this error: Encountered 'continue' outside of loop (test.ash, line 1)

===Expected===

This generally indicates a syntax problem (missing ending semi-colon, unmatched braces, unmatched parenthesis etc...).

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int a = 1
print(a);
</syntaxhighlight>}}
will cause this error: Expected ;, found print (test.ash, line 2)

===Function defined multiple times===

This indicates that the function in question has already been defined.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int abs(int a){
return a*((a>0).to_int()*2 - 1);
}
int abs(int a){
if(a<0) a = -a;
return a;
}
</syntaxhighlight>}}
will cause this error: Function <nowiki>'abs( int )'</nowiki> defined multiple times (test.ash, line 4)

==="if" requires a boolean conditional expression ===

This indicates that the condition inside an if statement is not a boolean.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
if(42) {
print("Don't panic.");
}
</syntaxhighlight>}}
will cause this error: "if" requires a boolean conditional expression (test.ash, line 1)

===Index type is not a primitive type===

This indicates that the map's index is not a standard datatype (float, int, string, etc.).

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
record alpha{
int a;
int b;
};
int[alpha] map;
</syntaxhighlight>}}
will cause this error: Index type 'alpha' is not a primitive type (test.ash, line 5)

===Invalid field name===

This indicates that the record does not contain the field in question.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
record my_record {
string a;
string b;
};

my_record [int] my_map;
my_map[1].c = "hello";
</syntaxhighlight>}}
will cause this error: Invalid field name 'c' (test.ash, line 7)

Note that this error may also be encountered when neglecting to name a field.
{{CodeSample|
description= For instance:|
code=
<syntaxhighlight>
record my_record {
string;
};
</syntaxhighlight>}}
will cause this error: Invalid field name ';' (test.ash, line 2)

===Invalid type name===

This indicates that the specified type is not recognized by Mafia.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int[fruit] map;
</syntaxhighlight>}}
will cause this error: Invalid type name 'fruit' (test.ash, line 1)

===Main method must appear at top level===

This indicates that the script's main method is inside another method, for some reason. This is usually caused by a missing brace.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
void stuff() {
// stuff happens here

void main() {
stuff();
}
</syntaxhighlight>}}
will cause this error: main method must appear at top level (test.ash, line 6)

===Missing return value===

The last line of a user-defined function has to be "return <value>;" (although the [[Control_Structures#return|return]] command can be used before too).

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int my_function( int a, int b ) {
if ( a > b ) return a ;
else return b ;
}
</syntaxhighlight>}}
will cause this error: Missing return value (test.ash, line 4)

===No closing found===

This can be caused by forgetting to put a '''"''' or a ''']''' at the end of an argument

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
buy(1000 , $item[disco ball, 225);
</syntaxhighlight>}}
will cause this error: No closing ] found (testing.ash, line 1)

===Record expected===

This indicates that an unrecognized record was found. This often appears when you forget to append "()" to a function name.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
print(4.to_string);
</syntaxhighlight>}}
will cause this error: Record expected (test.ash, line 2)

===Record name is already defined===

This indicates that the record name has already been defined, and so cannot be reused. The solution is to change the record name.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
record str {
string a;
string b;
};
record str {
int a;
int b;
};
</syntaxhighlight>}}
will cause this error: Record name 'str' is already defined (test.ash, line 5)

===Return needs [datatype] value===

This indicates that the return value is void when the function is not.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int stuff() {
return;
}
</syntaxhighlight>}}
will cause this error: Return needs int value (test.ash, line 2)

===Reserved word cannot be a [function|record|variable] name===

This indicates that the desired name has been [[Reserved Words|reserved]], and so cannot be used. The solution is to use a different name.

{{CodeSample|
description=An invalid name:|
code=
<syntaxhighlight>
int float(float a) {
return round(a);
}
</syntaxhighlight>}}
will cause this error: Reserved word 'float' cannot be used as a function name (test.ash, line 1)

An interesting point to note is that ASH functions take precedent over identically named custom functions rather than throw an exception.

{{CodeSample|
description=An invalid record name:|
code=
<syntaxhighlight>
record string {
string a;
string b;
};
</syntaxhighlight>}}
will cause this error: Reserved word 'string' cannot be a record name (test.ash, line 1)

{{CodeSample|
description=An invalid variable name:|
code=
<syntaxhighlight>
string item = "bottle of gin";
</syntaxhighlight>}}
will cause this error: Reserved word 'item' cannot be a variable name (test.ash, line 1)

===Script parsing error===

This generally indicates a syntax problem, as in having an excess amount of braces or a variable/function/record name that starts with an invalid character.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
put_shop(0 ,0 ,$item[wolf mask]);
put_shop(0 ,0 ,$item[rave whistle]);
put_shop(0 ,0 ,$item[giant needle]);
cli_execute ("undercut");
}
</syntaxhighlight>}}
will cause this error: Script parsing error (test.ash, line 5)

===Variable is already defined===

This indicates that the same variable has been declared twice.

{{CodeSample|
description=Example:|
code=
<syntaxhighlight>
int Drops ;
int Meat ;
int Drops = numeric_modifier("Item Drop");
</syntaxhighlight>}}
will cause this error: Variable Drops is already defined (test.ash, line 3)

{{RFI|Obviously, a lot more info is needed here.}}

[[Category:Scripting]]

Regex

2010-08-26T01:59:30Z

PhilmASTErpLus: Redirected page to Regular Expressions

#REDIRECT [[Regular Expressions]]

Mall price

2010-08-26T01:25:23Z

PhilmASTErpLus: A bit of information about untradeable items.

{{
#vardefine:name|mall_price}}{{
#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|shop_for}}|
p1desc={{Pspan|shop_for}} is the item to inquire on the mall price of|
}}|

function_description=Returns the current mall price of the given item, ignoring the first five items listed to compensate for stores with limits and min-priced sales. This function runs a new check each time it is called, so if you call this function and then purchase some of {{pspan|shop_for}} in the mall, calling this function again will return the new price of the item, again ignoring the first five.|

needscode=yes|

see_also={{SeeAlso|historical_price|buy|retrieve_item}}|
cli_equiv=The CLI command "searchmall" also returns current mall prices.|
special=Items not listed in the mall will return 0 (untradeable items will return 0 without any server requests). When not logged in, this function returns -1.|
}}

[[Category:Item Management]]

Weapon type

2010-08-23T02:17:49Z

PhilmASTErpLus: A few tests (Gnollish pie server, eggbeater, etc) tell me that weapons without stat requirements still yield stats based on their type (melee/ranged/mysticality weapon)

{{
#vardefine:name|weapon_type}}{{
#vardefine:return_type|stat}}{{

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|check_me}}|
p1desc={{Pspan|check_me}} is the item to check|
}}|

function_description=Returns the equip requirement stat for {{pspan|check_me}}, even if the weapon does not have any stat requirements. If {{pspan|check_me}} is not a weapon, this function returns $stat[none].|

needscode=yes|

see_also={{SeeAlso|weapon_hands}}|
}}

[[Category:Equipment]]

Get version

2010-07-30T15:03:38Z

PhilmASTErpLus: Added another code sample. I'm not sure whether checking for version/revision is the best method of feature detection.

{{
#vardefine:name|get_version}}{{
#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 latest version of KoLmafia pertaining to your current build.|
code1={{CodeSample|
title=Code Sample|
description=Will tell you when there is a new version of mafia|
code=
<syntaxhighlight>
string vers = get_version();
string page = visit_url("http://sourceforge.net/projects/kolmafia/files/");
string current = substring ( page, index_of ( page , "Download Now" ) , last_index_of ( page , "View all files" ) );
if (!contains_text( current , vers ))
print ("There is a new version. Go get it here http://sourceforge.net/projects/kolmafia/files/", "red");
else
print ("You are already using the most current version of KoLmafia.", "blue");
</syntaxhighlight>
}}|
code2={{CodeSample|
description=The following example prompts the user to update KoLmafia so as to handle newly introduced items and locations.|
code=
<syntaxhighlight>
if ( to_float( get_version() ) < 14.1 ) //Check Vanya's Castle and Kegger in the Woods
abort( "The current version does not support Uncle P's maps. Please update KoLmafia." );
</syntaxhighlight>
}}|
more_info=Note that a revision is distinct from a build in that a revision is a developer-sanctioned release of enough significance as to be promoted for the general public's use. When using a daily build, this function returns the most recent official version.|
see_also={{SeeAlso|get_revision}}|
}}
[[Category:Miscellaneous Functions]]

Talk:ASH Errors

2010-07-29T13:17:55Z

PhilmASTErpLus: Thanks for input, but does anyone know whether there exists other forms of code that can cause this error?

Is this like were things like Script parsing error (X.ash, line Y) are listed?--[[User:Icon315|Icon315]] 22:33, 14 April 2010 (UTC)

:It's where they WILL be listed, once they are listed. --[[User:Bale|Bale]] 22:52, 14 April 2010 (UTC)

What Bale said. Also, I changed that to orange; I kept trying to click on it. :( --[[User:StDoodle|StDoodle (#1059825)]] 00:35, 15 April 2010 (UTC)

Also, if anyone's feeling particularly ambitious, https://kolmafia.svn.sourceforge.net/svnroot/kolmafia/src/net/sourceforge/kolmafia/textui/Parser.java should help. Just look for all the instances of parseException. (Speaking of which, would it be useful if these were presented in the order that they're checked?) --[[User:Heeheehee|Heeheehee]] 00:17, 17 April 2010 (UTC)

I think alphabetical order would be better: this page is going to be excellent for first-time ASH scripters to understand what's wrong with their script. --[[User:Slyz|Slyz]] 10:41, 17 April 2010 (UTC)

Should we add the correct examples? Or are the fixes clear enough?
--[[User:Slyz|Slyz]] 08:36, 18 April 2010 (UTC)

If anything particularly complicated shows, we can give both. But so far, if you can't follow as written, I'm not sure you ever will. (That's the hypothetical "you," not the specific "hey Slyz what's wrong with you, you"). --[[User:StDoodle|StDoodle (#1059825)]] 23:35, 19 April 2010 (UTC)

{{CodeSample|description=The following code results in an error.
|code=<syntaxhighlight>
void my_function( string myvar = "value" )
{
/* Do something */
}
</syntaxhighlight>}}
Error message: <blockquote>Cannot initialize parameter myvar (filename.ash, line X)</blockquote>
I'd like to add this to the article myself, but I'm not sure how to explain its exact nature. Would this message appear only in a situation like the above code? --[[User:PhilmASTErpLus|PhilmASTErpLus]] 09:30, 28 July 2010 (UTC)
: Looks like a conflict of functionality -- the two ways to initialize a variable are '''string myvar''' and '''string myvar = "value"'''. The only proper way to define a parameter is the former. So basically you're defining a parameter, which then gets initialized with a value. This would lead to all sorts of problems, so the parser catches this exception and throws an error. I'm not really sure why anyone would want to do this, but I guess you can add it? (fun fact: the value that you set the parameter to doesn't actually have to match the datatype for this error to appear) --[[User:Heeheehee|Heeheehee]] 16:47, 28 July 2010 (UTC)

I'm guessing he tried it for the same reason I did; in some languages, that's how you provide a default value for a parameter. It's usually functionally equivalent to having two different versions of my_function() defined, one which accepts a single string, and one which accepts no parameters, and calls the other with the default value. Usually it isn't a big deal to do things one way or the other, but the method given above can actually be much simpler if you get into a large number of overloaded versions of a single function. --[[User:StDoodle|StDoodle (#1059825)]] 18:30, 28 July 2010 (UTC)
: In that case, would this be a reasonable low-priority feature request? --[[User:Heeheehee|Heeheehee]] 18:44, 28 July 2010 (UTC)

That's up to the devs, but I have a feeling it would be a non-trivial change to get a trivial benefit, and therefore ignored. Unless someone has a good argument for a situation in which it would make a huge difference. --[[User:StDoodle|StDoodle (#1059825)]] 21:08, 28 July 2010 (UTC)

{{CodeSample|description=Hardly worth suggesting. The KoLmafia method works just fine:
|code=<syntaxhighlight>
void my_function()
{
my_function("value");
}
</syntaxhighlight>}}
--[[User:Bale|Bale]] 04:31, 29 July 2010 (UTC)
:Yeah, when I posted that code, I wasn't thinking about requesting for a default parameter feature. All I'd like to know is whether there is a general case that will trigger this particular error message; for example, I would have expected this instead of "expected ) but got =" message when I tried assignment in the conditional for the <code>if</code> and <code>while</code> statements. --[[User:PhilmASTErpLus|PhilmASTErpLus]] 13:17, 29 July 2010 (UTC)

Talk:ASH Errors

2010-07-28T09:35:14Z

PhilmASTErpLus:

Talk:ASH Errors

2010-07-28T09:31:04Z

PhilmASTErpLus:

Talk:ASH Errors

2010-07-28T09:30:08Z

PhilmASTErpLus: Another error message I found.

ASH For Beginners

2010-07-27T08:08:54Z

PhilmASTErpLus: Undo revision 9457 by PhilmASTErpLus (Talk) - erm, okay.

{{TOCright}}
==File Editing==
To create and edit ASH scripts, you need a text editing program that doesn't automatically add line-breaks for word wrapping.

===Mac===
While the built in editor TextEdit will work fine (as long as you remember to write only in plaintext), [http://www.barebones.com/products/textwrangler/ TextWrangler] is a much more powerful tool. It may not be designed for ASH scripting specifically, but it was written for a similar purpose.

===Linux===
If you use Linux, you probably already know about the options available for text editing. Emacs, Vi, etc. are all fine for creating ASH scripts.

===Windows===
Windows users beware; using Microsoft Word to create ASH files will lead to no end of headaches! The built-in program notepad will work, as can wordpad when configured with the option "No Wrap" for text. However, having a program that can handle syntax-highlighting can be very beneficial. Many scripters recommend [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] for ASH (and other programmatic) scripting. In this case, it's also beneficial to have a style configuration that works well with ASH, and one example can be found [http://kolmafia.us/showthread.php?3164-How-do-you-write-an-ASH-file&p=21567&viewfull=1#post21567 here].

==Saving==
ASH scripts need to be saved with the file extension ".ash" to be properly recognized by KoLmafia. If you're using a built-in text editor on a Windows machine, it may automatically save your files with the ".txt" extension by default. (So you may end up with a file called "script.ash.txt" instead of the desired "script.ash".) One way around this on Windows that usually works is to put quotes around the file name when you save it, including the extension.

Most advanced text editors (such as Notepad++) will save files as specified, without the need for the quotes-trick.

Most files should be saved in the "scripts" directory, which is located by default at the same directory level as the KoLmafia .jar or .exe file on Windows. You can also create a sub-directory under "scripts," and it will be listed in KoLmafia's Scripts Menu.

Relay browser scripts are the exception to the rule: they must be saved in the "relay" directory. Relay browser overrides need to be saved in the top level of "relay," and must be named the same as the page they will override, except with an ".ash" extension. For example, to override "charpane.php" your script would need to be named "charpane.ash". For user-interface scripts, the script name needs to start with "relay_" and end with ".ash". These scripts must also be saved in the top-level of the "relay" directory.

==Programming==
You should first read through the various pages listed under "LANGUAGE CONVENTIONS" on the [[Main Page]]. One should also be aware that, with the exception of [[Control Structures]], all ASH commands need to end with a semi-colon.

===Variables===
Variables are used to hold information that you need to access multiple times. They must be declared before they can be used, by specifying the [[Data Types|Data Type]] that they will hold, followed by the variable name.
{{CodeSample|description=For example:|code=<syntaxhighlight>int count;</syntaxhighlight>}}
would declare a variable named "count" of an integer type. You can also set the initial value of a variable on the same line it is declared.
{{CodeSample|description=For example:|code=<syntaxhighlight>int count = 6;</syntaxhighlight>}}
would declare the variable "count" again, with an initial value of 6.

Notice that you would not want to have both of the above lines in your script! Variables operate under what's referred to as their scope. In a nutshell, scope defines where a variables is accessible. Scope "cascades" down, similar to stylesheets for those familiar with web programming. A variable declared at the top-level of a script (a "global" variable), outside of any functions, will be accessible anywhere in your script, or in any other scripts that import it. A variable declared inside of a function will be accessible only inside that function (including inside of control structures), but is considered to not exist by other functions.

Declaring a variable multiple times will generate an [[ASH Errors#Variable is already defined|error]]. Note that this only applies to variable with overlapping scope; if one function uses a variable named "bob" that is declared inside of the function, another function can declare another variable with the same name, even as a different datatype. However, the error will still occur if you have a globally-defined variable, and then declare a variable with the same name inside of a function (as their scopes overlap).

===Functions===
Functions are groupings of operations that can be applied multiple times by referencing the function name. Basically, they avoid having to re-type the same code over and over. Many functions are built-in to KoLmafia, and examples can be found all over this wiki. It's also possible to write your own functions. To do so, you declare them similarly to a variable as above. However, a function can also have the datatype of "void," which is not allowed for variables. A "void" function is one that does not return any value; it simply does what it's programmed to do and the rest of your program moves on, regardless of the results (unless of course an [[ASH Errors|error]] occurs, including a call to [[abort|abort()]].)
{{CodeSample|description=For example, this simple function will double an integer:|code=<syntaxhighlight>
int double_it(int value) {
return 2 * value;
}
</syntaxhighlight>}}
{{CodeSample|description=Furthermore, there are two distinct ways to call functions, user-defined or built-in: Conventional,|code=<syntaxhighlight>
function(param1[,param2,param3,...]);
</syntaxhighlight>}}
{{CodeSample|description=and "Java style":|code=<syntaxhighlight>
param1.function([param2,param3,...]);
</syntaxhighlight>}}
The only difference between the two forms is aesthetics, as they are functionally equivalent.
{{CodeSample|description=Also somewhat important to note is that these commands can be chained together, and they will be executed from left-to-right. So, for instance,|code=<syntaxhighlight>
"polka pop".to_item().to_int()
</syntaxhighlight>}}
{{CodeSample|description=will return the item number for $item[Polka Pop], 4342. This is one instance where "Java style" is more aesthetically pleasing compared to the conventional|code=<syntaxhighlight>
to_int(to_item("polka pop"))
</syntaxhighlight>}}

===String Concatenation===
The basics to string concatenation: "Hello" + "world" yields "Helloworld". Likewise, variables can be strung together in this fashion. Unless the variables are both numbers (floats, booleans, or ints), they will be converted to strings, then concatenated.
Argh, me tired, finish later.

[[Category:Scripting]]

ASH For Beginners

2010-07-27T04:20:07Z

PhilmASTErpLus: /* Programming */ Rather blunt information on references.

{{TOCright}}
==File Editing==
To create and edit ASH scripts, you need a text editing program that doesn't automatically add line-breaks for word wrapping.

===Mac===
While the built in editor TextEdit will work fine (as long as you remember to write only in plaintext), [http://www.barebones.com/products/textwrangler/ TextWrangler] is a much more powerful tool. It may not be designed for ASH scripting specifically, but it was written for a similar purpose.

===Linux===
If you use Linux, you probably already know about the options available for text editing. Emacs, Vi, etc. are all fine for creating ASH scripts.

===Windows===
Windows users beware; using Microsoft Word to create ASH files will lead to no end of headaches! The built-in program notepad will work, as can wordpad when configured with the option "No Wrap" for text. However, having a program that can handle syntax-highlighting can be very beneficial. Many scripters recommend [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] for ASH (and other programmatic) scripting. In this case, it's also beneficial to have a style configuration that works well with ASH, and one example can be found [http://kolmafia.us/showthread.php?3164-How-do-you-write-an-ASH-file&p=21567&viewfull=1#post21567 here].

==Saving==
ASH scripts need to be saved with the file extension ".ash" to be properly recognized by KoLmafia. If you're using a built-in text editor on a Windows machine, it may automatically save your files with the ".txt" extension by default. (So you may end up with a file called "script.ash.txt" instead of the desired "script.ash".) One way around this on Windows that usually works is to put quotes around the file name when you save it, including the extension.

Most advanced text editors (such as Notepad++) will save files as specified, without the need for the quotes-trick.

Most files should be saved in the "scripts" directory, which is located by default at the same directory level as the KoLmafia .jar or .exe file on Windows. You can also create a sub-directory under "scripts," and it will be listed in KoLmafia's Scripts Menu.

Relay browser scripts are the exception to the rule: they must be saved in the "relay" directory. Relay browser overrides need to be saved in the top level of "relay," and must be named the same as the page they will override, except with an ".ash" extension. For example, to override "charpane.php" your script would need to be named "charpane.ash". For user-interface scripts, the script name needs to start with "relay_" and end with ".ash". These scripts must also be saved in the top-level of the "relay" directory.

==Programming==
You should first read through the various pages listed under "LANGUAGE CONVENTIONS" on the [[Main Page]]. One should also be aware that, with the exception of [[Control Structures]], all ASH commands need to end with a semi-colon.

===Variables===
Variables are used to hold information that you need to access multiple times. They must be declared before they can be used, by specifying the [[Data Types|Data Type]] that they will hold, followed by the variable name.
{{CodeSample|description=For example:|code=<syntaxhighlight>int count;</syntaxhighlight>}}
would declare a variable named "count" of an integer type. You can also set the initial value of a variable on the same line it is declared.
{{CodeSample|description=For example:|code=<syntaxhighlight>int count = 6;</syntaxhighlight>}}
would declare the variable "count" again, with an initial value of 6.

Notice that you would not want to have both of the above lines in your script! Variables operate under what's referred to as their scope. In a nutshell, scope defines where a variables is accessible. Scope "cascades" down, similar to stylesheets for those familiar with web programming. A variable declared at the top-level of a script (a "global" variable), outside of any functions, will be accessible anywhere in your script, or in any other scripts that import it. A variable declared inside of a function will be accessible only inside that function (including inside of control structures), but is considered to not exist by other functions.

Declaring a variable multiple times will generate an [[ASH Errors#Variable is already defined|error]]. Note that this only applies to variable with overlapping scope; if one function uses a variable named "bob" that is declared inside of the function, another function can declare another variable with the same name, even as a different datatype. However, the error will still occur if you have a globally-defined variable, and then declare a variable with the same name inside of a function (as their scopes overlap).

===Functions===
Functions are groupings of operations that can be applied multiple times by referencing the function name. Basically, they avoid having to re-type the same code over and over. Many functions are built-in to KoLmafia, and examples can be found all over this wiki. It's also possible to write your own functions. To do so, you declare them similarly to a variable as above. However, a function can also have the datatype of "void," which is not allowed for variables. A "void" function is one that does not return any value; it simply does what it's programmed to do and the rest of your program moves on, regardless of the results (unless of course an [[ASH Errors|error]] occurs, including a call to [[abort|abort()]].)
{{CodeSample|description=For example, this simple function will double an integer:|code=<syntaxhighlight>
int double_it(int value) {
return 2 * value;
}
</syntaxhighlight>}}
{{CodeSample|description=Furthermore, there are two distinct ways to call functions, user-defined or built-in: Conventional,|code=<syntaxhighlight>
function(param1[,param2,param3,...]);
</syntaxhighlight>}}
{{CodeSample|description=and "Java style":|code=<syntaxhighlight>
param1.function([param2,param3,...]);
</syntaxhighlight>}}
The only difference between the two forms is aesthetics, as they are functionally equivalent.
{{CodeSample|description=Also somewhat important to note is that these commands can be chained together, and they will be executed from left-to-right. So, for instance,|code=<syntaxhighlight>
"polka pop".to_item().to_int();
</syntaxhighlight>}}
{{CodeSample|description=will return the item number for $item[Polka Pop], 4342. This is one instance where "Java style" is more aesthetically pleasing compared to the conventional|code=<syntaxhighlight>
to_int(to_item("polka pop"));
</syntaxhighlight>}}

===String Concatenation===
The basics to string concatenation: "Hello" + "world" yields "Helloworld". Likewise, variables can be strung together in this fashion. Unless the variables are both numbers (floats, booleans, or ints), they will be converted to strings, then concatenated.
Argh, me tired, finish later.

===References===

Most variables in ASH are called or passed "by value"—when they are given to other variables, they actually receive a copy of the variable. Such copies are transparently created in these cases:
*Passing variables as function arguments
*Returning a variable from a function
*Assigning a variable with a value.
However, some variables and data structures are often too large to make copies whenever you want to pass them to functions or assign other variables with their values. In such cases, ASH performs a call or pass "by reference", and makes the variables/data structures point to the same data in memory.
{{CodeSample|description=For example, assigning a map to another map will make them access a single map in memory.
|code=<syntaxhighlight>
string [int] mymap1 , mymap2;
file_to_map( "some_file.txt" , mymap1 ); //Fill mymap1 with data
mymap2 = mymap1; //Now, mymap2 points to mymap1

mymap2[ 12345 ] = "test value";
print( mymap1 [12345] ); //Displays: test value
</syntaxhighlight>}}
Most [[Data Types|data types]] are passed by value, whereas all aggregates and <code>buffer</code>s are passed by reference. Note that <code>string</code>s are passed by value; therefore, you should use <code>buffer</code>s instead when performing many string-related operations.

[[Category:Scripting]]

File to map

2010-07-17T04:46:51Z

PhilmASTErpLus: The entire contents of the map is wiped before loading new data from the file. Verified with KoLmafia r8532.

{{
#vardefine:name|file_to_map}}{{
#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|file_to_load}}|
parameter2={{Param|aggregate|map_to_fill}}|
}}|

function2={{Function|
name={{#var:name}}|
aggregate={{#var:aggregate}}|
return_type={{#var:return_type}}|
return_also={{#var:return_also}}|
parameter1={{Param|string|file_to_load}}|
parameter2={{Param|aggregate|map_to_fill}}|
parameter3={{Param|boolean|compact}}|
p1desc={{Pspan|file_to_load}} is the filename to load from|
p2desc={{Pspan|map_to_fill}} is the map to populate with data|
p3desc={{Pspan|compact}} is an (optional) flag; if omitted or true, records that do not contain any aggregate values are expected to be written on a single line, rather that one line per field.|
}}|

function_description=Loads data to the {{pspan|map_to_fill}} from a saved {{pspan|file_to_load}} in your KoLmafia "data" or "scripts" directory. Any data originally stored in the {{pspan|map_to_fill}} are wiped before loading the file. The {{pspan|compact}} parameter is not needed unless you specified it in the [[map_to_file|map_to_file()]] call that originally generated the file, in which case the values must match. This function returns the operation's success. If {{pspan|map_to_fill}} has not been delcared, this function will abort (as oppossed to returning false).

You can also directly load internal data files used by KoLmafia, such as concoctions.txt and fullness.txt, by specifying their name--KoLmafia will automatically load the file for you. For a full list of internal data files used by KoLmafia, see the [http://kolmafia.svn.sourceforge.net/viewvc/kolmafia/src/data/ KoLmafia source repository].|

code1={{CodeSample|
title=Code Sample|
description=This sample loads a simple map that includes item names keyed by a number.|
code=
<syntaxhighlight>
string [int] my_list;
file_to_map( "SavedList.txt" , my_list);
for i from 0 to (count(my_list) - 1) {
print( "At index: " + i + " We find: " + my_list[i] );
}
</syntaxhighlight>
}}
If the file "SavedList.txt" had the following:
<pre>
0 StDoodle
1 Grotfang
</pre>
Then the results would be:
<pre>
At index: 0 We find: StDoodle
At index: 1 We find: Grotfang
</pre>
{{CodeSample|
description=The following sample loads the full list of {{kolwiki|Category:Spleentacular Items|spleen-damaging items}} from [http://kolmafia.svn.sourceforge.net/viewvc/kolmafia/src/data/spleenhit.txt spleenhit.txt].|
code=<syntaxhighlight>
int [item] spleen_hits;
file_to_map( "spleenhit.txt" );

foreach itm, spleen_hit in spleen_hits
print( itm + " will damage " + spleen_hit + " of your spleen." );
</syntaxhighlight>|
}}|

see_also={{SeeAlso|map_to_file|}}|
more_info=You can load any information stored in a data file, as long as your map contains the appropriate [[Data Types]] separated by tabs. Spaces are just considered to be part of a string. 
Any line that begins with a number sign (<code>#</code>) is considered a comment, and is ignored by KoLmafia.|
}}

[[Category:Miscellaneous Functions]]

Print

2010-07-17T04:35:11Z

PhilmASTErpLus: Added link to W3C CSS color specs

{{
#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|logprint|print_html}}|
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= Using an invalid color name or code can cause odd colors to be chosen; see the [[Talk:Print|Talk Page]] for details.|
}}

[[Category:Miscellaneous Functions]]

Talk:Print

2010-07-17T04:32:12Z

PhilmASTErpLus: Browsing through KoLmafia tells me it uses the Swing HTML parser, which probably explains why it doesn't understand colornames like "AliceBlue".

Re: "How does color selection work when the specified color name / entity is invalid?" 
It returns with the default, black. That is, unless '> ash print("Hello world!","apple-orange");' returns a color that looks really close to black. (No, I'm not color-blind. It returns black. Even for faulty entities, like "42".) 
Edit: Apparently it doesn't recognize somewhat uncommon colors, like "lavender".
--[[User:Heeheehee|Heeheehee]] 06:47, 10 March 2010 (UTC)

That's true for named colors, but for numbers it appears to interpret some part of the number and chop the rest off; it was just a bit more than I wanted to look up in the moment. For instance, if you supply "#ff00000" (which is red with an extra 0), it used red; the "#" appears to make it choose the first 6 digits. However, you can leave off the "#" and it still works as expected with a 6-digit or 3-digit number; but anything else seems to be a weird substring match for which I can't find the logic.--[[User:StDoodle|StDoodle]] 13:26, 10 March 2010 (UTC)

Okay. I think I've fully worked out the logic for the numbers.
# If there's a # in front, take the first 6 digits that follow.
# If length = 6, skip to the last step.
# Remove all zeroes in the front of the string (e.g. "#00 00 F0 00 00" becomes "F0 00 00").
# If length > 7, replace the whole thing with "#00 00 00" (i.e. black).
# If length = 7, remove the first character (e.g. the red displayed from "#ff0 00 00" is actually "#f0 00 00").
# If length < 6, add zeroes to the front until length = 6 (e.g. "#42" becomes "#00 00 42", which looks pretty close to black -- hence my earlier misunderstanding).
# Pass the resultant value as your color.

:Perhaps KoLmafia uses some variant of the color parsing/interpreting scheme used in CSS, as it apparently supports the syntax <code>"rgb(148, 0, 211)"</code> and <code>"rgb(148 0 211)"</code>. We would need to look at the source code to confirm this... --[[User:PhilmASTErpLus|PhilmASTErpLus]] 17:00, 16 July 2010 (UTC)
:: IIRC, it passes it directly to HTML -- '''print(a,b)''' is functionally equivalent to '''print_html(""+a+"")'''. --[[User:Heeheehee|Heeheehee]] 17:18, 16 July 2010 (UTC)
:::It seems to use the native Swing HTML parser, which does not understand many unofficial colornames (see [http://www.w3.org/TR/CSS21/syndata.html#color-units CSS 2.1 color specification] and [http://www.w3.org/TR/html401/types.html#h-6.5 HTML 4.01 color specification] for color syntax. W3schools has a [http://www.w3schools.com/css/css_colornames.asp list of non-standard color names] supported by all major browsers.). --[[User:PhilmASTErpLus|PhilmASTErpLus]] 04:32, 17 July 2010 (UTC)
This ASH function might help with understanding:
string color (string input) {
if(index_of(input, "#" && length(input)>6) == 0) return substring(input, 0, 6);
if(length(input) == 6) return input;
while(index_of(input, "0") == 0) input = substring(input, 1);
if(length(input)>7) return "000000";
if(length(input)==7) return substring(input, 1);
while(length<6) input = "0" + input;
return input;
}
(is that too much string manipulation?)
--[[User:Heeheehee|Heeheehee]] 02:44, 14 March 2010 (UTC)

Re: the former RFI (echoing print statements to the adventuring status line)

I was referring to the version of such that is also shown on the login / logout screen, which I feel is relevant as there isn't a good way to give feedback on a logout script otherwise (currently, I have a logout script that uses a user_confirm() for the clunky purpose of getting around this). If there's a way I'm unaware of to deal with this, that would be fine; but otherwise I'd like to know if print() could once again place text there, or if I'm mis-remembering. --[[User:StDoodle|StDoodle (#1059825)]] 00:53, 30 April 2010 (UTC)
:Ah. I can see why you'd want that. Post it in a feature request on the mafia forums. That's the proper place for it. Then if your desire is granted we can update this page. :D --[[User:Bale|Bale]] 02:07, 30 April 2010 (UTC)

New

2010-07-16T17:17:38Z

PhilmASTErpLus: Whoops, didn't know it accepted parameters. Shouldn't have looked at it while sleepy. Fixed.

{{DISPLAYTITLE:new}}
Syntax: new ''record'' ( param, ... );
: ''record'' is the record to use.

Returns an instance of the given record, filling each field of the record with the given parameters. If no parameter is given, each field is filled with the default value of that type. For the default values of various types, see [[Data Types]].

For instance:
<div style="margin-bottom: 1em; border: dashed 1px green; padding: 1em; margin:0px 20px;"><syntaxhighlight>
record dblstr{
string a;
string b;
};

dblstr test;
test.a = "hello";
test.b = "world";
</syntaxhighlight></div>
is functionally identical to
<div style="margin-bottom: 1em; border: dashed 1px green; padding: 1em; margin:0px 20px;"><syntaxhighlight>
record dblstr{
string a;
string b;
};

dblstr test = new dblstr("hello","world");
</syntaxhighlight></div>

{{Format}}

[[Category:ASH Scripting]]

User:PhilmASTErpLus

2010-07-16T17:13:11Z

PhilmASTErpLus: Added link to test_new.ash

I'm using this page as my own personal sandbox :) Please contribute your comments, opinions, and ideas in the [[User Talk:PhilmASTErpLus|talk page]].

--[[User:PhilmASTErpLus|PhilmASTErpLus]] 02:36, 21 June 2010 (UTC)

"Datatype constants" are literals that begin with a dollar sign($), such as <code>$item[]</code>, <code>$effect[]</code>, etc. Types of data, such as <code>boolean</code> and <code>int</code>, are called [http://en.wikipedia.org/wiki/Data_type Data Types].

That is true, and deserves fixing; but please don't do so in a way that breaks a massive amount of links, ktx. --[[User:StDoodle|StDoodle (#1059825)]] 04:18, 21 June 2010 (UTC)

Heh, that's okay (re: discussion on Datatype Constants). For most pages it isn't a huge issue, but that one... it requires fixing in quite a few places, some of which unfortunately won't be automatically be fixed by redirects during a page move (this seems to happen when some of the links are from templates, which this page has a massive number of). For reference, this wiki has problems with both the "design by committee" philosophy & the "legacy problems" philosophy. Originally, the stuff here was simply copy & pasted from an guide that had been hosted elsewhere, which itself was about 2/3 original material and 1/3 copied from Hola's old reference material. That led to the problem of pages having inappropriate names, as by the time the issue was given thought, they were deeply ingrained in the wiki structure. Then there's the "committee" issue, which resulted in some over-elaborate templates. For the most part, the last issue doesn't present any issues with searching and display, but does up the learning curve for "proper" page editing in some places (mostly on the function pages). In the end, I'm glad to have another person interested in helping; but please, before making any massive-scale (many pages) edits, or moving pages, a discussion would be appreciated. As you now know, there are "methods in the madness" for some of this stuff... ;) Also, if you want to help with getting Datatype Constants corrected, I'd be happy to jot down some notes on what needs to be done in the next day or so. --[[User:StDoodle|StDoodle (#1059825)]] 15:51, 21 June 2010 (UTC)

P.S. User pages such as this are the perfect places for sandboxing & discussion; you can even make sub-pages in your own wiki-space by linking to them from here, with a "/" as the first character of the page name. Since user pages are outside of the normal search parameters, feel free to use them however you wish.

== To-Do ==

*Report & document ASH quirks
**{{f|print}} displays a blank line when given a string starting with a slash (<code>/</code>). To prevent this, the text color must be explicitly given. Easy to bypass, but weird.
**{{f|file_to_map}} ignores lines beginning with a sharp character (<code>#</code>), or any line that does not have a tab character in it.
*Make a [[Functions|page about functions in general]].
**Clarify call-by-value and call-by-reference, somewhere...
***Results from a [http://sites.google.com/site/philmasterplus/files/callby.ash test script] I made:
****Call by value: most types (boolean, int, float, string, item, effect, class, stat, skill, familiar, slot, location)
****Call by reference: aggregates (maps, records), buffer
**Notes: KoLmafia makes no implicit type conversion, unless the function itself supports one. Buffers and strings seem to be an exception.

=== Done ===

*Add information on directly accessing kolmafia data files--equipment.txt, pulverize.txt, etc. => see {{f|file_to_map}}
*[[Image:item_category.png|150px]] would go nicely in the pages for [[Item Management]]-related functions.
*To anyone who cares: the image above was created in Microsoft PowerPoint. You can get it [http://sites.google.com/site/philmasterplus/files/kolmafia_wiki.ppt here].

== External Links ==

*[http://sites.google.com/site/philmasterplus/files/test_new.ash test_new.ash] - tests the [[new]] command.

Data Types

2010-07-16T17:09:28Z

PhilmASTErpLus: Added information about default values for various types, tested myself with KoLmafia r8532. See my user page for the code that was used to test this (using the 'new' command)

{{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.

===float===

The float data type is a single-precision 32-bit IEEE 754 floating point. Its range of values is beyond the scope of this discussion, but is specified in section 4.2.3 of the Java Language Specification. [http://java.sun.com/docs/books/jls/third_edition/html/typesValues.html#4.2.3]

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>.

===class===

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

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

===effect===

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

The full range, besides $effect[ none ], is too much to list and keep up with here: please see the [http://kol.coldfront.net/thekolwiki/index.php/Effects Coldfront Wiki] page for more information.

===element===

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

* cold
* hot
* sleaze
* spooky
* stench
* slime

===familiar===

Any familiar available in KoL is valid for this datatype.

The full range, besides $familiar[ none ], is too much to list and keep up with here: please see the [http://kol.coldfront.net/thekolwiki/index.php/Familiars Coldfront Wiki] page for more information.

===item===

Any item in all of KoL is valid for this datatype. Note that unlike most special datatypes, item references can make use of the item ID number.
{{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 [http://kol.coldfront.net/thekolwiki/index.php/Items Coldfront Wiki] page for more information.

===location===

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

The full range, besides $location[ none ], is too much to list and keep up with here: please see the [http://kol.coldfront.net/thekolwiki/index.php/Locations Coldfront Wiki] page for more information.

===monster===

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

The full range, besides $monster[ none ], is too much to list and keep up with here: please see the [http://kol.coldfront.net/thekolwiki/index.php/Monster_Compendium Coldfront Wiki] page for more information.

===skill===

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

The full range, besides $skill[ none ], is too much to list and keep up with here: please see the [http://kol.coldfront.net/thekolwiki/index.php/Skills Coldfront Wiki] page for more information.

===slot===

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

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

===stat===

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

* muscle
* mysticality
* moxie
* submuscle
* submysticality
* submoxie

==Aggregate==

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

==Record==

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

==Plural Typed Constants==

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

Plural typed constants allow you to easily do something with a list of specified objects, without having to replicate code or laboriously build up an array of the objects so that you can iterate over it. Here's a quick example:
{{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:ASH Scripting]]

New

2010-07-16T17:01:45Z

PhilmASTErpLus: Brief explanation. Also, we need to explain what the default value of each type is.

{{DISPLAYTITLE:new}}
Syntax: new ''record'' ( param, ... );
: ''record'' is the record to use.

Returns an instance of the given record, where each field is filled with the default value of that type. For the default values of various types, see [[Data Types]].

For instance:
<div style="margin-bottom: 1em; border: dashed 1px green; padding: 1em; margin:0px 20px;"><syntaxhighlight>
record dblstr{
string a;
string b;
};

dblstr test;
test.a = "hello";
test.b = "world";
</syntaxhighlight></div>
is functionally identical to
<div style="margin-bottom: 1em; border: dashed 1px green; padding: 1em; margin:0px 20px;"><syntaxhighlight>
record dblstr{
string a;
string b;
};

dblstr test = new dblstr("hello","world");
</syntaxhighlight></div>

{{Format}}

[[Category:ASH Scripting]]

Talk:Print

2010-07-16T17:00:41Z

PhilmASTErpLus: KoLmafia can also interpret "rgb(x, y, z)". Should we try to clarify this once and for all (by looking at the source code) and explain it on the main page?

Re: "How does color selection work when the specified color name / entity is invalid?" 
It returns with the default, black. That is, unless '> ash print("Hello world!","apple-orange");' returns a color that looks really close to black. (No, I'm not color-blind. It returns black. Even for faulty entities, like "42".) 
Edit: Apparently it doesn't recognize somewhat uncommon colors, like "lavender".
--[[User:Heeheehee|Heeheehee]] 06:47, 10 March 2010 (UTC)

That's true for named colors, but for numbers it appears to interpret some part of the number and chop the rest off; it was just a bit more than I wanted to look up in the moment. For instance, if you supply "#ff00000" (which is red with an extra 0), it used red; the "#" appears to make it choose the first 6 digits. However, you can leave off the "#" and it still works as expected with a 6-digit or 3-digit number; but anything else seems to be a weird substring match for which I can't find the logic.--[[User:StDoodle|StDoodle]] 13:26, 10 March 2010 (UTC)

Okay. I think I've fully worked out the logic for the numbers.
# If there's a # in front, take the first 6 digits that follow.
# If length = 6, skip to the last step.
# Remove all zeroes in the front of the string (e.g. "#00 00 F0 00 00" becomes "F0 00 00").
# If length > 7, replace the whole thing with "#00 00 00" (i.e. black).
# If length = 7, remove the first character (e.g. the red displayed from "#ff0 00 00" is actually "#f0 00 00").
# If length < 6, add zeroes to the front until length = 6 (e.g. "#42" becomes "#00 00 42", which looks pretty close to black -- hence my earlier misunderstanding).
# Pass the resultant value as your color.

:Perhaps KoLmafia uses some variant of the color parsing/interpreting scheme used in CSS, as it apparently supports the syntax <code>"rgb(148, 0, 211)"</code> and <code>"rgb(148 0 211)"</code>. We would need to look at the source code to confirm this... --[[User:PhilmASTErpLus|PhilmASTErpLus]] 17:00, 16 July 2010 (UTC)

This ASH function might help with understanding:
string color (string input) {
if(index_of(input, "#" && length(input)>6) == 0) return substring(input, 0, 6);
if(length(input) == 6) return input;
while(index_of(input, "0") == 0) input = substring(input, 1);
if(length(input)>7) return "000000";
if(length(input)==7) return substring(input, 1);
while(length<6) input = "0" + input;
return input;
}
(is that too much string manipulation?)
--[[User:Heeheehee|Heeheehee]] 02:44, 14 March 2010 (UTC)

Re: the former RFI (echoing print statements to the adventuring status line)

I was referring to the version of such that is also shown on the login / logout screen, which I feel is relevant as there isn't a good way to give feedback on a logout script otherwise (currently, I have a logout script that uses a user_confirm() for the clunky purpose of getting around this). If there's a way I'm unaware of to deal with this, that would be fine; but otherwise I'd like to know if print() could once again place text there, or if I'm mis-remembering. --[[User:StDoodle|StDoodle (#1059825)]] 00:53, 30 April 2010 (UTC)
:Ah. I can see why you'd want that. Post it in a feature request on the mafia forums. That's the proper place for it. Then if your desire is granted we can update this page. :D --[[User:Bale|Bale]] 02:07, 30 April 2010 (UTC)

Data Structures

2010-07-15T14:22:15Z

PhilmASTErpLus: /* Clear */ clear() is a function, not a command.

{{TOCright}}

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

== Maps ==
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 new_pricelist */

my_pricelist = new_pricelist;
</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 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>}}

=== Sort ===

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

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 (even multidimensional maps, but note that you can only sort along a single dimension at a time). 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.

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).

== Records ==

(copy-pasted from Veracity's post introducing the record [http://kolmafia.us/showthread.php?t=280])

Starting with SVN revision 1311 of KoLmafia, ASH now supports a new kind of structured data: the record. Here is a little example of how you declare a record and variables of the new type you've created by doing so.

{{CodeSample|code=<syntaxhighlight>
record my_type {
int ifield;
string sfield;
record {
int first;
int second;
} rfield;
int [int, int] mfield;
};

my_type rvar;
my_type [int] mrvar;
</syntaxhighlight>}}

What I've done with the above is declare a new data type which I've named "my_type". Having declared the new type, I can use it (almost) anywhere that I can use a built-in type name. I declared a variable, "rvar", of that type, and I defined a map, "mrvar", which maps keys of type integer to values of type my_type.

The new type, "my_type" is a "composite" type. It contains four fields. "ifield" is an integer. "sfield" is a string. "rfield" is another composite field: an anonymous record containing two integers named "first" and "second". Finally, "mfield" is a map from [int, int] to int.

As you can see, a record can combine data of all the types ASH supports: primitive, aggregate, and composite.

Having defined the new data type and several variables using it, here are some examples of how to access the fields.

{{CodeSample|code=<syntaxhighlight>
rvar.ifield = 10;
rvar.sfield = "secret";
rvar.rfield.first = 1000;
rvar.sfield.second = 2000;
rvar.mfield[ 2, 3 ] = 12;

mrvar[ 1 ] = rvar;

foreach key in mrvar
foreach key1, key2 in mrvar[key].mfield
print( "val = " + mrvar[key].mfield[key1,key2] );
</syntaxhighlight>}}

As you can see, if you have a variable that is a record, you access the fields of the record by following the variable name with ".<field name>". The resulting value will be of whatever type you declared in the definition of the record. If the value is a map, you can give a list of keys within [], just like any other map. If the value is another record, you can access the fields of the nested record by using another ".<field name>".

If you are familiar with Pascal "records" or C/C++ "structs", this should all be comfortably familiar.

Finally, if you create a map whose values is a record, the file_to_map and map_to_file built-in ASH functions will Do The Right Thing; they will efficiently and reliably save and restore your data.
{{RFI|I, for one, don't have a good handle on multi-dimensional maps. Any effort to clarify how they are defined & accessed would be greatly appreciated.|Don't worry about formatting for now; I'll get to that once the info is there, unless you're feeling super-ambitious.}}
{{Format}}

[[Category:ASH Scripting]]

Data Types

2010-07-15T14:16:33Z

PhilmASTErpLus: /* buffer */ Slightly more information on efficiency -- should probably expand later.

{{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'''.

===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.

===float===

The float data type is a single-precision 32-bit IEEE 754 floating point. Its range of values is beyond the scope of this discussion, but is specified in section 4.2.3 of the Java Language Specification. [http://java.sun.com/docs/books/jls/third_edition/html/typesValues.html#4.2.3]

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>}}

===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>}}

===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>}}
===class===

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

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

===effect===

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

The full range, besides $effect[ none ], is too much to list and keep up with here: please see the [http://kol.coldfront.net/thekolwiki/index.php/Effects Coldfront Wiki] page for more information.

===element===

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

* cold
* hot
* sleaze
* spooky
* stench
* slime

===familiar===

Any familiar available in KoL is valid for this datatype.

The full range, besides $familiar[ none ], is too much to list and keep up with here: please see the [http://kol.coldfront.net/thekolwiki/index.php/Familiars Coldfront Wiki] page for more information.

===item===

Any item in all of KoL is valid for this datatype. Note that unlike most special datatypes, item references can make use of the item ID number.
{{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 [http://kol.coldfront.net/thekolwiki/index.php/Items Coldfront Wiki] page for more information.

===location===

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

The full range, besides $location[ none ], is too much to list and keep up with here: please see the [http://kol.coldfront.net/thekolwiki/index.php/Locations Coldfront Wiki] page for more information.

===monster===

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

The full range, besides $monster[ none ], is too much to list and keep up with here: please see the [http://kol.coldfront.net/thekolwiki/index.php/Monster_Compendium Coldfront Wiki] page for more information.

===skill===

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

The full range, besides $skill[ none ], is too much to list and keep up with here: please see the [http://kol.coldfront.net/thekolwiki/index.php/Skills Coldfront Wiki] page for more information.

===slot===

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

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

===stat===

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

* muscle
* mysticality
* moxie
* submuscle
* submysticality
* submoxie

==Aggregate==

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

==Record==

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

==Plural Typed Constants==

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

Plural typed constants allow you to easily do something with a list of specified objects, without having to replicate code or laboriously build up an array of the objects so that you can iterate over it. Here's a quick example:
{{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:ASH Scripting]]

KoLmafia Properties

2010-07-14T08:18:14Z

PhilmASTErpLus: /* Per-Account Variables */ Added info about lastEmptiedStorage

{{TOCright}}
Inside your KoLmafia "settings" directory, you should find several files. KoLmafia properties are stored in the files that end with "_prefs.txt". One of these files will start with "GLOBAL"; the settings inside are shared by all characters using the program (and some of these properties are needed by KoLmafia even when no character is logged in). The other files ending with "_prefs.txt" will start with the name of a character, one for each who has been logged in to date. (Note: the names will all be converted to lowercase.)

==Choice Adventures==
A large number of the preferences saved by KoLmafia are used to determine the default behavior when a choice adventure is automated (either through auto-adventuring or use of the "auto" button in the relay browser). The number of choice adventures in KoL is too large and too often updated to list each individual preference here. Please consult the main wiki's [http://kol.coldfront.net/thekolwiki/index.php/Choice_Adventures_by_Number Choice Adventures by Number] page for a comprehensive list. Note that each preference follows the same numbering scheme as KoL itself. For example, the adventure "Minnesota Incorporeals" is number 77 in KoL, and its KoLmafia preference is "choiceAdventure77".

Each choiceAdventure is set to a number, which corresponds to which choice you want to make from the available options in KoL (or in the GUI, in the case that mafia provides more options than KoL). According to Holatuwol ([http://kolmafia.us/index.php/topic,1155.0.html here]), the settings map to "X=pick the Xth Option" and "X+1=pick an item you don't have" (i.e., complete the outfit). Many preferences also have a "Show in [Mini] Browser" option, which corresponds to a setting of 0.

This is a list of all the Property variables included in KoLmafia. It was automatically generated from r7582. Note that, however, the latest (and most up-to-date) data is located in Mafia's internally-stored datafile defaults.txt (available for viewing at [https://kolmafia.svn.sourceforge.net/svnroot/kolmafia/src/data/defaults.txt the SourceForge page]).

==Global Variables==
{| class="wikitable" border="1"
|-
! Variable Name
! Default Value
! Notes
|-
| addChatCommandLine
| false
|
|-
| addCreationQueue
| true
|
|-
| addStatusBarToFrames
| false
|
|-
| allowCloseableDesktopTabs
| false
|
|-
| allowNegativeTally
| true
|
|-
| allowNonMoodBurning
| true
|
|-
| alwaysGetBreakfast
| false
|
|-
| autoLogin
|
|
|-
| allowSocketTimeout
| true
|
|-
| autoHighlightOnFocus
| true
|
|-
| autoPlantHardcore
| false
|
|-
| autoPlantSoftcore
| false
|
|-
| autoSatisfyWithCloset
| true
|
|-
| autoSatisfyWithMall
| true
|
|-
| autoSatisfyWithNPCs
| true
|
|-
| autoSatisfyWithStash
| false
|
|-
| breakfastHardcore
| Advanced Saucecrafting,Pastamastery,Advanced Cocktailcrafting
|
|-
| breakfastSoftcore
| Advanced Saucecrafting,Pastamastery,Advanced Cocktailcrafting
|
|-
| browserBookmarks
|
|
|-
| cacheMallSearches
| false
|
|-
| charsheetDropdown
| 1
|
|-
| chatFontSize
|
|
|-
| chatLinksUseRelay
| false
|
|-
| chatStyle
| 0
|
|-
| cloverProtectActive
| true
|
|-
| combatHotkey0
|
|
|-
| combatHotkey1
|
|
|-
| combatHotkey2
|
|
|-
| combatHotkey3
|
|
|-
| combatHotkey4
|
|
|-
| combatHotkey5
|
|
|-
| combatHotkey6
|
|
|-
| combatHotkey7
|
|
|-
| combatHotkey8
|
|
|-
| combatHotkey9
|
|
|-
| commandLineNamespace
|
|
|-
| connectViaAddress
| false
|
|-
| cookies.inventory
|
|
|-
| copyAsHTML
| false
|
|-
| createHackerSummons
| true
|
|-
| customizedTabs
| false
|
|-
| debugPathnames
| true
|
|-
| defaultBorderColor
| blue
|
|-
| defaultDropdown1
| 0
|
|-
| defaultDropdown2
| 1
|
|-
| defaultDropdownSplit
| 0
|
|-
| defaultLimit
| 5
|
|-
| defaultLoginServer
| 1
|
|-
| displayName
|
|
|-
| eSoluScriptType
| 0
|
|-
| getBreakfast
|
|
|-
| grabCloversHardcore
| false
|
|-
| grabCloversSoftcore
| true
|
|-
| greenScreenProtection
| false
|
|-
| grimoireSkillsHardcore
| none
|
|-
| grimoireSkillsSoftcore
| Summon Hilarious Objects
|
|-
| guiUsesOneWindow
| false
|
|-
| hideServerDebugText
| false
|
|-
| highlightList
|
|
|-
| http.proxyHost
|
|
|-
| http.proxyPassword
|
|
|-
| http.proxyPort
|
|
|-
| http.proxyUser
|
|
|-
| initialDesktop
| AdventureFrame,CommandDisplayFrame,MallSearchFrame,GearChangeFrame,SkillBuffFrame
|
|-
| initialFrames
| RecentEventsFrame
|
|-
| innerChatColor
| #ffa98c
|
|-
| innerTabColor
| #8ca9ff
|
|-
| itemManagerIndex
| 0
|
|-
| lastBuffRequestType
| 0
|
|-
| lastRelayUpdate
|
|
|-
| lastRssUpdate
| 0
|
|-
| lastRssVersion
|
|
|-
| lastUserAgent
|
|
|-
| lastUsername
|
|
|-
| libramSkillsHardcore
| none
|
|-
| libramSkillsSoftcore
| none
|
|-
| logAcquiredItems
| true
|
|-
| logBattleAction
| true
|
|-
| logBrowserInteractions
| false
|
|-
| logChatMessages
| true
|
|-
| logDecoratedResponses
| false
|
|-
| logFamiliarActions
| false
|
|-
| logGainMessages
| true
|
|-
| logReadableHTML
| false
|
|-
| loginRecoveryHardcore
| false
|
|-
| loginRecoverySoftcore
| true
|
|-
| loginScript
|
|
|-
| loginServerName
|
|
|-
| loginWindowLogo
| lantern.jpg
|
|-
| logMonsterHealth
| false
|
|-
| logoutScript
|
|
|-
| logReverseOrder
| false
|
|-
| logStatGains
| true
|
|-
| logStatusEffects
| false
|
|-
| logStatusOnLogin
| false
|
|-
| mementoListActive
| false
|
|-
| mergeHobopolisChat
| false
|
|-
| outerChatColor
| #b4460f
|
|-
| outerTabColor
| #0f46b4
|
|-
| pathedSummonsHardcore
| true
|
|-
| pathedSummonsSoftcore
| false
|
|-
| preferredWebBrowser
|
|
|-
| previousNotifyList
| <>
|
|-
| previousUpdateVersion
|
|
|-
| protectAgainstOverdrink
| true
|
|-
| proxySet
| false
|
|-
| readManualHardcore
| true
|
|-
| readManualSoftcore
| true
|
|-
| relayAddsCustomCombat
| true
|
|-
| relayAddsGraphicalCLI
| false
|
|-
| relayAddsKoLSimulator
| false
|
|-
| relayAddsQuickScripts
| false
|
|-
| relayAddsRestoreLinks
| true
|
|-
| relayAddsRoundNumber
| false
|
|-
| relayAddsUpArrowLinks
| true
|
|-
| relayAddsUseLinks
| true
|
|-
| relayAddsWikiLinks
| false
|
|-
| relayAllowsOverrides
| false
|
|-
| relayBrowserOnly
| false
|
|-
| relayBrowserOnly
| false
|
|-
| relayFormatsChatText
| true
|
|-
| relayHidesJunkMallItems
| true
|
|-
| relayMaintainsEffects
| false
|
|-
| relayMaintainsHealth
| true
|
|-
| relayMaintainsMana
| false
|
|-
| relayTextualizesEffects
| false
|
|-
| relayTrimsZapList
| true
|
|-
| relayUsesCachedImages
| false
|
|-
| relayUsesInlineLinks
| false
|
|-
| relayUsesIntegratedChat
| false
|
|-
| relayViewsCustomItems
| false
|
|-
| removeMalignantEffects
| true
|
|-
| saveSettingsOnSet
| true
|
|-
| saveState
|
|
|-
| saveStateActive
|
|
|-
| scriptButtonPosition
| 0
|
|-
| scriptList
| restore hp | restore mp
|
|-
| showAllRequests
| false
|
|-
| stealthLogin
| true
|
|-
| swingLookAndFeel
|
|
|-
| switchEquipmentForBuffs
| true
|
|-
| tomeSkillsHardcore
| Summon Snowcone
|
|-
| tomeSkillsSoftcore
| Summon Snowcone
|
|-
| toolbarPosition
| 1
|
|-
| useChatMonitor
| false
|
|-
| useChatToolbar
| true
|
|-
| useContactsFrame
| true
|
|-
| useCrimboToysHardcore
| false
|
|-
| useCrimboToysSoftcore
| true
|
|-
| useDecoratedTabs
|
|
|-
| useLastUserAgent
| false
|
|-
| useSeparateChannels
| true
|
|-
| useShinyTabbedChat
| true
|
|-
| useSystemTrayIcon
| false
|
|-
| useTabbedChatFrame
| true
|
|-
| useToolbars
| true
|
|-
| useZoneComboBox
| false
|
|-
| userAgent
|
|
|-
| visitLoungeHardcore
| true
|
|-
| visitLoungeSoftcore
| true
|
|-
| visitRumpusHardcore
| true
|
|-
| visitRumpusSoftcore
| true
|
|}

==Per-Account Variables==
Choice adventure preferences have been omitted (see above).
{| class="wikitable" border="1"
|-
! Variable Name
! Default Value
! Notes
|-
| autoAbortThreshold
| -0.05
| Abort adventuring at this percentage of HP. (-0.05 means if HP restoration failed)
|-
| autoAntidote
| 0
| Use antidotes in combat
|-
| autoBuyPriceLimit
| 20000
| Don't auto purchase anything that costs more than this
|-
| autoEntangle
| false
| Use Entangling Noodles at the beginning of combat
|-
| autoManaRestore
| true
| Restore MP in combat
|-
| autoOlfact
|
| Automatically cast Olfaction
|-
| autoPotionID
| false
| Attempt to ID ! potions in combat
|-
| autoPutty
|
| Automatically use Spooky Putty
|-
| autoRepairBoxServants
| true
| Create in-a-boxen before cooking or mixing
|-
| autoSphereID
| false
| Attempt to ID spheres from the Hidden City
|-
| autoSteal
| true
| Attempt to pickpocket in combat
|-
| autostartGalaktikQuest
| true
| Get Doc Galaktik's Quest at the start of ascension
|-
| availableDimes
| 0
|
|-
| availableLucre
| 0
|
|-
| availableQuarters
| 0
|
|-
| availableSandDollars
| 0
|
|-
| barrelGoal
| 1
|
|-
| barrelLayout
| ?????????
|
|-
| basementMallPrices
| 1
|
|-
| battleAction
| attack with weapon
|
|-
| betweenBattleScript
|
|
|-
| birdformCold
| 0
|
|-
| birdformHot
| 0
|
|-
| birdformRoc
| 0
|
|-
| birdformSleaze
| 0
|
|-
| birdformSpooky
| 0
|
|-
| birdformStench
| 0
|
|-
| blackPuddingsDefeated
| 0
|
|-
| breakfastCompleted
| false
|
|-
| buffBotCasting
|
|
|-
| buffBotMessageDisposal
| 0
|
|-
| buffBotPhilanthropyType
| 1
|
|-
| burrowgrubHiveUsed
| false
|
|-
| burrowgrubSummonsRemaining
| 0
|
|-
| buyScript
|
|
|-
| cameraMonster
|
|
|-
| cellarLayout
| 0
|
|-
| chatbotScript
|
|
|-
| chatbotScriptExecuted
| false
|
|-
| chosenTrip
|
|
|-
| clanAttacksEnabled
| false
|
|-
| cocktailSummons
| 0
|
|-
| concertVisited
| false
|
|-
| currentBountyItem
| 0
|
|-
| currentFullness
| 0
|
|-
| currentHippyStore
| none
|
|-
| currentJunkyardTool
|
|
|-
| currentJunkyardLocation
|
|
|-
| currentMojoFilters
| 0
|
|-
| currentMood
| default
|
|-
| currentNunneryMeat
| 0
|
|-
| currentPvpVictories
|
|
|-
| currentSpleenUse
| 0
|
|-
| currentWheelPosition
| muscle
|
|-
| customCombatScript
| default
|
|-
| dailyDungeonDone
| false
|
|-
| defaultAutoAttack
| 0
|
|-
| defaultFlowerLossMessage
|
|
|-
| defaultFlowerWinMessage
|
|
|-
| demonName1
|
|
|-
| demonName2
|
|
|-
| demonName3
|
|
|-
| demonName4
|
|
|-
| demonName5
|
|
|-
| demonName6
| Tatter
|
|-
| demonName7
| Ak'gyxoth
|
|-
| demonSummoned
| false
|
|-
| expressCardUsed
| false
|
|-
| extraRolloverAdventures
| 0
|
|-
| flyeredML
| 0
|
|-
| fratboysDefeated
| 0
|
|-
| friarsBlessingReceived
| false
|
|-
| gongPath
| 0
|
|-
| gourdItemCount
| 5
|
|-
| grimoire1Summons
| 0
|
|-
| grimoire2Summons
| 0
|
|-
| guardTurtlesFreed
| 0
| Number of times that [http://kol.coldfront.net/thekolwiki/index.php/Cold-Blooded_Warm_Fuzzies guard turtles have been freed] this ascension.
|-
| guyMadeOfBeesCount
| 0
|
|-
| guyMadeOfBeesDefeated
| false
|
|-
| hiddenCityLayout
| 0000000000000000000000000
|
|-
| hiddenCitySquare
| 0
|
|-
| hippiesDefeated
| 0
|
|-
| hpAutoRecovery
| -0.05
|
|-
| hpAutoRecoveryItems
| cannelloni cocoon;scroll of drastic healing;tongue of the walrus;lasagna bandages;doc galaktik's ailment ointment
|
|-
| hpAutoRecoveryTarget
| 1.0
|
|-
| invalidBuffMessage
| You sent an amount which does not correspond to a valid buff amount.
|
|-
| kingLiberated
| false
|
|-
| knownAscensions
| -1
|
|-
| lastAdventure
|
|
|-
| lastBarrelSmashed
| 0
|
|-
| lastBangPotion819
|
|
|-
| lastBangPotion820
|
|
|-
| lastBangPotion821
|
|
|-
| lastBangPotion822
|
|
|-
| lastBangPotion823
|
|
|-
| lastBangPotion824
|
|
|-
| lastBangPotion825
|
|
|-
| lastBangPotion826
|
|
|-
| lastBangPotion827
|
|
|-
| lastBangPotionReset
| -1
|
|-
| lastBarrelSmashed
| 0
|
|-
| lastBattlefieldReset
| -1
|
|-
| lastBreakfast
| -1
|
|-
| lastCellarReset
| -1
|
|-
| lastCouncilVisit
| 0
|
|-
| lastCounterDay
| -1
|
|-
| lastDustyBottle2271
|
|
|-
| lastDustyBottle2272
|
|
|-
| lastDustyBottle2273
|
|
|-
| lastDustyBottle2274
|
|
|-
| lastDustyBottle2275
|
|
|-
| lastDustyBottle2276
|
|
|-
| lastDustyBottleReset
| -1
|
|-
| lastDwarfDiceRolls
|
|
|-
| lastDwarfDigitRunes
| -------
|
|-
| lastDwarfEquipmentRunes
|
|
|-
| lastDwarfFactoryItem118
|
|
|-
| lastDwarfFactoryItem119
|
|
|-
| lastDwarfFactoryItem120
|
|
|-
| lastDwarfFactoryItem360
|
|
|-
| lastDwarfFactoryItem361
|
|
|-
| lastDwarfFactoryItem362
|
|
|-
| lastDwarfFactoryItem363
|
|
|-
| lastDwarfFactoryItem364
|
|
|-
| lastDwarfFactoryItem365
|
|
|-
| lastDwarfFactoryItem910
|
|
|-
| lastDwarfFactoryItem3199
|
|
|-
| lastDwarfOfficeItem3208
|
|
|-
| lastDwarfOfficeItem3209
|
|
|-
| lastDwarfOfficeItem3210
|
|
|-
| lastDwarfOfficeItem3211
|
|
|-
| lastDwarfOfficeItem3212
|
|
|-
| lastDwarfOfficeItem3213
|
|
|-
| lastDwarfOfficeItem3214
|
|
|-
| lastDwarfOreRunes
|
|
|-
| lastDwarfFactoryReset
| -1
|
|-
| lastDwarfHopper1
|
|
|-
| lastDwarfHopper2
|
|
|-
| lastDwarfHopper3
|
|
|-
| lastDwarfHopper4
|
|
|-
| lastEVHelmetValue
| 0
|
|-
| lastEVHelmetReset
| -1
|
|-
| lastEmptiedStorage
| -1
| Stores whether the storage was empty the last time it was checked.
|-
| lastFilthClearance
| -1
|
|-
| lastGalleryUnlock
| -1
|
|-
| lastGuildStoreOpen
| -1
|
|-
| lastGuyMadeOfBeesReset
| -1
|
|-
| lastHiddenCityAscension
| 0
|
|-
| lastFratboyCall
| -1
|
|-
| lastHippyCall
| -1
|
|-
| lastKingLiberation
| -1
|
|-
| lastLouvreMap
| 0
|
|-
| lastMessageId
|
|
|-
| lastMiningReset
| -1
|
|-
| lastPaperStripReset
| -1
|
|-
| lastPaperStrip3144
|
|
|-
| lastPaperStrip4138
|
|
|-
| lastPaperStrip4139
|
|
|-
| lastPaperStrip4140
|
|
|-
| lastPaperStrip4141
|
|
|-
| lastPaperStrip4142
|
|
|-
| lastPaperStrip4143
|
|
|-
| lastPaperStrip4144
|
|
|-
| lastPastamancerGhostReset
| -1
|
|-
| lastPirateEphemera
|
|
|-
| lastPirateEphemeraReset
| -1
|
|-
| lastPirateInsult1
| false
|
|-
| lastPirateInsult2
| false
|
|-
| lastPirateInsult3
| false
|
|-
| lastPirateInsult4
| false
|
|-
| lastPirateInsult5
| false
|
|-
| lastPirateInsult6
| false
|
|-
| lastPirateInsult7
| false
|
|-
| lastPirateInsult8
| false
|
|-
| lastPirateInsultReset
| -1
|
|-
| lastPyramidReset
| -1
|
|-
| lastQuartetAscension
| -1
|
|-
| lastQuartetRequest
| 0
|
|-
| lastSecondFloorUnlock
| -1
|
|-
| lastSemirareReset
| -1
|
|-
| lastStoneSphere2174
|
|
|-
| lastStoneSphere2175
|
|
|-
| lastStoneSphere2176
|
|
|-
| lastStoneSphere2177
|
|
|-
| lastStoneSphereReset
| -1
|
|-
| lastTavernAscension
| 0
|
|-
| lastTavernSquare
| 0
|
|-
| lastTelescopeReset
| -1
|
|-
| lastTowerClimb
| -1
|
|-
| lastVioletFogMap
| 0
|
|-
| lastZapperWand
| 0
|
|-
| libramSummons
| 0
|
|-
| libraryCardUsed
| false
|
|-
| louvreDesiredGoal
| 7
|
|-
| louvreGoal
| 0
|
|-
| louvreLayout
|
|
|-
| louvreOverride
|
|
|-
| luckySewerAdventure
| stolen accordion
|
|-
| manaBurnSummonThreshold
| 10
|
|-
| manaBurningThreshold
| -0.05
|
|-
| mayflyExperience
| 0
| Uses of mayfly bait necklace. Reset each ascension.
|-
| mineLayout1
|
|
|-
| mineLayout2
|
|
|-
| mineLayout3
|
|
|-
| moleTunnelLevel
| 0
|
|-
| mpAutoRecovery
| 0.0
|
|-
| mpAutoRecoveryItems
| phonics down;knob goblin superseltzer;mountain stream soda;magical mystery juice;knob goblin seltzer;cherry cloaca cola;soda water
|
|-
| mpAutoRecoveryTarget
| 0.3
|
|-
| munchiesPillsUsed
| 0
|
|-
| noodleSummons
| 0
|
|-
| nunsVisits
| 0
|
|-
| oceanAction
| savecontinue
|
|-
| oceanDestination
| manual
|
|-
| olfactedMonster
| unknown
|
|-
| oscusSodaUsed
| false
|
|-
| outrageousSombreroUsed
| false
|
|-
| pastamancerGhostExperience
| 0
|
|-
| pastamancerGhostName
|
|
|-
| pastamancerGhostSummons
| 0
|
|-
| pastamancerGhostType
|
|
|-
| plantingDate
|
|
|-
| plantingDay
| -1
|
|-
| plantingLength
|
|
|-
| plantingScript
|
|
|-
| postAscensionScript
|
|
|-
| preAscensionScript
|
|
|-
| preBlackbirdFamiliar
|
|
|-
| prismaticSummons
| 0
|
|-
| pyramidPosition
| 0
|
|-
| pyramidBombUsed
| false
|
|-
| rageGlandVented
| false
|
|-
| reagentSummons
| 0
|
|-
| recentLocations
| 5
|
|-
| recoveryScript
|
|
|-
| relayCounters
|
|
|-
| requireBoxServants
| false
|
|-
| requireSewerTestItems
| false
|
|-
| retrieveContacts
| true
|
|-
| seaodesFound
| 0
|
|-
| semirareCounter
| 0
|
|-
| semirareLocation
|
|
|-
| serverAddsCustomCombat
| false
|
|-
| setAutoAttack
| true
|
|-
| showGainsPerUnit
| false
|
|-
| sideDefeated
| neither
|
|-
| sidequestArenaCompleted
| none
|
|-
| sidequestFarmCompleted
| none
|
|-
| sidequestJunkyardCompleted
| none
|
|-
| sidequestLighthouseCompleted
| none
|
|-
| sidequestNunsCompleted
| none
|
|-
| sidequestOrchardCompleted
| none
|
|-
| skillLevel46
| 2
|
|-
| skillLevel47
| 1
|
|-
| skillLevel48
| 2
|
|-
| slimelingFullness
| 0
|
|-
| sortByRoom
| true
|
|-
| spadingData
|
|
|-
| spiceMelangeUsed
| false
|
|-
| spookyPuttyCopiesMade
| 0
|
|-
| spookyPuttyMonster
|
|
|-
| stationaryButton1
|
|
|-
| stationaryButton2
|
|
|-
| stationaryButton3
|
|
|-
| stationaryButton4
|
|
|-
| stationaryButton5
|
|
|-
| styxPixieVisited
| false
|
|-
| tavernLayout
| 0000000000000000000000000
|
|-
| telescope1
|
|
|-
| telescope2
|
|
|-
| telescope3
|
|
|-
| telescope4
|
|
|-
| telescope5
|
|
|-
| telescope6
|
|
|-
| telescope7
|
|
|-
| telescopeLookedHigh
| false
|
|-
| telescopeUpgrades
| 0
|
|-
| tempuraSummons
| 0
|
|-
| thanksMessage
| Thank you for the donation!
|
|-
| timesRested
| 99
|
|-
| tomeSummons
| 0
|
|-
| trapperOre
| chrome ore
|
|-
| usable1HWeapons
| 3
|
|-
| usable1xAccs
| 1
|
|-
| usable2HWeapons
| 1
|
|-
| usable3HWeapons
| 1
|
|-
| usableAccessories
| 3
|
|-
| usableHats
| 2
|
|-
| usableOffhands
| 1
|
|-
| usableOther
| 1
|
|-
| usablePants
| 1
|
|-
| usableShirts
| 1
|
|-
| violetFogGoal
| 0
|
|-
| violetFogLayout
|
|
|-
| warProgress
| unstarted
|
|-
| welcomeBackAdv
| 0
|
|-
| _absintheDrops
| 0
|
|-
| _aguaDrops
| 0
|
|-
| _astralDrops
| 0
|
|-
| _banderRunaways
| 0
|
|-
| _cameraUsed
| false
|
|-
| _gongDrops
| 0
|
|-
| _hotTubSoaks
| 0
|
|-
| _mayflySummons
| 0
| Mayfly summonings today
|-
| _navelRunaways
| 0
|
|-
| _sealsSummoned
| 0
|
|-
| _skateBuff1
| false
| lutz
|-
| _skateBuff2
| false
| comet
|-
| _skateBuff3
| false
| band shell
|-
| _skateBuff4
| false
| skate eels
|-
| _skateBuff5
| false
| merry-go-round
|-
| _userMods
|
|
|-
| unknownRecipe3542
| true
|
|-
| unknownRecipe3543
| true
|
|-
| unknownRecipe3544
| true
|
|-
| unknownRecipe3545
| true
|
|-
| unknownRecipe3546
| true
|
|-
| unknownRecipe3547
| true
|
|-
| unknownRecipe3548
| true
|
|-
| unknownRecipe3749
| true
|
|-
| unknownRecipe3751
| true
|
|-
| unknownRecipe4172
| true
|
|-
| unknownRecipe4173
| true
|
|-
| unknownRecipe4174
| true
|
|}

==User-defined variables==
In addition to setting the variables that KoLmafia predefines, you can also create any others to cover any information you wish. As you do so, keep in mind that while you can clear a variable’s value to the null string, there is currently no way to delete a key (aside from editing the .txt file in the text processor of your choice and deleting the line that contains the key).
{{SeeAlso|get_property|set_property}}

[[Category:ASH Scripting]]