shuffledQueues.lua

-- here's a shuffled queues library ig?
-- written by rixithechao on 1/4/2024
-- v0.1.0



-- QUEUE CLASS
local Queue = {}

Queue = {

    -- METHODS
    -- Returns true if there's no items left in the queue
    isEmpty = function(self)
        return (#self.remaining == 0)
    end,

    -- Refills the queue and shuffles it
    --    runEvent:         bool (default false)    if true and an onRefill event is defined for the cue, run that function
    refill = function(self, runEvent)
        self.remaining = table.ishuffle(table.iclone(self.itemSet))
        if  self.onRefill ~= nil  and  runEvent == true  then
            self:onRefill()
        end
    end,

    -- Gets the next item from the queue and removes it
    --    avoidRepeats:     bool (default false)    attempt to avoid selecting a repeated item
    --    maxAttempts:      int (default 10)        the max number of attempts to try picking a unique item
    popNext = function(self, avoidRepeats, maxAttempts)
        local pick = nil
        local i = 0
        maxAttempts = maxAttempts  or  10

        while  (pick == nil  or  (pick == self.previous  and  avoidRepeats  and  i < maxAttempts))  do

            -- Reset the queue
            if  self:isEmpty()  then
                self:refill(true)
            end

            -- Pick the attack
            pick = self.remaining[1]

            -- Increment the attempts count
            i = i+1

            -- If it's a repeat and there's attempts left
            if  i < maxAttempts  then
                if  pick == self.previous  and  avoidRepeats  then
                    if  #self.remaining > 1  then
                        self.remaining[#self.remaining+1] = pick
                    end
                    table.remove(self.remaining, 1)
                end

            -- Otherwise, give up and go with the repeat
            else
                --Misc.dialog("QUEUE FAILED AVOIDING A REPEAT AFTER "..tostring(maxAttempts).." ATTEMPTS.\nThis warning only appears when playtesting from the editor.", "\n\nFINAL PICK", pick, "\nREMAINING:", self.remaining, "\nITEM SET:", self.itemSet)
            end
        end

        if  not self:isEmpty()  then
            table.remove(self.remaining, 1)
        end

        self.previous = pick
        return pick
    end,

    -- Adds an item to the end of the queue
    push = function(self, item)
        self.remaining[#self.remaining+1] = item
    end,

    -- Adds an item to the specified position in the queue (wrapper for lua's table.insert)
    insert = function(self, ...)
        table.insert(self.remaining, ...)
    end,

    -- Refills the queue if it's empty, then gets the next item without removing it
    getNext = function(self, shouldRefill)
        if  self:isEmpty()  then
            self:refill(true)
        end
        return self.remaining[1]
    end,

    -- Refills the queue if it's empty, then gets the item at the end of the queue without removing it
    getEnd = function(self)
        if  self:isEmpty()  then
            self:refill(true)
        end
        return self.remaining[#self.remaining]
    end,
}
Queue.pop = Queue.popNext

local _classreadonly = {isEmpty=true, refill=true, popNext=true, pop=true, push=true, insert=true, getNext=true, getEnd=true}



-- QUEUE CLASS METATABLE
local QueueMT = {
    __index = function(obj,key)

        -- If it exists in the base structure, use that.
        if  Queue[key] ~= nil  then
            return Queue[key]

        -- Otherwise, get the member function/property.
        else
            return rawget(obj,key)
        end
    end,

    __newindex = function(obj,key,val)

        if  Queue[key] ~= nil  then
            if  _classreadonly[key] ~= nil  then
                error(key.." is a read-only property of the Queue class")
            else
                Queue[key] = val
            end

        elseif  _classreadonly[key] ~= nil  then
            error(key.." is a read-only property of the Queue object")
        else
            rawset(obj, key, val)
        end
    end
}


-- THE LIBRARY TABLE ITSELF
local shuffledqueues = {

    -- Create a new queue and return the object reference
    new = function(args)
        local tbl = {
            itemSet = args.items,
            remaining = (args.remaining or {}),
            previous = nil,
            onRefill = args.onRefill
        }
        setmetatable(tbl, QueueMT)

        return tbl
    end
}


return shuffledqueues