Add AnonymousWalk and update docstrings

Author: darsnack

docs/src/api.md

@@ -9,6 +9,15 @@ Functors.children
 Functors.isleaf
 ```
 
+```@docs
+Functors.AbstractWalk
+Functors.DefaultWalk
+Functors.StructuralWalk
+Functors.ExcludeWalk
+Functors.CachedWalk
+Functors.CollectWalk
+```
+
 ```@docs
 Functors.fmapstructure
 Functors.fcollect

src/Functors.jl

@@ -104,7 +104,8 @@ Equivalent to `functor(x)[1]`.
 children
 
 """
-    fmap(f, x; exclude = Functors.isleaf, walk = Functors._default_walk)
+    fmap(f, x, ys...; exclude = Functors.isleaf, walk = Functors.DefaultWalk()[, prune])
+    fmap(walk, f, x, ys...)
 
 A structure and type preserving `map`.
 
@@ -178,12 +179,23 @@ Foo("Bar([1, 2, 3])", (4, 5, "Bar(Foo(6, 7))"))
 To recurse into custom types without reconstructing them afterwards,
 use [`fmapstructure`](@ref).
 
-For advanced customization of the traversal behaviour, pass a custom `walk` function of the form `(f', xs) -> ...`.
-This function walks (maps) over `xs` calling the continuation `f'` to continue traversal.
+For advanced customization of the traversal behaviour,
+pass a custom `walk` function that subtypes [`Functors.AbstractWalk`](ref).
+The form `fmap(walk, f, x, ys...)` can be called for custom walks.
+The simpler form `fmap(f, x, ys...; walk = mywalk)` will wrap `mywalk` in
+[`ExcludeWalk`](@ref) then [`CachedWalk`](@ref).
 
 ```jldoctest withfoo
-julia> fmap(x -> 10x, m, walk=(f, x) -> x isa Bar ? x : Functors._default_walk(f, x))
-Foo(Bar([1, 2, 3]), (40, 50, Bar(Foo(6, 7))))
+julia> struct MyWalk <: Functors.AbstractWalk end
+
+julia> (::MyWalk)(recurse, x) = x isa Bar ? "hello" :
+                                            Functors.DefaultWalk()(recurse, x)
+
+julia> fmap(x -> 10x, m; walk = MyWalk())
+Foo("hello", (40, 50, "hello"))
+
+julia> fmap(MyWalk(), x -> 10x, m)
+Foo("hello", (4, 5, "hello"))
 ```
 
 The behaviour when the same node appears twice can be altered by giving a value

src/maps.jl

@@ -4,7 +4,7 @@ function fmap(f, x, ys...; exclude = isleaf,
                            walk = DefaultWalk(),
                            cache = IdDict(),
                            prune = NoKeyword())
-  _walk = CachedWalk(ExcludeWalk(walk, f, exclude), prune, cache)
+  _walk = CachedWalk(ExcludeWalk(AnonymousWalk(walk), f, exclude), prune, cache)
   fmap(_walk, f, x, ys...)
 end
 

src/walks.jl

@@ -1,5 +1,48 @@
+"""
+    AbstractWalk
+
+Any walk for use with [`fmap`](@ref) should inherit from this type.
+A walk subtyping `AbstractWalk` must satisfy the walk function interface:
+```julia
+struct MyWalk <: AbstractWalk end
+
+function (::MyWalk)(recurse, x, ys...)
+  # implement this
+end
+```
+The walk function is called on a node `x` in a Functors tree.
+It may also be passed associated nodes `ys...` in other Functors trees.
+The walk function recurses further into `(x, ys...)` by calling
+`recurse` on the child nodes.
+The choice of which nodes to recurse and in what order is custom to the walk.
+"""
 abstract type AbstractWalk end
 
+"""
+    AnonymousWalk(walk_fn)
+
+Wrap a `walk_fn` so that `AnonymousWalk(walk_fn) isa AbstractWalk`.
+This type only exists for backwards compatability and should be directly used.
+Attempting to wrap an existing `AbstractWalk` is a no-op (i.e. it is not wrapped).
+"""
+struct AnonymousWalk{F} <: AbstractWalk
+  walk::F
+end
+# do not wrap an AbstractWalk
+AnonymousWalk(walk::AbstractWalk) = walk
+
+(walk::AnonymousWalk)(recurse, x, ys...) = walk.walk(recurse, x, ys...)
+
+"""
+    DefaultWalk()
+
+The default walk behavior for Functors.jl.
+Walks all the [`Functors.children`](@ref) of trees `(x, ys...)` based on
+the structure of `x`.
+The resulting mapped child nodes are restructured into the type of `x`.
+
+See [`fmap`](@ref) for more information.
+"""
 struct DefaultWalk <: AbstractWalk end
 
 function (::DefaultWalk)(recurse, x, ys...)
@@ -8,10 +51,27 @@ function (::DefaultWalk)(recurse, x, ys...)
   re(map(recurse, func, yfuncs...))
 end
 
+"""
+    StructuralWalk()
+
+A structural variant of [`Functors.DefaultWalk`](@ref).
+The recursion behavior is identical, but the mapped children are not restructured.
+
+See [`fmapstructure`](@ref) for more information.
+"""
 struct StructuralWalk <: AbstractWalk end
 
 (::StructuralWalk)(recurse, x) = map(recurse, children(x))
 
+"""
+    ExcludeWalk(walk, fn, exclude)
+
+A walk that recurses nodes `(x, ys...)` according to `walk`,
+except when `exclude(x)` is true.
+Then, `fn(x, ys...)` is applied instead of recursing further.
+
+Typically wraps an existing `walk` for use with [`fmap`](@ref).
+"""
 struct ExcludeWalk{T, F, G} <: AbstractWalk
   walk::T
   fn::F
@@ -23,6 +83,18 @@ end
 
 struct NoKeyword end
 
+"""
+    CachedWalk(walk[; prune])
+
+A walk that recurses nodes `(x, ys...)` according to `walk` and storing the
+output of the recursion in a cache indexed by `x` (based on object ID).
+Whenever the cache already contains `x`, either:
+- `prune` is specified, then it is returned, or
+- `prune` is unspecified, and the previously cached recursion of `(x, ys...)`
+  returned.
+
+Typically wraps an existing `walk` for use with [`fmap`](@ref).
+"""
 struct CachedWalk{T, S} <: AbstractWalk
   walk::T
   prune::S
@@ -40,6 +112,15 @@ function (walk::CachedWalk)(recurse, x, ys...)
   end
 end
 
+"""
+    CollectWalk()
+
+A walk that recurses into a node `x` via [`Functors.children`](@ref),
+storing the recursion history in a cache.
+The resulting ordered recursion history is returned.
+
+See [`fcollect`](@ref) for more information.
+"""
 struct CollectWalk <: AbstractWalk
   cache::Base.IdSet{Any}
   output::Vector{Any}