module yeti.lang.compiler.eval

Yeti compiler invocation and code evaluation.

This module is also used by the yeti.lang.compiler.yeti program to provide a REPL and compile Yeti code.

typedef typedef_description = {
name is string,
The name of the new type alias defined by the typedef.
param is list<string>,
Type parameter names.
type is type
Type assigned to the type alias.
}

typedef module_description = {
doc is string,
Description of the module from the top doc-string.
name is string,
Module name (like yeti.lang.compiler.eval).
skipped is boolean,
Compilation was skipped, type don't have doc-strings.
type is type,
Module type signature.
typedefs is list<typedef_description>
List of typedefs exported by the module.
}

Module signature

{
compileYetiFiles genericOptions options source is
list?<
ClassPath. list?<string> |
Give class path to search for compiled libraries.
ClassWriter. (string → byte[] → ()) |
Set custom class writing function.
ICast. () |
If you have really broken JVM, generate superfluous casts.
NoFrames. () |
Disable generation of Java 1.6 frames to class files.

Mainly useful for debugging, this option is not needed to run on older JVMs.
NoImport. () |
Disable importing foreign classes. Useful when sandboxing.
ParseTree. () |
Print parse tree to stdout. Not very useful, unless you want to debug the compiler.
Preload. list?<string> |
Set modules that are preloaded. Default is yeti.lang.std and io.
SourceReader. (
{
var .name is string,
Source file name (may include directories). The reader function should assign a canonical path of the source file to it.
.parent is string
Parent directory from source path entry. Can be undef_str, when not searched from the source path.
} →
string
) |
Set custom source reader function.
To. string |
Set destination directory, where to write class files. Disables execution on evaluateYetiCode as side effect.
Warn. (~yeti.lang.compiler.CompileException → ())
> →
list?<
Exec. array<string> |
Execute main after compilation of the sources. The _argv will be set to the arg parameter.
JavaOption. string |
Option to give to the javac, when .java files were in source file set.
SourceDir. string |
Add source directory to source path (where compiler searches for uncompiled dependencies).
Type. (module_description → ())
Get module types. The action (module_description -> ()) is called after each module file given for compilation.
> →
list?<string> →
()
,
Compiles a set of Yeti (and possibly Java) source files into JVM class files. Module dependencies will be automatically compiled, if possible.
genericOptions-generic compile options
options-additional options
source-list of the source files to compile

Description

Compiles the source files into class files. Yeti sources (identified by the .yeti suffix) will be compiled directly. The Java sources (with .java suffix) will be compiled by invoking the javac compiler class com.sun.tools.javac.Main (lib/tools.jar is loaded from the JDK home, if the class is not already available).

On mixed compiles a three-way sequence is done, by partially parsing the Java source files first to obtain the class types, compiling Yeti sources and finally compiling Java sources using javac.

The source and class files don't have to be necessarily on the filesystem, if SourceReader or ClassWriter options are used and only Yeti code is compiled (the javac compiler used for the Java code works only with filesystem).

Examples

 load yeti.lang.compiler.eval;
 compileYetiFiles [To 'target'] [] ['hello.yeti'];
A hello.class will be generated to the target directory, given that you have the following hello.yeti file: 
 println 'Hello world!';

The compiled code can be executed with the usual java command: 
 java -cp yeti.jar:target hello

The yeti.jar (or yeti-lib.jar) is required here for the Yeti standard library.
evaluateYetiCode genericOptions evaluationOptions expression is
list?<
ClassPath. list?<string> |
Give class path to search for compiled libraries.
ClassWriter. (string → byte[] → ()) |
Set custom class writing function.
ICast. () |
If you have really broken JVM, generate superfluous casts.
NoFrames. () |
Disable generation of Java 1.6 frames to class files.

Mainly useful for debugging, this option is not needed to run on older JVMs.
NoImport. () |
Disable importing foreign classes. Useful when sandboxing.
ParseTree. () |
Print parse tree to stdout. Not very useful, unless you want to debug the compiler.
Preload. list?<string> |
Set modules that are preloaded. Default is yeti.lang.std and io.
SourceReader. (
{
var .name is string,
Source file name (may include directories). The reader function should assign a canonical path of the source file to it.
.parent is string
Parent directory from source path entry. Can be undef_str, when not searched from the source path.
} →
string
) |
Set custom source reader function.
To. string |
Set destination directory, where to write class files. Disables execution on evaluateYetiCode as side effect.
Warn. (~yeti.lang.compiler.CompileException → ())
> →
list?<
Bind. () |
Store top-level bindings in the evaluation environment.

Allows the bindings to be accessed by later evaluations with the same context.
Exec. array<string> |
Set _argv to given parameter turing execution.
GlobalSandbox. () |
Create global sandbox before execution. Unfortunately, you can't disable it later.
NoExec. () |
Don't execute the code actually, only compile. Useful, if you just want to get the type of expression.
Source. string
Source "filename"
> →
string →
{
bindings is list<string>,
List of new bindings created in the environment during evaluation.

The Yeti syntax "name is type = value" is used.
result is
CompileException ~yeti.lang.compiler.CompileException |
Exception ~java.lang.Throwable |
Result ~java.lang.Object
,
The result of evaluation.
str is string,
The result of evaluation formatted as string, like the Yeti REPL would print it (actually Yeti REPL uses this getter).
type is type
The inferred type of the evaluated expression.
}
,
Evaluates Yeti expression.
genericOptions-generic compile options
evaluationOptions-options about evaluating
expression-string containing the Yeti code

Description

Compiles the expression in memory to JVM class(es), and then lets the JVM to load and execute the bytecode from these generated classes.

Examples

Run a chunk of code, ignoring the result value: 
 load yeti.lang.compiler.eval;
 _ = evaluateYetiCode [] [] 'println "Hello world"';

Evaluate expression with specific binding environment: 
 // Creates the environment
 env = evaluateYetiCode [];
 // bind variable in the environment
 case env [Bind ()] 'x = 40' of
 {result = Result _}: (); // OK
 {str}: failWith str;
 esac;
 // use the binding
 res = env [] 'x + 2';
 println res;

The last println should print the following line: 
 {bindings=[], result=Result 42, str="42 is number\n", type=Simple "number"}
generateYetiDoc is
{
.directory is string,
Directory where to write the generated HTML files.

The directory is created if it doesn't exist already.
.error is string → (),
Error handler (takes error message as argument).
.modules is list?<module_description>
List of module descriptions.
} →
()
Generates HTML documentation for the given set of module descriptions.

Examples

The module descriptions can be obtained using the compileYetiFiles function with Type option. 
 load yeti.lang.compiler.eval;
 modules = array [];
 compileYetiFiles [] [Type (push modules)] ['modules/xml.yeti'];
 generateYetiDoc {directory = 'doctest', modules, error = failWith};

This should generate the documentation HTML into directory named doctest (given that the modules/xml.yeti module source file can be found).
}