Best way to create an "Alias" function?

[water]

As described here I would like to create some "alias" functions all "pointing" to the same function.
The following code seems to work perfectly.

Can you think of a situation where this approach might fail?

#include <Array.au3>
Global $a = "a", $b = "b", $c = ["c"]
$RV = F_Original($a, $b, $c)
ConsoleWrite("Original: Returnvalue = " & $RV & ", $a = " & $a & ", $b = " & $b & ", @error = " & @error & ", @extended = " & @extended & @CRLF)
_ArrayDisplay($c)
$RV = F_Alias($a, $b, $c)
ConsoleWrite("Alias   : Returnvalue = " & $RV & ", $a = " & $a & ", $b = " & $b & ", @error = " & @error & ", @extended = " & @extended & @CRLF)
_ArrayDisplay($c)
$RV = F_Alias($a, $b, $c)

Func F_Original($p1, ByRef $p2, ByRef $p3, $p4 = Default)
    $p1 = "aa"
    $p2 = "bb"
    $p3[0] = "cc"
    If $p4 = Default Then $p4 = "DEFAULT-VALUE"
    Return SetError(1, 2, $p4)
EndFunc   ;==>F_Original

Func F_Alias($p1, ByRef $p2, ByRef $p3, $p4 = Default)
    $vReturnValue = F_Original($p1, $p2, $p3, $p4)
    Return SetError(@error, @extended, $vReturnValue)
EndFunc   ;==>F_Alias

 

[BrewManNH]

You could make the main function a "helper" function like what is done in the Array UDF, see the function _ArrayMaxIndex as an example. There's an internal helper function called __Array_MinMaxIndex that is used to get the index of the item with the min/max value in the array. One function that can be used for 2 different functions. The internal function isn't described in the help file, just the functions that use it. This way you don't need to let the user's know about the internal function(s), just the external functions that you want to give them to use.

[water]

At the moment I have a single function named _AD_AddUserToGroup. I would like to add _AD_AddComputerToGroup and _AD_AddGroupToGroup. This 2 functions will call _AD_AddUserToGroup. So at the end I have 3 "main" functions which should all be visible to the user. I just don't want to have 3 identical functions with different names.

I manually have to make sure that the parameters of the 2 additional functions are identical to _AD_AddUserToGroup and that the values returned by _AD_AddUserToGroup are returned to the caller of _AD_AddComputerToGroup and _AD_AddGroupToGroup.

I have tested variables, arrays, optional parameters, ByRef parameters, @error and @extended and the ordinary return value.
The "alias" function always return the expected result.

But maybe I missed something?

[Nine]

Looks good to me.  I cannot think of a situation where it would fail, as long as you define parameters of all your function identically. 

[pixelsearch]

I like BrewManNH's approach.
And this has been done many times in Autoit, another example are 2 functions _ArrayDisplay() and _DebugArrayDisplay()

When you look at the help file, you may think that these 2 functions are very big... but they're not, because they are just "callers" to a huge 3rd function, which is named  __ArrayDisplay_Share() and is called by both of them.

1)  _ArrayDisplay() in Array.au3 :

; #FUNCTION# ================================================================================
; Author ........: randallc, Ultima
; Modified.......: Gary Frost (gafrost), Ultima, Zedna, jpm, Melba23, AZJIO, UEZ
; ===========================================================================================
Func _ArrayDisplay(Const ByRef $aArray, $sTitle = Default, $sArrayRange = Default, $iFlags = Default, $vUser_Separator = Default, $sHeader = Default, $iMax_ColWidth = Default)
    #forceref $vUser_Separator
    Local $iRet = __ArrayDisplay_Share($aArray, $sTitle, $sArrayRange, $iFlags, Default, $sHeader, $iMax_ColWidth, 0, False)
    Return SetError(@error, @extended, $iRet)
EndFunc   ;==>_ArrayDisplay

2) _DebugArrayDisplay() in Debug.au3 :

; #FUNCTION# ================================================================================
; Author ........: Melba23
; Modified.......: jpm
; ===========================================================================================
Func _DebugArrayDisplay(Const ByRef $aArray, $sTitle = Default, $sArrayRange = Default, $iFlags = Default, $vUser_Separator = Default, $sHeader = Default, $iMax_ColWidth = Default, $hUser_Function = Default)
    Local $iRet = __ArrayDisplay_Share($aArray, $sTitle, $sArrayRange, $iFlags, $vUser_Separator, $sHeader, $iMax_ColWidth, $hUser_Function, True)
    Return SetError(@error, @extended, $iRet)
EndFunc   ;==>_DebugArrayDisplay

3) __ArrayDisplay_Share() in ArrayDisplayInternals.au3 :

Func __ArrayDisplay_Share(Const ByRef $aArray, $sTitle = Default, $sArrayRange = Default, $iFlags = Default, $vUser_Separator = Default, $sHeader = Default, $iMax_ColWidth = Default, $hUser_Function = Default, $bDebug = True)
    Local $vTmp, $sMsgBoxTitle = (($bDebug) ? ("DebugArray") : ("ArrayDisplay"))

    ; Default values
    If $sTitle = Default Then $sTitle = $sMsgBoxTitle
    ...
    ; +++ hundred of lines of code here +++
    ...
EndFunc   ;==>__ArrayDisplay_Share

There's no need to paste the whole code of __ArrayDisplay_Share() here because it's much too big, but one could have a look (*) at the 3 functions to see how parameters (mandatories or optionals) are sent between them and how returns & errors are managed.

(*) Before doing this (opening include files to study them), please consider to set them all as read-only so no harm can be done.

We already can notice that the 9th parameter ($bDebug = True) found in __ArrayDisplay_Share() allows to know which of the 2 functions called __ArrayDisplay_Share() , allowing specific portions of code to be applied, and it starts at the very 1st line with a test based on $bDebug :

Local $sMsgBoxTitle = (($bDebug) ? ("DebugArray") : ("ArrayDisplay"))
If $sTitle = Default Then $sTitle = $sMsgBoxTitle

if this approach suits you, you could do same with 3 "small" functions named :
_AD_AddUserToGroup()
_AD_AddComputerToGroup()
_AD_AddGroupToGroup()

The 3 of them calling a same internal "big" function which could be named __AD_ToGroup()

Now if this approach doesn't suit you (or if it's too late to backward) then you probably will keep the "big" function you already wrote, _AD_AddUserToGroup() + 2 smaller functions calling it : _AD_AddComputerToGroup() and _AD_AddGroupToGroup()

So in the end, depending on your choice, it will be 1+3... or 1+2

Edited October 23, 2019 by pixelsearch

[water]

Thanks for the comprehensive explanation 👍🏻
I think I will stick with the 1+2 solution as this is less effort to implement and maintain.

BTW: I think i found a bug in _ArrayDisplay. The separator parameter isn't used but Default is being passed to the worker function.

Func _ArrayDisplay(Const ByRef $aArray, $sTitle = Default, $sArrayRange = Default, $iFlags = Default, $vUser_Separator = Default, $sHeader = Default, $iMax_ColWidth = Default)
    #forceref $vUser_Separator
    Local $iRet = __ArrayDisplay_Share($aArray, $sTitle, $sArrayRange, $iFlags, Default, $sHeader, $iMax_ColWidth, 0, False)
    Return SetError(@error, @extended, $iRet)
EndFunc   ;==>_ArrayDisplay

I think it should be:

Func _ArrayDisplay(Const ByRef $aArray, $sTitle = Default, $sArrayRange = Default, $iFlags = Default, $vUser_Separator = Default, $sHeader = Default, $iMax_ColWidth = Default)
    #forceref $vUser_Separator
    Local $iRet = __ArrayDisplay_Share($aArray, $sTitle, $sArrayRange, $iFlags, $vUser_Separator, $sHeader, $iMax_ColWidth, 0, False)
    Return SetError(@error, @extended, $iRet)
EndFunc   ;==>_ArrayDisplay

 

[RTFC]

I use alias wrappers all the time in my matrix environment (EIgen4AutoIt, link in sig). Your code would fail if your $vReturnValue is declared anywhere else  as a global (in your code, or in anyone else's code that includes yours, i.e., you cannot prevent this from happening). You have to declare it as a local inside the alias wrapper:

Func F_Alias($p1, ByRef $p2, ByRef $p3, $p4 = Default)
    Local $vReturnValue = F_Original($p1, $p2, $p3, $p4)
    Return SetError(@error, @extended, $vReturnValue)
EndFunc   ;==>F_Alias

To clarify, it fails in the sense that it overwrites the user's own contents of $vReturnvalue, if that exists. The alias func itself would work of course.

Edited October 23, 2019 by RTFC

[pixelsearch]

@water : Thanks!

I may be wrong but I think that $vUser_Separator not being passed to the worker, when called from _ArrayDisplay(), isn't an issue because this variable is only useful when the worker has been called from _DebugArrayDisplay() and we can see in my precedent post that it is correctly passed to the worker when the call has been made from _DebugArrayDisplay()

In this case (debug) more buttons are added to the display ($idCopy_ID, $idCopy_Data, to name a few) and the variable $iCW_ColWidth related to $vUser_Separator is only used within the portion of code related to debug in the worker function. Melba23 could confirm this if he reads us.

; Determine copy separator
Local $iCW_ColWidth = Number($vUser_Separator)

Now see how your solution makes sense too, when you wrote :

"I think I will stick with the 1+2 solution as this is less effort to implement and maintain"

Because though I like a lot the solution 1+3 in theory, it may be harder to maintain pratically, compared to the 1+2 solution.

Actually __ArrayDisplay_Share() contains many portions of code related to debug, mixed with portions of code related to the original pure array display, which makes it harder to maintain. I spent some time studying this worker because I use my own version of __ArrayDisplay_Share() with 5 personal tweaks, one of them allowing to display a filtered array on non-contiguous rows (Melba kindly promised me to think about that too)

And when the beta version 3.3.15.1-1 will become a final release, don't be surprised if more parameters will appear (you can already see them if you download the last beta). Here are a few of them, though it's only beta and may change in the future :

Func _ArrayDisplay(Const ByRef $aArray, $sTitle = Default, $sArrayRange = Default, $iFlags = Default, $vUser_Separator = Default, $sHeader = Default, $iMax_ColWidth = Default, $iCallerScriptLineNumber = @ScriptLineNumber, $iCallerError = @error, $iCallerExtended = @extended)

With a couple of new variables and new lines of code, showing the both parts of code based on $bDebug

If $_iCallerError Then
    If $bDebug Then
        ; Call _DebugReport() if available
        If IsDeclared("__g_sReportCallBack_DebugReport_Debug") Then
            $sMsg = "@@ Debug( " & $_iScriptLineNumber & ") : @error = " & _
                $_iCallerError & " in " & $sMsgBoxTitle & "( '" & $sTitle & "' )"
            Execute('$__g_sReportCallBack_DebugReport_Debug("' & $sMsg & '")')
        EndIf
        $iRet = 3
    ElseIf BitAND($iFlags, $ARRAYDISPLAY_CHECKERROR) Then
        $sMsg = "@error = " & $_iCallerError & " when calling the function"
        If $_iScriptLineNumber > 0 Then $sMsg &= " at line " & $_iScriptLineNumber
        $iRet = 3
    EndIf
EndIf

Poor Melba (and I truly mean it) this sure is very difficult for him to maintain all this, plus his personal GUIListViewEx (the "beast" as he names it) among numerous daily tasks. Thumbs up Melba for your endless devotion to AutoIt

Edited October 23, 2019 by pixelsearch

[Nine]

@RTFC Good catch ! 

@water Then the #forceref $vUser_Separator becomes useless...

[water]

7 hours ago, RTFC said:

You have to declare it as a local inside the alias wrapper:

@RTFC Thanks for this! I knew there could be a situation where my code fails.

[water]

8 hours ago, water said:

BTW: I think i found a bug in _ArrayDisplay. The separator parameter isn't used but Default is being passed to the worker function.

I was wrong RTFM would have told me why: "$vUser_Separator - [optional] Deprecated. Kept for script compatibility."

[water]

3 hours ago, Nine said:

@water Then the #forceref $vUser_Separator becomes useless...

Correct

[water]

@All Thanks for your support!

With your help I will be able to enhance my UDFs