tomtom / trag_vim Goto Github PK

This plugin uses ad-hoc searches to find strings in files. For certain 
languages, it can also find variable/function/class definitions, 
function calls etc.

Other than |tags| or |cscope|, it doesn't build a database to speed up 
searches but always scans all files. It can make use of the following 
external tools in order to gain acceptable performance for medium-sized 
projects:

    - `git grep`
    - `ack` http://beyondgrep.com/
    - `ag` https://github.com/ggreer/the_silver_searcher
    - `sift` https://sift-tool.org/

The builtin vimscript-based version file scanner and also 
|vimgrep| are suitable for small projects. See |g:trag#grep_type| for 
available options.


Usage~

First, define which files belong to your project. See 
|g:trag#file_sources| for available sources. If the variable contains 
"vcs" and the current buffer is under control of a supported VCS, trag 
will scan the files in the VCS. Maybe your project's source files are 
already registered in your tags files, in which case those will be used.

Secondly, use |:Trag| to scan your project's files. You can restrict searches 
to certain "kinds" like only variable definitions or only function calls. See 
|trag-kinds| for details.

You can also type <Leader>r# to search for the word under cursor (see 
|g:trag_map_leader| and |TragInstallMap()| for details on maps). In 
supported filetypes, <Leader>rd will search for the definition of the 
word under cursor.

Currently the following filetypes are supported:

    - java
    - javascript
    - json
    - make
    - r
    - ruby
    - viki
    - vim

Run `:echo globpath(&rtp, 'ftplugin/*/trag.vim')` to get a full listing 
of supported filetypes.

NOTE: Some kinds are available only for a subset of known filetypes.

Default maps (see also |TragInstallMap()|):

    <Leader>rr ... Trag the word under cursor
    <Leader>rq ... Show |quickfix|list via |:Tragcw|
    <Leader>rl ... Show |location-list| via |:Traglw|
    <Leader>rf ... Edit a file from the files list, i.e. the list that would be 
                   used if no "--file_sources" argument were passed to 
                   |:Trag|
    <Leader>r<Leader>x ... The same as `:Trag -l -i=x -x=i <cword><cr>`
                   where x is a alphabetical letter that describes a kind in 
                   |g:trag_kinds| and <cword> is the word under cursor.
                   "-x=i" (exclude commented text) is only added if kind x is 
                   in |g:trag_kinds_ignored_comments|.


-----------------------------------------------------------------------
Install~

Edit the vba file and type: >

    :so %

See :help vimball for details. If you have difficulties or use vim 7.0, 
please make sure, you have the current version of vimball (vimscript 
#1502) installed.

This script requires tlib (vimscript #1863) to be installed.


-----------------------------------------------------------------------
                                                    *trag-kinds*
Kinds~

Certain commands take a "kind" as argument. A "kind" in the context of 
trag means a way how the expression is interpreted and (in the future) 
how the lines are scanned. The meaning of the letter is specific for a 
certain filetype. In general, the following list should serve as a 
common base:

    c ... class definitions
    d ... function/method definitions
    f ... function calls
    i ... ignored lines, comments etc.
    l ... variable definition
    m ... module definitions
    r ... variable assignment (e.g. "= WORD")
    u ... uses of word (ignore comments)
    w ... find as word
    x ... subclasses

    fuzzy ... use a typo-tolerant regexp
    todo  ... TODO markers etc.

EXPERIMENTAL: Kinds can be joined as comma-separated list (OR) of 
period-seprated list (CONTAIN). This may be unintuitive but that's the 
way it is. Order in CONTAIN-patterns matters, i.e. w.i doesn't make too 
much sense (a word that CONTAINs a comment, which could only be the word 
itself) but i.w does (a comment that CONTAINs a word, which is quite 
possible).

The available command-line options are documented in |:Trag|. These 
command-line options allow users to defined which lines should be matched.

Example:
    -i=l,r ...... a word either on the left OR right hand side of an 
                  assignment
    -x=i ........ match lines that are not comments
    -i=w -x=i ... word that is NOT contained in a comment

More examples:
    File contents: >
        #1 function Foo() {}
        #2 function FooBar() {}
        #3 let x = FooBar()
        #4 let x = Foo()
<
    :TRag Foo
    => Find "Foo": 1-4

    :TRag -i=w Foo
    => Find the __w__ords "Foo": 1, 4

    :TRag -i=d Foo
    => Find __d__efinitions of "Foo": 1, 2

    :TRag -i=d.w Foo
    => Find __d__efinitions of the __w__ord "Foo": 1

    :TRag -i=f Foo
    => Find (__f__unction) calls of "Foo": 3, 4

    :TRag -i=f.w Foo
    => Find (__f__unction) calls of the __w__ord "Foo": 4


Not every kind is defined for every filetype. Currenty, support for 
the following filetype(s) is somewhat above average:
    - ruby
    - vim

Use |:TRagDefKind| to define new kinds.

See |trag#Grep()| for details of how to use this.


-----------------------------------------------------------------------
Install~

To install the vimball, edit the vba file and type: >

    :so %

See :help vimball for details.

To install from github, please use
    1. git + a plugin loader like enable_vim, pathogen, vim-unbundle etc.
    2. a plugin manager like VAM, Vundle, NeoBundle, vim-plug etc.

The tlib_vim plugin is required:
https://github.com/tomtom/tlib_vim

Also available via git: http://github.com/tomtom/trag_vim




Dependencies:
  tlib (>= 1.23) :: http://github.com/tomtom/tlib_vim

License: GPLv3 or later