Vim syntaxfile: Difference between revisions
(9 intermediate revisions by the same user not shown) | |||
Line 8: | Line 8: | ||
|- | |- | ||
| <code>:h syn-region</code> || https://vimhelp.org/syntax.txt.html#%3Asyn-region | | <code>:h syn-region</code> || https://vimhelp.org/syntax.txt.html#%3Asyn-region | ||
|- | |||
| <code>:h syn-pattern</code> (ex. <code>/^foo$/ms=s-1</code>) || https://vimhelp.org/syntax.txt.html#%3Asyn-pattern | |||
|- | |- | ||
| <code>:h syn-arguments</code> (ex. conceal, cchar, contained, ..) || https://vimhelp.org/syntax.txt.html#%3Asyn-arguments | | <code>:h syn-arguments</code> (ex. conceal, cchar, contained, ..) || https://vimhelp.org/syntax.txt.html#%3Asyn-arguments | ||
Line 13: | Line 15: | ||
|} | |} | ||
</blockquote><!-- Documentation --> | </blockquote><!-- Documentation --> | ||
= Tutorials = | |||
<blockquote> | |||
{| class="wikitable" | |||
|- | |||
| vimwiki: creating syntaxfiles || https://vim.fandom.com/wiki/Creating_your_own_syntax_files | |||
|- | |||
|} | |||
</blockquote><!-- Tutorials --> | |||
= Locations = | = Locations = | ||
Line 74: | Line 85: | ||
</blockquote><!-- Example --> | </blockquote><!-- Example --> | ||
= | = Debugging Syntax (identify syntax region under cursor) = | ||
<blockquote> | <blockquote> | ||
<syntaxhighlight lang="vim"> | |||
" array with the stack of the syntax items applied to the item under the cursor | |||
echo synstack( | |||
line('.'), | |||
line('.') | |||
) | |||
</blockquote><!-- | " 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" | |||
) | |||
</syntaxhighlight> | |||
</blockquote><!-- Debugging Syntax --> | |||
= Match Regions = | = Syntax = | ||
<blockquote> | |||
== Match Regions == | |||
<blockquote> | <blockquote> | ||
You define keywords/matches, optionally within a region.<br> | |||
these can be assigned styles with <code>:highlight</code> | |||
<syntaxhighlight lang="vim"> | <syntaxhighlight lang="vim"> | ||
" keyword matches are literal word-matches | " keyword matches are literal word-matches | ||
Line 97: | Line 136: | ||
\ transparent | \ transparent | ||
\ contains=mySqlKeywords,myComments | \ contains=mySqlKeywords,myComments | ||
" you can assign multiple starts/ends to the same region | |||
" (ex. in ruby '{...}' and 'do; ...; end' are identical) | |||
</syntaxhighlight> | </syntaxhighlight> | ||
</blockquote><!-- Match Regions --> | </blockquote><!-- Match Regions --> | ||
= Highlight = | == Syntax Arguments == | ||
<blockquote> | |||
=== contains/contained === | |||
<blockquote> | |||
<code>contains</code> indicates that a region/match contains another match-group.<br> | |||
Ex. if you wanted to syntax-highlight markdown within a doc-comment | |||
<syntaxhighlight lang="vim"> | |||
syntax region docComment | |||
\ start='"""' end='"""' | |||
\ transparent | |||
\ contains=markdownHeader,markdownBold | |||
</syntaxhighlight> | |||
<code>contained</code> is the counterpart of <code>contains</code><br> | |||
a contained match/keyword is only valid if it appears in a contains= statement | |||
(ex. it doesn't apply to the whole document) | |||
<syntaxhighlight lang="vim"> | |||
" don't apply to the whole document! only inside! | |||
syntax keyword myKwd1 | |||
\ contained | |||
\ SELECT | |||
</syntaxhighlight> | |||
</blockquote><!-- contains/contained --> | |||
=== matchgroup === | |||
<blockquote> | |||
<code>matchgroup</code> allows you to highlight the start/end pattern <br> | |||
differently than the body of the region. | |||
From the vim help page | |||
<syntaxhighlight lang="vim"> | |||
" quotation-marks can be styled with `Quote` | |||
" inside-quotation-marks can be styled with `String` | |||
syntax region String matchgroup=Quote | |||
\ start=+"+ skip=+\\"+ end=+"+ | |||
</syntaxhighlight> | |||
</blockquote><!-- matchgroup --> | |||
</blockquote><!-- Syntax Arguments --> | |||
== Highlight == | |||
<blockquote> | <blockquote> | ||
You apply highlights to captured keywords, matches, or regions. | You apply highlights to captured keywords, matches, or regions. | ||
Line 111: | Line 192: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
</blockquote><!-- Highlight --> | </blockquote><!-- Highlight --> | ||
</blockquote><!-- Syntax --> |
Latest revision as of 16:53, 7 January 2024
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-commentsyntax region docComment \ start='"""' end='"""' \ transparent \ contains=markdownHeader,markdownBold
contained
is the counterpart ofcontains
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 \ SELECTmatchgroup
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'