vimを使う上で欠かせないproject.vimのヘルプの日本語訳(意訳)
最近project.vimを使ってプロジェクトツリーを表示してソースを読む事が多いのですが、実際には、:Project {filename}で起動した後、
以上二つしか使ってきませんでした。
ただ他にもいろいろな使い方ができるようで、そのためにヘルプを読んでいたのですが、その際に作った意訳が他の人にも役立つかもしれないので掲載します。質が悪いので野良翻訳なので、原文も一緒です。
ちなみに、この度知った役に立ちそうなコマンドは、
- \Gで、現在のプロジェクト以下を全てgrep
で、プロジェクトウインドウの最大化、最小化 - \sで、水平分割して新たにファイルを表示
- zMで、プロジェクトを全てたたむ
- Ctrl+↑or↓で、ファイル名の並び替え
- プロジェクトファイルに # でコメント行としてTODOなどを記述
- ファイルを追加する時は、プロジェクトファイルに行追加して開くだけでできる
でした。
in.vimやout.vimを使っていろいろカスタマイズもできそうです。ここまでやると本当にIDE並みです。
なお、project.vimの配布元は
project.tar.gz : Organize/Navigate projects of files (like IDE/buffer explorer)
です。ここでダウンロードできる最新版のproject.txtを意訳しました。:help projectで読めます。
かなり適当な訳ですが悪しからず。
project.txtの日本語訳(意訳)
project.txt このプラグインは、複数のソースによる複数のプロジェクト を管理するためのものです。 Vimのバージョンは6.xと7.xに対応しています。 最終更新日時: Fri 13 Oct 2006 10:20:13 AM EDT 原著: Aric Blumer <aricvim at charter.net> 翻訳(意訳): Soichiro Yoshimura <yoshimura at soichiro.org> 内容: コマンド 継承 マッピング マッピング追加 設定 設定例 TIPS このプラグインは、よくアクセスするファイルのリストに簡単に ナビゲーションするための基本的な機能があります。 このリストはVimウインドウの左側に表示されます。 また<Return>かファイル名でダブルクリックするとリストのファイルを 開くことができます。またファイルエクスプローラーを使って簡単に ディレクトリ階層を探索することができます。 ディレクトリの変更と選択したファイルへのVimスクリプトの実行を プラグインにさせることができます。例えば、$PATH内のコンパイラを 含むような環境の変更ができます。これは異なる環境を使う複数の プロジェクトにクイックフィックスなどを簡単に利用する事ができます。 その他の含まれる特徴: プロジェクトの全てのファイルの読み込み/除去(\l, \L, \w, and \W) プロジェクト内の全てのファイルをgrepする (\g and \G) ユーザスクリプトのファイルへの実行(ファイル上の外部プログラムも可) (\1 through \9) プロジェクト内の全てのファイルへのユーザースクリプトの実行 (\f1-\f9 and \F1-\F9) 高いレベルでのユーザー設定機能 the XXXX://...という形式を用いるnetrwとの連携 (ftp, rcp, scp, http) これら全てはシンプルテキストとvimrc内のいくつかのグローバル変数に 記述します。 必ず、noconpatible設定をvimrcファイルにセットしてください。 もしこのプラグインを使わない場合には、vimrcに :let loaded_project = 1 を記述してください。 ============================================================================== コマンド このプラグインを使うために、 ~/.vim/pluginディレクトリに設置してください。 次に、このプラグインを使うためには、 :Project or :Project {file} 以上のコマンドを実行します。 特にファイルを指定しない場合は、$HOME/.vimprojects が読み込まれます。 起動時一緒にProjectのウインドウを起動するためには、 vim +Project として起動します。 Note 一つのファイルに対しては一度しか :Projectを実行できません。 もし、Projectのファイルを変更したい場合は、 Projectバッファ内で:bwipeを実行した後、プラグインを再実行して下さい。 複数のプロジェクトが{ }で区切られて同じファイルで表示されます。 プロジェクト階層の中に複数のプロジェクトをネストすることができます。 { } で表示されていない行はファイル名とみなします。 空行と#以降の文字は無視されます。 Vimの通常の折り畳み機能を使っているため、そのまま折り畳みコマンドが 使えます(zaで開閉、zaで再帰開閉など) 最初の行をダブルクリックすると その折り畳みが開いたり閉じたりします。ファイル名上にカーソルを置いて <Returen>またはダブルクリックでファイルが右側に表示されます。 もしファイルが存在していれば右側にウインドウを作り、 CTRL-W_p(右のウインドウに移動)を使ったのと同等の動きをします。 それぞれのプロジェクトのエントリは以下の形式です: project_entry ::= <Description>={projpath} [{options}] { [ filename ] [ project_entry ] } {options} は、ひとつ以上を同じ行に記述します: CD={path} in={filename} out={filename} filter="{pat}" flags={flag} Note プロジェクトエントリ内にプロジェクトエントリが存在できます。 これでプロジェクトの階層をセットアップできます。 <Description>部分は、折り畳みの際にも表示されますが=を含めません。 また=の横にはスペースを記述できません。 {projpath}はファイルが存在するパスで、環境変数なども含められます。 相対パスの場合、プラグインはパスをプロジェクトの親や親の親から構築します。 基本的に、プロジェクトエントリは、絶対パスで指定してください。 以下にプロジェクトの継承の例を表記します。{projpath}は、スペースを 含める事ができます。しかし、Vimの通常のエスケープが必要です。 二つの同じディレクトリの例を示します: Example=/my/directory/with\ spaces { } Example="/my/directory/with spaces" { } Windowsではこれがオススメです: Example="c:\My Documents" { } しかし、これでも十分にスマートです: Example=c:\My\ Documents { } CD= は折り畳みの中に入れる、ディレクトリを示します。 例えば、:makeでローカルのMakefileを使えるようにできます。 CD=. は、{projpath} と現在の作業ディレクトリの全てと同等なものになります。 もし、CDが省かれたときは、ディレクトリは変更しません。 なお =. の横にはスペースは記述できません。CDは相対パスも可能です。 project-inheritanceの例をご覧ください。このやり方は、netrw プロジェクトから 無視されています。{projpath}と同様にスペースもパスの中に記述できます。 in= と out= は、ファイルバッファに入ったとき、出た時に、実行される vimスクリプトです。次のように環境を立ち上げたり、終了させたりする ことができます: 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 これで現在編集中のファイルに会わせて適切な環境で:makeすることができます。 もしスクリプトへのパスが相対パスの場合は、{projpath}からの相対パスに なります。この設定はサブプロジェクトで設定しない限り、サブプロジェクトに 継承されます。netrwプロジェクトを使うたまには、 in=とout=が絶対パスか ローカルとなるようにパス設定してください。 filter= は glob()の ファイルパターンを記述します。 \r (<LocalLeade>r) で。 ファイルのリストを再生成します。フィルタの値は存在しなくてはならず、 複数のファイルパターンを含められます。もしフィルタが省略された場合、 * がパターンとして使われます。 =.の横にはスペースは記述できず、 サブプロジェクトもそこで記述しない限り設定を継承します。 flag= は特に折り畳みに関する機能を設定できます。 一般的なニーモニックスキーマは、小文字でオフ、大文字でオンを表します。 {flag} には以下のものがあります。 charactors: フラグ 説明 l 再帰的な不折り畳みの設定 r 表示された時にリフレッシュするかどうか(非再帰) S リフレッシュや作成時にソートする s リフレッシュや作成時にソートしない T リストの上方への重力のオン t リストの上方への重力オフ(リフレッシュ時) w 再帰的な折り畳みのオフ フラグはサブプロジェクトに継承されません。 折り畳みの外側の文字は無視されます。 ============================================================================== 継承 二つのプロジェクトファイルを比べて継承を紹介します。 Parent=~/my_project CD=. filter="Make* *.mk" flags=r { Child1=c_code { } Child2=include CD=. filter="*.h" { } } Child1のパスは~/my_project/c_codeです。 これは ~/my_projectから継承します。なおCDも継承します。 ここでは、親のCDは.となっています。 親のパスは~/my_projectです。 Child1は、CDの~/my_projectを継承している事になります。 最後にChild1はフィルタを親から継承します。しかしフラグは継承しません。 Child2は~/my_projectのみを継承しています。 以下は、全てを継承無しに同等に書いた場合です。 > 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" { } } 実際のプロジェクトでは、Child1は、親のフィルタを継承したくないはずです。 これは、コンセプトだけを示す例です。なお、\iでいつでも プロジェクトの継承の状態をを表示することができます。 ============================================================================== マッピング マッピング アクション ~ \r プロジェクトのリフレッシュ、リフレッシュで消えないようにするには、 行末に# pragma keepを記述。ちなみにnetrwは利用していない。 \R 再帰的な\r \c 対話形式でプロジェクトエントリを作成 \C フォルダ再帰的な\c <Return> ファイルを開きそのウインドウにカーソルを移動 <S-Return> \s 水平報告にファイルを開き、そのウインドウにカーソルを移動 \S プロジェクト内のファイルを全て読み込み垂直方向に分割表示(危険！) <C-Return> \o 新しいウインドウでファイルを開く。 <M-Return> \v 新しくファイルを開くがカーソルはそのまま。 <2-LeftMouse> ダブルクリックと一緒 <S-2-LeftMouse> <S-Return>と一緒 <C-2-LeftMouse> <C-Return>と一緒 <RightMouse> プロジェクトウインドウの枠を広げ最大化したり、戻したりする toggle between a width of g:proj_window_width + g:proj_window_increment and g:proj_window_width. <space> <RightMouse>と一緒 <CTRL-Up> \<Up> ファイルの一覧上で上方向に並べ替えしながら移動 <CTRL-Down> \<Down> ファイルの一覧上で下方向に並べ替えしながら移動 \i 今のプロジェクトのステータスや継承関係を表示 \I ファイルの完全修飾名を表示 \1 - \9 g:proj_run{x}で設定しておいたのコマンドを起動 詳しくは、設定のg:proj_run1 ... g:proj_run9の項を参照 \f1-\f9 \F1-\F9 g:proj_run_fold{x}で設定しておいたコマンドを実行 詳しくは、設定のg:proj_run_fold1 ... g:proj_run_fold9を参照 \0 1-9に登録してあるコマンドを表示 \f0 f1-f9登録してある登録してるコマンドを表示 \l 今のプロジェクトのファイルを読み込む \L 今のプロジェクトのサブプロジェクトも含めてファイルを読み込む \w 今のプロジェクトの読み込んでいるファイルを閉じる。保存もされる。 \W 今のプロジェクトのサブプロジェクトも含めてファイルを閉じ、保存する。 \g 今のプロジェクトのファイルをgrepする \G 今のプロジェクトのサブプロジェクトも含めてgrepする \e 現在のプロジェクトの環境設定をセットアップする \E 今いるプロジェクトのパスからファイルエクスプローラーを起動する <F12> 'g' フラグが g:proj_flags に設定されているなら、 ウインドウの開閉をトグルする ============================================================================== マッピング追加 ($HOME/.vimproject_mappingsで、マッピングを追加できますが、翻訳を省略します。 :help projectを参照ください。すみません。) ============================================================================== 設定 (翻訳を省略します。:help projectを参照ください。すみません。) ============================================================================== プロジェクトファイルの設定例 ~/.vimprojects の設定例です。 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 } (数字は、%s/^ \+[0-9]\+\t//g などで置換して数字は取り除いてください。) ============================================================================== TIPS 1. 以下のように入力してプロジェクトエントリを作成できます。 Label=~/wherever CD=. filter="*.c *.h" { } < 入力した後に\rを押します。そうするとディレクトリから、ファイルが 読み込まれます。これは\cのウィザードをダイアログ形式でなくやる方法です。 2. プロジェクトファイルは、ファイルを追加、削除、並べ直しをファイルのリスト 上でいつでもおこなうことができます。 3. 一度閉じてしまったプロジェクトを再度開く際は、 :Project と入力するだけで大丈夫です。 もし、g:proj_flagsに'm'が設定されていると、CTRL-W_oでもう一度表示させる ことができます。 4. プロジェクトにファイルを足す簡単な方法があります。 普通に、プロジェクトエントリ内にファイルを挿入、記述してください。 5. quickfixがファイルを読み込む際、ファイルの変更が適用されない時があるれど、 \Lを押す事でファイルが再帰的に読み込み直されます。 6. 再帰的に全て折りたたみたい際にはzMが利用できます。 7. 上級者向け、 function Project_GetAllFnames()でプロジェクトのファイル名 をサブプロジェクトを含めて取得できます。他にも、Project_ForEach()、 Project_GetFname(line_number)などがあります。 8. :Projectを\Pで実行する以下の設定をvimrcに記述すると便利です。 このコマンドでカレントディレクトリの.vimprojectsを読み込みます。 > nmap <silent> <Leader>P :Project<CR> < 9. .エントリが消えないようにしてプロジェクト内に置きたい場合、 コメントとして > . # pragma keep < のように記述します。 以上
project.txtの原文
*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:
