Difference between revisions of "Language Reference/Attributes"

From wiki.visual-prolog.com
(intrinsic)
(47 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Preliminary Documentation}}
{{languageReferenceNavbar|Attributes}}
{{languageReferenceNavbar|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.
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 ===
=== Syntax ===
Line 14: Line 12:
     <LowerCaseIdentifier> ( <Literal>-comma-sep-list )</vipbnf>
     <LowerCaseIdentifier> ( <Literal>-comma-sep-list )</vipbnf>


Where the literals must either be numbers or string literals.
where the literals must either be numbers or string literals.


=== Insertion Points ===
=== Insertion Points ===


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


<vipbnf><InterfaceDeclaration> :
<vipbnf><InterfaceDeclaration> :
  interface <IinterfaceName> <Attributes>-opt <ScopeQualifications> <Sections> end interface <IinterfaceName>-opt</vipbnf>
    interface <IinterfaceName>
        <ScopeQualifications>
        <Attributes>-opt
    <Sections>
end interface <IinterfaceName>-opt</vipbnf>


<vipbnf><ClassDeclaration> :
<vipbnf><ClassDeclaration> :
  class <ClassName> <ConstructionType>-opt <Attributes>-opt <ScopeQualifications> <Sections> end class <ClassName>-opt</vipbnf>
    class <ClassName> <ConstructionType>-opt
        <ScopeQualifications>
        <Attributes>-opt
    <Sections>
    end class <ClassName>-opt</vipbnf>


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


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


<vipbnf><ConstantDefinition>: one of
<vipbnf><ConstantDefinition>: one of
Line 39: Line 49:


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


<vipbnf><PropertyDeclaration> :
<vipbnf><PropertyDeclaration> :
Line 46: Line 56:


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


The attributes of formal arguments are at the end.
The attributes of formal arguments are at the end.
Line 55: Line 65:


=== Specific Attributes ===
=== Specific Attributes ===
==== 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.
{{Example|
<vip>
domains
    meta =
        meta;
        metaDisplayAs(string DisplayAs) [attribute].
</vip>
}}
See [[Program Defined Attributes]].


==== byVal ====
==== byVal ====
Line 61: Line 85:


{{Example|
{{Example|
<vip>predicates
<vip>
     externalP : (point Point [byVal]) language apicall.</vip>
domains
}}
    point = point(integer X, integer Y).
predicates
     externalP : (point Point [byVal]) language apicall.
</vip>}}
 
The attribute can also be used in combination with the <vp>out</vp> attribute:
 
{{Example|
<vip>
predicates
    externalP2 : (point Point [byVal, out]) language apicall.
</vip>}}
 
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:
 
<vip>
implement xxx
 
class predicates
    initialize : () [classInitializer].
clauses
    initialize() :-
        …
 
end class xxx
</vip>
 
==== constant ====
 
The <vp>constant</vp> attribute is used to declare fact variables that cannot be changed once they have been initialized.
 
See {{lang2|Facts|Constant fact variables|Constant fact variables}}.
 
==== 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.
 
<vip>
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
</vip>
 
==== 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:
 
<vip>
domains
    ppp =
        fct(
            integer A,
            real B,
            ddd C,
            integer* New [default([])],
            real New2 [default(0)]
        ).
</vip>
 
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 ====
==== deprecated ====


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


{{Example|
{{Example|
<vip>predicates
<vip>predicates
     oldFasioned : (string Arg) [deprecated("Use newFasion instead")].</vip>
     oldFashioned : (string Arg) [deprecated("Use newFashion instead")].</vip>
}}
}}


Line 83: Line 192:
     writef : (string Format [formatString], ...).</vip>
     writef : (string Format [formatString], ...).</vip>
}}
}}
==== immediate ====
The attribute immediate enforces immediate (i.e. non-late) initialization of a fact variable:
{{Example|
<vip>
facts
    current : integer := initializeCurrent() [immediate].
</vip>
}}
See also {{Lang2|Facts|Fact Variable Declarations|Fact Variable Declarations}}.


==== in ====
==== in ====
Line 90: Line 212:
{{Example|
{{Example|
<vip>predicates
<vip>predicates
     pred : (string InputArg [in]).</vip>
     pred : (string InputArg [in]).
</vip>
}}
}}
==== in_iterate ====
Defines an in-iterator predicate for a domain or interface. See the description of the {{lang2|Terms|in|in}} operator.
==== in_test ====
Defines an in-test for a domain or interface. See the description of the {{lang2|Terms|in|in}} operator.


==== inline ====
==== inline ====


<vp>inline</vp> alters the memory layout of a struct (i.e. a single alternative functor domain with an align qualification).  The corresponding field is inlined instead of being pointed to.
<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


{{Example|
{{Example|
<vip>domains
<vip>domains
     point = align 4
     point =p(integer X, integer Y).
        p(integer X, integer Y).


domains
domains
     rectangle = align 4
     rectangle =
        r(
      r(
             point UpperLeft [inline],
             point UpperLeft [inline],
             point LowerRight [inline]
             point LowerRight [inline]
        ).</vip>
Since <vp>UpperLeft</vp> and <vp>LowerRight</vp> are inlined the struct have the same memory layout as this one:
<vip>domains
    rectangle2 =
        r2(
            integer UpperLeft_X,
            integer UpperLeft_Y,
            integer LowerRight_X,
            integer LowerRight_Y
         ).</vip>
         ).</vip>
}}
}}




It is also possible to inline fixed size string and string8 fields in structs:
When using <vp>inline(<size>)</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><size></vp> characters (i.e. <vp>char</vp> or <vp>char8</vp>, respectively).  The strings will be zero terminated if they are shorter than <vp><size></vp>, but not if they have <vp><size></vp> characters.


{{Example|
{{Example|
<vip>domains
<vip>domains
     device = align 4
     device =
        device(
            integer Id,
            string DeviceName [inline(12)]
        ).</vip>
<vp>DeviceName</vp> is an inlined Unicode string of length 12.
The struct have the same layout as:
<vip>domains
    device =
         device(
         device(
             integer Id,
             integer Id,
             string DeviceName [inline(32)]
             char DeviceName_01,
            char DeviceName_02,
            char DeviceName_03,
            char DeviceName_04,
            char DeviceName_05,
            char DeviceName_06,
            char DeviceName_07,
            char DeviceName_08,
            char DeviceName_09,
            char DeviceName_10,
            char DeviceName_11,
            char DeviceName_12
        ).</vip>
}}
 
When using <vp>inline(<size>)</vp> on the <vp>pointer</vp> type the struct will contain <vp><size></vp> bytes, and the pointer will become a pointer to that field:
 
{{Example|
<vip>domains
    mark =
        mark(
            integer Position,
            pointer Data [inline(8)]
        ).</vip>
<vp>Data</vp> is pointer to 8 inlined bytes
The struct have the same layout as:
<vip>domains
    mark2 =
        mark2(
            integer Position,
            byte Data_1,
            byte Data_2,
            byte Data_3,
            byte Data_4,
            byte Data_5,
            byte Data_6,
            byte Data_7,
            byte Data_8
         ).</vip>
         ).</vip>
And <vp>Data</vp> will point to <vp>Data_1</vp>.
}}
==== 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 {{Lang2|Terms|Optional parameters|Optional parameters}}).
{{Example|This predicate does not have optional output paramters
<vip>
predicates
    ppp : (integer X [out]) [mandatoryOut]. % The output parameter is mandatory
</vip>
}}
}}


==== noDefaultConstructor ====
==== 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 constructors at all.  Valid for an object creating class declaration.
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.


{{Example|
{{Example|
<vip>class classWithoutPublicConstructors : myInterface
<vip>class classWithoutPublicConstructors : myInterface
    open core
     [noDefaultConstructor]
     [noDefaultConstructor]
...
...
Line 135: Line 344:
==== out ====
==== out ====


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


{{Example|
{{Example|
Line 141: Line 350:
     pred : (string OutputArg [out]).</vip>
     pred : (string OutputArg [out]).</vip>
}}
}}
==== 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.
{{Example|
<vip>
domains
    packed = packed(integer8, pointer) [pack(2)].
</vip>
}}
The attribute can used on a <vp>class</vp> declaration to cover all domains in that class.
{{Example|The domains used with the RichEdit control must all be packed with 4:
<vip>
class richEdit_native
    open core, gui_native
    [pack(4)]
% pack all domains with packing size 4
end class richEdit_native
</vip>
}}
==== 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:
<vip>domains
    programPoint = programPoint(hScopeDescriptor ClassDescriptor, string PredicateName, sourceCursor Cursor).
</vip>
The clause name of such predicate or constructor should have suffix "_explicit". Valid for a predicate or constructor declaration.
{{Example|
<vip>predicates
    pred : (string String) [programPoint].
clauses
    pred_explicit(ProgramPoint, String) :-
        ...
</vip>
}}
The <vp>programPoint</vp> attribute is described in more details in the description of [[Language Reference/Predicates#programPoint|Predicates]], and it is a vital part of the exception system, see [[Exception Handling]].
==== presenter ====
Used to specify the presenter of a domain.
{{Example|
<vip>domains
    someDomain = ... [presenter(presenter_someDomain)].
</vip>
}}
Also used without argument to specify that an interface has a presenter.
{{Example|
<vip>interface something [presenter]
...
end interface something</vip>
}}
See [[Presenters]].


==== retired ====
==== retired ====
Line 148: Line 423:
{{Example|
{{Example|
<vip>predicates
<vip>predicates
     veryOldFasioned : (string Arg) [retired("Use newFasion instead")].</vip>
     veryOldFashioned : (string Arg) [retired("Use newFashion instead")].</vip>
}}
 
==== retiredFunctor ====
 
Functor alternatives can be retired.
 
<vip>domains
    ppp =
        fct(integer A, real B, ddd C) [retiredFunctor(aaa::fct_ppp)];
        fct2(integer A, ddd C, integer* New).</vip>
 
<vp>aaa::fct_ppp</vp> must be a predicate with this type (it can be an anonymous predicate):
 
<vip>predicates
    fct_ppp : (integer A, real B, ddd C) -> ppp NewValue.</vip>
 
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.
 
{{Example|
<vip>interface myInterface
    [sealed]
...
end interface myInterface
 
class myClass : myInterface
...
end class myClass</vip>
}}
 
==== this ====
 
Used for declaring {{lang2|Predicates|Extension Predicates|extension predicates}}.
 
{{Example|
<vip>
class predicates
    extension : (unsigned V [this]).
</vip>
}}
}}


==== union ====
==== union ====


Used for creating functor domains with several alternatives but no real functors.  This should only be used to mimic C/C++ uninon structs in low-level interfacing.  Valid for functor domain with several alternatives and alignment.
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.


{{Example|
{{Example|
Line 165: Line 493:
==== used ====
==== 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 local members.
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.


{{Example|
{{Example|

Revision as of 16:09, 26 February 2019

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

Attributes :
    [ Attribute-comma-sep-list ]
Attribute : one of
    LowerCaseIdentifier
    LowerCaseIdentifier ( Literal-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.

InterfaceDeclaration :
    interface IinterfaceName
        ScopeQualifications
        Attributes-opt
    Sections
end interface IinterfaceName-opt
ClassDeclaration :
    class ClassName ConstructionType-opt
        ScopeQualifications
        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

Specific Attributes

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.

Example
domains
    meta =
        meta;
        metaDisplayAs(string DisplayAs) [attribute].

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 language is stdcall, apicall or c.

Example
domains
    point = point(integer X, integer Y).
predicates
    externalP : (point Point [byVal]) language apicall.

The attribute can also be used in combination with the out attribute:

Example
predicates
    externalP2 : (point Point [byVal, out]) language apicall.

In that case a point 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 runtime_api::runProgramInitialization. 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 xxx::initialize is registered as a class initializer:

implement xxx
 
class predicates
    initialize : () [classInitializer].
clauses
    initialize() :-
        …
 
end class xxx

constant

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

See Constant fact variables.

compiletimeSetting

The compiletimeSetting 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 default/1 and retiredFunctor/1 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.

Example
predicates
    oldFashioned : (string Arg) [deprecated("Use newFashion instead")].

formatString

The argument is a format string for a subsequent ellipsis argument (i.e. ...). 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).

Example
predicates
    writef : (string Format [formatString], ...).

immediate

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

Example
facts
    current : integer := initializeCurrent() [immediate].

See also Fact Variable Declarations.

in

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

Example
predicates
    pred : (string InputArg [in]).

in_iterate

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

in_test

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

inline

inline 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.

inline 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 inline on struct field in another struct its data will be inlined instead of having a pointer to the struct

Example
domains
    point =p(integer X, integer Y).
 
domains
    rectangle =
       r(
            point UpperLeft [inline],
            point LowerRight [inline]
        ).

Since UpperLeft and LowerRight are inlined the struct have the same memory layout as this one:

domains
    rectangle2 =
        r2(
            integer UpperLeft_X,
            integer UpperLeft_Y,
            integer LowerRight_X,
            integer LowerRight_Y
        ).


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

Example
domains
    device =
        device(
            integer Id,
            string DeviceName [inline(12)]
        ).

DeviceName is an inlined Unicode string of length 12. The struct have the same layout as:

domains
    device =
        device(
            integer Id,
            char DeviceName_01,
            char DeviceName_02,
            char DeviceName_03,
            char DeviceName_04,
            char DeviceName_05,
            char DeviceName_06,
            char DeviceName_07,
            char DeviceName_08,
            char DeviceName_09,
            char DeviceName_10,
            char DeviceName_11,
            char DeviceName_12
        ).

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

Example
domains
    mark =
        mark(
            integer Position,
            pointer Data [inline(8)]
        ).

Data is pointer to 8 inlined bytes The struct have the same layout as:

domains
    mark2 =
        mark2(
            integer Position,
            byte Data_1,
            byte Data_2,
            byte Data_3,
            byte Data_4,
            byte Data_5,
            byte Data_6,
            byte Data_7,
            byte Data_8
        ).

And Data will point to Data_1.

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 Optional parameters).

Example This predicate does not have optional output paramters
predicates
    ppp : (integer X [out]) [mandatoryOut]. % The output parameter is mandatory

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.

Example
class classWithoutPublicConstructors : myInterface
    open core
    [noDefaultConstructor]
...
end class classWithoutPublicConstructors

out

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

Example
predicates
    pred : (string OutputArg [out]).

pack

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

Example
domains
    packed = packed(integer8, pointer) [pack(2)].

The attribute can used on a class declaration to cover all domains in that class.

Example The domains used with the RichEdit control must all be packed with 4:
class richEdit_native
    open core, gui_native
    [pack(4)]
 
% pack all domains with packing size 4
 
end class richEdit_native

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.

Example
predicates
    pred : (string String) [programPoint].
clauses
    pred_explicit(ProgramPoint, String) :-
        ...

The programPoint 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.

Example
domains
    someDomain = ... [presenter(presenter_someDomain)].

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

Example
interface something [presenter]
...
end interface something

See Presenters.

retired

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

Example
predicates
    veryOldFashioned : (string Arg) [retired("Use newFashion instead")].

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).

aaa::fct_ppp 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 aaa::fct_ppp.

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.

Example
interface myInterface
    [sealed]
...
end interface myInterface
 
class myClass : myInterface
...
end class myClass

this

Used for declaring extension predicates.

Example
class predicates
    extension : (unsigned V [this]).

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.

Example
domains
    u64var = align 4
        u64(unsigned64 Value64);
        u64_struct(unsigned Low32, unsigned High32)
        [union].

used

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

Example
predicates
    seeminglyUnused : () [used].