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), 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 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 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 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. 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 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. Argh, me tired, finish later.