mode bits on this the beginning of a code example on how to use the SAC

2003-06-23 Dodji Seketeli <dodji 47 seketeli dot org>
* docs/design/parser-architecture.txt : mode bits on this
* the beginning of a code example on how to use the SAC api.

Dodji.

3 files changed, 203 insertions, 6 deletions

diff --git a/ChangeLog b/ChangeLog
index fb19d9d..c2fc410 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2003-06-23  Dodji Seketeli  <dodji()47()seketeli()dot()org>
+
+	* docs/design/parser-architecture.txt: more bits on this.
+
 2003-06-22  Dodji Seketeli  <dodji at seketeli dot org>
 
 	* src/parser/cr-statement.c: added
diff --git a/docs/design/parser-architecture.txt b/docs/design/parser-architecture.txt
index 1462296..e86fe33 100644
--- a/docs/design/parser-architecture.txt
+++ b/docs/design/parser-architecture.txt
@@ -33,11 +33,11 @@ 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 sane target to chase.
+given the ressource we have but we think it is a sane target to chase.
 
 II) Overall architecture
 =========================
-The parser is organized around two main classes :
+The parser is organized around several main classes :
 
 1/ CRInput
 2/ CRTknzr (Tokenizer or lexer)
@@ -55,7 +55,7 @@ and remote data sources (sockets, url-identified ressources) but at the
 moment, it abstracts local data sources only.
 
 Adding a new type of data source should be transparent for the
-classes that already use CRInput. After all, it is what is abstraction about :)
+classes that already use CRInput. After all, this is what abstraction is about :)
 
 
 II.2 The CRTknzr class
@@ -74,7 +74,7 @@ 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 
 has a matching parsing function (or method) in this class.
@@ -102,11 +102,11 @@ 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 
+             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".
 
-             * Builds a basic abstract data structure to 
+             * build a basic abstract data structure to 
 	     store the information encountered
 	     during the parsing of the current character string.
 
@@ -140,5 +140,8 @@ to:
 	     the parsing function hasn't been called at all.
 
 	     
+II.4 The selection Engine.
+--------------------------
+
 
  
\ No newline at end of file
diff --git a/docs/examples/sac-example-1.c b/docs/examples/sac-example-1.c
new file mode 100644
index 0000000..c72fd70
--- /dev/null
+++ b/docs/examples/sac-example-1.c
@@ -0,0 +1,190 @@
+/* -*- Mode: C; indent-tabs-mode:nil; c-basic-offset: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 :)
+ *
+ *To compile this file, type:
+ *
+ *gcc -g  -o sac-example-1 `pkg-config --cflags --libs libcroco` sac-example-1.c
+ *
+ *Make sure you have compiled and installed libcroco prior to trying to
+ *compile this file :)
+ *
+ *Initial Author: Dodji Seketeli <Dodji 47 seketeli dot org>
+ */
+
+#include <libcroco.h>
+
+/**
+ *This is a callback function that will
+ *be called at the begining of each css ruleset.
+ *@param a_handler a pointer to the current sac
+ *document handler
+ *@param a_selector a pointer to the selector.
+ *of the current ruleset.
+ */
+static void
+start_selector_cb (CRDocHandler *a_handler,
+		   CRSelector *a_selector)
+{
+	printf ("==========================================\n") ;
+	printf ("Hey, this is the begining of a ruleset\n") ;
+}
+
+/**
+ *This is a callback function that will be called at the end
+ *of the each css ruleset.
+ */
+static void
+end_selector_cb (CRDocHandler *a_handler,
+		 CRSelector *a_selector)
+{
+	printf ("Hey, this is the end of a ruleset\n") ;
+	printf ("======================================\n\n") ;
+}
+
+/**
+ *Displays some information about how to use this program.
+ *@param a_prog_name the name of the current program.
+ */
+void
+display_usage (unsigned char *a_prog_name)
+{
+	unsigned char *prog_name = a_prog_name ;
+
+	if (!prog_name)
+	{
+		prog_name = "sac-example-1" ;
+	}
+
+	printf ("usage: %s [--help] | <css file name>\n", prog_name) ;	
+}
+
+int
+main (int argc, char **argv)
+{	
+	unsigned short i = 0 ;
+	unsigned char * file_path = NULL ;
+	CRParser * parser = NULL ;
+	CRDocHandler *sac_handler = NULL ;
+
+	if (argc <= 1)
+	{
+		display_usage (argv[0]) ;
+		return -1 ;
+	}
+
+	/*
+	 *Let's parse the
+	 *command line arguments of this 
+	 *program in this loop.
+	 */
+	for (i=0 ; i < argc ;i++)
+	{
+		if (*argv[i] != '-')
+			break ;
+
+		if (!strcmp (argv[i], "--help")
+		    || !strcmp (argv[i], "-h"))
+		{
+			display_usage (argv[0]) ;
+			return ;
+		}
+		else
+		{
+			/*
+			 *no other option is
+			 *available now, so this is
+			 *a bit redundant...
+			 */
+			display_usage (argv[0]) ;
+		}
+	}
+
+	if (i >= argc)
+	{
+		/*
+		 *no file name has been given
+		 *in parameter, go out.
+		 */
+		return ;
+	}
+	
+	/****************************************
+	 *Now, the real libcroco related stuffs...
+	 ****************************************/
+
+	file_path = argv[i + 1] ;
+	
+	/*
+	 *Instanciate the libcroco parser.
+	 */
+	parser = cr_parser_new_from_file (file_path,
+					  CR_ASCII) ;
+	if (!parser)
+	{
+		/*
+		 *Damned, something bad happened ...
+		 */
+		return ;
+	}
+
+	/*
+	 *Instanciates the SAC document handler.
+	 */
+	sac_handler = cr_doc_handler_new () ;
+	if (!sac_handler)
+	{
+		/*
+		 *Argh, something bad happened here :-\
+		 *Let's release the resources we allocated 
+		 *and let's get out.
+		 */
+
+		cr_parser_destroy (parser) ;
+		return ;
+	}
+
+	/******************
+	 *Sets some of the sac document handlers.
+	 ****************/
+
+	/*
+	 *This sac handler callback function will get called by the parser
+	 *each time it encounters the beginning of a ruleset.
+	 */
+	sac_handler->start_selector = start_selector_cb ;
+	
+	/*
+	 *This sac handler callback function will get called by the parser
+	 *each time it encounters the end of a ruleset.
+	 */
+	sac_handler->end_selector = end_selector_cb ;
+
+	/*
+	 *Let's register our sac handler into the parser.
+	 */
+	cr_parser_set_sac_handler (parser, sac_handler) ;
+
+	/*
+	 *Now, let's do the parsing !!!
+	 */
+	cr_parser_parse (parser) ;
+	
+	/*******************************************************
+	 *End of the parsing. A lot of sentences begining with "Hey"
+	 *may have been printed on the screen...
+	 ***********************************************/
+
+	/*
+	 *Time to free the resources we allocated.
+	 */
+	cr_parser_destroy (parser) ;
+
+	cr_doc_handler_unref (sac_handler) ;
+
+	return 0 ;
+}