Module vpe.syntax¶
A pythonic API for creating syntax highlighting definitions.
Cluster¶
-
class
vpe.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
(...)¶ add( group1: Union[vpe.syntax.Group, str], *groups: Union[vpe.syntax.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: typing.Union[vpe.syntax.Group, str]
The first group to be added.
- groups: typing.Union[vpe.syntax.Group, str]
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 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.
Contains¶
-
class
vpe.syntax.
Contains
(*groups: Group)¶ Store for the syntax contains option.
Parameters
- groups: typing.List[vpe.syntax.Group]
This can optionally be initialised with one or more groups.
Group¶
-
class
vpe.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 automtically have the contained option set.
-
class
region_type
(syn: Syntax, syn_cmd: typing.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.
-
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 tkeyword to add.
- keywords
Additional tkeywords 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, **options)
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: typing.Optional[int]
The index of a line to tie the match to.
- lrange: typing.Optional[typing.Tuple[int, int]]
A range of lines to tie the match to.
- options
Additional options for the match.
-
add_region
(start: str, end: str, skip: Optional[str] = None, **options)¶ 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: typing.Optional[str]
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 thatgroup
andclear
should not be used.
-
invoke
() → 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
()¶ Set up highlight definition for this group.
GroupOption¶
-
class
vpe.syntax.
GroupOption
(group: Group)¶ Base class for group options.
Parameters
- group
A group instance.
LocationGroup¶
-
class
vpe.syntax.
LocationGroup
(name, group)¶ A grouphere or groupthere option.
Parameters
- name: str
The option name - ‘grouphere’ or groupthere’.
- group
A group instance.
NamedSyntaxItem¶
Option¶
Pattern¶
-
class
vpe.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 ayntax command.
Region¶
-
class
vpe.syntax.
Region
(syn: Syntax, syn_cmd: typing.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.
-
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¶
StdCluster¶
SyncGroup¶
-
class
vpe.syntax.
SyncGroup
(syn, name, std=False, contained=False)¶ A group use for synchronisation.
Syntax¶
-
class
vpe.syntax.
Syntax
(group_prefix)¶ 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.
-
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 automtically have the contained option set.
-
class
region_type
(syn: Syntax, syn_cmd: typing.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.
-
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 tkeyword to add.
- keywords
Additional tkeywords 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, **options)
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: typing.Optional[int]
The index of a line to tie the match to.
- lrange: typing.Optional[typing.Tuple[int, int]]
A range of lines to tie the match to.
- options
Additional options for the match.
-
add_region
(start: str, end: str, skip: Optional[str] = None, **options)¶ 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: typing.Optional[str]
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 thatgroup
andclear
should not be used.
-
invoke
() → 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
()¶ 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.
-
class
SyntaxBase¶
-
class
vpe.syntax.
SyntaxBase
¶ Base class for various syntax support classes.
Static methods
-
static
get_offsets
(...)¶ get_offsets( options: dict, offset_names: Iterable[str] ) -> Tuple[str, dict]
Extract the offset arguments from keyword options.
Parameters
- options: dict
A dictionary of options.
- offset_names: typing.Iterable[str]
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.
-
static
convert_syntax_options¶
deliminate¶
-
vpe.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¶
-
vpe.syntax.
extract_keys
(source_dict: dict, *keys: typing.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: typing.Any
The keys for the items to extract.
Return value
A new dictionary containing the items remove from the source_dict.