AutoHotkey Tip of the Week: Guidelines for AutoHotkey Function Libraries

When Using Function Libraries, You Don’t Need to Embed Your Functions into Each of Your AutoHotkey Scripts—But Sometimes Keeping Them Close Works Out Better

In the past two blogs, “Dynamic Regular Expressions (RegEx) for Math Calculating Hotstrings” and “The Eval() Function for Hotkey Math Calculations and Text Manipulation“, I highlighted two different powerful, auxiliary (not built-in) AutoHotkey functions: RegExHotstrings() and Eval(). Normally, you might embed a user-defined function inside your script but these two functions take up quite a few lines of code. Plus, you might want to use those same functions in a number of different scripts. Adding them to each script can get a little cumbersome—even when using the #Include directive.

Fortunately, when loading a script, if AutoHotkey doesn’t find a directly called function inside the script, it automatically searches the special Function Libraries. But, before you race to put all of your functions in one of those Libraries, you should consider a number of factors.

Function Libraries

Function Libraries give you an alternative location (outside of the script) for storing your AutoHotkey functions. When first loading a script, if AutoHotkey doesn’t find a called function inside the code (or load it using the #Include directive), it checks possible Library locations. From the online documentation:

A script may call a function in an external file without having to use #Include. For this to work, a file of the same name as the function must exist in one of the following library directories:

%A_ScriptDir%\Lib\  ; Local library - requires [v1.0.90+].
%A_MyDocuments%\AutoHotkey\Lib\  ; User library.
[running-AutoHotkey.exe-folder]\Lib\  ; Standard library.

AutoHotkey checks the listed ..\Lib folders in the following order:

  1. Local Library
  2. User Library
  3. Standard Library

For my money, if I use a Function Library at all, I prefer to maintain functions in the Standard Library (often %ProgramFiles%\AutoHotkey\AutoHotkey.exe\Lib\). Since the Standard Library aways resides in the same folder as the main AutoHotkey program, its location stays fixed. Unlike the other two possible Library locations, the Standard Function Library’s location depends upon neither the script location nor the current user.

*          *          *

Cover 200 BorderFor more information about how functions work and where to use them, see Chapter Four “Functions as Building Blocks” and Chapter Twelve “Writing AutoHotkey Functions to Make Life Easier” of the book Beginning Tips for Writing AutoHotkey Scripts. Not only does this book contain more information about how to use AutoHotkey functions but it offers numerous other AutoHotkey scripting tips—including script structure and a framework for how AutoHotkey scripts work.

Check out the AutoHotkey Library Bundles for deep discounts on Jack’s books!

*          *          *

Library Function Requirements

A Function Library always lies within a folder by the name Lib. The filename of each function in a Library must match the function name called in the script. For example, if you plan to use the Eval() function, assign the filename Eval.ahk to the function file and place it in the target Library (..\Lib\Eval.ahk). After that, any AutoHotkey script can access that function by calling its name:

Array := Eval("45+56")

(When using the Standard Library for your library, you’ll likely need Administrator authority to save and move the files.) Create one file for each function—unless you combine functions into one file per the special naming convention described here:

If a match is still not found and the function’s name contains an underscore (e.g. MyPrefix_MyFunc), the program searches [the] libraries for a file named MyPrefix.ahk and loads it if it exists. This allows MyPrefix.ahk to contain both the function MyPrefix_MyFunc and other related functions whose names start with MyPrefix_.

Once you add a function to the Standard Library, you don’t need to either insert the function code into your script or use the #Include directive, as long as you call the function directly—not embed it in an AutoHotkey command or attempt to call it dynamically after the script loads. For example, call the function in an evaluated expression:

Array := Eval("34+45")
MsgBox % Array[1]

The first line of code set the first element in Array (Array[1]) to the sum of 34+45 (or 79). This use of the Eval() function automatically pulls the function from the Library into the script. Calling a function indirectly or after the initial load (dynamically) with an AutoHotkey command does not load the function. For example, forcing an expression inside an AutoHotkey command does not load the Library Function—although,  I haven’t done enough testing to swear that it never works.

This can get a little confusing so I recommend testing various options when deciding where to store your functions. As a rule, I found running the function on the initial load works well, as shown above, or evaluating it in an expression as follows:

If Array := Eval("34+45")
  MsgBox % Array[1]

The expression loads the function even if located inside Hotkey routines or action Hotstrings. If you get either a “missing function” error or incorrect results, then you may need to #Include the function in the script.

Function Library Pluses and Minuses

While Function Libraries offer some major advantages, you should target how you use them. In some situations, they offer salvation—while others may lead to confusion.

Function Library Advantages

  • By keeping a general function in a Library, you can use that function in any script without explicitly adding the code (or using the #Include directive) in the script. That means you can use the same function(s) for all of your scripts by merely calling each in an expression.
  • If you make any changes to the function, it updates for every script that uses it without needing to alter each script. Only make adjustments in one place—the function itself.
  • When compiling scripts, AutoHotkey auto-includes the Library functions in the stand-alone executable file.

You might find these advantages compelling but should consider the drawbacks before moving all of your functions to a Library.

Function Library Disadvantages

Although Function Libraries act as a valuable tool in many AutoHotkey scripting scenarios, you need to understand their limitations:

  • When loading, the script must evaluate the function only as a direct function call or in an expression to initiate the auto-include. For example, calling the function with the SetTimer command or via a GUI (Graphical User Interface) control will not work.
  • Scripts lose portability. If you want to share scripts or move them to another computer, unless compiling into an executable file, you must consciously either embed the function in the script (or #Include and provide it separately). At a minimum, you should inform users which functions they need and where they can find them.
  • If you make a change to the function, it affects every script calling it. While listed above as an advantage, this can cause problems if you make an adjustment to a Library function for one script which adversely affects another.
  • Take care when choosing function names. You can inadvertently create conflicts by writing functions for new scripts using the same name as a needed Library Function.
  • Do not include script-specific functions in a Library. They only cause confusion for both yourself (and other users) when later reviewing and/or altering scripts. If the specialized function does not reside in the script, then you may find yourself at a loss when searching for it.

These Function Library advantages and disadvantages lead us to two basic guidelines:

  1. Maintain script-specific functions either in the script or in an #Include file. We often write user-defined functions to prevent the repetition of the same code in a script. If a new function only applies to the current script, then you may find it counterproductive to save it in a Function Library. Keep them close at hand by either locating the script-specific functions in the same file or in a nearby #Include file.
  2. Store universal functions in a Function Library. Any time you write (or discover) a function—such as Eval()—that might inspire you to use it in multiple scripts, you should place that general-use function in a Library—readily available at all times. This can save you both script bloat and development time. However, once you decide to make the script available to the outside world, you should inform everyone where to find the external function code.

In the past, I’ve maintained my functions inside each script. This makes it easier for readers to access all the needed code. For the most part, I’ll continue in that same manner. However, for my personal use (and quick testing of code), I have added my more universal functions to my Standard Function Library.

Click the Follow button at the top of the sidebar on the right of this page for e-mail notification of new blogs. (If you’re reading this on a tablet or your phone, then you must scroll all the way to the end of the blog—pass any comments—to find the Follow button.)


This post was proofread by Grammarly
(Any other mistakes are all mine.)

(Full disclosure: If you sign up for a free Grammarly account, I get 20¢. I use the spelling/grammar checking service all the time, but, then again, I write a lot more than most people. I recommend Grammarly because it works and it’s free.)

Find my AutoHotkey books at ComputorEdge E-Books!

Buy Jack a Cappuccino!

If you found a blog particularly useful, show your appreciation by buying Jack a cup of coffee! Or, if you prefer something for yourself, check out his books.


One thought on “AutoHotkey Tip of the Week: Guidelines for AutoHotkey Function Libraries

  1. […] Note: Since I have placed the GetActiveBrowserURL() function in my function library, you won’t find the function (or an #Include directive) in the script below. See “Capture Web Page Addresses (URLs)” to obtain a copy of the function. Either place it at the end of the script, #Include it, or add it to your library. See “Guidelines for AutoHotkey Function Libraries.” […]


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s