Commit b8fec0e5 authored by Michael Hanus's avatar Michael Hanus
Browse files

Manual updated, documentation of tools moved into currytools repo

parent b203fd82
currytools @ ef3f1a84
Subproject commit aa4d868612fc97be353527be788b5175bc95dbef
Subproject commit ef3f1a84a7e3c3bd5e0d9850f6b90262b056a9ff
......@@ -20,10 +20,10 @@ is translated into explicit case/or expressions
This representation might be useful for other back ends and
compilers for Curry and is the basis doing meta-programming in Curry.
This file is implicitly
generated when a program is read by \CYS.
generated when a program is compiled with \CYS.
It can be also explicitly generated by the Curry front end\pindex{cymake}
cymake --flat -i$\cyshome$/lib -i$\cyshome$/lib/meta prog
cymake --flat -i$\cyshome$/lib prog
The FlatCurry representation of a Curry program is usually
generated by the front-end after parsing, type checking and eliminating
......@@ -44,10 +44,7 @@ i.e., it is similar to \code{prog.fcy} but contains only exported
entities and the bodies of all functions omitted (i.e., ``external'').
This representation is useful for providing a fast access
to module interfaces.
It can be also implicitly generated by the Curry front end\pindex{cymake}
cymake --flat -i$\cyshome$/lib -i$\cyshome$/lib/meta prog
This file is implicitly generated when a program is compiled with \CYS
and stored in the same directory as \code{prog.fcy}.
\item[\code{}:] This file contains a Prolog program
\section{\cb: A Tool for Analyzing and Browsing Curry Programs}
\cb is a tool to browse through the modules and functions
of a Curry application, show them in various formats,
and analyze their properties.\footnote{Although \cb is
implemented in Curry, some functionalities of it require an
installed graph visualization tool (dot \url{}),
otherwise they have no effect.}
Moreover, it is constructed in a way so that
new analyzers can be easily connected to \cb.
A detailed description of the ideas behind this tool can be
found in \cite{Hanus05WCFLP,Hanus06WLPE}.
\cb is part of the \CYS distribution and can be
started in two ways:
In the command shell via the command: \code{\cyshome/bin/currybrowser mod}
In the \CYS environment after loading the module
\code{mod} and typing the command \ccode{:browse}.
Here, \ccode{mod} is the name of the main module of a Curry application.
After the start, \cb loads the interfaces of the main
module and all imported modules before a GUI is created
for interactive browsing.
\caption{Snapshot of the main window of CurryBrowser\label{fig-currybrowser}}
To get an impression of the use of \cb, Figure~\ref{fig-currybrowser}
shows a snapshot of its use on a particular application
(here: the implementation of \cb).
The upper list box in the left column shows the modules and their imports
in order to browse through the modules of an application.
Similarly to directory browsers, the list of imported modules of a module
can be opened or closed by clicking.
After selecting a module in the list of modules, its source code,
interface, or various other formats of the module can be shown
in the main (right) text area. For instance, one can show
pretty-printed versions of the intermediate flat programs (see below)
in order to see how local function definitions are translated by lambda lifting
or pattern matching is translated into case expressions \cite{Hanus97POPL,Wadler87}.
Since Curry is a language with parametric polymorphism and type inference,
programmers often omit the type signatures when defining functions.
Therefore, one can also view (and store) the selected module as source code where
missing type signatures are added.
Below the list box for selecting modules, there is a menu
(``Analyze selected module'') to analyze all functions
of the currently selected module at once. This is useful
to spot some functions of a module that could be problematic
in some application contexts, like functions that are impure (i.e., the result
depends on the evaluation time) or partially defined (i.e.,
not evaluable on all ground terms).
If such an analysis is selected,
the names of all functions are shown in the
lower list box of the left column (the ``function list'')
with prefixes indicating the properties of the individual functions.
The function list box can be also filled with functions
via the menu ``Select functions''. For instance, all functions
or only the exported functions defined in the currently selected
module can be shown there, or all functions from different modules
that are directly or indirectly called from
a currently selected function.
This list box is central to focus on a function in the
source code of some module or to analyze some function,
i.e., showing their properties. In order to focus on a function,
it is sufficient to check the ``focus on code'' button.
To analyze an individually selected function, one can
select an analysis from the list of available program analyses
(through the menu ``Select analysis'').
In this case, the analysis results are either shown
in the text box below the main text area
or visualized by separate tools, e.g., by a graph drawing tool for
visualizing call graphs.
Some analyses are local, i.e., they need only to consider the local definition
of this function (e.g., ``Calls directly,'' ``Overlapping rules,''
``Pattern completeness''),
where other analyses are global, i.e.,
they consider the definitions of all functions directly or indirectly called
by this function (e.g., ``Depends on,'' ``Solution complete,''
Finally, there are a few additional tools integrated into \cb,
for instance, to visualize the import relation between all modules
as a dependency graph. These tools are available through the ``Tools'' menu.
More details about the use of \cb and all built-in analyses
are available through the ``Help'' menu of \cb.
\section{CurryDoc: A Documentation Generator for Curry Programs}
\index{program!documentation}\index{documentation generator}
is a tool in the PAKCS distribution that generates
the documentation for a Curry program (i.e., the main module
and all its imported modules) in HTML format.
The generated HTML pages contain information about
all data types and functions exported by a module as well
as links between the different entities.
Furthermore, some information about the definitional status
of functions (like rigid, flexible, external, complete, or
overlapping definitions) are provided and combined with
documentation comments provided by the programmer.
A \emph{documentation comment}
\index{documentation comment}\index{comment!documentation}
starts at the beginning of a line
with \ccode{--- }\pindex{---} (also in literate programs!).
All documentation comments immediately before a
definition of a datatype or (top-level) function are kept together.\footnote{%
The documentation tool recognizes this association from the first identifier
in a program line. If one wants to add a documentation comment
to the definition of a function which is an infix operator,
the first line of the operator definition should be a type definition,
otherwise the documentation comment is not recognized.}
The documentation comments for the complete module occur before
the first ``module'' or ``import'' line in the module.
The comments can also contain several special tags. These tags
must be the first thing on its line (in the documentation comment)
and continues until the next tag is encountered or until the
end of the comment. The following tags are recognized:
\item[\code{@author}]\pindex{"@author} \emph{comment}\\
Specifies the author of a module (only reasonable in module comments).
\item[\code{@version}]\pindex{"@version} \emph{comment}\\
Specifies the version of a module (only reasonable in module comments).
\item[\code{@cons}]\pindex{"@cons} \emph{id} \emph{comment}\\
A comment for the constructor \emph{id} of a datatype
(only reasonable in datatype comments).
\item[\code{@param}]\pindex{"@param} \emph{id} \emph{comment}\\
A comment for function parameter \emph{id}
(only reasonable in function comments).
Due to pattern matching, this need not be the name of a parameter
given in the declaration of the function but all parameters
for this functions must be commented in left-to-right order
(if they are commented at all).
\item[\code{@return}]\pindex{"@return} \emph{comment}\\
A comment for the return value of a function
(only reasonable in function comments).
The comment of a documented entity can be any string in
\href{}{Markdown's syntax}\index{markdown}
(the currently supported set of elements
is described in detail in the appendix).
For instance, it can contain Markdown annotations for
emphasizing elements (e.g., \verb!_verb_!),
strong elements (e.g., \verb!**important**!),
code elements (e.g., \verb!`3+4`!), code blocks (lines prefixed by four blanks),
unordered lists (lines prefixed by ``\verb! * !''),
ordered lists (lines prefixed by blanks followed by a digit and a dot),
quotations (lines prefixed by ``\verb!> !''),
and web links of the form \ccode{<http://\ldots>}
or \ccode{[link text](http://\ldots)}.
If the Markdown syntax should not be used, one could run CurryDoc
with the parameter \ccode{--nomarkdown}.
The comments can also contain markups in HTML format
so that special characters like \ccode{<}
must be quoted (e.g., \ccode{\&lt;}).
However, header tags like \code{<h1>} should not be used
since the structuring is generated by CurryDoc.
In addition to Markdown or HTML markups,
one can also mark \emph{references to names} of operations or data types
in Curry programs which are translated into links inside
the generated HTML documentation. Such references have to be
enclosed in single quotes. For instance, the text
\verb!'conc'! refers to the Curry operation \code{conc}
inside the current module whereas the text
\verb!'Prelude.reverse'! refers to the operation \code{reverse}
of the module \code{Prelude}.
If one wants to write single quotes without this specific
meaning, one can escape them with a backslash:
--- This is a comment without a \'reference\'.
To simplify the writing of documentation comments,
such escaping is only necessary for single words,
i.e., if the text inside quotes has not the syntax of
an identifier, the escaping can be omitted, as in
--- This isn't a reference.
The following example text shows a Curry program with some
documentation comments:
--- This is an
--- example module.
--- @author Michael Hanus
--- @version 0.1
module Example where
--- The function `conc` concatenates two lists.
--- @param xs - the first list
--- @param ys - the second list
--- @return a list containing all elements of `xs` and `ys`
conc [] ys = ys
conc (x:xs) ys = x : conc xs ys
-- this comment will not be included in the documentation
--- The function `last` computes the last element of a given list.
--- It is based on the operation 'conc' to concatenate two lists.
--- @param xs - the given input list
--- @return last element of the input list
last xs | conc ys [x] =:= xs = x where x,ys free
--- This data type defines _polymorphic_ trees.
--- @cons Leaf - a leaf of the tree
--- @cons Node - an inner node of the tree
data Tree a = Leaf a | Node [Tree a]
To generate the documentation, execute the command\pindex{currydoc}
currydoc Example
(\code{currydoc} is a command usually stored in \code{$pakcshome$/bin}
where $pakcshome$ is the installation directory of PAKCS;
see Section~\ref{sec-general}).
This command creates the directory \code{DOC_Example} (if it does not exist)
and puts all HTML documentation files for the main program module
and all its imported modules in this directory together with
a main index file \code{index.html}.
If one prefers another directory for the documentation files,
one can also execute the command
currydoc docdir Example
where \code{docdir} is the directory for the documentation files.
In order to generate the common documentation for large collections
of Curry modules (e.g., the libraries contained in the PAKCS distribution),
one can call \code{currydoc} with the following options:
\item[\code{currydoc --noindexhtml docdir Mod}~:]
This command generates the documentation for module \code{Mod}
in the directory \code{docdir} without the index pages (i.e., main index page
and index pages for all functions and constructors defined in \code{Mod}
and its imported modules).
\item[\code{currydoc --onlyindexhtml docdir Mod1 Mod2 \ldots Mod$n$}~:]
This command generates only the index pages (i.e., a main index page
and index pages for all functions and constructors defined in the modules
\code{Mod1}, \code{M2},\ldots,\code{Mod$n$} and their imported modules)
in the directory \code{docdir}.
%%% Local Variables:
%%% mode: pdflatex
%%% TeX-master: "manual"
%%% End:
\section{CurryTest: A Tool for Testing Curry Programs}
CurryTest\index{CurryTest}\index{testing programs}\index{program!testing}
is a simple tool in the \CYS distribution to write
and run repeatable tests. CurryTest simplifies the task
of writing test cases for a module and executing them.
The tool is easy to use. Assume one has implemented a module \code{MyMod}
and wants to write some test cases to test its functionality,
making regression tests in future versions, etc.
For this purpose, there is a system library \code{Assertion}
(Section~\ref{Library:Assertion}) which
contains the necessary definitions for writing tests.
In particular, it exports an abstract polymorphic type \ccode{Assertion a}
together with the following operations:
assertTrue :: String -> Bool -> Assertion ()
assertEqual :: String -> a -> a -> Assertion a
assertValues :: String -> a -> [a] -> Assertion a
assertSolutions :: String -> (a->Bool) -> [a] -> Assertion a
assertIO :: String -> IO a -> a -> Assertion a
assertEqualIO :: String -> IO a -> IO a -> Assertion a
The expression \ccode{assertTrue $s$ $b$}
is an assertion (named $s$) that the expression $b$ has the value \code{True}.
Similarly, the expression \ccode{assertEqual $s$ $e_1$ $e_2$}
asserts that the expressions $e_1$ and $e_2$
must be equal (i.e., \code{$e_1$==$e_2$} must hold),
the expression \ccode{assertValues $s$ $e$ $vs$} asserts
that $vs$ is the multiset of all values of $e$,
and the expression \ccode{assertSolutions $s$ $c$ $vs$} asserts
that the constraint abstraction $c$ has the multiset of solutions $vs$.
Furthermore, the expression \ccode{assertIO $s$ $a$ $v$}
asserts that the I/O action $a$ yields the value $v$ whenever it is
executed, and
the expression \ccode{assertEqualIO $s$ $a_1$ $a_2$}
asserts that the I/O actions $a_1$ and $a_2$ yield equal values.
The name $s$ provided as a first argument in each assertion
is used in the protocol produced by the test tool.
One can define a test program by importing the module
to be tested together with the module \code{Assertion} and defining
top-level functions of type \code{Assertion} in this module
(which must also be exported).
As an example, consider the following program
that can be used to test some list processing functions:
import List
import Assertion
test1 = assertEqual "++" ([1,2]++[3,4]) [1,2,3,4]
test2 = assertTrue "all" (all (<5) [1,2,3,4])
test3 = assertSolutions "prefix" (\x -> x++_ =:= [1,2])
For instance, \code{test1} asserts that the result of evaluating the
expression \code{([1,2]++[3,4])} is equal to \code{[1,2,3,4]}.
We can execute a test suite by the command\pindex{currytest}
currytest TestList
(\code{currytest} is a program stored in \code{\cyshome/bin}
where \cyshome is the installation directory of \CYS;
see Section~\ref{sec-general}).
In our example, \ccode{TestList.curry} is the program containing the
definition of all assertions. This has the effect
that all exported top-level functions
of type \code{Assertion} are tested (i.e., the corresponding
assertions are checked) and the results
(\ccode{OK} or failure) are reported together with the name of each assertion.
%If failures occur, the complete test results are also
%written into a file named \ccode{TestList.testlog}.''
For our example above, we obtain the following successful protocol:
Testing module "TestList"...
OK: ++
OK: all
OK: prefix
All tests successfully passed.
There is also a graphical interface that summarizes the results
more nicely.\footnote{Due to a bug in older versions of SICStus-Prolog,
it works only with SICStus-Prolog version 3.8.5 (or newer).}
In order to start this interface, one has to add the parameter
\ccode{--window} (or \ccode{-w}), e.g., executing a test suite by
currytest --window TestList
currytest -w TestList
A snapshot of the interface is shown in Figure~\ref{fig-currytest}.
\caption{Snapshot of CurryTest's graphical interface\label{fig-currytest}}
\section{ERD2Curry: A Tool to Generate Programs from ER Specifications}
ERD2Curry\index{ERD2Curry}\index{database programming}
is a tool to generate Curry code to access and manipulate data
persistently stored from
entity relationship diagrams.\index{entity relationship diagrams}
The idea of this tool is described in detail in
Thus, we describe only the basic steps to use this tool
in the following.
If one creates an entity relationship diagram (ERD)
with the Umbrello UML Modeller, one has to store its
XML description in XMI format (as offered by Umbrello)
in a file, e.g., \ccode{myerd.xmi}.
This description can be compiled into a Curry program by the
erd2curry -x myerd.xmi
(\code{erd2curry} is a program stored in \code{\cyshome/bin}
where \cyshome is the installation directory of \CYS;
see Section~\ref{sec-general}).
If \code{MyData} is the name of the ERD, the Curry program file
\ccode{MyData.curry} is generated containing all the necessary
database access code as described in \cite{BrasselHanusMueller08PADL}.
In addition to the generated Curry program file,
two auxiliary program files
\code{ERDGeneric.curry} and \code{KeyDatabase.curry}
are created in the same directory.
If one does not want to use the Umbrello UML Modeller,
which might be the preferred method since the interface to the
Umbrello UML Modeller is no longer actively supported,
one can also create a textual description of the ERD
as a Curry term of type \code{ERD}
(w.r.t.\ the type definition given in module
and store it in some file, e.g., \ccode{myerd.term}.
This description can be compiled into a Curry program by the
erd2curry -t myerd.term
The directory \code{\cyshome/currytools/erd2curry/}
contains two examples for such ERD term files:
This is a simple ERD model for a blog with entries, comments,
and tags.
This is an ERD model for university lectures as
presented in the paper \cite{BrasselHanusMueller08PADL}.
There is also the possibility to visualize an ERD term
as a graph with the graph visualization program \code{dotty}
(for this purpose, it might be necessary to adapt the definition
of \code{dotviewcommand} in your \ccode{\curryrc} file,
see Section~\ref{sec-customization},
according to your local environment).
The visualization can be performed by the command
erd2curry -v myerd.term
......@@ -173,8 +173,6 @@ of the order of pattern matching. Note that other orders of pattern matching
can be obtained using auxiliary operations.
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "manual"
\subsection {Datatypes with Field Labels}\label{flab}
A datatype declaration may optionally define data constructors
with field labels.\footnote{Field labels are quite similar
to Haskell \cite{PeytonJones03Haskell} so that we adopt most of
the description of Haskell here.}
These field labels can be used to
construct, select from, and update fields in a manner that is
independent of the overall structure of the datatype.
\subsubsection{Declaration of Constructors with Labeled Fields}
A data constructor of arity $n$ creates an object with $n$ components.
These components are normally accessed positionally as arguments to
the constructor in expressions or patterns. For large datatypes it is
useful to assign \emph{field labels}\index{label}\index{field label}
to the components of a data
object. This allows a specific field to be referenced independently of
its location within the constructor. A constructor definition in a
data declaration may assign labels to the fields of the constructor,
using the \emph{record syntax}\index{record syntax}\pindex{\{\ldots{}\}}
Constructors using field labels
may be freely mixed with constructors without them. A constructor with
associated field labels may still be used as an ordinary constructor.
The various use of labels (see below)
are simply a shorthand for operations using an
underlying positional constructor. The arguments to the positional
constructor occur in the same order as the labeled fields.
\trans{$C$ \{ $lts$ \}} $=$ $C$ \trans{$lts$}\\
\trans{$lt$, $lts$} $=$ \trans{$lt$} \trans{$lts$}\\
\trans{$l$, $ls$\,::\,$t$} $=$ $t$ \trans{$ls$\,::\,$t$}\\
\trans{$l$\,::\,$t$} $=$ $t$
For example, the definition using field labels
data Person = Person { firstName, lastName :: String, age :: Int }
| Agent { firstName, lastName :: String, trueIdentity :: Person }
is translated to
data Person = Person String String Int
| Agent String String Person
A data declaration may use the same field label in multiple
constructors as long as the typing of the field is the same in all
cases after type synonym expansion. A label cannot be shared by more
than one type in scope. Field names share the top-level name space with
ordinary definition of functions % and class methods
and must not conflict with other top-level names in scope.
Consider the following example:
data S = S1 { x :: Int } | S2 { x :: Int } -- OK
data T = T1 { y :: Int } | T2 { y :: Bool } -- BAD
Here S is legal but T is not, because y is given inconsistent typings in the latter.
\subsubsection{Field Selection}\label{flab-sel}
Field labels are used as \emph{selector functions},\index{selector function}
i.e., each field label serves as a function
that extracts the field from an object. Selectors are top-level
bindings and so they may be shadowed by local variables but cannot
conflict with other top-level bindings of the same name. This
shadowing only affects selector functions; in record construction
(Section \ref{flab-constr}) and update (Section \ref{flab-upd}), field
labels cannot be confused with ordinary variables.
\translation{A field label $lab$ introduces a selector function defined as:\\
\code{$lab$ ($C_1$ $p_{11}$ \ldots $p_{1k_1}$) = x}\\
\code{$lab$ ($C_n$ $p_{n1}$ \ldots $p_{nk_n}$) = x}\\
where $C_1\ldots C_n$ are all the constructors of the datatype containing
a field labeled with $lab$, $p_{ij}$ is \code{x} when $lab$ labels the $j$th
component of $C_i$ or \code{\us} otherwise.}
For example the definition of \code{Person} above introduces the selector functions
firstName :: Person -> String
firstName (Person x _ _) = x
firstName (Agent x _ _) = x
lastName :: Person -> String
lastName (Person _ x _) = x
lastName (Agent _ x _) = x
age :: Person -> Int
age (Person _ _ x) = x
trueIdentity :: Person -> Person
trueIdentity (Agent _ _ x) = x
\subsubsection{Construction Using Field Labels}\label{flab-constr}
A constructor with labeled fields may be used to construct a value in
which the components are specified by name rather than by
position. In this case, the components are enclosed by braces.
Construction using field labels is subject to the following
\item Only field labels declared with the specified constructor may be
\item A field label may not be mentioned more than once.
\item Fields not mentioned are initialized to different free variables.
The expression \code{C\{\}}, where \code{C} is a data constructor,
is legal \emph{whether or not \code{C} was declared with record syntax};
it denotes \code{C Prelude.unknown$_1$ \ldots{} Prelude.unknown$_n$}
where $n$ is the arity of \code{C}.
Note that this will introduce the constructor \code{C} with
$n$ \emph{different} free variables as arguments.
\translation{In the binding $f = v$, the field $f$ labels $v$.\\
\centerline{\code{$C$ \{ $bs$ \} = $C$ ($pick_1^C\ bs\ \code{Prelude.unknown}$) \ldots{}
($pick_k^C\ bs\ \code{Prelude.unknown}$)}}
where $k$ is the arity of $C$.\\
The auxiliary function $pick_i^C\ bs\ d$ is defined as follows:
If the $i$th component of a constructor $C$ has the field label $f$ and $f = v$
appears in the binding list $bs$, then $pick_i^C\ bs\ d$ is $v$.
Otherwise, $pick_i^C\ bs\ d$ is the default value $d$.}
For example, a \code{Person} can be constructed by
smith = Agent { lastName = "Smith", firstName = "Agent" }
which is equivalent to the following agent, whose true identity
might be any person:
smith = Agent "Agent" "Smith" _
\subsubsection{Updates Using Field Labels}\label{flab-upd}
Values belonging to a datatype with field labels may be
non-destructively updated. This creates a new value in which the