a CSS selector compiler/engine\hypertarget{md_sfcode_node_modules_css_select_README_autotoc_md7209}{}\doxysection{What?}\label{md_sfcode_node_modules_css_select_README_autotoc_md7209}
css-\/select turns CSS selectors into functions that tests if elements match them. When searching for elements, testing is executed \char`\"{}from the top\char`\"{}, similar to how browsers execute CSS selectors.

In its default configuration, css-\/select queries the DOM structure of the \href{https://github.com/fb55/domhandler}{\texttt{ {\ttfamily domhandler}}} module (also known as htmlparser2 DOM). It uses \href{https://github.com/fb55/domutils}{\texttt{ {\ttfamily domutils}}} as its default adapter over the DOM structure. See Options below for details on querying alternative DOM structures.

{\bfseries{Features\+:}}


\begin{DoxyItemize}
\item Full implementation of CSS3 selectors
\item Partial implementation of j\+Query/\+Sizzle extensions
\item Very high test coverage
\item Pretty good performance
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_css_select_README_autotoc_md7210}{}\doxysection{Why?}\label{md_sfcode_node_modules_css_select_README_autotoc_md7210}
The traditional approach of executing CSS selectors, named left-\/to-\/right execution, is to execute every component of the selector in order, from left to right \+\_\+(duh)\+\_\+. The execution of the selector {\ttfamily a b} for example will first query for {\ttfamily a} elements, then search these for {\ttfamily b} elements. (That\textquotesingle{}s the approach of eg. \href{https://github.com/jquery/sizzle}{\texttt{ {\ttfamily Sizzle}}}, \href{https://github.com/dperini/nwmatcher/}{\texttt{ {\ttfamily nwmatcher}}} and \href{https://github.com/ded/qwery}{\texttt{ {\ttfamily qwery}}}.)

While this works, it has some downsides\+: Children of {\ttfamily a}s will be checked multiple times; first, to check if they are also {\ttfamily a}s, then, for every superior {\ttfamily a} once, if they are {\ttfamily b}s. Using \href{http://en.wikipedia.org/wiki/Big_O_notation}{\texttt{ Big O notation}}, that would be {\ttfamily O(n$^\wedge$(k+1))}, where {\ttfamily k} is the number of descendant selectors (that\textquotesingle{}s the space in the example above).

The far more efficient approach is to first look for {\ttfamily b} elements, then check if they have superior {\ttfamily a} elements\+: Using big O notation again, that would be {\ttfamily O(n)}. That\textquotesingle{}s called right-\/to-\/left execution.

And that\textquotesingle{}s what css-\/select does – and why it\textquotesingle{}s quite performant.\hypertarget{md_sfcode_node_modules_css_select_README_autotoc_md7211}{}\doxysection{How does it work?}\label{md_sfcode_node_modules_css_select_README_autotoc_md7211}
By building a stack of functions.

{\itshape Wait, what?}

Okay, so let\textquotesingle{}s suppose we want to compile the selector {\ttfamily a b} again, for right-\/to-\/left execution. We start by {\itshape parsing} the selector, which means we turn the selector into an array of the building-\/blocks of the selector, so we can distinguish them easily. That\textquotesingle{}s what the \href{https://github.com/fb55/css-what}{\texttt{ {\ttfamily css-\/what}}} module is for, if you want to have a look.

Anyway, after parsing, we end up with an array like this one\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{[}
\DoxyCodeLine{  \{ type: 'tag', name: 'a' \},}
\DoxyCodeLine{  \{ type: 'descendant' \},}
\DoxyCodeLine{  \{ type: 'tag', name: 'b' \}}
\DoxyCodeLine{] }

\end{DoxyCode}


Actually, this array is wrapped in another array, but that\textquotesingle{}s another story (involving commas in selectors).

Now that we know the meaning of every part of the selector, we can compile it. That\textquotesingle{}s where it becomes interesting.

The basic idea is to turn every part of the selector into a function, which takes an element as its only argument. The function checks whether a passed element matches its part of the selector\+: If it does, the element is passed to the next turned-\/into-\/a-\/function part of the selector, which does the same. If an element is accepted by all parts of the selector, it {\itshape matches} the selector and double rainbow ALL THE WAY.

As said before, we want to do right-\/to-\/left execution with all the big O improvements nonsense, so elements are passed from the rightmost part of the selector ({\ttfamily b} in our example) to the leftmost (\sout{which would be {\ttfamily c}} of course {\ttfamily a}).

\+\_\+//\+TODO\+: More in-\/depth description. Implementation details. Build a spaceship.\+\_\+\hypertarget{md_sfcode_node_modules_css_select_README_autotoc_md7212}{}\doxysection{API}\label{md_sfcode_node_modules_css_select_README_autotoc_md7212}

\begin{DoxyCode}{0}
\DoxyCodeLine{const CSSselect = require("{}css-\/select"{}); }

\end{DoxyCode}


{\bfseries{Note\+:}} css-\/select throws errors when invalid selectors are passed to it, contrary to the behavior in browsers, which swallow them. This is done to aid with writing css selectors, but can be unexpected when processing arbitrary strings.\hypertarget{md_sfcode_node_modules_css_select_README_autotoc_md7213}{}\doxysubsubsection{$<$tt$>$\+CSSselect(query, elems, options)$<$/tt$>$}\label{md_sfcode_node_modules_css_select_README_autotoc_md7213}
Queries {\ttfamily elems}, returns an array containing all matches.


\begin{DoxyItemize}
\item {\ttfamily query} can be either a CSS selector or a function.
\item {\ttfamily elems} can be either an array of elements, or a single element. If it is an element, its children will be queried.
\item {\ttfamily options} is described below.
\end{DoxyItemize}

Aliases\+: {\ttfamily CSSselect.\+select\+All(query, elems)}, {\ttfamily CSSselect.\+iterate(query, elems)}.\hypertarget{md_sfcode_node_modules_css_select_README_autotoc_md7214}{}\doxysubsubsection{$<$tt$>$\+CSSselect.\+compile(query)$<$/tt$>$}\label{md_sfcode_node_modules_css_select_README_autotoc_md7214}
Compiles the query, returns a function.\hypertarget{md_sfcode_node_modules_css_select_README_autotoc_md7215}{}\doxysubsubsection{$<$tt$>$\+CSSselect.\+is(elem, query, options)$<$/tt$>$}\label{md_sfcode_node_modules_css_select_README_autotoc_md7215}
Tests whether or not an element is matched by {\ttfamily query}. {\ttfamily query} can be either a CSS selector or a function.\hypertarget{md_sfcode_node_modules_css_select_README_autotoc_md7216}{}\doxysubsubsection{$<$tt$>$\+CSSselect.\+select\+One(query, elems, options)$<$/tt$>$}\label{md_sfcode_node_modules_css_select_README_autotoc_md7216}
Arguments are the same as for {\ttfamily CSSselect(query, elems)}. Only returns the first match, or {\ttfamily null} if there was no match.\hypertarget{md_sfcode_node_modules_css_select_README_autotoc_md7217}{}\doxysubsection{Options}\label{md_sfcode_node_modules_css_select_README_autotoc_md7217}

\begin{DoxyItemize}
\item {\ttfamily xml\+Mode}\+: When enabled, tag names will be case-\/sensitive. Default\+: {\ttfamily false}.
\item {\ttfamily strict}\+: Limits the module to only use CSS3 selectors. Default\+: {\ttfamily false}.
\item {\ttfamily root\+Func}\+: The last function in the stack, will be called with the last element that\textquotesingle{}s looked at. Should return {\ttfamily true}.
\item {\ttfamily adapter}\+: The adapter to use when interacting with the backing DOM structure. By default it uses \href{https://github.com/fb55/domutils}{\texttt{ {\ttfamily domutils}}}.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_css_select_README_autotoc_md7218}{}\doxysubsubsection{Custom Adapters}\label{md_sfcode_node_modules_css_select_README_autotoc_md7218}
A custom adapter must implement the following functions\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{isTag, existsOne, getAttributeValue, getChildren, getName, getParent,}
\DoxyCodeLine{getSiblings, getText, hasAttrib, removeSubsets, findAll, findOne }

\end{DoxyCode}


The method signature notation used below should be fairly intuitive -\/ if not, see the \href{https://github.com/ericelliott/rtype}{\texttt{ {\ttfamily rtype}}} or \href{https://www.typescriptlang.org/}{\texttt{ {\ttfamily Type\+Script}}} docs, as it is very similar to both of those. You may also want to look at -\/\href{https://github.com/fb55/domutils}{\texttt{ {\ttfamily domutils}}} to see the default -\/implementation, or at -\/\href{https://github.com/nrkn/css-select-browser-adapter/blob/master/index.js}{\texttt{ {\ttfamily css-\/select-\/browser-\/adapter}}} -\/for an implementation backed by the DOM.


\begin{DoxyCode}{0}
\DoxyCodeLine{\{}
\DoxyCodeLine{  // is the node a tag?}
\DoxyCodeLine{  isTag: ( node:Node ) => isTag:Boolean,}
\DoxyCodeLine{}
\DoxyCodeLine{  // does at least one of passed element nodes pass the test predicate?}
\DoxyCodeLine{  existsOne: ( test:Predicate, elems:[ElementNode] ) => existsOne:Boolean,}
\DoxyCodeLine{}
\DoxyCodeLine{  // get the attribute value}
\DoxyCodeLine{  getAttributeValue: ( elem:ElementNode, name:String ) => value:String,}
\DoxyCodeLine{}
\DoxyCodeLine{  // get the node's children}
\DoxyCodeLine{  getChildren: ( node:Node ) => children:[Node],}
\DoxyCodeLine{}
\DoxyCodeLine{  // get the name of the tag}
\DoxyCodeLine{  getName: ( elem:ElementNode ) => tagName:String,}
\DoxyCodeLine{}
\DoxyCodeLine{  // get the parent of the node}
\DoxyCodeLine{  getParent: ( node:Node ) => parentNode:Node,}
\DoxyCodeLine{}
\DoxyCodeLine{  /*}
\DoxyCodeLine{    get the siblings of the node. Note that unlike jQuery's `siblings` method,}
\DoxyCodeLine{    this is expected to include the current node as well}
\DoxyCodeLine{  */}
\DoxyCodeLine{  getSiblings: ( node:Node ) => siblings:[Node],}
\DoxyCodeLine{}
\DoxyCodeLine{  // get the text content of the node, and its children if it has any}
\DoxyCodeLine{  getText: ( node:Node ) => text:String,}
\DoxyCodeLine{}
\DoxyCodeLine{  // does the element have the named attribute?}
\DoxyCodeLine{  hasAttrib: ( elem:ElementNode, name:String ) => hasAttrib:Boolean,}
\DoxyCodeLine{}
\DoxyCodeLine{  // takes an array of nodes, and removes any duplicates, as well as any nodes}
\DoxyCodeLine{  // whose ancestors are also in the array}
\DoxyCodeLine{  removeSubsets: ( nodes:[Node] ) => unique:[Node],}
\DoxyCodeLine{}
\DoxyCodeLine{  // finds all of the element nodes in the array that match the test predicate,}
\DoxyCodeLine{  // as well as any of their children that match it}
\DoxyCodeLine{  findAll: ( test:Predicate, nodes:[Node] ) => elems:[ElementNode],}
\DoxyCodeLine{}
\DoxyCodeLine{  // finds the first node in the array that matches the test predicate, or one}
\DoxyCodeLine{  // of its children }
\DoxyCodeLine{  findOne: ( test:Predicate, elems:[ElementNode] ) => findOne:ElementNode,}
\DoxyCodeLine{}
\DoxyCodeLine{  /*}
\DoxyCodeLine{    The adapter can also optionally include an equals method, if your DOM}
\DoxyCodeLine{    structure needs a custom equality test to compare two objects which refer}
\DoxyCodeLine{    to the same underlying node. If not provided, `css-\/select` will fall back to}
\DoxyCodeLine{    `a === b`.}
\DoxyCodeLine{  */}
\DoxyCodeLine{  equals: ( a:Node, b:Node ) => Boolean}
\DoxyCodeLine{\} }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_css_select_README_autotoc_md7219}{}\doxysection{Supported selectors}\label{md_sfcode_node_modules_css_select_README_autotoc_md7219}
{\itshape As defined by CSS 4 and / or j\+Query.}


\begin{DoxyItemize}
\item Universal ({\ttfamily $\ast$})
\item Tag ({\ttfamily $<$tagname$>$})
\item Descendant ()
\item Child ({\ttfamily $>$})
\item Parent ({\ttfamily $<$}) $\ast$
\item Sibling ({\ttfamily +})
\item Adjacent ({\ttfamily $\sim$})
\item Attribute ({\ttfamily \mbox{[}attr=foo\mbox{]}}), with supported comparisons\+:
\begin{DoxyItemize}
\item {\ttfamily \mbox{[}attr\mbox{]}} (existential)
\item {\ttfamily =}
\item {\ttfamily $\sim$=}
\item {\ttfamily $\vert$=}
\item {\ttfamily $\ast$=}
\item {\ttfamily $^\wedge$=}
\item {\ttfamily \$=}
\item {\ttfamily !=} $\ast$
\item Also, {\ttfamily i} can be added after the comparison to make the comparison case-\/insensitive (eg. {\ttfamily \mbox{[}attr=foo i\mbox{]}}) $\ast$
\end{DoxyItemize}
\item Pseudos\+:
\begin{DoxyItemize}
\item {\ttfamily \+:not}
\item {\ttfamily \+:contains} $\ast$
\item {\ttfamily \+:icontains} $\ast$ (case-\/insensitive version of {\ttfamily \+:contains})
\item {\ttfamily \+:has} $\ast$
\item {\ttfamily \+:root}
\item {\ttfamily \+:empty}
\item {\ttfamily \+:parent} $\ast$
\item {\ttfamily \+:\mbox{[}first$\vert$last\mbox{]}-\/child\mbox{[}-\/of-\/type\mbox{]}}
\item {\ttfamily \+:only-\/of-\/type}, {\ttfamily \+:only-\/child}
\item {\ttfamily \+:nth-\/\mbox{[}last-\/\mbox{]}child\mbox{[}-\/of-\/type\mbox{]}}
\item {\ttfamily \+:link}
\item {\ttfamily \+:visited}, {\ttfamily \+:hover}, {\ttfamily \+:active} $\ast$ (these depend on optional Adapter methods, so these will work only if implemented in Adapter)
\item {\ttfamily \+:selected} $\ast$, {\ttfamily \+:checked}
\item {\ttfamily \+:enabled}, {\ttfamily \+:disabled}
\item {\ttfamily \+:required}, {\ttfamily \+:optional}
\item {\ttfamily \+:header}, {\ttfamily \+:button}, {\ttfamily \+:input}, {\ttfamily \+:text}, {\ttfamily \+:checkbox}, {\ttfamily \+:file}, {\ttfamily \+:password}, {\ttfamily \+:reset}, {\ttfamily \+:radio} etc. $\ast$
\item {\ttfamily \+:matches} $\ast$
\end{DoxyItemize}
\end{DoxyItemize}

{\bfseries{$\ast$}}\+: Not part of CSS3

\DoxyHorRuler{0}


License\+: BSD-\/2-\/\+Clause\hypertarget{md_sfcode_node_modules_css_select_README_autotoc_md7221}{}\doxysection{Security contact information}\label{md_sfcode_node_modules_css_select_README_autotoc_md7221}
To report a security vulnerability, please use the \href{https://tidelift.com/security}{\texttt{ Tidelift security contact}}. Tidelift will coordinate the fix and disclosure.\hypertarget{md_sfcode_node_modules_css_select_README_autotoc_md7222}{}\doxysection{$<$tt$>$css-\/select$<$/tt$>$ for enterprise}\label{md_sfcode_node_modules_css_select_README_autotoc_md7222}
Available as part of the Tidelift Subscription

The maintainers of {\ttfamily css-\/select} and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. \href{https://tidelift.com/subscription/pkg/npm-css-select?utm_source=npm-css-select&utm_medium=referral&utm_campaign=enterprise&utm_term=repo}{\texttt{ Learn more.}} 