Nullable reference types in F# (#44047)

* Nullable reference types in F#

* up

* up

* updates

* Up

* up

* Update docs/fsharp/language-reference/generics/constraints.md

Co-authored-by: Tomas Grosup <[email protected]>

* Up

* Update component-design-guidelines.md

* up

* up

* Update null-values.md

* Update docs/fsharp/style-guide/component-design-guidelines.md

Co-authored-by: Tomas Grosup <[email protected]>

* Update conventions.md

* Update docs/fsharp/language-reference/values/null-values.md

---------

Co-authored-by: Tomas Grosup <[email protected]>
Co-authored-by: Bill Wagner <[email protected]>

Author: 3 people

docs/fsharp/language-reference/active-patterns.md

@@ -177,6 +177,26 @@ let (|Int|_|) str =
 
 The attribute must be specified, because the use of a struct return is not inferred from simply changing the return type to `ValueOption`. For more information, see [RFC FS-1039](https://github.com/fsharp/fslang-design/blob/main/FSharp-6.0/FS-1039-struct-representation-for-active-patterns.md).
 
+## Null active patterns
+
+In F# 9, nullability related active patterns were added.
+
+The first one is `| Null | NonNull x |`, which is a recommended way to handle possible nulls. In the following example, parameter `s` is inferred nullable via this active pattern usage:
+
+```fsharp
+ let len s =
+    match s with
+    | Null -> -1
+    | NonNull s -> String.length s
+```
+
+If you rather want to automatically throw `NullReferenceException`, you can use the `| NonNullQuick |` pattern:
+
+```fsharp
+let len (NonNullQuick str) =  // throws if the argument is null
+    String.length str
+```
+
 ## See also
 
 - [F# Language Reference](index.md)

docs/fsharp/language-reference/compiler-directives.md

@@ -52,6 +52,28 @@ let str = "Debugging!"
 #endif
 ```
 
+## NULLABLE directive
+
+Starting with F# 9, you can enable nullable reference types in the project:
+
+```xml
+<Nullable>enable</Nullable>
+```
+
+This automatically sets `NULLABLE` directive to the build. It's useful while initially rolling out the feature, to conditionally change conflicting code by `#if NULLABLE` hash directives:
+
+```fsharp
+#if NULLABLE 
+let length (arg: 'T when 'T: not null) =
+    Seq.length arg
+#else
+let length arg =
+    match arg with
+    | null -> -1
+    | s -> Seq.length s
+#endif
+```
+
 ## Line Directives
 
 When building, the compiler reports errors in F# code by referencing line numbers on which each error occurs. These line numbers start at 1 for the first line in a file. However, if you are generating F# source code from another tool, the line numbers in the generated code are generally not of interest, because the errors in the generated F# code most likely arise from another source. The `#line` directive provides a way for authors of tools that generate F# source code to pass information about the original line numbers and source files to the generated F# code.

docs/fsharp/language-reference/compiler-options.md

@@ -18,6 +18,7 @@ The following table shows compiler options listed alphabetically. Some of the F#
 |`--allsigs`|Generates a new (or regenerates an existing) signature file for each source file in the compilation. For more information about signature files, see [Signatures](signature-files.md).|
 |`-a filename.fs`|Generates a library from the specified file. This option is a short form of `--target:library filename.fs`.|
 |`--baseaddress:address`|Specifies the preferred base address at which to load a DLL.<br /><br />This compiler option is equivalent to the C# compiler option of the same name. For more information, see [&#47;baseaddress &#40;C&#35; Compiler Options&#41;](../../csharp/language-reference/compiler-options/advanced.md#baseaddress).|
+|<code>--checknulls[+&#124;-]</code>|Enables [nullable reference types](./values/null-values.md#null-values-starting-with-f-9), added in F# 9.|
 |`--codepage:id`|Specifies which code page to use during compilation if the required page isn't the current default code page for the system.<br /><br />This compiler option is equivalent to the C# compiler option of the same name. For more information, see [&#47;code pages &#40;C&#35; Compiler Options&#41;](../../csharp/language-reference/compiler-options/advanced.md#codepage).|
 |`--consolecolors`|Specifies that errors and warnings use color-coded text on the console.|
 |`--crossoptimize[+ or -]`|Enables or disables cross-module optimizations.|

docs/fsharp/language-reference/fsharp-interactive-options.md

@@ -27,6 +27,7 @@ Where lists appear in F# Interactive option arguments, list elements are separat
 |------|-----------|
 |**--**|Used to instruct F# Interactive to treat remaining arguments as command-line arguments to the F# program or script, which you can access in code by using the list **fsi.CommandLineArgs**.|
 |**--checked**[**+**|**-**]|Same as the **fsc.exe** compiler option. For more information, see [Compiler Options](compiler-options.md).|
+|**--checknulls**[**+**|**-**]|Same as the **fsc.exe** compiler option. For more information, see [Compiler Options](compiler-options.md).|
 |**--codepage:<int>**|Same as the **fsc.exe** compiler option. For more information, see [Compiler Options](compiler-options.md).|
 |**--consolecolors**[**+**|**-**]|Outputs warning and error messages in color.|
 |**--compilertool:<extensionsfolder>|Reference an assembly or directory containing a design time tool (Short form: -t).|

docs/fsharp/language-reference/generics/constraints.md

@@ -20,7 +20,8 @@ There are several different constraints you can apply to limit the types that ca
 |Constraint|Syntax|Description|
 |----------|------|-----------|
 |Type Constraint|*type-parameter* :> *type*|The provided type must be equal to or derived from the type specified, or, if the type is an interface, the provided type must implement the interface.|
-|Null Constraint|*type-parameter* : null|The provided type must support the null literal. This includes all .NET object types but not F# list, tuple, function, class, record, or union types.|
+|Null Constraint|*type-parameter* : null|The provided type must support the null value. This includes all .NET object types but not F# list, tuple, function, class, record, or union types.|
+|Not Null Constraint|*type-parameter* : not null|The provided type must not support the null value. This disallows both `null` annotated types and types which have null as their representation value (such as the option type or types defined with AllowNullLiteral attribute). This generic constraint does allow value types, since those can never be null.|
 |Explicit Member Constraint|[(]*type-parameter* [or ... or *type-parameter*)] : (*member-signature*)|At least one of the type arguments provided must have a member that has the specified signature; not intended for common use. Members must be either explicitly defined on the type or part of an implicit type extension to be valid targets for an Explicit Member Constraint.|
 |Constructor Constraint|*type-parameter* : ( new : unit -> 'a )|The provided type must have a parameterless constructor.|
 |Value Type Constraint|*type-parameter* : struct|The provided type must be a .NET value type.|
@@ -54,6 +55,10 @@ type Class2<'T when 'T :> System.IComparable> =
 type Class3<'T when 'T : null> =
     class end
 
+// Not Null constraint
+type Class4<'T when 'T : not null> =
+    class end
+
 // Member constraint with instance member
 type Class5<'T when 'T : (member Method1 : 'T -> int)> =
     class end

docs/fsharp/language-reference/pattern-matching.md

@@ -210,6 +210,24 @@ The following example uses the null pattern and the variable pattern.
 
 [!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet4817.fs)]
 
+Null pattern is also recommended for the F# 9 [nullability capabilities](./values/null-values.md#null-values-starting-with-f-9):
+
+```fsharp
+let len (str: string | null) =
+    match str with
+    | null -> -1
+    | s -> s.Length
+```
+
+Similarly, you can use new dedicated nullability related [patterns](./active-patterns.md):
+
+```fsharp
+let let str =       // str is inferred to be `string | null`
+    match str with
+    | Null -> -1
+    | NonNull (s: string) -> s.Length
+```
+
 ## Nameof pattern
 
 The `nameof` pattern matches against a string when its value is equal to the expression that follows the `nameof` keyword. for example:

docs/fsharp/language-reference/values/null-values.md

@@ -7,7 +7,7 @@ ms.date: 08/15/2020
 
 This topic describes how the null value is used in F#.
 
-## Null Value
+## Null Values Prior To F# 9
 
 The null value is not normally used in F# for values or variables. However, null appears as an abnormal value in certain situations. If a type is defined in F#, null is not permitted as a regular value unless the [AllowNullLiteral](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-core-allownullliteralattribute.html#Value) attribute is applied to the type. If a type is defined in some other .NET language, null is a possible value, and when you are interoperating with such types, your F# code might encounter null values.
 
@@ -31,6 +31,73 @@ You can use the following code to check if an arbitrary value is null.
 
 [!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-1/snippet703.fs)]
 
+## Null Values starting with F# 9
+
+In F# 9, extra capabilities are added to the language to deal with reference types which can have `null` as a value. Those are off by default - to turn them on, the following property must be put in your project file:
+
+```xml
+<Nullable>enable</Nullable>
+```
+
+This passes the `--checknulls+` [flag](../compiler-options.md) to the F# compiler and sets a `NULLABLE` [preprocessor directive](../compiler-directives.md#nullable-directive) for the build.
+
+To explicitly opt-in into nullability, a type declaration has to be suffixed with the new syntax:
+
+```fsharp
+type | null
+```
+
+The bar symbol `|` has the meaning of a logical OR in the syntax, building a union of two disjoint sets of types: the underlying type, and the nullable reference. This is the same syntactical symbol which is used for declaring multiple cases of an F# discriminated union: `type AB = A | B` carries the meaning of either `A`, or `B`.
+
+The nullable annotation `| null` can be used at all places where a reference type would be normally used:
+
+- Fields of union types, record types and custom types.
+- Type aliases to existing types.
+- Type applications of a generic type.
+- Explicit type annotations to let bindings, parameters or return types.
+- Type annotations to object-programming constructs like members, properties or fields.
+
+```fsharp
+type AB = A | B
+type AbNull = AB | null
+
+type RecordField = { X: string | null }
+type TupleField = string * string | null
+
+type NestedGenerics = { Z : List<List<string | null> | null> | null }
+```
+
+The bar symbol `|` does have other usages in F# which might lead to syntactical ambiguities. In such cases, parentheses are needed around the null-annotated type:
+
+```fsharp
+// Unexpected symbol '|' (directly before 'null') in member definition
+type DUField = N of string | null
+```
+
+Wrapping the same type into a pair of `( )` parentheses fixes the issue:
+
+```fsharp
+type DUField = N of (string | null)
+```
+
+When used in pattern matching, `|` is used to separate different pattern matching clauses.
+
+```fsharp
+match x with
+| ?: string | null -> ...
+```
+
+This snippet is actually equivalent to code first doing a type test against the `string` type, and then having a separate clause for handling null:
+
+```fsharp
+match x with
+| ?: string 
+| null -> ...
+```
+
+> [!IMPORTANT]
+> The extra null related capabilities were added to the language for the interoperability purposes. Using `| null` in F# type modeling is not considered idiomatic for denoting missing information - for that purpose, use options (as described above). Read more about null-related [conventions](../../style-guide/conventions.md#nulls-and-default-values) in the style guide.
+
 ## See also
 
 - [Values](index.md)

docs/fsharp/style-guide/component-design-guidelines.md

@@ -693,11 +693,51 @@ let checkNonNull argName (arg: obj) =
     | null -> nullArg argName
     | _ -> ()
 
-let checkNonNull` argName (arg: obj) =
+let checkNonNull' argName (arg: obj) =
     if isNull arg then nullArg argName
     else ()
 ```
 
+Starting with F# 9, you can leverage the new `| null` [syntax](../language-reference/values/null-values.md#null-values-starting-with-f-9) to make the compiler indicate possible null values and where they need handling:
+
+```fsharp
+let checkNonNull argName (arg: obj | null) =
+    match arg with
+    | null -> nullArg argName
+    | _ -> ()
+
+let checkNonNull' argName (arg: obj | null) =
+    if isNull arg then nullArg argName 
+    else ()
+```
+
+In F# 9, the compiler emits a warning when it detects that a possible null value is not handled:
+
+```fsharp
+let printLineLength (s: string) =
+    printfn "%i" s.Length
+
+let readLineFromStream (sr: System.IO.StreamReader) =
+    // `ReadLine` may return null here - when the stream is finished
+    let line = sr.ReadLine()
+    // nullness warning: The types 'string' and 'string | null'
+    // do not have equivalent nullability
+    printLineLength line
+```
+
+These warnings should be addressed using F# [null pattern](../language-reference/pattern-matching.md#null-pattern) in matching:
+
+```fsharp
+let printLineLength (s: string) =
+    printfn "%i" s.Length
+
+let readLineFromStream (sr: System.IO.StreamReader) =
+    let line = sr.ReadLine()
+    match line with
+    | null -> ()
+    | s -> printLineLength s
+```
+
 #### Avoid using tuples as return values
 
 Instead, prefer returning a named type holding the aggregate data, or using out parameters to return multiple values. Although tuples and struct tuples exist in .NET (including C# language support for struct tuples), they will most often not provide the ideal and expected API for .NET developers.

docs/fsharp/style-guide/conventions.md

@@ -687,6 +687,54 @@ module Array =
 
 For legacy reasons some string functions in FSharp.Core still treat nulls as empty strings and do not fail on null arguments. However do not take this as guidance, and do not adopt coding patterns that attribute any semantic meaning to "null".
 
+### Leverage F# 9 null syntax at the API boundaries
+
+F# 9 adds [syntax](../language-reference/values/null-values.md#null-values-starting-with-f-9) to explicitly state that a value can be null. It's designed to be used on the API boundaries, to make the compiler indicate the places where null handling is missing.
+
+Here is an example of the valid usage of the syntax:
+
+```fsharp
+type CustomType(m1, m2) =
+    member _.M1 = m1
+    member _.M2 = m2
+
+    override this.Equals(obj: obj | null) =
+        match obj with
+        | :? CustomType as other -> this.M1 = other.M1 && this.M2 = other.M2
+        | _ -> false
+
+    override this.GetHashCode() =
+        hash (this.M1, this.M2)
+```
+
+**Avoid** propagating nulls further down your F# code:
+
+```fsharp
+let getLineFromStream (stream: System.IO.StreamReader) : string | null =
+    stream.ReadLine()
+```
+
+**Instead**, use idiomatic F# means (e.g., options):
+
+```fsharp
+let getLineFromStream (stream: System.IO.StreamReader) =
+    stream.ReadLine() |> Option.ofObj
+```
+
+For raising null related exceptions you can use special `nullArgCheck` and `nonNull` functions. They're handy also because in case the value is not null, they [shadow](../language-reference/functions/index.md#scope) the argument with its sanitized value - the further code cannot access possible null pointers anymore.
+
+```fsharp
+let inline processNullableList list =
+   let list = nullArgCheck (nameof list) list   // throws `ArgumentNullException`
+   // 'list' is safe to use from now on
+   list |> List.distinct
+
+let inline processNullableList' list =
+    let list = nonNull list                     // throws `NullReferenceException`
+    // 'list' is safe to use from now on
+    list |> List.distinct
+```
+
 ## Object programming
 
 F# has full support for objects and object-oriented (OO) concepts. Although many OO concepts are powerful and useful, not all of them are ideal to use. The following lists offer guidance on categories of OO features at a high level.