diff options
| -rw-r--r-- | docs/design/parser-architecture.txt | 66 | ||||
| -rw-r--r-- | docs/examples/sac-example-1.c | 11 |
2 files changed, 42 insertions, 35 deletions
diff --git a/docs/design/parser-architecture.txt b/docs/design/parser-architecture.txt index e86fe33..1891381 100644 --- a/docs/design/parser-architecture.txt +++ b/docs/design/parser-architecture.txt @@ -14,12 +14,12 @@ conformance. Simplicity ----------- -We want the code to be maintainable by anyone who knows the css spec +We want the code to be maintainable by anyone who knows the CSS spec and who knows how to code in C. Therefore, we avoid to overuse -the C preprocessor magic and all the tricks that tends to turn C into +the C preprocessor magic and all the tricks that tend to turn C into a maintainance nightmare. -We also try to adhere to the gnome coding guidelines specified +We also try to adhere to the Gnome coding guidelines specified at http://developer.gnome.org/doc/guides/programming-guidelines. @@ -27,17 +27,17 @@ Reliability ----------- Each single function of the libcroco library should never crash, and this, whatever the arguments it takes. -As a consequence we tend to be paranoic when it comes to check +As a consequence we tend to be paranoid when it comes to check pointers values before dereferencing them for example... Conformance ----------- -We try to stick to the css spec. We now this is almost impossible to achieve -given the ressource we have but we think it is a sane target to chase. +We try to stick to the CSS spec. We know this is almost impossible to achieve +given the ressources we have but we think it is a sane target to chase. II) Overall architecture ========================= -The parser is organized around several main classes : +The parser is organized around several main classes: 1/ CRInput 2/ CRTknzr (Tokenizer or lexer) @@ -46,13 +46,13 @@ The parser is organized around several main classes : II.1 The CRInput class ----------------------- -The CRInput class provides the abstraction of +The CRInput class provides the abstraction of an utf8-encoded character stream. -Ideally, it should abstracts local data sources +Ideally, it should abstract local data sources (local files and in-memory buffers) -and remote data sources (sockets, url-identified ressources) but at the -moment, it abstracts local data sources only. +and remote data sources (sockets, url-identified ressources) but for the +moment, it can only abstract local data sources. Adding a new type of data source should be transparent for the classes that already use CRInput. After all, this is what abstraction is about :) @@ -61,11 +61,11 @@ classes that already use CRInput. After all, this is what abstraction is about : II.2 The CRTknzr class ---------------------- The main job of the tokenizer (or lexer) is to -provide a get_next_token () method. -This methods returns the next css token found in the input stream. +provide a get_next_token() method. +This methods returns the next CSS token found in the input stream. (Note that the input stream here is an instance of CRInput). -This provides an extremely usefull facility to the parser. +This provides an extremely useful facility to the parser. II.3 The CRParser class ------------------------- @@ -74,24 +74,24 @@ The core of the parser. The main job of this class is to provide a cr_parser_parse_stylesheet() method. During the parsing (the execution of the cr_parser_stylesheet()) the parser sents events to notify the application when it encounters -remarquable css constructions. This is the SAC (Simple api for CSS) api model. +remarquable CSS constructions. This is the SAC (Simple API for CSS) API model. -To achieve that task, almost each production of the css grammar +To achieve that task, almost each production of the CSS grammar has a matching parsing function (or method) in this class. -For example, the following production named "ruleset" (specified in the -css2 spec in appendix D.1): +For example, the following production named "ruleset" (specified in the +CSS2 spec in appendix D.1): ruleset : selector [ ',' S* selector ]* '{' S* declaration [ ';' S* declaration ]* '}' S* -is "implemented" by the cr_parser_parse_ruleset () method. +is "implemented" by the cr_parser_parse_ruleset() method. The same thing applies for the "selector" production: selector : simple_selector [ combinator simple_selector ]* -which is implemented by the cr_parser_parse_selector() method... and so on +which is implemented by the cr_parser_parse_selector() method... and so on and so forth. II.3.1 Structure of a parsing method. @@ -100,11 +100,11 @@ A parsing method (e.g cr_parser_parse_ruleset()) is there to: * try to recognize a substring of the incoming character string - as something that matches a given css grammar production. + as something that matches a given CSS grammar production. e.g: the job of the cr_parser_parse_ruleset() is to try - to recognize if "what" comes next in the input strean - is a css2 "ruleset". + to recognize if "what" comes next in the input stream + is a CSS2 "ruleset". * build a basic abstract data structure to store the information encountered @@ -116,27 +116,27 @@ to: cr_parser_parse_declaration (CRParser *a_this, GString **a_property, CRTerm **a_value) ; - In case of successfull parsing, this method returns - (via its parameters) the property _and_ the - value of the css2 declaration. - Note that a css2 declaration is specified as follows: + In case of successful parsing, this method returns + (via its parameters) the property _and_ the + value of the CSS2 declaration. + Note that a CSS2 declaration is specified as follows: declaration : property ':' S* expr prio? | /* empty */ - * After completion, say if the parsing has succeed or not. + * After completion, say if the parsing has succeeded or not. eg: cr_parser_parse_declaration() returns CR_OK if the - parsing has succeed, and error code otherwise. Obviously, - the a_property and a_value out parameter are valid if and only - if the function return value is CR_OK. + parsing has succeeded, and error code otherwise. Obviously, + the out parameters "a_property" and "a_value" are valid if and only + if the return value is CR_OK. * whenever the function is parsing a construct that must - be notified to the user as part of the SAC api spec, notify + be notified to the user as part of the SAC API spec, notify the user by calling the right SAC callback. * if the parsing failed, leave the position in the stream unchanged. - That is the position in the character stream should be as if + That is, the position in the character stream should be as if the parsing function hasn't been called at all. diff --git a/docs/examples/sac-example-1.c b/docs/examples/sac-example-1.c index c72fd70..ded16f0 100644 --- a/docs/examples/sac-example-1.c +++ b/docs/examples/sac-example-1.c @@ -4,7 +4,8 @@ *This test example shows how to use the SAC api. * *This features a simple parser that says "hey" when - *it encounters a css ruleset :) + *it encounters the beginning of a CSS ruleset, and "woohoo" + *at the end of a CSS ruleset. * *To compile this file, type: * @@ -13,6 +14,12 @@ *Make sure you have compiled and installed libcroco prior to trying to *compile this file :) * + *Once you have compiled it, type: + * + *./sac-example-1 <a-path-to-a-css-file> + * + *to try it on a CSS file of your choice. + * *Initial Author: Dodji Seketeli <Dodji 47 seketeli dot org> */ @@ -42,7 +49,7 @@ static void end_selector_cb (CRDocHandler *a_handler, CRSelector *a_selector) { - printf ("Hey, this is the end of a ruleset\n") ; + printf ("Woohoo, this is the end of a ruleset\n") ; printf ("======================================\n\n") ; } |