dissimulo/drunkendotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit.

Browse Source
This commit is contained in:
yan
2011-11-17 15:45:33 -06:00
commit 882015bc6d
1819 changed files with 111625 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

547
vim/doc/EasyGrep.txt Normal file
View File

@@ -0,0 +1,547 @@
*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