\section{\texttt{curry-peval}: A Partial Evaluator for Curry}
\label{sec-peval}

peval\index{peval}\index{partial evaluation}
is a tool for the partial evaluation of Curry programs.
It operates on the FlatCurry representation and can thus
easily be incorporated into the normal compilation chain.
The essence of partial evaluation is to anticipate at compile time
(or partial evaluation time) some of the computations
normally performed at run time.
Typically, partial evaluation is worthwhile for functions or
operations where some of the input arguments are already known at compile time,
or operations built by the composition of multiple other ones.
The theoretical foundations, design and implementation of
the partial evaluator is described in detail in \cite{Peemoeller2016}.

\subsection{Installation}

The current implementation of the partial evaluator is a package
managed by the Curry Package Manager CPM
(see also Section~\ref{sec-cpm}).
Thus, to install the newest version of the partial evaluator,
use the following commands:
%
\begin{curry}
> cypm update
> cypm install peval
\end{curry}
%
This downloads the newest package, compiles it, and places
the executable \code{curry-peval} into the directory \code{\$HOME/.cpm/bin}.
Hence it is recommended to add this directory to your path
in order to use the partial evaluator as described below.

\subsection{Basic Usage}

The partial evaluator is supplied as a binary that can be invoked
for a single or multiple modules that should be partially evaluated.
In each module, the partially evaluator assumes the parts of the program
that should be partially evaluated to be annotated by the function
\begin{curry}
PEVAL :: a
PEVAL x = x
\end{curry}
predefined in the module \code{Prelude},
such that the user can choose the parts to be considered.

To give an example, we consider the following module which is assumed
to be placed in the file \code{Examples/power4.curry}:
\begin{curry}
square  x = x * x
even    x = mod x 2 == 0
power n x = if n <= 0 then 1
                      else if (even n) then power (div n 2) (square x)
                                       else x * (power (n - 1) x)
power4  x = PEVAL (power 4 x)
\end{curry}
By the call to \code{PEVAL}, the expression \code{power 4 x}
is marked for partial evaluation, such that the function \code{power}
will be improved w.r.t. the arguments \code{4} and\code{x}.
Since the first argument is known in this case,
the partial evalautor is able to remove the case distinctions
in the implementation of \code{power}, and we invoke it via
\pindex{curry-peval}\pindex{peval}
\begin{lstlisting}[mathescape=false]
$ curry-peval Examples/power4.curry
Curry Partial Evaluator
Version 0.1 of 12/09/2016
CAU Kiel

Annotated Expressions
---------------------
power4.power 4 v1

Final Partial Evaluation
------------------------
power4._pe0 :: Prelude.Int -> Prelude.Int
power4._pe0 v1 = let { v2 = v1 * v1 } in v2 * v2

Writing specialized program into file 'Examples/.curry/power4_pe.fcy'.
\end{lstlisting}

Note that the partial evaluator successfully removed the case distinction,
such that the operation \code{power4} can be expected to run reasonably faster.
The new auxiliary function \code{power4._pe0} is integrated into the
existing module such that only the implementation of \code{power4} is changed,
which becomes visible if we increase the level of verbosity:
\begin{lstlisting}[mathescape=false]
$ curry-peval -v2 Examples/power4.curry
Curry Partial Evaluator
Version 0.1 of 12/09/2016
CAU Kiel

Annotated Expressions
---------------------
power4.power 4 v1

... (skipped output)

Resulting program
-----------------
module power4 ( power4.square, power4.even, power4.power, power4.power4 ) where

import Prelude

power4.square :: Prelude.Int -> Prelude.Int
power4.square v1 = v1 * v1

power4.even :: Prelude.Int -> Prelude.Bool
power4.even v1 = (Prelude.mod v1 2) == 0

power4.power :: Prelude.Int -> Prelude.Int -> Prelude.Int
power4.power v1 v2 = case (v1 <= 0) of
    Prelude.True -> 1
    Prelude.False -> case (power4.even v1) of
        Prelude.True -> power4.power (Prelude.div v1 2) (power4.square v2)
        Prelude.False -> v2 * (power4.power (v1 - 1) v2)

power4.power4 :: Prelude.Int -> Prelude.Int
power4.power4 v1 = power4._pe0 v1

power4._pe0 :: Prelude.Int -> Prelude.Int
power4._pe0 v1 = let { v2 = v1 * v1 } in v2 * v2
\end{lstlisting}

\subsection{Options}

The partial evaluator can be parametrized using a number of options,
which can also be shown using \code{--help}.

\begin{description}
\item{\code{-h}, \code{-?}, \code{--help}}
These options trigger the output of usage information.

\item{\code{-V}, \code{--version}}
These options trigger the output of the version information
of the partial evaluator.

\item{\code{-d}, \code{--debug}}
This flag is intended for development and testing issues only,
and necessary to print the resulting program to the standard output
stream even if the verbosity is set to zero.

\item{\code{--assert}, \code{--closed}}
These flags enable some internal assertions which are reasonable
during development of the partial evaluator.

\item{\code{--no-funpats}}
Normally, functions defined using functional patterns are automatically
considered for partial evaluation, since their annotation using \code{PEVAL}
is a little bit cumbersome.
However, this automatic consideration can be disabled using this flag.

\item{\code{-v n}, \code{--verbosity=n}}
Set the verbosity level to \code{n}, see above for the explanation
of the different levels.

\item{\code{--color=mode}, \code{--colour=mode}}
Set the coloring mode to \code{mode}, see above for the explanation
of the different modes.

\item{\code{-S semantics}, \code{--semantics=semantics}}
Allows the use to choose a semantics used during partial evaluation.
Note that only the \code{natural} semantics can be considered correct
for non-confluent programs, which is why it is the default semantics
\cite{Peemoeller2016}.
However, the \code{rlnt} calculus can also be chosen which is based
on term rewriting, thus implementing a run-time choice semantics
\cite{AlbertHanusVidal02JFLP}.
The \code{letrw} semantics is currently not fully supported,
but implements the gist of let-rewriting \cite{Lopez-Fraguas07}.

\item{\code{-A mode}, \code{--abstract=mode}}
During partial evaluation, all expressions that may potentially
occur in the evaluation of an annotated expression are considered and
evaluated, in order to ensure that all these expressions are also
defined in the resulting program.
Unfortunately, this imposes the risk of non-termination,
which is why similar expressions are generalized according to the
abstraction criterion.
While the \code{none} criterion avoids generalizations
and thus may lead to non-termination of the partial evaluator,
the criteria \code{wqo} and \code{wfo} both ensure termination.
In general, the criterion \code{wqo} seems to be a good compromise
of ensured termination and the quality of the computed result program.

\item{\code{-P mode}, \code{--proceed=mode}}
While the abstraction mode is responsible to limit the number of
different expressions to be considered, the proceed mode
limits the number of function calls to be evaluated during
the evaluation of a \emph{single} expressions.
While the mode \code{one} only allows a single function call
to be evaluated, the mode \code{each} allows a single call
of each single function, while \code{all} puts no restrictions
on the number of function calls to be evaluated.
Clearly, the last alternative also imposes a risk of non-termination.

\item{\code{--suffix=SUFFIX}}
Set the suffix appended to the file name to compute the output file.
If the suffix is set to the empty string, then the original FlatCurry
file will be replaced.
\end{description}
