While Preplanning Script Writing Can Be Useful, Don’t Take It Too Seriously—Sometimes It Only Makes Sense to Rewrite Everything

The AutoHotkey script writing process rarely runs in a straight line. Often I start with a vague concept of what I want to do then start fiddling with the tools. Unlike when building a toolshed or bookcase, I rarely begin with a complete plan or blueprint for an AutoHotkey script. In fact, the code may undergo numerous changes during the debugging and problem-solving phases.

For anyone who builds things, this approach may be disconcerting. Afterall, you can’t afford to build a house by trial-and-error. The cost of wasted materials would be prohibitive. Traditionally, we spend a great deal of time in the planning phase to make sure we avoid expensive mistakes. Even in computer programming, large projects come together much better after extensive planning. But with smaller projects such as AutoHotkey scripts the opposite may be true. I often start a script with only a vague idea of what I want to do. As I work on it, the possibilities expand and I often change course.

Fortunately, there are no lost materials when rewriting AutoHotkey scripts—only time. Yet, I’ve found that even though I may lose little programming time early in the process, the later rewrites and changes save even more—either in programming time or a better-running app.

The adage “If you don’t know where you’re going, you’ll probably going to end up someplace else” might prevent some people from starting an AutoHotkey script. The ambiguity of not knowing exactly where you’re going makes a task seem more daunting. Regardless, I urge you to take those first few steps. My experience in writing scripts tells me that probably I will end up in a better place. The wrong direction is better than no direction. If you head down an errant path, you’ll soon discover it and correct course.

Don’t be afraid of rethinking what you’re doing even if it means junking everything and restarting. This is the essence of creativity and brings your AutoHotkey apps to the next level. Remember, AutoHotkey scripts usually act as enhancements to the main program. Short and easy to change AutoHotkey apps make Windows life easier, rather than acting as the center of your computing.

*          *          *

This blog assumes at least a minimal understanding of AutoHotkey or script writing in general. If you’re new to AutoHotkey, see this “Introduction to AutoHotkey: A Review and Guide for Beginners.”

*          *          *

Changing the AutoHotkey Quick Reference Script

I’m in the process of a major rethink of the AutoHotkeyQuickRef.ahk script (first discussed in an earlier part of this series). As I played with the hidden AutoHotkey.com index, I found a number of ways to take better advantage of its capabilities. In some cases, it looks like it might be an improvement to completely avoid the index. But first, I offer some of my observations.

1. Sometimes the index brings up strange results.
2. While AutoHotkey commands generally come up on a different Web page, most built-in variables are documented on one “Variables and Expressions” page.
3. I can speed up the app considerably by minimizing the number of times the script accesses the Web.
4. By switching from a MsgBox to a GUI window, I can incorporate more cool tools in the reference script (e.g. add more interactive features to the GUI window).

Each of these thoughts gives me a glimpse into how I might change things in the future.

Strange Results from the AutoHotkey.com Hidden Index

While randomly testing different searches with various keywords, I found that the word “space” located the If Var Is Type page as shown at right. It seemed to me that the A_Space variable would be a more appropriate result for “space”, but since I have no direct control over the AutoHotkey.com index, I needed to make some changes.

The A_Space variable name plugged into the hidden index search does return the “Variables and Expressions” page, but “Space” acts as the embedded HTML anchor ID. In order to make the script work more to my liking, I needed to deal with built-in variables first.

Fortunately, I could use the AHKRef.ini file to identify these variables without first downloading the Web page. In fact, if I saved a copy of the source code for the “Variables and Expressions” page on my computer, I could eliminate the need to access the Web at all—at least for the first part of the AutoHotkeyQuickRef.ahk script.

The built-in AutoHotkey variables are important enough to add this special handling to the script. I can see times when someone merely wants the specifics of how a variable works without needing to load the entire page. By using the AHKRef.ini lookup file with a saved copy of the “Variables and Expressions” page source code, a more accurate index can be created while greatly increasing the speed of the app.

The steps for speeding up the script and preventing a few anomalies:

1. Execute the built-in variable search function before any other hidden index search.
2. Use the INI file to determine if the search term qualifies as a variable.
3. Use a saved version of the “Variables and Expressions” page source code to speed up the process and eliminate the need for Internet access.
4. Display the variable information in a new MsgBox with three options for continuing: 1) Load “Variables and Expressions” page in the default Web browser; 2) Continue with another index search for commands and functions; 3) Exit without further action.

I rewrote the script and moved the location of this variable search to the beginning of the AutoHotkey file:

StringReplace, VarTerm, Clipboard, a_
IfExist AHKref.ini
 IniRead, VarTerm, AHKRef.ini, variables, %VarTerm%,No Value
Else
 MsgBox INI file AHKref.ini missing!

; if the file does not exist, we download just once
IfNotExist AHKVariables
  UrlDownloadToFile, https://autohotkey.com/docs/Variables.htm, AHKVariables

 FileRead, RefSource, AHKVariables
 
 If (VarTerm != "No Value")
 {
 Needle := "i).+?<tr id=""" . VarTerm . """>.<td>(.+?)</td>.<td>(.+?)</td>.+"
 CmdRef := RegExReplace(RefSource,Needle,"$1`r`r$2")
 CmdRef := RegExReplace(CmdRef,"<.+?>")
 StringReplace, CmdRef, CmdRef, &quot;, ", all
 ElapsedTime := A_TickCount - StartTime
; Wordwrap the MsgBox command using line continuation
 MsgBox, 3,%Clipboard%, %CmdRef%`r`rClick Yes to open AutoHotkey page
  .`rClick No to continue AutoHotkey search
  .`rClick Cancel to stop search.`r`rTickCount %ElapsedTime% 
 IfMsgBox Yes
 {
   Run https://autohotkey.com/docs/Variables.htm#%VarTerm%
   Exit
 }
 IfMsgBox Cancel
   Exit
 }

This snippet of code appears inside the standard Clipboard routine which saves the original contents of the Clipboard for later restoration.

How It Works

The first line StringReplace, VarTerm, Clipboard, a_ strips the A_ off any built-in variable saved in the Windows Clipboard.  While the complete variable name, including the preceding A_ (e.g. A_Space), when included in a hidden index search jumps immediately to the listing on the AutoHotkey.com site, it does not match the HTML anchor ID in the source code. For that reason we remove it, leaving only the portion which does match the ID. This must occur before checking the INI file since none of the keys include the A_.

Next, we check for the existence of the INI file:

IfExist AHKref.ini
 IniRead, VarTerm, AHKRef.ini, variables, %VarTerm%,No Value
Else
 MsgBox INI file AHKref.ini missing!

This new piece of the script will not function without the INI file. However, after bypassing the variable check section, the script will drop into the remainder of the script which executes the hidden index search. (In an update, I plan to offer the option to immediately download the current AHKRef.ini file.)

If AutoHotkey does not find the AHKVariables file which contains the source code for the AutoHotkey.com “Variables and Expressions” page, then we download it:

IfNotExist AHKVariables
  UrlDownloadToFile, https://autohotkey.com/docs/Variables.htm, AHKVariables

Unless you delete the AHKVariables file, this download only occurs once. Saving the source code on the computer increases the speed of execution and eliminates the need for Internet access (after the first download).

Saving the “Variables and Expressions” page source code on the computer makes sense because it contains information on virtually all of the built-in variables. However, since AutoHotkey commands appear on one or more different Web pages, it would be impractical to download all those pages—at least for a quick reference. For now, as I explore the possibilities, I may add more specific pages to the computer (e.g. math functions), but that will happen on a case-by-case basis.

Read the file into a variable with FileRead, RefSource, AHKVariables. This facilitates the parsing and manipulation of the page source code.

If found in the INI file (If (VarTerm != “No Value”)), then parse the data per previous discussions and display in a new MsgBox:

 MsgBox, 3,%Clipboard%, %CmdRef%`r`rClick Yes to open AutoHotkey page
  .`rClick No to continue AutoHotkey search
  .`rClick Cancel to stop search.`r`rTickCount %ElapsedTime% 
 IfMsgBox Yes
 {
   Run https://autohotkey.com/docs/Variables.htm#%VarTerm%
   Exit
 }
 IfMsgBox Cancel
   Exit
 }

By changing the MsgBox command parameter from 1 to 3, Three options appear in the window: Yes, No, and Cancel. This provides the choices for either: “Yes” loading in the default browser the “Variables and Expressions” page located at the designated anchor,: “No” continuing the script for other hidden index searches; or “Cancel” exiting the script when the window displayed as much as you needed.

As measured by TickCount (31 milliseconds) in the image above, this snippet runs way faster than downloading and parsing individual pages each time the script activates.

Advantage to Using an INI Lookup File

I can shortstop some of the strange lookup errors by adding keys to the AHKRef.ini file. For example, the word “time” finds the same If Var Is Type page as shown for the word “space” above. A logical result might be the built-in variable A_Now for the current time and date. By adding the key pair Time=Now to the INI file, the search gets trapped and returns the results for A_Now.

This redirect can be done for any term which makes sense to you. If you want to see the original result from the AutoHotkey.com hidden index, then select “No” from the MsgBox. The script continues in the same mode as the original script.

More to Come

I have not mapped out everything that will ultimately end up in this script—nor could I. It would be difficult to see all the possibilities while I continue exploring the hidden index and the resulting Web pages from AutoHotkey.com. As I work on the script and test various pieces, more ideas for improvement spring forth. Fortunately, nothing gets written in stone. AutoHotkey script writing is one of the few pursuits where too much preplanning can actually get in the way.