+<sect2>
+<title>Defining your own control structures</title>
+
+<para>
+As we're seen, arrow notation provides constructs,
+modelled on those for expressions,
+for sequencing, value recursion and conditionals.
+But suitable combinators,
+which you can define in ordinary Haskell,
+may also be used to build new commands out of existing ones.
+The basic idea is that a command defines an arrow from environments to values.
+These environments assign values to the free local variables of the command.
+Thus combinators that produce arrows from arrows
+may also be used to build commands from commands.
+For example, the <literal>ArrowChoice</literal> class includes a combinator
+<programlisting>
+ArrowChoice a => (<+>) :: a e c -> a e c -> a e c
+</programlisting>
+so we can use it to build commands:
+<programlisting>
+expr' = proc x ->
+ returnA -< x
+ <+> do
+ symbol Plus -< ()
+ y <- term -< ()
+ expr' -< x + y
+ <+> do
+ symbol Minus -< ()
+ y <- term -< ()
+ expr' -< x - y
+</programlisting>
+This is equivalent to
+<programlisting>
+expr' = (proc x -> returnA -< x)
+ <+> (proc x -> do
+ symbol Plus -< ()
+ y <- term -< ()
+ expr' -< x + y)
+ <+> (proc x -> do
+ symbol Minus -< ()
+ y <- term -< ()
+ expr' -< x - y)
+</programlisting>
+It is essential that this operator be polymorphic in <literal>e</literal>
+(representing the environment input to the command
+and thence to its subcommands)
+and satisfy the corresponding naturality property
+<screen>
+arr k >>> (f <+> g) = (arr k >>> f) <+> (arr k >>> g)
+</screen>
+at least for strict <literal>k</literal>.
+(This should be automatic if you're not using <literal>seq</literal>.)
+This ensures that environments seen by the subcommands are environments
+of the whole command,
+and also allows the translation to safely trim these environments.
+The operator must also not use any variable defined within the current
+arrow abstraction.
+</para>
+
+<para>
+We could define our own operator
+<programlisting>
+untilA :: ArrowChoice a => a e () -> a e Bool -> a e ()
+untilA body cond = proc x ->
+ if cond x then returnA -< ()
+ else do
+ body -< x
+ untilA body cond -< x
+</programlisting>
+and use it in the same way.
+Of course this infix syntax only makes sense for binary operators;
+there is also a more general syntax involving special brackets:
+<screen>
+proc x -> do
+ y <- f -< x+1
+ (|untilA (increment -< x+y) (within 0.5 -< x)|)
+</screen>
+</para>
+
+</sect2>
+
+<sect2>
+<title>Primitive constructs</title>
+
+<para>
+Some operators will need to pass additional inputs to their subcommands.
+For example, in an arrow type supporting exceptions,
+the operator that attaches an exception handler will wish to pass the
+exception that occurred to the handler.
+Such an operator might have a type
+<screen>
+handleA :: ... => a e c -> a (e,Ex) c -> a e c
+</screen>
+where <literal>Ex</literal> is the type of exceptions handled.
+You could then use this with arrow notation by writing a command
+<screen>
+body `handleA` \ ex -> handler
+</screen>
+so that if an exception is raised in the command <literal>body</literal>,
+the variable <literal>ex</literal> is bound to the value of the exception
+and the command <literal>handler</literal>,
+which typically refers to <literal>ex</literal>, is entered.
+Though the syntax here looks like a functional lambda,
+we are talking about commands, and something different is going on.
+The input to the arrow represented by a command consists of values for
+the free local variables in the command, plus a stack of anonymous values.
+In all the prior examples, this stack was empty.
+In the second argument to <literal>handleA</literal>,
+this stack consists of one value, the value of the exception.
+The command form of lambda merely gives this value a name.
+</para>
+
+<para>
+More concretely,
+the values on the stack are paired to the right of the environment.
+So when designing operators like <literal>handleA</literal> that pass
+extra inputs to their subcommands,
+More precisely, the type of each argument of the operator (and its result)
+should have the form
+<screen>
+a (...(e,t1), ... tn) t
+</screen>
+where <replaceable>e</replaceable> is a polymorphic variable
+(representing the environment)
+and <replaceable>ti</replaceable> are the types of the values on the stack,
+with <replaceable>t1</replaceable> being the <quote>top</quote>.
+The polymorphic variable <replaceable>e</replaceable> must not occur in
+<replaceable>a</replaceable>, <replaceable>ti</replaceable> or
+<replaceable>t</replaceable>.
+However the arrows involved need not be the same.
+Here are some more examples of suitable operators:
+<screen>
+bracketA :: ... => a e b -> a (e,b) c -> a (e,c) d -> a e d
+runReader :: ... => a e c -> a' (e,State) c
+runState :: ... => a e c -> a' (e,State) (c,State)
+</screen>
+We can supply the extra input required by commands built with the last two
+by applying them to ordinary expressions, as in
+<screen>
+proc x -> do
+ s <- ...
+ (|runReader (do { ... })|) s
+</screen>
+which adds <literal>s</literal> to the stack of inputs to the command
+built using <literal>runReader</literal>.
+</para>
+
+<para>
+The command versions of lambda abstraction and application are analogous to
+the expression versions.
+In particular, the beta and eta rules describe equivalences of commands.
+These three features (operators, lambda abstraction and application)
+are the core of the notation; everything else can be built using them,
+though the results would be somewhat clumsy.
+For example, we could simulate <literal>do</literal>-notation by defining
+<programlisting>
+bind :: Arrow a => a e b -> a (e,b) c -> a e c
+u `bind` f = returnA &&& u >>> f
+
+bind_ :: Arrow a => a e b -> a e c -> a e c
+u `bind_` f = u `bind` (arr fst >>> f)
+</programlisting>
+We could simulate <literal>do</literal> by defining
+<programlisting>
+cond :: ArrowChoice a => a e b -> a e b -> a (e,Bool) b
+cond f g = arr (\ (e,b) -> if b then Left e else Right e) >>> f ||| g
+</programlisting>
+</para>
+
+</sect2>
+
+<sect2>
+<title>Differences with the paper</title>
+
+<itemizedlist>
+
+<listitem>
+<para>Instead of a single form of arrow application (arrow tail) with two
+translations, the implementation provides two forms
+<quote><literal>-<</literal></quote> (first-order)
+and <quote><literal>-<<</literal></quote> (higher-order).
+</para>
+</listitem>
+
+<listitem>
+<para>User-defined operators are flagged with banana brackets instead of
+a new <literal>form</literal> keyword.
+</para>
+</listitem>
+
+</itemizedlist>
+
+</sect2>
+
+<sect2>
+<title>Portability</title>
+
+<para>
+Although only GHC implements arrow notation directly,
+there is also a preprocessor
+(available from the
+<ulink url="http://www.haskell.org/arrows/">arrows web page></ulink>)
+that translates arrow notation into Haskell 98
+for use with other Haskell systems.
+You would still want to check arrow programs with GHC;
+tracing type errors in the preprocessor output is not easy.
+Modules intended for both GHC and the preprocessor must observe some
+additional restrictions:
+<itemizedlist>
+
+<listitem>
+<para>
+The module must import
+<ulink url="../base/Control.Arrow.html"><literal>Control.Arrow</literal></ulink>.
+</para>
+</listitem>
+
+<listitem>
+<para>
+The preprocessor cannot cope with other Haskell extensions.
+These would have to go in separate modules.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Because the preprocessor targets Haskell (rather than Core),
+<literal>let</literal>-bound variables are monomorphic.
+</para>
+</listitem>
+
+</itemizedlist>
+</para>
+
+</sect2>
+
+</sect1>
+
+<!-- ==================== ASSERTIONS ================= -->
+
+<sect1 id="sec-assertions">
+<title>Assertions
+<indexterm><primary>Assertions</primary></indexterm>
+</title>
+
+<para>
+If you want to make use of assertions in your standard Haskell code, you
+could define a function like the following:
+</para>
+
+<para>
+
+<programlisting>
+assert :: Bool -> a -> a
+assert False x = error "assertion failed!"
+assert _ x = x
+</programlisting>
+
+</para>
+
+<para>
+which works, but gives you back a less than useful error message --
+an assertion failed, but which and where?
+</para>
+
+<para>
+One way out is to define an extended <function>assert</function> function which also
+takes a descriptive string to include in the error message and
+perhaps combine this with the use of a pre-processor which inserts
+the source location where <function>assert</function> was used.
+</para>
+
+<para>
+Ghc offers a helping hand here, doing all of this for you. For every
+use of <function>assert</function> in the user's source:
+</para>
+
+<para>
+
+<programlisting>
+kelvinToC :: Double -> Double
+kelvinToC k = assert (k >= 0.0) (k+273.15)
+</programlisting>
+
+</para>
+
+<para>
+Ghc will rewrite this to also include the source location where the
+assertion was made,
+</para>
+
+<para>
+
+<programlisting>
+assert pred val ==> assertError "Main.hs|15" pred val
+</programlisting>
+
+</para>
+
+<para>
+The rewrite is only performed by the compiler when it spots
+applications of <function>Control.Exception.assert</function>, so you
+can still define and use your own versions of
+<function>assert</function>, should you so wish. If not, import
+<literal>Control.Exception</literal> to make use
+<function>assert</function> in your code.
+</para>
+
+<para>
+To have the compiler ignore uses of assert, use the compiler option
+<option>-fignore-asserts</option>. <indexterm><primary>-fignore-asserts
+option</primary></indexterm> That is, expressions of the form
+<literal>assert pred e</literal> will be rewritten to
+<literal>e</literal>.
+</para>
+
+<para>
+Assertion failures can be caught, see the documentation for the
+<literal>Control.Exception</literal> library for the details.
+</para>
+
+</sect1>
+
+
+<!-- =============================== PRAGMAS =========================== -->
+
+ <sect1 id="pragmas">
+ <title>Pragmas</title>
+
+ <indexterm><primary>pragma</primary></indexterm>
+
+ <para>GHC supports several pragmas, or instructions to the
+ compiler placed in the source code. Pragmas don't normally affect
+ the meaning of the program, but they might affect the efficiency
+ of the generated code.</para>
+
+ <para>Pragmas all take the form
+
+<literal>{-# <replaceable>word</replaceable> ... #-}</literal>
+
+ where <replaceable>word</replaceable> indicates the type of
+ pragma, and is followed optionally by information specific to that
+ type of pragma. Case is ignored in
+ <replaceable>word</replaceable>. The various values for
+ <replaceable>word</replaceable> that GHC understands are described
+ in the following sections; any pragma encountered with an
+ unrecognised <replaceable>word</replaceable> is (silently)
+ ignored.</para>
+
+ <sect2 id="deprecated-pragma">
+ <title>DEPRECATED pragma</title>
+ <indexterm><primary>DEPRECATED</primary>
+ </indexterm>
+
+ <para>The DEPRECATED pragma lets you specify that a particular
+ function, class, or type, is deprecated. There are two
+ forms.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>You can deprecate an entire module thus:</para>
+<programlisting>
+ module Wibble {-# DEPRECATED "Use Wobble instead" #-} where
+ ...
+</programlisting>
+ <para>When you compile any module that import
+ <literal>Wibble</literal>, GHC will print the specified
+ message.</para>
+ </listitem>
+
+ <listitem>
+ <para>You can deprecate a function, class, or type, with the
+ following top-level declaration:</para>
+<programlisting>
+ {-# DEPRECATED f, C, T "Don't use these" #-}
+</programlisting>
+ <para>When you compile any module that imports and uses any
+ of the specifed entities, GHC will print the specified
+ message.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>You can suppress the warnings with the flag
+ <option>-fno-warn-deprecations</option>.</para>
+ </sect2>
+
+ <sect2 id="inline-noinline-pragma">
+ <title>INLINE and NOINLINE pragmas</title>
+
+ <para>These pragmas control the inlining of function
+ definitions.</para>
+
+ <sect3 id="inline-pragma">
+ <title>INLINE pragma</title>
+ <indexterm><primary>INLINE</primary></indexterm>
+
+ <para>GHC (with <option>-O</option>, as always) tries to
+ inline (or “unfold”) functions/values that are
+ “small enough,” thus avoiding the call overhead
+ and possibly exposing other more-wonderful optimisations.
+ Normally, if GHC decides a function is “too
+ expensive” to inline, it will not do so, nor will it
+ export that unfolding for other modules to use.</para>
+
+ <para>The sledgehammer you can bring to bear is the
+ <literal>INLINE</literal><indexterm><primary>INLINE
+ pragma</primary></indexterm> pragma, used thusly:</para>
+
+<programlisting>
+key_function :: Int -> String -> (Bool, Double)
+
+#ifdef __GLASGOW_HASKELL__
+{-# INLINE key_function #-}
+#endif
+</programlisting>
+
+ <para>(You don't need to do the C pre-processor carry-on
+ unless you're going to stick the code through HBC—it
+ doesn't like <literal>INLINE</literal> pragmas.)</para>
+
+ <para>The major effect of an <literal>INLINE</literal> pragma
+ is to declare a function's “cost” to be very low.
+ The normal unfolding machinery will then be very keen to
+ inline it.</para>
+
+ <para>Syntactially, an <literal>INLINE</literal> pragma for a
+ function can be put anywhere its type signature could be
+ put.</para>
+
+ <para><literal>INLINE</literal> pragmas are a particularly
+ good idea for the
+ <literal>then</literal>/<literal>return</literal> (or
+ <literal>bind</literal>/<literal>unit</literal>) functions in
+ a monad. For example, in GHC's own
+ <literal>UniqueSupply</literal> monad code, we have:</para>
+
+<programlisting>
+#ifdef __GLASGOW_HASKELL__
+{-# INLINE thenUs #-}
+{-# INLINE returnUs #-}
+#endif
+</programlisting>
+
+ <para>See also the <literal>NOINLINE</literal> pragma (<xref
+ linkend="noinline-pragma">).</para>
+ </sect3>
+
+ <sect3 id="noinline-pragma">
+ <title>NOINLINE pragma</title>
+
+ <indexterm><primary>NOINLINE</primary></indexterm>
+ <indexterm><primary>NOTINLINE</primary></indexterm>
+
+ <para>The <literal>NOINLINE</literal> pragma does exactly what
+ you'd expect: it stops the named function from being inlined
+ by the compiler. You shouldn't ever need to do this, unless
+ you're very cautious about code size.</para>
+
+ <para><literal>NOTINLINE</literal> is a synonym for
+ <literal>NOINLINE</literal> (<literal>NOTINLINE</literal> is
+ specified by Haskell 98 as the standard way to disable
+ inlining, so it should be used if you want your code to be
+ portable).</para>
+ </sect3>
+
+ <sect3 id="phase-control">
+ <title>Phase control</title>
+
+ <para> Sometimes you want to control exactly when in GHC's
+ pipeline the INLINE pragma is switched on. Inlining happens
+ only during runs of the <emphasis>simplifier</emphasis>. Each
+ run of the simplifier has a different <emphasis>phase
+ number</emphasis>; the phase number decreases towards zero.
+ If you use <option>-dverbose-core2core</option> you'll see the
+ sequence of phase numbers for successive runs of the
+ simpifier. In an INLINE pragma you can optionally specify a
+ phase number, thus:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>You can say "inline <literal>f</literal> in Phase 2
+ and all subsequent phases":
+<programlisting>
+ {-# INLINE [2] f #-}
+</programlisting>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>You can say "inline <literal>g</literal> in all
+ phases up to, but not including, Phase 3":
+<programlisting>
+ {-# INLINE [~3] g #-}
+</programlisting>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>If you omit the phase indicator, you mean "inline in
+ all phases".</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>You can use a phase number on a NOINLINE pragma too:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>You can say "do not inline <literal>f</literal>
+ until Phase 2; in Phase 2 and subsequently behave as if
+ there was no pragma at all":
+<programlisting>
+ {-# NOINLINE [2] f #-}
+</programlisting>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>You can say "do not inline <literal>g</literal> in
+ Phase 3 or any subsequent phase; before that, behave as if
+ there was no pragma":
+<programlisting>
+ {-# NOINLINE [~3] g #-}
+</programlisting>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>If you omit the phase indicator, you mean "never
+ inline this function".</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The same phase-numbering control is available for RULES
+ (<xref LinkEnd="rewrite-rules">).</para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="line-pragma">
+ <title>LINE pragma</title>
+
+ <indexterm><primary>LINE</primary><secondary>pragma</secondary></indexterm>
+ <indexterm><primary>pragma</primary><secondary>LINE</secondary></indexterm>
+ <para>This pragma is similar to C's <literal>#line</literal>
+ pragma, and is mainly for use in automatically generated Haskell
+ code. It lets you specify the line number and filename of the
+ original code; for example</para>
+
+<programlisting>
+{-# LINE 42 "Foo.vhs" #-}
+</programlisting>
+
+ <para>if you'd generated the current file from something called
+ <filename>Foo.vhs</filename> and this line corresponds to line
+ 42 in the original. GHC will adjust its error messages to refer
+ to the line/file named in the <literal>LINE</literal>
+ pragma.</para>
+ </sect2>
+
+ <sect2 id="options-pragma">
+ <title>OPTIONS pragma</title>
+ <indexterm><primary>OPTIONS</primary>
+ </indexterm>
+ <indexterm><primary>pragma</primary><secondary>OPTIONS</secondary>
+ </indexterm>
+
+ <para>The <literal>OPTIONS</literal> pragma is used to specify
+ additional options that are given to the compiler when compiling
+ this source file. See <xref linkend="source-file-options"> for
+ details.</para>
+ </sect2>
+
+ <sect2 id="rules">
+ <title>RULES pragma</title>
+
+ <para>The RULES pragma lets you specify rewrite rules. It is
+ described in <xref LinkEnd="rewrite-rules">.</para>
+ </sect2>
+