rocks.txt

==============================================================================
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://nvim-neorocks.github.io/rocks-binaries/" ]`
 - `dev_servers`: List of dev binary servers.
   Default: `[ "https://nvim-neorocks.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://nvim-neorocks.github.io/rocks-binaries/"
     ]
     dev_servers = [
         "https://nvim-neorocks.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)
                                                                          Whether to auto-sync if plugins cannot be found on startup. (Default: `false`).
                                                                          If unset, rocks.nvim will prompt to sync.
        {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<rock_name, Rock[]>`

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<rock_name, OutdatedRock>`.


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<rock_name,Rock[]>)  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<rock_name,OutdatedRock>)  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<rock_name,Rock[]>))  @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<rock_name,T>)
        {query}     (string)
        {opts?}     (FuzzyFilterOpts)

    Returns: ~
        (table<rock_name,T>)


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<rock_name,Rock>))  @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<rock_name,RockSpec>)  The `[rocks]` entries
        {plugins?}      (table<rock_name,RockSpec>)  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<rock_name,RockSpec>)


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*
api.register_rocks_subcommand({name}, {cmd})
    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_name,TomlRockSpec|rock_version>


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_name,RockSpec>):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*
api.install({rock_name}, {version?}, {opts?})
    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-<extension>.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<rock_name,RockSpec>))
        {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: