Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Deprecate showcompact() #26080

Merged
merged 2 commits into from
Mar 9, 2018
+84 −80
Merged

Deprecate showcompact() #26080

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8d6f752
Deprecate showcompact()
nalimilan Feb 16, 2018
e2b151f
Add documentation for IOContext's :compact property in Custom pretty-…
nalimilan Mar 9, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion NEWS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1093,7 +1093,11 @@ Deprecated or removed
* `DevNull`, `STDIN`, `STDOUT`, and `STDERR` have been renamed to `devnull`, `stdin`, `stdout`,
and `stderr`, respectively ([#25786]).

* `wait` and `fetch` on `Task` now resemble the interface of `Future`
* `wait` and `fetch` on `Task` now resemble the interface of `Future`.

* `showcompact(io, x...)` has been deprecated in favor of
`show(IOContext(io, :compact => true), x...)` ([#26080]).
Use `sprint(show, x..., context=:compact => true)` instead of `sprint(showcompact, x...)`.

Command-line option changes
---------------------------
Expand Down Expand Up @@ -1391,4 +1395,5 @@ Command-line option changes
[#25998]: https://github.com/JuliaLang/julia/issues/25998
[#26009]: https://github.com/JuliaLang/julia/issues/26009
[#26071]: https://github.com/JuliaLang/julia/issues/26071
[#26080]: https://github.com/JuliaLang/julia/issues/26080
[#26149]: https://github.com/JuliaLang/julia/issues/26149
2 changes: 1 addition & 1 deletion base/Enums.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ macro enum(T, syms...)
print(io, x)
else
print(io, x, "::")
showcompact(io, typeof(x))
show(IOContext(io, :compact => true), typeof(x))
print(io, " = ", $basetype(x))
end
end
Expand Down
4 changes: 4 additions & 0 deletions base/deprecated.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1495,6 +1495,10 @@ end
# Issue #26248
@deprecate conj(x) x

@deprecate showcompact(x) show(IOContext(stdout, :compact => true), x)
@deprecate showcompact(io, x) show(IOContext(io, :compact => true), x)
@deprecate sprint(::typeof(showcompact), args...) sprint(show, args...; context=:compact => true)

# END 0.7 deprecations

# BEGIN 1.0 deprecations
Expand Down
1 change: 0 additions & 1 deletion base/exports.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -619,7 +619,6 @@ export
println,
printstyled,
show,
showcompact,
showerror,
sprint,
summary,
Expand Down
5 changes: 3 additions & 2 deletions base/irrationals.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,8 @@ big(::Type{<:AbstractIrrational}) = BigFloat

# align along = for nice Array printing
function alignment(io::IO, x::AbstractIrrational)
m = match(r"^(.*?)(=.*)$", sprint(showcompact, x, context=io, sizehint=0))
m === nothing ? (length(sprint(showcompact, x, context=io, sizehint=0)), 0) :
ctx = IOContext(io, :compact=>true)
m = match(r"^(.*?)(=.*)$", sprint(show, x, context=ctx, sizehint=0))
m === nothing ? (length(sprint(show, x, context=ctx, sizehint=0)), 0) :
(length(m.captures[1]), length(m.captures[2]))
end
39 changes: 2 additions & 37 deletions base/show.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -205,8 +205,8 @@ IOContext(io::IO, context::IO) = IOContext(unwrapcontext(io)[1], unwrapcontext(c
Create an `IOContext` that wraps a given stream, adding the specified `key=>value` pairs to
the properties of that stream (note that `io` can itself be an `IOContext`).

- use `(key => value) in dict` to see if this particular combination is in the properties set
- use `get(dict, key, default)` to retrieve the most recent value for a particular key
- use `(key => value) in io` to see if this particular combination is in the properties set
- use `get(io, key, default)` to retrieve the most recent value for a particular key

The following properties are in common use:

Expand Down Expand Up @@ -1945,41 +1945,6 @@ function Base.showarg(io::IO, r::Iterators.Pairs{<:Any, <:Any, I, D}, toplevel)
print(io, "Iterators.Pairs(::$D, ::$I)")
end

"""
showcompact(x)
showcompact(io::IO, x)

Show a compact representation of a value to `io`. If `io` is not specified, the
default is to print to [`stdout`](@ref).

This is used for printing array elements without repeating type information (which would
be redundant with that printed once for the whole array), and without line breaks inside
the representation of an element.

To offer a compact representation different from its standard one, a custom type should
test `get(io, :compact, false)` in its normal [`show`](@ref) method.

# Examples
```jldoctest
julia> A = [1. 2.; 3. 4]
2×2 Array{Float64,2}:
1.0 2.0
3.0 4.0

julia> showcompact(A)
[1.0 2.0; 3.0 4.0]
```
"""
showcompact(x) = showcompact(stdout, x)
function showcompact(io::IO, x)
if get(io, :compact, false)
show(io, x)
else
show(IOContext(io, :compact => true), x)
end
end


# printing BitArrays

# (following functions not exported - mainly intended for debug)
Expand Down
8 changes: 7 additions & 1 deletion base/strings/io.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,9 @@ println(io::IO, xs...) = print(io, xs..., '\n')

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.
`context` can be either an [`IOContext`](@ref) whose properties will be used,
or a `Pair` specifying a property and its value. `sizehint` suggests the capacity
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Specifying a Pair does happen to work, but only the usage case of passing an IO was what I had really originally intended (and found to be common).

I think that we maybe instead should suggest the usage of anonymous functions as a general way of passing a configuration set of arbitrarily many new properties:

showcompact = (io, v) -> show(IOContext(io, :compact => true), v)
sprint(showcompact, 66.66666)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK. I assumed it was intended since the signature doesn't use ::IOContext.

I actually started with the anonymous function approach, but it's quite verbose and much less convenient than passing a pair for common cases (have a look at the diff to get and idea). So I'd say we'd better continue to support passing a pair.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't intend to prevent passing a Pair, but it simply doesn't generalize as well. Although I suppose it also quickly becomes easier just to write it out:

buf = IOBuffer(sizehint = sizehint)
io = IOContext(buf, :compact => true)
show(io, 66.66666)
return String(take!(buf))

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My thought was that passing a single pair is the most common case, and for other situations it's not too hard to create a full IOContext.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree it's very nice to be able to pass a single pair.

of the buffer (in bytes).

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
Expand All @@ -81,8 +84,11 @@ to allocate for the buffer used to write the string.

# Examples
```jldoctest
julia> sprint(showcompact, 66.66666)
julia> sprint(show, 66.66666; context=:compact => true)
"66.6667"

julia> sprint(showerror, BoundsError([1], 100))
"BoundsError: attempt to access 1-element Array{Int64,1} at index [100]"
```
"""
function sprint(f::Function, args...; context=nothing, sizehint::Integer=0)
Expand Down
8 changes: 4 additions & 4 deletions base/sysimg.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -942,12 +942,12 @@ tot_time = tot_time_base + Base.tot_time_stdlib[] + tot_time_userimg + tot_time_

println("Sysimage built. Summary:")
print("Total ─────── "); Base.time_print(tot_time * 10^9); print(" \n");
print("Base: ─────── "); Base.time_print(tot_time_base * 10^9); print(" "); showcompact((tot_time_base / tot_time) * 100); println("%")
print("Stdlibs: ──── "); Base.time_print(Base.tot_time_stdlib[] * 10^9); print(" "); showcompact((Base.tot_time_stdlib[] / tot_time) * 100); println("%")
print("Base: ─────── "); Base.time_print(tot_time_base * 10^9); print(" "); show(IOContext(stdout, :compact=>true), (tot_time_base / tot_time) * 100); println("%")
print("Stdlibs: ──── "); Base.time_print(Base.tot_time_stdlib[] * 10^9); print(" "); show(IOContext(stdout, :compact=>true), (Base.tot_time_stdlib[] / tot_time) * 100); println("%")
if isfile("userimg.jl")
print("Userimg: ──── "); Base.time_print(tot_time_userimg * 10^9); print(" "); showcompact((tot_time_userimg / tot_time) * 100); println("%")
print("Userimg: ──── "); Base.time_print(tot_time_userimg * 10^9); print(" "); show(IOContext(stdout, :compact=>true), (tot_time_userimg / tot_time) * 100); println("%")
end
print("Precompile: ─ "); Base.time_print(tot_time_precompile * 10^9); print(" "); showcompact((tot_time_precompile / tot_time) * 100); println("%")
print("Precompile: ─ "); Base.time_print(tot_time_precompile * 10^9); print(" "); show(IOContext(stdout, :compact=>true), (tot_time_precompile / tot_time) * 100); println("%")
end

empty!(LOAD_PATH)
Expand Down
1 change: 0 additions & 1 deletion doc/src/base/io-network.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,6 @@ Base.IOContext(::IO, ::IOContext)

```@docs
Base.show(::Any)
Base.showcompact
Base.summary
Base.print
Base.println
Expand Down
10 changes: 7 additions & 3 deletions doc/src/manual/networking-and-streams.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,19 +100,23 @@ Note that `a` is written to [`stdout`](@ref) by the [`write`](@ref) function and
value is `1` (since `0x61` is one byte).

For text I/O, use the [`print`](@ref) or [`show`](@ref) methods, depending on your needs (see
the Julia Base reference for a detailed discussion of the difference between the two):
the documentation for these two methods for a detailed discussion of the difference between them):

```jldoctest
julia> print(stdout, 0x61)
97
```

See [Custom pretty-printing](@ref man-custom-pretty-printing) for more information on how to
implement display methods for custom types.

## IO Output Contextual Properties

Sometimes IO output can benefit from the ability to pass contextual information into show methods.
The [`IOContext`](@ref) object provides this framework for associating arbitrary metadata with an IO object.
For example, [`showcompact`](@ref) adds a hinting parameter to the IO object that the invoked show method
should print a shorter output (if applicable).
For example, `:compact => true` adds a hinting parameter to the IO object that the invoked show method
should print a shorter output (if applicable). See the [`IOContext`](@ref) documentation for a list
of common properties.

## Working with Files

Expand Down
33 changes: 32 additions & 1 deletion doc/src/manual/types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1187,7 +1187,7 @@ Closest candidates are:
supertype(!Matched::UnionAll) at operators.jl:47
```

## Custom pretty-printing
## [Custom pretty-printing](@id man-custom-pretty-printing)

Often, one wants to customize how instances of a type are displayed. This is accomplished by
overloading the [`show`](@ref) function. For example, suppose we define a type to represent
Expand Down Expand Up @@ -1321,6 +1321,37 @@ julia> :($a == 2)
:(3.0 * exp(4.0im) == 2)
```

In some cases, it is useful to adjust the behavior of `show` methods depending
on the context. This can be achieved via the [`IOContext`](@ref) type, which allows
passing contextual properties together with a wrapped IO stream.
For example, we can build a shorter representation in our `show` method
when the `:compact` property is set to `true`, falling back to the long
representation if the property is `false` or absent:
```jldoctest polartype
julia> function Base.show(io::IO, z::Polar)
if get(io, :compact, false)
print(io, z.r, "ℯ", z.Θ, "im")
else
print(io, z.r, " * exp(", z.Θ, "im)")
end
end
```

This new compact representation will be used when the passed IO stream is an `IOContext`
object with the `:compact` property set. In particular, this is the case when printing
arrays with multiple columns (where horizontal space is limited):
```jldoctest polartype
julia> show(IOContext(stdout, :compact=>true), Polar(3, 4.0))
3.0ℯ4.0im

julia> [Polar(3, 4.0) Polar(4.0,5.3)]
1×2 Array{Polar{Float64},2}:
3.0ℯ4.0im 4.0ℯ5.3im
```

See the [`IOContext`](@ref) documentation for a list of common properties which can be used
to adjust printing.

## "Value types"

In Julia, you can't dispatch on a *value* such as `true` or `false`. However, you can dispatch
Expand Down
4 changes: 2 additions & 2 deletions test/complex.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ for T in (Int64, Float64)
@test complex(Complex{T}) == Complex{T}
end

#showcompact
@test sprint(showcompact, complex(1, 0)) == "1+0im"
#show
@test sprint(show, complex(1, 0), context=:compact => true) == "1+0im"
@test sprint(show, complex(true, true)) == "Complex(true,true)"

@testset "arithmetic" begin
Expand Down
2 changes: 1 addition & 1 deletion test/dict.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -350,7 +350,7 @@ end
@testset "Issue #15739" begin # Compact REPL printouts of an `AbstractDict` use brackets when appropriate
d = Dict((1=>2) => (3=>45), (3=>10) => (10=>11))
buf = IOBuffer()
showcompact(buf, d)
show(IOContext(buf, :compact => true), d)

# Check explicitly for the expected strings, since the CPU bitness effects
# dictionary ordering.
Expand Down
4 changes: 2 additions & 2 deletions test/float16.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ end
@test NaN16 != NaN16
@test isequal(NaN16, NaN16)
@test repr(NaN16) == "NaN16"
@test sprint(showcompact, NaN16) == "NaN"
@test sprint(show, NaN16, context=:compact => true) == "NaN"

@test isinf(Inf16)
@test isinf(-Inf16)
Expand All @@ -120,7 +120,7 @@ end
@test -Inf16 < Inf16
@test isequal(Inf16, Inf16)
@test repr(Inf16) == "Inf16"
@test sprint(showcompact, Inf16) == "Inf"
@test sprint(show, Inf16, context=:compact => true) == "Inf"

@test isnan(reinterpret(Float16,0x7c01))
@test !isinf(reinterpret(Float16,0x7c01))
Expand Down
2 changes: 1 addition & 1 deletion test/missing.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,7 @@ end

@testset "printing" begin
@test sprint(show, missing) == "missing"
@test sprint(showcompact, missing) == "missing"
@test sprint(show, missing, context=:compact => true) == "missing"
@test sprint(show, [missing]) == "$Missing[missing]"
@test sprint(show, [1 missing]) == "$(Union{Int, Missing})[1 missing]"
b = IOBuffer()
Expand Down
6 changes: 3 additions & 3 deletions test/mpfr.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -895,7 +895,7 @@ end
ends::String="",
starts::String="")
sx = sprint(show, x)
scx = sprint(showcompact, x)
scx = sprint(show, x, context=:compact => true)
strx = string(x)
@test sx == strx
@test length(scx) < 20
Expand All @@ -915,8 +915,8 @@ end
test_show_bigfloat(big"-2.3457645687563543266576889678956787e-10000", starts="-2.345", ends="e-10000")

for to_string in [string,
x->sprint(show, x),
x->sprint(showcompact,x)]
x->sprint(show, x),
x->sprint(show, x, context=:compact => true)]
@test to_string(big"0.0") == "0.0"
@test to_string(big"-0.0") == "-0.0"
@test to_string(big"1.0") == "1.0"
Expand Down
18 changes: 9 additions & 9 deletions test/numbers.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -410,14 +410,14 @@ end
@test repr(-NaN) == "NaN"
@test repr(Float64(pi)) == "3.141592653589793"
# issue 6608
@test sprint(showcompact, 666666.6) == "6.66667e5"
@test sprint(showcompact, 666666.049) == "666666.0"
@test sprint(showcompact, 666665.951) == "666666.0"
@test sprint(showcompact, 66.66666) == "66.6667"
@test sprint(showcompact, -666666.6) == "-6.66667e5"
@test sprint(showcompact, -666666.049) == "-666666.0"
@test sprint(showcompact, -666665.951) == "-666666.0"
@test sprint(showcompact, -66.66666) == "-66.6667"
@test sprint(show, 666666.6, context=:compact => true) == "6.66667e5"
@test sprint(show, 666666.049, context=:compact => true) == "666666.0"
@test sprint(show, 666665.951, context=:compact => true) == "666666.0"
@test sprint(show, 66.66666, context=:compact => true) == "66.6667"
@test sprint(show, -666666.6, context=:compact => true) == "-6.66667e5"
@test sprint(show, -666666.049, context=:compact => true) == "-666666.0"
@test sprint(show, -666665.951, context=:compact => true) == "-666666.0"
@test sprint(show, -66.66666, context=:compact => true) == "-66.6667"

@test repr(1.0f0) == "1.0f0"
@test repr(-1.0f0) == "-1.0f0"
Expand Down Expand Up @@ -2564,7 +2564,7 @@ end
(-T(Inf), "-Inf")]
@assert x isa T
@test string(x) == sx
@test sprint(io -> show(IOContext(io, :compact => true), x)) == sx
@test sprint(show, x, context=:compact => true) == sx
@test sprint(print, x) == sx
end
end
Expand Down
10 changes: 0 additions & 10 deletions test/show.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -747,16 +747,6 @@ end
@test !contains(repr(fill(1.,10,10)), "\u2026")
@test contains(sprint((io, x) -> show(IOContext(io, :limit => true), x), fill(1.,30,30)), "\u2026")

# showcompact() also sets :multiline=>false (#16817)
let io = IOBuffer(),
x = [1, 2]

showcompact(io, x)
@test String(take!(io)) == "[1, 2]"
showcompact(IOContext(io, :compact => true), x)
@test String(take!(io)) == "[1, 2]"
end

let io = IOBuffer()
ioc = IOContext(io, :limit => true)
@test sprint(show, ioc) == "IOContext($(sprint(show, ioc.io)))"
Expand Down