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.
-
+
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 = {}
+}
+```
+
+
-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 = ''}
```
+
-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: