Need Help Understanding #Include Usage Topic is solved

[wddogger]

I am trying to get my head wrapped around how to organize my directory structures for efficient use of #Include functionality. As a total noob at ahk and having read and reread the documentation and posts on this subject I feel I must be dumber than a box of rocks since "the light" has yet to go on, particularly with regard to lib placement in my directory structure and with regard to placement of #Include <scriptname> in scripts.

The following is my current understanding:

The AHK search order for inclusions is as follows & the Parent & all Children will be searched before proceeding further if Not Found in the chain:
1st C:\Users\Me\Documents\AutoHotkey\AHK_Scripts\lib or the directory defined by SetWorkingDir %A_ScriptDir%
‪ Next C:\Users\Me\Documents\AutoHotkey\lib
‪Last C:\Program Files\AutoHotkey\lib ;as defined by A_AhkPath (the location of the AutoHotkey.exe program)

#Include FileOrDirName ;the complete path to a single script, function, or subroutine .ahk or Dir to be included
;place where needed in the code stream as if placed by Cut & Paste the entire code.
;if DirName is used, all scripts, functions, or subroutines in it will be included.

#Include <LibName> ;all scripts, functions, or subroutines .ahk in the library will be included.
;placed in the autoexecute section.
;Does NOT execute included items at this point in the script.
;Requires #IncludeAgain to be placed where execution is required.

#IncludeAgain FileOrDirName ;Place where execution is needed in the code stream. (Multiple instances OK)
;#Include FileOrDirName must exist prior to #IncludeAgain FileOrDirName in the code.

I stumbled upon the following statement while crawling around the internet searching for understanding: "I love using the LIB folder and have a ton of functions in there so I don’t need to use the #Include directive."

If that is true and the Lib is a "container" for numerous scripts, functions and subroutines, how does any new script know where a specific script, function or subroutine is to occur if not by #Include or #IncludeAgain? The statement seems to imply that my understanding is completely incorrect.

Can anyone please confirm that my understanding is correct or, if incorrect, provide clarification with some examples.

My apologies for troubling everyone with what must surely be fundamental knowledge to more experienced/knowledgeable ahk folk.

[boiler]

If that is true and the Lib is a "container" for numerous scripts, functions and subroutines, how does any new script know where a specific script, function or subroutine is to occur if not by #Include or #IncludeAgain?

It looks for functions, not “scripts, functions and subroutines.” How does a script know to look there for functions? Because AHK was programmed to look there. It’s not really any more complicated than that.

[lexikos]

@wddogger
I think you are greatly overcomplicating things. #Include merely does what it says in the manual; Causes the script to behave as though the specified file's contents are present at this exact position. It doesn't care what the file contains, and the file isn't required to contain any functions or subroutines.

1st C:\Users\Me\Documents\AutoHotkey\AHK_Scripts\lib or the directory defined by SetWorkingDir %A_ScriptDir%

No. %A_ScriptDir%\Lib, as it says in the manual. SetWorkingDir and the current working directory have nothing to do with it. SetWorkingDir isn't even called until after the entire script is read from file(s), so after all #include (and other) directives are processed.

;the complete path to a single script, function, or subroutine .ahk

The path of a file from which arbitrary script text (source code) will be read. The directive doesn't care what the file contains. It can contain many functions and/or subroutines, something that isn't either of those things, or even nothing at all.

;if DirName is used, all scripts, functions, or subroutines in it will be included.

No. The documentation clearly states otherwise, next to "Directory:" in bold.

;placed in the autoexecute section.
;Does NOT execute included items at this point in the script.

That sounds like a misconception. You've already noted that #include effectively copy-pastes the content of the file. This has no effect whatsoever on whether or not the code will execute. If the file merely contains ExitApp, and you #include the file in the auto-execute section, it will execute and exit the script. It would be no different to replacing #include itself with ExitApp.

Functions placed in the autoexecute section or inside a subroutine do not execute automatically. They have to be called. This has nothing to do with #include.

;Requires #IncludeAgain to be placed where execution is required.

No. If the file defines functions and subroutines, this will produce an error, as they will be defined twice.

#IncludeAgain FileOrDirName ;Place where execution is needed in the code stream. (Multiple instances OK)

#IncludeAgain allows the contents of one file to be inserted multiple times. Whether or not that is "OK" depends on what the contents are.

;#Include FileOrDirName must exist prior to #IncludeAgain FileOrDirName in the code.

Only to satisfy humans who take the name too literally. The program does not require this.

[wddogger]

Thanks to both Lexikos and Boiler for your your replies. As I said at the outset, " I must be dumber than a box of rocks". With your comments and going back to re-read the documentation on Libraries of Functions: Standard Library and User Library and Using #Include To Share Functions Among Multiple Scripts, The light is beginning to come on. As with most things, one needs to have a firm grasp of the basics before attempting things of greater complexity. I shall return to the basics with some examples from AHK documentation. Thanks again.