NAME

vim-syntax-to-shb - Convert Vim syntax files to .shb syntax data files

SYNOPSIS

vim-syntax-to-shb [OPTIONS] FILE_OR_DIR [FILE_OR_DIR ...]

# Convert a single file
vim-syntax-to-shb /usr/share/vim/vim91/syntax/perl.vim

# Convert multiple files to a specific output directory
vim-syntax-to-shb --output-dir share/syntax /usr/share/vim/vim91/syntax/perl.vim \
    /usr/share/vim/vim91/syntax/python.vim

# Convert all .vim files in a directory
vim-syntax-to-shb --output-dir share/syntax /usr/share/vim/vim91/syntax/

# Override the language name
vim-syntax-to-shb --language bash /usr/share/vim/vim91/syntax/sh.vim

OPTIONS

--output-dir DIR

Directory to write .shb files (default: current directory).

--language NAME

Override the language name in the output file. Only valid with a single input file.

--follow-includes / --no-follow-includes

Follow runtime!/runtime, source, and syn include directives found in the Vim source and splice the referenced file's lines into the input before conversion (default: on). This fixes "delegating" Vim syntax files that pull all of their rules from another file (e.g. bash.vim delegates to sh.vim via runtime! syntax/sh.vim) and would otherwise produce an effectively empty .shb. Resolution order for a referenced file: relative to the directory of the file currently being processed, then relative to the top-level Vim syntax/ runtime directory the input came from. Includes are followed recursively (a visited-set guards against cycles; hard stop after 5 levels). If a referenced file cannot be located, a warning is printed and conversion continues using whatever rules were found. Use --no-follow-includes to reproduce the old single-file behavior.

--min-sections N

The minimum number of rule sections ([keyword:...], [match:...], [region:...]) a generated .shb must contain to avoid being reported as "thin" (default: 3). A file with 0 sections is always considered thin regardless of this setting.

--warn-thin / --no-warn-thin

Print a THIN ... warning line to STDERR for each generated file that is thin (default: on, i.e. warnings are printed). Use --no-warn-thin to suppress the per-file lines (the end-of-run converted/thin summary line is always printed).

--fail-on-thin / --no-fail-on-thin

If any generated (non-curated, actually-written) output file is thin, exit with a non-zero status so the condition can gate CI/build scripts (default: on). Use --no-fail-on-thin for exploratory runs where a non-zero exit is not desired.

--force

Overwrite curated .shb files (those beginning with a # @curated marker line) that would otherwise be protected from regeneration.

--verbose

Print progress messages to stderr.

-h, --help

Show this help message and exit.

DESCRIPTION

vim-syntax-to-shb reads Vim .vim syntax files and produces .shb (Syntax Highlight Basic) data files suitable for use by Syntax::Highlight::Basic::Parser at runtime.

The converter extracts:

• syn keyword statements → [keyword:GROUP] sections

• syn match statements → [match:GROUP] sections

• syn region statements → [region:GROUP] sections

• hi def link statements → group resolution map

Vim regex syntax is converted to Perl regex syntax where possible. Patterns that are too complex to convert are skipped with a warning.

Thin-file detection

A generated .shb is considered thin if it has zero rule sections, or fewer than --min-sections total rule sections. Thin output most commonly happens for two reasons:

1. The Vim source file delegates all of its rules to another file via runtime!, source, or syn include and defines no rules of its own. This is fixed automatically by --follow-includes (on by default), which inlines the referenced file's content before conversion.

2. The Vim source uses Vim-only regex magic (\v "very magic" mode, \</\> word-boundary atoms, etc.) that cannot be safely translated to Perl regex, or defines its keywords indirectly (via clusters, contains=, generated word lists) in a way the converter deliberately does not follow. These languages require hand-curated .shb content (see docs/syntax-format.md), marked with a leading # @curated line so the converter never overwrites the curation.

When --warn-thin is enabled (the default), each thin output file is reported on STDERR as it is written, including the delegation directive text when the thinness is due to reason 1 above. A one-line summary (Converted N file(s); M thin.) is printed at the end of the run. When --fail-on-thin is enabled (the default), the process exits non-zero if any thin file was produced, so this condition can gate CI/build scripts.

VERSION

0.1.0

AUTHOR

Sandor Patocs

LICENSE

This script is licensed under the same terms as Perl itself.

SEE ALSO

Syntax::Highlight::Basic::Parser