Author(s): The CLIP Group, clip@dia.fi.upm.es
, http://www.clip.dia.fi.upm.es/
, Facultad de Informática, Universidad Politécnica de Madrid.
Version: 1.3#124 (1999/11/27, 4:4:5 MET)
The
assertions
package adds a number of new declaration definitions and new operator definitions which allow including
program assertions in user programs. Such assertions can be used to describe predicates, properties, modules, applications, etc. These descriptions can be formal specifications (such as preconditions and post-conditions) or machine-readable textual comments.
This module is part of the
assertions
library. It defines the basic code-related assertions, i.e., those intended to be used mainly by compilation-related tools, such as the static analyzer or the run-time test generator.
Giving
specifications for predicates and other program elements is the main functionality documented here. The exact syntax of comments
is described in the autodocumenter (
lpdoc
[Knu84,Her99]) manual, although some support for adding machine-readable comments in assertions is also mentioned here.
There are two kinds of assertions: predicate assertions and program point assertions. All predicate assertions are currently placed as directives in the source code, i.e., preceded by ":-
". Program point assertions are placed as goals in clause bodies.
The facilities provided by the library are documented in the description of its component modules. This documentation is intended to provide information only at a "reference manual" level. For a more tutorial introduction to the subject and some more examples please see the document "An Assertion Language for Debugging of Constraint Logic Programs (Technical Report CLIP2/97.1)". The assertion language implemented in this library is modeled after this design document, although, due to implementation issues, it may differ in some details. The purpose of this manual is to document precisely what the implementation of the library supports at any given point in time.
docstring/1
type/grammar for details.
@var
command. For example, @var{VariableName}
should be used for referring to the variable "VariableName", which will appear then formatted as follows: VariableName
. See the description of the
docstring/1
type/grammar for details.
assrt
)assertions
syntax library, using one of the following declarations, as appropriate:
:- module(...,...,[assertions]). :- include(library(assertions)). :- use_package([assertions]).
=>/2
[975,xfx],
::/2
[978,xfx],
decl/1
[1150,fx],
decl/2
[1150,xfx],
pred/1
[1150,fx],
pred/2
[1150,xfx],
prop/1
[1150,fx],
prop/2
[1150,xfx],
modedef/1
[1150,fx],
calls/1
[1150,fx],
calls/2
[1150,xfx],
success/1
[1150,fx],
success/2
[1150,xfx],
comp/1
[1150,fx],
comp/2
[1150,xfx],
entry/1
[1150,fx],
regtype/1
[1150,fx],
regtype/2
[1150,xfx].
pred/1
,
pred/2
,
calls/1
,
calls/2
,
success/1
,
success/2
,
comp/1
,
comp/2
,
prop/1
,
prop/2
,
regtype/1
,
type/1
,
regtype/2
,
type/2
,
entry/1
,
modedef/1
,
decl/1
,
decl/2
,
comment/2
.
assrt
)
Usage: :- pred(AssertionBody)
.
AssertionBody
) contains properties or comments in the formats defined by
assrt_body/1
.
More than one of these assertions may appear per predicate, in which case each one represents a possible "
mode" of use (
usage) of the predicate. The exact scope of the usage is defined by the properties given for calls in the body of each assertion (which should thus distinguish the different usages intended).
AssertionBody
is an assertion body.
(assrt_body/1
)
Usage: :- pred(AssertionStatus,AssertionBody)
.
pred/1
assertion but it is explicitely qualified. Non-qualified
pred/1
assertions are assumed the qualifier check
.
AssertionStatus
is an acceptable status for an assertion.
(assrt_status/1
)
AssertionBody
is an assertion body.
(assrt_body/1
)
Usage: :- calls(AssertionBody)
.
Usage: :- calls(AssertionStatus,AssertionBody)
.
calls/1
assertion but it is explicitely qualified. Non-qualified
calls/1
assertions are assumed the qualifier check
.
AssertionStatus
is an acceptable status for an assertion.
(assrt_status/1
)
AssertionBody
is a call assertion body.
(c_assrt_body/1
)
Usage: :- success(AssertionBody)
.
Usage: :- success(AssertionStatus,AssertionBody)
.
success/1
assertion but it is explicitely qualified. Non-qualified
success/1
assertions are assumed the qualifier check
.
AssertionStatus
is an acceptable status for an assertion.
(assrt_status/1
)
AssertionBody
is a predicate assertion body.
(s_assrt_body/1
)
Usage: :- comp(AssertionBody)
.
Usage: :- comp(AssertionStatus,AssertionBody)
.
comp/1
assertion but it is explicitely qualified. Non-qualified
comp/1
assertions are assumed the qualifier check
.
AssertionStatus
is an acceptable status for an assertion.
(assrt_status/1
)
AssertionBody
is a comp assertion body.
(g_assrt_body/1
)
Usage: :- prop(AssertionBody)
.
AssertionBody
is an assertion body.
(assrt_body/1
)
Usage: :- prop(AssertionStatus,AssertionBody)
.
prop/1
assertion but it is explicitely qualified. Non-qualified
prop/1
assertions are assumed the qualifier check
.
AssertionStatus
is an acceptable status for an assertion.
(assrt_status/1
)
AssertionBody
is an assertion body.
(assrt_body/1
)
Usage: :- regtype(AssertionBody)
.
p(x, v_1, ..., v_n) :- body_1, ..., body_k.where:
x
is a term whose variables (which are called term variables) are unique, i.e., it is not allowed to introduce equality constraints between the variables of x
.
For example, p(f(X, Y)) :- ...
is valid, but p(f(X, X)) :- ...
is not.
p/n+1
the terms x
do not unify except maybe for one single clause in which x
is a variable.
n
>= 0 and p/n
is a parametric type functor (whereas the predicate defined by the clauses is p/n
+1).
v_1
, ..., v_n
are unique variables, which are called parametric variables.
body_i
is of the form:
regtype(z, t)
where z
is one of the term variables and t
is a regular type expression;
q(y, t_1, ..., t_m)
where m
>= 0, q/m
is a parametric type functor, not in the set of functors =/2
, ^/2
, ./3
regtype/2
.
t_1, ..., t_m
are regular type expressions, and y
is a term variable.
engine(basic_props)
manual.
The set of types is thus a well defined subset of the set of properties. Note that types can be used to describe characteristics of arguments in assertions and they can also be executed (called) as any other predicates.
AssertionBody
is an assertion body.
(assrt_body/1
)
Usage:
Usage: :- regtype(AssertionStatus,AssertionBody)
.
regtype/1
assertion but it is explicitely qualified. Non-qualified
regtype/1
assertions are assumed the qualifier check
.
AssertionStatus
is an acceptable status for an assertion.
(assrt_status/1
)
AssertionBody
is an assertion body.
(assrt_body/1
)
Usage:
Usage: :- entry(AssertionBody)
.
calls/1
assertion. However, the properties stated are not taken as something to be checked but are instead trusted by the compiler. As a result, if these assertions are erroneous they can introduce bugs in programs. Thus,
entry/1
assertions should be written with care.
An important use of these assertions is in
providing information to the compiler which it may not be able to infer from the program. The main use is in providing information on the ways in which exported predicates of a module will be called from outside the module. This will greatly improve the precision of the analyzer, which otherwise has to assume that the arguments that exported predicates receive are any arbitrary term.
AssertionBody
is a call assertion body.
(c_assrt_body/1
)
Usage: :- modedef(AssertionBody)
.
:- modedef +A : nonvar(A) # "A
is bound upon predicate entry.".
:- pred p(+A,B) : integer(A) => ground(B).
is equivalent to:
:- pred p(A,B) : (nonvar(A),integer(A)) => ground(B)
# "A
is bound upon predicate entry.".
AssertionBody
is an assertion body.
(assrt_body/1
)
Usage: :- decl(AssertionBody)
.
Usage: :- decl(AssertionStatus,AssertionBody)
.
decl/1
assertion but it is explicitely qualified. Non-qualified
decl/1
assertions are assumed the qualifier check
.
AssertionStatus
is an acceptable status for an assertion.
(assrt_status/1
)
AssertionBody
is an assertion body.
(assrt_body/1
)
Usage: :- comment(Pred,Comment)
.
Comment
for a given predicate Pred
.
Pred
is a head pattern.
(head_pattern/1
)
Comment
is a text comment with admissible documentation commands. The usual formatting commands that are applicable in comment strings are defined by
stringcommand/1
. See the
lpdoc
manual for documentation on comments.
(docstring/1
)
assrt
)
Usage: check(PropertyConjunction)
check/1
assertion can appear in the body of a clause in any place where a literal can normally appear. The property defined by PropertyConjunction
should hold in all the run-time stores corresponding to that program point.
PropertyConjunction
is either a term or a conjunction of terms. The main functor and arity of each of those terms corresponds to the definition of a property. The first argument of each such term is a variable which appears as a head argument.
(property_conjunction/1
)
Usage: trust(PropertyConjunction)
check/1
assertion. However, the properties stated are not taken as something to be checked but are instead trusted by the compiler. While the compiler may in some cases detect an inconsistency between a
trust/1
assertion and the program, in all other cases the information given in the assertion will be taken to be true. As a result, if these assertions are erroneous they can introduce bugs in programs. Thus,
trust/1
assertions should be written with care.
An important use of these assertions is in
providing information to the compiler which it may not be able to infer from the program (either because the information is not present or because the analyzer being used is not precise enough). In particular, providing information on external predicates which may not be accessible at the time of compiling the module can greatly improve the precision of the analyzer. This can be easily done with trust assertion.
PropertyConjunction
is either a term or a conjunction of terms. The main functor and arity of each of those terms corresponds to the definition of a property. The first argument of each such term is a variable which appears as a head argument.
(property_conjunction/1
)
Usage: true(PropertyConjunction)
check/1
assertion. However, the properties stated have been proved to hold by the analyzer. Thus, these assertions often represent the
analyzer output.
PropertyConjunction
is either a term or a conjunction of terms. The main functor and arity of each of those terms corresponds to the definition of a property. The first argument of each such term is a variable which appears as a head argument.
(property_conjunction/1
)
Usage: false(PropertyConjunction)
check/1
assertion. However, the properties stated have been proved not to hold by the analyzer. Thus, these assertions often represent the
analyzer output.
PropertyConjunction
is either a term or a conjunction of terms. The main functor and arity of each of those terms corresponds to the definition of a property. The first argument of each such term is a variable which appears as a head argument.
(property_conjunction/1
)
Go to the first, previous, next, last section, table of contents.