summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/design/parser-architecture.txt66
-rw-r--r--docs/examples/sac-example-1.c11
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") ;
}