Package ch.njol.skript.variables

Class HintManager

java.lang.Object

ch.njol.skript.variables.HintManager

@Experimental
public class HintManager
extends Object

Used for managing local variable type hints during the parsing process.

Hint Tracking

Type hints are tracked in scopes which are generally equivalent to sections. However, there may be additional scopes that are not associated with sections. These scopes may be used for a variety of reasons. For example, a non-section scope could be used for capturing the hints of a section. These hints could be filtered before being passed back up.

When entering a scope (enterScope(boolean)), it is initialized with the hints of the previous top-level scope. When exiting a scope (exitScope()), remaining hints from that scope are added to the existing hints of the new top-level scope. This merging of scopes is provided and described by mergeScope(int, int, boolean). Thus, it is only necessary to obtain hints for the current scope. get(Variable) is provided for obtaining the hints of a variable in the current scope.

It is possible to disable the collection and usage of hints through the activity state of a manager. See setActive(boolean) and isActive for detailed information.

Hint Modification

The standard syntax where hints are modified is the Change Effect (EffChange). Consider the following basic SET example:

 
 set {_x} to 5
 # hint for {_x} is Integer.class
 
 

A SET operation overrides all existing type hints for a variable in the current scope (see set(Variable, Class[])). In a more advanced example, we can see how hints are shared between scopes:

 
 set {_x} to 5
 # hint for {_x} is Integer.class
 if <some condition>:
   set {_x} to true
   # hint for {_x} is Boolean.class
 # here, it is not known if the section above would have executed
 # we consider all possible values
 # thus, hints for {_x} are Integer.class and Boolean.class
 
 

ADD is another considered operation (see add(Variable, Class[])). Consider the following example:

 
 add 5 to {_x::*}
 # hint for {_x::*} is Integer.class
 
 

Essentially, an ADD operation is handled similarly to a SET operation, but hints are combined rather than overridden, as the list may contain other types. Note that REMOVE is not a handled operation, as a list variable might contain multiple values of some type. However, for use cases where applicable, remove(Variable, Class[]) is provided. Finally, a DELETE operation (see delete(Variable)) allows us to trim down context where applicable. Consider the following examples:

 
 set {_x} to 5
 # hint for {_x} is Integer.class
 delete {_x}
 # now, there are no hints for {_x}
 
 

 
 set {_x} to 5
 # hint for {_x} is Integer.class
 if <some condition>:
   delete {_x}
   # now, there are no hints for {_x}
 # the previous section no longer had hints for {_x}, so there is nothing to copy over
 # thus, hint for {_x} is Integer.class
 
 

See Also:

• ParserInstance.getHintManager()

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	HintManager.Backup	Represents a snapshot of a scope.

Constructor Summary

Constructors

Constructor	Description
HintManager(boolean active)

Method Summary

Modifier and Type	Method	Description
void	add(Variable<?> variable, Class<?>... hints)	Adds hints for variable in the current scope.
void	add(String variableName, Class<?>... hints)	Adds hints for variableName in the current scope.
HintManager.Backup	backup()
static boolean	canUseHints(Variable<?> variable)
void	clearScope(int level, boolean sectionOnly)	Resets (clears) all type hints for the current (top-level) scope.
void	delete(Variable<?> variable)	Deletes hints for variable in the current scope.
void	delete(String variableName)	Deletes hints for variableName in the current scope.
void	enterScope(boolean isSection)	Enters a new scope for storing hints.
void	exitScope()	Exits the current (top-level) scope.
@Unmodifiable Set<Class<?>>	get(Variable<?> variable)	Obtains the type hints for variable in the current scope.
@Unmodifiable Set<Class<?>>	get(String variableName)	Obtains the type hints for variableName in the current scope.
boolean	isActive()
void	mergeScope(int from, int to, boolean sectionOnly)	Copies hints from one scope to another.
void	remove(Variable<?> variable, Class<?>... hints)	Removes hints for variable in the current scope.
void	remove(String variableName, Class<?>... hints)	Removes hints for variableName in the current scope.
void	restore(HintManager.Backup backup)	Overwrites the current scope with the scope represented in backup.
void	set(Variable<?> variable, Class<?>... hints)	Overrides hints for variable in the current scope.
void	set(String variableName, Class<?>... hints)	Overrides hints for variableName in the current scope.
void	setActive(boolean active)	Marks this hint manager as active or inactive.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

HintManager

public HintManager(boolean active)

Method Details

setActive

public void setActive(boolean active)

Marks this hint manager as active or inactive. An inactive hint manager does not collect hints. That is, actions such as setting, adding, etc. have no effect on the currently stored hints. Additionally, any calls to obtain hints will always result in an empty collection. As a result, type hints are effectively not used.

Parameters:

active - Whether this hint manager should be active.

See Also:

• isActive

isActive

public boolean isActive()

Returns:

Whether this manager is active.

See Also:

• setActive(boolean)

enterScope

public void enterScope(boolean isSection)

Enters a new scope for storing hints. Hints from the previous (current top-level) scope are copied over.

Parameters:

isSection - Whether this scope represents a section in a trigger.

See Also:

• exitScope()

exitScope

public void exitScope()

Exits the current (top-level) scope. Hints from the exited scope will be copied over to the new top-level scope.

See Also:

• enterScope(boolean)

clearScope

public void clearScope(int level,
 boolean sectionOnly)

Resets (clears) all type hints for the current (top-level) scope. Scopes are represented as integers, where 0 represents the most recently entered scope. For example, after calling enterScope(boolean), 0 would represent the scope just entered by calling the method, and 1 would represent the most recently entered scope before calling the method.

Parameters:

sectionOnly - Whether only scopes representing sections should be considered.

mergeScope

public void mergeScope(int from,
 int to,
 boolean sectionOnly)

Copies hints from one scope to another. Scopes are represented as integers, where 0 represents the most recently entered scope. For example, after calling enterScope(boolean), 0 would represent the scope just entered by calling the method, and 1 would represent the most recently entered scope before calling the method.

Note: This does not overwrite the existing hints of to. Instead, the hints are merged together.

Parameters:

from - The scope to copy hints from.

to - The scope to copy hints to.

sectionOnly - Whether only scopes representing sections should be considered.

set

public void set(Variable<?> variable,
 Class<?>... hints)

Overrides hints for variable in the current scope.

Parameters:

variable - The variable to set hints for.

hints - The hint(s) to set for variable.

See Also:

• set(String, Class[])

set

public void set(String variableName,
 Class<?>... hints)

Overrides hints for variableName in the current scope.

Parameters:

variableName - The name of the variable to set hints for.

hints - The hint(s) to set for variableName.

See Also:

• set(Variable, Class[])

delete

public void delete(Variable<?> variable)

Deletes hints for variable in the current scope.

Parameters:

variable - The variable to clear hints for.

See Also:

• delete(String)

delete

public void delete(String variableName)

Deletes hints for variableName in the current scope.

Parameters:

variableName - The name of the variable to clear hints for.

See Also:

• delete(Variable)

add

public void add(Variable<?> variable,
 Class<?>... hints)

Adds hints for variable in the current scope.

Parameters:

variable - The variable to add hints to.

hints - The hint(s) to add for variable.

See Also:

• add(String, Class[])

add

public void add(String variableName,
 Class<?>... hints)

Adds hints for variableName in the current scope.

Parameters:

variableName - The name of the variable to add hints to.

hints - The hint(s) to add for variableName.

See Also:

• add(Variable, Class[])

remove

public void remove(Variable<?> variable,
 Class<?>... hints)

Removes hints for variable in the current scope.

Parameters:

variable - The variable to remove hints from.

hints - The hint(s) to remove for variable.

See Also:

• remove(String, Class[])

remove

public void remove(String variableName,
 Class<?>... hints)

Removes hints for variableName in the current scope.

Parameters:

variableName - The name of the variable to add hints to.

hints - The hint(s) to remove for variableName.

See Also:

• remove(Variable, Class[])

get

public @Unmodifiable Set<Class<?>> get(Variable<?> variable)

Obtains the type hints for variable in the current scope.

Parameters:

variable - The variable to get hints from.

Returns:

An unmodifiable set of hints.

See Also:

• get(String)

get

public @Unmodifiable Set<Class<?>> get(String variableName)

Obtains the type hints for variableName in the current scope.

Parameters:

variableName - The name of the variable to get hints from.

Returns:

An unmodifiable set of hints.

See Also:

• add(Variable, Class[])

backup

public HintManager.Backup backup()

Returns:

A backup of this manager's current scope.

restore

public void restore(HintManager.Backup backup)

Overwrites the current scope with the scope represented in backup.

Parameters:

backup - The backup to apply.

canUseHints

public static boolean canUseHints(Variable<?> variable)

Parameters:

variable - The variable to check.

Returns:

Whether hints can be used for variable.