PathMatcher : Add in and containing

[murraystevenson]

These provide PathMatcher with equivalent behaviour to Gaffer's in and containing set expression operators.

This implementation of containing() is based on PathMatcher::intersection()'s existing find()-based approach, rather than Gaffer::SetExpressionAlgo's .match() & ( PathMatcher::ExactMatch | PathMatcher::DescendantMatch ).

Main quandary is what to name PathMatcher::in() as in is reserved in Python. For now, I've bound it to in_() as a placeholder for discussion. pathsIn()? commonDescendants() ? somethingBetterThatIHaventYetThoughtOf()?

[johnhaddon]

LGTM.

Main quandary is what to name PathMatcher::in() as in is reserved in Python. For now, I've bound it to in_() as a placeholder for discussion.

If we think in is definitely the best name, then binding as in_ would be the usual approach.

I still like in and containing in set expressions - they seem reasonably descriptive without being too long, and they're not overly technical. chrome in robot and buildings containing wood read pretty well to me. Matching them so there's continuity between the C++ API and the expression language has its benefits.

pathsIn()? commonDescendants() ? somethingBetterThatIHaventYetThoughtOf()

The only benefit of pathsIn() seems to be the underscore avoidance - it doesn't add much otherwise. commonDescendants() sounds odd, since it returns paths that aren't necessarily common to both matchers.

Other possibilities might be descendantsOf( paths ) and ancestorsOf( paths ). They're reasonably descriptive, but would still need documenting to say that we include exact matches in descendants and ancestors. And chrome descendantsOf robot and buildings ancestorsOf wood don't seem as good as what we have already.

Unless anyone else feels strongly, I think I'm inclined to stick with in_.

[murraystevenson]

in and containing do seem the most appropriate names, I wouldn't want to change them in the set expression syntax. Aside from the ergonomics, my main concern was in_() being the first method bound to Python with a trailing _ (having not found anywhere else in Cortex where we're doing that), but if that isn't a deal-breaker then I'm fine with things as they are.

[johnhaddon]

We don't seem to have methods with trailing _, but we have a few None_ enum bindings in Cortex, and a whole load in Gaffer. If we hadn't already established in and containing, and if this was likely to be widely used from Python, I might be looking for alternatives. But I think in_ will be fine.