How to use COOSy:
=================

COOSy (Curry Object Observation System) is a tool to observe
the execution of programs written in the declarative
multi-paradigm language Curry. It is based on the idea
to observe the evaluation of expressions (including functions
and logical variables) in a Curry program. Thus, one must
annotate the expressions to be observed in a Curry program
as explained in the following.

The observation of an expression is done by the following steps:

1. Start the COOSy environment by the command ":coosy" in the PAKCS
   environment. This command also adds to the load path the directory
   containing the modules to be imported for executing observations
   (see below).

2. Import the module "Observe" into your program by the import
   declaration "import Observe".

3. Annotate the expression to be observed. For instance, if e
   is this expression in your program, replace e by
     (observe <otype> <omsg> e)
   where <omsg> is a string to be printed with this observation
   and <otype> is an appropriate observer for the type of e.
   The library Observe defines observers for various types,
   e.g., oInt, oBool, oChar, oFloat, oSuccess for the base types,
   oLit for enumeration types consisting only of 0-ary data constructors,
   oList, oString, oPair, oTriple, oMaybe, oEither for some basic
   structured types, and a combinator ~> for functional types.
   Further observers can be automatically derived (see below).

4. Load and run your program with the PAKCS system.

5. Show the observations with the "Show" button in the COOSy environment.



A few examples:
===============

- Observe the evaluation of an integer expression (x+y):

     (observe oInt "Addition" (x+y))


- Observe the evaluation of an infinite list ([1..]):

     (observe (oList oInt) "enumFrom 1" [1..])

  If your program terminates, only the evaluated parts of this list
  are shown.


- Observe the evaluation (i.e., instantiations) of a logical variable x:

     (observe (oList oInt) "List variable" x) ++ y =:= [1,2]


- Observe the evaluation of a function (reverse):

     (observe (oList oInt ~> oList oInt) "reverse" reverse) [1,2,3]


- Observe all evaluations of a function (reverse):
  Insert a new function definition with observers

     orev = observe (oList oInt ~> oList oInt) "all_reverse" reverse

  and replace all calls to "reverse" (with integer lists) by "orev", e.g.

     orev [1,2] ++ orev [3,4]


- Observe all evaluations of a higher-order function (foldr):

     (observe ((oInt ~> oInt ~> oInt) ~> oInt ~> oList oInt ~> oInt)
              "foldr" foldr) (+) 0 [1..4]

  Note that in this example the representation of functions as bags
  of input/output tuples is relevant to represent the functional argument.


Interpretation of the output:
=============================

"_": unevaluated argument

"!": undefined result

"?": logical variable

"?/v": logical variable bound to value v

"{ ... }": Functional value represented as input/output pairs



Automatic generation of observers for user-defined types
========================================================

If you need observer functions for your own datatypes,
COOSy can automatically derive them from the datatype definitions
in your program. For this purpose, click on the button "Add observers"
and select your Curry program. As a result, all necessary definitions
of observer functions are added to your source program.