From a58d0ddf3d3ee7bf1f53ea0584fc0b4920376f1b Mon Sep 17 00:00:00 2001 From: hyung-hwan Date: Sun, 23 Sep 2007 13:20:00 +0000 Subject: [PATCH] Recovered from cvs revision 2007-09-23 03:02:00 --- ase/awk/Awk.hpp | 114 ++++++++++++++++++++++++++++++++------------- ase/awk/StdAwk.hpp | 9 +++- ase/change.log | 6 +++ 3 files changed, 94 insertions(+), 35 deletions(-) diff --git a/ase/awk/Awk.hpp b/ase/awk/Awk.hpp index e6d1d875..29a42035 100644 --- a/ase/awk/Awk.hpp +++ b/ase/awk/Awk.hpp @@ -1,5 +1,5 @@ /* - * $Id: Awk.hpp,v 1.56 2007/09/21 15:29:51 bacon Exp $ + * $Id: Awk.hpp,v 1.57 2007/09/22 14:40:44 bacon Exp $ */ #ifndef _ASE_AWK_AWK_HPP_ @@ -14,34 +14,36 @@ ASE_BEGIN_NAMESPACE(ASE) ///////////////////////////////// /** - * Represents the awk interpreter engine + * Represents the AWK interpreter engine */ class Awk { public: - /** boolean data type */ + /** Boolean data type */ typedef ase_bool_t bool_t; - /** data type that can hold any character */ + /** Data type that can hold any character */ typedef ase_char_t char_t; - /** data type that can hold any character or an end-of-file value */ + /** Data type that can hold any character or an end-of-file value */ typedef ase_cint_t cint_t; - + /** Represents an unsigned integer number of the same size as void* */ typedef ase_size_t size_t; + /** Signed version of size_t */ typedef ase_ssize_t ssize_t; + /** Represents an integer */ typedef ase_long_t long_t; + /** Represents a floating-point number */ typedef ase_real_t real_t; - - /** represents an internal awk value */ + /** Represents an internal awk value */ typedef ase_awk_val_t val_t; - /** represents the internal hash table */ + /** Represents the internal hash table */ typedef ase_awk_map_t map_t; - /** represents a key/value pair */ + /** Represents a key/value pair */ typedef ase_awk_pair_t pair_t; - /** represents the external i/o context */ + /** Represents the external I/O context */ typedef ase_awk_extio_t extio_t; - /** represents the run-time context */ + /** Represents the run-time context */ typedef ase_awk_run_t run_t; - /** reprensts the underlying awk interpreter */ + /** Represents the underlying interpreter */ typedef ase_awk_t awk_t; /** @@ -326,7 +328,7 @@ public: }; /** - * represents a return value of an intrinsic function + * Represents a return value of an intrinsic function */ class Return { @@ -361,11 +363,9 @@ public: } v; }; - /** - * represens the error code - */ // generated by generrcode.awk + /** Defines the error code */ enum ErrorCode { ERR_NOERR = ASE_AWK_ENOERR, @@ -497,11 +497,9 @@ public: }; // end of enum ErrorCode - /** - * Option - */ // generated by genoptcode.awk + /** Defines options */ enum Option { OPT_IMPLICIT = ASE_AWK_IMPLICIT, @@ -516,15 +514,20 @@ public: OPT_BLOCKLESS = ASE_AWK_BLOCKLESS, OPT_BASEONE = ASE_AWK_BASEONE, OPT_STRIPSPACES = ASE_AWK_STRIPSPACES, + /** Support the nextofile statement */ OPT_NEXTOFILE = ASE_AWK_NEXTOFILE, + /** Use CR+LF instead of LF for line breaking. */ OPT_CRLF = ASE_AWK_CRLF, + /** + * When set, the values specified in a call to Awk::run + * as the second and the third parameter are passed to + * the function specified as the first parameter. + */ OPT_ARGSTOMAIN = ASE_AWK_ARGSTOMAIN }; // end of enum Option - /** - * Represents the execution context - */ + /** Represents the execution context */ class Run { protected: @@ -545,7 +548,9 @@ public: bool callbackFailed; }; + /** Constructor */ Awk (); + /** Destructor */ virtual ~Awk (); /** Returns the error code */ @@ -566,12 +571,29 @@ protected: void retrieveError (); public: + /** + * Opens the interpreter. + * + * An application should call this method before doing anything + * meaningful to the instance of this class. + * + * @return + * On success, 0 is returned. On failure -1 is returned and + * extended error information is set. Call Awk::getErrorCode + * to get it. + */ virtual int open (); + + /** Closes the interpreter. */ virtual void close (); + /** Sets the option */ virtual void setOption (int opt); + + /** Gets the option */ virtual int getOption () const; + /** Defines the depth ID */ enum Depth { DEPTH_BLOCK_PARSE = ASE_AWK_DEPTH_BLOCK_PARSE, @@ -582,7 +604,9 @@ public: DEPTH_REX_MATCH = ASE_AWK_DEPTH_REX_MATCH }; + /** Sets the maximum depth */ virtual void setMaxDepth (int ids, size_t depth); + /** Gets the maximum depth */ virtual size_t getMaxDepth (int id) const; virtual const char_t* getErrorString (ErrorCode num) const; @@ -601,19 +625,44 @@ public: /** * Parses the source code. * - * Awk::parse parses the source and optionally can write the parse tree. - * @return 0 on success, -1 on error + * Awk::parse parses the source code read from the input stream and + * writes the parse tree to the output stream. A child class should + * override Awk::openSource, Awk::closeSource, Awk::readSource, + * Awk::writeSource to implement the source code stream. + * + * @return + * On success, 0 is returned. On failure, -1 is returned and + * extended error information is set. Call Awk::getErrorCode + * to get it. */ virtual int parse (); /** * Executes the parse tree. * - * Awk::run executes the parse tree created by Awk::parse. - * @param main name of an entry point - * @param args pointer to an array of character strings - * @param nargs number of characters strings in the array - * @return 0 on success, -1 on error + * This method executes the parse tree formed by Awk::parse. + * + * @param main Name of an entry point. + * If it is set, Awk::run executes the function of the specified + * name instead of entering BEGIN/pattern/END blocks. + * @param args Pointer to an array of character strings. + * If it is specified, the charater strings are passed to + * an AWK program. The values can be accesed with ARGC & ARGV + * inside the AWK program. If Awk::OPT_ARGSTOMAIN is set and + * the name of entry point is specified, the values are + * accessible as arguments to the entry point function. + * In this case, the number of arguments specified in the + * function definition should not exceed the number of + * character string passed here. + * @param nargs Number of character strings in the array + * + * @return + * On success, 0 is returned. On failure, -1 is returned if + * the run-time callback is not enabled. If the run-time callback + * is enabled, 0 is returned and the error is indicated through + * Awk::onRunEnd. The run-time callback is enabled and disbaled + * with Awk::enableRunCallback and Awk::disableRunCallback. + * Call Awk::getErrorCode to get extended error information. */ virtual int run (const char_t* main = ASE_NULL, const char_t** args = ASE_NULL, size_t nargs = 0); @@ -697,7 +746,7 @@ protected: virtual int closeSource (Source& io) = 0; /** - * Reads from the source code stream. + * Reads from the source code input stream. * A subclass should override this method. It should return 0 when * it has reached the end of the stream and -1 on falure. * When it has data to return, it should read characters not longer @@ -710,7 +759,7 @@ protected: virtual ssize_t readSource (Source& io, char_t* buf, size_t len) = 0; /** - * Writes to the source code stream. + * Writes to the source code output stream. * A subclass should override this method. It should return 0 when * it has reachedthe end of the stream and -1 on failure. * It should write up to len characters from the buffer pointed at @@ -722,7 +771,6 @@ protected: virtual ssize_t writeSource (Source& io, char_t* buf, size_t len) = 0; /*@}*/ - /** * @name Pipe I/O handlers * Pipe operations are achieved through the following methods. diff --git a/ase/awk/StdAwk.hpp b/ase/awk/StdAwk.hpp index c8156991..34231ee7 100644 --- a/ase/awk/StdAwk.hpp +++ b/ase/awk/StdAwk.hpp @@ -1,5 +1,5 @@ /* - * $Id: StdAwk.hpp,v 1.14 2007/09/07 05:40:16 bacon Exp $ + * $Id: StdAwk.hpp,v 1.15 2007/09/22 14:40:44 bacon Exp $ */ #ifndef _ASE_AWK_STDAWK_HPP_ @@ -11,6 +11,11 @@ ASE_BEGIN_NAMESPACE(ASE) ///////////////////////////////// +/** + * Provides a more useful AWK interpreter by overriding primitive methods, + * the file handler, the pipe handler and implementing common AWK intrinsic + * functions. + */ class StdAwk: public Awk { public: @@ -19,7 +24,7 @@ public: protected: - // builtin functions + // intrinsic functions int sin (Return* ret, const Argument* args, size_t nargs, const char_t* name, size_t len); int cos (Return* ret, const Argument* args, size_t nargs, diff --git a/ase/change.log b/ase/change.log index 4fffa53d..82947b4e 100644 --- a/ase/change.log +++ b/ase/change.log @@ -1,3 +1,9 @@ +[0.3.1] + +* changed the access modifier for the Awk::Source::Source from public + to protected. +* added source code documentation of ase/Awk/Awk.hpp. + [0.3.0] * added ase_awk_setword to enable customization of keywords and