|
| 1 | +""" |
| 2 | + AbstractWalk |
| 3 | +
|
| 4 | +Any walk for use with [`fmap`](@ref) should inherit from this type. |
| 5 | +A walk subtyping `AbstractWalk` must satisfy the walk function interface: |
| 6 | +```julia |
| 7 | +struct MyWalk <: AbstractWalk end |
| 8 | +
|
| 9 | +function (::MyWalk)(recurse, x, ys...) |
| 10 | + # implement this |
| 11 | +end |
| 12 | +``` |
| 13 | +The walk function is called on a node `x` in a Functors tree. |
| 14 | +It may also be passed associated nodes `ys...` in other Functors trees. |
| 15 | +The walk function recurses further into `(x, ys...)` by calling |
| 16 | +`recurse` on the child nodes. |
| 17 | +The choice of which nodes to recurse and in what order is custom to the walk. |
| 18 | +""" |
| 19 | +abstract type AbstractWalk end |
| 20 | + |
| 21 | +""" |
| 22 | + AnonymousWalk(walk_fn) |
| 23 | +
|
| 24 | +Wrap a `walk_fn` so that `AnonymousWalk(walk_fn) isa AbstractWalk`. |
| 25 | +This type only exists for backwards compatability and should be directly used. |
| 26 | +Attempting to wrap an existing `AbstractWalk` is a no-op (i.e. it is not wrapped). |
| 27 | +""" |
| 28 | +struct AnonymousWalk{F} <: AbstractWalk |
| 29 | + walk::F |
| 30 | + |
| 31 | + function AnonymousWalk(walk::F) where F |
| 32 | + Base.depwarn("Wrapping a custom walk function as an `AnonymousWalk`. Future versions will only support custom walks that explicitly subtyle `AbstractWalk`.", :AnonymousWalk) |
| 33 | + return new{F}(walk) |
| 34 | + end |
| 35 | +end |
| 36 | +# do not wrap an AbstractWalk |
| 37 | +AnonymousWalk(walk::AbstractWalk) = walk |
| 38 | + |
| 39 | +(walk::AnonymousWalk)(recurse, x, ys...) = walk.walk(recurse, x, ys...) |
| 40 | + |
| 41 | +""" |
| 42 | + DefaultWalk() |
| 43 | +
|
| 44 | +The default walk behavior for Functors.jl. |
| 45 | +Walks all the [`Functors.children`](@ref) of trees `(x, ys...)` based on |
| 46 | +the structure of `x`. |
| 47 | +The resulting mapped child nodes are restructured into the type of `x`. |
| 48 | +
|
| 49 | +See [`fmap`](@ref) for more information. |
| 50 | +""" |
| 51 | +struct DefaultWalk <: AbstractWalk end |
| 52 | + |
| 53 | +function (::DefaultWalk)(recurse, x, ys...) |
| 54 | + func, re = functor(x) |
| 55 | + yfuncs = map(y -> functor(typeof(x), y)[1], ys) |
| 56 | + re(map(recurse, func, yfuncs...)) |
| 57 | +end |
| 58 | + |
| 59 | +""" |
| 60 | + StructuralWalk() |
| 61 | +
|
| 62 | +A structural variant of [`Functors.DefaultWalk`](@ref). |
| 63 | +The recursion behavior is identical, but the mapped children are not restructured. |
| 64 | +
|
| 65 | +See [`fmapstructure`](@ref) for more information. |
| 66 | +""" |
| 67 | +struct StructuralWalk <: AbstractWalk end |
| 68 | + |
| 69 | +(::StructuralWalk)(recurse, x) = map(recurse, children(x)) |
| 70 | + |
| 71 | +""" |
| 72 | + ExcludeWalk(walk, fn, exclude) |
| 73 | +
|
| 74 | +A walk that recurses nodes `(x, ys...)` according to `walk`, |
| 75 | +except when `exclude(x)` is true. |
| 76 | +Then, `fn(x, ys...)` is applied instead of recursing further. |
| 77 | +
|
| 78 | +Typically wraps an existing `walk` for use with [`fmap`](@ref). |
| 79 | +""" |
| 80 | +struct ExcludeWalk{T, F, G} <: AbstractWalk |
| 81 | + walk::T |
| 82 | + fn::F |
| 83 | + exclude::G |
| 84 | +end |
| 85 | + |
| 86 | +(walk::ExcludeWalk)(recurse, x, ys...) = |
| 87 | + walk.exclude(x) ? walk.fn(x, ys...) : walk.walk(recurse, x, ys...) |
| 88 | + |
| 89 | +struct NoKeyword end |
| 90 | + |
| 91 | +usecache(::Union{AbstractDict, AbstractSet}, x) = |
| 92 | + isleaf(x) ? anymutable(x) : ismutable(x) |
| 93 | +usecache(::Nothing, x) = false |
| 94 | + |
| 95 | +@generated function anymutable(x::T) where {T} |
| 96 | + ismutabletype(T) && return true |
| 97 | + subs = [:(anymutable(getfield(x, $f))) for f in QuoteNode.(fieldnames(T))] |
| 98 | + return Expr(:(||), subs...) |
| 99 | +end |
| 100 | + |
| 101 | +""" |
| 102 | + CachedWalk(walk[; prune]) |
| 103 | +
|
| 104 | +A walk that recurses nodes `(x, ys...)` according to `walk` and storing the |
| 105 | +output of the recursion in a cache indexed by `x` (based on object ID). |
| 106 | +Whenever the cache already contains `x`, either: |
| 107 | +- `prune` is specified, then it is returned, or |
| 108 | +- `prune` is unspecified, and the previously cached recursion of `(x, ys...)` |
| 109 | + returned. |
| 110 | +
|
| 111 | +Typically wraps an existing `walk` for use with [`fmap`](@ref). |
| 112 | +""" |
| 113 | +struct CachedWalk{T, S} <: AbstractWalk |
| 114 | + walk::T |
| 115 | + prune::S |
| 116 | + cache::IdDict{Any, Any} |
| 117 | +end |
| 118 | +CachedWalk(walk; prune = NoKeyword(), cache = IdDict()) = |
| 119 | + CachedWalk(walk, prune, cache) |
| 120 | + |
| 121 | +function (walk::CachedWalk)(recurse, x, ys...) |
| 122 | + should_cache = usecache(walk.cache, x) |
| 123 | + if should_cache && haskey(walk.cache, x) |
| 124 | + return walk.prune isa NoKeyword ? walk.cache[x] : walk.prune |
| 125 | + else |
| 126 | + ret = walk.walk(recurse, x, ys...) |
| 127 | + if should_cache |
| 128 | + walk.cache[x] = ret |
| 129 | + end |
| 130 | + return ret |
| 131 | + end |
| 132 | +end |
| 133 | + |
| 134 | +""" |
| 135 | + CollectWalk() |
| 136 | +
|
| 137 | +A walk that recurses into a node `x` via [`Functors.children`](@ref), |
| 138 | +storing the recursion history in a cache. |
| 139 | +The resulting ordered recursion history is returned. |
| 140 | +
|
| 141 | +See [`fcollect`](@ref) for more information. |
| 142 | +""" |
| 143 | +struct CollectWalk <: AbstractWalk |
| 144 | + cache::Base.IdSet{Any} |
| 145 | + output::Vector{Any} |
| 146 | +end |
| 147 | +CollectWalk() = CollectWalk(Base.IdSet(), Any[]) |
| 148 | + |
| 149 | +# note: we don't have an `OrderedIdSet`, so we use an `IdSet` for the cache |
| 150 | +# (to ensure we get exactly 1 copy of each distinct array), and a usual `Vector` |
| 151 | +# for the results, to preserve traversal order (important downstream!). |
| 152 | +function (walk::CollectWalk)(recurse, x) |
| 153 | + if usecache(walk.cache, x) && (x in walk.cache) |
| 154 | + return walk.output |
| 155 | + end |
| 156 | + # to exclude, we wrap this walk in ExcludeWalk |
| 157 | + usecache(walk.cache, x) && push!(walk.cache, x) |
| 158 | + push!(walk.output, x) |
| 159 | + map(recurse, children(x)) |
| 160 | + |
| 161 | + return walk.output |
| 162 | +end |
0 commit comments