Module vpe.syntax

A pythonic API for creating syntax highlighting definitions.

Cluster

class syntax.Cluster(syn, name)

A cluster of groups.

Parameters

syn: The Syntax instance that created this cluster.
name: A name for this cluster.

Methods

add(group1: Group | str, *groups: Group | str)

Add groups to the cluster.

A group argument may be a name, in which case it references or creates a group within the parent syntax object.

Parameters

group1: Union
The first group to be added.

groups: Union
Additional groups to be added.
group(name, **options)
Create and add a new group.

The new group is within the parent Syntax objects namespace. This provides a convenient shortcut for:
g = syntax.group(name, ...)
cluster.add(g)
Parameters

name
The name of the group.

options
Options for the group.
include(path_name)

Include Vim syntax file, adding its groups to this cluster.

This does a syn-include operation with a cluster name.

Parameters

path_name
The path name of the syntax file to include. If this is a relative path, the file is searched for within the :runtimepath.

invoke(file=None) → None

Invoke any pending syntax commands.

This is only intended to be used by a Syntax instance.

ContainedIn

class syntax.ContainedIn(group: 'Group'): A containedin option.

Contains

class syntax.Contains(*groups: 'Group')

Store for the syntax contains option.

Parameters

groups: list: This can optionally be initialised with one or more groups.

End

class syntax.End(pat, *pats, lidx=None, lrange=None, **options): An end pattern.

Group

class syntax.Group(syn, name, std=False, contained=False)

A named syntax group.

Parameters

syn: The Syntax instance that created this item.
name: A name for the item.
std: If true then the group is treated as not in the Syntax object’s namespace.
contained: If true then all matches, keywords and regions this creates automatically have the contained option set.

class region_type(syn: 'Syntax', syn_cmd: Callable, name: str, **options)

A context manager for adding a region to a group.

Parameters

syn: The Syntax instance that created this item.
syn_cmd: The syntax command function.
name: A name for the item.
options: Named options for the region command.

Methods

end(pat: str, *pats: str, **kwargs) → Region

Define an end pattern

Parameters

pat: str
The first part of the regular expression string.

pats: str
Additional expression strings. These are concatenated with pat to form the complete regular expression.

kwargs
Additional options for the region skip.

matchgroup(group: Group | None)

Add or remove a matchgroup directive for this region.

skip(pat: str, *pats: str, **kwargs) → Region

Define a skip pattern

Parameters

pat: str
The first part of the regular expression string.

pats: str
Additional expression strings. These are concatenated with pat to form the complete regular expression.

kwargs
Additional options for the region skip.

start(pat: str, *pats: str, **kwargs) → Region

Define a start pattern

Parameters

pat: str
The first part of the regular expression string.

pats: str
Additional expression strings. These are concatenated with pat to form the complete regular expression.

kwargs
Additional options for the region start.

Methods

add_keyword(keyword, *keywords, **options)

Add one or more keywords to this syntax group.

Parameters

keyword
The first keyword to add.

keywords
Additional keywords to add.

options
Options for the set of keywords.

add_links(*groups)

Add groups to the set that link to this group.
add_match(...)
add_match(
        pat: str,
        *pats: str,
        lidx: Optional[int] = None,
        lrange: Optional[Tuple[int, int]] = None,
Add a syntax match for this group.

Parameters

pat: str
The first part of the regular expression string.

pats: str
Additional expression strings. These are concatenated with pat to form the complete regular expression.

lidx: Optional
The index of a line to tie the match to.

lrange: Optional
A range of lines to tie the match to.

options
Additional options for the match.
add_region(...)
add_region(
        start: str,
        end: str,
        skip: Optional[str] = None,
Add a syntax region for this group.

This is only suitable for simple region definitions. Only a single start, skip and end pattern can be added. For more complex cases use a region context.

Parameters

start: str
The start pattern.

end: str
The end pattern.

skip: Optional
Optional skip pattern.

options
Additional options for the region.
highlight(**kwargs)

Define highlighting for this group.

Parameters

kwargs
These are the same as for vpe.highlight, except that group and clear should not be used.

invoke(file=None) → None

Invoke any pending syntax commands.

This is only intended to be used by a Syntax instance.

region(**options)

Create a region context manager.

This supports regions with multiple start, skip and end patterns.

Parameters

options
Additional options for the region.

set_highlight(file=None)

Set up highlight definition for this group.

GroupOption

class syntax.GroupOption(group: 'Group')

Base class for group options.

Parameters

group: A group instance.

LocationGroup

class syntax.LocationGroup(name, group)

A grouphere or groupthere option.

Parameters

name: str: The option name - ‘grouphere’ or groupthere’.
group: A group instance.

MatchGroup

class syntax.MatchGroup(group: 'Group'): A matchgroup option.

MatchGroupDirective

class syntax.MatchGroupDirective(group: Group | None)

A matchgroup directive for a region.

Methods

arg_str() → str

Format matchgroup as an directove in a region command.

NamedSyntaxItem

class syntax.NamedSyntaxItem(syn: 'Syntax', name: str, std=False)

A syntax item with an assigned name.

Parameters

syn: The Syntax instance that created this item.
name: A name for the item.
std: If true then the item is treated as not in the Syntax object’s namespace.

Properties

property arg_name → str

A suitable name when used as an argument.

property name → str

The base name of this item, without the Sytntax ojbect’s prefix.

property qual_name → str

The qualified name of this item.

It this was created with std=True then this is the same as the name. Otherwise the parent Syntax object’s namespace is assed to name as a prefix.

NextGroup

class syntax.NextGroup(group: 'Group'): A nextgroup option.

Option

class syntax.Option

Base class for the syntax command options.

Methods

vim_fmt() → str

Format the option as a string for use in a :syntax command.

Pattern

class syntax.Pattern(pat, *pats, lidx=None, lrange=None, **options)

A syntax pattern.

Parameters

pat: The first part of the regular expression string.
pats: Additional expression strings. These are concatenated with pat to form the complete regular expression.
lidx: The index of a line to tie the match to.
lrange: A range of lines to tie the match to.
options: Additional options, including pattern offsets.

Methods

arg_str() → str

Format pattern as an argument to a syntax command.

Region

class syntax.Region(syn: 'Syntax', syn_cmd: Callable, name: str, **options)

A context manager for adding a region to a group.

Parameters

syn: The Syntax instance that created this item.
syn_cmd: The syntax command function.
name: A name for the item.
options: Named options for the region command.

Methods

end(pat: str, *pats: str, **kwargs) → Region

Define an end pattern

Parameters

pat: str
The first part of the regular expression string.

pats: str
Additional expression strings. These are concatenated with pat to form the complete regular expression.

kwargs
Additional options for the region skip.

matchgroup(group: Group | None)

Add or remove a matchgroup directive for this region.

skip(pat: str, *pats: str, **kwargs) → Region

Define a skip pattern

Parameters

pat: str
The first part of the regular expression string.

pats: str
Additional expression strings. These are concatenated with pat to form the complete regular expression.

kwargs
Additional options for the region skip.

start(pat: str, *pats: str, **kwargs) → Region

Define a start pattern

Parameters

pat: str
The first part of the regular expression string.

pats: str
Additional expression strings. These are concatenated with pat to form the complete regular expression.

kwargs
Additional options for the region start.

SimpleOption

class syntax.SimpleOption(name: str, value: bool)

A simple syntax option.

Parameters

name: The option’s name.
value: If true then the option is enabled.

Methods

vim_fmt() → str

Format the option as a string for use in a :syntax command.

Skip

class syntax.Skip(pat, *pats, lidx=None, lrange=None, **options): A skip pattern.

Start

class syntax.Start(pat, *pats, lidx=None, lrange=None, **options): A start pattern.

StdCluster

class syntax.StdCluster(syn, name)

A cluster of groups, not in a Syntax object’s namespace.

Properties

property arg_name

A suitable name when used as an argument.

Methods

invoke() → None

Null operation implementation.

SyncGroup

class syntax.SyncGroup(syn, name, std=False, contained=False): A group use for synchronisation.

Syntax

class syntax.Syntax(group_prefix, clear: bool = True)

Context manager for defining syntax highlighting.

This stores a sequence of syntax highlighting directives. The directives are executed (as syntax and highlight commands) when the context is exited.

Parameters

group_prefix: A prefix added to the name of all groups created using this Syntax instance.
clear: Whether to clear any previous syntax for the current buffer. This is True by default.

class group_type(syn, name, std=False, contained=False)

A named syntax group.

Parameters

syn: The Syntax instance that created this item.
name: A name for the item.
std: If true then the group is treated as not in the Syntax object’s namespace.
contained: If true then all matches, keywords and regions this creates automatically have the contained option set.

class region_type(syn: 'Syntax', syn_cmd: Callable, name: str, **options)

A context manager for adding a region to a group.

Parameters

syn: The Syntax instance that created this item.
syn_cmd: The syntax command function.
name: A name for the item.
options: Named options for the region command.

Methods

end(pat: str, *pats: str, **kwargs) → Region

Define an end pattern

Parameters

pat: str
The first part of the regular expression string.

pats: str
Additional expression strings. These are concatenated with pat to form the complete regular expression.

kwargs
Additional options for the region skip.

matchgroup(group: Group | None)

Add or remove a matchgroup directive for this region.

skip(pat: str, *pats: str, **kwargs) → Region

Define a skip pattern

Parameters

pat: str
The first part of the regular expression string.

pats: str
Additional expression strings. These are concatenated with pat to form the complete regular expression.

kwargs
Additional options for the region skip.

start(pat: str, *pats: str, **kwargs) → Region

Define a start pattern

Parameters

pat: str
The first part of the regular expression string.

pats: str
Additional expression strings. These are concatenated with pat to form the complete regular expression.

kwargs
Additional options for the region start.

Methods

add_keyword(keyword, *keywords, **options)

Add one or more keywords to this syntax group.

Parameters

keyword
The first keyword to add.

keywords
Additional keywords to add.

options
Options for the set of keywords.

add_links(*groups)

Add groups to the set that link to this group.
add_match(...)
add_match(
        pat: str,
        *pats: str,
        lidx: Optional[int] = None,
        lrange: Optional[Tuple[int, int]] = None,
Add a syntax match for this group.

Parameters

pat: str
The first part of the regular expression string.

pats: str
Additional expression strings. These are concatenated with pat to form the complete regular expression.

lidx: Optional
The index of a line to tie the match to.

lrange: Optional
A range of lines to tie the match to.

options
Additional options for the match.
add_region(...)
add_region(
        start: str,
        end: str,
        skip: Optional[str] = None,
Add a syntax region for this group.

This is only suitable for simple region definitions. Only a single start, skip and end pattern can be added. For more complex cases use a region context.

Parameters

start: str
The start pattern.

end: str
The end pattern.

skip: Optional
Optional skip pattern.

options
Additional options for the region.
highlight(**kwargs)

Define highlighting for this group.

Parameters

kwargs
These are the same as for vpe.highlight, except that group and clear should not be used.

invoke(file=None) → None

Invoke any pending syntax commands.

This is only intended to be used by a Syntax instance.

region(**options)

Create a region context manager.

This supports regions with multiple start, skip and end patterns.

Parameters

options
Additional options for the region.

set_highlight(file=None)

Set up highlight definition for this group.

class sync_group_type(syn, name, std=False, contained=False): A group use for synchronisation.

Methods

cluster(name, *add_groups)

Create a cluster within this syntax object’s namespace.

Parameters

name
The cluster’s name.

fmt_group(name: str) → str

Format the name of a group, adding the Syntax object’s prefix.

Parameters

name: str
The name of the group.

group(name, link_to=None, **options)

Create a group within this syntax object’s namespace.

Parameters

name
The group’s name.

link_to
The full name of a group to link to.

options
Options for the group.

include(name)

Do a simple include of syntax file.

The command executed is: runtime syntax/name.vim

Parameters

name
The syntax name.

preview_last() → str

Generate preview string of the last scheduled command.

This can be useful during debugging a new syntax.

schedule(func, *args, **kwargs)

Add a syntax command to those scheduled for later execution.

Parameters

func
The syntax command function.

args
Positional arguments for the command.

kwargs
Keyword arguments for the command.

std_cluster(name)

Create a standard (externally defined) cluster.

Parameters

name
The cluster’s full name.

std_group(name)

Create a standard (externally defined) group.

Parameters

name
The group’s full name.

sync_group(name, **options)

Create a sync group within this syntax object’s namespace.

Parameters

name
The group’s name.

options
Options for the group.

SyntaxBase

class syntax.SyntaxBase

Base class for various syntax support classes.

Static methods

static get_offsets(...)
get_offsets(
        options: dict,
        offset_names: Iterable[str]
Extract the offset arguments from keyword options.

Parameters

options: dict
A dictionary of options.

offset_names: Iterable
The offset option names to extract.

Return value

A tuple of the extracted offsets and the remaining options. The offsets value is a string of the form name=value[,…], ready to use in the Vim syntax command.

convert_syntax_options

syntax.convert_syntax_options(syn, options) → dict

Convert values in a dictionary of option to Option instances.

Parameters

options: The dictionary containing keyword defined options.

Return value

The same (modified in place) dictionary.

deliminate

syntax.deliminate(pat: str) → str

Put deliminators around a syntax expression.

If reasonably sensible, a deliminator that is not part of the pattern is used. If this is not possible then the double quote character is used and any double quotes within the pattern are escaped with a backslash.

Parameters

pat: str: The pattern to be deliminated.

extract_keys

syntax.extract_keys(source_dict: dict, *keys: Any) → dict

Extract a set of named items from a dictionary.

Any item in source_dict that has a key contained in keys is moved to a new dictionary.

Parameters

source_dict: dict: The dictionary from which to extract the items.
keys: Any: The keys for the items to extract.

Return value

A new dictionary containing the items remove from the source_dict.