From 72864c36d9292ffc29ca3d6c71da4bf29e86c7fb Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Thu, 9 May 2024 10:39:16 -0400 Subject: [PATCH 1/2] Port text from #700 The first commit ports in the text from #700 substantially without change. The only editorial change is to move the clause on "Nullable directives" in lexical-structure before the clause on Pragma directives. In addition, it fixes build warnings --- standard/basic-concepts.md | 10 ++--- standard/lexical-structure.md | 40 ++++++++++++++++++- .../standalone-console/Project.csproj | 2 +- 3 files changed, 44 insertions(+), 8 deletions(-) diff --git a/standard/basic-concepts.md b/standard/basic-concepts.md index a09db7b87..eaa2ca857 100644 --- a/standard/basic-concepts.md +++ b/standard/basic-concepts.md @@ -1024,7 +1024,7 @@ The behavior of the garbage collector can be controlled, to some degree, via sta > { > static void Main() > { -> B b = new B(new A()); +> B? b = new B(new A()); > b = null; > GC.Collect(); > GC.WaitForPendingFinalizers(); @@ -1069,19 +1069,19 @@ The behavior of the garbage collector can be controlled, to some degree, via sta > > class B > { -> public A Ref; +> public A? Ref; > > ~B() > { > Console.WriteLine("Finalize instance of B"); -> Ref.F(); +> Ref?.F(); > } > } > > class Test > { -> public static A RefA; -> public static B RefB; +> public static A? RefA; +> public static B? RefB; > > static void Main() > { diff --git a/standard/lexical-structure.md b/standard/lexical-structure.md index 7798388a1..590b4cddc 100644 --- a/standard/lexical-structure.md +++ b/standard/lexical-structure.md @@ -1026,7 +1026,7 @@ right_shift_assignment ### 6.5.1 General -The pre-processing directives provide the ability to conditionally skip sections of compilation units, to report error and warning conditions, and to delineate distinct regions of source code. +The pre-processing directives provide the ability to conditionally skip sections of compilation units, to report error and warning conditions, to delineate distinct regions of source code, and to set the nullable context. > *Note*: The term “pre-processing directives” is used only for consistency with the C and C++ programming languages. In C#, there is no separate pre-processing step; pre-processing directives are processed as part of the lexical analysis phase. *end note* @@ -1042,6 +1042,7 @@ fragment PP_Kind | PP_Diagnostic | PP_Region | PP_Pragma + | PP_Nullable ; // Only recognised at the beginning of a line @@ -1078,10 +1079,11 @@ The following pre-processing directives are available: - `#error`, which is used to issue errors ([§6.5.6](lexical-structure.md#656-diagnostic-directives)). - `#region` and `#endregion`, which are used to explicitly mark sections of source code ([§6.5.7](lexical-structure.md#657-region-directives)). - `#pragma`, which is used to specify optional contextual information to a compiler ([§6.5.9](lexical-structure.md#659-pragma-directives)). +- `#nullable`, which is used to specify the nullable context (§Nullable-Directives). A pre-processing directive always occupies a separate line of source code and always begins with a `#` character and a pre-processing directive name. White space may occur before the `#` character and between the `#` character and the directive name. -A source line containing a `#define`, `#undef`, `#if`, `#elif`, `#else`, `#endif`, `#line`, or `#endregion` directive can end with a single-line comment. Delimited comments (the `/* */` style of comments) are not permitted on source lines containing pre-processing directives. +A source line containing a `#define`, `#undef`, `#if`, `#elif`, `#else`, `#endif`, `#line`, `#endregion`, or `#nullable` directive can end with a single-line comment. Delimited comments (the `/* */` style of comments) are not permitted on source lines containing pre-processing directives. Pre-processing directives are not part of the syntactic grammar of C#. However, pre-processing directives can be used to include or exclude sequences of tokens and can in that way affect the meaning of a C# program. @@ -1507,6 +1509,40 @@ A `#line hidden` directive has no effect on the compilation unit and line number > *Note*: Although a *PP_Compilation_Unit_Name* might contain text that looks like an escape sequence, such text is not an escape sequence; in this context a ‘`\`’ character simply designates an ordinary backslash character. *end note* +### §Nullable-Directives Nullable directives + +Nullable directives control the nullable contexts (§Nullable-Contexts), as described below. + +```ANTLR +fragment PP_Nullable + : PP_Whitespace? '#' PP_Whitespace? 'nullable' PP_Whitespace PP_Nullable_Action + (PP_Whitespace PP_Nullable_Target)? PP_New_Line + ; +fragment PP_Nullable_Action + : 'disable' + | 'enable' + | 'restore' + ; +fragment PP_Nullable_Target + : 'warnings' + | 'annotations' + ; +``` + +A nullable directive sets the denoted nullable context(s) for subsequent lines of code, until another nullable directive overrides it, or until the end of the source code is reached. The effect of each form of nullable directive is, as follows: + +- `#nullable disable`: Sets both nullable contexts to “disabled” +- `#nullable enable`: Sets both nullable contexts to “enabled” +- `#nullable restore`: Restores both nullable contexts to the states specified by the external mechanism, if any +- `#nullable disable annotations`: Sets the nullable annotation context to “disabled” +- `#nullable enable annotations`: Sets the nullable annotation context to “enabled” +- `#nullable restore annotations`: Restores the nullable annotation context to the state specified by the external mechanism, if any +- `#nullable disable warnings`: Sets the nullable warning context to “disabled” +- `#nullable enable warnings`: Sets the nullable warning context to “enabled” +- `#nullable restore warnings`: Restores the nullable warning context to the state specified by the external mechanism, if any + +Disabling a nullable context that is already disabled has no effect. Likewise, enabling a nullable context that is already enabled has no effect. + ### 6.5.9 Pragma directives The `#pragma` preprocessing directive is used to specify contextual information to a compiler. diff --git a/tools/example-templates/standalone-console/Project.csproj b/tools/example-templates/standalone-console/Project.csproj index 281bd3de6..8beb2a9ed 100644 --- a/tools/example-templates/standalone-console/Project.csproj +++ b/tools/example-templates/standalone-console/Project.csproj @@ -4,7 +4,7 @@ Exe net6.0 enable - disable + annotations $example-name true annotations From 76fd1680b7718fd5a3ef8ea72996b04f2df9ae1c Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 10 May 2024 16:55:31 -0400 Subject: [PATCH 2/2] Remove link (which will need to get added) Remove an Xref to a section that's not in this PR. --- standard/lexical-structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standard/lexical-structure.md b/standard/lexical-structure.md index 590b4cddc..41997f5bc 100644 --- a/standard/lexical-structure.md +++ b/standard/lexical-structure.md @@ -1511,7 +1511,7 @@ A `#line hidden` directive has no effect on the compilation unit and line number ### §Nullable-Directives Nullable directives -Nullable directives control the nullable contexts (§Nullable-Contexts), as described below. +Nullable directives control the nullable contexts, as described below. ```ANTLR fragment PP_Nullable