Skip to content

Commit 1708fa9

Browse files
danielaferreirojfmc
authored andcommitted
(core) Minor improvements to modes package documentation
Src-commit: 333dab37eadf4da7b7c8d6132df1cd9c7e0e3155
1 parent 28235b5 commit 1708fa9

File tree

3 files changed

+50
-44
lines changed

3 files changed

+50
-44
lines changed

core/lib/isomodes/isomodes.pl

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
%% but then it says that the only error possible is for not
1616
%% meeting the : var... what to do?
1717
:- modedef '?'(_).
18-
:- modedef '@'(A) + not_further_inst(A).
18+
:- modedef '@'(A) : nonvar(A) + not_further_inst(A).
1919
%% Only in older versions of standard? It is obsolete now.
2020
%% :- modedef '*'(_).
2121

core/lib/modes/modes.pl

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -11,36 +11,38 @@
1111
% :- op(500, fx,(++)).
1212
% :- op(500, fx,(--).
1313

14-
%% "ISO-like" modes
14+
%% "ISO-like" modes (Note that, if nonvar in calls is included in the
15+
%% parametric versions —not done since implied by instantiation type—
16+
%% then these modes are equivalent to parametric versions with P = term).
1517
:- modedef +(A) : nonvar(A).
1618
:- modedef -(A) => nonvar(A). % This was : var(A). Could also imply steadfast.
17-
:- modedef --(A) : var(A). % Optional...
19+
:- modedef --(A) : var(A).
1820
:- modedef ?(_).
1921
:- modedef @(A) + not_further_inst(A).
2022

2123
%% Useful input-output modes
2224
:- modedef in(A) : ground(A) => ground(A).
2325
:- modedef ++(A) : ground(A) => ground(A). % Optional alias...
24-
:- modedef out(A) : var(A) => ground(A). % Take out the var/1 and no need for go?
25-
:- modedef go(A) => ground(A).
26+
:- modedef out(A) : var(A) => ground(A).
27+
:- modedef go(A) => ground(A). % Note: used in foreign interface
2628

27-
%%% Other possibilities:
29+
%% TODO: Other possibilities:
2830
%% : mode for meta (also implies nonvar)
29-
%% ! mode for mutables
31+
%% ! mode for mutables (cf. fsyntaxplus)
3032

3133
:- push_prolog_flag(read_hiord,on).
3234

3335
%% Parametric versions of above
34-
%% TODO: hiord order? (Need to change in assrt
35-
:- modedef +(A,P) : P(A). % This was :: P(A) : nonvar(A).
36-
:- modedef -(A,P) => P(A). % This was :: P(A) : var(A).
37-
:- modedef --(A,P) : var(A) => P(A).
38-
:- modedef ?(A,P) :: P(A).
36+
%% TODO: hiord order? (Need to change in assrt)
37+
:- modedef +(A,P) : (nonvar(A),P(A)). % Obviously implies nonvar(A)
38+
:- modedef -(A,P) => (nonvar(A),P(A)).
39+
:- modedef --(A,P) : var(A) => P(A).
40+
:- modedef ?(A,P) :: P(A).
3941
:- modedef @(A,P) :: P(A) + not_further_inst(A).
4042

41-
:- modedef in(A,P) : (ground(A),P(A)) => ground(A). % This was :: P(A) : ground(A) => ground(A).
43+
:- modedef in(A,P) : (ground(A),P(A)) => ground(A).
4244
:- modedef ++(A,P) : (ground(A),P(A)) => ground(A). % Optional alias...
43-
:- modedef out(A,P) : var(A) => (ground(A),P(A)). % This was :: P(A) : var(A) => ground(A).
44-
:- modedef go(A,P) => (ground(A),P(A)). % This was :: P(A) => ground(A).
45+
:- modedef out(A,P) : var(A) => (ground(A),P(A)).
46+
:- modedef go(A,P) => (ground(A),P(A)).
4547

4648
:- pop_prolog_flag(read_hiord).

core/lib/modes/modes_doc.pl

Lines changed: 33 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,11 @@
1010

1111
:- doc(module,"This package defines a number of @concept{modes} which
1212
are frequently useful in programs when describing predicates, e.g.,
13-
via @decl{pred} assertions. They correspond to the modes used in
13+
via @decl{pred} assertions (or @em{doccomments}, see below).
14+
They correspond to the modes used in
1415
many classical Prolog texts and code as documentation, with some
15-
additions. However, these modes are actually syntactic sugar for
16-
assertions, that can be checked either statically or
16+
additions. In Ciao these modes are actually syntactic sugar for
17+
assertions, so that they can be checked either statically or
1718
dynamically. Note that some of these modes use the same symbol as
1819
one of the @lib{basicmodes} and @lib{isomodes} packages (see
1920
@ref{Some basic Prolog modes} and @ref{ISO-Prolog modes}) but have
@@ -33,12 +34,12 @@
3334
@end{verbatim}
3435

3536
(more precise than the above), expresses that @pred{is/2} should be
36-
called with the second argument instantiated to an arithmetic
37+
called with the second argument @em{instantiated} to an arithmetic
3738
expression and that on success it will bind the first argument to a
3839
number. The argument of a mode as above can be any property,
3940
including, e.g., regular types.
4041

41-
The first declaration is equivalent to (it is in fact translated
42+
The first declaration is equivalent to (and is in fact translated
4243
to) the assertion:
4344

4445
@begin{verbatim}
@@ -60,11 +61,11 @@
6061
% and binds the first argument with the result.
6162
@end{verbatim}
6263

63-
and they are also translated to the corresponding assertions.").
64+
which are also translated to the corresponding assertions.").
6465

6566
:- use_package(modes).
6667

67-
:- doc( + /1,"Argument should be bound (nonvar) when the predicate is
68+
:- doc( + /1,"The argument should be bound (nonvar) when the predicate is
6869
called. For example:
6970

7071
@begin{verbatim}
@@ -74,12 +75,11 @@
7475
expresses that both arguments of @pred{>/2} should be bound when
7576
the predicate is called.").
7677

77-
:- doc( + /2,"Argument should be instantiated when the predicate is
78-
called to a term that has the indicated type or property. For
79-
example:
78+
:- doc( + /2,"This argument should be @em{instantiated} when the
79+
predicate is called. For example:
8080

8181
@begin{verbatim}
82-
:- pred + > +.
82+
:- pred +arithexpression > +arithexpression.
8383
@end{verbatim}
8484

8585
expresses that both arguments of @pred{>/2} should be bound to
@@ -91,60 +91,64 @@
9191
succeeds.").
9292

9393
:- doc( - /2,"The argument is an output argument. It may be bound or
94-
not at call time. It will be instantiated to a term that has the
95-
indicated type or property if the predicate succeeds. For example,
96-
this assertion:
94+
not at call time. It will be @em{instantiated} to a term that has
95+
the indicated type or property if the predicate succeeds. For
96+
example, this assertion:
9797

98-
@begin{verbatim} :- pred length(-list,-int). @end{verbatim}
98+
@begin{verbatim}
99+
:- pred length(-list,-int).
100+
@end{verbatim}
99101

100102
expresses that @pred{length/2} can be called in any mode, but on
101-
output the second argument will be instantiated to a number and the
102-
first one will be instantiated to a lit. Note that this does not
103-
mean that the list will be ground, but rather that it will be a
104-
complete list but whose elements can be any term, including
105-
variables.").
103+
output the second argument will be @em{instantiated} to a number
104+
and the first one will be @em{instantiated} to a list. Note that
105+
this does not mean that the list will be ground, but rather that it
106+
will be a complete list but whose elements can be any term,
107+
including variables (see the discussion of instantitation and
108+
compatibility types in @ref{Declaring regular types}.").
106109

107110
:- doc(-- /1,"The argument should be a free variable (i.e., unbound)
108111
when the predicate is called.").
109112

110113
:- doc(-- /2,"The argument should be a free variable (i.e., unbound)
111114
when the predicate is called and will be bound to a term that has
112-
the indicated type or property if the predicate succeeds.").
115+
the indicated type or property in general, if the predicate
116+
succeeds.").
113117

114118
:- doc( ? /1,"No information is given on this argument.").
115119

116-
:- doc( ? /2,"The argument can be a variable or, if it is intantiated,
117-
it is to a term that is compatible with the indicated type or
118-
property.").
120+
:- doc( ? /2,"The argument can be a variable or, if it is
121+
instantiated, it is to a term that is @em{compatible} with the
122+
indicated type or property.").
119123

120124
:- doc( @ /1,"The argument will not be further instantiated, i.e.,
121125
will not be more instantiated than when the predicate is called.").
122126

123127
:- doc( @ /2,"The argument will not be further instantiated, i.e.,
124128
will not be more instantiated than when the predicate is called,
125-
and the term is compatible with the indicated type or property.").
129+
and the term is @em{compatible} with the indicated type or property.").
126130

127131
:- doc( in/1,"The argument is ground at call time.").
128132

129-
:- doc( in/2,"The argument is ground at call time and is compatible
133+
:- doc( in/2,"The argument is ground at call time and is @em{compatible}
130134
with the indicated type or property.").
131135

132136
:- doc(++ /1,"Same as @tt{in}: the argument is ground at call time.").
133137

134138
:- doc(++ /2,"Same as @tt{in}: the argument is ground at call time and
135-
is compatible with the indicated type or property.").
139+
is @em{compatible} with the indicated type or property.").
136140

137141
:- doc(out/1,"The argument is a variable when the predicate is called
138142
and will be ground if the predicate succeeds.").
139143

140144
:- doc(out/2,"The argument is a variable when the predicate is called
141-
and will be be bound to a ground term that is compatible with the
145+
and will be bound to a ground term that is @em{compatible} with the
142146
indicated type or property, if the predicate succeeds.").
143147

144148
:- doc( go/1,"The argument is ground by the predicate, if it
145149
succeeds.").
146150

147151
:- doc( go/2,"The argument is ground by the predicate to a ground term
148-
that is compatible with the indicated type or property, if the
152+
that is @em{compatible} with the indicated type or property, if the
149153
predicate succeeds.").
150154

0 commit comments

Comments
 (0)