Skip to content
GitLab
Commit 846d7a0b authored by Michael Hanus's avatar Michael Hanus
Browse files

Manuals added to various tools in order to use them for both PAKCS and KiCS2

parent aa4d8686
Hide whitespace changes
Inline Side-by-side
browser/Docs/README.txt 0 → 100644
View file @ 846d7a0b
This directory contains some documention for the tool:
manual.tex:
A short description to be included in the main manual of the Curry system.
\ No newline at end of file
browser/Docs/manual.tex 0 → 100644
View file @ 846d7a0b
\section{\cb: A Tool for Analyzing and Browsing Curry Programs}
\label{sec-currybrowser}
\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{http://www.graphviz.org/}),
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:
\begin{itemize}
\item
In the command shell via the command: \code{\cyshome/bin/currybrowser mod}
\item
In the \CYS environment after loading the module
\code{mod} and typing the command \ccode{:browse}.
\end{itemize}
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.
\begin{figure}[t]
\begin{center}
\includegraphics[scale=0.7]{\curryhome/currytools/browser/Docs/currybrowser.jpg}
\end{center}
\caption{Snapshot of the main window of CurryBrowser\label{fig-currybrowser}}
\end{figure}
%
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
\cite{Johnsson85}
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,''
``Set-valued'').
%
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.
currydoc/Docs/README.txt 0 → 100644
View file @ 846d7a0b
This directory contains some documention for the tool:
manual.tex:
A short description to be included in the main manual of the Curry system.
\ No newline at end of file
currydoc/Docs/manual.tex 0 → 100644
View file @ 846d7a0b
\section{CurryDoc: A Documentation Generator for Curry Programs}
CurryDoc\index{CurryDoc}%
\index{program!documentation}\index{documentation generator}
is a tool in the \CYS 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:
\begin{description}
\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).
\end{description}
The comment of a documented entity can be any string in
\href{http://en.wikipedia.org/wiki/Markdown}{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:
\begin{curry}
--- This is a comment without a \'reference\'.
\end{curry}
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
\begin{curry}
--- This isn't a reference.
\end{curry}
%
The following example text shows a Curry program with some
documentation comments:
\begin{curry}
--- 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]
\end{curry}
\noindent
To generate the documentation, execute the command\pindex{currydoc}
\begin{curry}
currydoc Example
\end{curry}
(\code{currydoc} is a command usually stored in \code{\cyshome/bin}
where \cyshome is the installation directory of \CYS;
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
\code{Example}
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
\begin{curry}
currydoc docdir Example
\end{curry}
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 \CYS distribution),
one can call \code{currydoc} with the following options:
\begin{description}
\item[\code{currydoc --noindexhtml docdir Mod}~:]
\pindex{noindex}
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$}~:]
\pindex{onlyindex}
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}.
\end{description}
%%% Local Variables:
%%% mode: pdflatex
%%% TeX-master: "manual"
%%% End:
currytest/Docs/README.txt 0 → 100644
View file @ 846d7a0b
This directory contains some documention for the tool:
manual.tex:
A short description to be included in the main manual of the Curry system.
\ No newline at end of file
currytest/Docs/manual.tex 0 → 100644
View file @ 846d7a0b
\section{CurryTest: A Tool for Testing Curry Programs}
\label{sec-currytest}
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:
\begin{curry}
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
\end{curry}
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:
\begin{curry}
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])
[[],[1],[1,2]]
\end{curry}
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}
\begin{curry}
currytest TestList
\end{curry}
(\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:
\begin{curry}
============================================================
Testing module "TestList"...
OK: ++
OK: all
OK: prefix
All tests successfully passed.
============================================================
\end{curry}
There is also a graphical interface that summarizes the results
more nicely.
In order to start this interface, one has to add the parameter
\ccode{--window} (or \ccode{-w}), e.g., executing a test suite by
\begin{curry}
currytest --window TestList
\end{curry}
or
\begin{curry}
currytest -w TestList
\end{curry}
A snapshot of the interface is shown in Figure~\ref{fig-currytest}.
\begin{figure}%[t]
\begin{center}
\includegraphics[scale=0.7]{\curryhome/currytools/currytest/Docs/currytest.jpg}
\end{center}
\caption{Snapshot of CurryTest's graphical interface\label{fig-currytest}}
\end{figure}
erd2curry/Docs/README.txt 0 → 100644
View file @ 846d7a0b
This directory contains some documention for the tool:
manual.tex:
A short description to be included in the main manual of the Curry system.
\ No newline at end of file
erd2curry/Docs/manual.tex 0 → 100644
View file @ 846d7a0b
\section{ERD2Curry: A Tool to Generate Programs from ER Specifications}
\label{sec-erd2curry}
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
\cite{BrasselHanusMueller08PADL}.
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
command\pindex{erd2curry}
\begin{curry}
erd2curry -x myerd.xmi
\end{curry}
(\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
\code{\cyshome/currytools/erd2curry/ERD.curry})
and store it in some file, e.g., \ccode{myerd.term}.
This description can be compiled into a Curry program by the
command\pindex{erd2curry}
\begin{curry}
erd2curry -t myerd.term
\end{curry}
%
The directory \code{\cyshome/currytools/erd2curry/}
contains two examples for such ERD term files:
\begin{description}
\item[\code{Blog.erdterm}:]
This is a simple ERD model for a blog with entries, comments,
and tags.
\item[\code{Uni.erdterm}:]
This is an ERD model for university lectures as
presented in the paper \cite{BrasselHanusMueller08PADL}.
\end{description}
%
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
\begin{curry}
erd2curry -v myerd.term
\end{curry}
spicey/Docs/README.txt 0 → 100644
View file @ 846d7a0b
This directory contains some documention for the tool:
manual.tex:
A short description to be included in the main manual of the Curry system.
\ No newline at end of file
spicey/Docs/manual.tex 0 → 100644
View file @ 846d7a0b
\section{Spicey: An ER-based Web Framework}
\label{sec-spicey}
Spicey\index{Spicey} is a framework to support the implementation of
web-based systems in Curry. Spicey generates an initial implementation
from an entity-relationship (ER) description of the underlying
data. The generated implementation contains operations to create and
manipulate entities of the data model, supports authentication,
authorization, session handling, and the composition of individual
operations to user processes. Furthermore, the implementation ensures
the consistency of the database w.r.t. the data dependencies specified
in the ER model, i.e., updates initiated by the user cannot lead to an
inconsistent state of the database.
The idea of this tool, which is part of the distribution of \CYS,
is described in detail in \cite{HanusKoschnicke10PADL}.
Thus, we describe only the basic steps to use this tool
in order to generate a web application.
First, one has to create a textual description of the
entity-relationship model
as a Curry term of type \code{ERD}
(w.r.t.\ the type definitions given in module
\code{\cyshome/currytools/erd2curry/ERD.curry})
and store it in some file, e.g., \ccode{mymodel.erdterm}.
The directory \code{\cyshome/currytools/spicey/}
contains two examples for such ERD term files:
\begin{description}
\item[\code{Blog.erdterm}:]
This is a simple ER model for a blog with entries, comments,
and tags, as presented in the paper \cite{HanusKoschnicke10PADL}.
\item[\code{Uni.erdterm}:]
This is an ER model for university lectures as
presented in the paper \cite{BrasselHanusMueller08PADL}.
\end{description}
%
Then change to the directory in which you want to create
the project sources.
Execute the command\pindex{spiceup}
\begin{curry}
spiceup .../mymodel.erdterm
\end{curry}
with the path to the ERD term file as a parameter
(\code{spiceup} is a program stored in \code{\cyshome/bin}
where \cyshome is the installation directory of \CYS;
see Section~\ref{sec-general}).
You can also provide a path name, i.e., the name of a directory,
where the database files should be stored, e.g.,
\begin{curry}
spiceup --dbpath DBDIR .../mymodel.erdterm
\end{curry}
If the parameter \ccode{--dbpath DBDIR} is not provided,
then DBDIR is set to the current directory (\ccode{.}).
Since this specification will be used in the \emph{generated} web programs,
a relative database directory name will be relative to the place where
the web programs are stored.
In order to avoid such confusion, it might be better to specify
an absolute path name for the database directory.
After the generation of this project (see the generated file
\code{README.txt} for information about the generated project structure),
one can compile the generated programs by
\begin{curry}
make compile
\end{curry}
In order to generate the executable web application,
configure the generated \code{Makefile}
by adapting the variable \code{WEBSERVERDIR} to the location
where the compiled cgi programs should be stored, and run
\begin{curry}
make deploy
\end{curry}
After the successful compilation and deployment of all files,
the application is executable
in a web browser by selecting the URL \code{<URL of web dir>/spicey.cgi}.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment