README

Scope-aware tag support for Vim, using extended tags file format

  3.  {tagname}		{TAB} {tagfile} {TAB} {tagaddress} {term} {field} ..

with a field that indicates tag scope as a line:column range

  scope:startline:startpos-endline:endpos

We can then figure out which tags are in scope at cursor position, and in what
range to search for other occurrences of a tag (blanking out nested scopes
where our tag scope is shadowed). By giving the scopes as line:column-ranges,
the handling of scopes can be mostly language-independent. For an introductory
blog post, see

  Scoped tags support for Javascript, in Vim
  http://libraryinstitute.wordpress.com/2011/09/16/scoped-tags-support-for-javascript-in-vim/

To generate scope-aware tags files, you'll need a scope-tracking parser for
your language; the parser also needs to be able to associate source location
information with scopes; not all parsers track scopes, and those that do might
throw away source locations when no parse errors are generated, or only have
location information for tokens, not source spans for language constructs; but
all compiler frontends and static analysis tools should track scope and source
location information in some form, so you might be able to generate scoped tags
with limited effort.

For Javascript, I'm currently using [estr tags](https://github.com/clausreinke/estr)
to generate the tags. There is also an [extended jsctags](https://github.com/clausreinke/doctorjs).
The former is based on esprima and likely to be easier to use, the latter is
based on narcissus/doctorjs.

If you do add scoped tags generation for other languages, please let me know.

scoped_tags.vim is an autoload file (instead of sourcing it manually, you can
put it in an autoload folder in your runtimepath). The main operations are

  " goto tag definition in scope
  map _] :call scoped_tags#GotoTagDefinition(expand("<cword>"))<cr>

  " preview tag definition in scope
  map _} :call scoped_tags#GotoTagDefinition(expand("<cword>"),1)<cr>

  " cycle forward/backward through tag occurrences in scope
  map _* :call scoped_tags#CycleTagOccurrence(expand("<cword>"),'')<cr>
  map _# :call scoped_tags#CycleTagOccurrence(expand("<cword>"),'b')<cr>

(you can map these functions yourself, or :call scoped_tags#DefaultKeyBindings()
to get the mappings above; such a key mapping should go in your .vimrc).