Package com.blamejared.crafttweaker.api.zencode

Interface IPreprocessor

All Superinterfaces:
Comparator<IScriptFile>
All Known Implementing Classes:
DebugPreprocessor, EndIfPreprocessor, LoaderPreprocessor, LoadFirstPreprocessor, LoadLastPreprocessor, ModLoadedPreprocessor, ModLoaderPreprocessor, ModNotLoadedPreprocessor, NoBrandPreprocessor, NoLoadPreprocessor, OnlyIfPreprocessor, PriorityPreprocessor, ReplacePreprocessor
public interface IPreprocessor extends Comparator<IScriptFile>
Identifies a preprocessor for an IScriptFile.

A preprocessor is a piece of code that reads the contents of the file and modifies them according to various instructions present in the file itself. Each preprocessor instruction starts with a pound sign (#), followed by the name of the preprocessor and optional arguments. The line on which the pound sign is located, along with the name and the arguments identify a preprocessor match.

A preprocessor is allowed to modify the contents of the file, edit the information for the current run, change the order in which script files will be evaluated, and prevent a script from loading.

Since:
9.1.0

  • Field Details

    • PREPROCESSOR_PATTERN

      static final Pattern PREPROCESSOR_PATTERN
      Pattern that identifies the structure of a preprocessor instruction.
      Since:
      9.1.0

    • PREPROCESSOR_LOGGER

      static final org.apache.logging.log4j.Logger PREPROCESSOR_LOGGER
      Logger that can be used within a preprocessor to log messages.
      Since:
      11.0.0

  • Method Details

    • name

      String name()
      Gets the name of the preprocessor.

      It is illegal for a preprocessor name to contain spaces. It is also customary, although not required, for the preprocessor name to be all lowercase.

      It is not allowed to specify the pound symbol as part of the name.

      Returns:
      The name of the preprocessor.
      Since:
      9.1.0

    • preprocessorEndMarker

      default String preprocessorEndMarker()
      Gets the name of the preprocessor that marks the end of a preprocessor block.

      A preprocessor block is identified as a group of file lines, which can be either other preprocessor instructions or lines of code, contained between a "begin" marker and an "end" marker. It is up to the preprocessor to determine the begin and end markers. It is also up to the preprocessor to manage nesting of blocks if such a behavior is desired.

      Returns:
      The name of the instruction that closes the block, or name() if no block is desired.
      Since:
      9.1.0

    • priority

      default int priority()
      Gets the priority of the preprocessor.

      The higher the priority is, the earlier the preprocessor will be queried.

      Returns:
      The priority of the preprocessor.
      Since:
      9.1.0

    • defaultValue

      @Nullable String defaultValue()
      Gets the default value of a preprocessor.

      null is allowed and means that no default value is provided.

      Returns:
      The default value of the preprocessor.
      Since:
      9.1.0

    • apply

      boolean apply(IScriptFile file, List<String> preprocessedContents, IMutableScriptRunInfo runInfo, List<IPreprocessor.Match> matches)
      Applies the preprocessor to the IScriptFile and the IMutableScriptRunInfo.

      Each preprocessor for which at least one match has been identified or that defines a non-null default value will be called. This method will regardless be called at most once for every file in a single script run.

      It is possible for a preprocessor to modify the file contents by acting directly on the preprocessedContents list, whereas the run information can be altered through the runInfo parameter. All other information is read-only.

      A preprocessor can also prevent loading of the file and further pre-processing by returning false in this method.

      Parameters:
      file - The file on which the preprocessor is being invoked on.
      preprocessedContents - The contents of the file, as preprocessed by other preprocessors. If this preprocessor wants to modify the file contents, it is allowed to act directly on this list.
      runInfo - an IMutableScriptRunInfo representing information related to the run and allowing modification if desired.
      matches - A read-only list containing all preprocessor matches in the current file. The matches are guaranteed to be ordered from top to bottom.
      Returns:
      Whether the file is still eligible for loading (true) or if it should be discarded (false).
      Since:
      9.1.0

    • compare

      default int compare(IScriptFile a, IScriptFile b)
      Compares the two script files, allowing the preprocessor to alter their ordering.

      This method might get called even if the current preprocessor has no matches in the file. It is thus suggested to verify the presence of the preprocessor through IScriptFile.hasMatchesFor(IPreprocessor) instead of assuming its presence.

      Specified by:
      compare in interface Comparator<IScriptFile>
      Parameters:
      a - The first script file to compare.
      b - The second script file to compare.
      Returns:
      0 if the files are to be considered equal, -1 if a comes before b, 1 otherwise.
      Since:
      9.1.0