*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: <leader>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".

<Leader>vv  - Grep for the word under the cursor, match all occurences,
              like 'g*'.  See ":help gstar".
<Leader>vV  - Grep for the word under the cursor, match whole word, like
              '*'.  See ":help star".
<Leader>va  - Like vv, but add to existing list.
<Leader>vA  - Like vV, but add to existing list.

<Leader>vr  - Perform a global search on the word under the cursor
              and prompt for a pattern with which to replace it.
<Leader>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 "/<word\>" will match
    against "\<word\>" 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:

<Leader>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 <Leader>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 <silent> (keycombination) <plug>(MappingName)
e.g.
    map <silent> ,op <plug>EgMapGrepOptions


==============================================================================
  Commands                                                 *EasyGrep_Commands*
==============================================================================

:Grep [arg]
    Search for the specified arg, like <Leader>vv.  When an ! is added,
    search like <Leader>vV

:GrepAdd [arg]
    Search for the specified arg, add to existing file list, as in
    <Leader>va.  When an ! is added, search like <Leader>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 <C>
     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, <Leader>vv
matches whole word, while <Leader>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='<leader>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
      <leader>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
