[Function] BLStack v0.1 - Batch Lines Stack

[jballi]

Introduction
If use the SetBatchLines command more than once in a script, the BLStack function may help to keep track of the current SetBatchLines settings.

Synopsis
BLStack is a simple stack manager for the current SetBatchLines settings. It is useful if a script temporarily changes the SetBatchLines settings to do certain things. The "stack" feature is useful if a routine (subroutine, function, etc.) that uses the BLStack function calls another routine that also uses the BLStack function.

The Code

Code: Select all

;------------------------------
;
; Function: BLStack (aka "BatchLines stack")
;
; Description:
;
;   This function manages a last-in-first-out (LIFO) stack for the system
;   A_BatchLines variable.
;
; Parameters:
;
;   p_Command - Valid commands include the following:
;
;       (start code)
;       Command     Description
;       -------     -----------
;       Pop         Calls SetBatchLines using the value from the top item in
;                   stack or "10ms" if the stack is empty.  If it exists, the
;                   top item in the stack is removed.
;
;       Push        Add the current value of A_BatchLines to the top of stack.
;       (end)
;
;   p_Option - Optional SetBatchLines parameter.  If set and p_Command is
;       "Push", *SetBatchLines* is called using this value as the parameter.
;       See the *Remarks* section for more information.  If p_Command is "Pop",
;       this parameter is ignored.
;
; Returns:
;
;   If p_Command is "Pop", the top item from the stack (or "10ms" if the stack
;   is empty) is returned.  Since the "Pop" command calls the *SetBatchLines*
;   command, this information is also contained in the A_BatchLines system
;   variable.
;
; Remarks:
;
;   Use of the p_Option parameter can be a little confusing because when used
;   with the "Push" command, Ex: BLStack("Push","50ms"), it appears that the
;   request is push the "50ms" value to the stack, when in fact the current
;   batchlines value is pushed to the stack and then *SetBatchLines* is set to
;   the p_Option value.  To assist in the problem, only the first 4 characters
;   of a command that begins with "Push" are checked so additional words can be
;   added to reduce the confusion.  Ex: BLStack("PushAndSet","50ms").
;
; Example Of Use:
;
;   (start code)
;   SetBatchLines 15ms      ;-- Default priority level for this script
;   gosub DoStuff
;   gosub DoOtherStuff
;   return
;
;   DoStuff:                ;-- Subroutine that needs a bit more CPU priority
;   BLStack("Push")         ;-- Saves the current BatchLines speed
;   SetBatchLines 50ms      ;-- Priority bump
;
;   ;--
;   ;-- Code that needs higher priority goes here
;   ;--
;
;   ;-- End of subroutine. Reset back to previous level
;   BLStack("Pop")
;   return
;   (end)
;
;-------------------------------------------------------------------------------
BLStack(p_Command,p_Option="")
    {
    Static s_Stack
    StringUpper p_Command,p_Command,T  ;-- Just in case StringCaseSense is "On"
    if (SubStr(p_Command,1,4)="Push")
        {
        if not StrLen(s_Stack)
            s_Stack:=A_BatchLines
         else
            ;-- Prepend to the top of the list
            s_Stack:=A_BatchLines . "|" . s_Stack

        ;-- Request to set?
        if StrLen(p_Option)
            SetBatchLines %p_Option%

        Return
        }

    if (p_Command="Pop")
        {
        ;-- Empty stack?
        if not StrLen(s_Stack)
            l_BatchLines:="10ms"
         else
            {
            ;-- Determine the first delimiter position
            if l_DelimiterPos:=InStr(s_Stack,"|")
                {
                ;-- Pop the top item
                l_BatchLines:=SubStr(s_Stack,1,l_DelimiterPos-1)
                StringTrimLeft s_Stack,s_Stack,l_DelimiterPos
                }
             else ;-- Only one item in the stack
                {
                l_BatchLines:=s_Stack
                s_Stack:=""
                }
            }

        SetBatchLines %l_BatchLines%            
        Return l_BatchLines
        }
    }

Example Of Use
A similar example is included in the script documentation.

Code: Select all

SetBatchLines 15ms      ;-- Default priority level for this script
gosub DeleteStuff
return

DeleteStuff:            ;-- Subroutine that needs a bit more CPU priority
BLStack("Push","50ms")  ;-- Saves the current BatchLines speed and then sets to 50ms.

;--
;-- Code that needs higher priority goes here
;--

;-- End of subroutine. Reset back to previous level (15ms in this case)
BLStack("Pop")
return

Final Thoughts
This function has very little value for most small/simple scripts but can be useful for large interactive scripts that have multiple bottleneck points. I hope that someone finds this useful.
---------------------------------------------------------------------------
Release Notes

v0.1
Orginal release.

[joedf]

interesting concept