Quintus Prolog Manual

l-1: Reading the Reference pages

l-1-1: Mode Annotations

The mode annotations are useful to tell whether an argument is input or output or both. They also describe formally the instantiation pattern to the call which makes the call to the built-ins determinate. The mode annotations in the above example are '+' and '-'. Following is a complete description of the mode annotations you will find in the reference pages:

+

Input argument. This argument will be inspected by the predicate, and affects the behavior of the predicate, but will not be further instantiated by the predicate. An exception is raised if the argument isn't of the expected type. Note that the type class of an input arguments might include var.

-

Deterministic output argument. This argument is unified with the output value of the predicate. An output argument is only tested to be of the same type as the possible output value, if the type is simple (see {manual(l-1-3-1)}), and such testing is helpful to the user. Given the input arguments, the value of a deterministic output argument is uniquely defined.

*

Nondeterministic output argument. This argument is unified with the output value of the predicate. An output argument is only tested to be of the same type as the possible output value, if the type is simple (see {manual(l-1-3-1)}), and such testing is helpful to the user. The predicate might be resatisfiable, and might through backtracking generate more than one output value for this argument.

+-

An input argument that deterministically might be further instantiated by the predicate. Since it is an input argument, an exception will be raised if it isn't in the expected domain.

+*

An input argument that might be further instantiated by the predicate. The predicate might be resatisfiable, and might through backtracking generate more than one instantiation pattern for this argument. Since it is an input argument, an exception will be raised if it isn't in the expected domain.

If the synopsis of a predicate has more than one mode declaration, the first (the topmost) that satisfies both modes and types (of a goal instance), is the one to be applied (to that goal instance). All built-in predicates of arity zero are determinate (with the exception of repeat/0). For input arguments, an exception will be raised if the argument isn't of the specified type. For output arguments, an exception might be raised if the argument is nonvar, and not of the specified type. The generated value of the argument will be of the specified type.

l-1-2: Predicate Categories

This section describes the categories of predicates and how they are indicated in the reference pages for predicates of each given category. The names of categories hookable, hook, extendible, declaration, and meta-logical appear to the right of the title of the reference page.

• hookable : The behavior of the predicate can be customized/redefined by defining one or more hooks. The mode and type annotations of a hookable predicate might not be absolute, since hooks added by the user can change the behavior.
• hook : The predicate is user defined, and is called by a hookable builtin. A hook must be defined in module user. For a hook, the mode and type annotations should be seen as guide-lines to the user who wants to add his own hook; they describe how the predicate is used by the system.
• extendible : A dynamic, multifile predicate, to which new clauses can be added by the user. For such a predicate, the mode and type annotations should be seen as guide-lines to the user who wants to extend the predicate; they describe how the predicate is used by the system.
• declaration : You cannot call these directly but they can appear in files as ':- <declaration>' and give information to the compiler. The goal template is preceded by ':-' in the Synopsis .

Meta-predicates and operators are recognizable by the implicit conventions described below.

• Meta-predicates are predicates which need to assume some module. A list of built-in predicates which do module name expansion is provided in {manual(g-13-15)}. The reference pages of these predicates indicate which arguments are in a module expansion position by marking them as MOD in the Arguments field. That is, the argument can be preceded by a module prefix (an atom followed by a colon). For example:

           assert(mod:a(1), Ref)



   

If no module prefix is supplied, it will implicitly be set to the calling module. If the module prefix is a variable, an instantiation error will be raised. If it is not an atom a type error will be raised. So in any meta-predicate reference page the following exceptions are implicit: Exceptions:

• instantiation_error A module prefix is written as a variable.
• type_error A module prefix is not an atom.
• Whenever the name of a built-in predicate is defined as operator, the name is presented in the Synopsis as an operator, for example

           :- initialization +Goal                                      (A)

           +Term@-[1] @> +Term@-[2]                                    (B)



   

It is thus always possible to see if a name is an operator or not. The predicate can, of course, be written using the canonical representation, even when the name is an operator. Thus (A) and (B) can be written as (C) and (D), respectively:

           :- initialization(+Goal)                                     (C)

           @>(+Term@-[1],  +Term@-[2])                                  (D)



   

l-1-3: Argument Types

The argument section describes the type/domain of each argument. If it is a '+' argument, then the built-in always tests if the argument is the right type/domain. In some cases, types/domains mentioned in the Arguments section need not be the smallest set of all acceptable arguments.

l-1-3-1: Simple Types

The simple argument types are those for which type tests are provided. They are summarized in {manual(l-2-23)}. In addition there is stream_object, a special type of term described in {manual(g-7-6-1)}. If an output argument is given the type var, it means that that argument is not used by the predicate in the given instantiation pattern.

l-1-3-2: Extended Types

Following is a list of argument types which are defined in terms of the simple argument types. This is a formal description of the types/domains used in the Arguments sections of the reference pages for the built-ins. The rules are given in BNF (Backus-Naur form). term ::- (any Prolog term) list ::- list of Type ::- arity ::- (X <= 255)} char ::- pair ::- simple_pred_spec ::- pred_spec ::- pred_spec_tree ::- pred_spec_forest ::- gen_pred_spec ::- gen_pred_spec_tree ::- gen_pred_spec_tree_var ::- atoms also can be variables} extern_spec ::- extern_arg} extern_arg ::- foreign_spec ::- foreign_arg} foreign_arg ::- interf_arg_type ::- term | string | address file_spec ::- file_spec} expr ::- is/2; see the description of arithmetic expressions in {manual(g-8-3)}.} 2]: Exceptions:

• instantiation_error If Head (in Clause) or M is uninstantiated.
• type_error If Head is not of type callable, or if M is not an atom, or if Body is not a valid clause body.

For input arguments, an exception will be raised if the argument isn't of the specified type. For output arguments, an exception might be raised if the argument is nonvar, and not of the specified type. The generated value of the argument will be of the specified type. ", ELSE "" }

contact: product support sales information