sloth-flake.nvim

A neovim plugin and configuration management plugin, highly inspired by lazy, using nix.

• Description
• Features
• SemVer
• Installation
  • Flake installation
• Usage
• Documentation
  • nix
    • mkNeovimPkg
  • neovim (lua)
    • Using default init.lua
    • Using your own init.lua
    • :Sloth command
      • list subcommand
      • load subcommand
      • version subcommand
    • API

Description

sloth-flake.nvim is an alpha software. Please use caution when using it.

sloth-flake.nvim is both

• a neovim plugin to manage your plugins
• a nix flake to build your neovim package with your own configuration and plugins.

ℹ️ If you never heard of nix or you never used it, then this plugin is not for you.

Features

• Declare your plugin via nix files
  • Declare nix package as dependencies
  • Generate nix package from local files
• Generate default init.lua
• Accepts your own init.lua
• Lazy load your plugins
  • on command
  • on filetype
  • on event
  • on keybinding
• load plugins in order (via plugin dependencies property)
• Have a :Sloth command to load or query your plugins
• Generate spell files on build (maybe)

SemVer

This project will respect SemVer in the end, but will adopt a slightly different semantics in the beginning.

This project is considered alpha as long as the version is 0.0.x, therefore you can expect breaking change on each version. You can see the version as 0.0.MAJOR.

When this project will hit 0.1.0, the project will be in beta phase. If a new version have breaking change, then it will be 0.2.0 and 0.1.1 otherwise. You can see the version as 0.MAJOR.MINOR.

When this project will hit 1.0.0, it will then follow full SemVer (MAJOR.MINOR.PATCH).

Installation

Only flake installation is supported.

Flake installation

Import sloth-flake.nvim flake latest version:

inputs.sloth-flake.url = "github:lemarsu/sloth-flake.nvim";

You can give a specific version:

inputs.sloth-flake.url = "github:lemarsu/sloth-flake.nvim?tag=0.0.5";

Usage

Once installed, you can call the sloth-flake.lib.mkNeovimPkg to build your neovim package.

mkNeovimPkg requires a set as argument with at least pkgs that represents your nixpkgs.

sloth-flake.lib.mkNeovimPkg {
  inherit pkgs;
  viAlias = true;
  vimAlias = true;
  runtime = {
    version = "0.1";
    src = sloth-flake.lib.sourcesWith ./. [
      ./after
      ./colors
      ./ftplugin
      ./lua
      ./plugin
      ./queries
    ];
  };

  dependencies = [
    rust-vim
    vim-openscad
    ./lsp
    {
      plugin = telescope-nvim;
      config = ./telescope.lua;
    }
  ];
}

Documentation

nix

mkNeovimPkg

mkNeovimPkg requires only the pkgs argument.

Here's a list of all accepted arguments

name	default	description
pkgs	N/A	The nixpkgs set. REQUIRED
package	pkgs.neovim-unwrapped	The unwrapped neovim package to use
runtime	{}	Your Runtime configuration (see below)
dependencies	[]	A list of your dependencies (see below)
dependenciesExtraArgs	{}	Extra arguments to load your dependencies in other files
viAlias	false	Wether to create a vi alias to run neovim
vimAlias	false	Wether to create a vim alias to run neovim
vimdiffAlias	false	Wether to create a vimdiff alias to run neovim in diff mode
nvimdiffAlias	false	Wether to create a nvimdiff alias to run neovim in diff mode

The Runtime configuration object accepts the following properties:

name	default	description
version	null	The version of your runtime
init	null	The init.lua of your config¹
src	null	The content of your runtime

¹ If you give your own init.lua, you'll have to call sloth-flake lua plugin yourself. See more below.

The dependencies is a list of element of either:

• path: the path of the file to load other dependencies
• package: a nix package of a neovim/vim plugin
• Plugin configuration object: an object describing a plugin and its configuration.

The Plugin configuration object accepts the following properties:

name	default	description
plugin	N/A	The plugin to load² REQUIRED
init	null	Lua code (as string of path) to call before loading the plugin
config	null	Lua code (as string of path) to call after loading the plugin
dependencies	[]	The plugin dependencies³
lazy	false	Should the plugin be loaded lazily
cmd	[]	Command to put as place_holder to lazy load the plugin⁴
ft	[]	Filetype to watch to lazy load the plugin⁴

² The plugin can be either a nix package or an object with only name and src as properties. The latter will be used to create a nix package of your plugin on the fly.

³ nix handles the installation of your plugin, therefore, this list is NOT to declare dependencies that the nix package of the plugin doesn't know. This will tell sloth-flake in what order your plugins should be loaded.

⁴ Setting this property implicitly set lazy to true.

neovim (lua)

Using default init.lua

If your neovim configuration is only plugin configuration, sloth-flake will give you a default init.lua that will load sloth-flake plugin that will, in turn, load all your plugins. If you need more control over configuration startup, please look at next section.

Using your own init.lua

You can provide your init.lua, but you must call sloth-flake your self.

-- Requiring sloth-flake plugin
local sloth_flake = require 'sloth-flake'

-- Before this point, no plugin nor configuration is loaded
-- You can configure what you need before loading any plugin.
sloth_flake.setup {
  -- This function is called after calling all optional `init` functions of your plugins
  -- but before loading those plugins
  post_init = function()
    -- [...]
  end
}

-- From here, your plugins are loaded and their optional `config` function called

:Sloth command

sloth-flake give a Sloth command that you can call to gather some informations about or load your plugins.

Usage: Sloth [command] [args...]

If no arguments are given, the Sloth command will call the list subcommand.

list subcommand

Summary: List plugins.

Usage: Sloth list [filter]

• filter: filter the list of plugins.
  • all: list all declared plugins. Same as if no filter is given.
  • loaded: list only loaded plugins.
  • notloaded: list only not loaded plugins.

load subcommand

Summary: Load lazy plugins.

Usage: Sloth load <plugin> [plugin [...]]

• plugin: a plugin to load

version subcommand

Summary: Return Sloth version

Usage: Sloth version

API

The lua API is not really defined yet. This documentation will be completed then.