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 04:42:21.

CONTENTS					*lightline-contents*

Introduction				|lightline-introduction|
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.

------------------------------------------------------------------------------
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()}',
		    \ 'filename': '%t',
		    \ 'modified': '%M',
		    \ 'paste': '%{&paste?"PASTE":""}',
		    \ 'readonly': '%R',
		    \ 'fileencoding': '%{strlen(&fenc)?&fenc:&enc}',
		    \ 'fileformat': '%{&fileformat}',
		    \ 'filetype': '%{strlen(&filetype)?&filetype:"no ft"}',
		    \ 'percent': '%3p%%',
		    \ 'lineinfo': '%3l:%-2v' }
<
	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.
		For example, the visible condition for paste component is:
>
		let g:lightline.component_visible_condition = {
		    \ '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' && &ro ? '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 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| or |powerline|.

The patched font for |powerline| is available at
https://github.com/Lokaltog/powerline-fonts

How to create the 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 |g:lightline| variable.

	lightline#colorscheme()			*lightline#colorscheme()*
		Initializes the colorscheme and 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 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' && &ro ? '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 |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' && &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
<
------------------------------------------------------------------------------
TROUBLESHOOTING					*lightline-troubleshooting*


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

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

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