Constraint Implementation¶Tip
You may check how built-in Constraints are implemented here.
You may create your own custom Constraint implementation by following steps.
AutoSetSyntax: Create New Constraint from the command palette1.It will create a template like
Example
from __future__ import annotations
+
+import sublime
+from AutoSetSyntax.plugin import AbstractConstraint
+
+
+class MyOwnConstraint(AbstractConstraint):
+ """Your custom `Constraint` must inherit `AbstractConstraint` and implement the `test` method."""
+
+ def is_droppable(self) -> bool:
+ # Optionally, you can implement `is_droppable` to indicate that this object
+ # can be dropped under certain circumstances by the optimizer.
+ return False
+
+ def test(self, view: sublime.View) -> bool:
+ # Your job is to implement this function, at least.
+ # This function tests the `view`.
+ # There is a @staticmethod which returns cached contexts for using.
+ # def get_view_snapshot(view: sublime.View) -> ViewSnapshot: ...
+ return False
+Tip
There is a get_view_snapshot method, which accepts an sublime.View as an argument and returns a ViewSnapshot object. In the object, there are some cached information about the current view to provide a uniform format and prevent from calling resource-consuming function calls several times among rules.
@dataclass
+class ViewSnapshot:
+ id: int
+ """View ID."""
+ char_count: int
+ """Character count."""
+ content: str
+ """Pseudo file content."""
+ file_name: str
+ """The file name. Empty string if not on a disk."""
+ file_name_unhidden: str
+ """The file name without prefixed dots. Empty string if not on a disk."""
+ file_path: str
+ """The full file path with `/` as the directory separator. Empty string if not on a disk."""
+ file_size: int
+ """In bytes, -1 if file not on a disk."""
+ first_line: str
+ """Pseudo first line."""
+ line_count: int
+ """Number of lines in the original content."""
+ syntax: sublime.Syntax | None
+ """The syntax object. Note that the value is as-is when it's cached."""
+Decide the constraint name of your Constraint.
Say, if your class name is MyOwnConstraint, the constraint name is decided by
Constraint suffix from the class name. (MyOwnConstraint » MyOwn)MyOwn » my_own)That is, you can use it via "constraint": "my_own" in a constraint rule.
At least, implement the test method.
Save your implementation in Packages/AutoSetSyntax-Custom/constraints/. Conventionally, the file name used is the constraint name, my_own.py.
Restart ST and check whether your implementation is loaded via Debug Information.
Command palette: Ctrl+P for Windows/Linux. Cmd+P for macOS. ↩
Match Implementation¶Tip
You may check how built-in Matches are implemented here.
You may create your own custom Match implementation by following steps.
AutoSetSyntax: Create New Match from the command palette1.It will create a template like
Example
from __future__ import annotations
+
+import sublime
+from AutoSetSyntax.plugin import AbstractMatch, MatchableRule
+
+
+class MyOwnMatch(AbstractMatch):
+ """Your custom `Match` must inherit `AbstractMatch` and implement the `test` method."""
+
+ def is_droppable(self, rules: tuple[MatchableRule, ...]) -> bool:
+ # Optionally, you can implement `is_droppable` to indicate that this object
+ # can be dropped under certain circumstances by the optimizer.
+ return False
+
+ def test(self, view: sublime.View, rules: tuple[MatchableRule, ...]) -> bool:
+ # Your job is to implement this function, at least.
+ # This function tests `rules` (mix of `ConstraintRule`s and `MatchRule`s).
+ return False
+Decide the match name of your Match.
Say, if your class name is MyOwnMatch, the match name is decided by
Match suffix from the class name. (MyOwnMatch » MyOwn)MyOwn » my_own)That is, you can use it via "match": "my_own" in a match rule.
At least, implement the test method.
Save your implementation in Packages/AutoSetSyntax-Custom/matches/. Conventionally, the file name used is the match name, my_own.py.
Restart ST and check whether your implementation is loaded via Debug Information.
Command palette: Ctrl+P for Windows/Linux. Cmd+P for macOS. ↩
When AutoSetSyntax is loaded or plugin/project settings updated, AutoSetSyntax runs following procedures.
Match / Constraint implementations.AutoSetSyntax has some event listeners (see listener.py) which tests syntax rules by calling SyntaxRuleCollection.test(...) under certain circumstances.
Before SyntaxRuleCollection.test(...) runs, ViewSnapshot takes a snapshot of the view and that snapshot will be used in this whole run to prevent from calling expensive APIs among syntax rules.
When SyntaxRuleCollection.test(...) runs, syntax rules in it are tested in the order as they are defined in settings. If there is a syntax rule matches, the test ends and the syntax of the view will be set to the one defined in the syntax rule.
Merged settings are per-window. They are generated by merging plugin settings with project settings.
Info
Settings precedence: Project settings > User settings > Default settings
plugin/rules/constraints/__init__.py)_load_custom_implementations())This step compiles merged settings into a SyntaxRuleCollection object. All necessary objects are created in this step (and re-used in the future) rather than when rules are tested every time.
This step optimizes the compiled SyntaxRuleCollection object by calling its optimize method.
Currently, it drops invalid rules (like object with invalid args) and unreachable rules. is_droppable functions in Matches and Constraints are evaluated to decide whether it can be dropped or not.