From 7c6d1f9074405d0e925dd25d84551ddeb47637e5 Mon Sep 17 00:00:00 2001 From: shadmansaleh Date: Tue, 6 Apr 2021 20:03:41 +0600 Subject: [PATCH] Update options section of docs . --- README.md | 69 +++++++++++++------ doc/lualine.txt | 179 ++++++++++++++++++++++++++++++------------------ 2 files changed, 160 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index 49f9830..84bb14a 100644 --- a/README.md +++ b/README.md @@ -185,35 +185,58 @@ sections = {lualine_a = {'g:coc_status', 'bo:filetype'}} ### 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. -Global options change behaviour of all suported components. -All of these options can also be specifically set to all supported components, full example below. - -##### Available global options -Option | Default | Behaviour | Supported 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 -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 -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 -##### Global options example +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 | All + +#### Using global options +Global options can be set in two ways. One is as part of options table in setup. + ```lua -options = {icons_enabled = true} +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 -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 | Behaviour -:------: | :------: | :----: -icon | Differs for each component | Displays an icon in front of the component -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 - In addition, some components have unique options. * `diagnostics` component options @@ -246,6 +269,8 @@ color_removed | `DiffDelete` foreground color | changes diff's removed section f symbols | `{added = '+', modified = '~', removed = '-'}` | changes diff's symbols | table containing on or more symbols | +Component specific options can only be set with component configs. + ##### Component options example ```lua sections = { diff --git a/doc/lualine.txt b/doc/lualine.txt index 128779e..c58cbc3 100644 --- a/doc/lualine.txt +++ b/doc/lualine.txt @@ -163,7 +163,7 @@ Available components~ * fileformat (file format) * filename * filetype - * hostname + * hostname * location (location in file in line:column format) * mode (vim mode) * progress (%progress in file) @@ -208,11 +208,17 @@ CUSTOM OPTIONS FOR COMPONENTS *lualine_custom_options* Options for components~ ====================== -Global options~ ----------------------- +Available options:~ -Global options change behaviour of all suported components. -All of these options can also be specifically set to all supported components. +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) ------ --------------- @@ -222,6 +228,10 @@ option (default_value) 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 @@ -234,6 +244,10 @@ option (default_value) 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 @@ -275,6 +289,38 @@ option (default_value) the members of color table are optional and default to theme +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. + +> + 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~ @@ -352,25 +398,26 @@ In addition, some components have unique options. 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 - } + {'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 + } } } ------------------------------------------------------------------------------- @@ -431,29 +478,29 @@ Lua config example requires = {'kyazdani42/nvim-web-devicons', opt = true}, config = function() require('lualine').setup{ - options = { - theme = 'gruvbox', - section_separators = {'', ''}, - component_separators = {'', ''}, - icons_enabled = true, - }, - sections = { - lualine_a = { {'mode', upper = true} }, - lualine_b = { {'branch', icon = ''} }, - lualine_c = { {'filename', file_status = true} }, - 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 = { } - }, - extensions = { 'fzf' } + options = { + theme = 'gruvbox', + section_separators = {'', ''}, + component_separators = {'', ''}, + icons_enabled = true, + }, + sections = { + lualine_a = { {'mode', upper = true} }, + lualine_b = { {'branch', icon = ''} }, + lualine_c = { {'filename', file_status = true} }, + 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 = { } + }, + extensions = { 'fzf' } } end } @@ -462,30 +509,30 @@ Lua config example Vimscript config example > let g:lualine = { - \'options' : { - \ 'theme' : 'gruvbox', - \ 'section_separators' : ['', ''], - \ 'component_separators' : ['', ''], - \ 'icons_enabled' : v:true, - \}, - \'sections' : { - \ 'lualine_a' : [ ['mode', {'upper': v:true,},], ], - \ 'lualine_b' : [ ['branch', {'icon': '',}, ], ], - \ 'lualine_c' : [ ['filename', {'file_status': v:true,},], ], - \ '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' : [ ], - \}, - \'extensions' : [ 'fzf' ], - \} + \'options' : { + \ 'theme' : 'gruvbox', + \ 'section_separators' : ['', ''], + \ 'component_separators' : ['', ''], + \ 'icons_enabled' : v:true, + \}, + \'sections' : { + \ 'lualine_a' : [ ['mode', {'upper': v:true,},], ], + \ 'lualine_b' : [ ['branch', {'icon': '',}, ], ], + \ 'lualine_c' : [ ['filename', {'file_status': v:true,},], ], + \ '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' : [ ], + \}, + \'extensions' : [ 'fzf' ], + \} lua require("lualine").setup() < -------------------------------------------------------------------------------