touched up code and documentation

qse/README

@@ -1,28 +1,9 @@
-/** @mainpage 
-
-@section INTRODUCTION
-
 QSE provides a script engine for various scripting languages and utility programs. It aims to produce a flexible script engine framework that can be embedded into an application. A hosting application can access various aspects of the embedded script engine and vice versa.
 
 The library is licended under the Apache License, Version 2.0.
 
 The project webpage: http://qse.googlecode.com/
 
-For furthur information, contact: Chung, Hyung-Hwan <b a c o n e v i @ g m a i l . c o m>
+For furthur information, contact: 
+Chung, Hyung-Hwan <b a c o n e v i @ g m a i l . c o m>
 
-@section INSTALLATION
-Cross compiling for WIN32 with MINGW32
-
-	./configure --host=i586-mingw32msvc --target=i586-mingw32msvc --enable-syscall
-	make 
-
-@section DOCUMENTATION
-Generate the API documents with robodoc.
-	
-	robodoc --rc doc/robodoc.rc --css doc/robodoc.css --src . --doc ./doc/qse 
-
-@section MODULES
-QSE includes various modules:
-- AWK: ::qse_awk_t
-- SED: ::qse_sed_t
-*/

qse/doc/Doxyfile

@@ -564,7 +564,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = ../include ../README
+INPUT                  = ../include ./page
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 
@@ -581,7 +581,7 @@ INPUT_ENCODING         = UTF-8
 # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx 
 # *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90
 
-FILE_PATTERNS          = *.h *.c *.hpp *.cpp
+FILE_PATTERNS          = *.h *.c *.hpp *.cpp *.doc
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories 
 # should be searched for input files as well. Possible values are YES and NO. 
@@ -1210,13 +1210,13 @@ ENABLE_PREPROCESSING   = YES
 # compilation will be performed. Macro expansion can be done in a controlled 
 # way by setting EXPAND_ONLY_PREDEF to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES 
 # then the macro expansion is limited to the macros specified with the 
 # PREDEFINED and EXPAND_AS_DEFINED tags.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files 
 # in the INCLUDE_PATH (see below) will be search if a #include is found.
@@ -1244,7 +1244,11 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator 
 # instead of the = operator.
 
-PREDEFINED             = 
+PREDEFINED             =  \
+	"QSE_BEGIN_NAMESPACE(x)=namespace x {" \
+	"QSE_END_NAMESPACE(x)=}" \
+	"QSE_BEGIN_NAMESPACE2(x,y)=namespace x { namespace y {" \
+	"QSE_END_NAMESPACE2(x,y)=} }"
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 
 # this tag can be used to specify a list of macro names that should be expanded. 

qse/doc/page/awk.doc

@@ -0,0 +1,4 @@
+/** @page awk AWK
+
+AWK Interpreter
+*/

qse/doc/page/main.doc

@@ -0,0 +1,29 @@
+/** @mainpage QSE
+
+@section INTRODUCTION
+
+QSE provides a script engine for various scripting languages and utility programs. It aims to produce a flexible script engine framework that can be embedded into an application. A hosting application can access various aspects of the embedded script engine and vice versa.
+
+The library is licended under the Apache License, Version 2.0.
+
+The project webpage: http://qse.googlecode.com/
+
+For furthur information, contact:
+Chung, Hyung-Hwan <b a c o n e v i @ g m a i l . c o m>
+
+@section INSTALLATION
+Cross compiling for WIN32 with MINGW32
+
+	./configure --host=i586-mingw32msvc --target=i586-mingw32msvc --enable-syscall
+	make 
+
+@section DOCUMENTATION
+Generate the API documents with robodoc.
+	
+	robodoc --rc doc/robodoc.rc --css doc/robodoc.css --src . --doc ./doc/qse 
+
+@section MODULES
+QSE includes various modules:
+- @ref awk "AWK"
+- @ref sed "SED"
+*/

qse/doc/page/sed.doc

@@ -0,0 +1,9 @@
+/** @page sed SED
+
+STREAM EDITOR
+a stream editor is provided
+
+@section sed_io_handler How to write an IO handler
+IO handler has the following prototype...
+
+*/

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,6 +22,10 @@
 #include <qse/Mmgr.hpp>
 #include <qse/sed/sed.h>
 
+/**@file
+ * A stream editor
+ */
+
 /////////////////////////////////
 QSE_BEGIN_NAMESPACE(QSE)
 /////////////////////////////////
@@ -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);
 };
 
 /////////////////////////////////

qse/lib/sed/Sed.cpp

@@ -19,9 +19,6 @@
 #include <qse/sed/Sed.hpp>
 #include "sed.h"
 
-#include <qse/utl/stdio.h>
-#include <stdlib.h>
-
 /////////////////////////////////
 QSE_BEGIN_NAMESPACE(QSE)
 /////////////////////////////////
@@ -66,22 +63,40 @@ int Sed::execute () throw ()
 	return qse_sed_exec (sed, xin, xout);
 }
 
-int Sed::xin (sed_t* s, sed_io_cmd_t cmd, sed_io_arg_t* arg)
+const Sed::char_t* Sed::getErrorMessage () const
+{
+	return (sed == QSE_NULL)? QSE_T(""): qse_sed_geterrmsg (sed);
+}
+
+Sed::size_t Sed::getErrorLine () const
+{
+	return (sed == QSE_NULL)? 0: qse_sed_geterrlin (sed);
+}
+
+int Sed::getErrorNumber () const
+{
+	return (sed == QSE_NULL)? 0: qse_sed_geterrnum (sed);
+}
+
+Sed::ssize_t Sed::xin (sed_t* s, sed_io_cmd_t cmd, sed_io_arg_t* arg) throw ()
 {
 	Sed* sed = *(Sed**)QSE_XTN(s);
-	IO io (arg);
+
+	if (arg->path == QSE_NULL)
+	{
+		Console io (arg, Console::READ);
 
 		try
 		{
 			switch (cmd)	
 			{
 				case QSE_SED_IO_OPEN:
-				return sed->openInput (io);
+					return sed->openConsole (io);
 				case QSE_SED_IO_CLOSE:
-				return sed->closeInput (io);
+					return sed->closeConsole (io);
 				case QSE_SED_IO_READ:
-				return sed->readInput (
-					io, arg->u.r.buf, arg->u.w.len);
+					return sed->readConsole (
+						io, arg->u.r.buf, arg->u.r.len);
 				default:
 					return -1;
 			}
@@ -91,22 +106,50 @@ int Sed::xin (sed_t* s, sed_io_cmd_t cmd, sed_io_arg_t* arg)
 			return -1;
 		}
 	}
-
-int Sed::xout (sed_t* s, sed_io_cmd_t cmd, sed_io_arg_t* arg)
+	else
 	{
-	Sed* sed = *(Sed**)QSE_XTN(s);
-	IO io (arg);
+		File io (arg, File::READ);
 
 		try
 		{
 			switch (cmd)
 			{
 				case QSE_SED_IO_OPEN:
-				return sed->openOutput (io);
+					return sed->openFile (io);
 				case QSE_SED_IO_CLOSE:
-				return sed->closeOutput (io);
+					return sed->closeFile (io);
 				case QSE_SED_IO_READ:
-				return sed->writeOutput (
+					return sed->readFile (
+						io, arg->u.r.buf, arg->u.r.len);
+				default:
+					return -1;
+			}
+		}
+		catch (...)
+		{
+			return -1;
+		}
+	}
+}
+
+Sed::ssize_t Sed::xout (sed_t* s, sed_io_cmd_t cmd, sed_io_arg_t* arg) throw ()
+{
+	Sed* sed = *(Sed**)QSE_XTN(s);
+
+	if (arg->path == QSE_NULL)
+	{
+		Console io (arg, Console::WRITE);
+
+		try
+		{
+			switch (cmd)	
+			{
+				case QSE_SED_IO_OPEN:
+					return sed->openConsole (io);
+				case QSE_SED_IO_CLOSE:
+					return sed->closeConsole (io);
+				case QSE_SED_IO_WRITE:
+					return sed->writeConsole (
 						io, arg->u.w.data, arg->u.w.len);
 				default:
 					return -1;
@@ -117,6 +160,31 @@ int Sed::xout (sed_t* s, sed_io_cmd_t cmd, sed_io_arg_t* arg)
 			return -1;
 		}
 	}
+	else
+	{
+		File io (arg, File::WRITE);
+
+		try
+		{
+			switch (cmd)
+			{
+				case QSE_SED_IO_OPEN:
+					return sed->openFile (io);
+				case QSE_SED_IO_CLOSE:
+					return sed->closeFile (io);
+				case QSE_SED_IO_WRITE:
+					return sed->writeFile (
+						io, arg->u.w.data, arg->u.w.len);
+				default:
+					return -1;
+			}
+		}
+		catch (...)
+		{
+			return -1;
+		}
+	}
+}
 
 /////////////////////////////////
 QSE_END_NAMESPACE(QSE)

qse/lib/sed/StdSed.cpp

@@ -40,80 +40,57 @@ void StdSed::freeMem (void* ptr) throw ()
 	::free (ptr); 
 }
 
-int StdSed::openInput (IO& io)
+int StdSed::openConsole (Console& io)
 {
-	int flags;
-	const qse_char_t* path = io.getPath ();
-
-	if (path == QSE_NULL) io.setHandle (qse_sio_in);
-	else
-	{
-		qse_fio_t* fio;
-		fio = qse_fio_open (
-			this, 0, path,
-			QSE_FIO_READ | QSE_FIO_TEXT,
-			QSE_FIO_RUSR | QSE_FIO_WUSR |
-			QSE_FIO_RGRP | QSE_FIO_ROTH
-		);	
-		if (fio == NULL) return -1;
-
-		io.setHandle (fio);
-	}
-
+	io.setHandle ((io.getMode() == Console::READ)?  qse_sio_in: qse_sio_out);
 	return 1;
 }
 
-int StdSed::closeInput (IO& io)
+int StdSed::closeConsole (Console& io)
+{
+	return 0;
+}
+
+StdSed::ssize_t StdSed::readConsole (Console& io, char_t* buf, size_t len)
+{
+	return qse_sio_getsn ((qse_sio_t*)io.getHandle(), buf, len);
+}
+
+StdSed::ssize_t StdSed::writeConsole (Console& io, const char_t* data, size_t len) 
+{
+	return qse_sio_putsn ((qse_sio_t*)io.getHandle(), data, len);
+}
+
+int StdSed::openFile (File& io) 
+{
+	int flags = (io.getMode() == File::READ)?
+		QSE_FIO_READ: (QSE_FIO_WRITE|QSE_FIO_CREATE|QSE_FIO_TRUNCATE);
+
+	qse_fio_t* fio = qse_fio_open (
+		this, 0, io.getName(),
+		flags | QSE_FIO_TEXT,
+		QSE_FIO_RUSR | QSE_FIO_WUSR |
+		QSE_FIO_RGRP | QSE_FIO_ROTH
+	);	
+	if (fio == QSE_NULL) return -1;
+
+	io.setHandle (fio);
+	return 1;
+}
+
+int StdSed::closeFile (File& io) 
 {
-	if (io.getPath() != QSE_NULL) 
 	qse_fio_close ((qse_fio_t*)io.getHandle());
 	return 0;
 }
 
-ssize_t StdSed::readInput (IO& io, char_t* buf, size_t len)
+StdSed::ssize_t StdSed::readFile (File& io, char_t* buf, size_t len) 
 {
-	if (io.getPath() == QSE_NULL)
-		return qse_sio_getsn ((qse_sio_t*)io.getHandle(), buf, len);
-	else
 	return qse_fio_read ((qse_fio_t*)io.getHandle(), buf, len);
 }
 
-int StdSed::openOutput (IO& io) 
+StdSed::ssize_t StdSed::writeFile (File& io, const char_t* data, size_t len) 
 {
-	int flags;
-	const qse_char_t* path = io.getPath ();
-
-	if (path == QSE_NULL) io.setHandle (qse_sio_out);
-	else
-	{
-		qse_fio_t* fio;
-		fio = qse_fio_open (
-			this, 0, path,
-			QSE_FIO_WRITE | QSE_FIO_CREATE |
-			QSE_FIO_TRUNCATE | QSE_FIO_TEXT,
-			QSE_FIO_RUSR | QSE_FIO_WUSR |
-			QSE_FIO_RGRP | QSE_FIO_ROTH
-		);	
-		if (fio == NULL) return -1;
-
-		io.setHandle (fio);
-	}
-
-	return 1;
-}
-
-int StdSed::closeOutput (IO& io) 
-{
-	if (io.getPath() != QSE_NULL)
-		qse_fio_close ((qse_fio_t*)io.getHandle());
-	return 0;
-}
-
-ssize_t StdSed::writeOutput (IO& io, const char_t* data, size_t len) 
-{
-	if (io.getPath() == QSE_NULL)
-		return qse_sio_putsn ((qse_sio_t*)io.getHandle(), data, len);
-	else
 	return qse_fio_write ((qse_fio_t*)io.getHandle(), data, len);
 }
 

qse/test/sed/sed02.cpp

@@ -26,19 +26,23 @@ int sed_main (int argc, qse_char_t* argv[])
 
 	if (sed.open () == -1)
 	{
-		qse_printf (QSE_T("cannot open a stream editor\n"));
+		qse_printf (QSE_T("cannot open a stream editor - %s\n"), 
+			sed.getErrorMessage());
 		return -1;
 	}
 
 	if (sed.compile (argv[1]) == -1)
 	{
-		qse_printf (QSE_T("cannot compile\n"));
+		qse_printf (QSE_T("cannot compile - %s\n"), 
+			sed.getErrorMessage());
 		sed.close ();
+		return -1;
 	}
 
 	if (sed.execute () == -1)
 	{
-		qse_printf (QSE_T("cannot execute\n"));
+		qse_printf (QSE_T("cannot execute - %s\n"),
+			sed.getErrorMessage());
 		sed.close ();
 		return -1;
 	}