### Example Usage of InstallLocation

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-location.md

Demonstrates the complete workflow of getting the global install location, initializing directories, accessing directory paths, setting environment variables, and retrieving specific package paths.

```lua
local InstallLocation = require("mason-core.installer.InstallLocation")

-- Get global install location
local location = InstallLocation.global()

-- Initialize directories
local result = location:initialize()
if result:is_failure() then
    print("Failed to initialize:", result:err_or_nil())
    return
end

-- Access various directories
print("Packages:", location:package())
print("Bin:", location:bin())
print("Shared:", location:share())

-- Set up environment
location:set_env({ PATH = "prepend" })

-- Get specific package path
print("Rust-analyzer:", location:package("rust-analyzer"))
```

--------------------------------

### Get and Install a Package from Registry

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/README.md

Retrieve a package from the registry and install it if it's not already present. Includes a callback for installation status.

```lua
local registry = require("mason-registry")

-- Get a package
local pkg = registry.get_package("rust-analyzer")

-- Check if installed
if pkg:is_installed() then
    print("Already installed")
else
    -- Install it
    pkg:install(nil, function(success, error) 
        if success then
            print("Installation complete")
        end
    end)
end
```

--------------------------------

### Example Usage: Open and Configure UI

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/ui.md

Demonstrates opening the Mason UI and configuring custom keybindings during setup.

```lua
-- Open the UI
require("mason.ui").open()

-- Configure in setup with custom keybindings
require("mason").setup({
    ui = {
        keymaps = {
            toggle_package_expand = "<CR>",
            install_package = "i",
            update_package = "u",
            uninstall_package = "X",
            -- ... other keybindings
        }
    }
})
```

--------------------------------

### setup()

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/mason-module.md

Initializes Mason with the provided configuration. This function must be called once during plugin initialization and applies configuration settings, registers registries, initializes install locations, loads the command interface, and sets up VimLeavePre autocmd.

```APIDOC
## setup()

### Description
Initializes Mason with the provided configuration. This function must be called once during plugin initialization and applies configuration settings, registers registries, initializes install locations, loads the command interface, and sets up VimLeavePre autocmd.

### Method
`require("mason").setup(config: MasonSettings?)

### Parameters
#### Arguments
- **config** (`MasonSettings`) - Optional - Configuration table with settings for Mason initialization.

### Request Example
```lua
require("mason").setup({
    ui = {
        icons = {
            package_installed = "✓",
            package_pending = "➜",
            package_uninstalled = "✗"
        }
    },
    max_concurrent_installers = 4,
    PATH = "prepend"
})
```

### Response
#### Success Response
- **Return Type:** `nil`
```

--------------------------------

### Install a Single Package

Source: https://github.com/mason-org/mason.nvim/blob/main/doc/mason.txt

Installs a single package using the :MasonInstall command. For example, to install 'stylua'.

```vim
:MasonInstall stylua
```

--------------------------------

### Create and Install a Conditional System Package

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/system-package.md

Demonstrates creating a SystemPackage instance for 'sfw@latest', conditionally enabling it based on Mason settings, checking if installation is required, and performing the installation if necessary. Requires importing 'mason-core.async', 'mason-core.system-package', and 'mason.settings'.

```lua
local a = require("mason-core.async")
local SystemPackage = require("mason-core.system-package")
local settings = require("mason.settings")

a.run(function()
    -- Create a system package for the firewall tool
    local sfw = SystemPackage:new("sfw@latest")
        :conditional(function()
            return settings.current.firewall.enabled
        end)
    
    -- Check if installation is needed
    local needs = sfw:needs_install()
    if needs:is_success() and needs:get_or_nil() then
        print("Installing socket firewall...")
        sfw:install()
    end
end)
```

--------------------------------

### Basic Mason Setup

Source: https://github.com/mason-org/mason.nvim/blob/main/README.md

This is the basic setup for mason.nvim. It should be called during Neovim's initialization.

```lua
require("mason").setup()
```

--------------------------------

### SystemPackage:install

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/system-package.md

Asynchronously installs the system package.

```APIDOC
## pkg:install

### Description
Asynchronously installs the system package and waits for completion using internal channel communication.

### Method
`pkg:install(): Result<>`

### Response
#### Success Response
- **Result<nil>** - Indicates successful installation.

### Request Example
```lua
local result = system_pkg:install()
if result:is_success() then
    print("System package installed")
else
    print("Installation failed:", result:err_or_nil())
end
```
```

--------------------------------

### Get Current Installation Handle

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Retrieves the existing installation handle for the package, if one is currently active.

```lua
pkg:get_install_handle(): Optional<InstallHandle>
```

--------------------------------

### Basic Mason.nvim Setup

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/README.md

Configure the UI icons for package statuses. This is a basic setup for the mason.nvim plugin.

```lua
require("mason").setup({
    ui = {
        icons = {
            package_installed = "✓",
            package_pending = "➜",
            package_uninstalled = "✗"
        }
    }
})
```

--------------------------------

### Checking Installability Before Installation

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/errors.md

Illustrates checking if a package is installable with given options before proceeding with the installation. This helps prevent errors related to invalid install options.

```lua
if pkg:is_installable() then
    pkg:install()
end
```

--------------------------------

### Install a Package

Source: https://github.com/mason-org/mason.nvim/blob/main/doc/mason.txt

Installs the specified package(s). You can optionally include a version specifier.

```vim
:MasonInstall <package> ...
```

```vim
    :MasonInstall lua-language-server@v3.0.0
```

--------------------------------

### Basic Mason Setup

Source: https://github.com/mason-org/mason.nvim/blob/main/doc/mason.txt

Initializes the Mason plugin with default configurations.

```lua
require("mason")
```

--------------------------------

### Get Package Installation Receipt

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Retrieves metadata about the installation from mason-receipt.json. The location parameter specifies a particular install location, defaulting to global.

```lua
pkg:get_receipt(location?: InstallLocation): Optional<InstallReceipt>
```

--------------------------------

### Lazy.nvim Setup for Mason

Source: https://github.com/mason-org/mason.nvim/blob/main/README.md

Recommended setup for mason.nvim when using the lazy.nvim plugin manager. This setup automatically calls require("mason").setup().

```lua
{
    "mason-org/mason.nvim",
    opts = {}
}
```

--------------------------------

### Mason.nvim Setup with Custom UI Keymaps

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/configuration.md

Customize keybindings for UI actions within Mason.nvim. This allows users to define their preferred keys for installing, updating, and uninstalling packages.

```lua
require("mason").setup({
    ui = {
        keymaps = {
            install_package = "I",
            update_package = "U",
            uninstall_package = "D",
        },
    },
})

```

--------------------------------

### Get Currently Installed Package Version

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Gets the version string of the currently installed package, returning nil if not installed. The example demonstrates checking for an installed version and printing it.

```lua
pkg:get_installed_version(location?: InstallLocation): string?
```

```lua
local version = pkg:get_installed_version()
if version then
    print("Installed version:", version)
end
```

--------------------------------

### pkg:install()

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Installs the package with optional configurations and a callback for completion status. It can install specific versions, enable debug output, force reinstallation, and override target platforms or locations.

```APIDOC
## pkg:install()

### Description
Installs the package.

### Method
`pkg:install(opts?: PackageInstallOpts, callback?: InstallRunnerCallback): InstallHandle`

### Parameters
#### Path Parameters
- **opts** (`PackageInstallOpts`) - Optional - Installation options
  - **version** (`string`) - Specific version to install (default: latest)
  - **debug** (`boolean`) - Enable debug output (default: false)
  - **force** (`boolean`) - Force reinstall even if already installed (default: false)
  - **strict** (`boolean`) - Enable strict mode checks (default: false)
  - **target** (`string`) - Override target platform
  - **location** (`InstallLocation`) - Override install location (default: global)
- **callback** (`fun(success: boolean, error: any)`) - Optional - Callback when installation completes

### Return Type
`InstallHandle` - Handle representing this installation

### Throws
Asserts if package is already installing or uninstalling.

### Example
```lua
local registry = require("mason-registry")
local pkg = registry.get_package("rust-analyzer")
local handle = pkg:install({
    version = "nightly"
}, function(success, error) 
    if success then
        print("Installation complete")
    else
        print("Installation failed:", error)
    end
end)
```
```

--------------------------------

### Mason Setup with Configuration

Source: https://github.com/mason-org/mason.nvim/blob/main/doc/mason.txt

Sets up the Mason plugin with a provided configuration object.

```lua
require("mason").setup({config})
```

--------------------------------

### Check InstallHandle Queued State

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-handle.md

Checks if the installation handle is in the queued state, waiting to start.

```lua
handle:is_queued(): boolean
```

--------------------------------

### InstallLocation.global()

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-location.md

Gets the global install location based on current settings.

```APIDOC
## InstallLocation.global()

### Description
Gets the global install location from current settings.

### Method
`InstallLocation.global(): InstallLocation`

### Return Type
`InstallLocation` - The global location configured in `install_root_dir` setting

### Example
```lua
local InstallLocation = require("mason-core.installer.InstallLocation")
local global_loc = InstallLocation.global()
print("Install root:", global_loc:get_dir())
```
```

--------------------------------

### Install System Package

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/system-package.md

Asynchronously installs the system package and waits for the process to complete. Handles errors during installation.

```lua
local result = system_pkg:install()
if result:is_success() then
    print("System package installed")
else
    print("Installation failed:", result:err_or_nil())
end
```

--------------------------------

### Install Multiple Packages

Source: https://github.com/mason-org/mason.nvim/blob/main/doc/mason.txt

Installs multiple packages simultaneously using the :MasonInstall command. Packages are listed separated by spaces.

```vim
:MasonInstall stylua lua-language-server
```

--------------------------------

### Get All Available Package Versions

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Fetches all available version strings for a package from its configured provider. The example shows how to handle the Result type and iterate over successful version retrieval.

```lua
pkg:get_all_versions(): Result<string[]>
```

```lua
local result = pkg:get_all_versions()
if result:is_success() then
    local versions = result:get_or_nil()
    for _, version in ipairs(versions) do
        print("Available:", version)
    end
end
```

--------------------------------

### Install Packages in Headless Mode

Source: https://github.com/mason-org/mason.nvim/blob/main/doc/mason.txt

Installs packages in blocking mode without opening the UI. This is useful for automated setups. The command exits after installation.

```sh
$ nvim --headless -c "MasonInstall lua-language-server rust-analyzer" -c qall
```

--------------------------------

### Install Specific Package Version

Source: https://github.com/mason-org/mason.nvim/blob/main/doc/mason.txt

Installs a specific version of a package by appending '@version' to the package name. For example, installing the 'nightly' version of 'rust-analyzer'.

```vim
:MasonInstall rust-analyzer@nightly
```

--------------------------------

### Get All Installed Packages

Source: https://github.com/mason-org/mason.nvim/blob/main/doc/mason.txt

Retrieves instances of all currently installed packages. Note that this function is slower as it loads more modules.

```lua
mason-registry.get_installed_packages()
```

--------------------------------

### Initialize Install Location

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-location.md

Initializes the standard directory structure for mason.nvim. Use this to ensure all required subdirectories are created before installing packages.

```lua
location:initialize(): Result
```

```lua
local result = location:initialize()
if result:is_success() then
    print("Install location initialized")
end
```

--------------------------------

### Get Package Receipt Path

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Gets the path to the mason-receipt.json file for a specific install location, defaulting to global.

```lua
pkg:get_receipt_path(location?: InstallLocation): string
```

--------------------------------

### InstallHandle:active

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-handle.md

Transitions the installation handle from the IDLE or QUEUED state to the ACTIVE state.

```APIDOC
## active()

### Description
Transitions handle from IDLE or QUEUED to ACTIVE state.

### Return Type
nil

### Throws
Asserts if handle is not idle or queued
```

--------------------------------

### InstallHandle:queued

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-handle.md

Transitions the installation handle from the IDLE state to the QUEUED state.

```APIDOC
## queued()

### Description
Transitions handle from IDLE to QUEUED state.

### Return Type
nil

### Throws
Asserts if handle is not idle
```

--------------------------------

### Callback Error Handling

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/errors.md

Illustrates how to handle errors passed as the second parameter to installation callbacks. This is common for asynchronous installation processes.

```lua
pkg:install(nil, function(success, error) 
    if not success then
        print("Installation error:", error)
    end
end)
```

--------------------------------

### Install a Package

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Installs a specified package, optionally with a specific version and a callback for completion status. Use this to add new packages or update existing ones.

```lua
local registry = require("mason-registry")
local pkg = registry.get_package("rust-analyzer")
local handle = pkg:install({
    version = "nightly"
}, function(success, error) 
    if success then
        print("Installation complete")
    else
        print("Installation failed:", error)
    end
end)
```

--------------------------------

### Get Package Installation Path

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Retrieves the full file system path where a package is installed. This can be used to access package binaries or configuration files.

```lua
local install_path = pkg:get_install_path()
print("Package installed at:", install_path)
```

--------------------------------

### get_receipt_path

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Gets the file path to the installation receipt (`mason-receipt.json`) for a package. The path can be specific to an install location.

```APIDOC
## get_receipt_path()

### Description
Gets the path to the installation receipt file.

### Method
`pkg:get_receipt_path(location?: InstallLocation): string`

### Parameters
#### Path Parameters
- **location** (`InstallLocation`) - Optional - Specific install location (default: global)

### Return Type
`string` - Path to `mason-receipt.json`
```

--------------------------------

### Slowly Getting Installed Packages

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/README.md

Illustrates a slower operation that retrieves full Package objects for all installed packages, requiring more resources.

```lua
-- Slow: loads all Package classes
registry.get_installed_packages()
```

--------------------------------

### Efficiently Getting Installed Package Names

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/README.md

Demonstrates a fast operation that retrieves only the names of installed packages without loading full Package classes.

```lua
-- Fast: doesn't load Package classes
registry.get_installed_package_names()
```

--------------------------------

### InstallHandle:is_queued

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-handle.md

Checks if the installation handle is in the queued state, waiting to start an operation.

```APIDOC
## is_queued()

### Description
Checks if the handle is in the queued state.

### Return Type
boolean
```

--------------------------------

### is_installable

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Checks if the package is compatible and can be installed on the current system platform, optionally considering specific installation options.

```APIDOC
## is_installable()

### Description
Checks if the package can be installed on the current platform.

### Method
`pkg:is_installable(opts?: PackageInstallOpts): boolean`

### Parameters
#### Path Parameters
- **opts** (`PackageInstallOpts`) - Optional - Installation options to validate

### Return Type
`boolean`
```

--------------------------------

### Pre-configured sfw SystemPackage Installation

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/system-package.md

Installs the 'sfw' system package, which is pre-configured to be conditional on firewall settings. This simplifies managing the sfw tool.

```lua
local SystemPackage = require("mason-core.system-package")
-- sfw is only installed if firewall is enabled and auto-managed
SystemPackage.sfw:install()
```

--------------------------------

### InstallHandle Constructor

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-handle.md

Creates a new installation handle. This is typically created internally by package methods.

```lua
InstallHandle:new(pkg: AbstractPackage, location: InstallLocation): InstallHandle
```

--------------------------------

### Install a Specific Package Version

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/README.md

Install a specific version of a package from the registry. This is useful for managing exact dependencies.

```lua
local registry = require("mason-registry")
local pkg = registry.get_package("lua-language-server")
pkg:install({ version = "v3.6.0" })
```

--------------------------------

### Customize Core Mason.nvim Settings

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/configuration.md

Configure the installation directory, PATH modification strategy, logging level, and the maximum number of concurrent installers. Use this to tailor Mason's core behavior to your environment.

```lua
require("mason").setup({
    install_root_dir = "/custom/path/to/mason",
    PATH = "append",
    log_level = vim.log.levels.DEBUG,
    max_concurrent_installers = 8,
})

```

--------------------------------

### Access Staging Directory

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-location.md

Gets the path to the staging directory, which is used for downloads during the installation process. An optional path can be provided for subdirectories or files within staging.

```lua
location:staging(path?: string): string
```

--------------------------------

### Check if Package is Installable

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Determines if the package can be installed on the current platform, optionally considering provided installation options.

```lua
pkg:is_installable(opts?: PackageInstallOpts): boolean
```

--------------------------------

### Preventing Installation of Installing Package

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/errors.md

Demonstrates how to prevent attempting to install a package that is already in the process of installing. This avoids assertion failures.

```lua
if not pkg:is_installing() then
    pkg:install()
end
```

--------------------------------

### SystemPackage:await_channel

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/system-package.md

Waits for a pending installation to complete.

```APIDOC
## pkg:await_channel

### Description
Waits for a pending installation to complete. Blocks until installation completion signal is received on the channel.

### Method
`pkg:await_channel(): Result<>`

### Response
#### Success Response
- **Result<nil>** - Indicates completion signal received.

### Request Example
```lua
local result = system_pkg:await_channel()
```
```

--------------------------------

### Handle Package Installation Errors

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/README.md

Install a package and handle potential errors using a callback function. Logs success or failure messages along with error details.

```lua
local registry = require("mason-registry")
local pkg = registry.get_package("rust-analyzer")

pkg:install(nil, function(success, error) 
    if success then
        print("Installed:", pkg.name)
    else
        print("Failed to install:", pkg.name)
        print("Error:", error)
    end
end)
```

--------------------------------

### InstallHandle:new

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-handle.md

Creates a new installation handle. This is typically called internally by package management functions.

```APIDOC
## InstallHandle:new()

### Description
Creates a new installation handle.

### Parameters
#### Path Parameters
- **pkg** (AbstractPackage) - Yes - The package being installed/uninstalled
- **location** (InstallLocation) - Yes - The location where package will be installed

### Return Type
InstallHandle
```

--------------------------------

### Await Installation Completion

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/system-package.md

Blocks execution until a signal is received indicating that a pending installation has completed. This is a lower-level synchronization mechanism.

```lua
pkg:await_channel(): Result<>
```

--------------------------------

### Handle System Package Installation Failure

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/errors.md

When `SystemPackage:install()` fails, it returns a failure result. This snippet shows how to check the result and log the error.

```lua
local result = system_pkg:install()
if result:is_failure() then
    print("System package installation failed:", result:err_or_nil())
end
```

--------------------------------

### Check Package Installation State

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/errors.md

Attempting to install a package that is already installing or uninstalling will trigger an assertion error. Check the package's state using `is_installing()` before proceeding.

```lua
-- Problem
pkg:install()  -- Throws assertion if already installing
pkg:install()  -- Error!

-- Solution: Check state
if not pkg:is_installing() then
    pkg:install()
end
```

--------------------------------

### Set InstallHandle State

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-handle.md

Directly sets the state of the installation handle. Use this to manually transition states.

```lua
handle:set_state(new_state: InstallHandleState)
```

--------------------------------

### InstallReceipt Class Definition

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/types.md

Represents the metadata stored during package installation, such as version and timestamp. This class is used to retrieve installation details for a package.

```lua
---@class InstallReceipt
-- Methods: get_installed_package_version(), ...

```

--------------------------------

### Access Installed Packages Directory

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-location.md

Gets the path to the installed packages directory. Can optionally specify a package name to get the path for a specific package.

```lua
local all_packages_dir = location:package()
local specific_pkg_dir = location:package("rust-analyzer")
```

--------------------------------

### Check if Installation is Needed

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/system-package.md

Asynchronously determines if a system package requires installation. It considers set conditions, installation status, and version differences.

```lua
local result = system_pkg:needs_install()
if result:is_success() and result:get_or_nil() then
    print("Package needs installation")
end
```

--------------------------------

### Set Conditional Installation

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/system-package.md

Configures a SystemPackage to only install if a provided function returns true. Useful for environment-specific or setting-dependent installations.

```lua
local sfw = SystemPackage:new("sfw@latest")
    :conditional(function()
        return settings.current.firewall.enabled and 
               settings.current.firewall.auto_managed
    end)
```

--------------------------------

### Install Package in Headless Mode

Source: https://github.com/mason-org/mason.nvim/blob/main/doc/mason.txt

Installs a package using Neovim in headless mode, suitable for scripting or CI environments.

```sh
$ nvim --headless -c "MasonInstall stylua" -c "qall"
```

--------------------------------

### get_installed_version

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Gets the version of the package that is currently installed. Returns nil if the package is not installed. Can specify an install location.

```APIDOC
## get_installed_version()

### Description
Gets the currently installed version.

### Method
`pkg:get_installed_version(location?: InstallLocation): string?`

### Parameters
#### Path Parameters
- **location** (`InstallLocation`) - Optional - Specific install location (default: global)

### Return Type
`string?` - Version string or nil if not installed

### Example
```lua
local version = pkg:get_installed_version()
if version then
    print("Installed version:", version)
end
```
```

--------------------------------

### InstallHandle:close

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-handle.md

Closes the installation handle and marks the operation as complete.

```APIDOC
## close()

### Description
Closes the handle and marks operation complete.

### Return Type
nil

### Emits
close(success, result) - where success is boolean, result is operation result

### Throws
Asserts if handle is already closed
```

--------------------------------

### SystemPackage:needs_install

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/system-package.md

Asynchronously checks if the package needs to be installed.

```APIDOC
## pkg:needs_install

### Description
Asynchronously checks if package needs to be installed. Returns true if: Condition (if set) returns true, AND Package is not installed OR is currently installing, OR Installed version differs from latest version.

### Method
`pkg:needs_install(): Result<boolean>`

### Response
#### Success Response
- **Result<boolean>** - Result containing a boolean indicating if installation is needed.

### Request Example
```lua
local result = system_pkg:needs_install()
if result:is_success() and result:get_or_nil() then
    print("Package needs installation")
end
```
```

--------------------------------

### Basic Mason.nvim Setup

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/configuration.md

The minimal configuration required to set up Mason.nvim. This ensures the plugin is initialized with default settings.

```lua
require("mason").setup()

```

--------------------------------

### Get Global Install Location

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-location.md

Retrieves the global installation location based on the current settings. Useful for accessing the root directory configured for all installations.

```lua
local InstallLocation = require("mason-core.installer.InstallLocation")
local global_loc = InstallLocation.global()
print("Install root:", global_loc:get_dir())
```

--------------------------------

### Default Mason Settings

Source: https://github.com/mason-org/mason.nvim/blob/main/doc/mason.txt

Defines the default settings for mason.nvim, including installation directory, PATH modification, log level, and concurrent installer limit.

```lua
--@class MasonSettings
local DEFAULT_SETTINGS = {
    --@since 1.0.0
    -- The directory in which to install packages.
    install_root_dir = path.concat { vim.fn.stdpath "data", "mason" },

    --@since 1.0.0
    -- Where Mason should put its bin location in your PATH. Can be one of:
    -- - "prepend" (default, Mason's bin location is put first in PATH)
    -- - "append" (Mason's bin location is put at the end of PATH)
    -- - "skip" (doesn't modify PATH)
    ---@type '"prepend"' | '"append"' | '"skip"'
    PATH = "prepend",

    --@since 1.0.0
    -- Controls to which degree logs are written to the log file. It's useful to set this to vim.log.levels.DEBUG when
    -- debugging issues with package installations.
    log_level = vim.log.levels.INFO,

    --@since 1.0.0
    -- Limit for the maximum amount of packages to be installed at the same time. Once this limit is reached, any further
    -- packages that are requested to be installed will be put in a queue.
    max_concurrent_installers = 4,

    --@since 1.0.0
    -- [Advanced setting]
}
```

--------------------------------

### location:bin()

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-location.md

Gets the path to the executable binaries directory, optionally appending a path.

```APIDOC
## location:bin()

### Description
Gets the executable binaries directory path.

### Method
`location:bin(path?: string): string`

### Parameters
#### Path Parameters
- **path** (string) - Optional - Optional subdirectory or file within bin

### Return Type
`string` - Path to `<root>/bin[/path]`

### Example
```lua
local bin_dir = location:bin()
local cmd_path = location:bin("stylua")
```
```

--------------------------------

### Configure NPM Settings

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/configuration.md

Specify additional arguments to be used with npm install commands, such as setting a custom registry.

```lua
require("mason").setup({
    npm = {
        install_args = { "--registry", "https://registry.npmjs.org/" },
    },
})
```

--------------------------------

### Check InstallHandle Active State

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-handle.md

Checks if the installation handle is currently in the active state, meaning an installation or uninstallation is in progress.

```lua
handle:is_active(): boolean
```

--------------------------------

### Async Context Example

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/system-package.md

Demonstrates how to use asynchronous SystemPackage methods within an async context using Mason's async runner. This is the recommended way to handle async operations.

```lua
local a = require("mason-core.async")
local SystemPackage = require("mason-core.system-package")

a.run(function()
    local sfw = SystemPackage:new("sfw@latest")
    local needs_it = sfw:needs_install():get_or_throw()
    
    if needs_it then
        local result = sfw:install():get_or_throw()
        print("Installed successfully")
    end
end)
```

--------------------------------

### Default Mason.nvim Settings

Source: https://github.com/mason-org/mason.nvim/blob/main/README.md

Defines the default configuration structure for mason.nvim, including package installation directory, PATH modification, log level, concurrent installers, registries, and firewall settings.

```lua
---@class MasonSettings
local DEFAULT_SETTINGS = {
    ---@since 1.0.0
    -- The directory in which to install packages.
    install_root_dir = path.concat { vim.fn.stdpath "data", "mason" },

    ---@since 1.0.0
    -- Where Mason should put its bin location in your PATH. Can be one of:
    -- - "prepend" (default, Mason's bin location is put first in PATH)
    -- - "append" (Mason's bin location is put at the end of PATH)
    -- - "skip" (doesn't modify PATH)
    ---@type '"prepend"' | '"append"' | '"skip"'
    PATH = "prepend",

    ---@since 1.0.0
    -- Controls to which degree logs are written to the log file. It's useful to set this to vim.log.levels.DEBUG when
    -- debugging issues with package installations.
    log_level = vim.log.levels.INFO,

    ---@since 1.0.0
    -- Limit for the maximum amount of packages to be installed at the same time. Once this limit is reached, any further
    -- packages that are requested to be installed will be put in a queue.
    max_concurrent_installers = 4,

    ---@since 1.0.0
    -- [Advanced setting]
    -- The registries to source packages from. Accepts multiple entries. Should a package with the same name exist in
    -- multiple registries, the registry listed first will be used.
    registries = {
        "github:mason-org/mason-registry",
    },

    ---@since 2.3.0
    -- [Advanced setting]
    -- The registries to source system packages from. Accepts multiple entries. Should a package with the same name exist in
    -- multiple registries, the registry listed first will be used.
    system_registries = {
        "github:mason-org/mason-system-registry",
    },

    registry_cache = {
        ---@since 2.3.0
        -- [Advanced setting]
        -- Whether Mason should automatically refresh the registry when needed. If false, the registry will have to be
        -- updated manually via :MasonUpdate or the :Mason UI.
        refresh = true,

        ---@since 2.3.0
        -- Amount of seconds before the local registry cache is considered stale.
        -- Note that this setting has no effect if refresh is set to false.
        duration = 24 * 60 * 60, -- 24 hours
    },

    firewall = {
        ---@since 2.3.0
        -- Whether to enable the socket.dev firewall (sfw) for supported package sources.
        -- For more information, refer to https://socket.dev.
        enabled = false,

        ---@since 2.3.0
        -- Whether mason.nvim should automatically install and update the Socket Firewall client.
        -- If false, the sfw binary must exist in PATH if the firewall is enabled.
        auto_managed = true,
    },

    ---@since 1.0.0
    -- The provider implementations to use for resolving supplementary package metadata (e.g., all available versions).
    -- Accepts multiple entries, where later entries will be used as fallback should prior providers fail.
    -- Builtin providers are:
    --   - mason.providers.registry-api  - uses the https://api.mason-registry.dev API
    --   - mason.providers.client        - uses only client-side tooling to resolve metadata
    providers = {
        "mason.providers.registry-api",
        "mason.providers.client",
    },

    github = {
        ---@since 1.0.0
        -- The template URL to use when downloading assets from GitHub.
        -- The placeholders are the following (in order):
        -- 1. The repository (e.g. "rust-lang/rust-analyzer")
        -- 2. The release version (e.g. "v0.3.0")
        -- 3. The asset name (e.g. "rust-analyzer-v0.3.0-x86_64-unknown-linux-gnu.tar.gz")
        download_url_template = "https://github.com/%s/releases/download/%s/%s",
    },

    pip = {
        ---@since 1.0.0
        -- Whether to upgrade pip to the latest version in the virtual environment before installing packages.
        upgrade_pip = false,

        ---@since 1.0.0
        -- These args will be added to `pip install` calls. Note that setting extra args might impact intended behavior
        -- and is not recommended.
        --
        -- Example: { "--proxy", "https://proxyserver" }
        install_args = {},
    },

    npm = {
        ---@since 2.3.0
        -- These args will be added to `npm install` calls. Note that setting extra args might impact intended behavior
        -- and is not recommended.
        --
        -- Example: { "--registry", "https://registry.npmjs.org/" }
        install_args = {},
    },

    ui = {
        ---@since 1.0.0
        -- Whether to automatically check for new versions when opening the :Mason window.
        check_outdated_packages_on_open = true,

        ---@since 1.0.0
        -- The border to use for the UI window. Accepts same border values as |nvim_open_win()|.
        -- Defaults to `:h 'winborder'` if nil.
        border = nil,

        ---@since 1.11.0
        -- The backdrop opacity. 0 is fully opaque, 100 is fully transparent.
        backdrop = 60,

        ---@since 1.0.0
    }
}

```

--------------------------------

### SystemPackage:conditional

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/system-package.md

Sets a condition that must be true for the package to be installed.

```APIDOC
## pkg:conditional

### Description
Sets a condition that must be true for package to be installed.

### Method
`pkg:conditional(fn: fun(): boolean): SystemPackage`

### Parameters
#### Path Parameters
- **fn** (function) - Yes - Function returning true if installation needed

### Response
#### Success Response
- **SystemPackage** - Self for chaining

### Request Example
```lua
local sfw = SystemPackage:new("sfw@latest")
    :conditional(function()
        return settings.current.firewall.enabled and 
               settings.current.firewall.auto_managed
    end)
```
```

--------------------------------

### Change Mason Installation Provider

Source: https://github.com/mason-org/mason.nvim/blob/main/doc/mason.txt

Modify the installation provider to 'mason.providers.client' to bypass potential network or SSL issues with the default 'mason.providers.registry-api'. Note that the client provider may have lower coverage and performance.

```lua
require("mason").setup {
    providers = {
        "mason.providers.client",
        "mason.providers.registry-api",
    }
}
```

--------------------------------

### Get All Packages

Source: https://github.com/mason-org/mason.nvim/blob/main/doc/mason.txt

Retrieves instances of all packages available in the registry. This function is slower due to loading more modules.

```lua
mason-registry.get_all_packages()
```

--------------------------------

### InstallHandle Location Property

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-handle.md

Gets the installation location for the package managed by the InstallHandle. This property specifies where the package is being installed.

```lua
handle.location: InstallLocation
```

--------------------------------

### Get All Installed Package Names

Source: https://github.com/mason-org/mason.nvim/blob/main/doc/mason.txt

Returns a list of names for all installed packages. This is a fast function that does not load additional modules.

```lua
mason-registry.get_installed_package_names()
```

--------------------------------

### Configure UI Icons

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/configuration.md

Customize the icons used in the mason.nvim UI to represent package installation status.

```lua
require("mason").setup({
    ui = {
        icons = {
            package_installed = "✓",
            package_pending = "➜",
            package_uninstalled = "✗",
        },
    },
})
```

--------------------------------

### Complete Mason.nvim Configuration Structure

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/configuration.md

This snippet shows the full structure of the configuration table that can be passed to `require('mason').setup()`. All settings are optional and have sensible defaults.

```lua
require("mason").setup({
    -- Installation directory
    install_root_dir = vim.fn.stdpath("data") .. "/mason",

    -- PATH modification strategy
    PATH = "prepend",  -- or "append" or "skip"

    -- Logging level
    log_level = vim.log.levels.INFO,

    -- Concurrent installation limit
    max_concurrent_installers = 4,

    -- Package registries
    registries = {
        "github:mason-org/mason-registry",
    },

    -- System package registries
    system_registries = {
        "github:mason-org/mason-system-registry",
    },

    -- Registry caching
    registry_cache = {
        refresh = true,
        duration = 24 * 60 * 60,  -- 24 hours in seconds
    },

    -- Socket.dev firewall
    firewall = {
        enabled = false,
        auto_managed = true,
    },

    -- Package metadata providers
    providers = {
        "mason.providers.registry-api",
        "mason.providers.client",
    },

    -- GitHub settings
    github = {
        download_url_template = "https://github.com/%s/releases/download/%s/%s",
    },

    -- Python pip settings
    pip = {
        upgrade_pip = false,
        install_args = {},
    },

    -- Node npm settings
    npm = {
        install_args = {},
    },

    -- UI settings
    ui = {
        check_outdated_packages_on_open = true,
        border = nil,
        backdrop = 60,
        width = 0.8,
        height = 0.9,
        icons = {
            package_installed = "◍",
            package_pending = "◍",
            package_uninstalled = "◍",
        },
        keymaps = {
            toggle_package_expand = "<CR>",
            install_package = "i",
            update_package = "u",
            check_package_version = "c",
            update_all_packages = "U",
            check_outdated_packages = "C",
            uninstall_package = "X",
            cancel_installation = "<C-c>",
            apply_language_filter = "<C-f>",
            toggle_package_install_log = "<CR>",
            toggle_help = "g?",
        },
    },
})

```

--------------------------------

### mason-registry.get_installed_packages

Source: https://github.com/mason-org/mason.nvim/blob/main/doc/mason.txt

Returns all installed package instances. This is a slower function that loads more modules.

```APIDOC
## mason-registry.get_installed_packages()

### Description
Returns all installed package instances. This is a slower function that loads more modules.

### Returns
- **Package[]** - An array of installed Package instances.
```

--------------------------------

### location:system_package()

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-location.md

Gets the path to the system packages directory, optionally specifying a package name.

```APIDOC
## location:system_package()

### Description
Gets the system packages directory path.

### Method
`location:system_package(pkg?: string): string`

### Parameters
#### Path Parameters
- **pkg** (string) - Optional - Optional system package name

### Return Type
`string` - Path to `<root>/system_packages[/pkg]`
```

--------------------------------

### get_installed_package_names()

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/registry-module.md

Returns all installed package names efficiently without loading Package classes. This provides a quick way to get a list of installed package names.

```APIDOC
## get_installed_package_names()

### Description
Returns all installed package names efficiently without loading Package classes.

### Method
`registry.get_installed_package_names(): string[]`

### Return Type
`string[]` - Array of installed package names

### Example
```lua
local registry = require("mason-registry")
local installed = registry.get_installed_package_names()
for _, name in ipairs(installed) do
    print("Installed:", name)
end
```
```

--------------------------------

### Get all installed package instances

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/registry-module.md

Use `get_installed_packages` to retrieve all installed packages as full Package instances. Note that this function loads all Package classes and is slower than `get_installed_package_names()`.

```lua
local registry = require("mason-registry")
local installed_pkgs = registry.get_installed_packages()
-- Process installed_pkgs here
```

--------------------------------

### location:opt()

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-location.md

Gets the path to the optional data directory, optionally appending a path.

```APIDOC
## location:opt()

### Description
Gets the optional/optional data directory path.

### Method
`location:opt(path?: string): string`

### Parameters
#### Path Parameters
- **path** (string) - Optional - Optional subdirectory or file within opt

### Return Type
`string` - Path to `<root>/opt[/path]`
```

--------------------------------

### InstallHandle:is_idle

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-handle.md

Checks if the installation handle is currently in the idle state, meaning no operation is in progress.

```APIDOC
## is_idle()

### Description
Checks if the handle is in the idle state.

### Return Type
boolean
```

--------------------------------

### set_env()

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-location.md

Sets environment variables for the install location, including the MASON env var and modifying the PATH.

```APIDOC
## set_env(opts)

### Description
Sets environment variables for this install location.

### Parameters
#### Request Body
- **opts** (table) - Required - Environment options. Accepts a table with a `PATH` key.
  - **PATH** (string) - Optional - Specifies how to modify the PATH environment variable. Can be one of: `"append"`, `"prepend"`, or `"skip"`.

### Details
Sets `MASON` env var to the root directory. Modifies `PATH` according to the `PATH` option:
- `"prepend"` - Adds bin directory to start of PATH
- `"append"` - Adds bin directory to end of PATH
- `"skip"` - Does not modify PATH

### Return Type
`nil`

### Example
```lua
location:set_env({ PATH = "prepend" })
-- Now vim.env.MASON and vim.env.PATH are set
```
```

--------------------------------

### location:package()

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-location.md

Gets the path to the installed packages directory, optionally specifying a package name.

```APIDOC
## location:package()

### Description
Gets the installed packages directory path.

### Method
`location:package(pkg?: string): string`

### Parameters
#### Path Parameters
- **pkg** (string) - Optional - Optional package name

### Return Type
`string` - Path to `<root>/packages[/pkg]`

### Example
```lua
local all_packages_dir = location:package()
local specific_pkg_dir = location:package("rust-analyzer")
```
```

--------------------------------

### Create SystemPackage Instance

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/system-package.md

Instantiates a new SystemPackage object for a given system package name. This is the initial step to manage a system package.

```lua
local SystemPackage = require("mason-core.system-package")
local sfw = SystemPackage:new("sfw@latest")
```

--------------------------------

### pkg:get_install_path()

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Retrieves the full installation directory path for the package, optionally for a specific location.

```APIDOC
## pkg:get_install_path()

### Description
Gets the installation directory path for this package.

### Method
`pkg:get_install_path(location?: InstallLocation): string`

### Parameters
#### Path Parameters
- **location** (`InstallLocation`) - Optional - Specific install location (default: global)

### Return Type
`string` - Full path to package installation directory

### Example
```lua
local install_path = pkg:get_install_path()
print("Package installed at:", install_path)
```
```

--------------------------------

### Get names of all installed packages

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/registry-module.md

Use `get_installed_package_names` for an efficient way to retrieve a list of names for all currently installed packages. This avoids loading full Package classes, making it faster than `get_installed_packages`.

```lua
local registry = require("mason-registry")
local installed = registry.get_installed_package_names()
for _, name in ipairs(installed) do
    print("Installed:", name)
end
```

--------------------------------

### Initialize Mason with Configuration

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/mason-module.md

Call this function once during plugin initialization to set up Mason. It accepts an optional configuration table for UI elements, concurrent installers, and PATH management.

```lua
require("mason").setup({
    ui = {
        icons = {
            package_installed = "✓",
            package_pending = "➜",
            package_uninstalled = "✗"
        }
    },
    max_concurrent_installers = 4,
    PATH = "prepend"
})
```

--------------------------------

### Get Current Uninstallation Handle

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Retrieves the existing uninstallation handle for the package, if one is currently active.

```lua
pkg:get_uninstall_handle(): Optional<InstallHandle>
```

--------------------------------

### Programmatic UI Control Example

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/ui.md

Shows programmatic control of the Mason UI, including opening, setting views, and closing.

```lua
local ui = require("mason.ui")

-- Open UI and navigate to a specific view
ui.open()
vim.schedule(function()
    ui.set_view("package-list")
    ui.set_sticky_cursor("installing-section")
end)

-- Close after some operation
ui.close()
```

--------------------------------

### Prevent Assertion Errors in Package Operations

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/errors.md

Assertion errors occur due to precondition violations. This example shows how to check the state of a package before attempting installation or uninstallation.

```lua
if not pkg:is_installing() and not pkg:is_uninstalling() then
    if pkg:is_installable() then
        pkg:install()
    end
end
```

--------------------------------

### Example: Registering an update success listener

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/event-emitter.md

Shows how to use the `on` method to register a callback function that will be executed when the `update:success` event is emitted by the registry.

```lua
local registry = require("mason-registry")
registry:on("update:success", function(updated_registries)
    print("Update complete:", #updated_registries)
end)
```

--------------------------------

### Mason.nvim Setup with Firewall and Custom UI

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/configuration.md

Configure Mason.nvim with firewall settings and a custom user interface. This includes enabling the firewall, setting auto-managed mode, and customizing UI elements like icons, border style, and dimensions.

```lua
require("mason").setup({
    firewall = {
        enabled = true,
        auto_managed = true,
    },
    ui = {
        icons = {
            package_installed = "✓",
            package_pending = "➜",
            package_uninstalled = "✗",
        },
        border = "rounded",
        width = 100,
        height = 30,
    },
})

```

--------------------------------

### initialize()

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/install-location.md

Initializes the directory structure, creating all necessary subdirectories like bin, share, opt, packages, system_packages, staging, and registries.

```APIDOC
## initialize()

### Description
Initializes the directory structure, creating all necessary directories.

### Return Type
`Result` - Success if all directories created, failure with error otherwise

### Details
Creates all standard subdirectories (bin, share, opt, packages, system_packages, staging, registries)

### Example
```lua
local result = location:initialize()
if result:is_success() then
    print("Install location initialized")
end
```
```

--------------------------------

### Install Multiple Packages Concurrently

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/README.md

Install multiple specified packages if they are not already installed. This snippet iterates through a list of packages and installs them.

```lua
local a = require("mason-core.async")
local registry = require("mason-registry")

a.run(function()
    registry.refresh()
    local packages = {
        registry.get_package("rust-analyzer"),
        registry.get_package("lua-language-server"),
        registry.get_package("stylua"),
    }
    
    for _, pkg in ipairs(packages) do
        if not pkg:is_installed() then
            pkg:install()
        end
    end
end)
```

--------------------------------

### get_receipt

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Retrieves the installation receipt for a package, which contains metadata about its installation. It can optionally filter by a specific install location.

```APIDOC
## get_receipt()

### Description
Gets the installation receipt for this package.

### Method
`pkg:get_receipt(location?: InstallLocation): Optional<InstallReceipt>`

### Parameters
#### Path Parameters
- **location** (`InstallLocation`) - Optional - Specific install location (default: global)

### Return Type
`Optional<InstallReceipt>` - Optional containing installation receipt

### Details
Retrieves metadata about the installation from `mason-receipt.json`
```

--------------------------------

### Check if Package is Installing

Source: https://github.com/mason-org/mason.nvim/blob/main/_autodocs/api-reference/package.md

Determines if a package installation process is currently active. This prevents concurrent installation attempts.

```lua
pkg:is_installing(): boolean
```