public Interface LanguageProvider

Allows language providers to provide language options during the creation of the test context. LanguageProviders are only allowed to set options of the language they represent (Options starting with getId()). Attempts to set options other than their own language will throw IllegalArgumentException on test context creation.

Returns:Map<String, String>

The (key, value) pairs of language option to add to the context.

Since

22.3

Creates a collection of functions representing language expressions to test. For each language operator create a function performing given operator and assign a correct TypeDescriptors to its parameters and return type. The parameter types and return type can be one of the predefined TypeDescriptors, an array with component type, an executable with required parameter types or an union type.

The JavaScript sample implementation creating a plus operator:

@Override
public Collection<? extends Snippet> createExpressions(Context context) {
    final Collection<Snippet> expressions = new ArrayList<>();
    final TypeDescriptor numeric = TypeDescriptor.union(
                    TypeDescriptor.NUMBER,
                    TypeDescriptor.BOOLEAN);
    final TypeDescriptor nonNumeric = TypeDescriptor.union(
                    TypeDescriptor.STRING,
                    TypeDescriptor.OBJECT,
                    TypeDescriptor.ARRAY,
                    TypeDescriptor.EXECUTABLE_ANY);
    Snippet.Builder builder = Snippet.newBuilder(
                    "+",
                    context.eval("js",
                                    "(function (a, b){ return a + b;})"),
                    TypeDescriptor.NUMBER).parameterTypes(numeric, numeric);
    expressions.add(builder.build());
    builder = Snippet.newBuilder(
                    "+",
                    context.eval("js",
                                    "(function (a, b){ return a + b;})"),
                    TypeDescriptor.STRING).parameterTypes(nonNumeric, TypeDescriptor.ANY);
    expressions.add(builder.build());
    builder = Snippet.newBuilder(
                    "+",
                    context.eval("js",
                                    "(function (a, b){ return a + b;})"),
                    TypeDescriptor.STRING).parameterTypes(TypeDescriptor.ANY, nonNumeric);
    expressions.add(builder.build());
    return expressions;
}

@Override
public Collection<? extends Snippet> createExpressions(Context context) {
    final Collection<Snippet> expressions = new ArrayList<>();
    final TypeDescriptor numOrBool = TypeDescriptor.union(
                    TypeDescriptor.NUMBER,
                    TypeDescriptor.BOOLEAN);
    final TypeDescriptor arrNumOrBool = TypeDescriptor.array(
                    numOrBool);
    final TypeDescriptor numeric = TypeDescriptor.union(
                    numOrBool,
                    arrNumOrBool);
    Snippet.Builder builder = Snippet.newBuilder(
                    "+",
                    context.eval("R",
                                    "function (a, b){ a + b}"),
                    numeric).parameterTypes(numeric, numeric);
    expressions.add(builder.build());
    return expressions;
}

Parameters

context:Context

the context for a guest language code literal evaluation

Returns:Collection<? extends Snippet>

factories creating the language expressions

Since

0.30

Creates an identity function. The identity function just returns its argument.

The JavaScript sample implementation:

@Override
public Value createIdentityFunction(Context context) {
    return context.eval("js", "(function (a){ return a; })");
}

The R sample implementation:

@Override
public Value createIdentityFunction(Context context) {
    return context.eval("R", "function (a){ a }");
}

Parameters

context:Context

the context for a guest language code literal evaluation

Returns:Value

the Value representing the identity function

Since

0.30

Creates a Snippet for an identity function. The identity function just returns its argument. This method allows an implementor to override the default identity function verification. In most cases it's not needed to implement this method and it's enough to implement createIdentityFunction.

The implementor can delegate to the default identity function verifier obtained by ResultVerifier#getIdentityFunctionDefaultResultVerifier().

Parameters

context:Context

the context for a guest language code literal evaluation

Returns:Snippet

the Snippet representing the identity function

Since

19.1.0

Creates a collection of inline code snippets.

This method is optional, it should be implemented if TruffleLanguage.parse(InlineParsingRequest) is implemented. It returns an empty list by default.

The JavaScript sample implementation creating inline code snippets:

@Override
public Collection<? extends InlineSnippet> createInlineScripts(Context context) {
    final Collection<InlineSnippet> inlineScripts = new ArrayList<>();
    Snippet.Builder scriptBuilder = Snippet.newBuilder(
                    "factorial",
                    context.eval("js",
                                    "(function (){\n" +
                                                    "  let factorial = function(n) {\n" +
                                                    "    let f = 1;\n" +
                                                    "    for (let i = 2; i <= n; i++) {\n" +
                                                    "      f *= i;\n" +
                                                    "    }\n" +
                                                    "  };\n" +
                                                    "  return factorial(10);\n" +
                                                    "})"),
                    TypeDescriptor.NUMBER);
    InlineSnippet.Builder builder = InlineSnippet.newBuilder(
                    scriptBuilder.build(),
                    "n * n").locationPredicate((SourceSection section) -> {
                        int line = section.getStartLine();
                        return 3 <= line && line <= 6;
                    });
    inlineScripts.add(builder.build());
    builder = InlineSnippet.newBuilder(
                    scriptBuilder.build(),
                    "Math.sin(Math.PI)");
    inlineScripts.add(builder.build());
    return inlineScripts;
}

Parameters

context:Context

the context for a guest language code literal evaluation

Returns:Collection<? extends InlineSnippet>

A collection of inline code snippets.

Since

0.32

Creates a collection of scripts containing a syntax error.

The JavaScript sample implementation:

@Override
public Collection<? extends Source> createInvalidSyntaxScripts(Context ctx) {
    try {
        final Collection scripts = new ArrayList<>();
        Reader reader = new InputStreamReader(
                        getClass().getResourceAsStream("invalidSyntax.js"),
                        "UTF-8");
        scripts.add(Source.newBuilder(
                        "js",
                        reader,
                        "invalidSyntax.js").build());
        return scripts;
    } catch (IOException ioe) {
        throw new RuntimeException(ioe);
    }
}

Parameters

context:Context

the context for a guest language code literal evaluation

Returns:Collection<? extends Source>

the scripts

Since

0.30

Creates a collection of simple scripts used for instrumentation testing. Each script is represented as a function performing the script. The function must have no formal parameters but may return a result which can be asserted by ResultVerifier.

The JavaScript sample implementation:

@Override
public Collection<? extends Snippet> createScripts(Context context) {
    try {
        final Collection<Snippet> scripts = new ArrayList<>();
        Reader reader = new InputStreamReader(
                        getClass().getResourceAsStream("sample.js"),
                        "UTF-8");
        Source source = Source.newBuilder(
                        "js",
                        reader,
                        "sample.js").build();
        Snippet.Builder builder = Snippet.newBuilder(
                        source.getName(),
                        context.eval(source),
                        TypeDescriptor.NULL);
        scripts.add(builder.build());
        return scripts;
    } catch (IOException ioe) {
        throw new RuntimeException(ioe);
    }
}

Parameters

context:Context

the context for a guest language code literal evaluation

Returns:Collection<? extends Snippet>

the language scripts

Since

0.30

Creates a collection of functions representing language statements to test. For each control flow statement create a function performing given statement and assign a correct TypeDescriptors to its parameters and return type. The parameter types and return type can be one of the predefined TypeDescriptors, an array with component type, an executable with required parameter types or an union type.

The JavaScript sample implementation creating the if statement:

@Override
public Collection<? extends Snippet> createStatements(Context context) {
    final Collection<Snippet> statements = new ArrayList<>();
    Snippet.Builder builder = Snippet.newBuilder(
                    "if",
                    context.eval("js",
                                    "(function (p){\n" +
                                                    "  if (p) return true ; else  return false;\n" +
                                                    "})"),
                    TypeDescriptor.BOOLEAN).parameterTypes(
                                    TypeDescriptor.union(
                                                    TypeDescriptor.STRING,
                                                    TypeDescriptor.OBJECT,
                                                    TypeDescriptor.NUMBER,
                                                    TypeDescriptor.BOOLEAN));
    statements.add(builder.build());
    return statements;
}

The R sample implementation creating the if statement:

@Override
public Collection<? extends Snippet> createStatements(Context context) {
    final Collection<Snippet> statements = new ArrayList<>();
    final TypeDescriptor numberOrBoolean = TypeDescriptor.union(
                    TypeDescriptor.NUMBER,
                    TypeDescriptor.BOOLEAN);
    final TypeDescriptor arrayNumberOrBoolean = TypeDescriptor.array(
                    numberOrBoolean);
    Snippet.Builder builder = Snippet.newBuilder(
                    "if",
                    context.eval("R",
                                    "function(p){\n" +
                                                    "  if (p) { return (TRUE) } else { return (FALSE) }\n" +
                                                    "}"),
                    TypeDescriptor.BOOLEAN).parameterTypes(
                                    TypeDescriptor.union(
                                                    numberOrBoolean,
                                                    arrayNumberOrBoolean));
    statements.add(builder.build());
    return statements;
}

Parameters

context:Context

the context for a guest language code literal evaluation

Returns:Collection<? extends Snippet>

factories creating the language statements

Since

0.30

Creates a collection of functions creating language data types. For each language data type create a function returning a value of given type and assign a correct TypeDescriptor to it. The TypeDescriptor can be one of the predefined TypeDescriptors, an array with component type, an executable with required parameter types or an intersection type.

The JavaScript sample implementation creating a boolean type:

Parameters

context:Context
the context for a guest language code literal evaluation

Returns:Collection<? extends Snippet>
factories creating the language data types
Since
0.30

Returns an identification of a provider. The common pattern is to use the identification of the tested language.

Returns:String

the language identification

Since

0.30