vimprj.txt

*vimprj.txt* Plugin for managing options for some different projects




                     By Dmitry Frank
                   mail@dmitryfrank.com

Firstly: if you have any questions regards this plugin, feel free
to email me: mail@dmitryfrank.com


                                          *vimprj* *vimprj-plugin*

   Contents:

         Dependencies...............|vimprj-dependencies|
         Options.........................|vimprj-options|
         Commands.......................|vimprj-commands|
         Known bugs.........................|vimprj-bugs|


Please note: there's some dependencies. Please read |vimprj-dependencies|.

                                  * * *

Many times I faced a problem. That's the story:

I'd like to use 3-space indent in my projects.
No tabs, especially three spaces. One day I need to work on another project
written by someone else, and there's 4 spaces indent. Or maybe tabs.

I need to work on this project too, and I need to leave existing formatting
options.

I strongly dislike that I have to switch these options by hand: &shiftwidth,
&tabstop, &expandtab.

And then I decided to write this plugin to make my life easier.

Using this plugin is quite easy. You need to create in the root directory of
your project new directory ".vimprj" and put any number of files "*.vim" in it.
Every time you open new file in Vim, plugin looks for ".vimprj" directory up
by tree, and if it is found, then all *.vim files from it will be sourced.

OR: you can just put file ".vimprj", then this file will be sourced.
Name ".vimprj" can be changed by editing option g:vimprj_dirNameForSearch .

Usually for my own projects I create just one file .vimprj/my.vim with the
following contents: >

   let &tabstop = 3
   let &shiftwidth = 3
   set expandtab

This my .vimprj directory also contain tags and other project-specific files,
so, I'd prefer to use directory instead of just one file.

and for other projects I create files with appropriate options.

Now, when I open file from my project, file my.vim is sourced. When I open
file from some another project, its own file with options is sourced too. Of
course, when I switch buffer, this files are sourced too if project is
changed.

So, I always have correct options, and simultaneus work on several projects
with different formatting options is not painful anymore for me.

And, of course, you can use it not only to manage formatting options. For
instance, in some my projects I use mapping <F9> to open project window 
(from plugin project.tar.gz), but for some java projects I use Eclim, and <F9>
should be mapped to another command (to open Eclim's project). 
All these options can also be stated in .vimprj dir.

There is an issue: as I already said, I would like to use shiftwidth=3. Say,
I open some file from my project with shiftwidth=3. All ok here. Then I open
file from another project with shiftwidth=4. All is still ok. Then I open some
file not from any project (there's no ".vimprj" directory). Of course, I would
like to use my favorite options (e.g. shiftwidth=3), but now shiftwidth is 4,
because it was changed when I opened last project. It leads us to the fact
that we should define default options. But here let me make a digression.

Plugin provides some hooks for any other plugin. For instance, plugin 
Indexer (since version 4.0) uses these hooks to provide correct behavior 
when user works on different project simultaneusly.

Right now I have not documented yet all these hooks, because of lack of 
free time, but I just tell you about one hook, to let you specify your
default options.

This is a hook "SetDefaultOptions". Now I show you an example. Please insert
in your .vimrc the following, just specify your own default options instead of
mine ones: >

   function! <SID>SetMainDefaults()

      " your default options goes here!
      set tabstop=3
      set shiftwidth=3
      set expandtab

   endfunction

   call <SID>SetMainDefaults()

   " initialize vimprj plugin
   call vimprj#init()

   " define a hook
   function! g:vimprj#dHooks['SetDefaultOptions']['main_options'](dParams)
      call <SID>SetMainDefaults()
   endfunction

Now vimprj plugin will call your function SetMainDefaults just before sourcing
all *.vim files from .vimprj directory, and when you open file not from any
project.

If you are interesting about another hooks, you can just look how is they used
in Indexer plugin. I hope one day I will write all this here. =)


========================================================================
DEPENDENCIES                                        *vimprj-dependencies*

You need to download the following scripts to work with this plugin:

DfrankUtil     ( http://www.vim.org/scripts/script.php?script_id=3884 )

========================================================================
OPTIONS                                                  *vimprj-options*

There is few options right now.


g:vimprj_recurseUpCount                (default: 10)

   number of directories that plugin will check by going up by tree while
   looking for ".vimprj" directory.

g:vimprj_dirNameForSearch              (default: '.vimprj')

   if you don't like name ".vimprj" for some reason, you can change it.

g:vimprj_changeCurDirIfVimprjFound     (default: 0)

   If set, Vimprj changes current directory to directory in which ".vimprj" is
   found.

   I found it quite useful: when I work on some project, I always have
   root of my project as current directory. It becomes changed when I switch
   to buffer from another project.

   If I open some file not from any project, then my current directory becomes
   a directory from what Vim was started.

========================================================================
COMMANDS                                                *vimprj-commands*

:VimprjInfo

   Echoes current project root 
   (project root is a directory which contains .vimprj directory or file)

========================================================================
KNOWN BUGS                                                  *vimprj-bugs*

None.

 vim:ft=help:tw=78: