Jnvim

About

This is a Nvim configuration, configured in a modular, obsessively documented, portable and platform-independent way. Typed documentation is included.

This configuration uses lazy.nvim as the default plugin manager. Please read the Plugins section to get an understanding of how this works.

This configuration has its core entirely dependant on the user_api module, which provides a customized API which includes module checking, type checking, highlighting functions, options setting, keymap functions, annotations, and more. For more info make sure to check the User API section.

Requirements

(Optional, but recommended): A patched font

This config relies on essential plugins that improve the readability and understanding of how it works. For these to work, the following executables must be installed and in your $PATH:

git
lua-language-server
vscode-json-languageserver
ripgrep
(Optional (for telescope)):
- fzf
- fd
(Optional (for Lazy and/or Neorg)):
- luarocks
- pathspec

Structure

/lua
├── config/  <== Folder containing all Lua plugin configurations
│   ├── keymaps.lua  <== Setup default, non-plugin keymaps here
│   ├── lazy.lua  <== Plugin Installation. `plugin._spec` entry points are called here
│   └── util.lua  <== Utilities used in the file above (env checks, etc.)
├── plugin/  <==  Plugins are configured in this directory
│   ├── _spec/  <== Plugin categories are stored here in files serving as categories. `config.lazy` calls this  directory
│   │   ├── essentials.lua  <== Essential plugins. TREAT THIS ONE WITH CARE
│   │   ├── colorschemes.lua  <== Colorscheme plugins
│   │   ├── completion.lua  <== Completion plugins
│   │   ├── editing.lua  <== Editing enhancement plugins
│   │   ├── lsp.lua  <== LSP-related plugins
│   │   ├── neorg.lua  <== Neorg-related plugins
│   │   ├── syntax.lua  <== Syntax plugins
│   │   ├── telescope.lua  <== Telescope-related plugins
│   │   ├── treesitter.lua  <== Treesitter plugins
│   │   ├── ui.lua  <== UI-enhancement plugins
│   │   ├── utils.lua  <== Utilitary plugins
│   │   └── vcs.lua  <== Version Control plugins
│   ├── plugin1/  <== Arbitrary plugin #1
│   │   └── init.lua  <== Entry points + setup
│   ├── plugin2/  <== Arbitrary plugin #2
│   │   ├── init.lua  <== Entry points + setup
│   │   └── submoule.lua  <== Arbitrary submodule
│   └── ...  <==  More plugin configs...
├── user_api/  <== User API module
│   ├── init.lua  <== API entry points
│   ├── check/  <== Checker Functions
│   │   ├── init.lua  <== Entry points are defined here
│   │   ├── exists.lua  <== Existance checkers
│   │   └── value.lua  <== Value checkers
│   ├── commands.lua  <== User-defined commands
│   ├── distro/  <== OS Utilities
│   │   ├── init.lua  <== Entry points are defined here
│   │   └── archlinux.lua  <== Arch Linux utilities
│   ├── highlight.lua  <== Highlight Functions
│   ├── maps/  <== Mapping Utilities
│   │   ├── init.lua  <== Entry points are defined here
│   │   ├── kmap.lua  <== `vim.keymap.set` utilities
│   │   └── wk.lua  <== `which_key` utilities (regardless if installed or not)
│   ├── opts/  <== Vim Option Utilities
│   │   ├── init.lua  <== Entry points are defined here
│   │   ├── all_opts.lua  <== Internal checking utility [DO NOT TOUCH]
│   │   └── config.lua  <== Default options set here
│   ├── update.lua  <== Update utilities
│   ├── util/  <== Misc Utils
│   │   ├── init.lua  <== Entry points are defined here
│   │   ├── autocmd.lua  <== Autocommand utilities
│   │   ├── notify.lua  <== Notification utilities
│   │   └── string.lua  <== String operators/pre-defined lists
│   └── types/  <== Lua Type Annotations and Documentation
│       ├── init.lua  <== Entry points are defined here
│       ├── user/  <== User API Documentation
│       │   ├── init.lua  <== Entry points are defined here
│       │   ├── autocmd.lua  <== Autocommand annotations
│       │   ├── check.lua  <== `check` module annotations
│       │   ├── commands.lua  <== `commands` module annotations
│       │   ├── highlight.lua  <== `highlight` module annotations
│       │   ├── maps.lua  <== `maps` module annotations
│       │   ├── opts.lua  <== `opts` module annotations
│       │   ├── update.lua  <== `update` module annotations (WIP)
│       │   └── util.lua  <== `util` module annotations
└───────└── ...  <== Other annotations

Plugins

There's a lot of plugins included. The plugins are installed based on the files in the lua/plugin/_spec directory. You can create your own category file or expand from the existant files in said directory. Just make sure to read the lazy.nvim documentation for more info on how to install plugins.

Some of the included plugins...

which-key.nvim
mini.nvim
plenary.nvim
nvim-notify
nvim-treesitter
nvim-lspconfig
neoconf.nvim
lazydev.nvim
nvim-cmp
noice.nvim
telescope.nvim
LuaLine
nvim-tree.lua
nvim-web-devicons

The `user` API

The user API can be found in lua/user_api. It provides a bunch of functionalities to give easier code structures and to simplify configuration. It's still at an experimental phase, but it works as-is.

`user_api.types`

This submodule includes type annotations and documentation. It can be found in user_api/types.

You can include it by using the following code snippet:

require('user_api.types.module_name')
-- Or by using the entry point (not recommended):
require('user_api').types.module_name

For API-specific documentation, you can find them in the submodule user_api/types/user:

require('user_api.types.user.module_name')
-- Or by using the entry point (not recommended):
require('user_api').types.user.module_name

Each directory serves as an entry point for its pertinent files, sourced by the init.lua file in it.

`user_api.opts`

This submodule can be found at here. The options are defined in a default table to be processed by the funtion opts.setup().

To call the options:

local Opts1 = require('user_api.opts')
Opts1:setup()
--- Or by using the entry point:
local Opts2 = require('user_api').opts
Opts2:setup()

The setup() function optionally accepts a dictionary-like table with your own vim options. It overwrites some of the default options as defined in opts.lua. MAKE SURE THEY CAN BE ACCEPTED BY vim.opt.

As an example:

local User = require('user_api')
local Opts = User.opts

Opts:setup({
    completeopt = { 'menu', 'menuone', 'noselect', 'noinsert', 'preview' },
    nu = false, -- `:set nonumber`

    -- These equate to `:set tabstop=4 softtabstop=4 shiftwidth=4 expandtab`
    -- In the cmdline
    ts = 4,
    sts = 4,
    sw = 4,
    et = true,

    wrap = false,
})

`user_api.check`

This is the most important utility for this config. It currently provides a table with two sub-tables. Both used for many conditional checks, aswell as module handling.

These are the following:

user_api.check.value Used for value checking, differentiation and conditional code, aswell as for optional parameters in functions. It can be found in user_api/check/value.lua.

function	description	parameter types	return type
`is_nil`	Checks whether the input values are `nil` (AKA whether they even exist). By default it checks for a single value, but can be told to check for multiple by setting the 2nd param as `true`.	`var`: `unknown\|table`, `multiple`: `boolean` (default: `false`)	`boolean`
`is_str`	Checks whether the input values are of `string` type. By default it checks for a single value, but can be told to check for multiple by setting the 2nd param as `true`.	Same as `is_nil`.	`boolean`
`is_num`	Checks whether the input values are of `number` type. By default it checks for a single value, but can be told to check for multiple by setting the 2nd param as `true`.	Same as `is_nil`.	`boolean`
`is_bool`	Checks whether the input values are of `boolean` type. By default it checks for a single value, but can be told to check for multiple by setting the 2nd param as `true`.	Same as `is_nil`.	`boolean`
`is_fun`	Checks whether the input values are of `function` type. By default it checks for a single value, but can be told to check for multiple by setting the 2nd param as `true`.	Same as `is_nil`.	`boolean`
`is_tbl`	Checks whether the input values are of `table` type. By default it checks for a single value, but can be told to check for multiple by setting the 2nd param as `true`.	Same as `is_nil`.	`boolean`
`is_int`	Checks whether the input values are integers. By default it checks for a single value, but can be told to check for multiple by setting the 2nd param as `true`.	Same as `is_nil`.	`boolean`
`empty`	If input is a string, checks for an empty string. If input is number, checks for value `0`. If input is table, checks for an empty table. If other type return `true`.	`v`: `string\|number\|table`	`boolean`

user_api.check.exists Used for data existance checks, conditional module loading and fallback operations. It can be found in user_api/check/exists.lua.

function	description	parameter types	return type
`module`	Checks whether a `require(...)` statement is valid, given the input string. If 2nd parameter is `true`, attempt to return said statement if the module can be found.	`mod`: `string`, `return_mod`: `boolean` (default: `false`)	`boolean\|unknown`
`modules`	Checks whether multiple `require(...)` statements are valid, given the input strings. If 2nd parameter is `false` then check for each string, then stop and return false if one is not valid. If 2nd parameter is `true`, return a dictionary for each key as each input string, and a boolean as its respective value.	`mod`: `string[]`, `need_all`: `boolean` (default: `false`)	`boolean\|table<string, boolean>`
`vim_exists`	Checks whether a string or multiple strings are true statements using the Vimscript `exists()` function. If a string array is given, check each string and if any string is invalid, return `false`. Otherwise return `true` when finished.	`expr`: `string\|string[]`	`boolean`
`vim_has`	Checks whether a string or multiple are true statements when using the Vimscript `has()` function. If a string array is given, check each string and if any string is invalid, return `false`. Otherwise return `true` when finished.	`expr`: `string\|string[]`	`boolean`
`vim_isdir`	Checks whether the string is a directory.	`path`: `string`	`boolean`
`executable`	Checks whether one or multiple strings are executables found in `$PATH`. If a string array is given, check each string and if any string is invalid and the `fallback` parameter is a function then execute the fallback function. This function will return the result regardless of whether `fallback` has been set or not.	`exe`: `string\|string[]`, `fallback`: `fun()` (default: `nil`)	`boolean`

`user_api.maps`

This module provides keymapping utilities in a more complete, extensible and (hopefully) smarter way for the end user.

The maps.kmap module has the same function names for each mode:

maps.kmap.n(...): Same as :nmap
maps.kmap.i(...): Same as :imap
maps.kmap.v(...): Same as :vmap
maps.kmap.t(...): Same as :tmap
maps.kmap.o(...): Same as :omap
maps.kmap.x(...): Same as :xmap

`user_api.maps.kmap.desc`

There exists a kmap.desc() method that returns an option table with a description field and other fields corresponding to each parameter.

--- Returns a `vim.keymap.set.Opts` table
---@param msg: string Defaults to `'Unnamed Key'`
---@param silent? boolean Defaults to `true`
---@param bufnr? integer|nil Not included in output table unless explicitly set
---@param noremap? boolean Defaults to `true`
---@param nowait? boolean Defaults to `true`
---@param expr? boolean Defaults to `false`
---@return vim.keymap.set.Opts
require('user_api.maps.kmap').desc(msg, silent, bufnr, noremap, nowait, expr)

The function returns this table:

-- DO NOT COPY THIS DIRECTLY
{
    desc = 'Unnamed Key' or msg, -- First option is the default
    silent = true or false, -- First option is the default
    noremap = true or false, -- First option is the default
    nowait = true or false, -- First option is the default
    expr = false or true, -- First option is the default

    -- If buffer is passed as an argument:
    buffer = bufnr or 0,
}

`user_api.maps.wk`

The maps API also includes integration with which_key as user_api.maps.wk. It can be found found in user_api/maps.lua

This module creates mappings using custom-made functions that convert a specific type of mapping dictionary to a format compatible with which_key. To understand how this works refer to the aforementioned link to the which_key repository.

This module has the method wk.available(), which simply returns a boolean indicating whether which-key is installed and available to use. Use it, for example, to setup a fallback for setting keys, like in the following example:

local Kmap = require('user_api.maps.kmap')
local WK = require('user_api.maps.wk')

local my_keys = {
    --- Your maps go here...
}

if WK.available() then
    --- Use `WK`
else
    --- Use `Kmap`
end

If you try to use wk.register() despite not being available it'll return false and refuse to process your keymaps altogether.

If you want to convert a keymap table, you must first structure it as follows:

-- Using `vim.keymap.set()` (`User.maps.kmap`) as an example.

---@class KeyMapRhsOptsArr
---@field [1] User.Maps.Keymap.Rhs
---@field [2]? User.Maps.Keymap.Opts

---@alias KeyMapDict table<string, KeyMapRhsOptsArr> A dict with the key as lhs and the value as the class above

---@alias MapMode ('n'|'i'|'v'|'t'|'o'|'x') Vim Mode
---@alias MapModes MapMode[]

---@alias KeyMapModeDict table<MapMode, KeyMapDict>

-- Without modes
---@type KeyMapDict
local Keys1 = {
    ['lhs1'] = { 'rhs1', { desc = 'Keymap 1' } },
    ['lhs2'] = { function() print('this is rhs2') end, { desc = 'Keymap 1', noremap = true } }
}

-- With modes
---@type KeyMapModeDict
local Keys2 = {
    -- Normal Mode Keys
    n = {
        ['n_lhs1'] = { 'n_rhs1', { desc = 'Keymap 1' } },
        ['n_lhs2'] = { function() print('this is n_rhs2') end, { desc = 'Keymap 1', noremap = true } },
    },
    v = {
        ['v_lhs1'] = { 'v_rhs1', { desc = 'Keymap 1 (Visual Mode)' } },
    }
}

You can then pass this dictionary to user_api.maps.map_dict():

Example

-- Following the code above...

local map_dict = require('user_api.maps').map_dict

-- NOTE: Third parameter is `false` because the `Keys1` table doesn't tell what mode to use
map_dict(Keys1, 'wk.register', false, 'n')

-- NOTE: Third parameter is `true` because the `Keys2` table tells us what modes to use,
-- so fourth param can be `nil`
map_dict(Keys2, 'wk.register', true, nil)

You can also process keymap groups the following way:

---@class RegPfx
---@field group string The map group name. Should look like `'+Group'`
---@field hidden? boolean Whether to show the map in `which-key`
---@field mode? MapModes @see user_api.types.user.maps

---@alias RegKeysNamed table<string, RegKeysNamed>

---@type RegKeysNamed
local Names = {
    ['<leader>X'] = { group = '+Group X' },
    ['<leader>X1'] = { group = '+Subgroup X1' },

    ['<leader>t'] = { group = '+Group t' },
}

-- If `which_key` is available
if require('user_api.maps.wk').available() then
    require('user_api.maps').map_dict(Names, 'wk.register', false, 'n')
end

This API component is in early design so it will be simpler and more complete in the future.

`user_api.highlight`

This module provides utilities for setting highlights in an easier way. It can be found in user_api/highlight.lua.

A description will be pending until further notice, i.e. when the module is structured in a satisfactory manner.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Jnvim

Table Of Contents

About

Requirements

Structure

Plugins

The `user` API

`user_api.types`

`user_api.opts`

`user_api.check`

`user_api.maps`

`user_api.maps.kmap.desc`

`user_api.maps.wk`

`user_api.highlight`

Files

README.md

Latest commit

History

README.md

File metadata and controls

Jnvim

Table Of Contents

About

Requirements

Structure

Plugins

The user API

user_api.types

user_api.opts

user_api.check

user_api.maps

user_api.maps.kmap.desc

user_api.maps.wk

user_api.highlight

The `user` API

`user_api.types`

`user_api.opts`

`user_api.check`

`user_api.maps`

`user_api.maps.kmap.desc`

`user_api.maps.wk`

`user_api.highlight`