*vim-lsp-cxx-highlight*  vim-lsp-cxx-highlight: vim lsp semantic highlighting

===============================================================================
Contents ~

  1. Introduction ........................ |vim-lsp-cxx-highlight-introduction|
  2. Usage and Configuration .. |vim-lsp-cxx-highlight-usage-and-configuration|
   1. Commands ............................... |vim-lsp-cxx-highlight-commands|
   2. Variables ............................. |vim-lsp-cxx-highlight-variables|
   3. Highlight Groups ............... |vim-lsp-cxx-highlight-highlight-groups|
    a. Preprocessor Skipped Regions .. |vim-lsp-cxx-highlight-hl-group-skipped|
    b. Semantic Highlighting Symbols . |vim-lsp-cxx-highlight-hl-group-symbols|
  3. Troubleshooting .................. |vim-lsp-cxx-highlight-troubleshooting|
  4. Adding support for more LSP clients .... |vim-lsp-cxx-highlight-extending|
  5. Public API ................................... |vim-lsp-cxx-highlight-api|
   1. |g:lsp_cxx_hl_loaded| ..................................................
   2. |lsp_cxx_hl#notify_json_rpc| ...........................................
   3. |lsp_cxx_hl#notify_skipped| ............................................
   4. |lsp_cxx_hl#notify_symbols| ............................................


===============================================================================

                                           *vim-lsp-cxx-highlight-introduction*
Introduction ~

vim-lsp-cxx-highlight is a vim plugin that provides C/C++/ObjC semantic 
highlighting using the language server protocol.

Language Server Protocol: https://www.langserver.org

cquery: https://github.com/cquery-project/cquery

ccls: https://github.com/MaskRay/ccls

===============================================================================

                                *vim-lsp-cxx-highlight-usage-and-configuration*
Usage ~

For information on how to get this plugin working with cquery/ccls see the
README.md file at the root of this plugin's directory. It can also be viewed
at github: https://github.com/jackguo380/vim-lsp-cxx-highlight

===============================================================================

                                               *vim-lsp-cxx-highlight-commands*
Commands ~

vim-lsp-cxx-highlight adds the following commands:

-------------------------------------------------------------------------------

                                                              *LspCxxHighlight*
:LspCxxHighlight

Redo highlighting for the current buffer. This only reapplies highlighting
using the locally cached data. There is currently no way to force the language
server to resend highlighting data.

This command can be used after modifying a highlight group to see the changes.

If you have to manually call this command because your buffer is not
highlighted or has stale highlight consider filing a issue on github.

-------------------------------------------------------------------------------

                                                       *LspCxxHighlightDisable*
:LspCxxHighlightDisable

Disable highlighting for this buffer. Renable by using |:LspCxxHighlight|.

-------------------------------------------------------------------------------

                                                          *LspCxxHlIgnoredSyms*
:LspCxxHlIgnoredSyms

Show all symbols that don't have a highlight group defined for the current
buffer. This is useful for debugging why a symbol is not highlighted.

-------------------------------------------------------------------------------

                                                             *LspCxxHlDumpSyms*
:LspCxxHlDumpSyms

Show all symbols in the current buffer received from the language server.
Warning: this spams your messages.

-------------------------------------------------------------------------------

                                                            *LspCxxHlCursorSym*
:LspCxxHlCursorSym

Show the symbol under the cursor (if one exists) and what highlight group it
corresponds to. Occasionally multiple symbols are under the cursor, if this
happens often it may be due to a bug in your language server.

===============================================================================

                                              *vim-lsp-cxx-highlight-variables*
Variables

The following variables can be modified to change the behavior of this plugin:

-------------------------------------------------------------------------------

                                  *lsp_cxx_hl_log_file* *g:lsp_cxx_hl_log_file*
g:lsp_cxx_hl_log_file

The log file for vim-lsp-cxx-highlight. By default it is '', which is disabled.

>
  let g:lsp_cxx_hl_log_file = '/tmp/vim-lsp-cxx-hl.log'
<

-------------------------------------------------------------------------------

                            *lsp_cxx_hl_verbose_log* *g:lsp_cxx_hl_verbose_log*
g:lsp_cxx_hl_verbose_log

Extra verbose logging. By default it is 0 (off).

>
  let g:lsp_cxx_hl_verbose_log = 1
<

-------------------------------------------------------------------------------

                          *lsp_cxx_hl_ft_whitelist* *g:lsp_cxx_hl_ft_whitelist*
g:lsp_cxx_hl_ft_whitelist

Whitelist of filetypes to highlight.

Default = ['c', 'cpp', 'objc', 'objcpp', 'cc']

>
  let g:lsp_cxx_hl_ft_whitelist = ['c', 'cpp']
  let g:lsp_cxx_hl_ft_whitelist += ['abcd']
<

-------------------------------------------------------------------------------

  *lsp_cxx_hl_inactive_region_priority* *g:lsp_cxx_hl_inactive_region_priority*
g:lsp_cxx_hl_inactive_region_priority

The match priority of preprocessor skipped regions. Also see |matchadd()|.
This is very low to avoid the regions from overwriting other matches.

Note: this has no effect in |neovim| when |g:lsp_cxx_hl_use_nvim_text_props|
is |true|

Default = -99.
>
  let g:lsp_cxx_hl_inactive_region_priority = -10
<

-------------------------------------------------------------------------------

                    *lsp_cxx_hl_syntax_priority* *g:lsp_cxx_hl_syntax_priority*
g:lsp_cxx_hl_syntax_priority

The match priority of general semantic highlight. Also see |matchadd()|.
This is very low to avoid the highlighting from overwriting other matches.

Note: this has no effect in |neovim| when |g:lsp_cxx_hl_use_nvim_text_props|
is |true|

Default = -100.
>
  let g:lsp_cxx_hl_syntax_priority = -20
<

-------------------------------------------------------------------------------

                    *lsp_cxx_hl_use_nvim_text_props* *g:lsp_cxx_hl_use_nvim_text_props*
g:lsp_cxx_hl_use_nvim_text_props 

Use Neovim's |nvim_buf_add_highlight()| which allow for highlighting to
move with the text. This is auto-enabled for reasonably recent versions of Neovim.

Default = has('nvim-0.3.0').
>
  let g:lsp_cxx_hl_use_nvim_text_props = 1 
<

-------------------------------------------------------------------------------

                    *lsp_cxx_hl_use_text_props* *g:lsp_cxx_hl_use_text_props*
g:lsp_cxx_hl_use_text_props 

Warning: This a fairly new feature in Vim and may be buggy.

With Vim 8.1 |text-properties| have been added which allow for highlighting to
move with the text.

Default = 0.
>
  let g:lsp_cxx_hl_use_text_props = 1 
<

-------------------------------------------------------------------------------

                    *lsp_cxx_hl_light_bg* *g:lsp_cxx_hl_light_bg*
g:lsp_cxx_hl_light_bg 

Use default colors that are suitable for a light background color.

Default = 0.
>
  let g:lsp_cxx_hl_light_bg = 1 
<

-------------------------------------------------------------------------------

                    *lsp_cxx_hl_clear_delay_ms* *g:lsp_cxx_hl_clear_delay_ms*
g:lsp_cxx_hl_clear_delay_ms

Clear delay for the last remaining skipped region. This is a workaround for
debouncing erratic empty ccls notifications that appear upon saving.

Generally should be set to longer than it takes to compile the file or else
highlighting will flash when saving.

Default = 30000.
>
  let g:lsp_cxx_hl_clear_delay_ms = 10000
<

===============================================================================

                                       *vim-lsp-cxx-highlight-highlight-groups*

For more details also see syntax/lsp_cxx_highlight.vim from this plugin.

-------------------------------------------------------------------------------

                                       *vim-lsp-cxx-highlight-hl-group-skipped*
                                                        *LspCxxHlSkippedRegion*
                                                *LspCxxHlSkippedRegionBeginEnd*
Preprocessor Skipped Regions           

Preprocessor inactive regions are highlighted using |LspCxxHlSkippedRegion|.
The first and last lines are highlighted using |LspCxxHlSkippedRegionBeginEnd|,
this is because cquery/ccls includes the #if/#endif in the inactive region.

Note: |LspCxxHlSkippedRegionBeginEnd| only applies when not using |textprop|

Default Mapping
|LspCxxHlSkippedRegion| -> |Comment|
|LspCxxHlSkippedRegionBeginEnd| -> |Normal|

E.g.
>
  " Change skipped regions to Dark Gray
  highlight LspCxxHlSkippedRegion ctermfg=DarkGray guifg=DarkGray
<

-------------------------------------------------------------------------------

                                       *vim-lsp-cxx-highlight-hl-group-symbols*
                                                                  *LspCxxHlSym*
Semantic Highlighting Symbols          

Format of highlight groups:

`LspCxxHlSym[<ParentKind>]<Kind>[<StorageClass>]`

ParentKind   - (optional) the enclosing symbol kind
Kind         - the symbol kind
StorageClass - (optional) any storage specifiers
               (None, Extern, Static, PrivateExtern, Auto, Register)

About Kind and ParentKind
Kind and ParentKind are the same as the language server specification 
for SymbolKind. E.g. File, Constructor, Enum, etc...
See https://microsoft.github.io/language-server-protocol/specification#textDocument_documentSymbol

cquery and ccls also add custom values:
`TypeAlias`    - custom types from typedef
`Parameter`    - function parameter
`StaticMethod` - static methods
`Macro`        - macros and function like macros

Examples
>
  LspCxxHlSymClassMethod    - highlight group for methods in a class
  LspCxxHlSymStructMethod   - highlight group for methods in a struct
  LspCxxHlSymVariableStatic - highlight group for static variables
<

                                      *vim-lsp-cxx-highlight-hl-group-priority*
Highlight Group Priority
The highlight groups will be tried in this order:
1. Full match: 
   `LspCxxHlSym<ParentKind><Kind><StorageClass>`
   E.g. `LspCxxHlSymClassMethodStatic`

2. Full match minus StorageClass
   `LspCxxHlSym<ParentKind><Kind>`
   E.g. `LspCxxHlSymClassMethod`

3. Partial match
   `LspCxxHlSym<Kind><StorageClass>`
   E.g. `LspCxxHlSymMethodStatic`

4. Partial match minus Storage Class
   `LspCxxHlSym<Kind>`
   E.g. `LspCxxHlSymMethod`

The first highlight group that exists will be used.

Examples
>
  highlight LspCxxHlSymClassMethod ctermfg=Magenta guifg=Magenta
  highlight LspCxxHlSymStructMethod  ctermfg=Red guifg=Red
  highlight LspCxxHlSymVariableStatic ctermfg=Blue guifg=Blue
<

===============================================================================

                                        *vim-lsp-cxx-highlight-troubleshooting*
Troubleshooting

If you are experiencing issues getting highlighting to work at all then enable
logging and seeing if any log messages (or lack of messages) stand out.

>
  let g:lsp_cxx_hl_log_file = '/tmp/vim-lsp-cxx-hl.log'
  let g:lsp_cxx_hl_verbose_log = 1
<

If certain symbols don't look correct try |LspCxxHlCursorSym| or
|LspCxxHlIgnoredSyms| and looking at the output.

Otherwise you can seek support on github:
https://github.com/jackguo380/vim-lsp-cxx-highlight/issues
(Please clearly document what your configuration is and what you tried)

===============================================================================

                                              *vim-lsp-cxx-highlight-extending*
Adding support for more LSP clients

vim-lsp-cxx-highlight is designed to be simple to integrate with a LSP client.

In order to support vim-lsp-cxx-highlight with your LSP client there are a
couple of options.

1. Receive all LSP notifications and call |lsp_cxx_hl#notify_json_rpc()|
   
   This is how |vim-lsp| support is implemented.

Example pseudo code:
>
  function OnReceiveMessage(jsonstr)
    if IsResponse(a:jsonstr)
      " ...
    elseif IsNotification(a:jsonstr)
      call lsp_cxx_hl#notify_json_rpc(a:jsonstr)
    else
      " ...
    endif
  endfunction
<

2. Parse the LSP notifications and call the corresponding function.

   $cquery/publishSemanticHighlighting -> |lsp_cxx_hl#notify_symbols()|
   $cquery/setInactiveRegions          -> |lsp_cxx_hl#notify_skipped()|
   $ccls/publishSemanticHighlight      -> |lsp_cxx_hl#notify_symbols()|
   $ccls/publishSkippedRegions         -> |lsp_cxx_hl#notify_skipped()|

Example pseudo code:
>
  function OnReceiveNotification(msg)
    if a:msg['method'] ==# '$cquery/publishSemanticHighlighting'
      call lsp_cxx_hl#notify_symbols('cquery',
          \ a:msg['params']['uri'], msg['params']['symbols'])
    elseif " ...
      " ...
    endif
  endfunction
<

===============================================================================

                                                    *vim-lsp-cxx-highlight-api*
Public API

vim-lsp-cxx-highlight plugin provides the following API for other plugins:

-------------------------------------------------------------------------------

                                                          *g:lsp_cxx_hl_loaded*
g:lsp_cxx_hl_loaded

The existence of this plugin can be checked like so:
>
  if exists('g:lsp_cxx_hl_loaded')
    " Do something
  endif
<

-------------------------------------------------------------------------------

                    *lsp_cxx_hl#notify_json_rpc* *lsp_cxx_hl#notify_json_rpc()*
lsp_cxx_hl#notify_json_rpc()

Pass vim-lsp-cxx-highlight the full JSON RPC Notification.

This will call |lsp_cxx_hl#notify_skipped()| or |lsp_cxx_hl#notify_symbols()|
depending on the method/type of the message.
Unrelated messages are ignored without error.

>
  function lsp_cxx_hl#notify_json_rpc(json)
<
    json - |String| (JSON String) or |Dict| (Parsed by |json_decode()|).

-------------------------------------------------------------------------------

                      *lsp_cxx_hl#notify_skipped* *lsp_cxx_hl#notify_skipped()*
lsp_cxx_hl#notify_skipped()

Receive data from $cquery/setInactiveRegions or $ccls/publishSkippedRegions.
This parses the preprocessor skipped regions and sends it to be highlighted.

>
  function lsp_cxx_hl#notify_skipped(server, buffer, skipped)
<
    server  - |String|, either 'cquery' or 'ccls'
    buffer  - |String| (Raw URI or |bufname()|) or |Number| (|bufnr()|), which
              buffer the data is intended for.
    skipped - |List|, the inactive regions data

These arguments can be found in the LSP notification like so:
buffer = msg['response']['params']['uri']

skipped = msg['params']['inactiveRegions'] (cquery)
or
skipped = msg['params']['skippedRanges'] (ccls)

-------------------------------------------------------------------------------

                      *lsp_cxx_hl#notify_symbols* *lsp_cxx_hl#notify_symbols()*
lsp_cxx_hl#notify_symbols()

Receive data from $cquery/publishSemanticHighlighting or $ccls/publishSemanticHighlight.
This parses the semantic highlight symbols and sends it to be highlighted.

>
  function lsp_cxx_hl#notify_symbols(server, buffer, symbols)
<
    server  - |String|, either 'cquery' or 'ccls'
    buffer  - |String| (Raw URI or |bufname()|) or |Number| (|bufnr()|), which
              buffer the data is intended for.
    symbols - |List|, the list of semantic highlighting symbols

These arguments can be found in the LSP notification like so:
buffer = msg['params']['uri']
symbols = msg['params']['symbols']

===============================================================================

License: MIT

See LICENSE.txt at the root of this plugin.

===============================================================================

vim: ft=help
