Custom Constraint Implementation¶

You may create your own custom Constraint implementation by following steps.

1. Run AutoSetSyntax: Create New Constraint from the command palette¹.

2. It will create a template like

   Example

   from AutoSetSyntax.plugin import UNFOLDED
   from AutoSetSyntax.plugin import AbstractConstraint
   from AutoSetSyntax.plugin import Fold
   from AutoSetSyntax.plugin import ViewSnapshot
   
   
   class MyOwnConstraint(AbstractConstraint):
       """Your custom `Constraint` must inherit `AbstractConstraint` and implement the `test` method."""
   
       def fold(self) -> Fold:
           # Optionally, you can implement `fold` to tell the optimizer that this object's
           # arguments already settle the answer, so it needn't be tested on every view:
           # return `Fold(True/False, "why")` for the constant `test` would always return, or
           # `UNFOLDED` when the result still depends on the view.
           # The reason is shown to the user in the dropped-rules report, so phrase it for them,
           # e.g. `Fold(False, "no extension was given")`.
           return UNFOLDED
   
       def test(self, view_snapshot: ViewSnapshot) -> bool:
           # Your job is to implement this function, at least.
           # This function tests the `view_snapshot`.
           return False
   

3. Decide the constraint name of your Constraint.

   Say, if your class name is MyOwnConstraint, the constraint name is decided by

   1. Remove Constraint suffix from the class name. (MyOwnConstraint » MyOwn)
   2. Convert it into snake case. (MyOwn » my_own)

   That is, you can use it via "constraint": "my_own" in a constraint rule.

4. At least, implement the test method.

   Optionally:

   • Override fold() to let the optimizer drop the constraint when its arguments already settle the answer (see how it works).
   • Set needs_file = True (or needs_syntax = True) if the constraint is meaningless for an unsaved buffer (or a view without a syntax). It then fails without being inverted by inverted.
   • Raise AlwaysTruthyException or AlwaysFalsyException (from AutoSetSyntax.plugin.rules.constraint) in test() to force the verdict regardless of inverted.
   • Save your implementation in Packages/AutoSetSyntax-Custom/constraints/. Conventionally, the file name used is the constraint name, my_own.py.

5. Restart ST and check whether your implementation is loaded via Debug Information.