302 lines
9.1 KiB
ReStructuredText
302 lines
9.1 KiB
ReStructuredText
CSS parsing tests
|
||
#################
|
||
|
||
This repository contains implementation-independent test for CSS parsers,
|
||
based on the 2013 draft of the `CSS Syntax Level 3`_ specification.
|
||
|
||
.. _CSS Syntax Level 3: http://dev.w3.org/csswg/css-syntax-3/
|
||
|
||
The upstream repository for these tests is at
|
||
https://github.com/SimonSapin/css-parsing-tests
|
||
|
||
|
||
Projects using this
|
||
===================
|
||
|
||
CSS parsers using these tests:
|
||
|
||
* `tinycss2 <https://github.com/SimonSapin/tinycss2>`_ (Python)
|
||
* `rust-cssparser <https://github.com/mozilla-servo/rust-cssparser>`_
|
||
(Rust, used in `Servo <https://github.com/mozilla/servo/>`_)
|
||
* `Crass <https://github.com/rgrove/crass/>`_ (Ruby)
|
||
|
||
|
||
Importing
|
||
=========
|
||
|
||
The recommended way to use these tests in an implementation
|
||
is to import them with git-subtree_.
|
||
|
||
.. _git-subtree: https://github.com/git/git/tree/master/contrib/subtree
|
||
|
||
To import the first time to a ``./css-parsing-tests`` sub-directory,
|
||
run this from the top-level of a git repository::
|
||
|
||
git subtree add -P css-parsing-tests https://github.com/SimonSapin/css-parsing-tests.git master
|
||
|
||
Later, to merge changes made in the upstream repository, run::
|
||
|
||
git subtree pull -P css-parsing-tests https://github.com/SimonSapin/css-parsing-tests.git master
|
||
|
||
|
||
Test files
|
||
==========
|
||
|
||
CSS Syntax specification describes a number of "functions".
|
||
Each ``.json`` file in this repository corresponds to such a function.
|
||
The files are encoded as UTF-8
|
||
and each contain a JSON array with an even number of items,
|
||
where each pair of items is one function input
|
||
associated with the expected result.
|
||
|
||
``component_value_list.json``
|
||
Tests `Parse a list of component values
|
||
<http://dev.w3.org/csswg/css-syntax-3/#parse-a-list-of-component-values>`_.
|
||
The Unicode input is represented by a JSON string,
|
||
the output as an array of `component values`_ as described below.
|
||
|
||
``component_value_list.json``
|
||
Tests `Parse a component value
|
||
<http://dev.w3.org/csswg/css-syntax-3/#parse-a-component-value>`_.
|
||
The Unicode input is represented by a JSON string,
|
||
the output as a `component value`_.
|
||
|
||
``declaration_list.json``
|
||
Tests `Parse a list of declarations
|
||
<http://dev.w3.org/csswg/css-syntax-3/#parse-a-list-of-declarations>`_.
|
||
The Unicode input is represented by a JSON string,
|
||
the output as an array of declarations_ and at-rules_.
|
||
|
||
``one_declaration.json``
|
||
Tests `Parse a declaration
|
||
<http://dev.w3.org/csswg/css-syntax-3/#parse-a-declaration>`_.
|
||
The Unicode input is represented by a JSON string,
|
||
the output as a declaration_.
|
||
|
||
``one_rule.json``
|
||
Tests `Parse a rule
|
||
<http://dev.w3.org/csswg/css-syntax-3/#parse-a-rule>`_.
|
||
The Unicode input is represented by a JSON string,
|
||
the output as a `qualified rule`_ or at-rule_.
|
||
|
||
``rule_list.json``
|
||
Tests `Parse a list of rules
|
||
<http://dev.w3.org/csswg/css-syntax-3/#parse-a-list-of-rules>`_.
|
||
The Unicode input is represented by a JSON string,
|
||
the output as a list of `qualified rules`_ or at-rules_.
|
||
|
||
``stylesheet.json``
|
||
Tests `Parse a stylesheet
|
||
<http://dev.w3.org/csswg/css-syntax-3/#parse-a-stylesheet>`_.
|
||
The Unicode input is represented by a JSON string,
|
||
the output as a list of `qualified rules`_ or at-rules_.
|
||
|
||
``stylesheet_bytes.json``
|
||
Tests `Parse a stylesheet
|
||
<http://dev.w3.org/csswg/css-syntax-3/#parse-a-stylesheet>`_
|
||
together with `The input byte stream
|
||
<http://dev.w3.org/csswg/css-syntax/#input-byte-stream>`_.
|
||
The input is represented as a JSON object containing:
|
||
|
||
* A required ``css_bytes``, the input byte string,
|
||
represented as a JSON string where code points U+0000 to U+00FF
|
||
represent bytes of the same value.
|
||
* An optional ``protocol_encoding``,
|
||
a protocol encoding label as a JSON string, or null.
|
||
* An optional ``environment_encoding``,
|
||
an environment encoding label as a JSON string, or null.
|
||
* An optional ``comment`` that is ignored.
|
||
|
||
The output is represented a list of `qualified rules`_ or at-rules_.
|
||
|
||
``color3.json``
|
||
Tests the ``<color>`` syntax `defined in CSS Color Level 3
|
||
<http://www.w3.org/TR/css3-color/#colorunits>`_.
|
||
The Unicode input is represented by a JSON string,
|
||
the output as one of:
|
||
|
||
* null if the input is not a valid color in CSS syntax
|
||
* The string "currentColor" for the currentColor keyword
|
||
* An array of length 4 for every other values:
|
||
four (floating point) numbers for the Red, Green, Blue and Alpha channel.
|
||
Each value is between 0 and 1.
|
||
|
||
``color3_hsl.json``
|
||
Same as ``color3.json``.
|
||
This file is generated by the ``make_color3_hsl.py`` Python script.
|
||
|
||
``color3_keywords.json``
|
||
Same as ``color3.json``,
|
||
except that the values for the Red, Green and Blue channel
|
||
are between 0 and 255.
|
||
This file is generated by the ``make_color3_keywords.py`` Python script.
|
||
|
||
``An+B.json``
|
||
Tests the `An+B <http://dev.w3.org/csswg/css-syntax/#the-anb-type>`_
|
||
syntax defined in CSS Syntax Level 3.
|
||
This `differs <http://dev.w3.org/csswg/css-syntax/#changes>`_ from the
|
||
`nth grammar rule <http://www.w3.org/TR/css3-selectors/#nth-child-pseudo>`_
|
||
in Selectors Level 3 only in that
|
||
``-`` charecters and digits can be escaped in some cases.
|
||
The Unicode input is represented by a JSON string,
|
||
the output as null for invalid syntax,
|
||
or an array of two integers ``[A, B]``.
|
||
|
||
|
||
Result representation
|
||
=====================
|
||
|
||
AST nodes (the results of parsing) are represented in JSON as follow.
|
||
This representation was chosen to be compact
|
||
(and thus less annoying to write by hand)
|
||
while staying unambiguous.
|
||
For example, the difference between ``@import`` and ``\@import`` is not lost:
|
||
they are represented as ``["at-keyword", "import"]`` and ``["ident", "@import"]``,
|
||
respectively.
|
||
|
||
|
||
Rules and declarations
|
||
----------------------
|
||
|
||
.. _at-rule:
|
||
.. _at-rules:
|
||
.. _qualified rule:
|
||
.. _qualified rules:
|
||
.. _declaration:
|
||
.. _declarations:
|
||
|
||
|
||
At-rule
|
||
An array of length 4: the string ``"at-rule"``,
|
||
the name (value of the at-keyword) as a string,
|
||
the prelude as a nested array of `component values`_,
|
||
and the optional block as a nested array of component value, or null.
|
||
|
||
Qualified rule
|
||
An array of length 3: the string ``"qualified rule"``,
|
||
the prelude as a nested array of `component values`_,
|
||
and the block as a nested array of component value.
|
||
|
||
|
||
Declaration
|
||
An array of length 4: the string ``"declaration"``, the name as a string,
|
||
the value as a nested array of `component values`_,
|
||
and a the important flag as a boolean.
|
||
|
||
|
||
.. _component value:
|
||
.. _component values:
|
||
|
||
Component values
|
||
----------------
|
||
|
||
<ident>
|
||
Array of length 2: the string ``"ident"``, and the value as a string.
|
||
|
||
<at-keyword>
|
||
Array of length 2: the string ``"at-keyword"``, and the value as a string.
|
||
|
||
<hash>
|
||
Array of length 3: the string ``"hash"``, the value as a string,
|
||
and the type as the string ``"id"`` or ``"unrestricted"``.
|
||
|
||
<string>
|
||
Array of length 2: the string ``"string"``, and the value as a string.
|
||
|
||
<bad-string>
|
||
Array of length 1: the string ``"bad-string"``.
|
||
|
||
<url>
|
||
Array of length 2: the string ``"url"``, and the value as a string.
|
||
|
||
<bad-url>
|
||
Array of length 1: the string ``"bad-url"``.
|
||
|
||
<delim>
|
||
The value as a one-character string.
|
||
|
||
<number>
|
||
Array of length 4: the string ``"number"``, the representation as a string,
|
||
the value as a number, and the type as the string ``"integer"`` or ``"number"``.
|
||
|
||
<percentage>
|
||
Array of length 4: the string ``"percentage"``, the representation as a string,
|
||
the value as a number, and the type as the string ``"integer"`` or ``"number"``.
|
||
|
||
<dimension>
|
||
Array of length 4: the string ``"dimension"``, the representation as a string,
|
||
the value as a number, the type as the string ``"integer"`` or ``"number"``,
|
||
and the unit as a string.
|
||
|
||
<unicode-range>
|
||
Array of length 3: the string ``"unicode-range"``,
|
||
followed by the *start* and *end* integers as two numbers.
|
||
|
||
<include-match>
|
||
The string ``"~="``.
|
||
|
||
<dash-match>
|
||
The string ``"|="``.
|
||
|
||
<prefix-match>
|
||
The string ``"^="``.
|
||
|
||
<suffix-match>
|
||
The string ``"$="``.
|
||
|
||
<substring-match>
|
||
The string ``"*="``.
|
||
|
||
<column>
|
||
The string ``"||"``.
|
||
|
||
<whitespace>
|
||
The string ``" "`` (a single space.)
|
||
|
||
<CDO>
|
||
The string ``"<!--"``.
|
||
|
||
<CDC>
|
||
The string ``"-->"``.
|
||
|
||
<colon>
|
||
The string ``":"``.
|
||
|
||
<semicolon>
|
||
The string ``";"``.
|
||
|
||
<comma>
|
||
The string ``","``.
|
||
|
||
{} block
|
||
An array of length N+1: the string ``"{}"``
|
||
followed by the N `component values`_ of the block’s content.
|
||
|
||
[] block
|
||
An array of length N+1: the string ``"[]"``
|
||
followed by the N `component values`_ of the block’s content.
|
||
|
||
() block
|
||
An array of length N+1: the string ``"()"``
|
||
followed by the N `component values`_ of the block’s content.
|
||
|
||
Function
|
||
An array of length N+2: the string ``"function"``
|
||
and the name of the function as a string
|
||
followed by the N `component values`_ of the function’s arguments.
|
||
|
||
<bad-string>
|
||
The array of two strings ``["error", "bad-string"]``.
|
||
|
||
<bad-url>
|
||
The array of two strings ``["error", "bad-url"]``.
|
||
|
||
Unmatched <}>
|
||
The array of two strings ``["error", "}"]``.
|
||
|
||
Unmatched <]>
|
||
The array of two strings ``["error", "]"]``.
|
||
|
||
Unmatched <)>
|
||
The array of two strings ``["error", ")"]``.
|