CSS engine
==========
Requirements
------------
+ Parse stylesheets conforming to the forward compatible CSS grammar
(Note that in the short term, the semantic analysis stage only need
support CSS2.1)
+ Stylesheet management/merging (i.e. multiple stylesheets may be added
to a single engine context and thus affect style selection)
+ Be able to select a style for a DOM node based upon the current stylesheets
in the engine context.
+ Implemented as a standalone, reusable, library -- ideally MIT licensed.
Suggested API
-------------
struct css_context;
struct css_style;
struct css_stylesheet;
typedef struct css_context css_context;
typedef struct css_style css_style;
typedef struct css_stylesheet css_stylesheet;
typedef enum css_error {
CSS_OK,
CSS_NOMEM,
/* etc */
} css_error;
typedef enum css_origin {
CSS_ORIGIN_UA,
CSS_ORIGIN_USER,
CSS_ORIGIN_AUTHOR
} css_origin;
#define CSS_MEDIA_SCREEN (1<<0)
#define CSS_MEDIA_PRINT (1<<1)
/* etc */
#define CSS_MEDIA_ALL (0xffffffff)
#define CSS_PSEUDO_CLASS_NONE (0)
#define CSS_PSEUDO_CLASS_LINK (1<<0)
#define CSS_PSEUDO_CLASS_VISITED (1<<1)
#define CSS_PSEUDO_CLASS_HOVER (1<<2)
#define CSS_PSEUDO_CLASS_ACTIVE (1<<3)
#define CSS_PSEUDO_CLASS_FOCUS (1<<4)
typedef enum css_property {
CSS_BACKGROUND_ATTACHMENT,
/* etc */
} css_property;
typedef struct css_value {
css_property property;
union {
css_background_attachment background_attachment;
/* etc */
} value;
} css_value;
typedef css_error (*css_import_handler)(void *pw, const char *url,
css_stylesheet *sheet);
/* Initialise library */
css_error css_init(void);
/* Finalise library */
css_error css_fini(void);
/* Create a stylesheet associated with the given URL,
* specifying the sheet's origin, the media type(s) it applies to and
* a callback routine for fetching imported sheets */
css_stylesheet *css_stylesheet_create(const char *url,
css_origin origin, uint32_t media,
css_import_handler import_callback, void *pw);
/* Destroy a stylesheet */
void css_stylesheet_destroy(css_stylesheet *sheet);
/* Append data to a stylesheet, parsing progressively */
css_error css_stylesheet_append_data(css_stylesheet *sheet,
const uint8_t *data, size_t len);
/* Tell stylesheet parser that there's no more data (will complete parsing) */
css_error css_stylesheet_data_done(css_stylesheet *sheet);
/* Retrieve the URL associated with a stylesheet */
const char *css_stylesheet_get_url(css_stylesheet *sheet);
/* Retrieve the origin of a stylesheet */
css_origin css_stylesheet_get_origin(css_stylesheet *sheet);
/* Retrieve the media type(s) applicable to a stylesheet */
uint32_t css_stylesheet_get_media(css_stylesheet *sheet);
/* Create a selection context */
css_context *css_context_create(void);
/* Destroy a selection context */
void css_context_destroy(css_context *context);
/* Append a top-level stylesheet to a selection context */
css_error css_context_append_sheet(css_context *context,
css_stylesheet *sheet);
/* Insert a top-level stylesheet into a selection context, at the given index */
css_error css_context_insert_sheet(css_context *context,
css_stylesheet *sheet, uint32_t index);
/* Remove a top-level stylesheet from a selection context */
css_error css_context_remove_sheet(css_context *context,
css_stylesheet *sheet);
/* Retrieve the total number of top-level sheets in a selection context */
uint32_t css_context_count_sheets(css_context *context);
/* Get a stylesheet from a selection context given an index [0, count) */
const css_stylesheet *css_context_get_sheet(css_context *context,
uint32_t index);
/* Select a style for a given DOM node with the given pseudo classes active
* and media type.
*
* If the document language contains non-CSS presentational hints (e.g. HTML
* presentational attributes etc), then these are passed in through
* property_list and treated as if they were encountered at the start of the
* author stylesheet with a specificity of 0. */
css_style *css_style_select(css_context *context,
<dom_node_type> *node, uint32_t pseudo_classes, uint32_t media,
css_value **property_list, uint32_t property_list_length);
/* Destroy a selected style */
void css_style_destroy(css_style *style);
/* Retrieve a property value from a style */
css_value *css_value_get(css_style *style, css_property property);
/* Destroy a property value */
void css_value_destroy(css_value *value);
Memory management
-----------------
+ Stylesheets are owned by their creator. Selection contexts reference them.
+ Selection contexts are owned by the client.
+ Selected styles are owned by the client.
+ Property values are owned by the client.
Therefore, the only difficulty lies within the handling of stylesheets
inserted into a selection context. The client code must ensure that a
stylesheet is destroyed after it has been removed from any selection
contexts which are using it.
DOM node types & tree traversal
-------------------------------
This is currently undecided. Either the CSS engine is tied to a DOM
implementation (and makes API calls directly), or it's more generic and
performs API calls through a vtable provided by the client.
Imported stylesheets
--------------------
Imported stylesheets are handled by the CSS engine creating an appropriate
css_stylesheet object for the imported sheet and then asking the client
to fetch the data and append it to the sheet. The imported sheet is then
stored in the sheet that imported it. This effectively creates a tree of
stylesheets beneath the initial top-level sheet created by the client.
Style selection algorithm
-------------------------
css_style_select(context, node, pseudo_classes, media,
property_list, property_list_length):
result = blank_style;
done_props = false;
foreach sheet in context:
# Assumes that sheets are in the order UA, USER, AUTHOR
if !done_props && css_stylesheet_get_origin(sheet) == CSS_ORIGIN_AUTHOR:
fake_rule = fake_rule(node, property_list, property_list_length);
cascade(result, fake_rule, CSS_ORIGIN_AUTHOR);
done_props = true;
process_sheet(sheet, node, pseudo_classes, media, result);
return result;
fake_rule(node, property_list, property_list_length):
rule = (node.name, 0); # Specificity is 0
foreach (property, value, importance) in property_list:
rule[property] = (value, importance);
return rule;
process_sheet(sheet, node, pseudo_classes, media, result):
if (css_stylesheet_get_media(sheet) & media) == 0:
return;
foreach import in sheet:
process_sheet(import, node, pseudo_classes, media, result);
origin = css_stylesheet_get_origin(sheet);
foreach rule in sheet:
if matches_rule(rule, node, pseudo_classes):
cascade(result, rule, origin);
cascade(result, rule, origin):
foreach (property, value, importance) in rule:
insert = false;
if result[property]:
rOrigin = result[property].origin;
rImportance = result[property].importance;
rSpecificity = result[property].specificity;
if rOrigin < origin:
if rImportance == "important":
if rOrigin != CSS_ORIGIN_USER:
insert = true;
else:
insert = true;
else if rOrigin == origin:
if rImportance == "" && importance == "important":
if rOrigin == CSS_ORIGIN_UA:
if rSpecificity <= rule.specificity:
insert = true;
else:
insert = true;
else if rImportance == "important" && importance == "":
if rOrigin == CSS_ORIGIN_UA:
if rSpecificity <= rule.specificity:
insert = true;
else:
if rSpecificity <= rule.specificity:
insert = true;
else:
if origin == CSS_ORIGIN_USER && importance == "important":
insert = true;
else:
insert = true;
if insert:
result[property] = (value, origin, importance, rule.specificity);
Outstanding issues
------------------
+ Parsing/selection quirks.
Probably as an argument to css_stylesheet_create() and possibly
css_style_select(). This could either take the form of a blanket
full/almost/not quirks mode flag or be more granular and permit the
toggling of individual quirks.
References:
+ http://developer.mozilla.org/en/docs/Mozilla_Quirks_Mode_Behavior
+ http://www.opera.com/docs/specs/doctype/
+ http://www.quirksmode.org/css/quirksmode.html
+ http://www.cs.tut.fi/~jkorpela/quirks-mode.html
+ Grep WebKit sources for inCompatMode()
+ The :lang pseudo-class
Need to pass the current language string into css_style_select()
+ Pseudo-elements
Probably as an argument to css_style_select(). Most likely a bitfield
like the way in which pseudo-classes are handled.
The inheritance model of :first-line and :first-letter is such that:
+ css_style_select() must begin with a blank style and not the
parent node's style
+ an API for cascading one style onto another is needed
This is because pseudo-elements may be nested inside children of the
node to which they are logically connected. e.g.:
<div>
<p>
first paragraph
</p>
</div>
is logically equivalent to
<div>
<p>
<div:first-line>
<p:first-line>
first paragraph
</p:first-line>
</div:first-line>
</p>
</div>
so the actual cascade order is only known at the time the render tree is
built. Note that, courtesy of scripting, the location of pseudo-elements
can move around (e.g. if some text was inserted just before the <p> within
the div, above, then <div:first-line> would move). Additionally, the actual
content that pseudo-elements apply to can change due to reflow.
Pseudo-elements may also affect the processing of inline boxes. e.g.:
<p>
<span>foo bar baz bat</span>
</p>
becomes (logically):
<p>
<p:first-line>
<span>foo bar baz </span>
</p:first-line>
<span>bat</span>
</p>
In terms of interaction between pseudo-elements, :first-letter inherits
from :first-line e.g.:
<p>
first line
second line
</p>
becomes (logically):
<p>
<p:first-line>
<p:first-letter>
f
</p:first-letter>
irst line
</p:first-line>
second line
</p>
:first-line and :first-letter apply to the relevant content _including_ any
text inserted using :before and :after.
List of CSS 3 pseudo-elements:
+ :(:)?first-line
+ :(:)?first-letter
+ :(:)?before
+ :(:)?after
+ ::selection
+ ::footnote-call
+ ::footnote-marker
+ ::before-page-break
+ ::after-page-break
+ ::line-number-left
+ ::line-number-right
+ ::line-number-inside
+ ::line-number-outside
+ ::slot()
+ ::value
+ ::choices
+ ::repeat-item
+ ::repeat-index
+ ::marker
+ ::outside
+ ::alternate
+ ::line-marker
References:
+ CSS 2.1 $$5.12 and $$12.1
+ Stylesheet charset handling
An embedded stylesheet shares the charset of the containing document.
The charset of a stand-alone stylesheet can be specified by (in order of
priority, highest -> lowest):
+ the transport layer
+ a BOM and/or @charset at the immediate start of the sheet
+ <link charset=""> or other metadata from the linking mechanism
+ charset of referring stylesheet or document
+ assuming UTF-8
The API currently has no way of conveying the first, third, or fourth of
these to the engine. This can be realised through the addition of a
parameter to css_stylesheet_create()
CSS 2.1 $4.4 specifies that a stylesheet's transport encoding must be a
superset of US-ASCII.
The internal encoding will be UTF-8.
All strings passed in by the client are assumed to be UTF-8 encoded.
Strings retrieved from DOM nodes are assumed to be UTF-8 encoded.