Local Variable Type Hints

[APickledWalrus]

Problem

Local variables are essentially accepted wherever they are used. This results in more potential mistakes and (some) strange syntax behavior that is hard to track. Detailed type information for variables helps in two cases:

1. Mismatched types

It's possible you use the wrong variable somewhere. Detailed type information can catch this and print a warning (or error). Consider:

set {_a} to 5
set {_b} to "some string"
... do stuff ...
set {_c} to {_a} in lowercase # oops i used the wrong variable

We can catch that {_a} in lowercase is likely to be invalid and alert the user.

2. Syntax accepting objects

Consider syntax like ExprArithmetic:

set {_a} to "some string"
set {_b} to 1 + {_a}

With detailed type information, we can now identify at parse time that this is an invalid operation, instead of failing at runtime and returning none.

Solution

With systems like ExecutionIntent and multiple return types, we are finally in a position to execute this system well. Type tracking for local variables has been implemented across syntax interacting with variables using a HintManager that is attached to the ParserInstance.

The testing script along with HintManager's documentation provide insight into how hints are managed.

As of now, I believe this system is accurate enough for type issues to be errors rather than warnings. However, there are still scenarios where type hints will fail:

loop x times:
  if ...:
    set {_x} to 10
  if ...:
    # will only see {_x} as a number
    set {_x} to x in lowercase
    # do some terminating statement idk
  if ...:
    set {_x} to "hello world"

That is, variables in loops whose types are changing across iterations may trigger false-positive errors (in rare cases hidden type changes could cause erroneous runtime failures). To work around this, it is possible to [un]suppress type hints (for a statement or block of code) using a new statement. We may also consider putting this behind an experiment as we continue to improve upon it (maybe whether it's an error?). Variables that cannot have hints and variables that do not have any hints act the same as they do now.

Variables have also been reworked here. When variables are passed to patterns request objects, the possible return types of the variable is simply an array of the known hints. Additionally, when variables are passed to patterns requesting some combination of types, the possible return types of the variable is the intersection of the hints and requested types.

I believe the system is accurate and stable, but further testing is needed. As a result, I have elected to put this behind an experiment. Additionally, it is possible to suppress type hints (in scripts where the experiment is enabled) for specific regions of code.

Change Explanations

• Fixed an issue where the experimentRegistry (in Skript) was set to null too soon - it could be null even when more script code could run (consider on stop triggers)
• Added getName to arguments. This is used for providing type hints for named command arguments.
• Fixed an issue where EffReturn would return an incorrect ExecutionIntent for Functions. It needed to be using StopTrigger as the ReturnableTrigger is stopped in Functions when return is executed.
• Added EntryNode as a possible return type for ExprNode. This is for ensuring type hints work properly for the syntax.
• Added beforeChange runnable for loading sections into triggers. This was necessary for proper type hint implementation for these syntaxes. We need to be able to capture the hints and then merge them in once the trigger is loaded (since we copy variables at runtime).
• Now that some variables may have accurate return types, Variable#getConvertedExpression has been updated to restrict what conversions are allowed on those variables.
• Fixed an issue where Classes#getSuperClassInfo was not guaranteed to return the exact ClassInfo if one existed.
• I added a new class, SectionUtils, which includes a static utility method for loading a section's code into a Trigger. More specifically, it handles the type of behavior that is becoming more common: Loading a section into a Trigger to use different context/events, preventing delays, and copying local variables at runtime. With type hints, the need to copy type hints arose, and the behavior became far more complicated. This method serves to handle that behavior and reduce the effort needed by the increasing number of implementing classes.

API Support

Addon developers may need to support this feature if their syntax modifies variables (and results in type changes). First, you can use the HintManager to check if a Variable can use hints:

if (HintManager.canUseHints(variable)) {
    // safe to manage hints
}

If so, you can obtain the active HintManager using the ParserInstance:

ParserInstance.get().getHintManager();

Then, depending on what type of operation your syntax is performing, you can manage hints as necessary:

HintManager hintManager = ParserInstance.get().getHintManager();
// setting the hints (clears previous hints)
hintManager.set(variable, SomeType.class);
// adding a hint
hintManager.add(variable, SomeType.class);
// clearing hints (e.g. `delete {_var}`)
hintManager.delete(variable);

Testing Completed

I have added a basic type hints.sk test (more to come). I plan to implement JUnit testing for HintManager.

Supporting Information

Depends on:

• Return type accuracy and usage improvements #7891

---

Completes:

• Local variable type hints. Helps identify local variable return types #3864
• Variables can be used as function arguments of the wrong type #1229

Related:

• Fix Syntax Removal #7879 (syntax conflicts (due to variables) would benefit from type hints)

[Absolutionism]

Looks good to me.
also I think EffZombify may be applicable for hint changing

[sovdeeth]

looking good to me