path: root/start/lightline/doc/lightline.txt

*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: