lightline.vim/doc/lightline.txt

*lightline.txt*	A light and configurable statusline for Vim

Version: 0.0
Author: itchyny (https://github.com/itchyny)
License: MIT License
Repository: https://github.com/itchyny/lightline.vim
Last Change: 2013/08/27 23:25:34.

CONTENTS					*lightline-contents*

Introduction				|lightline-introduction|
Spirit					|lightline-spirit|
Option					|lightline-option|
Font					|lightline-font|
Function				|lightline-function|
Examples				|lightline-examples|
Nice Examples				|lightline-nice-examples|
Troubleshooting				|lightline-troubleshooting|
Changelog				|lightline-changelog|

==============================================================================
INTRODUCTION					*lightline-introduction*

The *lightline* plugin is a light and configurable statusline for Vim.

------------------------------------------------------------------------------
SPIRIT						*lightline-spirit*

	Minimalism
	    The core script is very small.

	Configurability
	    You can create your own component and easily add to the statusline.

	Orthogonality
	    Any plugin should not change the settings of another plugin.
	    Such plugin-crossing settings should be written by users in
	    .vimrc.

	You might find this plugin is not so useful by default. This plugin
	does not provide the branch information, which is a very basic
	component in existing plugins. The reason is that branch component is
	one of plugin-crossing settings so users should write the settings
	using the APIs of the both plugins. Hospitality makes a plugin messy.
	Good APIs keep a plugin clean.

------------------------------------------------------------------------------
OPTIONS						*lightline-option*

	g:lightline				*g:lightline*
		All the options are stored into this global variable.

	g:lightline.active			*g:lightline.active*
	g:lightline.inactive			*g:lightline.inactive*
		Dictionaries to specify the status 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' ] ] }
<
	g:lightline.component			*g:lightline.component*
		Dictionary for statusline 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': '%{strlen(&fenc)?&fenc:&enc}',
		    \ 'fileformat': '%{&fileformat}',
		    \ 'filetype': '%{strlen(&filetype)?&filetype:"no ft"}',
		    \ 'percent': '%3p%%',
		    \ 'percentwin': '%P',
		    \ 'lineinfo': '%3l:%-2v',
		    \ 'line': '%l',
		    \ 'column': '%c' }
<
	g:lightline.component_visible_condition		*g:lightline.component_visible_condition*
		Dictionary of boolean expressions for the components.
		Each expression should correspond to the condition each
		component have non-zero length.
		The default value is:
>
		let g:lightline.component_visible_condition = {
		    \ 'modified': '&modified||!&modifiable',
		    \ 'readonly': '&readonly',
		    \ 'paste': '&paste' }
<
		Users are recommended to set this option together with the
		component itself.

	g:lightline.component_function		*g:lightline.component_function*
		Another dictionary for components. This is more convenient
		because the user does not have to set both component and
		component_visible_condition. If a component set to both component and
		component_function, the setting of component_function has priority.
		For example, if you want a component for read-only mark, which
		disappears in help windows:
>
		let g:lightline = {
			\ 'active': {
			\   'left': [ [ 'mode', 'paste' ],
			\             [ 'myreadonly', 'filename', 'modified' ] ],
			\ },
			\ 'component_function': {
			\   'myreadonly': 'MyReadonly'
			\ },
			\ }
		function! MyReadonly()
			return &ft !~? 'help' && &readonly ? 'RO' : ''
		endfunction
<
	g:lightline.colorscheme			*g:lightline.colorscheme*
		The colorscheme for lightline.vim.
		Currently, wombat, solarized, powerline, jellybeans, Tomorrow,
		Tomorrow_Night, and landscape are available.
		The default value is:
>
		let g:lightline.colorscheme = 'default'
<
		Note that the default colorscheme is exactly the same as
		powerline theme.

	g:lightline.mode_map			*g:lightline.mode_map*
		A dictionary of names for mode.
		The default value is:
>
		let g:lightline.mode_map = {
		    \ 'n' : 'NORMAL',
		    \ 'i' : 'INSERT',
		    \ 'R' : 'REPLACE',
		    \ 'v' : 'VISUAL',
		    \ 'V' : 'V-LINE',
		    \ 'c' : 'COMMAND',
		    \ '': 'V-BLOCK',
		    \ 's' : 'SELECT',
		    \ 'S' : 'S-LINE',
		    \ '': 'S-BLOCK',
		    \ '?': '      ' }
<
		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*
		A dictionaries to store separators.
		The default value is
>
		let g:lightline.separator = { 'left': '', 'right': '' }
		let g:lightline.subseparator = { 'left': '|', 'right': '|' }
<

==============================================================================
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': 'MyReadonly',
		\   'fugitive': 'MyFugitive'
		\ },
		\ 'separator': { 'left': '', 'right': '' },
		\ 'subseparator': { 'left': '', 'right': '' }
		\ }
	function! MyReadonly()
		return &readonly ? '' : ''
	endfunction
	function! MyFugitive()
		return exists("*fugitive#head") && strlen(fugitive#head()) ? ''.fugitive#head() : ''
	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': 'MyReadonly',
		\   'fugitive': 'MyFugitive'
		\ },
		\ 'separator': { 'left': '⮀', 'right': '⮂' },
		\ 'subseparator': { 'left': '⮁', 'right': '⮃' }
		\ }
	function! MyReadonly()
		return &readonly ? '⭤' : ''
	endfunction
	function! MyFugitive()
		return exists("*fugitive#head") && strlen(fugitive#head()) ? '⭠ '.fugitive#head() : ''
	endfunction
<

==============================================================================
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 variable |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.

Following functions are exposed, but users may not need.

	lightline#link()			*lightline#link()*
		Creates links of the highlight groups for the active window.

	lightline#highlight(inactive)		*lightline#highlight()*
		Returns |statusline| strings. If the argument is 0, it returns
		the statusline for active window, and the statusline for
		inactive window otherwise.

==============================================================================

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': 'MyFilename',
		\   'myreadonly': 'MyReadonly',
		\   'mymodified': 'MyModified',
		\ }
		\ }
	function! MyFilename()
		return ('' != MyReadonly() ? MyReadonly() . ' ' : '') .
		      \ (&ft == 'vimfiler' ? vimfiler#get_status_string() :
		      \  &ft == 'unite' ? unite#get_status_string() :
		      \ '' != expand('%t') ? expand('%t') : '[No Name]') .
		      \ ('' != MyModified() ? ' ' . MyModified() : '')
	endfunction
	function! MyReadonly()
		return &ft !~? 'help' && &readonly ? 'RO' : ''
	endfunction
	function! MyModified()
		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': 'MyFugitive',
		\   'filename': 'MyFilename'
		\ }
		\ }
	function! MyModified()
		return &ft =~ 'help\|vimfiler' ? '' : &modified ? '+' : &modifiable ? '' : '-'
	endfunction
	function! MyReadonly()
		return &ft !~? 'help\|vimfiler' && &readonly ? 'RO' : ''
	endfunction
	function! MyFilename()
		return ('' != MyReadonly() ? MyReadonly() . ' ' : '') .
		\ (&ft == 'vimfiler' ? vimfiler#get_status_string() :
		\  &ft == 'unite' ? unite#get_status_string() :
		\  &ft == 'vimshell' ? vimshell#get_status_string() :
		\ '' != expand('%t') ? expand('%t') : '[No Name]') .
		\ ('' != MyModified() ? ' ' . MyModified() : '')
	endfunction
	function! MyFugitive()
		return &ft !~? 'vimfiler' && exists("*fugitive#head") && strlen(fugitive#head()) ? fugitive#head() : ''
	endfunction
<
A nice example for |vim-powerline| font users:
>
	let g:lightline = {
		\ 'colorscheme': 'wombat',
		\ 'active': {
		\   'left': [ [ 'mode', 'paste' ], [ 'fugitive', 'filename' ] ]
		\ },
		\ 'component_function': {
		\   'fugitive': 'MyFugitive',
		\   'filename': 'MyFilename'
		\ },
		\ 'separator': { 'left': '⮀', 'right': '⮂' },
		\ 'subseparator': { 'left': '⮁', 'right': '⮃' }
		\ }
	function! MyModified()
		return &ft =~ 'help\|vimfiler' ? '' : &modified ? '+' : &modifiable ? '' : '-'
	endfunction
	function! MyReadonly()
		return &ft !~? 'help\|vimfiler' && &readonly ? '⭤' : ''
	endfunction
	function! MyFilename()
		return ('' != MyReadonly() ? MyReadonly() . ' ' : '') .
		\ (&ft == 'vimfiler' ? vimfiler#get_status_string() :
		\  &ft == 'unite' ? unite#get_status_string() :
		\  &ft == 'vimshell' ? vimshell#get_status_string() :
		\ '' != expand('%t') ? expand('%t') : '[No Name]') .
		\ ('' != MyModified() ? ' ' . MyModified() : '')
	endfunction
	function! MyFugitive()
		return &ft !~? 'vimfiler' && exists("*fugitive#head") && strlen(fugitive#head()) ? '⭠ '.fugitive#head() : ''
	endfunction
<
------------------------------------------------------------------------------
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 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 on |unite|, |vimfiler| and |vimshell|
	buffers.

Problem 11:				|lightline-problem-11|
	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).
>
			Bundle 'itchyny/lightline.vim'
<
			2. Install with |:BundleInstall|.

		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|.

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 |:BundleInstall!|. Or try git pull in the
			directory of this plugin.

		If you have installed this plugin using NeoBundle:

			1. Execute |:NeoBundleInstall!|. Or try git pull in
			the directory of this plugin.

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 :Bundle 'itchyny/lightline.vim'
			configuration from your .vimrc(_vimrc).
			2. Update with |:BundleClean|.

		If you have installed this plugin using NeoBundle:

			1. Remove the :NeoBundle 'itchyny/lightline.vim'
			configuration from your .vimrc(_vimrc).
			2. Update with |:NeoBundleClean|.

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 look weird.

		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		''		''		'⮀'
	separator.right		''		''		'⮂'
	subseparator.left	'|'		''		'⮁'
	subseparator.right	'|'		''		'⮃'
	branch symbol		--		''		'⭠'
	readonly symbol		--		''		'⭤'
	linecolumn symbol	--		''		'⭡'

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


==============================================================================
CHANGELOG					*lightline-changelog*

0.0	2013-08-21, ...
	- Initial commit and implementation

==============================================================================
vim:tw=78:sw=4:ts=8:ft=help:norl:noet: