oga/doc/css_selectors.md

# CSS Selectors Specification

This document acts as an alternative specification to the official W3
[CSS3 Selectors Specification][w3spec]. This document specifies only the
selectors supported by Oga itself. Only CSS3 selectors are covered, CSS4 is not
part of this specification.

This document is best viewed in the YARD generated documentation or any other
Markdown viewer that supports the [Kramdown][kramdown] syntax. Alternatively it
can be viewed in its raw form.

## Abstract

The official W3 specification on CSS selectors is anything but pleasant to read.
A lack of good examples and unspecified behaviour are just two of many problems.
This document was written as a reference guide for myself as well as a way for
others to more easily understand how CSS selectors work.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be
interpreted as described in [RFC 2119][rfc-2119].

## Syntax

To describe syntax elements of CSS selectors this document uses the same grammar
as [Ragel][ragel]. For example, an integer would be defined as following:

    integer = [0-9]+;

In turn an integer that can optionally be prefixed by `+` or `-` would be
defined as following:

    integer = ('+' | '-')* [0-9]+;

A quick and basic crash course of the Ragel grammar:

* `*`: zero or more instance of the preceding token(s)
* `+`: one or more instances of the preceding token(s)
* `(` and `)`: used for grouping expressions together
* `^`: inverts a match, thus `^[0-9]` means "anything but a single digit"
* `"..."` or `'...'`: a literal character, `"x"` would match the literal "x"
* `|`: the OR operator, `x | y` translates to "x OR y"
* `[...]`: used to define a sequence, `[0-9]` translates to "0 OR 1 OR 2 OR
  3..." all the way upto 9

Semicolons are used to terminate lines. While not strictly required in this
specification they are included in order to produce a Ragel syntax compatible
grammar.

See the Ragel documentation for more information on the grammar.

## Terminology

local name
: The name of an element without a namespace. For the element `<strong>` the
  local name is `strong`.

namespace prefix
: The namespace prefix of an element. For the element `<foo:strong>` the
  namespace prefix is `foo`.

expression
: A single or multiple selectors used together to retrieve a set of elements
  from a document.

## Selector Scoping

Whenever a selector is used to match an element the selector applies to all
nodes in the context. For example, the selector `foo` would match all `foo`
elements at any position in the document. On the other hand, the selector
`foo bar` only matches any `bar` elements that are a descedant of any `foo`
element.

In XPath the corresponding axis for this is `descendant`. In other words, this
CSS expression:

    foo

is the same as this XPath expression:

    descendant::foo

In turn this CSS expression:

    foo bar

is the same as this XPath expression:

    descendant::foo/::bar

Note that in the various XPath examples the `descendant` axis is omitted in
order to enhance readability.

### Syntax

A CSS expression is made up of multiple selectors separated by one or more
spaces. There MUST be at least 1 space between two selectors, there MAY be more
than one. Multiple spaces do not alter the behaviour of the expression in any
way.

## Universal Selector

W3 chapter: <http://www.w3.org/TR/css3-selectors/#universal-selector>

The universal selector `*` (also known as the "wildcard selector") can be used
to match any element, regardless of its local name or namespace prefix.

Example XML:

    <root>
        <foo></foo>
        <bar></bar>
    </root>

CSS:

    root *

This would return a set containing two elements: `<foo>` and `<bar>`

The corresponding XPath is also `*`.

### Syntax

The syntax for the universal selector is very simple:

    universal = '*';

## Element Selector

W3 chapter: <http://www.w3.org/TR/css3-selectors/#type-selectors>

The element selector (known as "Type selector" in the official W3 specification)
can be used to match a set of elements by their local name or namespace. The
selector `foo` is used to match all elements with the local name being set to
`foo`.

Example XML:

    <root>
        <foo />
        <bar />
    </root>

CSS:

    root foo

This would return a set with only the `<foo>` element.

This selector can be used in combination with the
[Universal Selector][universal-selector]. This allows one to select elements
using both a given local name and namespace. The syntax for this is as
following:

    ns-prefix|local-name

Here the pipe (`|`) character separates the namespace prefix and the local name.
Both can either be an identifier or a wildcard. For example, the selector
`rb|foo` matches all elements with local name `foo` and namespace prefix `rb`.

The namespace prefix MAY be left out producing the selector `|local-name`. In
this case the selector only matches elements _without_ a namespace prefix.

If a namespace prefix is given and it's _not_ a wildcard then elements without a
namespace prefix will _not_ be matched.

The corresponding XPath expression for such a selector is
`ns-prefix:local-name`. For example, `rb|foo` in CSS is the same as `rb:foo` in
XPath.

### Syntax

The syntax for just the local name is as following:

    identifier = '*' | [a-zA-Z]+ [a-zA-Z\-_0-9]*;

The wildcard is put in place to allow a single rule to be used for both names
and wildcards.

The syntax for selecting an element including a namespace prefix is as
following:

    ns_plus_local_name = identifier* '|' identifier

This would match `|foo`, `*|foo` and `foo|bar`. In order to match `foo` the
regular `identifier` rule declared above can be used.

## Class Selector

Class selectors can be used to select a set of elements based on the values set
in the `class` attribute. Class selectors start with a period (`.`) followed by
an identifier. Multiple class selectors can be chained together, matching only
elements that have all the specified classes set.

As an example, `.foo` can be used to select all elements that have "foo" set in
the `class` attribute, either as the sole or one of many values. In turn,
`.foo.bar` matches elements that have both "foo" and "bar" set as the class.

Example XML:

    <root>
        <a class="first" />
        <b class="second" />
    </root>

Using the CSS selector `.first` would return a set containing only the `<a>`
element. Using `.first.second` would return a set containing both the `<a>` and
`<b>` nodes.

### Syntax

    identifier = '*' | [a-zA-Z]+ [a-zA-Z\-_0-9]*;

    # .foo, .foo.bar, .foo.bar.baz, etc
    class = ('.' identifier)+;

## ID Selector

The ID selector can be used to match elements where the value of the `id`
attribute matches whatever is specified in the selector. ID selectors start with
a hash sign (`#`) followed by an identifier.

While technically multiple ID selectors _can_ be chained together, HTML only
allows elements to have a single ID. As a result doing so is fairly useless.
Unlike classes IDs are globally unique, no two elements can have the same ID.

Example XML:

    <root>
        <a id="first" />
        <b id="second" />
    </root>

Using the CSS selector `#first` would return a set containing only the `<a>`
node.

### Syntax

    identifier = '*' | [a-zA-Z]+ [a-zA-Z\-_0-9]*;

    # .foo, .foo.bar, .foo.bar.baz, etc
    class = ('#' identifier)+;

## Attribute Selector

W3 chapter: <http://www.w3.org/TR/css3-selectors/#attribute-selectors>

Attribute selectors can be used to further narrow down a set of elements based
on their attribute list. In XPath these selectors are known as "predicates". For
example, the selector `foo[bar]` matches all `foo` elements that have a `bar`
attribute, regardless of the value of said attribute.

Example XML:

    <root>
        <foo number="1" />
        <bar />
    </root>

CSS:

    root foo[number]

This would return a set containing only the `<foo>` element since the `<bar>`
element has no attributes.

For the CSS expression `foo[number]` the corresponding XPath expression is the
following:

    foo[@number]

When specifying an attribute you MAY include an operator and a value to match.
In this case you MUST include an attribute value surrounded by either single or
double quotes (but not a combination of the two).

There are 6 operators available:

* `=`: equals operator
* `~=`: whitespace-in operator
* `^=`: starts-with operator
* `$=`: ends-with operator
* `*=`: contains operator
* `|=`: hyphen-starts-with operator

### Equals Operator

The equals operator matches an element if a given attribute value equals the
value specified. For example, `foo[number="1"]` matches all `foo` elements that
have a `number` attribute who's value is _exactly_ "1".

Example XML:

    <root>
        <foo number="1" />
        <foo number="2" />
    </root>

CSS:

    root foo[number="1"]

This would return a set containing only the first `<foo>` element.

The corresponding XPath expression is quite similar. For `foo[number="1"]` this
would be:

    foo[@number="1"]

### Whitespace-in Operator

This operator matches an element if the given attribute value consists out of
space separated values of which one is exactly the given value. For example,
`foo[numbers~="1"]` matches all `foo` elements that have the value `"1"` in the
`numbers` attribute.

Example XML:

    <root>
        <foo numbers="1 2 3" />
        <foo numbers="4 bar 6" />
    </root>

CSS:

    root foo[numbers~="1"]

This would return a set containing only the first `foo` element. On the other
hand, if one were to use the expression `root foo[numbers~="bar"]` instead then
only the second `<foo>` element would be matched.

The corresponding XPath expression is quite complex, `foo[numbers~="1"]` is
translated into the following XPath expression:

    foo[contains(concat(" ", @numbers, " "), concat(" ", "1", " "))]

The `concat` calls are used to ensure the expression doesn't match the substring
of an attrbitue value and that the expression matches elements of which the
attribute only has a single value. If `foo[contains(@numbers, ' 1 ')]` were to
be used then attributes such as `<foo numbers="1" />` would not be matched.

Software implementing this selector are free to decide how they concatenate
spaces around the value to match. Both Oga and Nokogiri use an extra call to
`concat` but the following would be perfectly valid too:

    foo[contains(concat(" ", @numbers, " "), " 1 ")]

### Starts-with Operator

This operator matches elements of which the attribute value starts _exactly_
with the given value. For example, `foo[numbers^="1"]` would match the element
`<foo numbers="1 2 3" />` but _not_ the element `<foo numbers="2 3 1" />`.

For `foo[numbers^="1"]` the corresponding XPath expression is as following:

    foo[starts-with(@numbers, "1")]

### Ends-with Operator

This operator matches elements of which the attribute value ends _exactly_ with
the given value. For example, `foo[numbers$="3"]` would match the element `<foo
numbers="1 2 3" />` but _not_ the element `<foo numbers="2 3 1" />`.

The corresponding XPath expression is quite complex due to a lack of a
`ends-with` function in XPath. Instead one has to resort to using the
`substring()` function. As such the corresponding XPath expression for
`foo[bar="baz"]` is as following:

    foo[substring(@bar, string-length(@bar) - string-length("baz") + 1, string-length("baz")) = "baz"]

### Contains Operator

This operator matches elements of which the attribute value contains the given
value. For example, `foo[bar*="baz"]` would match both `<foo bar="bazzzz" />`
and `<foo bar="hello baz" />`.

For `foo[bar*="baz"]` the corresponding XPath expression is as following:

    foo[contains(@bar, "baz")]

### Hyphen-starts-with Operator

This operator matches elements of which the attribute value is a hyphen
separated list of values that starts _exactly_ with the given value. For
example, `foo[numbers|="1"]` matches `<foo numbers="1-2-3" />` but not
`<foo numbers="2-1-3" />`.

For `foo[numbers|="1"]` the corresponding XPath expression is as following:

    foo[@numbers = "1" or starts-with(@numbers, concat("1", "-"))]

Note that this selector will also match elements such as
`<foo numbers="1- foo bar" />`.

### Syntax

The syntax of the various attribute selectors can be described as following:

    # Strings are used for the attribute values

    dquote = '"';
    squote = "'";

    string_dquote = dquote ^dquote* dquote;
    string_squote = squote ^squote* squote;

    string = string_dquote | string_squote;

    # The `identifier` rule is the same as the one used for matching element
    # names.
    attr_test = identifier '[' space* identifier (space* '=' space* string)* space* ']';

Whitespace inside the brackets does not affect the behaviour of the selector.

## Pseudo Classes

W3 chapter: <http://www.w3.org/TR/css3-selectors/#structural-pseudos>

Pseudo classes can be used to further narrow down elements besides just their
names and attribute values. In essence they are a combination of XPath function
calls and axes. Some pseudo classes can take an argument to alter their
behaviour.

Pseudo classes are often applied to element selectors. For example:

    foo:bar

Here `:bar` would be a pseudo class applied to the `foo` element. Some pseudo
classes (e.g. the `:root` pseudo class) can also be used on their own, for
example:

    :root

### :root

The `:root` pseudo class selects an element only if it's the top-level element
in a document.

Example XML:

    <root>
        <foo />
    </root>

Using the CSS expression `root foo:root` we'd get an empty set as the `<foo>`
element is not the root element. On the other hand, `root:root` would return a
set containing only the `<root>` element.

This selector can both be applied to an element selector as well as being used
on its own.

For the selector `foo:root` the corresponding XPath expression is as following:

    foo[not(parent::*)]

For `:root` the XPath expression is:

    *[not(parent::*)]

### :nth-child(n)

The `:nth-child(n)` pseudo class can be used to select a set of elements based
on their position or an interval, skipping elements that occur in a set before
the given position or interval.

In the form `:nth-child(n)` the identifier `n` is an argument that can be used
to specify one of the following:

1. A literal node set index
2. A node interval used to match every N nodes
3. A node interval plus an initial offset

The first element in a node set for `:nth-child()` is located at position 1,
_not_ position 0 (unlike most programming languages). As a result
`:nth-child(1)` matches the _first_ element, _not_ the second. This can be
visualized as following:

               :nth-child(2)

       1     2     3     4     5     6
     +---+ +---+ +---+ +---+ +---+ +---+
     |   | | X | |   | |   | |   | |   |
     +---+ +---+ +---+ +---+ +---+ +---+

Besides using a literal index argument you can also use an interval, optionally
with an offset. This can be used to for example match every 2nd element, or
every 2nd element starting at element number 4.

The syntax of this argument is as following:

    integer  = ('+' | '-')* [0-9]+;
    interval = ('n' | '-n' | integer 'n') integer;

Here `interval` would match any of the following:

    n
    -n
    2n
    2n+5
    2n-5
    -2n+5
    -2n-5

Due to `integer` also matching the `+` and `-` it will be part of the same
token. If this is not desired the following grammar can be used instead:

    integer  = [0-9]+;
    modifier = '+' | '-';
    interval = ('n' | '-n' | modifier* integer 'n') modifier integer;

To match every 2nd element you'd use the following:

               :nth-child(2n)

       1     2     3     4     5     6
     +---+ +---+ +---+ +---+ +---+ +---+
     |   | | X | |   | | X | |   | | X |
     +---+ +---+ +---+ +---+ +---+ +---+

To match every 2nd element starting at element 1 you'd instead use this:

              :nth-child(2n+1)

       1     2     3     4     5     6
     +---+ +---+ +---+ +---+ +---+ +---+
     | X | |   | | X | |   | | X | |   |
     +---+ +---+ +---+ +---+ +---+ +---+

As mentioned the `+1` in the above example is the initial offset. This is
however _only_ the case if the second number is positive. That means that for
`:nth-child(2n-2)` the offset is _not_ `-2`. When using a negative offset the
actual offset first has to be calculated. When using an argument in the form of
`An-B` we can calculate the actual offset as following:

    offset = A - (B % A)

For example, for the selector `:nth-child(2n-2)` the formula would be:

    offset = 2 - (-2 % 2) # => 2

This would result in the selector `:nth-child(2n+2)`.

As an another example, for the selector `:nth-child(2n-5)` the formula would be:

    offset = 2 - (-5 % 2) # => 1

Which would result in the selector `:nth-child(2n+1)`

To ease the process of selecting even and uneven elements you can also use
`even` and `odd` as an argument. Using `:nth-child(even)` is the same as
`:nth-child(2n)` while using `:nth-child(odd)` in turn is the same as
`:nth-child(2n+1)`.

Using `:nth-child(n)` simply matches all elements in the set. Using
`:nth-child(-n)` doesn't match any elements, though Oga treats it the same as
`:nth-child(n)`.

Expressions such as `:nth-child(-n-5)` are invalid as both parts of the interval
(`-n` and `-5`) are a negative. However, `:nth-child(-n+5)` is
perfectly valid and would match the first 5 elements in a set:

             :nth-child(-n+5)

      1     2     3     4     5     6
    +---+ +---+ +---+ +---+ +---+ +---+
    | X | | X | | X | | X | | X | |   |
    +---+ +---+ +---+ +---+ +---+ +---+


Using `:nth-child(n+5)` would match all elements starting at element 5:

                         :nth-child(n+5)

      1     2     3     4     5     6     7     8     9    10
    +---+ +---+ +---+ +---+ +---+ +---+ +---+ +---+ +---+ +---+
    |   | |   | |   | |   | | X | | X | | X | | X | | X | | X |
    +---+ +---+ +---+ +---+ +---+ +---+ +---+ +---+ +---+ +---+

To summarize:

    :nth-child(n)    => matches all elements
    :nth-child(-n)   => matches nothing, though Oga treats it the same as "n"
    :nth-child(5)    => matches element #5
    :nth-child(2n)   => matches every 2 elements
    :nth-child(2n+2) => matches every 2 elements, starting at element 2
    :nth-child(2n-2) => matches every 2 elements, starting at element 1
    :nth-child(n+5)  => matches all elements, starting at element 5
    :nth-child(-n+5) => matches the first 5 elements
    :nth-child(even) => matches every 2nd element, starting at element 2
    :nth-child(odd)  => matches every 2nd element, starting at element 1

The corresponding XPath expressions are quite complex and differ based on the
interval argument used. For the various forms the corresponding XPath
expressions are as following:

    :nth-child(n)    => *[((count(preceding-sibling::*) + 1) mod 1) = 0]
    :nth-child(-n)   => *[((count(preceding-sibling::*) + 1) mod 1) = 0]
    :nth-child(5)    => *[count(preceding-sibling::*) = 4]
    :nth-child(2n)   => *[((count(preceding-sibling::*) + 1) mod 2) = 0]
    :nth-child(2n+2) => *[(count(preceding-sibling::*) + 1) >= 2 and (((count(preceding-sibling::*) + 1) - 2) mod 2) = 0]
    :nth-child(2n-6) => *[(count(preceding-sibling::*) + 1) >= 2 and (((count(preceding-sibling::*) + 1) - 2) mod 2) = 0]
    :nth-child(n+5)  => *[(count(preceding-sibling::*) + 1) >= 5 and (((count(preceding-sibling::*) + 1) - 5) mod 1) = 0]
    :nth-child(-n+6) => *[((count(preceding-sibling::*) + 1) <= 6) and (((count(preceding-sibling::*) + 1) - 6) mod 1) = 0]
    :nth-child(even) => *[((count(preceding-sibling::*) + 1) mod 2) = 0]
    :nth-child(odd)  => *[(count(preceding-sibling::*) + 1) >= 1 and (((count(preceding-sibling::*) + 1) - 1) mod 2) = 0]

### :nth-last-child(n)

The `:nth-last-child(n)` pseudo class can be used to select a set of elements
based on their position or an interval, skipping elements that occur in a set
after the given position or interval.

The arguments that can be used by this selector are the same as those mentioned
in [:nth-child(n)][nth-childn].

Because this selectors matches in reverse (compared to
[:nth-child(n)][nth-childn]) using an index such as "1" will match the _last_
element in a set, not the first one:

               :nth-last-child(1)

       1     2     3     4     5     6
     +---+ +---+ +---+ +---+ +---+ +---+
     |   | |   | |   | |   | |   | | X | <- matching direction
     +---+ +---+ +---+ +---+ +---+ +---+

When using an interval (with or without an offset) the nodes are also matched in
reverse order. However, matched nodes should be returned in the order they
appear in in the document.

For example, the selector `:nth-last-child(2n)` would match as following:

               :nth-last-child(2n)

       1     2     3     4     5     6
     +---+ +---+ +---+ +---+ +---+ +---+
     | X | |   | | X | |   | | X | |   | <- matching direction
     +---+ +---+ +---+ +---+ +---+ +---+

The resulting set however would contain the nodes in the order `[1, 3, 5]`
instead of `[5, 3, 1]`.

When using an interval with an initial offset the offset is also applied in
reverse order. For example, the selector `:nth-last-child(2n)` would match as
following:

               :nth-last-child(2n+1)

       1     2     3     4     5     6
     +---+ +---+ +---+ +---+ +---+ +---+
     |   | | X | |   | | X | |   | | X | <- matching direction
     +---+ +---+ +---+ +---+ +---+ +---+

The corresponding XPath expressions are similar to those used for
[:nth-child(n)][nth-childn]:

    :nth-last-child(n)    => *[count(following-sibling::*) = -1]
    :nth-last-child(-n)   => *[count(following-sibling::*) = -1]
    :nth-last-child(5)    => *[count(following-sibling::*) = 4]
    :nth-last-child(2n)   => *[((count(following-sibling::*) + 1) mod 2) = 0]
    :nth-last-child(2n+2) => *[((count(following-sibling::*) + 1) >= 2) and ((((count(following-sibling::*) + 1) - 2) mod 2) = 0)]
    :nth-last-child(2n-6) => *[((count(following-sibling::*) + 1) >= 2) and ((((count(following-sibling::*) + 1) - 2) mod 2) = 0)]
    :nth-last-child(n+5)  => *[((count(following-sibling::*) + 1) >= 5) and ((((count(following-sibling::*) + 1) - 5) mod 1) = 0)]
    :nth-last-child(-n+6) => *[((count(following-sibling::*) + 1) <= 6) and ((((count(following-sibling::*) + 1) - 6) mod 1) = 0)]
    :nth-last-child(even) => *[((count(following-sibling::*) + 1) mod 2) = 0]
    :nth-last-child(odd)  => *[((count(following-sibling::*) + 1) >= 1) and ((((count(following-sibling::*) + 1) - 1) mod 2) = 0)]

### :nth-of-type(n)

The `:nth-of-type(n)` pseudo class can be used to select a set of elements that
has a set of preceding siblings with the same name. The arguments that can be
used by this selector are the same as those mentioned in
[:nth-child(n)][nth-childn].

The matching order of this selector is the same as [:nth-child(n)][nth-childn].

Example XML:

    <root>
        <foo />
        <foo />
        <foo />
        <foo />
        <bar />
    </root>

Using the CSS expression `root foo:nth-of-type(even)` would return a set
containing the 2nd and 4th `<foo>` nodes.

The corresponding XPath expressions for the various forms of this pseudo class
are as following:

    :nth-of-type(n)    => *[position() = n]
    :nth-of-type(-n)   => *[position() = -n]
    :nth-of-type(5)    => *[position() = 5]
    :nth-of-type(2n)   => *[(position() mod 2) = 0]
    :nth-of-type(2n+2) => *[(position() >= 2) and (((position() - 2) mod 2) = 0)]
    :nth-of-type(2n-6) => *[(position() >= 2) and (((position() - 2) mod 2) = 0)]
    :nth-of-type(n+5)  => *[(position() >= 5) and (((position() - 5) mod 1) = 0)]
    :nth-of-type(-n+6) => *[(position() <= 6) and (((position() - 6) mod 1) = 0)]
    :nth-of-type(even) => *[(position() mod 2) = 0]
    :nth-of-type(odd)  => *[(position() >= 1) and (((position() - 1) mod 2) = 0)]

### :nth-last-of-type(n)

The `:nth-last-of-type(n)` pseudo class behaves the same as
[:nth-of-type(n)][nth-last-of-typen] excepts it matches nodes in reverse order
similar to [:nth-last-child(n)][nth-last-childn].  To clarify, this means
matching occurs as following:


               :nth-last-of-type(1)

       1     2     3     4     5     6
     +---+ +---+ +---+ +---+ +---+ +---+
     |   | |   | |   | |   | |   | | X | <- matching direction
     +---+ +---+ +---+ +---+ +---+ +---+

Example XML:

    <root>
        <foo />
        <foo />
        <foo />
        <foo />
        <bar />
    </root>

Using the CSS expression `root foo:nth-of-type(even)` would return a set
containing the 1st and 3rd `<foo>` nodes.

The corresponding XPath expressions for the various forms of this pseudo class
are as following:

    :nth-last-of-type(n)    => *[position() = last() - -1]
    :nth-last-of-type(-n)   => *[position() = last() - -1]
    :nth-last-of-type(5)    => *[position() = last() - 4]
    :nth-last-of-type(2n)   => *[((last() - position()+1) mod 2) = 0]
    :nth-last-of-type(2n+2) => *[((last() - position()+1) >= 2) and ((((last() - position() + 1) - 2) mod 2) = 0)]
    :nth-last-of-type(2n-6) => *[((last() - position()+1) >= 2) and ((((last() - position() + 1) - 2) mod 2) = 0)]
    :nth-last-of-type(n+5)  => *[((last() - position()+1) >= 5) and ((((last() - position() + 1) - 5) mod 1) = 0)]
    :nth-last-of-type(-n+6) => *[((last() - position()+1) <= 6) and ((((last() - position() + 1) - 6) mod 1) = 0)]
    :nth-last-of-type(even) => *[((last() - position()+1) mod 2) = 0]
    :nth-last-of-type(odd)  => *[((last() - position()+1) >= 1) and ((((last() - position() + 1) - 1) mod 2) = 0)]

### :first-child

The `:first-child` pseudo class can be used to match a node that is the first
child node of another node (= a node without any preceding nodes).

Example XML:

    <root>
        <foo />
        <bar />
    </root>

Using the CSS selector `root :first-child` would return a set containing only
the `<foo>` node.

The corresponding XPath expression for this pseudo class is as following:

    :first-child => *[count(preceding-sibling::*) = 0]

### :last-child

The `:last-child` pseudo class can be used to match a node that is the last
child node of another node (= a node without any following nodes).

Example XML:

    <root>
        <foo />
        <bar />
    </root>

Using the CSS selector `root :last-child` would return a set containing only
the `<bar>` node.

The corresponding XPath expression for this pseudo class is as following:

    :last-child => *[count(following-sibling::*) = 0]

### :first-of-type

The `:first-of-type` pseudo class matches elements that are the first sibling of
its type in the list of elements of its parent element. This selector is the
same as [:nth-of-type(1)][nth-of-typen].

Example XML:

    <root>
      <a id="1" />
      <a id="2">
        <a id="3" />
        <a id="4" />
      </a>
    </root>

Using the CSS selector `root a:first-of-type` would return a node set containing
nodes `<a id="1">` and `<a id="3">` as both nodes are the first siblings of
their type.

The corresponding XPath for this pseudo class is as following:

    a:first-of-type => a[count(preceding-sibling::a) = 0]

An alternative way is to use the following XPath:

    a:first-of-type => //a[position() = 1]

This however relies on the less efficient `descendant-or-self::node()` selector.
For querying larger documents it's recommended to use the first form instead.

### :last-of-type

The `:last-of-type` pseudo class can be used to match elements that are the last
sibling of its type in the list of elements of its parent. This selector is the
same as [:nth-last-of-type(1)][nth-last-of-typen].

Example XML:

    <root>
      <a id="1" />
      <a id="2">
        <a id="3" />
        <a id="4" />
      </a>
    </root>

Using the CSS selector `root a:last-of-type` would return a set containing nodes
`<a id="2">` and `<a id="4">` as both nodes are the last siblings of their type.

The corresponding XPath for this pseudo class is as following:

    a:last-of-type => a[count(following-sibling::a) = 0]

Similar to [:first-of-type][first-of-typen] this XPath can alternatively be
written as following:

    a:last-of-type => //a[position() = last()]

### :only-child

The `:only-child` pseudo class can be used to match elements that are the only
child element of its parent.

Example XML:

    <root>
      <a id="1" />
      <a id="2">
        <a id="3" />
      </a>
    </root>

Using the CSS selector `root a:only-child` would return a set containing only
the `<a id="3">` node.

The corresponding XPath for this pseudo class is as following:

    a:only-child => a[count(preceding-sibling::*) = 0 and count(following-sibling::*) = 0]

### :only-of-type

The `:only-of-type` pseudo class can be used to match elements that are the only
child elements of its type of its parent.

Example XML:

    <root>
      <a id="1" />
      <a id="2">
        <a id="3" />
        <b id="4" />
      </a>
    </root>

Using the CSS selector `root a:only-of-type` would return a set containing
only the `<a id="3">` node due to it being the only `<a>` node in the list of
elements of its parent.

The corresponding XPath for this pseudo class is as following:

    a:only-child => a[count(preceding-sibling::a) = 0 and count(following-sibling::a) = 0]

### :empty

The `:empty` pseudo class can be used to match elements that have no child nodes
at all.

Example XML:

    <root>
        <a />
        <b>10</b>
    </root>

Using the CSS selector `root :empty` would return a set containing only the
`<a>` node.

### Syntax

The syntax of the various pseudo classes is as following:

    integer = ('+' | '-')* [0-9]+;

    odd  = 'odd';
    even = 'even';
    nth  = 'n';

    pseudo_arg_interval = '-'* integer* nth;
    pseudo_arg_offset   = ('+' | '-')* integer;

    pseudo_arg = odd
      | even
      | '-'* nth
      | integer
      | pseudo_arg_interval
      | pseudo_arg_interval pseudo_arg_offset;

    # The `identifier` rule is the same as the one used for element names.
    pseudo = ':' identifier ('(' space* pseudo_arg space* ')')*;

[w3spec]: http://www.w3.org/TR/css3-selectors/
[rfc-2119]: https://www.ietf.org/rfc/rfc2119.txt
[kramdown]: http://kramdown.gettalong.org/
[universal-selector]: #universal-selector
[ragel]: http://www.colm.net/open-source/ragel/
[nth-childn]: #nth-childn
[nth-last-childn]: #nth-last-childn
[nth-last-of-typen]: #nth-last-of-typen
[nth-of-typen]: #nth-of-type
[nth-last-of-typen]: #nth-last-of-typen
[first-of-typen]: #first-of-typen