import

From KoLMafia
Jump to: navigation, search

import <filename>
import <filename>;
import "filename"
import "filename";

All the invocations above will work equally well. It works with or without a semi-colon and you can use either angle brackets or quotes.

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 main() function is imported into another script with another main() function, only the primary script's main() is executed, and all main() 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.

Executing main()

While the main() function of an imported script is not run on import, it can be implicitly called by the importing script. To do so, the script calls it as a function with the name main@filename().

No spaces are allowed around the @ as the whole thing is a single token.

There are some rules for how filename is interpreted.

  • Normally, this is the file name of the imported file whose main() is to be executed.
  • If the imported script uses the "script" directive, then 'filename' is overriden by that name.
  • Any .ash suffix is dropped.
  • Any non-alphanumeric characters are replaced with underscores.

Example

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

# ...