Vim syntaxfile

Syntax for writing vim syntax-files.

Documentation

:h syn-match	https://vimhelp.org/syntax.txt.html#%3Asyn-match
:h syn-region	https://vimhelp.org/syntax.txt.html#%3Asyn-region
:h syn-pattern (ex. /^foo$/ms=s-1)	https://vimhelp.org/syntax.txt.html#%3Asyn-pattern
:h syn-arguments (ex. conceal, cchar, contained, ..)	https://vimhelp.org/syntax.txt.html#%3Asyn-arguments

Tutorials

vimwiki: creating syntaxfiles

https://vim.fandom.com/wiki/Creating_your_own_syntax_files

Locations

${vim-or-plug}/syntax/${vim_filetype}.vim

syntax files

Example

ftdetect/my_language.vim

Register a filetype based on a file-extension

" ftdetect/my_language.vim

au BufRead,BufNewFile *.todo set filetype=todolist_simple

syntax/my_language.vim

Define the syntax-highligting for the filetype

" syntax/my_language.vim

" don't reload if already loaded
if exists('b:my_language_syntax')
    finish
endif

" Define marker colours (CLI/GUI)
let s:todo_colour     = 'magenta'
let s:gui_todo_colour = '#F57900'

" Define Regexes
let s:todo_regex = '\(^\s*\)\@<=\*\([a-zA-Z]\)\@!'

" Define syntax for Regexes
execute "syntax match my_language_todo  '". s:todo_regex ."'"

" Apply highlighting
execute ' highlight todolistsimple_todo ctermfg='. s:todo_colour .' guifg='. s:gui_todo_colour .' ctermbg=none cterm=bold gui=bold'

" mark file as loaded
let b:my_language_syntax = 1

Debugging Syntax (identify syntax region under cursor)

" array with the stack of the syntax items applied to the item under the cursor
echo synstack(
    line('.'),
    line('.')
)

" the bottom-most ID of the syntax item
echo synID(
    line('.'),
    line('.'),
    "name",
)

" the name of the bottom-most syntax item for item under cursor
echo synIDattr(
    synID(
        line('.'),
        col('.'),
        "name"
    ),
    "name"
)

Syntax

Match Regions

You define keywords/matches, optionally within a region.
these can be assigned styles with :highlight

" keyword matches are literal word-matches
syntax keyword mySqlKeywords
  \ SELECT INSERT INNER LEFT JOIN

" matches are regex matches
syntax match myComments
  \ '\(--\|#\)'

" regions let you define (potentially multiline) regions
" you can have different rules within different types of regions
" (contains defines matches/keywords that apply within the region)
syntax region myBlock
  \ start='{' end='}'
  \ transparent
  \ contains=mySqlKeywords,myComments

" you can assign multiple starts/ends to the same region
" (ex. in ruby '{...}' and 'do; ...; end' are identical)

Syntax Arguments

contains/contained

contains indicates that a region/match contains another match-group.
Ex. if you wanted to syntax-highlight markdown within a doc-comment

syntax region docComment
 \ start='"""' end='"""'
 \ transparent
 \ contains=markdownHeader,markdownBold

contained is the counterpart of contains
a contained match/keyword is only valid if it appears in a contains= statement (ex. it doesn't apply to the whole document)

" don't apply to the whole document! only inside!
syntax keyword myKwd1
  \ contained
  \ SELECT

matchgroup

matchgroup allows you to highlight the start/end pattern
differently than the body of the region.

From the vim help page

" quotation-marks can be styled with `Quote`
" inside-quotation-marks can be styled with `String`
syntax region String matchgroup=Quote
  \ start=+"+  skip=+\\"+	end=+"+

Highlight

You apply highlights to captured keywords, matches, or regions.

" apply style to `someKeywordOrMatch`
highlight someKeywordOrMatch
  \ cterm=italic ctermfg=2      ctermbg=160
  \ gui=italic   guifg='#111111' guibg='#FFFFFF'