From 153f1ea15a6f55508a5874f17058e72279c968f3 Mon Sep 17 00:00:00 2001 From: Martin Angers Date: Thu, 29 Feb 2024 09:22:34 -0500 Subject: [PATCH] Add notes on cascadia behavior that may differ from jQuery`s --- README.md | 2 +- traversal.go | 6 ++++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 09562f8..7c101b8 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ Utility functions that are not in jQuery but are useful in Go are implemented as The complete [package reference documentation can be found here][doc]. -Please note that Cascadia's selectors do not necessarily match all supported selectors of jQuery (Sizzle). See the [cascadia project][cascadia] for details. Invalid selector strings compile to a `Matcher` that fails to match any node. Behaviour of the various functions that take a selector string as argument follows from that fact, e.g. (where `~` is an invalid selector string): +Please note that Cascadia's selectors do not necessarily match all supported selectors of jQuery (Sizzle). See the [cascadia project][cascadia] for details. Also, the selectors work more like the DOM's `querySelectorAll`, than jQuery's matchers - they have no concept of contextual matching (for some concrete examples of what that means, see [this ticket](https://github.com/andybalholm/cascadia/issues/61)). In practice, it doesn't matter very often but it's something worth mentioning. Invalid selector strings compile to a `Matcher` that fails to match any node. Behaviour of the various functions that take a selector string as argument follows from that fact, e.g. (where `~` is an invalid selector string): * `Find("~")` returns an empty selection because the selector string doesn't match anything. * `Add("~")` returns a new selection that holds the same nodes as the original selection, because it didn't add any node (selector string didn't match anything). diff --git a/traversal.go b/traversal.go index 5fa5315..c45fa5d 100644 --- a/traversal.go +++ b/traversal.go @@ -20,6 +20,12 @@ const ( // Find gets the descendants of each element in the current set of matched // elements, filtered by a selector. It returns a new Selection object // containing these matched elements. +// +// Note that as for all methods accepting a selector string, the selector is +// compiled and applied by the cascadia package and inherits its behavior and +// constraints regarding supported selectors. See the note on cascadia in +// the goquery documentation here: +// https://github.com/PuerkitoBio/goquery?tab=readme-ov-file#api func (s *Selection) Find(selector string) *Selection { return pushStack(s, findWithMatcher(s.Nodes, compileMatcher(selector))) }