I’m reading source code of OCaml projects and sometimes I see some interesting syntax overloading features.
For example, from the ocaml-non-empty-list package, I learned that you can overload the list literal syntax by naming your constructor as (::):
(** The non-empty list type. The use of the [( :: )] infix constructor
allows the usage of the built-in list syntactic sugar provided by OCaml.
For example, a singleton is given by [ [1] ]. A list containing 2 elements is given by
[ [1; 2] ]. *)
type 'a t = ( :: ) of 'a * 'a list [@@deriving eq, ord, show]
But for the love of my life, I can’t find any documentation about this syntax. My Google skills fail me on this one
Could you help me with some links?
Other syntax overloading features I found:
Overloading let+, and+, let*, and* (and more general let<op>)
I also often use this table from the manual to know the relative precedence of operators. It also serves me when I want to (re)define an operator: the first signs of the operator have an effect on the precedence.
As @polytypic said, this is not overloading, but a mere (re)binding of identifiers. Operator-like identifiers just happen to be treated differently by the parser.
You can also give operator-like names to type constructors, (edit: not really, see below) in which case there will some form of type-based disambiguation, true, but I wouldn’t call it overloading. I find it confusing as it brings to mind C++ where you can overload any function, which is definitely not the case in OCaml.
I called it “syntax overloading” because in my understanding, the meaning of a list literal like [1; 2; 3] depends on the (::) in scope and type, so in some sense you get an overloaded list literal (which is part of the syntax).
Still, I wonder, if there’s only (::) for lists or something similar for tuples or something else for something else? And where this particular thing is documented?
It’s also fine if the documentation is not complete but I wanted to ask first if anyone knows any available resources
Actually, you can only redefine a few existing constructors. I have not found an official list, but the type constructors that you can shadow seem to be: ::, [], (), true and false. Yes, you can redefine all those, so out of some arguably legitimate uses for :: and [], there is potential for obfuscation.
# type void = | (* Empty type *);;
# type _ tuple = () : void tuple | (::) : 'a * 'b -> ('a * 'b) tuple;;
type _ tuple = () : void tuple | (::) : 'a * 'b -> ('a * 'b) tuple
# let a :: b :: () = if true then 1 :: 2 :: () else assert false;;
val a : int = 1
val b : int = 2
All other operator-like identifiers cannot be used as constructors, so although you can use them to construct values, you can’t use them in patterns:
# let ( $-$ ) x y = x :: y;;
val ( $-$ ) : 'a -> 'b -> ('a * 'b) tuple = <fun>
# 42 $-$ 12 $-$ ();;
- : ((int * int) tuple * void tuple) tuple = (::) ((::) (42, 12), ())
The one not yet mentioned in the discussion is that you can redefine .[] and .[]<- as long as you do it inside a module named String, AFAIR. There’s a thread here on Discuss on how such valuable lexical estate is wasted on strings, but I can’t find it.
The list, unit, and other built-in types are documented in the OCaml Manual chapter on the core library (not Jane Street Core, OCaml core): OCaml - The core library
The documentation update we’ve started releasing includes a new tutorial on operators:
I’ve tried summarizing and grouping what’s in the reference manual and a couple of blog posts, in a readable form. Alas, it doesn’t cover the case of reusing the list syntactic sugar, yet. I’d be super happy if somebody could contribute some text. Up to my findings, documentation is available on unary operators, binary operators, indexing operators and custom binders. But I couldn’t find anything about what you mentioned. Interestingly, if you ask ChatGPT about that, it falls into a bad trip, which suggests it wasn’t fed with anything on that matter, probably because there isn’t anything available.
With overloading it would be possible to use both versions of ( :: ) in the same scope, and the “right” one would be picked, based on type. But once you have defined your own operator-constructor, it masks the previously available one, unless you use a type annotation
# type ('a, 'b) foo = ( :: ) of 'a * 'b;;
type ('a, 'b) foo = (::) of 'a * 'b
# let bar = function x :: y -> Some (x, y);;
val bar : ('a, 'b) foo -> ('a * 'b) option = <fun>
# let tail = function ((_ :: u) : 'a list) -> Some u | _ -> None;;
val tail : 'a list -> 'a list option = <fun>
A clarification: what we’ve published is not a blog post; it is a tutorial that is part of the official documentation.
The manual provides authoritative reference information. Tutorials are for learners. That’s two different use cases. I agree something seems to be missing in the manual. But something else was also missing for learners.
