julia: print, show, display, dump, … – What to override? What to use?

The julia language has quite a few functions to show information about an object to the user. While the output is often similar, it is not exactly the same with each of these methods. The official documentation is still missing a cohesive description of I/O functions, so I went through some of the julia base source code trying to understand the differences. Here is my current understanding:

# Which function is used for what?
– `display` is meant **for interactive use** and is Display aware. This means, that depending on whether a REPL or an IJulia notebook is used to evaluate the code, this output will vary. For example, the REPL display of an image may yield an instructive description of the object – including the type of the object and its identifying fields – while the Notebook output may yield an actual picture. When a function is called interactively, its return value is `display`ed.
– `print` is meant for non-interactive use, **generating output programatically**. It is thus the basis of `println`, etc. and yields an undecorated string representation. Undecorated here means that no julia-specific type info is included. E.g. while the `display` of an array may output

2-element Array{Float64,1}:
 1.0
 2.0

the same array will `print`

[1.0, 2.0]

– `dump` is meant for inspection. It will yield the most elaborate description of an object and, recursively, its fields, etc. This function is typically not called in everyday use.

# Which function should I override for my custom types?
This is where the function `show` comes in. In fact all displaying functions apart from `dump` rely on `show` under the hood. Note, that we probably don’t need to override `dump` anyways as we don’t want to deviate from the default behavior of showing all available information.
So for our custom types we can
– override `show(io,x)` with the undecorated form **for print**.
– override `show(io,mime::MIME…,x)` with the most useful interactive output with a given multimedia capability (MIME…). E.g. for the REPL version use `mime::MIME”text/plain”`. This will be used **for display**.

Should you nonetheless need to override `dump`, then `dump(io,x,maxdepth=8,indent=””)` is what you should be defining.

# Where is this documented?
Of course relying on implementational details instead of published documentation is a risky business, as these things tend to change over time. As stated above, I wasn’t able to find such documentation in the official docs. However, the understanding described above is consistent with this section from the docs:

Just as text output is performed by print and user-defined types can indicate their textual representation by overloading show, Julia provides a standardized mechanism for rich multimedia output (such as images, formatted text, or even audio and video) […]:

– A function display(x) to request the richest available multimedia display of a Julia object x (with a plain-text fallback).

– Overloading show allows one to indicate arbitrary multimedia representations (keyed by standard MIME types) of user-defined types.

[…] The base Julia runtime provides only plain-text display, but richer displays may be enabled by loading external modules or by using graphical Julia environments (such as the IPython-based IJulia notebook).