oga 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8b60359c51f8e8eb14fb35fbc7ffdd6da99a6d50
-  data.tar.gz: b7c569316e309823375f84dc628c1f170d3f2540
+  metadata.gz: 9abda7194e4d0f181bf8a43c5d5154c965fd1d81
+  data.tar.gz: 8cd27a710c2c761ffd37d9393e53e3b78f53444e
 SHA512:
-  metadata.gz: 57224b74df2f069a99826dcbc49d1bf4efdb7d31c5568c23e8b817952d3708b365198fcbafdd82d95e0e1f7af9b221d6b6a71cc1d09fd4cf2951d177fa4ed456
-  data.tar.gz: b7103802563321ebe4174a328e65d99a00df973abca79e1ef02544e0bcf2484e679db8009c9de98cb971d8912bfe573f0d0250bbbc25f77c5764e6d43f190d6c
+  metadata.gz: 556c869e33dfe785eda199e42a5d2fe869e269c8522809b81d8febdefe88285c52a3c7b17e22524b031cf5698395c505fd82f9ef8d69db538f9ac7f19f761e47
+  data.tar.gz: 149034fbe883e5e0df5f805aa17b07cf12afc8cccefbc22d9f73e6dcc6ba2b6fbe1ef39706f4945fbab90e9ecdcb208b4d299f939eb428706f724f657ecbc822

data/README.md

@@ -70,6 +70,12 @@ Querying a document using XPath:
 
     document.xpath('string(people/person)') # => "Alice"
 
+Querying a document using CSS:
+
+    document = Oga.parse_xml('<people><person>Alice</person></people>')
+
+    document.css('people person') # => NodeSet(Element(name: "person" ...))
+
 Modifying a document and serializing it back to XML:
 
     document = Oga.parse_xml('<people><person>Alice</person></people>')
@@ -95,6 +101,7 @@ Querying a document using a namespace:
 * Low memory footprint
 * High performance, if something doesn't perform well enough it's a bug
 * Support for XPath 1.0
+* CSS3 selector support
 * XML namespace support (registering, querying, etc)
 
 ## Requirements
@@ -127,6 +134,53 @@ _not_ thread-safe and should not be done by multiple threads at once.
 It is advised that you do not share parsed documents between threads unless you
 _really_ have to.
 
+## Namespace Support
+
+Oga fully supports parsing/registering XML namespaces as well as querying them
+using XPath. For example, take the following XML:
+
+    <root xmlns="http://example.com">
+        <bar>bar</bar>
+    </root>
+
+If one were to try and query the `bar` element (e.g. using XPath `root/bar`)
+they'd end up with an empty node set. This is due to `<root>` defining an
+alternative default namespace. Instead you can query this element using the
+following XPath:
+
+    *[local-name() = "root"]/*[local-name() = "bar"]
+
+Alternatively, if you don't really care where the `<bar>` element is located you
+can use the following:
+
+    descendant::*[local-name() = "bar"]
+
+And if you want to specify an explici namespace URI, you can use this:
+
+    descendant::*[local-name() = "bar" and namespace-uri() = "http://example.com"]
+
+Unlike Nokogiri, Oga does _not_ provide a way to create "dynamic" namespaces.
+That is, Nokogiri allows one to query the above document as following:
+
+    document = Nokogiri::XML('<root xmlns="http://example.com"><bar>bar</bar></root>')
+
+    document.xpath('x:root/x:bar', :x => 'http://example.com')
+
+Oga does have a small trick you can use to cut down the size of your XPath
+queries. Because Oga assigns the name "xmlns" to default namespaces you can use
+this in your XPath queries:
+
+    document = Oga.parse_xml('<root xmlns="http://example.com"><bar>bar</bar></root>')
+
+    document.xpath('xmlns:root/xmlns:bar')
+
+When using this you can still restrict the query to the correct namespace URI:
+
+    document.xpath('xmlns:root[namespace-uri() = "http://example.com"]/xmlns:bar')
+
+In the future I might add an API to ease this process, although at this time I
+have little interest in providing an API similar to Nokogiri.
+
 ## Documentation
 
 The documentation is best viewed [on the documentation website][doc-website].
@@ -134,6 +188,9 @@ The documentation is best viewed [on the documentation website][doc-website].
 * {file:CONTRIBUTING Contributing}
 * {file:changelog Changelog}
 * {file:migrating\_from\_nokogiri Migrating From Nokogiri}
+* {Oga::XML::Parser XML Parser}
+* {Oga::XML::SaxParser XML SAX Parser}
+* {file:xml\_namespaces XML Namespaces}
 
 ## Native Extension Setup
 

data/doc/changelog.md

@@ -3,6 +3,134 @@
 This document contains details of the various releases and their release dates.
 Dates are in the format `yyyy-mm-dd`.
 
+## 0.2.0 - 2014-11-17
+
+### CSS Selector Support
+
+Probably the biggest feature of this release: support for querying documents
+using CSS selectors. Oga supports a subset of the CSS3 selector specification,
+in particular the following selectors are supported:
+
+* Element, class and ID selectors
+* Attribute selectors (e.g. `foo[x ~= "y"]`)
+
+The following pseudo classes are supported:
+
+* `:root`
+* `:nth-child(n)`
+* `:nth-last-child(n)`
+* `:nth-of-type(n)`
+* `:nth-last-of-type(n)`
+* `:first-child`
+* `:last-child`
+* `:first-of-type`
+* `:last-of-type`
+* `:only-child`
+* `:only-of-type`
+* `:empty`
+
+You can use CSS selectors using the methods `css` and `at_css` on an instance of
+`Oga::XML::Document` or `Oga::XML::Element`. For example:
+
+    document = Oga.parse_xml('<people><person>Alice</person></people>')
+
+    document.css('people person') # => NodeSet(Element(name: "person" ...))
+
+The architecture behind this is quite similar to parsing XPath. There's a lexer
+(`Oga::CSS::Lexer`) and a parser (`Oga::CSS::Parser`). Unlike Nokogiri (and
+perhaps other libraries) the parser _does not_ output XPath expressions as a
+String or a CSS specific AST. Instead it directly emits an XPath AST. This
+allows the resulting AST to be directly evaluated by `Oga::XPath::Evaluator`.
+
+See <https://github.com/YorickPeterse/oga/issues/11> for more information.
+
+### Mutli-line Attribute Support
+
+Oga can now lex/parse elements that have attributes with newlines in them.
+Previously this would trigger memory allocation errors.
+
+See <https://github.com/YorickPeterse/oga/issues/58> for more information.
+
+### SAX after_element
+
+The `after_element` method in the SAX parsing API now always takes two
+arguments: the namespace name and element name. Previously this method would
+always receive a single nil value as its argument, which is rather pointless.
+
+See <https://github.com/YorickPeterse/oga/issues/54> for more information.
+
+### XPath Grouping
+
+XPath expressions can now be grouped together using parenthesis. This allows one
+to specify a custom operator precedence.
+
+### Enumerator Parsing Input
+
+Enumerator instances can now be used as input for `Oga.parse_xml` and friends.
+This can be used to download and parse XML files on the fly. For example:
+
+    enum = Enumerator.new do |yielder|
+      HTTPClient.get('http://some-website.com/some-big-file.xml') do |chunk|
+        yielder << chunk
+      end
+    end
+
+    document = Oga.parse_xml(enum)
+
+See <https://github.com/YorickPeterse/oga/issues/48> for more information.
+
+### Removing Attributes
+
+Element attributes can now be removed using `Oga::XML::Element#unset`:
+
+    element = Oga::XML::Element.new(:name => 'foo')
+
+    element.set('class', 'foo')
+    element.unset('class')
+
+### XPath Attributes
+
+XPath predicates are now evaluated for every context node opposed to being
+evaluated once for the entire context. This ensures that expressions such as
+`descendant-or-self::node()/foo[1]` are evaluated correctly.
+
+### Available Namespaces
+
+When calling `Oga::XML::Element#available_namespaces` the Hash returned by
+`Oga::XML::Element#namespaces` would be modified in place. This was a bug that
+has been fixed in this release.
+
+### NodeSets
+
+NodeSet instances can now be compared with each other using `==`. Previously
+this would always consider two instances to be different from each other due to
+the usage of the default `Object#==` method.
+
+### XML Entities
+
+XML entities such as `&amp;` and `&lt;` are now encoded/decoded by the lexer,
+string and text nodes.
+
+See <https://github.com/YorickPeterse/oga/issues/49> for more information.
+
+### General
+
+Source lines are no longer included in error messages generated by the XML
+parser. This simplifies the code and removes the need of re-reading the input
+(in case of IO/Enumerable inputs).
+
+### XML Lexer Newlines
+
+Newlines in the XML lexer are now counted in native code (C/Java). On MRI and
+JRuby the improvement is quite small, but on Rubinius it's a massive
+improvement. See commit `8db77c0a09bf6c996dd2856a6dbe1ad076b1d30a` for more
+information.
+
+### HTML Void Element Performance
+
+Performance for detecting HTML void elements (e.g. `<br>` and `<link>`) has been
+improved by removing String allocations that were not needed.
+
 ## 0.1.3 - 2014-09-24
 
 This release fixes a problem with serializing attributes using the namespace

data/doc/css/common.css

@@ -6,11 +6,12 @@ body
     max-width:   960px;
 }
 
-p code
+p code, dd code, li code
 {
-    background:    #f2f2f2;
-    padding-left:  3px;
-    padding-right: 3px;
+    background: #f9f2f4;
+    color: #c7254e;
+    border-radius: 4px;
+    padding: 2px 4px;
 }
 
 pre.code

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