Jump to content

Sky Slate Blueberry Blackcurrant Watermelon Strawberry Orange Banana Apple Emerald Chocolate
Photo

Standard Library (stdlib): Simple file-system approach


  • Please log in to reply
63 replies to this topic

Poll: Should each stdlib function name begin with an underscore? (8 member(s) have cast votes)

Should each stdlib function name begin with an underscore?

  1. Yes, to reduce competition with user function names and indicate at-a-glance that the function is external. (1 votes [12.50%])

    Percentage of vote: 12.50%

  2. No, it's better not to "penalize" stdlib functions in this way. (7 votes [87.50%])

    Percentage of vote: 87.50%

  3. Other (0 votes [0.00%])

    Percentage of vote: 0.00%

Vote Guests cannot vote
toralf
  • Moderators
  • 4035 posts
  • Last active: Aug 20 2014 04:23 PM
  • Joined: 31 Jan 2005

One of the easiest methods might be to create an init function that a user must call somewhere in their code to enable the functionality in their script.

INIT function will defintiely be used but it can not solve above issue as if there are no classes, parser will expect each module func to be in separate file.

I agree with corrupt. Because, if the init funtion, e.g. "MMenu()" is called, before any other MMenu_XXX() function gets called, the MMenu.ahk file gets included, so at the call of a MMenu_XXX() function that function is already part of the script.
Ciao
toralf
 
I use the latest AHK version (1.1.15+)
Please ask questions in forum on ahkscript.org. Why?
For online reference please use these Docs.

toralf
  • Moderators
  • 4035 posts
  • Last active: Aug 20 2014 04:23 PM
  • Joined: 31 Jan 2005
I voted for no "_" prefix.

I also do not see how a single character for internal functions would solve naming conflicts. In this respect I adopt majkinetor idea of classes: Internal functions have to have the main function (aka filename) as prefix with a "_" as separator. Then there only needs to be a rule that you should not create new library functions which name starts with an existing library functions name and a "_".

This will unfortinately remove the posibilty to have something like this:
Imagine there is a file toralf.ahk with the toralf() function in the library with internal functions (toralf_XXX()). Now users should not create a toralf_myversion.ahk file/function, since it might create naming conflicts. Of cause they could create a file/function toralfMyVersion.ahk.
Ciao
toralf
 
I use the latest AHK version (1.1.15+)
Please ask questions in forum on ahkscript.org. Why?
For online reference please use these Docs.

majkinetor
  • Moderators
  • 4512 posts
  • Last active: May 20 2019 07:41 AM
  • Joined: 24 May 2006
Yes, now it can be done this way as Chris stated that this is true :

If a script contains an explicit definition for a function (or one of its explicit #include files does), AutoHotkey won't ever search for that function externally. At least, that is the current plan, and it's also what fits best with the program's current design.


So when INIT function adds rest of the module, subsequent MMenu calls will not be searched as of above quote.

The problem is that we have additional function call for any module, so if user used 5 modules, it will need to have 5 inits. Not a big problem IMO, but alternative is more in AHK sprit. I beleive that missing INITs will be great source of confusion. Even I, forget to use my own inits. MMenu previously had INIT function and I remeoved it as I was often forgeting it. So, this "architectural detail" influence users alot.

Also, this will split every module to at least 2 files. File containing init and includes and file containing rest of the module. When you add new module function you have to add it in 2 places.

Imagine there is a file toralf.ahk with the toralf() function in the library with internal functions (toralf_XXX()). Now users should not create a toralf_myversion.ahk file/function, since it might create naming conflicts. Of cause they could create a file/function toralfMyVersion.ahk.


First, lets adopt something:

Private Function (PF)
The function not exposed and not documented to stdlib users, used privately in module implementation

Module API function (MF)
Function that is part of the module API exposed to stdlib users. Only modules have MF's. Although, standalone functions in single files are MF (like Anchor), as single function represent entire module interface, I will not use "MF" to reference those functions. See next defintiion.

Single Standalone Function (SSF)
Function that is the only interface function of trivial module.

- SSF don't have class separators. So any name should be allowed here as long as it isn't equal to some other library name.

- MF should have class separator. MF function should be named as Module_FunctionName. MF's are used together as a whole, as a module API, so it is not desirable to split modules into multiple files for the sake of organisation, maintaince, and performance.

- PF is function not documented for outer world. This function is to be used internaly by module or SSF. This function must be named so that it doesn't make problems to other developers or stdlib itself. One good way is to use SSFName_Function. Other developers should not choose function names that starts with the name of known stdlib function finished with underscore.

-------------------

So, torlaf is SSF, its private functions are named toralf_XXX. So other developers should not create functions starting with toralf_. Thus, toralf_MyVersion will obviously be example of bad code writting if the torlaf function already exists in StdLib.

Morover it would be good to reserve _ in stdlib only for classes. This is small rule and will create nicer environment. If you see _ in the name, you know it is part of some module, so you can check out the module to see what other things it offers. If you don't see _ you know it is SSF. As users of stdlib will never see PF's this will be good (PF's have MMF syntax) . This has nothing to do with implementation, just with coding standards for stdlib.
Posted Image

toralf
  • Moderators
  • 4035 posts
  • Last active: Aug 20 2014 04:23 PM
  • Joined: 31 Jan 2005
Regarding the 2 directories for stdlib and userlib:
I prefer to separate my own work from that of the installed data coming with the distro. Which prevents overwritting and allows easy backup. For years(even before Vista) microsoft suggests to use the A_AppData path for user specific data. I would like to see a AutoHotkey subdirectory created there with a subdirectory for includes. Or just a plain AutoHotKeyUserLib directory.
This would be a professional way, but I do not know how this works with a removeable stick.
Ciao
toralf
 
I use the latest AHK version (1.1.15+)
Please ask questions in forum on ahkscript.org. Why?
For online reference please use these Docs.

majkinetor
  • Moderators
  • 4512 posts
  • Last active: May 20 2019 07:41 AM
  • Joined: 24 May 2006

microsoft suggests to use the A_AppData path for user specific data.

Although this doesn't troubles me much, I must say that you can't call a thing non-proffesional just cuz its not using MS standards. Contrary to that, many pro apps don't follow it, but they are still pro.

Anyway, good old ini is returned and ppl like portable apps more then ever. I, basicly, don't use non-portable apps.
Posted Image

toralf
  • Moderators
  • 4035 posts
  • Last active: Aug 20 2014 04:23 PM
  • Joined: 31 Jan 2005

The problem is that we have additional function call for any module, so if user used 5 modules, it will need to have 5 inits. Not a big problem IMO, but alternative is more in AHK sprit. I beleive that missing INITs will be great source of confusion. Even I, forget to use my own inits. MMenu previously had INIT function and I remeoved it as I was often forgeting it. So, this "architectural detail" influence users alot.

I don't think it will be a big souce of error, since AHK will warn you that it doesn't find functions. AHKs warning message could be extended that if the function contains a "_" that the init function might have been missing, so that users would be pointed into a possible direction.
BTW: The init function doesn't need to have "init" in its name.

Also, this will split every module to at least 2 files. File containing init and includes and file containing rest of the module. When you add new module function you have to add it in 2 places.

Why? The file with the init function can contain all functions. To my understanding there is no need for a second file.
Ciao
toralf
 
I use the latest AHK version (1.1.15+)
Please ask questions in forum on ahkscript.org. Why?
For online reference please use these Docs.

majkinetor
  • Moderators
  • 4512 posts
  • Last active: May 20 2019 07:41 AM
  • Joined: 24 May 2006

Why? The file with the init function can contain all functions. To my understanding there is no need for a second file.

Yes, it can be done with single file if we adopt INIT function to be named as module. For MMenu case it must be MMenu(), so AHK searches for MMenu.ahk among stdlib. If I call it any other way, lets say MMenu_INIT(), I need to keep module in MMenu_INIT.ahk.

Having non standardized name for INIT function is not good, as users will have to read doc before using any module, as different modules will have different initialisation names. If module base name acts like INIT function ( MMenu() ) then we can use 1-1 principle without classes. The drawback would be users will have to initialise every module they use witch will lead to stdlib behaving differently then AHK language in which things usualy don't have to be initialised.
Posted Image

corrupt
  • Members
  • 2558 posts
  • Last active: Nov 01 2014 03:23 PM
  • Joined: 29 Dec 2004

This would be a professional way, but I do not know how this works with a removeable stick.

It seems to work ok with a directive added to prevent the UserLib from being used
#UserLib *None


majkinetor
  • Moderators
  • 4512 posts
  • Last active: May 20 2019 07:41 AM
  • Joined: 24 May 2006
IMO, directive should be capable to set paths to both user and std folders.
That is proffesional. Hardcoding folders isn't.

Maybe something like:

#Lib [U "userpath|*None"] [S "stdpath|*None"]

where user path would be able to use env vars.

Examples:

#Lib U "%A_AHKPATH%\Include-User" 
#Lib S "%USERPROFILE%\My Documents\AHKStdLib"
#Lib U "%A_AHKPATH%\Include-User"  S "%USERPROFILE%\My Documents\AHKStdLib"
#Lib U "*None" S "*None"

Posted Image

PhiLho
  • Moderators
  • 6850 posts
  • Last active: Jan 02 2012 10:09 PM
  • Joined: 27 Dec 2005
I admit I had not the time or courage to read the full discussion, sorry for that.
So I might have missed some evolution of the proposal.

But I don't like the idea of "one function per file". I won't see myself writing a dozen of files for my partial GDI+ wrapper, and it doesn't make sense as some functions might depend on others, public or private, they share the same set of constants, and so on. How conflicts or redundancy will be managed, then?

Why not say functions of a same library/package share the same prefix, which can be used as file name?
For example:
GDIplus#Start()
GDIplus#Stop()
GDIplus#LoadBitmap()
and so on. All these functions will go in the GDIplus.ahk file.

Or we do like most other languages, with a set of package dependency declarations, but I suppose this has been already discussed and rejected...
Posted Image vPhiLho := RegExReplace("Philippe Lhoste", "^(\w{3})\w*\s+\b(\w{3})\w*$", "$1$2")

toralf
  • Moderators
  • 4035 posts
  • Last active: Aug 20 2014 04:23 PM
  • Joined: 31 Jan 2005

IMO, directive should be capable to set paths to both user and std folders.
That is proffesional. Hardcoding folders isn't.

Maybe something like:

#Lib [U "userpath"|*None] [S "stdpath"|*None]

where user path would be able to use env vars.


For private use it might help, but it reduces portability/sharing.

For the directive with paths (if needed), I suggest a comma separated list of options like all other AHK commands use. First option is stdlib path, second is userlib path.
Ciao
toralf
 
I use the latest AHK version (1.1.15+)
Please ask questions in forum on ahkscript.org. Why?
For online reference please use these Docs.

majkinetor
  • Moderators
  • 4512 posts
  • Last active: May 20 2019 07:41 AM
  • Joined: 24 May 2006

But I don't like the idea of "one function per file".

We don't like it too (except corrupt), but it is trivial to implement and fastest around.

But we can have both worlds if we just addopt classes like I proposed (the same as you suggested)

For private use it might help, but it reduces portability/sharing.

Not with good defaults. This acctually if done correctly, extends portability.
Posted Image

toralf
  • Moderators
  • 4035 posts
  • Last active: Aug 20 2014 04:23 PM
  • Joined: 31 Jan 2005

Why not say functions of a same library/package share the same prefix, which can be used as file name?
For example:
GDIplus#Start()
GDIplus#Stop()
GDIplus#LoadBitmap()
and so on. All these functions will go in the GDIplus.ahk file.

That is what majkinetor calls a modul. And that is what we discussed. But we use "_" instead of "#". But we think it would need a init function GDIplus(), so that the GDIplus.ahk file gets included.
Ciao
toralf
 
I use the latest AHK version (1.1.15+)
Please ask questions in forum on ahkscript.org. Why?
For online reference please use these Docs.

majkinetor
  • Moderators
  • 4512 posts
  • Last active: May 20 2019 07:41 AM
  • Joined: 24 May 2006
No, it needs init function only if you like to include modules the same as SSF (i.e. using 1-1 principle)

If AHK searches for Module.ahk if it doesn't find Module_XXX.ahk, then we don't need init function. I don't like init functions anyway.

2PhiLho
See this post and this post
Posted Image

toralf
  • Moderators
  • 4035 posts
  • Last active: Aug 20 2014 04:23 PM
  • Joined: 31 Jan 2005
Using a "#" or "@" for modul/class functions would remove the requirement to not name a new lib function SSFName_Function. But it would just add a new requirement just with the new symbols. But I like the "@" since it reflects the dependency to a modul/class.
Ciao
toralf
 
I use the latest AHK version (1.1.15+)
Please ask questions in forum on ahkscript.org. Why?
For online reference please use these Docs.