BufferManager.txt

*vital/Vim/BufferManager.txt*	buffer manager.

Maintainers: thinca <thinca+vim@gmail.com>
             ujihisa <ujihisa at gmail com>

==============================================================================
CONTENTS			*Vital.Vim.BufferManager-contents*

INTRODUCTION			|Vital.Vim.BufferManager-introduction|
USAGE				|Vital.Vim.BufferManager-usage|
INTERFACE			|Vital.Vim.BufferManager-interface|
  FUNCTIONS			  |Vital.Vim.BufferManager-functions|
OBJECTS				|Vital.Vim.BufferManager-objects|
  Manger Object			  |Vital.Vim.BufferManager-Manager|
CONFIG				|Vital.Vim.BufferManager-config|



==============================================================================
INTRODUCTION			*Vital.Vim.BufferManager-introduction*

*Vital.Vim.BufferManager* is a Vim's buffer manager library.  This manager
stores the opened buffers, and reuses the opened window when opening a new
buffer.



==============================================================================
USAGE				*Vital.Vim.BufferManager-usage*
>
	let BM = V.import('Vim.BufferManager')
	let m = BM.new()  " creates new manager
	" opens a new buffer named "buffer name" to a new window
	call m.open('buffer name')
	" opens a new buffer to same window (reused automatically)
	call m.open('buffer 2')

	echo m.config('range')         " gets the config value
	call m.config('range', 'all')  " sets the config value

	let m2 = BM.new()  " creates new manager
	" each managers are independent
	call m2.open('buffer 3')
<


==============================================================================
INTERFACE			*Vital.Vim.BufferManager-interface*

------------------------------------------------------------------------------
FUNCTIONS			*Vital.Vim.BufferManager-functions*

				*Vital.Vim.BufferManager.new()*
new([{config} [, {user-config}]])
	Creates a new Manager object(|Vital.Vim.BufferManager-Manager|).

==============================================================================
OBJECTS				*Vital.Vim.BufferManager-objects*

------------------------------------------------------------------------------
Manger Object			*Vital.Vim.BufferManager-Manager*

				*Vital.Vim.BufferManager-Manager.open()*
Manager.open({bufname} [, {config}])
	Opens a buffer.
	First, this function searches a window that is opening a managed
	buffer from range(|Vital.Vim.BufferManager-config-range|).
	If a window is found, it moves to the window and opens a buffer.
	If it is not found, opens a buffer by
	opener(|Vital.Vim.BufferManager-config-opener|).
	The return value is a |Dictionary| which contains following attributes

	"loaded"
	A boolean which indicate whether the buffer was newly loaded or not.

	"newwin"
	A boolean which indicate whether the buffer was opened in a new
	window.

	"newbuf"
	A boolean which indicate whether the buffer was newly opened (in other
	word, listed).

	"bufnr"
	A |Number| which indicate the buffer index (|bufnr()|).

	"bufname"
	The {bufname}.

Manager.opened({info})		*Vital.Vim.BufferManager-Manager.opened()*
	This is called when a buffer is opened via
	Manager.open()(|Vital.Vim.BufferManager-Manager.open()|).
	{info} is a return value of Manager.open().
	User can overwrite this function and use as hook function.

Manager.close([{range}])	*Vital.Vim.BufferManager-Manager.close()*
	Closes the {range} buffer if it exists.

Manager.config()		*Vital.Vim.BufferManager-Manager.config()*
	Gets the config as |Dictionary|.
Manager.config({config})
	Sets the config by |Dictionary|.  All values are overwritten.
Manager.config({config-name})
	Gets the config value.
Manager.config({config-name}, {value})
	Sets the config value.

Manager.user_config({config})  *Vital.Vim.BufferManager-Manager.user_config()*
	Sets variable name of user's config.
	User can customize the behavior via the variable.
	If {config} is a |Dictionary|, variable name can be set per config.
>
	manager.user_config({'opener': 'g:your_plugin_opener'})
<

Manager.is_managed({bufnr})	*Vital.Vim.BufferManager-Manager.is_managed()*
	If the specified {bufnr} is managed by this Manager, returns true.

				*Vital.Vim.BufferManager-Manager.add()*
Manager.add({bufnr} [, {bufname}])
	Adds a buffer to this for managing.  The buffer must exist.

Manager.list()			*Vital.Vim.BufferManager-Manager.list()*
	Get the list of the buffer numbers that managed by this Manager.

Manager.nearest([{range}])	*Vital.Vim.BufferManager-Manager.nearest()*
	Searches the nearest managed buffer.  Returns the position and buffer
	number by the form like [{tabpagenr}, {winnr}, {bufnr}].  If the
	{range} argument is present and not zero, searches current tabpage
	only.  If the buffer is not found, returns empty list.

Manager.move([{range}])		*Vital.Vim.BufferManager-Manager.move()*
	Moves to the nearest managed buffer.  Returns true if focus moved or
	was already staying in the managed buffer.

Manager.do({cmd})		*Vital.Vim.BufferManager-Manager.do()*
	Executes ":execute {cmd} bufnr" for each managed buffers.  If {cmd}
	includes "%s", it is replaced by bufnr.
	Example: >
	call Manager.do('bwipeout')



==============================================================================
CONFIG				*Vital.Vim.BufferManager-config*

Priority:
method argument > user config > config

opener				*Vital.Vim.BufferManager-config-opener*
	Way to open a new window.  This is one of followings:
	- A command as |String|.
	- A |Funcref| to open a window.
	  This |Funcref| receives {bufname} as first argument.
	- A |String| that starts with "=".
	  This is treated as |expr|, and result is an opener.

range				*Vital.Vim.BufferManager-config-range*
	Range which searches a window.
	"current"
		Current window only.
	"tabpage"
		Current tabpage.
	"all"
		Windows of all tabpages.

mods				*Vital.Vim.BufferManager-config-mods*
	A command modifiers used when opening a buffer.
	See |Vital.Vim.Buffer.open()| for more detail.

cmdarg				*Vital.Vim.BufferManager-config-cmdarg*
	A command attribute used when opening a buffer.
	See |Vital.Vim.Buffer.open()| for more detail.

==============================================================================
vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl