============================================================================== rocks.nvim *rocks-nvim* A luarocks plugin manager for Neovim. ============================================================================== Table of Contents *rocks-contents* rocks.nvim ························································ |rocks-nvim| ·································································· |rocks-toml| ·························································· |rocks-toml.plugins| ························································· |rocks-toml.luarocks| rocks.nvim commands ··········································· |rocks-commands| rocks.nvim configuration ········································ |rocks-config| experimental features ····································· |rocks.experimental| rocks.nvim |User| |event|s ·································· |rocks.user-event| Lua API for rocks.nvim extensions ·································· |rocks-api| rocks.nvim API hooks ········································· |rocks-api-hooks| rocks.nvim logging API ············································· |rocks-log| ============================================================================== *rocks-toml* ============================================================================== *rocks-toml.plugins* rocks.nvim stores information about installed plugins in the `[plugins]` or `[rocks]` entries. `[plugins]` can be managed automatically using |rocks-commands|. Example: >toml [plugins] "rocks.nvim" = "2.0.0" neorg = { version = "8.0.0", opt = true } [plugins."sweetie.nvim"] version = "2.0.0" opt = true < For the foll spec, refer to |TomlRockSpec|. TomlRockSpec *TomlRockSpec* Fields: ~ {version?} (string) The rock version {opt?} (boolean) Set to `true` to prevent rocks from being loaded eagerly {pin?} (boolean) Pinned rocks will not be updated {install_args?} (string[]) Additional args to pass to `luarocks install` {string} (unknown) Fields that can be added by external modules NOTE: Currently, all options except for `install_args` can be passed to `:Rocks install`. ============================================================================== *rocks-toml.luarocks* You can configure how rocks.nvim interacts with luarocks using the `[luarocks]` setting. Configuration options: - `servers`: List of binary servers. Default: `[ "https://luarocks.org/manifests/neorocks/", "https://lumen-oss.github.io/rocks-binaries/" ]` - `dev_servers`: List of dev binary servers. Default: `[ "https://lumen-oss.github.io/rocks-binaries-dev/" ]` You can disable the default binary servers by setting these to empty lists. Example: >toml [luarocks] servers = [ "https://luarocks.org/manifests/neorocks/", "https://lumen-oss.github.io/rocks-binaries/" ] dev_servers = [ "https://lumen-oss.github.io/rocks-binaries-dev/" ] < ============================================================================== rocks.nvim commands *rocks-commands* `:Rocks[!] {command {args?}}` command action ------------------------------------------------------------------------------ install {rock} {version?} {args[]?} Install {rock} with optional {version} and optional {args[]}. Example: ':Rocks install neorg 8.0.0 opt=true' Will install or update to the latest version if called without {version}. args (optional): - opt={true|false} Rocks that have been installed with 'opt=true' can be sourced with |packadd|. - pin={true|false} Rocks that have been installed with 'pin=true' will be ignored by ':Rocks update'. Use 'Rocks! install ...' to skip prompts. prune {rock} Uninstall {rock} and its stale dependencies, and remove it from rocks.toml. sync Synchronize installed rocks with rocks.toml. It may take more than one sync to prune all rocks that can be pruned. update {rock?} Search for updated rocks and install them. If called with the optional {rock} argument, only {rock} will be updated. Use 'Rocks! update` to skip prompts. with breaking changes. edit Edit the rocks.toml file. pin {rock} Pin {rock} to the installed version. Pinned rocks are ignored by ':Rocks update'. unpin {rock} Unpin {rock}. log Open the log file. ============================================================================== rocks.nvim configuration *rocks-config* You can set rocks.nvim configuration options via `vim.g.rocks_nvim`. > ---@type RocksOpts vim.g.rocks_nvim < *vim.g.rocks_nvim* *g:rocks_nvim* RocksOpts *RocksOpts* Fields: ~ {rocks_path?} (string) Local path in your file system to install rocks (Default: a `rocks` directory in `vim.fn.stdpath("data")`). {config_path?} (string) Rocks declaration file path (Default: `rocks.toml`) in `vim.fn.stdpath("config")`. {luarocks_binary?} (string) Luarocks binary path. Defaults to the bundled installation if executable. {lazy?} (boolean) Whether to query luarocks.org lazily (Default: `false`). Setting this to `true` may improve startup time, but features like auto-completion will lag initially. {dynamic_rtp?} (boolean) Whether to automatically add freshly installed plugins to the 'runtimepath'. (Default: `true` for the best default experience). {generate_help_pages?} (boolean) Whether to re-generate plugins help pages after installation/upgrade. (Default: `true`). {update_remote_plugins?} (boolean) Whether to update remote plugins after installation/upgrade. (Default: `true`). {auto_sync?} (boolean|"disable") Whether to auto-sync if plugins cannot be found on startup. (Default: `false`). - `false` or unset: Prompt before syncing (default). - `true`: Sync automatically without prompting. - `'disable'` Do not prompt and do not sync plugins. {reinstall_dev_rocks_on_update?} (boolean) Whether to reinstall 'dev' rocks on update (Default: `true`, as rocks.nvim cannot determine if 'dev' rocks are up to date). {enable_luarocks_loader?} (boolean) Whether to use the luarocks loader to support multiple dependencies (Default: `true`). {luarocks_config?} (table) Extra luarocks config options. rocks.nvim will create a default luarocks config in `rocks_path` and merge it with this table (if set). {experimental_features?} (rocks.ExperimentalFeature[]) List of experimental features to enable. See |rocks.experimental|. ============================================================================== experimental features *rocks.experimental* WARNING: Experimental features may change or be removed without a major SemVer version bump. rocks.ExperimentalFeature *rocks.ExperimentalFeature* Values: ~ ext_module_dependency_stubs Install rocks stubs when using extensions like rocks-git.nvim or rocks-dev.nvim so that luarocks recognises them as dependencies. ============================================================================== rocks.nvim |User| |event|s *rocks.user-event* The following |User| |event|s are available: RocksInstallPost Invoked after installing or updating a rock The `data` is of type |rocks.user-events.data.RocksInstallPost|. RocksCachePopulated Invoked when the luarocks rocks cache has been populated. The `data` is a reference to the cached rocks, of type `table` RocksRemovableRocksCachePopulated Invoked when the removable rocks cache has been populated. The `data` is a reference to the rock names, of type `string[]` RocksOutdatedRocksCachePopulated Invoked when the outdated rocks cache has been populated. The `data` is a reference to the outdated rocks, of type `table`. To create an autocommand for an event: >lua vim.api.nvim_create_autocmd("User", { pattern = "RocksInstallPost", callback = function(ev) ---@type rocks.user-events.data.RocksInstallPost local data = ev.data -- ... end, }) < *rocks.user-events.data.RocksInstallPost* rocks.user-events.data.RocksInstallPost Fields: ~ {spec} (RockSpec) {installed} (Rock) ============================================================================== Lua API for rocks.nvim extensions *rocks-api* The Lua API for rocks.nvim. Intended for use by modules that extend this plugin. rock_name *rock_name* Type: ~ string RockSpec : TomlRockSpec *RockSpec* Fields: ~ {name} (string) The name of the rock Rock *Rock* Fields: ~ {name} (rock_name) {version} (string) api.try_get_cached_rocks() *api.try_get_cached_rocks* Tries to get the cached rocks. Returns an empty list if the cache has not been populated or no connection to luarocks.org can be established. Will spawn an async task to attempt to populate the cache if it is not ready. Returns: ~ (table) rocks OutdatedRock : Rock *OutdatedRock* Fields: ~ {target_version} (string) api.try_get_cached_outdated_rocks() *api.try_get_cached_outdated_rocks* Tries to get the cached outdated rocks. Returns an empty list if the cache has not been populated or no connection to luarocks.org can be established. Will spawn an async task to attempt to populate the cache if it is not ready. Returns: ~ (table) rocks api.query_luarocks_rocks({callback}) *api.query_luarocks_rocks* Queries luarocks.org for rocks and passes the rocks to a callback. Invokes the callback with an empty table if no rocks are found or no connection to luarocks.org can be established. Parameters: ~ {callback} (fun(rocks:table)) @async FuzzyFilterOpts *FuzzyFilterOpts* Fields: ~ {sort?} (boolean) Whether to sort the results (default: `true`). *api.fuzzy_filter_rock_tbl* api.fuzzy_filter_rock_tbl({rock_tbl}, {query}, {opts?}) @generic T Parameters: ~ {rock_tbl} (table) {query} (string) {opts?} (FuzzyFilterOpts) Returns: ~ (table) api.query_installed_rocks({callback}) *api.query_installed_rocks* Query for installed rocks. Passes the installed rocks (table indexed by name) to a callback when done. Parameters: ~ {callback} (fun(rocks:table)) @async api.get_rocks_toml_path() *api.get_rocks_toml_path* Gets the rocks.toml file path. Note that the file may not have been created yet. Returns: ~ (string) rocks_toml_file_path RocksToml *RocksToml* Fields: ~ {rocks?} (table) The `[rocks]` entries {plugins?} (table) The `[plugins]` entries {servers?} (string[]) {dev_servers?} (string[]) {import?} (string[]) {string} (unknown) Fields that can be added by external modules api.get_rocks_toml() *api.get_rocks_toml* Returns a table with the parsed rocks.toml file. If the file doesn't exist a file with the default configuration will be created. Returns: ~ (RocksToml) api.get_user_rocks() *api.get_user_rocks* Returns a table with the rock specifications parsed from the rocks.toml file. If the file doesn't exist a file with the default configuration will be created. Returns: ~ (table) RocksCmd *RocksCmd* Fields: ~ {impl} (fun(args:string[],opts:vim.api.keyset.user_command)) The command implementation {complete?} (fun(subcmd_arg_lead:string):string[]) Command completions callback, taking the lead of the subcommand's arguments api.register_rocks_subcommand({name}, {cmd}) *api.register_rocks_subcommand* Register a `:Rocks` subcommand. Parameters: ~ {name} (string) The name of the subcommand to register {cmd} (RocksCmd) rock_config_table *rock_config_table* Type: ~ table rock_version *rock_version* Type: ~ string MutRocksTomlRef *MutRocksTomlRef* A mutable Lua representation of rocks.toml. May be extended by external modules. Fields: ~ {rocks?} (rock_config_table) {plugins?} (rock_config_table) {string} (unknown) rock_handler.on_success.Opts *rock_handler.on_success.Opts* Fields: ~ {action} ("install"|"prune") {rock} (Rock) The rock stub to install or prune. {dependencies?} (string[]) The dependency constraints (e.g. { 'foo >= 1.0.0', }). rock_handler_callback *rock_handler_callback* Type: ~ fun(on_progress:fun(message:string),on_error:fun(message:string),on_success?:fun(opts:rock_handler.on_success.Opts)) An async callback that handles an operation on a rock. - The `on_success` callback is optional for backward compatibility. RockHandler *RockHandler* Fields: ~ {get_sync_callback?} (fun(spec:RockSpec):rock_handler_callback|nil) Return a function that installs or updates the rock, or `nil` if the handler cannot or does not need to sync the rock. {get_prune_callback?} (fun(specs:table):rock_handler_callback|nil) Return a function that prunes unused rocks, or `nil` if the handler cannot or does not need to prune any rocks. {get_install_callback?} (fun(rocks_toml:MutRocksTomlRef,arg_list:string[]):rock_handler_callback|nil) Return a function that installs a rock, or `nil` if the handler cannot install this rock. The `rocks_toml` table is mutable, and should be updated with the installed rock by the returned callback. {get_update_callbacks?} (fun(rocks_toml:MutRocksTomlRef):rock_handler_callback[]) Return a list of functions that update user rocks, or an empty list if the handler cannot or does not need to update any rocks. The `rocks_toml` table is mutable, and should be updated by the returned callbacks. api.register_rock_handler({handler}) *api.register_rock_handler* Parameters: ~ {handler} (RockHandler) api.source_runtime_dir() *api.source_runtime_dir* @deprecated Use the rtp.nvim luarock rocks.InstallOpts *rocks.InstallOpts* Fields: ~ {skip_prompts?} (boolean) Whether to skip any "search 'dev' manifest prompts {cmd?} ("install"|"update") Command used to invoke this function. Default: `'install'` {config_path?} (string) Config file path to use for installing the rock relative to the base config file {callback?} (fun(rock:Rock)) Invoked upon successful completion api.install({rock_name}, {version?}, {opts?}) *api.install* Invoke ':Rocks install' Parameters: ~ {rock_name} (rock_name) #The rock name {version?} (string) The version of the rock to use {opts?} (rocks.InstallOpts) Installation options ============================================================================== rocks.nvim API hooks *rocks-api-hooks* Hooks that rocks.nvim modules can inject behaviour into. Intended for use by modules that extend this plugin. Preload hooks *rocks.hooks.preload* By providing a module with the pattern, `rocks-.rocks.hooks.preload`, rocks.nvim modules can execute code before rocks.nvim loads any plugins (but after they have been added to the runtimepath). The module should return a table of type |rocks.hooks.Preload|. To be able to use this feature, a rocks.nvim extension *must* be named with a 'rocks-' prefix. rocks.hooks.RockSpecModifier *rocks.hooks.RockSpecModifier* Fields: ~ {hook} (rock_spec_modifier) {type} ("RockSpecModifier") rocks.hooks.Action *rocks.hooks.Action* Fields: ~ {hook} (fun(user_rocks:table)) {type} ("Action") rocks.hooks.Preload *rocks.hooks.Preload* Type: ~ rocks.hooks.RockSpecModifier|rocks.hooks.Action rock_spec_modifier *rock_spec_modifier* Type: ~ fun(rock:RockSpec):RockSpec ============================================================================== rocks.nvim logging API *rocks-log* The logging interface for rocks.nvim. Intended to be used by external modules. log.trace() *log.trace* log.debug() *log.debug* log.info() *log.info* log.warn() *log.warn* log.error() *log.error* log.set_level() *log.set_level* See: ~ |vim.log.levels| Usage: ~ >lua log.set_level(vim.log.levels.DEBUG) < vim:tw=78:ts=8:noet:ft=help:norl: