Merge pull request JuliaCollections#99 from ExpandingMan/em/overhaul1

a few more improvements

Author: oscardssmith

Project.toml

@@ -1,6 +1,6 @@
 name = "AbstractTrees"
 uuid = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
-version = "0.3.5"
+version = "0.4.0"
 authors = ["Keno Fischer <[email protected]>"]
 
 [deps]

README.md

@@ -2,9 +2,68 @@
 
 [![Build Status](https://github.com/JuliaCollections/AbstractTrees.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/JuliaCollections/AbstractTrees.jl/actions/workflows/CI.yml)
 [![codecov](https://codecov.io/gh/JuliaCollections/AbstractTrees.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaCollections/AbstractTrees.jl)
-[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaCollections.github.io/AbstractTrees.jl/stable)
 
-This package provides several utilities for working with tree-like data structures.
-See the [documentation](https://JuliaCollections.github.io/AbstractTrees.jl/stable)
-for details,
-and [NEWS.md](NEWS.md) for information about important changes.
+[![][docs-stable-img]][docs-stable-url] [![][docs-latest-img]][docs-latest-url]
+
+A package for dealing with generalized tree-like data structures.
+
+## Examples
+```julia
+julia> t = [[1,2], [3,4]];  # AbstractArray and AbstractDict are trees
+
+julia> children(t)
+2-element Vector{Vector{Int64}}:
+ [1, 2]
+ [3, 4]
+
+julia> getdescendant(t, (2,1))
+3
+
+julia> collect(PreOrderDFS(t))  # iterate from root to leaves
+7-element Vector{Any}:
+  [[1, 2], [3, 4]]
+  [1, 2]
+ 1
+ 2
+  [3, 4]
+ 3
+ 4
+
+julia> collect(PostOrderDFS(t))  # iterate from leaves to root
+7-element Vector{Any}:
+ 1
+ 2
+  [1, 2]
+ 3
+ 4
+  [3, 4]
+  [[1, 2], [3, 4]]
+
+julia> collect(Leaves(t))  # iterate over leaves
+4-element Vector{Int64}:
+ 1
+ 2
+ 3
+ 4
+
+julia> struct FloatTree  # make your own trees
+        x::Float64
+        children::Vector{FloatTree}
+    end;
+
+julia> AbstractTrees.children(t::FloatTree) = t.children;
+
+julia> AbstractTrees.nodevalue(t::FloatTree) = t.x;
+
+julia> print_tree(FloatTree(NaN, [FloatTree(Inf, []), FloatTree(-Inf, [])]))
+NaN
+├─ Inf
+└─ -Inf
+```
+
+[docs-latest-img]: https://img.shields.io/badge/docs-latest-blue.svg
+[docs-latest-url]: https://JuliaCollections.github.io/AbstractTrees.jl/dev
+
+[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
+[docs-stable-url]: https://JuliaCollections.github.io/AbstractTrees.jl/stable
+

docs/src/faq.md

@@ -79,10 +79,11 @@ several major obstacles
 All of this means that you are unlikely to get type-stable code from AbstractTrees.jl without some
 effort.
 
-The simplest way around this is to define the `eltype` of tree iterators
+The simplest way around this is to define the `NodeType` trait and `nodetype` (analogous to
+`Base.IteratorEltype` and `eltype`):
 ```julia
-Base.IteratorEltype(::Type{<:TreeIterator{ExampleNode}}) = Base.HasEltype()
-Base.eltype(::Type{<:TreeIterator{ExampleNode}}) = ExampleNode
+AbstractTrees.NodeType(::Type{<:ExampleNode}) = HasNodeType()
+AbstractTrees.nodetype(::Type{<:ExampleNode}) = ExampleNode
 ```
 which is equivalent to asserting that all nodes of a tree are of the same type.  Performance
 critical code must ensure that it is possible to construct such a tree, which may not be trivial.

docs/src/index.md

@@ -35,7 +35,6 @@ prevsibling
 childrentype
 childtype
 childstatetype
-siblings
 ```
 
 !!! note
@@ -81,6 +80,38 @@ The default value of `ChildIndexing` is `NonIndexedChildren`.
 Types with the `IndexedChildren` trait *must* return an indexable object from `children` (i.e.
 `children(node)[idx]` must be valid for positive integers `idx`).
 
+#### `NodeType`
+```@docs
+NodeType
+NodeTypeUnknown
+HasNodeType
+```
+
+Providing the `HasNodeType` trait will guarantee that all nodes connected to the node must be of the
+type returned by [`nodetype`](@ref).
+
+An important use case of this trait is to guarantee the return types of a `TreeIterator`.  Tree
+nodes with `NodeTypeUnknown` cannot have type-stable iteration over the entire tree.
+
+For example
+```julia
+struct ExampleNode
+    x::Int
+    children::Vector{ExampleNode}
+end
+
+AbstractTrees.nodevalue(x::ExampleNode) = x.x
+AbstractTrees.children(x::ExampleNode) = x.children
+
+AbstractTrees.NodeType(::Type{<:ExampleNode}) = HasNodeType()
+AbstractTrees.nodetype(::Type{<:ExampleNode}) = ExampleNode
+```
+In this example, iteration over a tree of `ExampleNode`s is type-stable with `eltype`
+`ExampleNode`.
+
+Providing the `nodetype(::Type)` method is preferable to defining `nodetype(::ExampleNode)` because
+it ensures that `nodetype` can be involved at compile time even if values are not known.
+
 
 ## The Indexed Tree Interface
 The abstract tree interface assumes that all information about the descendants of a node is
@@ -114,9 +145,25 @@ prevsiblingindex
 rootindex
 ```
 
+## Additional Functions
+```@docs
+getdescendant
+nodevalues
+ischild
+isroot
+intree
+isdescendant
+treebreadth
+treeheight
+descendleft
+getroot
+```
+
 ## Example Implementations
 - All objects in base which define the abstract trees interface are defined in
     [`builtins.jl`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/src/builtins.jl).
-- [`IDTree`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/idtree.jl)
-- [`OneNode`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/onenode.jl)
-- [`OneTree`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/onetree.jl)
+- [`IDTree`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/examples/idtree.jl)
+- [`OneNode`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/examples/onenode.jl)
+- [`OneTree`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/examples/onetree.jl)
+- [`FSNode`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/examples/fstree.jl)
+- [`BinaryNode`](https://github.com/JuliaCollections/AbstractTrees.jl/blob/master/test/examples/binarytree.jl)

examples/binarytree_core.jl

@@ -24,7 +24,8 @@ include("printing.jl")
 export ParentLinks, StoredParents, ImplicitParents
 export SiblingLinks, StoredSiblings, ImplicitSiblings
 export ChildIndexing, IndexedChildren, NonIndexedChildren
-export nodevalue, children, parentlinks, siblinglinks, childindexing, childtype, childrentype
+export NodeType, HasNodeType, NodeTypeUnknown
+export nodetype, nodevalue, nodevalues, children, parentlinks, siblinglinks, childindexing, childtype, childrentype
 #extended interface
 export nextsibling, prevsibling
 
@@ -35,7 +36,7 @@ export ischild, isroot, isroot, intree, isdescendant, treesize, treebreadth, tre
 export TreeCursor, TrivialCursor, ImplicitCursor, SiblingCursor
 
 #indexing
-export childindex, childindices, rootindex, parentindex, nextsiblingindex, prevsiblingindex, IndexNode
+export getdescendant, childindices, rootindex, parentindex, nextsiblingindex, prevsiblingindex, IndexNode
 
 # iteration
 export TreeIterator, PreOrderDFS, PostOrderDFS, Siblings, Leaves, StatelessBFS, MapNode

examples/binarytree_easy.jl

@@ -1,12 +1,11 @@
 # Tree API implementations for builtin types
 
 children(x::AbstractArray) = x
-ChildIndexing(::AbstractArray) = IndexedChildren()
+
+children(x::Tuple) = x
 
 children(x::Expr) = x.args
-ChildIndexing(::Expr) = IndexedChildren()
 
 children(p::Pair) = (p[2],)
-ChildIndexing(::Pair) = IndexedChildren()
 
 children(dict::AbstractDict) = pairs(dict)