From 5dc55f35675ee86e6499d155cabbcb54c34a79a6 Mon Sep 17 00:00:00 2001 From: Jeff Bezanson Date: Thu, 21 Jul 2016 18:50:21 -0400 Subject: [PATCH] improve docs for `IOContext`. fixes #16763 also remove some references to the removed `multiline` property --- base/docs/helpdb/Base.jl | 3 ++ base/multimedia.jl | 2 +- base/show.jl | 57 +++++++++++++++++++++++++------------- doc/stdlib/io-network.rst | 32 +++++++++++++++------ doc/stdlib/stacktraces.rst | 11 +++----- 5 files changed, 68 insertions(+), 37 deletions(-) diff --git a/base/docs/helpdb/Base.jl b/base/docs/helpdb/Base.jl index 3f73fbe8d0004..0086c7ff349e7 100644 --- a/base/docs/helpdb/Base.jl +++ b/base/docs/helpdb/Base.jl @@ -6294,6 +6294,9 @@ defining a 2-argument `show(stream::IO, x::MyType)` method. Technically, the `MIME"mime"` macro defines a singleton type for the given `mime` string, which allows us to exploit Julia's dispatch mechanisms in determining how to display objects of any given type. + +The first argument to `show` can be an `IOContext` specifying output format properties. +See `IOContext` for details. """ show(stream, mime, x) diff --git a/base/multimedia.jl b/base/multimedia.jl index 45b827e66d859..de2dd2492b11f 100644 --- a/base/multimedia.jl +++ b/base/multimedia.jl @@ -47,7 +47,7 @@ mimewritable(m::AbstractString, x) = mimewritable(MIME(m), x) # format and is returned unmodified. This is useful so that raw data can be # passed to display(m::MIME, x). -verbose_show(io, m, x) = show(IOContext(io,multiline=true,limit=false), m, x) +verbose_show(io, m, x) = show(IOContext(io,limit=false), m, x) macro textmime(mime) quote diff --git a/base/show.jl b/base/show.jl index 5d0bf1cf6e036..9b0d2f171d4c3 100644 --- a/base/show.jl +++ b/base/show.jl @@ -2,6 +2,14 @@ print(io::IO, s::Symbol) = (write(io,s); nothing) +""" + IOContext + +IOContext provides a mechanism for passing output configuration settings among `show` methods. + +In short, it is an immutable dictionary that is a subclass of IO. It supports standard +dictionary operations such as `getindex`, and can also be used as an I/O stream. +""" immutable IOContext{IO_t <: IO} <: AbstractPipe io::IO_t dict::ImmutableDict{Symbol, Any} @@ -12,27 +20,10 @@ immutable IOContext{IO_t <: IO} <: AbstractPipe end """ - IOContext{<:IO} <: IO - -IOContext provides a mechanism for passing output-configuration keyword arguments through arbitrary show methods. - -In short, it is an immutable Dictionary that is a subclass of IO. - - IOContext(io::IO, KV::Pair) - -Create a new entry in the IO Dictionary for the key => value pair + IOContext(io::IO; properties...) - - 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 - -``` -IOContext(io::IO, context::IOContext) -``` - -Create a IOContext that wraps an alternate IO but inherits the keyword arguments from the context +The same as `IOContext(io::IO, KV::Pair)`, but accepting properties as keyword arguments. """ -IOContext - IOContext(io::IO; kws...) = IOContext(IOContext(io, ImmutableDict{Symbol,Any}()); kws...) function IOContext(io::IOContext; kws...) for (k, v) in kws @@ -48,7 +39,34 @@ IOContext(io::IO, key, value) = IOContext(io, ImmutableDict{Symbol, Any}(key, va IOContext(io::IOContext, key, value) = IOContext(io, ImmutableDict{Symbol, Any}(io.dict, key, value)) IOContext(io::IO, context::IO) = IOContext(io) + +""" + IOContext(io::IO, context::IOContext) + +Create a IOContext that wraps an alternate IO but inherits the properties of `context`. +""" IOContext(io::IO, context::IOContext) = IOContext(io, context.dict) + +""" + IOContext(io::IO, KV::Pair) + +Create an `IOContext` that wraps a given stream, adding the specified key=>value pair 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 + +The following properties are in common use: + + - `:compact`: Boolean specifying that small values should be printed more compactly, e.g. + that numbers should be printed with fewer digits. This is set when printing array + elements. + - `:limit`: Boolean specifying that containers should be truncated, e.g. showing `…` in + place of most elements. + - `:displaysize`: A `Tuple{Int,Int}` giving the size in rows and columns to use for text + output. This can be used to override the display size for called functions, but to + get the size of the screen use the `displaysize` function. +""" IOContext(io::IO, KV::Pair) = IOContext(io, KV[1], KV[2]) show(io::IO, ctx::IOContext) = (print(io, "IOContext("); show(io, ctx.io); print(io, ")")) @@ -1561,7 +1579,6 @@ function showarray(io::IO, X::AbstractArray, repr::Bool = true; header = true) if repr && ndims(X) == 1 return show_vector(io, X, "[", "]") end - io = IOContext(io, multiline=false) if !haskey(io, :compact) io = IOContext(io, compact=true) end diff --git a/doc/stdlib/io-network.rst b/doc/stdlib/io-network.rst index edfea05d67835..2ddf77b578d4a 100644 --- a/doc/stdlib/io-network.rst +++ b/doc/stdlib/io-network.rst @@ -398,28 +398,40 @@ General I/O Read all available data on the stream, blocking the task only if no data is available. The result is a ``Vector{UInt8,1}``\ . -.. function:: IOContext{<:IO} <: IO +.. type:: IOContext .. Docstring generated from Julia source - IOContext provides a mechanism for passing output-configuration keyword arguments through arbitrary show methods. + IOContext provides a mechanism for passing output configuration settings among ``show`` methods. - In short, it is an immutable Dictionary that is a subclass of IO. + In short, it is an immutable dictionary that is a subclass of IO. It supports standard dictionary operations such as ``getindex``\ , and can also be used as an I/O stream. - .. code-block:: julia +.. function:: IOContext(io::IO, KV::Pair) - IOContext(io::IO, KV::Pair) + .. Docstring generated from Julia source - Create a new entry in the IO Dictionary for the key => value pair + Create an ``IOContext`` that wraps a given stream, adding the specified key=>value pair 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 - .. code-block:: julia + The following properties are in common use: - IOContext(io::IO, context::IOContext) + * ``:compact``\ : Boolean specifying that small values should be printed more compactly, e.g. that numbers should be printed with fewer digits. This is set when printing array elements. + * ``:limit``\ : Boolean specifying that containers should be truncated, e.g. showing ``…`` in place of most elements. + * ``:displaysize``\ : A ``Tuple{Int,Int}`` giving the size in rows and columns to use for text output. This can be used to override the display size for called functions, but to get the size of the screen use the ``displaysize`` function. + +.. function:: IOContext(io::IO, context::IOContext) + + .. Docstring generated from Julia source - Create a IOContext that wraps an alternate IO but inherits the keyword arguments from the context + Create a IOContext that wraps an alternate IO but inherits the properties of ``context``\ . + +.. function:: IOContext(io::IO; properties...) + + .. Docstring generated from Julia source + + The same as ``IOContext(io::IO, KV::Pair)``\ , but accepting properties as keyword arguments. Text I/O -------- @@ -717,6 +729,8 @@ Julia environments (such as the IPython-based IJulia notebook). Technically, the ``MIME"mime"`` macro defines a singleton type for the given ``mime`` string, which allows us to exploit Julia's dispatch mechanisms in determining how to display objects of any given type. + The first argument to ``show`` can be an ``IOContext`` specifying output format properties. See ``IOContext`` for details. + .. function:: mimewritable(mime, x) .. Docstring generated from Julia source diff --git a/doc/stdlib/stacktraces.rst b/doc/stdlib/stacktraces.rst index 46a5f0b857d48..1cc87e89aac3d 100644 --- a/doc/stdlib/stacktraces.rst +++ b/doc/stdlib/stacktraces.rst @@ -17,7 +17,7 @@ * ``func::Symbol`` The name of the function containing the execution context. - * ``outer_linfo::Nullable{LambdaInfo}`` + * ``linfo::Nullable{LambdaInfo}`` The LambdaInfo containing the execution context (if it could be found). * ``file::Symbol`` @@ -26,15 +26,12 @@ * ``line::Int`` The line number in the file containing the execution context. - * ``inlined_file::Symbol`` - - The path to the file containing the context for inlined code. - * ``inlined_line::Int`` - - The line number in the file containing the context for inlined code. * ``from_c::Bool`` True if the code is from C. + * ``inlined::Bool`` + + True if the code is from an inlined frame. * ``pointer::Int64`` Representation of the pointer to the execution context as returned by ``backtrace``\ .