\section{\CYS: An Interactive Curry Development System}
\label{sec-curry2prolog}

\CYS\index{\CYS} is an interactive system to develop applications
written in Curry.
It is implemented in Prolog and compiles
Curry programs into Prolog programs. It contains various tools,
a source-level debugger,
solvers for arithmetic constraints over real numbers
and finite domain constraints, etc. The compilation process and the
execution of compiled programs is fairly efficient
if a good Prolog implementation like SICStus-Prolog is used.


\subsection{Invoking \CYS}
\label{sec:invoke-kics2}

To start \CYS, execute the command
\ccode{pakcs}\pindex{pakcs} or \ccode{curry}\pindex{curry}
(these are shell scripts stored in
\code{\cyshome/bin} where \cyshome is the installation directory
of \CYS).
When the system is ready (i.e., when the prompt \ccode{Prelude>} occurs),
the prelude (\code{\cyshome/lib/Prelude.curry})
is already loaded, i.e., all definitions in the prelude are accessible.
Now you can type various commands (see next section)
or an expression to be evaluated.

One can also invoke \CYS with parameters.
These parameters are usual a sequence of commands
(see next section) that are executed before the user interaction
starts. For instance, the invocation
\begin{curry}
pakcs :load Mod :add List
\end{curry}
starts \CYS, loads the main module \code{Mod}, and adds the additional
module \code{List}.
The invocation
\begin{curry}
pakcs :load Mod :eval config
\end{curry}
starts \CYS, loads the main module \code{Mod}, and evaluates
the operation \code{config} before the user interaction starts.
As a final example, the invocation
\begin{curry}
pakcs :load Mod :save :quit
\end{curry}
starts \CYS, loads the main module \code{Mod}, creates an executable,
and terminates \CYS. This invocation could be useful in ``make'' files
for systems implemented in Curry.

There are also some additional options that can be used
when invoking \CYS:
\begin{description}
\item[\fbox{\code{-h}} or \fbox{\code{--help}}]:
Print only a help message.
\item[\fbox{\code{-V}} or \fbox{\code{--version}}]:
Print the version information of \CYS and quit.
\item[\fbox{\code{--compiler-name}}]:
Print just the compiler name (\code{pakcs}) and quit.
\item[\fbox{\code{--numeric-version}}]:
Print just the version number and quit.
\item[\fbox{\code{--noreadline}}]:
Do not use input line editing (see Section~\ref{sec:readline}).
\item[\fbox{\code{-Dname=val}}]
(these options must come before any \CYS command):
Overwrite values defined in the configuration file \ccode{.pakcsrc}
(see Section~\ref{sec-customization}),
where \code{name} is a property defined in the configuration file
and \code{val} its new value.
\item[\fbox{\code{-q}} or \fbox{\code{--quiet}}]:
With this option, \CYS works silently, i.e., the initial banner
and the input prompt are not shown.
The output of other information is determined by the options
\ccode{verbose} and \ccode{v$n$} (see Section~\ref{sec:options}).
\end{description}
%
One can also invoke \CYS with some run-time arguments
that can be accessed inside a Curry program
by the I/O operation \code{getArgs}
(see library \code{System} (Section~\ref{Library:System.Environment}).
These run-time arguments must be written at the end after
the separator \ccode{--}.
For instance, if \CYS is invoked by
\begin{curry}
pakcs :load Mod -- first and second
\end{curry}
then a call to the I/O operation \code{getArgs}
returns the list value
\begin{curry}
["first","and","second"]
\end{curry}


\subsection{Commands of \CYS}
\label{sec:pakcs-commands}

The {\bf most important commands} of \CYS are
(it is sufficient to type a unique prefix of a command if it is unique,
e.g., one can type \ccode{:r} instead of \ccode{:reload}):

\begin{description}
\item[\fbox{\code{:help}}]\pindex{:help}
Show a list of all available commands.

\item[\fbox{\code{:load $prog$}}]\pindex{:load}
Compile and load the program stored in \code{$prog$.curry}
together with all its imported modules.
If this file does not exist, the system looks for a FlatCurry
file \code{$prog$.fcy} and compiles from this intermediate representation.
% If the file \code{$prog$.fcy} does not exists, too, the system looks
% for a file \code{$prog$_flat.xml} containing a FlatCurry program in
% XML representation (compare command \ccode{:xml}\pindex{:xml}),
%translates this into a FlatCurry file \code{$prog$.fcy}
% and compiles from this intermediate representation.

\item[\fbox{\code{:reload}}]\pindex{:reload}
Recompile all currently loaded modules.

\item[\fbox{\code{:add} $m_1 \ldots m_n$}]\pindex{:add}
Add modules $m_1,\ldots,m_n$ to the set of currently loaded modules
so that their exported entities are available in the top-level environment.

\item[\fbox{$expr$}] Evaluate the expression $expr$ to normal form
and show the computed results. Since \CYS
compiles Curry programs into Prolog programs,
non-deterministic computations are implemented by backtracking.
Therefore, computed results are shown one after the other.
In the \emph{interactive mode} (which can be set in the
configuration file \ccode{\curryrc} or by setting the option
\code{interactive}, see below), you will be asked
after each computed result whether
you want to see the next alternative result or all alternative results.
The default answer value for this question can be defined
in the configuration file \ccode{\curryrc} file
(see Section~\ref{sec-customization}).

\textbf{Free variables in initial expressions} must be declared as
in Curry programs.
In order to see the results of their bindings,
they must be introduced by a \ccode{where\ldots{}free} declaration.
For instance, one can write
\begin{curry}
not b where b free
\end{curry}
in order to obtain the following bindings and results:
\begin{curry}
{b = True} False
{b = False} True
\end{curry}
Without these declarations, an error is reported in order to
avoid the unintended introduction of free variables in initial expressions
by typos.

\item[\fbox{:eval $expr$}]\pindex{:eval}
Same as $expr$. This command might be useful when putting
commands as arguments when invoking \code{pakcs}.

% \item[\fbox{:define $x$=$expr$}]
% Define the identifier $x$ as an abbreviation for the expression $expr$
% which can be used in subsequent expressions. The identifier $x$
% is visible until the next \code{load} or \code{reload} command.

\item[\fbox{\code{:quit}}]\pindex{:quit} Exit the system.
\end{description}
%
\bigskip
%
There are also a number of {\bf further commands} that are often
useful:
%
\begin{description}
\item[\fbox{\code{:type $expr$}}]\pindex{:type}
Show the type of the expression $expr$.

\item[\fbox{\code{:browse}}]\pindex{:browse}
Start the CurryBrowser to analyze the currently loaded
module together with all its imported modules
(see Section~\ref{sec-currybrowser} for more details).

\item[\fbox{\code{:edit}}]\pindex{:edit}
Load the source code of the current main module into a text editor.
If the variable \code{editcommand} is set in the
configuration file \ccode{.pakcsrc}
(see Section~\ref{sec-customization}),
its value is used as an editor command, otherwise
the environment variable \ccode{EDITOR}
or a default editor (e.g., \ccode{vi}) is used.

\item[\fbox{\code{:edit $m$}}]\pindex{:edit}
Load the source text of module $m$ (which must be accessible
via the current load path if no path specification is given)
into a text editor which is defined
as in the command \ccode{:edit}.

\item[\fbox{\code{:interface}}]\pindex{:interface}
Show the interface of the currently loaded
module, i.e., show the names of all imported modules,
the fixity declarations of all exported operators,
the exported datatypes declarations and the types
of all exported functions.

\item[\fbox{\code{:interface $prog$}}]\pindex{:interface}
Similar to \ccode{:interface}
but shows the interface of the module \ccode{$prog$.curry}.
If this module does not exist, this command looks in the
system library directory of \CYS for a module with this name,
e.g., the command \ccode{:interface FlatCurry} shows the interface
of the system module \code{FlatCurry} for meta-programming
(see Appendix~\ref{sec-flatcurry}).

\item[\fbox{\code{:usedimports}}]\pindex{:usedimports}
Show all calls to imported functions in the currently loaded module.
This might be useful to see which import declarations are really necessary.

\item[\fbox{\code{:modules}}]\pindex{:modules}
Show the list of all currently loaded modules.

\item[\fbox{\code{:programs}}]\pindex{:programs}
Show the list of all Curry programs that are available in the load path.

\item[\fbox{\code{:set $option$}}]\pindex{:set}
Set or turn on/off a specific option
of the \CYS environment (see \ref{sec:options} for a description
of all options). Options are turned on by the prefix
\ccode{+} and off by the prefix \ccode{-}. Options that can only
be set (e.g., \code{printdepth}) must not contain a prefix.

\item[\fbox{\code{:set}}]\pindex{:set}
Show a help text on the possible options
together with the current values of all options.

\item[\fbox{\code{:show}}]\pindex{:show}
Show the source text of the currently loaded Curry program.
If the variable \code{showcommand} is set in the
configuration file \ccode{.pakcsrc}
(see Section~\ref{sec-customization}),
its value is used as a command to show the source text,
otherwise the environment variable \code{PAGER} or the standard command
\ccode{cat} is used.
If the source text is not available
(since the program has been directly compiled from a FlatCurry
file), the loaded program is decompiled and
the decompiled Curry program text is shown.

\item[\fbox{\code{:show $m$}}]\pindex{:show}
Show the source text of module $m$ which must be accessible
via the current load path.

\item[\fbox{\code{:source $f$}}]\pindex{:source}
Show the source code of function $f$ (which must be visible
in the currently loaded module) in a separate window.

\item[\fbox{\code{:source $m$.$f$}}]\pindex{:source}
Show the source code of function $f$ defined in module $m$
in a separate window.

\item[\fbox{\code{:cd $dir$}}]\pindex{:cd}
Change the current working directory to $dir$.

\item[\fbox{\code{:dir}}]\pindex{:dir} Show the names of all Curry programs
in the current working directory.

\item[\fbox{\code{:!$cmd$}}]\pindex{:"!} Shell escape: execute $cmd$ in a Unix shell.

\item[\fbox{\code{:save}}]\pindex{:save} Save the currently loaded
program as an executable evaluating the main expression \ccode{main}.
The executable is stored in the file \code{Mod}
if \code{Mod} is the name of the currently loaded main module.

\item[\fbox{\code{:save $expr$}}]\pindex{:save} Similar as \ccode{:save}
but the expression $expr$ (typically: a call to the main
function) will be evaluated by the executable.

\item[\fbox{\code{:fork $expr$}}]\pindex{:fork}
The expression $expr$, which must be of type \ccode{IO ()},
is evaluated in an independent process which runs in
parallel to the current \CYS process.
All output and error messages from this new process are suppressed.
This command is useful to test distributed Curry programs
%(see Appendix~\ref{sec-ports})
where one can start
a new server process by this command. The new process
will be terminated when the evaluation of the expression $expr$
is finished.

\item[\fbox{\code{:coosy}}]\pindex{:coosy}
Start the Curry Object Observation System COOSy,
a tool to observe the execution of Curry programs.
This commands starts a graphical user interface to show
the observation results and adds to the load path the directory
containing the modules that must be imported in order to annotate
a program with observation points.
Details about the use of COOSy can be found in the
COOSy interface (under the ``Info'' button), and details
about the general idea of observation debugging and the implementation
of COOSy can be found in \cite{BrasselChitilHanusHuch04PADL}.

% \item[\fbox{\code{:xml}}]\pindex{:xml}
% Translate the currently loaded program module into an XML representation
% according to the format described in
% \url{http://www.informatik.uni-kiel.de/~curry/flat/}.
% Actually, this yields an implementation-independent
% representation of the corresponding FlatCurry program
% (see Appendix~\ref{sec-flatcurry} for a description of FlatCurry).
% If $prog$ is the name of the currently loaded program,
% the XML representation will be written into the file \ccode{$prog$_flat.xml}.

\item[\fbox{\code{:peval}}]\pindex{:peval}
Translate the currently loaded program module into an equivalent
program where some subexpressions are partially evaluated
so that these subexpressions are (hopefully) more efficiently executed.
An expression $e$ to be partially evaluated
must be marked in the source program by \code{(PEVAL e)}
(where \code{PEVAL} is defined as the identity function in the prelude
so that it has no semantical meaning).

The partial evaluator
translates a source program \code{$prog$.curry} into the
partially evaluated program in intermediate representation
stored in \code{$prog$_pe.fcy}. The latter program is implicitly loaded
by the \code{peval} command so that the partially evaluated program
is directly available. The corresponding source program
can be shown by the \code{show} command (see above).

The current partial evaluator is an experimental prototype
(so it might not work on all programs) based on the ideas
described in \cite{AlbertAlpuenteHanusVidal99LPAR,AlbertHanusVidal00LPAR,%
AlbertHanusVidal01FLOPS,AlbertHanusVidal02JFLP}.

\end{description}


\subsection{Options of \CYS}
\label{sec:options}

The following options (which can be set by the command \ccode{:set})
are currently supported:

\begin{description}
\item[\fbox{\code{+/-debug}}]\pindex{debug} Debug mode.
\index{debug mode}
In the debug mode, one can trace the evaluation of an expression,
setting spy points (break points) etc.\ (see the commands
for the debug mode described below).

\item[\fbox{\code{+/-printfail}}]\pindex{printfail} Print failures.
If this option is set, failures occurring during evaluation
(i.e., non-reducible demanded subexpressions) are printed.
This is useful to see failed reductions due to partially
defined functions or failed unifications.
Inside encapsulated search (e.g., inside evaluations of
\code{findall} and \code{findfirst}), failures are not printed
(since they are a typical programming technique there).
Note that this option causes some overhead in execution time
and memory so that it could not be used in larger applications.

\item[\fbox{\code{+/-allfails}}]\pindex{allfails}
If this option is set, \emph{all} failures
(i.e., also failures on backtracking and failures
of enclosing functions that fail due to the failure of an argument
evaluation) are printed if the option \code{printfail} is set.
Otherwise, only the first failure (i.e., the first non-reducible
subexpression) is printed.

\item[\fbox{\code{+/-consfail}}]\pindex{consfail} Print constructor failures.
If this option is set, failures due to application of
functions with non-exhaustive pattern matching or failures
during unification (application of \ccode{=:=}) are shown.
Inside encapsulated search (e.g., inside evaluations of
\code{findall} and \code{findfirst}), failures are not printed
(since they are a typical programming technique there).
In contrast to the option \code{printfail},
this option creates only a small overhead in execution time
and memory use.

\item[\fbox{\code{+consfail all}}]\pindex{consfail}
Similarly to \ccode{+consfail}, but the complete trace
of all active (and just failed) function calls from the main function
to the failed function are shown.

\item[\fbox{\code{+consfail file:$f$}}]\pindex{consfail}
Similarly to \ccode{+consfail all}, but the complete fail trace
is stored in the file $f$. This option is useful in non-interactive
program executions like web scripts.

\item[\fbox{\code{+consfail int}}]\pindex{consfail}
Similarly to \ccode{+consfail all}, but after each failure occurrence,
an interactive mode for exploring the fail trace is started
(see help information in this interactive mode).
When the interactive mode is finished, the program execution
proceeds with a failure.

\item[\fbox{\code{+/-compact}}]\pindex{compact}
Reduce the size of target programs by using the
parser option \ccode{--compact}
(see Section~\ref{sec-pakcspp} for details about this option).

\item[\fbox{\code{+/-interactive}}]\pindex{interactive}
Turn on/off the interactive mode.
In the interactive mode, the next non-deterministic value
is computed only when the user requests it.
Thus, one has also the possibility to terminate the
enumeration of all values after having seen some values.
The default value for this option can be set in the
configuration file \ccode{\curryrc} (initially, the interactive
mode is turned off).

\item[\fbox{\code{+/-first}}]\pindex{first}
Turn on/off the first-only mode.
In the first-only mode, only the first value
of the main expression is printed (instead of all values).

\item[\fbox{\code{+/-profile}}]\pindex{profile} Profile mode.
If the profile mode is on, then information about
the number of calls, failures, exits etc.\ are collected for
each function during the debug mode (see above) and shown
after the complete execution (additionaly, the result is stored
in the file \code{$prog$.profile} where $prog$ is the current main program).
The profile mode has no effect outside the debug mode.


\item[\fbox{\code{+/-suspend}}] Suspend mode (initially, it is off).
If the suspend mode is on, all suspended expressions
(if there are any) are shown (in their internal representation) at the end
of a computation.

\item[\fbox{\code{+/-time}}]\pindex{time} Time mode. If the time mode is on,
the cpu time and the elapsed time
of the computation is always printed together with the result
of an evaluation.

\item[\fbox{\code{+/-verbose}}] Verbose mode (initially, it is off).
If the verbose mode is on,
the initial expression of a computation is printed before it is evaluated.
If the verbose mode is on and the verbosity level (see below)
is non-zero, the type of the initial expression is also printed
and the output of the evaluation is more detailed.

\item[\fbox{\code{+/-warn}}]\pindex{warn} Parser warnings. If the parser
warnings are turned on (default), the parser will print
warnings about variables that occur only once in a program rule
(see Section~\ref{sec-restrictions})
or locally declared names that shadow the definition of
globally declared names. If the parser warnings are switched off,
these warnings are not printed during the reading of a Curry program.

\item[\fbox{\code{path $path$}}]\pindex{path} Set the additional search path
for loading modules to $path$.
Note that this search path is only used for loading modules
inside this invocation of \CYS, i.e., the environment variable
\ccode{CURRYPATH}\pindex{CURRYPATH} (see also Section~\ref{sec-modules})
is set to $path$ in this invocation of \CYS.

The path is a list of directories separated by \ccode{:}.
The prefix \ccode{\char126} is replaced by the home directory as
in the following example:
\begin{curry}
:set path aux:~/tests
\end{curry}
Relative directory names are replaced by absolute ones
so that the path is independent of later changes of the
current working directory.

\item[\fbox{\code{printdepth $n$}}]\pindex{printdepth}
Set the depth for printing terms to the value \code{n} (initially: 0).
In this case subterms with a depth greater than \code{n} are abbreviated
by dots when they are printed as a result of a computation
or during debugging. A value of \code{0} means infinite depth
so that the complete terms are printed.

\item[\fbox{\code{v$n$}}]\pindex{v}\index{verbosity}
Set the verbosity level to $n$. The following values are allowed
for $n$:
\begin{description}
\item[$n=0$:] Do not show any messages (except for errors).
\item[$n=1$:] Show only messages of the front-end, like loading
of modules.
\item[$n=2$:]
Show also messages of the back end, like loading intermediate files
or generating Prolog target files.
\item[$n=3$:]
Show also messages related to loading Prolog files and libraries
into the run-time systems and other intermediate messages and results.
\end{description}

\item[\fbox{\code{safe}}]\pindex{safe}
Turn on the safe execution mode.
In the safe execution mode, the initial goal is
not allowed to be of type \code{IO} and the program should not
import the module \code{Unsafe}.
Furthermore, the allowed commands are
\code{eval}, \code{load}, \code{quit}, and \code{reload}.
This mode is useful to use \CYS in uncontrolled environments,
like a computation service in a web page, where \CYS could
be invoked by
\begin{curry}
pakcs :set safe
\end{curry}

\item[\fbox{\code{parser $opts$}}]\pindex{parser}
Define additional options passed to the front end of \CYS, i.e.,
the parser program \code{\cyshome/bin/pakcs-frontend}.
For instance, setting the option
\begin{curry}
:set parser -F --pgmF=transcurry
\end{curry}
has the effect that each Curry module to be compiled is
transformed by the preprocessor command \code{transcurry}
into a new Curry program which is actually compiled.

\item[\fbox{\code{args $arguments$}}]\pindex{args}
Define run-time arguments for the evaluation
of the main expression.
For instance, setting the option
\begin{curry}
:set args first second
\end{curry}
has the effect that the I/O operation \code{getArgs}
(see library \code{System} (Section~\ref{Library:System.Environment})
returns the value \code{["first","second"]}.

\end{description}
%
\bigskip
%
\CYS can also execute programs in the {\bf debug mode}.
\index{debug mode}\pindex{debug}
The debug mode is switched on by setting the \code{debug} option
with the command \ccode{:set +debug}. In order to switch
back to normal evaluation of the program, one has to execute
the command \ccode{:set -debug}.

In the debug mode, \CYS offers the following additional options:
%
\begin{description}
\item[\fbox{\code{+/-single}}]\pindex{single}
Turn on/off single mode for debugging.
If the single mode is on, the evaluation of an expression
is stopped after each step and the user is asked how to proceed
(see the options there).

\item[\fbox{\code{+/-trace}}]\pindex{trace}
Turn on/off trace mode for debugging.
If the trace mode is on, all intermediate expressions occurring
during the evaluation of an expressions are shown.

\item[\fbox{\code{spy $f$}}]\pindex{spy}
Set a spy point (break point) on the
function $f$. In the single mode, you can ``leap'' from spy point
to spy point (see the options shown in the single mode).

\item[\fbox{\code{+/-spy}}]\pindex{spy} Turn on/off spy mode for debugging.
If the spy mode is on, the single mode is automatically activated
when a spy point is reached.
\end{description}


\subsection{Using \CYS in Batch Mode}

Although \CYS is primarily designed as an interactive system,
it can also be used to process data in batch mode.
For example, consider a Curry program, say \code{myprocessor}, that
reads argument strings from the command line and processes them.
Suppose the entry point is a function called \code{just_doit}
that takes no arguments. Such a processor can be invoked from
the shell as follows:
\begin{curry}
> pakcs :set args string1 string2 :load myprocessor.curry :eval just_doit :quit
\end{curry}
The \ccode{:quit} directive in necessary to avoid \CYS going
into interactive mode after the
excution of the expression being evaluated.
The actual run-time arguments (\code{string1}, \code{string2})
are defined by setting the option \code{args} (see above).

Here is an example to use \CYS in this way:
\begin{curry}
> pakcs :set args Hello World :add System :eval "getArgs >>= putStrLn . unwords" :quit
Hello World
>
\end{curry}


\subsection{Command Line Editing}
\label{sec:readline}

In order to have support for line editing or history functionality
in the command line of \CYS (as often supported by the \code{readline}
library), you should have the Unix command \code{rlwrap} installed
on your local machine.
If \code{rlwrap} is installed, it is used by \CYS if called on a terminal.
If it should not be used (e.g., because it is executed
in an editor with \code{readline} functionality), one can
call \CYS with the parameter \ccode{--noreadline}.


\subsection{Customization}
\label{sec-customization}

In order to customize the behavior of \CYS to your own preferences,
there is a configuration file which is read by \CYS when it is invoked.
When you start \CYS for the first time, a standard version of
this configuration file is copied with the name
\ccode{.pakcsrc}\pindex{pakcsrc}\pindex{.pakcsrc}
into your home directory. The file contains definitions
of various settings, e.g., about showing warnings, progress messages etc.
After you have started \CYS for the first time, look into this file
and adapt it to your own preferences.


\subsection{Emacs Interface}

Emacs is a powerful programmable editor suitable for program development.
It is freely available for many platforms
(see \url{http://www.emacs.org}).
The distribution of \CYS contains also a special
\emph{Curry mode}\index{Curry mode}\index{Emacs}
that supports the development of Curry programs in
the Emacs environment.
This mode includes support for syntax highlighting,
finding declarations in the current buffer, and
loading Curry programs into \CYS
in an Emacs shell.

The Curry mode has been adapted from a similar mode for Haskell programs.
Its installation is described in the file \code{README}
in directory \ccode{\cyshome/tools/emacs} which also contains
the sources of the Curry mode and a short description about
the use of this mode.


%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "manual"
%%% End: 
