ScriptSyntaxModel

public interface ScriptSyntaxModel

Model representation of build script files.

Script models are used to retrieve various informations from scripts. They are most commonly used by IDEs to provide syntax highlight, content assist, and related features. Script models can also be used outside of an IDE.

Script models are created with parsing options which can contain user-specified configuration data. They are also passed a IOSupplier<? extends ByteSource> instance which serves as the input of the underlying build script file. This is called the base input.

The base input should be used as a baseline for retrieving the source data of the build script file. As the models can be used inside IDEs, there is a possibility that the current representation of the build script file doesn't match the one on the file system. In this case the models should be able to handle the scenario when they don't use this base input for the source data of the script file. Methods which should handle this scenario has a replacement data supplier parameter. (See createModel(IOSupplier<? extends ByteSource>), updateModel(List<? extends TextRegionChange>, IOSupplier<? extends ByteSource>))

Models are not required to support all information querying methods, they might return null or empty collections.

Script models have a state depending on the current state of input.
When the model is first created, it is in uninitialized state. When some information query method is called, models should attemt to parse the base input and provide the information based on that.
If the model failed to parse the input script, then it is in invalid state. In this state information query methods can return empty results, but may not throw an exception due to the model being in invalid state.
If any of the updating methods return successfully, the model will be in a valid state. A valid state only means that the model implementation was able to create a representation of the data conveyed in the build script, but doesn't mean that the underlying script is safe to be a subject of build execution. Model and script language implementations should strive to be error-tolerant.

When a model is in a valid state, subsequent updateModel(List<? extends TextRegionChange>, IOSupplier<? extends ByteSource>) calls can be used to incrementally update the model by providing a list of incremental changes to the underlying source data of the build script. This is mainly used when the user is editing a build script in the IDE. Models are not required to support updating the model incrementally.

Models provide some information based on tokens. Tokens are non-overlapping regions of source code that have specified properties based on the model implementation. Via tokens, models can provide syntax highlighting, and general information about them.

Models can provide a structure outline for themselves, which is a tree representation of the model source code.

During IDE use the users will expect content assistant features to be present. With getCompletionProposals(int) method the models can provide a list of source code completions which are then displayed to the user.

Models can (and recommended to) use the ExternalScriptInformationProvider interface to retrieve informational data based on the current build configuration. Instances of these interfaces are avaiable from the script modelling environment configuration by calling ScriptModellingEnvironment.getConfiguration().getExternalScriptInformationProviders(). Models should not keep references to these information providers, but query them every time it would like to use them, as they might change during the lifetime of the model.
Models can also use the ScriptModellingEnvironmentConfiguration.getPathConfiguration() of the same configuration instance to provide assistant features for the user based on file data. Same with external information providers, do not keep references to the path configuration, or file providers.

Methods

public void	createModel(IOSupplier<? extends ByteSource> scriptdatasupplier) Creates the model for the given data input.
public default Collection<? extends BuildTargetInformation>	getBuildTargets() Gets information about the build targets in the script file.
public default List<? extends ScriptCompletionProposal>	getCompletionProposals(int offset) Gets a list of completion proposals which can be applied to the text at the given character offset.
public ScriptParsingOptions	getParsingOptions() Gets the script parsing options used to create this model.
public default ScriptStructureOutline	getStructureOutline() Gets the structural outline for this script model.
public default Set<String>	getTargetNames() Use getBuildTargets() instead.
public default ScriptToken	getTokenAtOffset(int offset) Gets the script token at the given offset.
public default ScriptTokenInformation	getTokenInformation(ScriptToken token) Queries the information about a particular token.
public default Map<String, Set<? extends TokenStyle>>	getTokenStyles() Gets the token styles used by this model.
public default Iterable<? extends ScriptToken>	getTokens(int offsethint, int lengthhint) Gets the script tokens for a given range of the document.
public void	invalidateModel() Invalidates the model, resets it to the uninitialized state.
public default void	updateModel(List<? extends TextRegionChange> events, IOSupplier<? extends ByteSource> scriptdatasupplier) Updates the model incrementally for the specified list of text changes occurred since the last successful update.

public abstract void createModel(IOSupplier<? extends ByteSource> scriptdatasupplier) throws IOException, ScriptParsingFailedException

Creates the model for the given data input.

Implementations should parse the provided input and build the model data required for operation of this class.

The argument input supplier may be null, in which case implementations should use the base input supplier passed during instantiation to parse the data.

scriptdatasupplierThe script data supplier or null to use the base input supplier.

IOExceptionIn case of I/O error.

ScriptParsingFailedExceptionIf the parsing of the script failed.

public default Collection<? extends BuildTargetInformation> getBuildTargets() throws ScriptParsingFailedException, IOException

Gets information about the build targets in the script file.

Note that in some cases, the returned collection is allowed to contain multiple different build targets with the same name, as the script can be in an inconsistent state during editing.

Implementations are recommended to return the build targets in order of their declarations if possible. Clients may sort them in any way they see fit if needed.

The collection of build targets.

ScriptParsingFailedExceptionIf the parsing of the script failed.

IOExceptionIn case of I/O error.

saker.build 0.8.18

public default List<? extends ScriptCompletionProposal> getCompletionProposals(int offset)

Gets a list of completion proposals which can be applied to the text at the given character offset.

offsetThe character offset in the file.

An unmodifiable list of completion proposals.

public abstract ScriptParsingOptions getParsingOptions()

Gets the script parsing options used to create this model.

This doesn't change during the lifetime of the model.

The script parsing options.

public default ScriptStructureOutline getStructureOutline()

Gets the structural outline for this script model.

The structure outline is usually displayed in a tree view alongside the code in the IDE.

The structure outline.

@Deprecated

public default Set<String> getTargetNames() throws ScriptParsingFailedException, IOException

Use getBuildTargets() instead.

Gets the build target names in this script.

If the model is in an invalid state, it should attempt to parse it using the base input.

An unmodifiable set of target names.

ScriptParsingFailedExceptionIf the parsing of the script failed.

IOExceptionIn case of I/O error.

public default ScriptToken getTokenAtOffset(int offset)

Gets the script token at the given offset.

As script token doesn't overlap, this method should uniquely identify the token that is at a given offset.

If the offset is located at the edge of two token ranges, then the implementation may choose which token it wants to return (left or right). They can choose, but they are encouraged to be consistent with this choosing. (I.e. always return the left token or always the right when the offset is exactly between two tokens).

If there are more than two tokens at a given offset (due to 0 length tokens), the tokens which has a length greater than 0 should be returned.

Implementations can return null if no token is found at the given offset.

The default implementation searches the tokens returned by getTokens(int, int) and returns an appropriate one. (It returns the left token if the offset is at the edges, and searches for a token with greater than 0 length if there are more.)

offsetThe offset to get the token for.

The token at the given offset or null if not found.

getTokens(int, int)

public default ScriptTokenInformation getTokenInformation(ScriptToken token)

Queries the information about a particular token.

The token informations are usually displayed when the user hovers over a given token in the code editor, or explicitly requests information about it.

tokenThe token to get the information for.

The token information or null if not available.

public default Map<String, Set<? extends TokenStyle>> getTokenStyles()

Gets the token styles used by this model.

The token styles are mapped to the token types, and contain a set of applicable styles. The applied style will be chosen on the current theme of the IDE.

The result should contain all styles the script model may contain. Callers of this method may cache the returned token styles in order to avoid calling this method multiple times.

An unmodifiable map of token styles.

public default Iterable<? extends ScriptToken> getTokens(int offsethint, int lengthhint)

Gets the script tokens for a given range of the document.

This method returns the tokens in the order sorted by their starting offset.

The offset and length hint parameters can be used to only return a subset of the tokens. Implementations aren't required to always satisfy the range request, but they can to reduce computational load. All tokens should be returned which intersect (or touch) a given token region.

To get all tokens, pass 0, and Integer.MAX_VALUE as region hints.

The returned token regions should not overlap.

offsethintThe character offset hint for the starting region of the tokens.

lengthhintThe length of the hint region.

An iterable for the script tokens.

public abstract void invalidateModel()

Invalidates the model, resets it to the uninitialized state.

Implementations are to discard any internal state when this method is called and rebuild it from the input next time some information is requested from the model.

public default void updateModel(List<? extends TextRegionChange> events, IOSupplier<? extends ByteSource> scriptdatasupplier) throws IOException, ScriptParsingFailedException

Updates the model incrementally for the specified list of text changes occurred since the last successful update.

This method takes a list of changes as a parameter, which describe what text related changes occurred to the document since the last successful update. The list is ordered historically, meaning that the first item is the first change that occurred to the text after the last successful update. The offsets in the TextRegionChange structure are relative to the directly previous state of the source document. Meaning, that unlike ScriptCompletionProposal, the text changes can be applied after each other to the starting document to get the current state.

This method might be called even when createModel(IOSupplier<? extends ByteSource>) has not yet been called before, or the parsing wasn't successful. Implementations should gracefully handle this scenario, use the provided data supplier for retrieving the whole contents of the source code, and parse the code based on that.

The default implementation of this method simply calls createModel(IOSupplier<? extends ByteSource>) with the provided supplier.

eventsThe text change events in sequential order.

scriptdatasupplierThe data supplier for the whole contents of the script.

IOExceptionIn case of I/O error.

ScriptParsingFailedExceptionIf the parsing/updating of the script failed.