More bits on the parser documentation front.

2003-06-22 Dodji Seketeli <dodji at seketeli dot org>

More bits on the parser documentation front.

Dodji.

1 files changed, 70 insertions, 2 deletions

diff --git a/docs/design/parser-architecture.txt b/docs/design/parser-architecture.txt
index 094c055..96e94d1 100644
--- a/docs/design/parser-architecture.txt
+++ b/docs/design/parser-architecture.txt
@@ -42,6 +42,7 @@ The parser is organized around two main classes :
 1/ CRInput
 2/ CRTknzr (Tokenizer or lexer)
 3/ CRParser
+4/ CROMParser
 
 II.1 The CRInput class
 -----------------------
@@ -58,7 +59,7 @@ classes that already use CRInput. After all, it is what is abstraction 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.
@@ -67,4 +68,71 @@ This methods returns the next css token found in the input stream.
 This provides an extremely usefull facility to the parser.
 
 II.3 The CRParser class
--------------------------
\ No newline at end of file
+-------------------------
+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
+
+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):
+
+ruleset : selector [ ',' S* selector ]*
+        '{' S* declaration [ ';' S* declaration ]* '}' S*
+
+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
+and so forth.
+
+II.3.1 Structure of a parsing method.
+-------------------------------------
+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.
+
+             eg: 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".
+
+             * Builds a basic abstract data structure to 
+	     store the information encountered
+	     during the parsing of the current character string.
+
+	     eg: cr_parser_parse_declaration() has the following prototype:
+
+             enum CRStatus
+	     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:
+
+	     declaration : property ':' S* expr prio?
+	                  | /* empty */
+
+	     * After completion, say if the parsing has succeed 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.
+
+	     * if the parsing failed, leave the position in the stream unchanged.
+	     That is the position in the character stream should be as if
+	     the parsing function hasn't been called at all.
+
+ 
\ No newline at end of file