Recovered from cvs revision 2007-09-22 13:46:00

ase/awk/Awk.cpp

@@ -1,5 +1,5 @@
 /*
- * $Id: Awk.cpp,v 1.54 2007/09/07 05:40:16 bacon Exp $
+ * $Id: Awk.cpp,v 1.55 2007/09/21 15:29:51 bacon Exp $
  */
 
 
@@ -16,7 +16,7 @@ ASE_BEGIN_NAMESPACE(ASE)
 // Awk::Source
 //////////////////////////////////////////////////////////////////
 
-Awk::Source::Source (Mode mode): mode (mode)
+Awk::Source::Source (Mode mode): mode (mode), handle (ASE_NULL)
 {
 }
 

ase/awk/Awk.hpp

@@ -1,5 +1,5 @@
 /*
- * $Id: Awk.hpp,v 1.55 2007/09/19 11:38:12 bacon Exp $
+ * $Id: Awk.hpp,v 1.56 2007/09/21 15:29:51 bacon Exp $
  */
 
 #ifndef _ASE_AWK_AWK_HPP_
@@ -14,87 +14,165 @@ ASE_BEGIN_NAMESPACE(ASE)
 /////////////////////////////////
 
 /** 
- * Provides 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;
 
-
 	typedef ase_size_t  size_t;
 	typedef ase_ssize_t ssize_t;
 	typedef ase_long_t  long_t;
 	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 operation
-	 */
+	/** represents the external i/o context */
 	typedef ase_awk_extio_t extio_t;
-
-	/**
-	 * represents the run-time instance of an awk interpreter
-	 */
+	/** represents the run-time context */
 	typedef ase_awk_run_t run_t;
-
-	/**
-	 * reprensts the underlying awk interpreter
-	 */
+	/** reprensts the underlying awk interpreter */
 	typedef ase_awk_t awk_t;
 
 	/**
-	 * The source class 
-	 * @see openSource
+	 * Represents the source code I/O context for Awk::parse.
+	 * An instance of Awk::Source is passed to Awk::openSource, 
+	 * Awk::readSource, Awk::writeSource, Awk::closeSource
+	 * when Awk::parse calls them to read the source code and write the 
+	 * internal parse tree. It indicates the mode of the context and
+	 * provides space for data that may be needed for the I/O operation.
 	 */
 	class Source
 	{
 	public:
-		/**
-		 * Indicates the mode of the source code I/O
-		 */
+		friend class Awk;
+
+		/** Mode of source code I/O. */
 		enum Mode
 		{	
-			READ,   /**< readable I/O */
-			WRITE   /**< writable I/O */
+			READ,   /**< source code read. */
+			WRITE   /**< source code write. */
 		};
 
+	protected:
 		Source (Mode mode);
 
+	public:
+		/**
+		 * Returns the mode of the source code I/O. 
+		 * You may call this method in Awk::openSource and 
+		 * Awk::closeSource to determine the mode as shown in 
+		 * the example below. This method always returns Source::READ 
+		 * and Source::WRITE respectively when called from 
+		 * Awk::readSource and Awk::writeSource.
+		 *
+		 * <pre>
+		 * int openSource (Source& io)
+		 * {
+		 * 	if (io.getMode() == Source::READ)
+		 * 	{
+		 * 		// open for reading 
+		 * 		return 1;
+		 * 	}
+		 * 	else (io.getMode() == Source::WRITE)
+		 * 	{
+		 *		// open for writing
+		 *		return 1;
+		 * 	}
+		 * 	return -1;
+		 * }
+		 *
+		 * int closeSource (Source& io)
+		 * {
+		 * 	if (io.getMode() == Source::READ)
+		 * 	{
+		 * 		// close for reading 
+		 * 		return 0;
+		 * 	}
+		 * 	else (io.getMode() == Source::WRITE)
+		 * 	{
+		 *		// close for writing
+		 *		return 0;
+		 * 	}
+		 * 	return -1;
+		 * }
+		 * </pre>
+		 *
+		 * @return Awk::Source::READ or Awk::Source::WRITE
+		 */
 		Mode getMode() const;
+
+		/**
+		 * Returns the value set with Source::setHandle. 
+		 * ASE_NULL is returned if it has not been set with 
+		 * Source::setHandle. You usually call this method
+		 * from Awk::readSource, Awk::writeSource, and 
+		 * Awk::closeSource to get the value set in Awk::openSource
+		 * as shown in the example below.
+		 *
+		 * <pre>
+		 * int closeSource (Source& io)
+		 * {
+		 * 	if (io.getMode() == Source::READ)
+		 * 	{
+		 * 		fclose ((FILE*)io.getHandle());
+		 * 		return 0;
+		 * 	}
+		 * 	else (io.getMode() == Source::WRITE)
+		 * 	{
+		 * 		fclose ((FILE*)io.getHandle());
+		 * 		return 0;
+		 * 	}
+		 * 	return -1;
+		 * }
+		 * </pre>
+		 *
+		 * @return an arbitrary value of type void* set with 
+		 *         Source::setHandle or ASE_NULL
+		 */
 		const void* getHandle () const;
+
+		/**
+		 * Sets the handle value. Source::getHandle can retrieve
+		 * the value set with Source::setHandle. You usually call 
+		 * this from Awk::openSource as shown in the example below.
+		 *
+		 * <pre>
+		 * int openSource (Source& io)
+		 * {
+		 * 	if (io.getMode() == Source::READ)
+		 * 	{
+		 * 		FILE* fp = fopen ("t.awk", "r");
+		 * 		if (fp == NULL) return -1;
+		 * 		io.setHandle (fp);
+		 * 		return 1;
+		 * 	}
+		 * 	else (io.getMode() == Source::WRITE)
+		 * 	{
+		 * 		FILE* fp = fopen ("t.out", "w");
+		 * 		if (fp == NULL) return -1;
+		 * 		io.setHandle (fp);
+		 *		return 1;
+		 * 	}
+		 * 	return -1;
+		 * }
+		 * </pre>
+		 *
+		 * @param handle an arbitrary value of the type void*
+		 */
 		void  setHandle (void* handle);
 
-	private:
+	protected:
 		Mode  mode;
 		void* handle;
 	};
@@ -113,12 +191,12 @@ public:
 		void  setHandle (void* handle);
 
 		/** 
-		 * returns the underlying extio_t handle
+		 * Returns the underlying extio_t handle
 		 */
 		const extio_t* getRawExtio () const;
 
 		/**
-		 * returns the underlying run_t handle associated 
+		 * Returns the underlying run_t handle associated 
 		 * with the underlying extio_t handle
 		 */
 		const run_t* getRawRun () const;
@@ -445,7 +523,7 @@ public:
 	// end of enum Option
 
 	/**
-	 * Run
+	 * Represents the execution context
 	 */
 	class Run
 	{
@@ -470,8 +548,13 @@ public:
 	Awk ();
 	virtual ~Awk ();
 	
+	/** Returns the error code */
 	ErrorCode getErrorCode () const;
+
+	/** Returns the line of the source code where the error occurred */
 	size_t getErrorLine () const ;
+
+	/** Returns the error message */
 	const char_t* getErrorMessage () const;
 
 protected:
@@ -516,42 +599,51 @@ public:
 	virtual int unsetAllWords ();
 
 	/**
-	 * parses the source code
+	 * Parses the source code.
+	 *
+	 * Awk::parse parses the source and optionally can write the parse tree.
+	 * @return 0 on success, -1 on error
 	 */
 	virtual int parse ();
 
 	/**
-	 * executes the parse tree
+	 * 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
 	 */
 	virtual int run (const char_t* main = ASE_NULL, 
 	         const char_t** args = ASE_NULL, size_t nargs = 0);
 
 	/**
-	 * defines the user-defined function 
+	 * Represents a user-defined function 
 	 */
 	typedef int (Awk::*FunctionHandler) (
 		Return* ret, const Argument* args, size_t nargs, 
 		const char_t* name, size_t len);
 
 	/**
-	 * adds a new user-defined function
+	 * Adds a new user-defined function
 	 */
 	virtual int addFunction (
 		const char_t* name, size_t minArgs, size_t maxArgs, 
 		FunctionHandler handler);
 
 	/**
-	 * deletes a user-defined function
+	 * Deletes a user-defined function
 	 */
 	virtual int deleteFunction (const char_t* main);
 
 	/**
-	 * enables the run-time callback
+	 * Enables the run-time callback
 	 */
 	virtual void enableRunCallback ();
 
 	/**
-	 * disables the run-time callback
+	 * Disables the run-time callback
 	 */
 	virtual void disableRunCallback ();
 
@@ -565,33 +657,68 @@ protected:
 	 * source code input and output. The awk interpreter calls the 
 	 * following methods when the parse method is invoked.
 	 *
-	 * To read the source code, the interpter calls Awk::openSource with 
-	 * an Awk::Source object whose mode is set to Awk::Source::READ. 
-	 * If Awk::openSource returns 1, it calls Awk::readSource with 
-	 * the Awk::Source object subsequently until it returns 0. Finally, 
-	 * it calls Awk::closeSource with the same Awk::Source object. 
-	 * If Awk::openSource returns 0, the interpreter calls Awk::closeSource
-	 * immediately without calling Awk::readSource. If Awk::openSource 
-	 * returns -1, Awk::closeSource is not called. If readSource returns 
-	 * -1, the source code reading is aborted and Awk::closeSource is 
-	 *  called.
+	 * To read the source code, Awk::parse calls Awk::openSource, 
+	 * Awk::readSource, and Awk::closeSource as shown in the diagram below.
+	 * Any failures wll cause Awk::parse to return an error.
 	 *
-	 * \image html awk-extio.png
+	 * \image html awk-srcio-read.png
 	 *
-	 * The interpter is able to write back the internal parse tree
-	 * if openSource returns 1 when the mode of the Source object 
-	 * is set to Awk::Source::WRITE. Then it calls writeSource until
-	 * it has finished writing the parse tree, and calls closeSource.
+	 * Awk::parse is able to write back the internal parse tree by
+	 * calling Awk::openSource, Awk::writeSource, and Awk::closeSource
+	 * as shown in the diagram below. Any failures will cause Awk::parse
+	 * to return an error.
 	 *
+	 * \image html awk-srcio-write.png
+	 *
+	 * Awk::parse passes an instance of Awk::Source when invoking these
+	 * methods. You can determine the context of the method by calling
+	 * Awk::Source::getMode and inspecting its return value. You may use
+	 * Awk::Source::getHandle and Awk::Source::setHandle to store and
+	 * retrieve the custom information needed to complete the operation.
 	 */
 	/*@{*/
-	/** opens the source stream. */
-	virtual int     openSource  (Source& io) = 0;
-	/** closes the source stream */
-	virtual int     closeSource (Source& io) = 0;
-	/** reads from the source stream */
+	/** 
+	 * Opens the source code stream. 
+	 * A subclass should override this method. It should return 1 on
+	 * success, -1 on failure, and 0 if the opening operation
+	 * is successful but has reached the end of the stream.
+	 * @param io  I/O context passed from Awk::parse
+	 * @see Awk::Source::getMode, Awk::Source::setHandle
+	 */
+	virtual int openSource  (Source& io) = 0;
+
+	/** 
+	 * Closes the source code stream.
+	 * A subclass should override this method. It should return 0 on
+	 * success and -1 on failure.
+	 * @param io  I/O context passed from Awk::parse
+	 * @see Awk::Source::getMode, Awk::Source::getHandle
+	 */
+	virtual int closeSource (Source& io) = 0;
+
+	/** 
+	 * Reads from the source code 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
+	 * than len characters, fill the buffer pointed at by buf with them,
+	 * and return the number of the charaters read.
+	 * @param io  I/O context passed from Awk::parse
+	 * @param buf pointer to a character buffer
+	 * @param len number of characters in the buffer
+	 */
 	virtual ssize_t readSource  (Source& io, char_t* buf, size_t len) = 0;
-	/** writes to the source stream */
+
+	/** 
+	 * Writes to the source code 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
+	 * by buf and return the number of characters written.
+	 * @param io  I/O context passed from Awk::parse
+	 * @param buf pointer to a character buffer
+	 * @param len size of the buffer in characters
+	 */
 	virtual ssize_t writeSource (Source& io, char_t* buf, size_t len) = 0;
 	/*@}*/
 	

ase/doc/doxyfile

@@ -0,0 +1,244 @@
+# Doxyfile 1.4.6
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+PROJECT_NAME           = ase
+PROJECT_NUMBER         = 
+OUTPUT_DIRECTORY       = doxy
+CREATE_SUBDIRS         = NO
+OUTPUT_LANGUAGE        = English
+USE_WINDOWS_ENCODING   = YES
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = "The $name class" \
+                         "The $name widget" \
+                         "The $name file" \
+                         is \
+                         provides \
+                         specifies \
+                         contains \
+                         represents \
+                         a \
+                         an \
+                         the
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        = ../..
+STRIP_FROM_INC_PATH    = 
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = YES
+MULTILINE_CPP_IS_BRIEF = NO
+DETAILS_AT_TOP         = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 8
+ALIASES                = 
+OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_JAVA   = NO
+BUILTIN_STL_SUPPORT    = NO
+DISTRIBUTE_GROUP_DOC   = NO
+SUBGROUPING            = YES
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+HIDE_UNDOC_MEMBERS     = YES
+HIDE_UNDOC_CLASSES     = YES
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = NO
+HIDE_SCOPE_NAMES       = NO
+SHOW_INCLUDE_FILES     = YES
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_BY_SCOPE_NAME     = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       = 
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_DIRECTORIES       = NO
+FILE_VERSION_FILTER    = 
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           = 
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT                  = ../../ase
+FILE_PATTERNS          = *.cc \
+                         *.cxx \
+                         *.cpp \
+                         *.c++ \
+                         *.hxx \
+                         *.hpp \
+                         *.h++ 
+RECURSIVE              = YES
+EXCLUDE                = ../net \
+                         ../com \
+                         ../stx \
+                         ../test/net \
+                         ../test/com \
+                         ../test/stx
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = 
+EXAMPLE_PATH           = 
+EXAMPLE_PATTERNS       = *
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             = imgs
+INPUT_FILTER           = 
+FILTER_PATTERNS        = 
+FILTER_SOURCE_FILES    = NO
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = NO
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX     = NO
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          = 
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            = 
+HTML_FOOTER            = 
+HTML_STYLESHEET        = 
+HTML_ALIGN_MEMBERS     = YES
+GENERATE_HTMLHELP      = NO
+CHM_FILE               = 
+HHC_LOCATION           = 
+GENERATE_CHI           = NO
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+DISABLE_INDEX          = NO
+ENUM_VALUES_PER_LINE   = 4
+GENERATE_TREEVIEW      = NO
+TREEVIEW_WIDTH         = 250
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4wide
+EXTRA_PACKAGES         = 
+LATEX_HEADER           = 
+PDF_HYPERLINKS         = NO
+USE_PDFLATEX           = NO
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    = 
+RTF_EXTENSIONS_FILE    = 
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN           = NO
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_LINKS              = NO
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_SCHEMA             = 
+XML_DTD                = 
+XML_PROGRAMLISTING     = YES
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF   = NO
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX = 
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor   
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = NO
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = 
+INCLUDE_FILE_PATTERNS  = 
+PREDEFINED             = 
+EXPAND_AS_DEFINED      = 
+SKIP_FUNCTION_MACROS   = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references   
+#---------------------------------------------------------------------------
+TAGFILES               = 
+GENERATE_TAGFILE       = 
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+PERL_PATH              = /usr/bin/perl
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool   
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS         = YES
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = NO
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+DOT_PATH               = 
+DOTFILE_DIRS           = 
+MAX_DOT_GRAPH_WIDTH    = 1024
+MAX_DOT_GRAPH_HEIGHT   = 1024
+MAX_DOT_GRAPH_DEPTH    = 1000
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine   
+#---------------------------------------------------------------------------
+SEARCHENGINE           = NO