Merge pull request #445 from fsprojects/repo-assist/docs-nonnullable-customattrs-measurebuilder-170-67-812d6974b0540f7c

[Repo Assist] Add docs and tests for nonNullable, hideObjectMethods, AddCustomAttribute and ProvidedMeasureBuilder

Author: dsyme

docs/technical-notes.md

@@ -128,3 +128,156 @@ or
     System.InvalidOperationException: the operation is not valid due to the current state of the object. at System.Reflection.MemberInfo.get_MetadataToken() in f:\dd\ndp\clr\src\BCL\system\reflection\memberinfo.cs:line 65
 ```
 
+## Type Definition Properties: nonNullable, hideObjectMethods, and Custom Attributes
+
+### NonNullable
+
+Set `nonNullable = true` when constructing a `ProvidedTypeDefinition` to mark the type with
+`[<AllowNullLiteral(false)>]`. This prevents the F# `null` literal from being used with the
+provided type, which is the standard F# behaviour for non-nullable reference types.
+
+```fsharp
+let myType = ProvidedTypeDefinition(asm, ns, "MyType", Some typeof<obj>, nonNullable = true)
+// myType.NonNullable = true
+// myType.GetCustomAttributesData() contains AllowNullLiteralAttribute
+```
+
+The `NonNullable` property can be read back to check whether the flag was set.
+
+### HideObjectMethods
+
+Set `hideObjectMethods = true` to suppress the standard .NET `Object` methods (`ToString`,
+`GetHashCode`, `Equals`) from appearing in IntelliSense for instances of the provided type.
+This is useful for simple record-like or data types where the inherited methods add noise.
+
+```fsharp
+let myType = ProvidedTypeDefinition(asm, ns, "MyType", Some typeof<obj>, hideObjectMethods = true)
+// myType.HideObjectMethods = true
+```
+
+### AddCustomAttribute
+
+Use `AddCustomAttribute` to attach arbitrary custom attribute data to provided types, methods,
+properties, parameters, and constructors. Implement `CustomAttributeData` inline:
+
+```fsharp
+open System
+open System.Reflection
+
+// Add [<Obsolete("use something else")>] to a provided type
+let myType = ProvidedTypeDefinition(asm, ns, "MyType", Some typeof<obj>)
+myType.AddCustomAttribute {
+    new CustomAttributeData() with
+        member _.Constructor = typeof<ObsoleteAttribute>.GetConstructor([| typeof<string> |])
+        member _.ConstructorArguments =
+            [| CustomAttributeTypedArgument(typeof<string>, "use something else" :> obj) |] :> _
+        member _.NamedArguments = [||] :> _
+}
+
+// Add [<ReflectedDefinition>] to a method parameter
+let param = ProvidedParameter("p", typeof<Microsoft.FSharp.Quotations.Expr<int>>)
+param.AddCustomAttribute {
+    new CustomAttributeData() with
+        member _.Constructor = typeof<ReflectedDefinitionAttribute>.GetConstructor([||])
+        member _.ConstructorArguments = [||] :> _
+        member _.NamedArguments = [||] :> _
+}
+```
+
+`AddCustomAttribute` is available on `ProvidedTypeDefinition`, `ProvidedProperty`,
+`ProvidedMethod`, and `ProvidedParameter`. Note that `ProvidedConstructor` does not support
+`AddCustomAttribute`; use `AddObsoleteAttribute` for the common case of marking a constructor
+as obsolete.
+
+When using cross-targeting (the normal mode), custom attributes whose types exist in the
+target reference assemblies will appear in `GetCustomAttributesData()` on the translated
+(target) type. Attributes whose types are not present in the target assemblies are silently
+omitted from the cross-targeted model.
+
+## Units of Measure with ProvidedMeasureBuilder
+
+The `ProvidedMeasureBuilder` type allows type providers to create and compose F# units of measure.
+Units can be used to annotate numeric types (e.g. `float<kg>`) exposed by the type provider.
+
+### Standard SI Units
+
+Use `ProvidedMeasureBuilder.SI` to reference standard units from
+`Microsoft.FSharp.Data.UnitSystems.SI`. Pass either the unit symbol (e.g. `"kg"`) or the
+unit name in lowercase (e.g. `"kilogram"`):
+
+```fsharp
+let kg = ProvidedMeasureBuilder.SI "kg"       // UnitSymbols.kg
+let m  = ProvidedMeasureBuilder.SI "m"        // UnitSymbols.m
+let s  = ProvidedMeasureBuilder.SI "s"        // UnitSymbols.s
+let kelvin = ProvidedMeasureBuilder.SI "kelvin" // UnitNames.kelvin
+```
+
+### Annotating Types with Units
+
+Use `ProvidedMeasureBuilder.AnnotateType` to produce annotated numeric types such as `float<kg>`:
+
+```fsharp
+let kg = ProvidedMeasureBuilder.SI "kg"
+let floatKg = ProvidedMeasureBuilder.AnnotateType(typeof<float>, [ kg ])
+// floatKg represents float<kg>
+
+let weightProp = ProvidedProperty("WeightKg", floatKg, getterCode = fun _ -> <@@ 70.0 @@>)
+myType.AddMember weightProp
+```
+
+### Compound Units
+
+`ProvidedMeasureBuilder` provides combinators for composing units:
+
+```fsharp
+let kg = ProvidedMeasureBuilder.SI "kg"
+let m  = ProvidedMeasureBuilder.SI "m"
+let s  = ProvidedMeasureBuilder.SI "s"
+
+// Product: kg·m
+let kgTimesM = ProvidedMeasureBuilder.Product(kg, m)
+
+// Ratio: kg/m
+let kgPerM = ProvidedMeasureBuilder.Ratio(kg, m)
+
+// Square: m²
+let mSquared = ProvidedMeasureBuilder.Square(m)
+
+// Acceleration: m/s²
+let accel = ProvidedMeasureBuilder.Ratio(m, ProvidedMeasureBuilder.Square(s))
+
+// Inverse: 1/s (frequency in Hz)
+let perSecond = ProvidedMeasureBuilder.Inverse(s)
+
+// Dimensionless
+let one = ProvidedMeasureBuilder.One
+```
+
+### Non-Standard (Custom) Units
+
+To expose a custom unit of measure (not from the SI library), define an erased
+`ProvidedTypeDefinition` and use it directly as a measure argument to `AnnotateType`:
+
+```fsharp
+// Define a custom unit "USD" (US dollars)
+let dollar = ProvidedTypeDefinition(asm, ns, "USD", None, isErased = true)
+this.AddNamespace(ns, [ dollar ])
+
+// Use the custom unit to annotate a type
+let floatDollar = ProvidedMeasureBuilder.AnnotateType(typeof<float>, [ dollar ])
+
+let priceProp = ProvidedProperty("Price", floatDollar, getterCode = fun _ -> <@@ 9.99 @@>)
+myType.AddMember priceProp
+```
+
+### Multiple Unit Arguments (Generic Types)
+
+`AnnotateType` also supports generic types with multiple type arguments. For example, to produce
+`Vector<float, kg>`:
+
+```fsharp
+let kg = ProvidedMeasureBuilder.SI "kg"
+// Suppose vectorType is the generic definition of Vector<'T, 'U>
+let annotated = ProvidedMeasureBuilder.AnnotateType(vectorType, [ typeof<float>; kg ])
+```
+

tests/BasicErasedProvisionTests.fs

@@ -593,4 +593,127 @@ let ``check on-demand production of members``() =
     Assert.Equal(5, containersType.GetMethods(bindAll).Length) // 5 properties, 5 getters for properties
     Assert.Equal(5, containersType.GetProperties(bindAll).Length) // 5 properties, 5 getters for properties
     Assert.Equal(0, containersType.GetFields(bindAll).Length) // 5 properties, 5 getters for properties
-    Assert.Equal(0, containersType.GetEvents(bindAll).Length) // 5 properties, 5 getters for properties
+    Assert.Equal(0, containersType.GetEvents(bindAll).Length) // 5 properties, 5 getters for properties
+
+// ---------------------------------------------------------------------------
+// Tests for type definition properties: nonNullable, hideObjectMethods
+// Addresses https://github.com/fsprojects/FSharp.TypeProviders.SDK/issues/170
+// ---------------------------------------------------------------------------
+
+[<Fact>]
+let ``nonNullable=true sets NonNullable property and adds AllowNullLiteralAttribute``() =
+    let refs = Targets.DotNetStandard20FSharpRefs()
+    let config = Testing.MakeSimulatedTypeProviderConfig(resolutionFolder=__SOURCE_DIRECTORY__, runtimeAssembly="whatever.dll", runtimeAssemblyRefs=refs)
+    use _tp = new TypeProviderForNamespaces(config)
+    let asm = Assembly.GetExecutingAssembly()
+
+    let t = ProvidedTypeDefinition(asm, "Test.Namespace", "NonNullableType", Some typeof<obj>, nonNullable = true)
+    Assert.True(t.NonNullable, "NonNullable property should be true")
+    let attrs = t.GetCustomAttributesData()
+    Assert.True(
+        attrs |> Seq.exists (fun a -> a.Constructor.DeclaringType.Name = typeof<AllowNullLiteralAttribute>.Name),
+        "Expected AllowNullLiteralAttribute to be present when nonNullable=true")
+
+[<Fact>]
+let ``nonNullable=false (default) does not add AllowNullLiteralAttribute``() =
+    let refs = Targets.DotNetStandard20FSharpRefs()
+    let config = Testing.MakeSimulatedTypeProviderConfig(resolutionFolder=__SOURCE_DIRECTORY__, runtimeAssembly="whatever.dll", runtimeAssemblyRefs=refs)
+    use _tp = new TypeProviderForNamespaces(config)
+    let asm = Assembly.GetExecutingAssembly()
+
+    let t = ProvidedTypeDefinition(asm, "Test.Namespace", "NullableType", Some typeof<obj>)
+    Assert.False(t.NonNullable, "NonNullable property should default to false")
+    let attrs = t.GetCustomAttributesData()
+    Assert.False(
+        attrs |> Seq.exists (fun a -> a.Constructor.DeclaringType.Name = typeof<AllowNullLiteralAttribute>.Name),
+        "AllowNullLiteralAttribute should not be present when nonNullable is not set")
+
+[<Fact>]
+let ``hideObjectMethods=true sets HideObjectMethods property``() =
+    let refs = Targets.DotNetStandard20FSharpRefs()
+    let config = Testing.MakeSimulatedTypeProviderConfig(resolutionFolder=__SOURCE_DIRECTORY__, runtimeAssembly="whatever.dll", runtimeAssemblyRefs=refs)
+    use _tp = new TypeProviderForNamespaces(config)
+    let asm = Assembly.GetExecutingAssembly()
+
+    let t = ProvidedTypeDefinition(asm, "Test.Namespace", "HiddenObjectType", Some typeof<obj>, hideObjectMethods = true)
+    Assert.True(t.HideObjectMethods, "HideObjectMethods should be true when hideObjectMethods=true")
+
+[<Fact>]
+let ``hideObjectMethods=false (default) leaves HideObjectMethods false``() =
+    let refs = Targets.DotNetStandard20FSharpRefs()
+    let config = Testing.MakeSimulatedTypeProviderConfig(resolutionFolder=__SOURCE_DIRECTORY__, runtimeAssembly="whatever.dll", runtimeAssemblyRefs=refs)
+    use _tp = new TypeProviderForNamespaces(config)
+    let asm = Assembly.GetExecutingAssembly()
+
+    let t = ProvidedTypeDefinition(asm, "Test.Namespace", "NormalType", Some typeof<obj>)
+    Assert.False(t.HideObjectMethods, "HideObjectMethods should default to false")
+
+[<Fact>]
+let ``AddCustomAttribute on method is visible``() =
+    let asm = Assembly.GetExecutingAssembly()
+    let t = ProvidedTypeDefinition(asm, "Test.Namespace", "TypeWithAttrMethod", Some typeof<obj>)
+    let m = ProvidedMethod("OldMethod", [], typeof<unit>, invokeCode = fun _ -> <@@ () @@>)
+    m.AddCustomAttribute {
+        new CustomAttributeData() with
+            member _.Constructor = typeof<ObsoleteAttribute>.GetConstructor([| typeof<string> |])
+            member _.ConstructorArguments = [| CustomAttributeTypedArgument(typeof<string>, "use NewMethod" :> obj) |] :> _
+            member _.NamedArguments = [||] :> _
+    }
+    t.AddMember m
+    let mi = t.GetMethod("OldMethod")
+    Assert.NotNull(mi)
+    let methodAttrs = mi.GetCustomAttributesData()
+    Assert.True(
+        methodAttrs |> Seq.exists (fun a -> a.Constructor.DeclaringType.Name = typeof<ObsoleteAttribute>.Name),
+        "Expected ObsoleteAttribute on method")
+
+// ---------------------------------------------------------------------------
+// Tests for ProvidedMeasureBuilder: SI units, compound units, annotation
+// Addresses https://github.com/fsprojects/FSharp.TypeProviders.SDK/issues/67
+// ---------------------------------------------------------------------------
+
+[<Fact>]
+let ``ProvidedMeasureBuilder SI symbol creates a FSharpTypeAbbreviation``() =
+    let kg = ProvidedMeasureBuilder.SI "kg"
+    match kg with
+    | :? ProvidedTypeSymbol as sym ->
+        Assert.True(sym.IsFSharpTypeAbbreviation, "SI 'kg' should be a FSharpTypeAbbreviation")
+    | _ -> failwith "Expected ProvidedTypeSymbol for 'kg'"
+
+[<Fact>]
+let ``ProvidedMeasureBuilder AnnotateType produces IsFSharpUnitAnnotated``() =
+    let kg = ProvidedMeasureBuilder.SI "kg"
+    let floatKg = ProvidedMeasureBuilder.AnnotateType(typeof<float>, [ kg ])
+    match floatKg with
+    | :? ProvidedTypeSymbol as sym ->
+        Assert.True(sym.IsFSharpUnitAnnotated, "float<kg> should be IsFSharpUnitAnnotated")
+    | _ -> failwith "Expected ProvidedTypeSymbol for annotated type"
+
+[<Fact>]
+let ``ProvidedMeasureBuilder compound units Product, Ratio, Square, Inverse, One are non-null``() =
+    let kg = ProvidedMeasureBuilder.SI "kg"
+    let m  = ProvidedMeasureBuilder.SI "m"
+    let s  = ProvidedMeasureBuilder.SI "s"
+
+    Assert.NotNull(ProvidedMeasureBuilder.Product(kg, m))
+    Assert.NotNull(ProvidedMeasureBuilder.Ratio(kg, m))
+    Assert.NotNull(ProvidedMeasureBuilder.Square(m))
+    Assert.NotNull(ProvidedMeasureBuilder.Inverse(s))
+    Assert.NotNull(ProvidedMeasureBuilder.One)
+
+    // float<m/s²> annotated type should also be IsFSharpUnitAnnotated
+    let accel = ProvidedMeasureBuilder.Ratio(m, ProvidedMeasureBuilder.Square(s))
+    let floatAccel = ProvidedMeasureBuilder.AnnotateType(typeof<float>, [ accel ])
+    match floatAccel with
+    | :? ProvidedTypeSymbol as sym ->
+        Assert.True(sym.IsFSharpUnitAnnotated, "float<m/s²> should be IsFSharpUnitAnnotated")
+    | _ -> failwith "Expected ProvidedTypeSymbol for float<m/s²>"
+
+[<Fact>]
+let ``ProvidedMeasureBuilder SI name (lowercase) creates a FSharpTypeAbbreviation``() =
+    let kelvin = ProvidedMeasureBuilder.SI "kelvin"
+    Assert.NotNull(kelvin)
+    match kelvin with
+    | :? ProvidedTypeSymbol as sym ->
+        Assert.True(sym.IsFSharpTypeAbbreviation, "SI 'kelvin' should be a FSharpTypeAbbreviation")
+    | _ -> failwith "Expected ProvidedTypeSymbol for 'kelvin'"