feat: add setting to control PATH modification (#514)

Closes #509.

5 files changed, 131 insertions, 86 deletions

diff --git a/README.md b/README.md
index da252049..f21aa12e 100644
--- a/README.md
+++ b/README.md
@@ -152,6 +152,41 @@ require("mason").setup({
 
 ```lua
 local DEFAULT_SETTINGS = {
+    -- The directory in which to install packages.
+    install_root_dir = path.concat { vim.fn.stdpath "data", "mason" },
+
+    -- 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",
+
+    pip = {
+        -- 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 = {},
+    },
+
+    -- 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,
+
+    -- 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,
+
+    github = {
+        -- 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",
+    },
+
     ui = {
         -- Whether to automatically check for new versions when opening the :Mason window.
         check_outdated_packages_on_open = true,
@@ -189,33 +224,5 @@ local DEFAULT_SETTINGS = {
             apply_language_filter = "<C-f>",
         },
     },
-
-    -- The directory in which to install packages.
-    install_root_dir = path.concat { vim.fn.stdpath "data", "mason" },
-
-    pip = {
-        -- 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 = {},
-    },
-
-    -- 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,
-
-    -- 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,
-
-    github = {
-        -- 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",
-    },
 }
 ```
diff --git a/doc/mason.txt b/doc/mason.txt
index eaeac3cb..3d8b4674 100644
--- a/doc/mason.txt
+++ b/doc/mason.txt
@@ -168,6 +168,41 @@ Example:
                                                       *mason-default-settings*
 
     local DEFAULT_SETTINGS = {
+        -- The directory in which to install packages.
+        install_root_dir = path.concat { vim.fn.stdpath "data", "mason" },
+
+        -- 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",
+
+        pip = {
+            -- 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 = {},
+        },
+
+        -- 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,
+
+        -- 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,
+
+        github = {
+            -- 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",
+        },
+
         ui = {
             -- Whether to automatically check for new versions when opening the :Mason window.
             check_outdated_packages_on_open = true,
@@ -205,34 +240,6 @@ Example:
                 apply_language_filter = "<C-f>",
             },
         },
-
-        -- The directory in which to install packages.
-        install_root_dir = path.concat { vim.fn.stdpath "data", "mason" },
-
-        pip = {
-            -- 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 = {},
-        },
-
-        -- 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,
-
-        -- 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,
-
-        github = {
-            -- 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",
-        },
     }
 
 
diff --git a/lua/mason/init.lua b/lua/mason/init.lua
index eb64d136..37926acc 100644
--- a/lua/mason/init.lua
+++ b/lua/mason/init.lua
@@ -10,7 +10,11 @@ function M.setup(config)
         settings.set(config)
     end
 
-    vim.env.PATH = path.bin_prefix() .. platform.path_sep .. vim.env.PATH
+    if settings.current.PATH == "prepend" then
+        vim.env.PATH = path.bin_prefix() .. platform.path_sep .. vim.env.PATH
+    elseif settings.current.PATH == "append" then
+        vim.env.PATH = vim.env.PATH .. platform.path_sep .. path.bin_prefix()
+    end
 
     require "mason.api.command"
 end
diff --git a/lua/mason/settings.lua b/lua/mason/settings.lua
index 0a980235..afe77953 100644
--- a/lua/mason/settings.lua
+++ b/lua/mason/settings.lua
@@ -4,6 +4,41 @@ local M = {}
 
 ---@class MasonSettings
 local DEFAULT_SETTINGS = {
+    -- The directory in which to install packages.
+    install_root_dir = path.concat { vim.fn.stdpath "data", "mason" },
+
+    -- 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",
+
+    pip = {
+        -- 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 = {},
+    },
+
+    -- 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,
+
+    -- 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,
+
+    github = {
+        -- 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",
+    },
+
     ui = {
         -- Whether to automatically check for new versions when opening the :Mason window.
         check_outdated_packages_on_open = true,
@@ -41,34 +76,6 @@ local DEFAULT_SETTINGS = {
             apply_language_filter = "<C-f>",
         },
     },
-
-    -- The directory in which to install packages.
-    install_root_dir = path.concat { vim.fn.stdpath "data", "mason" },
-
-    pip = {
-        -- 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 = {},
-    },
-
-    -- 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,
-
-    -- 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,
-
-    github = {
-        -- 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",
-    },
 }
 
 M._DEFAULT_SETTINGS = DEFAULT_SETTINGS
diff --git a/tests/mason/setup_spec.lua b/tests/mason/setup_spec.lua
index f7abf125..07f3b671 100644
--- a/tests/mason/setup_spec.lua
+++ b/tests/mason/setup_spec.lua
@@ -3,9 +3,29 @@ local mason = require "mason"
 local path = require "mason-core.path"
 
 describe("mason setup", function()
+    before_each(function()
+        vim.env.PATH = "/usr/local/bin:/usr/bin"
+    end)
+
     it("should enhance the PATH environment", function()
         mason.setup()
-        assert.is_true(vim.startswith(vim.env.PATH, path.bin_prefix()))
+        assert.equals(("%s:/usr/local/bin:/usr/bin"):format(path.bin_prefix()), vim.env.PATH)
+    end)
+
+    it("should prepend the PATH environment", function()
+        mason.setup { PATH = "prepend" }
+        assert.equals(("%s:/usr/local/bin:/usr/bin"):format(path.bin_prefix()), vim.env.PATH)
+    end)
+
+    it("should append PATH", function()
+        mason.setup { PATH = "append" }
+        assert.equals(("/usr/local/bin:/usr/bin:%s"):format(path.bin_prefix()), vim.env.PATH)
+    end)
+
+    it("shouldn't modify PATH", function()
+        local PATH = vim.env.PATH
+        mason.setup { PATH = "skip" }
+        assert.equals(PATH, vim.env.PATH)
     end)
 
     it("should set up user commands", function()