Merge pull request #62 from jlumpe/printing

Misc changes to tree printing

Author: jlumpe

docs/src/api.md

@@ -25,4 +25,6 @@ AbstractTrees.printnode
 AbstractTrees.siblinglinks
 treemap
 treemap!
+AbstractTrees.DEFAULT_CHARSET
+AbstractTrees.ASCII_CHARSET
 ```

src/printing.jl

@@ -3,17 +3,19 @@
     print_tree(io::IO, tree; kwargs...)
     print_tree(f::Function, io::IO, tree; kwargs...)
 
-# Usage
-Prints an ASCII formatted representation of the `tree` to the given `io` object.
-By default all children will be printed up to a maximum level of 5, though this
-value can be overriden by the `maxdepth` parameter. Nodes that are truncated are
-indicated by a vertical ellipsis below the truncated node, this indication can be
-turned off by providing `indicate_truncation=false` as a kwarg. The charset to use in
-printing can be customized using the `charset` keyword argument.
-You can control the printing of individual nodes by passing a function `f(io, node)`;
-the default is [`AbstractTrees.printnode`](@ref).
+Print a text representation of `tree` to the given `io` object.
+
+# Arguments
+
+* `f::Function` - custom implementation of [`printnode`](@ref) to use. Should have the
+  signature `f(io::IO, node)`.
+* `maxdepth::Integer = 5` - truncate printing of subtrees at this depth.
+* `indicate_truncation::Bool = true` - print a vertical ellipsis character beneath
+  truncated nodes.
+* `charset::TreeCharSet` - [`TreeCharSet`](@ref) to use to print branches.
 
 # Examples
+
 ```julia
 julia> print_tree(stdout, Dict("a"=>"b","b"=>['c','d']))
 Dict{String,Any}("b"=>['c','d'],"a"=>"b")
@@ -50,7 +52,7 @@ Print a single node. The default is to show a compact representation of `node`.
 Override this if you want nodes printed in a custom way in [`print_tree`](@ref),
 or if you want your print function to print part of the tree by default.
 
-# Example
+# Examples
 
 ```
 struct MyNode{T}
@@ -60,9 +62,32 @@ end
 AbstractTrees.printnode(io::IO, node::MyNode) = print(io, "MyNode(\$(node.data))")
 ```
 """
-printnode(io::IO, node) = show(IOContext(io, :compact => true), node)
+printnode(io::IO, node) = show(IOContext(io, :compact => true, :limit => true), node)
+
+
+"""
+    repr_node(node; context=nothing)
+
+Get the string representation of a node using [`printnode`](@ref). This works
+analagously to `Base.repr`.
+
+`context` is an `IO` or `IOContext` object whose attributes are used for the
+I/O stream passed to `printnode`.
+"""
+function repr_node(node; context=nothing)
+    buf = IOBuffer()
+    io = context === nothing ? buf : IOContext(buf, context)
+    printnode(io, node)
+    return String(take!(buf))
+end
 
 
+"""
+    TreeCharSet
+
+Set of characters (or strings) used to pretty-print tree branches in
+[`print_tree`](@ref).
+"""
 struct TreeCharSet
     mid
     terminator
@@ -71,12 +96,22 @@ struct TreeCharSet
     trunc
 end
 
-# Default charset
-TreeCharSet() = TreeCharSet('├','└','│','─','⋮')
-TreeCharSet(mid, term, skip, dash) = TreeCharSet(mid, term, skip, dash, '⋮')
+"""Default `charset` argument used by [`print_tree`](@ref)."""
+const DEFAULT_CHARSET = TreeCharSet('├', '└', '│', '─', '⋮')
+"""Charset using only ASCII characters."""
+const ASCII_CHARSET = TreeCharSet("+", "\\", "|", "--", "...")
+
+function TreeCharSet()
+    Base.depwarn("The 0-argument constructor of TreeCharSet is deprecated, use AbstractTrees.DEFAULT_CHARSET instead.", :TreeCharSet)
+    return DEFAULT_CHARSET
+end
 
 
-function print_prefix(io, depth, charset, active_levels)
+"""
+Print tree branches in the initial part of a [`print_tree`](@ref) line, before
+the node itself is printed.
+"""
+function print_prefix(io::IO, depth::Int, charset::TreeCharSet, active_levels)
     for current_depth in 0:(depth-1)
         if current_depth in active_levels
             print(io,charset.skip," "^(textwidth(charset.dash)+1))
@@ -87,7 +122,7 @@ function print_prefix(io, depth, charset, active_levels)
 end
 
 function _print_tree(printnode::Function, io::IO, tree; maxdepth = 5, indicate_truncation = true,
-                     depth = 0, active_levels = Int[], charset = TreeCharSet(), withinds = false,
+                     depth = 0, active_levels = Int[], charset = DEFAULT_CHARSET, withinds = false,
                      inds = [], from = nothing, to = nothing, roottree = tree)
     nodebuf = IOBuffer()
     isa(io, IOContext) && (nodebuf = IOContext(nodebuf, io))
@@ -148,6 +183,8 @@ print_tree(tree, args...; kwargs...) = print_tree(stdout::IO, tree, args...; kwa
 
 
 """
+    repr_tree(tree; context=nothing, kw...)
+
 Get the string result of calling [`print_tree`](@ref) with the supplied arguments.
 
 The `context` argument works as it does in `Base.repr`.

test/printing.jl

@@ -1,10 +1,31 @@
 # Test print_tree()
 
 
-struct Num{I} end
-Num(I::Int) = Num{I}()
-Base.show(io::IO, ::Num{I}) where {I} = print(io, I)
-AbstractTrees.children(x::Num{I}) where {I} = (Num(I+1), Num(I+1))
+# count(pattern::String, string::String) and equivalent findall() method not
+# present in Julia 0.7
+function count_matches(pattern::AbstractString, string::AbstractString)
+    c = 0
+    next = 1
+
+    while true
+        match = findnext(pattern, string, next)
+        if match === nothing
+            return c
+        else
+            c += 1
+            next = match.stop + 1
+        end
+    end
+end
+
+
+# Node type that wraps an integer value `n` and has two children with value `n + 1`.
+# Resulting tree has infinite height.
+struct Num
+    n::Int
+end
+Base.show(io::IO, x::Num) = print(io, x.n)
+AbstractTrees.children(x::Num) = (Num(x.n+1), Num(x.n+1))
 
 struct SingleChildInfiniteDepth end
 AbstractTrees.children(::SingleChildInfiniteDepth) = (SingleChildInfiniteDepth(),)
@@ -31,34 +52,23 @@ AbstractTrees.children(::SingleChildInfiniteDepth) = (SingleChildInfiniteDepth()
     #       └─ 3
     #
 
+    truncation_char = AbstractTrees.DEFAULT_CHARSET.trunc
+
     for maxdepth in [3,5,8]
         ptxt = repr_tree(Num(0), maxdepth=maxdepth)
 
-        n1  = sum([1 for c in ptxt if c=="$(maxdepth-1)"[1]])
-        n2  = sum([1 for c in ptxt if c=="$maxdepth"[1]])
-        n3  = sum([1 for c in ptxt if c=="$(maxdepth+1)"[1]])
-
-        @test n1==2^(maxdepth-1)
-        @test n2==2^maxdepth
-        @test n3==0
-    end
-
-    # test that `print_tree(headnode)` prints truncation characters under each
-    # node at the default maxdepth level = 5
-    truncation_char = AbstractTrees.TreeCharSet().trunc
-    ptxt = repr_tree(Num(0))
-
-    n1  = sum([1 for c in ptxt if c=='5'])
-    n2  = sum([1 for c in ptxt if c=='6'])
-    n3  = sum([1 for c in ptxt if c==truncation_char])
-    @test n1==2^5
-    @test n2==0
-    @test n3==2^5
-
-    lines = split(ptxt, '\n')
-    for i in 1:length(lines)
-        if ~isempty(lines[i]) && lines[i][end] == '5'
-            @test lines[i+1][end] == truncation_char
+        # Check that we see depth #s the expected number of times
+        @test count_matches(string(maxdepth-1), ptxt) == 2^(maxdepth-1)
+        @test count_matches(string(maxdepth), ptxt) == 2^maxdepth
+        @test count_matches(string(maxdepth+1), ptxt) == 0
+
+        # test that `print_tree(headnode)` prints truncation characters under each
+        # node at the maximum depth
+        lines = split(ptxt, '\n')
+        for i in 1:length(lines)
+            if occursin(string(maxdepth), lines[i])
+                @test lines[i+1][end] == truncation_char
+            end
         end
     end