This plugin provides a nice interface for navigating code built on top of Ctags.
Surfer requires Vim 7.3+ compiled with Python 2.x support (2.6+).
First, you need to get Exuberant Ctags (You can check if it is
already installed on your system with $ ctags --version.
)
Windows
You can easily get the ctags.exe
executable from the Exuberant Ctags
site. Download and extract the ctags.exe
executable in a folder within your %PATH%
.
OS X
Unfortunately, the Ctags program that you may find under /usr/bin
is outdated, so you need to
get the right version. The easiest way to do that is with homebrew
$ brew install ctags
Debian, Ubuntu, Mint, etc
$ sudo apt-get install exuberant-ctags
Red Hat, Fedora, CentOS, etc
$ sudo yum install ctags
Install the plugin with Vundle
# this line needs to be added to your .vimrc file
Bundle "gcmt/surfer.vim"
or Pathogen
$ cd ~/.vim/bundle
$ git clone git://github.com/gcmt/surfer.vim.git
Now, if you are a OS X or Linux user, to complete the installation go to the plugin root directory and run
$ ./install.sh
This will compile some files needed for better search performances.
Usually Surfer is able to locate the correct Ctags program by himself, but if this is not the
case, add the following line in your .vimrc
:
let g:surfer_ctags_prg = "/path/to/ctags"
To open Surfer execute the :Surf
command. As you type something, Surfer will show you a list of
tags in the current session that match your query. You can interact with search results with the
following keys.
UP
,TAB
,CTRL+K
: move up.DOWN
,CTRL+J
: move down.RETURN
,CTRL+O
,CTRL+G
: jump to the selected tag.CTRL+P
: open a preview window for the selected tag.CTRL+S
: split the window for the selected tag.ESC
,CTRL+C
: close Surfer.CTRL+U
: clear the current search.
Rememberer that when you jump to a tag you can easily jump back to the previous position with
CTRL+T
, as you would normally do in Vim.
Searches are not limited to the current session. You can narrow or widen the search scope using modifiers. A modifier is simply a special letter that you prepend to your search query. Below is list of all available modifiers:
%
: this modifier narrows the search scope to the current buffer.#
: this modifier widens the search scope to all files of the current project. Note that a project root is assumed to be the one that contains any of the file or directory names listed ing:surfer_root_markers
.
Note that project-wide search is still very inefficient and has to be considered still an experimental feature.
With this option you can set the path of the Ctags executable on your system. You usually need to do this only if Surfer is not able to locate the Ctags executable by himself.
Default: ""
This option controls the way matching works. When this option is turned on, a search is case-insensitive only if you enter the search string in all lower case letters.
Default: 1
With this option tou can set glob patterns that are used to exclude files and directories from search results.
Example:
let g:surfer_exclude = ["*/[Dd]oc?/*", "*/[Tt]est?/*"]
Default: []
With this option you can exclude kinds from search results. To get a list of the kinds that Ctags is able to recognize per language, execute
$ ctags --list-kinds
Note that this option apply only to languages recognized by Exuberant Ctags.
Default: []
With this option you can set file and directory names that are used to locate the root of the current project.
Note that when you assign a list to g:surfer_root_markers
the default markers won't be replaced
but just extended.
Default: ['.git', '.svn', '.hg', '.bzr', '.travis.yml']
With this option you can add support for languages not supported by Exuberant Ctags. See the dedicated section in the documentation to see how to set this option.
Default: {}
This option controls the maximum number of search results displayed.
Default: 15
With this option you can set the cahracter/s used by Surfer to indicate the currently selected tag.
Default: " "
This options controls the format of search results. This option is a list of strings and each one can contain at most one special placeholder that will be substituted with the corresponding value. When the value is absent, the whole list item won't displayed. Available placeholders vary across different languages but common placeholders include:
{file}
: the file in which the tag is defined.{line}
: the line of the tag in{file}
.{kind}
: the kind of the tag.{class}
: the name of the class for which the tag is a member or method.{language}
: the language of the file in which tags is defined.
Example:
let g:surfer_line_format = ["{file}", " ({line})", " class: {class}"]
Default: [" @ {file}"]
This option controls how the value for the placeholder {file}
is formatted. If the value is
greater than zero, the value represent the maximum number of container directories displayed in the
file path.
Default: -1
When this option is turned on, the value of the placeholder {file}
is displayed relative to the
project root, if a root exists. This option ovverride g:surfer_tag_file_custom_depth
when
a project root is found.
Default: 1
With this option you can set the color everything except the tag name and the current line indicator. As value, you can use either a predefined color group or a complete color definition. Set this option to an empty string if you want no color.
Examples:
# example 1
let g:surfer_shade_color = "String"
# example 2
let g:surfer_shade_color = "guifg=#cccccc guibg=#000000"
Default: 'Comment'
With this option you can set the color for matching letters in tag names. As value, you can use either a predefined color group or a complete color definition. Set this option to an empty string if you want no color.
Examples:
# example 1
let g:surfer_matches_color = "WarningMsg"
# example 2
let g:surfer_matches_color = "guifg=#ff0000"
Default: 'WarningMsg'
With this option you can customize the prompt appearance.
Default: " @ "
This option controls the color of the Surfer prompt. As value, you can use either a predefined color group or a complete color definition. Set this option to an empty string if you want no color.
Examples
# example 1
let g:surfer_prompt_color = "String"
# example 2
let g:surfer_prompt_color = "guifg=#ff00ff"
Default: ""
When this option is turned on, a colored square (or anything you set with g:surfer_visual_kinds_shape
)
is displayed before each tag name to indicate the kind of the tag.
Default: 1
With this option you can set a custom character to be used when the option g:surfer_visual_kinds
is turned on.
Default: "\uFFED"
With this option you can customize the color of g:surfer_visual_kinds_shape
for each kind when the
option g:surfer_visual_kinds
is turned on. (to get a list of what kinds can be recognized by Ctags
execute $ctags --list-kinds
). As value, you can use either a predefined color group or a complete
color definition.
Note that when you want to change these colors you need to assign to g:surfer_visual_kinds_colors
a dictionary with just the kinds you want to update or add.
Default:
{
"interface": "Repeat",
"class": "Repeat",
"member": "Function",
"method": "Function",
"function": "Function",
"type": "Type",
"variable": "Conditional",
"constant": "Conditional",
"field": "String",
"property": "String"
}
Exuberant Ctags only supports a limited set of languages ($ ctags --list-languages
).
If you want to add support for a new language there are mainly two methods for doing this.
The first method relies directly on Ctags and its extending capabilities. It just requires you to
add some lines to the file $HOME/.ctags
and you are done. If you search the web you'll certainly
find what you need for your language.
Check this link for further information about how to integrate custom languages in Exuberant Ctags.
If you want to rely on an external Ctags-compatible tag generator for your language, Surfer
provides the g:surfer_custom_languages
option to do this. Setting this option is better explained
with an example.
With the following example we are going to add support for the Go language with the help of gotags, a ctags-compatible tag generator for Go.
let g:surfer_custom_languages = {
\ "go": {
\ "ctags_prg": "/usr/local/bin/gotags",
\ "ctags_args": "-silent -sort",
\ "kinds_map": {
\ 'p': 'package', 'i': 'import', 'c': 'constant', 'v': 'variable',
\ 't': 'type', 'n': 'interface', 'w': 'field','e': 'embedded',
\ 'm': 'method', 'r': 'constructor', 'f': 'function'},
\ "exclude_kinds": ["variable", "constant"],
\ "extensions": [".go"]
\ },
\ }
As you can see from the example above, adding support for a custom language requires you to use a unique filetype name, along with other mandatory information, such as the executable of the Ctags-compatible tag generator, its arguments and the extensions of the files for which you want to use the specified tag generator.
With the ctags_prg
and ctags_args
keys you can set the path of custom Ctags program and its
arguments respectively. In order to make things work you have to be sure that the output of the
custom Ctags-compatible program is will be sorted and redirected to stdout, so you may
need to set the arguments accordingly.
Setting the extensions key is paramount. This is a list of file extensions used for the files for which you to used the custom Ctags program.
With the exclude_kinds
key you can set exclusion rules based on the kind of the tag. For example,
the code above will exclude all tags with the kind constant
or variable
from search results for
tags generated with the custom Ctags program. Note that this override the global option
g:surfer_exclude_kinds
.
Setting the kinds_map
key may be required when your custom Ctags prgram displays only single
letters for the kind field and you want more readable names.
Do not esitate to send patches, suggestion or just to ask questions! There is always room for improvement.
See this page for all Surfer contributors.