Thoughts on AutoHotkey

[jeeswg]

INTRODUCTION
- I intend this post to contain my main thoughts re. AutoHotkey.
- There isn't really too much I want to say regarding meta discussions of AutoHotkey. And what I do want to say, I've collected here.
- I have been concerned to get AHK v1.1 some of the (in my opinion) key features it needs before it's 'abandoned', and to anticipate newbie concerns re. AHK 2.0, and to avoid some of the problems that occurred during the AHK v1.0 to AHK v1.1 transition.

LINKS RE. THOUGHTS
AutoHotkey v2
https://autohotkey.com/v2/
v2-thoughts
https://autohotkey.com/v2/v2-thoughts.htm
v2-changes
https://autohotkey.com/v2/v2-changes.htm

THOUGHTS ON V2-THOUGHTS
v2-thoughts
https://autohotkey.com/v2/v2-thoughts.htm
- I view the ahk_mode/ahk_dhw functionality as something that AHK fundamentally needs, and not 'bells and whistles', in the same way that AHK v1.0 needed, but never got, ahk_exe. I don't mind a delay in it being added to AHK v2, but I do feel it is something that AHK v1.1 would also need. [If AHK v1.1 ever lets you refer to built-in functions, that you have redefined, I could do a custom backport.]
- I think that perhaps some of the ControlXXX functions should be replaced with functions like EditXXX or LVXXX. After much reflection, it seems like the most sensible solution. [I don't really mind what the final outcome is.]
Control Functions
https://lexikos.github.io/v2/docs/commands/Control.htm
[see the very bottom of this post:]
why was LoopParse (no space) removed? - Page 2 - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=37&t=41821&p=190742#p190742
- 'it could be used for calling an overridden built-in function'. Sounds interesting.
- Re. changing functions. Commands can be changed in any way whatsoever pretty much, without problems, as they are being replaced with functions. However, any changes to how existing functions work (that aren't simply increasing functionality) could cause major headaches. I fully support the changes to InStr/SubStr/RegExMatch/RegExReplace (the previous behaviours for these were undesirable).
- Re. linear arrays. I don't mind if none of this is added for AHK v2's first release or for a long time after that, but I am curious re. things like: sort linear array keys by values, or generally, the equivalent of applying the Sort function to items in a linear array, i.e. general handy/simple array-related functions. I.e. I had thought that such functionality might be added in to AHK v2, and was curious as to what it would be.

FUNCTION DESIGN PRINCIPLES (IN MY FUNCTION LIBRARIES)
(generally speaking)
- Win functions: first parameter should be an hWnd
- Ctl functions: first parameter should be a control hWnd
- Date functions: first parameter should be a datestamp
- Date functions: for functions that return a datestamp, include a Format parameter, cf. FormatTime, but with default format 'yyyyMMddHHmmss'
- Date functions: use if (vFormat == "yyyyMMddHHmmss"), it must be '==', not '=', to do a case-sensitive comparison
- Time functions: for absolute amounts of time, not datestamps
- numbers are not memorable: e.g. for file/registry loops, F/FD/D and V/VK/K (is better than the previous 0/1/2)
- numbers are not memorable: I would recommend for ahk_mode/SetTitleMatchMode: S/C/X/R starts/contains/exact/RegEx, not 1/2/3/RegEx (and 'E' for 'ends')
- numbers are not memorable: I would recommend for ahk_dhw (i.e. DetectHiddenWindows): V/VH/H (visible and/or hidden)
- c x s e: commonly with strings, you want (e.g. in RegEx form): contains, ^exact$, ^starts, ends$

FUNCTION DESIGN: RECURRING ISSUES
- Syntax for a parameter that could be an object or a variable.
notation: parameter could be a variable or an object - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=43090
- Syntax for specifying delimiters/separators.
notation: parameter that specifies delimiters/separators - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=43273
- Algorithms for looping through hierarchies.
objects: hierarchies: listing/comparing objects - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=41510&p=195297#p195297

NEW FEATURES: PRIORITIES (FOR AHK V1/V2)
- Deref function: bring it back (in my opinion)
- ahk_dhw (s/c/x/e/r) and ahk_mode (v/vh/h) [I could recreate this via custom functions, but then none of those scripts could be shared on the forum without providing the custom functions]
note: an extra reason for ahk_dhw/ahk_mode:
DetectHiddenWindows bug? - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=14&t=30010
- #Include: support more 'A_' variables (e.g. A_Desktop/A_AhkPath/A_UserName), and allow an /inc command-line switch [EDIT: Support for all 'A_' variables has been added to AutoHotkey.]
- See also:
Wish List 2.0 - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=13&t=36789

TWO-WAY COMPATIBILITY BENEFITS
- Apologies if this section is a bit harsh, but I've heard so much rubbish re. people complaining about two-way compatibility.
- [EDIT:] To clarify: I intend that you can have scripts/libraries that can work in both AHK v1/v2. The new AHK v2 functions are recreated as custom functions for AHK v1, that is the core principle that makes two-way compatibility possible.
- You can share AHK v2 libraries, that also work in AHK v1, if you use a proposed AHK v1 directive (e.g. prepend '% ' to Loop parameters, `" to ""), or do some minor conversions yourself.
- You can test AHK v1 scripts against the #MustDeclare warnings from AHK v2, to help improve/correct your scripts.
- You can convert and test complicated parts of AHK v1 scripts, without having to convert the entire script.
- You may have difficulties converting an AHK v1 script to AHK v2, that *someone else* wrote, it will be easier to partially convert it (but run it in AHK v1), using an AHK forwards compatibility function library, before you then convert it to AHK v2.
- To identify what the AHK v1/v2 one-way conversion(/two-way compatibility) obstacles are. I.e. I run an AHK v1 script in AHK v2, and see if any new errors have emerged.
- Don't forget the newbies. It was an odyssey for me to convert from AHK v1.0 to AHK v1.1 at the time.
- Anything to facilitate conversion or compatibility is a bonus.
- [EDIT:] You may want to check that a *script* is AHK v2 ready, even though the *function libraries* that it uses are not yet AHK v2 ready.
- Note: Complaints about additional overhead (when using a two-way compatibility library that wraps commands as functions) are a straw man argument.
- Note: You probably haven't converted *all* of your AHK v1 scripts(/libraries) to AHK v2 yet, or don't use AHK very much(/don't use many libraries), and so are in no position to comment for or against it.
- Note: You have probably underestimated the difficulties relating to conversion. [EDIT:] Btw you have to convert the libraries(/code by other people) that you use, not just your own scripts.
- Note: There are no costs involved in two-way compatibility, apart from the work involved in any functionality explicitly added to AHK v1 to make it easier to run scripts written for AHK v2.
- Note: Of course I thought about not stunting AHK v2 scripts, when making them backwards compatible, there are simple solutions to this.
- Note: Honestly, stop being so arrogant thinking that you've sussed out all the conversion difficulties.
- Note: 'I'm going to convert all of my scripts, within a short time period, with no difficulties.' Sure you will.

GENERAL SCRIPT/FUNCTIONALITY IDEAS
#MustDeclare - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=37&t=6905&p=191203#p191203
objects/object classes: new features from a newbie-friendly perspective - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=37&t=6905&p=191203#p191203

TUTORIAL PRINCIPLES
- I consider a tutorial to be made up of text with occasional/frequent code examples. Where ...
- You can learn everything from the text alone, without the examples.
- You can learn everything from the examples alone, without the text.
- This is done by bulking up the text/code examples to make sure that they fully explain everything independently, and don't rely on each other.
- (Normally my concept of a tutorial is quite clear, but there can be grey areas, e.g. a tutorial explaining how to speed up a script, that revolves around benchmark tests. The benchmark tests may seem self-explanatory, but actually a paragraph introduction for each one might be beneficial. Imagine that all the code boxes are removed, what remains?)
- Never use 'foo' or 'bar' in an example. It instantly makes things less clear.
- Never compare the concept of an object to something from real life. Or rather, go straight to something simple but that has an IT context.

WRITING PRINCIPLES
- To simplify/structure posts, use headers (e.g. titles in upper case) and bullet points.
- Ask can any paragraphs be chucked out.
- Ask can I combine two things.
- Ask what are the key points that I want to make (and highlight/clarify those points, and possibly remove other things).
- If you change subject, make that clear in the first sentence of the paragraph.
- ... Outline in the first sentence of each paragraph what is meant.
- ... Outline at the start of a bullet point what you're referring to.
- Basics. Reread to add omitted words.
- Basics. Consider things like commas, to add clarity.
- Basics. Use a spellchecker, e.g. one written in AutoHotkey.
- Consider concrete example scripts/prototypes, instead of a complicated description of code, or a list of required features.

WRITING PRINCIPLES (RESPONSES)
- If someone makes an invalid criticism that you feel you need to respond to, but you feel a response could clutter/derail your post. Respond, but be concise.
- If you partially agree with someone, express this.
- If you can anticipate somebody else's concerns, express this.

FIRST PRINCIPLES
Mind Set - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=17&t=37065&p=180760#p180760
[How does it work?]
jeeswg's homepage - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=17&t=30931&p=144442#p144442

Thanks for reading.