presser.nvim/presser/context_manager/init.lua

local a = vim.api
local g = vim.g

-- @Dev: The following table layout is the structure of contexts stored in the global manager.
--
-- vim.g.presser_buf_ctx = {
--    <ctx> = {
--        <int> {
--            id = <win_id>,
--            what = "Name of window" | id,
--            allowed = true | false,
--        },
--        ...
--    }
-- }
--

-- setup a new global context manager for windows/buffers
g.presser_buf_ctx = g.presser_buf_ctx or {} 

local M = {}

-- @TODO: getters which might be useful
--    + get_win_by_name
--    + get_idx_from_win_id
--    + get_next_allowed_win
--    + get_prev_allowed_win


-- @Description: Create a new context in the global context manager if it doesn't already exist.
-- @Params:
--    + `ctx` ~ A string which represents the name of the new context to be created.
-- @Returns: nil. Updates the global context manager with a new context.
--
-- @Dev: note that this function shouldn't be responsible for multiple contexts existing in the global manager. Whilst
-- it's possible that multiple contexts could exist, it would imply multiple UIs open at once, so unideal.
M.create = function ( ctx )
  local c = g.presser_buf_ctx
  -- create specific context manager if it doesn't exist
  if not c[ctx] then
    c[ctx] = {}
    g.presser_buf_ctx = c
  end
end


-- @Description: Update a context within the global context manager with a new buffer record. If the context doesn't
-- exist, this function will guarantee that it does. If an ID for the window to be recorded in the context manager isn't
-- provided, then this function errors. The table passed to `obj` must contain the key `id` for the function to succeed.
-- The fields are as followed:
--    + `id` ~ A number which is given when a new buffer window is constructed.
--    + `what` ~ A string which gives the ID meaning; a label for the window (not related to buffer).
--    + `allowed` ~ A boolean value which tells the context manager if the cursor is allowed in a window (virtually 
--    disables the buffer).
--
--  `id` is the unique value to the record. Whilst `what` is a guaranteed value, its uniqueness isn't guaranteed in a
--  given context. Since `what` can be used to fetch the associated `id` of the record, it should be unique from other
--  records to prevent conflicts within a context to multiple window IDs.
-- @Params:
--    + `ctx` ~ A string representing the context which the record will be added to in the global context manager.
--    + `obj` ~ A table holding one argument and two optionals.
-- @Returns: bool.
--
-- @Dev: this function should require proper error handling to alert a dev when something really should be guaranteed,
-- such as ID. (bool is fine to return, so perhaps error handling should be considered here for benefits).
M.update = function ( ctx, obj )
  -- ensure that the context exists
--  if not g.presser_buf_ctx[ctx] then
--    M.create( ctx )
--  end
  
  if not obj.id then
    print("[ERROR - context_manager]  cannot allocate window. No ID was provided.")
    return false
  end

  if obj.allowed == nil then
    obj.allowed = true
  end

  -- construct new buffer record for context
  local data = {
    id = obj.id,
    what = obj.what or obj.id,
    allowed = obj.allowed,
  }

  -- read the global context buffer and add new buffer to context
  local c = g.presser_buf_ctx
  table.insert(c[ctx], data)
  
  g.presser_buf_ctx = c
  return true
end


-- @Description: Flush the contents of the global context manager and destroy all associated windows and buffers to a
-- context. Any information stored in the buffers is not saved during this process. Any such buffer contents should be
-- handled before calling to flush.
-- @Params: nil.
-- @Returns: nil. Destroys all windows/buffers and clears the global context manager
--
-- @Dev: This is why it's important to guarantee that the IDs are stored in the context manager. They are required here
-- to close the windows using the vim API calls, and force closing them too.
M.flush = function ()
  for _, ctx_tbl in pairs( g.presser_buf_ctx ) do
    for _, data in pairs( ctx_tbl ) do
      print("Deleting:", _, data.id)
      a.nvim_win_close( data.id, true ) -- buffer contents are irrelevant in this context to save
    end
  end

  g.presser_buf_ctx = {} -- clear the global context manager
end

M.get_global_context_manager = function ()
  return g.presser_buf_ctx
end

return M