SAC: Simple API for CSS

Abstract

This note describes a project for developing a common API for the CSS parsers in the W3C. A sample source code is already available for download ([SAC]). The software is OpenSource.

Status of this document

This document is a NOTE made available by the W3C for discussion only. Publication of this Note by W3C indicates no endorsement by W3C or the W3C Team, or any W3C Members. It contains a proposal for a generic API for CSS parser.

We plan to update this note according to the comments and, if there is enough interest, increases our ressources on SAC.

Comments on this document are invited and are to be sent to the public mailing list www-style@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-style/.

This document has been produced as part of the W3C Style Activity.

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.

Table of contents

1. Goals of the project

The goal of the project is to promote W3C technology.

One of the successes of the XML syntax was the interoperability between the XML parsers. This interoperability has been accomplished with the Simple API for XML ([SAX]). SAC plays a similar role for CSS.

The CSS specifications ([CSS1] and [CSS2]) introduce a forward-compatible grammar common to all versions of CSS. Any future versions of CSS should adhere to this core syntax, even if they add additional syntactic constraints.

The Simple API for CSS (SAC) is a proposal for a standard API for event-based CSS parsing. It is designed to support CSS1, CSS2 and future versions of CSS.

2. Overview of SAC

The SAC model follows the Simple API for XML ([SAX])) model:

1. A parser interface: a set of functions implemented by every parser, that can be called from an application program. They enable the application to parse a CSS style sheet, a CSS rule, a CSS selector, etc.
2. A DocumentHandler interface: prototypes of call-back functions implemented by the application program and called by the parser to report events. They enable the application to listen to the events (startDocument, start a @media rule, start a CSS selector, etc.)
3. An API for CSS selectors: a set of type definitions for objects that completely describe a selector.
4. An API for CSS lexical units: a set of type definitions for the tokens that make up a property value.

The current proposal for SAC ([SAC]) is available in Java ([Java]) and C). A Java implementation with CSS2 support, called "flute", is also available at the same address.

This note only gives a brief outline of SAC, please refer to the online documentation for details.

3. SAC and the CSS Object Model

The DOM Level 2 specification introduces an object model for CSS ([CSSOM]).

SAC complements the CSS Object Model:

1. SAC can be used to construct the CSS Object Model.
2. SAC provides an API to the CSS syntax unlike the CSS Object Model which provides access to the internal representation of the CSS engine. All new CSS values (such as "matrix(0 0 1 1)" or "attr('value') + 3cm") require an extension of the object model but not of SAC.
3. SAC doesn't provide a string based model of CSS.

4. The Parser interface

This interface represents the parser itself. All SAC parsers must implement this basic interface. It allows applications to register handlers for differents types of events, to set the factories for the CSS selectors, and to initiate the parsing of the CSS document or a partial CSS document.The conventional solution to create instance of objects in object-oriented design is to define factory methods. Objects implementing some interface "X" are created by a "createX()".

getParserVersion

Returns an absolute URI indicating which CSS language is supported by the underlying parser. Currently, two URIs are known:

• "http://www.w3.org/TR/REC-CSS1": The parser is a [CSS1] parser and will generate only CSS1 compatible events
• "http://www.w3.org/TR/REC-CSS2": The parser is a [CSS2] parser and will generate only CSS2 compatible events

parseStyleSheet

Parse a CSS document

parseSelectors

Parse a comma separated list of selectors. The parser will generate only comment and startSelector events

For a complete description, please report on the documentation available on the SAC public page ([SAC]).

5. The DocumentHandler interface

This is the main event-handling interface for SAC. An application will implement call-back functions for each of these, which are then called by the parser when the corresponding event occurs. The order of events in this interface is important, and mirrors the order of information in the document itself. For example, all of an @font-face rule's content (the properties) will occur, in order, between the startFontFace and the endFontFace events.

Here is a partial list of the functions:

comment(String text)

Receive notification of a comment. This is not required to be supported by the CSS parser.

startDocument(InputSource source)

Receive the notification of the start of a CSS document.

endDocument(InputSource source)

Receive the notification of the end of the CSS document.

startSelector(SelectorList selectors)

Receive the notification of the beginning of a style declaration. A style declaration is composed by a list of selectors and a list of properties.

endSelector(SelectorList selectors)

Receive the notification of the end of a style declaration. The parser notifies the end of a style declaration after the lkist of properties.

property(String name, LexicalUnit value, boolean important)

Receive notification of a property declaration.

startFontFace()

Receive notification of the beginning of a font face statement.

endFontFace()

Receive notification of the end of a font face statement.

6. The Selectors API

Contrary to the CSS Object Model ([CSSOM]), SAC represents the CSS selectors as objects. The SAC selectors can select any types of primary Nodes and apply a condition to these Nodes. Combinations between selectors and between conditions are also possible. SAC can express more selectors than are are currently possible in CSS1 and CSS2.

6.1. Selector

A primary Node can be:

• an element type node
• a pseudo-element type (such as :first-line or :first-letter)
• a text node
• a PI node
• A comment node
• a root node
• a cdata node

Combinations between these selectors are:

• parent-child relation (SAC_CHILD_SELECTOR or SAC_DESCENDANT_SELECTOR)
• sibling relation (SAC_DIRECT_ADJACENT_SELECTOR or SAC_INDIRECT_ADJACENT_SELECTOR) (@@ adjacent selectors with type node)
• others (SAC_NEGATIVE_SELECTOR).

Note that CSS1 and CSS2 have no syntax to express selectors for other Nodes than elements and pseudo-elements, and that negative selectors and indirect adjacent selectors also do not currently exist in CSS 1 or 2.

6.2. Condition

A condition can be attached to a selector with the ConditionalSelector interface.

Conditions can be:

• on attribute Node (SAC_ATTRIBUTE_CONDITION, SAC_BEGIN_HYPHEN_ATTRIBUTE_CONDITION, SAC_ONE_OF_ATTRIBUTE_CONDITION, SAC_CLASS_CONDITION, SAC_ID_CONDITION)
• on the language (SAC_LANG_CONDITION)
• on the order (SAC_POSITIONAL_CONDITION)
• ...

Combinations between these conditions are only logical (SAC_AND_CONDITION, SAC_OR_CONDITION).

7. The LexicalUnit interface

This interface represents a lexical unit for a CSS value. All lexical unit are represented (including comma, number, string, pixel units, etc.) as well as expressions over them (e.g., "12pt/14pt" is an expression with three parts: "12pt", "/" and "14pt").

8. Example

A small example for SAC is available in Java.

9. References

CSS1

Bert Bos; Hakon Wium Lie (eds). Cascading Style Sheets, Level 1. January 1999. W3C Recommendation. Available at http://www.w3.org/TR/REC-CSS1

CSS2

Bert Bos; Hakon Wium Lie; Chris Lilley; Ian Jacobs (eds). Cascading Style Sheets, Level 2. May 1998. W3C Recommendation. Available at http://www.w3.org/TR/REC-CSS2

CSSOM

Vidur Apparao; Philippe Le Hégaret; Chris Wilson (eds). Cascading Style Sheets, Level 2. May 2000. W3C Candidate Recommendation. Available at http://www.w3.org/TR/2000/CR-DOM-Level-2-20000510/css.html

Java

Gosling, James; Joy, Bill; Steele, Guy. The Java language specification. Addison-Wesley. 1998. Available at http://java.sun.com/docs/books/jls/index.html

SAC

Philippe Le Hegaret. Simple API for CSS. May 2000. Available at http://www.w3.org/Style/CSS/SAC/

SAX

David Megginson. Simple API for XML. May 2000. Available at http://www.megginson.com/SAX/