The Handlers argument specifies a list of handler predicates for several built-in operations which require user-defined actions whenever an attributed variable is encountered. The list contains elements in the form Operation:Pred, where Operation is the predefined name of the built-in operation and Pred is the handler predicate specification. The handler definition module is assumed to be the module in which meta_attribute/2 is being called; another module can be specified by using the tool body predicate meta_attribute_body/3. When true/0 is specified as the handler or when no handler for a particular operation is specified, this operation will ignore this extension. If the extension Name already exists, the specified handlers are updated, the non-specified ones remain.
The call meta_attribute(Name, []) can be used as a preliminary declaration of a particular attribute, e.g. to compile a module part before the actual declaration is called, or when processing separate files that belong to a particular module.
The meta_attribute/2 predicate is sensitive to the flag debug_compile. If it is on, the calls to the local handlers will be traceable (and slower), if it is off, it will be the opposite. All specified handlers will be exported from their definition module.
The predefined operations and the corresponding handler arguments are the following:
unify
Operation : unification
Handler : handler(+Term, ?Attribute, ?Goals, -GoalsTail)
Description : The handler for the usual unification. Term is the term that was unified with the attributed variable, it is either a nonvariable or an attributed variable. Attribute is directly the contents of the attribute slot corresponding to the extension, i.e. it is not the whole attributed variable. The remaining two arguments are a difference list of goals that should be woken after all attributes of all extensions are processed. When this handler is invoked, the attributed variable is already bound to Term. The handler can also have only 2 first arguments in case that it does not want to pass any suspended goal to the waking routine. The handler is free to wake any suspended goals directly, without returning them to the caller.
test_unify
Operation : unification test
Handler : handler(+Term, ?Attribute)
Description : The handler for the unification which is not supposed to trigger constraints propagation. It is used e.g. in the not_unify/2 predicate. The handler arguments are equivalent to those of the unification handler, Term is the term that was unified with the attributed variable, Attribute is the attribute of this extension. During the execution of the handler the attributed variable is bound to Term, however when all local handlers succeed, all bindings are undone.
compare_instances
Operation : instance and variant tests
Handler : handler(-Res, ?TermL, ?TermR)
Description : The handler for the variant/2, instance/2 and other instance-testing predicates. The handler arguments are similar to those of the compareinstances/3 predicate: Res is the relation between the two terms TermL and TermR, it can be either = or < (the handler might directly fail if the result is >). All bindings made in the handler will be undone after processing the local handlers.
copy_term
Operation : copying an attributed variable
Handler : handler(?Meta, ?Var)
Description : The handler for the copy_term/2 predicate. Meta is the attributed variable encountered in the copied term, Var is its corresponding variable in the copy. All extension handlers receive the same arguments. This means that if the attributed variable should be copied as an attributed variable, the handler must check if Var is still a free variable or if it was already bound to an attributed variable by a previous handler.
delayed_goals
Operation : querying suspended goals of a variable
Handler : handler(?Meta, ?Goals, -GoalsTail)
Description : The handler for the delayed_goals/2 predicate. Meta is the attributed variable encountered in the predicate. The handler is supposed to create a difference list of all goals in the suspended lists for this attribute.
delayed_goals_number
Operation : querying suspended goals of a variable
Handler : handler(?Meta, -GoalsNumber)
Description : The handler for the delayed_goals_number/2 predicate. Meta is the attributed variable encountered in the predicate. The handler is supposed to return the number of all suspended goals in this attribute.
Operation : printing the attribute
Handler : handler(?Meta, -Attribute)
Description : Printing the attribute in printf/2, 3 when the m option is specified. Meta is the attributed variable being printed, Attribute is the term which will be printed as a value for this attribute, qualified by the attribute name. If no handler is specified for an attribute, it will not be printed. If there is only one attribute with an associated print handler, the attribute value is not qualified with the attribute name.
[eclipse 5]: write(X{a}). undefined metaterm attribute in trans_meta_in(X, _g370, eclipse) syntax error : in source transformation | write(X{a}). | ^ here [eclipse 6]: meta_attribute(eclipse, []). yes. [eclipse 7]: printf("%QPMw", X{a}). X{suspend : _g386 , a} X = X yes.