Cross Reference List (XRef)

Post your working scripts, libraries and tools
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Cross Reference List (XRef)

11 Mar 2016, 20:37

Introduction
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.

Options window
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.)


Function Map
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.)


Subsets
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.


Defaults
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.


Output
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.)


#Include Processing
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.)
This list will also show any error messages that may have occurred during processing.
(#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.
Files which are auto-included need to be processed by the installed 'AutoHotkey.exe' executable, which will be called by XRef if required. If AutoHotkey.exe has not been installed, then an error message will be shown, and any auto-included files will not be processed. Also, if the script contains syntax errors detected by AutoHotkey.exe an error will occur. These error messages can be suppressed by checking the 'Block auto-includes' check-box.

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. You have to 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. You would then 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.


Automatic Mode
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

Download
XRef can be downloaded from here. The zip file includes AHK v1.1 source, executable, and preferred icon.

Update History (latest at top)
Last edited by TAC109 on 02 Jun 2019, 18:57, edited 53 times in total.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

18 May 2016, 22:45

Updated 19 May 2016 -
The 'mono' button now doesn't generate a UAC prompt and keeps Notepad's previous position and size.
The 'Print Report' option has been updated.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

19 May 2016, 19:52

One of the last changes I made was to the 'Print Report' facility to try and make it work correctly on non-English versions of Windows. I would be interested to hear back from anyone using this option of XRef under these circumstances. (There may be a pause of 4 seconds while the 'print' Windows of Notepad are shown.)

So, any comments on this from users would be helpful.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

10 Jul 2016, 19:12

Updated 11 July 2016 -
Added two options for 'tighter' formatting, which will generate more compact reports.
Separated out the 'Exit Notepad' option from 'Print report'.
The Notepad window now comes to the front after a report is generated.
Can select a new file to process from the Options window.
Eliminated the possibility of some incorrect references when generating a Function Map.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

12 Jul 2016, 02:51

Updated 12 July 2016 -
Fixed a bug when generating a Function Map for some .js scripts.
Fixed a bug when generating a Function Map for .ahk scripts when including comments.
Last edited by TAC109 on 16 Feb 2017, 18:26, edited 1 time in total.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

11 Aug 2016, 20:09

Updated 12 August 2016 -
Fixed a formatting issue when generating a Function Map and Lines/page is zero.
Last edited by TAC109 on 16 Feb 2017, 18:27, edited 1 time in total.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
Helgef
Posts: 3703
Joined: 17 Jul 2016, 01:02
Contact:

Re: Cross Reference List (XRef)

11 Aug 2016, 23:51

Could be very useful, I'm going to try this when I get the chance. Does it include content in #include
files?
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

12 Aug 2016, 00:12

No, just the file selected. You can process the #include files separately, as they may not change frequently and thus not need to be reprocessed.

You can also use 'automatic mode' by setting up a shortcut to XRef containing the names of all the relevant program files. You can then run this to produce all the outputs. Note that the reports will still be separate, one per input file.

[Edited to include automatic mode suggestion]
Last edited by TAC109 on 18 Jul 2017, 19:51, edited 1 time in total.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

14 Aug 2016, 01:20

Amended and added to the description in the first post.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
Helgef
Posts: 3703
Joined: 17 Jul 2016, 01:02
Contact:

Re: Cross Reference List (XRef)

14 Aug 2016, 11:38

Hello TAC109. I did a breif test, it looks good and is quick! On the #include matter, for me it would be useful since I often split my (slightly bigger) projects into quite a few files, basically one main script with just a bunch of #include.
Great job though, thanks.
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

14 Aug 2016, 18:53

Thanks for your kind comments.

I've read up on #include in the help and the rules are quite complex. The 'file/dir' parameter can include various 'A_' type references, many of which relate to the script's actual location. The related 'libraries of functions' section introduces further complexities where functions can be implicitly included from various folder locations.

Then there is the question of how this extra data should be included in the report. One large combined list with the current neat line numbers list replaced by file/line number references, or many separate reports, one for each file.

I don't see that all the extra programming required as yielding many advantages over what I've suggested, that is to just sequentially select the files to be processed as needed. If you change a couple of files in your program suite, then just run XRef on those files.

The only deficiency is with the optional 'Function Map' report which will be incomplete without the included files. This is not a report I use very often, as this data is also embedded in the main report.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

01 Nov 2016, 20:56

Updated 02 November 2016 -
Added an option to analyse a subset of the script.
The Cross Reference List file is now saved as Unicode (UTF-8).
Last edited by TAC109 on 16 Feb 2017, 18:26, edited 1 time in total.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

14 Jan 2017, 21:31

Updated 15 January 2017 -
Can save separate defaults for the 'Get script subset' option - see amended documentation.
Supports AHK2 Unicode variable names.
Last edited by TAC109 on 16 Feb 2017, 18:25, edited 1 time in total.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

16 Feb 2017, 18:25

Updated 17 February 2017 -
Added a drag and drop facility (Automatic mode) and updated documentation.
Last edited by TAC109 on 23 Jul 2017, 19:53, edited 1 time in total.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

18 Mar 2017, 17:20

19 March 2017 - updated download link.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
IMEime
Posts: 750
Joined: 20 Sep 2014, 06:15

Re: Cross Reference List (XRef)

20 Mar 2017, 19:34

I've tried it.
Working well and looks nice.

Interesting..

I have a question.
Your coding style is so unfamiliar to me.
Lots lots of commas and not much spaces.
I'm using Notepad++ and I concluded, it is not human readable codes.
How do you write, edit and debug it ?
Do you use something special method to compress it after you completed ? If so, why ?
And for the exe file.
Do you use your own method to compile it ?
If I open it with Notepad++ (usually, it shows the codes cleaner than mine) I've failed to see the source codes within it.

Thanks for the nice codes.
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

21 Mar 2017, 00:25

Thanks for your kind comments!

I suppose my coding style could be regarded as 'normalised'. You will have heard of data normalisation, where basically, any duplicate data is removed and replaced by a reference to a single occurrence (see Date & Codd normalisation). Well, I like to do similar by normalising my code. Not to everyone's taste but it suits me.

I just use SCiTE4AHK as my editor and debugger.

You'll see that my code is very modular. The tricky code I often debug by creating a simple test harness for each routine to ensure that it works correctly. Many routines start with basic code and then are enhanced incrementally, with testing after each amendment.

(Using XRef on itself will reveal a lot.)

I use fincs' AHK2EXE (preview2a) to compile my source and UPX to compress it. (I have found that Mpress can occasionally generate corrupt .exe's.)

[Edit] - I now use the excellent AHK_Compile_II to compile my programs. This automatically compresses with UPX.

As a diagnostic, if you press Win+F2 after generating a cross reference, you will see the structure of the 'q' object which holds the various 'n/up' report data items. (The program uses the 'q' object to produce and select the most compact report.) This diagnostic was a great help when debugging this part of the program.
Last edited by TAC109 on 23 Jul 2017, 01:41, edited 1 time in total.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
IMEime
Posts: 750
Joined: 20 Sep 2014, 06:15

Re: Cross Reference List (XRef)

21 Mar 2017, 06:07

Thanks reply.
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

12 May 2017, 01:19

Updated 12 May 2017 -
An error message is shown if the script file cannot be found when in automatic mode.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
TAC109
Posts: 287
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Cross Reference List (XRef)

10 Sep 2017, 23:00

Updated 11 September 2017 -
Now processes the changed v2 */ comment delimiter correctly.
My programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts

Return to “Scripts and Functions”

Who is online

Users browsing this forum: No registered users and 26 guests