tagls

tagls is a language server based on gtags.

Why I wrote it?

Almost all modern editors have great support to LSP, but language servers based on semantic are not always reliable (for example, in dynamic languages like Python).

On the other hand, the good old gtags has more comprehensive (sometimes verbose, though) result, but it is not the first class citizen of modern editors and is usually poorly supported.

A language server based on gtags can give us the best of both worlds.

Usage

Install tagls by pip3 install tagls and register it in your code editor. For example, in coc.nvim:

  "languageserver": {
    "tagls": {
      "command": "python3",
      "args": ["-m", "tagls"],
      "filetypes": [
        "c",
        "cpp",
        "python"
      ],
      "initializationOptions": {
        // Add the following line if you only want tagls as a fallback (also see "Custom LSP methods" section)
        // "register_official_methods": []
        // Add the following line for LeaderF support (https://github.com/daquexian/tagls/issues/1)
        // "gtags_provider": "leaderf"
        // Add the following line for custom cache dir
        // "cache_dir": "/tmp/gtags"
      },
      "settings": {}
    }
  }

Or if you use Emacs lsp-mode:

  (lsp-register-client
   (make-lsp-client :new-connection
                    (lsp-stdio-connection '("python3" "-m" "tagls"))
                    :server-id 'tagls
                    :activation-fn (lsp-activate-on "c" "cpp" "python")
                    ;; provide initialization options:
                    ;;   :initialization-options '((cache_dir . "/tmp/gtags"))
                    ))

Custom LSP methods

Tagls provides custom LSP methods beginning with $tagls/, so if you want, you can keep tagls from registering official LSP methods and communicate with tagls only by these custom methods. For example, if you want to use tagls only when all other languages servers cannot give any results, you can set register_official_methods to [] (also see above section), and add the following lines in your .vimrc (also see the following "NOTE"):

function! CallbackForTagLS(kind, err, resp)
  if a:err != v:null || a:resp != v:true
    echohl WarningMsg | echom "[coc.nvim] " . kind . " not found by tagls" | echohl None
  else
    echom "[coc.nvim] use tagls as callback"
  endif
endfunction

function! CallbackForOfficalLSP(kind, err, resp)
  if a:err != v:null || a:resp != v:true
    " NOTE: Please use the latest coc.nvim so that `CocLocationsAsync` supports callback
    call CocLocationsAsync('tagls', '$tagls/textDocument/' . a:kind, {err, resp -> CallbackForTagLS(a:kind, err, resp)})
  endif
endfunction

function! GoToWithTagLSFallback(action, kind)
  call CocActionAsync(a:action, {err, resp -> CallbackForOfficalLSP(a:kind, err, resp)})
endfunction

nmap <silent> <leader>jd :call GoToWithTagLSFallback('jumpDefinition', 'definition')<cr>
nmap <silent> <leader>jf :call GoToWithTagLSFallback('jumpReferences', 'references')<cr>

Supported

initialize (auto create/update gtags tag files when opening a project in the editor)
textDocument/didSave (auto update gtags tag files when a file is updated)
textDocument/definition
textDocument/references
textDocument/documentSymbol
workspace/symbol
Per-feature configuration (e.g. disable every feature but "textDocument/references")
Custom LSP methods ("$tagls/textDocument/definition" and so on)
Integrate with LeaderF