PauseUtils

//! zinc
library PauseUtils requires TimerUtils, AutoIndex {
/**
 *      This is just a simple snippet that is meant to prevent units from being unpaused 
 *   prematurely due to the lack of multi-instanceability of the native function.
 *   It also provides the user with responses that are evaluated when a unit is
 *   effectively paused or unpaused as well as pausing units for a specified duration.
 *
 *   It requires the latest version of JassHelper and the AutoIndex and TimerUtils libraries. 
 *   
 *   Credits go to:
 *      1. BBQ for writing the PauseUtils snippet.
 *      2. grim001 for his AutoIndex library.
 *      3. Vexorian for his TimerUtils library, Zinc and JassHelper.
 *      4. All of the contributors to the Jass NewGen Pack.
 *
 *   The functions provided by this snippet are as follows:
 *
 *      - function Pause takes unit whichUnit returns nothing
 *           This is the same as PauseUnit(whichUnit, true), except that it is fully
 *           multi-instanceable. Note that the unit must be indexed in order for this to
 *           be any different than its native counterpart.
 *
 *      - function Unpause takes unit whichUnit returns nothing
 *           This is the same as PauseUnit(whichUnit, false), except that it is fully
 *           multi-instanceable. Note that the unit must be indexed in order for this to
 *           be any different than its native counterpart.
 *      
 *      - function TimedPause takes unit whichUnit, real duration returns nothing
 *           The unit passed to the function will be paused for the specified duration.
 *
 *      - function OnUnitPaused takes response whichResponse returns nothing
 *           The "response" function or static method will be evaluated when a unit is 
 *           effectively paused. Note that it needs to take unit and return nothing. 
 *           The unit it takes is the unit that was paused.
 *      
 *      - function OnUnitUnpaused takes response whichResponse returns nothing
 *           The "response" function or static method will be evaluated when a unit is 
 *           effectively unpaused. Again, it needs to take unit and return nothing. 
 *           The unit it takes is the unit that was unpaused.
 *
 *       Unfortunately, you must abide to a few limitations in order to use this snippet to its fullest.
 *   All your PauseUnit(unit, true) calls should be replaced with Pause(unit),
 *   and all your PauseUnit(unit, false) calls should be replaced with Unpause(unit).
 *   The natives would still work normally but there would be no safety and no responses would be evaluated.      
 */
    type response extends function(unit);

    integer pauseResponses_n = 0, unpauseResponses_n = 0, pauseCounter[];
    response pauseResponses[], unpauseResponses[];
    
    //! textmacro PauseUtils__runEvents takes which
        for (n = 1; n <= $which$Responses_n; n += 1) {   
            $which$Responses[n].evaluate(whichUnit);
        }
    //! endtextmacro
    
    public function OnUnitPaused(response whichResponse) {
        pauseResponses_n += 1;
        pauseResponses[pauseResponses_n] = whichResponse;
    }

    public function OnUnitUnpaused(response whichResponse) {
        unpauseResponses_n += 1;
        unpauseResponses[unpauseResponses_n] = whichResponse;
    }

    public function Pause(unit whichUnit) {
        integer index, n;
        if (IsUnitIndexed(whichUnit)) {
            index = GetUnitId(whichUnit);
            if (pauseCounter[index] == 0) {
                PauseUnit(whichUnit, true);
                //! runtextmacro PauseUtils__runEvents("pause")
            }
            pauseCounter[index] += 1;
        }
        else PauseUnit(whichUnit, true);
    }

    public function Unpause(unit whichUnit) {
        integer index, n;
        if (IsUnitIndexed(whichUnit) && IsUnitPaused(whichUnit)) {
            index = GetUnitId(whichUnit);
            pauseCounter[index] -= 1;
            if (pauseCounter[index] <= 0) {
                PauseUnit(whichUnit, false); 
                pauseCounter[index] = 0;
                //! runtextmacro PauseUtils__runEvents("unpause")
            }
        }
        else PauseUnit(whichUnit, false);
    }

    struct pauseData {
        unit pausedUnit;
    }

    public function TimedPause(unit whichUnit, real duration) {
        pauseData data;
        timer durationTimer;
        if (duration <= 0.0) {
            Pause(whichUnit);
            Unpause(whichUnit);
        }
        else {
            Pause(whichUnit);
            durationTimer = NewTimer();
            data = pauseData.create();
            data.pausedUnit = whichUnit;
            SetTimerData(durationTimer, integer(data));
            TimerStart(durationTimer, duration, false, function() {
                pauseData data = pauseData(GetTimerData(GetExpiredTimer()));
                Unpause(data.pausedUnit);
                data.pausedUnit = null;
                data.destroy();
                ReleaseTimer(GetExpiredTimer());
            });
            durationTimer = null;
        }
    }

    function onInit() {
        OnUnitDeindexed(function(unit leavingUnit) {
            pauseCounter[GetUnitId(leavingUnit)] = 0;
            /* Since AutoIndex recycles its indices, we need to reset the counter as well. */
        });
    }
}
//! endzinc

public function Interrupt(unit whichUnit) {
    if (pauseCounter[GetUnitId(whichUnit)] == 0 && !IsUnitPaused(whichUnit)) {
        PauseUnit(whichUnit, true);
        IssueImmediateOrderById(whichUnit, 851972);
        PauseUnit(whichUnit, false);
    }
}

function AbortOrder takes unit u returns boolean
    if IsUnitPaused(u) then
        return false
    else
        call PauseUnit(u, true)
        call IssueImmediateOrder(u, "stop")
        call PauseUnit(u, false)
    endif
    return true
endfunction