Package team.unnamed.mocha

Interface MochaEngine<T>

public interface MochaEngine<T>
The engine's entry class. Provides methods to evaluate and parse Molang code from strings and readers.
Since:
3.0.0

  • Method Details

    • create

      static <T> MochaEngine<T> create(T entity)

    • create

      static <T> MochaEngine<T> create(T entity, Consumer<Scope.Builder> scopeBuilder)

    • create

      static MochaEngine<?> create()

    • createStandard

      @Contract("_ -> new") @NotNull static <T> @NotNull MochaEngine<T> createStandard(T entity)
      Creates a new, clean and empty MochaEngine instance with the standard, default bindings.
      Returns:
      The created MochaEngine instance.
      Since:
      3.0.0

    • createStandard

      @Contract("-> new") @NotNull static @NotNull MochaEngine<?> createStandard()
      Creates a new, clean and empty MochaEngine instance with the standard, default bindings.
      Returns:
      The created MochaEngine instance.
      Since:
      3.0.0

    • parse

      @NotNull @NotNull List<Expression> parse(@NotNull @NotNull Reader reader) throws IOException
      Parses the data from the given reader to a List of Expression Note that this method won't close the given reader
      Parameters:
      reader - The reader to read the data from
      Returns:
      The list of parsed expressions
      Throws:
      ParseException - If read failed or there are syntax errors in the script
      IOException
      Since:
      3.0.0

    • parse

      @NotNull default @NotNull List<Expression> parse(@NotNull @NotNull String string) throws ParseException
      Parses the given string to a list of Expression
      Parameters:
      string - The MoLang string
      Returns:
      The list of parsed expressions
      Throws:
      ParseException - If parsing fails

    • eval

      double eval(@NotNull @NotNull List<Expression> expressions)
      Evaluates the given expressions, these expressions are already parsed and are interpreted as fast as possible.
      Parameters:
      expressions - The expressions to evaluate.
      Returns:
      The result of the evaluation.
      Since:
      3.0.0

    • eval

      double eval(@NotNull @NotNull Reader source)
      Parses and evaluates the given Molang source.

      Note that the engine instance is not responsible for caching parsed expressions, so if you want to re-use parsed expressions, you should use the parse(Reader) and eval(List) methods.

      Parameters:
      source - The source to evaluate.
      Returns:
      The result of the evaluation.
      Since:
      3.0.0
      See Also:

    • eval

      default double eval(@NotNull @NotNull String source)
      Parses and evaluates the given Molang source.

      Note that the engine instance is not responsible for caching parsed expressions, so if you want to re-use parsed expressions, you should use the parse(String) and eval(List) methods.

      Parameters:
      source - The source to evaluate.
      Returns:
      The result of the evaluation.
      Since:
      3.0.0
      See Also:

    • prepareEval

      @NotNull @NotNull MochaFunction prepareEval(@NotNull @NotNull Reader reader)
      Parses the data from the given reader and returns a cached, interpretable MochaFunction. 
      Note that this method won't close the given
 reader

      This approach is the same as parsing to a List of expressions, caching them and then evaluating using eval(List), but easier, since it already keeps this MochaEngine instance.

      Parameters:
      reader - The reader to read the data from
      Returns:
      The cached, interpretable function
      Since:
      3.0.0

    • prepareEval

      @NotNull default @NotNull MochaFunction prepareEval(@NotNull @NotNull String string)
      Parses the given string and returns a cached, interpretable MochaFunction.

      This approach is the same as parsing to a List of expressions, caching them and then evaluating using eval(List), but easier, since it already keeps this MochaEngine instance.

      Parameters:
      string - The MoLang string
      Returns:
      The cached, interpretable function
      Since:
      3.0.0

    • compile

      @NotNull <F extends MochaCompiledFunction> F compile(@NotNull @NotNull Reader reader, @NotNull @NotNull Class<F> interfaceType)
      Compiles the given code into a Molang function that can take arguments.
      Parameters:
      reader - The code to compile.
      interfaceType - The interface to implement, must have a single method.
      Returns:
      The compiled function.
      Since:
      3.0.0

    • compile

      @NotNull default <F extends MochaCompiledFunction> F compile(@NotNull @NotNull String code, @NotNull @NotNull Class<F> interfaceType)
      Compiles the given code into a Molang function that can take arguments.
      Parameters:
      code - The code to compile.
      interfaceType - The interface to implement, must have a single method.
      Returns:
      The compiled function.
      Since:
      3.0.0

    • compile

      @NotNull default @NotNull MochaFunction compile(@NotNull @NotNull Reader reader)
      Compiles the given code into a Molang function that takes no arguments.
      Parameters:
      reader - The code to compile.
      Returns:
      The compiled function.
      Since:
      3.0.0

    • compile

      @NotNull default @NotNull MochaFunction compile(@NotNull @NotNull String code)
      Compiles the given code into a Molang function that takes no arguments.
      Parameters:
      code - The code to compile.
      Returns:
      The compiled function.
      Since:
      3.0.0

    • classPool

      @Internal @NotNull @NotNull javassist.ClassPool classPool()
      Returns the internal ClassPool used by the compiler.
      Returns:
      The compiler class pool
      Since:
      3.0.0

    • bind

      void bind(@NotNull @NotNull Class<?> clazz)
      Binds the given clazz static fields and methods.

      Fields and methods are bound in the following format:

           namespace.field
     namespace.method()
     namespace.method(arg1, arg2)

      Where namespace is given by the given class' Binding annotation, and the field and method names are also given by Binding annotations.

      Parameters:
      clazz - The class to bind.
      Since:
      3.0.0
      See Also:

    • bindInstance

      <B> void bindInstance(@NotNull @NotNull Class<? super B> clazz, @NotNull B instance, @NotNull @NotNull String name, @NotNull @NotNull String @NotNull ... aliases)
      Binds the given instance non-static fields and methods.

      Fields and methods are bound in the following format:

           name.field
     name.method()
     name.method(arg1, arg2)

      Where name is given by the name parameter, and the field and method names are given by Binding annotations.

      Type Parameters:
      B - The instance's type.
      Parameters:
      clazz - The instance's class (or interface) to use.
      instance - The instance to bind.
      name - The name to bind the instance to.
      aliases - The aliases to bind the instance to.
      Since:
      3.0.0

    • warnOnReflectiveFunctionUsage

      @Contract("_ -> this") @NotNull @NotNull MochaEngine<T> warnOnReflectiveFunctionUsage(boolean warnOnReflectiveFunctionUsage)
      Sets the boolean value for the "warn on reflective function usage" option.

      When set to true, eval(java.util.List<team.unnamed.mocha.parser.ast.Expression>) may log a warning when evaluating code that includes a call to a function that was registered using only annotations, and for so, has to be called using Reflection, taking some extra time.

      Note that this behavior can be avoided by setting a ObjectValue when binding static or non-static methods and fields

      By default this is false.

      Parameters:
      warnOnReflectiveFunctionUsage - The new value for the option
      Returns:
      This engine instance
      Since:
      3.0.0

    • handleParseExceptions

      @Contract("_ -> this") @NotNull @NotNull MochaEngine<T> handleParseExceptions(@Nullable @Nullable Consumer<@NotNull ParseException> exceptionHandler)
      Sets the ParseException handler. This handler will be called whenever an internal call to the parse(java.io.Reader) method fails. These internal calls commonly include interpreting or compiling code.

      Usually useful for logging/debugging purposes.

      By default this is null.

      Parameters:
      exceptionHandler - The new parse exception handler
      Returns:
      This engine instance
      Since:
      3.0.0

    • postCompile

      @Contract("_ -> this") @NotNull @NotNull MochaEngine<T> postCompile(@Nullable @Nullable Consumer<byte @NotNull []> bytecodeConsumer)
      Sets the post-compile function, which is called after a script is compiled to a new class, and before it is loaded. The received argument is the class bytecode, which can be written to a file for debugging purposes.

      By default this is set to null.

      Parameters:
      bytecodeConsumer - The new post-compile function
      Returns:
      This engine instance
      Since:
      3.0.0

    • scope

      @NotNull @NotNull Scope scope()
      Returns the bindings for this Molang engine instance.
      Returns:
      This engine's bindings
      Since:
      3.0.0