*lookupfile.txt* Lookup files using Vim7 ins-completion
                    Requires Vim 7.0
            Last Change: 24-Aug-2007 @ 18:25
                 Author: Hari Krishna Dara (hari.vim at gmail dot com)

                                            *lookupfile-introduction*
                                            *lookupfile-plugin*
Lookupfile is a very simple approach to opening files by typing a pattern to
represent the file you are looking for, and selecting a file from the completion
dropdown to open in the current Vim session. It provides a consistent interface
to lookup files by various means (tags, path, buffers, external tools etc.). It
uses the new Vim7 insert-mode completion mechanism to show matching files. It
is a new tool 


The default functionality of the plugin is to lookup filenames from the tag
files, by matching the pattern against tag names. However, using the standard
tags (generated by ctags) can be very slow at best, so it is recommended to use
specially generated tagfiles, that are meant only for finding the filenames. You
don't however need to generate tag files at all to use the plugin, as there are
ways to lookup files from sources other than tag files.

==============================================================================
OVERVIEW                                    *lookupfile-overview*

|lookupfile-installation|     Installing the plugin.

|lookupfile-usage|            A brief usage to get you quickly started.

|lookupfile-maps|             Mappings defined in the lookup window.

|lookupfile-tags|             Creating index of files for a fast lookup.

|lookupfile-settings|         An explanation of various configure options.

|lookupfile-extend|           Features that make the plugin extensible.

|lookupfile-known-issues|     A list of known issues.

|lookupfile-wishlist|         Wishlist items that may be worth doing for a future
                              version.

|lookupfile-changes|          A change list for current version from the previous
                              versions.

|lookupfile-acknowledgements| Acknowledgements.
==============================================================================

                                            *lookupfile-installation*
The distribution comes as a zipfile that can be extracted straight into your
runtime directory (vimfiles/.vim). Please note that it depends on genutils
plugin that needs to be downloaded separately and installed. Also note that
the version of genutils that this plugin depends on is a newer autoload
version that is not backwards compatible with the older versions of genutils.
This means, if you have other plugins that depend on the non-autoload version
of genutils, you need to follow special instructions given in genutils such
that you can have both installed at the same time.

To install the help file, you need to run :helptags command on your runtime
doc directory.

                                            *lookupfile-map*
                                            *lookupfile-default-cmd*
                                            *LookupFile-command*
                                            *:LookupFile*
Once installed, you can optionally choose a key to be used to open the
lookupfile window. The default is <F5>. To change this value, choose a key of
your liking, say <A-S-L>, and add the below line to your vimrc: >

	nmap <unique> <silent> <A-S-L> <Plug>LookupFile
<
Note that the plugin creates a mapping for the insert-mode as well, so unless
you also explicitly specify a mapping for insert mode, the default <F5> will get
mapped to invoke lookupfile in the insert-mode. >

	imap <unique> <silent> <A-S-L> <C-O><Plug>LookupFile
<
The <Plug>LookupFile mapping is mapped to the :LookupFile command, which always
assumes the last :LU command you use. This means, after using |:LUWalk|,
pressing <F5> would result in executing the :LUWalk command until you type
another command. Take a look at the |LookupFile_DefaultCmd| to specify the
initial command that this map should get assigned to and
|LookupFile_EnableRemapCmd| to disable this behavior. If you want a map to
always execute a specific command, you can also create additional maps. E.g.,
if you want <F7> to always execute :LUTags, irrespective of what command you
last used, then you can define something like:
>
        nnoremap <silent> <F7> :LUTags<CR>
<
You can also disable the default map completely, see
|LookupFile_DisableDefaultMap| for details.
==============================================================================

                                            *lookupfile-usage*
To lookup a file, press the assigned key (default: F5) or use the :LookupFile
command. This will open a small window above the current window, where you can
type in a regex, and the matching filenames will be shown in the Vim7 completion
style. Selecting a matching file and pressing Enter (<CR>) will open it in the
previous window (or ^O (C-O) will open it in a split window).  You can also
press <Esc> and scroll back to previous filenames to press o or O (or use
:OpenFile[!]) to open the file in the previous window or a new window,
respectively.

If you want to quickly close the [Lookup File] window without making a file
selection, you can press the same key that you assigned to open the plugin, to
also cancel the completion menu and close the window.

Note that this works only when you use the <Plug> mapping to create a mapping
(see |lookupfile-map|), not when you assign a mapping directly while disablign
the default <Plug> mapping (see |LookupFile_DisableDefaultMap|).

Note that the completion menu will be shown only when you are in the insert
mode and the cursor is at the end of the line (this is the normal Vim behavior).

Here is a summary of all the commands that the plugin defines. All commands
accept the initial pattern as an argument, and support appropriate
|command-completion| mode.

        Command         Lookup source ~
        LUTags          Lookup files from tag files. This is a like a fast GNU
                        find on name. It can lookup files from any Vim
                        compatible tag file (which includes those from ctags),
                        but at the moment it is advisable to generate
                        specialized tag files using :find command (see
                        |lookupfile-tags|).
        LUPath          Lookup files from 'path' using |globpath()|. The :find
                        command while being able to lookup files from 'path', it
                        doesn't provide any completion mechanism, and it is
                        clumsy when there are multiple files with the same name.
                        The :find command doesn't even accept a pattern.
        LUBufs          Lookup loaded files (buffers) using |bufname()|. This is
                        a great addition to whatever buffer-explorer you are
                        using. When there are too many buffers open, this
                        sometimes makes it easy to find the right buffer, by
                        typing part of its name.
        LUWalk          Lookup files using |glob()|. This works like the Emacs
                        ido.el, allowing you to walk up and down a path looking
                        for files. If you use the filename completion with :edit
                        command, then you will find this a lot more convenient
                        and faster to use.
        LUArgs          Lookup files from |:args| list.
        LookupFile      A shortcut to the last command used from above set.

It is also very easy to add new commands to or customize the plugin at various
levels. At the simplest, you can create custom command on top of the above that
either pass dynamic arguments or tmporarily change the settings (e.g., you could
have a command that will start LUPath with the 'path' temporarily changed to
find only the include header files). You can also take advantage of the the
|lookupfile-extend| features to add new commands that lookup files from a
completely new source. You can even add commands that lookup something
completely different than a file (like e.g., a spelling using spellsuggest()).

The :LookupFile and all the above commands accept an argument which is treated
as the initial pattern. Specify a bang(!) after the command to always start with
an empty line.

                                            *:LUTags*
                                            *lookupfile-from-tags-files*
The LUTags command provides a fast lookup of files from tags files. This works
similar to the "Open Resource" command in eclipse where you can type part of the
name and all the resources whose name has matching part are shown for selection.

To use the :LUTags command, it is recommended to generate and maintain
separate tags files containing only filenames, for this plugin to work
efficiently (see |lookupfile-tags|). Though it will work with the regular tags
files, it could be very slow (due to the current performance of |taglist()| and
might not return the right set of filenames. Configure the tag expression such
that the plugin will use the right tag files. It is any valid Vim {rhs}, the
evaluated value should be a valid 'tags' value. For a static string, use extra
quotes. Ex:
>
        let g:LookupFile_TagExpr = string('./filenametags')

< or >
        let g:myLookupFileTagExpr = './filenanmetags'
        let g:LookupFile_TagExpr = 'g:myLookupFileTagExpr'
<
Also see |LookupFile_UsingSpecializedTags| to enable better formatting of
results once these specialized tags are generated and lookupfile is configured
to take advantage of them.
                                            *:LUPath*
                                            *lookupfile-find-cmd-alternative*
The LUPath command is a complete replacement for the built-in |:find| command.
The completion popup alone is a good enough reason to use this command instead
of the :find, but since it also recognizes the 'ignorecase' and 'smartcase'
settings it makes it easier to type and still be able to do exact match when
required.

                                            *lookupfile-ido*
The LUWalk and LUBufs commands are special in that they provide features that
will be very fimilar to those who used Emacs ido lisp package.

Similar to the ido, you can quickly switch from file lookup to buffer lookup
using <C-B> and from buffer lookup to file lookup using <C-F> while in insert
mode.

                                            *:LUBufs*
                                            *lookupfile-buffer-cmd-alternative*
LUBufs command allows you to quickly search the already loaded buffers for a
match and open it, so it can be used in the place of the built-in |:buffer|
command and provides the same matching semantics by default. Take a look at the
settings that start with "LookupFile_Bufs_" in their name to configure the
behavior of this command. The :LUBufs command also supports an initial pattern
as an arguments and supports filename completion.

A good use case for :LUBufs command is when you have several files named
similarly (e.g., having several buffers named Makefile or build.xml is very
common). Using a traditional buffer explorer plugin, finding the right file can
become cumbersome when you have a large set of buffers opened. In this case, the
:LUBufs command can help you locate the buffer much faster, as only the buffers
that match what you specify will be shown with their path clearly visible.

                                            *:LUWalk*
                                            *lookupfile-walk-path*
The LUWalk command is very useful to quickly navigate or "walk" filesystem
paths. The plugin provides a popup with matches for each path component as you
type in a partial string. The matches are based on the Vim |glob()| expression
rules.  The :LUWalk command also accepts the initial directory name with or
without a pattern as an argument, and supports directory name completion.

When no root is specified, the match starts from the current directory.
Pressing <Tab> before typing in any pattern will result in inserting the
directory of the last file automatically. Type an extra "/" after a directory
name to have only the directories shown in the results.

To accept the first entry in the matches, you can simply press <CR> or <C-O>,
and if the entry happens to be a directory, new matches will be shown for that
directory.

                                            *lookupfile-recent-files*
The plugin saves a list of most recently opened files using any of the above
commands. To trigger showing this list, simply use a space by itself. For more
details, see |LookupFile_RecentFileListSize|.
==============================================================================

                                            *lookupfile-maps*
The maps that are available in the [Lookup File] window are listed below. Some
of them are the same from |popupmenu-keys|, but have been modified to behave
slightly differently. All the below maps are applicable only when the popup menu
is visible, otherwise, they should have their default behavior.
        Key         mode    Action ~
        <CR>        i       Opens the selected file in the previous window/
                            Select the first file.
        <C-Y>       i       Same as <CR>
        <C-O>       i       Same as <CR>, except that the file opens in a split
                            window.
        <Down>      i       Selects next file. Same as |i_CTRL-N|.
        <Up>        i       Selects previous file. Same as |i_CTRL-P|.
        <PageDown>  i       Selects a file several entries down.
        <PageUp>    i       Selects a file several entries up.
        <Esc>       i       Stops completion and insert mode, and restores
                            pattern.
        <BS>        i       Stops completion, restores pattern and executes
        o           n       Opens the current file in the previous window.
        O           n       Same as o, except the file opens in a split window.
==============================================================================

                                            *lookupfile-tags*
Unless you want to lookup files from alternate sources such as 'path', you
should generate special tags files for the lookup from filesystem to work well.

It is very easy to generate a tag file for an efficient lookup of filenames.
If you have Unixy tools installed, you can run the below shell command to
generate a tags file (you can put it in a shell-script and schedule it to be run
every now and then to keep this file up to date) >

        (echo "!_TAG_FILE_SORTED	2	/2=foldcase/";
         (find . -type f -printf "%f\t%p\t1\n" | \
         sort -f)) > ./filenametags

Typically you would want to exclude generated files such as .class and
.o. You can do this easily by specifying additional expressions to
the find command (see manpage for find command). E.g., replace the find
command above with: >

        find . -not -iname "*.class" -type f -printf "%f\t%p\t1\n" \

< or, with something more useful: >

        find . \( -name .svn -o -wholename ./classes \) -prune -o -not -iregex '.*\.\(jar\|gif\|jpg\|class\|exe\|dll\|pdd\|sw[op]\|xls\|doc\|pdf\|zip\|tar\|ico\|ear\|war\|dat\).*' -type f -printf "%f\t%p\t1\n" \
<
==============================================================================

                                            *lookupfile-settings*
The settings are global variables that you can set in your vimrc. All settings
are optional, as they all have default values, but it is highly recommended that
you fine tune the g:LookupFile_TagExpr setting, as per |lookupfile-tags|.
                                            *LookupFile_DefaultCmd*
- This specifies the |lookupfile-command| that should be invoked when the
  |LookupFile-command| or |lookupfile-map| is used. This defaults to ":LUTags",
  but you can change it to say, ":LUWalk". The :LookupFile command always
  assumes the last command that you used, so this setting only specifies the
  command to be invoked for the first time.
  Ex: >
        let g:LookupFile_DefaultCmd = ':LUWalk'
<
                                            *LookupFile_EnableRemapCmd*
- When this is set (the default), the :LookupFile command takes the form of
  the last command that is used. Disabling this while setting
  |LookupFile_DefaultCmd| allows you to configure a custom command as the
  command to run when you press the <Plug>LookupFile mapping. See
  |LookupFile-command| for more details.

                                            *LookupFile_DisableDefaultMap*
- Setting this flag turns off the default maps created by the plugin such that
  the user has full control on what maps to what command. >
        let g:LookupFile_DisableDefaultMap = 1
<
NOTE: setting this doesn't prevent the <Plug> mapping from created, try
setting no_lookupfile_maps or no_plugin_maps for this (see |usr_41.txt|).

                                            *LookupFile_TagExpr*
- Use g:LookupFile_TagExpr to use custom tagfiles. A valid Vim expression
  resulting in a String should be used, which means "eval(g:LookupFile_TagExpr)"
  should return a valid value for 'tags' setting. Once you set a value for this
  setting and startup Vim, try >
        echo eval(g:LookupFile_TagExpr)
< to make sure it is valid. Ex: >
        let g:LookupFile_TagExpr = string('./filenametags')
<
                                            *LookupFile_MinPatLength*
- By default g:LookupFile_MinPatLength is set to 4, which means you have to type
  at least 4 characters before the lookup is triggered. This is because the
  current taglist() function is too slow if the tag file is large.  Depending on
  the number of files you have, you may be able to set a lower value (or may
  even have to increase the value) for this setting.
                                            *LookupFile_ShowFiller*
- If you don't want the filler to be shown while the tags are being
  looked up, you can disable it by setting g:LookupFile_ShowFiller to 0. If you
  know for sure that the lookup never takes too long, then disabling the filler
  could make the completion menu less flashy.
                                            *LookupFile_UsingSpecializedTags*
- When you generate specialized tags as described in the |lookupfile-tags|
  section, you can set g:LookupFile_UsingSpecializedTags to enabled better
  formatting for showing the results.
                                            *LookupFile_PreservePatternHistory*
- By default, the plugin leaves a copy of the pattern that you used to
  lookup the file, so that you can scroll-back and find them (this is like a
  history), but you can disable this behavior by setting
  g:LookupFile_PreservePatternHistory to 0.
                                            *LookupFile_PreserveLastPattern*
- By default, the lookup window is started with the last pattern, which you can
  remove by quick pressing <Ctrl-U>, but if you always want to start blank, set
  g:LookupFile_PreserveLastPattern to 0.
                                            *LookupFile_LookupFunc*
                                            *LookupFile_LookupNotifyFunc*
                                            *LookupFile_LookupAcceptFunc*
- If you want to lookup matches yourself using an alternative procedure, you
  can specify a user function that should be called by the plugin, and
  by-pass the default tag based lookup. Use g:LookupFile_LookupFunc
  setting to specify the name or Funcref for such a function. The function
  will be called with one argument, which is the pattern typed so far. The
  results will be sorted by the plugin anyway, so your function need not.
  You can also set g:LookupFile_LookupNotifyFunc to be notified when a
  file is selected from the matches (not called with o or O commands), and
  g:LookupFile_LookupAcceptFunc to override the default handling of selection.
                                            *LookupFile_switchbuf*
- If you have 'switchbuf' set to "split" for your quickfix commands to
  always split open windows, the plugin recognizes this setting and split-opens
  all files.
                                            *LookupFile_AlwaysAcceptFirst*
- Normally when <CR> or <C-O> is pressed while the popup is visible, the first
  item in the list is selected, unless there is exactly only one item matching.
  This means, if you want to select the first item, you have to press it
  twice. You can change this behavior to always accept the first item by
  setting g:LookupFile_AlwaysAcceptFirst (like ido.el).
                                            *LookupFile_FileFilter*
- Use the g:LookupFile_FileFilter to specify a Vim regular expression pattern
  that, when matched against the filename (or path, depending on the mode)
  results in filtered out. E.x: >

    " Don't display binary files
    let g:LookupFile_FileFilter = '\.class$\|\.o$\|\.obj$\|\.exe$\|\.jar$\|\.zip$\|\.war$\|\.ear$'
<
  NOTE that the |:LUPath| and |:LUWalk| commands use the Vim functions |globpath()|
  and |glob()| that recognize the Vim setting 'wildignore', so setting this in
  addition to 'wildignore' will have the matches filtered by both rules.
                                            *LookupFile_AllowNewFiles*
- Use the g:LookupFile_AllowNewFiles to specify whether entering non-existent
  files should generate an error or result in getting a new buffer created.
                                            *LookupFile_ignorecase*
                                            *LookupFile_smartcase*
- The plugin now recognizes 'ignorecase' and 'smartcase' settings to match files
  even on systems that are case-sensitive. On unix like platforms, glob()
  matches patterns in a case-sensitive manner, so setting 'ignorecase' will
  enable special translation of patterns so that you get case-insensitive
  results. On Windows, since glob() is already case-insensitive no special
  handling is required for 'ignorecase', however, when 'smartcase' is set, there
  is no way to force glob() to return case-sensitive results, so a
  post-processing of the results is done to drop files that would not otherwise
  have matched.
                                            *LookupFile_SortMethod*
- Use this setting to specify the sort method to use for sorting results. The
  default value is "alpha", which means that they will be sorted alphabatically.
  You can also set an empty value to disable sorting. See also
  |LookupFile_Bufs_BufListExpr| to enable MRU sorting for |:LUBufs| command.
                                            *LookupFile_Bufs_BufListExpr*
- Use g:LookupFile_Bufs_BufListExpr to specify an expression that returns a
  |List| of buffers to display. By default this is set to an empty string, but
  you can set any valid Vim expression that results in a List. If you also have
  the latest version of SelectBuf (http://www.vim.org/script.php?script_id=107)
  installed, a useful value that you can set here is "g:SB_MRUlist", which will
  then display buffers in the MRU order. >

        let g:LookupFile_Bufs_BufListExpr = 'g:SB_MRUlist'
<
  You can use this setting to even specify your own global function.
                                            *LookupFile_Bufs_SkipUnlisted*
- By default, the |:LUBufs| commands skips all unlisted buffers from results,
  but if you want them to be included, reset LookupFile_Bufs_SkipUnlisted
  setting.
                                            *LookupFile_Bufs_LikeBufCmd*
- This setting impacts the behavior of |:LUBufs| command on how the pattern is
  matched. By default, it matches just like the |:buffer| command, so the
  pattern is treated as per the rules of |wildcard| matching against the current
  |bufname()| of each buffer. Clearing this setting will cause the command to
  match the pattern as a Vim regex against only the filename portion of each
  buffer.
                                            *LookupFile_UpdateTime*
- LookupFile uses |CursorHoldI| autocommand to trigger the completion and this
  event doesn't get triggered unless nothing is typed for 'updatetime'
  milliseconds. Since the default value for 'updatetime' is rather large,  the
  plugin changes this value to g:LookupFile_UpdateTime (which defaults to 300
  milliseconds or 3/10th of a second) while the [Lookup File] window is active.
                                            *LookupFile_EscCancelsPopup*
- On some systems, the mapping for <Esc> to cancel the popup could interfere
  with the arrow keys, so if you want the plugin to not map <Esc> key, then
  reset |LookupFile_EscCancelsPopup| setting. >

        let g:LookupFile_EscCancelsPopup = 0
<
                                            *LookupFile_SearchForBufsInTabs*
- Normally, when you seleclt a file that is already visible in a window,
  LookupFile simply makes that window the current window instead of opening
  the file again. Setting this flag will make LookupFile also search in other
  tabs for a window that already has this file visible, and switch to that tab
  to set the focus. This setting is most useful with the |LUBufs| command. >

        let g:LookupFile_SearchForBufsInTabs = 1
<
                                            *LookupFile_TagsExpandCamelCase*
- When this setting is enabled (the default), typing consecutive upper case
  letters are treated as abbreviations for type names that follow the
  CamelCase naming pattern (like all the java class names are) and the pattern
  is translated automatically. This is modelled after the "Open Type" dialog
  in eclipse and works only for the tag lookup (|LUTags| command). To disable
  this feature, set it to 0 >

        let g:LookupFile_TagsExpandCamelCase = 0
<
  Ex:
    - To match the filename VimTheSupremeEditor.txt, you could enter the pattern
      in several variations such as: >
        VTSE
        VTSEditor
        VTSEdi.*
        VTS.*
        VTheSE
<
NOTE: While using the CamelCase expansion, 'ignorecase' is disabled so
something like "VTSEDi.*" will not match "VimTheSupremeEditor", but will match
"VimTheSupremeEditorDictator", if it exists.
                                            *LookupFile_RecentFileListSize*
This setting allows you to control the number of most recently used filenames
that should be rememberd by the plugin. The default size is 20, but it can be
set to 0 to not remember any and any -ve value to remember all. The list is
not persisted across Vim sessions. >

        let g:LookupFile_RecentFileListSize = 30
<
See also, |lookupfile-recent-files|.
==============================================================================

                                            *lookupfile-extend*
If you want to extend the functionality of the plugin, by creating new commands
to lookup files in different ways, you can take advantage of the
g:LookupFile_LookupFunc and lookupfile_LookupNotifyFunc settings as below:

    - Create a function that can take a pattern and return file matches for it:
      function! FileMatches(pattern)
        let matches = []
        " Find and fill up matches.
        return matches
      endfunction
    - Create an entry function and a command:
      function! MyLookup()
        unlet! s:savedLookupFunc s:savedLookupNotifyFunc
        let g:savedLookupFunc = g:LookupFile_LookupFunc
        let g:savedLookupNotifyFunc = g:LookupFile_LookupNotifyFunc
        unlet g:LookupFile_LookupFunc g:LookupFile_LookupNotifyFunc
        let g:LookupFile_LookupFunc = 'FileMatches'
        let g:LookupFile_LookupNotifyFunc = 'MyNotify'
        LookupFile
      endfunction
      command! MyLookup call MyLookup()
    - Define the MyNotify() function to clear the settings.
      function! MyNotify()
        unlet g:LookupFile_LookupFunc g:LookupFile_LookupNotifyFunc
        let g:LookupFile_LookupFunc = g:savedLookupFunc
        let g:LookupFile_LookupNotifyFunc = g:savedLookupNotifyFunc
      endfunction

Once you follow the above steps, you can use both the default LookupFile command
as well as the new MyLookup command. The completion will behave differently
based on how you opened the lookup window.

You can also override the default action when the user presses <CR> or <C-O> to
get your function invoked, by setting the g:LookupFile_LookupAcceptFunc. The
function should have the below signature: >

    " splitWin is 1 if a new window should be split.
    " key is the exact key that user pressed ("\<CR>"/"\<C-O>").
    function accept(splitWin, key)
<
The last pattern and the matching results for it are accessible in the global
variables g:lookupfile#lastPattern and g:lookupfile#lastResults.

You can also create ftplugin/lookupfile.vim in your vim runtime and put commands
to further customize or override the behavior of the plugin. E.g., you could put
a map such that pressing <Esc> twice in succession will close the window: >

    nnoremap <buffer> <Esc><Esc> <C-W>q
    inoremap <buffer> <Esc><Esc> <Esc><C-W>q
<
                                            *lookupfile-tips*
- A pattern is a Vim regex, so you can e.g., start with an "^" to anchor the
  pattern match to the start of the filename. This will also speed up the
  lookup. You can also enter the extension (such as \.prop) to narrow down the
  results further.
- If the filename has special characters, don't forget to protect them while
  entering the pattern, or you may not find what you are looking for (or
  might find too much). E.g., to find a file named "abc*xyz" (not possible
  on windows), you need to enter "abc\*" as pattern. Since the pattern is
  used as if 'magic' is set, unless you have the "\" itself in the
  filenames, you only have to worry about those characters that are special
  without needing to prefix with a "\", and these are ".", "^", "[", "*" and
  "$".
- If the lookup is taking too long, you can stop it by pressing ^C. You may
  still be able to see partial set of matches.
- You can use <Ctrl-J> instead of <CR> to deliberately insert a newline into
  the lookup buffer.
- Pressing <Esc> after selecting a file, results in restoring the pattern. If
  you actually want to cancel the completion menu, without restoring the
  pattern, you can press <C-C>.
- When you want to start entering a new pattern, press <Ctrl-U> to quickly
  kill the previous pattern.
- Use g:LookupFile_LookupFunc setting to modify the functionality of the
  plugin. The plugin/lookupfile.vim comes with a few of alternative ways to
  lookup files, such as looking up files from 'path' (see |lookupfile-usage|).
  Other ideas for alternative lookup for files are:
  - Use id-utils' lid to lookup files from ID database. You can e.g., use the
    command "lid -R filenames -S newline -k token" to lookup for the typed
    pattern as a token (there are other options for lid to treat token as regex)
  - Use GNU find to find files matching the pattern, something like:
    "find . -name '*pattern*'". There are a number of options for find, so this
    could be made very flexible, but running find for every character typed
    could be very slow.
  - You can create an alternate tags file to store only directory names such
    that you can lookup directory names instead of filenames. The following
    command can create such a tags file: >

        (echo "!_TAG_FILE_SORTED	2	/2=foldcase/";
        find . -type d -printf "%f\t%p\t1\n") | \
        sort -f > ./dirnametags
<
    Note that this generates tag file with relative paths, which is known to
    cause problem with |taglist()| function when the tag file is not in the same
    directory as Vim's current directory (see |lookupfile-known-issues|. To
    workaround, you can generate absolute paths, you can use "`pwd`" instead of "."
    as the root.
- You can create custom commands/mappings that always start with a fixed or
  computed pattern. E.g., to always start LUWalk in the root of c: drive, create
  a command as: >

        command! WalkRoot LUWalk c:/
<
  Another useful variation of the above is to start with the directory of the
  current file: >

        command! WalkCur :exec "LUWalk" expand('%:p:h').'/'
<
  Another example that works well with :LookupFile is to start with the current
  word as pattern: >

        command! CurWord :LookupFile <cword>
<
- The :LUWalk command maps your <BS> key such that it will remove a complete
  directory component at a time (like ido.el). To remove only a part of the
  directory name, first press <C-W> to remove the "/" and use <BS> to remove the
  required number characters. You can also press <Esc> and use normal commands
  to edit.
- While using :LUWalk, when no pattern is entered yet, you can press <Tab> to
  show the files in the directory of the current buffer.
- While using :LUWalk, you can enter "**" after any directory in the path to
  match keyword recursively under that path.
- If you want to extend the funcationality of the plugin, take a look at the
  plugin/lookupfile.vim for various examples.
- Here is a sample function that you can use to lookup spellings as you type,
  using spellsuggest() function. You need to first turn on 'spell' inside
  lookup window for this to work. >
    function! s:LookupSpell(pattern)
      return spellsuggest(a:pattern)
    endfunction
<
  This is a dummy accept function that prevents the word from being treated as a
  file and open it: >
    function! s:SpellAccept(splitWin, key)
      call input('SpellAccept')
    endfunction
<
==============================================================================

                                            *lookupfile-known-issues*
- Vim sometimes automatically replaces the pattern with the first filename
  from the completion menu. You have to select back the original pattern using
  ^P.
- The taglist() function's performance (on which this plugin depends on)
  seems to be bad. A newer version of Vim might accept additional arguments
  for taglist() to limit the number of matches, which can speed up some of
  the cases.
- If you press the <Plug>LookupFile key while making a file selection, the
  completion doesn't get aborted, but instead it gets selected and the 
  [Lookup File] window still remains open.
- There is a bug in taglist() that returns incorrect relative paths if the
  current directory of Vim is not the same as the directory in which tags file
  resides. This impacts the :LookupFile command. If this is an issue for you,
  you should generate the tag files with absolute paths instead of relative
  paths, by giving absolute directory names.
==============================================================================

                                            *lookupfile-wishlist*
- Allow on the fly filtering of the filenames by prompting the user for a
  pattern to match (or not match) against the whole filename.
- Option to sort filenames by their extension, or by MRU.
- Save and restore matching results, for patterns that take a long time to build
  (especially those that involve "**").
- Option to have separate window/buffers for each type of command (Timothy,
  Guo)
==============================================================================

                                            *lookupfile-changes*

                                            *lookupfile-changes-1.8*
- New settings |LookupFile_EnableRemapCmd|, |LookupFile_SearchForBufsInTabs|,
  |LookupFile_TagsExpandCamelCase|, |Lookupfile_RecentFileListSize|.
- Even more control on the mappings with the new setting
  |LookupFile_EnableRemapCmd|.
- New feature to specify names that follow CamelCasing pattern by abbreviating
  them. This works more or less like for the "Open Type" dialog in Eclipse.
  For more information see, |LookupFile_TagsExpandCamelCase|.
- New feature to remember the recent files, see
  |Lookupfile_RecentFileListSize|.
- Changed the message line such that the message is shown on the left side and
  the pattern is shown on the right side. This prevents the more important
  message from getting lost when the filenames are too long.

                                            *lookupfile-changes-1.7*
- Bug fix: LUPath and LUArgs were broken (stoning at gmail dot com).
- Removed debugging code.

                                            *lookupfile-changes-1.6*
                                            *lookupfile-changes-1.5*
- LookupFile now uses CursorHoldI instead of CursorMovedI to show matches. This
  means, the matches are not computed until you stop typing, which should give a
  better experience. See |LookupFile_UpdateTime| for more information.
- The plugin now sets 'completefunc' such that you can now hit <C-X><C-U> to
  trigger completions explicitly (instead of waiting for
  g:LookupFile_UpdateTime). This is useful if you are a slow typer and so prefer
  a large value for g:LookupFile_UpdateTime.
- The plugin now recognizes 'ignorecase' and 'smartcase' settings to match files
  even on systems that are case-sensitive. This is mainly significant for the
  commands that use |globpath()| or |glob()| which are, |:LUPath| and |:LUWalk|,
  as the others already respect these settings.
- There is now a separate command called :LUTags that always does what
  :LookupFile used to do, while the :LookupFile command itself now gets
  dynamically assigned to the last command used. This also means, the map that
  is choosen in |lookupfile-map| now invokes the last command that is used, use
  |LookupFile_DefaultCmd| and |LookupFile_DisableDefaultMap| settings to control
  this behavior.
- LUWalk now supports showing only directory names in the results. Just type
  an extra / to filter those that are not directories (the suffix will then be
  two slashes).
- The default behavior of |:LUBufs| is now to match the entire |bufname()|,
  just like the |:buffer| command would do. To see the old behavior, reset
  |LookupFile_Bufs_LikeBufCmd| setting.
- If you have the new version of SelectBuf also installed, you can have
  |:LUBufs| sort buffers in MRU order. See, |LookupFile_Bufs_BufListExpr|.
- When tags file is not generated as per the requirements of |lookupfile-tags|,
  the format of the matches doesn't look good, so by default the matches just
  show full filenames. See |LookupFile_UsingSpecializedTags| to get better
  formatted results.
- New settings |LookupFile_UsingSpecializedTags|, |LookupFile_SortMethod|,
  |LookupFile_DefaultCmd|, |LookupFile_DisableDefaultMap|,
  |LookupFile_Bufs_LikeBufCmd|, |LookupFile_Bufs_BufListExpr|,
  |LookupFile_EscCancelsPopup|.
- Bug fix: exact matches were getting dropped from results  (Max Dyckhoff).
- Bug fix: <BS> in |:LUWalk| right after selecting a directory match caused it
  to misbehave.
- Bug fix: if tags file is not in the current directory, the opening fails. Now
  :LookupFile expands the filenames explicitly so that the paths are always
  valid.
- Bug fix: Unsetting |LookupFile_AllowNewFiles| didn't disable the feature.
- Bug fix: <C-E> was not hiding the popup.
- Bug fix: <S-BS> triggers the default insert-mode completion (Max Dyckhoff).
- Fixed misc. bugs in opening files.
- Workaround for <Esc> not working on some systems, allow disabling the
  mapping.
- Bug fix: When there is an exising swapfile, opening the files result in an
  error message (David Fishburn).
- When LookupFile_UsingSpecializedTags is set, sorting should be done on the
  filename (patch by Timothy, Guo).

                                            *lookupfile-changes-1.4*
- Fixed a bug in the initial pattern getting ignored.
- LUBufs now completes the full pathname of the buffers, so that it is less
  dependent on the current directory of Vim.
- LUBufs and LUPath commands now present the matches in a better format.
- Pressing <F5> while popup is visible didn't close the lookupfile window.

                                            *lookupfile-changes-1.3*
- New feature to create a file, if the file doesn't already exist (Ido). Can be
  disabled using g:LookupFile_AllowNewFiles setting.
- Bug fix: while using LUWalk, if the first match is a directory, then selecting
  files was offset by one.

                                            *lookupfile-changes-1.2*
- g:LookupFile_AlwaysAcceptFirst setting to always accept the first
  entry (the default is 0).
- g:LookupFile_FileFilter to specify a filter.
- New LUWalk command that works very similar to Emacs ido.el to quickly navigate
  paths.
- All commands now accepts the initial pattern as argument. This provides
  unlimited number of possibilities to create your own custom commands (see
  |lookupfile-tips| for some examples).
- The g:LookupFile_MinPatLength is automatically set to 0 except for tag and
  'path' lookup.
- When Lookup window is opened, the filetype is set to "lookupfile". This allows
  you to create ftplugins to fine tune the behavior.
- Renamed :LUBuf command to :LUBufs.

                                            *lookupfile-changes-1.1*
- Added LUBuf and LUPath commands.
- Renamed the prefix for all the settings from g:lookupfile_ to g:LookupFile_.
  This is required to support Funcref settings.
- Now the cursor position is preserved, while opening a file that is already
  loaded.
- Using genutils 2.1.
==============================================================================

                                            *lookupfile-acknowledgements*
- Max Dyckhoff (maxd at microsoft dot com) for beta testing and reporting
  numerous issues and suggesting improvements etc. The plugin is a lot
  more stable, thanks to him.
  I would also like to specially thank him for proof reading the first version
  of this documentation.
- Eddy Zhao (eddy dot y dot zhao at gmail dot com> for suggesting several
  improvements on the lines of emacs ido.el and rigorously testing them. The
  LUWalk command is the result of this.
- Eddy Zhao (eddy dot y dot zhao at gmail dot com> for suggesting several
- Dane Summers (dsummersl at yahoo dot com) for feedback and doc updates.
- Timothy, Guo (firemeteor dot guo at gmail dot com) for improving the sorting
  and other feedback.


 vim6:tw=80:ts=8:ft=help:ai:sw=4:et
