[ Syntax Settings | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

local portray(+TermClass, +TransPred, +Options), export portray(+TermClass, +TransPred, +Options)

Defines a portray transformation for the functor or type specified by TermClass.
+TermClass
Term in the form Atom, Atom/Integer or type(Type).
+TransPred
Term in the form Atom/Integer.
+Options
Possibly empty list of option flags.

Description

This declaration is used to define a portray transformation on a class of terms. Portray transformations are performed when a term is written by one of the predicates write/1,2, writeln/1,2, print/1,2, display/1,2 or printf/2,3 without the 'T' output option.

The TermClass specifies to which terms the transformation will be applied:

Name/Arity
transform all terms with the specified functor
type(Type)
transform all terms of the specified type, where Type is one of compound, string, integer, rational, float, breal, goal, atom, meta.
The +TransPred argument specifies the predicate that will perform the transformation. TransPred must be of arity 2 or 3 and be in the form: 
    trans_function(OldTerm, NewTerm [, Module]) :- ... .
At transformation time, the system will call TransPred in the module where local portray/3 was invoked. The term to transform is passed as the first argument, the second is a free variable which the transformation should bind to the transformed term, and the optional third argument is the module where the term is going to be printed.

Options is a list which may be empty or contain one of the following type specification atoms:

term
Transform all terms (this is the default)
clause
Transform only if the term is printed as a program clause, i.e. by printf/2,3 with the 'C' output option.
goal
Transform only if the term is printed as a goal, i.e. by printf/2,3 with the 'G' output option.
and possibly some of the following options:
protect_arg
Disable transformation of subterms (optional)
top_only
Consider only the whole term, not subterms (optional)
The visibility of portray declarations is controlled by the module system. Transformations only take place when the portray declarations is visible in the module where the term is being printed. The visibility is local or exported, depending on the declaration.

The functor no_macro_expansion/1 can be wrapped around specific instances of a term to prevent it from being transformed.

Portray declarations are being treated as 'write'-macros in current_macro/4 and erase_macro/2.

Fail Conditions

None.

Resatisfiable

No.

Exceptions

(4) instantiation fault
One or more arguments not instantiated.
(5) type error
TermClass not of form Atom, Atom/Integer or type(Type).
(5) type error
TransPred not of form Atom/Integer.
(5) type error
Options not a list or contains invalid flags.
(6) out of range
Arity of TransPred is not 2 or 3.
(6) out of range
Illegal flag in Options.
(161) macro transformation already defined in this module
Transformation already defined in the current module for TermClass

Examples

% Example showing use of write macros

    [eclipse 1]: [user].

     tr_s(0, 0).
     tr_s(s(S), N) :- tr_s(S, N1), N is N1+1.

     :- local portray(s/1, tr_s/2, []).

    yes.
    [eclipse 2]: write(s(s(s(0)))).
    3
    yes.


Error:
   local portray(X, trx/2, []).              (Error 4).
   local portray(a/1, tra/2, [c]).           (Error 6).

See Also

portray_goal / 2, macro / 3, printf / 2, printf / 3, current_macro / 4, erase_macro / 2