alice
library
manual.

The `Compiler` structure

^Synopsis^{____________________________________________}

    signature COMPILER
    structure Compiler : COMPILER

This structure provides runtime access to the compiler and allows evaluating Alice ML programs in source form dynamically.

See also: Component, Package, Pickle

^Import^{______________________________________________}

    import structure Compiler from "x-alice:/lib/system/Compiler"
    import signature COMPILER from "x-alice:/lib/system/COMPILER-sig"

^Interface^{___________________________________________}

    signature COMPILER =
    sig
	type env
	type warnings = {conventions :         bool,
	                 shadowing :           bool,
	                 monomorphism :        bool,
	                 unusedImports :       bool,
	                 addedImports :        bool,
	                 inaccessibleExports : bool}

	val warnings :        warnings

	exception Error

	val initialEnv :      env

	val compile :         string -> Component.t
	val compileWith :     env * string -> Component.t
	val compileFile :     string * string option -> unit
	val compileFileWith : env * string * string option -> unit

	val eval :            string -> package
	val evalWith :        env * string -> env * package
	val evalFile :        string -> package
	val evalFileWith :    env * string -> env * package

	val withStreams :     {out : TextIO.outstream option,
	                       err : TextIO.outstream option,
	                       trace : TextIO.outstream option,
	                       annot : TextIO.outstream option}
	                       -> ('a -> 'b) -> 'a -> 'b
	val withWidths :      {out : int, err : int, trace : int}
	                       -> ('a -> 'b) -> 'a -> 'b
	val withWarnings :    warnings -> ('a -> 'b) -> 'a -> 'b
    end

^Description^{_________________________________________}

type env

The type of compilation environments.

type warning

A record type collecting all possible warning switches.

Note: This type may change in future versions of Alice. Use record update on the default record warnings if you want your code to be robust against changes.

warning

A record withg the default settings warning switches.

exception Error

Raised when a compile-time error occurs.

initialEnv

The initial compilation environment that contains all library entries that are available by default.

compileWith (env, source) compile source

Compiles the string source to a first-class component, under environment env. Raises Error if compilation was not successful. A respective error message will be written to the TextIO.stdErr stream by default, but can be redirected using the withStreams function below. The second variant uses initialEnv as the default environment.

Note that incremental compilation is likely to create a component that is sited and can hence not be exported. With non-incremental compilation this problem does not occur, because all external entities will be referenced indirectly through imports in the created component.

compileFileWith (env, file, dest) compileFile (file, dest)

Compiles the content of file and saves the resulting component to a second file. If dest is given, it is used as the destination's file name. Otherwise, the file name is derived from file by replacing its extension with Component.extension. Raises Error if compilation was not successful. A respective error message is written to the TextIO.stdErr stream by default, but can be redirected using the withStreams function below. The first variant compiles under the given environemnt, the second uses initialEnv as the default environment.

Note that incremental compilation is likely to create a sited component and hence can easily fail with an IO.Io exception. With non-incremental compilation this problem does not occur, because all external entities will be referenced indirectly through imports in the created component.

evalWith (env, source) eval source

Compiles the string source to a first-class component, under environment env, evaluates it, and returns a package containing the component's export module. Raises Error if compilation was not successful. A respective error message is written to the TextIO.stdErr stream by default, but can be redirected using the withStreams function below. Any exception raised by evaluation of the component will also be propagated to the caller.

The first variant allows for incremental evaluation, it takes a given environment and returns an environment that is extended with all entities declared by the program. The second variant uses initialEnv as the default environment. (See below for examples.)

evalFileWith (env, file) evalFile file

Like evalWith and eval, respectively, but the program is read from a source file instead of being given as a string.

withStreams {out, err, trace, annot} f

Redirects the output produced by compilation function f. Error messages are written to err, logging output (such as access to components) is written to out, special output tracing the phases of execution is written to trace, and type annotations are written to annot. By giving NONE for any of these values the respective output will be suppressed. Default mode of operation is {err = SOME TextIO.stdErr, out = NONE, trace = NONE, annot = NONE}.

Note that the I/O produced by evaluation of the compiled component is not affected.

withWidths {out, err, trace} f

Sets widths for pretty-printing output on the respective message streams. All values default to 80.

withWarnings w f

Sets warning switches for compilation. For compatibily with future versions of Alice ML, the argument w is best given in terms of record update on the default switches represented by the predefined record warnings, as in the following example:

      withWarnings {warnings where conventions=false} eval source

^Examples^{____________________________________________}

Here are some simple examples of using the compiler:

Evaluation for side effects:
```
	eval "print \"Hello\\n\""
```

Using the result of evaluation:

	structure It = unpack eval "84 div 2" : (val it : int);
	print (Int.toString It.it ^ "\n")

Exception handling:
```
	eval "raise Empty" handle Empty => ()
```

Incremental evaluation:

	val (env, _) = evalWith (initialEnv, "val x = 4");
	evalWith (env, "print (Int.toString x)")

Component import and nested evaluation (note the double quoting):

	eval "import \"x-alice:/lib/system/Compiler\"; \
	     \Compiler.eval \"print \\\"Hello\\\\n\\\"\""

Runtime creation and manual insertion of imported components:

	import val myval : int from "myscheme:/bla"
	val c = compile "val myval = 7"
	val _ = ComponentManager.enter (Url.fromString "myscheme:/bla", c)
	val _ = Print.printVal (myval + 1)

Error message redirection:

	val f = TextIO.openOut "/tmp/log";
	withStreams {err=SOME f, out=NONE, trace=NONE, annot=NONE} compile s

Error message redirection to an incremental list of lines:

	val (lines,wr) = TextPrimIO.openVectorListWr ()
	val f = TextIO.mkOutstream (TextIO.StreamIO.mkOutstream (wr, IO.LINE_BUF));
	withStreams {err=SOME f, out=NONE, trace=NONE, annot=NONE} compile s;
	TextIO.closeOut f

Combined message redirection and layout customization (note the parenthesization):

	withStreams {err=SOME TextIO.stdOut, out=SOME TextIO.stdOut, trace=NONE, annot=NONE}
	    (withWidths {err=120, out=120, trace=80} compile) s

last modified 2007/Mar/30 17:10

alice library manual.

The Compiler structure

________ Synopsis ____________________________________________________

________ Import ______________________________________________________

________ Interface ___________________________________________________

________ Description _________________________________________________