Vim documentation: vital/Vim/BufferManager

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