Modules [v2.1-alpha.11+]

A module is basically a script within the script. Each module has its own:

• Global namespace for variables, functions and classes.
• Body, sometimes referred to as an auto-execute section.

Splitting the components of a script into modules can make the components easier to reuse and maintain.

By default, all lines of code and global variables (including functions and classes) are added to an implicitly-defined module named "__Main". The script can start a new module with #Module or load one from file with #Import.

An #Import directive can be used to make a module or some of its functions, classes and variables accessible within the current module.

All modules implicitly import from the built-in "AHK" module, which contains all built-in classes, variables and functions outside the KS module. A declaration or assignment within a module can reuse the name of a built-in class or function, in which case that class or function is not accessible except through the AHK module (e.g. #Import AHK, AHK.MsgBox()). Built-in (A_) variables do not require a declaration or explicit import to allow assignment, and a declaration or assignment cannot create a new variable with the same name. An explicitly imported alias can use such a name. In AutoHotkey v2.1, A_Args is the exception (it is a normal variable defined in __Main). In Keysharp, A_Args is a built-in variable which every module and function shares.

Named imports can introduce normal variables into AHK. These variables are available through implicit global lookup unless the current module declares or assigns the same name.

A module name is added to a module's global namespace only when imported, and conflicts can be resolved by giving the imported module an alias within the destination module.

#Include is able to include a file once per module.

#Warn can enable or disable warnings within the current module without affecting other modules. For details, see the #Warn remarks.

#HotIf affects only the current module. #HotIf and HotIf expressions are module-scoped, as they may contain references to module-level variables. For instance, the effect of #HotIf myToggle depends on what value myToggle has in the current module.

Module.__Ref [v2.1-alpha.33+]

Retrieves a VarRef for a module's global variable or explicitly imported name.

Reference := ModuleObject.__Ref(Name)

Name is the name of a member in the module, including a named or wildcard import. Imports may pass a name through multiple modules: every alias reaches the original variable and returns its reference. Bare and dynamic references to an explicitly imported variable share this reference and its native string memory. If the name cannot be resolved, the method returns unset without creating a variable.

A reference to a function, class or read-only built-in variable can be read, but assigning through it raises a read-only error.

Retrieving the reference does not read the variable's value. If that value is another VarRef, the returned reference still points to the variable holding it.

The reference operator uses this method: &ModuleObject.Member is equivalent to ModuleObject.__Ref("Member").

KS Module

The built-in KS module exports Keysharp-specific classes, functions and variables. A script must import a name to use it, and the names are not members of the AHK module.

#Import "Ks" { Image, A_DirSeparator }

Capture := Image.FromDesktop()
MsgBox A_DirSeparator

New methods or properties added to an existing built-in class, such as Array or Buffer, are available without importing KS.

The full set of exports is listed below.

Classes

Functions

Variables

The KS module's variables are listed under KS Module Variables.

Execution

The body of each module is executed eagerly at program startup, by the auto-execute thread. A module normally executes after the modules it imports. Declaration order resolves modules which are otherwise unrelated or form a cycle.

This eager, import-aware order is a Keysharp difference from AutoHotkey v2.1, which starts from the last-defined module and can execute another module lazily when one of its variables or constants is first referenced. For example:

#module A
MsgBox "A executing"  ; Shown first.
global ANSWER := 42

#module B
#import A {ANSWER}
MsgBox "B executing"  ; Shown second.
MsgBox ANSWER

Search Path [v2.1-alpha.20+]

The module search path is a list of directories which the #Import statement looks in to find module files. The directory of the file which contains the #Import directive is always searched first. The AhkImportPath environment variable can contain a semicolon-delimited list of additional directories to search. If it is not defined, the default list is as follows:

%A_ScriptDir%;%A_MyDocuments%\AutoHotkey;%A_AhkPath%\..

Built-in variables may be used in the value of AhkImportPath by enclosing them in percent signs. Any percent signs which are not part of a valid variable reference are interpreted literally. References to environment variables are not resolved by AutoHotkey, as they are typically resolved before the process starts. List items can be absolute paths or relative to the directory containing the script (A_ScriptDir). The list is resolved only once, so A_LineFile always refers to the main script.

Directories are searched in the order they are listed. Within each directory, files are considered in this order:

• ModuleName
• ModuleName\__Init.ahk
• ModuleName.ahk

For example, #Import M may load the file with exact name M, M\__Init.ahk or M.ahk. #Import "M" is the same except that the name M is not added to the current module.

Examples

#Import Other
MyVar := 1
      ShowVar()  ; Our MyVar is 1.
Other.ShowVar()  ; Other MyVar is still 2.
MsgBox "Within main, Other.MyVar = " (Other.MyVar ?? "inaccessible")  ; MyVar is accessible in v2.1-alpha.19+.
ShowVar() => MsgBox("Main MyVar = " MyVar)

#Module Other
MyVar := 2
ShowVar() => MsgBox("Other MyVar = " MyVar)

#Import "X" {Calculate as CalculateX}
#Import "Y" {*}

MyVar := 1
MsgBox Calculate()
MsgBox CalculateX()
MsgBox Check(3)
MsgBox "X = " (X ?? "not imported")
MsgBox "Y = " (Y ?? "not imported")

Calculate() => 1

#Module X
Calculate() => 2

#Module Y
Calculate() => 3
Check(n) => n = Calculate()

#import AHK

MsgBox "Hello, world!",, "T2"

; Add the Info icon by default.
MsgBox(Text?, Title?, Options:="") {
    return AHK.MsgBox(Text?, Title?, "Iconi " Options)
}

#Module Other
MsgBox "Other still has the original MsgBox.",, "T2"