Custom Attributes: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		Custom Attributes currently allow you to decorate type definitions and published properties of classes with additional metadata that can be queried using RTTI (runtime type information).
2	2
3	3		Currently (as of October 2020) the feature is available only in FPC trunk (aka 3.3.1)
4	4
5	5		## What can attributes be used for?
6	6
7	7		An attribute is used to associate specific metadata with a class. For example you can use an attribute to mark a class with the name of its corresponding database table, or to annotate a web service class with a string identifying its base path.
8	8
9	9		## How are attributes declared?
10	10
11	11		Attributes are simply classes that descend from the new System type TCustomAttribute. The constructors of such TCustomAttribute descendants are the most important feature to implement since they are used to pass additional parameters to the attribute (such as the associated database table name, or the base path in the above examples).
12	12
13	13		Important: If you want to use your attribute type without any arguments then you must declare a parameterless constructor yourself as the one of TCustomAttribute is private.
14	14
15	15		## How are attributes used?
16	16
17	17		Attributes are bound to a type or property by specifying at least one attribute clause ahead of the type or property. For a type the attribute is specified in the type definition (such as a class, record, or enum declaration) or in a unique type redeclaration (e.g. "TLongInt = type LongInt"). Mere type renames (e.g. "TLongInt = LongInt") are not allowed.
18	18
19	19		Attribute clauses are only available if the new modeswitch PREFIXEDATTRIBUTES is set, which is the default in mode Delphi and DelphiUnicode.
20	20
21	21		The syntax of an attribute clause is as follows:
22	22
23		-	~~`ATTRIBUTECLAUSE::='[' ATTRIBUTELIST ']'`\~~
24		-	~~`ATTRIBUTELIST::=ATTRIBUTE [, ATTRIBUTELIST ]`\~~
25		-	~~`ATTRIBUTE::=IDENTIFIER [ ( PARAMLIST ) ]`\~~
26		-	~~`PARAMLIST::=CONSTEXPR [, PARAMLIST ]`~~
	23	+	``` pascal
	24	+	ATTRIBUTECLAUSE::='[' ATTRIBUTELIST ']'
	25	+	ATTRIBUTELIST::=ATTRIBUTE [, ATTRIBUTELIST ]
	26	+	ATTRIBUTE::=IDENTIFIER [ ( PARAMLIST ) ]
	27	+	PARAMLIST::=CONSTEXPR [, PARAMLIST ]
	28	+	```
27	29
28	30		The IDENTIFIER is the name of the attribute class. If you name the attribute class to end with "Attribute" (the case of the "attribute" suffix is immaterial) then the name may be used subsequently without the "Attribute" suffix. So TMyAttribute and TMy are equivalent alternatives in the following example:
29	31
30	32		```delphi
31	33
32	34		program tcustomattr;
33	35
34	36		{$mode objfpc}{$H+}
35	37		{$modeswitch prefixedattributes}
36	38
37	39		type
38	40		TMyAttribute = class(TCustomAttribute)
39	41		constructor Create;
40	42		constructor Create(aArg: String);
41	43		constructor Create(aArg: TGUID);
42	44		constructor Create(aArg: LongInt);
43	45		end;
44	46
45	47		{$M+}
46	48		[TMyAttribute]
47	49		TTestClass = class
48	50		private
49	51		fTest: LongInt;
50	52		published
51	53		[TMyAttribute('Test')]
52	54		property Test: LongInt read fTest;
53	55		end;
54	56		{$M-}
55	57
56	58		[TMyAttribute(1234)]
57	59		[TMy('Hello World')]
58	60		TTestEnum = (
59	61		teOne,
60	62		teTwo
61	63		);
62	64
63	65		[TMyAttribute(IInterface), TMy(42)]
64	66		TLongInt = type LongInt;
65	67
66	68		constructor TMyAttribute.Create;
67	69		begin
68	70		end;
69	71
70	72		constructor TMyAttribute.Create(aArg: String);
71	73		begin
72	74		end;
73	75
74	76		constructor TMyAttribute.Create(aArg: LongInt);
75	77		begin
76	78		end;
77	79
78	80		constructor TMyAttribute.Create(aArg: TGUID);
79	81		begin
80	82		end;
81	83
82	84		begin
83	85
84	86		end.
85	87		```
86	88
87	89		### Querying attributes
88	90
89	91		Attributes can be accessed by both the TypInfo and Rtti units.
90	92
91	93		For the TypInfo unit the ways to access attributes are as follows:
92	94
93	95		For types:
94	96
95	97		- use the AttributesTable field in TTypeData
96	98		- use GetAttributeTable on a PTypeInfo
97	99		- use GetAttribute on the attribute table together with an index to get a TCustomAttribute instance
98	100
99	101		For properties:
100	102
101	103		- use the AttributesTable of TPropInfo
102	104		- use GetAttribute on the attribute table together with an index to get a TCustomAttribute instance
103	105		- use GetPropAttribute on the PPropInfo together with an index to get a TCustomAttribute instance
104	106
105	107		For the Rtti unit the ways to access attributes are as follows:
106	108
107	109		For types:
108	110
109	111		- use GetAttributes on the TRttiType of the type in question
110	112
111	113		For properties:
112	114
113	115		- use GetAttributes on the TRttiProperty of the property in question
114	116
115	117		## The attributes feature's compatibility with Delphi
116	118
117	119		The feature itself is Delphi compatible with the proviso that FPC is much more unforgiving regarding unbound properties. If the attribute class is not known or the attribute clauses are not bound to a valid type or property the compiler will generate an error.
118	120
119	121		FPC's RTTI is not considered Delphi compatible. However it covers the same functionality. In contrast to Delphi (which uses Invoke to create the attribute instance) FPC uses a constructor function. FPC's implementation has the advantage of working on systems that don't have full Invoke support.
120	122
121	123		Additionally using the PREFIXEDATTRIBUTES modeswitch disables the directive clauses for functions, methods and procedure/method types. The following is not allowed any more with the PREFIXEDATTRIBUTES modeswitch enabled:
122	124
123	125		```delphi
124	126		procedure Test; [cdecl];
125	127		begin
126	128		end;
127	129		```
128	130
129	131		## Complete example
130	132
131	133		```Delphi
132	134		program testattributes;
133	135		{
134	136		This is a simple example on how to use custom attributes.
135	137		The class uses a custom attribute to retrieve a static date
136	138		at program start-up. This is just for the purpose of demo.
137	139		This demo's:
138	140		- Creation
139	141		- Decoration
140	142		- Retrieval
141	143		}
142	144
143	145		{$mode delphi}{$H+}{$M+}
144	146		{$warn 5079 off} { turn warning experimental off }
145	147		uses
146	148		sysutils, typinfo, rtti, classes;
147	149
148	150		type
149	151		{A custom attribute to decorate a class with a certain date }
150	152		ADateTimeAttribute = class(TCustomAttribute)
151	153		private
152	154		FArg:TDateTime;
153	155		public
154	156		{ Just to show a Custom Attribute can have mutiple constructors }
155	157		constructor Create(const aArg: TDateTime);overload;
156	158		{ We can use the predefined %DATE% compiler include
157	159		In the context of a custom attribute we need a
158	160		constant expression for the default parameter }
159	161		constructor Create(const aArg: String = {$I %DATE%});overload;
160	162		published
161	163		property Date:TDateTime read Farg;
162	164		end;
163	165
164	166		{ A datetime class that is decorated with our custom attribute }
165	167		{ Note you can leave out 'Attribute', the compiler resolves it }
166	168		{ [ADateTime(21237.0)] uses first constructor,displays some date in 1958 }
167	169
168	170		{This calls the second constructor }
169	171		[ADateTime]
170	172		TMyDateTimeClass = class
171	173		private
172	174		FDateTime:TDateTime;
173	175		public
174	176		constructor create;
175	177		published
176	178		[ADateTime]
177	179		property Day:TDateTime read FDatetime write FdateTime;
178	180		end;
179	181
180	182		constructor ADateTimeAttribute.Create(const aArg: TDateTime);
181	183		begin
182	184		FArg := aArg;
183	185		end;
184	186
185	187		constructor ADateTimeAttribute.Create(const aArg: string );
186	188		var
187	189		MySettings:Tformatsettings;
188	190		begin
189	191		{ set up the date format according to how
190	192		the compiler formats %DATE% include }
191	193		MySettings :=DefaultFormatSettings;
192	194		MySettings.ShortDateFormat:='yyyymmdd';
193	195		MySettings.DateSeparator :='/';
194	196		{ Now convert }
195	197		FArg := StrToDateTime(aArg, MySettings);
196	198		end;
197	199
198	200		{ We query the rtti to set the value }
199	201		constructor TMyDateTimeClass.Create;
200	202		var
201	203		Context : TRttiContext;
202	204		AType : TRttiType;
203	205		Attribute : TCustomAttribute;
204	206		begin
205	207		inherited;
206	208		Context := TRttiContext.Create;
207	209		try
208	210		AType := Context.GetType(typeinfo(TMyDateTimeClass));
209	211		for Attribute in AType.GetAttributes do begin
210	212		if Attribute is ADateTimeAttribute then
211	213		FDateTime := ADateTimeAttribute(Attribute).Date;
212	214		end;
213	215		finally
214	216		Context.Free
215	217		end;
216	218		end;
217	219
218	220
219	221		var
220	222		Test:TMyDateTimeClass;
221	223		begin
222	224		Test := TMyDateTimeClass.Create;
223	225		try
224	226		writeln('Compile date is :',DateTimeToStr(Test.Day));
225	227		finally
226	228		test.free;
227	229		end;
228	230		end.
229	231		```
230	232
231	233		## See Also
232	234
233	235		- [[FPC New Features Trunk]]
234	236		- <http://docwiki.embarcadero.com/RADStudio/XE6/en/Overview_of_Attributes> - Delphi Attributes reference
235	237		- <http://delphi.about.com/od/oopindelphi/a/delphi-attributes-understanding-using-attributes-in-delphi.htm> Delphi Tutorial on property attributes
236	238
237	239		---
238	240		From the Free Pascal wiki, page "Custom Attributes", as it stood on 2022-12-30 after a change by Zoltanleo, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
239	241		Category: FPC

Back to history