|
10 | 10 |
|
11 | 11 | :- doc(module,"This package defines a number of @concept{modes} which
|
12 | 12 | 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 |
14 | 15 | 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 |
17 | 18 | dynamically. Note that some of these modes use the same symbol as
|
18 | 19 | one of the @lib{basicmodes} and @lib{isomodes} packages (see
|
19 | 20 | @ref{Some basic Prolog modes} and @ref{ISO-Prolog modes}) but have
|
|
33 | 34 | @end{verbatim}
|
34 | 35 |
|
35 | 36 | (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 |
37 | 38 | expression and that on success it will bind the first argument to a
|
38 | 39 | number. The argument of a mode as above can be any property,
|
39 | 40 | including, e.g., regular types.
|
40 | 41 |
|
41 |
| - The first declaration is equivalent to (it is in fact translated |
| 42 | + The first declaration is equivalent to (and is in fact translated |
42 | 43 | to) the assertion:
|
43 | 44 |
|
44 | 45 | @begin{verbatim}
|
|
60 | 61 | % and binds the first argument with the result.
|
61 | 62 | @end{verbatim}
|
62 | 63 |
|
63 |
| - and they are also translated to the corresponding assertions."). |
| 64 | + which are also translated to the corresponding assertions."). |
64 | 65 |
|
65 | 66 | :- use_package(modes).
|
66 | 67 |
|
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 |
68 | 69 | called. For example:
|
69 | 70 |
|
70 | 71 | @begin{verbatim}
|
|
74 | 75 | expresses that both arguments of @pred{>/2} should be bound when
|
75 | 76 | the predicate is called.").
|
76 | 77 |
|
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: |
80 | 80 |
|
81 | 81 | @begin{verbatim}
|
82 |
| -:- pred + > +. |
| 82 | +:- pred +arithexpression > +arithexpression. |
83 | 83 | @end{verbatim}
|
84 | 84 |
|
85 | 85 | expresses that both arguments of @pred{>/2} should be bound to
|
|
91 | 91 | succeeds.").
|
92 | 92 |
|
93 | 93 | :- 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: |
97 | 97 |
|
98 |
| -@begin{verbatim} :- pred length(-list,-int). @end{verbatim} |
| 98 | +@begin{verbatim} |
| 99 | +:- pred length(-list,-int). |
| 100 | +@end{verbatim} |
99 | 101 |
|
100 | 102 | 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}."). |
106 | 109 |
|
107 | 110 | :- doc(-- /1,"The argument should be a free variable (i.e., unbound)
|
108 | 111 | when the predicate is called.").
|
109 | 112 |
|
110 | 113 | :- doc(-- /2,"The argument should be a free variable (i.e., unbound)
|
111 | 114 | 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."). |
113 | 117 |
|
114 | 118 | :- doc( ? /1,"No information is given on this argument.").
|
115 | 119 |
|
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."). |
119 | 123 |
|
120 | 124 | :- doc( @ /1,"The argument will not be further instantiated, i.e.,
|
121 | 125 | will not be more instantiated than when the predicate is called.").
|
122 | 126 |
|
123 | 127 | :- doc( @ /2,"The argument will not be further instantiated, i.e.,
|
124 | 128 | 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."). |
126 | 130 |
|
127 | 131 | :- doc( in/1,"The argument is ground at call time.").
|
128 | 132 |
|
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} |
130 | 134 | with the indicated type or property.").
|
131 | 135 |
|
132 | 136 | :- doc(++ /1,"Same as @tt{in}: the argument is ground at call time.").
|
133 | 137 |
|
134 | 138 | :- 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."). |
136 | 140 |
|
137 | 141 | :- doc(out/1,"The argument is a variable when the predicate is called
|
138 | 142 | and will be ground if the predicate succeeds.").
|
139 | 143 |
|
140 | 144 | :- 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 |
142 | 146 | indicated type or property, if the predicate succeeds.").
|
143 | 147 |
|
144 | 148 | :- doc( go/1,"The argument is ground by the predicate, if it
|
145 | 149 | succeeds.").
|
146 | 150 |
|
147 | 151 | :- 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 |
149 | 153 | predicate succeeds.").
|
150 | 154 |
|
0 commit comments