Notation

Throughout this documentation the following notational conventions are used:

Mode Declarations

The following prefixes to argument names indicate how to call the documented predicate:

  • + – at call time the respective argument must be bound, that is, it must be a constant, function term or a variable that has been unified to a constant or function term.
  • - – at call time the respective argument must be free, that is, it must be a variable that has not been unified to a constant or function term.
  • ? – at call time the respective argument may be either bound or free.

The documentation typically specifies invocation modes. Upon successful completion of a call it is generally assumed that all arguments of the call are non-variable (+). Other result modes should be explicitly documented.

Note that "non-variable") is weaker than "variable-free". For instance, the term ”classDefT(Id,Pack,Name,Members)” is non-variable but it is not variable-free since it contains the variables Id, Pack, Name and Members.

(Non)Determinism

A Prolog predicate is said to be deterministic for a given invocation mode if every call to it that respects this mode succeeds only once. Otherwise, it is non-deterministic.

For instance, the append/3 predicate is deterministic if invoked with non-variable terms in the first two parameters or with a non-variable term in the third parameter. However, if invoked with a nonvariable term only in the first parameter it is nondeterministic, returning upon backtracking an infinite number of results (all possible extensions of the first list).

Deterministic invocation modes are indicated by is det after the invocation mode. Non-deterministic modes are indicated by is nondet:

   append(+First:list, +Second:list, ?Third:list) is det
   append(?First:list, ?Second:list, +Third:list) is det
   append(+First:list, ?Second:list, ?Third:list) is nondet

Argument Types

Prolog does no static typechecking. However, for documentation purposes, in all the predicate specifications that you find on this website, arguments are annotated like this

   mypredicate(+First:list, +Second:atom, ?Third:id, ?Fourth:term) is det

with the following types listed:

  • atom – Any Prolog constant. Either a number (e.g. 100), or a string starting with a lower case letter (e.g. myObject), or a string enclosed in simple quotes (e.g. 'MyClassName').
  • id – This is an atom used as the unique identity of an abstract syntax tree node. Via ids, nodes can refer to each other. Structurally an ID is not different from any other atom. However, its special use lets it deserve special documentation.
  • list – A Prolog list. Occasionally, it is indicated as [elementtype, …], to emphasize its element type.
  • term – A Prolog term that is neither an atom nor a list. It typically consists of a functor and some arguments enclosed in round brackets, e.g. classDefT(ClassId, PackageId, 'Object', MemberIdList).
  • any – A Prolog term that may be any of the above.

If there is no annotation it is just because the documentation is incomplete. Please help us by updating it (if you have write access to these pages) or otherwise, by asking us to do so.

More Argument Type Conventions

In some parts of the documentation the above notation is replaced by some other conventions (sorry for the temporary inconsistency):

  • id – An argument name starting with # represents an ID (an identifier of an AST node).
  • atom – An argument name surrounded by single quotes 'atom' represents an atom.
  • lists – Square braces [ and ] enclose lists of values.
  • term – The string TYPE indicates that the respective argument value is a type term.
  • alternatives – The pipe symbol ('|') separates different, alternative types of an argument.

So the above example could also appear as

   mypredicate(+[First], +'Second', ?#Third, ?Fourth:term) is det
Last modified: 2014/07/29 14:30
*