From d28c5d365d9e08e3f941028717e36fcfa866b7aa Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 13:59:00 +0100 Subject: [PATCH 01/78] plaintext printing documentation --- .../fsharp-interactive-options.md | 111 +++++- .../plaintext-formatting.md | 339 ++++++++++++++++++ 2 files changed, 442 insertions(+), 8 deletions(-) create mode 100644 docs/fsharp/language-reference/plaintext-formatting.md diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 9be87fdec82ba..239c661affd7e 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -1,21 +1,18 @@ --- title: Interactive Options description: Learn about the command-line options supported by F# Interactive, fsi.exe. -ms.date: 05/16/2016 +ms.date: 22/07/2030 --- # F# Interactive Options -> [!NOTE] -> This article currently describes the experience for Windows only. It will be rewritten. - This topic describes the command-line options supported by F# Interactive, `fsi.exe`. F# Interactive accepts many of the same command line options as the F# compiler, but also accepts some additional options. ## Using F# Interactive for Scripting -F# Interactive, `fsi.exe`, can be launched interactively, or it can be launched from the command line to run a script. The command line syntax is +F# Interactive, `dotnet fsi`, can be launched interactively, or it can be launched from the command line to run a script. The command line syntax is ```console -> fsi.exe [options] [ script-file [arguments] ] +> dotnet fsi [options] [ script-file [arguments] ] ``` The file extension for F# script files is `.fsx`. @@ -52,8 +49,6 @@ Where lists appear in F# Interactive option arguments, list elements are separat |**--quotations-debug**|Specifies that extra debugging information should be emitted for expressions that are derived from F# quotation literals and reflected definitions. The debug information is added to the custom attributes of an F# expression tree node. See [Code Quotations](code-quotations.md) and [Expr.CustomAttributes](https://msdn.microsoft.com/library/eb89943f-5f5b-474e-b125-030ca412edb3).| |**--readline**[**+**|**-**]|Enable or disable tab completion in interactive mode.| |**--reference:<filename>**

**-r:<filename>**|Same as the **fsc.exe** compiler option. For more information, see [Compiler Options](compiler-options.md).| -|**--shadowcopyreferences**[**+**|**-**]|Prevents references from being locked by the F# Interactive process.| -|**--simpleresolution**|Resolves assembly references using directory-based rules rather than MSBuild resolution.| |**--tailcalls**[**+**|**-**]|Enable or disable the use of the tail IL instruction, which causes the stack frame to be reused for tail recursive functions. This option is enabled by default.| |**--targetprofile:<string>**|Specifies target framework profile of this assembly. Valid values are mscorlib, netcore or netstandard. The default is mscorlib.| |**--use:<filename>**|Tells the interpreter to use the given file on startup as initial input.| @@ -62,6 +57,106 @@ Where lists appear in F# Interactive option arguments, list elements are separat |**--warnaserror**[**+**|**-**]|Same as the **fsc.exe** compiler option. For more information, see [Compiler Options](compiler-options.md).| |**--warnaserror**[**+**|**-**]:**<int-list>**|Same as the **fsc.exe** compiler option. For more information, see [Compiler Options](compiler-options.md).| +## F# Interactive Structured Printing + +F# Interactive (`dotnet fsi`) uses an extended version of [structured plain text formatting](plaintext-formatting.md) to +report values. + +1. All features of `%A` plaintext formatting are supported, and some are additionally customizable (see below). + +2. Printing is colorized if colours are aupported by the output console. + +3. A limit is placed on the length of strings shown, unless you explicitly evaluate that string. + +4. A set of user-definable settings are available via the `fsi` object. + +The available settings to customize plain text printing for reported values are: + +```fsharp +open System.Globalization + +fsi.FormatProvider <- CultureInfo("de-DE") // control the default culture for primitives + +fsi.PrintWidth <- 120 // control the width used for structured printing + +fsi.PrintDepth <- 10 // control the maximum depth of nested printing + +fsi.PrintLength <- 10 // control the length of lists and arrays + +fsi.PrintSize <- 100 // control the maximum overall object count + +fsi.ShowProperties <- false // control whether properties of .NET objects are shown by default + +fsi.ShowIEnumerable <- false // control whether sequence values are expanded by default + +fsi.ShowDeclarationValues <- false // control whether values are shown for declaration outputs +``` + +### Customizing F# Interactive structured printing with `AddPrinter` and `AddPrintTransformer` + +Printing in F# Interactive outputs can be customized by using `fsi.AddPrinter` and `fsi.AddPrintTransformer`. +The first gives text to replace the printing of an object, the second returns a surrogate object to display +instead. For example, in F# Interactive + +```fsharp +open System + +fsi.AddPrinter(fun dt -> dt.ToString("s")) + +type DateAndLabel = + { Date : DateTime + Label : string } + +let newYearsDay1999 = + { Date = DateTime(1999, 1, 1) + Label = "New Year" } +``` + +gives output that uses the specific date time format: + +```console +type DateAndLabel = + { Date: DateTime + Label: string } +val newYearsDay1999 : DateAndLabel = { Date = 1999-01-01T00:00:00 + Label = "New Year" } +``` + +`fsi.AddPrintTransformer` can be used to give a surrogate object for printing: + +```fsharp +type MyList(values: int list) = + member x.Values = values + +fsi.AddPrintTransformer(fun (x:MyList) -> box x.Values) + +let x = MyList([1..10]) +``` + +gives + +```console +val x : MyList = [1; 2; 3; 4; 5; 6; 7; 8; 9; 10] +``` + +If the transformer function passed to `fsi,AddPrintTransformer` returns `null` then the print transformer is ignored. +This can be used to filter any input value by starting with type `obj`. For example, + +```fsharp +fsi.AddPrintTransformer(fun (x:obj) -> + match x with + | :? string as s when s = "beep" -> box ["quack"; "quack"; "quack"] + | _ -> null) + +let y = "beep" +``` + +gives + +```console +val y : string = ["quack"; "quack"; "quack"] +``` + ## Related Topics |Title|Description| diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md new file mode 100644 index 0000000000000..d801c4fa08fb0 --- /dev/null +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -0,0 +1,339 @@ +--- +title: "Tutorial: Plain Text Formatting" +description: Learn how to use structured formatted plain text in F# applications and scripts. +ms.date: 22/07/2020 +--- + +# Plain Text Formatting + +F# allows values to be formatted as structured plain text in a compositional way. +As a simple example, consider the following and note how the otuput has been formatted as a matrix-like display of tuples. + +```console +dotnet fsi + +> let data = [ for i in 1 .. 3 -> [ for j in 1 .. 3 -> (i, j) ] ];; + +val data : (int * int) list list = + [[(1, 1); (1, 2); (1, 3); (1, 4); (1, 5)]; + [(2, 1); (2, 2); (2, 3); (2, 4); (2, 5)]; + [(3, 1); (3, 2); (3, 3); (3, 4); (3, 5)]; + [(4, 1); (4, 2); (4, 3); (4, 4); (4, 5)]; + [(5, 1); (5, 2); (5, 3); (5, 4); (5, 5)]] + +> printfn "%A" data;; +[[(1, 1); (1, 2); (1, 3); (1, 4); (1, 5)]; + [(2, 1); (2, 2); (2, 3); (2, 4); (2, 5)]; + [(3, 1); (3, 2); (3, 3); (3, 4); (3, 5)]; + [(4, 1); (4, 2); (4, 3); (4, 4); (4, 5)]; + [(5, 1); (5, 2); (5, 3); (5, 4); (5, 5)]] +``` + +Plain text formatting is activated when using the `%A` format in printf formatting strings. This has limited customizability. +It is also used when formatting the output of values in F# interactive, when the output includes extra information and is additionally customizable. +Plain text formatting is observable through the following: + +1. The default results of `x.ToString()` on F# union and record values, when `sprintf "%+A"` is used. + +2. The default debug text of F# union and record values (and structured values containing these), when `sprintf "%+A"` is also used. + +## `%A` formatting + +The `%A` format specifier is used to format values in a human-readable way suitable for interpretation by the F# +programmer. It is not suitable for formatting results for other users and should not generally be used to format +results in a user interface or web programming service. It is often useful for reporting diagnostic information. + +### `%A` formatting of primitive values + +When formatting plain text using the `%A` specifier, F# numeric values are formatted +with their suffix and invariant culture. Floating point values are formatted using +10 places of floating point precision. For example, + +```fsharp +printfn "%A" (1L, 3n, 5u, 7, 4.03f, 5.000000001, 5.0000000001) +``` + +produces + +```console +(1L, 3n, 5u, 7, 4.03000021f, 5.000000001, 5.0) +``` + +When using the `%A` specifier, strings are formatted using quotes. Escape codes are not added and instead the raw characters are printed. For example, + +```fsharp +printfn "%A" ("abc", "a\tb\nc\"d") + +``` + +produces + +```console +("abc", "a b +c"d") +``` + +### `%A` formatting of .NET values + +When formatting plain text using the `%A` specifier, non-F# .NET objects are formatted by using `x.ToString()` using the default settings of .NET given by +`System.Globalization.CultureInfo.CurrentCulture` and `System.Globalization.CultureInfo.CurrentUICulture`. For example, + +```fsharp +open System.Globalization + +let date = System.DateTime(1999, 12, 31) + +CultureInfo.CurrentCulture <- CultureInfo.GetCultureInfo("de-DE") +printfn "Culture 1: %A" date + +CultureInfo.CurrentCulture <- CultureInfo.GetCultureInfo("en-US") +printfn "Culture 2: %A" date +``` + +produces + +```console +Culture 1: 31.12.1999 00:00:00 +Culture 2: 12/31/1999 12:00:00 AM +``` + +### `%A` formatting of structured values + +When formatting plain text using the `%A` specifier, block indentation is used for F# lists and tuples. The is shown in the example above. +The structure of arrays is also used, including multi-dimensional arrays. Single-dimensional arrays are shown with `[| ... |]` syntax. For example, + +```fsharp +printfn "%A" [| for i in 1 .. 20 -> (i, i*i) |] +``` + +produces + +```console +[|(1, 1); (2, 4); (3, 9); (4, 16); (5, 25); (6, 36); (7, 49); (8, 64); (9, 81); + (10, 100); (11, 121); (12, 144); (13, 169); (14, 196); (15, 225); (16, 256); + (17, 289); (18, 324); (19, 361); (20, 400)|] +``` + +A default print width of 80 is used. This can be customized by using a print width in the format specifier. For example, + +```fsharp +printfn "%10A" [| for i in 1 .. 5 -> (i, i*i) |] + +printfn "%20A" [| for i in 1 .. 5 -> (i, i*i) |] + +printfn "%50A" [| for i in 1 .. 5 -> (i, i*i) |] +``` + +produces + +```console +[|(1, 1); + (2, 4); + (3, 9); + (4, 16); + (5, 25)|] +[|(1, 1); (2, 4); + (3, 9); (4, 16); + (5, 25)|] +[|(1, 1); (2, 4); (3, 9); (4, 16); (5, 25)|] +``` + +A depth limit of 4 is used for sequence (IEnumerable) values, which are shown as `seq { ...}`, and a depth limit of 100 is used for list and array values. +For example, + +```fsharp +printfn "%A" (seq { for i in 1 .. 10 -> (i, i*i) }) +``` + +produces + +```console +seq [(1, 1); (2, 4); (3, 9); (4, 16); ...] +``` + +Block indentation is also used for the the structure of public record and union values. For example, + +```fsharp +type R = { X : int list; Y : string list } + +printfn "%A" { X = [ 1;2;3 ]; Y = ["one"; "two"; "three"] } +``` + +produces + +```console +{ X = [1; 2; 3] + Y = ["one"; "two"; "three"] } +``` + +If `%+A` is used then the private structure of records and unions +is also revealed by using reflection. For example + +```fsharp +type internal R = + { X : int list; Y : string list } + override x.ToString() = "R" + +let internal data = { X = [ 1;2;3 ]; Y = ["one"; "two"; "three"] } + +printfn "external view:\n%A" data + +printfn "internal view:\n%+A" data + +``` + +produces + +```console +external view: +R + +internal view: +{ X = [1; 2; 3] + Y = ["one"; "two"; "three"] } +``` + +### `%A` formatting of large, cyclic or deeply nested values + +Large structured values are formatted to a maximum overall object node count of 10000. +Deeply nested values are formatted to a depth of 100. In both cases `...` is used +to elide some of the output. For example, + +```fsharp +type Tree = Node of Tree * Tree | Tip + +let rec make n = if n = 0 then Tip else Node(Tip, make (n-1)) + +printfn "%A" (make 1000) +``` + +produces a large output with some parts elided + +```console +Node(Tip, Node(Tip, ....Node (..., ...)...)) +``` + +Cycles are detected in the object graphs and `...` is used at places where cycles are detected. For example + +```fsharp +type R = { mutable Links: R list } +let r = { Links = [] } +r.Links <- [r] +printfn "%A" r +``` + +produces + +```console +{ Links = [...] } +``` + +### `%A` formatting of lazy, null and function values + +Lazy values are printed as `Value is not created` or equivalent text when the value has not yet been evaluated. + +Null values are printed as `null` unless the static type of the value is determined to be a union type where `null` is +a permitted represenation. + +F# function values are printed as their internally generated closure name, for example ``. + +### Customizing plain text formatting with `StructuredFormatDisplayAttribute` + +When using the `%A` specifier, the presence of `StructuredFormatDisplayAttribute` on type declarations is respected. This can +be used to specify surrogate text and property to display a value. For example: + +```fsharp +[] +type Counts = { Clicks:int list} + +printfn "%20A" {Clicks=[0..20]} +``` + +produces + +```console +Counts([0; 1; 2; 3; + 4; 5; 6; 7; + 8; 9; 10; 11; + 12; 13; 14; + 15; 16; 17; + 18; 19; 20]) +``` + +### Customizing plain text formatting by overriding `ToString` + +The default implementation of `x.ToString()` is observable in F# programming. Often the default results +are not suitable for use in either programmer-facing information display nor user output, and as a result it +is common to override the default implementation. + +By default F# record and union types override the implementation of `x.ToString()` with an implementation that +uses `sprintf "%+A"`. For example, + +```fsharp +type Counts = { Clicks:int list } + +printfn "%s" ({Clicks=[0..10]}.ToString()) +``` + +produces + +```console +{ Clicks = [0; 1; 2; 3; 4; 5; 6; 7; 8; 9; 10] } +``` + +For class types, no default implementation of `ToString()` is provided and the .NET default is used, which reports the +name of the type. For example, + +```fsharp +type MyClassType(clicks: int list) = + member x.Clicks = clicks + +printfn "The default ToString gives --> %s" (MyClassType([1..5]).ToString()) +``` + +produces + +```console +The default ToString gives --> MyClassType +``` + +Sometimes `sprintf "%A"` plus a `StructuredFormatDisplay` attribute makes for a suitable implementation +of `ToString`, e.g. + +```fsharp +[] +type MyClassType(clicks: int list) = + member x.Clicks = clicks + override x.ToString() = sprintf "%A" x + +printfn "ToString now gives --> %s" (MyClassType([1..5]).ToString()) +``` + +produces + +```console +ToString now gives --> Counts([1; 2; 3; 4; 5]) +``` + +## F# Interactive Structured Printing + +F# Interactive (`dotnet fsi`) uses an extended version of structured plain text formatting to +report values and allows additional customizability. See [F# Interactive](fsharp-interactive-options.md) +for details. + +## Customizing debug displays using DebuggerDisplayAttribute, DebuggerTypeProxyAttribute and other attributes + +Debuggers for .NET respect the use of attributes such as `DebuggerDisplayAttribute` and `DebuggerTypeProxyAttribute` +and these affect the structured display of objects in debugger inspection windows. +The F# compiler automatically generated these attributes for discriminated union and record types, but +not class, interface or struct types. + +These attributed are ignored in F# plain text formatting, but it can be useful to implement +these methods to improve displays when debugging F# types. + +## See also + +- [Strings](strings.md) +- [Records](records.md) +- [Discriminated Unions](discriminated-unions.md) +- [F# Interactive](fsharp-interactive-options.md) From cb774e117f84e65a3f50d12581576f633123662c Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 16:37:57 +0100 Subject: [PATCH 02/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index d801c4fa08fb0..405ac3cb9f724 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -1,7 +1,7 @@ --- title: "Tutorial: Plain Text Formatting" description: Learn how to use structured formatted plain text in F# applications and scripts. -ms.date: 22/07/2020 +ms.date: 07/22/2020 --- # Plain Text Formatting From 7c58838ebecf49658cc0e849f29193a336aebbe8 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 16:38:03 +0100 Subject: [PATCH 03/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 239c661affd7e..98400c120f2c1 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -1,7 +1,7 @@ --- title: Interactive Options description: Learn about the command-line options supported by F# Interactive, fsi.exe. -ms.date: 22/07/2030 +ms.date: 07/22/2020 --- # F# Interactive Options From 22d5d7a7c9b2e3efcde63c1f7cd024e5a6a9480f Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 17:58:19 +0100 Subject: [PATCH 04/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 405ac3cb9f724..1eca58a1e470f 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -1,5 +1,5 @@ --- -title: "Tutorial: Plain Text Formatting" +title: "Plain Text Formatting" description: Learn how to use structured formatted plain text in F# applications and scripts. ms.date: 07/22/2020 --- From 0d4c566d6789fb9df7093518a08f9db54b5b030a Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 17:58:29 +0100 Subject: [PATCH 05/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 1eca58a1e470f..abd5fa97ca79c 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -7,7 +7,7 @@ ms.date: 07/22/2020 # Plain Text Formatting F# allows values to be formatted as structured plain text in a compositional way. -As a simple example, consider the following and note how the otuput has been formatted as a matrix-like display of tuples. +For example, consider the following and note how the output has been formatted as a matrix-like display of tuples. ```console dotnet fsi From a62c18eeb28f8eb77eacc5830a44b42ad00f116f Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 17:58:43 +0100 Subject: [PATCH 06/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 98400c120f2c1..3cf8aa83da070 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -62,7 +62,7 @@ Where lists appear in F# Interactive option arguments, list elements are separat F# Interactive (`dotnet fsi`) uses an extended version of [structured plain text formatting](plaintext-formatting.md) to report values. -1. All features of `%A` plaintext formatting are supported, and some are additionally customizable (see below). +1. All features of `%A` plain text formatting are supported, and some are additionally customizable. 2. Printing is colorized if colours are aupported by the output console. From 28b3dbe61e58e3a0d7043f13cc47e816782e6f7f Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 17:58:51 +0100 Subject: [PATCH 07/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 3cf8aa83da070..27b978ed45b29 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -64,7 +64,7 @@ report values. 1. All features of `%A` plain text formatting are supported, and some are additionally customizable. -2. Printing is colorized if colours are aupported by the output console. +2. Printing is colorized if colors are supported by the output console. 3. A limit is placed on the length of strings shown, unless you explicitly evaluate that string. From 2a730648d39ad9b94005ae1be15d47a58aabd630 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 17:59:06 +0100 Subject: [PATCH 08/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Phillip Carter --- .../fsharp-interactive-options.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 27b978ed45b29..cad900e6869c7 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -77,19 +77,19 @@ open System.Globalization fsi.FormatProvider <- CultureInfo("de-DE") // control the default culture for primitives -fsi.PrintWidth <- 120 // control the width used for structured printing +fsi.PrintWidth <- 120 // Control the width used for structured printing -fsi.PrintDepth <- 10 // control the maximum depth of nested printing +fsi.PrintDepth <- 10 // Control the maximum depth of nested printing -fsi.PrintLength <- 10 // control the length of lists and arrays +fsi.PrintLength <- 10 // Control the length of lists and arrays -fsi.PrintSize <- 100 // control the maximum overall object count +fsi.PrintSize <- 100 // Control the maximum overall object count -fsi.ShowProperties <- false // control whether properties of .NET objects are shown by default +fsi.ShowProperties <- false // Control whether properties of .NET objects are shown by default -fsi.ShowIEnumerable <- false // control whether sequence values are expanded by default +fsi.ShowIEnumerable <- false // Control whether sequence values are expanded by default -fsi.ShowDeclarationValues <- false // control whether values are shown for declaration outputs +fsi.ShowDeclarationValues <- false // Control whether values are shown for declaration outputs ``` ### Customizing F# Interactive structured printing with `AddPrinter` and `AddPrintTransformer` From d0e394f4e566fa417b0e363c87bc6262275541cd Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 18:07:45 +0100 Subject: [PATCH 09/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index abd5fa97ca79c..99ddae7efcbb8 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -30,7 +30,7 @@ val data : (int * int) list list = ``` Plain text formatting is activated when using the `%A` format in printf formatting strings. This has limited customizability. -It is also used when formatting the output of values in F# interactive, when the output includes extra information and is additionally customizable. +Plain text formatting is also used when formatting the output of values in F# interactive, when the output includes extra information and is additionally customizable. Plain text formatting is observable through the following: 1. The default results of `x.ToString()` on F# union and record values, when `sprintf "%+A"` is used. From 2ed567c2e014c530e4953cfd9c6e31f9ed2a2d74 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 18:42:34 +0100 Subject: [PATCH 10/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 99ddae7efcbb8..8e41d98231f58 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -29,7 +29,7 @@ val data : (int * int) list list = [(5, 1); (5, 2); (5, 3); (5, 4); (5, 5)]] ``` -Plain text formatting is activated when using the `%A` format in printf formatting strings. This has limited customizability. +Plain text formatting is activated when you use the `%A` format in `printf` formatting strings. Plain text formatting is also used when formatting the output of values in F# interactive, when the output includes extra information and is additionally customizable. Plain text formatting is observable through the following: From 3e315a644f690e3c6e3a76c81ce44822cdeef8c5 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 18:42:55 +0100 Subject: [PATCH 11/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 8e41d98231f58..08eef2fc5a774 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -39,9 +39,7 @@ Plain text formatting is observable through the following: ## `%A` formatting -The `%A` format specifier is used to format values in a human-readable way suitable for interpretation by the F# -programmer. It is not suitable for formatting results for other users and should not generally be used to format -results in a user interface or web programming service. It is often useful for reporting diagnostic information. +The `%A` format specifier is used to format values in a human-readable way, and can also be useful for reporting diagnostic information. ### `%A` formatting of primitive values From a30abea78b7155705a34c7cd46a6d74508a6872b Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 18:43:04 +0100 Subject: [PATCH 12/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index cad900e6869c7..92bfa0d7538bf 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -1,5 +1,5 @@ --- -title: Interactive Options +title: Interactive options description: Learn about the command-line options supported by F# Interactive, fsi.exe. ms.date: 07/22/2020 --- From f7b7cf7f6c78bf2f1c4694f42432a6f4bdb8ec4e Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 18:43:12 +0100 Subject: [PATCH 13/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 92bfa0d7538bf..c2b4b4f9e9854 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -7,7 +7,7 @@ ms.date: 07/22/2020 This topic describes the command-line options supported by F# Interactive, `fsi.exe`. F# Interactive accepts many of the same command line options as the F# compiler, but also accepts some additional options. -## Using F# Interactive for Scripting +## Using F# Interactive for scripting F# Interactive, `dotnet fsi`, can be launched interactively, or it can be launched from the command line to run a script. The command line syntax is From 081e138adca147470645354718b3c0fde4646a8c Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 18:43:19 +0100 Subject: [PATCH 14/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index c2b4b4f9e9854..19b0ec7489db9 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -11,7 +11,7 @@ This topic describes the command-line options supported by F# Interactive, `fsi. F# Interactive, `dotnet fsi`, can be launched interactively, or it can be launched from the command line to run a script. The command line syntax is -```console +```dotnetcli > dotnet fsi [options] [ script-file [arguments] ] ``` From 35b695ecb4155f0f58b8050b02fc72a60ce25b21 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 18:43:28 +0100 Subject: [PATCH 15/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 19b0ec7489db9..e0d77988ff659 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -3,7 +3,7 @@ title: Interactive options description: Learn about the command-line options supported by F# Interactive, fsi.exe. ms.date: 07/22/2020 --- -# F# Interactive Options +# F# Interactive options This topic describes the command-line options supported by F# Interactive, `fsi.exe`. F# Interactive accepts many of the same command line options as the F# compiler, but also accepts some additional options. From dd05c96740000d77d70fa51a2b4068bdd7830cfa Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 18:43:38 +0100 Subject: [PATCH 16/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 08eef2fc5a774..0668fd50988b4 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -319,7 +319,7 @@ F# Interactive (`dotnet fsi`) uses an extended version of structured plain text report values and allows additional customizability. See [F# Interactive](fsharp-interactive-options.md) for details. -## Customizing debug displays using DebuggerDisplayAttribute, DebuggerTypeProxyAttribute and other attributes +## Customize debug displays using `DebuggerDisplayAttribute`, `DebuggerTypeProxyAttribute`, and other attributes Debuggers for .NET respect the use of attributes such as `DebuggerDisplayAttribute` and `DebuggerTypeProxyAttribute` and these affect the structured display of objects in debugger inspection windows. From b144740603a7b6cdc7210950c7fdf990824f2b0c Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 18:43:49 +0100 Subject: [PATCH 17/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 0668fd50988b4..ec46187dd15fd 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -258,7 +258,7 @@ Counts([0; 1; 2; 3; 18; 19; 20]) ``` -### Customizing plain text formatting by overriding `ToString` +### Customize plain text formatting by overriding `ToString` The default implementation of `x.ToString()` is observable in F# programming. Often the default results are not suitable for use in either programmer-facing information display nor user output, and as a result it From 24c61737c640c38046db5a62443e7c82c83d7c4f Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 18:45:25 +0100 Subject: [PATCH 18/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index e0d77988ff659..ab5374492fa01 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -157,7 +157,7 @@ gives val y : string = ["quack"; "quack"; "quack"] ``` -## Related Topics +## Related topics |Title|Description| |-----|-----------| From 1521b93db0b7b9755c3ac517a0f731e725254906 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 18:47:22 +0100 Subject: [PATCH 19/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index ec46187dd15fd..577cbf847100d 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -235,7 +235,7 @@ a permitted represenation. F# function values are printed as their internally generated closure name, for example ``. -### Customizing plain text formatting with `StructuredFormatDisplayAttribute` +### Customize plain text formatting with `StructuredFormatDisplayAttribute` When using the `%A` specifier, the presence of `StructuredFormatDisplayAttribute` on type declarations is respected. This can be used to specify surrogate text and property to display a value. For example: From 4b5e57de7e613ae3a5edc1eb7f89c7650ababf55 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 18:47:30 +0100 Subject: [PATCH 20/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 577cbf847100d..eb918f0179a8d 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -226,7 +226,7 @@ produces { Links = [...] } ``` -### `%A` formatting of lazy, null and function values +### `%A` formatting of lazy, null, and function values Lazy values are printed as `Value is not created` or equivalent text when the value has not yet been evaluated. From 1de04e9f4a77d58f3ef6f8daa573cce8552d1b29 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 19:24:22 +0100 Subject: [PATCH 21/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index eb918f0179a8d..9725c960d30b4 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -191,7 +191,7 @@ internal view: Y = ["one"; "two"; "three"] } ``` -### `%A` formatting of large, cyclic or deeply nested values +### `%A` formatting of large, cyclic, or deeply nested values Large structured values are formatted to a maximum overall object node count of 10000. Deeply nested values are formatted to a depth of 100. In both cases `...` is used From 7e21846018a4fb29dd367e7ee42fca965bd48771 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 19:24:33 +0100 Subject: [PATCH 22/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index ab5374492fa01..5c8626ff04364 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -12,7 +12,7 @@ This topic describes the command-line options supported by F# Interactive, `fsi. F# Interactive, `dotnet fsi`, can be launched interactively, or it can be launched from the command line to run a script. The command line syntax is ```dotnetcli -> dotnet fsi [options] [ script-file [arguments] ] +dotnet fsi [options] [ script-file [arguments] ] ``` The file extension for F# script files is `.fsx`. From 74293ac606edcd4c679df5235089f76b81fbbb3a Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 19:24:45 +0100 Subject: [PATCH 23/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 5c8626ff04364..73ade27d1e484 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -151,7 +151,7 @@ fsi.AddPrintTransformer(fun (x:obj) -> let y = "beep" ``` -gives +This outputs: ```console val y : string = ["quack"; "quack"; "quack"] From afa4512b99a88852250bbf879ae04c9057139099 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 19:24:55 +0100 Subject: [PATCH 24/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 73ade27d1e484..8beccec7bde48 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -96,7 +96,7 @@ fsi.ShowDeclarationValues <- false // Control whether values are shown for decla Printing in F# Interactive outputs can be customized by using `fsi.AddPrinter` and `fsi.AddPrintTransformer`. The first gives text to replace the printing of an object, the second returns a surrogate object to display -instead. For example, in F# Interactive +instead. For example, consider the following F# code: ```fsharp open System From 63de19e3a0c8bc14e99bb4d54028175520387f7d Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 19:27:30 +0100 Subject: [PATCH 25/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 8beccec7bde48..bf7a46d28bcb0 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -140,7 +140,7 @@ val x : MyList = [1; 2; 3; 4; 5; 6; 7; 8; 9; 10] ``` If the transformer function passed to `fsi,AddPrintTransformer` returns `null` then the print transformer is ignored. -This can be used to filter any input value by starting with type `obj`. For example, +This can be used to filter any input value by starting with type `obj`. For example: ```fsharp fsi.AddPrintTransformer(fun (x:obj) -> From a8b49bc177e938ec5769e7451c0a31e07aaeba23 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 19:27:37 +0100 Subject: [PATCH 26/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index bf7a46d28bcb0..e8eb68773d7ef 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -139,7 +139,7 @@ gives val x : MyList = [1; 2; 3; 4; 5; 6; 7; 8; 9; 10] ``` -If the transformer function passed to `fsi,AddPrintTransformer` returns `null` then the print transformer is ignored. +If the transformer function passed to `fsi.AddPrintTransformer` returns `null` then the print transformer is ignored. This can be used to filter any input value by starting with type `obj`. For example: ```fsharp From c4c38953cfcb22aaf2b5863caca75d070f94b0fb Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 19:27:46 +0100 Subject: [PATCH 27/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index e8eb68773d7ef..69fdacfdaa613 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -133,7 +133,7 @@ fsi.AddPrintTransformer(fun (x:MyList) -> box x.Values) let x = MyList([1..10]) ``` -gives +This outputs: ```console val x : MyList = [1; 2; 3; 4; 5; 6; 7; 8; 9; 10] From cc5ff2162f21b56fe246a1ae50b8c2f836c1c478 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 19:27:56 +0100 Subject: [PATCH 28/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 69fdacfdaa613..b827fff85bad6 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -112,7 +112,7 @@ let newYearsDay1999 = Label = "New Year" } ``` -gives output that uses the specific date time format: +If you execute the example in F# Interactive, it outputs based on the formatting option set. In this case, it affects the formatting of date and time: ```console type DateAndLabel = From fccef2754e7fd26a97fdbfe7f5d1d3120b7db325 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 19:49:16 +0100 Subject: [PATCH 29/78] Update plaintext-formatting.md --- .../plaintext-formatting.md | 53 ++++++++++++++----- 1 file changed, 40 insertions(+), 13 deletions(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 9725c960d30b4..e8039ce9372ae 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -6,7 +6,7 @@ ms.date: 07/22/2020 # Plain Text Formatting -F# allows values to be formatted as structured plain text in a compositional way. +F# allows structured values to be formatted as plain text. For example, consider the following and note how the output has been formatted as a matrix-like display of tuples. ```console @@ -31,9 +31,8 @@ val data : (int * int) list list = Plain text formatting is activated when you use the `%A` format in `printf` formatting strings. Plain text formatting is also used when formatting the output of values in F# interactive, when the output includes extra information and is additionally customizable. -Plain text formatting is observable through the following: - -1. The default results of `x.ToString()` on F# union and record values, when `sprintf "%+A"` is used. +Plain text formatting is also observable through any calls to `x.ToString()` on F# union and record values, including those +that occur implicitly in debugging, logging and other tooling. 2. The default debug text of F# union and record values (and structured values containing these), when `sprintf "%+A"` is also used. @@ -136,6 +135,27 @@ produces [|(1, 1); (2, 4); (3, 9); (4, 16); (5, 25)|] ``` +Specifying a print width of 0 results in no print width being used. A single line of text will result, except where embedded strings in the +output themselves contain linebreaks. For example + +```fsharp +printfn "%0A" [| for i in 1 .. 5 -> (i, i*i) |] + +printfn "%0A" [| for i in 1 .. 5 -> "abc\ndef |] +``` + +produces + +```console +[|(1, 1); (2, 4); (3, 9); (4, 16); (5, 25)|] +[|"abc +def"; "abc +def"; "abc +def"; "abc +def"; "abc +def"|] +``` + A depth limit of 4 is used for sequence (IEnumerable) values, which are shown as `seq { ...}`, and a depth limit of 100 is used for list and array values. For example, @@ -286,31 +306,38 @@ name of the type. For example, type MyClassType(clicks: int list) = member x.Clicks = clicks -printfn "The default ToString gives --> %s" (MyClassType([1..5]).ToString()) +let data = [ MyClassType([1..5]); MyClassType([1..5]) ] +printfn "Default structured print gives this:\n%A" data +printfn "Default ToString gives:\n%s" (data.ToString()) ``` produces ```console -The default ToString gives --> MyClassType +Default structured print gives this: +[MyClassType; MyClassType] +Default ToString gives: +[MyClassType; MyClassType] ``` -Sometimes `sprintf "%A"` plus a `StructuredFormatDisplay` attribute makes for a suitable implementation -of `ToString`, e.g. - +Adding an override for `ToString()` can give better formatting. ```fsharp -[] type MyClassType(clicks: int list) = member x.Clicks = clicks - override x.ToString() = sprintf "%A" x + override x.ToString() = sprintf "MyClassType(%0A)" clicks -printfn "ToString now gives --> %s" (MyClassType([1..5]).ToString()) +let data = [ MyClassType([1..5]); MyClassType([1..5]) ] +printfn "Now structured print gives this:\n%A" data +printfn "Now ToString gives:\n%s" (data.ToString()) ``` produces ```console -ToString now gives --> Counts([1; 2; 3; 4; 5]) +Now structured print gives this: +[MyClassType([1; 2; 3; 4; 5]); MyClassType([1; 2; 3; 4; 5])] +Now ToString gives: +[MyClassType([1; 2; 3; 4; 5]); MyClassType([1; 2; 3; 4; 5])] ``` ## F# Interactive Structured Printing From 54e2908518aace94cf0ed6c9efa6f4a295738e4a Mon Sep 17 00:00:00 2001 From: Don Syme Date: Wed, 22 Jul 2020 20:40:28 +0100 Subject: [PATCH 30/78] Update plaintext-formatting.md --- docs/fsharp/language-reference/plaintext-formatting.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index e8039ce9372ae..8ca4b68b2c721 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -34,8 +34,6 @@ Plain text formatting is also used when formatting the output of values in F# in Plain text formatting is also observable through any calls to `x.ToString()` on F# union and record values, including those that occur implicitly in debugging, logging and other tooling. -2. The default debug text of F# union and record values (and structured values containing these), when `sprintf "%+A"` is also used. - ## `%A` formatting The `%A` format specifier is used to format values in a human-readable way, and can also be useful for reporting diagnostic information. @@ -321,6 +319,7 @@ Default ToString gives: ``` Adding an override for `ToString()` can give better formatting. + ```fsharp type MyClassType(clicks: int list) = member x.Clicks = clicks From 8d2c52cba21da197293313b3cf27e05d1aa6a26e Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 13:03:08 +0100 Subject: [PATCH 31/78] add printf information --- .../plaintext-formatting.md | 98 ++++++++++++++++--- 1 file changed, 85 insertions(+), 13 deletions(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 8ca4b68b2c721..e89c2ed6cb7cb 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -1,27 +1,34 @@ --- title: "Plain Text Formatting" -description: Learn how to use structured formatted plain text in F# applications and scripts. +description: Learn how to use printf and other plain text formatting in F# applications and scripts. ms.date: 07/22/2020 --- # Plain Text Formatting -F# allows structured values to be formatted as plain text. -For example, consider the following and note how the output has been formatted as a matrix-like display of tuples. +F# supports type-checked formatting of plain text using `printf`, `printfn`, `sprintf` and related functions. +For example, ```console dotnet fsi -> let data = [ for i in 1 .. 3 -> [ for j in 1 .. 3 -> (i, j) ] ];; +> printfn "Hello %s, %d + %d is %d" "world" 2 2 (2+2);; +``` + +gives the output + +```fsharp +Hello world, 2 + 2 is 4 +``` + +F# also allows structured values to be formatted as plain text. +For example, consider the following and note how the output has been formatted as a matrix-like display of tuples. + +```console +dotnet fsi -val data : (int * int) list list = - [[(1, 1); (1, 2); (1, 3); (1, 4); (1, 5)]; - [(2, 1); (2, 2); (2, 3); (2, 4); (2, 5)]; - [(3, 1); (3, 2); (3, 3); (3, 4); (3, 5)]; - [(4, 1); (4, 2); (4, 3); (4, 4); (4, 5)]; - [(5, 1); (5, 2); (5, 3); (5, 4); (5, 5)]] +> printfn "%A" [ for i in 1 .. 5 -> [ for j in 1 .. 5 -> (i, j) ] ];; -> printfn "%A" data;; [[(1, 1); (1, 2); (1, 3); (1, 4); (1, 5)]; [(2, 1); (2, 2); (2, 3); (2, 4); (2, 5)]; [(3, 1); (3, 2); (3, 3); (3, 4); (3, 5)]; @@ -29,11 +36,76 @@ val data : (int * int) list list = [(5, 1); (5, 2); (5, 3); (5, 4); (5, 5)]] ``` -Plain text formatting is activated when you use the `%A` format in `printf` formatting strings. -Plain text formatting is also used when formatting the output of values in F# interactive, when the output includes extra information and is additionally customizable. +Structured plain text formatting is activated when you use the `%A` format in [`printf` formatting strings](printf.md) +and also when formatting the output of values in F# interactive, where the output includes extra information and is additionally customizable. Plain text formatting is also observable through any calls to `x.ToString()` on F# union and record values, including those that occur implicitly in debugging, logging and other tooling. +## Checking of `printf`-format strings + +A compile-time error will be reported if a `printf` formatting function is used with an argument that doesn't match the printf format +specifiers in the format string. For example, + +```fsharp +sprintf "Hello %s" (2+2) +``` + +gives the output + +```console + sprintf "Hello %s" (2+2) + ----------------------^ + +stdin(3,25): error FS0001: The type 'string' does not match the type 'int' +``` + +Technically speaking, when using `printf` and other related functions a special rule in the F# compiler +checks the string literal passed as the format string, ensuring the subsequent arguments applied are of +the correct type to match the format specifiers used. + +## Format Specifiers for `printf` + +Format specifications for `printf` formats are strings with `%` markers indicating format. Format placeholders consist of `%[flags][width][.precision][type]` +where the type is interpreted as follows: + +| Format specifier | Type(s) | Remarks | +|:-------------------|:---------------|:-----------------------------| +| `%b` | bool | Formatted as `true` or `false` | +| `%s` | string | Formatted as its unescaped contents | +| `%c` | char | Formatted as the character literal | +| `%d`, `%i` | a basic integer type | Formatted as a decimal integer, signed if the basic integer type is signed | +| `%u` | a basic integer type | Formatted as an unsigned decimal integer | +| `%x`, `%X` | a basic integer type | Formatted as an unsigned hexadecimal number (a-f or A-F for hex digits respectively) | +| `%o` | a basic integer type | Formatted as an unsigned octal number | +| `%e`, `%E` | a basic floating point type | Formatted as a signed value having the form `[-]d.dddde[sign]ddd` where d is a single decimal digit, dddd is one or more decimal digits, ddd is exactly three decimal digits, and sign is `+` or `-` | +| `%f` | a basic floating point type | Formatted as a signed value having the form `[-]dddd.dddd`, where `dddd` is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision. | +| `%g`, `%G` | a basic floating point type | Formatted using as a signed value printed in `%f` or `%e` format, whichever is more compact for the given value and precision. | +| `%M` | a `System.Decimal` value | Formatted using the `"G"` format specifier for `System.Decimal.ToString(format)` | +| `%O` | any value | Formatted by boxing the object and valling its `System.Object.ToString()` method | +| `%A` | any value | Formatted using [structured plain text formatting](plaintext-formatting.md) with the default layout settings | +| `%a` | any value | Requires two arguments - a formatting function accepting a context parameter and the value, and the particular value to print | +| `%t` | any value | Requires one argument, a formatting function accepting a context parameter which either outputs or returns the appropriate text | + +Basic integer types are `byte` (`System.Byte`), `sbyte` (`System.SByte`), `int16` (`System.Int16`), `uint16` (`System.UInt16`), `int32` (`System.Int32`), `uint32` (`System.UInt32`), `int64` (`System.Int64`), `uint64` (`System.UInt64`), `nativeint` (`System.IntPtr`)and `unativeint` (`System.UIntPtr`). + Basic floating point types are `float` (`System.Double`) and `float32` (`System.Single`). + +The optional width is an integer indicating the minimal width of the result. For instance, `%6d` prints an integer, prefixing it with spaces +to fill at least 6 characters. If width is `*`, then an extra integer argument is taken to specify the corresponding width. + +Valid flags are: + +| Flag | Effect | Remarks | +|:-------------------|:---------------|:-----------------------------| +| `0` | add zeros instead of spaces to make up the required width | | +| `-` | left justify the result within the width specified | | +| `+` | add a `+` character if the number is positive (to match a `-` sign for negatives) | | +| a space character | add an extra space if the number is positive (to match a '-' sign for negatives) | + +The printf `#` flag is invalid and a compile-time error will be reported if it is used. + +Values are formatted using invariant culture and culture settings are irrelevant to `printf` formatting except +when they affect the results of `%O` and `%A` formatting, see [structured plain text formatting](plaintext-formatting.md) for more details. + ## `%A` formatting The `%A` format specifier is used to format values in a human-readable way, and can also be useful for reporting diagnostic information. From 39abef6132e5c9e97be62bdc5ddeb541cc7870d3 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 13:04:00 +0100 Subject: [PATCH 32/78] add printf information --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index e89c2ed6cb7cb..1b5951b9b4cd7 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -36,7 +36,7 @@ dotnet fsi [(5, 1); (5, 2); (5, 3); (5, 4); (5, 5)]] ``` -Structured plain text formatting is activated when you use the `%A` format in [`printf` formatting strings](printf.md) +Structured plain text formatting is activated when you use the `%A` format in `printf` formatting strings. and also when formatting the output of values in F# interactive, where the output includes extra information and is additionally customizable. Plain text formatting is also observable through any calls to `x.ToString()` on F# union and record values, including those that occur implicitly in debugging, logging and other tooling. From 9411d5368519b8107cc54f6219beea347550c89c Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 13:10:22 +0100 Subject: [PATCH 33/78] add printf information --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 1b5951b9b4cd7..7144b35c382cc 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -99,7 +99,7 @@ Valid flags are: | `0` | add zeros instead of spaces to make up the required width | | | `-` | left justify the result within the width specified | | | `+` | add a `+` character if the number is positive (to match a `-` sign for negatives) | | -| a space character | add an extra space if the number is positive (to match a '-' sign for negatives) | +| a space character | add an extra space if the number is positive (to match a '-' sign for negatives) | The printf `#` flag is invalid and a compile-time error will be reported if it is used. From 366fc1d77e9f82eb34c0b27f471d6302c4e97e43 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 13:10:57 +0100 Subject: [PATCH 34/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 7144b35c382cc..0af46f5031fd9 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -104,7 +104,7 @@ Valid flags are: The printf `#` flag is invalid and a compile-time error will be reported if it is used. Values are formatted using invariant culture and culture settings are irrelevant to `printf` formatting except -when they affect the results of `%O` and `%A` formatting, see [structured plain text formatting](plaintext-formatting.md) for more details. +when they affect the results of `%O` and `%A` formatting. For more information, see [structured plain text formatting](plaintext-formatting.md). ## `%A` formatting From 60af23fd35b526d44e51244ce05f125969482cf6 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:45:04 +0100 Subject: [PATCH 35/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 0af46f5031fd9..ea10c2cf8504d 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -424,7 +424,7 @@ and these affect the structured display of objects in debugger inspection window The F# compiler automatically generated these attributes for discriminated union and record types, but not class, interface or struct types. -These attributed are ignored in F# plain text formatting, but it can be useful to implement +These attributes are ignored in F# plain text formatting, but it can be useful to implement these methods to improve displays when debugging F# types. ## See also From d8cb5187f9e0544ea3db06a949e83f61b926154d Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:45:17 +0100 Subject: [PATCH 36/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index ea10c2cf8504d..e4c26c58e3379 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -422,7 +422,7 @@ for details. Debuggers for .NET respect the use of attributes such as `DebuggerDisplayAttribute` and `DebuggerTypeProxyAttribute` and these affect the structured display of objects in debugger inspection windows. The F# compiler automatically generated these attributes for discriminated union and record types, but -not class, interface or struct types. +not class, interface, or struct types. These attributes are ignored in F# plain text formatting, but it can be useful to implement these methods to improve displays when debugging F# types. From c36d032dcec75339e2022d3628cfd95c32021f34 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:45:34 +0100 Subject: [PATCH 37/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index b827fff85bad6..bd88f11813ed4 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -5,7 +5,7 @@ ms.date: 07/22/2020 --- # F# Interactive options -This topic describes the command-line options supported by F# Interactive, `fsi.exe`. F# Interactive accepts many of the same command line options as the F# compiler, but also accepts some additional options. +This article describes the command-line options supported by F# Interactive, `fsi.exe`. F# Interactive accepts many of the same command line options as the F# compiler, but also accepts some additional options. ## Using F# Interactive for scripting From 2fa71781a7c35bec9fb41a9b2308f641fbb24b20 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:45:42 +0100 Subject: [PATCH 38/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index bd88f11813ed4..d9d892bde7fc9 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -57,7 +57,7 @@ Where lists appear in F# Interactive option arguments, list elements are separat |**--warnaserror**[**+**|**-**]|Same as the **fsc.exe** compiler option. For more information, see [Compiler Options](compiler-options.md).| |**--warnaserror**[**+**|**-**]:**<int-list>**|Same as the **fsc.exe** compiler option. For more information, see [Compiler Options](compiler-options.md).| -## F# Interactive Structured Printing +## F# Interactive structured printing F# Interactive (`dotnet fsi`) uses an extended version of [structured plain text formatting](plaintext-formatting.md) to report values. From 9b655f795f6351528b78a7213b28de929b6c49f2 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:45:58 +0100 Subject: [PATCH 39/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index d9d892bde7fc9..81b93e05e40a3 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -92,7 +92,7 @@ fsi.ShowIEnumerable <- false // Control whether sequence values are expanded by fsi.ShowDeclarationValues <- false // Control whether values are shown for declaration outputs ``` -### Customizing F# Interactive structured printing with `AddPrinter` and `AddPrintTransformer` +### Customize with `AddPrinter` and `AddPrintTransformer` Printing in F# Interactive outputs can be customized by using `fsi.AddPrinter` and `fsi.AddPrintTransformer`. The first gives text to replace the printing of an object, the second returns a surrogate object to display From b3db8eea1276d9f8b051ee813b10429221de12c3 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:46:23 +0100 Subject: [PATCH 40/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 81b93e05e40a3..ddaefcaa5ee70 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -95,7 +95,7 @@ fsi.ShowDeclarationValues <- false // Control whether values are shown for decla ### Customize with `AddPrinter` and `AddPrintTransformer` Printing in F# Interactive outputs can be customized by using `fsi.AddPrinter` and `fsi.AddPrintTransformer`. -The first gives text to replace the printing of an object, the second returns a surrogate object to display +The first function gives text to replace the printing of an object. The second function returns a surrogate object to display instead. For example, consider the following F# code: ```fsharp From 6288d9567d24a7dd7f2009a7fcbb2627b01a3913 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:46:36 +0100 Subject: [PATCH 41/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index e4c26c58e3379..89d1ab02dff40 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -415,7 +415,6 @@ Now ToString gives: F# Interactive (`dotnet fsi`) uses an extended version of structured plain text formatting to report values and allows additional customizability. See [F# Interactive](fsharp-interactive-options.md) -for details. ## Customize debug displays using `DebuggerDisplayAttribute`, `DebuggerTypeProxyAttribute`, and other attributes From f1ed1d66ae6ac845948f158b9d8cfe8a0d11e5b2 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:46:48 +0100 Subject: [PATCH 42/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 89d1ab02dff40..4c36b3b50eaec 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -416,7 +416,7 @@ Now ToString gives: F# Interactive (`dotnet fsi`) uses an extended version of structured plain text formatting to report values and allows additional customizability. See [F# Interactive](fsharp-interactive-options.md) -## Customize debug displays using `DebuggerDisplayAttribute`, `DebuggerTypeProxyAttribute`, and other attributes +## Customize debug displays Debuggers for .NET respect the use of attributes such as `DebuggerDisplayAttribute` and `DebuggerTypeProxyAttribute` and these affect the structured display of objects in debugger inspection windows. From 8e1e9bb2b85f495b5491eb6de9aa142dc2edb80d Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:47:00 +0100 Subject: [PATCH 43/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 4c36b3b50eaec..2213d4924baf3 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -418,7 +418,7 @@ report values and allows additional customizability. See [F# Interactive](fsharp ## Customize debug displays -Debuggers for .NET respect the use of attributes such as `DebuggerDisplayAttribute` and `DebuggerTypeProxyAttribute` +Debuggers for .NET respect the use of attributes such as `DebuggerDisplayAttribute` and `DebuggerTypeProxyAttribute`, and these affect the structured display of objects in debugger inspection windows. The F# compiler automatically generated these attributes for discriminated union and record types, but not class, interface, or struct types. From a0d1bff4140d2979e28d34154789de5f7c6d14cb Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:47:17 +0100 Subject: [PATCH 44/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index ddaefcaa5ee70..91e106c70cd42 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -139,7 +139,7 @@ This outputs: val x : MyList = [1; 2; 3; 4; 5; 6; 7; 8; 9; 10] ``` -If the transformer function passed to `fsi.AddPrintTransformer` returns `null` then the print transformer is ignored. +If the transformer function passed to `fsi.AddPrintTransformer` returns `null`, then the print transformer is ignored. This can be used to filter any input value by starting with type `obj`. For example: ```fsharp From 4f678c71ee0dba7b307827fe2839554685eaa8b6 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:47:41 +0100 Subject: [PATCH 45/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 91e106c70cd42..7825cd8c8fbd5 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -7,7 +7,7 @@ ms.date: 07/22/2020 This article describes the command-line options supported by F# Interactive, `fsi.exe`. F# Interactive accepts many of the same command line options as the F# compiler, but also accepts some additional options. -## Using F# Interactive for scripting +## Use F# Interactive for scripting F# Interactive, `dotnet fsi`, can be launched interactively, or it can be launched from the command line to run a script. The command line syntax is From d94601f2fdfa59d6c5a638b192e25008cd1c14d7 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:47:53 +0100 Subject: [PATCH 46/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 2213d4924baf3..f926837229170 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -4,7 +4,7 @@ description: Learn how to use printf and other plain text formatting in F# appli ms.date: 07/22/2020 --- -# Plain Text Formatting +# Plain text formatting F# supports type-checked formatting of plain text using `printf`, `printfn`, `sprintf` and related functions. For example, From 8fed80c14fd61cc5b0d0f9d0a5d68f90ade7850b Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:48:08 +0100 Subject: [PATCH 47/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index f926837229170..9b7cf388d44ba 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -6,7 +6,7 @@ ms.date: 07/22/2020 # Plain text formatting -F# supports type-checked formatting of plain text using `printf`, `printfn`, `sprintf` and related functions. +F# supports type-checked formatting of plain text using `printf`, `printfn`, `sprintf`, and related functions. For example, ```console From 0d5302057ac0e6d568faa6eae9edbafd45948489 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:48:26 +0100 Subject: [PATCH 48/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 9b7cf388d44ba..6c1b628a08e91 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -22,7 +22,7 @@ Hello world, 2 + 2 is 4 ``` F# also allows structured values to be formatted as plain text. -For example, consider the following and note how the output has been formatted as a matrix-like display of tuples. +For example, consider the following example that formats the output as a matrix-like display of tuples. ```console dotnet fsi From a2e234a7ffeb488588714ef68b15f11b1882c686 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:48:38 +0100 Subject: [PATCH 49/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 6c1b628a08e91..9a0ed9b64b854 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -37,7 +37,7 @@ dotnet fsi ``` Structured plain text formatting is activated when you use the `%A` format in `printf` formatting strings. -and also when formatting the output of values in F# interactive, where the output includes extra information and is additionally customizable. +It's also activated when formatting the output of values in F# interactive, where the output includes extra information and is additionally customizable. Plain text formatting is also observable through any calls to `x.ToString()` on F# union and record values, including those that occur implicitly in debugging, logging and other tooling. From fe274527491081cc86d8183d008cb4f68a20693a Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:48:51 +0100 Subject: [PATCH 50/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 9a0ed9b64b854..c0e461bb5a011 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -39,7 +39,7 @@ dotnet fsi Structured plain text formatting is activated when you use the `%A` format in `printf` formatting strings. It's also activated when formatting the output of values in F# interactive, where the output includes extra information and is additionally customizable. Plain text formatting is also observable through any calls to `x.ToString()` on F# union and record values, including those -that occur implicitly in debugging, logging and other tooling. +that occur implicitly in debugging, logging, and other tooling. ## Checking of `printf`-format strings From eab81f92bfc1bf290ceef60fd7e3cbb6b9ce8b81 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:49:58 +0100 Subject: [PATCH 51/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index c0e461bb5a011..08d0085805138 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -59,7 +59,7 @@ gives the output stdin(3,25): error FS0001: The type 'string' does not match the type 'int' ``` -Technically speaking, when using `printf` and other related functions a special rule in the F# compiler +Technically speaking, when using `printf` and other related functions, a special rule in the F# compiler checks the string literal passed as the format string, ensuring the subsequent arguments applied are of the correct type to match the format specifiers used. From 70c498a8aa72605b4516a10739c0a1a5c3df1ade Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:50:09 +0100 Subject: [PATCH 52/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 08d0085805138..491ad5cf11751 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -63,7 +63,7 @@ Technically speaking, when using `printf` and other related functions, a special checks the string literal passed as the format string, ensuring the subsequent arguments applied are of the correct type to match the format specifiers used. -## Format Specifiers for `printf` +## Format specifiers for `printf` Format specifications for `printf` formats are strings with `%` markers indicating format. Format placeholders consist of `%[flags][width][.precision][type]` where the type is interpreted as follows: From 7ec62a5da038a5223a627922173fed4231a2b654 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:50:24 +0100 Subject: [PATCH 53/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 491ad5cf11751..4931c34be07eb 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -65,7 +65,7 @@ the correct type to match the format specifiers used. ## Format specifiers for `printf` -Format specifications for `printf` formats are strings with `%` markers indicating format. Format placeholders consist of `%[flags][width][.precision][type]` +Format specifications for `printf` formats are strings with `%` markers that indicate format. Format placeholders consist of `%[flags][width][.precision][type]` where the type is interpreted as follows: | Format specifier | Type(s) | Remarks | From 298fe9695a0ac228418c3d16056458570f3dc35f Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:50:51 +0100 Subject: [PATCH 54/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 4931c34be07eb..1245fb2b10a2a 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -84,7 +84,7 @@ where the type is interpreted as follows: | `%O` | any value | Formatted by boxing the object and valling its `System.Object.ToString()` method | | `%A` | any value | Formatted using [structured plain text formatting](plaintext-formatting.md) with the default layout settings | | `%a` | any value | Requires two arguments - a formatting function accepting a context parameter and the value, and the particular value to print | -| `%t` | any value | Requires one argument, a formatting function accepting a context parameter which either outputs or returns the appropriate text | +| `%t` | any value | Requires one argument, a formatting function accepting a context parameter that either outputs or returns the appropriate text | Basic integer types are `byte` (`System.Byte`), `sbyte` (`System.SByte`), `int16` (`System.Int16`), `uint16` (`System.UInt16`), `int32` (`System.Int32`), `uint32` (`System.UInt32`), `int64` (`System.Int64`), `uint64` (`System.UInt64`), `nativeint` (`System.IntPtr`)and `unativeint` (`System.UIntPtr`). Basic floating point types are `float` (`System.Double`) and `float32` (`System.Single`). From 569642d7b6880164d0ee50d10061c087ba50926c Mon Sep 17 00:00:00 2001 From: Don Syme Date: Thu, 30 Jul 2020 20:51:01 +0100 Subject: [PATCH 55/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 1245fb2b10a2a..76d418f4389be 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -86,7 +86,7 @@ where the type is interpreted as follows: | `%a` | any value | Requires two arguments - a formatting function accepting a context parameter and the value, and the particular value to print | | `%t` | any value | Requires one argument, a formatting function accepting a context parameter that either outputs or returns the appropriate text | -Basic integer types are `byte` (`System.Byte`), `sbyte` (`System.SByte`), `int16` (`System.Int16`), `uint16` (`System.UInt16`), `int32` (`System.Int32`), `uint32` (`System.UInt32`), `int64` (`System.Int64`), `uint64` (`System.UInt64`), `nativeint` (`System.IntPtr`)and `unativeint` (`System.UIntPtr`). +Basic integer types are `byte` (`System.Byte`), `sbyte` (`System.SByte`), `int16` (`System.Int16`), `uint16` (`System.UInt16`), `int32` (`System.Int32`), `uint32` (`System.UInt32`), `int64` (`System.Int64`), `uint64` (`System.UInt64`), `nativeint` (`System.IntPtr`), and `unativeint` (`System.UIntPtr`). Basic floating point types are `float` (`System.Double`) and `float32` (`System.Single`). The optional width is an integer indicating the minimal width of the result. For instance, `%6d` prints an integer, prefixing it with spaces From 834074810d1c3a5edcedd5b15ae5b18a56465418 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 02:58:52 +0100 Subject: [PATCH 56/78] Update index.md --- docs/fsharp/language-reference/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/fsharp/language-reference/index.md b/docs/fsharp/language-reference/index.md index 18d96c688f099..c0f7acf318ad6 100644 --- a/docs/fsharp/language-reference/index.md +++ b/docs/fsharp/language-reference/index.md @@ -45,6 +45,7 @@ The following table shows reference topics available that describe language conc |[Signatures](signature-files.md)|Describes signatures and signature files. A signature file contains information about the public signatures of a set of F# program elements, such as types, namespaces, and modules. It can be used to specify the accessibility of these program elements.| |[XML Documentation](xml-documentation.md)|Describes support for generating documentation files for XML doc comments, also known as triple slash comments. You can produce documentation from code comments in F# just as in other .NET languages.| |[Verbose Syntax](verbose-syntax.md)|Describes the syntax for F# constructs when lightweight syntax is not enabled. Verbose syntax is indicated by the `#light "off"` directive at the top of the code file.| +|[Plain Text Formatting](plaintext.md)|Learn how to use sprintf and other plain text formatting in F# applications and scripts.| ## F# Types From 8c133dd44aab85969d541549045baa986f5e9eb4 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:00:14 +0100 Subject: [PATCH 57/78] Update toc.yml --- docs/fsharp/toc.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/fsharp/toc.yml b/docs/fsharp/toc.yml index 0af790dc9575c..a71b37f9d5a7c 100644 --- a/docs/fsharp/toc.yml +++ b/docs/fsharp/toc.yml @@ -226,6 +226,8 @@ href: language-reference/signature-files.md - name: Units of Measure href: language-reference/units-of-measure.md + - name: Plain Text Formatting + href: language-reference/plaintext-formatting.md - name: XML Documentation href: language-reference/xml-documentation.md - name: Lazy Expressions From 45de888dcdd5c6a5d034de36f42ca794e6fcb260 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:00:39 +0100 Subject: [PATCH 58/78] Update index.md --- docs/fsharp/language-reference/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/index.md b/docs/fsharp/language-reference/index.md index c0f7acf318ad6..7f0edbe759636 100644 --- a/docs/fsharp/language-reference/index.md +++ b/docs/fsharp/language-reference/index.md @@ -45,7 +45,7 @@ The following table shows reference topics available that describe language conc |[Signatures](signature-files.md)|Describes signatures and signature files. A signature file contains information about the public signatures of a set of F# program elements, such as types, namespaces, and modules. It can be used to specify the accessibility of these program elements.| |[XML Documentation](xml-documentation.md)|Describes support for generating documentation files for XML doc comments, also known as triple slash comments. You can produce documentation from code comments in F# just as in other .NET languages.| |[Verbose Syntax](verbose-syntax.md)|Describes the syntax for F# constructs when lightweight syntax is not enabled. Verbose syntax is indicated by the `#light "off"` directive at the top of the code file.| -|[Plain Text Formatting](plaintext.md)|Learn how to use sprintf and other plain text formatting in F# applications and scripts.| +|[Plain Text Formatting](plaintext-formatting.md)|Learn how to use sprintf and other plain text formatting in F# applications and scripts.| ## F# Types From 4695c6486e14cf184196dc20f57aea62e7be538c Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Mon, 3 Aug 2020 19:42:43 -0700 Subject: [PATCH 59/78] Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- .../plaintext-formatting.md | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 76d418f4389be..8cc2edf95d9bc 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -96,14 +96,14 @@ Valid flags are: | Flag | Effect | Remarks | |:-------------------|:---------------|:-----------------------------| -| `0` | add zeros instead of spaces to make up the required width | | -| `-` | left justify the result within the width specified | | -| `+` | add a `+` character if the number is positive (to match a `-` sign for negatives) | | -| a space character | add an extra space if the number is positive (to match a '-' sign for negatives) | +| `0` | Add zeros instead of spaces to make up the required width | | +| `-` | Left justify the result within the specified width | | +| `+` | Add a `+` character if the number is positive (to match a `-` sign for negatives) | | +| space character | Add an extra space if the number is positive (to match a '-' sign for negatives) | The printf `#` flag is invalid and a compile-time error will be reported if it is used. -Values are formatted using invariant culture and culture settings are irrelevant to `printf` formatting except +Values are formatted using invariant culture. Culture settings are irrelevant to `printf` formatting except when they affect the results of `%O` and `%A` formatting. For more information, see [structured plain text formatting](plaintext-formatting.md). ## `%A` formatting @@ -166,7 +166,7 @@ Culture 2: 12/31/1999 12:00:00 AM ### `%A` formatting of structured values -When formatting plain text using the `%A` specifier, block indentation is used for F# lists and tuples. The is shown in the example above. +When formatting plain text using the `%A` specifier, block indentation is used for F# lists and tuples. The is shown in the previous example. The structure of arrays is also used, including multi-dimensional arrays. Single-dimensional arrays are shown with `[| ... |]` syntax. For example, ```fsharp @@ -181,7 +181,7 @@ produces (17, 289); (18, 324); (19, 361); (20, 400)|] ``` -A default print width of 80 is used. This can be customized by using a print width in the format specifier. For example, +The default print width is 80. This width can be customized by using a print width in the format specifier. For example, ```fsharp printfn "%10A" [| for i in 1 .. 5 -> (i, i*i) |] @@ -226,7 +226,7 @@ def"; "abc def"|] ``` -A depth limit of 4 is used for sequence (IEnumerable) values, which are shown as `seq { ...}`, and a depth limit of 100 is used for list and array values. +A depth limit of 4 is used for sequence (`IEnumerable`) values, which are shown as `seq { ...}`. A depth limit of 100 is used for list and array values. For example, ```fsharp @@ -254,7 +254,7 @@ produces Y = ["one"; "two"; "three"] } ``` -If `%+A` is used then the private structure of records and unions +If `%+A` is used, then the private structure of records and unions is also revealed by using reflection. For example ```fsharp @@ -295,7 +295,7 @@ let rec make n = if n = 0 then Tip else Node(Tip, make (n-1)) printfn "%A" (make 1000) ``` -produces a large output with some parts elided +produces a large output with some parts elided: ```console Node(Tip, Node(Tip, ....Node (..., ...)...)) @@ -323,7 +323,7 @@ Lazy values are printed as `Value is not created` or equivalent text when the va Null values are printed as `null` unless the static type of the value is determined to be a union type where `null` is a permitted represenation. -F# function values are printed as their internally generated closure name, for example ``. +F# function values are printed as their internally generated closure name, for example, ``. ### Customize plain text formatting with `StructuredFormatDisplayAttribute` @@ -350,11 +350,11 @@ Counts([0; 1; 2; 3; ### Customize plain text formatting by overriding `ToString` -The default implementation of `x.ToString()` is observable in F# programming. Often the default results -are not suitable for use in either programmer-facing information display nor user output, and as a result it +The default implementation of `x.ToString()` is observable in F# programming. Often, the default results +aren't suitable for use in either programmer-facing information display or user output, and as a result it is common to override the default implementation. -By default F# record and union types override the implementation of `x.ToString()` with an implementation that +By default, F# record and union types override the implementation of `x.ToString()` with an implementation that uses `sprintf "%+A"`. For example, ```fsharp @@ -411,10 +411,10 @@ Now ToString gives: [MyClassType([1; 2; 3; 4; 5]); MyClassType([1; 2; 3; 4; 5])] ``` -## F# Interactive Structured Printing +## F# Interactive structured printing F# Interactive (`dotnet fsi`) uses an extended version of structured plain text formatting to -report values and allows additional customizability. See [F# Interactive](fsharp-interactive-options.md) +report values and allows additional customizability. For more information, see [F# Interactive](fsharp-interactive-options.md). ## Customize debug displays From 1e20bb00cafab584e15b43e173cbd3bece1f0371 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:51:59 +0100 Subject: [PATCH 60/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 8cc2edf95d9bc..e281152327083 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -110,7 +110,7 @@ when they affect the results of `%O` and `%A` formatting. For more information, The `%A` format specifier is used to format values in a human-readable way, and can also be useful for reporting diagnostic information. -### `%A` formatting of primitive values +### Primitive values When formatting plain text using the `%A` specifier, F# numeric values are formatted with their suffix and invariant culture. Floating point values are formatted using From c3f48b16f6d214a7eefb8092f147c8c7b8c3f3a8 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:52:20 +0100 Subject: [PATCH 61/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index e281152327083..2a14c99b4e8c3 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -140,7 +140,7 @@ produces c"d") ``` -### `%A` formatting of .NET values +### .NET values When formatting plain text using the `%A` specifier, non-F# .NET objects are formatted by using `x.ToString()` using the default settings of .NET given by `System.Globalization.CultureInfo.CurrentCulture` and `System.Globalization.CultureInfo.CurrentUICulture`. For example, From 0d3a1f1f4b9ec496f5df13a77f34967ab76f498f Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:52:33 +0100 Subject: [PATCH 62/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 2a14c99b4e8c3..51af9eaf5d04d 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -164,7 +164,7 @@ Culture 1: 31.12.1999 00:00:00 Culture 2: 12/31/1999 12:00:00 AM ``` -### `%A` formatting of structured values +### Structured values When formatting plain text using the `%A` specifier, block indentation is used for F# lists and tuples. The is shown in the previous example. The structure of arrays is also used, including multi-dimensional arrays. Single-dimensional arrays are shown with `[| ... |]` syntax. For example, From 154546316e2a7ea25ef8bef6672e542105ff343f Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:52:46 +0100 Subject: [PATCH 63/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 51af9eaf5d04d..10c1c89185952 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -260,7 +260,7 @@ is also revealed by using reflection. For example ```fsharp type internal R = { X : int list; Y : string list } - override x.ToString() = "R" + override _.ToString() = "R" let internal data = { X = [ 1;2;3 ]; Y = ["one"; "two"; "three"] } From 0257abb9f5fca44573f311a2330e523c6aa93d72 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:52:59 +0100 Subject: [PATCH 64/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 10c1c89185952..f85526db07233 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -281,7 +281,7 @@ internal view: Y = ["one"; "two"; "three"] } ``` -### `%A` formatting of large, cyclic, or deeply nested values +### Large, cyclic, or deeply nested values Large structured values are formatted to a maximum overall object node count of 10000. Deeply nested values are formatted to a depth of 100. In both cases `...` is used From d46d1c8a8a0aacb1eb2da65111b5b224c9ad7ac9 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:53:12 +0100 Subject: [PATCH 65/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index f85526db07233..b8d86ed8d267d 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -288,7 +288,9 @@ Deeply nested values are formatted to a depth of 100. In both cases `...` is us to elide some of the output. For example, ```fsharp -type Tree = Node of Tree * Tree | Tip +type Tree = + | Tip + | Node of Tree * Tree let rec make n = if n = 0 then Tip else Node(Tip, make (n-1)) From 8e34ab8029c0ff05150911a029ee2812e3095fb0 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:53:25 +0100 Subject: [PATCH 66/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index b8d86ed8d267d..d9b4eb68f30e3 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -292,7 +292,11 @@ type Tree = | Tip | Node of Tree * Tree -let rec make n = if n = 0 then Tip else Node(Tip, make (n-1)) +let rec make n = + if n = 0 then + Tip + else + Node(Tip, make (n-1)) printfn "%A" (make 1000) ``` From 1be9163860e8d0a66b135fcbabd1171e6cb8c7e1 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:53:41 +0100 Subject: [PATCH 67/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index d9b4eb68f30e3..84e01dbe0fd6c 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -322,7 +322,7 @@ produces { Links = [...] } ``` -### `%A` formatting of lazy, null, and function values +### Lazy, null, and function values Lazy values are printed as `Value is not created` or equivalent text when the value has not yet been evaluated. From 41e0ae67ba7638a28bbc6d7b7b34da3872409228 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:53:55 +0100 Subject: [PATCH 68/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 84e01dbe0fd6c..be41e77a65edf 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -331,7 +331,7 @@ a permitted represenation. F# function values are printed as their internally generated closure name, for example, ``. -### Customize plain text formatting with `StructuredFormatDisplayAttribute` +### Customize plain text formatting with `StructuredFormatDisplay` When using the `%A` specifier, the presence of `StructuredFormatDisplayAttribute` on type declarations is respected. This can be used to specify surrogate text and property to display a value. For example: From 7c179364e46d868de92c5da8ee38d97f2d174cf6 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:54:13 +0100 Subject: [PATCH 69/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index be41e77a65edf..0d35febe8b24c 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -333,7 +333,7 @@ F# function values are printed as their internally generated closure name, for e ### Customize plain text formatting with `StructuredFormatDisplay` -When using the `%A` specifier, the presence of `StructuredFormatDisplayAttribute` on type declarations is respected. This can +When using the `%A` specifier, the presence of the `StructuredFormatDisplay` attribute on type declarations is respected. This can be used to specify surrogate text and property to display a value. For example: ```fsharp From 035ab50ae03c48fbc549f9c86358f10e4b6d55fc Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:54:26 +0100 Subject: [PATCH 70/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 0d35febe8b24c..82c0e55487921 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -356,7 +356,7 @@ Counts([0; 1; 2; 3; ### Customize plain text formatting by overriding `ToString` -The default implementation of `x.ToString()` is observable in F# programming. Often, the default results +The default implementation of `ToString` is observable in F# programming. Often, the default results aren't suitable for use in either programmer-facing information display or user output, and as a result it is common to override the default implementation. From ff561d08b48d7b500f3fdcd3342aa5fbdd9ce708 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:54:39 +0100 Subject: [PATCH 71/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 82c0e55487921..8174b899000ca 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -360,7 +360,7 @@ The default implementation of `ToString` is observable in F# programming. Often, aren't suitable for use in either programmer-facing information display or user output, and as a result it is common to override the default implementation. -By default, F# record and union types override the implementation of `x.ToString()` with an implementation that +By default, F# record and union types override the implementation of `ToString` with an implementation that uses `sprintf "%+A"`. For example, ```fsharp From e2e95976dcb029edd6bc6ad6440d6e929a53a8db Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:54:53 +0100 Subject: [PATCH 72/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 8174b899000ca..97ad365eab304 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -375,7 +375,7 @@ produces { Clicks = [0; 1; 2; 3; 4; 5; 6; 7; 8; 9; 10] } ``` -For class types, no default implementation of `ToString()` is provided and the .NET default is used, which reports the +For class types, no default implementation of `ToString` is provided and the .NET default is used, which reports the name of the type. For example, ```fsharp From 6110a823348502fe1cbb4dec9b7edf7cf3341ff1 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:55:05 +0100 Subject: [PATCH 73/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 97ad365eab304..a36b17c0731aa 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -380,7 +380,7 @@ name of the type. For example, ```fsharp type MyClassType(clicks: int list) = - member x.Clicks = clicks + member _.Clicks = clicks let data = [ MyClassType([1..5]); MyClassType([1..5]) ] printfn "Default structured print gives this:\n%A" data From 1e3c523a0d333ea8b971e037cf463755ddf4cd6b Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:55:17 +0100 Subject: [PATCH 74/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index a36b17c0731aa..87d3937f37b65 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -396,7 +396,7 @@ Default ToString gives: [MyClassType; MyClassType] ``` -Adding an override for `ToString()` can give better formatting. +Adding an override for `ToString` can give better formatting. ```fsharp type MyClassType(clicks: int list) = From 512cdc9552cbd3123aff9c4d56a51a96765cf7e0 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:55:30 +0100 Subject: [PATCH 75/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 87d3937f37b65..8e2b1e5800d28 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -400,8 +400,8 @@ Adding an override for `ToString` can give better formatting. ```fsharp type MyClassType(clicks: int list) = - member x.Clicks = clicks - override x.ToString() = sprintf "MyClassType(%0A)" clicks + member _.Clicks = clicks + override _.ToString() = sprintf "MyClassType(%0A)" clicks let data = [ MyClassType([1..5]); MyClassType([1..5]) ] printfn "Now structured print gives this:\n%A" data From a456db990700624eeb5aa4323a1aee416a9f5404 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 03:55:42 +0100 Subject: [PATCH 76/78] Update docs/fsharp/language-reference/plaintext-formatting.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/plaintext-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/plaintext-formatting.md b/docs/fsharp/language-reference/plaintext-formatting.md index 8e2b1e5800d28..02afef93d83f7 100644 --- a/docs/fsharp/language-reference/plaintext-formatting.md +++ b/docs/fsharp/language-reference/plaintext-formatting.md @@ -424,7 +424,7 @@ report values and allows additional customizability. For more information, see [ ## Customize debug displays -Debuggers for .NET respect the use of attributes such as `DebuggerDisplayAttribute` and `DebuggerTypeProxyAttribute`, +Debuggers for .NET respect the use of attributes such as `DebuggerDisplay` and `DebuggerTypeProxy`, and these affect the structured display of objects in debugger inspection windows. The F# compiler automatically generated these attributes for discriminated union and record types, but not class, interface, or struct types. From 301ef8eac59fdeff0704931674812fa5eec89880 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 04:21:14 +0100 Subject: [PATCH 77/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Phillip Carter --- .../language-reference/fsharp-interactive-options.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index 7825cd8c8fbd5..eead39bd59e6c 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -104,12 +104,12 @@ open System fsi.AddPrinter(fun dt -> dt.ToString("s")) type DateAndLabel = - { Date : DateTime - Label : string } + { Date: DateTime + Label: string } let newYearsDay1999 = - { Date = DateTime(1999, 1, 1) - Label = "New Year" } + { Date = DateTime(1999, 1, 1) + Label = "New Year" } ``` If you execute the example in F# Interactive, it outputs based on the formatting option set. In this case, it affects the formatting of date and time: From 9fd796d6c42b7daf0d9dfad4cd99d8f12f3c2ff8 Mon Sep 17 00:00:00 2001 From: Don Syme Date: Tue, 4 Aug 2020 04:21:25 +0100 Subject: [PATCH 78/78] Update docs/fsharp/language-reference/fsharp-interactive-options.md Co-authored-by: Phillip Carter --- docs/fsharp/language-reference/fsharp-interactive-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/language-reference/fsharp-interactive-options.md b/docs/fsharp/language-reference/fsharp-interactive-options.md index eead39bd59e6c..b17f86b95f1ee 100644 --- a/docs/fsharp/language-reference/fsharp-interactive-options.md +++ b/docs/fsharp/language-reference/fsharp-interactive-options.md @@ -126,7 +126,7 @@ val newYearsDay1999 : DateAndLabel = { Date = 1999-01-01T00:00:00 ```fsharp type MyList(values: int list) = - member x.Values = values + member _.Values = values fsi.AddPrintTransformer(fun (x:MyList) -> box x.Values)