Building a Lookup Table with an INI File (AutoHotkey Reference Tip)

In AutoHotkey, You Can Use an INI File as a Database for Relating Lookup Table Items

Admittedly, AutoHotkey lacks sophisticated database tools for storing, sorting, and reporting sets of information. While you can piece together commands to create pretty good database file systems, AutoHotkey does not hold a candle to specialized data handling software packages which use SQL and other high-powered relational tools. However, AutoHotkey does support a simple form of a database called an INI file with built-in commands which make it easy to read and write data. These features give us a method for building a lookup table to relate our AutoHotkey Version 1.1 commands to 2.0 functions references.

*          *          *

Library BenefitsHighlighting the scriptwriting process, this series of blogs offers tips and tricks for building an app using a simplified INI database as a lookup table for relating data items, accessing Web pages without using a browser, extracting information from Web pages with RegEx functions, and introducing new techniques for dealing with the exceptions. In this series, I plan to build an AutoHotkey application using the online AutoHotkey reference information for both Version 1.1 commands and the corresponding Version 2.0 functions. Although designed for the AutoHotkey documentation, the approaches demonstrated in these blogs apply equally as well to many other AutoHotkey projects.

Creating any AutoHotkey app of this nature demands a great deal of trial and error while writing and testing code in a step-by-step manner. As I progress in this effort, I plan to document the critical aspects of development while highlighting any insights. The order of feature development may vary, but the most important requirement for app creation lies in the vision of the final product held in the scriptwriter’s brainpan. I test many possible techniques while almost continuously adding and altering code.

To date, the series includes this and the following blogs:

Part 1: Accessing Web Pages (AutoHotkey Tips)

*          *          *

AutoHotkey INI Files

Microsoft Windows uses INI files as “Initialization” files—generally for software set up and saving program parameters. In the current versions of Windows, the Windows Registry replaces the old operating system dependencies on INI files, however, many Windows programs continue to use INI files for configuration data. Since AutoHotkey directly supports INI files, they offer an excellent method for saving and accessing data—as long as the application doesn’t demand too much. For a simple index such as relating AutoHotkey V1.1 command to V2.0 functions, INI files provide a reasonable solution.

The fact that you can automatically search two hierarchal terms in an INI file provides a built-in advantage over other forms of AutoHotkey file reading and writing. As an additional plus, the all-text structure of an INI file makes it easy to build and edit the file with any text editor. (I generally use Windows NotePad or the free text editor .) On the downside, those same limits of search capability and the lack of data indexing make INI files unsuitable for the most elaborate applications.

AutoHotkey searches INI files from top to bottom using a SectionName, followed by a Key which matches (equates =) to the saved Value, as shown in the following file structure:


By placing the SectionName within square brackets, you create the top-level search category. The Key, which represents a subcategory within the Section, uses the equals sign (=) to designate the Value stored in the INI file. You can use almost any text for these three entries. While all Keys must fall below the appropriate SectionName, the order of the Keys does not matter. The AutoHotkey IniRead command returns the first Key encountered—regardless of duplicate Keys within the same Section.

When to Use an INI File as a Lookup Table

Click an image and an audio WAV file plays.

A simple INI database can save a great deal of code writing. By placing Key=Value pairs in a file, rather than adding individual items to the AutoHotkey script, you can create short routines which perform operations based on results from the INI lookup table. For example, suppose you want to write a kid’s app which plays sounds when clicking on a graphic image embedded in a GUI pop-up window. You might use an INI file similar to the following:

Dancing Dogs.jpg=dog_bark_x.wav
Cheese Burger.jpg=cow-madcow.wav
Phone.jpg=Windows Ringin.wav

By building an INI file which links each graphic to the appropriate sound, you can eliminate the need for a separate gLabel subroutine for each graphic in the GUI pop-up window. Now, it’s just a matter of adding the appropriate images to the GUI pop-up:

Gui, Add, Picture, x50 w50 h-1 section gFunctionTest, Dancing Dogs.jpg
Gui, Add, Picture, w50 h-1 gFunctionTest, Cheese Burger.jpg
Gui, Add, Picture, w50 h-1 gFunctionTest, Phone.jpg
Gui, show, w150 h175

FunctionTest(CtrlHwnd, GuiEvent, EventInfo, ErrLevel:="")
  GuiControlGet, OutputVar , , %CtrlHwnd%,
  IniRead, Sound, PictureSounds.ini, Sounds, %OutputVar%
  SoundPlay, %Sound%

In this sample script, AutoHotkey adds images to a GUI window using the same file names listed as Keys in the INI file. Then, using this special GUI Control  function (added into V1.1 to replace a gLabel):

CtrlEvent(CtrlHwnd, GuiEvent, EventInfo, ErrLevel:="")

we can recall the name of the image file to use as a Key to locate the appropriate WAV sound file in the INI file search.

Note: While I don’t go into the details of how this PictureSound.ahk script works (shown above), I plan to use it as an example of a database-driven AutoHotkey application in a future blog. Database-driven apps can create extensive, flexible apps with very little code.

Working with AutoHotkey INI File Commands

AutoHotkey uses three commands to read and write INI files—IniRead (to access data), IniWrite (to save data), and IniDelete (for deleting specific Sections/Keys). The IniRead command scans through an INI file and returns Values by searching first for the SectionName (no square brackets), then the Key:

IniRead, OutputVar, Filename, Section, Key , [Default]

If found, the command stores the Key ⇒ Value in OutputVar.

The AutoHotkey Reference Lookup Table (INI File)

As I don’t plan to do anything which reaches beyond the limits of INI files—even without any type of database index—AutoHotkey should quickly execute the INI searches.

Since most of what I want in my lookup table appears in the AutoHotkey Alphabetic Command and Function Index Web page, I start with that list. After opening the source code for that page (right-click and select View page source in the Google Chrome browser) and copying all of the code (CTRL+A, then CTRL+C), I paste (CTRL+V) it into the top Text to be searched pane of the RegExReplace tab of Ryan’s RegEx Tester to extract the INI file startup data.

(Rather than going into the details of the RegEx process I used to create this first INI file, I refer you to “Ryan’s RegEx Tester for Building INI Data Files (AutoHotkey Quick Reference Script” where I build a simple INI file which took advantage of the (now defunct) AutoHotkey documentation’s secret index. While it required a bit more complicated RegEx to do this one, the steps remain the same. In future blogs, I will use simpler RegEx codes to extract information directly from Web pages.)

Note: If you don’t know or work with Regular Expressions (RegEx), then this blog may wade too far into the weeds for you. However, AutoHotkey contains hundreds of commands and functions and I don’t know where else I can get a comprehensive list to start my INI file without using Regular Expressions. I wrote the book A Beginner’s Guide to Using Regular Expression in AutoHotkey primarily to ensure that I know how to work with RegEx. Even so, I often refer to the online “Regular Expressions (RegEx) – Quick Reference” page to remind me of how the functions work. (For a quick peek at RegEx, see this “Introduction to Regular Expressions (RegEx) in AutoHotkey page.”)

Ryan’s RegEx Tester converts the text from the AutoHotkey V1.1 Comand and Functions Index page into the startup data for the new INI lookup table. See the AutoHotkey Regular Expression – Quick Reference page for the meaning of the Regular Expression and the RegExReplace() function for the Replacement Text code shown in this image.

I copied the output from the Results pane of Ryan’s RegEx Tester into my text editor to create my new INI file and inserted the SectionName, [Commands], into the first line at the top of the file.

Paste the text copied from the Results pane of Ryan’s RegEx Tester directly into a new text file.

I used the vertical line character ( | ) as a delimiter for separating the various values for each data Key. The initial fields correspond to the following types of data:

Command=Command/Function|Web page|Description|
  ⇓             ⇓          ⇓          ⇓
 Input  =     Input  |  Input.htm | Waits for the user to type a string.|

I insert the special character (|) to delimit Value items as a trick for storing multiple types of data in the INI file. I will use the StrSplit() function to parse (separate) the values in the AutoHotkey V1.1/V2.0 Reference script.

While this setup offers a decent start for the INI lookup table, many V1.1 commands don’t directly correlate with a V2.0 function. I will need to make adjustment directly to the INI file by changing data and adding more fields (inserting additional vertical lines—most likely by hand).

Reading the AutoHotkey Reference INI File

Once I set up the file, I can use it to relate data for reading the AutoHotkey online documentation for both V1.1 and V2.0.

This MsgBox window uses data extracted directly from the AutoHotkey V1.1 command page, the alternative function for any deprecated commands, and the parallel V2.0 function page. The window title at the top and the description at the bottom of the window come directly from the INI lookup table.

This MsgBox uses the INI lookup table to match AutoHotkey V1.1 commands to V2.0 functions, then accesses the associated Web pages and extracts the command/function format directly from those pages. I’ll save discussing that code for a future blog. (I also plan to eventually switch to a GUI pop-up to overcome the limitations of the MsgBox command.)

GraphicSoundsIn my next blog, I plan to temporarily segway into using an INI file to create database-driven applications. I’ll demonstrate how to use both ends of the PictureSound.ahk INI file (the Key and the Value) to generate code and link results.


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. I’ve never used the paid version of the software so I can’t give an opinion on that service.)

One thought on “Building a Lookup Table with an INI File (AutoHotkey Reference Tip)

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