vim-go-syntax
provides fast and feature-rich Vim syntax highlighting for Go,
with results comparable to tree-sitter in Neovim.
Feedback is welcome! This syntax is still fairly new and I'd like feedback or issues to improve it. Please see if there's already an issue open or create a new one.
Syntax highlighting can make reading code easier by using colour to convey
additional information. Existing Vim syntax definitions aren't able to to
correctly highlight key parts of the syntax, which motivated me to write
vim-go-syntax
from the ground up using the Go language specification. Not only
does it fix many of the shortfalls of existing syntax definitions, it's more
than 2x faster even with all features enabled!
![Syntax Comparison; vim-go on the left, vim-go-syntax on the right](https://github.com/charlespascoe/vim-go-syntax/raw/main/Syntax%20Comparison.png)
Comparison of vim-go
(left) with vim-go-syntax
(right) using my colour
scheme; see :help group-name
to see how your colour scheme highlights Vim's
default syntax groups. Most syntax highlighting features can be disabled if
you'd prefer - see Configuration.
Key features compared to vim-go
and the built-in Vim syntax:
- Correctly display user-defined types and packages
- E.g in structs, struct literals, parameters, slices, maps,
var
/const
declarations, type parameters, type assertions, type switches,make()
,new()
, etc.
- E.g in structs, struct literals, parameters, slices, maps,
- Correctly highlights imported package names
- Godoc highlighting in
vim-go
- More customisable Configuration
- Vastly more fine-grained highlighting
- Parentheses, Braces, and Brackets highlighted and individually configurable
- E.g. struct and function braces can be different
- Correctly highlight functions, including:
- User-defined types and packages in receiver, parameters, and return types
- Multiline parameters/return values, including successive parameters of the same type
- Identifier/type differentiation in function types (e.g.
func (int, MyType)
vsfunc (a, b MyType)
) and return types
- Correctly handle generics:
- Type parameters and their constraints (including user-defined types) are highlighted correctly
- User-defined types in type arguments are highlighted correctly
- Type arguments don't break function call or struct value highlighting
- Multiline field chains, even with comments
- Correct use of Vim's syntax groups
- More consistent with syntax definitions of other languages. See
:help group-name
to see your current colour scheme (or:help :hi
to create your own).
- More consistent with syntax definitions of other languages. See
- Many other small improvements, including labels, embedded types, invalid rune error highlighting, and better string behaviour.
Listed in the table below are various options that can be used to customise
highlighting. These can be set at any time before the syntax is loaded, usually
your .vimrc
is best.
Each option can be:
- A
1
or a0
to enable/disable the highlighting. For example:
let g:go_highlight_parens = 0
let g:go_highlight_fields = 1
- A syntax group name; see '
:help group-name
' to see what default groups are available and how your colour scheme styles them. For example, to make function calls look like types:
let g:go_highlight_function_calls = 'Type'
- A highlight description; see '
:help hi
' for syntax and options. For example, to make type parameters blue and italic:
let g:go_highlight_type_parameters = 'ctermfg=4 cterm=italic'
If you want even more customisation, you can override the default highlighting
by adding custom highlighting rules to ~/.vim/after/syntax/go.vim
(you'll need
to create this file first). The previous configuration examples could also be
achieved like this:
" ~/.vim/after/syntax/go.vim
hi clear goParens
hi link goField Identifier
hi link goFuncCall Type
hi goTypeParam ctermfg=4 cterm=italic
See syntax/go.vim
for the names of all syntax and
highlight groups.
Summary of options (see below table for descriptions):
Configuration Option | Default | Default Group |
---|---|---|
g:go_highlight_braces |
Enabled | Delimiter |
g:go_highlight_brackets |
Enabled | Delimiter |
g:go_highlight_builtins |
Enabled | Special |
g:go_highlight_comma |
Disabled | Delimiter |
g:go_highlight_dot |
Enabled | Operator |
g:go_highlight_fields |
Disabled | Identifier |
g:go_highlight_format_strings |
Enabled | SpecialChar |
g:go_highlight_format_string_errors |
Disabled | Error |
g:go_highlight_functions |
Enabled | Function |
g:go_highlight_function_parens |
Enabled | Delimiter |
g:go_highlight_function_braces |
Enabled | Delimiter |
g:go_highlight_function_calls |
Enabled | Function |
g:go_highlight_function_call_parens |
Enabled | Delimiter |
g:go_highlight_generate_tags |
Enabled | PreProc |
g:go_highlight_rune_literal_error |
Enabled | Error |
g:go_highlight_labels |
Enabled | Label |
g:go_highlight_map_brackets |
Enabled | Delimiter |
g:go_highlight_operators |
Enabled | Operator |
g:go_highlight_function_parameters |
Enabled | Identifier |
g:go_highlight_parens |
Enabled | Delimiter |
g:go_highlight_semicolon |
Disabled | Delimiter |
g:go_highlight_short_variable_declarations |
Enabled | Identifier |
g:go_highlight_slice_brackets |
Enabled | Delimiter |
g:go_highlight_format_strings |
Enabled | SpecialChar |
g:go_highlight_struct_type_fields |
Disabled | Identifier |
g:go_highlight_struct_tags |
Enabled | PreProc |
g:go_highlight_struct_fields |
Disabled | Identifier |
g:go_highlight_types |
Enabled | Type |
g:go_highlight_type_parameters |
Enabled | Identifier |
g:go_highlight_variable_assignments |
Disabled | Special |
g:go_highlight_variable_declarations |
Enabled | Identifier |
g:go_highlight_braces
- All braces (
{}
). More specific brace options (e.g.g:go_highlight_function_braces
) will take precedence over this option.
- All braces (
g:go_highlight_brackets
- All brackets (
[]
). More specific bracket options (e.g.g:go_highlight_map_brackets
) will take precedence over this option.
- All brackets (
g:go_highlight_builtins
- Highlight built-in functions differently from other functions.
g:go_highlight_comma
- Commas.
g:go_highlight_dot
- Dot operators, e.g. the dot in
foo.bar()
- Dot operators, e.g. the dot in
g:go_highlight_fields
- Fields in expressions, e.g.
bar
infoo.bar = 123
- Fields in expressions, e.g.
g:go_highlight_format_strings
- Format strings, e.g.
"Hello, %s"
.
- Format strings, e.g.
g:go_highlight_format_string_errors
- Invalid format strings. Currently only zero index in format strings, e.g.
fmt.Sprintf("%[0]d", 123)
which should befmt.Sprintf("%[1]d", 123)
.
- Invalid format strings. Currently only zero index in format strings, e.g.
g:go_highlight_functions
- Function declaration names, e.g.
foo
infunc foo() { }
. Also applies to method names.
- Function declaration names, e.g.
g:go_highlight_function_parens
- Parentheses around parameter list and receiver type.
g:go_highlight_function_braces
- The braces of the function block.
g:go_highlight_function_calls
- Function calls. Turning this off does not affect other syntax elements (e.g. generics, function call parentheses).
g:go_highlight_function_call_parens
- The parentheses of a function call.
g:go_highlight_generate_tags
- Generate comments, e.g.
//go:generate ...
. Turning this off makes them look like regular comments.
- Generate comments, e.g.
g:go_highlight_rune_literal_error
- Invalid rune literals.
g:go_highlight_labels
- User-defined labels.
g:go_highlight_map_brackets
- The brackets in map types, e.g.
map[string]int
.
- The brackets in map types, e.g.
g:go_highlight_operators
- Operators including assignment, e.g.
+
,-
,&&
,||
,=
,:=
, etc.
- Operators including assignment, e.g.
g:go_highlight_function_parameters
- Parameter names, e.g.
bar
infunc foo(bar int)
- Parameter names, e.g.
g:go_highlight_parens
- All parentheses. More specific parenthesis options (e.g.
g:go_highlight_function_parens
) will take precedence.
- All parentheses. More specific parenthesis options (e.g.
g:go_highlight_semicolon
- Semicolons.
g:go_highlight_short_variable_declarations
- Highlight the names of new variables defined by the declaration syntax,
e.g.
a
andb
ina, b := foo()
.
- Highlight the names of new variables defined by the declaration syntax,
e.g.
g:go_highlight_slice_brackets
- The brackets in slice types, e.g.
[]string
.
- The brackets in slice types, e.g.
g:go_highlight_format_strings
- Format placeholders in in format strings, e.g.
%s
infmt.Printf("%s", foo)
- Format placeholders in in format strings, e.g.
g:go_highlight_struct_type_fields
- Field names in struct types, e.g.
Bar
intype Foo struct { Bar int }
- Field names in struct types, e.g.
g:go_highlight_struct_tags
- Struct tags, the backtick-delimited strings in structs, e.g.
`json:bar`
instruct { Bar int `json:"bar"` }
.
- Struct tags, the backtick-delimited strings in structs, e.g.
g:go_highlight_struct_fields
- Field names in struct literals, e.g.
Bar
inf := Foo{ Bar: 123 }
.
- Field names in struct literals, e.g.
g:go_highlight_types
- Type declaration names, e.g.
Foo
intype Foo struct { Bar int }
. Even with this option off, types parameters etc. will still be highlighted as types.
- Type declaration names, e.g.
g:go_highlight_type_parameters
- Type parameter names in type parameter lists, e.g. the
T
in the brackets oftype Foo[T] { Bar T }
; theT
in the struct will be highlighted as a type.
- Type parameter names in type parameter lists, e.g. the
g:go_highlight_variable_assignments
- Variable names in assignments, e.g.
a
andb
ina, b = foo()
.
- Variable names in assignments, e.g.
g:go_highlight_variable_declarations
- Names in
var
orconst
assignments, e.g.a
invar a []string
. Also applies to short variable declarations (i.e.:=
) unlessg:go_highlight_short_variable_declarations
is set.
- Names in
Other configuration options:
g:go_fold_decl_blocks
(default: 1)- Fold
var
andconst
declaration blocks.
- Fold
g:go_fold_function_blocks
(default: 1)- Fold function blocks.
g:go_fold_struct_blocks
(default: 1)- Fold struct blocks.
g:go_fold_interface_blocks
(default: 1)- Fold interface blocks.
g:go_syntax_fold
(default: 1)- Global fold setting. If set to 0, all folding is disabled. If set to 1,
each respective
g:go_fold_*
option is used.
- Global fold setting. If set to 0, all folding is disabled. If set to 1,
each respective
- Type arguments to types and functions are limited to at most three nested
generic types, e.g.
val := Type1[Type2[Type3[Foo]]]{ ... }
. The number of arguments at each level is unlimited, e.g.Type1[Type2[A, B, C, ...]]
- The type parameters of a generic type embedded within a struct (that is, the
A,B,C
instruct { Foo[A,B,C] }
) can't be spread across multiple lines, though this is very uncommon in practical use. - Structs literals (
MyStruct{...}
) can't have a space between the name and the braces, despite the fact that Go permits this. - Type conversion (
MyType(someVal)
) is highlighted like a function call - A slice or map literal whose type is a function with multiple return values
and the type is not in parentheses (e.g.
[]func(a, b int) (c, d Foo){ f1, f2, f3 }
) is technically valid Go code, but theFoo
type will not be highlighted correctly.- This can easily be avoided by wrapping the type in parentheses to make it
clear (e.g.
[](func(a, b int) (c, d Foo)){ f1, f2, f3 }
, which is highlighted correctly), or preferably use a named type to make the code easier to read (e.g.type MyFunc func(a, b int) (c, d Foo)
, and then use[]MyFunc{ f1, f2, f3 }
, all of which will be highlighted correctly).
- This can easily be avoided by wrapping the type in parentheses to make it
clear (e.g.
iota
is matched in any expression. While not ideal, this currently avoids complex restructuring of the syntax code or performance degradation. It may be worth revisiting this at some point.
- Possibly integrate with
vim-go
to get actual type information to highlight things like type conversion correctly