vxlib_utils.txt          Utilities               Last Change: February 2010

==============================================================================
VXLIB UTILITIES                                              vxlib-utilities

   Multiple histories        vxlib-history
   Python support            vxlib-python

==============================================================================
HISTORY                                                        vxlib-history

Multiple histories
------------------

Use multiple histories with input() command.

This module implements functions to save and restore the history used by the
input() command. New types of histories can be defined by the user. Custom
histories are also saved to .viminfo.

Example: Substitute command with separate histories for search patterns and
replacement strings
>
   function! Substitute()
      call inputsave()
      " save the content of 'input' history
      let hinp = vxlib#hist#GetHistory('input')

      " use 'search' history in input command (copy from 'search' to 'input')
      call vxlib#hist#CopyHistory('search', 'input')
      let l:patt = input("Find:/")
      call vxlib#hist#AddHistory('search', l:patt)   " same effect as histadd()

      " use custom 'replace' history in input command
      call vxlib#hist#CopyHistory('replace', 'input') 
      let l:repl = input("Repl:/")
      call vxlib#hist#AddHistory('replace', l:repl)  " add to custom history

      " restore the content of the 'input' history
      call vxlib#hist#SetHistory('input', l:hinp) " restore

      " execute the search
      call inputrestore()
      let l:cmd = "s/" . escape(l:patt, "/") . "/" . escape(l:repl, "/") . "/"
      exec l:cmd
   endfunc
<

Initialization/Termination:
   - s:UserHistory (a dictionary of lists) will be restored from
     g:CUSTOM_HISTORIES the first time vxlib#hist# is used
   - at the same time a VimLeavePre autocmd will be registered and the history
     will be saved to g:CUSTOM_HISTORIES before writing the viminfo file
   - if vxlib#hist# isn't used in a session, g:CUSTOM_HISTORIES remains
     unchanged (if it was present in viminfo).


==============================================================================
PYTHON SUPPORT                                                 vxlib-python

Prepare Python environment             vxlib-python-prepare
--------------------------

To keep all Python modules used by Vim in one place (eg. ~/.vim/modpython),
the function vxlib#python#prepare() can be called from a script that imports
Python modules. The function will search for a directory named "modpython" in
the runtime path. It the directory is found, it will be added to Python
sys.path, but only the first time the function is called.

Example:
>
    call vxlib#python#prepare()
    python << EOF
    import my_vim_module   # my_vim_module.py installed in ~/.vim/modpython
    ...
    EOF
<

Call Vim functions from Python         vxlib-python-callback
------------------------------

If the Python code needs to call Vim functions that are local to a Vim script,
there is a utility function vxlib#plugin#MakeSID() that will create two variables
in the calling script: s:SID and s:SNR (s:SNR = '<SNR>' . s:SID). These
variables can be used to define Vim callbacks for Python code.

Example:
>
   exec vxlib#plugin#MakeSID()
   function s:Message()
      echom "Callback called"
   endfunc
   exec 'python vim.eval("' . s:SNR . 'Message()")'
<

==============================================================================
POPUP MENU                                                       vxlib-menu

Displays a popup menu using one of the supported menu backends:
   - "popup" - use :popup
   - "vimuiex" - use vimuiex VxTextMenu
   - "choice" - use inputlist()

If the selected backend isn't available, an available backend is selected. The
order of backends to choose from can be modified.

Display a Vim popup menu
------------------------
>
   :call vxlib#menu#DoVimMenu('Tools.Spelling', 'vimuiex')
<
Displays the Vim menu 'Tools.Spelling' using the menu-backend 'vimuiex'. If
the backend isn't avialable, another one will be chosen.

To change the order of backends: >
   let g:vxlib_menu_backend_order = ['vimuiex', 'popup', 'choice']
<




## vim:tw=78:noet:wrap:ts=8:ft=help:norl: