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

I know nothing about Macs; please edit in useful information here.

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

For example:

int count = 6;

would declare the variable "count" again, with an initial value of 6.

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

Argh, me tired, finish later.