codemp/dist/lua/annotations.lua

415 lines
13 KiB
Lua
Raw Normal View History

2024-08-22 20:21:43 +02:00
---@meta annotations
-- type annotations for codemp native lua library
-- [[ ASYNC STUFF ]]
-- TODO lua-language-server doesn't seem to support generic classes
-- https://github.com/LuaLS/lua-language-server/issues/1532
-- so we need to expand every possible promise type...
2024-08-27 23:05:17 +02:00
--
-- do you have a better idea? send a PR our way!
2024-08-22 20:21:43 +02:00
2024-08-27 23:05:17 +02:00
---@class (exact) Promise
2024-08-22 20:21:43 +02:00
---@field ready boolean true if promise completed
2024-08-27 23:05:17 +02:00
---@class (exact) NilPromise : Promise
local NilPromise = {}
--- block until promise is ready
function NilPromise:await() end
---@param cb fun() callback to invoke
---invoke callback asynchronously as soon as promise is ready
function NilPromise:and_then(cb) end
2024-08-22 20:21:43 +02:00
2024-08-27 23:05:17 +02:00
---@class (exact) StringPromise : Promise
local StringPromise = {}
--- block until promise is ready and return value
--- @return string
function StringPromise:await() end
---@param cb fun(x: string) callback to invoke
---invoke callback asynchronously as soon as promise is ready
function StringPromise:and_then(cb) end
2024-08-27 23:05:17 +02:00
---@class (exact) StringArrayPromise : Promise
local StringArrayPromise = {}
--- block until promise is ready and return value
--- @return string[]
function StringArrayPromise:await() end
---@param cb fun(x: string[]) callback to invoke
---invoke callback asynchronously as soon as promise is ready
function StringArrayPromise:and_then(cb) end
2024-08-22 20:21:43 +02:00
2024-08-27 23:05:17 +02:00
---@class (exact) ClientPromise : Promise
local ClientPromise = {}
--- block until promise is ready and return value
--- @return Client
function ClientPromise:await() end
---@param cb fun(x: Client) callback to invoke
---invoke callback asynchronously as soon as promise is ready
function ClientPromise:and_then(cb) end
2024-08-22 20:21:43 +02:00
2024-08-27 23:05:17 +02:00
---@class (exact) WorkspacePromise : Promise
local WorkspacePromise = {}
--- block until promise is ready and return value
--- @return Workspace
function WorkspacePromise:await() end
---@param cb fun(x: Workspace) callback to invoke
---invoke callback asynchronously as soon as promise is ready
function WorkspacePromise:and_then(cb) end
2024-08-22 20:21:43 +02:00
2024-08-27 23:05:17 +02:00
---@class (exact) WorkspaceEventPromise : Promise
local WorkspaceEventPromise = {}
--- block until promise is ready and return value
--- @return WorkspaceEvent
function WorkspaceEventPromise:await() end
---@param cb fun(x: WorkspaceEvent) callback to invoke
---invoke callback asynchronously as soon as promise is ready
function WorkspaceEventPromise:and_then(cb) end
2024-08-22 20:21:43 +02:00
2024-08-27 23:05:17 +02:00
---@class (exact) BufferControllerPromise : Promise
local BufferControllerPromise = {}
--- block until promise is ready and return value
--- @return BufferController
function BufferControllerPromise:await() end
---@param cb fun(x: BufferController) callback to invoke
---invoke callback asynchronously as soon as promise is ready
function BufferControllerPromise:and_then(cb) end
2024-08-22 20:21:43 +02:00
2024-08-27 23:05:17 +02:00
---@class (exact) CursorPromise : Promise
local CursorPromise = {}
--- block until promise is ready and return value
--- @return Cursor
function CursorPromise:await() end
---@param cb fun(x: Cursor) callback to invoke
---invoke callback asynchronously as soon as promise is ready
function CursorPromise:and_then(cb) end
2024-08-22 20:21:43 +02:00
2024-08-27 23:05:17 +02:00
---@class (exact) MaybeCursorPromise : Promise
local MaybeCursorPromise = {}
--- block until promise is ready and return value
--- @return Cursor | nil
function MaybeCursorPromise:await() end
---@param cb fun(x: Cursor | nil) callback to invoke
---invoke callback asynchronously as soon as promise is ready
function MaybeCursorPromise:and_then(cb) end
2024-08-22 20:21:43 +02:00
2024-08-27 23:05:17 +02:00
---@class (exact) TextChangePromise : Promise
local TextChangePromise = {}
--- block until promise is ready and return value
--- @return TextChange
function TextChangePromise:await() end
---@param cb fun(x: TextChange) callback to invoke
---invoke callback asynchronously as soon as promise is ready
function TextChangePromise:and_then(cb) end
2024-08-22 20:21:43 +02:00
2024-08-27 23:05:17 +02:00
---@class (exact) MaybeTextChangePromise : Promise
local MaybeTextChangePromise = {}
--- block until promise is ready and return value
--- @return TextChange | nil
function MaybeTextChangePromise:await() end
---@param cb fun(x: TextChange | nil) callback to invoke
---invoke callback asynchronously as soon as promise is ready
function MaybeTextChangePromise:and_then(cb) end
2024-08-22 20:21:43 +02:00
-- [[ END ASYNC STUFF ]]
2024-08-27 23:05:17 +02:00
---@class (exact) Client
2024-08-22 20:21:43 +02:00
---@field id string uuid of local user
---@field username string name of local user
---@field active_workspaces string[] array of all currently active workspace names
---the effective local client, handling connecting to codemp server
local Client = {}
---@return NilPromise
---@async
---@nodiscard
---refresh current user token if possible
function Client:refresh() end
---@param ws string workspace id to connect to
---@return WorkspacePromise
---@async
---@nodiscard
---join requested workspace if possible and subscribe to event bus
function Client:join_workspace(ws) end
---@param ws string workspace id to create
---@return NilPromise
---@async
---@nodiscard
---create a new workspace with given id
2024-08-27 23:05:17 +02:00
function Client:create_workspace(ws) end
2024-08-22 20:21:43 +02:00
---@param ws string workspace id to leave
---leave workspace with given id, detaching and disconnecting
function Client:leave_workspace(ws) end
---@param ws string workspace id to delete
---@return NilPromise
---@async
---@nodiscard
---delete workspace with given id
function Client:delete_workspace(ws) end
---@param ws string workspace id to delete
---@param user string user name to invite to given workspace
---@return NilPromise
---@async
---@nodiscard
---grant user acccess to workspace
function Client:invite_to_workspace(ws, user) end
---@param owned boolean? list owned workspaces, default true
---@param invited boolean? list invited workspaces, default true
---@return StringArrayPromise
---@async
---@nodiscard
---grant user acccess to workspace
function Client:list_workspaces(owned, invited) end
---@param ws string workspace id to get
---@return Workspace?
---get an active workspace by name
function Client:get_workspace(ws) end
2024-08-27 23:05:17 +02:00
---@class (exact) Workspace
2024-08-22 20:21:43 +02:00
---@field name string workspace name
---@field cursor CursorController workspace cursor controller
---@field active_buffers string[] array of all currently active buffer names
---a joined codemp workspace
local Workspace = {}
---@param path string relative path ("name") of new buffer
---@return NilPromise
---@async
---@nodiscard
---create a new empty buffer
function Workspace:create(path) end
2024-08-22 20:21:43 +02:00
---@param path string relative path ("name") of buffer to delete
---@return NilPromise
---@async
---@nodiscard
---delete buffer from workspace
function Workspace:delete(path) end
2024-08-22 20:21:43 +02:00
---@param path string relative path ("name") of buffer to get
---@return BufferController?
---get an active buffer controller by name
function Workspace:get_buffer(path) end
---@param path string relative path ("name") of buffer to attach to
---@return BufferControllerPromise
---@async
---@nodiscard
---attach to a remote buffer, synching content and changes and returning its controller
function Workspace:attach(path) end
2024-08-22 20:21:43 +02:00
---@param path string relative path ("name") of buffer to detach from
---@return boolean
---detach from an active buffer, closing all streams. returns false if buffer was no longer active
function Workspace:detach(path) end
2024-08-22 20:21:43 +02:00
2024-09-13 21:24:12 +02:00
---@param filter? string apply a filter to the return elements
---@param strict? boolean whether to strictly match or just check whether it starts with it
2024-08-22 20:21:43 +02:00
---@return string[]
---return the list of available buffers in this workspace, as relative paths from workspace root
2024-09-13 21:24:12 +02:00
function Workspace:filetree(filter, strict) end
2024-08-22 20:21:43 +02:00
---@return NilPromise
---@async
---@nodiscard
---force refresh buffer list from workspace
function Workspace:fetch_buffers(path) end
---@return NilPromise
---@async
---@nodiscard
---force refresh users list from workspace
function Workspace:fetch_users(path) end
2024-08-27 23:05:17 +02:00
---@class (exact) WorkspaceEvent
2024-08-22 20:21:43 +02:00
---@field type string
---@field value string
---@return WorkspaceEventPromise
---@async
---@nodiscard
---get next workspace event
function Workspace:event() end
2024-08-27 23:05:17 +02:00
---@class (exact) BufferController
2024-08-22 20:21:43 +02:00
---handle to a remote buffer, for async send/recv operations
local BufferController = {}
2024-09-11 15:50:19 +02:00
---@class TextChange
2024-08-22 20:21:43 +02:00
---@field content string text content of change
---@field start integer start index of change
---@field finish integer end index of change
2024-08-22 20:21:43 +02:00
---@field hash integer? optional hash of text buffer after this change, for sync checks
local TextChange = {}
---@param other string text to apply change to
---apply this text change to a string, returning the result
function TextChange:apply(other) end
2024-08-22 20:21:43 +02:00
2024-09-11 15:50:19 +02:00
---@param change TextChange text change to broadcast
2024-08-22 20:21:43 +02:00
---@return NilPromise
---@async
---@nodiscard
---update buffer with a text change; note that to delete content should be empty but not span, while to insert span should be empty but not content (can insert and delete at the same time)
2024-09-11 15:50:19 +02:00
function BufferController:send(change) end
2024-08-22 20:21:43 +02:00
---@return MaybeTextChangePromise
---@async
---@nodiscard
---try to receive text changes, returning nil if none is available
function BufferController:try_recv() end
---@return TextChangePromise
---@async
---@nodiscard
---block until next text change and return it
function BufferController:recv() end
---@return NilPromise
---@async
---@nodiscard
---block until next text change without returning it
function BufferController:poll() end
---@return boolean
---stop buffer worker and disconnect, returns false if was already stopped
function BufferController:stop() end
---clears any previously registered buffer callback
function BufferController:clear_callback() end
---@param cb fun(c: BufferController) callback to invoke on each text change from server
---register a new callback to be called on remote text changes (replaces any previously registered one)
function BufferController:callback(cb) end
2024-08-27 23:05:17 +02:00
---@return StringPromise
---@async
---@nodiscard
---get current content of buffer controller, marking all pending changes as seen
function BufferController:content() end
2024-08-22 20:21:43 +02:00
2024-08-27 23:05:17 +02:00
---@class (exact) CursorController
2024-08-22 20:21:43 +02:00
---handle to a workspace's cursor channel, allowing send/recv operations
local CursorController = {}
2024-09-11 15:50:19 +02:00
---@class Cursor
2024-08-22 20:21:43 +02:00
---@field user string? id of user owning this cursor
---@field buffer string relative path ("name") of buffer on which this cursor is
---@field start [integer, integer] cursor start position
---@field finish [integer, integer] cursor end position
2024-08-22 20:21:43 +02:00
---a cursor position
2024-09-11 15:50:19 +02:00
---@param cursor Cursor cursor event to broadcast
2024-08-22 20:21:43 +02:00
---@return NilPromise
---@async
---@nodiscard
---update cursor position by sending a cursor event to server
2024-09-11 15:50:19 +02:00
function CursorController:send(cursor) end
2024-08-22 20:21:43 +02:00
---@return MaybeCursorPromise
---@async
---@nodiscard
---try to receive cursor events, returning nil if none is available
function CursorController:try_recv() end
---@return CursorPromise
---@async
---@nodiscard
---block until next cursor event and return it
function CursorController:recv() end
---@return NilPromise
---@async
---@nodiscard
---block until next cursor event without returning it
function CursorController:poll() end
---@return boolean
---stop cursor worker and disconnect, returns false if was already stopped
function CursorController:stop() end
---clears any previously registered cursor callback
function CursorController:clear_callback() end
---@param cb fun(c: CursorController) callback to invoke on each cursor event from server
---register a new callback to be called on cursor events (replaces any previously registered one)
function CursorController:callback(cb) end
2024-09-11 15:50:19 +02:00
---@class Config
---@field username string user identifier used to register, possibly your email
---@field password string user password chosen upon registration
---@field host string | nil address of server to connect to, default api.code.mp
---@field port integer | nil port to connect to, default 50053
---@field tls boolean | nil enable or disable tls, default true
---@class Codemp
2024-08-22 20:21:43 +02:00
---the codemp shared library
local Codemp = {}
2024-09-11 15:50:19 +02:00
---@param config Config configuration for
2024-08-22 20:21:43 +02:00
---@return ClientPromise
---@async
---@nodiscard
---connect to codemp server, authenticate and return client
2024-09-11 15:50:19 +02:00
function Codemp.connect(config) end
2024-08-22 20:21:43 +02:00
2024-09-17 14:33:14 +02:00
---@return function, any | nil
---@nodiscard
---check if codemp thread sent a callback to be run on main thread
function Codemp.poll_callback() end
2024-08-22 20:21:43 +02:00
---@param data string
---@return integer
---use xxh3 hash, returns an i64 from any string
function Codemp.hash(data) end
2024-08-27 23:05:17 +02:00
---@class (exact) RuntimeDriver
local RuntimeDriver = {}
---@return boolean
---stops the runtime thread, returns false if driver was already stopped
function RuntimeDriver:stop() end
2024-08-22 20:21:43 +02:00
---@return RuntimeDriver
---spawns a background thread and uses it to run the codemp runtime
function Codemp.spawn_runtime_driver() end
---@param printer? string | fun(string) | nil log sink used for printing, if string will go to file, otherwise use given function
---@param debug? boolean show more verbose debug logs, default false
2024-08-22 20:21:43 +02:00
---@return boolean true if logger was setup correctly, false otherwise
---setup a global logger for codemp, note that can only be done once
function Codemp.logger(printer, debug) end