eof is true when no more chars are available, not when we've read the

2000-01-13  bertrand  <bertrand@helixcode.com>

	* camel/providers/mbox/camel-mbox-parser.c (read_next_buffer_chunk):
	eof is true when no more chars are available, not
	when we've read the entire file.
	(initialize_buffer): ditto.
	(read_message_begining): documented.
	(read_header): ditto.
	(new_message_detected): ditto.
	(advance_n_chars): ditto.
	(goto_next_char): ditto.
	(read_next_buffer_chunk): ditto.
	(initialize_buffer): ditto.
	(parser_free): ditto.
	(new_parser): ditto.

More parser decoding and clean-ups.
Documented all the static routines properly.

svn path=/trunk/; revision=1567

1 files changed, 104 insertions, 19 deletions

diff --git a/camel/providers/mbox/camel-mbox-parser.c b/camel/providers/mbox/camel-mbox-parser.c
index 1e9b2abe3d..2509a5a49a 100644
--- a/camel/providers/mbox/camel-mbox-parser.c
+++ b/camel/providers/mbox/camel-mbox-parser.c
@@ -106,6 +106,16 @@ clear_message_info (CamelMboxParserMessageInfo *preparsing_info)
 
 
 
+/**
+ * new_parser: create a new parser object
+ * @fd: file descriptor opened on the mbox file
+ * @message_delimiter: the string that announce the start of a new message.
+ * 
+ * Create a new parser object. This object is the place where are 
+ * stored all the information concerning the parsing process. 
+ * 
+ * Return value: The newly created parser object.
+ **/
 static CamelMboxPreParser *
 new_parser (int fd,
 	    const gchar *message_delimiter) 
@@ -134,10 +144,18 @@ new_parser (int fd,
 
 
 
+/**
+ * parser_free: free the parser object
+ * @parser: the parser objet to free.
+ * 
+ * it is important to notice that all structures allocated
+ * in new_parser () are freed ** EXCEPT ** the message
+ * information array, i.e. the preparsed_messages 
+ * field. 
+ **/
 void 
 parser_free (CamelMboxPreParser *parser)
 {
-	
 	g_free (parser->buffer);
 	g_free (parser->message_delimiter);
 	g_string_free (parser->tmp_string, TRUE);
@@ -149,7 +167,14 @@ parser_free (CamelMboxPreParser *parser)
 
 
 /* ** handle exceptions here */
-/* read the first chunk of data in the buffer */
+/**
+ * initialize_buffer: read the first chunk of data in the buffer
+ * @parser: parser object to fill
+ * @first_position: position to start the read at
+ * 
+ * read the first chunk of data from the mbox file. 
+ * 
+ **/
 static void 
 initialize_buffer (CamelMboxPreParser *parser,
 		   guint first_position)
@@ -177,7 +202,8 @@ initialize_buffer (CamelMboxPreParser *parser,
 	/* ** check for an error here */
 
 	parser->last_position = buf_nb_read;
-	if (buf_nb_read < (MBOX_PARSER_BUF_SIZE - parser->left_chunk_size))
+
+	if (buf_nb_read == 0)
 		parser->eof =TRUE;
 
 	parser->current_position = parser->left_chunk_size;
@@ -186,13 +212,24 @@ initialize_buffer (CamelMboxPreParser *parser,
 
 
 
-/* read next data in the mbox file */
+/**
+ * read_next_buffer_chunk: read the next chunk of data in the mbox file
+ * @parser: parser object
+ * 
+ * read the next chunk of data in the mbox file. 
+ * Routine copies the last part of the buffer at 
+ * the begining are concatenate the read data to
+ * it. This allows strcmp of keywords in the buffer,
+ * until the last postion. That means you can 
+ * do a strcmp (buffer, keyword) for any of the
+ * keyword defined at the begining of this file. 
+ * 
+ **/
 static void 
 read_next_buffer_chunk (CamelMboxPreParser *parser)
 {
 	gint buf_nb_read;
 
-
 	g_assert (parser);
 	
 	/* read the next chunk of data in the folder file  : */
@@ -210,9 +247,9 @@ read_next_buffer_chunk (CamelMboxPreParser *parser)
 	} while ((buf_nb_read == -1) && (errno == EINTR));
 	/* ** check for an error here */
 
-
 	parser->last_position = buf_nb_read;
-	if (buf_nb_read < (MBOX_PARSER_BUF_SIZE - parser->left_chunk_size))
+
+	if (buf_nb_read == 0)
 		parser->eof =TRUE;
 
 	parser->current_position = 0;
@@ -221,7 +258,15 @@ read_next_buffer_chunk (CamelMboxPreParser *parser)
 
 
 
-/* read next char in the buffer */
+/**
+ * goto_next_char: go one postion forward in the buffer
+ * @parser: parser object
+ * 
+ * goto one position forward in the buffer. If necessary, 
+ * read the next chunk of data in the file, possibly
+ * raising the parser->eof flag. 
+ * 
+ **/
 static void 
 goto_next_char (CamelMboxPreParser *parser) 
 {	
@@ -238,7 +283,13 @@ goto_next_char (CamelMboxPreParser *parser)
 
 
 
-/* advance n_chars in the buffer */
+
+/**
+ * advance_n_chars: go n positions forward in the buffer.
+ * @parser: parser object
+ * @n: number of characters to advance. 
+ * 
+ **/
 static void
 advance_n_chars (CamelMboxPreParser *parser, guint n) 
 {	
@@ -271,6 +322,17 @@ advance_n_chars (CamelMboxPreParser *parser, guint n)
    store the previous message information and 
    clean the temporary structure used to store 
    the informations */
+
+
+/**
+ * new_message_detected: routine to call when a new message has been detected
+ * @parser: parser object.
+ * 
+ * this routine must be called when the keyword determining the 
+ * begining of a new message has been detected. It pushes the
+ * information fetched for the last message into the message information
+ * array. Also, it gets the parser to the end of the line. 
+ **/
 static void 
 new_message_detected (CamelMboxPreParser *parser)
 {
@@ -291,12 +353,13 @@ new_message_detected (CamelMboxPreParser *parser)
 
 	/* go to the end of the line */
 	do {
+
 		c = parser->buffer[parser->current_position];
 		goto_next_char (parser);	
-		//printf ("%c", c);
+
 	} while (c != '\n');
 	
-	//printf ("\n");
+	/* save message position in the message information structure */
 	(parser->current_message_info).message_position = parser->real_position;
 
 	parser->is_pending_message = TRUE;
@@ -308,10 +371,25 @@ new_message_detected (CamelMboxPreParser *parser)
 
 
 
-/* read a header value and put it in the string pointer
-   to by header_content. This routine stops on a 
-   the first character after the last newline of the 
-   header content. 
+
+/**
+ * read_header: read the header content contained after the current position.
+ * @parser: the parser object.
+ * @header_content: a pointer on a (char *) variable to feed with the obtained header string. 
+ * 
+ * This routine must be called when the parser has detected a header 
+ * and it wants the header content to be stored. The parser current position 
+ * must EXACTELY be located at the begining of the header content line. 
+ * For example, if the file contains the line : 
+ *     from:Bertrand Guiheneuf <bertrand@helixcode.com>
+ *
+ * When this routine is called, the parser must be located 
+ * on the "B" of "Bertrand".
+ * 
+ * When this routine returns, the parser is located just 
+ * after the "\n" at the end of the header content.
+ *
+ **/
 */
 static void 
 read_header (CamelMboxPreParser *parser, gchar **header_content)
@@ -377,10 +455,17 @@ read_header (CamelMboxPreParser *parser, gchar **header_content)
 
 
 
-/* read the begining of the message and put it in the message
-   summary field. If we the search ended on a newline, returns 
-   %TRUE, else returns %FALSE   
-*/
+
+/**
+ * read_message_begining: read the first characters of a message body
+ * @parser: parser object
+ * @message_summary: a pointer on a (gchar *) variable where the obtained string will be stored. 
+ * 
+ * Read the first lines of a message. When calling this routine, the
+ * parser must be located at the begining of the message body. 
+ * 
+ * Return value: if the parsing inside this routine last read a newline, then %TRUE is returned, otherwise %FALSE is returned
+ **/
 static gboolean
 read_message_begining (CamelMboxPreParser *parser, gchar **message_summary)
 {