<!--
  - Author:
  -   Leif Kornstaedt <kornstae@ps.uni-sb.de>
  -
  - Copyright:
  -   Leif Kornstaedt, 1998-2003
  -
  - Last change:
  -   $Date$ by $Author$
  -   $Revision$
  -
  - 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.
  -
  -->

<Section id="section.api.examples">
  <Title/Examples/
  <SubSection>
    <Title/Inspecting the Parse Tree/
    <P>
      As a first example, here is an application that expects as single
      argument the name of an Oz source file.  It parses the file, accepting
      Gump syntax, and displays the parse tree in the Inspector (or
      <<parseError>> if parsing failed).  If there was a parse error,
      it extracts an error messages and prints that to standard output.
      <Code.Extern display to="InspectParseTree.oz">
  <SubSection>
    <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 specified 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">
</Section>
