Added plugin
This commit is contained in:
parent
28bf03aa10
commit
b25edc0a0f
710
doc/project.txt
Normal file
710
doc/project.txt
Normal file
@ -0,0 +1,710 @@
|
|||||||
|
*project.txt* Plugin for managing multiple projects with multiple sources
|
||||||
|
For Vim version 6.x and Vim version 7.x.
|
||||||
|
Last Change: Fri 13 Oct 2006 10:20:13 AM EDT
|
||||||
|
|
||||||
|
|
||||||
|
By Aric Blumer
|
||||||
|
aricvim email-at-sign charter.net
|
||||||
|
|
||||||
|
*project* *project-plugin*
|
||||||
|
Contents:
|
||||||
|
|
||||||
|
Commands...................|project-invoking|
|
||||||
|
Inheritance.............|project-inheritance|
|
||||||
|
Mappings...................|project-mappings|
|
||||||
|
Adding Mappings.....|project-adding-mappings|
|
||||||
|
Settings...................|project-settings|
|
||||||
|
Example File................|project-example|
|
||||||
|
Tips...........................|project-tips|
|
||||||
|
|
||||||
|
|
||||||
|
You can use this plugin's basic functionality to set up a list of
|
||||||
|
frequently-accessed files for easy navigation. The list of files will be
|
||||||
|
displayed in a window on the left side of the Vim window, and you can press
|
||||||
|
<Return> or double-click on filenames in the list to open the files. I find
|
||||||
|
this easier to use than having to navigate a directory hierarchy with the
|
||||||
|
|file-explorer|.
|
||||||
|
|
||||||
|
You can also instruct the Plugin to change to a directory and to run Vim
|
||||||
|
scripts when you select a file. These scripts can, for example, modify the
|
||||||
|
environment to include compilers in $PATH. This makes it very easy to use
|
||||||
|
quickfix with multiple projects that use different environments.
|
||||||
|
|
||||||
|
Other features include:
|
||||||
|
o Loading/Unloading all the files in a Project (\l, \L, \w, and \W)
|
||||||
|
o Grepping all the files in a Project (\g and \G)
|
||||||
|
o Running a user-specified script on a file (can be used to launch an
|
||||||
|
external program on the file) (\1 through \9)
|
||||||
|
o Running a user-specified script on all the files in a Project
|
||||||
|
(\f1-\f9 and \F1-\F9)
|
||||||
|
o High degree of user-configurability
|
||||||
|
o Also works with |netrw| using the XXXX://... notation where XXXX is
|
||||||
|
ftp, rcp, scp, or http.
|
||||||
|
|
||||||
|
All of this is specified within a simple text file and a few global variables
|
||||||
|
in your vimrc file.
|
||||||
|
|
||||||
|
You must set 'nocompatible' in your |vimrc| file to use this plugin. You can
|
||||||
|
stop the plugin from being loaded by setting the "loaded_project" variable: >
|
||||||
|
:let loaded_project = 1
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
COMMANDS *project-invoking*
|
||||||
|
|
||||||
|
You can use the plugin by placing it in your plugin directory (e.g.,
|
||||||
|
~/.vim/plugin). See |add-global-plugin|. When you start vim the next time, you
|
||||||
|
then enter the command >
|
||||||
|
:Project
|
||||||
|
or >
|
||||||
|
:Project {file}
|
||||||
|
|
||||||
|
If you do not specify the filename, $HOME/.vimprojects is used.
|
||||||
|
|
||||||
|
To have Vim come up with the Project Window enabled automatically (say, from a
|
||||||
|
GUI launcher), run Vim like this: [g]vim +Project
|
||||||
|
|
||||||
|
Note that you can invoke :Project on only one file at a time. If you wish to
|
||||||
|
change the Project File, do a :bwipe in the Project Buffer, then re-invoke the
|
||||||
|
Plugin as described above.
|
||||||
|
|
||||||
|
Several Projects can be kept and displayed in the same file, each in a fold
|
||||||
|
delimited by { and } (see |fold.txt|). There can be any number of nested
|
||||||
|
folds to provide you with a Project hierarchy. Any line without a { or a } in
|
||||||
|
the file is considered to be a filename. Blank lines are ignored, and any
|
||||||
|
text after a # is ignored.
|
||||||
|
|
||||||
|
Because the plugin uses standard Vim folds, you can use any of the
|
||||||
|
|fold-commands|. You can double-click on the first line of a fold to open and
|
||||||
|
close it. You can select a file to open by putting the cursor on its name and
|
||||||
|
pressing <Return> or by double-clicking on it. The plugin will create a new
|
||||||
|
window to the right or use the |CTRL-W_p| equivalent if it exists.
|
||||||
|
|
||||||
|
*project-syntax*
|
||||||
|
Each Project Entry has this form:
|
||||||
|
|
||||||
|
project_entry ::=
|
||||||
|
<Description>={projpath} [{options}] {
|
||||||
|
[ filename ]
|
||||||
|
[ project_entry ]
|
||||||
|
}
|
||||||
|
|
||||||
|
{options} is one or more of the following (on the same line):
|
||||||
|
CD={path}
|
||||||
|
in={filename}
|
||||||
|
out={filename}
|
||||||
|
filter="{pat}"
|
||||||
|
flags={flag}
|
||||||
|
|
||||||
|
Note that a project_entry can reside within a project_entry. This allows you
|
||||||
|
to set up a hierarchy within your Project.
|
||||||
|
|
||||||
|
The <Description> will be displayed in the foldtext and cannot contain "=".
|
||||||
|
There can be no space character directly on either side of the =.
|
||||||
|
|
||||||
|
The {projpath} is the path in which the files listed in the Project's fold
|
||||||
|
will be found, and it may contain environment variables. If the path is a
|
||||||
|
relative path, then the plugin constructs the whole path from the Project's
|
||||||
|
parent, grandparent, etc., all the way up the hierarchy. An outermost
|
||||||
|
project_entry must have an absolute path. See the |project-inheritance|
|
||||||
|
example below. {projpath} may contain spaces, but they must be escaped like
|
||||||
|
normal Vim escapes. Here are two examples of the same directory:
|
||||||
|
>
|
||||||
|
Example=/my/directory/with\ spaces {
|
||||||
|
}
|
||||||
|
Example="/my/directory/with spaces" {
|
||||||
|
}
|
||||||
|
|
||||||
|
I recommend this for Windows®: >
|
||||||
|
|
||||||
|
Example="c:\My Documents" {
|
||||||
|
}
|
||||||
|
|
||||||
|
But Vim is smart enough to do this, too: >
|
||||||
|
|
||||||
|
Example=c:\My\ Documents {
|
||||||
|
}
|
||||||
|
|
||||||
|
CD= provides the directory that Vim will change to when you select a file in
|
||||||
|
that fold (using |:cd|). This allows you, for example, to enter |:make| to use
|
||||||
|
the local Makefile. A CD=. means that Vim will make {projpath} or its
|
||||||
|
inherited equivalent the current working directory. When CD is omitted, the
|
||||||
|
directory is not changed. There can be no space on either side of the =. The
|
||||||
|
value of CD can also be a relative path from a parent's CD. See the
|
||||||
|
|project-inheritance| example below. This directive is ignored for |netrw|
|
||||||
|
projects. Spaces are allowed in the path as for {projpath}.
|
||||||
|
|
||||||
|
in= and out= provide the means to run arbitrary Vim scripts whenever you enter
|
||||||
|
or leave a file's buffer (see the |BufEnter| and |BufLeave| autocommand
|
||||||
|
events). The idea is to have a Vim script that sets up or tears down the
|
||||||
|
environment for the Project like this:
|
||||||
|
|
||||||
|
in.vim: >
|
||||||
|
let $PROJECT_HOME='~/my_project'
|
||||||
|
" Put the compiler in $PATH
|
||||||
|
if $PATH !~ '/path/to/my/compiler'
|
||||||
|
let $PATH=$PATH.':/path/to/my/compiler'
|
||||||
|
endif
|
||||||
|
|
||||||
|
out.vim: >
|
||||||
|
" Remove compiler from $PATH
|
||||||
|
if $PATH =~ '/path/to/my/compiler'
|
||||||
|
let $PATH=substitute($PATH, ':/path/to/my/compiler', '', 'g')
|
||||||
|
endif
|
||||||
|
|
||||||
|
Then you can use :make with the proper environment depending on what file you
|
||||||
|
are currently editing. If the path to the script is relative, then it is
|
||||||
|
relative from {projpath}. These directives are inherited by Subprojects
|
||||||
|
unless the Subproject specifies its own. For use with |netrw| projects, the
|
||||||
|
paths specified for in= and out= must be absolute and local.
|
||||||
|
|
||||||
|
filter= specifies a |glob()| file pattern. It is used to regenerate the list
|
||||||
|
of files in a Project fold when using the \r (<LocalLeader>r) map in the
|
||||||
|
Project Window. The filter value must be in quotes because it can contain
|
||||||
|
multiple file patterns. If filter is omitted, then the * pattern is used.
|
||||||
|
There can be no space on either side of the =. A Subproject will inherit the
|
||||||
|
filter of its parent unless it specifies its own filter.
|
||||||
|
|
||||||
|
flags= provides the means to enable/disable features for a particular fold.
|
||||||
|
The general mnemonic scheme is for lower case to turn something off and upper
|
||||||
|
case to turn something on. {flag} can contain any of the following
|
||||||
|
characters:
|
||||||
|
|
||||||
|
flag Description ~
|
||||||
|
|
||||||
|
l Turn off recursion for this fold for \L. Subfolds are also
|
||||||
|
blocked from the recursion.
|
||||||
|
|
||||||
|
r Turn off refresh. When present, do not refresh this fold when
|
||||||
|
\r or \R is used. This does not affect subfold recursion.
|
||||||
|
|
||||||
|
S Turn on sorting for refresh and create.
|
||||||
|
|
||||||
|
s Turn off sorting for refresh and create.
|
||||||
|
|
||||||
|
T Turn on top gravity. Forces folds to the top of the current
|
||||||
|
fold when refreshing. It has the same affect as the 'T' flag
|
||||||
|
in g:proj_flags, but controls the feature on a per-fold basis.
|
||||||
|
|
||||||
|
t Turn off top gravity. Forces folds to the bottom of the
|
||||||
|
current fold when refreshing.
|
||||||
|
|
||||||
|
w Turn off recursion for this fold for \W. Subfolds are also
|
||||||
|
blocked from the recursion.
|
||||||
|
|
||||||
|
|
||||||
|
Flags are not inherited by Subprojects.
|
||||||
|
|
||||||
|
Any text outside a fold is ignored.
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
INHERITANCE *project-inheritance*
|
||||||
|
|
||||||
|
It's best to show inheritance by comparing these two Project Files:
|
||||||
|
>
|
||||||
|
Parent=~/my_project CD=. filter="Make* *.mk" flags=r {
|
||||||
|
Child1=c_code {
|
||||||
|
}
|
||||||
|
Child2=include CD=. filter="*.h" {
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
Child1's path is "~/my_project/c_code" because ~/my_project is inherited. It
|
||||||
|
also inherits the CD from Parent. Since Parent has CD=., the Parent's cwd is
|
||||||
|
"~/my_project". Child1 therefore inherits a CD of "~/my_project". Finally,
|
||||||
|
Child1 inherits the filter from Parent. The flags are not inherited.
|
||||||
|
|
||||||
|
Child2 only inherits the "~/my_project" from Parent.
|
||||||
|
|
||||||
|
Thus, the example above is exactly equivalent to this:
|
||||||
|
>
|
||||||
|
Parent=~/my_project CD=. filter="Make* *.mk" flags=r {
|
||||||
|
Child1=~/my_project/c_code CD=~/my_project filter="Make* *.mk" {
|
||||||
|
}
|
||||||
|
Child2=~/my_project/include CD=~/my_project/include filter="*.h" {
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
(For a real Project, Child1 would not want to inherit its parent's filter, but
|
||||||
|
this example shows the concept.) You can always enter \i to display what the
|
||||||
|
cursor's project inherits.
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
MAPPINGS *project-mappings*
|
||||||
|
|
||||||
|
Map Action ~
|
||||||
|
|
||||||
|
\r Refreshes the Project fold that the cursor is in by placing in the
|
||||||
|
fold all the files that match the filter. The Project is refreshed
|
||||||
|
using an indent of one space for every foldlevel in the hierarchy.
|
||||||
|
|
||||||
|
You may place a "# pragma keep" (without the quotes) at the end of a
|
||||||
|
line, and the file entry on that line will not be removed when you
|
||||||
|
refresh. This is useful, for example, when you have . as an entry so
|
||||||
|
you can easily browse the directory.
|
||||||
|
|
||||||
|
Note that this mapping is actually <LocalLeader>r, and the default of
|
||||||
|
|<LocalLeader>| is \.
|
||||||
|
|
||||||
|
This does not work for Projects using |netrw|.
|
||||||
|
|
||||||
|
\R Executes \r recursively in the current fold and all folds below.
|
||||||
|
This does not work for Projects using |netrw|.
|
||||||
|
|
||||||
|
\c Creates a Project fold entry. It asks for the description, the path
|
||||||
|
to the files, the CD parameter, and the filename |glob()| pattern.
|
||||||
|
From this information, it will create the Project Entry below the
|
||||||
|
cursor.
|
||||||
|
|
||||||
|
This does not work for Projects using |netrw|.
|
||||||
|
|
||||||
|
\C Creates a Project fold entry like \c, but recursively includes all the
|
||||||
|
subdirectories.
|
||||||
|
|
||||||
|
<Return>
|
||||||
|
Select a file to open in the |CTRL-W_p| window or in a new window. If
|
||||||
|
the cursor is on a fold, open or close it.
|
||||||
|
|
||||||
|
<S-Return>
|
||||||
|
\s
|
||||||
|
Same as <Return> but horizontally split the target window.
|
||||||
|
<LocalLeader>s is provided for those terminals that don't recognize
|
||||||
|
<S-Return>.
|
||||||
|
|
||||||
|
\S
|
||||||
|
Load all files in a project by doing horizontal splits.
|
||||||
|
|
||||||
|
<C-Return>
|
||||||
|
\o
|
||||||
|
Same as <Return> but ensure that the opened file is the only other
|
||||||
|
window. <LocalLeader>o is provided for those terminals that don't
|
||||||
|
recognize <C-Return>.
|
||||||
|
|
||||||
|
<M-Return>
|
||||||
|
\v
|
||||||
|
Same as <Return> but only display the file--the cursor stays in the
|
||||||
|
Project Window.
|
||||||
|
|
||||||
|
<2-LeftMouse>
|
||||||
|
(Double-click) If on a closed fold, open it. If on an open fold
|
||||||
|
boundary, close it. If on a filename, open the file in the |CTRL-W_p|
|
||||||
|
window or in a new window.
|
||||||
|
|
||||||
|
<S-2-LeftMouse>
|
||||||
|
Same as <S-Return>.
|
||||||
|
|
||||||
|
<C-2-LeftMouse>
|
||||||
|
Same as <C-Return>.
|
||||||
|
|
||||||
|
<RightMouse>
|
||||||
|
Increase the width of the Project Window by g:proj_window_increment or
|
||||||
|
toggle between a width of
|
||||||
|
g:proj_window_width + g:proj_window_increment
|
||||||
|
and
|
||||||
|
g:proj_window_width.
|
||||||
|
|
||||||
|
Whether you toggle or monotonically increase the width is determined
|
||||||
|
by the 't' flag of the g:proj_flags variable (see |project-flags|).
|
||||||
|
|
||||||
|
Note that a Right Mouse click will not automatically place the cursor
|
||||||
|
in the Project Window if it is in a different window. The window will
|
||||||
|
go back to the g:proj_window_width width when you leave the window.
|
||||||
|
|
||||||
|
<space> Same as <RightMouse>
|
||||||
|
|
||||||
|
<CTRL-Up>
|
||||||
|
\<Up>
|
||||||
|
Move the text or fold under the cursor up one row. This may not work
|
||||||
|
in a terminal because the terminal is unaware of this key combination.
|
||||||
|
<LocalLeader><Up> is provided for those terminals that don't recognize
|
||||||
|
<C-Up>.
|
||||||
|
|
||||||
|
|
||||||
|
<CTRL-Down>
|
||||||
|
\<Down>
|
||||||
|
Move the text or fold under the cursor down one row. This may not work
|
||||||
|
in a terminal because the terminal is unaware of this key combination.
|
||||||
|
<LocalLeader><Down> is provided for those terminals that don't
|
||||||
|
recognize <C-Down>.
|
||||||
|
|
||||||
|
\i Show in the status line the completely resolved and inherited
|
||||||
|
parameters for the fold the cursor is in. This is intended for
|
||||||
|
debugging your relative path and inherited parameters for manually
|
||||||
|
entered Projects.
|
||||||
|
|
||||||
|
\I Show in the status line the completely resolved filename. Uses the
|
||||||
|
Project_GetFname(line('.')) function.
|
||||||
|
|
||||||
|
\1 - \9
|
||||||
|
Run the command specified in g:proj_run{x} where {x} is the number
|
||||||
|
of the key. See the documentation of g:proj_run1 below.
|
||||||
|
|
||||||
|
\f1-\f9
|
||||||
|
Run the command specified in g:proj_run_fold{x} where {x} is the
|
||||||
|
number of the key. The command is run on the files at the current
|
||||||
|
Project level. See the |project-settings| below.
|
||||||
|
|
||||||
|
\F1-\F9
|
||||||
|
Run the command specified in g:proj_run_fold{x} where {x} is the
|
||||||
|
number of the key. The command is run on the files at the current
|
||||||
|
Project level and all Subprojects. See the |project-settings| below.
|
||||||
|
|
||||||
|
\0 Display the commands that are defined for \1 through \9.
|
||||||
|
|
||||||
|
\f0 Display the commands that are defined for \f1 through \f9 and \F1
|
||||||
|
through \F0. Same as \F0.
|
||||||
|
|
||||||
|
\l Load all the files in the current Project level into Vim. While files
|
||||||
|
are being loaded, you may press any key to stop.
|
||||||
|
|
||||||
|
\L Load all the files in the current Project and all Subprojects into
|
||||||
|
Vim. Use this mapping with caution--I wouldn't suggest using \L to
|
||||||
|
load a Project with thousands of files. (BTW, my Project file has more
|
||||||
|
than 5,300 files in it!) While files are being loaded, you may press
|
||||||
|
any key to stop.
|
||||||
|
|
||||||
|
\w Wipe all the files in the current Project level from Vim. (If files
|
||||||
|
are modified, they will be saved first.) While files are being wiped,
|
||||||
|
you may press any key to stop.
|
||||||
|
|
||||||
|
\W Wipe all the files in the current Project and all Subprojects from
|
||||||
|
Vim. (If files are modified, they will be saved first.) While files
|
||||||
|
are being wiped, you may press any key to stop.
|
||||||
|
|
||||||
|
\g Grep all the files in the current Project level.
|
||||||
|
|
||||||
|
\G Grep all the files in the current Project level and all Subprojects.
|
||||||
|
|
||||||
|
\e Set up the Environment for the Project File as though you had selected
|
||||||
|
it with <Return>. This allows you to do a \e and a :make without
|
||||||
|
having to open any files in the project.
|
||||||
|
|
||||||
|
\E Explore (using |file-explorer|) the directory of the project the
|
||||||
|
cursor is in. Does not work with netrw.
|
||||||
|
|
||||||
|
<F12> When the 'g' flag is present in g:proj_flags (see |project-flags|)
|
||||||
|
this key toggles the Project Window open and closed. You may remap
|
||||||
|
this toggle function by putting the following in your vimrc and
|
||||||
|
replacing <Leader>P with whatever key combination you wish:
|
||||||
|
|
||||||
|
nmap <silent> <Leader>P <Plug>ToggleProject
|
||||||
|
|
||||||
|
Note that the Project Plugin remaps :help because the Help Window and the
|
||||||
|
Project Window get into a fight over placement. The mapping avoids the
|
||||||
|
problem.
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
ADDING MAPPINGS *project-adding-mappings*
|
||||||
|
|
||||||
|
You can add your own mappings or change the mappings of the plugin by placing
|
||||||
|
them in the file $HOME/.vimproject_mappings. This file, if it exists, will be
|
||||||
|
sourced when the plugin in loaded. Here is an example that will count the
|
||||||
|
number of entries in a project when you press \K (Kount, C is taken :-): >
|
||||||
|
|
||||||
|
function! s:Wc()
|
||||||
|
let b:loadcount=0
|
||||||
|
function! SpawnExec(infoline, fname, lineno, data)
|
||||||
|
let b:loadcount = b:loadcount + 1
|
||||||
|
if getchar(0) != 0 | let b:stop_everything=1 | endif
|
||||||
|
endfunction
|
||||||
|
call Project_ForEach(1, line('.'), "*SpawnExec", 0, '')
|
||||||
|
delfunction SpawnExec
|
||||||
|
echon b:loadcount." Files\r"
|
||||||
|
unlet b:loadcount
|
||||||
|
if exists("b:stop_everything")
|
||||||
|
unlet b:stop_everything
|
||||||
|
echon "Aborted.\r"
|
||||||
|
endif
|
||||||
|
endfunction
|
||||||
|
|
||||||
|
nnoremap <buffer> <silent> <LocalLeader>K :call <SID>Wc()<CR>
|
||||||
|
|
||||||
|
Here's another example of how I integrated the use of perforce with the plugin
|
||||||
|
in my $HOME/.vimproject_mappings:
|
||||||
|
>
|
||||||
|
function! s:DoP4(cmd)
|
||||||
|
let name=Project_GetFname(line('.'))
|
||||||
|
let dir=substitute(name, '\(.*\)/.*', '\1', 'g')
|
||||||
|
exec 'cd '.dir
|
||||||
|
exec "!".a:cmd.' '.Project_GetFname(line('.'))
|
||||||
|
cd -
|
||||||
|
endfunction
|
||||||
|
|
||||||
|
nmap <buffer> <silent> \pa :call <SID>DoP4("p4add")<CR>
|
||||||
|
nmap <buffer> <silent> \pe :call <SID>DoP4("p4edit")<CR>
|
||||||
|
<
|
||||||
|
(Note that I CD to the directory the file is in so I can pick of the $P4CONFIG
|
||||||
|
file. See the perforce documentation.)
|
||||||
|
|
||||||
|
This creates the mappings \pe to check out the file for edit and \pa to add
|
||||||
|
the file to the depot.
|
||||||
|
|
||||||
|
Here is another example where I remap the <Return> mapping to use an external
|
||||||
|
program to launch a special kind of file (in this case, it launches ee to view
|
||||||
|
a jpg file). It is a bit contrived, but it works.
|
||||||
|
>
|
||||||
|
let s:sid = substitute(maparg('<Return>', 'n'), '.*\(<SNR>.\{-}\)_.*', '\1', '')
|
||||||
|
function! s:LaunchOrWhat()
|
||||||
|
let fname=Project_GetFname(line('.'))
|
||||||
|
if fname =~ '\.jpg$'
|
||||||
|
exec 'silent! !ee "'.fname.'"&'
|
||||||
|
else
|
||||||
|
call {s:sid}_DoFoldOrOpenEntry('', 'e')
|
||||||
|
endif
|
||||||
|
endfunction
|
||||||
|
nnoremap <buffer> <silent> <Return> \|:call <SID>LaunchOrWhat()<CR>
|
||||||
|
<
|
||||||
|
If the file ends in .jpg, the external program is launched, otherwise the
|
||||||
|
original mapping of <Return> is run.
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
SETTINGS *project-settings*
|
||||||
|
|
||||||
|
You can set these variables in your vimrc file before the plugin is loaded to
|
||||||
|
change its default behavior
|
||||||
|
|
||||||
|
g:proj_window_width
|
||||||
|
The width of the Project Window that the plugin attempts to maintain.
|
||||||
|
Default: 24
|
||||||
|
|
||||||
|
The Project Plugin is not always successful in keeping the window
|
||||||
|
where I want it with the size specified here, but it does a decent
|
||||||
|
job.
|
||||||
|
|
||||||
|
g:proj_window_increment
|
||||||
|
The increment by which to increase the width of the Project Window
|
||||||
|
when pressing <space> or clicking the <LeftMouse>. Default: 100
|
||||||
|
(See |project-mappings|.)
|
||||||
|
|
||||||
|
*project-flags*
|
||||||
|
g:proj_flags
|
||||||
|
Default: "imst"
|
||||||
|
Various flags to control the behavior of the Project Plugin. This
|
||||||
|
variable can contain any of the following character flags.
|
||||||
|
|
||||||
|
flag Description ~
|
||||||
|
|
||||||
|
b When present, use the |browse()| when selecting directories
|
||||||
|
for \c and \C. This is off by default for Windows, because
|
||||||
|
the windows browser does not allow you to select directories.
|
||||||
|
|
||||||
|
c When present, the Project Window will automatically close when
|
||||||
|
you select a file.
|
||||||
|
|
||||||
|
F Float the Project Window. That is, turn off automatic
|
||||||
|
resizing and placement. This allows placement between other
|
||||||
|
windows that wish to share similar placement at the side of
|
||||||
|
the screen. It is also particularly helpful for external
|
||||||
|
window managers.
|
||||||
|
|
||||||
|
g When present, the mapping for <F12> will be created to toggle
|
||||||
|
the Project Window open and closed.
|
||||||
|
|
||||||
|
i When present, display the filename and the current working
|
||||||
|
directory in the command line when a file is selected for
|
||||||
|
opening.
|
||||||
|
|
||||||
|
l When present, the Project Plugin will use the |:lcd| command
|
||||||
|
rather than |:cd| to change directories when you select a file
|
||||||
|
to open. This flag is really obsolete and not of much use
|
||||||
|
because of L below.
|
||||||
|
|
||||||
|
L Similar to l, but install a BufEnter/Leave |:autocommand| to
|
||||||
|
ensure that the current working directory is changed to the
|
||||||
|
one specified in the fold CD specification whenever that
|
||||||
|
buffer is active. (|:lcd| only changes the CWD for a window,
|
||||||
|
not a buffer.)
|
||||||
|
|
||||||
|
m Turn on mapping of the |CTRL-W_o| and |CTRL-W_CTRL_O| normal
|
||||||
|
mode commands to make the current buffer the only visible
|
||||||
|
buffer, but keep the Project Window visible, too.
|
||||||
|
|
||||||
|
n When present, numbers will be turned on for the project
|
||||||
|
window.
|
||||||
|
|
||||||
|
s When present, the Project Plugin will use syntax highlighting
|
||||||
|
in the Project Window.
|
||||||
|
|
||||||
|
S Turn on sorting for refresh and create.
|
||||||
|
|
||||||
|
t When present, toggle the size of the window rather than just
|
||||||
|
increase the size when pressing <space> or right-clicking.
|
||||||
|
See the entry for <RightMouse> in |project-mappings|.
|
||||||
|
|
||||||
|
T When present, put Subproject folds at the top of the fold when
|
||||||
|
refreshing.
|
||||||
|
|
||||||
|
v When present, use :vimgrep rather than :grep when using \G.
|
||||||
|
|
||||||
|
g:proj_run1 ... g:proj_run9
|
||||||
|
Contains a Vim command to execute on the file. See the
|
||||||
|
mappings of \1 to \9 above.
|
||||||
|
|
||||||
|
%f is replaced with the full path and filename
|
||||||
|
%F is replaced with the full path and filename with spaces
|
||||||
|
quoted
|
||||||
|
%n is replaced with the filename alone
|
||||||
|
%N is replaced with the filename alone with spaces quoted
|
||||||
|
%h is replaced with the home directory
|
||||||
|
%H is replaced with the home directory with spaces quoted
|
||||||
|
%r is replaced with the directory relative to the CD path
|
||||||
|
%R is replaced with the directory relative to the CD path
|
||||||
|
with spaces quoted
|
||||||
|
%d is replaced with the CD directory.
|
||||||
|
%D is replaced with the CD directory.with spaces quoted
|
||||||
|
%% is replaced with a single % that is not used in
|
||||||
|
expansion.
|
||||||
|
|
||||||
|
(Deprecated: %s is also replaced with the full path and
|
||||||
|
filename for backward compatibility.)
|
||||||
|
|
||||||
|
For example, gvim will be launched on the file under the
|
||||||
|
cursor when you enter \3 if the following is in your vimrc
|
||||||
|
file: >
|
||||||
|
let g:proj_run3='silent !gvim %f'
|
||||||
|
< Here are a few other examples: >
|
||||||
|
let g:proj_run1='!p4 edit %f'
|
||||||
|
let g:proj_run2='!p4 add %f'
|
||||||
|
let g:proj_run4="echo 'Viewing %f'|sil !xterm -e less %f &"
|
||||||
|
<
|
||||||
|
On Windows systems you will want to put the %f, %h, and %d in
|
||||||
|
single quotes to avoid \ escaping.
|
||||||
|
|
||||||
|
g:proj_run_fold1 ... g:proj_run_fold9
|
||||||
|
Contains a Vim command to execute on the files in a fold. See
|
||||||
|
the mappings of \f1 to \f9 and \F1 to \F9 above.
|
||||||
|
|
||||||
|
%f is the filename, %h is replaced with the project home
|
||||||
|
directory, and %d is replaced with the CD directory. Multiple
|
||||||
|
filenames can be handled in two ways:
|
||||||
|
|
||||||
|
The first (default) way is to have %f replaced with all the
|
||||||
|
absolute filenames, and the command is run once. The second
|
||||||
|
is to have the command run for each of the non-absolute
|
||||||
|
filenames (%f is replaced with one filename at a time). To
|
||||||
|
select the second behavior, put an '*' character at the
|
||||||
|
beginning of the g:proj_run_fold{x} variable. (The '*' is
|
||||||
|
stripped before the command is run.)
|
||||||
|
|
||||||
|
For example, note the difference between the following: >
|
||||||
|
let g:proj_run_fold3="*echo '%h/%f'"
|
||||||
|
let g:proj_run_fold4="echo '%f'"
|
||||||
|
<
|
||||||
|
Note that on Windows systems, you will want the %f, %h, and %c
|
||||||
|
within single quotes, or the \ in the paths will cause
|
||||||
|
problems. The alternative is to put them in |escape()|.
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
PROJECT EXAMPLE FILE *project-example*
|
||||||
|
|
||||||
|
Here is an example ~/.vimprojects file: >
|
||||||
|
|
||||||
|
1 My Project=~/c/project CD=. in=in.vim out=out.vim flags=r {
|
||||||
|
2 Makefile
|
||||||
|
3 in.vim
|
||||||
|
4 out.vim
|
||||||
|
5 GUI Files=. filter="gui*.c gui*.h" {
|
||||||
|
6 gui_window.c
|
||||||
|
7 gui_dialog.c
|
||||||
|
8 gui_list.c
|
||||||
|
9 gui.h # Header file
|
||||||
|
10 }
|
||||||
|
11 Database Files=. filter="data*.c data*.h" {
|
||||||
|
12 data_read.c
|
||||||
|
13 data_write.c
|
||||||
|
14 data.h
|
||||||
|
15 }
|
||||||
|
16 OS-Specific Files {
|
||||||
|
17 Win32=. filter="os_win32*.c os_win32*.h" {
|
||||||
|
18 os_win32_gui.c
|
||||||
|
19 os_win32_io.c
|
||||||
|
20 }
|
||||||
|
21 Unix=. filter="os_unix*.c os_unix*.h" {
|
||||||
|
22 os_unix_gui.c
|
||||||
|
23 os_unix_io.c
|
||||||
|
24 }
|
||||||
|
25 }
|
||||||
|
26 }
|
||||||
|
|
||||||
|
(Don't type in the line numbers, of course.)
|
||||||
|
|
||||||
|
|
||||||
|
==============================================================================
|
||||||
|
TIPS ON USING PROJECT PLUGIN *project-tips*
|
||||||
|
|
||||||
|
1. You can create a Project Entry by entering this: >
|
||||||
|
|
||||||
|
Label=~/wherever CD=. filter="*.c *.h" {
|
||||||
|
}
|
||||||
|
<
|
||||||
|
Then you can put the cursor in the fold and press \r. The script will fill
|
||||||
|
in the files (C files in this case) from this directory for you. This is
|
||||||
|
equivalent to \c without any dialogs.
|
||||||
|
|
||||||
|
2. You can edit the Project File at any time to add, remove, or reorder files
|
||||||
|
in the Project list.
|
||||||
|
|
||||||
|
3. If the Project Window ever gets closed, you can just enter >
|
||||||
|
:Project
|
||||||
|
< to bring it back again. (You don't need to give it the filename; the
|
||||||
|
plugin remembers.)
|
||||||
|
|
||||||
|
If you have the 'm' flag set in g:proj_flags, then you get the Project
|
||||||
|
Window to show up again by pressing |CTRL-W_o|. This, of course, will
|
||||||
|
close any other windows that may be open that the cursor is not in.
|
||||||
|
|
||||||
|
4. Adding files to a Project is very easy. To add, for example, the 'more.c'
|
||||||
|
file to the Project, just insert the filename in the Project Entry then
|
||||||
|
hit <Return> on it.
|
||||||
|
|
||||||
|
5. When |quickfix| loads files, it is not equivalent to pressing <Return> on
|
||||||
|
a filename, so the directory will not be changed and the scripts will not
|
||||||
|
be run. (If I could make this otherwise, I would.) The solution is to use
|
||||||
|
the \L key to load all of the files in the Project before running
|
||||||
|
quickfix.
|
||||||
|
|
||||||
|
6. If the Project window gets a bit cluttered with folds partially
|
||||||
|
open/closed, you can press |zM| to close everything and tidy it up.
|
||||||
|
|
||||||
|
7. For advanced users, I am exporting the function Project_GetAllFnames()
|
||||||
|
which returns all the filenames within a fold and optionally all its
|
||||||
|
Subprojects. Also, I export Project_ForEach() for running a function for
|
||||||
|
each filename in the project. See the code for examples on how to use
|
||||||
|
these. Finally, I export Project_GetFname(line_number) so that you can
|
||||||
|
write your own mappings and get the filename for it.
|
||||||
|
|
||||||
|
8. Some people have asked how to do a global mapping to take the cursor to
|
||||||
|
the Project window. One of my goals for the plugin is for it to be as
|
||||||
|
self-contained as possible, so I'm not going to add it by default. But you
|
||||||
|
can put this in your vimrc:
|
||||||
|
>
|
||||||
|
nmap <silent> <Leader>P :Project<CR>
|
||||||
|
|
||||||
|
<
|
||||||
|
9. You can put the . entry in a project, and it will launch the
|
||||||
|
|file-explorer| plugin on the directory. To avoid removal when you
|
||||||
|
refresh, make the entry look like this:
|
||||||
|
>
|
||||||
|
. # pragma keep
|
||||||
|
<
|
||||||
|
==============================================================================
|
||||||
|
THANKS
|
||||||
|
|
||||||
|
The following people have sent me patches to help with the Project
|
||||||
|
Plugin development:
|
||||||
|
|
||||||
|
Tomas Zellerin
|
||||||
|
Lawrence Kesteloot
|
||||||
|
Dave Eggum
|
||||||
|
A Harrison
|
||||||
|
Thomas Link
|
||||||
|
Richard Bair
|
||||||
|
Eric Arnold
|
||||||
|
Peter Jones
|
||||||
|
Eric Van Dewoestine
|
||||||
|
|
||||||
|
|
||||||
|
vim:ts=8 sw=8 noexpandtab tw=78 ft=help:
|
||||||
1293
plugin/project.vim
Normal file
1293
plugin/project.vim
Normal file
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user