<!--
  - Author:
  -   Leif Kornstaedt <kornstae@ps.uni-sb.de>
  -
  - Copyright:
  -   Leif Kornstaedt, 1998
  -
  - Last change:
  -   $Date: 2001/10/19 12:17:22 $ by $Author: kornstae $
  -   $Revision: 1.8.2.2 $
  -
  - This file is part of Mozart, an implementation of Oz 3:
  -   http://www.mozart-oz.org
  -
  - See the file "LICENSE" or
  -   http://www.mozart-oz.org/LICENSE.html
  - for information on usage and redistribution
  - of this file, and for a DISCLAIMER OF ALL
  - WARRANTIES.
  -
  -->

<Chapter id="chapter.api">
  <Title/Application Programmer's Interface/
  <P>
    The compiler is available to Mozart applications through the module
    <<Compiler>>.  This chapter describes the functionality provided by
    that module and its classes.
  <P>
    First, a number of additional secondary type names used in this
    description is introduced in <Ptr to="section.api.types">, then the
    <<Compiler>> module is described in <Ptr to="section.api.module">.
    The material in that section should prove sufficient for most cases.
    The remainder of the chapter is intended for advanced uses.
  <P>
    An arbitrary number of compilers may be instantiated, each with its
    own internal state, and used concurrently.  We distinguish between
    <Def/compiler engines/, described in <Ptr to="section.api.engines">,
    which store the state of a compiler and perform the compilation
    proper, and <Def/compiler interfaces/, described in <Ptr
    to="section.api.interfaces">, which allow to observe the
    activities of compiler engines and to react to them.  Both
    of these use the narrator&slash;listener mechanism described
    in <Ptr to="appendix.narrator">; familiarity with this is
    assumed.
  <P>
    Finally, serving the purpose of examples, the provided abstractions
    are explained in terms of compiler engines and interfaces in <Ptr
    to="section.api.abstractions">.
  <Section id="section.api.types">
    <Title/Additional Secondary Types/
    <P>
      This section describes additional secondary types used in the
      descriptions in this chapter.  The conventions defined in <Ptr.Extern
      to="ozdoc:base" key="section.typestruct.format"> will be respected.
      <List>
	<Entry>?_{Coord}
	<Item>
	  stands for information about source coordinates.  This is
	  either <<unit>> if no information is known or a tuple
	  <<pos(?_{FileName} ?_{Line} ?_{Column})>>, where ?_{FileName}
	  is represented as an atom (<<''>> meaning <Q class=quasi/unknown/)
	  and ?_{Line} and ?_{Column} are integers.  Line numbering begins
	  at&nbsp;<<1>> and column numbering at&nbsp;<<0>>; a column number
	  of <<~1>> means <Q class=quasi/unknown/.
	<Entry>?_{SwitchName}
	<Item>
	  is an atom which must be a valid switch name (see <Ptr
	  to="appendix.switches">).
	<Entry>?_{PrintName}
	<Item>
	  is an atom which must be a valid variable print name.
	<Entry>?_{Env}
	<Item>
	  represents an environment, represented as a record whose
	  features are valid print names.
      </List>
  <Section id="section.api.module">
    <Title/The <<Compiler>> Module/
    <P>
      <List>
	<Entry><<evalExpression>>
	<Synopsis>
	  <<{Compiler.evalExpression ?+{V} ?+{Env} ??{KillP} ?_{X}}>>
	<Item>
	  evaluates an expression, given as a virtual string&nbsp;?_{V}, in
	  a base environment enriched by the bindings given by ?_{Env}, either
	  returning the result&nbsp;?_{X} of the evaluation or raising an
	  exception.  Furthermore, the variable ?_{KillP} is bound to a
	  nullary procedure which, when applied, interrupts compilation.

	<Entry><<virtualStringToValue>>
	<Synopsis>
	  <<{Compiler.virtualStringToValue ?+{V} ?_{X}}>>
	<Item>
	  is a replacement for <<System.virtualStringToValue>>, which
	  was available in Mozart's predecessor DFKI Oz.
	<P>
	  Note that you are discouraged from using this for large
	  data structures:  Because it is much more powerful than
	  <<System.virtualStringToValue>>, it can also be much less
	  efficient.  Rather, you should use pickling and unpickling
	  of data structures (see <Ptr.Extern to="ozdoc:system"
	  key="chapter.pickle">).

	<Entry><<engine>>
	<Synopsis>
	  <<Compiler.engine>>
	<Item>
	  is the final class from which compiler engines can be instantiated.
	  This is described in detail in <Ptr to="section.api.engines">.

	<Entry><<interface>>
	<Synopsis>
	  <<Compiler.interface>>
	<Item>
	  is a class providing a simple mechanism to create
	  compiler interfaces.  It is described in detail in
	  <Ptr to="section.api.interfaces">.

	<Entry><<parseOzFile>>
	<Synopsis>
	  <<{Compiler.parseOzFile ?+{V} ?+{O} ?+{P} ?+{Dictionary} ??{T}}>>
	<Item>
	  parses the Oz source file named ?_{V}, returning an abstract
	  syntax tree as defined in <Ptr to="appendix.syntax"> in ?_{T}.
	  ?_{O} is an instance of the <<PrivateNarrator>> class described
	  in <Ptr to="appendix.narrator">; its methods are invoked for
	  example to report compilation errors.  ?_{P} is a unary procedure
	  expecting a switch name as described in <Ptr to="appendix.switches">
	  and returning a boolean value indicating the switch's state;
	  in the current implementation, only the settings of <<gump>>,
	  <<allowdeprecated>> and <<showinsert>> are requested.  Finally,
	  ?_{Dictionary} is the set of macro names:  The keys are defined
	  macro names; its items should always be <<true>>.  As a side-effect,
	  ?_{Dictionary} is modified according to <<\define>> and <<\undef>>
	  macro directives.

	<Entry><<parseOzVirtualString>>
	<Synopsis>
<<{Compiler.parseOzVirtualString ?+{V} ?+{O} ?+{P} ?+{Dictionary} ??{T}}>>
	<Item>
	  is similar to <<parseOzFile>>, except that ?_{V} denotes the
	  source text itself instead of a source file name.

	<Entry><<assemble>>
	<Synopsis>
	  <<{Compiler.assemble ?+{Ts} ?+{Xs} ?+{SwitchR} ??{P}}>>
	<Item>
	  takes a list of bytecode instructions ?_{Ts} for the Mozart virtual
	  machine (see <Ptr to="appendix.bytecode">), assembles them and
	  returns the result in ?_{P}, a nullary procedure which causes the
	  code to be executed when applied.  ?_{Xs} is a list of global
	  variables (the closure of ?_{P}), the first element corresponding
	  to register <<g(0)>>.  ?_{SwitchR} is a record whose features
	  are switch names and whose values are booleans.  In the current
	  implementation, the switches <<profile>>, <<controlflowinfo>>,
	  <<verify>>, and <<peephole>> are used.  All features of ?_{SwitchR}
	  are optional (default values are substituted).
      </List>
  &engines;
  &interfaces;
  <Section id="section.api.abstractions">
    <Title/A Look into the Provided Abstractions/
    <P>
      The implementation of the <<Compiler.evalExpression>> procedure
      is a good example of how to use compiler engines and interfaces.
      <<evalExpression>> causes compilation of an expression within
      a speciied environment.  It is synchronous, &ie;, only returns
      after the compilation has finished.  Compiler error messages are
      raised as exceptions, and the compilation may be interrupted using
      the nullary procedure returned in <<Kill>>.
    <Para class=apropos><Title/Startup/
      Since we both want to control a compilation (done by a new compiler
      engine) and to observe the compilation process (to synchronize and
      to determine whether it produced errors), we first instantiate both
      an engine and an interface which we register with the engine.
      A number of queries are enqueued to the engine:  We need to set
      the environment and appropriate compiler switches for compilation
      of an expression and to cause synchronous execution of the compiled
      program.  When we're done configuring the compiler, we can start
      compilation of the source proper, expecting a result to be
      returned in variable <<Result>>.
    <Para class=apropos><Title/Killing/
      We then define the <<Kill>> procedure.  The rest of the observation
      is performed in a new thread, because we want to kill the observation
      as well when <<Kill>> is invoked.  <<Kill>> will clear any non-processed
      queries from the queue and interrupt the current one, then kill the
      observation thread (unless it had been already dead).
    <Para class=apropos><Title/Observing/
      Next we'll observe the running compiler, and for this we need to make
      use of the interface we created earlier.  When the compiler becomes
      idle, we check whether it has output any error messages, in which
      case we record the faulty condition, else we report success.  The main
      thread waits until the condition becomes known and reacts upon it.
      <Code.Extern display to="EvalExpression.oz">
    <Para class=apropos><Title/virtualStringToValue/
      The <<Compiler.virtualStringToValue>> is trivial to implement on
      top of the functionality provided by <<evalExpression>>.
      <Code.Extern display to="VirtualStringToValue.oz">
</Chapter>
