touched up code and documentation

qse/include/qse/Types.hpp

@@ -26,6 +26,9 @@
 QSE_BEGIN_NAMESPACE(QSE)
 /////////////////////////////////
 
+/**
+ * The Types class defines handy aliases for various QSE types.
+ */
 class Types
 {
 public:

qse/include/qse/sed/Sed.hpp

@@ -22,11 +22,15 @@
 #include <qse/Mmgr.hpp>
 #include <qse/sed/sed.h>
 
+/**@file
+ * A stream editor
+ */
+
 /////////////////////////////////
 QSE_BEGIN_NAMESPACE(QSE)
 /////////////////////////////////
 
-/** 
+/**
  * The Sed class implements a stream editor.
  */
 class Sed: public Mmgr
@@ -36,59 +40,188 @@ public:
 	typedef qse_sed_io_cmd_t sed_io_cmd_t;
 	typedef qse_sed_io_arg_t sed_io_arg_t;
 
+	/**
+	 * The Sed() function creates a uninitialized stream editor.
+	 */
 	Sed () throw (): sed (QSE_NULL) {}
 
+	/**
+	 * The open() function initializes a stream editor and makes it
+	 * ready for subsequent use.
+	 * @return 0 on success, -1 on failure.
+	 */
 	int open () throw ();
+
+	/**
+	 * The close() function finalized a stream editor.
+	 */
 	void close () throw ();
 
-	int compile (const char_t* sptr) throw ();
-	int compile (const char_t* sptr, size_t slen) throw ();
+	/**
+	 * The compile() function compiles a null-terminated string pointed
+	 * to by @a sptr.
+	 * @return 0 on success, -1 on failure
+	 */
+	int compile (
+		const char_t* sptr ///< a pointer to a null-terminated string
+	) throw ();
 
+	/**
+	 * The compile() function compiles a string pointed to by @a sptr
+	 * and of the length @a slen.
+	 * @return 0 on success, -1 on failure
+	 */
+	int compile (
+		const char_t* sptr, ///< a pointer to a string 
+		size_t slen         ///< the number of characters in the string
+	) throw ();
+
+	/**
+	 * The execute() function executes compiled commands over the IO
+	 * streams defined through IO handlers
+	 * @return 0 on success, -1 on failure
+	 */
 	int execute () throw ();
 
+	/**
+	 * The getErrorMessage() function gets the description of the last 
+	 * error occurred. It returns an empty string if the stream editor
+	 * has not been initialized with the open() function.
+	 */
+	const char_t* getErrorMessage() const;
+
+	/**
+	 * The getErrorLine() function gets the number of the line where
+	 * the last error occurred. It returns 0 if the stream editor has 
+	 * not been initialized with the open() function.
+	 */
+	size_t getErrorLine () const;
+
+	/**
+	 * The getErrorNumber() function gets the number of the last 
+	 * error occurred. It returns 0 if the stream editor has not been
+	 * initialized with the open function.
+	 */
+	int getErrorNumber () const;
+
+protected:
+	/**
+	 * The IO class is a base class for IO operation. It wraps around the 
+	 * qse_sed_io_arg_t type and exposes relevant information to
+	 * an IO handler 
+	 */
 	class IO
 	{
 	public:
-		friend class Sed;
+		/** 
+		 * The Mode enumerator defines IO operation modes.
+		 */
+		enum Mode
+		{
+			READ, ///< open a stream for reading
+			WRITE ///< open a stream for writing
+		};
 
 	protected:
-		IO (sed_io_arg_t* arg): arg(arg) {}
+		IO (sed_io_arg_t* arg, Mode mode): arg(arg), mode (mode) {}
 
 	public:
-		const char_t* getPath () const
-		{
-			return arg->path;
-		}
-
+		/**
+		 * The getHandle() function gets an IO handle set with the
+		 * setHandle() function. Once set, it is maintained until
+		 * an assoicated IO handler closes it or changes it with
+		 * another call to setHandle().
+		 */
 		const void* getHandle () const
 		{
 			return arg->handle;
 		}
 
+		/**
+		 * The setHandle() function sets an IO handle and is typically
+		 * called in stream opening functions such as Sed::openConsole()
+		 * and Sed::openFile(). You can get the handle with the 
+		 * getHandle() function as needed.
+		 */
 		void setHandle (void* handle)
 		{
 			arg->handle = handle;
 		}		
 
+		/**
+		 * The getMode() function gets the IO operation mode requested.
+		 * A stream opening function can inspect the mode requested and
+		 * open a stream properly 
+		 */
+		Mode getMode ()
+		{
+			return this->mode;
+		}
+
 	protected:
 		sed_io_arg_t* arg;
+		Mode mode;
 	};
 
+	/**
+	 * The Console class inherits the IO class and provides functionality 
+	 * for console IO operations.
+	 */
+	class Console: public IO
+	{
+	protected:
+		friend class Sed;
+		Console (sed_io_arg_t* arg, Mode mode): IO (arg, mode) {}
+	};
+
+	/**
+	 * The File class inherits the IO class and provides functionality
+	 * for file IO operations.
+	 */
+	class File: public IO
+	{
+	protected:
+		friend class Sed;
+		File (sed_io_arg_t* arg, Mode mode): IO (arg, mode) {}
+
+	public:
+		/**
+		 * The getName() function gets the file path requested.
+		 * You can call this function from the openFile() function
+		 * to determine a file to open.
+		 */
+		const char_t* getName () const
+		{
+			return arg->path;
+		}
+	};
+
+	/**
+	 * The openConsole() function should be implemented by a subclass
+	 * to open a console
+	 */
+	virtual int openConsole (Console& io) = 0;
+	virtual int closeConsole (Console& io) = 0;
+	virtual ssize_t readConsole (
+		Console& io, char_t* buf, size_t len) = 0;
+	virtual ssize_t writeConsole (
+		Console& io, const char_t* data, size_t len) = 0;
+
+	virtual int openFile (File& io) = 0;
+	virtual int closeFile (File& io) = 0;
+	virtual ssize_t readFile (
+		File& io, char_t* buf, size_t len) = 0;
+	virtual ssize_t writeFile (
+		File& io, const char_t* data, size_t len) = 0;
+
 protected:
 	sed_t* sed;
 
-	virtual int openInput (IO& io) = 0;
-	virtual int closeInput (IO& io) = 0;
-	virtual ssize_t readInput (IO& io, char_t* buf, size_t len) = 0;
-
-	virtual int openOutput (IO& io) = 0;
-	virtual int closeOutput (IO& io) = 0;
-	virtual ssize_t writeOutput (
-		IO& io, const char_t* data, size_t len) = 0;
-
 private:
-	static int xin (sed_t* s, sed_io_cmd_t cmd, sed_io_arg_t* arg);
-	static int xout (sed_t* s, sed_io_cmd_t cmd, sed_io_arg_t* arg);
+	static ssize_t xin (
+		sed_t* s, sed_io_cmd_t cmd, sed_io_arg_t* arg) throw ();
+	static ssize_t xout (
+		sed_t* s, sed_io_cmd_t cmd, sed_io_arg_t* arg) throw ();
 };
 
 /////////////////////////////////

qse/include/qse/sed/StdSed.hpp

@@ -21,24 +21,40 @@
 
 #include <qse/sed/Sed.hpp>
 
+/** @file
+ * A standard stream editor
+ *
+ * @example sed02.cpp
+ * The example shows a simple usage of the StdSed class.
+ */
+
 /////////////////////////////////
 QSE_BEGIN_NAMESPACE(QSE)
 /////////////////////////////////
 
+/**
+ * The StdSed class inherits the Sed class and implements the standard
+ * IO handlers and memory manager for easier use.
+ */
 class StdSed: public Sed
 {
 protected:
+	/** allocate a memory chunk */
 	void* allocMem   (qse_size_t n)            throw ();
+	/** resize a memory chunk */
 	void* reallocMem (void* ptr, qse_size_t n) throw ();
+	/** free a memory chunk */
 	void  freeMem    (void* ptr)               throw ();
 
-	int openInput (IO& io);
-	int closeInput (IO& io);
-	ssize_t readInput (IO& io, char_t* buf, size_t len);
+	int openConsole (Console& io);
+	int closeConsole (Console& io);
+	ssize_t readConsole (Console& io, char_t* buf, size_t len);
+	ssize_t writeConsole (Console& io, const char_t* data, size_t len);
 
-	int openOutput (IO& io);
-	int closeOutput (IO& io);
-	ssize_t writeOutput (IO& io, const char_t* data, size_t len);
+	int openFile (File& io);
+	int closeFile (File& io);
+	ssize_t readFile (File& io, char_t* buf, size_t len);
+	ssize_t writeFile (File& io, const char_t* data, size_t len);
 };
 
 /////////////////////////////////