*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: `'|│|'` - Short: `'│'` 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: