rocks.txt

==============================================================================
rocks.nvim                                                          *rocks-nvim*


A luarocks plugin manager for Neovim.


==============================================================================
Table of Contents                                               *rocks-contents*

rocks.nvim ························································ |rocks-nvim|
 ·································································· |rocks-toml|
rocks.nvim commands ··········································· |rocks-commands|
rocks.nvim configuration ········································ |rocks-config|
Lua API for rocks.nvim extensions ·································· |rocks-api|
rocks.nvim API hooks ········································· |rocks-api-hooks|
rocks.nvim logging API ············································· |rocks-log|

==============================================================================
                                                                    *rocks-toml*

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 the |RockSpec|.

RockSpec                                                              *RockSpec*

    Fields: ~
        {name}           (string)    The name of the rock
        {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.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'
                                     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 'pim=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                              Search for updated rocks and install them.
                                     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`).
        {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).


==============================================================================
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


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


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
        {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,RockSpec|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_callback                                    *rock_handler_callback*

    Type: ~
        fun(report_progress:fun(message:string),report_error:fun(message:string))


An async callback that handles an operation on a rock.

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


                                                                   *api.install*
api.install({rock_name}, {version?}, {callback?})
    Invoke ':Rocks install' with a callback

    Parameters: ~
        {rock_name}  (rock_name)       #The rock name
        {version?}   (string)          The version of the rock to use
        {callback?}  (fun(rock:Rock))  Invoked upon successful completion


==============================================================================
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: