diff options
Diffstat (limited to 'modules/vim/vim.dot.link/doc/project.txt')
| -rw-r--r-- | modules/vim/vim.dot.link/doc/project.txt | 710 |
1 files changed, 0 insertions, 710 deletions
diff --git a/modules/vim/vim.dot.link/doc/project.txt b/modules/vim/vim.dot.link/doc/project.txt deleted file mode 100644 index 8f85c23..0000000 --- a/modules/vim/vim.dot.link/doc/project.txt +++ /dev/null @@ -1,710 +0,0 @@ -*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: |