<!--
  - Author:
  -   Leif Kornstaedt <kornstae@ps.uni-sb.de>
  -
  - Copyright:
  -   Leif Kornstaedt, 1998
  -
  - Last change:
  -   $Date: 2001-10-18 14:33:56 +0200 (Thu, 18 Oct 2001) $ by $Author: kornstae $
  -   $Revision: 14366 $
  -
  - 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.directives">
  <Title/Directives/
  <Para class=apropos><Title/Directive Syntax/
    The Mozart compiler understands the full syntax of Oz programs.
    Additionally, it also accepts <Def/directives/ in its input.
    A directive can start anywhere on a line and is introduced by a
    backslash; it always extends until the end of the line.
  <P>
    Directives come in two flavors.  So-called <Def/compiler directives/
    provide a way to change the compiler's switches, whereas <Def/macro
    directives/ can be used for inserting files or performing compilation
    conditionally.  While macro directives may appear between any two tokens
    in the input, the use of compiler directives underlies restrictions as
    described below.
  <Para class=apropos><Title/Compilation Units/
    A single input file is split into a number of compilation units as
    follows:
    <List>
      <Item>
	Each compiler directive forms a compilation unit.
      <Item>
	Each <<declare>> statement starts a compilation unit, which includes
	all following non-<<declare>> statements.
      <Item>
	A sequence of statements without <<declare>> forms a compilation
	unit.
    </List>
    Note that this implies that compiler directives can only appear between
    top-level Oz statements.
  <P>
    All compilation units in a file are processed sequentially.
  <Section>
    <Title/Compiler Directives/
    <P>
      <List>
	<Entry><<\switch>> ( <Q class=terminal/+/ ?={switchname} |
	  <Q class=terminal/-/ ?={switchname} )*
	<Item>
	  Set (<Q class=terminal/+/) &resp; reset (<Q class=terminal/-/)
	  the specified switches.  The values for ?={switchname} the compiler
	  understands are described in <Ptr to="appendix.switches">.  Case
	  matters.
	<Entry><<\pushSwitches>>
	<Item>
	  Save the current settings of all switches onto the internal switch
	  state stack.
	<Entry><<\popSwitches>>
	<Item>
	  Restore all switch settings from the topmost element of the
	  internal switch state stack, provided it is not empty, else do
	  nothing.
	<Entry><<\localSwitches>>
	<Item>
	  Save the current settings of all switches as well as the internal
	  switch state stack if no <<\localSwitches>> has occurred in the
	  current input before, else do nothing.  They are automatically
	  restored after the last compilation unit of the current input has
	  been processed.
      </List>
  <Section id="section.directives.macro">
    <Title/Macro Directives/
    <P>
      <List>
	<Entry><<\line>> ?={filename}
	<Entry><<\line>> ?={int} ?={filename}
	<Item>
	  sets the internal file name (and the line number of the subsequent
	  line) to the given values.  This data will appear in the error
	  messages and debug information generated by the compiler.
	<Entry><<\insert>> ?={filename}
	<Item>
	  is substituted by the contents of the referenced file.  The
	  <Samp/~user/ syntax is supported under Unix for absolute file
	  names.  If the file name is relative, it is first resolved
	  against the directory in which the file containing the <<\insert>>
	  resides, then against all directories named in the <Var
	  type=env/OZPATH/ environment variable (which has standard
	  <Var type=env/PATH/ syntax).
      </List>
    <Para class=apropos><Title/Macro Names/
      Note that although macro names have the same syntax as Oz variables,
      there is absolutely no connection between macro names and Oz variables.
      <List>
	<Entry><<\define>> ?={variable}
	<Item>
	  adjoins ?={variable} to the set of macro names.
	<Entry><<\undef>> ?={variable}
	<Item>
	  removes ?={variable} from the set of macro names.
	<Entry><<\ifdef>> ?={variable}
	<Item>
	  causes the text until the next balanced <<\else>> or <<\endif>>
	  only to be compiled if ?={variable} is a macro name.
	<Entry><<\ifndef>> ?={variable}
	<Item>
	  caused the text until the next balanced <<\else>> or <<\endif>>
	  to be ignored if ?={variable} is a macro name.
	<Entry><<\else>>
	<Item>
	  causes the text until the next balanced <<\endif>> to be
	  <List>
	    <Item>
	      ignored, if the <<\else>> occurs after a text region that was
	      being compiled;
	    <Item>
	      compiled, if the <<\else>> occurs after a text region that was
	      being ignored.
	  </List>
	<Entry><<\endif>>
	<Item>
	  terminates the active <<\ifdef>> or <<\ifndef>>.  Every <<\ifdef>>
	  and every <<\ifndef>> must be terminated by a corresponding
	  <<\endif>>.
      </List>
</Chapter>
