doc/EasyGrep.txt

*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:     1.1                                         |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|
                2.2 Performance............|EasyGrep_Performance|
             3. Keymaps....................|EasyGrep_Keymaps|
                3.1 Default Bindings ......|EasyGrep_KeymapsDefault|
                3.2 Option Mappings........|EasyGrep_KeymapsOptions|
                3.3 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|


==============================================================================
  1. 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!


==============================================================================
  2. Operation                                            *EasyGrep_Operation*
==============================================================================

EasyGrep makes using Vim's grep capabilities easier.  When using EasyGrep,
searching for a word in multiple files is as easy as typing a simple mapping
(see |EasyGrep_Keymaps)|.  In addition to keymaps, search and replace can be
invoked through commands (see |EasyGrep_Commands)|.

To determine which files to search, EasyGrep provides several builtinmodes,
described in the next section.

------------------------------------------------------------------------------
 2.1 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.


The startup mode is indicated by |EasyGrepMode|. These modes can be quickly
changed through the |EasyGrep_OptionsExplorer| or |EasyGrep_KeymapsOptions|.


------------------------------------------------------------------------------
 2.2 Performance                                         *EasyGrep_Performance*
------------------------------------------------------------------------------

By default, EasyGrep completes its searches using Vim's vimgrep command. While
easy to use, vimgrep's searching time can be considerably longer than
traditional tools like your system's grep command. Because of this, EasyGrep
provides several options to allow you to control your performance:

- Consider setting EasyGrep to use your system's grep command.
  (see |EasyGrepCommand|)
- Consider whether recursive operation is set and whether you need it on all
  the time. Note that it can be toggled easily with '<leader>vyr'.
  (see |EasyGrepRecursive|)
- Consider setting grep exclusions if your grep command supports it.
  (see |EasyGrepFilesToExclude|)


==============================================================================
  3. Keymaps                                                *EasyGrep_Keymaps*
==============================================================================

This section discusses EasyGrep's default keybindings and how to customize
them.

------------------------------------------------------------------------------
 3.1 Default Bindings                                *EasyGrep_KeymapsDefault*
------------------------------------------------------------------------------

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|.


------------------------------------------------------------------------------
 3.2 Option Mappings                                 *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 mapping for option is
<Leader>vy<option>, where <option> is the character listed in the options
window for each of the options.

    e.g. To change to buffers mode, type '\vyb'
    e.g. To toggle recursive search, type '\vyr'

See |EasyGrepOptionPrefix| to change the prefix from '\vy' or to turn these
keymappings off.


------------------------------------------------------------------------------
 3.3 Mapping Customization                     *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


==============================================================================
  4. Commands                                              *EasyGrep_Commands*
==============================================================================

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

                                                                    *:GrepAdd*
: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 that override
    the configured settings:
    -r   Perform a recursive search
    -R   Perform a recursive search
    -i   Perform a case-insensitive search
    -I   Perform a case-sensitive search
    -m   Specify the number of matches to get

                                                                    *:Replace*
: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*
: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.

                                                                *:GrepOptions*
: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'").

                                                            *:ResultListFilter*
:ResultListFilter [args]
    Removes entries from the error list according to whether or not they match
    a set of specified patterns.  The default behaviour is to save all entries
    that match one of the patterns and remove those that do not.

    The Above command can additionally accept command switches:
    -v   Switch the criteria for matching; remove entries matching one of the
         specified patterns instead of saving them

                                                             *:ResultListOpen*
:ResultListOpen
    Opens all of the entries in the current result list in a new tab.


==============================================================================
  5. Options                                                *EasyGrep_Options*
==============================================================================

------------------------------------------------------------------------------
 5.1 Options Summary                                 *EasyGrep_OptionsSummary*
------------------------------------------------------------------------------

 Option                               Description
`````````````````````````````````   ````````````````````````````````````````
o |EasyGrepFileAssociations|            - Specifies the location of the EasyGrep
                                        file associations
o |EasyGrepMode|                        - Mode of operation
o |EasyGrepCommand|                     - Whether to use vimgrep or grepprg
o |EasyGrepRecursive|                   - Recursive searching
o |EasyGrepIgnoreCase|                  - Case-sensitivity in searches
o |EasyGrepHidden|                      - Include hidden files in searches
o |EasyGrepFilesToExclude|              - Comma-separated list of files patterns
                                        that will be excluded from the search
o |EasyGrepAllOptionsInExplorer|        - How many options to show in the explorer
o |EasyGrepWindow|                      - Quickfix or location list
o |EasyGrepWindowPosition|              - Where the error list window is opened
o |EasyGrepOpenWindowOnMatch|           - Open grep window on successful match
o |EasyGrepEveryMatch|                  - Match multiple times per line
o |EasyGrepJumpToMatch|                 - Jump to first match
o |EasyGrepSearchCurrentBufferDir|      - Whether to search current buffers dir
                                        in addition to working dir
o |EasyGrepInvertWholeWord|             - Invert the meaning of whole word for vv
                                        and vV keymaps
o |EasyGrepFileAssociationsInExplorer|  - Whether to show the file associations
                                        list in the options explorer
o |EasyGrepReplaceWindowMode|           - Controls whether to use tabs or splits
                                        when replacing in files
o |EasyGrepReplaceAllPerFile|           - Replace on per file or global basis
o |EasyGrepOptionPrefix|                - Specify the keymap for toggling options
o |EasyGrepExtraWarnings|               - Whether to show extra warnings
o |EasyGrepDefaultUserPattern|          - The default 'User' mode pattern


------------------------------------------------------------------------------
 5.2 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.


------------------------------------------------------------------------------
 5.3 Options Details                                 *EasyGrep_OptionsDetail*
------------------------------------------------------------------------------

*EasyGrepFileAssociations*
[default=&runtimepath/plugin/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*  [default=0]
Specifies the mode in which to start.
0 - All files
1 - Open Buffers
2 - Track the current extension
3 - User mode -- Use a custom, on demand set of extensions

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*  [default=0]
Specifies the grep command to use.

0 - vimgrep
1 - grep (follows grepprg)

When the grep command is set to vimgrep, Vim's builtin |:vimgrep| command will
be used.
When the grep command is set to , Vim's builtin |:grep| command will be used.
This command inspects the 'grepprg' variable to determine the external tool
that will be used for the search. Note that an external tool is often faster
to search than vimgrep (see |EasyGrep_Performance|).

*EasyGrepRecursive*  [default=0]
Specifies that recursive search be activated on start.

*EasyGrepIgnoreCase*  [default=&ignorecase]
Specifies the case sensitivity of searches.  Note that this can be further
overrided for vimgrep searches with \c and \C.

*EasyGrepHidden*  [default=0]
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.

*EasyGrepFilesToExclude*  [default=""]
Specifies a list of file patterns that will be excluded from the search.
Multiple exclusions must be separated by commas. Note that these patterns will
be passed unmodified on to the search program.

Currently only supported when EasyGrepCommand=1 and your grepprg is "grep" or
"ack".

*EasyGrepAllOptionsInExplorer*  [default=0]
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*  [default=0]
Specifies the window to use for matches.
0 - quickfix
1 - location list

*EasyGrepWindowPosition*  [default=""]
Specifies where the error list window is opened.  If empty, the default
behavior for Vim's error list opening commands will be used. If not empty, the
value of this option must match one of Vim's splitting positional window
commands, such as topleft or botright.

*EasyGrepOpenWindowOnMatch*  [default=1]
Specifies whether to open the with matches after a search.

*EasyGrepEveryMatch*  [default=0]
Specifies that multiple matches on the same line be treated as different
matches, like the g option to vimgrep.

*EasyGrepJumpToMatch*  [default=1]
Specifies that jump to first match be activated, like the j option to vimgrep.

*EasyGrepSearchCurrentBufferDir*  [default=1]
Setting this option causes EasyGrep to search not only the current directory,
but also the directories for all buffers currently opened.

*EasyGrepInvertWholeWord*  [default=0]
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*  [default=0]
Specifies whether to show the file associations list in the options explorer
window.

*EasyGrepOptionPrefix*  [default=<leader>vy]
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'      (where ',oe' is your custom prefix)
None:
    let g:EasyGrepOptionPrefix=''         (this disables all mappings)

*EasyGrepReplaceWindowMode*  [default=0]
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*  [default=0]
Specifies that selecting 'a' (for all) will apply the replacements on a per
file basis, as opposed to globally as is the default.

*EasyGrepExtraWarnings*  [default=1]
Specifies that warnings be issued for conditions that may be valid but have
the potential to confuse some users.

*EasyGrepDefaultUserPattern*  [default=""]
Specifies the default pattern for 'User' mode. (see |EasyGrepMode| and
|EasyGrep_OperationModes|).  This pattern must be defined and non-empty if
|EasyGrepMode| is set to start in 'User' mode.


==============================================================================
  6. Future                                                  *EasyGrep_Future*
==============================================================================

------------------------------------------------------------------------------
set file/directory inclusions.
create capability to include paths other than the active directories in a
search.  e.g.  ../../include, $INCLUDE, etc.
------------------------------------------------------------------------------
set file/directory exclusions.
This is currently supported with grepprg=grep or grepprg=ack but not with vimgrep.
------------------------------------------------------------------------------
Provide recommendations on the best way to use the script
------------------------------------------------------------------------------
Implement ResultListDo
------------------------------------------------------------------------------

==============================================================================
  7. Bugs                                                      *EasyGrep_Bugs*
==============================================================================

If you discover any bugs not listed here, please contact the |EasyGrep_Author|

------------------------------------------------------------------------------
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
------------------------------------------------------------------------------
Patterns with backslashes in them require double-backslash to be searched from
the command line.  This behaviour matches the builtin / command but it may be
unintuitive.
------------------------------------------------------------------------------
Support canceling a search and print a nice message
------------------------------------------------------------------------------


==============================================================================
  8. History                                                *EasyGrep_History*
==============================================================================

  1.1
      Improved: much better support when grepprg is ack or grep. These tools
          can search much more quickly than vimgrep and so may be preferable
          to some users.
      Feature: added a mapping to echo the command that EasyGrep will issue
          (see 'v' in the options explorer)
      Feature: Added keymap toggle for EasyGrepSearchCurrentBufferDir
      Fixed: command line parsing of Grep command discarded spaces
      Feature: added support for grep exclusions when grepprg is grep or ack
      Feature: Added EasyGrepDefaultUserPattern option.
          Thanks to Jesus Barcons for the suggestion.
      Improved: Cleaned up the documentation
      Improved: Cleaned up the internals of the script substantially
      Improved: Formalized multi-select mode, which is when multiple file
          extensions are selected from the options explorer
      Improved: lots of misc fixes
  1.0
      Documentation: Added a help tag for each of the commands so that you can
          look up more information on them.
      Improved: Cleaned up the internals of the script substantially
      Improved: Changed the name of FilterErrorList to ResultListFilter
      Feature: Added ResultListOpen command to open all of the files in the
          result list (aka error list)
      Fixed: Added -- to signify the end of the command line options. Grepping
          for patterns such as '->var' are now possible with ':Grep -- ->var'
  0.98
      Highlight: The Replace and ReplaceUndo commands were reimplemented.  The
          granularity of matches inside of a Replace call were improved so that
          you can now decide replacements individually per line.
          Additionally, Complex operations such as replacing x[i][j][k] with
          x(i,j,k) and following it up with a ReplaceUndo are now possible.

          e.g.
          :Replace /x\[\([^]]\+\)\]\[\([^]]\+\)\]\[\([^]]\+\)\]/x(\1,\2,\3)/
          :ReplaceUndo

          Please report any regressions with either of these functions.

      Feature: Added count command line option (-m 4 or -4)
      Feature: Improved Grep options window keybindings; searching within the
          options explorer window is now possible
      Feature: Expanded searches to include all of the active buffers'
          directories
      Bugfix:  Fixed recursive operation and expanded search from reporting
          duplicate results
      Bugfix:  Fixed <C-e> and <C-y> in replace mode
      Feature: Added EasyGrepWindowPosition for specifying where the error
          list window will be opened
      Feature: Added FilterErrorlist command for filtering the results within
          the quickfix or location list windows
      Feature: Improved printout when no matches are found
      Feature: Improved searching when an entire line is selected
  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


==============================================================================
  9. 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