Tutorial on Polymorphic Variants

[cuihtlauac]

Polymorphic variants deserve a tutorial supplementing documentation from the manual and gathering information spread in the mailing list, discuss and blog posts.

Here is the outline:

1. Introduction and historical notes
2. A First Example
3. Exact, Closed and Open Variants
4. Subtyping
5. Named Polymorphic Variants
6. Advanced: Alised, Parametrized and Recursive Polymorphic Variabnts
7. Advanced: Combining Polymorphic Variants and Simple Variants
8. Uses-Cases
9. Drawbacks
10. When to Use Polymorphic Variants
11. Conclusions & References

[christinerose]

Apologies, this commit ^^ is through li. 65.

[leostera]

Love this bits of trivia <3 but I'd put them all the way at the end of the tutorial. Almost an appendix for those that are interested in deepening the context in which polyvars where created.

[cuihtlauac]

Agreed. Your feedback on this is consistent with the discuss thread; it will go at the end of the document.

[leostera]

Looking at the learning goals for this page, I'm not sure if this clarification helps me write/use/assess polyvars at all.

Feels like a "nice to know" but not a "must know" 🤔 – maybe it would fit better near ## When to Use Polymorphic Variant?

[Octachron]

I agree, if this section belongs to this tutorial, it is not at its place.

[cuihtlauac]

Your suggestion makes sense too. I'll do that.

[leostera]

Love prerequisites! ✨ I think I'd phrase it around skills/concepts rather than completed tutorials, and it could be placed right below the main title or in a dedicated section so the very first thing I notice is whether I need to learn something before digging into this tutorial.

[cuihtlauac]

It is hard to reach a consensus on this. Some want to have prerequisites as the very first thing. Others prefer to start with the learning goals. Ideally, both could be turned into metadata. That would allow more rendering options.

[leostera]

I think rather than preambling around LLMs or whether other kinds of types are also polymorphic (but meaning something different), I'd just immediately start building an intuition:

1. what is a polymorphic variant,
2. why would I want to use them,
3. and how to identify them.

A polymorphic variant is a more flexible kind of variant type that does not need
to be defined upfront, and is useful for working with groups of constructors
(we call them _tags_) that can grow or shrink.

When they are used to create values, you'll see them prefixed with a backtick:
`` `hello_world ``.

When they are used in type-signatures, you'll see them wrapped in square brackets:
 `` [ `hello_world ] ``.

The rest of the tutorial can then dig into these facets and make sure we go from an intuition to a proper understanding, including things like its origins or why the relationship between value and type may be different.

[cuihtlauac]

That seems consistent with the feedback in the discuss thread. A differently toned introduction is demanded. Let's write it.

[leostera]

An even smaller example we could use here is a list. I think it could cement the intuition that polyvars are closer to the data itself than to defined types:

# let my_favorite_fruits = [ `banana ];;
val my_favorite_fruits : [> `banana ] list

# let my_favorite_fruits = [ `banana; `apple ];;
val my_favorite_fruits : [> `apple | `banana ] list

# let my_favorite_fruits = [ `banana; `apple; `kiwi ];;
val my_favorite_fruits : [> `apple | `banana | `kiwi ] list

You could easily go from there to using polyvars that carry data:

# let my_favorite_fruits = [ `banana; `apple `green; `orange `blood; ];;
val my_favorite_fruits :
  [> `apple of [> `green ] | `banana | `orange of [> `blood ] ] list

[leostera]

This is the path I'd take when explaining them, starting from the smallest possible example and growing one step at a time:

1. `banana is of type [> `banana ]

2. if you put it together with other things that are their own type (`apple) then they form a larger type ([> `apple | `banana ])

3. if you use an argument like a polyvar in a function, then the input type gets formed by its usage:

# let f `hello = `world ;;
val f : [< `hello ] -> [> `world ] = <fun>

4. then we can explain > and <, the exact polyvar type, and what combinations like [> `name of string < `age of int ] mean

5. then we can introduce sharing

# let say_hi (`name name) = "hello, " ^ name;;
val say_hi : [< `name of string ] -> string

# let say_bye (`name name) = "goodbye, " ^ name;;
val say_bye : [< `name of string ] -> string

7. and upfront definitions to make the reuse cleaner

type name = [ `name of string ]

8. and now that you have a polyvar defined upfront, you can introduce composition

type name = [ `name of string ]
type age = [ `age of int ]
type attributes = [ name | age | `other of (string, string) ]

9. profit!

[leostera]

"but it also inhabits any type that contains it."

This is going to raise eyebrows. Inhabits alone is a term that confused the hell out of me for a long time.

I think if we build the intuition that `Broccoli is a value that belongs to the type [ > `Broccoli ] then it would make more sense that anywhere that we see `Broccoli in the type, then `Broccoli is a valid value.

Of course there's the case where `Broccoli belongs to [ > `Apple ] because of > but I'd leave > until we talk about polyvars as function inputs/outputs.

[cuihtlauac]

Agreed. The terminology I've used here is clumsy. This is needs to be rewritten.

[leostera]

"isn't a single type"

Not entirely sure if the idea that "in OCaml every value has a single type" (principality) has been hammered in by now in the tutorials, but if it has then this would be weird to read.

[cuihtlauac]

You're right again. This needs to be said differently.

[leostera]

Consider that if I jump into this section, I don't know where f came from or what it is. Keeping it self-contained should be okay since these examples are super small.

[cuihtlauac]

You are right. The document does not state explicitly examples are meant to be played in order and jumping into a section does not work. This needs to be clarified.

[leostera]

This section seems unnecessary if the remarks of the LLM hallucinating are removed.

[cuihtlauac]

Fair enough, it is just a remark.

[Octachron]

I don't understand what this paragraph is trying to explain.

First, since typecheckers are not the subject on the article, bringing type-checker algorithms only encourage the idea that you can only understand OCaml language if you are a type system expert .

Second, polymorphic variants are using the same type-checking algorithm that the rest of the language.

Third, None already belongs to multiple type, there is nothing special at this level with respect to the row type variable of objects or polymorphic variable.

I advocate to completely remove this paragraph.

[cuihtlauac]

I like the idea of an introduction that would list the practical features of polymorphic variants, from a developer's perspective. I agree it would be friendlier. What do you think of this ?

• Optional declaration
• Tag sharing
• Hash patterns

That creates a different, and probably better, learning track. It implies a large refactoring of the rest of the text, but I agree it's worth the effort.

I'm concerned about the relationship with simple variants. Some newcomers are puzzled by the resemblance-difference with polymorphic variants. Plenty of questions arise in relation to that.

[Octachron]

This paragraph should probably be a footnote except if the expected audience of the tutorial are student in a Programming Language class.

[cuihtlauac]

Agree. This is consistent with feedback in the discuss thread.

[Octachron]

This is misleading, consider None.

[cuihtlauac]

You're right. If we downplay the type-checking algorithm story, this will likely disappear.

[Octachron]

The simplest value with a structural in OCaml is probably let id x = x which doesn't fit this paragraph.

I am also still confused why we are speaking of a data structure that represent types? Why are the type system implementation details the focus of this paragraph?

[cuihtlauac]

Agreed.

[leostera]

"Only using polymorphic variants is over-engineering,"

I also don't recommend people to only use polyvars but I think we can do better and explain why.

For example, the type errors can get VERY out of hand.

Also not sure why reiterating the whole "not an extension, but equivalent" is relevant.

[cuihtlauac]

Do you have an example code triggering such type errors? I may be useful.

"not an extension, but equivalent": Yes, and that discussion will by downsized and what's left will move to the end of the document.

[leostera]

When you write "weaken type-checking" are you referring to having both a Gray and Grey tags? I assumed this was meant to be an example of an accident/typo, but I don't think its fair to call it "weakened type-checking".

Like the compiler isn't going to mistake Grey for Gray.

[cuihtlauac]

Like the compiler isn't going to mistake Grey for Gray.

But it would if it had been simple variants. That's the point. But I didn't say it explicitly, so that's on me.

[leostera]

Instead of a Conclusion i'd have a section that summarizes what was learned in this tutorial:

• We learned how to create new polymorphic variant tags
• We learned how to to constraint them
• We learned how to reuse tags
• We learned how to use polymorphic variants for flexible error handling
• etc

[cuihtlauac]

Yes, that's simpler.

[reynir]

I found some typos in the OCaml code.

[reynir]

I think let* is not defined in this snippet, and when defining it in the snippet below it may be worth linking to some text about the let* syntax(?)

[cuihtlauac]

You are right, the definition of let should move up. Links are also needed you are right

[tmattio]

I'm closing this as stalled. I've heard that a rewrite was in progress somewhere, but in the meantime, I'll close this. Feel free to re-open or open a new PR if you resume work on this.