Difference between revisions of "Language Reference/Attributes"
(formatString details moved here) Tags: Manual revert Reverted |
m (Reverted edits by Thomas Linder Puls (talk) to last revision by Tbn) Tags: Reverted Rollback |
||
Line 65: | Line 65: | ||
=== Specific Attributes === | === Specific Attributes === | ||
==== byVal ==== | ==== byVal ==== | ||
Line 85: | Line 71: | ||
{{Example| | {{Example| | ||
<vip> | <vip>predicates | ||
externalP : (point Point [byVal]) language apicall.</vip> | |||
}} | |||
predicates | |||
externalP : (point Point [byVal]) language apicall. | |||
</vip> | |||
==== deprecated ==== | ==== deprecated ==== | ||
Line 182: | Line 83: | ||
<vip>predicates | <vip>predicates | ||
oldFashioned : (string Arg) [deprecated("Use newFashion instead")].</vip> | oldFashioned : (string Arg) [deprecated("Use newFashion instead")].</vip> | ||
}} | }} | ||
Line 205: | Line 93: | ||
writef : (string Format [formatString], ...).</vip> | writef : (string Format [formatString], ...).</vip> | ||
}} | }} | ||
==== in ==== | ==== in ==== | ||
Line 236: | Line 100: | ||
{{Example| | {{Example| | ||
<vip>predicates | <vip>predicates | ||
pred : (string InputArg [in]). | pred : (string InputArg [in]).</vip> | ||
</vip> | |||
}} | }} | ||
==== inline ==== | ==== inline ==== | ||
Line 257: | Line 112: | ||
* inlining a fixed size string | * inlining a fixed size string | ||
* inlining a fixed number of bytes | * 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 struct field in another struct its data will be inlined instead of having a pointer to the struct | ||
Line 320: | Line 174: | ||
mark( | mark( | ||
integer Position, | integer Position, | ||
pointer Data [ | pointer Data [8] | ||
).</vip> | ).</vip> | ||
<vp>Data</vp> is pointer to 8 inlined bytes | <vp>Data</vp> is pointer to 8 inlined bytes | ||
Line 338: | Line 192: | ||
).</vip> | ).</vip> | ||
And <vp>Data</vp> will point to <vp>Data_1</vp>. | And <vp>Data</vp> will point to <vp>Data_1</vp>. | ||
}} | }} | ||
Line 374: | Line 213: | ||
<vip>predicates | <vip>predicates | ||
pred : (string OutputArg [out]).</vip> | pred : (string OutputArg [out]).</vip> | ||
}} | }} | ||
Line 422: | Line 236: | ||
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]]. | 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]]. | ||
==== | ==== retired ==== | ||
The declared entity is retired. The string literal describes how to migrate from it. The entity does not exist anymore. | |||
{{Example| | {{Example| | ||
<vip> | <vip>predicates | ||
veryOldFashioned : (string Arg) [retired("Use newFashion instead")].</vip> | |||
</vip> | |||
}} | }} | ||
==== 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| | {{Example| | ||
<vip>interface | <vip>interface myInterface | ||
[sealed] | |||
... | ... | ||
end interface | end interface myInterface | ||
class myClass : myInterface | |||
... | |||
end class myClass</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 members. | |||
{{Example| | {{Example| | ||
<vip>predicates | <vip>predicates | ||
seeminglyUnused : () [used].</vip> | |||
}} | }} | ||
==== default ==== | |||
{{Template:NonReleased}} | |||
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]]. | |||
==== retiredFunctor ==== | ==== retiredFunctor ==== | ||
{{Template:NonReleased}} | |||
Functor alternatives can be retired. | Functor alternatives can be retired. | ||
Line 481: | Line 335: | ||
See also [[Functor Domain Versioning]]. | See also [[Functor Domain Versioning]]. | ||
Revision as of 11:25, 4 January 2024
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
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.
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 exists, but usage will cause a warning. The entity will not exist in future versions of Visual Prolog. Valid for member declarations and scopes.
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).
predicates writef : (string Format [formatString], ...).
in
The argument is an input argument. Valid for a formal predicate argument.
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 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
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.
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:
domains mark = mark( integer Position, pointer Data [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.
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.
class classWithoutPublicConstructors : myInterface open core [noDefaultConstructor] ... end class classWithoutPublicConstructors
out
The argument is an output argument. Valid for a formal predicate argument.
predicates pred : (string OutputArg [out]).
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.
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.
retired
The declared entity is retired. The string literal describes how to migrate from it. The entity does not exist anymore.
predicates veryOldFashioned : (string Arg) [retired("Use newFashion instead")].
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.
interface myInterface [sealed] ... end interface myInterface class myClass : myInterface ... end class myClass
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.
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.
predicates seeminglyUnused : () [used].
default
Visual Prolog 11 preliminary documentation. This article contains preliminary documentation for the upcoming release |
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.
retiredFunctor
Visual Prolog 11 preliminary documentation. This article contains preliminary documentation for the upcoming release |
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.