From 879f4addd4c94492c21c36c0be98122a879907bf Mon Sep 17 00:00:00 2001
From: Stef Walter <stef@memberwebs.com>
Date: Thu, 22 Jul 2004 22:30:48 +0000
Subject: - Comments and formatting changes.

---
 src/rtfparser.h | 97 ++++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 68 insertions(+), 29 deletions(-)

(limited to 'src/rtfparser.h')

diff --git a/src/rtfparser.h b/src/rtfparser.h
index bfa2e59..6b9e10d 100644
--- a/src/rtfparser.h
+++ b/src/rtfparser.h
@@ -36,6 +36,8 @@
  *
  */
 
+// RENAME RTFParser.h
+
 #ifndef __RTFREADER_H__
 #define __RTFREADER_H__
 
@@ -43,29 +45,22 @@
 #include <stack>
 #include <stdio.h>
 
-class RtfReader;
+class RtfHandler;
 
-class RtfHandler
-{
-public:
-	virtual void startDocument(RtfReader* reader) = 0;
-	virtual void endDocument() = 0;
-  virtual void controlWord(const string& cw, int flags, int param) = 0;
-	virtual void groupStart() = 0;
-	virtual void groupEnd() = 0;
-	virtual void charData(wstring data) = 0;
-
-	static const int kAsterisk;
-	static const int kHasParam;
-	static const int kIsEncoded;
-};
-
-class RtfReader
+/*
+ * RTFParser
+ *
+ * A class that parses the RTF into it's tags and groups etc... It feeds its
+ * parsed data into into a handler interface (see below) for processing.
+ *
+ * Performs some basic conversion and sanity checking (unicode chars etc...)
+ * as well.
+ */
+class RtfParser
 {
 public:
-	RtfReader();
-	virtual ~RtfReader();
-
+	RtfParser();
+	virtual ~RtfParser();
 
 	bool parse(string fileName);
 	bool parse(FILE* file);
@@ -81,12 +76,13 @@ public:
 	void setUnicode(bool unicode);
 
 protected:
-	RtfHandler* m_handler;
-	int m_depth;
-	bool m_parseHex;
-	string m_parseErrors;
+	RtfHandler* m_handler;         // The current handler
+	int m_depth;                   // To keep track of group depth
+	bool m_parseHex;               // Whether to parse hex chars or not
+	string m_parseErrors;          // A list of all the RTF parsing errors
 
-	// Unicode handling
+    // TODO: Look at exactly what this is doing
+    // Unicode char handling
 	bool m_parseUnicode;
 	typedef std::stack<int> StackInt;
 	StackInt m_uniEatStack;
@@ -94,19 +90,62 @@ protected:
 
 private:
 
+    // TODO: Why aren't these just members?
+
 	struct RtfContext
 	{
-		FILE* file;
-		bool isData;
-		wstring data;
+		FILE* file;       // The current file being parsed
+		wstring data;     // Any data stored up ready to be sent to handler
+        bool isData;      // TODO: Do we need this?
 	};
 
+    // Parse helpers
 	bool parseControlWord(RtfContext& cx);
 	bool parseHexChar(RtfContext& cx, int num);
+
+    // Convenience functions for calling the handler
 	void sendControlWord(RtfContext& cx, string cw, int flags, int param);
 	void sendData(RtfContext& cx, wchar_t ch);
 	void sendData(RtfContext& cx, wstring data);
-	void emptyData(RtfContext& cx);
+	void flushData(RtfContext& cx);
+};
+
+/*
+ * RTFHandler
+ *
+ * An interface called by RTFParser with tags and groups etc... parsed from
+ * an RTF file.
+ */
+class RtfHandler
+{
+public:
+
+    // Called at the beginning of the document
+    virtual void startDocument(RtfReader* reader) = 0;
+
+    // Called at the end of the document
+    virtual void endDocument() = 0;
+
+    // Called when an RTF control word is hit. Flags below.
+    // If control word has no param then param is -1
+    virtual void controlWord(const string& cw, int flags, int param) = 0;
+
+    // Called when an RTF group opened
+    virtual void groupStart() = 0;
+
+    // Called when an RTF group is closed
+    virtual void groupEnd() = 0;
+
+    // A block of character data encountered
+    virtual void charData(wstring data) = 0;
+
+    // Flags for controlWord
+    enum
+    {
+        kAsterisk = 0x00000001,
+        kHasParam = 0x00000002,
+        kIsEncoded = 0x00000004
+    };
 };
 
 #endif // __RTFREADER_H__
-- 
cgit v1.2.3