Language Reference/Attributes

Various definitions and declarations can be annotated with attributes. This section describes the general syntax of attributes and where they can be placed. It also describes the meaning of the specific attributes.

Syntax
 : [ -comma-sep-list ]

 : one of     ( -comma-sep-list )

where the literals must either be numbers or string literals.

Insertion Points
The attributes of interfaces, classes and implementations are right after the scope qualifications.

 : interface   -opt  end interface -opt

 : class  -opt  <Attributes>-opt <Sections> end class <ClassName>-opt

<ClassImplementation> : implement <ClassName> <ScopeQualifications> <Attributes>-opt <Sections> end implement <ClassName>-opt

The attributes of constants, domains, predicates, properties and facts are at the end (i.e. right before the terminating dot).

<ConstantDefinition>: one of   <ConstantName> = <ConstantValue> <Attributes>-opt <ConstantName> : <TypeName> = <ConstantValue> <Attributes>-opt

<DomainDefinition>: <DomainName> <FormalTypeParameterList>-opt = <TypeExpression> <Attributes>-opt

<PredicateDeclaration> : <PredicateName> : <PredicateDomain> <LinkName>-opt <Attributes>-opt <PredicateName> : <PredicateDomainName> <LinkName>-opt <Attributes>-opt

<PropertyDeclaration> : <PropertyName> : <PropertyType> <FlowPattern>-list-opt <Attributes>-opt

<FactDeclaration> : <FactVariableDeclaration> <Attributes>-opt <FactFunctorDeclaration> <Attributes>-opt

The attributes of formal arguments are at the end.

<FormalArgument> : <TypeExpression> <ArgumentName>-opt <Attributes>-opt

attribute
This attribute is used on a functor domain to indicate that the functors in the domain can be used as attributes elsewhere in the program.

See Program Defined Attributes.

byVal
An argument is transferred directly on the stack rather than using a pointer. Valid for formal predicate arguments provided the <vp>language</vp> is <vp>stdcall</vp>, <vp>apicall</vp> or <vp>c</vp>.

The attribute can also be used in combination with the <vp>out</vp> attribute:

In that case a <vp>point</vp> structure will be allocated before the call then a pointer to that structure is transferred handed to the external predicate which can then fill the structure with relevant data.

classInitializer
This attribute indicates that a predicate should be invoked as a class initializer. It can be applied to a class predicate that does not take any arguments. The predicate will be invoked when the initialization code invokes the <vp>runtime_api::runProgramInitialization</vp>. A class can have any number of class initializer which will be invoked in an undetermined order. Notice that other classes may not have been initialized.

The predicate <vp>xxx::initialize</vp> is registered as a class initializer:

implement xxx

class predicates initialize : [classInitializer]. clauses initialize :- …

end class xxx

constant
The <vp>constant</vp> attribute is used to declare fact variables that cannot be changed once they have been initialized.

See.

compiletimeSetting
The <vp>compiletimeSetting</vp> attribute indicates that a constant should be considered a compiletime setting. As a result the compiler will suppress warnings about always failing/succeding code and about unreachable code that may be caused by this constant. The warning suppession is an approximation, because it a may be impossible/difficult to determine the cause of a warning.

implement xxx

constants debugOutput : boolean = false [compiletimeSetting].

clauses pppp(...) :- ...       if true = debugOutput then % do not give a warning about unreachable code log::write(...) end if, ...

end implement xxx

default
It is problematic to update functor domains, if terms have been persisted in serialized form. Because new programs cannot deal with old serializations.

The two attributes <vp>default/1</vp> and <vp>retiredFunctor/1</vp> can help dealing with this problem.

The last arguments of a functor can have default values:

domains ppp = fct(           integer A,            real B,            ddd C,            integer* New [default([])],            real New2 [default(0)]        ).

The default attribute does not change anything within the program; it only affects the deserialization. If during deserialization we meet the closing parenthesis too soon we supply default values for the remaining arguments.

Notice that this will only work for text deserialization.

See also Functor Domain Versioning.

deprecated
The declared entity is deprecated. The string literal describes how to migrate from it. The entity still exists, but usage will cause a warning. The entity will not exist in future versions of Visual Prolog. Valid for member declarations and scopes.

formatString
The argument is a for a subsequent ellipsis argument (i.e. <vp>...</vp>). Valid for one string argument of a predicate with an ellipsis argument. The use of formatString will make the compiler check the validity of actual arguments with respect to actual format strings (where possible).

immediate
The attribute immediate enforces immediate (i.e. non-late) initialization of a fact variable:

See also.

in
The argument is an input argument. Valid for a formal predicate argument.

in_iterate
Defines an in-iterator predicate for a domain or interface. See the description of the operator.

in_test
Defines an in-test for a domain or interface. See the description of the operator.

inline
<vp>inline</vp> alters the memory layout of a struct (i.e. a single alternative functor domain with an align qualification). The purpose of the attribute is to ease interfacing to foreign languages and should normally not be used for pure Visual Prolog.

<vp>inline</vp> can be used in three cases:


 * inlining a struct rather than having a pointer to the struct
 * inlining a fixed size string
 * inlining a fixed number of bytes

When using <vp>inline</vp> on struct field in another struct its data will be inlined instead of having a pointer to the struct

When using <vp>inline</vp> on a <vp>string</vp> or a <vp>string8</vp> field in a struct, the struct will contain a fixed size string with <vp> </vp> characters (i.e. <vp>char</vp> or <vp>char8</vp>, respectively). The strings will be zero terminated if they are shorter than <vp> </vp>, but not if they have <vp> </vp> characters.

When using <vp>inline</vp> on the <vp>pointer</vp> type the struct will contain <vp> </vp> bytes, and the pointer will become a pointer to that field:

intrinsic
A declaration which has special meaning and handling in the compiler (semi-built-in).

mandatoryOut
Used to prevent a predicate from having optional output parameters (see ).

noDefaultConstructor
Used for a class to indicate that it should not have an implicit default constructor, and can thus be used to a class that does not have any public constructors at all. Valid for an object creating class declaration.

out
The argument is an output argument. Valid for a formal predicate argument.

pack
The <vp>[pack(n)]</vp> attribute (where <vp>n</vp> is a number) instructs the compiler to use <vp>n</vp> as packing size for a functor domains. By default the packing size is <vp>4</vp> in 32 bit programs and <vp>8</vp> in 64 bit programs. This attribute is mainly intended for compatibility with C/C++ api's.

The attribute can used on a <vp>class</vp> declaration to cover all domains in that class.

programPoint
Used for a predicate or constructor declaration to indicate that it recieves an extra input argument which describes the place in a program (program point) where this predicate was called. This additional argument has programPoint type which is declared in the PFC core class like:

domains programPoint = programPoint(hScopeDescriptor ClassDescriptor, string PredicateName, sourceCursor Cursor).

The clause name of such predicate or constructor should have suffix "_explicit". Valid for a predicate or constructor declaration.

The <vp>programPoint</vp> attribute is described in more details in the description of Predicates, and it is a vital part of the exception system, see Exception Handling.

presenter
Used to specify the presenter of a domain.

Also used without argument to specify that an interface has a presenter.

See Presenters.

retired
The declared entity is retired. The string literal describes how to migrate from it. The entity does not exist anymore.

retiredFunctor
Functor alternatives can be retired.

domains ppp = fct(integer A, real B, ddd C) [retiredFunctor(aaa::fct_ppp)]; fct2(integer A, ddd C, integer* New).

<vp>aaa::fct_ppp</vp> must be a predicate with this type (it can be an anonymous predicate):

predicates fct_ppp : (integer A, real B, ddd C) -> ppp NewValue.

I.e. it takes the arguments of the old functor and returns a value in the functor domain.

In the program fct is does not exist at all, it is retired. But in the deserialization fct terms can still be handled: The arguments are parsed according to the types, and then the value is created by invoking <vp>aaa::fct_ppp</vp>.

This method will also work for binary serializations, provided:


 * The old domain had more than one alternative (so there are functor numbers in the serialization)
 * New alternatives are added last (to retain functor numbers)

It is however not recommend using binary serialization for inter-session persistence.

See also Functor Domain Versioning.

sealed
Used for an interface to indicate that it cannot be supported by any other interface. This allows to create more efficient codes, because the compiler provides some optimization when using the objects of such type. Valid for an object creating class declaration as a construction interface.

this
Used for declaring.

union
Used for creating functor domains with several alternatives but no real functors. This should only be used to mimic C/C++ union structs in low-level interfacing. Valid for functor domain with several alternatives and alignment.

used
An unused local member can be marked <vp>used</vp> to prevent the compiler to issue a warning and remove the corresponding code. Valid for members.