Docs information on MIMEs?

[nathanrboyer]

I was reading through the docs section on Custom pretty-printing which introduces adding methods of show for different MIME types, but I have not been able to find the following information on MIMEs in the docs:

1. What is a MIME?
2. What MIMEs are available, and which should I implement for my custom type?
3. When to use each of the various MIME creation methods shown and what the differences are?
   a. show(stdout, ::MIME("text/plain"), "hi")
   b. show(stdout, MIME("text/plain"), "hi")
   c. show(stdout, MIME"text/plain", "hi")
   d. show(stdout, "text/plain", "hi").

The docs passage linked above has links to Networking and Streams and Multimedia I/O, but neither contain the information I am looking for. I imagine that information should be added to the top of Multimedia I/O, but I have not been able to find the answers myself yet outside of Wikipedia.

(I have an open PR #56767 on the Custom pretty-printing section to add other clarifications, but I'm not sure that is the place to add information about the MIMEs themselves.)

[stevengj]

1. MIME ("media") types are an internet-standard naming for content types/formats, e.g. text/plain or image/png. MIME in Julia is a type to represent media types as a set of singleton types MIME{mime} where mime is a Symbol.
   • for example, MIME{Symbol("text/plain")} is a singleton type to represent text/plain media. This is awkward to type, so we also define a string macro MIME"..." for MIME(Symbol("...")), e.g. MIME"text/plain". The string macro also ensures that the symbol is evaluated at parse/lowering time, so that the type is inferred correctly (constant propagation may suffice these days, though?).
   • what you pass to functions like show or repr is an instance of such a MIME"..." type, which can be created by MIME"..."(). e.g. MIME"text/plain"() constructs a (singleton) instance of the MIME"text/plain" type. You can also use the constructor MIME("...") to create an instance of MIME"...", passing a string, but this may lead to dynamic dispatch (unless constant propagation is enough these days? we may need to add some @constprop annotation to the constructor).
2. The mime in MIME{mime} can be literally any Symbol, but ordinarily you should stick to Internet-standard MIME types if they are available. Any given environment for Julia will typically only look for show methods of a small set of supported MIME types for that environment.
   • the REPL only uses text/plain in its display. (Unless you call pushdisplay! to install a display that supports more types.)
   • In Jupyter/IJulia, you can mainly use text/plain, image/svg+xml, image/png, image/jpeg, text/markdown, text/html, and text/latex, but there is some support for extensibility via plug-ins. (We should probably add image/gif.)
   • I think Pluto supports a similar set as Jupyter, with a few more image types, along with a specialized application/vnd.pluto.table+object type.
3. With regards to your examples:
   • show(stdout, ::MIME("text/plain"), "hi") is invalid Julia syntax. If you want to define a method you do Base.show(io::IO, ::MIME"text/plain", x::MyType) = ... — notice that the type signature is ::MIME"text/plain" since MIME"text/plain" is a string macro for the type as explained above.
   • show(stdout, MIME("text/plain"), "hi") — this is fine, it may involve a dynamic dispatch unless the MIME("...") constructor is constant-propagated.
   • show(stdout, MIME"text/plain", "hi") — this is invalid, because you are passing a type and not an instance of the type. You want show(stdout, MIME"text/plain"(), "hi"). This has the advantage of not requiring dynamic dispatch since the MIME{...} type is constructed at parse/lowering time by the string macro.
   • show(stdout, "text/plain", "hi") — this is fine, it will call show(stdout, MIME("text/plain"), "hi"), which may involve a dynamic dispatch as noted above.

[nathanrboyer]

Okay, so the options for method definitions are these (where the variable name mime is dropped since it's not needed for the method definition) ...

1. Base.show(io::IO, ::MIME{Symbol("text/plain")}, x::MyType) = print(io, ...)
2. Base.show(io::IO, ::MIME"text/plain", x::MyType)= print(io, ...) - converts to 1

and the options for method calls are these?

1. show(stdout, "text/plain", x) - calls 2
2. show(stdout, MIME("text/plain"), x)
3. show(stdout, MIME"text/plain"(), x) - fastest option since type is static

[stevengj]

Looks like constant propagation nowadays makes the MIME(mimestring) constructor type-stable for literal strings, and maybe similarly for show(io, mimestring, x)?

julia> using Test

julia> f() = MIME("text/plain")
f (generic function with 2 methods)

julia> @inferred f()
MIME type text/plain

julia> g(x) = show(stdout, "text/plain", x)
g (generic function with 1 method)

julia> @inferred g(3)

though I'm not 100% convinced that @inferred g(3) eliminates the possibility of dynamic dispatch in that case?