[selectors] Dfn 'evaluate a selector', make it take scoping into account, refine the 'Match a Selector' API hook.

Author: tabatkins

selectors/Overview.html

@@ -1373,15 +1373,36 @@ <h3 id=structure><span class=secno>3.1. </span> Structure and Terminology</h3>
   <h3 id=evaluating-selectors><span class=secno>3.2. </span> Evaluating a
    Selector</h3>
 
+  <p>This section describes how to <dfn data-export=data-export
+   id=evaluate-a-selector>evaluate a selector</dfn> against a set of
+   elements.
+
   <p>A <a href="#selector"><i>selector</i></a> is evaluated against some
    initial list of elements, as determined by the context that the selector
    is evaluated in: the <dfn data-export=data-export
-   id=selector-match-list>selector match list</dfn>. The selector is
-   processed from left to right in order, with <a href="#simple"><i>simple
+   id=selector-match-list>selector match list</dfn>. If the selector is <a
+   href="#scope-contained"><i>scope-contained</i></a>, the <a
+   href="#selector-match-list"><i>selector match list</i></a> is immediately
+   filtered to contain only elements that are either the <a
+   href="#scoping-root"><i>scoping root</i></a> or descendants of the <a
+   href="#scoping-root"><i>scoping root</i></a>. The selector is processed
+   from left to right in order, with <a href="#simple"><i>simple
    selectors</i></a> filtering the <i>selector match set</i>, and <a
    href="#combinator0"><i>combinators</i></a> changing the <i>selector match
-   set</i> into something new. When this process is done, the elements in the
-   <i>selector match set</i> are the elements said to match the selector.
+   set</i> into something new. If the selector is <a
+   href="#scope-contained"><i>scope-contained</i></a> then after each <a
+   href="#combinator0"><i>combinator</i></a> the <a
+   href="#selector-match-list"><i>selector match list</i></a> must be
+   filtered to contain only elements that are either the <a
+   href="#scoping-root"><i>scoping root</i></a> or descendants of the <a
+   href="#scoping-root"><i>scoping root</i></a>. If the selector is <a
+   href="#scope-filtered"><i>scope-filtered</i></a>, then after the selector
+   is finished processing, the <a href="#selector-match-list"><i>selector
+   match list</i></a> must be filtered to contain only elements that are
+   either the <a href="#scoping-root"><i>scoping root</i></a> or descendants
+   of the <a href="#scoping-root"><i>scoping root</i></a>. When this process
+   is done, the elements in the <i>selector match set</i> are the elements
+   said to match the selector.
 
   <p>For example, to evaluate the selector "div > i.name" against a document,
    the <a href="#selector-match-list"><i>selector match list</i></a> is first
@@ -4383,48 +4404,25 @@ <h3 id=parse-a-relative-selector><span class=secno>17.2. </span> Parse A
   <h3 id=match-a-selector><span class=secno>17.3. </span> Match A Selector</h3>
 
   <p> This section describes how to <dfn id=match-a-selector0>match a
-   selector</dfn> <var title="">selector</var> against a tree of nodes
+   selector</dfn> <var title="">selector</var>. Optionally, a tree of nodes
+   <var>nodes</var> to be matched against may be provided; if not, the
+   default <a href="#initial-selector-match-list"><i>initial selector match
+   list</i></a> for selectors in the given context is used as
    <var>nodes</var>. Optionally, a <a href="#scoping-root"><i>scoping
-   root</i></a> and scoping method (<a
+   root</i></a> and <a href="#scoping-methods"><i>scoping method</i></a> (<a
    href="#scope-contained"><i>scope-contained</i></a> or <a
    href="#scope-filtered"><i>scope-filtered</i></a>) may be provided.
    Optionally, an explicit <a href="#reference-element-set"><i>reference
    element set</i></a> <var>element set</var> (which may be empty) may be
    provided. It returns a list of zero or more elements.
 
-  <p> If an explicit <a href="#reference-element-set"><i>reference element
-   set</i></a> is given, this algorithm may be called without specifying a
-   tree of nodes. (The tree will be inferred from each element in the set;
-   this makes it easier to invoke the algorithm for a relative selector.)
-
-  <ol>
-   <li> If no explicit <a href="#reference-element-set"><i>reference element
-    set</i></a> was given, return the result of matching <var
-    title="">selector</var> against <var>nodes</var>, with the <a
-    href="#scoping-root"><i>scoping root</i></a> and scoping method if they
-    were provided.
-
-   <li> Otherwise, let <var>result</var> initially be the empty list.
-
-   <li> For each element <var>reference element</var> in <var>element
-    set</var>:
-    <ol>
-     <li> If <var>nodes</var> was not given, let <var>nodes</var> be all the
-      nodes in the same tree as <var>reference element</var>.
-
-     <li> Let <var>single result</var> be the result of matching <var
-      title="">selector</var> against <var>nodes</var>, with the <a
-      href="#scoping-root"><i>scoping root</i></a> and scoping method if they
-      were provided, and <var>reference element</var> as the <a
-      href="#reference-element-set"><i>reference element set</i></a>.
-
-     <li> Append each element in <var>single result</var> to
-      <var>result</var>, unless the element is already present in
-      <var>result</var>.
-    </ol>
-
-   <li> Return <var>result</var>.
-  </ol>
+  <p> <a href="#evaluate-a-selector"><i>Evaluate a selector</i></a> <var
+   title="">selector</var> against <var>nodes</var> with the <a
+   href="#scoping-root"><i>scoping root</i></a>, <a
+   href="#scoping-methods"><i>scoping method</i></a>, and <a
+   href="#reference-element-set"><i>reference element set</i></a> if they
+   were provided, and return the elements that match the selector. Return the
+   nodes matched by the selector.
 
   <h2 id=changes><span class=secno>18. </span> Changes</h2>
 

selectors/Overview.src.html

@@ -643,12 +643,30 @@ <h3 id="structure">
 <h3 id='evaluating-selectors'>
 Evaluating a Selector</h3>
 
+  <p>This section describes how to <dfn data-export>evaluate a selector</dfn> against a set of elements.
+
   <p>A <i>selector</i> is evaluated against some initial list of elements,
   as determined by the context that the selector is evaluated in:
   the <dfn data-export>selector match list</dfn>.
+  If the selector is <i>scope-contained</i>,
+  the <i>selector match list</i> is immediately filtered
+  to contain only elements that are either the <i>scoping root</i>
+  or descendants of the <i>scoping root</i>.
+
   The selector is processed from left to right in order,
   with <i>simple selectors</i> filtering the <i>selector match set</i>,
   and <i>combinators</i> changing the <i>selector match set</i> into something new.
+  If the selector is <i>scope-contained</i>
+  then after each <i>combinator</i>
+  the <i>selector match list</i> must be filtered
+  to contain only elements that are either the <i>scoping root</i>
+  or descendants of the <i>scoping root</i>.
+  If the selector is <i>scope-filtered</i>,
+  then after the selector is finished processing,
+  the <i>selector match list</i> must be filtered
+  to contain only elements that are either the <i>scoping root</i>
+  or descendants of the <i>scoping root</i>.
+
   When this process is done, the elements in the <i>selector match set</i>
   are the elements said to match the selector.
 
@@ -3208,48 +3226,22 @@ <h3 id='match-a-selector'>
 Match A Selector</h3>
 
   <p>
-    This section describes how to <dfn>match a selector</dfn> <var title=''>selector</var> against a tree of nodes <var>nodes</var>.
-    Optionally, a <i>scoping root</i> and scoping method (<i>scope-contained</i> or <i>scope-filtered</i>) may be provided.
+    This section describes how to <dfn>match a selector</dfn> <var title=''>selector</var>.
+    Optionally, a tree of nodes <var>nodes</var> to be matched against may be provided;
+    if not, the default <i>initial selector match list</i> for selectors in the given context is used as <var>nodes</var>.
+    Optionally, a <i>scoping root</i> and <i>scoping method</i> (<i>scope-contained</i> or <i>scope-filtered</i>) may be provided.
     Optionally, an explicit <i>reference element set</i> <var>element set</var> (which may be empty) may be provided.
     It returns a list of zero or more elements.
 
   <p>
-    If an explicit <i>reference element set</i> is given,
-    this algorithm may be called without specifying a tree of nodes.
-    (The tree will be inferred from each element in the set;
-    this makes it easier to invoke the algorithm for a relative selector.)
-
-  <ol>
-    <li>
-      If no explicit <i>reference element set</i> was given,
-      return the result of matching <var title=''>selector</var> against <var>nodes</var>,
-      with the <i>scoping root</i> and scoping method if they were provided.
-
-    <li>
-      Otherwise,
-      let <var>result</var> initially be the empty list.
-
-    <li>
-      For each element <var>reference element</var> in <var>element set</var>:
-
-      <ol>
-        <li>
-          If <var>nodes</var> was not given,
-          let <var>nodes</var> be all the nodes in the same tree as <var>reference element</var>.
+    <i>Evaluate a selector</i> <var title=''>selector</var> against <var>nodes</var>
+    with the <i>scoping root</i>,
+    <i>scoping method</i>,
+    and <i>reference element set</i>
+    if they were provided,
+    and return the elements that match the selector.
+    Return the nodes matched by the selector.
 
-        <li>
-          Let <var>single result</var> be the result of matching <var title=''>selector</var> against <var>nodes</var>,
-          with the <i>scoping root</i> and scoping method if they were provided,
-          and <var>reference element</var> as the <i>reference element set</i>.
-
-        <li>
-          Append each element in <var>single result</var> to <var>result</var>,
-          unless the element is already present in <var>result</var>.
-      </ol>
-
-    <li>
-      Return <var>result</var>.
-  </ol>