[selectors] Remove 'match a selector', by making 'evaluate a selector' a usable API entry point.

Author: tabatkins

selectors/Overview.bs

@@ -568,6 +568,37 @@ Evaluating a Selector</h3>
 
 	This section describes how to <dfn export>evaluate a selector</dfn> against a set of elements.
 
+	APIs using this algorithm must provide a selector.
+	They may optionally provide:
+
+	<ul>
+		<li>
+			a <a>selector match list</a> of elements to match against.
+			If not specified, the <a>initial selector match list</a> for the selector's context is used.
+
+		<li>
+			a <a>scoping method</a> and <a>scoping root</a>.
+			If not specified, the selector defaults to being unscoped.
+
+		<li>
+			a set of <a>:scope elements</a>,
+			for resolving the '':scope'' pseudo-class against.
+			If not specified,
+			the set defaults to being empty.
+
+			If the selector is a <a>relative selector</a>,
+			the set of <a>:scope elements</a> must not be empty.
+
+			Note: Note that if the selector is scoped,
+			the scoping root is automatically taken as the <a>:scope element</a>,
+			so it doesn't have to be provided explicitly
+			unless a different result is desired.
+
+		<li>
+			which <a>pseudo-elements</a> are allowed to show up in the match list, if any.
+			If not specified, this defaults to allowing all pseudo-elements.
+	</ul>
+
 	A <a>selector</a> is evaluated against some initial list of elements,
 	as determined by the context that the selector is evaluated in:
 	the <dfn export>selector match list</dfn>.
@@ -578,18 +609,24 @@ Evaluating a Selector</h3>
 
 	The selector is processed from left to right in order,
 	with <a>simple selectors</a> filtering the <a>selector match list</a>,
-	and <a>combinators</a> changing the <a>selector match list</a> into something new.
+	and <a>combinators</a> and <a>pseudo-elements</a> changing the <a>selector match list</a> into something new.
 	If the selector is <a>scope-contained</a>
 	then after each <a>combinator</a>
 	the <a>selector match list</a> must be filtered
 	to contain only elements that are either the <a>scoping root</a>
 	or descendants of the <a>scoping root</a>.
+
 	If the selector is <a>scope-filtered</a>,
 	then after the selector is finished processing,
 	the <a>selector match list</a> must be filtered
 	to contain only elements that are either the <a>scoping root</a>
 	or descendants of the <a>scoping root</a>.
 
+	After the selector is finished matching,
+	the <a>selector match list</a> must be filtered
+	to only contain elements and <a>pseudo-elements</a>
+	allowed by the invoker of this algorithm.
+
 	When this process is done, the elements in the <a>selector match list</a>
 	are the elements said to match the selector.
 	If the order of elements matter,
@@ -3294,24 +3331,6 @@ Parse A Relative Selector</h3>
 			Return <var>selector</var>.
 	</ol>
 
-<h3 id='match-a-selector'>
-Match A Selector</h3>
-
-	This section describes how to <dfn export>match a selector</dfn> <var>selector</var>.
-	Optionally, a tree of nodes <var>nodes</var> to be matched against may be provided;
-	if not, the default <a>initial selector match list</a> for selectors in the given context is used as <var>nodes</var>.
-	Optionally, a <a>scoping root</a> and <a>scoping method</a> (<a>scope-contained</a> or <a>scope-filtered</a>) may be provided.
-	Optionally, an explicit <a>:scope elements</a> <var>element set</var> (which may be empty) may be provided.
-	It returns a list of zero or more elements.
-
-	<a>Evaluate a selector</a> <var>selector</var> against <var>nodes</var>
-	with the <a>scoping root</a>,
-	<a>scoping method</a>,
-	and <a>:scope elements</a>
-	if they were provided,
-	and return the elements that match the selector.
-	Return the nodes matched by the selector.
-
 
 <h2 id="changes">
 Changes</h2>

selectors/Overview.html

@@ -59,7 +59,7 @@
 </p>
   <h1 class="p-name no-ref" id=title>Selectors Level 4</h1>
   <h2 class="no-num no-toc no-ref heading settled heading" id=subtitle><span class=content>Editor’s Draft,
-    <span class=dt-updated><span class=value-title title=20140328>28 March 2014</span></span></span></h2>
+    <span class=dt-updated><span class=value-title title=20140329>29 March 2014</span></span></span></h2>
   <div data-fill-with=spec-metadata><dl><dt>This version:<dd><a class=u-url href=http://dev.w3.org/csswg/selectors>http://dev.w3.org/csswg/selectors</a><dt>Latest version:<dd><a href=http://www.w3.org/TR/selectors/>http://www.w3.org/TR/selectors/</a><dt>Editor’s Draft:<dd><a href=http://dev.w3.org/csswg/selectors>http://dev.w3.org/csswg/selectors</a><dt>Previous Versions:<dd><a href=http://www.w3.org/TR/2013/WD-selectors4-20130502/ rel=previous>http://www.w3.org/TR/2013/WD-selectors4-20130502/</a><dd><a href=http://www.w3.org/TR/2012/WD-selectors4-20120823/ rel=previous>http://www.w3.org/TR/2012/WD-selectors4-20120823/</a><dd><a href=http://www.w3.org/TR/2011/WD-selectors4-20110929/ rel=previous>http://www.w3.org/TR/2011/WD-selectors4-20110929/</a>
     <dt>Feedback:</dt>
         <dd><a href="mailto:www-style@w3.org?subject=%5Bselectors%5D%20feedback">www-style@w3.org</a>
@@ -237,8 +237,7 @@ <h2 class="no-num no-toc no-ref heading settled heading" id=contents><span class
 	<li><a href=#api-hooks><span class=secno>17</span> API Hooks</a>
 		<ul class=toc>
 		<li><a href=#parse-a-selector><span class=secno>17.1</span> Parse A Selector</a>
-		<li><a href=#parse-a-relative-selector><span class=secno>17.2</span> Parse A Relative Selector</a>
-		<li><a href=#match-a-selector><span class=secno>17.3</span> Match A Selector</a></ul>
+		<li><a href=#parse-a-relative-selector><span class=secno>17.2</span> Parse A Relative Selector</a></ul>
 	<li><a href=#changes><span class=secno>18</span> Changes</a>
 	<li><a href=#acknowledgements><span class=secno>19</span> Acknowledgements</a>
 	<li><a href=#conformance><span class=secno></span> Conformance</a>
@@ -797,6 +796,37 @@ <h3 class="heading settled heading" data-level=3.2 id=evaluating-selectors><span
 
 <p>	This section describes how to <dfn data-dfn-type=dfn data-export="" id=evaluate-a-selector>evaluate a selector<a class=self-link href=#evaluate-a-selector></a></dfn> against a set of elements.
 
+<p>	APIs using this algorithm must provide a selector.
+	They may optionally provide:
+
+<p>	<ul>
+		<li>
+			a <a data-link-type=dfn href=#selector-match-list title="selector match list">selector match list</a> of elements to match against.
+			If not specified, the <a data-link-type=dfn href=#initial-selector-match-list title="initial selector match list">initial selector match list</a> for the selector’s context is used.
+
+		<li>
+			a <a data-link-type=dfn href=#scoping-method- title="scoping method">scoping method</a> and <a data-link-type=dfn href=#scoping-root title="scoping root">scoping root</a>.
+			If not specified, the selector defaults to being unscoped.
+
+		<li>
+			a set of <a data-link-type=dfn href=#scope-element title=":scope elements">:scope elements</a>,
+			for resolving the <a class=css data-link-type=maybe href=#scope-pseudo title=:scope>:scope</a> pseudo-class against.
+			If not specified,
+			the set defaults to being empty.
+
+<p>			If the selector is a <a data-link-type=dfn href=#relative-selector- title="relative selector">relative selector</a>,
+			the set of <a data-link-type=dfn href=#scope-element title=":scope elements">:scope elements</a> must not be empty.
+
+<p class=note>			Note: Note that if the selector is scoped,
+			the scoping root is automatically taken as the <a data-link-type=dfn href=#scope-element title=":scope element">:scope element</a>,
+			so it doesn’t have to be provided explicitly
+			unless a different result is desired.
+
+		<li>
+			which <a data-link-type=dfn href=#pseudo-element title=pseudo-elements>pseudo-elements</a> are allowed to show up in the match list, if any.
+			If not specified, this defaults to allowing all pseudo-elements.
+	</ul>
+
 <p>	A <a data-link-type=dfn href=#selector title=selector>selector</a> is evaluated against some initial list of elements,
 	as determined by the context that the selector is evaluated in:
 	the <dfn data-dfn-type=dfn data-export="" id=selector-match-list>selector match list<a class=self-link href=#selector-match-list></a></dfn>.
@@ -807,18 +837,24 @@ <h3 class="heading settled heading" data-level=3.2 id=evaluating-selectors><span
 
 <p>	The selector is processed from left to right in order,
 	with <a data-link-type=dfn href=#simple title="simple selectors">simple selectors</a> filtering the <a data-link-type=dfn href=#selector-match-list title="selector match list">selector match list</a>,
-	and <a data-link-type=dfn href=#combinator title=combinators>combinators</a> changing the <a data-link-type=dfn href=#selector-match-list title="selector match list">selector match list</a> into something new.
+	and <a data-link-type=dfn href=#combinator title=combinators>combinators</a> and <a data-link-type=dfn href=#pseudo-element title=pseudo-elements>pseudo-elements</a> changing the <a data-link-type=dfn href=#selector-match-list title="selector match list">selector match list</a> into something new.
 	If the selector is <a data-link-type=dfn href=#scope-contained- title=scope-contained>scope-contained</a>
 	then after each <a data-link-type=dfn href=#combinator title=combinator>combinator</a>
 	the <a data-link-type=dfn href=#selector-match-list title="selector match list">selector match list</a> must be filtered
 	to contain only elements that are either the <a data-link-type=dfn href=#scoping-root title="scoping root">scoping root</a>
 	or descendants of the <a data-link-type=dfn href=#scoping-root title="scoping root">scoping root</a>.
-	If the selector is <a data-link-type=dfn href=#scope-filtered- title=scope-filtered>scope-filtered</a>,
+
+<p>	If the selector is <a data-link-type=dfn href=#scope-filtered- title=scope-filtered>scope-filtered</a>,
 	then after the selector is finished processing,
 	the <a data-link-type=dfn href=#selector-match-list title="selector match list">selector match list</a> must be filtered
 	to contain only elements that are either the <a data-link-type=dfn href=#scoping-root title="scoping root">scoping root</a>
 	or descendants of the <a data-link-type=dfn href=#scoping-root title="scoping root">scoping root</a>.
 
+<p>	After the selector is finished matching,
+	the <a data-link-type=dfn href=#selector-match-list title="selector match list">selector match list</a> must be filtered
+	to only contain elements and <a data-link-type=dfn href=#pseudo-element title=pseudo-elements>pseudo-elements</a>
+	allowed by the invoker of this algorithm.
+
 <p>	When this process is done, the elements in the <a data-link-type=dfn href=#selector-match-list title="selector match list">selector match list</a>
 	are the elements said to match the selector.
 	If the order of elements matter,
@@ -3401,24 +3437,6 @@ <h3 class="heading settled heading" data-level=17.2 id=parse-a-relative-selector
 			Return <var>selector</var>.
 	</ol>
 
-<h3 class="heading settled heading" data-level=17.3 id=match-a-selector><span class=secno>17.3 </span><span class=content>
-Match A Selector</span><a class=self-link href=#match-a-selector></a></h3>
-
-<p>	This section describes how to <dfn data-dfn-type=dfn data-export="" id=match-a-selector0>match a selector<a class=self-link href=#match-a-selector0></a></dfn> <var>selector</var>.
-	Optionally, a tree of nodes <var>nodes</var> to be matched against may be provided;
-	if not, the default <a data-link-type=dfn href=#initial-selector-match-list title="initial selector match list">initial selector match list</a> for selectors in the given context is used as <var>nodes</var>.
-	Optionally, a <a data-link-type=dfn href=#scoping-root title="scoping root">scoping root</a> and <a data-link-type=dfn href=#scoping-method- title="scoping method">scoping method</a> (<a data-link-type=dfn href=#scope-contained- title=scope-contained>scope-contained</a> or <a data-link-type=dfn href=#scope-filtered- title=scope-filtered>scope-filtered</a>) may be provided.
-	Optionally, an explicit <a data-link-type=dfn href=#scope-element title=":scope elements">:scope elements</a> <var>element set</var> (which may be empty) may be provided.
-	It returns a list of zero or more elements.
-
-<p>	<a data-link-type=dfn href=#evaluate-a-selector title="evaluate a selector">Evaluate a selector</a> <var>selector</var> against <var>nodes</var>
-	with the <a data-link-type=dfn href=#scoping-root title="scoping root">scoping root</a>,
-	<a data-link-type=dfn href=#scoping-method- title="scoping method">scoping method</a>,
-	and <a data-link-type=dfn href=#scope-element title=":scope elements">:scope elements</a>
-	if they were provided,
-	and return the elements that match the selector.
-	Return the nodes matched by the selector.
-
 
 <h2 class="heading settled heading" data-level=18 id=changes><span class=secno>18 </span><span class=content>
 Changes</span><a class=self-link href=#changes></a></h2>
@@ -3636,7 +3654,6 @@ <h2 class="no-num no-ref heading settled heading" id=index><span class=content>
 <li>:last-of-type, <a href=#last-of-type-pseudo title="section 12.5.4">12.5.4</a>
 <li>:link, <a href=#link-pseudo title="section 8.2">8.2</a>
 <li>:local-link, <a href=#local-link-pseudo title="section 8.3">8.3</a>
-<li>match a selector, <a href=#match-a-selector0 title="section 17.3">17.3</a>
 <li>:matches(), <a href=#matches-pseudo title="section 4.2">4.2</a>
 <li>next-sibling combinator, <a href=#next-sibling-combinator title="section 13.3">13.3</a>
 <li>:not(), <a href=#negation-pseudo title="section 4.3">4.3</a>