improved error handling functions in sed

qse/include/qse/Mmgr.hpp

@@ -26,6 +26,13 @@
 QSE_BEGIN_NAMESPACE(QSE)
 /////////////////////////////////
 
+/**
+ * The Mmgr class defines a memory manager interface that can be inherited
+ * by a class in need of a memory manager as defined in the primitive 
+ * qse_mmgr_t type. Using the class over the primitive type enables you to
+ * write code in more object-oriented fashion. An inheriting class should 
+ * implement three pure virtual functions.
+ */ 
 class Mmgr: public qse_mmgr_t
 {
 public:
@@ -40,20 +47,54 @@ public:
 	virtual ~Mmgr () {}
 
 protected:
-	virtual void* allocMem (qse_size_t n) throw () = 0;
-	virtual void* reallocMem (void* ptr, qse_size_t n) throw () = 0;
-	virtual void  freeMem (void* ptr) throw () = 0;
+	/** 
+	 * The allocMem() function allocates a chunk of memory of the 
+	 * size \a n and return the pointer to the beginning of the chunk.
+	 * If it fails to allocate memory, it should return QSE_NULL.
+	 */
+	virtual void* allocMem (
+		qse_size_t n /**< the size of allocate in bytes */
+	) throw () = 0;
 
+	/**
+	 * The reallocMem() function resizes a chunk of memory previously
+	 * allocated with the allocMem() function. When resized, the contents
+	 * of a surviving memory chunk is left untouched. If it fails to
+	 * resize memory, it should return QSE_NULL.
+	 */
+	virtual void* reallocMem (
+		void* ptr,   /**< a pointer to a memory chunk to resize */
+		qse_size_t n /**< new size in bytes */
+	) throw () = 0;
+
+	/**
+	 * The freeMem() function frees a chunk of memory allocated with
+	 * the allocMem() function or resized with the reallocMem() function.
+	 */
+	virtual void freeMem (
+		void* ptr /**< a pointer to a memory chunk to free */
+	) throw () = 0;
+
+protected:
+	/**
+	 * a bridge function from the qse_mmgr_t type the allocMem() function.
+	 */
 	static void* alloc_mem (void* data, qse_size_t n) throw ()
 	{
 		return ((Mmgr*)data)->allocMem (n);
 	}
 
+	/**
+	 * a bridge function from the qse_mmgr_t type the reallocMem() function.
+	 */
 	static void* realloc_mem (void* data, void* ptr, qse_size_t n) throw ()
 	{
 		return ((Mmgr*)data)->reallocMem (ptr, n);
 	}
 
+	/**
+	 * a bridge function from the qse_mmgr_t type the freeMem() function.
+	 */
 	static void  free_mem (void* data, void* ptr) throw ()
 	{
 		return ((Mmgr*)data)->freeMem (ptr);

qse/include/qse/macros.h

@@ -1,5 +1,5 @@
 /*
- * $Id: macros.h 140 2009-05-18 12:55:01Z hyunghwan.chung $
+ * $Id: macros.h 150 2009-05-21 06:17:17Z hyunghwan.chung $
  *
    Copyright 2006-2009 Chung, Hyung-Hwan.
 
@@ -202,13 +202,23 @@
 	qse_mmgr_t* mmgr;
 	
 /**
- * The QSE_DEFINE_COMMON_FUNcTIONS() macro defines common object functions.
+ * The QSE_DEFINE_COMMON_FUNCTIONS() macro defines common object functions.
+ * - @code void qse_xxx_setmmgr (qse_xxx_t* xxx, qse_mmgr_t* mmgr); @endcode
+ *   The qse_xxx_setmmgr() function change the memory manager of a relevant
+ *   object. Take extreme care if you want to use this function.
+ * - @code qse_mmgr_t* qse_xxx_getmmgr (qse_xxx_t* xxx); @endcode
+ *   The qse_xxx_getmmgr() function returns the memory manager of a relevant
+ *   object.
+ * - @code void qse_xxx_getxtn (qse_xxx_t* xxx); @endcode
+ *   The qse_xxx_getxtn() function returns the pointer to an extension area
+ *   of a relevant object created with an extension size greater than 0.
  */
 #define QSE_DEFINE_COMMON_FUNCTIONS(name) \
 void qse_##name##_setmmgr (qse_##name##_t* name, qse_mmgr_t* mmgr); \
 qse_mmgr_t* qse_##name##_getmmgr (qse_##name##_t* name); \
 void* qse_##name##_getxtn (qse_##name##_t* name);
 
+
 /**
  * The QSE_MMGR() macro gets the memory manager field from an object.
  */

qse/include/qse/sed/sed.h

@@ -65,7 +65,7 @@ enum qse_sed_errnum_t
 	QSE_SED_ETMTXT,  /**< too much text */
 	QSE_SED_ECMDNR,  /**< a command is not recognized */
 	QSE_SED_ECMDMS,  /**< a command is missing */
-	QSE_SED_ECMDGB,  /**< command garbled */
+	QSE_SED_ECMDIC,  /**< a command is incomplete */
 	QSE_SED_EREXBL,  /**< regular expression build error */
 	QSE_SED_EREXMA,  /**< regular expression match error */
 	QSE_SED_EA1PHB,  /**< address 1 prohibited */
@@ -76,13 +76,11 @@ enum qse_sed_errnum_t
 	QSE_SED_EBSDEL,  /**< \ used a delimiter */
 	QSE_SED_EGBABS,  /**< garbage after \ */
 	QSE_SED_ESCEXP,  /**< ; is expected */
-	QSE_SED_ELABTL,  /**< label too long */
 	QSE_SED_ELABEM,  /**< label name is empty */
 	QSE_SED_ELABDU,  /**< duplicate label name */
 	QSE_SED_ELABNF,  /**< label not found */
 	QSE_SED_EFILEM,  /**< file name is empty */
 	QSE_SED_EFILIL,  /**< illegal file name */
-	QSE_SED_ENOTRM,  /**< not terminated properly */
 	QSE_SED_ETSNSL,  /**< translation set not the same length*/
 	QSE_SED_EGRNBA,  /**< group brackets not balanced */
 	QSE_SED_EGRNTD,  /**< group nested too deeply */
@@ -169,8 +167,15 @@ extern "C" {
 QSE_DEFINE_COMMON_FUNCTIONS (sed)
 
 /**
- * The qse_sed_open() function creates a stream editor.
- * @return A pointer to a stream editor on success, QSE_NULL on a failure
+ * The qse_sed_open() function creates a stream editor object. A memory
+ * manager provided is used to allocate and destory the object and any dynamic
+ * data through out its lifetime. An extension area is allocated if an
+ * extension size greater than 0 is specified. You can access it with the
+ * qse_sed_getxtn() function and use it to store arbitrary data associated
+ * with the object. See #QSE_DEFINE_COMMON_FUNCTIONS() for qse_sed_getxtn().
+ * When done, you should destroy the object with the qse_sed_close() function
+ * to avoid any resource leaks including memory. 
+ * @return A pointer to a stream editor on success, QSE_NULL on failure
  */
 qse_sed_t* qse_sed_open (
 	qse_mmgr_t*    mmgr, /**< a memory manager */
@@ -202,13 +207,54 @@ void qse_sed_setoption (
 );
 
 /**
- * The qse_sed_geterrmsg() function retrieves an error message
- * @return a pointer to a string describing an error occurred 
+ * The qse_sed_geterrnum() function gets the number of the last error.
+ * @return the number of the last error
+ */
+int qse_sed_geterrnum (
+	qse_sed_t* sed /**< a stream editor */
+);
+
+/**
+ * The qse_sed_geterrlin() function gets the number of the line where
+ * the last error has occurred.
+ * @return the line number of the last error
+ */
+qse_size_t qse_sed_geterrlin (
+	qse_sed_t* sed /**< a stream editor */
+);
+
+/**
+ * The qse_sed_geterrmsg() function gets a string describing the last error.
+ * @return a pointer to an error message
  */
 const qse_char_t* qse_sed_geterrmsg (
 	qse_sed_t* sed /**< a stream editor */
 );
 
+/**
+ * The qse_sed_geterror() function gets an error number, an error line, and 
+ * an error message. The information is set to the memory area pointed to by
+ * each parameter.
+ */
+void qse_sed_geterror (
+	qse_sed_t*         sed,    /**< a stream editor */
+	int*               errnum, /**< a pointer to an error number holder */
+	qse_size_t*        errlin, /**< a pointer to an error line holder */
+	const qse_char_t** errmsg  /**< a pointer to an error message */
+);
+
+/**
+ * The qse_sed_seterror() function sets an error number, an error line, and
+ * an error message. An error string is composed of a formatting string
+ * and an array of formatting parameters.
+ */
+void qse_sed_seterror (
+	qse_sed_t*        sed,    /**< a stream editor */
+	int               errnum, /**< an error number */
+	qse_size_t        errlin, /**< an error line */
+	const qse_cstr_t* errarg  /**< a string array for formatting an error message */
+);
+
 /**
  * The qse_sed_comp() function compiles editing commands into an internal form.
  * @return 0 on success, -1 on error 

qse/include/qse/types.h

@@ -1,5 +1,5 @@
 /*
- * $Id: types.h 127 2009-05-07 13:15:04Z hyunghwan.chung $
+ * $Id: types.h 150 2009-05-21 06:17:17Z hyunghwan.chung $
  *
    Copyright 2006-2009 Chung, Hyung-Hwan.
 
@@ -404,16 +404,37 @@ struct qse_cstr_t
 typedef struct qse_cstr_t qse_cstr_t;
 /******/
 
-/****t* Base/qse_mmgr_t
- * NAME
- *  qse_mmgr_t - define a memory manager
- * SYNOPSIS
+/**
+ * The qse_mmgr_t type defines a set type of functions for memory management.
+ * As the type is merely a structure, it is just used as a single container
+ * for memory management functions with a pointer to user-defined data. 
+ * The user-defined \a data is passed to each memory management function
+ * whenever it is called. You can allocate, reallocate, and free a memory
+ * chunk.
+ *
+ * For example, a qse_xxx_open() function accepts a pointer of the qse_mmgr_t *
+ * type and the xxx object uses it to manage dynamic data within the object. 
  */
 struct qse_mmgr_t
 {
+	/** 
+	 * allocate a memory chunk of the size \a n.
+	 * @return a pointer to a memory chunk on success, QSE_NULL on failure.
+	 */
 	void* (*alloc)   (void* data, qse_size_t n);
+	/** 
+	 * resize a memory chunk pointed to by \a ptr to the size \a n.
+	 * @return a pointer to a memory chunk on success, QSE_NULL on failure.
+	 */
 	void* (*realloc) (void* data, void* ptr, qse_size_t n);
+	/**
+	 * frees a memory chunk pointed to by \a ptr.
+	 */
 	void  (*free)    (void* data, void* ptr);
+	/** 
+	 * a pointer to user-defined data passed as the first parameter to
+	 * alloc(), realloc(), and free().
+	 */
 	void*   data;
 };
 typedef struct qse_mmgr_t qse_mmgr_t;