CLAIRE

claire(3) claire(7)

CLAIRE(3) Library Functions Manual CLAIRE(3)

NAME
claire - a high-level functional and object-oriented language with rule
processing capabilities

DESCRIPTION
Methods in CLAIRE.

^ (Kernel)

x:integer ^ y:integer → integer
x:float ^ y:float → float
x:list ^ y:integer → list
x:set ^ y:set → set

(x ^ y) returns x ^ y when x and y are numbers. If x is an integer,
then y must be a positive integer, otherwise an error is raised.

(l ^ y) skips the y first members of the list l. If the integer y is
bigger than the length of the list l, the result is the empty list,
otherwise it is the sublist starting at the y+1 position in l (up to
the end).

(s1 ^ s2) returns the intersection of the two sets s1 and s2 that is
the set of entities that belong to both s1 and s2. Other internal re-
strictions of the property ^ exist, where ^ denotes the intersection
(it is used for the type lattice)

^2 (Core)

^2(x:integer) → integer

^2(x) returns 2 to the power of x

% (Kernel)

x:any % y:class → boolean
x:any % y:collection → boolean

(x % y) returns (x ∈ y) for any entity x and any abstract set y. An ab-
stract set is an object that represents a set, which is a type or a
list. Note that membership to a static type is actually "diet".

* (Kernel)

x:integer * y:integer → integer
x:float * y:float → float

(x * y) returns x × y when x and y are numbers. If x is an integer,
then y must also be an integer, otherwise an error is raised (explicit
conversion is supported with float!).

The operation * defines a commutative monoid, with associated divisi-
bility operator divide? and associated division /.

/ (Kernel)

x:integer / y:integer → integer
x:float / y:float → float

(x / y) returns x ÷ y when x and y are numbers. If x is an integer,
then y must also be an integer, otherwise an error is raised (explicit
conversion is supported with float!).

+ (Kernel)

x:integer + y:integer → integer
x:float + y:float → float

(x + y) returns x + y when x and y are numbers. If x is an integer,
then y must be an integer, otherwise an error is raised (explicit con-
version is supported with float!).

The operation + defines a group structure, with associated inverse -.

- (Kernel)

x:integer - y:integer → integer
x:float - y:float → float
-(x:integer) → integer
-(x:float) → float

(x - y) returns x − y when x and y are numbers. -(x) returns the oppo-
site of x.

/+ (Kernel)

x:list /+ y:list → list
x:string /+ y:string → string
x:symbol /+ y:(string U symbol) → symbol

(x /+ y) returns the concatenation of x and y ( represents the append
operation). Concatenation is an associative operation that applies to
strings, lists and symbols. It is not represented with + because it is
not commutative. When two symbols are concatenated, the resulting sym-
bol belongs to the namespace (module) of the first symbol, thus the
second symbol is simply used as a string. By extension, a symbol can be
concatenated directly with a string.

.., -- (Kernel)

.. x:integer .. y:integer → Interval
-- x:integer .. y:integer → Interval

(x .. y) returns the interval {z | x ≤ z ≤ y}. Intervals are only sup-
ported for integers, in CLAIRE v3.0. Notice that (3 .. 1) returns the
empty set, which is a type. The new method (x -- y) is an explicit in-
terval constructor (it produces an error if the first argument is
larger than the second).The result is an object from the class Inter-
val, which is a type.

=, != (Kernel)

x:any = y:any → boolean
x:any != y:any → boolean

(x = y) returns true if x is equal to y and nil otherwise. Equality is
defined in Section 2: equality is defined as identity for all entities
except strings, lists and sets. For lists, sets and strings, equality
is defined recursively as follows: x and y are equal if they are of
same size n and if x[i] is equal to y[i] for all i in (1 .. n).

(x != y) is simply the negation of (x = y).

=type? (Core)

=type?(x:any, y:any) → boolean

returns true if x and y denote the same type. For example =type?(bool-
ean, {true, false}) returns true because final(boolean) was declared
after the two instances true and false were created, so the system
knows that no other instances of boolean may ever be created in the fu-
ture. This equality is stronger than set equality in the sense that the
system answers true if it knows that the set equality will hold ever
after.

<=, >=, <, > (Kernel)

x:integer <= y:integer → boolean
x:float <= y:float → boolean
x:char <= y:char → boolean
x:string <= y:string → boolean
x:type <= y:type → boolean
x:X < y:X → boolean for X = integer, float, char and string
x:X > y:X → boolean for X = integer, float, char and string
x:X >= y:X → boolean for X = integer, float, char and string

The basic order property is <=. It is defined on integers and floats
with the obvious meaning. On characters, it is the ASCII order, and on
strings it is the lexicographic order induced by the ASCII order on
characters. The order on types is the inclusion: ((x <= y) if all mem-
bers of type x are necessarily members of type y).

(x < y), (x > y) and (x >= y) are only defined for numbers, char and
strings with the usual meaning.

<<, >> (Kernel)

l:list << n:integer → list
x:integer << n:integer → integer
x:integer >> n:integer → integer
l:string << n:integer → string

(l << n) left-shifts the list l by n units, which means that the n
first members of the list are removed. This is a method with a side-ef-
fect since the returned value is the original list, which has been mod-
ified. (x <<n) and (x >> n) are the result of shifting the integer x
seen as a bitvector respectively to the left and to the right by n po-
sitions.

(s << n) removes the n first characters of a string s. This is an effi-
cient but destructive operation (no allocation, but the initial string
is lost).

@ (Core)

p:property @ t:type → entity
p:property @ l:list[type] → entity
t:type @ p:parameter → type

(p @ t) returns the restriction of p that applies to arguments of type
t. When no restrictions applies, the value nil is returned. If more
than one restriction applies, the value unknown is returned. Notice
that the form p@t (without blank spaces) is used to print the restric-
tion and also in the control structure @(...).

(p @ list(t1,..tn)) is similar and returns the restriction of p that
applies to arguments in t1 X... X tn.

(t @ p) returns the type that is inferred for x.p when x is an object
of type t and p a parameter (read-only property).

abs (Core)

abs(x:integer) → integer
abs (x:float) → float

abs(x) returns the absolute value (-(x) is x is negative, x otherwise).

abstract (Core)

abstract(c:class) → void
abstract(p:property) → void

abstract(c) forbids the class c to have any instance. abstract(p) de-
fines p as an extensible property. This is used by the compiler to pre-
serve the ability to add new restrictions to p in the future that would
change its semantics on existing classes. By default, a property is ex-
tensible until it is compiled. A corollary is that function calls that
use extensible properties are compiled using late binding.

add (Kernel)

add(s:set,x:any) → set
add(l:list,x:any) → list
add(p:relation,x:object,y:any) → any

add(s,x) adds x to the set s. The returned value is the set s ∪ {x}.
This method may modify the set s but not necessarily. When x is a list,
add(l,x) inserts x at the end of l. The returned value is also the list
obtained by appending (x) to l, and l may be modified as a result but
not necessarily. The pseudo-destructive behavior of add is similar to
that of add*, which is described below.

add(p,x,y) is equivalent to p(x) :add y (This form is interesting when
one wants to write such an expression for a variable p)

add* (Kernel)

add*(l1:list, l2:list) → list

add*(l1,l2) returns the concatenated list l1 . l2, but it is destruc-
tive: it uses l1 as the data structure on which to perform the concate-
nation. Hence, the original l1 is no longer available after the method
add* has been called.

and (Kernel)

and(x :integer,y :integer) → integer

and(x,y) returns the bitwise intersection of two integers (seen as
bitvectors).

apply (Core)

apply(p:property, l:list) → any
apply(f:external_function, ls:list[class], lx:list) → any
apply(la:lambda, lx:list) → any
apply(m:method, lx:list) → any

apply(p,l) is equivalent to a function call where the selector is p and
the argument list is l. For instance, apply(+,list(1,2)) = (1 + 2) =
call(+,1,2).

apply(f,ls,l) applies the function f to the argument list l, where ls
is the list of sort of the arguments and the result (i.e. length(ls) =
length(l) + 1). For instance, if f is the external function that de-
fines + @ integer, apply(f,list(integer,integer,integer),list(1,2)) = 1
+ 2.
apply(la,lx) applies the lambda expression to the argument list. ap-
ply(m,lx) applies the method to the argument list.

array! (Kernel)

array!(x:list,t:type) → type[t[]]

creates a copy of the list x that is represented as an array. The mem-
ber type must be given as a parameter t and an error will occur if a
member of the list does not belong to t.

begin (Kernel)

begin(m:module) → void

sets the current namespace to m (a module).

but (Core)

but(s:any,x:any) → any

Returns the set of members of s that are different from x.

car, cdr (Kernel)

car(l:list) → type[member(l)]
cdr(l:list) → type[l]

These two classical LISP methods return the head of the list, e.g. l[1]
(for car) and its tail, e.g. the list l starting at its second element
(for cdr).

call (Kernel)

call(p:property, l:listargs) → any
call(x:lambda, l:listargs) → any

call(X,x1,x2 ,...,xn) is equivalent to apply(X,list(x1,x2 ,...,xn)).

cast! (Kernel)

cast!(s:bag,t:type) → bag

cast(s,t) sets the member type of the bag s to t. This is a system
method, that should not be used lightly since it does not perform any
check and may yield nasty errors. The proper way to cast a bag is to
use "as": (s as t).

char! (Kernel)

char!(n:integer) → char

char!(n) returns the character which ASCII code is n.

class! (Core)

class!(x:any) → class

class!(x) returns the intersection of all classes y such that x <= y
(Such an intersection always exists since classes are organized in a
lattice). Hence, if c is a class class!(c)=c.

close (Core)

close(m:module) → module
close(c:class) → class
close(e:exception) → any
close(v:global_variable) → global_variable

The method close is called each time an object is created. It is exe-
cuted and returns the created object. It can sometimes be very helpful
to define new restrictions, they will be automatically called when an
instance is created. Exceptions are a special case: raising an excep-
tion is done internally by creating an instance of exception. The
method close is responsible for looking for the innermost handler, etc.

cons (Kernel)

cons(x:any, l:list) → list

This traditional method appends x at the beginning of l and returns the
constructed list.

contradiction!() (Kernel)

contradiction!() → void

This method creates a contradiction, which is an instance of the class
contradiction. It is equivalent to contradiction() but is more effi-
cient and should be preferred.

copy (Kernel)

copy(x:object) → object
copy(s:bag) → bag
copy(a:array) → array
copy(s:string) → string

copy(x) returns a duplicate of the object x. It is not recursive : the
slots of the copied object are shared with that of the original one.
Similarly, the copy of a bag (a set or a list) returns a fresh set or
list with the same elements and the copy of a string is ... a copy of
the string.

cos (Kernel)

cos(x:float) → float

cos(x) returns the cosine of x (x is expressed in radians).

date! (Kernel)

date!(i:integer) → string

date!(i) returns the date, using the integer parameter i to indicate
whether the full date is needed or only the day or the time. For in-
stance

date!(0) = "Thu Mar 9 08:04:22 2000"
date!(1) = "Thu Mar 9 2000"
date!(2) = "08:04:22"

delete (Kernel)

delete(p:relation, x:object, y:any) → any
delete(s:bag, x:any) → bag

delete(s,x) returns s if x is not in s and the list (resp. set) s with-
out the first (resp. only) occurrence of x otherwise. delete(p,x,y) is
equivalent to p(x) :delete y. This is a destructive method in the sense
that it modifies its input argument. The proper way to use delete,
therefore, is either destructive (l :delete x) or non-destructive
(delete(copy(l),x)).

difference (Kernel)

difference(s:set, t:set) → set

difference(s,t) returns the difference set s - t, that is the set of
all elements of s which are not elements of t.

end_of_string (Kernel)

end_of_string() → string

end_of_string() returns the string containing everything that has been
printed since the last call to print_in_string().

erase (Kernel)

erase(a:table) → any
erase(r:property,x:any) → any

erase(a) removes all value pairs contained in the table. This means
that, on one hand, the value a[x] becomes unknown for each object x,
and also that any references to an object from the table’s domain or an
associated value is lost, which may be useful to allow for complete
garbage collection.

erase(p,x) removes the value associated to x with the property p. The
default value, or the unknown value, is placed in the slot x.p, and the
inverse if updated (if any).

exception! (Kernel)

exception!() → exception

exception!() returns the last exception that was raised.

exit (Kernel)

exit(n:integer) → void

exit(n) stops CLAIRE running and returns to the hosting system the
value n. What can happen next is platform-dependent. For instance,
exit(0) exits CLAIRE with a clean stop, while exit(-1) returns an error
so the go debugging platform gives may be used (and give some context
about the call stack).

factor? (Kernel)

factor?(x:integer, y:integer) → boolean

factor?(x,y) returns true if x is a multiple of y.

fcall (Core)

fcall(f:external_function, s1:class, x:any, s:class) → any
fcall(f:external_function, s1:class, x:any, s2:class, y:any, s:class) →
any
fcall(f:external_function, s1:class, x:any, s2:class, y:any, s3:class,z
:class,s :class) → any

fcall provide an easy interface with external (C++) functions.
fcall(f,s1,x,s) applies an external function to an argument of sort s1.
The sort of the returned value must be passed as an argument (cf. Ap-
pendix C). . fcall(f,s1,x,s2,y,s) is the equivalent method in the two-
arguments case.

final (Core)

final (c:class) → void
final (p:property) → void

final(c) forbids the user to create any subclass of the class c. If c
is a constant class, this is taken as a "diet" compiling directive.

final(p) change the extensibility status of the property p (represented
with the slot open) so that the property p becomes closed, which means
that a new restriction may no longer be added if it causes an inheri-
tance conflict.

finite? (Core)

finite?(t:type) → boolean

finite?(t) returns true if the type t represents a finite set. Set it-
eration (with the for loop) can only be done over finite sets

float! (Kernel)

float!(x:integer) → float
float!(x:string) → float

transforms an integer or a string into a float.

flush (Kernel)

flush(p:port) → void

Communications with ports are buffered, so it can happen that some mes-
sages wait in a queue for others to come, before being actually sent to
their destination port. flush(p) for input and output ports and empties
the buffer associated with p, by physically sending the print messages
to their destination.

fopen, fclose (Kernel)

fopen(s1:string,s2:string) → port
fclose(p:port) → any

fopen returns a port that is handle on the file or external device as-
sociated with it. The first string argument is the name of the file,
the second is a combination of several control characters, among which
'r' allows reading the file, 'w' (over)writing the file and 'a' append-
ing what will be write at the end of the file. Other possibilities may
be offered, depending on the underlying possibilities. Such other pos-
sibilities are platform-dependent.

format (Kernel)

format(string,list) → any

This method does the same thing as printf, except that there are always
two arguments, thus the arguments must be replaced by an explicit list.

gensym (Kernel)

gensym() → symbol
gensym(s:string) → symbol

gensym() generates randomly a new symbol. gensym(s) generates randomly
a new symbol that begin with s.

get (Kernel)

get(p:property + slot, x:object) → any
get(a:table, x:any) → integer
get(s:string, c:char) → integer
get(l:list, x:any) → integer
get(m:module) → integer

get(p,x) is equivalent to p(x), but without any verification on un-
known. So does get(a,x) for a table.get(s,x) returns i such that s[i]=x
(if no such i exists, 0 is returned). So does get(l,x) for a
list.get(m) is equivalent for a module m to (load(m), open(m))

get_module (Core, Optimize)

get_module(s:symbol) → module
get_module(x:thing) → module

get_module returns the module where the identifier s was created.

get_value (Kernel)

get_value(s:string) → any
get_value(m:module, s:string) → any

returns the object whose name corresponds to the string; if a module
argument is passed, the associated symbol is sought in the module’s
namespace, otherwise the module claire is used by default. To find the
value associated to a string within the current module, simply use
get_value(module!(),s).

getc (Kernel)

getc(p:port) → char

getc(p) returns the next character read on port p.

getenv (Kernel)

getenv(s:string) → string

getenv(s) returns the value of the environment variable s if it exists
(an error occurs otherwise since an attempt is made to create a string
from the NULL value that is returned by the environment).

hash (Kernel)

hash(l:list,x:any) → integer
hash(n:integer,x:any) → integer

hash(l,x) returns an integer between 1 and length(l) that is obtained
through generic hashing. To obtain the best dispersion, one may use a
list of size 2ⁱ-3. This function can be used to implement hash tables
in CLAIRE; it used to be the basis of the table implementation before
version 4.

Id (Kernel)

Id(x:any) → type[x]

Id(x) returns x. Id has a special behavior when compiled which makes it
useful. The argument is evaluated before being compiled. The intended
use is with global variables: the compiler uses the actual value of the
variable instead of a reference to the global variable. This is very
convenient to introduce parameters that are defined outside the module
that is being compiled.

This is also used to tell the compiler that an iteration should make
explicit use of all iterations rules that may apply to some subclasses
of the set expression that is being iterated.

inherit? (Core)

inherit?(c1:class, c2:class) → boolean

inherit?(c1,c2) returns (c2 % ancestors(c1))

instanced (Core)

instanced(c:class) → void

instanced(c) tells CLAIRE to maintain the list of instances (e.g, c.in-
stances). This is not necessary if c inherits from things, but other-
wise, CLAIRE will assume by default that the extension is not kept.
This choice has a strong impact:

· if the extension is kept, the class may be used as a set but ob-
jects will not be garbage collected (explicit kill is necessary)
· otherwise, the class cannot be enumerated (like in "for c in
class show(c)") but garbage collection is implicit (memory is re-
claimed as soon as the object is no longer used).

integer! (Kernel)

integer!(s:string) → integer
integer!(f:float) → integer
integer!(c:char) → integer
integer!(l:set[(0 .. 29)]) → integer
integer!(s:symbol) → integer

integer!(s) returns the integer denoted by the string s if s is a
string formed by a sign and a succession of digits, integer!(f) returns
the lower integer approximation of f, integer!(c) returns the ASCII
code of c and integer!(l) returns the integer represented by the
bitvector l, i.e. the sum of all 2ⁱ for i in l. Last, integer(s) re-
turns a unique index associated to a symbol s.

invert (Core)

invert(r:relation,x:any) → any

invert(r,x) return r^-1(x) assuming that r has an inverse.

kill, kill! (Kernel)

kill(x:object) → any
kill(x:class) → any
kill!(x:any) → any

kill is used to remove an object from the database of the language.
kill does it properly, removing the object from all the relation net-
work but without deallocating. kill! is more brutal and deallocates
without any checking.

known? (Kernel)

known?(p:relation, x:object) → boolean
known?(x:any) → boolean

known?(p,x) is equivalent to get(p,x) != unknown. The general method
known? simply returns true whenever the object exists in the database.

last (Kernel)

last(l:list) → type[member(l)]

last(l) returns l[length(l)]

length (Kernel)

length(l:bag) → integer
length(a:array) → integer
length(l:string) → integer

returns the length of an array, a bag or a string. The length of a list
is not its size! The following is true: length(set!(l)) = size(l) =
size(l) = size(set!(l)).

list! (Kernel)

list!(a:array) → type[member_type(a)[]]
list!(s:set) → type[list[member(s)]]

For any array or set x, list!(s) transforms x into a list. If x is a
set, the order of the elements in the list can be anything.

load, sload, oload, eload (Reader)

load(s:string) → any
sload(s:string) → any
oload(s:string) → any
eload(s:string) → any
load(m:module) → any
sload(m:module) → any
oload(m:module) → any

These methods load a file (or the files associated to a module). The
difference between them is that load(s) reads and evaluates all the in-
structions found in the file named s, whereas sload(s) reads, prints,
evaluates and prints the results of the evaluation of all the instruc-
tions found in the file named s. oload(s) is similar to load(s) but
also optimizes the methods that are newly defined by substituting an
optimized version of the lambda abstraction. eload(s) is similar to
load(s) but assumes that the file only contains expressions (such as
f(1,2)). This is convenient for loading data input files using a func-
tional format.

log (Kernel)

log(x:float) → float

computes log(x) – base e.

make_array (Kernel)

make_array(n:integer,t:type,x:any) → type[t[]]

returns an array of length n filled with x. The parameter t is the mem-
ber_type of the array, thus x must belong to t, as well as any future
value that will be put in the array. Note that x is shared for all mem-
bers of the array, which cause a problem if updates can be performed.

make_list (Kernel)

make_list(n:integer,x:any) → type[list[x]]

returns a list of length n filled with x (e.g., make_list(3,0) =
list<any>(0,0,0)). This is a typed list with member type any, thus it
can be updated.

make_string (Kernel)

make_string(i:integer, c:char) → string
make_string(s:symbol) → string
make_string(l:list) → string

make_string(i,c) returns a string of length i filled with the character
c.

make_string(s) returns a string denoting the same identifier. If s is
given in the qualified form (module/identifer), than the result will
contain the name of the module ("module/identifier").

make_string(l) creates a string from the list of its characters.

member (Core)

member(x:type) → type

member(x) returns the type of all instances of type x, assuming that x
is a CLAIRE type which contains objects y such that other objects z can
belong to. If this is the case, member(x) is a valid type for all such
z, otherwise the returned value is the empty set. For instance, if x is
list[integer], all instances of x are lists that contain integers, and
all members of these lists are integers. Therefore, member(list[inte-
ger]) is integer.

member_type (Kernel)

member_type(x:array) → type

member_type(x) returns the type of all members of the array x. There-
fore, member(a) = member_type(a) for an array a.

methods (Reader)

methods(d:class,r:class) → set[method]

methods(d,r) returns the set of methods with a range included in r and
a domain which is a tuple which first component is included in d.

min / max (Core)

min(m:method[domain:tuple(X,X), range:boolean],
l:set[X] U list[X]) → type[X]
min(x:integer,y:integer) → integer
max(x:integer,y:integer) → integer

given an order function (m(x,y) returns true if x <= y) and a bag, this
function returns the minimum of the bag, according to this order.
min/max on integer returns the smallest/largest of two integers.

mod (Kernel)

mod(x:integer, y:integer) → integer

mod(x,y) is the rest of the Euclidean division of x by y.

module! (Core, Optimize)

module!() → module
module!(r:restriction) → module

module!(r) returns the module where the method r was created.

module!() (= system.module! ) returns the current module, that is the
module into which the reader is currently reading.

new (Core)

new(c:class) → any
new(c:class, s:symbol) → thing

new is the generic instantiation method. new(c) creates an object of
class c (It is equivalent to c()). new(c,s) creates an object of class
c with name s.

not (Kernel)

not(x:any) → boolean

not(x) returns false for all x except false, the empty set and the
empty list.

nth, nth=, nth+, nth- (Kernel)

nth(a:table, x:any) → any
nth(x:integer, i:integer) → boolean
nth(l:bag, i:integer) → any
nth(a:array, i:integer) → any
nth(s:string, i:integer) → char
nth=(a:table, x:any, y:any) → any
nth=(a:array, x:any, y:any) → any
nth=(l:list, i:integer, x:any) → any
nth=(s:string, i:integer, x:char) → char
nth+(l:list, i:integer, x:any) → bag
nth-(l:list, i:integer) → bag
nth_put(l:string, i:integer, x:char) → string
nth_get(l:string, i:integer) → string

nth is used for accessing elements of structured data: nth(l,i) is the
i^th element of the bag l, nth(s,i) is the i^th character of the string
s. For tables, nth(a,x) is equivalent to a[x], even when x is not an
integer. Finally, nth also deals with the bitvector representation of
integers: nth(x,i) returns true if the i^th digit of x in base 2 is 1.

nth= is used for changing an element at a certain place to a certain
value. In all the restrictions nth=(s,i,x) means: change the i^th value
of s to x.

There exists two other ways of modifying the values in such data struc-
tures: nth+ and nth-. nth+ uses the same syntax as nth= : nth+(l,i,x)
returns a list (that may be l) where x has been inserted in the i^th po-
sition. By extension, i may be length(l) + 1, in which case x is in-
serted at the end of l.

nth- is used for removing an element. nth-(s,i) returns a value that
differs from s only in that the i^th place has been erased.

Strings in CLAIRE can be used as buffers (arrays of characters) using
the methods nth_get and nth_put that do not perform bound checking. The
string does not need to be terminated by a null character and any posi-
tion may be accessed. This use of strings may provoke severe errors
since there are no bound checks, thus it should be used scarcely and
with a lot of care.

occurrence (Language)

occurrence(exp:any, x:variable) → integer

returns the number of times when the variable x appears in exp

or (Kernel)

or(x:integer,y:integer) → integer

or(x,y) returns the bitwise union of two integers (seen as bitvectors).

owner (Kernel)

owner(x:any) → class

owner(x) returns the class from which the object is an instance. It x
is an object, then owner(x) = isa(x) = the unique class c such that x %
instances(c).

port! (Kernel)

port!() → port
port!(s:string) → port

creates a port that is bound to a string. The first method creates an
empty string port that is used for writing. The value of the string as-
sociated with the port may be retrieved with the method
string!(p:port). The second method transforms an existing string into a
port that can be read. This is useful to read an expression stored in a
string, although the simpler method read(s:string) is most often enough
for the task.

pretty_print (Language)

pretty_print(x:any) → void

performs the pretty_printing of x. For example, you can pretty print
CLAIRE code: if <inst> is a CLAIRE instruction pretty_print(`<inst>)
will print it nicely indented (the backquote here is to prevent the in-
struction from begin evaluated).

princ, print (Kernel)

princ(x:integer) → void
princ(x:float) → void
princ(x:string) → void
princ(x:char) → void
princ(x:symbol) → void
princ(x:bag) → void
princ(x:string, i:integer) → void
princ(x:float, i:integer) → void
print(x:any) → void

print(x) prints the entity x (x can be anything). princ(x:integer or
float) is equivalent to print(x). If x is a string /char / symbol/ bag,
print(x) prints x without the “ / ‘ / ‘/ separator. Princ(s:string,i)
prints the i first characters, while princ(x:float,i:integer) prints
the float x with i figures after the decimal point.

print_in_string (Kernel)

print_in_string() → void

print-in-string() opens a new output port that will be stored as a
string. The user is given access to the string at the end of the tran-
scription, when the call to end_of_string() returns this string.

put (Kernel)

put(p:property, x:object, y:any) → any
put(a:table, x:object, y:any) → any
put(s:slot, x:object, y:any) → any
put(s:symbol,x:any) → any

put(p,x,y) is equivalent to p(x) := y but does not trigger the rules
associated to r or the inverse of r. Besides, this operation is per-
formed without any type-checking. The method put is often used in con-
junction with propagate. put(s,x) binds the symbol s to the object x.

put_store (Kernel)

put_store(r1: relation, x:any, v:any,b:boolean) → void

put_store(r,x,v,b) is equivalent to put(r,x,v) but also stores this up-
date in the current world if b is true. The difference with the use of
the statement store(p) is that put_store allows the user to control
precisely which update should be backtracked. Put_store(r,x,y,b) does
nothing if r(x) = y.

putc (Kernel)

putc(c:char, p:port) → void

putc(c,p) sends c to the output port p.

random, random! (Kernel)

random(n:integer) → integer
random (n:integer,m:integer) → integer
random (b:boolean) → boolean
random (l:bag) → any
random!(n:integer) → void

random(n) returns an integer in (0 .. n-1), supposedly with uniform
probability. random(n,m) returns an integer between n and m. ran-
dom(b:Boolean) returns a random boolean (true or false) is b is true,
and false otherwise. random(l:bag) returns a random member of the bag
l. random!(n) resets the seed for the random number generation process.

range (Kernel), (Language)

range(r:restriction) → any
range(r:relation) → any
range(v:global_variable) → any
range(v:Variable) → any

For a relation or a restriction r, range(r) returns the allowed type
for the values taken by r over its domain. For a variable v, range(v)
is the allowed type for the value of v.

read (Kernel), (Reader)

read(p:property, x:object) → any
read(p:port) → any
read(s:string) → any

read(p,x) is strictly equivalent to p(x): it reads the value and raises
an exception if it is unknown. read(p) and read(s) both read an expres-
sion from the input port p or the string s.

release (Core)

release() → string

returns a release number of your CLAIRE system (<release>.<ver-
sion>.<revision>).

restrictions (Kernel)

restrictions(p:property) → list[restriction]

returns the list of all restrictions of the property. A property is
something a priori defined for all entities. A restriction is an actual
definition of this property for a given class (or type).

safe (Optimize)

safe(x:any) → any

safe(x) is semantically equivalent to x and is ignored by the inter-
preter (x = safe(x)). On the other hand, this tells the compiler that
the expression x must be compiled with the safe setting of the optimiz-
ing options. This is useful when a complete program requires high opti-
mization settings for performance reasons but you still want to ensure
that (say) overflow errors will be detected. A typical use would be

try safe( x * y) catch error MAXINT

to implement a bounded multiplication that can be placed in an opti-
mized module.

self_print (Kernel)

self_print(x:any) → any

this is the standard method for printing unnamed objects (objects that
are not in thing). It is called by default by printf on objects.

set! (Core)

set!(s:collection) → set
set!(x:integer) → set[(0 .. 29)]

set!(s) returns an enumeration of the collection s. The result is, by
definition, a set that contains exactly the members of s. An error oc-
cur if s is not finite, which can be tested with finite?(x).

set!(x) returns a set that contains all integers i such that (x / 2ⁱ)
mod 2 = 1. This method considers x as the bitvector representation of
a subset of (0 .. 29). The inverse is integer!.

shell (Kernel)

shell(s:string) → any

Passes the command s to the operating system (the shell).

show (Reader)

show(x:any) → any

The method show prints all the information it can possibly find about
the object it has been called on: the value of all its slots are dis-
played. This method is called by the debugger.

shrink (Kernel)

shrink(x:list,n:integer) → list
shrink(x:string,n:integer) → string

The method shrink truncates the list or the string so that its length
becomes n. This is a true side-effect and the value returned is always
the same as the input. As a consequence, shrink(l,0) returns an empty
list that is different from the canonical empty list nil.

sin (Kernel)

sin(x:float) → float

sin(x) returns the sine of x (x is expressed in radians).

size (Core)

size(l:bag) → integer
size(x:any) → integer

size(l) gives the number of elements in l. If x is an abstract set (a
type, a class, ...) then size(x) denotes the number of elements of type
x. If the set is infinite, an exception will be raised. Note that the
size of a list is not its length because of possible duplicates.

slots (Kernel)

slots(c:class) → any

slots(c) returns the list of all slots that c may have

sort (Core)

sort(m:method, l:list) → type[l]

The method sort has two arguments: an order method m such that m(x,y) =
true if x <= y and a list of objects to be sorted in ascending order
(according to m). The method returns the sorted list. The method is
usually designated using @, as in sort(< @ integer, list(1,2,8,3,4,3)).

In CLAIRE 3, the compiler is able to “macroexpand” the definition of
sort (using a quicksort algorithm) when the method is a constant and
when the call to sort is used to define a single-instruction method
that sorts a given list (with a void range). If we define:

SortByf(l:list<myObject>) : void -> sort(myOrder @ myObject, l)

The compiler will produce a very efficient implementation for this
method through code generation, which is not a trivial feature since
quicksort is doubly recursive. Notice that this optimization will only
take place if:

· the sort(...) message is the unique instruction of the method,
which must return nothing
· the sorting method is an expression of the kind (p @ class)
· the list argument is the unique argument of the method

sqr (Kernel)

sqr(x:integer) → integer
sqr(x:float) → float

returns the square of x, that is x * x.

sqrt (Kernel)

sqrt(x:float) → float

returns the square root of x. Returns an irrelevant value when x is
strictly negative.

statistics (Kernel)

statistics() → void

statistics() prints the memory situation of the CLAIRE system : the
size of the evaluation stack as well as the string buffer (parameters
that may be changed with the -s option), and the memory allocation re-
turned by Go : the total allocated memory, the memory that is being
used and the number of Go calls to garbage collection.

store (Kernel)

store(r1: relation, r2:relation ...) → void
store(v: global_variable) → void
store(a:array,n:integer,v:any,b:boolean) → void
store(l:list,n:integer,v:any,b:boolean) → void

store(r1,r2,...) declares the relations (properties or tables) as de-
feasible (using the world mechanism). If x is an array or a list,
store(x,n,v,b) is equivalent to x[n] := v but also stores this update
in the current world if b is true. As a syntactical convenience, the
argument b may be omitted if it is true. Note that there is a similar
method for properties called put_store. store(v) can be used to declare
a global_variable v as defeasible (notice that only one argument is al-
lowed).

string! (Kernel)

string!(s:symbol) → string
string!(n:integer) → string
string!(x :float) → string

string! converts a symbol, an integer or a float into a string. For ex-
ample string!(toto) returns "toto" and string!(12) returns "12". Un-
like make_string, it returns the unqualified form (string!(Fran-
cois/agenda) = "agenda", whereas make_string(Francois/agenda) = "Fran-
cois/agenda").

substitution (Language)

substitution(exp:any, v:Variable, f:any) → any

substitution(exp,v,f) returns exp where any occurrence of the free
variable v is substituted by f. Hence, if occurrences(exp,v) = 0 then
substitution(exp,v,f) returns exp for any f.

substring (Kernel)

substring(s:string, i:integer, j:integer) → string
substring(s1:string, s2:string, b:boolean) → integer

substring(s,i,j) returns the substring of s starting at the i^th charac-
ter and ending at the j^th. For example, substring("CLAIRE",3,4) returns
"AI". If i is negative, the empty string is returned and if j is out
of bounds (j > length(s)), then the system takes j=length(s). sub-
string(s1,s2,b) returns i if s2 is a subsequence of s1, starting at
s1's i^th character. The boolean b is there to allow case-sensitiveness
or not (identify 'a' and 'A' or not). When s2 cannot be identified with
any subsequence of s1, the returned value is 0.

symbol! (Kernel)

symbol!(s:string) → symbol
symbol!(s:string, m:module) → symbol

symbol!(s) returns the symbol associated to s in the claire module.
For example, symbol!("toto") returns claire/«toto». symbol!(s,m) re-
turns the symbol associated to s in the module m.
m.

time_get, time_set, time_show, time_read (Kernel)

time_get() → integer
time_read() → integer
time_set() → void
time_show() → void

time_set() starts a clock, time_get() stops it and returns an integer
proportional to the elapsed time. Several such counters can be embedded
since they are stored in a stack. time_show() pretty prints the result
from time_get(). time_read() returns the elapsed time in micro-seconds,
it can be used to read the value of the time counter without stopping
it.

type! (Language)

type!(x:any) → any

returns the smallest type greater than x (with respect to the inclusion
order on the type lattice), that is the intersection of all types
greater or equal to x.

U (Core)

U(s1:set, s2:set) → set
U(s:set, x:any) → any
U(x:any, y:any) → any

U(s1,s2) returns the union of the two sets. Otherwise, U returns a type
which is the union of its two arguments. This constructor helps build-
ing types from elementary types.

uniform? (Core)

uniform?(p:property) → boolean

Tells if a property is uniform, that is contains only methods as re-
strictions, with the same types for arguments and ranges. Note that in-
terface properties should be uniform, as well as all properties that
are used dynamically in a "diet" program.

use_as_output (Kernel)

use_as_output(p:port) → port

uses_as_output(p) changes the value of the current output (the port
where all print instructions will be sent) to p. It returns the previ-
ous port that was used as output which can thus be saved and possibly
restored later.

world?, commit, choice, backtrack (Kernel)

world?() → integer
choice() → void
backtrack() → void
backtrack(n:integer) → void
commit() → void
backtrack0() → void
commit(n:integer) → void

These methods concern the version mechanism and should be used for hy-
pothetical reasoning: each world corresponds to a state of the data-
base. The slots s that are kept in the database are those for which
store(s) has been declared. These worlds are organized into a stack,
each world indexed by an integer (starting form 0). world?() returns
the index of the current world; choice() creates a new world and steps
into it; backtrack() pops the current world and returns to the previous
one; backtrack(n) returns to the world numbered with n, and pops all
the intermediary worlds. The last three methods have a different behav-
ior since they are used to return to a previous world without forget-
ting what was asserted in the current world. The method commit() re-
turns to the previous world but carries the updates that were made
within the current world; these updates now belong to the previous
world and anothe r call to backtrack() would undo them. On the other
hand, backtrack0() also return to the previous world, but the updates
from the current world are permanently confirmed, as if they would be-
long to the world with index 0, which cannot be undone. Last, commit(n)
returns to the world numbered with n through successive applications of
commit().

write (core)

write(p:property, x:object, y:any) → any

This method is used to store a value in a slot of an ob-
ject.write(p,x,y) is equivalent to p(x) := y.

AUTHORS
Written by Yves Caseau and François Laburthe.

COPYRIGHT
Copyright © 1994-2023, Yves Caseau. All rights reserved.

SEE ALSO
claire(7)

Full documentation
<https://sites.google.com/view/claire4/home/a>>

CLAIRE(3)