*EasyGrep.txt* ============================================================================== EasyGrep *EasyGrep* ============================================================================== Author: Dan Price vim@danprice.fastmail.net *EasyGrep_Author* Goal: To be an easy to use, powerful find and |EasyGrep_Motivation| replace tool for users of all skill levels. Version: 0.96 |EasyGrep_History| License: Public domain, no restrictions whatsoever |EasyGrep_License| Contribute: Please report any bugs or suggestions |EasyGrep_Bugs| to the address above. |EasyGrep_Future| ============================================================================== Table of Contents *EasyGrep_Contents* ============================================================================== 1. Motivation.................|EasyGrep_Motivation| 2. Operation..................|EasyGrep_Operation| 2.1 Modes..................|EasyGrep_OperationModes| 3. Keymaps....................|EasyGrep_Keymaps| 3.1 Option Mappings........|EasyGrep_KeymapsOptions| 3.2 Mapping Customization..|EasyGrep_KeymapsCustomization| 4. Commands...................|EasyGrep_Commands| 5. Options....................|EasyGrep_Options| 5.1 Summary...............|EasyGrep_OptionsSummary| 5.2 Explorer..............|EasyGrep_OptionsExplorer| 5.3 Details...............|EasyGrep_OptionsDetail| 6. Bugs.......................|EasyGrep_Bugs| 7. Future.....................|EasyGrep_Future| 8. History....................|EasyGrep_History| 9. License....................|EasyGrep_License| ============================================================================== Motivation *EasyGrep_Motivation* ============================================================================== EasyGrep's main goal is to make search and replace in files easy. Other Vim plugins provide similar functionality, but few provide the same level of functionality with as little configuration as EasyGrep does. In the common case, all it takes to search for a string across multiple files is three keypresses: vv. No clicks, no commands, no project/tags setup -- just three keys. When you need a substitution, it also takes the same number of keys to start a replace in files. After using EasyGrep, you'll wonder at how you got around without it. While EasyGrep's default configuration will satisfy many users, it provides more than a dozen options for those who need more control |EasyGrep_Options|. When you need to change options, EasyGrep provides an options explorer that indicates which files will be searched and allows visual customization of its options |EasyGrep_OptionsExplorer|. When this isn't fast enough, EasyGrep provides key mappings for each option to toggle its value |EasyGrep_KeymapsOptions|. If you can't find an option you need, contact me |EasyGrep_Author| and if it doesn't already exist, we'll make it happen. I hope that EasyGrep makes Vim more fun, productive, and easy for you to use. Happy Vimming! ============================================================================== Operation *EasyGrep_Operation* ============================================================================== EasyGrep makes using Vim's grep capabilities easier. When using EasyGrep, searching for a word is as easy as typing a three keypress mapping |EasyGrep_Keymaps|. In addition to keymaps, search and replace can be invoked through commands |EasyGrep_Commands|. To determine which files to search, EasyGrep provides three modes, described in the next section. Search Modes |EasyGrep_OperationModes| All All files will be searched (default). Buffers Files currently open in vim will be searched. Recursion has no meaning in this mode, and will be turned off. TrackExt Files that match the extension of the currently opened file will be searched. Additionally, this extension can be mapped to a user defined set of extensions that will also be searched |EasyGrepFileAssociations|. For example: in the default configuration, when test.cpp is open, files that match any one of *.cpp *.hpp *.cxx *.hxx *.cc *.c *.h will be searched when a Grep is initiated. I find this mode to be the most useful. User Specify a custom set of file extensions to search. These modes can be quickly changed through the |EasyGrep_OptionsExplorer| or |EasyGrep_KeymapsOptions|. ============================================================================== Keymaps *EasyGrep_Keymaps* ============================================================================== EasyGrep uses Vim's leader key, which is by default '\'. For information on this key, type ":help mapleader". vv - Grep for the word under the cursor, match all occurences, like 'g*'. See ":help gstar". vV - Grep for the word under the cursor, match whole word, like '*'. See ":help star". va - Like vv, but add to existing list. vA - Like vV, but add to existing list. vr - Perform a global search on the word under the cursor and prompt for a pattern with which to replace it. vR - Like vr, but match whole word. Each of these commands has an 'all occurences' and 'whole word' option, designated by the case of the last character. If you would prefer that these be reversed, see |EasyGrepInvertWholeWord|. In addition to grepping the word under the cursor, text may be visually selected and these mappings may be used analogously to as they are used above. Visual selections will automatically be escaped so as not to confuse the selection with a regular expression. e.g. Selecting the text inside the quotes here "/" will match against "\" but not against "word". To search with a regular expression, see the :Grep command |EasyGrep_Commands| Each of the above commands will search files according to settings controlled by: vo - Open an options explorer to select the files to search in and set grep options. For the options provided, see |EasyGrep_Options|. *EasyGrep_KeymapsOptions* For each of the options presented in the options explorer, there is a mapping that allows a direct change of this option. The pattern is vy* , where star is the value listed in the options window for each of the options. e.g. To toggle recursive mode, type '\vyr' See |EasyGrepOptionPrefix| to change the prefix from '\vy' or to turn these keymappings off. *EasyGrep_KeymapsCustomization* Beyond EasyGrepOptionPrefix, other keymaps may be remapped to your liking. See the "Keymaps" section of EasyGrep.vim for the names of these items. Mappings take the form: map (keycombination) (MappingName) e.g. map ,op EgMapGrepOptions ============================================================================== Commands *EasyGrep_Commands* ============================================================================== :Grep [arg] Search for the specified arg, like vv. When an ! is added, search like vV :GrepAdd [arg] Search for the specified arg, add to existing file list, as in va. When an ! is added, search like vA The Above commands can additionally accept command switches: -r Perform a recursive search -R Perform a recursive search -i Perform a case-insensitive search -I Perform a case-sensitive search :Replace [target] [replacement] :Replace /[target]/[replacement]/ Perform a global search and replace. The function searches the same set of files a grep for the desired target and opens a dialog to confirm replacement. In the second, forward slash delineated form, back and forward slashes must be explicitly escaped. :ReplaceUndo Undoes the last :Replace operation. Does not stack successive searches; only the last replace may be undone. This function may not work well when edits are made between a call to Replace and a call to ReplaceUndo. Note: currently implemented ReplaceUndo will fail to restore replacements that make use of backreferences.|EasyGrep_Bugs| :GrepOptions Open the options explorer to set options. For each of the search and replace commands, searching with regular expressions is supported. Note that regular expressions are handled as indicated by the 'magic' option (see ":help 'magic'"). ============================================================================== Options *EasyGrep_Options* ============================================================================== Options Summary *EasyGrep_OptionsSummary* Option Description ------------------------------------------------------------------------------ |EasyGrepFileAssociations| Specifies the location of the EasyGrep file associations ------------------------------------------------------------------------------ |EasyGrepMode| Mode of operation ------------------------------------------------------------------------------ |EasyGrepCommand| Whether to use vimgrep or grepprg ------------------------------------------------------------------------------ |EasyGrepRecursive| Recursive searching ------------------------------------------------------------------------------ |EasyGrepIgnoreCase| Case-sensitivity in searches ------------------------------------------------------------------------------ |EasyGrepHidden| Include hidden files in searches ------------------------------------------------------------------------------ |EasyGrepAllOptionsInExplorer| How many options to show in the explorer ------------------------------------------------------------------------------ |EasyGrepWindow| Quickfix or location list ------------------------------------------------------------------------------ |EasyGrepOpenWindowOnMatch| Open grep window on successful match ------------------------------------------------------------------------------ |EasyGrepEveryMatch| Match multiple times per line ------------------------------------------------------------------------------ |EasyGrepJumpToMatch| Jump to first match ------------------------------------------------------------------------------ |EasyGrepSearchCurrentBufferDir| Whether to search current buffers dir in addition to working dir ------------------------------------------------------------------------------ |EasyGrepInvertWholeWord| Invert the meaning of whole word for vv and vV keymaps ------------------------------------------------------------------------------ |EasyGrepFileAssociationsInExplorer| Whether to show the file associations list in the options explorer ------------------------------------------------------------------------------ |EasyGrepReplaceWindowMode| Controls whether to use tabs or splits when replacing in files ------------------------------------------------------------------------------ |EasyGrepReplaceAllPerFile| Replace on per file or global basis ------------------------------------------------------------------------------ |EasyGrepOptionPrefix| Specify the keymap for toggling options ------------------------------------------------------------------------------ |EasyGrepExtraWarnings| Whether to show extra warnings ------------------------------------------------------------------------------ Options Explorer *EasyGrep_OptionsExplorer* To invoke the options explorer, type '\vo' (default). The options explorer presents all of EasyGrep's customizable options and provides information on the file patterns that will be searched when invoking a Grep. A useful exercise for beginners is to toggle between EasyGrep's options and modes (|EasyGrep_OperationModes|) and type 'e' to see which files will be searched for a given configuration. Options Details *EasyGrep_OptionsDetail* *EasyGrepFileAssociations* Specifies the location of a file that contains groups of files that should be associated with one another. When set to an empty string "", no file read will be attempted. This file has a simple syntax used to logically link different files types. A simple configuration is shown below: C=*.c *.h C++=*.cpp *.hpp *.cxx *.hxx *.cc VHDL=*.hdl *.vhd *.vhdl *.vbe *.vst Web=*.htm *.html *.js For example, in this configuration, whenever the active file has the .c extension, files with the .h extension will also be search. A special feature of this syntax is the ability to link groups together. For example, the C++ group links to all files that are in the C group. *EasyGrepMode* Specifies the mode in which to start. 0 - All files 1 - Open Buffers 2 - Track the current extension Note: I find option 2 to be the most powerful, but option 0 is activated by default because it is the most intuitive for users who haven't take the time to understand how the script works. See |EasyGrep_OperationModes|. *EasyGrepCommand* Specifies the grep command to use. 0 - vimgrep 1 - grep (follows grepprg) *EasyGrepRecursive* Specifies that recursive search be activated on start. *EasyGrepIgnoreCase* Specifies the case sensitivity of searches. Note that this can be further overrided for vimgrep searches with \c and \C. *EasyGrepHidden* Specifies that hidden files search be activated on start. Note that hidden implies the unix meaning of those files that are prepended with a '.', and not the Windows meaning of those files with a hidden attribute. *EasyGrepAllOptionsInExplorer* Specifies that all options be included in the explorer window. Note: settting this option is very useful when you want to try out and learn all of the options available in this script. *EasyGrepWindow* Specifies the window to use for matches. 0 - quickfix 1 - location list *EasyGrepOpenWindowOnMatch* Specifies whether to open the with matches after a search. *EasyGrepEveryMatch* Specifies that multiple matches on the same line be treated as different matches, like the g option to vimgrep. *EasyGrepJumpToMatch* Specifies that jump to first match be activated, like the j option to vimgrep. *EasyGrepSearchCurrentBufferDir* Setting this option causes EasyGrep to search the current buffer's directory in addition to the current working directory. *EasyGrepInvertWholeWord* Specifies that the whole word search keys should be inverted from their default meaning. For example, when this option is activated, vv matches whole word, while vV matches everything that includes the word. Note that this affects both keymappings and commands. *EasyGrepFileAssociationsInExplorer* Specifies whether to show the file associations list in the options explorer window. *EasyGrepOptionPrefix* Specifies the prefix that is used when building keymaps for setting options directly. To specify that no option keymaps be created, set this to the empty string. Default: let g:EasyGrepOptionPrefix='vy' Custom: let g:EasyGrepOptionPrefix=',oe' None: let g:EasyGrepOptionPrefix='' *EasyGrepReplaceWindowMode* Specifies the mode that the script will use when a buffer needs to be changed while performing a global replace. 0 - Open a new tab for each window 1 - Perform a split of the current window with the next window 2 - autowriteall; create no new windows Note: Option 1 has the possibility of running out of vertical space to split more windows. Actions are taken to make this a non-issue, but this option can often be more clunky than other options. Note: As a result of the limitation above, option 0 is the only mode that won't require saving the files during a replace. *EasyGrepReplaceAllPerFile* Specifies that selecting 'a' (for all) will apply the replacements on a per file basis, as opposed to globally as is the default. *EasyGrepExtraWarnings* Specifies that warnings be issued for conditions that may be valid but confuse some users. ============================================================================== Future *EasyGrep_Future* ============================================================================== ------------------------------------------------------------------------------ Show search progress? ------------------------------------------------------------------------------ Allow entries in the file associations list to be regular expressions ------------------------------------------------------------------------------ Idea: create capability to include paths other than the active directory (and below) in a search. e.g. ../../include, $INCLUDE, etc. ------------------------------------------------------------------------------ Idea: set file/directory exclusions ------------------------------------------------------------------------------ ============================================================================== Bugs *EasyGrep_Bugs* ============================================================================== If you discover any bugs not listed here, please contact the |EasyGrep_Author| ------------------------------------------------------------------------------ ReplaceUndo can't correctly restore replacements that use numbered sub-expressions ------------------------------------------------------------------------------ ReplaceUndo can't currently replace the text accurately in all cases if case insensitivity is turned on ------------------------------------------------------------------------------ Increase the granularity of the match inside of a Replace call so that you can individually decide per line ------------------------------------------------------------------------------ Cursorline doesn't always follow to the line at which the replacement is going to happen ------------------------------------------------------------------------------ Successive warning messages can hide a previous message ------------------------------------------------------------------------------ ReplaceUndo opens a window even if it is already open? ------------------------------------------------------------------------------ Report that a swap file can't be opened ------------------------------------------------------------------------------ Don't warn when the current file will actually be searched because recursion is on and it is below the current directory ------------------------------------------------------------------------------ ============================================================================== History *EasyGrep_History* ============================================================================== 0.96 Feature: Expanded upon the list of file associations Feature: Expanded searches to the current buffer's directory in addition to the current working directory Feature: Added command line arguments to :Grep and :Replace for recursive searches and case sensitivity Feature: Added toggle for window replace mode Feature: Added toggle for showing file associations list in options explorer Bugfix: Case insensitivity would fail in replacing some patterns 0.95 Feature: Added search and replace on visual selections Feature: Improved Grepping for items that can be interpreted as regular expressions. Selections are assumed to be literal, whereas explicit commands are assumed to be regular expressions. Feature: Removed option g:EasyGrepNoDirectMappings in favor of g:EasyGrepOptionPrefix, which allows the option prefix to be changed. Bugfix: The tracked extension would sometimes fail to be updated when switching between buffers Documentation: Split the documentation into its own file; greatly expanded upon its contents Change: Activating a mode that is already activated will no longer deactivate it Change: GrepOptions no longer accepts an argument; use user mode instead Change: Clarified mapping names; custom mappings will need to be reset. 0.9 Feature: Added forward slash delineated pattern to the Replace command e.g. :Replace /target/replacement/ that allows more complicated replacements; you can now work with patterns that have spaces in them. Bugfix: If cursorline is off at the start of a replace, now ensuring that cursorline is turned off for all buffers, and not just the last one Bugfix: fixed an issue with an extra tab being opened during a replacement 0.8 Implemented case sensitivity that is independent of ignorecase, thanks to Doro Wu for contributing to this functionality Changed shortcut key for hidden files from 'i' to 'h' 0.7 Expanded search of EasyGrepFileAssociations list to every component of 'runtimepath'. This solves a starting message for those who placed EasyGrepFileAssociations in a location other than the first location in 'runtimepath'. 0.6 Fixed paths with spaces in them Folds will now be disabled where replacements are to be made Fixed an error with checking for extra warnings Better highlighting while replacing Recursive mode can no longer be activated when Buffers mode is activated 0.5 Fixed an issue with tracking the file extension where sometimes the desired extension wouldn't be registered. Better reporting when no files match. Now warning when searching from a working directory that doesn't match the current file's directory. Added g:EasyGrepExtraWarnings option. 0.4 Improved Replace and ReplaceUndo Added two configurable modes for how the windows operate when doing a global replace. Fixed an issue with linked filetypes. 0.3 Added experimental :Replace and :ReplaceUndo commands; keymapped vr for :Replace Improved response when no matches 0.2 Added option to toggle showing fewer or more options; showing fewer options by default. Added option '?' to print the current configuration and save it to a register. Now creating direct mappings by default; see g:EasyGrepNoDirectMappings to turn this off. 0.1 Initial version ============================================================================== License *EasyGrep_License* ============================================================================== Public domain, no restrictions whatsoever When writing EasyGrep, I wanted it to be free in the broadest sense. Of course, most (if not all) plugins for Vim are free, but I wanted mine to be freer still: I've released EasyGrep in the public domain. It took a lot of time and learning to get EasyGrep to work, and I want anyone to take advantage of my contribution. If you see some (or many) snippets of EasyGrep's code that you need, use it -- you don't need to ask me, think about any copyright, worry about violating a license, or even note that the code came from me, just use it. My only request is that if you are thinking of forking EasyGrep (or enhancing, as some authors claim to do), please contact me to let me know what you feel is lacking in EasyGrep, and I promise I'll be receptive to correcting these issues. ============================================================================== vim:tw=78:ts=4:ft=help:norl:fdm=marker