RFC: move stringmime to Base64, rename reprmime -> repr (#25990)

* stringmime(text/plain, x) can be replaced with repr(text/plain, x)

Author: stevengj

NEWS.md

@@ -183,6 +183,10 @@ Language changes
     backslashes and the end of the literal while 2n+1 backslashes followed by a quote encodes n
     backslashes followed by a quote character ([#22926]).
 
+  * `reprmime(mime, x)` has been renamed to `repr(mime, x)`, and along with `repr(x)`
+    and `sprint` it now accepts an optional `context` keyword for `IOContext` attributes.
+    `stringmime` has been moved to the Base64 stdlib package ([#25990]).
+
   * The syntax `(x...)` for constructing a tuple is deprecated; use `(x...,)` instead ([#24452]).
 
   * Non-parenthesized interpolated variables in strings, e.g. `"$x"`, must be followed

base/deprecated.jl

@@ -1365,6 +1365,8 @@ end
 @deprecate IOBuffer(read::Bool, write::Bool) IOBuffer(read=read, write=write)
 @deprecate IOBuffer(maxsize::Integer) IOBuffer(read=true, write=true, maxsize=maxsize)
 
+@deprecate reprmime(mime, x) repr(mime, x)
+
 # PR #23332
 @deprecate ^(x, p::Integer) Base.power_by_squaring(x,p)
 

base/exports.jl

@@ -875,8 +875,6 @@ export
     istextmime,
     MIME,
     @MIME_str,
-    reprmime,
-    stringmime,
     mimewritable,
     popdisplay,
     pushdisplay,

base/loading.jl

@@ -1116,7 +1116,7 @@ function create_expr_cache(input::String, output::String, concrete_deps::typeof(
         begin
         import Pkg
         empty!(Base.LOAD_PATH)
-        append!(Base.LOAD_PATH, $(repr(LOAD_PATH, :module => nothing)))
+        append!(Base.LOAD_PATH, $(repr(LOAD_PATH, context=:module=>nothing)))
         empty!(Base.DEPOT_PATH)
         append!(Base.DEPOT_PATH, $(repr(DEPOT_PATH)))
         empty!(Base.LOAD_CACHE_PATH)

base/multimedia.jl

@@ -3,7 +3,7 @@
 module Multimedia
 
 export AbstractDisplay, display, pushdisplay, popdisplay, displayable, redisplay,
-    MIME, @MIME_str, reprmime, stringmime, istextmime,
+    MIME, @MIME_str, istextmime,
     mimewritable, TextDisplay
 
 ###########################################################################
@@ -15,8 +15,7 @@ export AbstractDisplay, display, pushdisplay, popdisplay, displayable, redisplay
 # struct MIME{mime} end
 # macro MIME_str(s)
 import Base: MIME, @MIME_str
-import Base64
-import Base: show, print, string, convert
+import Base: show, print, string, convert, repr
 MIME(s) = MIME{Symbol(s)}()
 show(io::IO, ::MIME{mime}) where {mime} = print(io, "MIME type ", string(mime))
 print(io::IO, ::MIME{mime}) where {mime} = print(io, mime)
@@ -79,59 +78,60 @@ show(stream, mime, x)
 show(io::IO, m::AbstractString, x) = show(io, MIME(m), x)
 mimewritable(m::AbstractString, x) = mimewritable(MIME(m), x)
 
-verbose_show(io, m, x) = show(IOContext(io, :limit => false), m, x)
-
 """
-    reprmime(mime, x)
+    repr(mime, x; context=nothing)
 
 Returns an `AbstractString` or `Vector{UInt8}` containing the representation of
-`x` in the requested `mime` type, as written by [`show`](@ref) (throwing a
+`x` in the requested `mime` type, as written by [`show(io, mime, x)`](@ref) (throwing a
 [`MethodError`](@ref) if no appropriate `show` is available). An `AbstractString` is
 returned for MIME types with textual representations (such as `"text/html"` or
 `"application/postscript"`), whereas binary data is returned as
 `Vector{UInt8}`. (The function `istextmime(mime)` returns whether or not Julia
 treats a given `mime` type as text.)
 
+The optional keyword argument `context` can be set to `:key=>value` pair
+or an `IO` or [`IOContext`](@ref) object whose attributes are used for the I/O
+stream passed to `show`.
+
 As a special case, if `x` is an `AbstractString` (for textual MIME types) or a
-`Vector{UInt8}` (for binary MIME types), the `reprmime` function assumes that
+`Vector{UInt8}` (for binary MIME types), the `repr` function assumes that
 `x` is already in the requested `mime` format and simply returns `x`. This
 special case does not apply to the `"text/plain"` MIME type. This is useful so
 that raw data can be passed to `display(m::MIME, x)`.
 
+In particular, `repr("text/plain", x)` is typically a "pretty-printed" version
+of `x` designed for human consumption.  See also [`repr(x)`](@ref) to instead
+return a string corresponding to [`show(x)`](@ref) that may be closer to how
+the value of `x` would be entered in Julia.
+
 # Examples
 ```jldoctest
 julia> A = [1 2; 3 4];
 
-julia> reprmime("text/plain", A)
+julia> repr("text/plain", A)
 "2×2 Array{Int64,2}:\\n 1  2\\n 3  4"
 ```
 """
-reprmime(m::MIME, x) = istextmime(m) ? _textreprmime(m, x) : _binreprmime(m, x)
+repr(m::MIME, x; context=nothing) = istextmime(m) ? _textrepr(m, x, context) : _binrepr(m, x, context)
+repr(m::AbstractString, x; context=nothing) = repr(MIME(m), x; context=context)
 
 # strings are shown escaped for text/plain
-_textreprmime(m::MIME, x) = sprint(verbose_show, m, x)
-_textreprmime(::MIME, x::AbstractString) = x
-_textreprmime(m::MIME"text/plain", x::AbstractString) =
-    sprint(verbose_show, m, x)
+_textrepr(m::MIME, x, context) = String(__binrepr(m, x, context))
+_textrepr(::MIME, x::AbstractString, context) = x
+_textrepr(m::MIME"text/plain", x::AbstractString, context) = String(__binrepr(m, x, context))
 
-function _binreprmime(m::MIME, x)
+
+function __binrepr(m::MIME, x, context)
     s = IOBuffer()
-    verbose_show(s, m, x)
+    if context === nothing
+        show(s, m, x)
+    else
+        show(IOContext(s, context), m, x)
+    end
     take!(s)
 end
-_binreprmime(m::MIME, x::Vector{UInt8}) = x
-
-"""
-    stringmime(mime, x)
-
-Returns an `AbstractString` containing the representation of `x` in the
-requested `mime` type. This is similar to [`reprmime`](@ref) except
-that binary data is base64-encoded as an ASCII string.
-"""
-stringmime(m::MIME, x) = istextmime(m) ? reprmime(m, x) : _binstringmime(m, x)
-
-_binstringmime(m::MIME, x) = Base64.base64encode(verbose_show, m, x)
-_binstringmime(m::MIME, x::Vector{UInt8}) = Base64.base64encode(write, x)
+_binrepr(m::MIME, x, context) = __binrepr(m, x, context)
+_binrepr(m::MIME, x::Vector{UInt8}, context) = x
 
 """
     istextmime(m::MIME)
@@ -149,11 +149,7 @@ false
 ```
 """
 istextmime(m::MIME) = startswith(string(m), "text/")
-
-# it is convenient to accept strings instead of ::MIME
 istextmime(m::AbstractString) = istextmime(MIME(m))
-reprmime(m::AbstractString, x) = reprmime(MIME(m), x)
-stringmime(m::AbstractString, x) = stringmime(MIME(m), x)
 
 for mime in ["application/atom+xml", "application/ecmascript",
              "application/javascript", "application/julia",
@@ -169,7 +165,7 @@ end
 # We have an abstract AbstractDisplay class that can be subclassed in order to
 # define new rich-display output devices.  A typical subclass should
 # overload display(d::AbstractDisplay, m::MIME, x) for supported MIME types m,
-# (typically using reprmime or stringmime to get the MIME
+# (typically using show, repr, ..., to get the MIME
 # representation of x) and should also overload display(d::AbstractDisplay, x)
 # to display x in whatever MIME type is preferred by the AbstractDisplay and
 # is writable by x.  display(..., x) should throw a MethodError if x

base/strings/io.jl

@@ -69,11 +69,16 @@ println(io::IO, xs...) = print(io, xs..., '\n')
 ## conversion of general objects to strings ##
 
 """
-    sprint(f::Function, args...)
+    sprint(f::Function, args...; context=nothing, sizehint=0)
 
 Call the given function with an I/O stream and the supplied extra arguments.
 Everything written to this I/O stream is returned as a string.
 
+The optional keyword argument `context` can be set to `:key=>value` pair
+or an `IO` or [`IOContext`](@ref) object whose attributes are used for the I/O
+stream passed to `f`.  The optional `sizehint` is a suggersted (in bytes)
+to allocate for the buffer used to write the string.
+
 # Examples
 ```jldoctest
 julia> sprint(showcompact, 66.66666)
@@ -147,12 +152,17 @@ function print_quoted_literal(io, s::AbstractString)
 end
 
 """
-    repr(x)
-    repr(x, context::Pair{Symbol,<:Any}...)
+    repr(x; context=nothing)
 
 Create a string from any value using the [`show`](@ref) function.
-If context pairs are given, the IO buffer used to capture `show` output
-is wrapped in an `IOContext` object with those context pairs.
+
+The optional keyword argument `context` can be set to an `IO` or [`IOContext`](@ref)
+object whose attributes are used for the I/O stream passed to `show`.
+
+Note that `repr(x)` is usually similar to how the value of `x` would
+be entered in Julia.  See also [`repr("text/plain", x)`](@ref) to instead
+return a "pretty-printed" version of `x` designed more for human consumption,
+equivalent to the REPL display of `x`.
 
 # Examples
 ```jldoctest
@@ -164,17 +174,7 @@ julia> repr(zeros(3))
 
 ```
 """
-function repr(x)
-    s = IOBuffer()
-    show(s, x)
-    String(take!(s))
-end
-
-function repr(x, context::Pair{Symbol}...)
-    s = IOBuffer()
-    show(IOContext(s, context...), x)
-    String(take!(s))
-end
+repr(x; context=nothing) = sprint(show, x; context=context)
 
 # IOBuffer views of a (byte)string:
 

base/sysimg.jl

@@ -448,12 +448,6 @@ let BINDIR = ccall(:jl_get_julia_bindir, Any, ())
     init_load_path(BINDIR)
 end
 
-INCLUDE_STATE = 3 # include = include_relative
-
-import Base64
-
-INCLUDE_STATE = 2
-
 include("asyncmap.jl")
 
 include("multimedia.jl")
@@ -576,6 +570,7 @@ Base.require(Base, :UUIDs)
     @deprecate_stdlib base64decode Base64 true
     @deprecate_stdlib Base64EncodePipe Base64 true
     @deprecate_stdlib Base64DecodePipe Base64 true
+    @deprecate_stdlib stringmime Base64 true
 
     @deprecate_stdlib poll_fd FileWatching true
     @deprecate_stdlib poll_file FileWatching true

doc/src/base/io-network.md

@@ -94,8 +94,7 @@ Base.Multimedia.redisplay
 Base.Multimedia.displayable
 Base.show(::Any, ::Any, ::Any)
 Base.Multimedia.mimewritable
-Base.Multimedia.reprmime
-Base.Multimedia.stringmime
+Base.repr(::Any, ::Any)
 ```
 
 As mentioned above, one can also define new display backends. For example, a module that can display
@@ -105,8 +104,9 @@ types with PNG representations will automatically display the image using the mo
 In order to define a new display backend, one should first create a subtype `D` of the abstract
 class `AbstractDisplay`.  Then, for each MIME type (`mime` string) that can be displayed on `D`, one should
 define a function `display(d::D, ::MIME"mime", x) = ...` that displays `x` as that MIME type,
-usually by calling [`reprmime(mime, x)`](@ref).  A `MethodError` should be thrown if `x` cannot be displayed
-as that MIME type; this is automatic if one calls [`reprmime`](@ref). Finally, one should define a function
+usually by calling [`show(io, mime, x)`](@ref) or [`repr(io, mime, x)`](@ref).
+A `MethodError` should be thrown if `x` cannot be displayed
+as that MIME type; this is automatic if one calls `show` or `repr`. Finally, one should define a function
 `display(d::D, x)` that queries [`mimewritable(mime, x)`](@ref) for the `mime` types supported by `D`
 and displays the "best" one; a `MethodError` should be thrown if no supported MIME types are found
 for `x`.  Similarly, some subtypes may wish to override [`redisplay(d::D, ...)`](@ref Base.Multimedia.redisplay). (Again, one should

doc/src/base/strings.md

@@ -8,7 +8,7 @@ Base.:^(::AbstractString, ::Integer)
 Base.string
 Base.repeat(::AbstractString, ::Integer)
 Base.repeat(::Char, ::Integer)
-Base.repr
+Base.repr(::Any)
 Core.String(::AbstractString)
 Base.SubString
 Base.transcode

stdlib/Base64/docs/src/index.md

@@ -5,4 +5,5 @@ Base64.Base64EncodePipe
 Base64.base64encode
 Base64.Base64DecodePipe
 Base64.base64decode
+Base64.stringmime
 ```