feat(lua-api): add rocks.packadd function

README.md

@@ -231,6 +231,7 @@ opt = true
 ```
 
 You can then load the plugin with the `:Rocks[!] packadd {rock}` command.
+Or, before rocks.nvim is initialised, with `require("rocks").packadd("<rock_name>")`.
 
 > [!NOTE]
 >

doc/rocks.txt

@@ -1,20 +1,39 @@
 ==============================================================================
 Table of Contents                                               *rocks.contents*
 
-rocks.nvim ····························································· |rocks|
+rocks.nvim ························································ |rocks.nvim|
+rocks.nvim Lua API ················································· |rocks.lua|
 rocks.nvim commands ··········································· |rocks.commands|
 rocks.nvim configuration ········································ |rocks.config|
-rocks.nvim Lua API ················································· |rocks.api|
+Lua API for rocks.nvim extensions ·································· |rocks.api|
 rocks.nvim API hooks ········································· |rocks.api.hooks|
 rocks.nvim logging API ············································· |rocks.log|
 
 ==============================================================================
-rocks.nvim                                                               *rocks*
+rocks.nvim                                                          *rocks.nvim*
 
 
 A luarocks plugin manager for Neovim.
 
 
+==============================================================================
+rocks.nvim Lua API                                                   *rocks.lua*
+
+rocks.packadd({rock_name}, {opts})                               *rocks.packadd*
+    Search for a rock with `opt = true`, add it to the runtimepath and source any plugin files found.
+
+    Parameters: ~
+        {rock_name}  (string)
+        {opts}       (rocks.PackaddOpts)
+
+
+rocks.PackaddOpts                                            *rocks.PackaddOpts*
+
+    Fields: ~
+        {bang?}              (boolean)  If `true`, rocks.nvim will only add the rock to the runtimepath, but not source any plugin or ftdetect scripts. Default: `false`.
+        {packadd_fallback?}  (boolean)  Fall back to the builtin |packadd|? Default `true`.
+
+
 ==============================================================================
 rocks.nvim commands                                             *rocks.commands*
 
@@ -68,7 +87,7 @@ RocksOpts                                                            *RocksOpts*
 
 
 ==============================================================================
-rocks.nvim Lua API                                                   *rocks.api*
+Lua API for rocks.nvim extensions                                    *rocks.api*
 
 
 The Lua API for rocks.nvim.

lua/rocks/api/init.lua

@@ -1,4 +1,4 @@
----@mod rocks.api rocks.nvim Lua API
+---@mod rocks.api Lua API for rocks.nvim extensions
 ---
 ---@brief [[
 ---

lua/rocks/init.lua

@@ -1,6 +1,6 @@
 ---@toc rocks.contents
 
----@mod rocks rocks.nvim
+---@mod rocks.nvim rocks.nvim
 ---
 ---@brief [[
 ---
@@ -13,10 +13,23 @@
 -- Version:    0.1.0
 -- License:    GPLv3
 -- Created:    05 Jul 2023
--- Updated:    27 Aug 2023
+-- Updated:    20 Mar 2024
 -- Homepage:   https://github.com/nvim-neorocks/rocks.nvim
 -- Maintainers: NTBBloodbath <bloodbathalchemist@protonmail.com>, Vhyrro <vhyrro@gmail.com>, mrcjkb <marc@jakobi.dev>
 
+---@mod rocks.lua rocks.nvim Lua API
+
 local rocks = {}
 
+---Search for a rock with `opt = true`, add it to the runtimepath and source any plugin files found.
+---@param rock_name string
+---@param opts rocks.PackaddOpts
+function rocks.packadd(rock_name, opts)
+    require("rocks.runtime").packadd(rock_name, opts)
+end
+
+---@class rocks.PackaddOpts
+---@field bang? boolean If `true`, rocks.nvim will only add the rock to the runtimepath, but not source any plugin or ftdetect scripts. Default: `false`.
+---@field packadd_fallback? boolean Fall back to the builtin |packadd|? Default `true`.
+
 return rocks

lua/rocks/runtime.lua

@@ -107,21 +107,19 @@ local function rtp_append(rtp_glob)
     _appended_rtp[rtp_glob] = true
 end
 
----@class (exact) PackaddOpts
----@field bang? boolean
----@field packadd_fallback? boolean Fall back to the builtin |packadd|? Default `true`.
+---@class PackaddOpts: rocks.PackaddOpts
 ---@field error_on_not_found? boolean Notify with an error message if no plugin could be found. Ignored if `packadd_fallback` is set to `true`.
 
 ---@param rock_name rock_name
----@param opts? PackaddOpts
+---@param opts? rocks.PackaddOpts
 function runtime.packadd(rock_name, opts)
     ---@cast rock_name rock_name
-    ---@cast opts table
     opts = vim.tbl_deep_extend("force", {
         bang = false,
         packadd_fallback = true,
         error_on_not_found = false,
     }, opts or {})
+    ---@cast opts PackaddOpts
     local rtp_glob = mk_rtp_glob(rock_name)
     rtp_append(rtp_glob)
     if opts.bang then