From 83a6e0d3b02d616b4f8833c4fd21f21c8a18bbbc Mon Sep 17 00:00:00 2001 From: hyung-hwan Date: Thu, 28 May 2009 01:01:33 +0000 Subject: [PATCH] touched up code and documentation --- qse/README | 23 +---- qse/doc/Doxyfile | 14 ++- qse/doc/page/awk.doc | 4 + qse/doc/page/main.doc | 29 ++++++ qse/doc/page/sed.doc | 9 ++ qse/include/qse/Types.hpp | 3 + qse/include/qse/sed/Sed.hpp | 175 +++++++++++++++++++++++++++++---- qse/include/qse/sed/StdSed.hpp | 28 ++++-- qse/lib/sed/Sed.cpp | 134 ++++++++++++++++++------- qse/lib/sed/StdSed.cpp | 81 ++++++--------- qse/test/sed/sed02.cpp | 10 +- 11 files changed, 369 insertions(+), 141 deletions(-) create mode 100644 qse/doc/page/awk.doc create mode 100644 qse/doc/page/main.doc create mode 100644 qse/doc/page/sed.doc diff --git a/qse/README b/qse/README index 04308a51..0340abb1 100644 --- a/qse/README +++ b/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 +For furthur information, contact: +Chung, Hyung-Hwan -@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 -*/ diff --git a/qse/doc/Doxyfile b/qse/doc/Doxyfile index 319f04b5..484e7b76 100644 --- a/qse/doc/Doxyfile +++ b/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. diff --git a/qse/doc/page/awk.doc b/qse/doc/page/awk.doc new file mode 100644 index 00000000..b2e7c1f9 --- /dev/null +++ b/qse/doc/page/awk.doc @@ -0,0 +1,4 @@ +/** @page awk AWK + +AWK Interpreter +*/ diff --git a/qse/doc/page/main.doc b/qse/doc/page/main.doc new file mode 100644 index 00000000..01cc14ef --- /dev/null +++ b/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 + +@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" +*/ diff --git a/qse/doc/page/sed.doc b/qse/doc/page/sed.doc new file mode 100644 index 00000000..b845284f --- /dev/null +++ b/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... + +*/ diff --git a/qse/include/qse/Types.hpp b/qse/include/qse/Types.hpp index 3669396a..721f252d 100644 --- a/qse/include/qse/Types.hpp +++ b/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: diff --git a/qse/include/qse/sed/Sed.hpp b/qse/include/qse/sed/Sed.hpp index da61f885..b391fe17 100644 --- a/qse/include/qse/sed/Sed.hpp +++ b/qse/include/qse/sed/Sed.hpp @@ -22,11 +22,15 @@ #include #include +/**@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 (); }; ///////////////////////////////// diff --git a/qse/include/qse/sed/StdSed.hpp b/qse/include/qse/sed/StdSed.hpp index 0cb231c4..592c0798 100644 --- a/qse/include/qse/sed/StdSed.hpp +++ b/qse/include/qse/sed/StdSed.hpp @@ -21,24 +21,40 @@ #include +/** @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); }; ///////////////////////////////// diff --git a/qse/lib/sed/Sed.cpp b/qse/lib/sed/Sed.cpp index e74757cf..a82b435e 100644 --- a/qse/lib/sed/Sed.cpp +++ b/qse/lib/sed/Sed.cpp @@ -19,9 +19,6 @@ #include #include "sed.h" -#include -#include - ///////////////////////////////// QSE_BEGIN_NAMESPACE(QSE) ///////////////////////////////// @@ -66,55 +63,126 @@ 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); - try + if (arg->path == QSE_NULL) { - switch (cmd) + Console io (arg, Console::READ); + + try { - case QSE_SED_IO_OPEN: - return sed->openInput (io); - case QSE_SED_IO_CLOSE: - return sed->closeInput (io); - case QSE_SED_IO_READ: - return sed->readInput ( - io, arg->u.r.buf, arg->u.w.len); - default: - return -1; + switch (cmd) + { + case QSE_SED_IO_OPEN: + return sed->openConsole (io); + case QSE_SED_IO_CLOSE: + return sed->closeConsole (io); + case QSE_SED_IO_READ: + return sed->readConsole ( + io, arg->u.r.buf, arg->u.r.len); + default: + return -1; + } + } + catch (...) + { + return -1; } } - catch (...) + else { - return -1; + File io (arg, File::READ); + + 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_READ: + return sed->readFile ( + io, arg->u.r.buf, arg->u.r.len); + default: + return -1; + } + } + catch (...) + { + return -1; + } } } -int Sed::xout (sed_t* s, sed_io_cmd_t cmd, sed_io_arg_t* arg) +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); - IO io (arg); - try + if (arg->path == QSE_NULL) { - switch (cmd) + Console io (arg, Console::WRITE); + + try { - case QSE_SED_IO_OPEN: - return sed->openOutput (io); - case QSE_SED_IO_CLOSE: - return sed->closeOutput (io); - case QSE_SED_IO_READ: - return sed->writeOutput ( - io, arg->u.w.data, arg->u.w.len); - default: - return -1; + 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; + } + } + catch (...) + { + return -1; } } - catch (...) + else { - return -1; + 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; + } } } diff --git a/qse/lib/sed/StdSed.cpp b/qse/lib/sed/StdSed.cpp index b7215362..21d98b09 100644 --- a/qse/lib/sed/StdSed.cpp +++ b/qse/lib/sed/StdSed.cpp @@ -40,81 +40,58 @@ 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) { - 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::readConsole (Console& 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); + return qse_sio_getsn ((qse_sio_t*)io.getHandle(), buf, len); } -int StdSed::openOutput (IO& io) +StdSed::ssize_t StdSed::writeConsole (Console& io, const char_t* data, size_t len) { - int flags; - const qse_char_t* path = io.getPath (); + return qse_sio_putsn ((qse_sio_t*)io.getHandle(), data, len); +} - 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; +int StdSed::openFile (File& io) +{ + int flags = (io.getMode() == File::READ)? + QSE_FIO_READ: (QSE_FIO_WRITE|QSE_FIO_CREATE|QSE_FIO_TRUNCATE); - io.setHandle (fio); - } + 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::closeOutput (IO& io) +int StdSed::closeFile (File& io) { - if (io.getPath() != QSE_NULL) - qse_fio_close ((qse_fio_t*)io.getHandle()); + qse_fio_close ((qse_fio_t*)io.getHandle()); return 0; } -ssize_t StdSed::writeOutput (IO& io, const char_t* data, size_t len) +StdSed::ssize_t StdSed::readFile (File& io, char_t* buf, 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); + return qse_fio_read ((qse_fio_t*)io.getHandle(), buf, len); +} + +StdSed::ssize_t StdSed::writeFile (File& io, const char_t* data, size_t len) +{ + return qse_fio_write ((qse_fio_t*)io.getHandle(), data, len); } ///////////////////////////////// diff --git a/qse/test/sed/sed02.cpp b/qse/test/sed/sed02.cpp index c313a858..e8e20508 100644 --- a/qse/test/sed/sed02.cpp +++ b/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; }