Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/charlespascoe/vim-go-syntax

Fast, 'tree-sitter'-like Vim Syntax Highlighting for Go
https://github.com/charlespascoe/vim-go-syntax
go go-syntax golang vim vim-syntax vim-syntax-highlight vim-syntax-highlighting
Last synced: about 1 month ago
JSON representation
Fast, 'tree-sitter'-like Vim Syntax Highlighting for Go
Host: GitHub
URL: https://github.com/charlespascoe/vim-go-syntax
Owner: charlespascoe
License: mit
Created: 2022-11-04T19:20:51.000Z (about 2 years ago)
Default Branch: main
Last Pushed: 2024-02-14T17:06:42.000Z (9 months ago)
Last Synced: 2024-09-29T02:05:57.171Z (about 2 months ago)
Topics: go, go-syntax, golang, vim, vim-syntax, vim-syntax-highlight, vim-syntax-highlighting
Language: Vim Script
Homepage:
Size: 1010 KB
Stars: 42
Watchers: 1
Forks: 1
Open Issues: 7
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project

README

        # Fast, 'tree-sitter'-like Vim Syntax Highlighting for Go

`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!







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](#configuration).

## Key Features

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.

- **Correctly highlights imported package names**

- **Godoc highlighting in `vim-go`**

- **More customisable [Configuration](#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)` vs `func (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).

- Many other small improvements, including labels, embedded types, invalid rune

  error highlighting, and better string behaviour.

## Configuration

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 a `0` to enable/disable the highlighting. For example:

```vim

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:

```vim

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:

```vim

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

" ~/.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 
| ------------------------------ 
| `g:go_highlight_braces` 
| `g:go_highlight_brackets` 
| `g:go_highlight_builtins` 
| `g:go_highlight_comma` 
| `g:go_highlight_dot` 
| `g:go_highlight_fields` 
| `g:go_highlight_format_strings` 
| `g:go_highlight_format_string_errors` 
| `g:go_highlight_functions` 
| `g:go_highlight_function_parens` 
| `g:go_highlight_function_braces` 
| `g:go_highlight_function_calls` 
| `g:go_highlight_function_call_parens` 
| `g:go_highlight_generate_tags` 
| `g:go_highlight_rune_literal_error` 
| `g:go_highlight_labels` 
| `g:go_highlight_map_brackets` 
| `g:go_highlight_operators` 
| `g:go_highlight_function_parameters` 
| `g:go_highlight_parens` 
| `g:go_highlight_semicolon` 
| `g:go_highlight_short_variable 
| `g:go_highlight_slice_brackets` 
| `g:go_highlight_format_strings` 
| `g:go_highlight_struct_type_fields` 
| `g:go_highlight_struct_tags` 
| `g:go_highlight_struct_fields` 
| `g:go_highlight_types` 
| `g:go_highlight_type_parameters` 
| `g:go_highlight_variable_assignments` 
| `g:go_highlight_variable_declarations`

| Default     | Default Group | -------------- | ----------- | ------------- | | **Enabled** | `Delimiter`   | | **Enabled** | `Delimiter`   | | **Enabled** | `Special`     | |   Disabled  | `Delimiter`   | | **Enabled** | `Operator`    | |   Disabled  | `Identifier`  | | **Enabled** | `SpecialChar` | |   Disabled  | `Error`       | | **Enabled** | `Function`    | | **Enabled** | `Delimiter`   | | **Enabled** | `Delimiter`   | | **Enabled** | `Function`    | | **Enabled** | `Delimiter`   | | **Enabled** | `PreProc`     | | **Enabled** | `Error`       | | **Enabled** | `Label`       | | **Enabled** | `Delimiter`   | | **Enabled** | `Operator`    | | **Enabled** | `Identifier`  | | **Enabled** | `Delimiter`   | |   Disabled  | `Delimiter`   | _declarations` | **Enabled** | `Identifier`  | | **Enabled** | `Delimiter`   | | **Enabled** | `SpecialChar` | |   Disabled  | `Identifier`  | | **Enabled** | `PreProc`     | |   Disabled  | `Identifier`  | | **Enabled** | `Type`        | | **Enabled** | `Identifier`  | |   Disabled  | `Special`     | | **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.

- `g:go_highlight_brackets`

    - All brackets (`[]`). More specific bracket options (e.g.

      `g:go_highlight_map_brackets`) will take precedence over this option.

- `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()`

- `g:go_highlight_fields`

    - Fields in expressions, e.g. `bar` in

  `foo.bar = 123`

- `g:go_highlight_format_strings`

    - Format strings, e.g. `"Hello, %s"`.

- `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 be `fmt.Sprintf("%[1]d", 123)`.

- `g:go_highlight_functions`

    - Function declaration names, e.g. `foo` in `func foo() { }`. Also applies

      to method names.

- `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.

- `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`.

- `g:go_highlight_operators`

    - Operators including assignment, e.g. `+`, `-`, `&&`, `||`, `=`, `:=`, etc.

- `g:go_highlight_function_parameters`

    - Parameter names, e.g. `bar` in `func

  foo(bar int)`

- `g:go_highlight_parens`

    - All parentheses. More specific parenthesis options (e.g.

      `g:go_highlight_function_parens`) will take precedence.

- `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` and `b` in `a, b := foo()`.

- `g:go_highlight_slice_brackets`

    - The brackets in slice types, e.g. `[]string`.

- `g:go_highlight_format_strings`

    - Format placeholders in in format strings, e.g. `%s` in `fmt.Printf("%s",

      foo)`

- `g:go_highlight_struct_type_fields`

    - Field names in struct types, e.g. `Bar` in `type Foo struct { Bar int }`

- `g:go_highlight_struct_tags`

    - Struct tags, the backtick-delimited strings in structs, e.g. `` `json:bar` ``

      in ``struct { Bar int `json:"bar"` }``.

- `g:go_highlight_struct_fields`

    - Field names in struct literals, e.g. `Bar` in `f := Foo{ Bar: 123 }`.

- `g:go_highlight_types`

    - Type declaration names, e.g. `Foo` in `type Foo struct { Bar int }`. Even

      with this option off, types parameters etc. will still be highlighted

      as types.

- `g:go_highlight_type_parameters`

    - Type parameter names in type parameter lists, e.g. the `T` in the brackets

      of `type Foo[T] { Bar T }`; the `T` in the struct will be highlighted as a

      type.

- `g:go_highlight_variable_assignments`

    - Variable names in assignments, e.g. `a` and `b` in `a, b = foo()`.

- `g:go_highlight_variable_declarations`

    - Names in `var` or `const` assignments, e.g. `a` in `var a []string`. Also

      applies to short variable declarations (i.e. `:=`) unless

      `g:go_highlight_short_variable_declarations` is set.

Other configuration options:

- `g:go_fold_decl_blocks` (default: 1)

    - Fold `var` and `const` declaration blocks.

- `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.

## Caveats

- 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` in `struct { 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 the `Foo` 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).

- `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.

## What's Next

- [ ] Possibly integrate with `vim-go` to get actual type information to

  highlight things like type conversion correctly