001package org.jsoup.select; 002 003import org.jsoup.helper.Validate; 004import org.jsoup.nodes.Element; 005 006import java.util.ArrayList; 007import java.util.Collection; 008import java.util.IdentityHashMap; 009 010/** 011 * CSS-like element selector, that finds elements matching a query. 012 * 013 * <h2>Selector syntax</h2> 014 * <p> 015 * A selector is a chain of simple selectors, separated by combinators. Selectors are <b>case insensitive</b> (including against 016 * elements, attributes, and attribute values). 017 * </p> 018 * <p> 019 * The universal selector (*) is implicit when no element selector is supplied (i.e. {@code *.header} and {@code .header} 020 * is equivalent). 021 * </p> 022 * <table summary=""> 023 * <tr><th align="left">Pattern</th><th align="left">Matches</th><th align="left">Example</th></tr> 024 * <tr><td><code>*</code></td><td>any element</td><td><code>*</code></td></tr> 025 * <tr><td><code>tag</code></td><td>elements with the given tag name</td><td><code>div</code></td></tr> 026 * <tr><td><code>*|E</code></td><td>elements of type E in any namespace <i>ns</i></td><td><code>*|name</code> finds <code><fb:name></code> elements</td></tr> 027 * <tr><td><code>ns|E</code></td><td>elements of type E in the namespace <i>ns</i></td><td><code>fb|name</code> finds <code><fb:name></code> elements</td></tr> 028 * <tr><td><code>#id</code></td><td>elements with attribute ID of "id"</td><td><code>div#wrap</code>, <code>#logo</code></td></tr> 029 * <tr><td><code>.class</code></td><td>elements with a class name of "class"</td><td><code>div.left</code>, <code>.result</code></td></tr> 030 * <tr><td><code>[attr]</code></td><td>elements with an attribute named "attr" (with any value)</td><td><code>a[href]</code>, <code>[title]</code></td></tr> 031 * <tr><td><code>[^attrPrefix]</code></td><td>elements with an attribute name starting with "attrPrefix". Use to find elements with HTML5 datasets</td><td><code>[^data-]</code>, <code>div[^data-]</code></td></tr> 032 * <tr><td><code>[attr=val]</code></td><td>elements with an attribute named "attr", and value equal to "val"</td><td><code>img[width=500]</code>, <code>a[rel=nofollow]</code></td></tr> 033 * <tr><td><code>[attr="val"]</code></td><td>elements with an attribute named "attr", and value equal to "val"</td><td><code>span[hello="Cleveland"][goodbye="Columbus"]</code>, <code>a[rel="nofollow"]</code></td></tr> 034 * <tr><td><code>[attr^=valPrefix]</code></td><td>elements with an attribute named "attr", and value starting with "valPrefix"</td><td><code>a[href^=http:]</code></td></tr> 035 * <tr><td><code>[attr$=valSuffix]</code></td><td>elements with an attribute named "attr", and value ending with "valSuffix"</td><td><code>img[src$=.png]</code></td></tr> 036 * <tr><td><code>[attr*=valContaining]</code></td><td>elements with an attribute named "attr", and value containing "valContaining"</td><td><code>a[href*=/search/]</code></td></tr> 037 * <tr><td><code>[attr~=<em>regex</em>]</code></td><td>elements with an attribute named "attr", and value matching the regular expression</td><td><code>img[src~=(?i)\\.(png|jpe?g)]</code></td></tr> 038 * <tr><td></td><td>The above may be combined in any order</td><td><code>div.header[title]</code></td></tr> 039 * <tr><td><td colspan="3"><h3>Combinators</h3></td></tr> 040 * <tr><td><code>E F</code></td><td>an F element descended from an E element</td><td><code>div a</code>, <code>.logo h1</code></td></tr> 041 * <tr><td><code>E {@literal >} F</code></td><td>an F direct child of E</td><td><code>ol {@literal >} li</code></td></tr> 042 * <tr><td><code>E + F</code></td><td>an F element immediately preceded by sibling E</td><td><code>li + li</code>, <code>div.head + div</code></td></tr> 043 * <tr><td><code>E ~ F</code></td><td>an F element preceded by sibling E</td><td><code>h1 ~ p</code></td></tr> 044 * <tr><td><code>E, F, G</code></td><td>all matching elements E, F, or G</td><td><code>a[href], div, h3</code></td></tr> 045 * <tr><td><td colspan="3"><h3>Pseudo selectors</h3></td></tr> 046 * <tr><td><code>:lt(<em>n</em>)</code></td><td>elements whose sibling index is less than <em>n</em></td><td><code>td:lt(3)</code> finds the first 3 cells of each row</td></tr> 047 * <tr><td><code>:gt(<em>n</em>)</code></td><td>elements whose sibling index is greater than <em>n</em></td><td><code>td:gt(1)</code> finds cells after skipping the first two</td></tr> 048 * <tr><td><code>:eq(<em>n</em>)</code></td><td>elements whose sibling index is equal to <em>n</em></td><td><code>td:eq(0)</code> finds the first cell of each row</td></tr> 049 * <tr><td><code>:has(<em>selector</em>)</code></td><td>elements that contains at least one element matching the <em>selector</em></td><td><code>div:has(p)</code> finds divs that contain p elements </td></tr> 050 * <tr><td><code>:not(<em>selector</em>)</code></td><td>elements that do not match the <em>selector</em>. See also {@link Elements#not(String)}</td><td><code>div:not(.logo)</code> finds all divs that do not have the "logo" class.<p><code>div:not(:has(div))</code> finds divs that do not contain divs.</p></td></tr> 051 * <tr><td><code>:contains(<em>text</em>)</code></td><td>elements that contains the specified text. The search is case insensitive. The text may appear in the found element, or any of its descendants.</td><td><code>p:contains(jsoup)</code> finds p elements containing the text "jsoup".</td></tr> 052 * <tr><td><code>:matches(<em>regex</em>)</code></td><td>elements whose text matches the specified regular expression. The text may appear in the found element, or any of its descendants.</td><td><code>td:matches(\\d+)</code> finds table cells containing digits. <code>div:matches((?i)login)</code> finds divs containing the text, case insensitively.</td></tr> 053 * <tr><td><code>:containsOwn(<em>text</em>)</code></td><td>elements that directly contain the specified text. The search is case insensitive. The text must appear in the found element, not any of its descendants.</td><td><code>p:containsOwn(jsoup)</code> finds p elements with own text "jsoup".</td></tr> 054 * <tr><td><code>:matchesOwn(<em>regex</em>)</code></td><td>elements whose own text matches the specified regular expression. The text must appear in the found element, not any of its descendants.</td><td><code>td:matchesOwn(\\d+)</code> finds table cells directly containing digits. <code>div:matchesOwn((?i)login)</code> finds divs containing the text, case insensitively.</td></tr> 055 * <tr><td><code>:containsData(<em>data</em>)</code></td><td>elements that contains the specified <em>data</em>. The contents of {@code script} and {@code style} elements, and {@code comment} nodes (etc) are considered data nodes, not text nodes. The search is case insensitive. The data may appear in the found element, or any of its descendants.</td><td><code>script:contains(jsoup)</code> finds script elements containing the data "jsoup".</td></tr> 056 * <tr><td></td><td>The above may be combined in any order and with other selectors</td><td><code>.light:contains(name):eq(0)</code></td></tr> 057 * <tr><td colspan="3"><h3>Structural pseudo selectors</h3></td></tr> 058 * <tr><td><code>:root</code></td><td>The element that is the root of the document. In HTML, this is the <code>html</code> element</td><td><code>:root</code></td></tr> 059 * <tr><td><code>:nth-child(<em>a</em>n+<em>b</em>)</code></td><td><p>elements that have <code><em>a</em>n+<em>b</em>-1</code> siblings <b>before</b> it in the document tree, for any positive integer or zero value of <code>n</code>, and has a parent element. For values of <code>a</code> and <code>b</code> greater than zero, this effectively divides the element's children into groups of a elements (the last group taking the remainder), and selecting the <em>b</em>th element of each group. For example, this allows the selectors to address every other row in a table, and could be used to alternate the color of paragraph text in a cycle of four. The <code>a</code> and <code>b</code> values must be integers (positive, negative, or zero). The index of the first child of an element is 1.</p> 060 * In addition to this, <code>:nth-child()</code> can take <code>odd</code> and <code>even</code> as arguments instead. <code>odd</code> has the same signification as <code>2n+1</code>, and <code>even</code> has the same signification as <code>2n</code>.</td><td><code>tr:nth-child(2n+1)</code> finds every odd row of a table. <code>:nth-child(10n-1)</code> the 9th, 19th, 29th, etc, element. <code>li:nth-child(5)</code> the 5h li</td></tr> 061 * <tr><td><code>:nth-last-child(<em>a</em>n+<em>b</em>)</code></td><td>elements that have <code><em>a</em>n+<em>b</em>-1</code> siblings <b>after</b> it in the document tree. Otherwise like <code>:nth-child()</code></td><td><code>tr:nth-last-child(-n+2)</code> the last two rows of a table</td></tr> 062 * <tr><td><code>:nth-of-type(<em>a</em>n+<em>b</em>)</code></td><td>pseudo-class notation represents an element that has <code><em>a</em>n+<em>b</em>-1</code> siblings with the same expanded element name <em>before</em> it in the document tree, for any zero or positive integer value of n, and has a parent element</td><td><code>img:nth-of-type(2n+1)</code></td></tr> 063 * <tr><td><code>:nth-last-of-type(<em>a</em>n+<em>b</em>)</code></td><td>pseudo-class notation represents an element that has <code><em>a</em>n+<em>b</em>-1</code> siblings with the same expanded element name <em>after</em> it in the document tree, for any zero or positive integer value of n, and has a parent element</td><td><code>img:nth-last-of-type(2n+1)</code></td></tr> 064 * <tr><td><code>:first-child</code></td><td>elements that are the first child of some other element.</td><td><code>div {@literal >} p:first-child</code></td></tr> 065 * <tr><td><code>:last-child</code></td><td>elements that are the last child of some other element.</td><td><code>ol {@literal >} li:last-child</code></td></tr> 066 * <tr><td><code>:first-of-type</code></td><td>elements that are the first sibling of its type in the list of children of its parent element</td><td><code>dl dt:first-of-type</code></td></tr> 067 * <tr><td><code>:last-of-type</code></td><td>elements that are the last sibling of its type in the list of children of its parent element</td><td><code>tr {@literal >} td:last-of-type</code></td></tr> 068 * <tr><td><code>:only-child</code></td><td>elements that have a parent element and whose parent element hasve no other element children</td><td></td></tr> 069 * <tr><td><code>:only-of-type</code></td><td> an element that has a parent element and whose parent element has no other element children with the same expanded element name</td><td></td></tr> 070 * <tr><td><code>:empty</code></td><td>elements that have no children at all</td><td></td></tr> 071 * </table> 072 * 073 * @author Jonathan Hedley, jonathan@hedley.net 074 * @see Element#select(String) 075 */ 076public class Selector { 077 // not instantiable 078 private Selector() {} 079 080 /** 081 * Find elements matching selector. 082 * 083 * @param query CSS selector 084 * @param root root element to descend into 085 * @return matching elements, empty if none 086 * @throws Selector.SelectorParseException (unchecked) on an invalid CSS query. 087 */ 088 public static Elements select(String query, Element root) { 089 Validate.notEmpty(query); 090 return select(QueryParser.parse(query), root); 091 } 092 093 /** 094 * Find elements matching selector. 095 * 096 * @param evaluator CSS selector 097 * @param root root element to descend into 098 * @return matching elements, empty if none 099 */ 100 public static Elements select(Evaluator evaluator, Element root) { 101 Validate.notNull(evaluator); 102 Validate.notNull(root); 103 return Collector.collect(evaluator, root); 104 } 105 106 /** 107 * Find elements matching selector. 108 * 109 * @param query CSS selector 110 * @param roots root elements to descend into 111 * @return matching elements, empty if none 112 */ 113 public static Elements select(String query, Iterable<Element> roots) { 114 Validate.notEmpty(query); 115 Validate.notNull(roots); 116 Evaluator evaluator = QueryParser.parse(query); 117 ArrayList<Element> elements = new ArrayList<>(); 118 IdentityHashMap<Element, Boolean> seenElements = new IdentityHashMap<>(); 119 // dedupe elements by identity, not equality 120 121 for (Element root : roots) { 122 final Elements found = select(evaluator, root); 123 for (Element el : found) { 124 if (!seenElements.containsKey(el)) { 125 elements.add(el); 126 seenElements.put(el, Boolean.TRUE); 127 } 128 } 129 } 130 return new Elements(elements); 131 } 132 133 // exclude set. package open so that Elements can implement .not() selector. 134 static Elements filterOut(Collection<Element> elements, Collection<Element> outs) { 135 Elements output = new Elements(); 136 for (Element el : elements) { 137 boolean found = false; 138 for (Element out : outs) { 139 if (el.equals(out)) { 140 found = true; 141 break; 142 } 143 } 144 if (!found) 145 output.add(el); 146 } 147 return output; 148 } 149 150 /** 151 * Find the first element that matches the query. 152 * @param cssQuery CSS selector 153 * @param root root element to descend into 154 * @return the matching element, or <b>null</b> if none. 155 */ 156 public static Element selectFirst(String cssQuery, Element root) { 157 Validate.notEmpty(cssQuery); 158 return Collector.findFirst(QueryParser.parse(cssQuery), root); 159 } 160 161 public static class SelectorParseException extends IllegalStateException { 162 public SelectorParseException(String msg, Object... params) { 163 super(String.format(msg, params)); 164 } 165 } 166}