Recovered from cvs revision 2007-09-23 03:02:00

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.
+	 * Awk::parse parses the source code read from the input stream and 
-	 * @return 0 on success, -1 on error
+	 * 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.
+	 * This method executes the parse tree formed by Awk::parse.
-	 * @param main name of an entry point
+	 *
-	 * @param args pointer to an array of character strings
+	 * @param main Name of an entry point.
-	 * @param nargs number of characters strings in the array
+	 * 	If it is set, Awk::run executes the function of the specified 
-	 * @return 0 on success, -1 on error
+	 * 	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.

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, 

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