367 lines
14 KiB
Plaintext
367 lines
14 KiB
Plaintext
*mini.statusline* Statusline
|
|
*MiniStatusline*
|
|
|
|
MIT License Copyright (c) 2021 Evgeni Chasnovski
|
|
|
|
==============================================================================
|
|
|
|
Features:
|
|
- Define own custom statusline structure for active and inactive windows.
|
|
This is done with a function which should return string appropriate for
|
|
|statusline|. Its code should be similar to default one with structure:
|
|
- Compute string data for every section you want to be displayed.
|
|
- Combine them in groups with |MiniStatusline.combine_groups()|.
|
|
|
|
- Built-in active mode indicator with colors.
|
|
|
|
- Sections can hide information when window is too narrow (specific window
|
|
width is configurable per section).
|
|
|
|
# Dependencies ~
|
|
|
|
Suggested dependencies (provide extra functionality, will work without them):
|
|
|
|
- Nerd font (to support extra icons).
|
|
|
|
- Enabled |MiniIcons| module for |MiniStatusline.section_fileinfo()|.
|
|
Falls back to using 'nvim-tree/nvim-web-devicons' plugin or shows nothing.
|
|
|
|
- Enabled |MiniGit| module for |MiniStatusline.section_git()|.
|
|
Falls back to using 'lewis6991/gitsigns.nvim' plugin or shows nothing.
|
|
|
|
- Enabled |MiniDiff| module for |MiniStatusline.section_diff()|.
|
|
Falls back to using 'lewis6991/gitsigns.nvim' plugin or shows nothing.
|
|
|
|
# Setup ~
|
|
|
|
This module needs a setup with `require('mini.statusline').setup({})`
|
|
(replace `{}` with your `config` table). It will create global Lua table
|
|
`MiniStatusline` which you can use for scripting or manually (with
|
|
`:lua MiniStatusline.*`).
|
|
|
|
See |MiniStatusline.config| for `config` structure and default values. For
|
|
some content examples, see |MiniStatusline-example-content|.
|
|
|
|
You can override runtime config settings locally to buffer inside
|
|
`vim.b.ministatusline_config` which should have same structure as
|
|
`MiniStatusline.config`. See |mini.nvim-buffer-local-config| for more details.
|
|
|
|
# Highlight groups ~
|
|
|
|
Highlight depending on mode (second output from |MiniStatusline.section_mode|):
|
|
* `MiniStatuslineModeNormal` - Normal mode.
|
|
* `MiniStatuslineModeInsert` - Insert mode.
|
|
* `MiniStatuslineModeVisual` - Visual mode.
|
|
* `MiniStatuslineModeReplace` - Replace mode.
|
|
* `MiniStatuslineModeCommand` - Command mode.
|
|
* `MiniStatuslineModeOther` - other modes (like Terminal, etc.).
|
|
|
|
Highlight used in default statusline:
|
|
* `MiniStatuslineDevinfo` - for "dev info" group
|
|
(|MiniStatusline.section_git| and |MiniStatusline.section_diagnostics|).
|
|
* `MiniStatuslineFilename` - for |MiniStatusline.section_filename| section.
|
|
* `MiniStatuslineFileinfo` - for |MiniStatusline.section_fileinfo| section.
|
|
|
|
Other groups:
|
|
* `MiniStatuslineInactive` - highliting in not focused window.
|
|
|
|
To change any highlight group, modify it directly with |:highlight|.
|
|
|
|
# Disabling ~
|
|
|
|
To disable (show empty statusline), set `vim.g.ministatusline_disable`
|
|
(globally) or `vim.b.ministatusline_disable` (for a buffer) to `true`.
|
|
Considering high number of different scenarios and customization
|
|
intentions, writing exact rules for disabling module's functionality is
|
|
left to user. See |mini.nvim-disabling-recipes| for common recipes.
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline-example-content*
|
|
Example content
|
|
|
|
# Default content ~
|
|
|
|
This function is used as default value for active content: >lua
|
|
|
|
function()
|
|
local mode, mode_hl = MiniStatusline.section_mode({ trunc_width = 120 })
|
|
local git = MiniStatusline.section_git({ trunc_width = 40 })
|
|
local diff = MiniStatusline.section_diff({ trunc_width = 75 })
|
|
local diagnostics = MiniStatusline.section_diagnostics({ trunc_width = 75 })
|
|
local lsp = MiniStatusline.section_lsp({ trunc_width = 75 })
|
|
local filename = MiniStatusline.section_filename({ trunc_width = 140 })
|
|
local fileinfo = MiniStatusline.section_fileinfo({ trunc_width = 120 })
|
|
local location = MiniStatusline.section_location({ trunc_width = 75 })
|
|
local search = MiniStatusline.section_searchcount({ trunc_width = 75 })
|
|
|
|
return MiniStatusline.combine_groups({
|
|
{ hl = mode_hl, strings = { mode } },
|
|
{ hl = 'MiniStatuslineDevinfo', strings = { git, diff, diagnostics, lsp } },
|
|
'%<', -- Mark general truncate point
|
|
{ hl = 'MiniStatuslineFilename', strings = { filename } },
|
|
'%=', -- End left alignment
|
|
{ hl = 'MiniStatuslineFileinfo', strings = { fileinfo } },
|
|
{ hl = mode_hl, strings = { search, location } },
|
|
})
|
|
end
|
|
<
|
|
# Show boolean options ~
|
|
|
|
To compute section string for boolean option use variation of this code
|
|
snippet inside content function (you can modify option itself, truncation
|
|
width, short and long displayed names): >lua
|
|
|
|
local spell = vim.wo.spell and (MiniStatusline.is_truncated(120) and 'S' or 'SPELL') or ''
|
|
<
|
|
Here `x and y or z` is a common Lua way of doing ternary operator: if `x`
|
|
is `true`-ish then return `y`, if not - return `z`.
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.setup()*
|
|
`MiniStatusline.setup`({config})
|
|
Module setup
|
|
|
|
Parameters ~
|
|
{config} `(table|nil)` Module config table. See |MiniStatusline.config|.
|
|
|
|
Usage ~
|
|
>lua
|
|
require('mini.statusline').setup() -- use default config
|
|
-- OR
|
|
require('mini.statusline').setup({}) -- replace {} with your config table
|
|
<
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.config*
|
|
`MiniStatusline.config`
|
|
Module config
|
|
|
|
Default values:
|
|
>lua
|
|
MiniStatusline.config = {
|
|
-- Content of statusline as functions which return statusline string. See
|
|
-- `:h statusline` and code of default contents (used instead of `nil`).
|
|
content = {
|
|
-- Content for active window
|
|
active = nil,
|
|
-- Content for inactive window(s)
|
|
inactive = nil,
|
|
},
|
|
|
|
-- Whether to use icons by default
|
|
use_icons = true,
|
|
|
|
-- Whether to set Vim's settings for statusline (make it always shown with
|
|
-- 'laststatus' set to 2).
|
|
-- To use global statusline, set this to `false` and 'laststatus' to 3.
|
|
set_vim_settings = true,
|
|
}
|
|
<
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.active()*
|
|
`MiniStatusline.active`()
|
|
Compute content for active window
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.inactive()*
|
|
`MiniStatusline.inactive`()
|
|
Compute content for inactive window
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.combine_groups()*
|
|
`MiniStatusline.combine_groups`({groups})
|
|
Combine groups of sections
|
|
|
|
Each group can be either a string or a table with fields `hl` (group's
|
|
highlight group) and `strings` (strings representing sections).
|
|
|
|
General idea of this function is as follows;
|
|
- String group is used as is (useful for special strings like `%<` or `%=`).
|
|
- Each table group has own highlighting in `hl` field (if missing, the
|
|
previous one is used) and string parts in `strings` field. Non-empty
|
|
strings from `strings` are separated by one space. Non-empty groups are
|
|
separated by two spaces (one for each highlighting).
|
|
|
|
Parameters ~
|
|
{groups} `(table)` Array of groups.
|
|
|
|
Return ~
|
|
`(string)` String suitable for 'statusline'.
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.is_truncated()*
|
|
`MiniStatusline.is_truncated`({trunc_width})
|
|
Decide whether to truncate
|
|
|
|
This basically computes window width and compares it to `trunc_width`: if
|
|
window is smaller then truncate; otherwise don't. Don't truncate by
|
|
default.
|
|
|
|
Use this to manually decide if section needs truncation or not.
|
|
|
|
Parameters ~
|
|
{trunc_width} `(number|nil)` Truncation width. If `nil`, output is `false`.
|
|
|
|
Return ~
|
|
`(boolean)` Whether to truncate.
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.section_mode()*
|
|
`MiniStatusline.section_mode`({args})
|
|
Section for Vim |mode()|
|
|
|
|
Short output is returned if window width is lower than `args.trunc_width`.
|
|
|
|
Parameters ~
|
|
{args} `(table)` Section arguments.
|
|
|
|
Return ~
|
|
`(...)` Section string and mode's highlight group.
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.section_git()*
|
|
`MiniStatusline.section_git`({args})
|
|
Section for Git information
|
|
|
|
Shows Git summary from |MiniGit| (should be set up; recommended). To tweak
|
|
formatting of what data is shown, modify buffer-local summary string directly
|
|
as described in |MiniGit-examples|.
|
|
|
|
If 'mini.git' is not set up, section falls back on 'lewis6991/gitsigns' data
|
|
or showing empty string.
|
|
|
|
Empty string is returned if window width is lower than `args.trunc_width`.
|
|
|
|
Parameters ~
|
|
{args} `(table)` Section arguments. Use `args.icon` to supply your own icon.
|
|
|
|
Return ~
|
|
`(string)` Section string.
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.section_diff()*
|
|
`MiniStatusline.section_diff`({args})
|
|
Section for diff information
|
|
|
|
Shows diff summary from |MiniDiff| (should be set up; recommended). To tweak
|
|
formatting of what data is shown, modify buffer-local summary string directly
|
|
as described in |MiniDiff-diff-summary|.
|
|
|
|
If 'mini.diff' is not set up, section falls back on 'lewis6991/gitsigns' data
|
|
or showing empty string.
|
|
|
|
Empty string is returned if window width is lower than `args.trunc_width`.
|
|
|
|
Parameters ~
|
|
{args} `(table)` Section arguments. Use `args.icon` to supply your own icon.
|
|
|
|
Return ~
|
|
`(string)` Section string.
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.section_diagnostics()*
|
|
`MiniStatusline.section_diagnostics`({args})
|
|
Section for Neovim's builtin diagnostics
|
|
|
|
Shows nothing if diagnostics is disabled, no diagnostic is set, or for short
|
|
output. Otherwise uses |vim.diagnostic.get()| to compute and show number of
|
|
errors ('E'), warnings ('W'), information ('I'), and hints ('H').
|
|
|
|
Short output is returned if window width is lower than `args.trunc_width`.
|
|
|
|
Parameters ~
|
|
{args} `(table)` Section arguments. Use `args.icon` to supply your own icon.
|
|
Use `args.signs` to use custom signs per severity level name. For example: >lua
|
|
|
|
{ ERROR = '!', WARN = '?', INFO = '@', HINT = '*' }
|
|
<
|
|
Return ~
|
|
`(string)` Section string.
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.section_lsp()*
|
|
`MiniStatusline.section_lsp`({args})
|
|
Section for attached LSP servers
|
|
|
|
Shows number of LSP servers (each as separate "+" character) attached to
|
|
current buffer or nothing if none is attached.
|
|
Nothing is shown if window width is lower than `args.trunc_width`.
|
|
|
|
Parameters ~
|
|
{args} `(table)` Section arguments. Use `args.icon` to supply your own icon.
|
|
|
|
Return ~
|
|
`(string)` Section string.
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.section_filename()*
|
|
`MiniStatusline.section_filename`({args})
|
|
Section for file name
|
|
|
|
Show full file name or relative in short output.
|
|
|
|
Short output is returned if window width is lower than `args.trunc_width`.
|
|
|
|
Parameters ~
|
|
{args} `(table)` Section arguments.
|
|
|
|
Return ~
|
|
`(string)` Section string.
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.section_fileinfo()*
|
|
`MiniStatusline.section_fileinfo`({args})
|
|
Section for file information
|
|
|
|
Short output contains only buffer's 'filetype' and is returned if window
|
|
width is lower than `args.trunc_width` or buffer is not normal.
|
|
|
|
Nothing is shown if there is no 'filetype' set (treated as temporary buffer).
|
|
|
|
If `config.use_icons` is true and icon provider is present (see
|
|
"Dependencies" section in |mini.statusline|), shows icon near the filetype.
|
|
|
|
Parameters ~
|
|
{args} `(table)` Section arguments.
|
|
|
|
Return ~
|
|
`(string)` Section string.
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.section_location()*
|
|
`MiniStatusline.section_location`({args})
|
|
Section for location inside buffer
|
|
|
|
Show location inside buffer in the form:
|
|
- Normal: `'<cursor line>|<total lines>│<cursor column>|<total columns>'`
|
|
- Short: `'<cursor line>│<cursor column>'`
|
|
|
|
Short output is returned if window width is lower than `args.trunc_width`.
|
|
|
|
Parameters ~
|
|
{args} `(table)` Section arguments.
|
|
|
|
Return ~
|
|
`(string)` Section string.
|
|
|
|
------------------------------------------------------------------------------
|
|
*MiniStatusline.section_searchcount()*
|
|
`MiniStatusline.section_searchcount`({args})
|
|
Section for current search count
|
|
|
|
Show the current status of |searchcount()|. Empty output is returned if
|
|
window width is lower than `args.trunc_width`, search highlighting is not
|
|
on (see |v:hlsearch|), or if number of search result is 0.
|
|
|
|
`args.options` is forwarded to |searchcount()|. By default it recomputes
|
|
data on every call which can be computationally expensive (although still
|
|
usually on 0.1 ms order of magnitude). To prevent this, supply
|
|
`args.options = { recompute = false }`.
|
|
|
|
Parameters ~
|
|
{args} `(table)` Section arguments.
|
|
|
|
Return ~
|
|
`(string)` Section string.
|
|
|
|
|
|
vim:tw=78:ts=8:noet:ft=help:norl: |