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
    • mkPluginsFromInputs
    • 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

mkPluginsFromInputs

mkPluginsFromInputs is a helper function that converts flake inputs (starting by "plugin-" by default) into vimPlugins.

Example:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    sloth-flake.url = "github:lemarsu/sloth-flake.nvim";
    utils.url = "github:numtide/flake-utils";

    plugin-base64 = {
      url = "github:moevis/base64.nvim";
      flake = false;
    };

    plugin-cellular-automaton = {
      url = "github:eandrju/cellular-automaton.nvim";
      flake = false;
    };
  };
  outputs = {utils, sloth-flake, ...}@inputs: let
    fu = utils.lib;
  in fu.eachDefaultSystem (system: let
    plugins = sloth-flake.lib.mkPluginsFromInputs {
      inherit pkgs inputs;
    };
  in {
    packages = rec {
      default = neovim;
      neovim = pkgs.callPackage ./package.nix {
        # By adding `plugins` here, we can use `with plugins; base64 cellular-automaton`, 
        inherit plugins sloth-flake;
      };
    };
  };
}

The function accepts the following attributes:

• pkgs REQUIRED the nixpkgs set.
• inputs REQUIRED the inputs from a flake.
• predicate optional predicate to filter input by name. By default, it's filter inputs with hasPrefix "plugin-".
• nameMap optional function to change the key of the input in the resulting set. By default, the 7 first letters are removed, so to remove the "plugin-" prefix.
• buildVimPlugin optional function used to build the plugin. Defaults to pkgs.vimUtils.buildVimPlugin.

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
init	null	The init.lua of your config (string, path or init config object)¹
runtime	{}	Your Runtime configuration (see below)
dependencies	[]	A list of your dependencies (see below)
dependenciesExtraArgs	{}	Extra arguments to load your dependencies in other files
extraLuaPackages	null	Extra lua packages needed for the plugin
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

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

The init configuration object accepts the following properties:

name	default	description
init	null	Lua code call before plugins init. String or path.
postInit	null	Lua code call after plugins init and before plugin config. String or path.
config	null	Luas cod call after plugins config. String or path.

The Runtime configuration object accepts the following properties:

name	default	description
version	null	The version of your runtime
src	null	The content of your runtime

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³
extraLuaPackages	null	Extra lua packages needed for the plugin
lazy	false	Should the plugin be loaded lazily
cmd	[]	Command to put as place_holder to load the lazy plugin⁴
ft	[]	Filetype to watch to load the lazy plugin⁴
events	[]	Events to watch to load the lazy plugin⁴⁵
keymaps	[]	Keymaps that when press will load the lazy 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.

⁵ Events can be a string, an Event object or a list of either. You can represent a simple event name and pattern with the following string format : "BufRead *.md".

⁶ Keymaps can be a string, an Keymap object or a list of either.

The Event configuration object accepts the following properties:

name	default	description
name	N/A	The name of the event as string or list of string REQUIRED
pattern	null	Pattern (as string or list of string) associated to the event

The Keymap configuration object accepts the following properties:

name	default	description
mode	"n"	The mode of the keymap as string or list of string
mapping	N/A	The actual mapping REQUIRED

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.