RFC FS-1125 - print and println functions

[albert-du]

implements RFC FS-1125, fsharp/fslang-suggestions#1092

Adds print and println functions with examples.

[Happypig375]

Since these functions would likely be the first functions beginners encounter, the XML documentation should either avoid use of technical jargon such as stdout or explain what that is. Also, should tests be included with these two functions?

[albert-du]

I changed the xml docs to remove references to stdout

[brianrourkeboll]

Since these functions would likely be the first functions beginners encounter, the XML documentation should either avoid use of technical jargon such as stdout or explain what that is. Also, should tests be included with these two functions?

Note that printf and printfn already do mention stdout, while eprintf and eprintfn mention stderr—perhaps it's better to maintain consistency with these and use stdout for the new functions as well instead of switching to console.

[Happypig375]

Since these functions would likely be the first functions beginners encounter, the XML documentation should either avoid use of technical jargon such as stdout or explain what that is. Also, should tests be included with these two functions?

Note that printf and printfn already do mention stdout, while eprintf and eprintfn mention stderr—perhaps it's better to maintain consistency with these and use stdout for the new functions as well instead of switching to console.

In that case, an explanation of what stdout is would be desirable.

[abelbraaksma]

@albert-du, I believe it is customary to mention the RFC also in the title of the PR (something like: RFC 1015: implementing print and println), this way, once it gets merged, it will be directly clear from the log what was implemented. Great work btw!

[albert-du]

@abelbraaksma Thank you!

[albert-du]

I adjusted the wording on the xml docs to add a remark describing stdout, it may need more depth but should suffice for a basic explanation.

[Happypig375]

Remarks won't be visible in Visual Studio tooltips though.

[albert-du]

Remarks won't be visible in Visual Studio tooltips though.

Did not know that, @Happypig375 any idea how it should be done?

[Happypig375]

Probably as part of summary.

[vzarytovskii]

That looks good to me.

One thought is that maybe in some future PR we can unify it to use printf, and have the latter to accept both plain string and format (via the when guards with type matches?).

Cc @KevinRansom@dsyme

[Happypig375]

@vzarytovskii Currently let a = printf infers a function taking PrintfFormat and I don't see it changing.

[KevinRansom]

@albert-du

Hey I was wondering, why it is restricted to strings, especially since TextWriter has a bunch of useful strongly typed overrides.

Did you consider a design looking like this:

open System
module PrintStuff =
let print<'T> (v'T) =
Console.Out.Write(v)
let println<'T> (v:'T) =
Console.Out.WriteLine(v)

The sig file looks like:
[<CompiledName("Print")>]
val print<'T>: v:'T -> unit

[<CompiledName("PrintLine")>]
val println<'T>: v:'T -> unit

Which would be really terribly useful like this:

module test =
PrintStuff.println $"{1} is not {2} see {1 <> 2}"
PrintStuff.println true
PrintStuff.println "one"
PrintStuff.println 1
PrintStuff.println 1.1

let x = 7.5
PrintStuff.println x

Produces output looking like:

C:\Temp\abc>Program.exe
1 is not 2 see True
True
one
1
1.1
7.5

You can print some blank lines using:
PrintStuff.println ()
PrintStuff.println ()
PrintStuff.println ()
PrintStuff.println ()
PrintStuff.println ()

[Happypig375]

@KevinRansom One problem of that would be being easier to fall into the trap of globalization variances.

[KevinRansom]

@KevinRansom One problem of that would be being easier to fall into the trap of globalization variances.

This is what I see:, it looks like it is obeying international rules pretty much how I would expect:, am I missing something?

And this is fsi

C:\Program Files\Microsoft Visual Studio\2022\Community>fsi
Microsoft (R) F# Interactive version 12.0.4.0 for F# 6.0
Copyright (c) Microsoft Corporation. All Rights Reserved.
For help type #help;;
> open System
- open System.Globalization
-
- let println<'T> (v:'T) =
- Console.Out.WriteLine(v)
-
-
- let date = new DateTime(2000, 1, 2)
- let number = 12345.6789
-
- System.Threading.Thread.CurrentThread.CurrentCulture <- new CultureInfo("de-DE")
- println "FSharp - DE"
- println date // 02.01.2000 00:00:00
- println number // 12.345,68 ?
-
- println "FSharp - US"
- System.Threading.Thread.CurrentThread.CurrentCulture <- new CultureInfo("us-US")
- println date // 02.01.2000 00:00:00
- println number // 12.345,68 ?
- ;;
FSharp - DE
02.01.2000 00:00:00
12345,6789
FSharp - US
01/02/2000 00:00:00
12345.6789
val println: v: 'T -> unit
val date: System.DateTime = 01/02/2000 00:00:00
val number: float = 12345.6789
val it: unit = ()
>

[Happypig375]

@KevinRansom That's what I mean: globalization will be implicit and will be unexpected for beginners, as that is not how corresponding code is written.

[abelbraaksma]

@Happypig375, as long as internally the string version is used, everything will be output without globalisation, as that uses CultureInfo.InvariantCulture. In other words, that can be used to fix these overloads if needed.

This principle of least surprise and idempotency regardless where your code runs is, I believe, one of the underpinnings of F#. So, if we use @KevinRansom’s suggestion, I think that’s the way to go.

This would also give better predictability, as we won’t rely on any changes to Console.WriteLine.

[KevinRansom]

I may have lost the thread somehow. Are we suggesting that the globalization mechanisms built into the CLR are wrong and should be avoided?

[abelbraaksma]

I guess coding guidelines that demand .Net framework style formatting is the way to go

We (at my current company) actually have a coding guideline for the opposite. Use F# type-safe formatting (i.e., use $"Price: %f{x}", not $"Price: {x}"). If we need localization, we require programmers to be explicit about it, i.e. by using ToString() overloads. But in 99% of coding I've seen, auto-localization leads to bugs and (even in the .NET Framework days) opted for a policy to diligently use InvariantCulture and specific formatting strings as much as possible, unless specific cultures (i.e. for user-facing screens or something) was warranted.

This was a rabbit hole, I now wish I had never jumped in.

Yeah, it's a tricky mess. I've fallen for the trap in your "code review" example many times. Just as often I asked a programmer (from USA): "how do you think this will render on my machine, you think your test will pass"? Since I'm in NL, it often won't.

oops you used printf style formats, it may not work the way you expect in other locales.

The real question is: what do people expect? Most people are surprised that auto-internationalization is even a thing. If you write an English website, you don't want the numbers and dates to be localized in the native language of the user. And yes, this happens a lot: accidentally localized pages :).

[abelbraaksma]

One other big pool of bugs with these pitfals: serialization. We just uncovered major bugs where some programmers hand-crafted JSON serialization. Little did they know that the string interpolation would make their output different, depending where the code ran. it wasn't machine-parsable anymore.

[abelbraaksma]

@albert-du, I see you are updating this, and the RFC. But I'm not sure if there's consensus. @KevinRansom, what do you think? @dsyme, TLDR: we ended up discussing print: 'T -> unit and println: 'T -> unit vs the current implementation of print: string -> unit and println: string -> unit.

Bottom line of that discussion is, if we go the 'T approach, would we follow the serialization semantics of string and/or printfn "%A" (or printfn "%O"), or would we follow the semantics of typed (similar to any of prinfn "%i" | printfn "%f" etc) or untyped string interpolation (similar to printfn "%O" most of the time)?

Differences are abound. I.e., do we want "None" and "Some 42" be output, or "" and "Some(42)" (the latter is the default of Console.Write). And do we want to use InvariantCulture (used in string and printfn) added or not (used only in untyped string interpolation)?

W.r.t Invariant Culture, if we do not go that route, it means that, just like Console.Write by itself would do, that the output differs depending where you are in the world. Most existing F# functions use Invariant Culture now (printfn, sprintf, typed string interpolation and string).

We could vote. Choices:

1. (vote 👍) As with string >> Console.Write. This is the same as #2 below, but with InvariantCulture.
2. (vote 😄) As with Console.Write (x: obj), i.e. null and None both become "" and Some x becomes "Some(42)". Output differs per locale. This is the same as untyped string interpolation: fun x -> $"{x}" >> Console.Write .
3. (vote ❤️) As with printfn "%A" >> Console.Write, i.e. null -> "<null>", "None -> "None" and Some 42 -> "Some 42". Has Invariant Culture. Floats are output using their simplest form: 42.1 -> "42.1".
4. (vote 🚀) As with printfn "%f >> Console.Write, i.e. type-directed. Has Invariant Culture. Differs slightly for individual type, i.e. floats are output with 6 significant digits.
5. (vote: 😕) Stick with current implementation, i.e., require a string. This is let print (x: string) = Console.Write.

[dsyme]

Please note that ideally design discussion on the RFC would happen on the RFC discussion thread: fsharp/fslang-design#675

Still, let's continue here for now

[dsyme]

The approved RFC was for print: string -> unit. The discussion here led to a proposed change to

valprint:'T ->unit

I don't think we can realistically make this change. A generic print raises a huge number of issues - most of them touched on above - thank you to @abelbraaksma for the detailed knowledge on this

• localization
• correspondence with %A
• whether multi-line output is used by default and line-width if it is
• printing of null values
• printing of option values

Plus there's the problem that the generic functions are just less safe - e.g. you can easily end up printing an unapplied function value, which results in nothing useful, just some garbage ToString of a closure type.

I honestly think it's print: string -> unit or nothing. The user must then clarify the intent by various means.

---

Aside information about localization, please follow up at fsharp/fslang-suggestions#897

The design intent of FSharp.Core functionality has always been "use invariant culture unless explicitly specificed otherwise".

• This rule is kept by %d, %f and friends which always use InvariantCulture

• This rule is kept by string x which always uses InvariantCulture for IFormattable values.

• This rule is generally kept by %A. The intent here is to always use invariant culture - this is reasonable as it's main use is in debugging output for structured data. However, a long standing omission is that %A uses .ToString() for .NET IFormattable types that are not well known to FSharp.Core. This is noted in the documentation but means there is a discrepency between string and %A for things like System.DateTime. I actually think we should fix this and make %A always use InvariantCulture for IFormattable values, just like string does. The spec of %A has changed a little from time to time and since it is human-facing output I think it is correct to make it more consistently invariant culture.

• This rule is broken by %O and unadorned string interpolation $"...{x}..." which always uses obj.ToString() which in turn will generally use .NET localization. It is definitely arguable that this should have used invariant culture but I believe the breaking change is too significant to change this. It also means %O and unadorned string interpolation are the primary way to implicitly get localized output.

For visual outputs from F# Interactive, the user can specify fsi.FormatProvider but the default is InvariantCulture. An argument could be made that the default should be localized, but it isn't and I don't think we should change that now.

Some of these issues are captured here: fsharp/fslang-suggestions#897

Finally, I'm surprised it's never been suggested that %f, %A and friends take an option to pick up the current localization according to standard .NET rules, e.g. %$d, %$A (or some other character). There could also be a corresponding option to suppress it for %O, getting back to invariant, e.g. %-O or $"....%-O{x}....."

I'd encourage people to review https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/plaintext-formatting and contribute to it. There should really be a specific separate section on locales - there are mentions in the doc but a separate section should cover the above.

[albert-du]

I reverted the implementation back to the original rfc spec

[dsyme]

@albert-du This discussion has raised important questions. I'll do my best to capture these as unresolved questions in the text of the RFC.

I think it's best to put the implementation on hold until we resolve those design questions.

In private conversation Kevin is pretty adamant that the "use print to any data" scenario is under-represented in the discussion and that we shouldn't introduce a print taking just a string if we don't address this scenario - which would require solving the much larger and much harder question of "should print be generic and if so what is its specification". This is so fundamental that it will be hard to resolve it, and unfortunately we may need to put this RFC on ice.

This is partly my fault, because in the design process I didn't adequately predict or list out the scope of the unresolved issues in the RFC.

[charlesroddie]

The suggestion print:string -> unit adds simplicity to the beginner experience (since print is most commonly found in tutorials). It acknowledges that beginner tutorials and many F# users would prefer to use one word rather than Console.Write. It works nicely with interpolated strings and simplifies printf $"..." to print $"...", a much larger simplification than the removal of one character would suggest (the latter can be understood by almost anyone, and the former by almost no one).

A generic function would remove some of this simplicity for beginners. The type signature gets slightly more complex, and understanding what it does gets a lot more complex. It will add to the existing string and .ToString() and {...} and "%..." which do different things in ways that only a handful of people understand. It hides complexity behind and apparently simple form of words, and loses explicitness.

So I believe that print:string->unit would be an improvement in the language, but print:'a->unit would be worse than doing nothing.

[vzarytovskii]

The type signature gets slightly more complex, and understanding what it does gets a lot more complex.

I think it is something we can easily compensate this with good XML docs and examples.

The decision is tough because once the function is there (in FSharp.Core), there's no way back or no way of changing it, and it would be a shame if we waste such a great name for something we didn't give a good thought.

That's why we have to thing really good about it.

[jasiozet]

I completely understand that this need to be very well thought out, because
print
is such an iconic name, that we need to take a lot of things into account.

Fairly recently (less than year ago) I was a complete F# beginner and what I did use a lot when experimenting doing tutorials etc was:

let test = // something I was experimenting with
printfn "%A" test

That was my newbish console debugging, but to be honest I still do it from time to time.
I think that just enabling string is not doing very much:

printfn $""
vs
println $""
Are we really saving that much? This have even the same number of characters. Does this only improve HelloWorld example?
But at the same time I see that kinda the same can be said about Console.WriteLine

But I would actually want to open another angle of discussion.
If we are aiming at discoverability, ease of use for beginners, shouldn't we go with print adding newline character in the end like println. Kinda the way Python does this?

[bisen2]

I definitely agree with Vlad that this deserves careful consideration before making a change that might be regretted down the line. My apologies for having been a bit preemptive in submitting the RFC and letting it get to the point of implementation before these concerns came up.

Personally, I think that a generic print function in the style of the %A formatter would be the least surprising for newcomers. Needing to convert every other type into a string in order to print it will most likely circumvent all of the convenience of introducing the print function in the first place. If the print function is designed to be the most simple first printing function that a new user interacts with, it should behave in the least surprising way and then users can be directed towards printf/printfn in cases where they want more customization in how the formatting is done.

[NatElkins]

My expectation would be that print or println would be able to take anything in as a parameter. Basically act the same way as Console.WriteLine. Here's the signature in Kotlin:

I think it would be very frustrating to users (new and old alike) if only strings were permitted.

[charlesroddie]

@jasiozet This is how adding printn: string -> unit improves simplicity of code in your example. Note this advantage also applies to printn<'a>:'a -> unit. While not much changes in terms of diffs of characters, there is a large decrease in complexity of types involved from one to the next.

lettest=0
printfn "%A" test // `printfn` is `Printf.TextWriterFormat<int -> unit> -> int -> unit` and `"%A"` is `Printf.TextWriterFormat<int -> unit>`.
printfn $"{test}"// `printfn` is `Printf.TextWriterFormat<unit> -> unit` and `$"{test}"` is `Printf.TextWriterFormat<unit>`
printn $"{test}"// `printn` is `string -> unit` and `$"{test}"` is `string`.

Describing F# I would say that in F# you need to understand all the types involved and then the code will almost write itself.
The first two examples rather defeat the nature of F# in that they present beginners with code whose types are not intended to be fully understood.

@vzarytovskii I think it is something we can easily compensate this with good XML docs and examples.

It's possible but the string function and "%A" behaviour have been badly documented and understood (I believe @abelbraaksma has worked on identifying the behaviour of these recently). So there would need to be some dramatic improvement in documentation around this to add an extra function and make all of the functions clear.

A separate conversion to string step is more composed and explicit. But educationally, I believe understanding types fully is more important than understanding behaviour fully, so if users write print something and they don't know exactly what print does to create the string it's not all that bad as they probably just meant "print some representation of something" without needing to pin it down. So on reflection I'd rank add printn:string -> unit > add printn:'a -> unit > nothing.

[dsyme]

Some interesting feedback here: fsharp/fslang-suggestions#1092 (comment)

[dsyme]

I'm now pretty convinced that if we add anything for print, it should be a generic print function of some form.

I'll close this, as the implementation would be very different

@albert-du I want to thank you again for your contribution and apologise for approving the "string" suggestion before taking into account enough points of view. This is on me, and we're immensely grateful for you taking the time to engage with this.

[ShalokShalom]

And where do we track the new implementation?

[abelbraaksma]

@ShalokShalom, it’s a little bit all over the place, and some of it is captured in the RFC as unresolved questions (linked in the description).

The discussion about the RFCs and to records decisions should go here: fsharp/fslang-design#675.

Some discussion has happened in the original suggestion (linked from RFC) and in this thread (also linked from RFC). There’s also a wider encompassing suggestion to overhaul the text output printing and formatting stuff: fsharp/fslang-suggestions#897.

[abelbraaksma]

@ShalokShalom (been a while, lol), I'm trying to spark renewed interest in this comment thread: fsharp/fslang-design#675 (comment)