From 9c44cfad7175ae9c68b244794d91981d73cc0e1d Mon Sep 17 00:00:00 2001 From: skl131313 Date: Sun, 31 Dec 2017 20:19:26 -0500 Subject: [PATCH 01/27] Add DIP for Enum and Function Parameter Attributes. --- DIPs/dip10ss.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 DIPs/dip10ss.md diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md new file mode 100644 index 000000000..34af90c57 --- /dev/null +++ b/DIPs/dip10ss.md @@ -0,0 +1,100 @@ +# Enum and Function Parameter Attributes + +| Field | Value | +|-----------------|-----------------------------------------------------------------| +| DIP: | 10ss | +| Review Count: | NA | +| Author(s): | @skl131313 | +| Status: | NA | + + +## Abstract + +Allow additional meta information (attributes) to be attached with enums and functions parameters, including built-in attributes such as `deprecated`. + +### Links + +[Does it require a DIP?](http://forum.dlang.org/thread/cltyrthdxkkfvuxqasqw@forum.dlang.org) + +## Rationale + +It is currently not possible to attach attributes to both enums and function parameters. This excludes a few features that can be used with almost any other symbol in D. Attributes and User Defined Attributes serve as a means to provide extra meta data for a symbol. What can be said for why attributes were included as a feature in D can also be said for why they should be extended to enums and function parameters. It is benefitial to provide extra meta data about a symbol that can be used at compile-time. + +## Description + +TBD + +## Existing Solutions + +Existing solutions exist only for UDAs, for an attribute such a `deprecated`, there is no existing solution to receive the desired effect. + +Apply UDA through parent symbol with additional information for which child it should be applied to: + +```D +@MyUda("feature0", "...") +enum SomeEnum +{ + feature0, + feature1, + feature2, +} + +@MyUda("param0", "...") +void foo(int param0) +{ +} + +``` + +This allows the desired UDA to be used and associated with the desired symbol. It introduces some duplication and the information stored in the UDA is separated from the rest of the information of the symbol. + + +### Examples + +Allowing to deprecate enums which should not be used anymore: + +```D +enum SomeEnum +{ + feature0, + feature1, + + deprecated("use feature0 or feature1 instead") + feature2, +} +``` + +Provide information on function parameters for use with scripting languages or other type evaluation: + +```D +enum ScriptType +{ + vehicle, + character, + scenery, +} + +// scripting language can now know that the index is of a specific type +// the scripting language not being aware that it is just an index +void someFunction(string name, @ScriptType.vehicle int vehicleIndex) +{ + // ... +} +``` + +Providing extra attributes that can be used to take advantage of knowledge known about the function parameters: + +```D + +extern(C) void fetch(@NonNull int* ptr) +{ + // ... +} +``` + +## Copyright & License + +Licensed under [Creative Commons Zero 1.0](https://creativecommons.org/publicdomain/zero/1.0/legalcode.txt) + + + From 65b80d984c4b1024c57a0936c3bbfb4375901aed Mon Sep 17 00:00:00 2001 From: skl131313 Date: Mon, 1 Jan 2018 19:04:08 -0500 Subject: [PATCH 02/27] Changes to wording and additional more concrete examples. --- DIPs/dip10ss.md | 134 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 112 insertions(+), 22 deletions(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 34af90c57..f94f66124 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -14,11 +14,15 @@ Allow additional meta information (attributes) to be attached with enums and fun ### Links -[Does it require a DIP?](http://forum.dlang.org/thread/cltyrthdxkkfvuxqasqw@forum.dlang.org) +[Preliminary discussion about Enum and Function Parameter Attributes on the NG](http://forum.dlang.org/thread/cltyrthdxkkfvuxqasqw@forum.dlang.org) ## Rationale -It is currently not possible to attach attributes to both enums and function parameters. This excludes a few features that can be used with almost any other symbol in D. Attributes and User Defined Attributes serve as a means to provide extra meta data for a symbol. What can be said for why attributes were included as a feature in D can also be said for why they should be extended to enums and function parameters. It is benefitial to provide extra meta data about a symbol that can be used at compile-time. +It is currently not possible to attach attributes to both enums and function parameters. This excludes a few features that can be used with almost any other symbol in D. + +Attributes and user-defined attributes (UDA) serve as a means to provide extra meta data for a symbol. What can be said for why attributes were included as a feature in D can also be said for why they should be extended to enums and function parameters. It is benefitial to provide extra meta data about a symbol that can be used at compile-time. + +The concept know as orthogonality of language features applies here. Attributes can be applied to almost every symbol in D. A user would expect them to also be applicable to enums and function parameters. ## Description @@ -26,8 +30,6 @@ TBD ## Existing Solutions -Existing solutions exist only for UDAs, for an attribute such a `deprecated`, there is no existing solution to receive the desired effect. - Apply UDA through parent symbol with additional information for which child it should be applied to: ```D @@ -43,24 +45,108 @@ enum SomeEnum void foo(int param0) { } - ``` This allows the desired UDA to be used and associated with the desired symbol. It introduces some duplication and the information stored in the UDA is separated from the rest of the information of the symbol. +Deprecation of an enum can be done by reimplementing an enum as a structure with static enums as follows: + +```D +enum SomeEnumImpl +{ + none = -1, + actualValue2 = 2, + actualValue3 = 3, +} + +public struct SomeEnum +{ + SomeEnumImpl x; + alias this x; + + deprecated("reason for deprecation") + static enum deprecatedValue0 = none; + + deprecated("reason for deprecation") + static enum deprecatedValue1 = none; +} +``` ### Examples -Allowing to deprecate enums which should not be used anymore: +Allowing to deprecate enums which should not be used anymore as seen [here](https://github.com/vibe-d/vibe.d/pull/1947/files): ```D +enum SomeEnumImpl +{ + none = -1, + actualValue2 = 2, + actualValue3 = 3, +} + +public struct SomeEnum +{ + SomeEnumImpl x; + alias this x; + + deprecated("reason for deprecation") + static enum deprecatedValue0 = SomeEnumImpl.none; + + deprecated("reason for deprecation") + static enum deprecatedValue1 = SomeEnumImpl.none; +} + +// becomes + enum SomeEnum { - feature0, - feature1, + none = -1, + deprecated("reason for deprecation") + deprecatedValue0 = none, + deprecated("reason for deprecation") + deprecatedValue1 = none, + actualValue2 = 2, + actualValue3, +} +``` - deprecated("use feature0 or feature1 instead") - feature2, +Providing extra attributes that can be used to take advantage of knowledge known about the function parameters: + +```D +extern(C) void fetch(@NonNull int* ptr) +{ +} +``` + +Examples of above from [vibe.d](https://github.com/vibe-d/vibe.d): + +```D +@body("user") +@errorDisplay +auto postUsers(User _user, string _error) +{ +} + +// becomes + +auto postUser(@body User user, @errors Errors errors) +{ +} + +// Another example: + +@path("/users/:id") +@queryParam("page") +@before!authenticate("user") +auto getUsers(string _id, int page, User user) +{ +} + +// becomes + +@path("/users/:id") +auto getUser(@urlParam string id, @queryParam int page, @auth User user) +{ } ``` @@ -74,27 +160,31 @@ enum ScriptType scenery, } -// scripting language can now know that the index is of a specific type -// the scripting language not being aware that it is just an index -void someFunction(string name, @ScriptType.vehicle int vehicleIndex) +struct ScriptParameter { - // ... + string name; + ScriptType type; } -``` -Providing extra attributes that can be used to take advantage of knowledge known about the function parameters: +@ScriptParameter("vehicleIndex", ScriptType.vehicle) +void someFunction(string name, int vehicleIndex) +{ +} -```D +// becomes -extern(C) void fetch(@NonNull int* ptr) +enum ScriptType +{ + vehicle, + character, + scenery, +} + +void someFunction(string name, @ScriptType.vehicle int vehicleIndex) { - // ... } ``` ## Copyright & License Licensed under [Creative Commons Zero 1.0](https://creativecommons.org/publicdomain/zero/1.0/legalcode.txt) - - - From b559df38c6fdfc4e7363f1b106294e941e945e2a Mon Sep 17 00:00:00 2001 From: skl131313 Date: Mon, 1 Jan 2018 19:12:35 -0500 Subject: [PATCH 03/27] Spelling and quotes. --- DIPs/dip10ss.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index f94f66124..53c833b15 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -22,7 +22,7 @@ It is currently not possible to attach attributes to both enums and function par Attributes and user-defined attributes (UDA) serve as a means to provide extra meta data for a symbol. What can be said for why attributes were included as a feature in D can also be said for why they should be extended to enums and function parameters. It is benefitial to provide extra meta data about a symbol that can be used at compile-time. -The concept know as orthogonality of language features applies here. Attributes can be applied to almost every symbol in D. A user would expect them to also be applicable to enums and function parameters. +The concept known as "orthogonality of language features" applies here. Attributes can be applied to almost every symbol in D. A user would expect them to also be applicable to enums and function parameters. ## Description From 3fc4d89fc420a6c50ba4286d1a2e0567615bc918 Mon Sep 17 00:00:00 2001 From: skl131313 Date: Mon, 1 Jan 2018 19:34:18 -0500 Subject: [PATCH 04/27] Add link to existing pull request. --- DIPs/dip10ss.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 53c833b15..d0e3e970a 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -4,7 +4,7 @@ |-----------------|-----------------------------------------------------------------| | DIP: | 10ss | | Review Count: | NA | -| Author(s): | @skl131313 | +| Author(s): | [skl131313](https://github.com/skl131313) | | Status: | NA | @@ -15,6 +15,7 @@ Allow additional meta information (attributes) to be attached with enums and fun ### Links [Preliminary discussion about Enum and Function Parameter Attributes on the NG](http://forum.dlang.org/thread/cltyrthdxkkfvuxqasqw@forum.dlang.org) +[Pull request implementing UDAs for function parameters](https://github.com/dlang/dmd/pull/4783/files) ## Rationale From 8de20adc089b991cfdf9a9a2cc245fbd3f61afd4 Mon Sep 17 00:00:00 2001 From: skl131313 Date: Mon, 1 Jan 2018 20:22:30 -0500 Subject: [PATCH 05/27] Fix formatting of links. --- DIPs/dip10ss.md | 1 + 1 file changed, 1 insertion(+) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index d0e3e970a..d66d846c3 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -15,6 +15,7 @@ Allow additional meta information (attributes) to be attached with enums and fun ### Links [Preliminary discussion about Enum and Function Parameter Attributes on the NG](http://forum.dlang.org/thread/cltyrthdxkkfvuxqasqw@forum.dlang.org) + [Pull request implementing UDAs for function parameters](https://github.com/dlang/dmd/pull/4783/files) ## Rationale From b59038f24f0b25bcb930c79907bb59b3a4ab86e7 Mon Sep 17 00:00:00 2001 From: skl131313 Date: Mon, 1 Jan 2018 21:05:49 -0500 Subject: [PATCH 06/27] Add grammar changes for enum attributes. --- DIPs/dip10ss.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index d66d846c3..4587f7b1d 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -28,7 +28,29 @@ The concept known as "orthogonality of language features" applies here. Attribut ## Description -TBD +Grammar changes for [Enum](https://dlang.org/spec/enum.html): + +``` +EnumMember: + Identifier + Identifier = AssignExpression + +// becomes ------------------------------------------- + +EnumAttribute: + DeprecatedAttribute + UserDefinedAttribute + +EnumAttributes: + EnumAttribute + EnumAttiribute EnumAttributes + +EnumMember: + Identifier + Identifier = AssignExpression + EnumAttributes Identifier + EnumAttributes Identifier = AssignExpression +``` ## Existing Solutions From b15c0198d86cb830648c39f60c9082018473819d Mon Sep 17 00:00:00 2001 From: skl131313 Date: Mon, 1 Jan 2018 21:56:17 -0500 Subject: [PATCH 07/27] Add function grammar changes. --- DIPs/dip10ss.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 4587f7b1d..9122a7193 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -52,6 +52,36 @@ EnumMember: EnumAttributes Identifier = AssignExpression ``` +Grammar change for [Function](https://dlang.org/spec/function.html): + +``` +Parameter: + InOut_opt BasicType Declarator + InOut_opt BasicType Declarator ... + InOut_opt BasicType Declarator = AssignExpression + InOut_opt Type + InOut_opt Type ... + +// becomes ----------------------------- + +ParameterAttribute: + UserDefinedAttribute + +ParameterAttributes: + ParameterAttribute + ParameterAttribute ParameterAttributes + +Parameter: + InOut_opt BasicType Declarator + InOut_opt BasicType Declarator ... + InOut_opt BasicType Declarator = AssignExpression + InOut_opt Type + InOut_opt Type ... + ParameterAttributes InOut_opt BasicType Declarator + ParameterAttributes InOut_opt BasicType Declarator = AssignExpression + ParameterAttributes InOut_opt Type +``` + ## Existing Solutions Apply UDA through parent symbol with additional information for which child it should be applied to: From a95041312895c8d19a72ba43e2c659d60dc8a5f8 Mon Sep 17 00:00:00 2001 From: skl131313 Date: Mon, 1 Jan 2018 22:06:18 -0500 Subject: [PATCH 08/27] Clarifcations in exiting solutions. --- DIPs/dip10ss.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 9122a7193..7c0786354 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -84,7 +84,7 @@ Parameter: ## Existing Solutions -Apply UDA through parent symbol with additional information for which child it should be applied to: +A current solution for applying an UDA to an enum or parameter is to use an UDA on the parent symbol with some additional information for which child element it should be applied to. This allows the desired UDA to be used and associated with the desired symbol. It introduces some duplication and the information stored in the UDA is separated from the rest of the information of the symbol. ```D @MyUda("feature0", "...") @@ -101,9 +101,7 @@ void foo(int param0) } ``` -This allows the desired UDA to be used and associated with the desired symbol. It introduces some duplication and the information stored in the UDA is separated from the rest of the information of the symbol. - -Deprecation of an enum can be done by reimplementing an enum as a structure with static enums as follows: +A solution for applying the `deprecation` attribute to an enum member can be done by reimplementing an enum as a structure with static enums. This allows the attribute to be placed with the desired enum member. While still allowing for any existing code that simply used an enum before hand to still work accordingly, as if the struct was an enum. ```D enum SomeEnumImpl @@ -113,7 +111,7 @@ enum SomeEnumImpl actualValue3 = 3, } -public struct SomeEnum +struct SomeEnum { SomeEnumImpl x; alias this x; From dd535cd29b0ed61c15ff1810d3fc6001ed23fae0 Mon Sep 17 00:00:00 2001 From: skl131313 Date: Mon, 1 Jan 2018 22:11:50 -0500 Subject: [PATCH 09/27] Some calrifications in examples. --- DIPs/dip10ss.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 7c0786354..b2044ee32 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -162,7 +162,7 @@ enum SomeEnum } ``` -Providing extra attributes that can be used to take advantage of knowledge known about the function parameters: +Providing extra attributes that can be used to take advantage of knowledge known about the function parameters. An example of this is `NonNull` as could be implemented in LDC2 through LLVM. More details [here](https://clang.llvm.org/docs/AttributeReference.html#nonnull). ```D extern(C) void fetch(@NonNull int* ptr) @@ -170,7 +170,7 @@ extern(C) void fetch(@NonNull int* ptr) } ``` -Examples of above from [vibe.d](https://github.com/vibe-d/vibe.d): +More examples of parameter attributes from [vibe.d](https://github.com/vibe-d/vibe.d): ```D @body("user") From 907fd540ee9f0e6646f254095b3478c900442907 Mon Sep 17 00:00:00 2001 From: skl131313 Date: Tue, 2 Jan 2018 18:26:41 -0500 Subject: [PATCH 10/27] Add link to new pull request. --- DIPs/dip10ss.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index b2044ee32..065e7288d 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -16,7 +16,9 @@ Allow additional meta information (attributes) to be attached with enums and fun [Preliminary discussion about Enum and Function Parameter Attributes on the NG](http://forum.dlang.org/thread/cltyrthdxkkfvuxqasqw@forum.dlang.org) -[Pull request implementing UDAs for function parameters](https://github.com/dlang/dmd/pull/4783/files) +[(New) Pull request implementing UDAs for function parameters](https://github.com/dlang/dmd/pull/7576) + +[(Old) Pull request implementing UDAs for function parameters](https://github.com/dlang/dmd/pull/4783/files) ## Rationale From 6183ef9f35603e554b5a8325e685d5be2e5d16ad Mon Sep 17 00:00:00 2001 From: skl131313 Date: Tue, 2 Jan 2018 21:31:49 -0500 Subject: [PATCH 11/27] Addition work for description. --- DIPs/dip10ss.md | 44 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 39 insertions(+), 5 deletions(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 065e7288d..c912b7e23 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -30,6 +30,40 @@ The concept known as "orthogonality of language features" applies here. Attribut ## Description +The changes made to D would be relatively minor. Most of the framework for attributes already exist and it would just be a matter of extending that into the respective symbols for enums and function parameters. + +The following syntaxes are being proposed to be accepted: + +```D +enum SomeEnum +{ + // attributes declared infront of enum value + @90 @MyUda deprecated("reason") someEnumValue0, + @91 @MyUda deprecated("reason") someEnumValue1 = 1, +} + +// attributes for enum values can be retrieved with __traits(getAttributes, ...) +static assert(__traits(getAttributes, SomeEnum.someEnumValue0)[0] == 90); +static assert(__traits(getAttributes, SomeEnum.someEnumValue1)[0] == 91); + +// for functions, attributes are allowed infront of function parameters +void someFunction(@93 @MyUda int someParameter) +{ + // can use __traits(getAttributes, ...) with the paramter from inside of function + static assert(__traits(getAttributes, someParamter)[0] == 93); +} + +void someExternalFunction() +{ + // attributes can be accessed for paramters by another function + // through existing functionality of __parameters + static if(is(typeof(someFunction) PT == __parameters)) + { + static assert(__traits(getAttributes, PT[0 .. 1]) == 93); + } +} +``` + Grammar changes for [Enum](https://dlang.org/spec/enum.html): ``` @@ -50,8 +84,8 @@ EnumAttributes: EnumMember: Identifier Identifier = AssignExpression - EnumAttributes Identifier - EnumAttributes Identifier = AssignExpression ++ EnumAttributes Identifier ++ EnumAttributes Identifier = AssignExpression ``` Grammar change for [Function](https://dlang.org/spec/function.html): @@ -79,9 +113,9 @@ Parameter: InOut_opt BasicType Declarator = AssignExpression InOut_opt Type InOut_opt Type ... - ParameterAttributes InOut_opt BasicType Declarator - ParameterAttributes InOut_opt BasicType Declarator = AssignExpression - ParameterAttributes InOut_opt Type ++ ParameterAttributes InOut_opt BasicType Declarator ++ ParameterAttributes InOut_opt BasicType Declarator = AssignExpression ++ ParameterAttributes InOut_opt Type ``` ## Existing Solutions From fbe730495ebc9c10db7b9ad59c7d6460eee832cc Mon Sep 17 00:00:00 2001 From: skl131313 Date: Wed, 3 Jan 2018 21:19:29 -0500 Subject: [PATCH 12/27] Corrections to sample code. --- DIPs/dip10ss.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index c912b7e23..5f950d47b 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -38,8 +38,8 @@ The following syntaxes are being proposed to be accepted: enum SomeEnum { // attributes declared infront of enum value - @90 @MyUda deprecated("reason") someEnumValue0, - @91 @MyUda deprecated("reason") someEnumValue1 = 1, + @(90) @MyUda deprecated("reason") someEnumValue0, + @(91) @MyUda deprecated("reason") someEnumValue1 = 1, } // attributes for enum values can be retrieved with __traits(getAttributes, ...) @@ -47,7 +47,7 @@ static assert(__traits(getAttributes, SomeEnum.someEnumValue0)[0] == 90); static assert(__traits(getAttributes, SomeEnum.someEnumValue1)[0] == 91); // for functions, attributes are allowed infront of function parameters -void someFunction(@93 @MyUda int someParameter) +void someFunction(@(93) @MyUda int someParameter) { // can use __traits(getAttributes, ...) with the paramter from inside of function static assert(__traits(getAttributes, someParamter)[0] == 93); From 01fd897e493c06d8919cdba408dfb31d922b5f1e Mon Sep 17 00:00:00 2001 From: skl131313 Date: Wed, 7 Mar 2018 23:00:19 -0500 Subject: [PATCH 13/27] Update layout to new template. --- DIPs/dip10ss.md | 75 +++++++++++++++++++++++++++---------------------- 1 file changed, 41 insertions(+), 34 deletions(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 5f950d47b..a98179beb 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -2,17 +2,17 @@ | Field | Value | |-----------------|-----------------------------------------------------------------| -| DIP: | 10ss | -| Review Count: | NA | -| Author(s): | [skl131313](https://github.com/skl131313) | -| Status: | NA | - +| DIP: | (number/id -- assigned by DIP Manager) | +| Review Count: | 0 (edited by DIP Manager) | +| Author: | [@skl131313](https://github.com/skl131313) | +| Implementation: | [(Partial) Function UDAS](https://github.com/dlang/dmd/pull/7576) | +| Status: | Will be set by the DIP manager (e.g. "Approved" or "Rejected") | ## Abstract Allow additional meta information (attributes) to be attached with enums and functions parameters, including built-in attributes such as `deprecated`. -### Links +### Reference [Preliminary discussion about Enum and Function Parameter Attributes on the NG](http://forum.dlang.org/thread/cltyrthdxkkfvuxqasqw@forum.dlang.org) @@ -20,6 +20,13 @@ Allow additional meta information (attributes) to be attached with enums and fun [(Old) Pull request implementing UDAs for function parameters](https://github.com/dlang/dmd/pull/4783/files) +## Contents +* [Rationale](#rationale) +* [Description](#description) +* [Breaking Changes and Deprecations](#breaking-changes-and-deprecations) +* [Acknowledgements](#acknowledgements) +* [Reviews](#reviews) + ## Rationale It is currently not possible to attach attributes to both enums and function parameters. This excludes a few features that can be used with almost any other symbol in D. @@ -66,20 +73,14 @@ void someExternalFunction() Grammar changes for [Enum](https://dlang.org/spec/enum.html): -``` -EnumMember: - Identifier - Identifier = AssignExpression - -// becomes ------------------------------------------- - -EnumAttribute: - DeprecatedAttribute - UserDefinedAttribute +```diff ++ EnumAttribute: ++ DeprecatedAttribute ++ UserDefinedAttribute -EnumAttributes: - EnumAttribute - EnumAttiribute EnumAttributes ++ EnumAttributes: ++ EnumAttribute ++ EnumAttiribute EnumAttributes EnumMember: Identifier @@ -90,22 +91,13 @@ EnumMember: Grammar change for [Function](https://dlang.org/spec/function.html): -``` -Parameter: - InOut_opt BasicType Declarator - InOut_opt BasicType Declarator ... - InOut_opt BasicType Declarator = AssignExpression - InOut_opt Type - InOut_opt Type ... - -// becomes ----------------------------- - -ParameterAttribute: - UserDefinedAttribute +```diff ++ ParameterAttribute: ++ UserDefinedAttribute -ParameterAttributes: - ParameterAttribute - ParameterAttribute ParameterAttributes ++ ParameterAttributes: ++ ParameterAttribute ++ ParameterAttribute ParameterAttributes Parameter: InOut_opt BasicType Declarator @@ -273,6 +265,21 @@ void someFunction(string name, @ScriptType.vehicle int vehicleIndex) } ``` +## Breaking Changes and Deprecations + +No breaking changes are to occur from including these features. + +## Acknowledgements + +* Todo + ## Copyright & License +Copyright (c) 2017 by the D Language Foundation + Licensed under [Creative Commons Zero 1.0](https://creativecommons.org/publicdomain/zero/1.0/legalcode.txt) + +## Reviews + +The DIP Manager will supplement this section with a summary of each review stage +of the DIP process beyond the Draft Review. From eb5cb5d210826740e9b807370e86bd53a49f9234 Mon Sep 17 00:00:00 2001 From: skl131313 Date: Wed, 7 Mar 2018 23:02:06 -0500 Subject: [PATCH 14/27] Refactor some sections. --- DIPs/dip10ss.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index a98179beb..69f88c087 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -23,8 +23,9 @@ Allow additional meta information (attributes) to be attached with enums and fun ## Contents * [Rationale](#rationale) * [Description](#description) +* [Existing Solutions](#existing-solutions) +* [Examples](#examples) * [Breaking Changes and Deprecations](#breaking-changes-and-deprecations) -* [Acknowledgements](#acknowledgements) * [Reviews](#reviews) ## Rationale @@ -269,9 +270,6 @@ void someFunction(string name, @ScriptType.vehicle int vehicleIndex) No breaking changes are to occur from including these features. -## Acknowledgements - -* Todo ## Copyright & License From 612350f439abda30d33140d62adaec370b4368c6 Mon Sep 17 00:00:00 2001 From: skl131313 Date: Wed, 7 Mar 2018 23:05:39 -0500 Subject: [PATCH 15/27] Minor change to Enum UDA existing solution. --- DIPs/dip10ss.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 69f88c087..3c3ae3a7f 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -117,6 +117,8 @@ A current solution for applying an UDA to an enum or parameter is to use an UDA ```D @MyUda("feature0", "...") +@MyUda("feature1", "...") +@MyUda("feature2", "...") enum SomeEnum { feature0, From c458df4ba457e926d634760bd1b1e76818761e31 Mon Sep 17 00:00:00 2001 From: skl131313 Date: Wed, 7 Mar 2018 23:07:13 -0500 Subject: [PATCH 16/27] Minsor style change for Enum deprecation example. --- DIPs/dip10ss.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 3c3ae3a7f..6a34f257b 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -184,12 +184,11 @@ public struct SomeEnum enum SomeEnum { none = -1, - deprecated("reason for deprecation") - deprecatedValue0 = none, - deprecated("reason for deprecation") - deprecatedValue1 = none, actualValue2 = 2, actualValue3, + + deprecated("reason for deprecation") deprecatedValue0 = none, + deprecated("reason for deprecation") deprecatedValue1 = none, } ``` From 35672aa5445999d9011376a8e77f4fd471bd95cc Mon Sep 17 00:00:00 2001 From: skl131313 Date: Wed, 21 Mar 2018 15:24:31 -0400 Subject: [PATCH 17/27] Fix example code for function UDA with __parameters. --- DIPs/dip10ss.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 6a34f257b..8a0b32ec8 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -67,7 +67,7 @@ void someExternalFunction() // through existing functionality of __parameters static if(is(typeof(someFunction) PT == __parameters)) { - static assert(__traits(getAttributes, PT[0 .. 1]) == 93); + static assert(__traits(getAttributes, PT[0 .. 1])[0] == 93); } } ``` From ad72631471ca9871f0594f7f6dfb5b583c3283dd Mon Sep 17 00:00:00 2001 From: skl131313 Date: Wed, 21 Mar 2018 15:28:02 -0400 Subject: [PATCH 18/27] Add enum pull request link. --- DIPs/dip10ss.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 8a0b32ec8..f486723b2 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -20,6 +20,8 @@ Allow additional meta information (attributes) to be attached with enums and fun [(Old) Pull request implementing UDAs for function parameters](https://github.com/dlang/dmd/pull/4783/files) +[Pull request implement UDAs for enums](https://github.com/dlang/dmd/pull/6161) + ## Contents * [Rationale](#rationale) * [Description](#description) From 7e20213e7a5d24278ecd6c54907b28ac92594ae6 Mon Sep 17 00:00:00 2001 From: skl131313 Date: Wed, 21 Mar 2018 15:40:44 -0400 Subject: [PATCH 19/27] Grammer and spelling. --- DIPs/dip10ss.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index f486723b2..fe468bb8e 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -10,7 +10,7 @@ ## Abstract -Allow additional meta information (attributes) to be attached with enums and functions parameters, including built-in attributes such as `deprecated`. +Allow additional meta information (attributes) to be attached to enums and functions parameters, including built-in attributes such as `deprecated`. ### Reference @@ -32,15 +32,15 @@ Allow additional meta information (attributes) to be attached with enums and fun ## Rationale -It is currently not possible to attach attributes to both enums and function parameters. This excludes a few features that can be used with almost any other symbol in D. +It is currently not possible to attach attributes to enums or function parameters. This excludes a few features that can be used with almost any other symbol in D. -Attributes and user-defined attributes (UDA) serve as a means to provide extra meta data for a symbol. What can be said for why attributes were included as a feature in D can also be said for why they should be extended to enums and function parameters. It is benefitial to provide extra meta data about a symbol that can be used at compile-time. +Attributes and user-defined attributes (UDA) serve as a means to provide extra metadata for a symbol. The reasoning for why attributes were included as a feature in D can be included as to why UDAs should be extended to enums and function parameters. It is benefitial to provide extra metadata about a symbol that can be used at compile-time. The concept known as "orthogonality of language features" applies here. Attributes can be applied to almost every symbol in D. A user would expect them to also be applicable to enums and function parameters. ## Description -The changes made to D would be relatively minor. Most of the framework for attributes already exist and it would just be a matter of extending that into the respective symbols for enums and function parameters. +The changes made to D would be relatively minor. Most of the framework for attributes already exists, and it would just be a matter of extending that to the respective symbols for enums and function parameters. The following syntaxes are being proposed to be accepted: @@ -115,7 +115,7 @@ Parameter: ## Existing Solutions -A current solution for applying an UDA to an enum or parameter is to use an UDA on the parent symbol with some additional information for which child element it should be applied to. This allows the desired UDA to be used and associated with the desired symbol. It introduces some duplication and the information stored in the UDA is separated from the rest of the information of the symbol. +A current solution for applying a UDA to an enum or parameter is to use an UDA on the parent symbol with some additional information for which child element it should be applied to. This allows the desired UDA to be used and associated with the desired symbol. It introduces some duplication and the information stored in the UDA is separated from the rest of the information of the symbol. ```D @MyUda("feature0", "...") @@ -134,7 +134,7 @@ void foo(int param0) } ``` -A solution for applying the `deprecation` attribute to an enum member can be done by reimplementing an enum as a structure with static enums. This allows the attribute to be placed with the desired enum member. While still allowing for any existing code that simply used an enum before hand to still work accordingly, as if the struct was an enum. +A solution for applying the `deprecation` attribute to an enum member can be done by reimplementing an enum as a structure with static enums. This allows the attribute to be placed with the desired enum member. While still allowing for any existing code that simply used an enum beforehand to still work accordingly, as if the struct was an enum. ```D enum SomeEnumImpl @@ -159,7 +159,7 @@ struct SomeEnum ### Examples -Allowing to deprecate enums which should not be used anymore as seen [here](https://github.com/vibe-d/vibe.d/pull/1947/files): +Deprecating individual enums value which should not be used anymore as seen [here](https://github.com/vibe-d/vibe.d/pull/1947/files): ```D enum SomeEnumImpl From 65735ac899fd4a517b43b890853503edfe7c6a79 Mon Sep 17 00:00:00 2001 From: skl131313 Date: Wed, 21 Mar 2018 15:41:06 -0400 Subject: [PATCH 20/27] Remove static from enum. --- DIPs/dip10ss.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index fe468bb8e..2d25abcb8 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -150,10 +150,10 @@ struct SomeEnum alias this x; deprecated("reason for deprecation") - static enum deprecatedValue0 = none; + enum deprecatedValue0 = none; deprecated("reason for deprecation") - static enum deprecatedValue1 = none; + enum deprecatedValue1 = none; } ``` @@ -175,10 +175,10 @@ public struct SomeEnum alias this x; deprecated("reason for deprecation") - static enum deprecatedValue0 = SomeEnumImpl.none; + enum deprecatedValue0 = SomeEnumImpl.none; deprecated("reason for deprecation") - static enum deprecatedValue1 = SomeEnumImpl.none; + enum deprecatedValue1 = SomeEnumImpl.none; } // becomes From dbd886331ee4d551fa78fcdc77ea6c7d02e2189b Mon Sep 17 00:00:00 2001 From: skl131313 Date: Wed, 21 Mar 2018 15:48:08 -0400 Subject: [PATCH 21/27] Change asbtract a bit. --- DIPs/dip10ss.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 2d25abcb8..2e75d113a 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -10,7 +10,7 @@ ## Abstract -Allow additional meta information (attributes) to be attached to enums and functions parameters, including built-in attributes such as `deprecated`. +Rationale for why additional meta information (attributes) should be allowed to be attached to enums and functions parameters, including built-in attributes such as `deprecated`. ### Reference From 9c3a8d028f6411ac8232d8cbe51e098442c567db Mon Sep 17 00:00:00 2001 From: skl131313 Date: Wed, 21 Mar 2018 16:09:53 -0400 Subject: [PATCH 22/27] Add link to implemention for Enum. --- DIPs/dip10ss.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 2e75d113a..3e320a90f 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -5,7 +5,7 @@ | DIP: | (number/id -- assigned by DIP Manager) | | Review Count: | 0 (edited by DIP Manager) | | Author: | [@skl131313](https://github.com/skl131313) | -| Implementation: | [(Partial) Function UDAS](https://github.com/dlang/dmd/pull/7576) | +| Implementation: | [Function UDAS](https://github.com/dlang/dmd/pull/7576) [Enum UDAs](https://github.com/dlang/dmd/pull/6161) | | Status: | Will be set by the DIP manager (e.g. "Approved" or "Rejected") | ## Abstract From d064e56538110d55c1e78e8e7ac96b4a1d8f310d Mon Sep 17 00:00:00 2001 From: skl131313 Date: Wed, 21 Mar 2018 16:10:48 -0400 Subject: [PATCH 23/27] Add backslash to separate links. --- DIPs/dip10ss.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 3e320a90f..b8a09606c 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -5,7 +5,7 @@ | DIP: | (number/id -- assigned by DIP Manager) | | Review Count: | 0 (edited by DIP Manager) | | Author: | [@skl131313](https://github.com/skl131313) | -| Implementation: | [Function UDAS](https://github.com/dlang/dmd/pull/7576) [Enum UDAs](https://github.com/dlang/dmd/pull/6161) | +| Implementation: | [Function UDAS](https://github.com/dlang/dmd/pull/7576) / [Enum UDAs](https://github.com/dlang/dmd/pull/6161) | | Status: | Will be set by the DIP manager (e.g. "Approved" or "Rejected") | ## Abstract From 4373d73a7d1ca47996aa36a00d01c8c4964790ab Mon Sep 17 00:00:00 2001 From: skl131313 Date: Wed, 21 Mar 2018 16:12:05 -0400 Subject: [PATCH 24/27] Fix capitalization of "UDAs" to match rest of style. --- DIPs/dip10ss.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index b8a09606c..1b0218e8c 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -5,7 +5,7 @@ | DIP: | (number/id -- assigned by DIP Manager) | | Review Count: | 0 (edited by DIP Manager) | | Author: | [@skl131313](https://github.com/skl131313) | -| Implementation: | [Function UDAS](https://github.com/dlang/dmd/pull/7576) / [Enum UDAs](https://github.com/dlang/dmd/pull/6161) | +| Implementation: | [Function UDAs](https://github.com/dlang/dmd/pull/7576) / [Enum UDAs](https://github.com/dlang/dmd/pull/6161) | | Status: | Will be set by the DIP manager (e.g. "Approved" or "Rejected") | ## Abstract From 61b1cd5becbb291329b8db4fbe55054a6a6896c2 Mon Sep 17 00:00:00 2001 From: skl131313 Date: Mon, 26 Mar 2018 20:45:51 -0400 Subject: [PATCH 25/27] Update abstract. --- DIPs/dip10ss.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 1b0218e8c..375b631a0 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -10,7 +10,9 @@ ## Abstract -Rationale for why additional meta information (attributes) should be allowed to be attached to enums and functions parameters, including built-in attributes such as `deprecated`. +User-defined attributes (UDA) serve as a means of adding additional compile time information to a symbol. This additional information can be used for various purposes in combination with the type system. D also has some built-in attributes such as `deprecated` which provide some additional functinality. In the case of `deprecated`, a message is displayed warning if a symbol that is marked with deprecated is used. + +D current allows UDAs/built-in attributes on most symbols, but there are some instances where they are currently prohibited, specifically for enums and function parameters. This proposal looks to make the change that would allow UDAs/built-in attributes to be attached to enums and functions paramters. ### Reference From 9038c6b3b64f5d8f9f08c89984977f817cc0e868 Mon Sep 17 00:00:00 2001 From: skl131313 Date: Mon, 2 Apr 2018 13:29:39 -0400 Subject: [PATCH 26/27] Use 10x better abstract. --- DIPs/dip10ss.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 375b631a0..2592e23c9 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -10,9 +10,9 @@ ## Abstract -User-defined attributes (UDA) serve as a means of adding additional compile time information to a symbol. This additional information can be used for various purposes in combination with the type system. D also has some built-in attributes such as `deprecated` which provide some additional functinality. In the case of `deprecated`, a message is displayed warning if a symbol that is marked with deprecated is used. +In D, attributes provide a means of attaching compile-time information to a symbol. Built-in attributes provide information to the compiler, User-Defined Attributes (UDAs) provide information to the programmer or tooling, and both are accessible through compile-time reflection. -D current allows UDAs/built-in attributes on most symbols, but there are some instances where they are currently prohibited, specifically for enums and function parameters. This proposal looks to make the change that would allow UDAs/built-in attributes to be attached to enums and functions paramters. +D currently prohibits the use of attributes on some types of symbols, specifically enums and function parameters. This document describes a proposal to allow UDAs and built-in attributes to be attached to enums and function parameters. ### Reference From 03e128322626b79b242a9d83026a4feb73e052ea Mon Sep 17 00:00:00 2001 From: skl131313 Date: Mon, 2 Apr 2018 13:53:56 -0400 Subject: [PATCH 27/27] Update rationale and remove code from existing solutions. --- DIPs/dip10ss.md | 29 +++-------------------------- 1 file changed, 3 insertions(+), 26 deletions(-) diff --git a/DIPs/dip10ss.md b/DIPs/dip10ss.md index 2592e23c9..ce130c197 100644 --- a/DIPs/dip10ss.md +++ b/DIPs/dip10ss.md @@ -34,11 +34,9 @@ D currently prohibits the use of attributes on some types of symbols, specifical ## Rationale -It is currently not possible to attach attributes to enums or function parameters. This excludes a few features that can be used with almost any other symbol in D. +Allowing attributes to be attached to function parameters and enums would enable current implementations to be simplified and result in cleaner, more easily readable code. Current workarounds involve attaching the attributes to the parent symbol instead, as such additional identifying information needs to be added to the attribute indicating which child the attribute belongs to. This makes it difficult to read as information pertaining to a symbol isn't located with it, instead you would need to look through the parent's attributes. -Attributes and user-defined attributes (UDA) serve as a means to provide extra metadata for a symbol. The reasoning for why attributes were included as a feature in D can be included as to why UDAs should be extended to enums and function parameters. It is benefitial to provide extra metadata about a symbol that can be used at compile-time. - -The concept known as "orthogonality of language features" applies here. Attributes can be applied to almost every symbol in D. A user would expect them to also be applicable to enums and function parameters. +The concept known as "orthogonality of language features" can be said to apply to this proposal. Attributes can be applied to almost every symbol in D, a user would expect them to also be applicable to enums and function parameters. ## Description @@ -136,28 +134,7 @@ void foo(int param0) } ``` -A solution for applying the `deprecation` attribute to an enum member can be done by reimplementing an enum as a structure with static enums. This allows the attribute to be placed with the desired enum member. While still allowing for any existing code that simply used an enum beforehand to still work accordingly, as if the struct was an enum. - -```D -enum SomeEnumImpl -{ - none = -1, - actualValue2 = 2, - actualValue3 = 3, -} - -struct SomeEnum -{ - SomeEnumImpl x; - alias this x; - - deprecated("reason for deprecation") - enum deprecatedValue0 = none; - - deprecated("reason for deprecation") - enum deprecatedValue1 = none; -} -``` +A solution for applying the `deprecation` attribute to an enum member can be done by reimplementing an enum as a structure with static enums. This allows the attribute to be placed with the desired enum member. While still allowing for any existing code that simply used an enum beforehand to still work accordingly, as if the struct was an enum. An example of this workaround can be seen in the [Examples](#examples) section, with the corresponding solution if this proposal was implemented. ### Examples