Recent changes to Attributes

Attributes modified by Will Pittenger

Will Pittenger — Sun, 16 Feb 2014 10:05:08 -0000

--- v7
+++ v8
@@ -66,6 +66,7 @@
 When you apply an attribute to something, use the syntax below.  Note the "Attribute" part of the attribute's name is missing.  The parser should append that automatically.  This syntax is for everything but data members and parameters.  It  also assumes the Attribute doesn't need parameters.

 ~~~~
+:::text
 @[AttributeName]
 'declare something
 ~~~~
@@ -73,6 +74,7 @@
 The reason for the combination of @ and \[\] should be clear shortly.  Below is the syntax for data members and parameters.  This time, the attribute goes immediately before the member/parameter name.

 ~~~~
+:::text
 var String @[AttributeName] strValue
 var @[AttribueName] s$
 var ref int @[AttributeName] myInt
@@ -83,6 +85,7 @@
 If you need to apply several attributes, just use them one after the other, on the same line if needed.

 ~~~~
+:::text
 var String @[Attribute1]@[Attribute2] myString
 ~~~~

@@ -91,6 +94,7 @@
 Attributes that require parameters really aren't that much different from those that don't require parameters.  Below is a sample of code that declares such an attribute and then applies it to a member.

 ~~~~
+:::text
 class MyClass
   class CustomAttribute
     constructor var String param
@@ -105,6 +109,7 @@
 Take a look at the three lines of code below.

 ~~~~
+:::text
 command Sample1 var [AttributeName] s$ ' The parser might see the attribute as an optional section
 command Sample2 var @AttributeName s$ ' Not optional, but where does this attribute call end?
 command Sample3 var @[AttributesName] s$ ' Correct

Attributes modified by Will Pittenger

Will Pittenger — Sun, 16 Feb 2014 10:04:26 -0000

--- v6
+++ v7
@@ -40,6 +40,7 @@
 Attributes in ASIL all derive from the class Attribute.  The compiler should require attribute classes to end with "Attribute".  You specify what the attribute can be applied to by passing a combination of values from the IdentifierTypes enum inside Attribute to the base class.  Using an attribute calls the attribute's constructor.  That constructor is just a normal constructor that can have any syntax needed.

 ~~~~
+:::text
 class Attribute
   ' Not a complete listing of the class, but showing the IdentifierTypes enum

Attributes modified by Will Pittenger

Will Pittenger — Fri, 14 Feb 2014 04:14:22 -0000

--- v5
+++ v6
@@ -41,7 +41,7 @@

 ~~~~
 class Attribute
-  ' Note complete listing of the class, but showing the IdentifierTypes enum
+  ' Not a complete listing of the class, but showing the IdentifierTypes enum

   @[CombinableEnum]
   enum IdentifierType

Attributes modified by Will Pittenger

Will Pittenger — Fri, 14 Feb 2014 04:12:13 -0000

--- v4
+++ v5
@@ -2,38 +2,38 @@

 Overview
 --------
-.NET attributes and Java annotations serve similar purposes.  However, .NET's attribute system is more powerful.  Java annotations can't take parameters.  They're implemented as a simple interface.  Attributes are actual classes which can take parameters.  Java has very few annotations while .NET has an extensive attribute ecosystem.  Hence, ASIL follows the .NET system with attributes.
+.NET attributes and Java annotations serve similar purposes.  However, .NET's attribute system is more powerful.  Java annotations just static data structures while .NET attributes are actual classes.  Java has very few annotations while .NET has an extensive attribute ecosystem.  Hence, ASIL follows the .NET system with attributes.

 Like in .NET, attributes can be applied to most identifiers when they are declared.  .NET allows attribute classes to specify restrictions on which types of identifiers the attribute being declared can applied to.  ASIL does the same.  The table below lists what identifier types attributes in general can be applied to.

 Identifier type | Can have attributes | Details
 ----------------|---------------------|--------
-[**conditional**] variable | ✗ | These only exist at compile-time
+**[conditional](keywords-conditional)** variable | ✗ | These only exist at compile-time
 constant member | ✗ | These also exist at compiler-type only, at least as a named constant
 custom keyword | ✗ | 
-[**namespace**] | ✗ |
+**[namespace](keywords-namespace)** | ✗ |
 local variable | ✗ | If you need to pass it to a procedure that needs attributes, put them on the parameter of the procedure
-[**creator**] | ✗ |
-[**destructor**] | ✗ |
-global variable (DASIL only) | ✗ |
+**[creator](keywords-creator)** | ✗ |
+**[destructor](keywords-destructor)** | ✗ |
+global variable ([DASIL](Derivatives-DASIL) only) | ✗ |
 primitve-based enum | ✓ | In fact, use an attribute to direct the compiler to allow values of your type to be combined
 entry inside a primitive-based enum | ✓ |
-[**struct**] | ✓ |
-[**interface**] | ✓ |
-[**class**] | ✓ |
+**[struct](keywords-struct)** | ✓ |
+**[interface](keywords-interface)** | ✓ |
+**[class](keywords-class)** | ✓ |
 struct-based enum | ✓ |
 entry inside a struct-based enum | ✓ | These are just instances of the type
-global procedure (DASIL only) | ✓ |
+global procedure ([DASIL(Derivatives-DASIL) only) | ✓ |
 data member | ✓ |
-[**constructor**] | ✓ |
-[**command**] | ✓ |
-[**function**] | ✓ |
+**[constructor](keywords-constructor)** | ✓ |
+**[command](keywords-command)** | ✓ |
+**[function](keywords-function)** | ✓ |
 complex statement | ✓ |
-[**property**] | ✓ |
-accessor of a [**property**] | ✓ |
-[**delegate**] | ✓ |
-[**event**] | ✓ |
-parameter to procedure or [**property**] | ✓ | Apply the attribute immediately before the parameter's identifier
+**[property](keywords-property)** | ✓ |
+accessor of a **[property](keywords-property)** | ✓ |
+**[delegate](keywords-delegate)** | ✓ |
+**[event](keywords-event)** | ✓ |
+parameter to procedure or **[property](keywords-property)** | ✓ | Apply the attribute immediately before the parameter's identifier

 Declaring custom attribute types
 --------------------------------
@@ -47,7 +47,7 @@
   enum IdentifierType
     @enum
     @struct
-    enumValue
+    enumStruct
     @interface
     @class
     structBasedEnum
@@ -58,7 +58,7 @@
     dataMember ' includes values inside a struct-based enum type
 ~~~~

-Note: You saw mention of the CombinableEnumAttribute type in the discussion on [Enums].
+Note: You saw mention of the CombinableEnumAttribute type in the discussion on [Enums].  It's an attribute class that passes Identifier.@enum to it's base class constructor.

 Using simple attributes
 -----------------------
@@ -74,7 +74,7 @@
 ~~~~
 var String @[AttributeName] strValue
 var @[AttribueName] s$
-var & int @[AttributeName] myInt
+var ref int @[AttributeName] myInt
 ~~~~

 Applying  multiple attributes

Attributes modified by Will Pittenger

Will Pittenger — Sun, 09 Feb 2014 03:10:13 -0000

--- v3
+++ v4
@@ -58,7 +58,7 @@
     dataMember ' includes values inside a struct-based enum type
 ~~~~

-Note: You saw usage of the CombinableEnumAttribute type in the discussion on [Enums].
+Note: You saw mention of the CombinableEnumAttribute type in the discussion on [Enums].

 Using simple attributes
 -----------------------

Attributes modified by Will Pittenger

Will Pittenger — Sun, 09 Feb 2014 03:08:25 -0000

--- v2
+++ v3
@@ -84,3 +84,29 @@
 ~~~~
 var String @[Attribute1]@[Attribute2] myString
 ~~~~
+
+Attributes that take parameters
+-------------------------------
+Attributes that require parameters really aren't that much different from those that don't require parameters.  Below is a sample of code that declares such an attribute and then applies it to a member.
+
+~~~~
+class MyClass
+  class CustomAttribute
+    constructor var String param
+      base IdentifierType.dataMember
+      'Do something with the param
+
+  var String @[Custom "this is a parameter for an attribute"] myString
+~~~~
+
+Why the strange syntax?
+-----------------------
+Take a look at the three lines of code below.
+
+~~~~
+command Sample1 var [AttributeName] s$ ' The parser might see the attribute as an optional section
+command Sample2 var @AttributeName s$ ' Not optional, but where does this attribute call end?
+command Sample3 var @[AttributesName] s$ ' Correct
+~~~~
+
+ASIL needs the brackets to be combined with the at sign to clarify what's needed.

Attributes modified by Will Pittenger

Will Pittenger — Sun, 09 Feb 2014 02:46:06 -0000

--- v1
+++ v2
@@ -1,3 +1,7 @@
+[TOC]
+
+Overview
+--------
 .NET attributes and Java annotations serve similar purposes.  However, .NET's attribute system is more powerful.  Java annotations can't take parameters.  They're implemented as a simple interface.  Attributes are actual classes which can take parameters.  Java has very few annotations while .NET has an extensive attribute ecosystem.  Hence, ASIL follows the .NET system with attributes.

 Like in .NET, attributes can be applied to most identifiers when they are declared.  .NET allows attribute classes to specify restrictions on which types of identifiers the attribute being declared can applied to.  ASIL does the same.  The table below lists what identifier types attributes in general can be applied to.
@@ -11,6 +15,7 @@
 local variable | ✗ | If you need to pass it to a procedure that needs attributes, put them on the parameter of the procedure
 [**creator**] | ✗ |
 [**destructor**] | ✗ |
+global variable (DASIL only) | ✗ |
 primitve-based enum | ✓ | In fact, use an attribute to direct the compiler to allow values of your type to be combined
 entry inside a primitive-based enum | ✓ |
 [**struct**] | ✓ |
@@ -18,7 +23,6 @@
 [**class**] | ✓ |
 struct-based enum | ✓ |
 entry inside a struct-based enum | ✓ | These are just instances of the type
-global variable (DASIL only) | ✓ |
 global procedure (DASIL only) | ✓ |
 data member | ✓ |
 [**constructor**] | ✓ |
@@ -29,4 +33,54 @@
 accessor of a [**property**] | ✓ |
 [**delegate**] | ✓ |
 [**event**] | ✓ |
+parameter to procedure or [**property**] | ✓ | Apply the attribute immediately before the parameter's identifier

+Declaring custom attribute types
+--------------------------------
+Attributes in ASIL all derive from the class Attribute.  The compiler should require attribute classes to end with "Attribute".  You specify what the attribute can be applied to by passing a combination of values from the IdentifierTypes enum inside Attribute to the base class.  Using an attribute calls the attribute's constructor.  That constructor is just a normal constructor that can have any syntax needed.
+
+~~~~
+class Attribute
+  ' Note complete listing of the class, but showing the IdentifierTypes enum
+
+  @[CombinableEnum]
+  enum IdentifierType
+    @enum
+    @struct
+    enumValue
+    @interface
+    @class
+    structBasedEnum
+    @procedure
+    @parameter
+    @property
+    @constructor
+    dataMember ' includes values inside a struct-based enum type
+~~~~
+
+Note: You saw usage of the CombinableEnumAttribute type in the discussion on [Enums].
+
+Using simple attributes
+-----------------------
+When you apply an attribute to something, use the syntax below.  Note the "Attribute" part of the attribute's name is missing.  The parser should append that automatically.  This syntax is for everything but data members and parameters.  It  also assumes the Attribute doesn't need parameters.
+
+~~~~
+@[AttributeName]
+'declare something
+~~~~
+
+The reason for the combination of @ and \[\] should be clear shortly.  Below is the syntax for data members and parameters.  This time, the attribute goes immediately before the member/parameter name.
+
+~~~~
+var String @[AttributeName] strValue
+var @[AttribueName] s$
+var & int @[AttributeName] myInt
+~~~~
+
+Applying  multiple attributes
+-----------------------------
+If you need to apply several attributes, just use them one after the other, on the same line if needed.
+
+~~~~
+var String @[Attribute1]@[Attribute2] myString
+~~~~

Attributes modified by Will Pittenger

Will Pittenger — Sun, 09 Feb 2014 02:07:59 -0000

.NET attributes and Java annotations serve similar purposes. However, .NET's attribute system is more powerful. Java annotations can't take parameters. They're implemented as a simple interface. Attributes are actual classes which can take parameters. Java has very few annotations while .NET has an extensive attribute ecosystem. Hence, ASIL follows the .NET system with attributes.

Like in .NET, attributes can be applied to most identifiers when they are declared. .NET allows attribute classes to specify restrictions on which types of identifiers the attribute being declared can applied to. ASIL does the same. The table below lists what identifier types attributes in general can be applied to.

Identifier type	Can have attributes	Details
[conditional] variable	✗	These only exist at compile-time
constant member	✗	These also exist at compiler-type only, at least as a named constant
custom keyword	✗
[namespace]	✗
local variable	✗	If you need to pass it to a procedure that needs attributes, put them on the parameter of the procedure
[creator]	✗
[destructor]	✗
primitve-based enum	✓	In fact, use an attribute to direct the compiler to allow values of your type to be combined
entry inside a primitive-based enum	✓
[struct]	✓
[interface]	✓
[class]	✓
struct-based enum	✓
entry inside a struct-based enum	✓	These are just instances of the type
global variable (DASIL only)	✓
global procedure (DASIL only)	✓
data member	✓
[constructor]	✓
[command]	✓
[function]	✓
complex statement	✓
[property]	✓
accessor of a [property]	✓
[delegate]	✓
[event]	✓