feat!: portal extension support

[cbochs]

Context

Up until now, Portal relied on builtin integrations (i.e jumplist, quickfix). This is inflexible and doesn't allow external plugins to leverage Portal's API. This PR adds support for users to build their own extensions.

Breaking Changes

Note: those who are not using the Portal API directly, but instead are simply using the builtins that Portal provides should likely not experience any breakages.

• Rename max_results as limit in the search options
• Remove settings.max_results
• Remove settings.escape table. Make this simple and quit on q, <esc>, and <c-c>. Might consider adding back`
• Queries are now a first-class citizen. They have also been changed from a table of source and slots. Instead, queries are constructed with a generating function which returns an iterable. For example,

local function generator()
    return { 1, 2, 3, 4 }
end

require("portal.query").new(generator)
    :prepare({ reverse = true, limit = 2 })
    :search()  -- returns an iterator
    :totable() -- collect() has been renamed to totable()
-- Returns { 4, 3 }

• Portal's public API has slightly changed:

Before: Portal.tunnel(q: Portal.Query[], o?: Portal.Settings)
After:  Portal.tunnel(q: Portal.Query[], o?: Portal.Options)

Before: Portal.search(q: Portal.Query[])
After:  Portal.search(q: Portal.Query[], o?: Portal.SearchOptions)

Before: Portal.portals(c: Portal.Content[], o?: Portal.Settings)
After: Portal.portals(c: Portal.Content[], labels: string[], win_opts?: vim.api.keyset.win_config)

Where:

---@class Portal.Options
---@field labels? string[]
---@field select_first? boolean
---@field win_opts? vim.api.keyset.win_config
---@field search? Portal.SearchOptions

---@class Portal.SearchOptions: Portal.QueryOptions
---@field slots? Portal.Predicate | Portal.Predicate[]

---@class Portal.QueryOptions
---@field start? integer the absolute starting position
---@field skip? integer
---@field reverse? boolean
---@field lookback? integer maximum number of searched items
---@field limit? integer maximum number of returned results
---@field filter? Portal.Predicate

Changes

• Delete Portal's logger, it's not useful
• Replace Portal's iterator with a drop-in replacement for the upcoming vim.iter
• Add Portal.Query to bridge the gap between generating and searching lists
• Demote Portal.Content to a simple object, it doesn't need to be more than that
• Add Portal.Extension: make it easy for users to extend Portal
• General refactoring and cleanup

Todo

• Refactor changelist builtin
• Refactor harpoon builtin (and adapt for harpoon2)
• Verify jumplist builtin works the same
• Verify grapple builtin works the same (this will later be moved to the grapple repo)
• Write up breaking changes
• Update builtin documentation
• Update Portal API documentation
• Update (remove?) "iterator" documentation
• Document extension examples
• Fix recursion bug (portal bug? builtin bug?) edit: it was a grapple bug
• bug: builtin queries aren't prepared with any options during Builtin.tunnel
• bug: reverse start position doesn't work well with lists like grapple
• Document "what is a query?"