Difference between revisions of "Language Reference/Attributes"

From wiki.visual-prolog.com
(Attributes in scope)
(Attributes in scope)
Line 1: Line 1:
{{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.
=== Syntax ===
<vipbnf><Attributes> :
    [ <Attribute>-comma-sep-list ]</vipbnf>
<vipbnf><Attribute> : one of
    <LowerCaseIdentifier>
    <LowerCaseIdentifier> ( <Literal>-comma-sep-list )</vipbnf>
where the literals must either be numbers or string literals.
{{languageReferenceNavbar|Attributes}}
{{languageReferenceNavbar|Attributes}}


Line 51: Line 66:
<vipbnf><FormalArgument> :
<vipbnf><FormalArgument> :
     <TypeExpression> <ArgumentName>-opt <Attributes>-opt</vipbnf>
     <TypeExpression> <ArgumentName>-opt <Attributes>-opt</vipbnf>
=== Specific 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>.
{{Example|
<vip>predicates
    externalP : (point Point [byVal]) language apicall.</vip>
}}
==== 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 entity will not exist in future versions of Visual Prolog.  Valid for member declarations and scopes.
{{Example|
<vip>predicates
    oldFasioned : (string Arg) [deprecated("Use newFasion instead")].</vip>
}}
==== formatString ====
The argument is a {{lang2|Domains|Format Strings|format string}} 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).
{{Example|
<vip>predicates
    writef : (string Format [formatString], ...).</vip>
}}
==== in ====
The argument is an input argument.  Valid for a formal predicate argument.
{{Example|
<vip>predicates
    pred : (string InputArg [in]).</vip>
}}
==== 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.
{{Example|
<vip>domains
    point = align 4
        p(integer X, integer Y).
domains
    rectangle = align 4
        r(
            point UpperLeft [inline],
            point LowerRight [inline]
        ).</vip>
}}
It is also possible to inline fixed size string and string8 fields in structs:
{{Example|
<vip>domains
    device = align 4
        device(
            integer Id,
            string DeviceName [inline(32)]
        ).</vip>
}}
==== 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.
{{Example|
<vip>class classWithoutPublicConstructors : myInterface
    [noDefaultConstructor]
...
end class classWithoutPublicConstructors</vip>
}}
==== out ====
The argument is an output argument.  Valid for a formal predicate argument.
{{Example|
<vip>predicates
    pred : (string OutputArg [out]).</vip>
}}
==== retired ====
The declared entity is retired. The string literal describes how to migrate from it.  The entity does not exist anymore.
{{Example|
<vip>predicates
    veryOldFasioned : (string Arg) [retired("Use newFasion instead")].</vip>
}}
==== 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|
<vip>domains
    u64var = align 4
        u64(unsigned64 Value64);
        u64_struct(unsigned Low32, unsigned High32)
        [union].</vip>
}}
==== 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.
{{Example|
<vip>predicates
    seeminglyUnused : () [used].</vip>
}}


=== Specific Attributes ===
=== Specific Attributes ===

Revision as of 21:16, 31 August 2010

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.


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 before 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

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
predicates
    externalP : (point Point [byVal]) language apicall.

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 entity will not exist in future versions of Visual Prolog. Valid for member declarations and scopes.

Example
predicates
    oldFasioned : (string Arg) [deprecated("Use newFasion 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], ...).

in

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

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

inline

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

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


It is also possible to inline fixed size string and string8 fields in structs:

Example
domains
    device = align 4
        device(
            integer Id,
            string DeviceName [inline(32)]
        ).

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.

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

out

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

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

retired

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

Example
predicates
    veryOldFasioned : (string Arg) [retired("Use newFasion instead")].

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 local members.

Example
predicates
    seeminglyUnused : () [used].

Specific 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
predicates
    externalP : (point Point [byVal]) language apicall.

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 entity will not exist in future versions of Visual Prolog. Valid for member declarations and scopes.

Example
predicates
    oldFasioned : (string Arg) [deprecated("Use newFasion 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], ...).

in

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

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

inline

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

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


It is also possible to inline fixed size string and string8 fields in structs:

Example
domains
    device = align 4
        device(
            integer Id,
            string DeviceName [inline(32)]
        ).

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.

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

out

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

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

retired

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

Example
predicates
    veryOldFasioned : (string Arg) [retired("Use newFasion instead")].

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 local members.

Example
predicates
    seeminglyUnused : () [used].