From 6c5672d6862ba97ef73812783ba714d66fdec2fe Mon Sep 17 00:00:00 2001 From: Bailey Ling Date: Wed, 28 Aug 2013 02:36:12 +0000 Subject: [PATCH] update documentation. --- autoload/airline/extensions.vim | 6 +---- autoload/airline/extensions/example.vim | 24 +++++++------------ autoload/airline/extensions/whitespace.vim | 1 + doc/airline.txt | 28 ++++++++++++++-------- 4 files changed, 29 insertions(+), 30 deletions(-) diff --git a/autoload/airline/extensions.vim b/autoload/airline/extensions.vim index 9d65207e..744a4985 100644 --- a/autoload/airline/extensions.vim +++ b/autoload/airline/extensions.vim @@ -28,11 +28,7 @@ let s:filetype_regex_overrides = {} function! s:check_defined_section(name) if !exists('w:airline_section_{a:name}') - if g:airline_section_{a:name} == '__' - let w:airline_section_{a:name} = '' - else - let w:airline_section_{a:name} = g:airline_section_{a:name} - endif + let w:airline_section_{a:name} = g:airline_section_{a:name} endif endfunction diff --git a/autoload/airline/extensions/example.vim b/autoload/airline/extensions/example.vim index a37f2405..d522bd68 100644 --- a/autoload/airline/extensions/example.vim +++ b/autoload/airline/extensions/example.vim @@ -6,24 +6,18 @@ if !exists('g:airline#extensions#example#number_of_cats') let g:airline#extensions#example#number_of_cats = 42 endif -" There are predominantly two methods for integrating a plugin into -" vim-airline. The first method here simply modifies the global section and -" appends information to it. This is useful for cases where the information -" should be displayed all the time for all filetypes. +" First we define an init function that will be invoked from extensions.vim function! airline#extensions#example#init(ext) - let g:airline_section_y .= '%{airline#extensions#example#get_cats()}' -endfunction -" The second method involves using the 'ext'ension manager that was passed in -" and appends a name of a function. This function will be invoked just prior -" to updating the statusline. This method is useful for plugin-specific -" statuslines (like NERDTree or Tagbar) or language specific plugins (like -" virtualenv) which do not need to be loaded all the time. -function! airline#extensions#example#init(ext) + " Here we define a new part for the plugin. This allows users to place this + " extension in arbitrary locations. + let g:airline_parts.cats = '%{airline#extensions#example#get_cats()}' + + " Next up we add a funcref so that we can run some code prior to the + " statusline getting modifed. call a:ext.add_statusline_func('airline#extensions#example#apply') - " There is also the following function for making changes just prior to an - " inactive statusline. + " You can also add a funcref for inactive statuslines. " call a:ext.add_inactive_statusline_func('airline#extensions#example#unapply') endfunction @@ -34,7 +28,7 @@ function! airline#extensions#example#apply(...) " Let's use a helper function. It will take care of ensuring that the " window-local override exists (and create one based on the global " airline_section if not), and prepend to it. - call airline#extensions#prepend_to_section('x', '%{airline#extensions#example#get_cats()} ') + call airline#extensions#prepend_to_section('x', g:airline_parts.cats) endif endfunction diff --git a/autoload/airline/extensions/whitespace.vim b/autoload/airline/extensions/whitespace.vim index a2029acb..0aa8fbe2 100644 --- a/autoload/airline/extensions/whitespace.vim +++ b/autoload/airline/extensions/whitespace.vim @@ -61,6 +61,7 @@ function! airline#extensions#whitespace#toggle() call airline#extensions#whitespace#init() let s:enabled = 1 endif + echo 'Whitespace checking: '.(s:enabled ? 'Enabled' : 'Disabled') endfunction function! airline#extensions#whitespace#init(...) diff --git a/doc/airline.txt b/doc/airline.txt index 7a348fe8..3734a1e2 100644 --- a/doc/airline.txt +++ b/doc/airline.txt @@ -168,11 +168,11 @@ extension. > variable names default contents ---------------------------------------------------------------------------- - let g:airline_section_a (the mode/paste indicator) - let g:airline_section_b (the fugitive/lawrencium branch indicator) + let g:airline_section_a (mode, paste, iminsert) + let g:airline_section_b (hunks, branch) let g:airline_section_c (bufferline or filename) let g:airline_section_gutter (readonly, csv) - let g:airline_section_x (tagbar, virtualenv, filetype) + let g:airline_section_x (tagbar, filetype, virtualenv) let g:airline_section_y (fileencoding, fileformat) let g:airline_section_z (percentage, line number, column number) let g:airline_section_warning (syntastic, whitespace) @@ -309,23 +309,29 @@ temporary override. > PIPELINE *airline-pipeline* Sometimes you want to do more than just use overrides. The statusline funcref -is invoked and passed a bunch of arguments. The first of these arguments is -the statusline builder. You can use this to build completely custom -statuslines to your liking. Here is an example: > +is invoked and passed two arguments. The first of these arguments is the +statusline builder. You can use this to build completely custom statuslines +to your liking. Here is an example: > > function! MyPlugin(...) " first variable is the statusline builder let builder = a:1 - " build and set the statusline " WARNING: the API for the builder is not finalized and may change call builder.add_section('Normal', '%f') call builder.add_section('WarningMsg', '%{getcwd()}') - call setwinvar(winnr(), '&statusline', builder.build()) + call builder.split() + call builder.add_section('airline_z', '%p%%') - return -1 + " tell the core to use the contents of the builder + return 1 endfunction < +The above example uses various some example highlight groups to demonstrate +that you can make any combination from the loaded colorscheme. However, if +you want colors to change between modes, you should use one of the section +highlight groups, e.g. `airline_a` and `airline_b`. + The second variable is the context, which is a dictionary containing various values such as whether the statusline is active or not, and the window number. > @@ -334,7 +340,6 @@ values such as whether the statusline is active or not, and the window number. 'active': 'whether the window is active or not', } < - *airline-pipeline-return-codes* The pipeline accepts various return codes and can be used to determine the next action. The following are the supported codes: > @@ -374,6 +379,9 @@ For contributions into the plugin, here are the following guidelines: b. Configuration variables for the extension should reside in the extension, e.g. `g:airline#extensions#foo_plugin#bar_variable`. + c. A value should be added to the `g:airline_parts` dictionary such that + the extension can be arbitrarily positioned. + See the source of |example.vim| for a working extension. ==============================================================================