ASH For Beginners

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), BBEdit is a much more powerful tool. It may not be designed for ASH scripting specifically, but it was written for a similar purpose. It can has a paid mode with more features, but those features are optional. BBEdit users can install the BBEdit ASH Language Module to provide syntax colorization.

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

Several dedicated code editors provide useful features such as syntax highlighting and code suggestions:

• Notepad++: Lightweight and easy-to-use editor. There is a code style configuration for ASH.

• Visual Studio Code: More complex than Notepad++, but fast enough for most users. Also great for editing HTML, CSS, and JavaScript. Install the KoLmafia ASH++ extension to enable syntax highlighting and code suggestions.

  Not to be confused with Visual Studio, which is a much bigger program.

• Notepad: Can be used for quick-and-dirty code editing, but lacks many useful code editing features.

Do not use Microsoft Word or Wordpad for editing ASH files. These programs are suited for writing formatted documents, and can corrupt your code if you are not careful.

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 string myVar="abb" and STRing MYvar="abb" 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 Type that they will hold, followed by the variable name.

For example:

int count;

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.

On the other hand:

int count = 6;

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 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 function'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 error occurs, including a call to abort().)

For example, this simple function will double an integer:

int double_it(int value) {
   return 2 * value;
}

Furthermore, there are two distinct ways to call functions, user-defined or built-in:
Conventional,

function(param1[,param2,param3,...]);

and "Java style":

param1.function([param2,param3,...]);

The only difference between the two forms is aesthetics, as they are functionally equivalent.

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,

"polka pop".to_item().to_int()

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

to_int(to_item("polka pop"))

Note that scope (discussed above, under 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".

Running a Script

Once your script is saved, you can run it. Scripts saved in the scripts directory will appear in Mafia under the scripts menu. Simply clicking on one will run it. You may also run your script from the command line by typing "exec" followed by the script name For instance: exec myscript.

The script looks for the function 'main()' in order to know where to start.

Generally the function will look like this:

void main() {
   // the rest of your code
}

The main function can contain variables, other code and calls to other functions within the script.

You may also have an input into your main function. By requiring an input, this will cause KoLmafia to show a textbox to the user in order to get input into the script. This textbox can be filled in and submitted, or cancelled.