Vim plugin for saving syntax match rules

What is it good for

If you do log investigation it’s handy to differentiate identifiers with colors.
When you close Vim and later open the log file again it’s fine to have preserved the colors.

Quick howto

install the syntax match plugin
open file with suffix .log or .txt
use command :Y search_pattern to highlight some text
- you’ve used the prepared shortcuts for coloring log parts
quit the file, then open it again
- syntax is loaded from a saved syntax file and restored for you (see How works internally)

What the plugin provides

This plugin offers functionality to save syntax match rules to an auxiliary file placed beside of file with the original content. Then the syntax highligting will be restored based on the saved rules in the auxiliary file.

Beside of having capability to restore defined syntax match rules when specific files is opened again it tries to solve trouble that I have with vim match command (:match Comment /pattern/). You can match only one pattern at time. When using match again the previously hightlighted text is not hightligted anymore. I wanted chance to add highligting dynamically for different patterns with the same 'color'. Sure there are commands 2match and 3match but for me it’s not normally enough (see my usecase).

How to install

The easiest way to install is use pathogen plugin: http://www.vim.org/scripts/script.php?script_id=2332

For installation steps for pathogen plugin see the link above or do following. This downloads file with the pathogen plugin to directory ~/.vim/autoload (see http://learnvimscriptthehardway.stevelosh.com/chapters/42.html) and loads pathogen plugin each time when a vim is used.

mkdir -p ~/.vim/autoload ~/.vim/bundle
curl -LSso ~/.vim/autoload/pathogen.vim https://tpo.pe/pathogen.vim
add line execute pathogen#infect() to your ~/.vimrc file

Now the installation of this plugin is easy like

git clone git@github.com:ochaloup/vim-syntax-match.git ~/.vim/bundle/vim-syntax-match

Note

You can have troubles with using syntax highligting or with showing colours.

Check that syntax setting is set up :syntax on.
You can have permitted only limited number of colors to be displayed. First there could be issue with your terminal. As a first instance of help try to check colors to be shown in your vim instance :set t_Co?. If displayed number is 8 or lower than 256 then try to change it with command :set t_Co=256 (see http://vim.wikia.com/wiki/256_colors_setup_for_console_Vim#Vim_still_does_not_display_the_color_scheme_correctly)

Summarized .vimrc setup could be

syntax on
if (&t_Co != 256)
  set t_Co=256
endif

Usage

Basics

Whenever you open any .log or .txt file the plugin is activated. Now you can use syntax match (:help syn-match) command to have specific highlighting for this file.

Note

Syntax match command has basic syntax syntax match <color> /regexp/.

<color> has to be defined hightlight definition (see :help :highlight). If you want basically you will set hi yellow guibg=#ffff00 ctermbg=11.
regexp is standard regular expression pattern when matched then hightlight is used
command syntax does have abbreviation to syn only (syn match red /hello/)

Save the file and quit. Next time when you open the file the syntax will be loaded.
So enjoy!

If you open any file of different type you can call command :SaveSyntax (shortcut command name is :SS). At that time the syntax match rules are saved to the auxiliary file. When you open the same file next time syntax rules are loaded and shown.

Helper commands

For you not need to repeatedly write command sentence :syn match Boolean /pattern/ plugin brings two things.

Predefined hightlightings named as colors. You can write :syn match red /pattern/. For you to see what colors are defined see ~/.vim/bundle/vim-syntax-match/colors/syntaxmatch.vim.

Predefined user commans which abbreviate necessity to write the syn match color. You can write only :Yellow pattern. Or more abbreviated only :Y pattern.

Command	Abbreviation	Example	Meaning
Yellow	Y	`:Y pattern`	`:syn match yellow /pattern/`
Yellow2	Y2	`:Y2 pattern`	`:syn match yellow2 /pattern/`
Yellow3	Y3	`:Y3 pattern`	`:syn match yellow3 /pattern/`
Yellow4	Y4	`:Y4 pattern`	`:syn match yellow4 /pattern/`
Red	R	`:R pattern`	`:syn match red /pattern/`
Red2	R2	`:R2 pattern`	`:syn match red2 /pattern/`
Red3	R3	`:R3 pattern`	`:syn match red3 /pattern/`
Red4	R4	`:R4 pattern`	`:syn match red4 /pattern/`
Orange	O	`:O pattern`	`:syn match orange /pattern/`
Orange2	O2	`:O2 pattern`	`:syn match orange2 /pattern/`
Orange3	O3	`:O3 pattern`	`:syn match orange3 /pattern/`
Violet	V	`:V pattern`	`:syn match violet /pattern/`
Violet2	V2	`:V2 pattern`	`:syn match violet2 /pattern/`
Violet3	V3	`:V3 pattern`	`:syn match violet3 /pattern/`
Violet4	V4	`:V4 pattern`	`:syn match violet4 /pattern/`
Violet5	V5	`:V5 pattern`	`:syn match violet5 /pattern/`
Green	G	`:G pattern`	`:syn match green /pattern/`
Green2	G2	`:G2 pattern`	`:syn match green2 /pattern/`
Green3	G3	`:G3 pattern`	`:syn match green3 /pattern/`
Green4	G4	`:G4 pattern`	`:syn match green4 /pattern/`
Blue	B	`:B pattern`	`:syn match blue /pattern/`
Blue2	B2	`:B2 pattern`	`:syn match blue2 /pattern/`
Blue3	B3	`:B3 pattern`	`:syn match blue3 /pattern/`
Blue4	B4	`:B4 pattern`	`:syn match blue4 /pattern/`
Grey	GY	`:GY pattern`	`:syn match grey /pattern/`
Grey2	GY2	`:GY2 pattern`	`:syn match grey2 /pattern/`
Grey3	GY3	`:GY3 pattern`	`:syn match grey3 /pattern/`
Brown	BR	`:BR pattern`	`:syn match brown /pattern/`
Cyan	C	`:C pattern`	`:syn match cyan /pattern/`
White	W	`:W pattern`	`:syn match white /pattern/`
Pink	P	`:P pattern`	`:syn match pink /pattern/`
Pink2	P2	`:P2 pattern`	`:syn match pink2 /pattern/`
Pink3	P3	`:P3 pattern`	`:syn match pink3 /pattern/`
Whitefg	WF	`:WF pattern`	`:syn match whitefg /pattern/`
Cyanfg	CF	`:CYF pattern`	`:syn match cyanfg /pattern/`
Brownfg	BRF	`:BRF pattern`	`:syn match brownfg /pattern/`
Greyfg	GYF	`:GYF pattern`	`:syn match greyfg /pattern/`
Bluefg	BF	`:BF pattern`	`:syn match bluefg /pattern/`
Greenfg	GF	`:GF pattern`	`:syn match greenfg /pattern/`
Violetfg	VF	`:VF pattern`	`:syn match violetfg /pattern/`
Orangefg	OF	`:OF pattern`	`:syn match orangefg /pattern/`
Redfg	RF	`:RF pattern`	`:syn match redfg /pattern/`
Yellowfg	YF	`:YF pattern`	`:syn match yellowfg /pattern/`
Pinkfg	PF	`:PF pattern`	`:syn match pinkfg /pattern/`
	YA	`:YA pattern`	`:syn match yellow /pattern/` in all opened buffers
	RA	`:RA pattern`	`:syn match red /pattern/` in all opened buffers
	GA	`:GA pattern`	`:syn match green /pattern/` in all opened buffers
	BA	`:BA pattern`	`:syn match blue /pattern/` in all opened buffers
	GYA	`:GYA pattern`	`:syn match grey /pattern/` in all opened buffers
	BRA	`:BRA pattern`	`:syn match brown /pattern/` in all opened buffers
	CA	`:CA pattern`	`:syn match cyan /pattern/` in all opened buffers
	WA	`:WA pattern`	`:syn match white /pattern/` in all opened buffers
	PA	`:PA pattern`	`:syn match pink /pattern/` in all opened buffers
ClearAllSyntax	SyntaxClearAll	`:clear syntax`	clearing syntax in all opened buffers

How works internally

Plugin defines autocommand for .log and .txt to call function syntaxmatch#saveSyntax() function at time when such file is closed.
syntaxmatch#saveSyntax() function calls Vim internal command :syntax which list all currently defined syntax highlighting rules.
Function filter only those which uses match (see http://learnvimscriptthehardway.stevelosh.com/chapters/46.html or :help syn-match).
It converts output of :syntax command and creates valid syntax match <color> /pattern/ commands.
These commands are then saved to auxiliary file with name pattern .<original_file_name>.syntax. That means after syntax is saved you can find a .syntax file besides of your original file.
When a file is opened then it check existence of the .syntax file with the same name.
If the auxiliary file (*.syntax) exists then its content line by line is executed.

Warning

A file could be highlighted with different syntax highlighting rules before you start to use your own. That’s caused by other plugin or syntax rules (see http://learnvimscriptthehardway.stevelosh.com/chapters/45.html). All rules that uses match are saved to the result file.

There could be a clash between rules. Meaning two match patterns could hightlight the same text. Which pattern is used is resolved based priority rules (see :help syn-priority). Basically the last used rule overrule the previous one.

As rules are saved and then loaded from a file there is no check for their order. That causes that highlighting result will be different when edited and then later when loaded. Rules could beat each other when their patterns overlaps.

Tips

Hightligting to HTML

Vim comes with handy command :TOhtml which takes your text document and convert it to html file. That html file is highighted as you defined it with syntax commands. This plugin offers small enhancement to the internal command that adds clickable line numbers. When command :TOHtmlWithLines is executed you can click on the shown line numbers to get link with anchor (#) which can be then shared with a co-worker.

Synchronized scrolling in vim windows

If you investigate some logs which are similar but not the same and you want to see them in sync one beside other try vim command :set scrollbind. Any file (buffer) that has set this is then scrolled in sync with all other buffers that used this settings as well. Abbreviation is :set scb and unsetting is done by :set scb!.

Usage is like

open a file vim filename
:set scb
open other file as new window in vim :vsplit otherfile
:set scb
scroll

(for switching from one window to other you can use shortcut CTRL+W W)

The plugin adds special user command named SCB which you can run as :SCB and it’s functionality is to run scroll bind on all opened windows. This user command does the same as when you run manually :windo set scb.

How do I use it (aka my usecase)

My usecase is for investigation in log files. I have usually works with logs from WildFly app server where I investigate issues connected to Narayana transaction manager. That means that I met long transaction ids on several places of the log file and it’s very useful to differentiate them visually by coloring them.

This is especially good when I need to connect ids of JMS or JDBC with transaction ids. I normally uses the same color for the connected identifiers and then I’m able to follow what happens in the log file.

normful / vim-syntax-match