From e083bf957698a14cf63df5858a32b6dd0515ca64 Mon Sep 17 00:00:00 2001 From: Hubert Pelczarski <41551030+hoob3rt@users.noreply.github.com> Date: Thu, 13 May 2021 21:01:37 +0200 Subject: [PATCH] docs: update README.md & lualine.txt (#239) * docs: updated luline.txt * docs: updated lualine.txt tags * docs: removed whitespaces from lualine.txt * docs: updated README.md to match lualine.txt * docs: added separators to readme * docs: changes options section to provide examples instead of table * docs: fixed wrong comment in options * docs: made lualine.txt consistent with readme.md * docs: removed notice about theme mirroring * docs: changes tags structure --- README.md | 414 +++++++++++++++--------------- doc/lualine.txt | 657 ++++++++++++++++++------------------------------ 2 files changed, 451 insertions(+), 620 deletions(-) diff --git a/README.md b/README.md index 5e19258..abef5be 100644 --- a/README.md +++ b/README.md @@ -7,24 +7,22 @@ A blazing fast and easy to configure neovim statusline written in pure lua. `lualine.nvim` requires neovim 0.5 ## Contributing -Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before contributing. - -You can check [this](https://github.com/hoob3rt/lualine.nvim/projects/3) out if you want to see what is currently being worked on. - Feel free to create an issue/pr if you want to see anything else implemented. +Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pr. + ## Screenshots Here is a preview of how lualine can look like. ![normal_cropped](https://user-images.githubusercontent.com/41551030/108650373-bb025580-74bf-11eb-8682-2c09321dd18e.png) ![powerline_cropped](https://user-images.githubusercontent.com/41551030/108650377-bd64af80-74bf-11eb-9c55-fbfc51b39fe8.png) -![diff_croped](https://user-images.githubusercontent.com/41551030/108650378-be95dc80-74bf-11eb-9718-82b242ecdd54.png) +![diff_cropped](https://user-images.githubusercontent.com/41551030/108650378-be95dc80-74bf-11eb-9718-82b242ecdd54.png) ![diagnostics_cropped](https://user-images.githubusercontent.com/41551030/108650381-bfc70980-74bf-11eb-9245-85c48f0f154a.png) ![replace](https://user-images.githubusercontent.com/41551030/103467925-32372b00-4d54-11eb-88d6-6d39c46854d8.png) Screenshots of all available themes are listed in [THEMES.md](./THEMES.md) -For those who want to break the norms. You can create custom looks in lualine . +For those who want to break the norms. You can create custom looks in lualine. **Example** : @@ -72,13 +70,48 @@ Lualine has sections as shown below. ``` Each sections holds it's components e.g. current vim's mode. -Colorscheme of sections is mirrored, meaning section `A` will have the same colorscheme as section `Z` etc. +--- ### Starting lualine -All configurations happens in the setup function ```lua -require('lualine').setup{} +require('lualine').setup() ``` + +
Default config + +```lua +require'lualine'.setup { + options = { + icons_enabled = true, + theme = 'gruvbox', + component_separators = {'', ''}, + section_separators = {'', ''}, + disabled_filetypes = {} + }, + sections = { + lualine_a = {'mode'}, + lualine_b = {'branch'}, + lualine_c = {'filename'}, + lualine_x = {'encoding', 'fileformat', 'filetype'}, + lualine_y = {'progress'}, + lualine_z = {'location'} + }, + inactive_sections = { + lualine_a = {}, + lualine_b = {}, + lualine_c = {'filename'}, + lualine_x = {'location'}, + lualine_y = {}, + lualine_z = {} + }, + tabline = {}, + extensions = {} +} +``` + +
+ +--- ### Setting a theme ```lua options = {theme = 'gruvbox'} @@ -89,30 +122,26 @@ All available themes are listed in [THEMES.md](./THEMES.md) Please create a pr if you managed to port a popular theme before me, [here is how to do it](./CONTRIBUTING.md).
-Tweaking themes +Customizing themes -You like a theme but would like to tweek some colors. -You can do that in your config easily. - -Example: ```lua local custom_gruvbox = require'lualine.themes.gruvbox' - -- Chnage the background of lualine_c section for normal mode custom_gruvbox.normal.c.bg = '#112233' -- rgb colors are supported - require'lualine'.setup{ options = { theme = custom_gruvbox }, ... } ``` -You can checkout structure of a lualine theme [here](https://github.com/hoob3rt/lualine.nvim/blob/master/CONTRIBUTING.md#adding-a-theme) +Theme structure is available [here](https://github.com/hoob3rt/lualine.nvim/blob/master/CONTRIBUTING.md#adding-a-theme)
-### Changing separators -Lualine defines two kinds of seperators. One is for sections and other is for components. Default section seperators are '', '' and component separators are '', ''. -They require powerline patched fonts. But you can easily change yours to something else like below +--- +### Separators +Lualine defines two kinds of seperators: + * `section_separators` - separators between sections + * `components_separators` - separators between components in sections ```lua options = { @@ -121,59 +150,41 @@ options = { } ``` -or disable it +
Disabling separators ```lua options = {section_separators = '', component_separators = ''} ``` +
+ +--- ### Changing components in lualine sections -
-Lualine defaults - ```lua -sections = { - lualine_a = {'mode'}, - lualine_b = {'branch'}, - lualine_c = {'filename'}, - lualine_x = {'encoding', 'fileformat', 'filetype'}, - lualine_y = {'progress'}, - lualine_z = {'location'} -}, -inactive_sections = { - lualine_a = {}, - lualine_b = {}, - lualine_c = {'filename'}, - lualine_x = {'location'}, - lualine_y = {}, - lualine_z = {} -} +sections = {lualine_a = {'mode'}} ``` -
-
Available components -* branch (git branch) -* diagnostics (diagnostics count from your prefered source) -* encoding (file encoding) -* fileformat (file format) -* filename -* filetype -* hostname -* location (location in file in line:column format) -* mode (vim mode) -* progress (%progress in file) -* diff (git diff status) +* `branch` (git branch) +* `diagnostics` (diagnostics count from your prefered source) +* `encoding` (file encoding) +* `fileformat` (file format) +* `filename` +* `filetype` +* `hostname` +* `location` (location in file in line:column format) +* `mode` (vim mode) +* `progress` (%progress in file) +* `diff` (git diff status)
-
-Using custom functions as lualine component +#### Custom components -You can define a custom function as a lualine component +##### Lua functions as lualine component ```lua local function hello() @@ -182,164 +193,84 @@ end sections = {lualine_a = {hello}} ``` -
- -
- -Using vim functions as lualine component - -You can use vim functions as a lualine component +##### Vim functions as lualine component ```lua sections = {lualine_a = {'FugitiveHead'}} ``` -
+##### Vim variables as lualine component +Variables from `g:`, `v:`, `t:`, `w:`, `b:`, `o`, `go:`, `vo:`, `to:`, `wo:`, `bo:` scopes can be used. -
-Using variables as lualine component - -You can use variables from vim a lualine component -Variables from g:, v:, t:, w:, b:, o, go:, vo:, to:, wo:, bo: scopes -can be used. Scopes ending with o are options usualy accessed with `&` in vimscript +See `:h lua-vim-variables` and `:h lua-vim-options` if you are not sure what to use. ```lua sections = {lualine_a = {'g:coc_status', 'bo:filetype'}} ``` -
+##### Lua expressions as lualine component +You can use any valid lua expression as a component including + * oneliners + * global variables + * require statements +```lua +sections = {lualine_c = {"os.data('%a')", 'data', require'lsp-status'.status}} +``` +`data` is a global variable in this example. +--- +### Component options +Component options can change the way a component behave. +There are two kinds of options: + * global options affecting all components + * local options affecting specific + +Global options can be used as local options (can be applied to specific components) +but you cannot use local options as global. +Global option used locally overwrites the global, for example: +```lua + require'lualine'.setup { + options = {lower = true}, + sections = {lualine_a = {{'mode', lower = false}}, lualine_b = {'branch'}} + } +``` + +`mode` will be displayed with `lower = false` and `branch` will be displayed with `lower = true` + +#### Available options
-Using lua expressions as lualine component - -You can use any valid lua expression as a component . This allows global -variables to be used as a component too. Even require statements can be used to access values returned by specific scripts. -One liner functions can be inlined by utilizeing this . - -For exmaple this will show day of the week. -And 2nd one will display current value of global variable data. +Global options ```lua -sections = {lualine_c = {"os.data('%a')", 'data'}} +options = { + icons_enabled = 1, -- displays icons in alongside component + padding = 1, -- adds padding to the left and right of components + left_padding = 1, -- adds padding to the left of components + right_padding =1, -- adds padding to the right of components + upper = false, -- displays components in uppercase + lower = false, -- displays components in lowercase + format = nil -- format function, formats component's output +} ```
-Options for components +Local options -### Available options: - -Options can change the way a component behave. -There are two kinds of options some that work on every kind of component. -Even the ones you create like custom function component . And some that only -work on specific component. -Detailed list of available options are given below. - -#### Global options -These options are available for all components. - -Option | Default | Behaviour | Supported components -:------: | :------: | :------: | :--------: -icons_enabled | true | Displays icons on components You should have nerd-fonts supported fonts to see icons properly. | branch, fileformat, filetype, location, diagnostics -icon | Differs for each component | Displays an icon in front of the component | All -padding | 1 | Adds padding to the left and right of components | All -left_padding | 1 | Adds padding to the left of components | All -right_padding | 1 | Adds padding to the right of components | All -separator | (component_separators) | which separator to use at end of component | all -upper | false | Changes components to be uppercase | All -lower | false | Changes components to be lowercase | All -format | nil | Takes a function . The funtion gets the result of component as argument and it's return value is displayed. So this function can parse and format the output as user wants. | All -condition | nil | Takes a function. The component is loaded if the function returns true otherwise not. It can be used to load some comoonents on specific cases. | All -color | nil | Sets custom color for the component in this format

`color = {fg = '#rrggbb', bg= '#rrggbb', gui='style'}`

The fields of color table are optional and default to theme

Color option can also be a string containing highlight group name `color = "WarningMsg"`. One neat trick set the color to highlight group name then change that highlight with :hi command to change color of that component at runtime. | All -disabled_filetypes | {} | Disables lualine for specific filetypes | It works on entire statusline instead of on a single component - -#### Using global options -Global options can be set in two ways. One is as part of options table in setup. - -```lua -require'lualine'.setup{ - options = { - icons_enabled = true, - padding = 2, - } -} -``` -When set this way these values work as default for all component. -These defaults can be overwritten by setting option as part of component -configuration like following. - -```lua -lualine_a = { - -- Displays only first char of mode name - {'mode', format=function(mode_name) return mode_name:sub(1,1) end}, - -- Disables icon for branch component - {'branch', icons_enabled=false}, -}, -lualine_c = { - -- Displays filename only when window is wider then 80 - {'filename', condition=function() return vim.fn.winwidth(0) > 80 end}, -} -``` - -#### Component specific options -In addition, some components have unique options. - -* `diagnostics` component options - -Option | Default | Behaviour | Format -:------: | :------: | :----: | :---: -sources | `nil` | displays diagnostic count from defined source | array containing one or many string from set `{'nvim_lsp', 'coc', 'ale', 'vim_lsp'}` -sections | `{'error', 'warn', 'info'}` | displays diagnostics of defined severity | array containing one or many string from set `{'error', 'warn', 'info'}` -color_error | `DiffDelete` foreground color | changes diagnostic's error section foreground color | color in `#rrggbb` format -color_warn | `DiffText` foreground color | changes diagnostic's warn section foreground color | color in `#rrggbb` format -color_info | `Normal` foreground color | changes diagnostic's info section foreground color | color in `#rrggbb` format -symbols | `{error = ' ', warn = ' ', info = ' '}` or `{error = 'E:', warn = 'W:', info = 'I:'}` | changes diagnostic's info section foreground color | table containing one or more symbols for levels | - -* `filename` component options - -Option | Default | Behaviour -:------: | :------: | :----: -file_status | true | Displays file status (readonly status, modified status) -path | 0 | filename `path` option: 0 = just filename, 1 = relative path, 2 = absolute path -symbols | `{modified = '[+]', readonly = '[-]'}` | changes status symbols | table containing one or more symbols | - -* `filetype` component options - -Option | Default | Behaviour -:------: | :------: | :----: -colored | true | Displays filetype icon in color if set to `true` - -* `diff` component options - -Option | Default | Behaviour | Format -:------: | :------: | :----: | :---: -colored | true | displays diff status in color if set to `true` | -color_added | `DiffAdd` foreground color | changes diff's added section foreground color | color in `#rrggbb` format -color_modified | `DiffChange` foreground color | changes diff's changed section foreground color | color in `#rrggbb` format -color_removed | `DiffDelete` foreground color | changes diff's removed section foreground color | color in `#rrggbb` format -symbols | `{added = '+', modified = '~', removed = '-'}` | changes diff's symbols | table containing one or more symbols | - - -Component specific options can only be set with component configs. - -##### Component options example ```lua sections = { - lualine_b = { - {'branch', icon = '', upper = true, color = {fg = '#00aa22'}}, { - 'filename', - full_name = true, - shorten = true, - format = function(name) - -- Capitalize first charecter of filename to capital. - local path, fname = name:match('(.*/)(.*)') - if not path then - path = ''; - fname = name - end - return path .. fname:sub(1, 1):upper() .. fname:sub(2, #fname) - end + lualine_a = { + { + 'mode', + icon = nil, -- displays icon in front of the component + separator = nil, -- overwrites component_separators for component + condition = nil, -- condition function, component is loaded when function returns true + -- custom color for component in format + -- color = {fg = '#rrggbb', bg= '#rrggbb', gui='style'} + -- or highlight group + -- color = "WarningMsg" + color = nil } } } @@ -348,10 +279,81 @@ sections = {
-Using tabline as statusline (statusline on top) -You can use lualine to display components in tabline. -The sections, configurations and highlights are same as statusline. +Component specific local options +#### `diagnostics` component options + +```lua +sections = { + lualine_a = { + { + 'diagnostics', + -- table of diagnostic sources, available sources: + -- nvim_lsp, coc, ale, vim_lsp + sources = nil, + -- displays diagnostics from defined severity + sections = {'error', 'warn', 'info'}, + -- all colors are in format #rrggbb + color_error = nil, -- changes diagnostic's error foreground color + color_warn = nil, -- changes diagnostic's warn foreground color + color_info = nil, -- Changes diagnostic's info foreground color + symbols = {error = 'E', warn = 'W', info = 'I'} + } + } +} +``` + +#### `filename` component options + +```lua +sections = { + lualine_a = { + { + 'filename', + file_status = true, -- displays file status (readonly status, modified status) + path = 0 -- 0 = just filename, 1 = relative path, 2 = absolute path + } + } +} +``` + +#### `filetype` component options + +```lua +sections = { + lualine_a = { + { + 'filetype', + colored = true -- displays filetype icon in color if set to `true` + } + } +} +``` + +#### `diff` component options + +```lua +sections = { + lualine_a = { + { + 'diff', + colored = true, -- displays diff status in color if set to true + -- all colors are in format #rrggbb + color_added = nil, -- changes diff's added foreground color + color_modified = nil, -- changes diff's modified foreground color + color_removed = nil, -- changes diff's removed foreground color + symbols = {added = '+', modified = '~', removed = '-'} -- changes diff symbols + } + } +} +``` + +
+ +--- +### Tabline +You can use lualine to display components in tabline. +The configuration for tabline sections is exactly the same as for statusline. ```lua tabline = { lualine_a = {}, @@ -364,9 +366,9 @@ tabline = { ``` This will show branch and filename component in top of neovim inside tabline . +You can also completely move your statuline to tabline by configuring +`lualine.tabline` and disabling `lualine.sections` and `lualine.inactive_sections`. -You can also completely move your statuline to tabline by configuring lualine.tabline -instead of lualine.sections & lualine.inactive_sections and setting them to empty ```lua tabline = { ...... @@ -374,14 +376,16 @@ tabline = { sections = {}, inactive_sections = {}, ``` - -### Loading plugin extensions -Lualine extensions change statusline appearance for a window/buffer with a plugin loaded e.g. [junegunn/fzf.vim](https://github.com/junegunn/fzf.vim) +--- +### Extensions +Lualine extensions change statusline appearance for a window/buffer with +specified filetypes. -By default no plugin extension are loaded to improve performance. If you are using a plugin which is supported you can load it this way: +By default no extension are loaded to improve performance. +You can load extensions with: ```lua -extensions = { 'fzf' } +extensions = {'quickfix'} ```
@@ -396,6 +400,14 @@ extensions = { 'fzf' }
+--- +### Disabling lualine +You can disable lualine for specific filetypes +```lua +options = {disabled_filetypes = {'lua'}} +``` + +--- ### Lua config example
diff --git a/doc/lualine.txt b/doc/lualine.txt index 8bc4be2..bcd1521 100644 --- a/doc/lualine.txt +++ b/doc/lualine.txt @@ -1,122 +1,87 @@ -*lualine.txt* A blazing fast and easy to configure statusline - *lualine_nvim* *lualine* - -Author: hoob3rt (https://github.com/hoob3rt) -License: MIT License -Repository: https://github.com/hoob3rt/lualine.nvim - -=============================================================================== -LUALINE.NVIM *lualine_lualine.nvim* - - +*lualine.txt* blazing fast and easy to configure statusline + *lualine.nvim* *lualine* __ __ __ ______ __ __ __ __ ______ /\ \ /\ \/\ \ /\ __ \ /\ \ /\ \ /\ "-.\ \ /\ ___\ \ \ \____ \ \ \_\ \ \ \ __ \ \ \ \____ \ \ \ \ \ \-. \ \ \ __\ \ \_____\ \ \_____\ \ \_\ \_\ \ \_____\ \ \_\ \ \_\\"\_\ \ \_____\ \/_____/ \/_____/ \/_/\/_/ \/_____/ \/_/ \/_/ \/_/ \/_____/ +Author: hoob3rt (https://github.com/hoob3rt) +License: MIT License +Repository: https://github.com/hoob3rt/lualine.nvim +============================================================================== +CONTENTS *lualine-contents* +1. lualine.nvim..........................................|lualine-lualine.nvim| + 1.1. Usage and customization..............|lualine-usage_and_customization| + 1.1.1 Starting lualine.........................|lualine-starting_lualine| + 1.1.2 Setting a theme.....................................|lualine-theme| + 1.1.3 Separators.....................................|lualine-separators| + 1.1.4 Changing components............................|lualine-components| + 1.1.5 Custom components.......................|lualine-custom_components| + 1.1.6 Component options.......................|lualine-component_options| + 1.1.7 Tabline...........................................|lualine-tabline| + 1.1.8 Extensions.....................................|lualine-extensions| + 1.2 Config examples..............................|lualine-config_examples| + 1.2.1 Lua config example...................|lualine-lua_config_example| + 1.2.2 Vimscript config example.......|lualine-vimscript_config_example| -A blazing fast and easy to configure neovim statusline written in pure lua. - -`lualine.nvim` requires neovim 0.5 - -================================================================================ -CONTENTS *lualine_contents* - -1. lualine.nvim...........................................|lualine_lualine.nvim| - 1.1. Performance comparison.................|lualine_performance_comparison| - 1.2. Installation.....................................|lualine_installation| - 1.2.1. vim-plug.......................................|lualine_vim-plug| - 1.2.2.packer.nvim..................................|lualine_packer.nvim| - 1.3. Usage and customization...............|lualine_usage_and_customization| - 1.3.1. Starting lualine.......................|lualine_starting_lualine| - 1.3.2. Setting theme.............................|lualine_setting_theme| - 1.3.3. Changing separator...................|lualine_changing_separator| - 1.3.4. Changing components.................|lualine_changing_components| - 1.3.5. Building Custom components............|lualine_custom_components| - 1.3.6. Custom options...........................|lualine_custom_options| - 1.3.7. Using tabline as statusline...............|lualine_using_tabline| - 1.3.8. Loading plugin extensions.....|lualine_loading_plugin_extensions| - 1.3.9 Config examples.........................|lualine_config_examples| - 1.3.9.1. Packer.nvim......|lualine_config_example_using_packer.nvim| - 1.3.9.2 VIML example.......|lualine_full_config_example_inside_viml| - 1.4. Contributing.....................................|lualine_contributing| - 1.5. Screenshots.......................................|lualine_screenshots| - -================================================================================ -PERFORMANCE COMPARISON *lualine_performance_comparison* - -Unlike other statusline plugins lualine loads only defined components, nothing else. - -Startup time performance measured with an amazing plugin -tweekmonster/startuptime.vim (https://github.com/tweekmonster/startuptime.vim) - -All times are measured with only `startuptime.vim` and given statusline plugin -installed - -| clean vimrc | lualine | lightline | airline | -| :------------: | :----------: | :----------: | :----------: | -| 8.943 ms | 9.034 ms | 11.463 ms | 13.425 ms | - --------------------------------------------------------------------------------- -INSTALLATION *lualine_installation* - -VIM-PLUG *lualine_vim-plug* -> - Plug 'hoob3rt/lualine.nvim' - " If you want to have icons in your statusline choose one of these - Plug 'kyazdani42/nvim-web-devicons' - Plug 'ryanoasis/vim-devicons' -< - -PACKER.NVIM *lualine_packer.nvim* -> - use { - 'hoob3rt/lualine.nvim', - requires = {'kyazdani42/nvim-web-devicons', opt = true} - } -< - --------------------------------------------------------------------------------- -USAGE AND CUSTOMIZATION *lualine_usage_and_customization* +============================================================================== +USAGE AND CUSTOMIZATION *lualine-usage_and_customization* Lualine has sections as shown below. > +-------------------------------------------------+ | A | B | C X | Y | Z | +-------------------------------------------------+ -< Each sections holds it's components e.g. current vim's mode. -Colorscheme of sections is mirrored, meaning section `A` will have the same -colorscheme as section `Z` etc. -Configuration is currently limited to lua, please use lua block or a separate -lua file to configure lualine. - -STARTING LUALINE *lualine_starting_lualine* +------------------------------------------------------------------------------ +STARTING LUALINE *lualine-starting_lualine* *lualine.setup()* > - require('lualine').setup{} -< + require('lualine').setup() -SETTING THEME *lualine_setting_theme* +Default config~ +> + require'lualine'.setup { + options = { + icons_enabled = true, + theme = 'gruvbox', + component_separators = {'', ''}, + section_separators = {'', ''}, + disabled_filetypes = {} + }, + sections = { + lualine_a = {'mode'}, + lualine_b = {'branch'}, + lualine_c = {'filename'}, + lualine_x = {'encoding', 'fileformat', 'filetype'}, + lualine_y = {'progress'}, + lualine_z = {'location'} + }, + inactive_sections = { + lualine_a = {}, + lualine_b = {}, + lualine_c = {'filename'}, + lualine_x = {'location'}, + lualine_y = {}, + lualine_z = {} + }, + tabline = {}, + extensions = {} + } + +------------------------------------------------------------------------------ +SETTING A THEME *lualine-theme* > options = {theme = 'gruvbox'} -< -All available themes are listed in THEMES.md (./THEMES.md) +Available themes are listed here: +https://github.com/hoob3rt/lualine.nvim/blob/master/THEMES.md -Please create a pr if you managed to port a popular theme before me, here is -how to do it (./CONTRIBUTING.md). - -Tweeking themes~ - -You like a theme but would like to tweek some colors. -You can do that in your config easily. - -Example: +Customizing themes~ > local custom_gruvbox = require'lualine.themes.gruvbox' @@ -128,395 +93,249 @@ Example: ... } < -You can checkout structure of a lualine theme [here](https://github.com/hoob3rt/lualine.nvim/blob/master/CONTRIBUTING.md#adding-a-theme) +Theme structure is available here: +https://github.com/hoob3rt/lualine.nvim/blob/master/CONTRIBUTING.md#adding-a-theme -CHANGING SEPARATOR IN SECTION *lualine_changing_separator* +------------------------------------------------------------------------------ +SEPARATORS *lualine-separators* -Lualine defines two kinds of seperators. One is for sections and other is -for components. Default section seperators are '', '' and component -separators are '', ''.They require powerline patched fonts. But you can -easily change yours to something else like below. +Lualine defines two kinds of seperators: + * |section_separators| - separators between sections + * |components_separators| - separators between components in sections > options = { section_separators = {'', ''}, component_separators = {'', ''} } -or disable it +Disabling separators~ > options = {section_separators = '', component_separators = ''} -< - -CHANGING COMPONENTS IN LUALINE SECTIONS *lualine_changing_components* - - -Lualine defaults~ -> - sections = { - lualine_a = { 'mode' }, - lualine_b = { 'branch' }, - lualine_c = { 'filename' }, - lualine_x = { 'encoding', 'fileformat', 'filetype' }, - lualine_y = { 'progress' }, - lualine_z = { 'location' }, - } - inactive_sections = { - lualine_a = { }, - lualine_b = { }, - lualine_c = { 'filename' }, - lualine_x = { 'location' }, - lualine_y = { }, - lualine_z = { } - } -< - +------------------------------------------------------------------------------ +CHANGING COMPONENTS IN LUALINE SECTIONS *lualine-components* + `sections = {lualine_a = {'mode'}}` Available components~ - general~ - * branch (git branch) - * diagnostics (diagnostics count from your prefered source) - * encoding (file encoding) - * fileformat (file format) - * filename - * filetype - * hostname - * location (location in file in line:column format) - * mode (vim mode) - * progress (%progress in file) - * diff (git diff status) + * |branch| (git branch) + * |diagnostics| (diagnostics count from your preferred source) + * |encoding| (file encoding) + * |fileformat| (file format) + * |filename| + * |filetype| + * |hostname| + * |location| (location in file in line:column format) + * |mode| (vim mode) + * |progress| (%progress in file) + * |diff| (git diff status) +------------------------------------------------------------------------------ +CUSTOM COMPONENTS *lualine-custom_components* --------------------------------------------------------------------------------- -BUILDING YOUR COMPONENTS *lualine_custom_components* - - -Using custom functions as lualine component~ - -You can define a custom function as a lualine component +Lua functions as lualine component~ > local function hello() return [[hello world]] end sections = {lualine_a = {hello}} < -Using vim functions as lualine component~ - -You can use vim functions as a lualine component - +Vim functions as lualine component~ > sections = {lualine_a = {'FugitiveHead'}} < +Vim variables as lualine component~ -Using variables as lualine component~ - -You can use variables from vim. Variables from g:, v:, t:, -w:, b:, o, go:, vo:, to:, wo:, bo: scopes can be used. -Scopes ending with o are options usualy accessed with `&` in -vimscript - +Variables from `g:`, `v:`, `t:`, `w:`, `b:`, `o`, `go:`, `vo:`, `to:`, `wo:`, `bo:` scopes can be used. +See `:h lua-vim-variables` and `:h lua-vim-options` if you are not sure what to use. > sections = {lualine_a = {'g:coc_status', 'bo:filetype'}} < -Using lua expressions as lualine component~ +Lua expressions as lualine component~ -You can use any valid lua expression as a component . This -allows global variables to be used as a component too. Even -require statements can be used to access values returned by -specific scripts. One liner functions can be inlined by -utilizeing this . - -For exmaple this will show day of the week. And 2nd one -will display current value of global variabke data. +You can use any valid lua expression as a component including + * oneliners + * global variables + * require statements > - sections = {lualine_c = {"os.data('%a')", 'data'}} -< + sections = {lualine_c = {"os.data('%a')", 'data', require'lsp-status'.status}} --------------------------------------------------------------------------------- -CUSTOM OPTIONS FOR COMPONENTS *lualine_custom_options* +`data` is a global variable in this example. +------------------------------------------------------------------------------ +COMPONENT OPTIONS *lualine-component_options* -Options for components~ -====================== +Component options can change the way a component behave. +There are two kinds of options: + * global options affecting all components + * local options affecting specific + +Global options can be used as local options (can be applied to specific components) +but you cannot use local options as global. +Global option used locally overwrites the global, for example: +> + require'lualine'.setup { + options = {lower = true}, + sections = {lualine_a = {{'mode', lower = false}}, lualine_b = {'branch'}} + } + +`mode` will be displayed with `lower = false` and `branch` will be displayed with `lower = true` Available options:~ -Options can change the way a component behave. -There are two kinds of options some that work on every kind of component. -Even the ones you create like custom function component . And some that only -work on specific component. -Detailed list of available options are given below. - Global options~ - -These options are available for all components. - -option (default_value) ------- --------------- - - • icons_enabled (true) - Displays icons on components - You should have nerd-fonts supported fonts to see icons properly. - Supported components: branch, fileformat, filetype, location, diagnostics - - • icon (depends on component) - displays an icon infront of a component - Supported components: all - - • padding (1) - spaces on left and right - Supported components: all - - • left_padding (1) - spaces on left - Supported components: all - - • right_padding (1) - spaces on right - Supported components: all - - • separator (component_separators) - which separator to use at end of component - Supported components: all - - • upper (false) - Displayed in upper case - Supported components: all - - • lower (false) - Displayed in lower case - Supported components: all - - • format (nil) - Takes a function . The funtion gets the result of component - as argument and it's return value is displayed. So this function - can parse and format the output as user wants. - Supported components: all - - • disabled_filetypes ({}) - Disables lualine for specific filetypes. It works on entire - statusline instead of on a single component. - - Example: - `lualine.options.icons_enabled = true` - - -Component specific options --------------- -As mentioned above, all global options can be applied to specific components. -However there are some options which are component-only (you cannot set them as globals) - -option (default_value) ------- --------------- - - • icon (differs for each component) - displays an icon infront of a component - - • condition (nil) - Takes a function. The component is loaded if the function - returns true otherwise not. It can be used to load some - comoonents on specific cases. - - • color (Theme colors) - color option can be used to set custom color to a component - Color format: - `lua color = {fg = '#rrggbb', bg= '#rrggbb', gui='style'}` - the members of color table are optional and default to theme - Color option can also be a string containing highlight group name > - color = "WarningMsg"` -< One neat trick set the color to highlight group name then change - that highlight with :hi command to change color of that component - at runtime. - -Using global options~ - -Global options can be set in two ways. One is as part of options table in setup. - > - require'lualine'.setup{ - options = { - icons_enabled = true, - padding = 2, - } - } -< -When set this way these values work as default for all component. -These defaults can be overwritten by setting option as part of component -configuration like following. + options = { + icons_enabled = 1, -- displays icons in alongside component + padding = 1, -- adds padding to the left and right of components + left_padding = 1, -- adds padding to the left of components + right_padding =1, -- adds padding to the right of components + upper = false, -- displays components in uppercase + lower = false, -- displays components in lowercase + format = nil -- format function, formats component's output + } +Local options~ +--------------- > + sections = { lualine_a = { - -- Displays only first char of mode name - {'mode', format=function(mode_name) return mode_name:sub(1,1) end}, - -- Disables icon for branch component - {'branch', icons_enabled=false}, - }, - lualine_c = { - -- Displays filename only when window is wider then 80 - {'filename', condition=function() return vim.fn.winwidth(0) > 80 end}, - } -< - - -Component specific options~ - -In addition, some components have unique options. - - • diagnostics~ - • sources (nil) - displays diagnostic count from defined source. - array containing one or many string from set - {'nvim_lsp', 'coc', 'ale', 'vim_lsp'} - - • sections ({'error', 'warn', 'info'}) - displays diagnostics of defined severity. - array containing one or many string from set - {'error', 'warn', 'info'} - - • color_error (DiffDelete foreground color) - changes diagnostic's error section foreground color. - color in #rrggbb format - - • color_warn (DiffText foreground color) - changes diagnostic's warn section foreground color - color in #rrggbb format - - • color_info (Normal foreground color) - changes diagnostic's info section foreground color - color in #rrggbb format - - • symbols - (icons_enabled: true -> {error = ' ', warn = ' ', info = ' '}) - (icons_enabled: false -> {error = 'E:', warn = 'W:', info = 'I:'}) - changes diagnostic's symbol characters. You can set one or more symbols - for each level. - > - { - 'diagnostics', - symbols = { - -- set the error symbol and use defaults for warn and info. - error = '!!', - }, - } -< - - • filename~ - • file_status (true) - Displays file status (readonly status, modified status) - - • path (0) - filename `path` option: 0 = just filename, 1 = relative path, 2 = absolute path - - • symbols (`{modified = '[+]', readonly = '[-]'}`) - changes status symbols - - • filetype~ - • colored (true) - Displays filetype icon in color if set to `true` - - • fileformat~ - • icons_enabled (true) - Whether to displays icon before component. Colors - are automaticaly extracted from colorscheme . If you - want to change any of those you can use options given below. - - • diff~ - • colored (true) - displays diff status in color if set to `true` - - • color_added (DiffAdd foreground color) - Changes diff's added section foreground color - Color in `#rrggbb` format - - • color_modified (DiffChange foreground color) - Changes diff's changed section foreground color - Color in `#rrggbb` format - - • color_removed (DiffDelete foreground color) - Changes diff's removed section foreground color - Color in `#rrggbb` format - - • symbols (`{added = '+', modified = '~', removed = '-'}`) - changes diff's symbols - Color in `#rrggbb` format -< -Component specific options can only be set with component configs. - -Example:~ -> - sections = { - lualine_b = { - {'branch', icon = '', upper = true, color = {fg = '#00aa22'}}, { - 'filename', - full_name = true, - shorten = true, - format = function(name) - -- Capitalize first charecter of filename to capital. - local path, fname = name:match('(.*/)(.*)') - if not path then - path = ''; - fname = name - end - return path .. fname:sub(1, 1):upper() .. fname:sub(2, #fname) - end - } + { + 'mode', + icon = nil, -- displays icon in front of the component + separator = nil, -- overwrites component_separators for component + condition = nil, -- condition function, component is loaded when function returns true + -- custom color for component in format + -- color = {fg = '#rrggbb', bg= '#rrggbb', gui='style'} + -- or highlight group + -- color = "WarningMsg" + color = nil } } -------------------------------------------------------------------------------- -USING TABLINE AS STATUSLINE *lualine_using_tabline* + } -You can use lualine to display components in tabline . -The sections, configurations and highlights are same as statusline. +Component specific local options~ +--------------- +* diagnostics~ + > + sections = { + lualine_a = { + { + 'diagnostics', + -- table of diagnostic sources, available sources: + -- nvim_lsp, coc, ale, vim_lsp + sources = nil, + -- displays diagnostics from defined severity + sections = {'error', 'warn', 'info'}, + -- all colors are in format #rrggbb + color_error = nil, -- changes diagnostic's error foreground color + color_warn = nil, -- changes diagnostic's warn foreground color + color_info = nil, -- Changes diagnostic's info foreground color + symbols = {error = 'E', warn = 'W', info = 'I'} + } + } + } + +* filename~ +> + sections = { + lualine_a = { + { + 'filename', + file_status = true, -- displays file status (readonly status, modified status) + path = 0 -- 0 = just filename, 1 = relative path, 2 = absolute path + } + } + } + +* filetype~ +> + sections = { + lualine_a = { + { + 'filetype', + colored = true -- displays filetype icon in color if set to `true` + } + } + } + +* diff~ +> + sections = { + lualine_a = { + { + 'diff', + colored = true, -- displays diff status in color if set to true + -- all colors are in format #rrggbb + color_added = nil, -- changes diff's added foreground color + color_modified = nil, -- changes diff's modified foreground color + color_removed = nil, -- changes diff's removed foreground color + symbols = {added = '+', modified = '~', removed = '-'} -- changes diff symbols + } + } + } + +------------------------------------------------------------------------------ +TABLINE *lualine-tabline* + +You can use lualine to display components in tabline. +The configuration for tabline sections is exactly the same as for statusline. > tabline = { - lualine_a = { }, - lualine_b = { 'branch' }, - lualine_c = { 'filename' }, - lualine_x = { }, - lualine_y = { }, - lualine_z = { }, + lualine_a = {}, + lualine_b = {'branch'}, + lualine_c = {'filename'}, + lualine_x = {}, + lualine_y = {}, + lualine_z = {}, } < -This will show branch and filename component in top of neovim inside tabline . +This will show branch and filename component on top of neovim inside tabline. -You can also completely move your statuline to tabline by configuring lualine.tabline -instead of lualine.sections & lualine.inactive_sections and setting them to empty +You can also completely move your statuline to tabline by configuring +|lualine.tabline| and disabling |lualine.sections| and |lualine.inactive_sections|. > tabline = { ...... } sections = {} inactive_sections = {} -< - --------------------------------------------------------------------------------- -LOADING PLUGIN EXTENSIONS *lualine_loading_plugin_extensions* +------------------------------------------------------------------------------ +EXTENSIONS *lualine-extensions* Lualine extensions change statusline appearance for a window/buffer with -a plugin loaded e.g. junegunn/fzf.vim (https://github.com/junegunn/fzf.vim) +specified filetypes. -By default no plugin extension are loaded to improve performance. If you are -using a plugin which is supported you can load it this way: +By default no extension are loaded to improve performance. +You can load extensions with: > - extensions = { 'fzf' } + extensions = {'quickfix'} < - Available extensions - * chadtree - * fugitive - * fzf - * nerdtree - * nvim-tree - * quickfix + * |chadtree| + * |fugitive| + * |fzf| + * |nerdtree| + * |nvim-tree| + * |quickfix| --------------------------------------------------------------------------------- -CONGIG EXAMPLES *lualine_config_examples* +============================================================================== +DISABLING LUALINE *lualine-disable* -Lua config example +You can disable lualine for specific filetypes + +`options = {disabled_filetypes = {'lua'}}` + +============================================================================== + +CONGIG EXAMPLES *lualine-config_examples* + +------------------------------------------------------------------------------ +LUA CONFIG EXAMPLE *lualine-lua_config_example* > use { 'hoob3rt/lualine.nvim', @@ -551,8 +370,8 @@ Lua config example end } < --------------------------------------------------------------------------------- -Vimscript config example +------------------------------------------------------------------------------ +VIMSCRIPT CONFIG EXAMPLE *lualine-vimscript_config_example* > let g:lualine = { \'options' : { @@ -582,5 +401,5 @@ Vimscript config example \} lua require("lualine").setup() < -------------------------------------------------------------------------------- +----------------------------------------------------------------------------- vim:tw=80:sw=4:ts=8:noet:ft=help:norl:et: