/**********************************************************************/
/*               klint - Mode Analyzer for KL1 Programs               */
/*                                                                    */
/*                            Version 1.0                             */
/*                             April 1996                             */
/*                                                                    */
/*                           Kazunori Ueda                            */
/*           Department of Information and Computer Science           */
/*                         Waseda University                          */
/*                    ueda@ueda.info.waseda.ac.jp                     */
/*                                                                    */
/*                 Copyright (C) 1996  Kazunori Ueda                  */
/*                                                                    */
/**********************************************************************/

OVERVIEW:

The klint system analyses the mode of a KL1 program using the ideas
described in [1].  Well-modedness roughly means that the communication
protocols used in a program are cooperative.  It is highly recommended
to write your KL1 programs in a well-moded manner, because it enables
the klint system to detect many of program errors statically [3].

You don't have to provide mode declarations to benefit from the mode
system; instead, the klint system will infer the mode of the your
program.

The klint system consists of two parts: a mode constraint generator
(klint1) and a mode constraint solver (klint2).  The mode constraint
generator generates the mode constraints syntactically imposed by a
given KL1 program.  The mode constraint solver tries to solve the set S
of mode constraints by forming a mode graph [1] to see if S is
consistent (satisfiable).  The mode graph thus formed is regarded as
expressing the 'principal' (i.e., most general) mode of the program.  If
S is [in]consistent, the program is said to be [non-]well-moded,
respectively.

An introductory article of mode analysis can be found in [2].


INPUT:

The input to the klint system is a KL1 program that may consist of more
than one module, which are read from stdin (standard input).

OUTPUT:

When the given program is well-moded, the klint system outputs the mode
graph of the program from stdout (standard output).

When the program is non-well-moded, the current version reports what
mode constraint finally caused an mode error, and then outputs the
current mode graph.  Non-well-modedness mean that the set of mode
constraints is inconsistent.  The next version of klint will find
minimal inconsistent subsets of mode constraints, which will help you to
locate bugs better.

The mode constraints generated by the program can be viewed by running
klint1 instead of klint.  Actually, klint is simply a parallel
composition of klint1 and klint2, connected by a Unix pipe.


EXAMPLE:

The program

    :- module m.
    merge([],   Y,    Z ) :- true| Z=Y.
    merge(X,    [],   Z ) :- true| Z=X.
    merge([A|X],Y,    Z0) :- true| Z0=[A|Z], merge(X,Y,Z).
    merge(X,    [A|Y],Z0) :- true| Z0=[A|Z], merge(X,Y,Z).

has the following mode graph:

    node(0): (unconstrained)
     <(m:(=)-0)/2,2> ---> node(13)
     <(m:(=)-0)/2,1> --*> node(13)
     <(m:merge)/3,1> ---> node(13)
     <(m:merge)/3,2> ---> node(13)
     <(m:merge)/3,3> --*> node(13)
     <(m:(=)-1)/2,2> ---> node(13)
     <(m:(=)-1)/2,1> --*> node(13)
     <(m:(=)-2)/2,2> ---> node(13)
     <(m:(=)-2)/2,1> --*> node(13)
     <(m:(=)-3)/2,2> ---> node(13)
     <(m:(=)-3)/2,1> --*> node(13)
    node(13): in
     <list,2> ---> node(13)
     <list,1> ---> node(15)
    node(15): (unconstrained)

By ignoring the arcs corresponding to the arguments of unification body
goals, this can be reduced to:

    node(0): (unconstrained)
     <(m:merge)/3,1> ---> node(13)
     <(m:merge)/3,2> ---> node(13)
     <(m:merge)/3,3> --*> node(13)
    node(13): in
     <list,2> ---> node(13)
     <list,1> ---> node(15)
    node(15): (unconstrained)

The arcs from the root node (0) say that the first and the second
arguments have exactly the same mode, which is represented by node 13,
and that the third argument has an exactly opposite mode.  Node 13 says
that the cdr of a list occurring as an argument of merge will have the
same mode with the whole list.  The graphical representation of this
graph can be found in [3].


INSTALLATION:

klint1 and klint2 are totally written in KL1 and can be compiled using
KLIC.  Use Makefile to make klint1, klint2.  klint is defined as a
shellscript.


FEATURES NOT YET SUPPORTED:

(1) Macro expansion.  We expect that a future release of klic will
feature a KL1 counterpart of cc's  -E option.

(2) 'inline' feature.

(3) Some built-in predicates.


BUGS:

(1) Body goals whose names coincide with those of built-ins are regarded
as calls to built-in predicates, even if the module names are explicitly
specified.

(2) 'arg', 'setarg', 'vector_element', 'set_vector_element' do not check
the consistency of the modes of structures/vectors and those of
elements.  This means that the current system will report weaker
principal modes.

(3) The satisfiability of non-binary constraints that could not be
reduced to unary/binary constraints is not checked.  Instead, the system
reports what non-binary constraints remained unreduced.



REFERENCES:

[1] Ueda, K. and Morita, M., Moded Flat GHC and Its Message-Oriented
Implementation Technique.  New Generation Computing, Vol.13, No.1
(1994), pp.3-43.

[2] Ueda, K., I/O Mode Analysis in Concurrent Logic Programming.  In
Theory and Practice of Parallel Programming, LNCS 907, Springer, 1995,
pp.356-368.

[3] Ueda, K., Experiences with Strong Moding in Concurrent
Logic/Constraint Programming.  In Proc. Int. Workshop on Parallel
Symbolic Languages and Systems (PSLS'95), T. Ito, R.H. Halstead, Jr., and
C. Queinnec (eds.), LNCS 1068, Springer, 1996, pp.134-153.

[4] Cho, K. and Ueda, K., Diagnosing Non-Well-Moded Concurrent Logic
Programs.  To be presented at 1996 Joint International Conference and
Symposium on Logic Programming (JICSLP'96), Bonn, Germany, September
1996.
