diff options
Diffstat (limited to 'doc/reference.md')
| -rw-r--r-- | doc/reference.md | 504 |
1 files changed, 0 insertions, 504 deletions
diff --git a/doc/reference.md b/doc/reference.md deleted file mode 100644 index 23eb306c..00000000 --- a/doc/reference.md +++ /dev/null @@ -1,504 +0,0 @@ -# Mason API reference - -This document contains the API reference for `mason.nvim`'s' public APIs and is a more in-depth complementary to the -documentation available in `:h mason`. -The intended audience of this document are plugin developers and people who want to further customize their own Neovim -configuration. - -_Note that APIs not listed in this document (or `:h mason`) are not considered public, and are subject to unannounced, -breaking, changes. Use at own risk._ - -Please [reach out](https://github.com/williamboman/mason.nvim/discussions/new?category=api-suggestions) if you think -something is missing or if something could be improved! - ---- - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT -RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14][bcp14], -[RFC2119][rfc2119], and [RFC8174][rfc8174] when, and only when, they appear in all capitals, as shown here. - ---- - -[bcp14]: https://tools.ietf.org/html/bcp14 -[rfc2119]: https://tools.ietf.org/html/rfc2119 -[rfc8174]: https://tools.ietf.org/html/rfc8174 - -<!--toc:start--> -- [Architecture diagram](#architecture-diagram) -- [Registry events](#registry-events) -- [`RegistryPackageSpec`](#registrypackagespec) -- [`Package`](#package) - - [`Package.Parse({package_identifier})`](#packageparsepackage_identifier) - - [`Package.Lang`](#packagelang) - - [`Package.Cat`](#packagecat) - - [`Package.License`](#packagelicense) - - [`Package:new({spec})`](#packagenewspec) - - [`Package.spec`](#packagespec) - - [`Package:is_installing()`](#packageis_installing) - - [`Package:install({opts?}, {callback?})`](#packageinstallopts-callback) - - [`Package:uninstall()`](#packageuninstall) - - [`Package:is_installed()`](#packageis_installed) - - [`Package:get_install_path()`](#packageget_install_path) - - [`Package:get_installed_version()`](#packageget_installed_version) - - [`Package:get_latest_version()`](#packageget_latest_version) - - [`Package:is_installable({opts?})`](#packageis_installableopts) -- [`PackageInstallOpts`](#packageinstallopts-1) -- [`InstallContext`](#installcontext) - - [`InstallContext.package`](#installcontextpackage) - - [`InstallContext.handle`](#installcontexthandle) - - [`InstallContext.cwd`](#installcontextcwd) - - [`InstallContext.spawn`](#installcontextspawn) - - [`InstallContext.fs`](#installcontextfs) - - [`InstallContext.requested_version`](#installcontextrequested_version) - - [`InstallContext.stdio_sink`](#installcontextstdio_sink) -- [`ContextualFs`](#contextualfs) -- [`ContextualSpawn`](#contextualspawn) -- [`CwdManager`](#cwdmanager) - - [`CwdManager:set({cwd)})`](#cwdmanagersetcwd) - - [`CwdManager:get()`](#cwdmanagerget) -- [`InstallHandleState`](#installhandlestate) -- [`InstallHandle`](#installhandle) - - [`InstallHandle.package`](#installhandlepackage) - - [`InstallHandle.state`](#installhandlestate) - - [`InstallHandle.is_terminated`](#installhandleis_terminated) - - [`InstallHandle:is_idle()`](#installhandleis_idle) - - [`InstallHandle:is_queued()`](#installhandleis_queued) - - [`InstallHandle:is_active()`](#installhandleis_active) - - [`InstallHandle:is_closed()`](#installhandleis_closed) - - [`InstallHandle:kill({signal})`](#installhandlekillsignal) - - [`InstallHandle:terminate()`](#installhandleterminate) -- [`EventEmitter`](#eventemitter) - - [`EventEmitter:on({event}, {handler})`](#eventemitteronevent-handler) - - [`EventEmitter:once({event, handler})`](#eventemitteronceevent-handler) - - [`EventEmitter:off({event}, {handler})`](#eventemitteroffevent-handler) -<!--toc:end--> - -## Architecture diagram - -<!-- https://excalidraw.com/#json=vbTmp7nM8H5odJDiaw7Ue,TghucvHHAw8bl7sgX1VuvA --> - - - -## Registry events - -The `mason-registry` Lua module extends the [EventEmitter](#eventemitter) interface and emits the following events: - -| Event | Handler signature | -| --------------------------- | ------------------------------------------------------ | -| `package:handle` | `fun(pkg: Package, handle: InstallHandle)` | -| `package:install:success` | `fun(pkg: Package, handle: InstallHandle)` | -| `package:install:failed` | `fun(pkg: Package, handle: InstallHandle, error: any)` | -| `package:uninstall:success` | `fun(pkg: Package)` | - -The following is an example for how to register handlers for events: - -```lua -local registry = require "mason-registry" - -registry:on( - "package:handle", - vim.schedule_wrap(function(pkg, handle) - print(string.format("Installing %s", pkg.name)) - end) -) - -registry:on( - "package:install:success", - vim.schedule_wrap(function(pkg, handle) - print(string.format("Successfully installed %s", pkg.name)) - end) -) -``` - -## `RegistryPackageSpec` - -| Key | Value | -| ----------- | ------------------------------------- | -| schema | `"registry+v1"` | -| name | `string` | -| description | `string` | -| homepage | `string` | -| licenses | [`PackageLicense[]`](#packagelicense) | -| categories | [`PackageCategory[]`](#packagecat) | -| languages | [`PackageLanguage[]`](#packagelang) | -| source | `table` | -| bin | `table<string, string>?` | -| share | `table<string, string>?` | -| opt | `table<string, string>?` | - -## `Package` - -Module: [`"mason-core.package"`](../lua/mason-core/package/init.lua) - -The `Package` class encapsulates the installation instructions and metadata about a Mason package. - -**Events** - -This class extends the [EventEmitter](#eventemitter) interface and emits the following events: - -| Event | Handler signature | -| ------------------- | ------------------------------------------------------ | -| `install:success` | `fun(handle: InstallHandle)` | -| `install:failed` | `fun(pkg: Package, handle: InstallHandle, error: any)` | -| `uninstall:success` | `fun()` | - -### `Package.Parse({package_identifier})` - -**Parameters:** - -- `package_identifier`: `string` For example, `"rust-analyzer@nightly"` - -**Returns:** `(string, string|nil)` Tuple where the first value is the name and the second value is the specified -version (or `nil`). - -### `Package.Lang` - -**Type:** `table<string, string>` - -Metatable used to declare language identifiers. Any key is valid and will be automatically indexed on first access, for -example: - -```lua -print(vim.inspect(Package.Lang)) -- prints {} -local lang = Package.Lang.SomeMadeUpLanguage -print(lang) -- prints "SomeMadeUpLanguage" -print(vim.inspect(Package.Lang)) -- prints { SomeMadeUpLanguage = "SomeMadeUpLanguage" } -``` - -### `Package.Cat` - -**Type:** - -```lua -Package.Cat = { - Compiler = "Compiler", - Runtime = "Runtime", - DAP = "DAP", - LSP = "LSP", - Linter = "Linter", - Formatter = "Formatter", -} -``` - -### `Package.License` - -Similar as [`Package.Lang`](#packagelang) but for SPDX license identifiers. - -### `Package:new({spec})` - -**Parameters:** - -- `spec`: [`RegistryPackageSpec`](#registrypackagespec) - -### `Package.spec` - -**Type**: [`RegistryPackageSpec`](#registrypackagespec) - -### `Package:is_installing()` - -**Returns:** `boolean` - -### `Package:install({opts?}, {callback?})` - -**Parameters:** - -- `opts?`: [`PackageInstallOpts`](#packageinstallopts-1) (optional) -- `callback?`: `fun(success: boolean, result: any)` (optional) - Callback to be called when package installation completes. _Note: this is called before events (["package:install:success"](#registry-events), ["install:success"](#package)) are emitted._ - -**Returns:** [`InstallHandle`](#installhandle) - -Installs the package instance this method is being called on. Accepts an optional `{opts}` argument which can be used to -for example specify which version to install (see [`PackageInstallOpts`](#packageinstallopts-1)), and an optional -`{callback}` argument which is called when the installation finishes. - -The returned [`InstallHandle`](#installhandle) can be used to observe progress and control the installation process -(e.g., cancelling). - -_Note that if the package is already being installed this method will error. See -[`Package:is_installing()`](#packageis_installing)._ - -### `Package:uninstall()` - -Uninstalls the package instance this method is being called on. - -### `Package:is_installed()` - -**Returns:** `boolean` - -### `Package:get_install_path()` - -**Returns:** `string` The full path where this package is installed. _Note that this will always return a string, -regardless of whether the package is actually installed or not._ - -### `Package:get_installed_version()` - -**Returns:** `string?` The currently installed version of the package. Returns `nil` if the package is not installed. - -### `Package:get_latest_version()` - -**Returns:** `string` The latest package version as provided by the currently installed version of the registry. - -_Note that this method will not check if one or more registries are outdated. If it's desired to retrieve the latest -upstream version, refresh/update registries first (`:h mason-registry.refresh()`, `:h mason-registry.update()`), for -example:_ - -```lua -local registry = require "mason-registry" -registry.refresh(function() - local pkg = registry.get_package "rust-analyzer" - local latest_version = pkg:get_latest_version() -end) -``` - -### `Package:is_installable({opts?})` - -**Parameters:** - -- `opts?`: [`PackageInstallOpts`](#packageinstallopts-1) (optional) - -**Returns:** `boolean` Returns `true` if the package is installable on the current platform. - -## `PackageInstallOpts` - -**Type:** - -| Key | Value | Description | -| ------- | ---------- | -------------------------------------------------------------------------------------------------------- | -| version | `string?` | The desired version of the package. | -| target | `string?` | The desired target of the package to install (e.g. `darwin_arm64`, `linux_x64`). | -| debug | `boolean?` | If debug logs should be written. | -| force | `boolean?` | If installation should continue if there are conditions that would normally cause installation to fail. | -| strict | `boolean?` | If installation should NOT continue if there are errors that are not necessary for package to be usable. | - -## `InstallContext` - -The `InstallContext` class will be instantiated by Mason every time a package installer is executed. The `install` -function of a package will receive an instance of `InstallContext` as its first argument. - -As the name suggests, this class provides contextual information to be used when installing a package. This includes -which package is being installed, a `spawn` method that allow you to spawn processes that (i) use the correct working -directory of the installation, and (ii) automatically registers stdout and stderr with the `InstallHandle`. - -### `InstallContext.package` - -**Type:** [`Package`](#package) - -### `InstallContext.handle` - -**Type:** [`InstallHandle`](#installhandle) - -### `InstallContext.cwd` - -**Type:** [`CwdManager`](#cwdmanager) - -### `InstallContext.spawn` - -**Type:** [`ContextualSpawn`](#contextualspawn) - -### `InstallContext.fs` - -**Type:** [`ContextualFs`](#contextualfs) - -### `InstallContext.requested_version` - -**Type:** `Optional<string>` - -### `InstallContext.stdio_sink` - -**Type:** `{ stdout: fun(chunk: string), stderr: fun(chunk: string) }` - -The `.stdio_sink` property can be used to send stdout or stderr output, to be presented to the user. - -Example: - -```lua -local pkg = Pkg:new { - --- ... - ---@async - ---@param ctx InstallContext - install = function(ctx) - ctx.stdio_sink.stdout "I am doing stuff\n" - ctx.stdio_sink.stderr "Something went wrong!\n" - end, -} -``` - -## `ContextualFs` - -Provides wrapper functions around `mason-core.fs`. These wrapper functions all accept relative paths, which will be -expanded based on the associated `InstallContext`'s current working directory. - -## `ContextualSpawn` - -**Type:** `table<string, async fun(opts: SpawnOpts)>` - -Provides an asynchronous interface to spawn processes (via libuv). Each spawned process will, by default, be spawned -with the current working directory of the `InstallContext` it belongs to. stdout & stderr will also automatically be -registered with the relevant `InstallHandle`. - -Example usage: - -```lua -local pkg = Pkg:new { - --- ... - ---@async - ---@param ctx InstallContext - install = function(ctx) - ctx.spawn.npm { "install", "some-package" } - -- Calls to spawn will raise an error if it exits with a non-OK exit code or signal. - pcall(function() - ctx.spawn.commandoesntexist {} - end) - end, -} -``` - -## `CwdManager` - -Manages the current working directory of an installation (through `InstallContext`). - -### `CwdManager:set({cwd)})` - -**Parameters:** - -- `cwd`: `string` - -Changes the current working directory to `{cwd}`. `{cwd}` MUST be within the user's configured `install_root_dir` -setting. - -### `CwdManager:get()` - -**Returns:** `string` - -## `InstallHandleState` - -**Type:** `"IDLE" | "QUEUED" | "ACTIVE" | "CLOSED"` - -## `InstallHandle` - -An `InstallHandle` is a handle for observing and controlling the installation of a package. -Every package installed via Mason will be managed via a `InstallHandle` instance. - -It has a finite set of states, with an initial (`IDLE`) and terminal (`CLOSED`) one. This state can be accessed via the -`InstallHandle.state` field, or through one of the `:is_idle()`, `:is_queued()`, `:is_active()`, `:is_closed()` methods. -In most cases a handler's state will transition like so: - -```mermaid -stateDiagram-v2 - IDLE: IDLE - QUEUED: QUEUED - note right of QUEUED - The installation has been queued and will be ran when the next permit is available (according to the user's - settings.) - It can now be aborted via the :terminate() method. - end note - ACTIVE: ACTIVE - note right of ACTIVE - The installation has now started. The handler will emit `stdout` and `stderr` events. - The installation can also be cancelled via the :terminate() method, and you can send signals - to running processes via :kill({signal}). - end note - CLOSED: CLOSED - note right of CLOSED - The installation is now finished, and all associated resources have been closed. - This is the final state and the handler will not emit any more events. - end note - [*] --> IDLE - IDLE --> QUEUED - QUEUED --> ACTIVE - ACTIVE --> CLOSED - CLOSED --> [*] -``` - -**Events** - -This class extends the [EventEmitter](#eventemitter) interface and emits the following events: - -| Event | Handler signature | -| -------------- | ------------------------------------------------------------------- | -| `stdout` | `fun(chunk: string)` | -| `stderr` | `fun(chunk: string)` | -| `state:change` | `fun(new_state: InstallHandleState, old_state: InstallHandleState)` | -| `kill` | `fun(signal: integer)` | -| `terminate` | `fun()` | -| `closed` | `fun()` | - -### `InstallHandle.package` - -**Type:** [`Package`](#package) - -### `InstallHandle.state` - -**Type:** [`InstallHandleState`](#installhandlestate) - -### `InstallHandle.is_terminated` - -**Type:** `boolean` - -### `InstallHandle:is_idle()` - -**Returns:** `boolean` - -### `InstallHandle:is_queued()` - -**Returns:** `boolean` - -### `InstallHandle:is_active()` - -**Returns:** `boolean` - -### `InstallHandle:is_closed()` - -**Returns:** `boolean` - -### `InstallHandle:kill({signal})` - -**Parameters:** - -- `signal`: `integer` The `signal(3)` to send. - -### `InstallHandle:terminate()` - -Instructs the handle to terminate itself. On Windows, this will issue a -`taskkill.exe` treekill on all attached libuv handles. On Unix, this will -issue a SIGTERM signal to all attached libuv handles. - -## `EventEmitter` - -The `EventEmitter` interface includes methods to subscribe (and unsubscribe) -to events on the associated object. - -### `EventEmitter:on({event}, {handler})` - -**Parameters:** - -- `event`: `string` -- `handler`: `fun(...)` - -Registers the provided `{handler}`, to be called every time the provided -`{event}` is dispatched. - -_Note that the provided `{handler}` may be executed outside the main Neovim loop (`:h vim.in_fast_event()`), where most -of the Neovim API is disabled._ - -### `EventEmitter:once({event, handler})` - -**Parameters:** - -- `event`: `string` -- `handler`: `fun(...)` - -Registers the provided `{handler}`, to be called only once - the next time the -provided `{event}` is dispatched. - -_Note that the provided `{handler}` may be executed outside the main Neovim loop (`:h vim.in_fast_event()`), where most -of the Neovim API is disabled._ - -### `EventEmitter:off({event}, {handler})` - -**Parameters:** - -- `event`: `string` -- `handler`: `fun(...)` - -Deregisters the provided `{handler}` for the provided `{event}`. |