*vimple#ls.txt* Plugin for accessing the :ls info programatically
VIM REFERENCE MANUAL by Barry Arthur
Help on using vimple#ls *vimple#ls*
1. The Vimple Architecture |vimple#ls-architecture|
2. The Buffer List Object |vimple#ls-object|
3. Public Methods |vimple#ls-public_methods|
4. Plugins Using Vimple Buffer List |vimple#ls-plugins|
==============================================================================
1. THE VIMPLE ARCHITECTURE *vimple#ls-architecture*
|Vimple| uses VimLOO (Object Oriented VimL) and so returns Objects which
contain methods to update and manipulate them. See OBJECT ORIENTED PROGRAMMING
in section |41.8| to learn more about VimLOO.
==============================================================================
2. THE BUFFER LIST OBJECT *vimple#ls-object*
The Vimple Buffer List provides a scriptable interface to Vim's |:buffers| (or
|:ls|) command.
*vimple#ls-constructor*
Constructor~
To instantiate a new vimple#ls object:
>
:let bl = vimple#ls#new()
<
This will create a globally accessible object called:
>
bl
<
3. BUFFER LIST PUBLIC METHODS *vimple#ls-public-methods*
*vimple#ls-update()*
------------------------------------------------------------------------------
Args: NONE~
Overview:~
Refreshes the object's internal buffer list data structure.
Synopsis:~
>
:call vimple#bl.update()
<
Description:~
Use this method to update the vimple#bl object's knowledge of Vim's
current buffer state. If you open new files or use |:bdelete| or |:bwipeout|
to remove buffers, you will need to manually update your vimple#ls
objects to reflect those changes. The need to call this manually for certain
vimple#ls calls might be removed in future versions.
Return:~
The bl object which allows chaining of vimple#ls methods, like:
>
:echo vimple#bl.update().to_s()
<
*vimple#ls-to_s()*
------------------------------------------------------------------------------
Args: [format]~
Overview:~
Returns a string representation of the buffer list.
Synopsis:~
>
:echo vimple#bl.to_s( ... )
<
Description:~
This method returns a simple textual representation of the buffer list. The
default (without arguments) tries to emulate the layout of the builtin |:ls|
output. This method should be used with Vim's :echo or :let statements, like:
>
:echo vimple#bl.to_s()
:echo vimple#bl.to_s("%n\n")
:let my_buffers = split(vimple#bl.to_s("%n\n"), "\n")
<
Arguments:~
format~
Using a printf-like format specifier, you can alter the appearance of the
output. The available format specifiers are:
- %b buffer number
- %n name
- %f flags
- %l cursor line
Return:~
A string of newline terminated buffer list entries similar to the |:ls|
builtin.
NOTE: Currently you have to manually call vimple#bl.update() before calling
vimple#bl.to_s() if you want the latest information. This may change in a
future version.
*vimple#ls-to_l()*
------------------------------------------------------------------------------
Args: [buffer_property]~
Overview:~
Returns a list representation of the buffer list.
Synopsis:~
>
:echo vimple#bl.to_l( ... )
<
Description:~
This method returns a list representation of the buffer list.
Arguments:~
The to_l() method is actually just a wrapper for the |vimple#ls-buffers()|
method. See that method for details about the buffer_property argument.
Return:~
The to_l() method returns a list of dictionaries, each with the following
fields (with example values):
>
{'active': 0,
'number': '1',
'alternate': 0,
'name': 'doc/buffer_list.txt',
'readonly': 0,
'current': 1,
'line': '1',
'modified': 0,
'modifiable': 1,
'hidden': 0,
'read_error': 0,
'listed': 1
}
<
NOTE: Currently you have to manually call vimple#bl.update() before calling
vimple#bl.to_l() if you want the latest information. This may change in a
future version.
*vimple#ls-to_d()*
------------------------------------------------------------------------------
Args: [buffer_property]~
Overview:~
Returns a dictionary representation of the buffer list.
Synopsis:~
>
:echo vimple#bl.to_d( ... )
<
Description:~
This method returns a dictionary representation of the buffer list. The key
for each entry in the dictionary is the buffer number as shown by |:ls|
Arguments:~
The to_d() method is actually just a wrapper for the |vimple#ls-buffers()|
method. See that method for details about the buffer_property argument.
Return:~
The to_d() method returns a dictionary of dictionaries with the following
fields (with example values):
>
{'1':
{'active': 0,
'number': '1',
'alternate': 0,
'name': 'doc/buffer_list.txt',
'readonly': 0,
'current': 1,
'line': '1',
'modified': 0,
'modifiable': 1,
'hidden': 0,
'read_error': 0,
'listed': 1
}
}
<
NOTE: Currently you have to manually call vimple#bl.update() before calling
vimple#bl.to_d() if you want the latest information. This may change in a
future version.
*vimple#ls-print()*
------------------------------------------------------------------------------
Args: [show_unlisted]~
Overview:~
Prints (colourfully) the buffer list.
Synopsis:~
>
:call vimple#bl.print( BOOL )
<
Description:~
Use this method to print to the screen a coloured representation of the buffer
list. The layout resembles the builtin |:ls| command but is by default
coloured to show important information more obviously. See the
autoload/vimple/vimple.vim file to see how to customise the colours used by
vimple#ls.print().
Arguments:~
show_unlisted~
If this boolean argument is not false then all buffers (including the unlisted
ones) are printed (as with the |:ls!| command. With no argument or one that
evaluates to false, only the listed buffers are shown (as with the |:ls|
command).
Return:~
The bl object (for chaining), although it's not immediately clear how this
could be useful (for the print() method), but a design decision was made to
return the bl object for all methods that didn't have to explicitly return a
different type (as the to_x() methods do).
NOTE: Unlike most of the other methods, the print() method -does- update the
buffer list (with an internal call to update()) prior to printing.
*vimple#ls-filter()*
------------------------------------------------------------------------------
Args: [filter]~
Overview:~
Auxilliary method used to filter out desired buffers only.
Synopsis:~
>
:call vimple#bl.filter( ... )
<
Description:~
The filter() method selects buffers from the internal list based on the
criteria provided in the argument. This method is used heavily internally by
other public methods, like the to_l() and to_d() and buffers() methods. This
method returns a new vimple#ls object containing only the selected buffers.
Arguments:~
filter~
The vimple#ls#filter() method uses the built-in |filter()| function which
uses the |v:val| variable to aaccess the elements of the internal buffer
properties. Call filter() like this:
>
:call vimple#bl.filter('v:val.modified').print()
:call vimple#bl.filter('v:val.name =~ "\.txt$"').print()
:echo vimple#bl.filter('v:val.name =~ "\.txt$"').to_s()
<
The available v:val properties are:
- active
- alternate
- current
- hidden
- line
- listed
- modifiable
- modified
- name
- number
- read_error
- readonly
Return:~
The bl object (for chaining).
*vimple#ls-buffers()*
------------------------------------------------------------------------------
Args: [buffer_property]~
Overview:~
Simplified filter wrapper.
Synopsis:~
>
:echo vimple#bl.buffers( ... )
<
Description:~
This utility method provides a simpler way to filter based on the flags
commonly used to select buffers.
Arguments:~
buffer_property~
Call buffers() like this:
>
:echo vimple#bl.buffers('modified')
:echo vimple#bl.buffers('hidden')
<
The available buffer properties are:
- active
- hidden
- listed
- modifiable
- modified
- read_error
- readonly
Return:~
The bl object (for chaining).
==============================================================================
4. PLUGINS USING VIMPLE BUFFER LIST *vimple#ls-plugins*
Vimple was designed to be a library for Vim developers and plugin writers. The
currently known plugins using Vimple:
- the buffalo (https://github.com/Raimondi/vim-buffalo) - A lightning fast
buffer switching tool using fuzzy matching.
vim:tw=78:ts=8:ft=help:norl: