diff options
Diffstat (limited to 'start/lightline/doc/lightline.txt')
| -rw-r--r-- | start/lightline/doc/lightline.txt | 1325 |
1 files changed, 1325 insertions, 0 deletions
diff --git a/start/lightline/doc/lightline.txt b/start/lightline/doc/lightline.txt new file mode 100644 index 0000000..7c2a886 --- /dev/null +++ b/start/lightline/doc/lightline.txt @@ -0,0 +1,1325 @@ +*lightline.txt* A light and configurable statusline/tabline for Vim + +Version: 0.1 +Author: itchyny (https://github.com/itchyny) +License: MIT License +Repository: https://github.com/itchyny/lightline.vim +Last Change: 2018/04/28 00:08:18. + +CONTENTS *lightline-contents* + +Introduction |lightline-introduction| +Spirit |lightline-spirit| +Option |lightline-option| +Font |lightline-font| +Function |lightline-function| +Component Expansion |lightline-component-expansion| +Colorscheme |lightline-colorscheme| +Examples |lightline-examples| +Nice Examples |lightline-nice-examples| +Powerful Example |lightline-powerful-example| +Troubleshooting |lightline-troubleshooting| + +============================================================================== +INTRODUCTION *lightline-introduction* + +The *lightline* plugin is a light and configurable statusline/tabline for Vim. + +------------------------------------------------------------------------------ +SPIRIT *lightline-spirit* + + Minimalism + The core script is very small to achieve enough functions as a + statusline plugin. + + Configurability + You can create your own component and easily add to the statusline + and the tabline. + + Orthogonality + The plugin does not rely on the implementation of other plugins. + Such plugin crossing settings should be configured by users. + + You find this plugin does not integrate with other plugins by default. + This plugin does not provide branch information, which is a basic + component in existing statusline plugins. It is a design of + lightline.vim that such plugin crossing configuration should be + written by users. Once a plugin starts to integrate with some famous + plugins, it should be kept updated to follow the changes of the + plugins and should accept integration requests with new plugins. + Instead, lightline.vim is designed very carefully so that users can + easily integrate with other plugins. Good APIs keep a plugin clean. + +------------------------------------------------------------------------------ +OPTIONS *lightline-option* + + g:lightline *g:lightline* + All the configurations are stored in this global variable. + + g:lightline.active *g:lightline.active* + g:lightline.inactive *g:lightline.inactive* + g:lightline.tabline *g:lightline.tabline* + Dictionaries to store the statusline/tabline components. + Note that right groups of components are stored from right to + left. + The default values are: +> + let g:lightline.active = { + \ 'left': [ [ 'mode', 'paste' ], + \ [ 'readonly', 'filename', 'modified' ] ], + \ 'right': [ [ 'lineinfo' ], + \ [ 'percent' ], + \ [ 'fileformat', 'fileencoding', 'filetype' ] ] } + let g:lightline.inactive = { + \ 'left': [ [ 'filename' ] ], + \ 'right': [ [ 'lineinfo' ], + \ [ 'percent' ] ] } + let g:lightline.tabline = { + \ 'left': [ [ 'tabs' ] ], + \ 'right': [ [ 'close' ] ] } +< + g:lightline.tab *g:lightline.tab* + A dictionary to store the tab components in each tabs. + The default values are: +> + let g:lightline.tab = { + \ 'active': [ 'tabnum', 'filename', 'modified' ], + \ 'inactive': [ 'tabnum', 'filename', 'modified' ] } +< + g:lightline.component *g:lightline.component* + A dictionary for statusline/tabline components. + The default value is: +> + let g:lightline.component = { + \ 'mode': '%{lightline#mode()}', + \ 'absolutepath': '%F', + \ 'relativepath': '%f', + \ 'filename': '%t', + \ 'modified': '%M', + \ 'bufnum': '%n', + \ 'paste': '%{&paste?"PASTE":""}', + \ 'readonly': '%R', + \ 'charvalue': '%b', + \ 'charvaluehex': '%B', + \ 'fileencoding': '%{&fenc!=#""?&fenc:&enc}', + \ 'fileformat': '%{&ff}', + \ 'filetype': '%{&ft!=#""?&ft:"no ft"}', + \ 'percent': '%3p%%', + \ 'percentwin': '%P', + \ 'spell': '%{&spell?&spelllang:""}', + \ 'lineinfo': '%3l:%-2v', + \ 'line': '%l', + \ 'column': '%c', + \ 'close': '%999X X ', + \ 'winnr': '%{winnr()}' } +< + g:lightline.component_visible_condition + *g:lightline.component_visible_condition* + A dictionary to store the visible condition of the components. + Note that this configuration is used to control the visibility + of the subseparators, not to control the visibility of the + components themselves. Each expression should correspond to + the condition on which each component is not empty. + The default value is: +> + let g:lightline.component_visible_condition = { + \ 'modified': '&modified||!&modifiable', + \ 'readonly': '&readonly', + \ 'paste': '&paste', + \ 'spell': '&spell' } +< + g:lightline.component_function *g:lightline.component_function* + A dictionary to store the function components. + This is useful to write a complex component configuration and + to integrate with other plugins. If a component set in both + component and component_function, the configuration of + component_function has priority. + + The default value is: +> + let g:lightline.component_function = {} +< + For example, if you want to display the name of the git branch, + install |vim-fugitive| plugin and then configure as: +> + let g:lightline = { + \ 'active': { + \ 'left': [ [ 'mode', 'paste' ], + \ [ 'gitbranch', 'readonly', 'filename', 'modified' ] ] + \ }, + \ 'component_function': { + \ 'gitbranch': 'fugitive#head' + \ }, + \ } +< + g:lightline.component_function_visible_condition + *g:lightline.component_function_visible_condition* + A dictionary to store the visible conditions of the function + components. Each expression should correspond to the condition + each component is not empty. This configuration is used to + control the visibility of the sub-separators. You can use this + configuration to reduce the number of function calls for + performance improvement by setting the value 1 (to tell lightline + that the component is always visible). + The default value is: +> + let g:lightline.component_function_visible_condition = {} +< + g:lightline.component_expand *g:lightline.component_expand* + A dictionary to store expanding components. You can create + warning and critical components. The values should be the name + of functions should return either one of: + + a string + + an array of three elements: + [[ left ], [ middle ], [ right ]] + The component in this dictionary has priority over + |g:lightline.component| and |g:lightline.component_function|. + Note that the return string is appended to the statusline + string without any conversion. So you should replace all the + % signs with %%. Otherwise, lightline will be disabled in case + the text has a % sign. + (example: return substitute(text, '%', '%%', 'g')). + See |lightline-component-expansion| for more detail. +> + let g:lightline.component_expand = { + \ 'tabs': 'lightline#tabs' } +< + g:lightline.component_type *g:lightline.component_type* + A dictionary to specify the types for components in + |g:lightline.component_expand|. The types are used to specify + the color. Specifically, the type raw is used to specify a + component which should not be wrapped by item group: %(...%). + If you want to specify the type of a raw component, please use + |g:lightline.component_raw|. + The default value is: > + + let g:lightline.component_type = { + \ 'tabs': 'tabsel', + \ 'close': 'raw' } +< + g:lightline.component_raw *g:lightline.component_raw* + A dictionary to specify the raw type components. When you + register a component to this dictionary (like > + let g:lightline.component_raw = { 'example': 1 } +< ), the example component is not wrapped by item group: %(...%). + The default value is: > + + let g:lightline.component_raw = {} +< + g:lightline.tab_component *g:lightline.tab_component* + A dictionary for components in one tab. + The default value is: > + + let g:lightline.tab_component = {} +< + g:lightline.tab_component_function *g:lightline.tab_component_function* + Another dictionary for components in one tab. + A function specified as a tab component takes one argument: + the tab [count]. + The default value is: +> + let g:lightline.tab_component_function = { + \ 'filename': 'lightline#tab#filename', + \ 'modified': 'lightline#tab#modified', + \ 'readonly': 'lightline#tab#readonly', + \ 'tabnum': 'lightline#tab#tabnum' } +< + g:lightline.colorscheme *g:lightline.colorscheme* + The colorscheme for lightline.vim. + Currently, wombat, solarized, powerline, jellybeans, Tomorrow, + Tomorrow_Night, Tomorrow_Night_Blue, Tomorrow_Night_Eighties, + PaperColor, seoul256, landscape, one, darcula, molokai, materia, + material, OldHope, nord, 16color and deus are available. + The default value is: +> + let g:lightline.colorscheme = 'default' +< + Note that the default colorscheme is exactly the same as the + powerline theme. + + g:lightline.mode_map *g:lightline.mode_map* + A dictionary of names for the modes. The keys are the return + values of |mode()|. + The default value is: +> + let g:lightline.mode_map = { + \ 'n' : 'NORMAL', + \ 'i' : 'INSERT', + \ 'R' : 'REPLACE', + \ 'v' : 'VISUAL', + \ 'V' : 'V-LINE', + \ "\<C-v>": 'V-BLOCK', + \ 'c' : 'COMMAND', + \ 's' : 'SELECT', + \ 'S' : 'S-LINE', + \ "\<C-s>": 'S-BLOCK', + \ 't': 'TERMINAL', + \ } +< + When you search a word, you get into the command mode. But if + you want to keep the mode indicator as 'NORMAL', add > + let g:lightline = { 'mode_map': { 'c': 'NORMAL' } } +< to your .vimrc. + + g:lightline.separator *g:lightline.separator* + g:lightline.subseparator *g:lightline.subseparator* + Dictionaries to store separators. + The default value is +> + let g:lightline.separator = { 'left': '', 'right': '' } + let g:lightline.subseparator = { 'left': '|', 'right': '|' } +< + g:lightline.tabline_separator *g:lightline.tabline_separator* + g:lightline.tabline_subseparator *g:lightline.tabline_subseparator* + Dictionaries to store separators for the tabline. + The default value is +> + let g:lightline.tabline_separator = g:lightline.separator + let g:lightline.tabline_subseparator = g:lightline.subseparator +< + g:lightline.enable *g:lightline.enable* + A dictionary to specify which feature is turned on. + The default value is +> + let g:lightline.enable = { + \ 'statusline': 1, + \ 'tabline': 1 + \ } +< +============================================================================== +FONT *lightline-font* +You can use the patched font you used for |vim-powerline| and |powerline|. + +The patched fonts for |powerline| are available at +https://github.com/Lokaltog/powerline-fonts + +A tutorial to create a patched font for |vim-powerline| is available at +https://github.com/Lokaltog/vim-powerline/tree/develop/fontpatcher + +If you have installed the patched font for |powerline|, following settings look +nice. +> + let g:lightline = { + \ 'component': { + \ 'lineinfo': ' %3l:%-2v', + \ }, + \ 'component_function': { + \ 'readonly': 'LightlineReadonly', + \ 'fugitive': 'LightlineFugitive' + \ }, + \ 'separator': { 'left': '', 'right': '' }, + \ 'subseparator': { 'left': '', 'right': '' } + \ } + function! LightlineReadonly() + return &readonly ? '' : '' + endfunction + function! LightlineFugitive() + if exists('*fugitive#head') + let branch = fugitive#head() + return branch !=# '' ? ''.branch : '' + endif + return '' + endfunction +< +If you have installed the patched font for |vim-powerline|, following settings +look nice. +> + let g:lightline = { + \ 'component': { + \ 'lineinfo': '⭡ %3l:%-2v', + \ }, + \ 'component_function': { + \ 'readonly': 'LightlineReadonly', + \ 'fugitive': 'LightlineFugitive' + \ }, + \ 'separator': { 'left': '⮀', 'right': '⮂' }, + \ 'subseparator': { 'left': '⮁', 'right': '⮃' } + \ } + function! LightlineReadonly() + return &readonly ? '⭤' : '' + endfunction + function! LightlineFugitive() + if exists('*fugitive#head') + let branch = fugitive#head() + return branch !=# '' ? '⭠ '.branch : '' + endif + return '' + endfunction +< +If the statusline does not correctly show the special characters, use the +unicode numbers. For |powerline| font users: +> + \ 'separator': { 'left': "\ue0b0", 'right': "\ue0b2" }, + \ 'subseparator': { 'left': "\ue0b1", 'right': "\ue0b3" } +< +For |vim-powerline| font users: +> + \ 'separator': { 'left': "\u2b80", 'right': "\u2b82" }, + \ 'subseparator': { 'left': "\u2b81", 'right': "\u2b83" } +< +See |lightline-problem-9| for more detail. +============================================================================== +FUNCTION *lightline-function* +Exposed functions for lightline.vim. + + lightline#mode() *lightline#mode()* + Returns the mode of the Vim using |g:lightline.mode_map|. + + lightline#init() *lightline#init()* + Initializes the internal state from |g:lightline|. + + lightline#colorscheme() *lightline#colorscheme()* + Initializes the colorscheme and the highlight groups. + + lightline#update() *lightline#update()* + Updates all the statuslines of existing windows. + + lightline#update_once() *lightline#update_once()* + Updates the statuslines only once. + + lightline#enable() *lightline#enable()* + Enables |lightline|. + + lightline#disable() *lightline#disable()* + Disables |lightline|. + + lightline#toggle() *lightline#toggle()* + Toggles |lightline|. + + lightline#link([mode]) *lightline#link()* + Creates links of the highlight groups for the active window. + This function accepts an optional argument. It should be one + of the return value of |mode()|. + + lightline#highlight() *lightline#highlight()* + Set the highlight groups. + + lightline#statusline({inactive}) *lightline#statusline()* + Returns |statusline| strings. If the argument is 0, it returns + the statusline for active window, and the statusline for + inactive window otherwise. + + lightline#tabline() *lightline#tabline()* + Returns the tabline string. + + lightline#concatenate({list}, {num}) *lightline#concatenate()* + A string concatenation function. Concatenating all the strings + in {list} using the sub-separator of lightline. If {num} is 0, + then the left sub-separator is used. Otherwise, the right + sub-separator is used. + + lightline#palette() *lightline#palette()* + Returns the palette data. + +============================================================================== +COMPONENT EXPANSION *lightline-component-expansion* +You can create components, which have specific colors. This section gives an +example using |syntastic|. + +If you want to add the |syntastic| flag to the statusline, an easy example is: +> + " Example A + let g:lightline = { + \ 'active': { + \ 'right': [ [ 'lineinfo', 'syntastic' ], + \ [ 'percent' ], + \ [ 'fileformat', 'fileencoding', 'filetype' ] ] + \ }, + \ 'component_function': { + \ 'syntastic': 'SyntasticStatuslineFlag', + \ } + \ } + let g:syntastic_mode_map = { 'mode': 'passive', + \ 'active_filetypes': ['c', 'cpp'] } +< +However, the color of the syntastic component is the same as the lineinfo +component. + +In order to change the syntastic component more outstanding, you have to use +|g:lightline.component_expand|. See the following example: +> + " Example B + let g:lightline = { + \ 'active': { + \ 'right': [ [ 'syntastic', 'lineinfo' ], + \ [ 'percent' ], + \ [ 'fileformat', 'fileencoding', 'filetype' ] ] + \ }, + \ 'component_expand': { + \ 'syntastic': 'SyntasticStatuslineFlag', + \ }, + \ 'component_type': { + \ 'syntastic': 'error', + \ } + \ } + " Syntastic can call a post-check hook, let's update lightline there + " For more information: :help syntastic-loclist-callback + function! SyntasticCheckHook(errors) + call lightline#update() + endfunction +< +In order to understand the above codes, you firstly should know how the +colorschemes work in lightline.vim. Open the following file. + autoload/lightline/colorscheme/powerline.vim +The colorscheme is created by one dictionary: s:p (abbreviation for palette). +See the value of s:p.normal.right. +> + let s:p.normal.right = [ ['gray5', 'gray10'], + \ ['gray9', 'gray4'], + \ ['gray8', 'gray2'] ] +< +This array corresponds to the structure of g:lightline.active.right. Recall +the example A. +> + " Example A + let g:lightline.active.right = [ [ 'lineinfo', 'syntastic' ], + \ [ 'percent' ], + \ [ 'fileformat', 'fileencoding', 'filetype' ] ] +< +The colors are ([fgcolor, bgcolor): +> + (0) [ 'lineinfo', 'syntastic' ] --- s:p.normal.right[0] = ['gray5', 'gray10'] + (1) [ 'percent' ] --- s:p.normal.right[1] = ['gray9', 'gray4'] + (2) [ 'fileformat', 'fileencoding', 'filetype' ] --- s:p.normal.right[2] = ['gray8', 'gray2'] +< +Recall the example B. +> + " Example B + let g:lightline.active.right = [ [ 'syntastic', 'lineinfo' ], + \ [ 'percent' ], + \ [ 'fileformat', 'fileencoding', 'filetype' ] ] +< +If a component is specified in |g:lightline.component_expand|, lightline.vim +expands the components before setting to statusline/tabline. In this example, +the syntastic component is expanded using the |SyntasticStatuslineFlag| function. +This function returns a {string}. Let us call it `syntastic_flag`. +> + let syntastic_flag = SyntasticStatuslineFlag() +< +The syntastic component is now expanded, so it go up to one component group. +The type of the syntastic component is error, and the palette has error +colors, the result is: +> + " Expanded result of Example B + (error) [ syntastic_flag ] --- s:p.normal.error[0] = ['gray9', 'brightestred'] + (0) [ 'lineinfo' ] --- s:p.normal.right[0] = ['gray5', 'gray10'] + (1) [ 'percent' ] --- s:p.normal.right[1] = ['gray9', 'gray4'] + (2) [ 'fileformat', 'fileencoding', 'filetype' ] --- s:p.normal.right[2] = ['gray8', 'gray2'] +< +Thus the syntastic component has the red color. + + +Another example for |g:lightline.component_expand| is the tabs component. +Actually, the expand feature is created for the tabs component. +> + let g:lightline.tabline.left = [ [ 'tabs' ] ] + let g:lightline.component_expand = { + \ 'tabs': 'lightline#tabs' } +< +Create three tabs and select the middle tab. Then execute +> + echo lightline#tabs() + " [['%1T%{lightline#onetab(1,0)}'], + " ['%2T%{lightline#onetab(2,1)}'], + " ['%3T%{lightline#onetab(3,0)}%T']] +< +It returns an array of three elements. The expanded result is: +> + " Expanded result of tabline + (0) ['%1T%{lightline#onetab(1,0)}'] --- s:p.tabline.left[0] = ['gray9', 'gray4'] + (tabsel) ['%2T%{lightline#onetab(2,1)}'] --- s:p.tabline.tabsel[0] = ['gray9', 'gray1'] + (0) ['%3T%{lightline#onetab(3,0)}%T'] --- s:p.tabline.left[0] = ['gray9', 'gray4'] +< +If the tabline components are +> + let g:lightline.tabline.left = [ [ 'A', 'B', 'tabs', 'C', 'D' ] ] +< +then the expanded result is: +> + (0) ['A', 'B', '%1T%{lightline#onetab(1,0)}'] --- s:p.tabline.left[0] + (tabsel) ['%2T%{lightline#onetab(2,1)}'] --- s:p.tabline.tabsel[0] + (0) ['%3T%{lightline#onetab(3,0)}%T', 'C', 'D'] --- s:p.tabline.left[0] +< +In summary, when a function in |g:lightline.component_expand| returns an +array of three elements, the first element and the last element remains as a +part of existing component group. And the middle element goes up to new +component group. +------------------------------------------------------------------------------ +COLORSCHEME *lightline-colorscheme* +You can configure the colorscheme of lightline. For example, +> + let g:lightline = { + \ 'colorscheme': 'wombat', + \ } +< +The colorscheme files are found in the directory + + lightline.vim/autoload/lightline/colorscheme/ + +In each file, one global variable is defined. For example, in the landscape.vim +file, you see +> + let g:lightline#colorscheme#landscape#palette = s:p +< +In the file, the colors for the landscape colorscheme are defined. For example, +> + let s:p.normal.left = [ ['#0000ff', '#ffffff', 21, 231, 'bold' ], [ '#ffffff', '#0000ff', 231, 21 ] ] +< +defines the colors for the components on the left hand side, in normal mode. +> + let s:p.tabline.tabsel = [ [ '#dadada', '#121212', 253, 233 ] ] +< +defines the colors for the selected tab in tabline. In general, each palette +follows the following style: +> + let s:p.{mode}.{where} = [ [ {guifg}, {guibg}, {ctermfg}, {ctermbg} ], ... ] +< + + +Now, you can create your own colorscheme for lightline. Create a +yourcolorscheme.vim at + + {one of the paths in &rtp}/autoload/lightline/colorscheme/yourcolorscheme.vim + +The following code gives the minimal palette definition for lightline. +> + let s:p = {'normal': {}} + let s:p.normal.left = [ [ ... ] ] + let s:p.normal.right = [ [ ... ] ] + let s:p.normal.middle = [ [ ... ] ] + let g:lightline#colorscheme#yourcolorscheme#palette = s:p +< +And if you add the colorscheme configuration to your .vimrc(_vimrc), +> + let g:lightline = { + \ 'colorscheme': 'yourcolorscheme', + \ } +< +you find it possible to change the lightline colors as you wish. + +Moreover, if you want to change the colors based on the mode of vim, write +something like this: +> + let s:p.insert.left = [ [ ... ] ] + let s:p.insert.right = [ [ ... ] ] + let s:p.replace.left = [ [ ... ] ] + let s:p.replace.right = [ [ ... ] ] + ... + ... +< +For expanded components, you are recommended to define the following two +colors. +> + let s:p.normal.error = [ [ ... ] ] + let s:p.normal.warning = [ [ ... ] ] +< +For the complete list of components the color of which you should define in +your colorscheme, see the colorscheme files in lightline. + +It is sometimes painful to write all the colors for both gui and cterm. +Actually, lightline has some useful functions for writing colorschemes. For +example, see + lightline.vim/autoload/lightline/colorscheme/Tomorrow_Night.vim +this colorscheme is defined using only gui color numbers. And convert to the +normal colorscheme form using: +> + let g:lightline#colorscheme#Tomorrow_Night#palette = lightline#colorscheme#fill(s:p) +< +This function fills the cterm colors for a palette which has only gui colors, or +vice versa. However, note that using the convenient function sources an +additional Vim script file (autoload/lightline/colorscheme.vim), which causes +a little slow down. If you want to avoid this situation, write all the colors +as done in autoload/lightline/colorscheme/landscape.vim; firstly create the +colorscheme using the fill function, and see the result, in a sense, the +compiled version of your colorscheme. +> + echo g:lightline#colorscheme#yourcolorscheme#palette +< +Then copy and paste the result to the colorscheme file. + +If you want to contribute a new colorscheme that is not currently available +please follow the following rules: + *) All hex codes should be lowercase only + *) Use 2 space soft tabs + *) If your colorscheme has both light and dark variants, use a single file + *) Normal Mode should default to Cyan + *) Insert Mode should default to Green + *) Visual Mode should default to Yellow + *) Replace Mode should default to Red + +============================================================================== +EXAMPLES *lightline-examples* +You can configure the appearance of statusline. +Write the following examples in you .vimrc(_vimrc). + +In order to change the colorscheme: +> + let g:lightline = { + \ 'colorscheme': 'wombat', + \ } +< + +In order to define your own component: +> + let g:lightline = { + \ 'active': { + \ 'left': [ [ 'mode', 'paste' ], [ 'myfilename' ] ] + \ }, + \ 'component_function': { + \ 'myfilename': 'LightlineFilename', + \ 'myreadonly': 'LightlineReadonly', + \ 'mymodified': 'LightlineModified', + \ } + \ } + function! LightlineFilename() + return ('' != LightlineReadonly() ? LightlineReadonly() . ' ' : '') . + \ (&ft == 'vimfiler' ? vimfiler#get_status_string() : + \ &ft == 'unite' ? unite#get_status_string() : + \ '' != expand('%:t') ? expand('%:t') : '[No Name]') . + \ ('' != LightlineModified() ? ' ' . LightlineModified() : '') + endfunction + function! LightlineReadonly() + return &ft !~? 'help' && &readonly ? 'RO' : '' + endfunction + function! LightlineModified() + return &modifiable && &modified ? '+' : '' + endfunction +< + +Separators settings: +> + let g:lightline = { + \ 'separator': { 'left': '', 'right': '' }, + \ 'subseparator': { 'left': '|', 'right': '|' } + \ } +< + +For |powerline| font users: +> + let g:lightline = { + \ 'separator': { 'left': '', 'right': '' }, + \ 'subseparator': { 'left': '', 'right': '' } + \ } +< + +For |vim-powerline| font users: +> + let g:lightline = { + \ 'separator': { 'left': '⮀', 'right': '⮂' }, + \ 'subseparator': { 'left': '⮁', 'right': '⮃' } + \ } +< + +------------------------------------------------------------------------------ +NICE EXAMPLES *lightline-nice-examples* + +A nice example for non-patched font users. +> + let g:lightline = { + \ 'colorscheme': 'wombat', + \ 'active': { + \ 'left': [ [ 'mode', 'paste' ], [ 'fugitive', 'filename' ] ] + \ }, + \ 'component_function': { + \ 'fugitive': 'LightlineFugitive', + \ 'filename': 'LightlineFilename' + \ } + \ } + function! LightlineModified() + return &ft =~ 'help\|vimfiler' ? '' : &modified ? '+' : &modifiable ? '' : '-' + endfunction + function! LightlineReadonly() + return &ft !~? 'help\|vimfiler' && &readonly ? 'RO' : '' + endfunction + function! LightlineFilename() + return ('' != LightlineReadonly() ? LightlineReadonly() . ' ' : '') . + \ (&ft == 'vimfiler' ? vimfiler#get_status_string() : + \ &ft == 'unite' ? unite#get_status_string() : + \ &ft == 'vimshell' ? vimshell#get_status_string() : + \ '' != expand('%:t') ? expand('%:t') : '[No Name]') . + \ ('' != LightlineModified() ? ' ' . LightlineModified() : '') + endfunction + function! LightlineFugitive() + if &ft !~? 'vimfiler' && exists('*fugitive#head') + return fugitive#head() + endif + return '' + endfunction +< +A nice example for |vim-powerline| font users: +> + let g:lightline = { + \ 'colorscheme': 'wombat', + \ 'active': { + \ 'left': [ [ 'mode', 'paste' ], [ 'fugitive', 'filename' ] ] + \ }, + \ 'component_function': { + \ 'fugitive': 'LightlineFugitive', + \ 'filename': 'LightlineFilename' + \ }, + \ 'separator': { 'left': '⮀', 'right': '⮂' }, + \ 'subseparator': { 'left': '⮁', 'right': '⮃' } + \ } + function! LightlineModified() + return &ft =~ 'help\|vimfiler' ? '' : &modified ? '+' : &modifiable ? '' : '-' + endfunction + function! LightlineReadonly() + return &ft !~? 'help\|vimfiler' && &readonly ? '⭤' : '' + endfunction + function! LightlineFilename() + return ('' != LightlineReadonly() ? LightlineReadonly() . ' ' : '') . + \ (&ft == 'vimfiler' ? vimfiler#get_status_string() : + \ &ft == 'unite' ? unite#get_status_string() : + \ &ft == 'vimshell' ? vimshell#get_status_string() : + \ '' != expand('%:t') ? expand('%:t') : '[No Name]') . + \ ('' != LightlineModified() ? ' ' . LightlineModified() : '') + endfunction + function! LightlineFugitive() + if &ft !~? 'vimfiler' && exists('*fugitive#head') + let branch = fugitive#head() + return branch !=# '' ? '⭠ '.branch : '' + endif + return '' + endfunction +< + +------------------------------------------------------------------------------ +POWERFUL EXAMPLE *lightline-powerful-example* + +For users who uses lots of plugins: +> + let g:lightline = { + \ 'colorscheme': 'wombat', + \ 'active': { + \ 'left': [ [ 'mode', 'paste' ], [ 'fugitive', 'filename' ], ['ctrlpmark'] ], + \ 'right': [ [ 'syntastic', 'lineinfo' ], ['percent'], [ 'fileformat', 'fileencoding', 'filetype' ] ] + \ }, + \ 'component_function': { + \ 'fugitive': 'LightlineFugitive', + \ 'filename': 'LightlineFilename', + \ 'fileformat': 'LightlineFileformat', + \ 'filetype': 'LightlineFiletype', + \ 'fileencoding': 'LightlineFileencoding', + \ 'mode': 'LightlineMode', + \ 'ctrlpmark': 'CtrlPMark', + \ }, + \ 'component_expand': { + \ 'syntastic': 'SyntasticStatuslineFlag', + \ }, + \ 'component_type': { + \ 'syntastic': 'error', + \ }, + \ 'subseparator': { 'left': '|', 'right': '|' } + \ } + + function! LightlineModified() + return &ft =~ 'help' ? '' : &modified ? '+' : &modifiable ? '' : '-' + endfunction + + function! LightlineReadonly() + return &ft !~? 'help' && &readonly ? 'RO' : '' + endfunction + + function! LightlineFilename() + let fname = expand('%:t') + return fname == 'ControlP' && has_key(g:lightline, 'ctrlp_item') ? g:lightline.ctrlp_item : + \ fname == '__Tagbar__' ? g:lightline.fname : + \ fname =~ '__Gundo\|NERD_tree' ? '' : + \ &ft == 'vimfiler' ? vimfiler#get_status_string() : + \ &ft == 'unite' ? unite#get_status_string() : + \ &ft == 'vimshell' ? vimshell#get_status_string() : + \ ('' != LightlineReadonly() ? LightlineReadonly() . ' ' : '') . + \ ('' != fname ? fname : '[No Name]') . + \ ('' != LightlineModified() ? ' ' . LightlineModified() : '') + endfunction + + function! LightlineFugitive() + try + if expand('%:t') !~? 'Tagbar\|Gundo\|NERD' && &ft !~? 'vimfiler' && exists('*fugitive#head') + let mark = '' " edit here for cool mark + let branch = fugitive#head() + return branch !=# '' ? mark.branch : '' + endif + catch + endtry + return '' + endfunction + + function! LightlineFileformat() + return winwidth(0) > 70 ? &fileformat : '' + endfunction + + function! LightlineFiletype() + return winwidth(0) > 70 ? (&filetype !=# '' ? &filetype : 'no ft') : '' + endfunction + + function! LightlineFileencoding() + return winwidth(0) > 70 ? (&fenc !=# '' ? &fenc : &enc) : '' + endfunction + + function! LightlineMode() + let fname = expand('%:t') + return fname == '__Tagbar__' ? 'Tagbar' : + \ fname == 'ControlP' ? 'CtrlP' : + \ fname == '__Gundo__' ? 'Gundo' : + \ fname == '__Gundo_Preview__' ? 'Gundo Preview' : + \ fname =~ 'NERD_tree' ? 'NERDTree' : + \ &ft == 'unite' ? 'Unite' : + \ &ft == 'vimfiler' ? 'VimFiler' : + \ &ft == 'vimshell' ? 'VimShell' : + \ winwidth(0) > 60 ? lightline#mode() : '' + endfunction + + function! CtrlPMark() + if expand('%:t') =~ 'ControlP' && has_key(g:lightline, 'ctrlp_item') + call lightline#link('iR'[g:lightline.ctrlp_regex]) + return lightline#concatenate([g:lightline.ctrlp_prev, g:lightline.ctrlp_item + \ , g:lightline.ctrlp_next], 0) + else + return '' + endif + endfunction + + let g:ctrlp_status_func = { + \ 'main': 'CtrlPStatusFunc_1', + \ 'prog': 'CtrlPStatusFunc_2', + \ } + + function! CtrlPStatusFunc_1(focus, byfname, regex, prev, item, next, marked) + let g:lightline.ctrlp_regex = a:regex + let g:lightline.ctrlp_prev = a:prev + let g:lightline.ctrlp_item = a:item + let g:lightline.ctrlp_next = a:next + return lightline#statusline(0) + endfunction + + function! CtrlPStatusFunc_2(str) + return lightline#statusline(0) + endfunction + + let g:tagbar_status_func = 'TagbarStatusFunc' + + function! TagbarStatusFunc(current, sort, fname, ...) abort + let g:lightline.fname = a:fname + return lightline#statusline(0) + endfunction + + " Syntastic can call a post-check hook, let's update lightline there + " For more information: :help syntastic-loclist-callback + function! SyntasticCheckHook(errors) + call lightline#update() + endfunction + + let g:unite_force_overwrite_statusline = 0 + let g:vimfiler_force_overwrite_statusline = 0 + let g:vimshell_force_overwrite_statusline = 0 +< +------------------------------------------------------------------------------ +TROUBLESHOOTING *lightline-troubleshooting* + +Problem 1: |lightline-problem-1| + How to install this plugin. + +Problem 2: |lightline-problem-2| + How to update this plugin. + +Problem 3: |lightline-problem-3| + How to uninstall this plugin. + +Problem 4: |lightline-problem-4| + Cool statuslines appear only on |:vsp|. + +Problem 5: |lightline-problem-5| + The statusline does not seem to be correctly colored. + +Problem 6: |lightline-problem-6| + How to install a patched font. + +Problem 7: |lightline-problem-7| + Right triangles do not stick to the right components with the + patched font. + +Problem 8: |lightline-problem-8| + Triangles do not appear. Triangles look weird. + +Problem 9: |lightline-problem-9| + Where can I find the list of all the cool characters for patched fonts? + +Problem 10: |lightline-problem-10| + Cool statusline disappears in |unite|, |vimfiler| and |vimshell| + buffers. + +Problem 11: |lightline-problem-11| + Cool statusline disappears in |CtrlP|, |Tagbar| buffers. + +Problem 12: |lightline-problem-12| + How to make the plus sign red like |powerline|? + +Problem 13: |lightline-problem-13| + How to change the lightline colorscheme on the fly. + +Problem 14: |lightline-problem-14| + The 'E541' warning appears on the right hand side. + Many components disable the statusline of lightline. + +Problem 15: |lightline-problem-15| + Do not deal with the tabline. + Do not use the fancy separators in the tabline. + +Problem 16: |lightline-problem-16| + When changed the component to a function component to an expanding + component, the statusline of lightline is sometimes disabled. + +Problem 17: |lightline-problem-17| + Found a bug of this plugin. + Got many errors while using this plugin. + Vim hangs while using this plugin. + Want this plugin to be more configurable. + This troubleshooting is not helpful. + +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +Problem 1: *lightline-problem-1* + How to install this plugin. + + If you are to install this plugin manually: + + 1. Put all the files under $VIM. + + If you are using |vim-pathogen|, install this plugin with the + following command. +> + git clone https://github.com/itchyny/lightline.vim \ + ~/.vim/bundle/lightline.vim +< + If you are to install this plugin using |Vundle|: + + 1. Add the following configuration to your + .vimrc(_vimrc). +> + Plugin 'itchyny/lightline.vim' +< + 2. Install with |:PluginInstall|. + + If you are to install this plugin using |NeoBundle|: + + 1. Add the following configuration to your + .vimrc(_vimrc). +> + NeoBundle 'itchyny/lightline.vim' +< + 2. Install with |:NeoBundleInstall|. + + If you are to install this plugin using |vim-plug|: + + 1. Add the following configuration to your + .vimrc(_vimrc). +> + Plug 'itchyny/lightline.vim' +< + 2. Install with |:PlugInstall|. + +Problem 2: *lightline-problem-2* + How to update this plugin. + + If you have installed this plugin manually: + + 1. Access https://github.com/itchyny/lightline.vim . + 2. Download the latest scripts. + 3. Place the scripts as written in Problem 1. + + If you have installed this plugin using Vundle: + + 1. Execute |:PluginUpdate|. + + If you have installed this plugin using NeoBundle: + + 1. Execute |:NeoBundleUpdate|. + + If you have installed this plugin using vim-plug: + + 1. Execute |:PlugUpdate|. + +Problem 3: *lightline-problem-3* + How to uninstall this plugin. + + If you have installed this plugin manually: + + 1. Remove all the lightline.*s under $VIM. + + If you have installed this plugin using Vundle: + + 1. Remove the :Plugin 'itchyny/lightline.vim' + configuration from your .vimrc(_vimrc). + 2. Update with |:PluginClean|. + + If you have installed this plugin using NeoBundle: + + 1. Remove the :NeoBundle 'itchyny/lightline.vim' + configuration from your .vimrc(_vimrc). + 2. Update with |:NeoBundleClean|. + + If you have installed this plugin using vim-plug: + + 1. Remove the :Plug 'itchyny/lightline.vim' + configuration from your .vimrc(_vimrc). + 2. Update with |:PlugClean|. + +Problem 4: *lightline-problem-4* + Cool statuslines appear only on |:vsp|. + + Add the following setting to your .vimrc(_vimrc). +> + set laststatus=2 +< +Problem 5: *lightline-problem-5* + The statusline does not seem to be correctly colored. + + Add +> + export TERM=xterm-256color +< + to your .*shrc and add +> + if !has('gui_running') + set t_Co=256 + endif +< + to your .vimrc(_vimrc). + +Problem 6: *lightline-problem-6* + How to install a patched font. + + There are two kinds of patched fonts: + + + The patched fonts for |vim-powerline| + (https://github.com/Lokaltog/vim-powerline): + follow the guide https://github.com/Lokaltog/vim-powerline/tree/develop/fontpatcher + + The patched fonts for |powerline| + (https://github.com/Lokaltog/powerline): + download from https://github.com/Lokaltog/powerline-fonts + +Problem 7: *lightline-problem-7* + Right triangles do not stick to the right components with patched + font. + + Remove the following setting from your .vimrc(_vimrc). +> + set ambiwidth=double +< + If you want to keep this setting, try the patched font for + |vim-powerline|. + +Problem 8: *lightline-problem-8* + Triangles do not appear. Triangles look weird. + + If the triangles do not appear (but you get some spaces or + weird characters like <bf> or ¿), firstly try adding +> + scriptencoding utf-8 + set encoding=utf-8 +< + to the head of your .vimrc(_vimrc). Still you have weird + characters, use the unicode numbers. For |powerline| font + users: +> + \ 'separator': { 'left': "\ue0b0", 'right': "\ue0b2" }, + \ 'subseparator': { 'left': "\ue0b1", 'right': "\ue0b3" } +< + For |vim-powerline| font users: +> + \ 'separator': { 'left': "\u2b80", 'right': "\u2b82" }, + \ 'subseparator': { 'left': "\u2b81", 'right': "\u2b83" } +< + The full list of unicode numbers for fancy characters is shown + in |lightline-problem-9|. + + If the triangles are shown in appropriate characters but the + colors do not look correctly, see the following. + If you are using iTerm2, change the following settings. + + + set Profiles>Colors>Minimum contrast to the Lowest. + + set Profiles>Window>Transparency to the Opaquest. + + For other terminals, this weird-triangle problem will be + resolved by disabling transparency or contrast adjustment. + +Problem 9: *lightline-problem-9* + Where can I find the list of all the cool characters for patched fonts? + + Default powerline vim-powerline + separator.left '' '' (\ue0b0) '⮀' (\u2b80) + separator.right '' '' (\ue0b2) '⮂' (\u2b82) + subseparator.left '|' '' (\ue0b1) '⮁' (\u2b81) + subseparator.right '|' '' (\ue0b3) '⮃' (\u2b83) + branch symbol -- '' (\ue0a0) '⭠' (\u2b60) + readonly symbol -- '' (\ue0a2) '⭤' (\u2b64) + linecolumn symbol -- '' (\ue0a1) '⭡' (\u2b61) + +Problem 10: *lightline-problem-10* + Cool statusline disappears on |unite|, |vimfiler| and |vimshell| + buffers. + + Add the following settings to your .vimrc(_vimrc). +> + let g:unite_force_overwrite_statusline = 0 + let g:vimfiler_force_overwrite_statusline = 0 + let g:vimshell_force_overwrite_statusline = 0 +< +Problem 11: *lightline-problem-11* + Cool statusline disappears in |CtrlP|, |Tagbar| buffers. + + Add the following settings to your .vimrc(_vimrc). +> + let g:ctrlp_status_func = { + \ 'main': 'CtrlPStatusFunc_1', + \ 'prog': 'CtrlPStatusFunc_2', + \ } + function! CtrlPStatusFunc_1(focus, byfname, regex, prev, item, next, marked) + return lightline#statusline(0) + endfunction + function! CtrlPStatusFunc_2(str) + return lightline#statusline(0) + endfunction + + let g:tagbar_status_func = 'TagbarStatusFunc' + function! TagbarStatusFunc(current, sort, fname, ...) abort + return lightline#statusline(0) + endfunction +< + See |lightline-powerful-example| for more cool settings for + these plugins. + +Problem 12: *lightline-problem-12* + How to make the plus sign red like |powerline|? + + Use the following settings. +> + let g:lightline = { + \ 'component': { + \ 'modified': '%#ModifiedColor#%{LightlineModified()}', + \ } + \ } + function! LightlineModified() + let map = { 'V': 'n', "\<C-v>": 'n', 's': 'n', 'v': 'n', "\<C-s>": 'n', 'c': 'n', 'R': 'n'} + let mode = get(map, mode()[0], mode()[0]) + let bgcolor = {'n': [240, '#585858'], 'i': [31, '#0087af']} + let color = get(bgcolor, mode, bgcolor.n) + exe printf('hi ModifiedColor ctermfg=196 ctermbg=%d guifg=#ff0000 guibg=%s term=bold cterm=bold', + \ color[0], color[1]) + return &modified ? '+' : &modifiable ? '' : '-' + endfunction +< + It's surely complicated. There's no easy API to do a thing + like this. But it means that your request does not match + the spirit of lightline. + +Problem 13: *lightline-problem-13* + How to change the lightline colorscheme on the fly. + + To update your lightline colorscheme in sync with your vim + colorscheme (only for select colorschemes which exist for + both), add the following settings to your .vimrc(_vimrc). +> + augroup LightlineColorscheme + autocmd! + autocmd ColorScheme * call s:lightline_update() + augroup END + function! s:lightline_update() + if !exists('g:loaded_lightline') + return + endif + try + if g:colors_name =~# 'wombat\|solarized\|landscape\|jellybeans\|seoul256\|Tomorrow' + let g:lightline.colorscheme = + \ substitute(substitute(g:colors_name, '-', '_', 'g'), '256.*', '', '') + call lightline#init() + call lightline#colorscheme() + call lightline#update() + endif + catch + endtry + endfunction +< + If you have not settled on a single lightline colorscheme, you + can easily switch between lightline colorschemes by adding the + following LightlineColorscheme command to your .vimrc(_vimrc). +> + function! s:set_lightline_colorscheme(name) abort + let g:lightline.colorscheme = a:name + call lightline#init() + call lightline#colorscheme() + call lightline#update() + endfunction + + function! s:lightline_colorschemes(...) abort + return join(map( + \ globpath(&rtp,"autoload/lightline/colorscheme/*.vim",1,1), + \ "fnamemodify(v:val,':t:r')"), + \ "\n") + endfunction + + command! -nargs=1 -complete=custom,s:lightline_colorschemes LightlineColorscheme + \ call s:set_lightline_colorscheme(<q-args>) +< +Problem 14: *lightline-problem-14* + The 'E541' warning appears on the right hand side. + Many components disable the statusline of lightline. + + The number of items in statusline/tabline is limited to 80 + (see |E541|). You cannot register too much components. + +Problem 15: *lightline-problem-15* + Do not deal with the tabline. + Do not use the fancy separators in the tabline. + + You can disable the tabline feature of lightline.vim using: +> + let g:lightline = { + \ 'enable': { 'tabline': 0 }, + \ } +< + If you don't like the separators in the tabline, use: +> + let g:lightline = { + \ 'tabline_separator': { 'left': "", 'right': "" }, + \ 'tabline_subseparator': { 'left': "", 'right': "" }, + \ } +< +Problem 16: *lightline-problem-16* + When changed the component to a function component to an expanding + component, the statusline of lightline is sometimes disabled. + + When you changed from +> + \ 'component_function': { + \ 'my': 'My', + \ } +< + to +> + \ 'component_expand': { + \ 'my': 'My', + \ } +< + the statusline of lightline is disabled unexpectedly. + In such a case, the text returned by 'My' function may include + the '%' character. Replace all the '%' signs with '%%'. +> + function My() + ... + return substitute(text, '%', '%%', 'g') + endfunction +< +Problem 17: *lightline-problem-17* + Found a bug of this plugin. + Got many errors while using this plugin. + Vim hangs while using this plugin. + Want this plugin to be more configurable. + This troubleshooting is not helpful. + + Report/Request the issue/feature at + https://github.com/itchyny/lightline.vim/issues. + +============================================================================== +vim:tw=78:sw=4:ts=8:ft=help:norl:noet: |