This 'XRef' program produces an alphabetical cross reference list of all the names, numbers, and words in an *.AHK file, showing the source line numbers where these items occurred. Any quoted information is also included.
XRef can also process DOS batch files, as well as C and JS files.
A cross reference listing is very useful for:-
- Locating where program variables are set and used.
- Determining unused variable names when allocating new ones.
- Spotting mis-spelled variable names.
- Understanding an unfamiliar script.
The options window is used to specify which reports are required and provides options to control report format and amount of data to be included, etc. Note that several check-boxes in the options window can be toggled into a third state. In these cases the option text will alter to show more details about the selection made. (See the screen shot below.)
An optional extra 'Function Map' can also be produced, showing where in the program functions and subroutines are defined, and where they are referenced. This map is in addition to the main report, however it displays the data in the same order that it occurs in the program being analysed. When '#Include' processing is enabled, the listing will show all processed scripts in order, with the file name at the start of the script section. (See the example output snippet.)
There is an option to process a subset of the script; 'Get script subset'. When prompted, enter the starting and ending line numbers separated by a space. This facility can be used to analyse a self-contained portion of a script, such as a function definition.
A particular set of options plus setup can be saved as the overall default, and a different set of options can be saved for each script to be processed, if necessary.
As well, a different default set of options plus setup can be saved for a general subset-type report (select 'Get script subset' with any line numbers first), and yet another set of subset-type options can also be saved for the currently selected script.
The type of default options in use is shown between hyphens in the title bar at the top of the Options window.
Any script options previously saved may be erased - click on the 'Update...' checkbox to see the different saving and erasing options. To access the subset-type defaults for the currently selected script, first select 'Get script subset' (with any line numbers), then the 'Update...' checkbox and button will process the subset-type defaults.
The generated report is shown in Notepad and may be automatically printed to the default printer if required. If a 'page size' is supplied in the setup, the report will be formatted 'n/up' to take up less space.
To show the report correctly, Notepad should be set to use a mono-spaced font. This can be achieved by using the 'Mono' button to set Notepad to its defaults. The old position and size of Notepad's window is preserved.
Script comments are usually excluded from the report, however there is an option to include this information if required. (As syntax analysis is rudimentary in this program, it is possible that valid data in some scripts may be inadvertently flagged as comments.)
AHK '#Include' statements can now be processed to generate composite reports of the complete program, if required. (Script types other than AHK are not supported.)
When this option is enabled, each included file is assigned a single alphabetic reference key from the series A, B, C, … Z. If there are more than 26 included files, the lower case letters a, b, c, … z are used as required. If there are more than 52 included files, an extra letter is used to give the series AA, AB, and so on. The reports will show the appropriate reference key appended to the line numbers. (See the example in the output snippets.)
An extra '#Include List' is produced (see the output snippets example below) which specifies what #Include options were used, and shows for each included file:-
- The key assigned. (If none, the file is not included in the cross reference.)
- The full path and file name.
- A reference to the relevant #Include statement. (If none, the file was auto-included.)
(#Includes which change the working directory will not be shown.)
When the '#Include processing' option is selected, there are two levels of processing available:-
- '#Include with partial library links':- In this case, files included using the '#Include <LibName>' form of the directive, and any auto-included files will be almost completely omitted, except for any function calls made from the other files. The thinking here is that as library files should contain self-contained, trusted, reliable code, most of this data can be omitted from the reports.
- '#Include with full library links':- In this case all Included files will be fully processed.
To make use of the auto-includes facility in the case where AutoHotkey has not been formally installed but the executable is available, XRef has a facility whereby the AHK executable can be used. As part of the setup, create a shortcut pointing to XRef.exe, and include as the first parameter the full path and file name of the AHK executable to be used to process auto-includes. Subsequently, start XRef with this shortcut. This facility can also be used if there are different versions of AHK present on the computer (e.g. v1 and v2) by creating different shortcuts as required.
To process one or more scripts without any user intervention, you can drag and drop the scripts onto XRef.exe (or a shortcut pointing to XRef.exe), and the scripts will be processed automatically using the default options (script or overall). The same will happen if you run XRef.exe supplying the script names as parameters. (If a script can't be found, an error message is shown, then the usual file selection dialog will be displayed.)
Screen shot and output snippets
XRef can be downloaded from here. The zip file includes AHK v1.1 source, executable, and preferred icon.
Update History (latest at top)