Block filter passed to find_by method on Block should be able to skip subtree

[mojavelinux]

Currently, if the block filter passed to Block#find_by returns false, the corresponding node is not included in the result set. However, the method still continues to discover descendant nodes (i.e., descend the subtree). It should be possible to return a value, such as :skip, that tells the method to skip the subtree altogether.

Current (does not include dlist, but includes all children)

doc.find_by {|b| b.context == :dlist ? false : true }

Proposed (does not include dlist or its children)

doc.find_by {|b| b.context == :dlist ? :skip : true }

[mojavelinux]

This is related to, but different from, #2900.

[mojavelinux]

An open question is whether it should be possible to include the node, but skip its children.

[mojavelinux]

I think we need to support both :skip and :skip_subtree. :skip is the same as false, except it also stops descending. :skip_subtree is the same as true, except it stop descending.

[mojavelinux]

To be consistent with NodeFilter, I think we should change the definition we are using for :skip to mean consider children. Hence, here's the list of possible return values:

• true - accept node and continue descending
• :skim - accept node, but stop descending (alternatives :skip_subtree, :skip_children)
• false - reject node and any children
• :skip - reject node, but still consider children
• (from 2900) raise StopIteration - stop traversing and return result

[mojavelinux]

The problem with that proposal is that it would break a lot of uses of find_by that rely on the existing true/false behavior. Therefore, we'll need to stick with :skip meaning to reject the node and any children.

• true - accept node and continue descending
• false - reject node, but still consider children
• :skip - reject node and any children
• :skip_children - accept node, but stop descending
• (from 2900) raise StopIteration - stop traversing and return result

[mojavelinux]

@Mogztter do you like this proposal? (see #2902 for the impl)