rubyjedi-oga 1.0.3

data/doc/css/common.css

@@ -0,0 +1,77 @@
+body
+{
+    font-size:   14px;
+    line-height: 1.6;
+    margin:      0 auto;
+    max-width:   960px;
+}
+
+p code, dd code, li code
+{
+    background: #f9f2f4;
+    color: #c7254e;
+    border-radius: 4px;
+    padding: 2px 4px;
+}
+
+pre.code
+{
+    font-size:   13px;
+    line-height: 1.4;
+    overflow:    auto;
+}
+
+blockquote
+{
+    border-left: 5px solid #eee;
+    margin: 0px;
+    padding-left: 15px;
+}
+
+/**
+ * YARD uses generic table styles, using a special class means those tables
+ * don't get messed up.
+ */
+.table
+{
+    border:          1px solid #ccc;
+    border-right:    none;
+    border-collapse: separate;
+    border-spacing:  0;
+    text-align:      left;
+}
+
+.table.full
+{
+    width: 100%;
+}
+
+    .table .field_name
+    {
+        min-width: 160px;
+    }
+
+    .table thead tr th.no_sort:first-child
+    {
+        width: 25px;
+    }
+
+    .table thead tr th, .table tbody tr td
+    {
+        border-bottom:  1px solid #ccc;
+        border-right:   1px solid #ccc;
+        min-width:      20px;
+        padding:        8px 5px;
+        text-align:     left;
+        vertical-align: top;
+    }
+
+    .table tbody tr:last-child td
+    {
+        border-bottom: none;
+    }
+
+    .table tr:nth-child(odd) td
+    {
+        background: #f9f9f9;
+    }

data/doc/css_selectors.md

@@ -0,0 +1,935 @@
+# 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